# Contract: Genesis G2b — `SetTuningContext`, and the accept-set raise it pays for Repo root `/home/jeans/Repos/active/epiphany`. Governed by `spec/RULING_GENESIS_PERSISTENCE.md`, `spec/PLAN_GENESIS_OPS.md` §4, and `spec/PASS13_CANDIDATES.md` (P13-S13, which **closes** here). **One operation, one kind, one tag, one accept-set raise.** G2 was split precisely so this surface could be isolated: minimal stamping is a pure function of each payload's value, and `ScoreTuningContext` is the **only** genesis payload born at schema major 3. The raise is charged here, not amortised across nine surfaces as the ruling's framing first implied. **Prerequisite, already met:** G-minor landed at `ff9bd0f`. This contract appends kinds/tags **34**, which is why it sequences after that sweep — running it first would have shipped 34 with the very defect G-minor retired. **Parallel safety.** The editor track owns `crates/epiphany-editor-gui/**`, `crates/epiphany-render-svg/**`, `crates/epiphany-glyphs/**`, `crates/epiphany-testkit/benches/editor_pipeline.rs`, `spec/PLAN_EDITOR_APP.md`, every `spec/CONTRACT_EDITOR_*.md`, `spec/DRAFT_T4_FIXTURE_RECIPE.md`, `spec/ANALYSIS_*.md`, `crates/epiphany-editor-gui/goldens/*.png`, and the entire `spikes/` tree. **All out of scope. Stage only the files this contract names.** **One-time authorization, not generalising:** this packet **will** need to edit `crates/epiphany-editor-core/src/barriers.rs` (`subjects_of`) and `crates/epiphany-layout-ir/src/barrier.rs`. Rust exhaustiveness forces the first, and the second holds a "one past the vocabulary" literal. **Budget both up front** — this is the G1 lesson, where an unbudgeted crossing blocked the entire gate because `epiphany-testkit` depends on `epiphany-editor-core`. --- ## 1. The pin, RESOLVED — subset, not normalization **This was the open pin. It is resolved here, in the contract, not left to the implementation.** ### The hazard `ScoreTuningContext` has six fields, but its `Codec` **deliberately encodes five** (`core/src/codec.rs:1939`): `default_pitch_space`, `default_tuning_system`, `reference`, `smufl`, `overrides`. `accidental_extensions` is staged out of schema major 3 and `dec` reconstructs it as `Vec::new()` (`graph.rs:1676` documents it "**In memory only**"). A naïve full-value `SetTuningContextOp(ScoreTuningContext)` therefore diverges: * **Live session** — `OperationSet::accept` stores the envelope as a **value** (`opset.rs`, `OperationSlot::Single(env)`), so reduction applies `accidental_extensions` intact. * **Same document reloaded** — the envelope round-trips through bytes, the field decodes as empty, and reduction applies an empty one. Same document, two graph states, depending only on whether you just authored it. **`canonical_value!` structurally cannot catch this.** Its generated `decode_canonical` does decode → `finish()` → re-encode → reject-on-mismatch, comparing **bytes** and never the originating value. A field that never reached the bytes is invisible to it. This is not a gap to plug; it is what that macro is. ### The ruling: **subset** `SetTuningContextOp` carries a **new payload type holding exactly the five wire-bearing fields**, in the codec's existing order. Reduction writes those five onto `score.tuning_context` and **leaves `accidental_extensions` untouched**, preserving whatever the graph already held. Four reasons, in order of weight: 1. **The wire bytes are identical either way, so this costs no layout design.** `ScoreTuningContext::enc` already encodes exactly those five fields in exactly that order. The subset type's canonical encoding is byte-for-byte the current one. This is a **type-level narrowing, not a new wire form** — `canonical_value!` still applies and the G1/G2a payload template is unchanged. 2. **It makes the divergence unrepresentable.** Normalization would make correctness depend on remembering to clear a field at every construction site, enforced by nothing the compiler or the codec can see — and this track has now been burned twice by exactly that shape (four stale literal sites at Push 4a, six found during G2a). A field that does not exist cannot be set wrongly. 3. **Preserving is semantically right; clearing is not.** The operation carries no information about `accidental_extensions`. Normalization would make "set the tuning context" silently *erase* a live in-memory registry extension — an effect the author never asked for and the wire cannot even record. 4. **The forward path is identical.** When a later schema major lands `accidental_extensions` on the wire, the subset type gains the field: a normal major payload change, the same cost normalization would have paid. **Rejected: normalization** (clear the field at construction) — fails 2 and 3. **Rejected: reject-on-non-empty** (`well_formed` refuses a populated field) — turns an in-memory-only field into an authoring error for callers who never opted into persistence, and still needs the check maintained by hand. **Evidence this is low-risk today:** nothing in production populates `accidental_extensions` — every non-`Vec::new()` reference in the tree is a test (`codec.rs:3725`, `textvalue_graph.rs:1092`). The **text projection drops it too** (`textvalue_graph.rs:1123`), so it already survives no persistence surface at all. The subset type ratifies the status quo rather than changing it. **Open for ratification:** the type's **name**. `TuningContextSettings` is the default. It must not be named so as to imply it is the whole context. --- ## 2. Design pins ### Pin 1 — kinds and tags are 34, in both spaces `OperationKind::SetTuningContext` = **34** (`payload.rs`, the hand-written `discriminant()` match at :275 — **the exact site Push 4a got wrong**) and `OperationKindTag::SetTuningContext` = **34** inside `operation_kind_tag_vocabulary!`. They coincide numerically here; that is a coincidence, not an alignment. **Two rows, never one.** ### Pin 2 — `schema_major()` gains a real arm, unlike G2a G2a's pin 3 said `schema_major()` gains **no** arm, because both setters were major 0 and fell through the catch-all. **G2b is the opposite.** `SetTuningContext` must return **3**, unconditionally — `ScoreTuningContext`'s wire form is born at major 3 and its appends are mandatory, not `Option`-hidden. This is the single fact the whole rung is charged for. ### Pin 3 — the accept-set raise, and the prose that must move with it `max_supported_major(ChunkKind::OperationEnvelopeBlock)` goes **2 → 3** (`bundle/src/bundle.rs:69`). **The doc comment above it does not merely document the cap — it asserts a claim this rung falsifies.** `bundle.rs:56-58` currently reads: *"Schema major 3 (Push 4b tranche 3b-i) does **not** raise this role: no operation payload embeds the tuning context, so no op block is ever born at v3."* After G2b that sentence is **false**. Rewrite it; do not leave it beside a changed number. A stale rationale next to a correct constant is how `binary_format.tex:2373` happened. ### Pin 4 — G-minor interaction: kind 34 needs an epoch G-minor's `introduced_minor()` is **exhaustive with no wildcard arm**, so kind/tag 34 **cannot compile** without an epoch. That is the control working as designed — do not defeat it. **Epoch 10, for the genesis G2b event.** This extends the ratified ladder (`PLAN_GMINOR_SCHEMA_MINOR.md` §4, minors 2–9) by one, monotonically. **This addition requires ratification** alongside this contract; it is the first exercise of the ladder's own growth path. ### Pin 5 — undo must distinguish never-authored from authored-to-default `Score::empty` seeds `tuning_context` with a **default value**, so the `WriteChain` cannot treat "no base" and "base equals default" alike. Follow G2a's chain shape (`reduce.rs`), and note the chain's value type is the **subset type**, not `ScoreTuningContext` — `accidental_extensions` never participates in undo because no operation ever writes it. ### Pin 6 — P13-S13 closes here Mark it resolved in `spec/PASS13_CANDIDATES.md`, citing this rung. Its closure argument is the `metadata` precedent: the op log is canonical, and the canonical base embeds no graph values for **any** field. ### Pin 7 — the four-document append ritual applies in full **This is the G2a lesson and it is not optional.** An operation-vocabulary append is a documented event in **four** specification documents: * `binary_format.tex` — payload-layout table, tag table, **and** the §2373 minor-additive bullet (now G-minor-repaired; kind 34 extends its history), version, Revision History row; * `operation_catalog.tex` — a `\section`, version, changelog paragraph; * `core_spec.tex` — the **normative** `OperationKind` *and* `OperationKindTag` listings, plus any spelled-out payload count; * `text_projection.tex` — a kind production and **`COMPANION_VERSION` 0.10.0 → 0.11.0**. **The signature to grep for: a spelled-out count sitting next to an enumeration that disagrees with it.** ### Pin 8 — the hand-maintained sites, budgeted up front Five non-compiler-checked sites (`layout_stub`'s is now derived): 1. `ops/src/payload.rs` — `OperationKind::discriminant()`; 2. `layout-ir/src/barrier.rs` — the "one past the vocabulary" literal; 3. `testkit/tests/text_projection_grammar.rs` — a kind **count**; 4. `ops/src/textproj_kind.rs` — a kind **count**; 5. `testkit/src/generators.rs` — an `rng.below(N)` bound. Plus `editor-core/src/barriers.rs`'s `subjects_of`, which the compiler forces. **Prefer deriving over extending** wherever the site allows it. ### Pin 9 — P13-S15 stays open The golden lock ends at 29 and **this rung must not extend it**. Adding 34 while 30–33 remain unlocked would make the table look maintained while the gap persists. S15 lands as its own rung with its own mutation evidence. --- ## 3. Tests — each with the mutation that must kill it | # | Test | Required mutation | |---|---|---| | t1 | Kind and tag are both 34, and the discriminant byte leads the canonical encoding | Move either to 35; must fail | | t2 | `schema_major()` returns **3** for `SetTuningContext` | Return 0 (the pre-G2b catch-all behaviour); must fail | | t3 | A block containing one `SetTuningContext` stamps major **3** | Make `schema_major` ignore the new arm; must fail | | t4 | That block is **admitted** by the accept-set | Revert the cap to 2; must fail | | t5 | **The subset pin holds**: an op authored live and the same op reloaded from bytes produce **identical** graph states, with a pre-existing non-empty `accidental_extensions` **preserved across both** | Make the payload carry the full `ScoreTuningContext`; must fail — this is the pin's whole reason for existing | | t6 | Undo restores the previous five-field value | Restore the default instead of the predecessor; must fail | | t7 | Undo of the **first** authoring returns to never-written, distinguished from authored-to-default | Treat the `Score::empty` seed as a base write; must fail | | t8 | Kind 34 carries **epoch 10** and a block containing it stamps minor 10 | Assign epoch 9; must fail | | t9 | The from-empty spine still reaches a note, now with a tuning context authored | — regression guard; mutation is t2's | | t10 | The accept-set prose no longer claims no payload embeds the tuning context | Grep-assert the stale sentence is absent; restore it to see the test fail | --- ## 4. Gate `cargo fmt --check`; `cargo clippy --workspace --all-targets` **0 warnings**; `cargo test --workspace` green with the count; conformance suites with counts including `[7f]`; decode vectors regenerated with the count; text-projection vectors regenerated; **all four PDFs at 0 undefined references**, committing `binary_format.pdf`, `operation_catalog.pdf`, `core_spec.pdf` and `text_projection.pdf` (**all four `.tex` sources change here**, unlike G-minor); and `git status --short` **before and after**, whose only differences may be this contract's own touch set — the editor track's dirt must appear unchanged in both. ## 5. Report The gate outputs; every mutation with the failure actually observed; any touch outside this contract; and **any place where this contract's own assumptions turned out to be wrong**. Required, not politeness: G1 shipped five normative falsehoods because its contract said "no `binary_format.tex`", and G2a's "derived by enumerating every `SetMetadata` site" was false with the evidence already in a grep that had been read.