epiphany/spec/CONTRACT_GENESIS_G2B_TUNING.md

# 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.

**RATIFIED 2026-07-28:** the subset design, and the type's name and path —
**`epiphany_core::TuningContextSettings`**. It lives in `epiphany-core`
alongside the type it narrows, and is publicly exported at that exact path.

---

## 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 — RATIFIED 2026-07-28** and already
recorded in the authoritative ladder (`PLAN_GMINOR_SCHEMA_MINOR.md` §4).
**Transcribe it; do not edit that plan.** This is the first exercise of the
ladder's own growth path, and it stayed monotonic and prefix-closed.

### Pin 5 — undo restores the **seeded base**, and the never-authored /
authored-to-default distinction must stay **unobservable**

**An earlier draft of this contract had this backwards.** It required undo to
distinguish "never authored" from "authored to the default value".
`spec/PLAN_GENESIS_OPS.md` §5 trap 5 **withdrew** that on 2026-07-28, and
`SetMetadata` is the disproof: `Score::empty` seeds `metadata` exactly as it
seeds `tuning_context` (`graph.rs:1749`, `:1757`), and base ingest then runs
`metadata_chain.seed(score.metadata.clone())` (`reduce.rs:1385`) precisely so a
value-restoring undo of the *first* operational write restores the
pre-operational state.

**The rule:**

* From-empty reduces **onto** `Score::empty` (via `reduce_operation_set_onto`),
  so **the seed runs**. Undoing the first write yields
  `Restore(Some(Predecessor::Base(seeded)))`.
* **Undo restores the seeded base settings — default or non-default alike.**
  Restoring the seeded value is correct in *both* cases, so the distinction is
  unobservable, **and this contract must keep it so.** Writing code that can
  tell them apart is a defect, not a safeguard.
* **`Predecessor::Base` vs `::Write` earns its keep only for the canonical
  bookkeeping families** (`spellings`, `breaks`, `page_breaks`,
  `reduce.rs:707`), where a base predecessor returns a **map key to absence**.
  `ScoreTuningContext` is an **always-valued** `Score` field, like `metadata`:
  **there is no absent state to return to.**
* **Copy `set_metadata` structurally**, as all three G2 setters do. Do not
  invent a chain shape for this field.

The chain's value type is the **subset type**, not `ScoreTuningContext`:
`accidental_extensions` never participates in undo, because no operation ever
writes it and undo must leave it exactly as it found 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 — explicit non-goal: G2b authorizes **no** pruning or compaction

**G2b does not authorize pruning or compaction of the canonical operation
log**, and nothing in this packet may implement, enable, or prepare either.

`spec/PLAN_GENESIS_OPS.md` §3 requires this stated outright, and the reason is
that G2b **sharpens** the standing prohibition rather than relaxing it. Before
this rung, pruning was a performance concern: it would have discarded
re-derivable state. **The moment G2b lands, pruning would discard *authored
genesis state*** — the tuning context exists canonically only in the op log,
because the canonical base embeds no graph values for any field.

The prohibition remains blocked on **disposition C** (the canonical base
carrying graph values). There is no `fn prune` in the tree today, which is
exactly why the prohibition is free now and would be catastrophic later. **If
the implementation finds itself wanting a prune or compaction step for any
reason, that is a finding to report, not a feature to add.**

### Pin 10 — 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. Touch table

**Derived from G2a's actual footprint** (`git show 7df5ca1 --name-only`, thirty
files) plus G1's one extra, then extended for what G2b does that neither did.
It is a **floor, not a ceiling** — a touch outside it is a finding to report,
but a file here that turns out not to need changing is fine, said plainly.

### Core — the new type

| # | File | Change |
|---|---|---|
| 1 | `core/src/graph.rs` | **new `TuningContextSettings`** (the five wire-bearing fields, in codec order); doc it as the authored subset of `ScoreTuningContext` and say why `accidental_extensions` is absent |
| 2 | `core/src/lib.rs` | **public export** `epiphany_core::TuningContextSettings` (the ratified path) |
| 3 | `core/src/codec.rs` | its `Codec` — **byte-identical to `ScoreTuningContext`'s existing five-field walk**; add the assertion that the two encodings agree |
| 4 | `core/DECISIONS.md` | the subset ruling and its rationale |

### Ops — the operation

| # | File | Change |
|---|---|---|
| 5 | `ops/src/payload.rs` | `SetTuningContext` **kind 34** in the enum, the hand-written `discriminant()` match, `schema_major()` → **3** (pin 2), `tag()`, tag **34** inside `operation_kind_tag_vocabulary!`, and **`introduced_minor()` → epoch 10 in both spaces** (pin 4) |
| 6 | `ops/src/reduce.rs` | the `WriteChain<TuningContextSettings>` — decl, snapshot, init, **seed**, setter, undo verdict, restoration apply, working-snapshot save/restore. **Copy `set_metadata` structurally** (pin 5) |
| 7 | `ops/src/envdecode.rs` | envelope decode arm |
| 8 | `ops/src/migrate.rs` | migration arm |
| 9 | `ops/src/v0.rs` | v0-catalog arm |
| 10 | `ops/src/valuegen.rs` | a generator for the payload |
| 11 | `ops/src/vectors.rs` | **decode vectors pinned to literal bytes, not round-trip** (plan trap 4: a self-consistent reorder passed 1283 tests and 8/8) |
| 12 | `ops/src/fuzz.rs` | fuzz arm |
| 13 | `ops/src/textproj_kind.rs` | the kind **count** — hand-maintained (pin 8) |
| 14 | `ops/src/lib.rs` | public exports |
| 15 | `ops/DECISIONS.md` | the rung's decisions |

### Bundle — the accept-set raise (**new to G2b; G2a touched no bundle file**)

| # | File | Change |
|---|---|---|
| 16 | `bundle/src/bundle.rs` | `max_supported_major(OperationEnvelopeBlock)` **2 → 3** (:69) **and the rewritten rationale at :53-58** whose current text this rung falsifies (pin 3) |
| 17 | `bundle/DECISIONS.md` | why the raise is charged to this surface alone |

### Boundary crossings — budgeted up front (pin 8)

| # | File | Change |
|---|---|---|
| 18 | `editor-core/src/barriers.rs` | `subjects_of` arm — **compiler-forced**; without it the workspace does not build and the gate cannot run at all |
| 19 | `layout-ir/src/barrier.rs` | the "one past the vocabulary" literal → 35 |
| 20 | `testkit/src/generators.rs` | the `rng.below(N)` bound |
| 21 | `testkit/src/layout_stub.rs` | confirm the derived `PAYLOAD_FREE` path still holds — **prefer deriving over extending** |
| 22 | `testkit/tests/text_projection_grammar.rs` | the kind **count** |

### Text projection

| # | File | Change |
|---|---|---|
| 23 | `textproj/src/parse.rs` | the kind production |
| 24 | `textproj/src/project.rs` | the projection arm (G1 touched this; G2a did not — **check, don't assume**) |
| 25 | `textproj/src/vectors.rs` | vector coverage for the new kind |
| 26 | `textproj/src/lib.rs` | **`COMPANION_VERSION` 0.10.0 → 0.11.0** |

### Normative documents — the four-document ritual (pin 7)

| # | File | Change |
|---|---|---|
| 27 | `spec/binary_format.tex` | payload-layout row, tag row, the **accept-set/major-3 text**, the §2373 minor-additive history (kind 34 / epoch 10), version, Revision History row |
| 28 | `spec/operation_catalog.tex` | a `\section{SetTuningContext}`, version, changelog |
| 29 | `spec/core_spec.tex` | the **normative `OperationKind` *and* `OperationKindTag` listings**, plus any spelled-out payload count |
| 30 | `spec/text_projection.tex` | kind production, companion 0.11.0, changelog |
| 31–34 | `spec/binary_format.pdf`, `operation_catalog.pdf`, `core_spec.pdf`, `text_projection.pdf` | **all four regenerate and are committed** — every `.tex` source changes here |

### Vectors and tracking

| # | File | Change |
|---|---|---|
| 35 | `spec/vectors/decode_vectors.txt` | regenerate |
| 36 | `spec/vectors/textproj_document_vectors.txt` | regenerate |
| 37 | `spec/PASS13_CANDIDATES.md` | **close P13-S13**, citing this rung and the `metadata` precedent (pin 6) |
| 38 | `spec/PLAN_GENESIS_OPS.md` | mark G2b complete; ladder advances to G3 |

**Already done by the ratification, do NOT redo:** epoch 10 is recorded in
`spec/PLAN_GMINOR_SCHEMA_MINOR.md` §4. Transcribe it into code; do not edit that
plan.

## 4. 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 restores the **seeded base** settings, and does so identically whether the seed was the default or a non-default value — with `accidental_extensions` untouched throughout | Skip `seed()` on the tuning chain during base ingest, so the first undo yields `NotWritten` instead of `Restore(Base)`; must fail. **Assert the two cases are indistinguishable**, not that they differ |
| 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 | Replace the dispatch arm with `OperationKind::SetTuningContext(_) => OperationEffect::Applied` (`reduce.rs`), bypassing tuning reduction while keeping the match exhaustive; must fail on the **authored tuning-context** assertions while the spine ops stay applied and the note stays reachable. **Corrected 2026-07-29:** this row previously said "mutation is t2's", which the sweep disproved — t9 stayed green under t2's `schema_major` change, because the spine reaches a note regardless of stamping. A shared mutation that does not kill the test signs nothing |
| 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 |

---

## 5. 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
the §3 touch table — the editor track's dirt must appear unchanged
in both.

## 6. 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.