Files
notarius/docs/adr/0023-unify-accepted-artifact-and-plan-caching.md

4.5 KiB

ADR-0023: Unify accepted artifact and plan caching

Status: Accepted Date: 2026-11-22

Context

Source-keyed plans and fingerprinted checkpoints imposed two recovery models and substantial identity/provenance machinery. The selected need is narrower: reuse successful model-backed predecessors after downstream failure without repeating their complete production and assessment.

Decision

Use one best-effort filesystem cache for final accepted typed artifacts and LLM-generated chunk plans. Prepare the initial native request once and use its opaque MessageContentHash unchanged, with no additional identity dimensions. Execute that same prepared handle on a miss and discard it on a hit. Corrections do not change the key. Store the final accepted codec artifact, including applied normalization, rather than a native response, exchange, or reconciliation proposal.

Message roles, exact text, boundaries, and order select reuse. Model/settings, session, schema metadata, policy, library versions, and implementation changes add no key dimensions. Text rendered into the messages participates as content. Changed policy may therefore reuse old acceptance; operators deliberately choose bypass or refresh when they want re-execution.

Hits receive ordinary codec and current-source usability checks, not renewed semantic assessment, replayed exchanges, fabricated execution, or historical usage. Cached plans are rematerialized against the current source. Unusable entries miss. Deterministic operations remain uncached without synthetic requests.

Store only final ordinary acceptance. Failed, rejected, incomplete, canceled, and fallback results cannot be stored. Fallback and actually affected dependent work skip lookup as well as storage; unrelated accepted predecessors remain reusable. Eligibility is a small handoff fact, not a dependency fingerprint graph.

Auto reads and stores acceptance; bypass does neither; refresh skips lookup and replaces only after new acceptance. Failed refresh preserves earlier accepted bytes. Cache I/O failures produce diagnostics without failing otherwise successful work or repeating model calls. Records are plain accepted JSON, not envelopes, manifests, acceptance ledgers, or copied source/execution histories. Exact root, layout, and control precedence belong in configuration and operations references.

Ignore legacy checkpoint and source-plan records without importing, rewriting, or deleting them. Remove explicit resume, recomputation barriers, and the separate canonical-partition guarantee. Matching initial messages may reuse a plan; changed prompt/reference/input content may select another partition. Retain plan range, annotation, source-order, and deterministic materialization correctness.

This supersedes ADR-0005 and ADR-0007, and the two-cache model in ADR-0006. It replaces checkpoint/fingerprint clauses in ADRs 0010, 0011, 0013, and 0019, not their retained domain, content, or identity boundaries.

Apply ADR-0017's permission ownership to this unified cache: deployment umask, setgid, and default ACLs govern effective access. Retain confined paths, symlink rejection, validation, atomic publication, and recovery without permission convergence or automatic migration. Output and debug retain independent roots and lifecycles.

Alternatives considered

  • Keep one canonical partition per source. This ignores changed initial task content and retains a second lookup/publication mechanism.
  • Use comprehensive execution or policy fingerprints. That changes the selected reuse semantics and restores the removed compatibility bookkeeping.
  • Cache native responses or restore conversations. Neither is the accepted typed application result, and each requires replay or renewed interpretation.

Consequences

Ordinary reruns recover reusable accepted predecessors without a resume request. Acceptance under changed model or validation policy is not implied by a hit. Cache is reconstructible and best effort, not an execution history or a storage durability guarantee. Legacy data stays available for operator-managed cleanup; no automatic conversion, expiry service, or garbage collector is introduced.