# C29 — Self-description: every surface explains itself

**Guarantee.** Every closed-vocabulary entry the binary exposes carries a
one-line meaning, enforced at the seam where the entry enters the system;
everything entering the content-addressed store describes itself; a refusal
for a missing description names the entry, the field, and the rule. One
shared deterministic gate — `doc_gate` in aura-core, importable by every
seam per [C28](c28-stratification.md); it fails on an empty/whitespace doc
and on a doc that normalizes to the entry's own name — the full id or its
bare display segment after the last `::`, so a namespaced extension entry
cannot pass its short-name alibi
(`DocGateFault::{Empty, RestatesName}`) — guards three seams:

1. **Compile/unit seam (engine-shipped).** `NodeSchema.doc` is a required
   field, so the compiler enumerates every construction site; metrics and
   tap slots are schema carriers (`MetricSchema` / `TapSchema`, id + doc);
   blocks (`BlockSchema.doc`, the pre-existing model) and tap folds (the
   registry roster, [C27](c27-declared-taps.md)) already carried theirs.
   The coverage walk (`aura-cli/tests/self_description.rs`) asserts the
   gate over all five vocabularies — the engine satisfies its own law.
2. **Load seam (extension).** `load_crate` walks every charter-checked
   type id and gates the resolved schema's doc; a fault refuses the load
   naming type and rule (`ProjectError::UndescribedVocabularyEntry`).
   Field presence is compile-enforced for any crate built against the new
   core; the load gate catches the shape violations the compiler cannot
   see across the cdylib boundary — the empty-string alibi and the name
   restatement.
3. **Register seam (data plane).** The registry's public `put_blueprint`
   parses the canonical bytes and requires a gate-passing doc on the root
   composite and on every named nested composite — the gate guards the
   store boundary itself, so the register verb, every register-then-run
   sugar path, and any future caller are gated by construction. The
   op-script vocabulary carries the `doc` op as the builder `.doc(...)`'s
   twin ([C25](c25-role-model.md): a closed, typed metadata construct).
   Process/campaign documents take an additive-optional top-level
   `description`, gated only when present (`DocFault::BadDescription`).

**Scope at this record's writing (#321).** The gate walks five
vocabularies — process/campaign blocks, metrics, tap slots, tap folds, and
the closed node roster — plus the document `description` and the three
seams above. Recorded residue, tracked as #321 and not silently claimed:
`emit_vocabulary()` and `binding_column_vocabulary()` remain bare name
arrays, and builder schemas outside the closed node roster (e.g. the
internal tap recording sink) carry compile-required but shape-unwalked
docs. Closing #321 widens the walk and removes this paragraph.

**Id treatment.** Description fields that serialize participate in the
content id and are blanked for the identity id, exactly as `Composite.doc`
(`strip_debug_symbols`); `NodeSchema` is not serialized
([C24](c24-blueprint-data.md)), so node docs move no id. Documents have no
identity projection — their pair is: absent `description` is byte-identical
to the field-less form (existing content ids stable), present participates.

**Forbids.** The engine evaluating description text — the gate is
deterministic string shape, never content judgement (no freetext logic
hole; C17 / domain invariant 10 untouched). A description influencing
execution, identity ids, or determinism (C1). Retroactive invalidation of
already-registered artifacts — the gate guards the write path only (the
raw in-crate write survives as the store-mechanics and back-compat
witness: pre-C29 doc-less entries stay readable). Machine-invented meaning
lines — an authored text is corrected against the source, never weakened
to an empty string or a name restatement.

**Why.** The audience is headless LLM agents and scripts (#319 ruling),
for whom the binary is the only always-present teacher. Field evidence
2026-07-22 (#314): an agent holding only the release binary had to recover
execution semantics and document schemas by CAS forensics — the removed
failure class is exactly that forensic recovery.

Rendering of the carried texts on the help/introspection surfaces is #315;
the generated agent bootstrap card is #267; a fold introspection surface
is blocked on #310.