epiphany/spec/CONTRACT_GMINOR_VOCABULARY_AUDIT.md

Contract: G-minor vocabulary audit — a reachability matrix, and nothing else

Repo root /home/jeans/Repos/active/epiphany. Governed by spec/PLAN_GMINOR_SCHEMA_MINOR.md (§3 and §5.1; policy ratified 2026-07-28) and spec/PASS13_CANDIDATES.md (P13-S14).

This is a READ-ONLY packet. It produces one document. It changes no Rust, no .tex, no vectors, and no goldens.

Parallel safety. The editor track owns crates/epiphany-editor-gui/**, crates/epiphany-render-svg/**, crates/epiphany-glyphs/**, spec/PLAN_EDITOR_APP.md, every spec/CONTRACT_EDITOR_*.md, spec/DRAFT_T4_FIXTURE_RECIPE.md, the entire spikes/ tree, and the current unstaged root Cargo.toml change. All of it is out of scope, and since this packet writes only one new file, none of it should ever be staged.

---

Why this packet exists

The G-minor rung cannot be contracted until every append-only discriminant reachable from an affected chunk payload is known. A first attempt scoped the problem as per-OperationKind and recommended a policy that could not work — an envelope also emits the outer OperationPayload discriminant, and ResolveEquivocation carries no OperationKind at all. That scoping error is the reason this audit is a separate packet rather than a paragraph in a contract.

The deliverable

One new file, spec/AUDIT_GMINOR_VOCABULARIES.md, containing two linked parts.

Part 1 — the vocabulary ledger

Every reachable vocabulary, with every variant and its discriminant, classified as one of:

• baseline — present at the format's initial ratification;
• post-baseline native — appended later (the rows the matrix cares about);
• escape / reserved — Registered and any reserved slot.

Baseline variants are mandatory, not optional. Enumerating them is what makes each post-baseline classification checkable against a complete list rather than asserted — and this plan has already been revised once for a vocabulary that was scoped by assertion.

The ledger is the single place large baseline sets are written down, so the matrix can reference a vocabulary by name instead of repeating it per role.

Part 2 — the reachability matrix

Keyed by role, referencing Part 1 rather than restating it:

| chunk role | encoded payload type | discriminant vocabulary | post-baseline variants | introduction event | derivation site |

• chunk role — a ChunkKind variant (bundle/src/chunk.rs:18; nine of them). Every role gets at least one row or an explicit "emits no additive discriminant" row with the reason.
• encoded payload type — the Rust type whose canonical encoding is that role's payload. Some roles are payload-polymorphic (Snapshot is the canonical-base MaterializedState or the acceleration full-Score); those get one row per form, distinguished.
• discriminant vocabulary — the enum whose tag is written. This is the reference into Part 1; the ledger holds its full variant set.
• post-baseline variants — the specific variants appended after the format's initial ratification, listed individually with their discriminant values. Not a count. Must agree exactly with Part 1's post-baseline native classification for that vocabulary; a disagreement between the two parts is a defect in the audit, not a nuance to explain away.
• introduction event — the tranche or revision that appended it (e.g. "Phase-3 first tranche", "schema-major-2 repeat revision", "Push 4a", "genesis G1", "genesis G2a"). Name the event, not an epoch number.
• derivation site — file.rs:line of the code that writes the tag, so the G-minor implementation knows where introduced_minor has to live.

Method — walk the encoder, never the type

The ground truth is the encoder, not the struct definition. A field can exist on a type and never reach the wire: ScoreTuningContext::accidental_extensions is staged out of schema major 3 and its Codec deliberately drops it (core/src/codec.rs:1939). A type-driven walk would record a vocabulary that is not actually emitted, and the matrix's whole purpose is to say what is emitted.

So: start from each role's payload type, walk its encode_canonical / Codec::enc implementation transitively, and record every site that writes a tag or discriminant. grep -rn "push_tag\|fn discriminant" over crates/epiphany-core/src and crates/epiphany-ops/src returns ~65 hits across 11 files and is a reasonable starting net — but it is a net, not the method. Confirm reachability from a role by following the encoder.

Inclusions and exclusions

IN scope: every reachable discriminant vocabulary — whether open, append-only, or expanded by a ratified revision. That last clause is not decorative: binary_format.tex:2386 states that the value-layer unions enumerated as closed in req:binfmt:frozen-layout may still gain appended variants through a ratified revision of that document, and that such appends are also minor-additive. A vocabulary described as closed is therefore not automatically out of scope; only ChunkKind is (see below).

• Native variants appended to any such vocabulary after baseline.

• Nested additive variants — a vocabulary reached only through another value's encoder counts, at whatever depth.

• Later native additions to enums that also carry a Registered escape. This is the audit's sharpest edge: the escape variant is out of scope, but a new native variant on the same enum is in scope, and the two are easy to conflate.

  This checklist is authoritative; no count of it is. BarrierScope and BarrierCondition are separate enums (layout-ir/src/barrier.rs:60, :75), and a prose summary that pairs them undercounts — which is exactly why the number is omitted here rather than corrected:

  1. RepairKind
  2. ReanchorReason
  3. PreconditionFailureReason
  4. IntegrityAnomalyKind
  5. ReplicaAnomalyReason
  6. TransactionCategory
  7. ResolutionAction
  8. ConflictKind (via ExtensionConflict)
  9. BarrierScope
  10. BarrierCondition
  11. TieClass
  12. StaffGroupKind
  13. PitchSpacePosition
  14. SpellingNominal
  15. TypedObjectId
  16. the barrier ObjectKind's open value space

  Every entry needs checking for native appends, and every entry needs a recorded result — including the clean ones.

OUT of scope:

• Registered payload values. Extension through an escape variant is not a schema change at all — the wire form is already defined.
• ChunkKind itself. It is closed: no Registered variant, and its discriminant enters every chunk's hash preimage, so a new chunk kind is a format-major event.
• Anything requiring a schema-major bump. Field additions are major regardless of type — an Option still occupies a positional slot (binary_format.tex:2360). Only discriminant appends are minor-additive.

Traps

1. The spec's "append at ≥N" phrasing names the next free slot, not the baseline boundary. binary_format.tex:2369 says OperationPayload appends at ≥4 — yet discriminant 3 (ResolveEquivocation) is itself an append, as both the spec (:1291) and the code comment (payload.rs:80, "the ratified 0..=2 stay stable") state. Likewise OperationKind "appends at ≥30" while 24–29 were also appends. Do not derive post-baseline membership from the ≥N numbers. Establish each variant's introduction event from the spec's revision history, the DECISIONS.md files, and git log — and say which source settled it when they disagree.
2. OperationKind and OperationKindTag are independent, misaligned spaces. RespellPitch is kind 2 / tag 3. They are two rows, never one.
3. Payload-polymorphic roles. Snapshot carries both the canonical-base MaterializedState and the acceleration full-Score; they emit different vocabularies and must not be merged. The canonical base notably does not emit OperationKind at all.
4. A hand-written discriminant() match is not evidence of completeness. OperationKind::discriminant() is exactly the site Push 4a got wrong. Where a macro-generated vocabulary exists (operation_kind_tag_vocabulary!), prefer it as the source of truth and note the divergence if the hand-written sibling disagrees.

What this packet must NOT do

• Do not ratify epoch numbers. Column 5 records the introduction event. Assigning epochs is a later ruling that depends on this matrix being complete.
• Do not write or modify any Rust, including tests, and do not add introduced_minor anywhere.
• Do not modify any .tex, vectors, or goldens.
• Do not draft the G-minor implementation contract.
• Do not touch spikes/, the root Cargo.toml, or any editor-track file.

Completeness — how to know the matrix is done

The audit's failure mode is a missed vocabulary, and it is silent. So every one of the nine roles must be accounted for — an unlisted role is indistinguishable from an overlooked one. Each role resolves to exactly one of four dispositions, and "opaque" is not one of them, because opacity is a property of a layer, not of the bytes:

(a) Rows. The role's payload encoder is walked and yields matrix rows.

(b) Emits no additive discriminant. Stated with the reason.

(c) Normatively typed bytes, opaque only to the immediate layer. The carrying layer treats the payload as bytes, but a specification pins what produced them — operation envelopes inside an OperationEnvelopeBlock, and barrier blobs inside a manifest, are both of this shape. The audit must cross that boundary and walk the specified producer's encoder. Treating these as opaque would silently drop the single most important vocabulary in the whole matrix, since the op-block role is the entire reason G-minor exists.

(d) Truly producer-owned opaque bytes. ExtensionData is the case: no core encoder produces it and no core derivation is possible. Record that explicitly — the schema is carried from the producer, and core cannot derive a minor for it — and do not write it up as emitting nothing. "We cannot see inside" and "there is nothing inside" are different findings, and only the first is true here.

State explicitly:

• which roles emit no additive discriminant, and why;
• every escape-carrying enum checked for native appends, including those that turned out to have none — a negative result recorded is evidence, a negative result omitted is a gap;
• any variant whose introduction event could not be established from the sources in trap 1, flagged as unresolved rather than guessed;
• any place where the spec and the code disagree about what was appended when.

A guess presented as a finding is the worst possible output here, because the epoch mapping will be ratified on top of it and a wrong epoch is a wrong wire record that then freezes.

Gate

cargo fmt --check and cargo test --workspace are expected to be untouched and green — that is the check that this packet really was read-only.

The status check is a delta, not an absolute. The working tree is already dirty with the editor track's work — a modified root Cargo.toml and an untracked spikes/ subtree — so "exactly one file" is unsatisfiable and any gate demanding it would have to be either faked or argued around. Instead:

1. Capture git status --short before starting. Include it in the report.
2. Capture git status --short after. Include it in full.
3. The only difference between them must be the addition of ?? spec/AUDIT_GMINOR_VOCABULARIES.md.

Any other delta — including a Cargo.lock touched by running cargo — is a finding to report, not something to clean up silently.

Report

The matrix itself, plus: the completeness statement above; the sources used to establish introduction events and which settled disputes; anything found that the plan's §3 four-vocabulary table did not name; and any place where this contract's own assumptions turned out to be wrong. That last one is not politeness — the plan this packet serves already had to be revised once for a scoping error of exactly this kind, and the contract's four-vocabulary starting table is a floor, not a ceiling.