Evidence
How a Numinance change becomes a signed, hash-linked record chain that an independent party can verify offline, and what that verification does and does not prove.
evidence/v1), its schemas, the conformance vectors and the offline verifier are public and runnable today. Exports are produced by the proprietary Numinance runtime, which is not generally available.Don't trust the agent. Check the evidence.
Evidence is engineering accounting
An autonomous engineer is only as credible as the account it leaves behind. Numinance treats that account as a first-class artifact: every change produces an append-only chain of records written by the runner identity, not by the agent. Each record names the action, the actor, the policy decision that allowed it, the risk class, the inputs and outputs by digest, and the outcome, including denied. The chain is exported as a plain directory of files that someone who does not run Numinance can check.
That someone needs three things and nothing else: the export directory, the public key of the runner, and the public key and origin of the transparency log. They do not need the engine, a network connection or an account. The checker is numi evidence verify in the open build, a thin wrapper over the Go package sdk/go/evidenceverify, which is written from the public specification only and uses the standard library only.
The design consequence is the one that matters: the party that ran the agent is not the party whose word you take. You decide which keys to trust before you look at the export, and the verifier tells you how much of the account those keys can vouch for.
What you can do with it today
| Task | Where |
|---|---|
| Read the shape of a record and the rules of the chain | Record chain |
| Know which files an export directory holds and why | Export format |
| Verify an export with the CLI or from Go, read the exit codes | Offline verification |
Interpret verified, self-consistent, unauthenticated and the rest | Trust levels |
| Understand checkpoints, inclusion proofs and component receipts | Anchoring and receipts |
| Run the 302 conformance vectors against a verifier | Conformance vectors |
| Know what a pass cannot tell you | Threat model and limits |
How the parts fit
Evidence chain inspector
What does verification actually establish, and which inputs does it depend on?
Hash-linked records (drawing 6 of 12)
- seq 1link
previous_record_hash empty (sequence 1)
signature verified - seq 2link
links to previous
signature verified - seq 3link
links to previous
signature verified - seq 4link
links to previous
signature verified - seq 5link
links to previous
signature verified - seq 12 (head)link
terminal state: Closed
signature verified
attestation.json
signed summary, re-derived from the chain
verifiedhead-checkpoint + inclusion proof
checked under the pinned log key and origin
verifiedVerifier inputs (what you bring, not what the export says)
- ✓ pinned runner key(s)
- ✓ pinned log key + origin
- provenance/signers.json and any checkpoint in the export are claims, not trust.
numi evidence verify --runner-key keys/runner.pub --log-key keys/log.pub --log-origin numinance.test/log --complete exports/closed-author
simulated output, shape as in the real CLI
change: chg_01010101010101010101010101010101 records: 12, head sha256:8dec4e3d… state: ended Closed level: verified chain: records link, hash and end as stated signatures: verified under the pinned runner keys anchor: head proved under the pinned log attestation: signed, re-derived from the chain result: verified
exit 0
level: verifiedexit 0
Provenance and chain integrity hold under keys and a log you pinned.
What this does NOT prove, at any level
- The code is correct.
- The tests are thorough.
- The model reasoned well.
- Completeness against a compromised host: events it never logged are not in the chain.
Level verified, exit 0. No findings or weaknesses.
Text description
Illustrative and simulated: no export is read. The rules are those of docs/evidence/verification.md; the baseline report is the real output of the open verifier on the conformance export exports/closed-author.
- You must choose exactly one key mode. Pinned runner keys (
--runner-key) are the only way to reachverified.--trust-bundle-keystakes the keys the export claims and tops out atself-consistent.--skip-signaturestops out atunauthenticated. - A pinned log (
--log-keywith--log-origin) is needed to prove the head. Without it the result isunanchored(exit 5) unless--allow-unanchoredis given. - Any finding makes the level
failed(exit 3). Edit or remove a record:chain_broken. A chain signed by a key you did not pin:signer_untrusted. With keys from the export or signatures skipped, the same forged-but-consistent chain is not caught, which is why those levels are weaker. - Exit codes: 0 verified, 3 failed, 5 consistent but weaker than verified.
Verified does not prove the code is correct, the tests are thorough, the model reasoned well, or that a compromised host logged every event.
The pipeline has five stages, and each is verifiable on its own terms.
- Actions become records. Every privileged action, lifecycle transition and policy denial becomes one canonical JSON record. Records are hash-linked: record
ncarries the hash of recordn-1. - Records are signed. The runner signs each record with an Ed25519 key. The signature covers the chain fields, so reordering or editing a record is visible.
- Components add receipts. The credential broker and the egress proxy state what they did as records in the same chain, so an auditor reads component behavior from the chain and not from a side log.
- The log anchors the head. A transparency log commits the chain head, and the attestation, in a Merkle tree. An inclusion proof in the export lets a verifier confirm the head against a log key it pinned.
- The export is a directory. Records, a summary, an index, derived views, a signed attestation and a signed manifest of every file. The verifier reads it as untrusted input.
Verification then runs the other way. It decodes strictly, re-derives everything the chain can state (summary, diff digest, views, attestation fields), checks signatures against your pinned keys, and reports one level and a set of findings.
What one real run looks like
This is the open verifier against a conformance fixture, a golden export generated by the Numinance evidence code over in-memory adapters with fixed test keys. It is not an export of a real engineering run. The test public keys are stored in the spec repository.
$ numi evidence verify --runner-key keys/runner.pub --log-key keys/log.pub --log-origin numinance.test/log --complete exports/closed-author
change: chg_01010101010101010101010101010101
records: 12, head sha256:8dec4e3d5cf4bd7650ef6010671298793c05493cb20c3dd946bc3ef805689e48
state: ended Closed
level: verified
chain: records link, hash and end as stated
signatures: verified under the pinned runner keys
anchor: head proved under the pinned log
attestation: signed, re-derived from the chain
credential_scopes: unsourced: no credential broker statement is in the attestation
network_policy: unsourced: no egress proxy statement is in the attestation
not applicable: deployment.json (not applicable at PR level: the change closed from Merging (design section 6) and was never released, deployed or observed)
not applicable: observation.json (not applicable at PR level: the change closed from Merging (design section 6) and was never released, deployed or observed)
result: verifiedRead the last two notes before the verdict. The attestation states no credential-broker or egress-proxy source, and the verifier says so as a note instead of hiding it. A verified result is exact about what it verified; it does not round up.
The boundary, stated once
Verified is provenance, not correctness
verified means the records link and hash as stated, the signatures hold under keys you pinned, and the head is proved under a log you pinned. It does not mean the code is correct, the tests were thorough, the model reasoned well, or that a compromised host logged every event. Numinance's own verifier stages and your own review decide quality. Evidence decides who did what, in what order, under which decision. See Threat model and limits.
Two more boundaries keep the claim honest:
- There is no built-in trust root. A key stated by the export never reaches
verified, whatever it says about itself. - Passing the conformance vectors shows that a verifier agrees with the specification at a version. It is not an audit or a certification of any deployment.
Where it fits in the rest of the platform
Evidence is the last link of the loop that governed execution opens: policy decides before the action, the runner writes the record at the action, and a third party checks the record afterwards. The concept-level view is in Evidence and trust. To run the verifier on your own machine in a few minutes, use the evidence quickstart.
Kinds and JSON Schema
How the sixteen configuration kinds map to protobuf messages, the strict JSON Schemas generated from them, and what numi validate --files does and does not check.
Record chain
The canonical form, fields, hash links and signatures of an evidence/v1 record, how a verifier walks the chain, and why denied actions are recorded.