Reproducibility¶
Every artifact is reproducible from a versioned source specification plus an overlay, and says which bytes it came from.
Digests everywhere¶
Every document loaded during a compile is digested, not only the root. The IR, plan, policy manifest, surface and overlay all carry the source digest, so an artifact cannot be detached from the specification revision that produced it.
Canonical JSON makes this stable: object keys are sorted so dictionary insertion order cannot change the bytes, while sequences are never reordered, because operation order is source order and is itself part of the contract.
Overlays are bound, and rebinding is explicit¶
An overlay records human decisions against a specification revision. If the specification changes, the overlay no longer matches and is refused rather than silently applied. Rebinding is a separate, deliberate command:
This has teeth in practice. Editing a comment in an example specification changes its bytes, its digest, its IR and every golden artifact downstream, and the gate refuses until the overlay is restamped. A cosmetic edit is still an edit.
Golden artifacts¶
Golden IR, plan, policy, surface, review and evaluation artifacts are committed. Regenerate them deliberately and read the diff:
An unexplained diff means the change was not the one intended. The same command refreshes the notebook's stored outputs, so one run produces the whole diff to review.
The notebook is held to the same standard¶
A notebook is documentation that claims to be a transcript, and a reader cannot tell a printed digest that is current from one that was current a year ago. So its stored outputs are regenerated by a command, compared by the verification gate, and never hand-edited.
The distribution is checked, not assumed¶
The verification gate builds the wheel and the sdist, reads both archives for every declared contract schema, unpacks the wheel elsewhere, and makes an installed copy validate an artifact with no source tree on the path. Then it makes that copy reject an invalid artifact, because a validator that accepted everything would pass the first half.
This exists because the opposite was true for most of the project's life: the schemas lived at the repository root, every test passed against the source tree, and the wheel shipped none of them.