feat(cli): one install answers all three registry questions, and lead with it - #75
Merged
Conversation
Until now `pip install trace-verify` answered one of the three questions a
reader can ask of this registry. Inclusion had a CLI. Chain verification was a
Python API with no command. Witness-receipt verification was not in the package
at all. The other two were reachable only by cloning this repository, which is
the opposite of what a public accountability layer should ask of a third party.
trace-verify --claim C.json --proof P.json --entry E.ndjson (unchanged)
trace-verify chain E.ndjson [MORE...]
trace-verify receipt --checkpoint CP.json --response POST.json \
--registry-key HEX --witness-key HEX --expected-log-id ID
The inclusion check keeps its bare-flag form, so every invocation written
against 0.3.x runs unchanged. Only the two literal tokens route; anything else
falls through to the inclusion parser, which also means an argument typo is
reported by the parser the caller was actually using.
verify_against_raw_entries moves from tools/verify_checkpoint_chain.py into
trace_verify._checkpoint as verify_chain_against_entries and is exported. This
is the substantive half. That function is the check that catches a quiet edit to
an already-anchored entry: such an edit leaves every checkpoint record's own
math self-consistent, so the chain check still passes and only the recompute
fails. It was the one check a pip user could not reach. Verified by editing a
single field outside mmr_checkpoint in the September entry: chain consistency
passes, the recompute reports root 5da32203 against the claimed 3af8ddf2.
tools/verify_witness_receipt.py moves to trace_verify._witness. cbor2 and
scitt-cose stay imported inside verify(), so `import trace_verify` still works
for the inclusion-only reader, and a test asserts no top-level import of either
creeps back. The witness extra carries them: pip install "trace-verify[witness]".
Without it, `receipt` names the extra rather than raising ImportError.
Both tools/ scripts stay, re-exporting rather than reimplementing, because the
evidence packets cite them by path and a second copy of a verifier is exactly
what should not exist.
CI smoke-tests all three commands the way a reader who only ran pip install runs
them. 273 tests pass, up from 263.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X2GDChXjA7BAdDNzCAmBJv
The README told a reader to clone this repository and run tools/verify_inclusion.py, while the trace-spec tutorial told them to pip install trace-verify. Two front doors, and the repository's own one was the longer path. It now opens on one install and three commands, and says plainly that answering the first question needs no clone at all, because --entry-url fetches an entry over https from an allowlisted host. pyproject's URL block carried the instruction "Do not point any of these back at trace-registry until that repository is public." That condition has been met. Homepage, Bug Tracker and Changelog come back here, where the code, the issues and the changelog actually are. Documentation and Anchor format stay at trace-spec: those are normative spec documents that describe this implementation, not documents about this package. A test asserts that any URL naming a file in this tree names one that exists, so a rename fails in CI rather than silently on PyPI, which is how the previous breakage lasted a week. The publish workflow now refuses to build a release whose tag disagrees with the packaged version, or whose __version__ disagrees with pyproject. Both 0.3.0 and 0.3.1 shipped answering --version with 0.1.0, so a bug reporter was handing us a string that named neither their release nor the code in it. The guard is checked against the current tree: v0.4.0 passes, v0.3.1 fails. Also: the bug template asks for the installed command first, docs/mmr-checkpoint names `trace-verify chain` before the clone form, and the September 7 evidence packet gains the no-clone invocation beside its existing one, with SHA256SUMS moved to match and sha256sum -c passing on all eight files. 276 tests pass. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01X2GDChXjA7BAdDNzCAmBJv
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The problem
pip install trace-verifyanswered one of the three questions a reader can ask of this registry.trace-verify --claim ...trace-verify chain ...trace-verify receipt ...The second and third were reachable only by cloning this repository, which is the wrong ask for a public accountability layer. The README made it worse by leading with
git clonewhile the trace-spec tutorial led withpip install.The substantive half
verify_against_raw_entriesmoves fromtools/verify_checkpoint_chain.pyintotrace_verify._checkpointasverify_chain_against_entries, and is exported.That function is the check that catches a quiet edit to an already-anchored entry. Such an edit leaves every checkpoint record's own math self-consistent, so the chain-consistency check still passes and only the recompute fails. It existed here and nowhere a pip user could reach it. Verified by editing one field outside
mmr_checkpointin the September entry:Compatibility
The inclusion check keeps its bare-flag form, so every invocation written against 0.3.x runs unchanged. Only the two literal tokens
chainandreceiptroute; anything else falls through to the inclusion parser, which also means an argument typo is reported by the parser the caller was actually using. Tested.cbor2andscitt-cosestay imported insideverify(), soimport trace_verifystill works with no CBOR stack installed, and a test asserts no top-level import of either creeps back. They arrive through a new extra,pip install "trace-verify[witness]"; without it,receiptnames the extra instead of raisingImportError. Bothtools/scripts stay, re-exporting rather than reimplementing, because the evidence packets cite them by path.Two defects found on the way
The published CLI reported the wrong version.
trace-verify0.3.0 and 0.3.1 both answer--versionwith0.1.0—__version__had not moved since #19 and nothing compared it to anything. A bug reporter was handing us a string naming neither their release nor the code in it. The publish workflow now refuses a release whose tag disagrees with the packaged version, or whose__version__disagrees withpyproject.toml. Checked against this tree:v0.4.0passes,v0.3.1fails.pyproject's own comment said to undo it. It read "Do not point any of these back at trace-registry until that repository is public." The repo is public. Homepage, Bug Tracker and Changelog come back; Documentation and Anchor format stay at trace-spec, where the normative text belongs. A test asserts any URL naming a file in this tree names one that exists, since the previous breakage went unnoticed for a week.
Verification
276 tests pass, up from 263. CI smoke-tests all three commands the way a reader who only ran
pip installruns them. All three were also run from a clean venv against a built wheel, plus a base install without the extra to confirmchainstill works andreceiptexplains itself.sha256sum -cpasses on all eight files of the September 7 packet.🤖 Generated with Claude Code
https://claude.ai/code/session_01X2GDChXjA7BAdDNzCAmBJv