# Contract: Push 4b tranche 3a — the accidental vocabulary, in memory

Repo root `/home/jeans/Repos/active/epiphany`. The plan is
`spec/PLAN_PUSH4B_TUNING.md`, Ruling D. Read this file in full before editing.

Tranche 3 completes `ScoreTuningContext` — its three unencoded spec fields
(`accidental_extensions`, `smufl`, `overrides`) go on the wire, which opens
schema major 3 and freezes the layout permanently. Because that freeze is
irreversible, the work is split: **3a (this tranche) builds the type surface in
memory with a real consumer, so the shapes are exercised while still free to
change; 3b freezes them on the wire.** This is the same reversible-first
discipline tranches 1 and 2 used, and it has caught real bugs twice.

So this tranche adds **no `Codec`, no wire movement** — canonical bytes stay
byte-identical. It is entirely `epiphany-core`, in memory.

## Blast radius

* `crates/epiphany-core/src/` — a new module for the accidental/glyph/engraving
  vocabulary; small changes to `graph.rs` (`ScoreTuningContext`), `codec.rs` (the
  hand codec's `dec` only — see below), `pitch.rs` (new id newtypes), `lib.rs`
  (re-exports); the compatibility consumer (likely `invariants.rs`).
* `crates/epiphany-core/DECISIONS.md`.
* Test files under `crates/epiphany-core/`.

You edit **no `.tex`**, add **no requirement** (counts stay 212/282/282), and
touch **no other crate**. In particular **do not touch `epiphany-layout-ir`** —
see the `SmuflVersion` note below — and stay clear of `crates/epiphany-editor-gui/`,
`spec/PLAN_EDITOR_APP.md`, `spec/CONTRACT_EDITOR_T1A_GOLDENS.md` (concurrent
parallel work).

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

Same as tranches 1/2/2b. Do not write a `Codec` impl for any new type, do not put
anything new on the wire. Canonical bytes MUST be byte-identical before and after
— if any golden or fuzz digest moves, stop and report.

### The `ScoreTuningContext` codec, exactly as far as it must go

`ScoreTuningContext` (`graph.rs:1659`) currently has four Rust fields
(`default_pitch_space`, `default_tuning_system`, `reference`, `overrides`), and a
**hand-written** `Codec` (`codec.rs:1848`) that encodes the first three and
defaults `overrides` on decode. Add the two missing spec fields **in memory**:

```rust
pub accidental_extensions: Vec<ScoreAccidentalExtensions>,
pub smufl: SmuflVersionRequirement,
```

Then extend **only the hand codec's `dec`** to default these two as well
(`accidental_extensions: Vec::new()`, `smufl: <the default below>`). **`enc` is
unchanged** — it still writes exactly the three wire fields, in the same order.
The three new fields are in-memory-only this tranche; 3b encodes them.

Prove it: a round-trip test that a `ScoreTuningContext` (or a `Score`) with
non-empty `accidental_extensions`/`smufl`/`overrides` encodes to **byte-identical**
output as one with all three empty/default, and decoding either reconstructs the
three as empty/default. This is the direct analogue of tranche 2's
`overrides_do_not_reach_the_wire`, extended to all three. The hand codec's
rationale comment (`codec.rs:1835`) should be updated to say all three fields stay
off the wire until 3b.

`SmuflVersionRequirement` needs a `Default` for the decode path. Use
**`{ minimum: SmuflVersion(1.4), authored_against: SmuflVersion(1.4) }`** — 1.4 is
the SMuFL version the repo already targets (`layout-ir/glyph.rs:120`), so the
default aligns with what 3b will unify against.

## What to build

### 1. The types, transcribed from Chapter 4 with three ratified corrections

From `core_spec.tex` §"Accidental Registries" (`3054`–`3234`) and §"Glyph
References and SMuFL" (`3235`–`3277`). Transcribe field-for-field, in spec order,
**except** the three corrections below (P13-S10/S11/S12, ratified 2026-07-23):

* `ScoreAccidentalExtensions { base: AccidentalRegistryId, additions: Vec<AccidentalDefinition>, overrides: Vec<AccidentalDefinition> }` (`:3228`)
* `AccidentalDefinition { id: AccidentalId, name: String, glyph: GlyphReference, modification: PitchSpaceModification, engraving: AccidentalEngraving, combination: AccidentalCombination }` (`:3073`)
* `GlyphReference` (`:3244`) — `enum { Smufl(u32), Custom(CustomGlyphId), Composite(Vec<GlyphReference>) }`. **Recursive**, and **Chapter 4's own** — do NOT unify with or import layout-ir's `struct GlyphReference(Cow<str>)`, a different concept sharing the name (the homonym the plan's Ruling D §"correction" calls out).
* `PitchSpaceModification` (`:3097`) — `enum { CmnChromatic(i8), EdoSteps(i16), JiRatio { numerator: i32, denominator: NonZeroU32 }, Cents(CanonicalF64), Registered(ModificationRegistryId) }`. **S10 correction: `Cents(CanonicalF64)`, not `Cents(f64)`** — a raw `f64` is unencodable in canonical state (`serialize.rs:110` decodes floats only through `CanonicalF64::from_le_bytes → NonFiniteFloat`; there is no `Codec for f64`). Reuse `CanonicalF64`/`SpaceUnit`'s existing pattern.
* `AccidentalEngraving { bounding_box: EngravingBoundingBox, anchor: AnchorPoint, advance_width: SpaceUnit, stacking_order: i32, default_parenthesized: bool }` (`:3159`)
* `EngravingBoundingBox { left: SpaceUnit, right: SpaceUnit, top: SpaceUnit, bottom: SpaceUnit }` (`:3150`) — Ruling D's canonical-safe box; `SpaceUnit` already exists (`graph.rs:895`).
* `AnchorPoint { x: SpaceUnit, y: SpaceUnit }` — **S11 correction: it is undefined in the spec** (`:3166` references it, nothing defines it), and core cannot depend on layout-ir. Define it core-native over `SpaceUnit`, and give it a doc comment pinning the frame per the ratification: **x/y in canonical space units, y-up, relative to the glyph's coordinate origin** (the box at `:3160` is "relative to the glyph's anchor point", so the anchor needs an unambiguous origin).
* `AccidentalCombination` (`:3210`) — `enum { Solitary, Stacking { compatible_groups: Vec<AccidentalGroupId> } }`
* `SmuflVersion` — **S12 correction, read this carefully.** `{ major: u16, minor_centi: u16 }`, where `minor_centi` is the version's fractional part **normalized to hundredths**: SMuFL versions are decimal fractions, so 1.12→`(1,12)`, 1.18→`(1,18)`, 1.20→`(1,20)`, **1.3→`(1,30)`**, **1.4→`(1,40)`**. Derived `Ord` on `(major, minor_centi)` is then correct across SMuFL's real release order (1.12 < 1.18 < 1.20 < 1.3 < 1.4); literal-minor storage would sort 1.3 and 1.4 *before* 1.12. Give it a constructor or documented mapping that performs the normalization (interpret the fractional digits as a decimal, express in hundredths: one digit ×10, two digits as-is), so a caller cannot accidentally pass a literal minor. **Do NOT touch `layout-ir`'s existing `SmuflVersion`** (`glyph.rs:29`, literal-minor, load-bearing for `GlyphCatalogIdentity`): unifying the two and moving `GlyphCatalogIdentity` is 3b's job, done deliberately with golden regen. For this tranche `core::SmuflVersion` and layout-ir's are a bounded homonym — and core cannot import layout-ir's, so within core there is no ambiguity. Leave a comment saying 3b unifies them.
* `SmuflVersionRequirement { minimum: SmuflVersion, authored_against: SmuflVersion }` (`:3269`)

New id newtypes (`catalog_id!` in `pitch.rs`, beside the others): `CustomGlyphId`,
`ModificationRegistryId`, `AccidentalGroupId`. `AccidentalRegistryId` and
`AccidentalId` already exist.

**No `Codec` for any of these.** They are in-memory only.

### 2. The consumer — this is what keeps the surface from being NOTEHEAD_ANCHORS

A type surface with no reader is the trap this project has paid for. Build two
in-core consumers that read the new types:

**(a) Accidental resolution.** A function that resolves an `AccidentalId` against a
score's `accidental_extensions`, honoring the spec's precedence (`:3224`:
"Extensions are stored on the score and override or augment the base registry"):
an `overrides` entry wins over an `additions` entry wins over the base registry.
Returns the resolved `AccidentalDefinition` (so it reads the whole structure —
`base`, `additions`, `overrides`, and the definition's fields).

**(b) The modification-compatibility invariant** —
`req:tuning:accidental-modification-compatibility` (`core_spec.tex`, the
requirement label at `:3120`): an accidental's `PitchSpaceModification` MUST be
expressible in the interval algebra of every pitch space referencing its
registry, and an implementation MUST reject a score that violates this. The
requirement's rules: `CmnChromatic` is valid only in `DiatonicOverChromatic` (or
compatible) spaces; `EdoSteps` only in `Chromatic` (or `Registered`); extend the
same shape to `JiRatio`↔`JiLattice`. Add this as a `check_invariants` violation
(`invariants.rs:221`), reading `built_in_position_structure` (tranche 1) for each
referenced space. Fail closed on a genuinely unknown space, as tranche 1 did.

Glyph and engraving metadata (`GlyphReference`, `AccidentalEngraving`,
`AccidentalCombination`) are carried by these consumers but their deep consumer is
the engraver, out of core — a later tranche. Say so in your report; do not
fabricate an in-core engraving consumer to manufacture coverage.

## Proof of life — assert behaviour and the ratified corrections

1. **S12 ordering** — `SmuflVersion` constructed from the real release sequence
   orders correctly: 1.12 < 1.18 < 1.20 < 1.3 < 1.4 (i.e. `(1,12) < (1,18) <
   (1,20) < (1,30) < (1,40)`). A test that would FAIL under literal-minor storage
   (where 1.3 sorts before 1.12). This directly locks S12.
2. **S10** — a `PitchSpaceModification::Cents` round-trips a finite value and
   cannot be constructed with a non-finite one (the `CanonicalF64` guard).
3. **Compatibility invariant** — a `CmnChromatic` accidental in a `cmn-12`
   (`DiatonicOverChromatic`) space passes; the same accidental in an `edo-31`
   (`Chromatic`) space is rejected with the violation. A test that only checks the
   accept case would miss the reject — assert both.
4. **Resolution precedence** — an `overrides` entry for an id shadows an
   `additions` entry for the same id; a base-registry id with no extension
   resolves to the base.
5. **The wire invariant** — the byte-identity round-trip from §"the codec"
   (all three new fields off the wire).

## Verification

**Mutation-verify every new test.** Assert the anchor is present before
substituting. **Restore by reversing the exact substitution — never `git
checkout`, which discards uncommitted work.** Mutate meaningfully — e.g. store
`SmuflVersion`'s minor literally instead of centi-normalized and confirm the S12
ordering test dies; weaken the compatibility check to accept everything and
confirm the reject test dies. Report each mutation and the test that died.

Then the full gate, actual commands and output:

1. `cargo fmt --all --check`
2. `cargo clippy --workspace --all-targets` → 0
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
   212/282/282.

Zero golden churn and zero canonical-byte movement expected.

## Citations

Read any `req:*` you cite and confirm it says what your sentence claims (P13-S9).
Labels here: `req:tuning:accidental-modification-compatibility`,
`req:tuning:smufl-version-fallback`, `req:determinism:canonical-floating-point`,
`req:pitch:alteration-unit`.

## Do not

* Write a `Codec` impl, or move anything onto the wire.
* Edit `layout-ir` (the `SmuflVersion` unification and `GlyphCatalogIdentity` move
  are 3b), any other crate, any `.tex`, or the parallel editor-app files.
* Use `Cents(f64)`, literal-minor `SmuflVersion`, or an `AnchorPoint` without the
  frame doc.
* Unify Chapter 4's `GlyphReference` with layout-ir's — they are homonyms.
* Restore a mutation with `git checkout`. Re-bless a golden or move a count.

## Report

State: the types added and where; the three ratified corrections as you
implemented them (Cents→CanonicalF64, AnchorPoint frame, SmuflVersion
minor_centi); the extended hand codec and the byte-identity proof that all three
fields stay off the wire; the two consumers and exactly which fields each reads
(and which fields are carried-but-not-consumed-in-core, honestly); the mutation
for every test and which died; the actual gate output; whether any golden moved;
and anything you chose not to do and why.