Files
notarius/docs/internal/state.md

11 KiB

Run State Internals

This guide explains physical cache, capture, and publication collaborators. Operations owns layout, permissions, retention, and recovery procedures; Configuration owns settings/defaults; CLI Reference owns reporting. Pipeline Internals owns assessment, workers, and dependency eligibility.

Composition And Independent State

The run handler is the physical-path composition root. It obtains loaded configuration and a safe run identity, allocates requested capture before engine/preflight, resolves/materializes/ prepares, and then constructs the cache/recorder collaborators for the runner. Shared inspection loaders create no run storage.

Modules receive explicit operation/cache/evidence interfaces and data, not roots or CommandKit reporters. Output, accepted-result cache, and optional capture remain independent. None is a required metadata bundle for another. In-memory normalized artifacts support handoffs/evidence; they are not a persisted resume ledger.

Prepared Result Reuse

RunProducer owns native request selection and cache interaction for an eligible model operation:

  1. Prepare the initial request once with PrepareExecution, retain its detached details and opaque MessageContentHash.
  2. For a read-enabled selection, decode a found entry through the expected durable codec and current-source usability checks. On a usable hit, discard the prepared handle and return the artifact without model work.
  3. On a miss, execute that exact handle with RunPrepared, then use ordinary interpretation, complete assessment, and native continuation.
  4. Store only final ordinary acceptance, encoded as the applied typed artifact or checked logical plan, under the initial key. Dispose of unused prepared handles on every exit.

Typed bindings attach codec and source-evidence checks; chunk-plan bindings decode and rematerialize against the current document. A hit has no ordinary semantic revalidation, native execution event, restored exchange, or historical usage. Normalizers store applied domain results, not reconciliation proposals. Deterministic operations stay uncached without manufactured requests.

The key is the native initial message-content value, not a configuration, policy, model/session, implementation, or source-only fingerprint. Rendered message changes can change selection; settings-only changes need not. Correction retains the initial key. Public reuse choices and their consequences belong in Operations.

Reuse eligibility is separate from the selected cache mode. Fallback and actual dependent work perform neither lookup nor storage, even if they later produce otherwise accepted output. Bypass/ineligible work uses ordinary native execution without cache-specific split preparation. Capture reuses available prepared details; it never adds preparation to explain a hit.

Filesystem Store And Failure Handling

artifactcache.FilesystemStore implements the narrow contracts.ArtifactCache interface. Construction retains the exact selected root without creating it. Lookup checks one confined regular JSON entry; missing data is an ordinary miss. Stored bytes are the unchanged accepted artifact, without provenance/execution envelopes or alternate key dimensions. Physical placement belongs in Operations.

The store honors the resolved read/write mode. Refresh does not read or remove previous acceptance in anticipation of execution. Only a newly supplied accepted value can replace it. Failed refresh execution or a failed cache write preserves the old entry. Legacy data is not scanned, converted, rewritten, or deleted.

Publication uses fileio's confined atomic process-permission writer. New cache objects use process/deployment creation permissions; there is no permission convergence on an existing root. ADR-0017 owns that decision.

Cache integration treats unreadable/malformed/codec-unusable entries as diagnostic misses. Store failures become scoped process warnings without failing successful production or calling the provider again. Artifact encoding, caller cancellation, requested evidence, and observer failures retain their own error boundaries; they are not swallowed as best-effort storage failures.

Accepted predecessors can survive downstream failure and be reused by an ordinary rerun. There is no checkpoint loader, resume barrier, forced-recompute policy, or canonical partition selected solely by source digest. New message selections populate independently; an accepted plan is rematerialized, not restored with a historic execution claim.

Artifact Publication And Native Reporting

The runner returns logical deliverable files only after successful execution/ encoding. The JSON encoder owns domain-file selection and optional auxiliary inclusion. JSON output, chunk maps, and evidence context own logical paths/schemas, not the store or recorder.

writeOutputFiles validates every logical path before allocating the run directory, refuses an existing destination, and writes files with confined atomic helpers. This is per-file publication, not an all-files transaction. A later write can leave a partial new directory; existing siblings are preserved. No rollback deletes available artifacts.

After complete publication, the run handler finalizes requested capture before reportRunResult submits the small native completion value. The report is not automatically persisted or required to decode domain files. No index, manifest, receipt, or process-diagnostic sidecar is emitted. Artifact count counts returned deliverables, including selected available auxiliaries, not cache/debug/intermediate files.

Post-publication capture/render/delivery failure remains nonzero with available locations. Valid artifacts remain; model work and capture terminalization are not repeated. Native delivery evidence is separate from the operation cause, and failed stdout may be partial. Public outcomes and caller responsibilities belong in CLI Reference and the subprocess guide.

Capture Lifecycle

Debug selection preserves native boolean and supplied directory semantics independently of verbosity. The run path alone calls debug.Start. Bundle allocation validates identity, creates a new absolute per-run directory, and atomically updates a relative latest link at start. Failure can return an available directory for explanation/ retention. Disabled capture creates nothing; completion never retargets the link.

One synchronized recorder writes evidence incrementally, retaining lifecycle state and the first recording error rather than accumulating whole-run content. Callback failures are exposed at the next boundary that can return an error. Finalize attempts terminal evidence once, joins primary and capture causes, and retains its result. Repeated calls do not rewrite evidence or retarget latest. A later presentation failure does not change capture into another terminal run. Allocation/link/record/finalization failures never trigger model retries or a fallback directory. Available files are retained.

Native And Application Evidence

Run capture snapshots the original secret-aware application/PromptKit configuration and source evidence. Scoped pipeline capture records source/reference/incoming artifacts, normalization originals/mappings/ proposals, candidates, complete findings/guidance, fallback/deterministic outcomes, and cache selection/current artifact bytes.

NativeCapture composes existing observers and preparation callbacks. Preparation callbacks retain detached details cheaply; ordinary boundaries write prepared contracts, native results, raw response text, and full readable exchanges. Events are written incrementally. Scope includes operation/step/lane/chunk/validator identity to avoid concurrent evidence collisions.

One invocation ExecutionGroup enrolls actual initial, continuation, and nested validator executions once. Native identity, terminal coverage, and unknown usage remain native facts, not a copied profile/attempt accounting model. Hits can retain prepared evidence without execution or usage. Result-less failures retain availability/cause evidence; undelivered responses are explicitly unassessed.

Native credential omissions and ConfigKit marked-secret paths are preserved. Arbitrary source/prompt/response text is not heuristically rewritten or made safe for general logging. Exact evidence names/nesting/serialized forms are private, not a public protocol or reconstruction requirement. Debug is neither cache input nor an artifact-discovery interface; Operations owns handling.

Focused Verification

Use focused pipeline/cache/recorder/CLI checks for state-boundary changes. Development owns wider validation.