# Contract: Push 4b tranche 2 — tuning resolution, in memory

Repo root `/home/jeans/Repos/active/epiphany`. The plan is
`spec/PLAN_PUSH4B_TUNING.md`; its four rulings are granted. Tranche 1 (the
pitch-space vocabulary and the retired P13-S2 guard) has landed. Read this file
in full before editing anything.

This tranche makes tuning **resolvable**: given a pitch, a tuning system, and a
reference pitch, compute the frequency it sounds at, walking the five resolution
scopes. Like tranche 1 it is a **vertical slice that stays in memory** — no
`Codec`, no wire movement, nothing frozen. It is the reversible half of the
remaining work; the schema-major-3 wire bump is a separate later tranche, so that
the resolution logic is exercised and proven correct before anything is frozen.

## Blast radius

* `crates/epiphany-core/src/` — a new module for the tuning-resolution
  vocabulary and the resolver; small changes to `graph.rs` (the
  `ScoreTuningContext` struct) and `codec.rs` (see the macro trap below);
  `lib.rs` re-exports.
* `crates/epiphany-core/DECISIONS.md` — record the tranche.
* Test files under `crates/epiphany-core/`.

You edit **no `.tex` file** and add **no requirement**, so all three counts in
`crates/epiphany-testkit/tests/requirement_labels.rs` stay at 212 / 282 / 282 —
if one moves, stop and report. You touch no other crate's source. In particular
`crates/epiphany-editor-gui/**` is being worked in parallel — do not go near it.

## The central prohibition: no `Codec`, no wire movement

Same as tranche 1, and for the same reason (Ruling C, `req:binfmt:frozen-layout`):
**canonical bytes MUST be byte-identical before and after this tranche.** The
resolver and its types stay in memory so they remain free to change when the wire
tranche discovers something about them. Do not write a `Codec` impl for any new
type. Do not add anything to the wire.

### The `ScoreTuningContext` field, and the macro trap

The resolver's scope walk needs `overrides`. Add exactly one field to
`ScoreTuningContext` (`graph.rs:1646`):

```rust
pub overrides: Vec<TuningOverride>,
```

Add **only** this one. Do **not** add `accidental_extensions` or `smufl` — the
resolver does not consume them, they pull in a large unconsumed type subtree, and
they belong to the wire tranche where they are added, encoded, and consumed by
engraving together. An unconsumed type surface is the `NOTEHEAD_ANCHORS` trap;
tranche 1 held that line and so does this one.

**The trap:** `ScoreTuningContext` is encoded by `struct_codec!` (`codec.rs:1835`),
whose generated `dec` ends `Ok(ScoreTuningContext { default_pitch_space,
default_tuning_system, reference })` — a struct literal naming exactly the three
wire fields. Adding a fourth field makes that literal fail to compile, and the
macro's `TextValue` destructure fails too. So you **must replace the
`struct_codec!` line with a hand-written `Codec` (and `TextValue`) impl** that
encodes and decodes exactly the three existing fields in their existing order and
constructs `overrides` as `Vec::new()`. The wire stays three fields; `overrides`
is in-memory-only. Confirm with a round-trip test that a `ScoreTuningContext`
with non-empty `overrides` encodes to the same bytes as one with empty
`overrides` — the field must not reach the wire this tranche.

Field *order* is the wire tranche's problem, not yours: the spec order places
`overrides` last, after `accidental_extensions` and `smufl`. Where you put it in
the Rust struct is free (the manual codec names its own encode order); leave a
comment that the encoded order is fixed at the three wire fields and the rest is
the major-3 delta.

## What to build

### 1. Types (in memory, grown not stubbed)

From `core_spec.tex` §"Tuning Systems" (`:3279` onward): `TuningSystem`
(`:3287`), `TuningResolution` (`:3309`), `TuningOverride` (`:3527`), `TuningScope`
(`:3534`). `ReferencePitch` already exists (`pitch.rs:469`) and is encoded — reuse
it.

`TuningResolution` is a six-variant enum in the spec. **Define only the variants
this tranche's built-in catalog constructs** — `EqualTemperament { divisions_per_octave }`
and `PerPositionRatios(Vec<PositionRatio>)` — plus `PositionRatio` itself. The
other four (`Function`, `Overlay`, `Imported`, `Adaptive`) are added when a
built-in needs them: `Function` in the temperament tranche, `Adaptive` when
`HarmonicContext` exists. Growing an in-memory enum later is free; transcribing
four variants whose payload subtrees (`TuningParameters`, `ImportedTuningData`,
`AdaptiveTuningParameters`, …) nothing constructs is exactly the unconsumed
surface to avoid. Note in a comment that the enum is deliberately partial and
which tranche each remaining variant waits on.

### 2. The built-in tuning catalog, as data (partial, honestly)

A lookup from `TuningSystemId` to a `TuningSystem`. This tranche resolves **nine**
of the twenty:

* **Six `tet-*`** (`tet-12`, `-19`, `-22`, `-31`, `-53`, `-72`) —
  `EqualTemperament { divisions_per_octave: N }` from the identifier.
* **Three `ji-static-5limit-*`** (`-C`, `-G`, `-D`) — `PerPositionRatios` whose
  twelve ratios are **computed from the lattice block**
  $\{3^a 5^b \mid a \in [-1,2],\ b \in [-1,1]\}$ (ratified,
  `req:tuning:ji-static-construction`, `core_spec.tex:4015`), octave-reduced and
  assigned in ascending order from the anchor. Compute them from the block in
  code — do **not** paste the twelve ratios as a literal table. The construction
  belongs in the code, exactly as it now belongs in the spec, so the two state
  the same rule in the same form. `-C`/`-G`/`-D` are the one construction at three
  anchors.

**Deferred, fail-closed, and reported (do not fake):**

* **The ten historical temperaments** (`pythagorean`, the three `meantone-*`,
  `werckmeister-iii`/`-iv`, `vallotti`, `kirnberger-ii`/`-iii`, `young-ii`) are
  **tranche 2b**, not this one — see the closing section. Their catalog entries
  resolve to a not-yet-supported result here (fail closed), not to a guess.
* **`ji-adaptive-5limit`** needs `HarmonicContext`, which does not exist in Rust
  and whose completion the spec puts out of scope. Fail closed; a later tranche
  builds the context and the adaptive resolver together.

An unresolved or deferred system MUST fail closed at the resolver — a clear
"not yet supported" error, never a fallback frequency. Report which of the twenty
resolve and which do not.

### 3. The frequency resolver

A function from (pitch-space position, `TuningSystem`, `ReferencePitch`) to a
frequency in **Hz as `f64`**. Frequency is non-canonical:
`req:determinism:canonical-floating-point` lists tuning among the floating-point
contexts and bars floating point only "where exact identity is needed", which a
sounding frequency is not. So `f64` is correct and nothing here goes near
canonical bytes.

The one subtlety worth stating: the construction's ratios are relative to the
tuning's own 1/1 (the anchor), but the **reference pitch** fixes a *different*
position's absolute frequency (A4 = 440 Hz by default). Anchor correctly: derive
the 1/1 frequency from the reference, then every position's frequency is the 1/1
frequency times that position's ratio (and octave). For `EqualTemperament`,
frequency is `ref_freq · 2^((position − ref_position)/N)`. Getting this anchoring
right is the point of building the resolver in memory first, where it is free to
be wrong and fix.

### 4. The five-scope resolution walk

`req:tuning:tuning-resolution-order` (`core_spec.tex:3549`): for a pitch, resolve
each of the three components (pitch space, tuning system, reference)
**independently**, walking from most specific to most general and halting at the
first scope that supplies a non-inherited value:

1. the pitch's own `AcousticPitch` — an explicit `TuningReference::Explicit` or
   `AcousticRealization::AbsoluteHz` short-circuits;
2. the voice containing the pitch;
3. the staff containing the voice;
4. each region enclosing the pitch, innermost to outermost;
5. the score's default tuning context.

Scopes 2–4 come from `ScoreTuningContext.overrides`: each `TuningOverride` carries
a `TuningScope` (`Voice`/`Staff`/`Region`/`Range`) and optional per-component
values. The walk finds the applicable overrides for the pitch (matching scope to
the pitch's voice/staff/region via the score graph) and takes the most specific
value per component. Independent per-component resolution is normative — a passage
may override only the reference while inheriting space and system.

### 5. The compatibility check

`req:tuning:tuning-system-compatibility` (`core_spec.tex:3581`): the resolved
tuning system's declared `pitch_space` MUST equal the resolved pitch space, or be
declared compatible via a registered mapping; otherwise the configuration MUST be
rejected. **No mapping
registry exists.** This tranche accepts **only same-`pitch_space`** and fails
closed on any mismatch — the registry is deferred, matching how tranche 1 handled
the underdetermined spaces. Report it as a deliberate deferral.

## Proof of life

Tests that assert *values*, not `is_ok()`:

1. **`tet-12`, A4 = 440 Hz → C5 ≈ 523.2511 Hz.** Assert within a tight tolerance
   (`ToleranceClass::AcousticCents` in `epiphany-determinism` is the project's
   acoustic tolerance; a cents-level check is right). This pins the reference
   anchoring.
2. **`ji-5limit` resolves a major third distinctly from `tet-12`.** The just
   major third is 5/4 (386.31 ¢); the equal-tempered one is 400 ¢. Assert the two
   resolved frequencies differ by the expected ~13.7 ¢, in the right direction.
   This is the "tuning actually does something" test.
3. **Scope precedence.** A voice-scoped `TuningOverride` changes the resolution
   for a pitch in that voice, and a pitch *outside* it still resolves to the score
   default. Assert both — a walk that ignores scope passes the first and fails the
   second.
4. **Compatibility rejects a mismatch.** A tuning system whose `pitch_space`
   differs from the resolved pitch space is rejected, not silently resolved.
5. **A deferred system fails closed.** `ji-adaptive-5limit` (and a temperament)
   return the not-supported error, never a frequency.

## Verification

**Mutation-verify every new test.** Re-introduce the bug each exists to catch,
confirm it fails, restore — and **assert the anchor text is present before
substituting**, because a replacement that matches nothing is a no-op mutation
indistinguishable from a passing test (this project has been bitten by exactly
that when rustfmt rewrapped the target line). **Restore by reversing the exact
substitution — never with `git checkout`, which discards all uncommitted work in
the file.** Report each mutation and the test that died.

Then the full gate, reporting actual commands and actual output:

1. `cargo fmt --all --check`
2. `cargo clippy --workspace --all-targets` → 0 warnings
3. `cargo test --workspace` → 0 failed
4. `RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps` → 0
5. `cargo run -q -p epiphany-testkit --example conformance_suite` → 8/8
6. `cargo test -p epiphany-testkit --test requirement_labels` → 6 passed, counts
   unchanged at 212 / 282 / 282.

**Zero golden churn and zero canonical-byte movement are expected** — this tranche
is in-memory only. If any golden file or fuzz digest moves, something reached the
wire; stop and report rather than re-blessing.

CI pins clippy at 1.95.0 and the MSRV at 1.85; local `cargo clippy` is CI's
toolchain, and `clippy::incompatible_msrv` catches any API above the 1.85 floor.

## Citations

If you cite a requirement in a doc comment, **read it first and confirm it says
what your sentence claims** — the checker proves only that a `req:*` string
resolves, not that it is relevant (filed as P13-S9 after three
resolve-but-irrelevant citations in one day). The labels in play here:
`req:tuning:tuning-resolution-order`, `req:tuning:tuning-system-compatibility`,
`req:tuning:ji-static-construction`, `req:determinism:canonical-floating-point`.

## Do not

* Write a `Codec` impl for any new type, or let any new type reach the wire.
* Add `accidental_extensions` or `smufl` to `ScoreTuningContext`, or any field
  beyond the single `overrides`.
* Transcribe `TuningResolution` variants no built-in constructs this tranche.
* Paste the twelve `ji-static` ratios as a literal table — compute them from the
  lattice block.
* Invent a frequency for a deferred system, or a compatibility mapping for a
  mismatched pitch space. Fail closed and report.
* Edit any other crate (especially `epiphany-editor-gui`, worked in parallel),
  any `.tex`, or any `DECISIONS.md` but `epiphany-core`'s.
* Restore a mutation with `git checkout`. Reverse the substitution.
* Re-bless a golden or move a requirement count to make a test pass.

## Report

State: the types added and where; the manual `ScoreTuningContext` codec and the
round-trip proof that `overrides` stays off the wire; which of the twenty tuning
systems resolve and which fail closed, with the reason for each deferral; the
reference-anchoring computation and the `tet-12` C5 value you got; the mutation
for every new test and which test died; the actual gate output; whether any
golden or digest moved; and anything you chose not to do and why.

## Next: tranche 2b — the ten historical temperaments

Not this tranche. Named here so the deferral above is a plan, not a gap.

The ten temperaments resolve via `TuningResolution::Function` with reserved
built-in identifiers, each computing its ratios **from the ratified construction**
(which fifths are tempered, by what fraction of which comma) rather than from a
transcribed cents table — the constructions are normative in `core_spec.tex`
§"Temperament Constructions" as of `5e465a1`. They are their own pass because that
is where the arithmetic must be re-verified: the S6 draft produced two
arithmetically impossible temperaments and one false ambiguity, every one properly
cited, caught only by the closure invariant. The code re-derivation deserves the
same scrutiny — each construction's twelve-fifth closure sum recomputed in code
and checked against the ratified 23.4600 ¢ (or the stated wolf residue for the
non-circulating meantones and Pythagorean). Bundling that verify-heavy arithmetic
into the resolver plumbing would make a plumbing bug and a temperament-arithmetic
bug hard to tell apart.