> ## Documentation Index > Fetch the complete documentation index at: https://delivery.vexa.ai/llms.txt > Use this file to discover all available pages before exploring further. # The evidence model > Values, rank, the three subjects, and contracts as the gates to a channel — with what is built and what is not. This is the model the factory is being built to. It is not a description of what runs today. **Every table carries a `State` column, and [State of implementation](#state-of-implementation) is the same picture in one place, as of 2026-08-29.** A spec written as though it were all shipped is a lie with a schema attached, and the honest state is part of what makes the rest credible. | Marker | Meaning | | --------------- | ------------------------------------------------------------ | | **BUILT** | code exists, runs, and has produced the artifact in question | | **IN REVIEW** | written and under review — the PR is named | | **RULED** | decided, not built | | **NOT STARTED** | no execution, no code | ## The objective A merge reaches production the same day, through machine gates, and every claim made about it is provable: traceable from **value → evidence → environment**, and verifiable offline by a subscriber whose cluster the vendor never touches. Two concerns, deliberately separate: * **Delivery speed** — how long a merge takes to become a running image. * **Provability** — whether what shipped can be shown to have earned it. **Evidence never blocks the loop. It rides it.** A gate that halts delivery to collect evidence turns provability into a tax, and a taxed loop stops turning. Evidence is emitted by steps that were going to run anyway, signed where it is produced, and carried forward by digest. ## Value and evidence are different nouns The single most load-bearing distinction in this model, and the one that collapses first if left implicit. | | **A value** | **Evidence** | | -------------- | ----------------------------------------- | ---------------------------------- | | What it is | a claim | an observation | | Shape | one sentence a human can witness | a signed envelope | | Declared | on the work item, before the work | by the step that produced it | | Identity | a `value_id` that travels with the change | subject digest + predicate type | | Always carries | its rank (below) | the environment it was observed in | | Answers | *what did we say this does* | *what was seen, where* | **The relation is many-to-many.** One evidence run covers many values — a single set-level validation exercises dozens of claims at once. One value needs fresh evidence per environment: the same claim proven in staging is not proven in production, because the configuration differs and the configuration is what makes an observation mean anything. See ADR-0010 (in review, [#10](https://github.com/Vexa-ai/vexa-delivery/pull/10)) § *What must ride with the per-image claim, or it means nothing*: the per-image claim carries the configuration it was exercised under, or it is not a claim. **Environment is stamped, never inferred.** An envelope without the environment it ran on is a sentence with the subject removed. **Nondeterministic modules get statistical evidence, not a green tick.** Where a module is flaky by nature — a browser joining a live meeting, a transcription pass over real audio — a single passing run is evidence that it passed once, which is not the claim anyone cares about. The evidence is a **rate over a declared window**: numerator, denominator, window bounds, and the environment. A threshold is then a contract predicate over that rate, not a boolean the producer decides. ### What a soak is **A soak is letting a release carry real production traffic for a declared stretch, and counting what happened.** Not a test suite, not a longer test suite — the same work the software does for users anyway, watched. Its output is a rate over a window: this many meetings joined out of this many attempted, over these hours, on these image digests, in this environment. It exists because some claims cannot be made any other way. A join path that works ten times in a test rig and fails one time in twenty against real calendars, real networks and real meeting platforms has a defect a suite will never see; only volume finds it. So the soak is the producer for `statistical`-rank values, and the reason production traffic is an evidence source rather than merely the thing we are protecting. Two properties matter downstream. **It is per-digest**, so the claim survives into any assembly that reuses those images. And **it keeps running**, so it is the standing watch that catches interactions nobody predicted, described in [evidence reuse](evidence-reuse). | Element | State | | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `value_id` declared on the work item and carried to the candidate map | **RULED, NOT BUILT** — minimal form planned: `value_ids[]` on the candidate map | | Environment stamped on every evidence row | **BUILT** for entry-level evidence; **RULED, NOT BUILT** per-image | | Statistical evidence as a rate over a declared window | **IN REVIEW** — spec draft v2 in [#10](https://github.com/Vexa-ai/vexa-delivery/pull/10); no producer | ## Rank — who can prove a claim Every value declares its **rank**. Every evidence envelope records **how it was produced**. The contract is where the two meet. | Rank | What can produce it | Example | State | | ------------- | ----------------------------------- | -------------------------------------------------- | -------------------- | | `autonomous` | a machine gate that ran and exited | a named CI gate result; a schema conformance check | **RULED, NOT BUILT** | | `statistical` | a metric window over real operation | a production soak: rate over a declared window | **RULED, NOT BUILT** | | `human` | only a person, attesting | perceived transcription quality; a value sign-off | **RULED, NOT BUILT** | **Enforcement is by signature, not by convention.** Rank maps to the class of functionary permitted to sign the evidence that satisfies it. A contract row for a `human`-rank value requires an attestation signed by a **human identity**; a green CI run cannot satisfy it, however many gates it contains, because no human key signed anything. Conversely an `autonomous` row is not satisfied by a person asserting the gate passed — the gate's own signed result is the only thing that counts. This is what makes rank more than a label: it is a constraint on the permitted signer set, checked by the same machinery that checks anything else in the contract. The witness flow — a human observing a run and recording what they saw — exists today and is **unsigned**, so nothing it produces can satisfy a `human`-rank row yet. That gap is the work, not an oversight. ## The three subjects A claim binds to the thing it is actually about, and to nothing larger. Full reasoning in ADR-0010 (in review, [#10](https://github.com/Vexa-ai/vexa-delivery/pull/10) — not on `main`, so it is referenced by PR, not by path); the shape: ``` PULL REQUEST compliance · security · value · rights · licence (repo#number, claims about a CHANGE AND ITS ARGUMENT pinned to its merge commit SHA) │ │ merge commit → release archive → SLSA source provenance ▼ IMAGE DIGEST build provenance · SBOM · CVE scan · prod soak (sha256:…) claims about an ARTIFACT │ │ collected by the candidate map (image → source, per image) ▼ DIGEST SET station verdict · delivery receipt (the entry's images) claims about an ASSEMBLY ``` **The pull request, not the commit.** A commit is a diff; a PR is a diff **with an argument attached**, and compliance and value are judgments about the argument. The merge commit rides along as the *binding* — the path by which a PR's claims reach an image — not as the subject. **Set-level validation exists because some claims are assembly claims.** *"The documented API surface works as documented"* is not provable on a PR: no single change owns it, and it is false or true only of a running assembly. **Set evidence binds to the set and decomposes onto members.** The vocabulary already exists in [`validation-contract.schema.json`](https://github.com/Vexa-ai/vexa-delivery/blob/main/spec/validation-contract.schema.json), and it is the point of that document: | Field | What it carries | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `dependencies[].fidelity` | `real` · `double(…)` · `dummy-endpoint` · `absent`; anything but `real` REQUIRES a justification | | `proves` | one line: what this configuration genuinely establishes | | `does_not_prove` | one line: what a reader must NOT conclude | | `unproven_claims[]` | claims an absent or substituted dependency makes unavailable, written out so a receipt cannot accidentally assert them | An image reused in a different assembly therefore inherits exactly what the configuration rows justify — not the set's verdict, and not nothing. A consumer running outside the exercised configuration does not get a weaker claim; they get the claim plus the explicit statement of what it does not prove for them, and their contract decides whether that is enough. **Through `value_id`s on the candidate map, one set run validates many PRs.** Some claims are only ever true of an assembly — *"the documented API surface responds as documented"* is nobody's pull request — so they are proven once against the set, then **propagate down the two edges the map already holds**: | Direction | How it propagates | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | set → **image** | the observation records the digests it exercised and the configuration it ran under, so each digest carries the part of the claim its configuration rows justify | | set → **pull request** | each image resolves through the map to its source commits and their PRs, so a PR's value id is discharged by the set run that exercised the image it produced | Carrying the value ids on the map is the whole mechanism. One set-level observation settles the claims of every change inside it with nothing re-run per PR — and a PR whose value id no set run covered shows as `unproven` rather than quietly passing. | Element | State | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | PR as an attestation subject | **RULED, NOT BUILT** | | Image-digest subject: candidate map binds image → source → runs | **BUILT** | | Per-image SLSA provenance | **NOT STARTED** — every entry declares `image_provenance` in `evidence_absent[]` | | Digest-set subject: station verdict + delivery receipt | verdict producer and chart wiring **IN REVIEW** ([#10](https://github.com/Vexa-ai/vexa-delivery/pull/10)); delivery receipt **BUILT** | | Decomposition vocabulary (`proves` / `does_not_prove` / `unproven_claims`) | **BUILT** as schema; **no producer** | | `value_ids[]` on the candidate map | **RULED, NOT BUILT** | ## Contracts are the gates to channels A **channel** is an ordered stream of entries ([`channel.md`](https://github.com/Vexa-ai/vexa-delivery/blob/main/spec/channel.md)). A **contract** is what decides whether an entry may enter it, and whether an entry may run once pulled. **The contract belongs to the channel.** Not to a release train, and not to a station: a staging station and a prod station are two **enforcement points** of the same channel contract, and neither owns one of its own. Composition is across channels — `oenb-stable` extends `vexa-internal` and may only tighten it. Founder correction, 2026-08-29, recorded on [#12](https://github.com/Vexa-ai/vexa-delivery/issues/12); the mechanics are on [How channel contracts compose](contract-composition). A contract is a machine-readable list of: * **required evidence** — kind, and (ruled, not built) the rank or signer identity that must have produced it, and its freshness bound; * **refusals** — including the refusal of a *declared absence*: `evidence_absent[]` states what an entry does not carry, and `forbid_absent_evidence` is how a subscriber refuses an entry for declaring away something they require. The gap becomes checkable data rather than silence. ### The contract is a form; a station run fills it in The other founder ruling of 2026-08-29, on the same issue: **there is no separate validation document.** The contract is the form, and a run fills it in — per row, beside the demand it answers: `proof: proven | unproven | not-run`, a pointer to the evidence that proves it, the **fidelity** of whatever stood in for a real dependency, and a `does_not_prove` line. The decomposition vocabulary that used to live in a standalone document moves onto the rows it qualifies, so a reader stops holding two files side by side working out which caveat attaches to which claim. One train yields **one filled instance** of its channel's contract: the same `contract_id`, sha-linked back to the unfilled demand. The demand is constant across the trains that run on a channel; the **proof column is what varies per set**. The verdict is that instance's bottom line and the PROOF card is that instance rendered — one record, two readings, neither written by hand. Every demand row appears in the instance whether or not it was answered, and the verdict has a third value, `INCOMPLETE`, for a run that ended with required rows neither proven nor refuted — so a station that could not reach a dependency cannot be filed as a pass or as a failure. The definition is **`spec/filled-contract.schema.json`**, committed with the seq-7 respin and not on `main` yet: as of that turn it defines the document and validates instances offline, nothing produces one, and the in-cluster verifier does not read it. The evidence kind on the wire stays `validation_contract`. The name is now wrong for what it carries and is kept this turn anyway, because the entry schema, the carriage predicates that name it in `require_evidence_kinds` and `forbid_absent_evidence`, and the entries already published under it all depend on the string. The prose says *the filled contract*; the wire says `validation_contract`. Contracts are checked **at publish and at admission** — and, stated plainly rather than papered over, **these are two gates, not one gate run twice**: | Gate | Where | What it evaluates | State | | --------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Publish | publisher, gate `C8` and its siblings | the publisher's own invariants: evidence completeness unless `--break-glass`, digest-pinning well-formedness, `delivery_scope` on the rendered chart | **BUILT** — has gated the five entries published to date | | Admission | the subscriber's cluster | the subscriber's contract predicates — `require_evidence_kinds`, `require_attestations`, `forbid_absent_evidence`, `max_entry_age_days` — plus stock signature and digest-pinning checks | **BUILT**, runs; `admission.enabled` is false in the estate today, pending the signature-repository ruling ([ADR-0002](/adr/0002-channel-format)) | The publisher does not hold the subscriber's contract and cannot evaluate it. That is a correct consequence of the two-party design, and it means "both sides run the same contract" is not a claim this repository can make. **`evidence_absent[]` + `forbid_absent_evidence` is built and barely exercised.** The only contract that forbids an absence today is the vendor's own internal one. No subscriber contract forbids anything yet, which means the sharpest property of the design is currently unproven by use. | Element | State | | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Contract keyed to a channel, stations as enforcement points | **RULED, NOT BUILT** — the live contract is one flat file named for an estate | | Tighten-only composition across channels (`extends` + compiler check) | **RULED, NOT BUILT** | | Filled contract — proof column, per-row fidelity and `does_not_prove` | **RULED, NOT BUILT** — `spec/filled-contract.schema.json` (committed with the seq-7 respin) defines it and validates instances offline; the first instance is authored **by hand** for SET seq-7, and there is no producer | | Verifier evaluating demand rows against proof rows in one pass | **RULED, NOT BUILT** — required values are checked by a script today, which is the hole the filled shape retires | ## Where everything lives, and how it is traced Three stores, three jobs, and no store does two of them. | Store | Role | Holds | Never | | ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | | **OCI registry** | the truth store | signed envelopes, content-addressed, offline-mirrorable | is not a read surface — deliberately dumb, no query, no index of its own | | **Git ledger** | the history | records naming digests, positions, receipts | never holds envelopes | | **Projection** | the legibility layer | read-models rebuilt from artifacts at ingest: which values are proven, at what rank, in which environment, expiring when | never authoritative; disposable and rebuildable; one writer per surface | **The reason there are three and not one: a bucket of signed blobs is durable and unreadable.** Files in a store nobody indexes will answer *"is this signature valid"* and will never answer *"what is the state of our software"* — which is the question actually being asked. Content addressing is what makes evidence trustworthy and is exactly what makes it unbrowsable: to find a claim you must already know its digest. So the three stores split that: the registry proves, the ledger records what happened in order, and **the projection is the surface a human or a dashboard reads.** It is rebuilt from the artifacts at ingest and holds no fact of its own, so it can be wrong only by being stale, never by disagreeing — delete it and it comes back. Traceability is then a property of the chain rather than of any store: value id → evidence envelope → subject digest → entry → station, each hop a pin rather than a lookup by name. Two further consequences: * **Entries move pointers, not bytes.** The channel pointer moves by descriptor copy; an immutable tag carries identity and a floating tag carries position. Nothing is re-wrapped and nothing is rewritten. * **Mirroring a registry is how evidence reaches an air-gapped estate.** Because the truth store is content-addressed and the verification path needs no network, a copied registry is a complete copy of the proof. | Element | State | | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Registry as truth store; entries as signed OCI artifacts | **BUILT** | | Attestation addressing | **RULED, NOT BUILT** — attestations are currently addressed by mutable release tag (`attestations:.`), not by subject digest. This is a defect, named here rather than deferred | | Git ledger of positions and receipts | **BUILT** | | Ledger head-hash anchored into an external log | **RULED, NOT BUILT** ([#12](https://github.com/Vexa-ai/vexa-delivery/issues/12)) | | Projection read-model | **RULED, NOT BUILT** | ## The standard stack Founder ruling, 2026-08-29 ([#12](https://github.com/Vexa-ai/vexa-delivery/issues/12)): **wherever a widely-adopted standard covers a layer, adopt it; keep bespoke machinery only where the void is verified.** Borrowed vocabulary lets a reviewer who recognises the standard stop evaluating and start checking. | Layer | Standard | Why this one | State | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | Evidence envelope | [in-toto Statement](https://github.com/in-toto/attestation) + [DSSE](https://github.com/secure-systems-lab/dsse) | CNCF **graduated**; it is the envelope under SLSA, GitHub attestations, Kyverno and every attestation store — adopting anything else means converting to it later | **RULED, NOT BUILT** | | Build claim, per image | [SLSA provenance v1](https://slsa.dev/spec/v1.1/provenance) | the one supply-chain claim a reviewer already has a checkbox for; default for public repos on GitHub, and shipped by npm and PyPI | **NOT STARTED** — declared absent on every entry | | Verdict | [SLSA VSA v1](https://slsa.dev/spec/v1.1/verification_summary), `policy.digest` = the contract's sha256 | our verdict already carries verifier, policy, inputs and result — this is that object, named, so `slsa-verifier` and graph tools can read it | **RULED, NOT BUILT** — the bespoke verdict producer is **IN REVIEW** ([#10](https://github.com/Vexa-ai/vexa-delivery/pull/10)) | | Signing | [cosign](https://docs.sigstore.dev/cosign/system_config/registry_support/) key-mode, one identity per station, `threshold` in the contract | the de-facto signing tool for container artifacts; key mode because offline verification must not call home | **RULED, NOT BUILT** — one key signs everything today; station identity is string-compared | | Admission | [Kyverno](https://kyverno.io/docs/policy-types/cluster-policy/verify-images/sigstore/), Audit-first on a first install | CNCF **graduated** and already installed in most enterprise clusters — the subscriber runs it whether or not we arrive | policy **BUILT**; Audit-first **RULED, NOT BUILT** | | Addressing | subject digest, with [OCI referrers](https://github.com/opencontainers/distribution-spec/blob/main/spec.md) where the consumer's registry supports it | the registry-native answer to *what is attested about this digest*; support is real but uneven, so the contract probes rather than assumes | **RULED, NOT BUILT** | | Statistical production evidence | [AnalysisRun](https://argo-rollouts.readthedocs.io/en/stable/features/analysis/)-pattern metric windows, wrapped as an in-toto predicate and signed onto image digests | the shape a platform team already recognises from progressive delivery; nobody signs it, which is the half we add | **IN REVIEW** ([#10](https://github.com/Vexa-ai/vexa-delivery/pull/10)); no producer | | Ledger | git, with the head hash periodically anchored into a log we cannot rewrite ([Rekor](https://github.com/sigstore/rekor) or equivalent) | git is already the record; anchoring buys tamper-evidence without adopting a transparency log wholesale | **RULED, NOT BUILT** | ## What is deliberately not standard, and why Each of the following was searched for across in-toto, SLSA, VSA, Witness, Kargo, Binary Authorization, Flux, Ratify and GUAC, and not found. *Not found* is a bounded search, not a proof of novelty, and is written that way. | Ours | Why no standard covers it | State | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | **PR as attestation subject** | in-toto subjects are matched purely by digest. A change **plus its argument** is not a digest, and compliance and value are judgments about the argument | **RULED, NOT BUILT** | | **Soak signed onto image digests** | verification systems mark an *assembly* verified in a stage; none decompose a runtime claim to per-image digests, so none let a recombined bundle inherit production history | **IN REVIEW** ([#10](https://github.com/Vexa-ai/vexa-delivery/pull/10)); no producer | | **`evidence_absent[]` + `forbid_absent_evidence`** | declaring a gap has prior art; a machine-checkable consumer policy that **refuses a specific declared gap** does not. A verdict object reports pass or fail and has no vocabulary for *"I did not check X, and you may refuse me for it"* | **BUILT**, exercised only by the vendor's own contract | | **`unproven` as a first-class verdict** | pass/fail leaves a leg with no producer to be silently omitted. A leg that nothing produces must say so out loud | **RULED, NOT BUILT** | ## The development flow this enables 1. **State the value** — one sentence a human can witness — **its rank**, and **which contracts will consume it**. 2. **Validation is derived from those contracts, not designed per change.** Nobody invents a test plan per pull request; the contracts that will have to accept the result already say what evidence must exist and who must have signed it. 3. **Agents implement, and collect evidence en route.** The evidence is a by-product of the steps that were going to run, signed where produced. 4. **Two human moments remain**, and only two: **value sign-off** — a person attesting the claim is the claim — and **promotion approval** — a person releasing it into an environment. Everything between those two moments is machine-gated. That is the whole point of ranking values: it makes explicit which moments genuinely require a person, so the rest can stop requiring one. ## State of implementation As of **2026-08-29**. Nothing below is aspiration stated as fact. Two parts of the model have their own rendered pages, each carrying its own state: [Evidence reuse and blast radius](evidence-reuse) — how a claim is inherited when the diff cannot have touched it — and [How channel contracts compose](contract-composition) — the tighten-only chain across channels, the values registry that lets a claim be written exactly once, and the filled instance a train returns. | Piece of the model | State | | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Publish gate (`C8` and siblings) | **BUILT** — has gated the five entries published to date | | Channel entry: signed digest set + evidence bundle, offline-verifiable | **BUILT** | | Candidate map binding image → source → runs | **BUILT** | | `evidence_absent[]` + `forbid_absent_evidence` | **BUILT** — exercised only by the vendor's own internal contract; no subscriber contract forbids anything yet | | Admission gate (Kyverno policy, signature + digest-pinning) | **BUILT**, runs — `admission.enabled` false in the estate today, pending the signature-repository ruling ([ADR-0002](/adr/0002-channel-format)) | | Set-level decomposition vocabulary (`proves` / `does_not_prove` / `unproven_claims`) | **BUILT** as schema — **no producer** | | Station-verdict producer + chart wiring | **IN REVIEW** — [#10](https://github.com/Vexa-ai/vexa-delivery/pull/10) | | ADR-0010, three subjects | **IN REVIEW** — [#10](https://github.com/Vexa-ai/vexa-delivery/pull/10) | | Statistical soak evidence (rate over a declared window) | **IN REVIEW** — spec draft v2 in [#10](https://github.com/Vexa-ai/vexa-delivery/pull/10); **no producer** | | Verdict emitted as a SLSA VSA | **RULED, NOT BUILT** — [#12](https://github.com/Vexa-ai/vexa-delivery/issues/12) | | Contract keyed to a channel; stations as enforcement points of it | **RULED, NOT BUILT** — [#12](https://github.com/Vexa-ai/vexa-delivery/issues/12), 2026-08-29; the live contract is one flat file named for an estate | | Filled contract — one instance per train, proof column populated per row | **RULED, NOT BUILT** — [#12](https://github.com/Vexa-ai/vexa-delivery/issues/12), 2026-08-29; `spec/filled-contract.schema.json` is committed with the seq-7 respin and validates instances offline, the first instance is authored by hand, no producer | | Verifier evaluating demand rows against proof rows in one pass | **RULED, NOT BUILT** — required values are checked by a script today | | Value ids (`value_ids[]` on the candidate map) | **RULED, NOT BUILT** | | Rank (`autonomous` / `statistical` / `human`), enforced by signer class | **RULED, NOT BUILT** — the witness flow exists and is unsigned, so no `human`-rank row can be satisfied today | | Per-station signing identities + `threshold` in the contract | **RULED, NOT BUILT** — one key signs everything; station identity is string-compared | | Digest addressing for attestations | **RULED, NOT BUILT** — attestations are tag-addressed today, which is a defect | | Projection read-model | **RULED, NOT BUILT** | | Ledger head-hash anchoring | **RULED, NOT BUILT** | | Kyverno Audit-first on first install | **RULED, NOT BUILT** — the kit installs at Enforce | | Per-image SLSA provenance | **NOT STARTED** — every entry declares `image_provenance` absent | **Two honest readings of that table.** The evidence *carriage* is built — entries, bundles, digests, offline verification, the publish gate. The evidence *semantics* — values, rank, subjects, standard predicates — are ruled and mostly unbuilt. And the property the design leans on hardest, a subscriber refusing a declared absence, has never been exercised by a subscriber.