Design: a signed artifact is validated as strictly as it is built — one receipt contract for pkgs/id artifacts #3231

Design-architect pass 28 (2026-10-31), audit at origin/main 357ec7fb. Full design doc: files/designs/code-id-artifact-receipt-validation.md in the keep-the-four-repos-healthy goal workspace. NO user/review — every origin carries explicit acceptance with verified probe evidence, and the judgment calls below are the architect's recorded decisions.

Problem

pkgs/id has three signed-statement types, and two state the same contract in their docs — documents.rs: "The builder and the decoder both apply them, so a signed document always passes them on receipt"; chain.rs (ChainExt::validate): the same sentence for signed events. The third type, artifacts (pkgs/id/src/artifact.rs), never applied it to itself: its receipt gates check() (envelope) and parsed() (the four known kinds) each enforce some of the rules the crate's own producers and sibling validators obey and silently omit others — one omission per field, filed one at a time. Four filings in two days (three in the hours after pass 27 assessed #3146 as a single): #3146 (friend_remove.requests never inspected), #3187 (home_declared.world_id only is_empty-checked; duplicate endpoints pass), #3192 (document/tag text accepts non-NFC every sibling path refuses), #3196 (check() accepts a duplicated after frontier chain.rs refuses as DuplicateAfter).

The rules (recorded decisions)

1. Receipt is construction. parsed() refuses a known-kind body no in-tree producer could build; check() refuses an envelope no legitimate signer could build — Refusal::Forbidden naming the rule, existing per-arm style. Unknown kinds untouched (stored, never applied, envelope-only — the module's deliberate forward-compatibility rule).
2. A signed list names each thing once. Duplicates refused, never silently deduped on receipt (the signed bytes are evidence; rewriting falsifies them and breaks the hash). Covers after, friend_remove.requests, and home_declared servers by endpoint. sign_after refuses a duplicated after at build time — the builder/decoder symmetry the sibling types document.
3. Text in a signed body follows the crate's text rules. document.media_type, tag.name, tag.value must be NFC via the same unicode_normalization::is_nfc the three sibling validators import. world_id gets MAX_WORLD_ID_BYTES = 64 (aligned with MAX_WORLD_NAME_BYTES): 1–64 bytes, not whitespace-only, no control (Cc) or format (Cf) characters.

Field pins: requests ≤ MAX_FRIEND_REQUESTS = 3 (the sole producer Directory::friendship_requests, directory.rs:1710–1721, structurally builds at most 3, sorted+deduped), each entry exactly 32 lowercase hex characters (the envelope-ID shape), no duplicates. Junk requests entries are not inert — Directory::apply extends the permanent removed_requests void guard with every string (directory.rs:1698–1705).

Phases (adopt the origins — no parallels)

• Phase 1 — List integrity: id(artifact): check() accepts duplicate after hashes — the same hash can fill all 32 frontier slots, unlike chain.rs which refuses DuplicateAfter #3196 + id(artifact): friend_remove requests is the one known-kind body parsed() never validates — any count, any shape, any length passes, and every string lands permanently in the directory's removed_requests void guard #3146.
• Phase 2 — Text fields: id(artifact): parsed() accepts non-NFC text in document and tag — media_type, tag name and value bypass the NFC rule documents.rs and tag_claims.rs both enforce #3192 + id(artifact): home_declared world_id gets only an is_empty check in parsed() — a 100 KB, whitespace-only, control- or bidi-bearing world_id is accepted and stored, and the same endpoint can be listed twice with different worlds #3187. Independent of Phase 1.
• Phase 3 — Closing audit + contract statement: filed this pass as a sub-issue, gated on Phases 1–2 (status/blocked). Field-by-field disposition table for every known-kind and envelope field; must explicitly disposition the kind string (unknown kinds), document.content internal strings, prev's shape beyond store()'s position check, and full builder-side symmetry; writes the contract sentence into the artifact.rs module doc, where documents.rs/chain.rs already carry it.

Alternatives rejected (in the doc)

Fixing the four independently (rules diverge — the drift is how the family arose: the artifact arms already mirror the sibling caps while missing the NFC half); validating at application time instead of parsed() (the log would still store and serve junk; parsed() is the single gate insert/open/pull all pass); normalizing on receipt (breaks hash/signature — refusal is the only honest outcome); folding into #3068 (JS/TS shape contract — different gate, different failure mode; cross-referenced, neither gates the other — this answers #3187's triage note); pinning the full a-z0-9-_ world-name charset for world_id now (WorldCore::new accepts any non-blank ID — charset stays an open question, below).

Risks (in the doc)

ArtifactLog::open() replays through the same gates, so tightened rules apply to stored chains — legitimate chains unaffected (no producer emits these shapes), refusal-on-open with the line named is existing behaviour; MAX_FRIEND_REQUESTS = 3 is a producer invariant (constant and producer change together); Cf refusal in world_id is safe for machine-chosen IDs ("home"/"lobby" today).

Open questions (in the doc, never as issues)

world_id charset (validate_world_name's a-z0-9-_?) — needs evidence of how declared() consumers resolve it; document.content internal text NFC (chain's all-text rule vs the documents.rs media-type-only precedent); unknown-kind kind-string bounds vs forward compatibility; full builder symmetry for sign. The neighbouring plain-output rendering family (#2839, #3111, #3089, world/util.rs sanitizers) governs printing untrusted text, not storing it — not adopted; #3187's Cf pin is deliberately aligned with it.

Acceptance criteria

• Phase 1 (adopting id(artifact): check() accepts duplicate after hashes — the same hash can fill all 32 frontier slots, unlike chain.rs which refuses DuplicateAfter #3196 + id(artifact): friend_remove requests is the one known-kind body parsed() never validates — any count, any shape, any length passes, and every string lands permanently in the directory's removed_requests void guard #3146) and Phase 2 (adopting id(artifact): parsed() accepts non-NFC text in document and tag — media_type, tag name and value bypass the NFC rule documents.rs and tag_claims.rs both enforce #3192 + id(artifact): home_declared world_id gets only an is_empty check in parsed() — a 100 KB, whitespace-only, control- or bidi-bearing world_id is accepted and stored, and the same endpoint can be listed twice with different worlds #3187) land under the recorded rules: receipt (check() / parsed()) refuses with Refusal::Forbidden any envelope or known-kind body no in-tree producer could build; duplicates are refused, never silently deduped on receipt.
• The Phase 3 closing audit completes the field-by-field disposition table (including kind, document.content internal strings, prev shape, builder-side symmetry) and writes the receipt contract sentence into the pkgs/id/src/artifact.rs module docs, alongside documents.rs / chain.rs.
• No legitimate producer output is refused: existing stored artifact chains replay through ArtifactLog::open() unchanged.