onetrace

onetrace makes a pipeline write a record as it runs: one receipt per stage, and a manifest that chains the receipts together. Anyone can then check the record, and compare two runs, with tools that don't trust your code.

This is onetrace 0.2.0 and onetrace-verify 0.2.0. Start with the quickstart.

What onetrace is

• One receipt per stage. Each receipt says what the stage read and what it wrote, by sha256 digest; which tool did the work and how it was configured; and how the stage ended.
• A manifest chains the receipts in order, ending in a chain head. Change, remove or reorder any receipt and the chain no longer matches.
• A run folder holds MANIFEST.json, receipts/ and artifacts/: each stage's outputs, which can include documents, prompts and answers. Treat run folders like logs that may contain sensitive data.
• onetrace-verify reads the run folder and prints one row per check, each PASS, FAIL or NOT-RUN, then the result. Exit code 0 is PASS: the record is consistent and unbroken. Exit code 1 is FAIL, and the [FAIL] rows say which check failed. Exit code 2 is NOT VERIFIED or refused: a receipt's format this verifier doesn't implement, with nothing failed, or a manifest it can't read.
• Beside the chain, never part of it: an anchor in anchors/, a timestamp proof over the chain head from a party outside the recorder, and a signature in signatures/, an Ed25519 signature over the chain head by a key you hold. Signing changes no byte that was there before.

Install and run

1. Install: pip install onetrace. onetrace-verify, the reference verifier, comes with it.
2. Add two decorators: @ot.run on the function that does the whole job once, and @ot.stage on each step. Change nothing else.
3. Run it: the run writes a folder under runs/, named by its run id.
4. Verify it: onetrace-verify --require-artifacts runs/<run id>. When a run closes, onetrace prints that command for it.

Comparing two runs

• onetrace diff A B calls the reference verifier first. A run the verifier refuses is refused by the verb too.
• Then every stage gets exactly one of five verdicts: same, FIRST DIFFERENCE, downstream, reconverged or COULD NOT CHECK. A verdict is always about a stage's output.
• onetrace localize finds the first unclean stage in one run, or the first difference between two runs, and its cause.
• onetrace diff A B --text shows the first stage that differs and the text that changed in its outputs, checked against the receipts first.

What each verdict and result means.

What it does not show

• onetrace does not check whether a pipeline's output is true. It checks what was recorded, and whether an independent verifier can confirm that record is internally consistent and its chain unbroken.
• same does not mean "nothing changed". It means a stage's output digest matched.
• A signature does not show that the key wasn't stolen or misused, or who the person behind the key is.

Everything onetrace does not claim.

Where next

• Quickstart: add onetrace to a small pipeline in two steps, one stage first, then the rest; then switch it off, and take it out.
• Developer manual: from knowing nothing about onetrace to recording, verifying and comparing your own pipeline's runs.
• Error messages and their fixes: every refusal, why it happens, the one-line fix.
• Agent recipe: instrument an existing pipeline.
• On PyPI: the onetrace package and the onetrace-verify package.
• Report an issue.