Evidence Contract v1 — Versioning and Freeze Policy¶

Status: Normative (freeze as of 2026-02) Scope: Bundle container, evidence event envelope, and pack compatibility. Positioning (informational): Assay Evidence = CloudEvents + W3C Trace Context + Deterministic Bundle. Related: ADR-006 Evidence Contract, ADR-007 Deterministic Provenance.

Governance: Changes to this document MUST follow the versioning and deprecation policy set out in §5 (deprecation) and §2/§4 (version axes and breaking-change rules): no breaking changes without a new major Assay Evidence Spec version or bundle schema_version, with migration notes. Additive clarifications and version history entries are allowed within v1.

1. Terminology and layers¶

Naming note: CloudEvents specversion is the string "1.0" (CloudEvents context attribute). Assay Evidence Spec is Assay’s contract version (also "1.0" for v1). They are distinct concepts; tooling and tickets should distinguish “CloudEvents specversion” from “Assay Evidence Spec”. Code and tooling SHOULD use distinct constant names for these axes (CE_SPECVERSION for CloudEvents; ASSAY_EVIDENCE_SPEC_VERSION for Assay Evidence) and SHOULD avoid ambiguous names such as SPEC_VERSION in new code.

Source of truth for breaking changes: This spec and the bundle manifest schema_version. Event envelope or payload changes that break existing consumers require a new spec version (e.g. v2) or a new bundle schema_version, with migration notes.

2. Compatibility matrix¶

Note (pack vs verify): Evidence verify accepts v1.x additive bundles (schema_version 1). Pack engines that enforce exact match on "1.0" may reject bundles produced with Assay Evidence Spec v1.1+ until the pack or engine is updated. So: supported by verify; pack engine policy may be stricter than verify.

Normative rule: For Evidence Contract v1, the only supported bundle container axis is schema_version 1, and the baseline Assay Evidence Spec is v1.0. Verify MAY accept v1.x additive bundles (see note above). Pack engine policy MAY require exact 1.0 (see §1); that match is enforced by the pack engine/lint, not by evidence verify.

Version axes and evolution (mechanically testable): - In v1, bundle schema_version is always 1. There is no schema_version 2 while the Assay Evidence Spec is v1.x. - Any bundle schema_version greater than 1 is outside Assay Evidence Spec v1.x and therefore requires Assay Evidence Spec v2+ with migration notes. - Assay Evidence Spec minor (v1.1, v1.2, …) MAY contain only additive changes (new optional fields, new event types). Breaking changes are not allowed within v1.x. - Breaking change rule: (1) Container/layout breaking ⇒ bundle schema_version bump (e.g. 2) with migration notes. (2) Meaning or payload breaking for an existing event type ⇒ new type identifier (preferred) or Assay Evidence Spec major (v2). Prefer adding a new type over bumping the spec major to reduce disruption for tooling.

3. CloudEvents invariants¶

Canonical split (use consistently): CE-required = specversion, type, source, id. Assay-required = time, assay* extensions, datacontenttype, data. No other attribute is CloudEvents-required beyond those four.

• Required (CloudEvents v1.x minimum only): specversion, type, source, id. (time is not required by CloudEvents v1.x.)
• Required by Assay (stricter-than-CloudEvents): time; assay-flattened fields (assayrunid, assayseq, assayproducer, assayproducerversion, assaycontenthash) per ADR-006; datacontenttype and data for the payload. Assay requires time even though CloudEvents does not; downstream tooling that validates CloudEvents “by the book” should treat this as an Assay-specific requirement.
• Constant: Assay Evidence Spec v1 uses CloudEvents 1.0 (specversion="1.0"). Any change to envelope versioning requires a new Assay Evidence Spec major (v2).
• Free/optional: traceparent, tracestate, subject, and other CloudEvents extensions as defined in ADR-006 (optional where stated).
• Type naming: Event type is a stable namespaced identifier (recommended: reverse-DNS or dot-separated; e.g. assay.profile.started, assay.tool.decision). No whitespace; ASCII recommended; treat as case-sensitive. New event types (new identifier values) are additive and allowed. Changing the meaning or payload schema of an existing type is breaking and requires a new type identifier (preferred) or new spec version. (Use “URN” only when referring to URI-style identifiers such as urn:assay:….)

4. Schema evolution rules¶

• Additive only for v1: New optional fields and new event types are allowed. New fields MUST be optional or have defined default/absence semantics so existing consumers remain valid; producers MUST NOT introduce new required fields in an existing event type within v1.x.
• Producers MUST NOT: Emit duplicate keys in event JSON at any nesting level (avoids parser confusion / differential parsing); change the meaning of existing fields within v1; reuse an existing event type with an incompatible payload (use a new type identifier instead). JSON (RFC 8259) says object member names SHOULD be unique; Assay requires MUST NOT for safety.
• No semantic change: The meaning of existing fields MUST NOT change.
• No type change: Changing the type of an existing field is breaking.
• Removal or rename: Breaking. Allowed only after deprecation window and only in a new spec version (v2) or new bundle schema_version, with migration notes.
• Unknown fields (compatibility mode vs strict JSON): Verify/reader MUST accept events that contain unknown JSON object keys, unless one of the following applies (closed list): duplicate keys at any nesting level, event line bytes not valid UTF-8 or invalid Unicode escapes (including lone surrogates)—event lines are UTF-8 NDJSON (events.ndjson), manifest or event size limit exceeded, event count limit exceeded, decompression limit exceeded. No other condition may be used to reject solely on “unknown” keys. Compatibility mode: Unknown keys MUST be ignored by consumers. Strict JSON (parser hardening): The conditions above are the only security overrides; this aligns with JCS/canonical JSON and fail-closed verification. Limit values used by security overrides MUST have a documented source of truth if intended to be normative across implementations; in the reference implementation these defaults live in VerifyLimits. Otherwise, such checks are implementation hardening behavior and MUST be documented by the verifier.

4.1 New event types (compatibility)¶

Policy (normative): A new evidence event type string MUST NOT be introduced unless:

1. It is added to the Event types (v1) registry table.
2. Its payload contract is documented in ADR-006 or the relevant spec: at minimum the type string, payload shape (required/optional fields + types), semantics (1–2 sentences), and versioning posture (v1 additive-only; breaking ⇒ new type or v2). A field-level contract is required; full JSON Schema is not.
3. At least one conformance test verifies that an event of this type passes verify (happy path) and checks at least one required invariant. The payload must be validated/decoded by the consumer(s) that are supposed to understand it—at minimum: evidence verify can parse the envelope and content-hash invariants hold. At minimum, the test MUST assert: (a) verify succeeds, and (b) assaycontenthash matches the canonicalized v1 content-hash input (directly or indirectly via verify). Lint/explore coverage is optional. Stable event types MUST have at least one type-specific conformance test that checks a payload-level invariant beyond envelope/hash validity.

Existing type strings MUST NOT change payload meaning; breaking changes require a new type string.

This policy applies to any new type intended for production/stable use. Experimental and test-only types MUST still be registered, but MAY use TBD links and MAY use weaker test coverage; they MUST NOT be emitted by default in released builds. Experimental rows whose payload contract points to a plan are provisional: they MAY be emitted only by an explicitly invoked experimental/importer surface, and MUST NOT be emitted by default or implicit evidence-export paths until the payload contract and conformance tests are merged. A type may only be marked experimental or test-only temporarily; promotion to stable requires the full bar (schema link + conformance test) and MUST be recorded in version history.

Version suffixes in the type string (e.g. .v1) are allowed but not required; use them when the payload contract itself is versioned independently (e.g. mandate lifecycle).

Source of truth: The contract registry is the Event types (v1) table in this spec, not "grep in code". Code that emits a type string not listed in the registry is a process breach; reviewers should require "where is the registry row?".

4.2 Event types (v1)¶

This table lists event types for Assay Evidence Spec v1.x (bundle schema_version 1).

Stable rows MUST link to a concrete payload section (no "implied"). Types without such a section MUST remain experimental.

Test coverage MUST reference at least one concrete test identifier (suite::testname) or generator (generate_fixture) that demonstrably emits/verifies the type.

5. Deprecation policy¶

• Announcement: In release notes and in this spec (version history or a dedicated "Deprecations" subsection).
• Window: At least 2 minor releases or 6 months, whichever is longer, before removal or breaking change. Security fixes may shorten the window when necessary; breaking changes still require a new spec or container version and migration notes. Security fixes may tighten validation, but MUST NOT silently ignore invalid events.
• Release discipline (SemVer): Deprecations MUST ship in a minor release (not a patch). Removals only in a major Assay Evidence Spec version (e.g. v2) or a new bundle schema_version, with explicit migration notes.
• Marking: Documented in this spec and release notes. Optional: schema or type-level annotation in code/docs.
• Removal: Only in a new major spec version (e.g. v2) or new bundle schema_version, with explicit migration notes.
• Migration notes: Required for any breaking change; must describe how to migrate from deprecated to supported form.

Canonicalization and hashing (freeze): Canonicalization (e.g. JCS / RFC 8785) is used so that content hashes and signing are deterministic and reproducible across implementations. If canonicalization is used for signing or digests, it MUST follow the project’s chosen scheme (JCS for v1) and be versioned if changed. Content hash algorithm and encoding MUST be stable for v1 (e.g. SHA-256, lowercase hex). Any change requires a version bump and migration notes. See ADR-007.

6. Golden fixtures contract¶

The following fixtures are normative. Consumers (verify, lint, explore, and CI) MUST pass the checks referenced below against these fixtures.

Container golden vs event golden: Container golden covers tar layout, manifest schema, file hashes, and entry ordering. Event golden covers CloudEvents envelope and payload semantics (required attributes, types, content hashes). Both are part of the normative contract; fixtures may target one or both.

Container determinism (tar.gz): For reproducible “container golden” builds the canonical writer MUST normalize so output is platform-independent: tar entry ordering fixed (e.g. manifest.json first, then events.ndjson); tar header uid, gid, uname, gname, mtime (e.g. 0 / epoch); gzip mtime and OS byte (e.g. mtime=0, OS=255 “unknown”). Other implementations SHOULD do the same for byte-identical compatibility. determinism_test pins the container hash for the canonical writer output; implementations that produce different tar/gzip header bytes are not byte-for-byte compatible with that pinned output. They may still be semantically compatible (verify passes), but are not deterministic-identical to the canonical writer output.

Determinism goldens vs smoke goldens (do not conflate): - Determinism goldens (pinned hashes): The pinned hashes in determinism_test.rs apply to a bundle generated inside that test (in-memory), not to the file test-bundle.tar.gz. Updating “pinned hashes” means updating the assertions in test_golden_hash after changing the writer or event format. - Smoke goldens (file fixtures): test-bundle.tar.gz is a separate file fixture used to verify layout, verify, lint, and explore; it uses a different event set (from generate_fixture). Regenerating test-bundle.tar.gz does not change the determinism_test pinned values.

What is pinned (exact inputs): (1) SHA-256 of the manifest.json bytes as stored in the tar; (2) SHA-256 of the events.ndjson bytes (UTF-8, one event per line, newline \n); (3) SHA-256 of the entire compressed tar.gz. Event-level content hashes use JCS (RFC 8785) canonicalization for the v1 content-hash input: specversion, type, datacontenttype, optional subject, and data. They do not cover the full CloudEvents envelope. JCS is the norm for deterministic hashing and signing in v1; implementations that hash different normalized bytes are not compatible.

Required conformance tests (stable IDs): Implementations and downstream consumers may reference these test IDs for assay-evidence-v1 conformance. MUST pass at least:

These IDs are stable; if a test is renamed, maintain a compatibility alias (e.g. old test name as wrapper) or document the change in the spec version history. See Codebase verification. Test names live in crates/assay-evidence/tests/ (verify_strict_test.rs, determinism_test.rs, bundle_security_test.rs).

Regeneration (reproducible-by-default): For test-bundle.tar.gz, run cargo test -p assay-evidence --test generate_fixture -- --ignored --nocapture from the workspace root. Use the same Rust/toolchain and crate features as CI. Pinned-hash assertions (exact location): crates/assay-evidence/tests/determinism_test.rs, test test_golden_hash. Search for the three assert_eq! that compare hash_bytes(&manifest), hash_bytes(&events), and _container_hash to hex strings; those are the pinned values. After any change to the writer or event format, regenerate and update those assertions. See the fixture README for toolchain and hash locations.

7. Version history¶

8. Normative checklist (summary)¶

Before treating this document as normative, confirm:

• Terminologie: CloudEvents specversion vs Assay Evidence Spec are clearly separated; new code uses CE_SPECVERSION and ASSAY_EVIDENCE_SPEC_VERSION rather than conflating the axes.
• Unknown keys: Verify MUST accept unknown keys unless one of the closed list applies (duplicate keys, invalid UTF-8/surrogate, size/count/decompression limits); no other reject reason for “unknown” alone.
• v1.x additive-only: In v1, bundle schema_version remains 1; Assay Evidence Spec minor (v1.1, v1.2) contains only additive changes; breaking ⇒ v2 or schema_version bump.
• Deprecations: Deprecations ship in a minor release; removals only in a major spec or new schema_version.
• Container determinism: Canonical writer MUST normalize tar/gzip headers; determinism_test pins container hash for that output.
• Fixture regen: Pinned-hash locations are exactly named (see §6: determinism_test.rs, test test_golden_hash, three assert_eq! hex values).
• New event types (§4.1): No new type without registry row + payload contract (concrete section for stable) + conformance test (verify + assaycontenthash content-hash-input invariant). Stable rows no "implied"; experimental/test-only temporary until full bar; promotion in version history.

9. References¶

• ADR-006 Evidence Contract
• ADR-007 Deterministic Provenance
• SPEC-Pack-Engine-v1
• SPEC-Replay-Bundle-v1
• Evidence fixture README
• Codebase verification
• RFC 2119 (MUST/SHOULD/MAY); SemVer 2.0.0; CloudEvents v1.x; RFC 8785 (JCS).