Status: APPROVED 2026-08-12. Known-answer test vectors for the ZDDC v1 custody layer — the thing memo §6.2 asks for so that "a third-party .html is provably conforming" (constraint 2). Nothing here is implemented in the codebase; these fixtures are the target Stage 4 builds against, in both implementations (the Go server and the browser tools).

node docs/spec/custody/vectors/gen.js            # regenerate in place
node docs/spec/custody/vectors/gen.js --out DIR  # generate elsewhere
node docs/spec/custody/vectors/gen.js --check    # drift guard, exit 1 on diff

1. The conformance contract

An implementation conforms if and only if it ACCEPTS every vector under a valid/ directory and REJECTS every vector under an invalid/ directory with the reason class the vector names — plus, for currency/, derives the named currency verdict.

Three clarifications that make that testable:

1. Reason classes are checked, not just accept/reject. An implementation that rejects everything passes an accept/reject-only suite. The class must match (§4).
2. A rejection must be attributable to the named requirement. Each vector lists the requirements it exercises; a runner that rejects envelope/invalid/03-payload-not-canonical for the wrong reason is not conforming, which is why the class is part of the contract.
3. Vectors are additive. A future version may add vectors; it must never change an existing one's expected outcome without a payloadType version bump, because the vectors are the wire format.

2. Layout and file shapes

vectors/
├── keys.json          the five test keys (seeds, public halves, keyids)
├── contexts.json      anchor state + link context, referenced by name
├── merkle/            zddc-merkle-v1 file hashing and inclusion proofs
├── canonical/         RFC 8785 canonical form and the statement id
├── envelope/          the DSSE profile: PAE, signatures, key resolution
├── statements/        payload-level rules — the seven link types + the local record-revision and content-attestation
└── currency/          the derived currency verdict

Every vector file carries id, spec, kind, requirements, description, input, and expect; envelope/statement vectors also carry context. The kind decides how a runner reads input:

File inputs are a pinned byte pattern

merkle/ inputs describe their bytes rather than embedding them (decisions.md D-21): pattern: "zddc-vector-p251" means byte i = i mod 251, for size bytes. Cases at or below 4096 bytes also carry bytes_b64 so the pattern can be cross-checked directly.

251, not 256, is load-bearing. 1 MiB is a multiple of 256, so a mod-256 pattern would make every chunk byte-identical, and an implementation that ignored chunk order would pass the whole suite.

payload vectors are payload-only on purpose

statements/ vectors carry the canonical payload bytes and the payload type, not an envelope — they test the rules that apply after an envelope has verified, so a runner can exercise them without re-implementing signature checks. Some of them carry extra input, because some rules are not decidable from a payload alone; each such key names exactly what the verifier is being handed, and a rule whose input is absent is not evaluated rather than assumed to have passed:

• ledger — what the verifier already holds on this link (chain_tip, statements[] with type/supersedes/re/manifest_paths). Rules like [M-S6] and [M-S14] are inherently cross-statement.
• files — the container's bytes behind named manifest paths, as [{path, pattern, size}] using the same pinned pattern merkle/ uses (D-21). [M-M6]'s "size MUST equal the byte length of the file whose chunks produce root" is a claim about bytes, and no payload carries them: with no files, size: 813 against an 812-byte file's root is indistinguishable from a legal entry, since both describe a single-chunk file. A runner materializes the named bytes and streams them through the Merkle construction; a manifest path the vector does not describe is skipped.
• envelope_signature_count — the succession vectors need to know how many signatures the (absent) envelope carried, since [M-S38] is a cross-check between payload and envelope.
• record_bytes_b64 — the stored bytes of the revision a record-revision statement pins ([M-S62]): a hash-equality claim about bytes, decidable only with them in evidence, exactly as [M-M6]'s files.

3. Keys, contexts, and personas

keys.json holds seven Ed25519 keys derived from labelled ASCII seeds (zddc-test-vector-key:<label> padded to 32 bytes with .). They are published test keys. They authenticate nothing and MUST NOT be anchored by any deployment.

Plus one non-Ed25519 credential (the S4 addendum, D-31): the personal-webauthn vectors use a P-256 credential derived the same way — private scalar = SHA-256 of ASCII zddc-test-vector-webauthn:alice-yubikey, public half the 65-byte uncompressed point, registered to alice@example.com under rp_id zddc.example with a fixed 32-byte credential_id. It lives in gen.js and the two webauthn contexts, not in keys.json (which stays Ed25519-only by its own alg header). Because ECDSA signing is randomized, its assertion signatures are minted once (node gen.js --mint) and pinned in gen.js (WEBAUTHN_SIGS); every default run re-verifies each pin against the freshly composed assertion message, so the suite stays byte-deterministic ([M-R7]) without an unverified constant anywhere.

contexts.json holds sixteen anchor states plus seven record-signer contexts (record-local, record-local-none, record-local-kind-mismatch, record-local-personal, record-local-personal-no-email, record-local-webauthn, record-local-webauthn-no-rpid) for the local record-revision type — they carry record_signers ([M-K31]/[M-K32], keys.md §5.0) and deliberately no link and no anchors, which is itself part of what they pin: a local statement needs neither. Each carries as_of (the verifier's last trust-anchor update from the link — [M-K16]) and now (the verifier's clock, which is the evaluation instant when no receipt is held — [M-K19]). Both are fixed literals, so a runner reads no clock. Ten of the sixteen exist to refuse the same valid envelope on anchor-state grounds: expired, revoked-with-compromise-date, revoked-with-no-instant-at-all, stale, person-not-certified, person-not-in-allowlist, unsupported-alg, no-alg-at-all, fingerprint-mismatch, and an operational list holding nothing but a corrupt entry. Refusing one envelope ten ways is deliberate — it isolates the anchor layer from the signature layer, since the bytes are identical every time and only what the verifier knows has changed. Two more exist to accept it despite something odd in the state (acme-owner-junk-operational-entry, where a corrupt entry must not mask the valid one) or to refuse it on the link rather than on the key (acme-owner-one-ended-link, [M-S9]).

Two more carry the OPTIONAL container key ([M-K16] §5.0): where the container the statement was read from lives, in the verifier's own tree frame. It is the only frame an anchor's scope is meaningful in ([M-K14], D-25), and acme-owner-in-scope / acme-owner-out-of-scope differ in nothing else — same row, same bytes, one address inside project 100004/ and one outside it. Every other context omits container, which is a real answer and not a default: a verifier that has not been told does not evaluate the rule and must not report it as satisfied.

Personas are alice@example.com, sam@example.com, admin@example.com; parties are Acme and a generic counterparty named owner. The repo's pre-push PII guard applies to every file here.

4. Reason classes

Closed vocabulary (decisions.md D-20). These are for logs, local UI, and this suite — never for a network response, which answers a single undifferentiated refusal ([M-E22]).

Where a verifier could plausibly emit either of two classes for one input (bad_pae vs bad_signature), the vector names the more specific one and a runner MAY accept the more general — stated here, not left to interpretation.

5. Requirement traceability

Every MUST/MUST-NOT in the four artifact spec documents (manifest.md, envelope.md, keys.md, statements.md) is either exercised by a vector or listed below with why it cannot be.

Covered by vectors: 122 of 157 artifact requirement ids, across 233 committed vectors. The twelve [M-R*] ids in conformance.md are excluded from that denominator by construction: they are rules about how a runner behaves (read no clock, run offline, treat drift as a failure), not properties of any artifact a vector could present. They are pinned by tests/custody-vectors.spec.js and by the Stage 4 runners themselves.

Those three numbers are derived, not maintained. tests/custody-vectors.spec.js counts the tree and fails if the sentence above disagrees with it, so a vector added without its traceability entry — or a requirement added without a vector — shows up as a test failure rather than as a number nobody re-checked. The same test guards the counts in ../README.md. To see them by hand:

# ids defined by the artifact specs, vs ids named by any vector's "requirements"
grep -ho '\*\*\[M-[A-Z]*[0-9]*\]' docs/spec/custody/{manifest,envelope,keys,statements}.md \
  | sort -u | wc -l

Not vector-testable — and why

6. Drift guard

tests/custody-vectors.spec.js (Playwright project custody-vectors) runs gen.js --check and fails on any byte difference between the committed tree and a fresh generation, so a hand-edited vector cannot survive a test run. It additionally asserts the structural contract: every vector parses, names a known kind and a known reason class, and references only requirement ids that actually exist in the spec documents.

The spec adds no custody code to any server package — the guard is a Node script plus a test, exactly as Stage 3's documents-only scope requires.