What it does for you
Receipts help only when a reviewer can read them quickly. Proof Surface Report takes proof-surface packets and EMET witness receipts and writes one Markdown handoff: a summary table, each packet's claims, checks and action items, and each receipt's verdict, subject and evidence. It refuses wording that would turn the handoff into an approval or a certification.
- One readable handoffPackets and receipts in, one Markdown report out, with sources named.
- Shape checked firstUnknown fields and ungoverned verdicts are rejected before anything renders.
- No authority wordsCertified, approved, compliant and safe to release are refused in titles, claims and verdicts.
- A small adapterStandard library plus the shared proof-surface contract package.
Source: README.md at a930401 (version 0.1.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 renders the bundled synthetic examples, examples/public-surface.packet.json and examples/emet.receipt.json. Every line is output from proof-surface-report at commit a930401.
- 01
A packet and a receipt
The packet comes from a public-surface sweep: three claims, one check that warned at score 90, and one action item about an em dash in a README. The receipt is from EMET: a MATCH on README.md with its digest and the witness's own facts.
Source: examples/public-surface.packet.json, examples/emet.receipt.json
- 02
One Markdown handoff
The renderer validates both, then writes a summary table and a section for each artifact. The report opens by calling itself an evidence handoff, and disclaims certification, safety verdicts and authority in the same sentence.
Source: src/proof_surface_report/core.py
- 03
Two packets roll up to the weaker status
Render the public-surface packet with the provenance packet beside it. The provenance packet is ready; the public-surface packet needs polish. The summary counts six claims and two checks, and the aggregate status is needs-polish: the report carries the weaker of the two forward.
Source: examples/provenance.packet.json; src/proof_surface_report/core.py
- 04
Shape is checked before wording
Add a field the packet contract does not define, such as
reviewer_signoff, and validation fails before rendering starts. A handoff cannot carry a sign-off field in through the side.Source: the proof-surface packet contract; src/proof_surface_report/core.py
- 05
Words that would overclaim are refused
Give the report the title "Certified release review" and it refuses to render. Write a claim that the release is approved and safe to release, and the packet fails validation, naming each word. Set a receipt's verdict to TRUSTED, a word outside EMET's closed set, and it is rejected. Pick each case in the panel.
Source: src/proof_surface_report/core.py; README.md, "Existing technical notes"
Walkthrough
Install it, run it once, then use the main feature. Each command below is real, and so is its output.
Install
Install the proof-surface contract, then this package. Python 3.10 or newer.
$ pip install git+https://github.com/HarperZ9/proof-surface.git $ git clone https://github.com/HarperZ9/proof-surface-report && cd proof-surface-report $ pip install .First run: render a report
Render a packet and a receipt into one report.
$ proof-surface-report examples/public-surface.packet.json examples/emet.receipt.json # Proof Surface Handoff Report This report summarizes proof-surface artifacts. It is an evidence handoff, not a certification, safety verdict, or authority claim. | Packets | 1 | | Witness receipts | 1 | | Aggregate status | needs-polish | ### Claims - Public text hygiene is checkable. Evidence: em-dash findings=1 ### Action Items - README.md:14: replace em dash with plain punctuation ## Witness Receipt: emet-verify-example-7d26e03c2a4f13b0 | Verdict | MATCH |An inflated title is refused
A title that claims more than the evidence shows is refused.
$ proof-surface-report examples/public-surface.packet.json --title "Certified release review" error: report title validation failed: $.title contains authority-shaped wording: certified
Output from proof-surface-report at a930401 with proof-surface on the path. The two refused files change one field each in copies of the bundled examples.
What it does not do
- It renders a handoff. It is not a release approval system and makes no certification, safety or compliance finding.
- The wording guard catches the words on its list. A claim can still overstate in other words, and a reviewer reads for that.
- It validates two artifact shapes, proof-surface packets and EMET witness receipts. Other shapes are rejected.
Source: README.md at a930401, "Current status" and "Existing technical notes"
Check what stuck
Answer each one in your head before you open it.
What does the report call itself at the top?
An evidence handoff, with certification, safety verdicts and authority disclaimed.
Why is a receipt with the verdict TRUSTED rejected twice over?
TRUSTED is outside EMET's closed verdict set, and it is also a forbidden authority token.
Where does the authority-word guard apply?
In artifact text, such as claims, and in the report title.