Processing evidence without losing the recovery story

A processing result is not just an output file. We also need to know which input it came from, whether the work finished, and what happens if the process stops halfway through.

The public Processor makes that problem concrete with a deterministic metadata-report operation over immutable raw media. It is not a general AI processing engine. Its database and spool carry the authority; a CLI summary is a projection of that authority, not a replacement for it.

Two stores, different responsibilities

SQLite records artifact metadata, deterministic processing-job state, the derived artifact registration and its one-parent derived_from lineage. The POSIX spool holds raw and derived bytes/manifests, staging files and the advisory publication lock.

Raw evidence is not replaced. The spool still needs to be writable because processing adds derived files and uses staging/locking metadata. “Immutable input” does not mean “a completely read-only filesystem.”

Before processing, the code checks the database, raw artifact identity/digest, file, manifest and media evidence. It rejects ambiguous input assertions instead of choosing an occurrence implicitly. The worker treats MISSING as a snapshot classification—not a persisted job state.

Source: Processor architecture, evidence and eligibility gate.

A durable checkpoint is not a completed result

The processing plan derives job identity from the input digest and the processor/version/output-contract/parameter identity. The important sequence is:

validate input + acquire the spool lock
→ derive the same job identity
→ commit PREPARED
→ stage and publish report, then manifest
→ verify published bytes
→ one database transaction registers artifact + lineage + COMPLETE

There is a deliberate gap between the PREPARED commit and the final database transaction. The database and filesystem are not one distributed atomic transaction. The recovery logic must handle that gap explicitly.

The report is published before its manifest using no-replace filesystem primitives. Files are flushed and checked; directories are synchronized by the staging primitives. Exact compatible final bytes can be adopted. Contradictory content at a content-addressed path fails closed rather than being overwritten.

A report without its manifest is a permitted interrupted state that can be completed on retry. A final manifest without its report is treated as corruption. Invalid or incomplete partials can be quarantined before regeneration; final conflicting evidence is not silently repaired.

Source: publication and partial recovery, staging primitives.

Retry means verify and continue—not start over blindly

If an exact COMPLETE job already exists, the fast path verifies its authority and adopts it without rewriting. If work stopped after PREPARED, retry resumes the same deterministic job identity. It does not create a new job merely because a process restarted.

The synthetic demo exposes normal, resume and busy-lock scenarios. The resume case interrupts immediately after the PREPARED commit, checks that no derived artifact/lineage was committed, resumes the same job to completion and then checks replay. Busy-lock work is deferred without creating a processing job or changing authoritative database state.

These are bounded reliability demonstrations. They do not prove universal exactly-once execution across arbitrary storage providers or concurrent distributed writers.

Source: synthetic reliability demo, worker tests.

Worked synthetic trace: interrupted after PREPARED

The checked-in resume demonstration deliberately stops a child process at the after_prepared_commit barrier. The following is the test’s expected state sequence, not a newly collected run or fabricated console transcript.

These assertions are executable in examples/synthetic_processor.py, _run_resume and relate to the PREPARED/publication path. The demo checks persisted SQLite authority, report/manifest evidence, and the final lineage before considering the sequence passed. The exact generated job ID and hashes depend on the synthetic inputs; no invented ID or digest appears in this example.

To inspect the demo from a properly bootstrapped checkout at the pinned source commit, run its documented entry point and read generated receipts:

python examples/synthetic_processor.py demo
python examples/synthetic_processor.py inspect

The implementation’s README and demo help are authoritative for environment setup. This sequence is a local SQLite/POSIX scenario, not a cloud durability or distributed exactly-once guarantee.

What a reviewer should inspect

Inspect the input and derived manifests, digest bindings, SQLite job state and lineage, then the retained bytes—not only a friendly receipt. Ask whether replay reused the same identity and whether a refusal left the authoritative state unchanged.

The focused local check for this draft ran 15 Processor worker/contract tests successfully after installing the package normally. The first import-only test attempt lacked distribution metadata; that setup error was corrected without changing source. These tests include mocked media probing and are not a new container, filesystem durability, cloud or production-runtime attestation.

The design deliberately favors a bounded single-writer SQLite/POSIX authority model. Lock contention reduces throughput; validation and readback add I/O; recovery is more explicit than “write a file and mark done.” Those are tradeoffs, not incidental implementation details.

The Visual Gateway does not execute this processing path. The separate Showcase JSON/API proof returns a synthetic Processor + Replication execution result that may be cached, using its own bundled worker sources. Neither UI inspection nor this chapter changes Project 03’s frozen audit findings.