How Repo Proof Index works

What it does for you

As a repository collects receipts and proof packets, a reviewer needs to find what each one claims and where its evidence lives. Repo Proof Index reads them all, whatever their shape, and gives one row per artifact: its kind, the surface it describes, the status it reports, a short evidence line and its path. It says plainly which statuses it checked and which it only read.

One table for many shapesProof contracts, proof-surface packets, witness receipts and backend descriptors all become rows.
Declared is not verifiedEach row records the producer's status and a separate verification state.
Action items--summary counts kinds and statuses and lists what needs work.
A strict reader firstDuplicate keys, NaN and Infinity, oversized files and deep nesting are rejected before indexing.

Source: README.md at 11a3121 (version 0.2.0)

Watch

No concept film fits this tool closely yet. The walkthrough below covers it in text, with real commands and output.

Video walkthrough: coming with the next release.

How it works, one step at a time

Scroll, or use the step buttons. The panel indexes the four artifacts in examples/contracts/. Every line is output from repo-proof-index at commit 11a3121.

01
Four artifacts, one table

The examples hold a proof-surface packet, a backend capability descriptor, a product use-case contract and a witness receipt. Each has its own shape. The index gives every one the same columns.

Source: examples/contracts; src/repo_proof_index/indexer.py
02
A status read is not a status checked

The witness receipt says MATCH. The index records that as the producer's status and sets its own verification state to not_assessed, because it did not re-run the witness. It indexes the evidence; it does not decide whether the evidence is enough.

Source: src/repo_proof_index/indexer.py; README.md, opening paragraph
03
A summary with what to do next

--summary counts the kinds, the statuses and the verification states, and turns any status that needs work into an action item. Here the proof-surface packet says it needs polish.

Source: src/repo_proof_index/cli.py
04
Validate a packet's shape

--validate checks a proof-surface packet against the shared contract. The example packet is structurally valid. Valid shape and a verified status are different things, and the index keeps them apart.

Source: src/repo_proof_index/cli.py; the proof-surface packet contract
05
A strict reader before a tolerant one

The parser tolerates unknown shapes, but only after a strict JSON read. A key written twice, such as a status of MATCH and then DRIFT, is rejected; so is a NaN value, and so is a file that holds no JSON object. Pick each file in the panel.

Source: src/repo_proof_index/strict_json.py

Walkthrough

Install it, run it once, then use the main feature. Each command below is real, and so is its output.

Install

Install from PyPI and clone for the examples. Python 3.10 or newer.

$ python -m pip install repo-proof-index
$ git clone https://github.com/HarperZ9/repo-proof-index && cd repo-proof-index

First run: index one record

Read one proof record and report its kind and verification state.

$ repo-proof-index examples/contracts/sample-witness-receipt.json --json
"kind": "witness-receipt"
"status": "MATCH"
"producer_status": "MATCH"
"verification_state": "not_assessed"

Summarize a folder

Count records by verification state.

$ repo-proof-index examples/contracts/*.json --summary
total: 4
kinds: backend-capability=1, product-use-case=1, proof-surface-packet=1, witness-receipt=1
statuses: MATCH=1, backend-matrix=1, needs-polish=1, release-candidate=1
verification_states: not_assessed=3, not_verified=1
evidence_gaps: 0
action_items:
- proof-surface-public-release-demo: resolve needs-polish

A malformed record is rejected
A file with a duplicate key is refused.
```
$ repo-proof-index dup.json
error: duplicate JSON key: status
```

Output from repo-proof-index at 11a3121 run from source with proof-surface on the path.

What it does not do

It indexes evidence. It does not decide whether the evidence is enough, and it produces no compliance finding.
A status in the table is the producer's word unless the verification state says otherwise.
Shape-tolerant parsing gives unknown artifacts best-effort fields, which a reviewer should read as guesses.

Source: README.md at 11a3121, opening paragraph, "Current status" and "Existing technical notes"

Check what stuck

Answer each one in your head before you open it.

The witness receipt says MATCH. What is its verification state, and why?

not_assessed: the index read the status and did not re-run the witness.

A file writes the key status twice. What happens?

The strict reader rejects it before indexing: duplicate JSON key.

What turns a row into an action item?

A status that needs work, such as the packet's needs-polish.

What it does for you

Watch

How it works, one step at a time

Four artifacts, one table

A status read is not a status checked

A summary with what to do next

Validate a packet's shape

A strict reader before a tolerant one