What it does for you
Proof Surface checks the records AI workflows leave behind: authorization receipts, pre-execution gates, claim ledgers, delegation chains and evidence packets. Each validator returns the exact location of every problem, and each decision helper is default-deny. On top, eleven domain wedges turn evidence a tool already produces into a packet with a MATCH, DRIFT or UNVERIFIABLE verdict that anyone can recompute. It never emits TRUSTED, APPROVED or AUTHORIZED.
- Default-deny checksA revoked grant, an expired window or an out-of-scope action all deny, with the field that decided it.
- Unknown means a person looksA gate check that cannot be confirmed escalates to needs-human and never passes.
- Packets you can recomputeEach wedge writes the packet, a report and crucible inputs so a checker re-derives the verdict.
- No authority wordsValidators reject authority-shaped fields; the library records evidence and grants nothing.
Source: README.md at 3d5d945 (version 0.2.0)
Watch
Video walkthrough: coming with the next release.
How it works, one step at a time
Scroll, or use the step buttons. Every line is output from proof-surface at commit 3d5d945: the worked example and examples/demo.py, and the visual-measurement wedge on its shipped example input.
- 01
A grant to read, and nothing else
Alice grants an agent permission to
read_fileonrepo:proof-surface, from 17 to 19 June 2026. The receipt validates with no issues.check_actionon 18 June allows a read: it returns nothing.Source: README.md, "Worked example"; src/proof_surface/__init__.py
- 02
Everything else is denied, with the reason
The check is default-deny. Pick each request in the panel: a delete, another repository, a day after the window, a revoked grant. Each denial names the field that decided it.
A receipt that adds an unexpected field such as
approvedfails validation: the shape is closed at every level. - 03
A gate before the action runs
evaluate_gatetakes one planned action and runs four checks: authorization, budget, state and the human gap. Each returns pass, fail, unknown or not applicable.The aggregate is not a vote. Any fail denies. With no fail but any unknown, a person has to look. Allow needs authorization to pass outright. Drop the budget estimate and the same request escalates.
Source: src/proof_surface/pre_execution_gate.py,
evaluate_gate - 04
Delegation that can only narrow
A delegation chain roots authority in a real person, and each hop can only narrow the scope. The demo's chain verifies VALID for an in-scope action and DENIED for one outside it.
Asked for signature assurance with no verifier available, it returns UNVERIFIABLE. The chain is hash-linked but keyless, so it shows self-consistency. Tamper evidence against someone who rewrites every hash needs an external anchor.
Source: src/proof_surface/delegation_chain.py; README.md, "The base contracts"
- 05
A proof packet from a real measurement
The visual-measurement wedge takes a capture's measurements: a mean Delta E 2000 of 1.42 against a tolerance of 2.0, and a white luminance of 118 cd/m2 against a target of 120 with a tolerance of 5. Both are within tolerance, so the packet reads MATCH.
It writes six files: the packet, a report, a content-addressed bundle, and the crucible thesis, measurements and assessment for an independent recheck. The packet is read-only and makes no physical-calibration claim.
Source: examples/visual_measurement/measurement.json; src/proof_surface/visual_measurement/builder.py
- 06
The gate on an inflated claim
A read-only capture never touched the display, so it may not claim a physical calibration. Mark the packet's calibration boundary as a physical-calibration claim, with no hardware measurement, no instrument and no mutation evidence, and validation rejects it, even though both measurements still read MATCH.
The gate reads the structured boundary. The free-text claim line is recorded as written.
Source: src/proof_surface/visual_measurement/_calibration.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 a checkout. Python 3.10 or newer.
$ git clone https://github.com/HarperZ9/proof-surface && cd proof-surface $ python -m pip install -e ".[test]"First run: the demo
The demo gates the same action with and without a budget.
$ python examples/demo.py with budget : allow without budget : needs-humanBuild a proof packet from a measurement
Turn a real measurement into a packet with a stated claim and scope.
$ telos-proof visual-measurement --input examples/visual_measurement/measurement.json --claim "sRGB coverage measured on a read-only capture" --scope "software capture only, no hardware probe" --out ./demo-out | delta_e_2000_mean | 1.42 dE | 0.0 | 1.42 | 2.0 | MATCH | | white_luminance | 118.0 cd/m2 | 120.0 | 2.0 | 5.0 | MATCH | Calibration boundary: hardware_measurement_used=False, physical_calibration_claim=False bundle.json crucible-assessment.json crucible-measurements.json crucible-thesis.json packet.json report.md
Output from proof-surface at 3d5d945 on Windows with Python 3.12.
What it does not do
- Proof Surface validates records. It grants no authority, executes no action and stores no private payload.
- Decision helpers are advisory. The caller must enforce the decision.
- The delegation chain is keyless. It gives self-consistent integrity, and real anti-forgery needs an external anchor or per-hop signatures.
- Honesty gates read structured fields. A free-text claim is recorded as written and is not parsed for overclaims.
- The claim ledger reports provenance and declared conflicts. It does not decide which claim is true.
Source: README.md at 3d5d945, "Why it matters" and "The base contracts"; src/proof_surface/visual_measurement/_calibration.py
Check what stuck
Answer each one in your head before you open it.
check_action returns None. What does that mean?
The action is allowed. Every denial comes back as an Issue naming the field that decided it.
A gate request has no budget estimate. Why is the answer needs-human and not allow?
The budget check returns unknown, and any unknown with no fail escalates to a person.
Why can a keyless hash chain not stop a forger?
Someone who rewrites the document can recompute every hash. Only an outside anchor or signatures fix that.
Both measurements read MATCH, yet the packet is rejected. Why?
Its calibration boundary claims a physical calibration without a hardware measurement, an instrument, mutation evidence and a non-read-only packet.