epiphany/spec/CONTRACT_EDITOR_T4PRE_W2_GLYPHS.md

# Contract: Editor T4-pre W2 — the shared typed glyph-asset seam

Repo root `/home/jeans/Repos/active/epiphany`. Governed by
`spec/CONTRACT_EDITOR_T4PRE_IR.md` §W2 and `spec/PLAN_EDITOR_APP.md` §3.7 /
Ruling A, which names "a shared typed glyph-asset seam" as a T4 prerequisite:
a canvas tessellator needs typed vector paths from a crate both the renderer
and the app can depend on. W1 landed at `dd33b34`.

Execution model as T1a/T2/T3/W1: Sonnet subagent, coordinator line-level
review with independent mutation re-runs, user deep-dives at contract
sign-off, any new golden baseline, and the final report. Mutation discipline
throughout: anchor-assert before substituting, restore by reversing, never
`git checkout`.

**Parallel safety.** The genesis-operation tranche is in flight on the other
track, laddered as G1/G2/G3 in `spec/PLAN_GENESIS_OPS.md` under
`spec/RULING_GENESIS_PERSISTENCE.md`. Across its rungs it owns
`epiphany-core`, `epiphany-ops`, all `.tex` (so the requirement counts move),
testkit's requirement-label constants, vectors and fuzz generators, and — at
G2 — `epiphany-bundle` for the `OperationEnvelopeBlock` accept-set raise.
**This packet touches none of them**, at any rung. Report observed requirement
actuals; never assert stale numbers.

---

## The verified starting point

Confirm these as you go; they make the packet far smaller than §3.7's wording
suggests:

* **The typed path type already exists, in `layout-ir`.** `PathCommand`,
  `GlyphRenderData { outline: Vec<PathCommand>, bitmap: Option<GlyphBitmap> }`,
  and `GlyphCatalog::render_data(&self, name) -> Option<GlyphRenderData>` are
  all defined (`layout-ir/src/glyph.rs:~285-315`). **W2 populates a seam that
  is already designed; it does not design one.** `BravuraCatalog::render_data`
  returns `None` today by deliberate, documented honesty — "reporting `Some`
  would claim render data that does not exist."
* **The outlines exist, as SVG `d` strings**, in
  `render-svg/src/outlines_generated.rs`: `BravuraOutline { name, codepoint,
  path: &'static str, bbox: [f32; 4] }`, staff-space units, y-up, 4 decimals,
  sorted by name. `outline()` is `pub(crate)`; `bundled_glyph_count()` and
  `smufl_codepoint()` are `pub` but have **no callers outside `render-svg`**
  (verified workspace-wide).
* **`Bravura.otf` is NOT in the tree.** `render-svg/tools/` holds only
  `extract_bravura_outlines.py` and `OFL.txt`; the generated header pins
  source SHA-256s verified *at extraction time*. Re-running the extractor
  therefore requires fetching the font and **cannot be assumed**. This
  determines pin 4.
* **The metrics table is conformance identity.** `BRAVURA_METRICS` lives in
  `layout-ir/src/glyph.rs`; `metrics_hash_for` hashes `(name, metrics)` pairs
  with the *values* participating (the crate's own note at `glyph.rs:372-375`
  exists precisely to prove a field participates), and `GlyphCatalogIdentity`
  is encoded into `ResolvedLayoutIR`'s canonical bytes.

## Design pins

1. **A new crate, `epiphany-glyphs`**, owns the glyph assets: the moved
   `outlines_generated.rs`, the extractor tool, and **`OFL.txt`, which travels
   with the redistributed outlines** (the generated file's license header
   stays intact — Bravura is SIL OFL 1.1 and the notice is a redistribution
   condition, not decoration). It depends on `epiphany-layout-ir` and exposes
   a catalog type implementing `GlyphCatalog` with a **real `render_data`**.
   No cycle: glyphs → layout-ir, never the reverse.
2. **`render-svg` keeps its public API and its exact output.** It depends on
   `epiphany-glyphs`, and `bundled_glyph_count`/`smufl_codepoint` remain
   exported from `render-svg` (delegating or re-exporting) even though nothing
   outside calls them — an API that costs one `pub use` is not worth breaking.
   `font_subset_generated.rs` stays in `render-svg`: an embeddable font subset
   is a renderer concern, not a shared asset.
3. **The metrics table does not move and does not change.** Out of bounds
   entirely. Any edit to it churns every conformance byte in the repo.
4. **Typed paths are derived from the `d` strings by an in-crate parser, not
   by re-running the extractor.** The font is not in the tree, so regeneration
   is not reproducible here. The parser covers exactly the grammar the
   generator emits — absolute `M`/`L`/`C`/`Z`, decimal coordinates — and the
   crate stays **dependency-free** (it is in the MSRV closure; no new
   dependency, no `build.rs`).
5. **Equivalence is proven by round-trip, not asserted.** Parse every bundled
   glyph's `d`, re-emit it in the generator's exact formatting, and compare to
   the original string **byte-for-byte**. If all bundled glyphs round-trip,
   the typed form provably describes the same geometry and no geometric
   spot-checking is needed. *Sanctioned fallback if the generator's number
   formatting cannot be reproduced exactly:* parse both the original and the
   re-emitted string and compare the full coordinate sequences as exact `f32`.
   **Report which was used and why** — do not silently take the weaker one.
6. **`render_data` is deterministic and side-effect-free.** Caching (a
   one-time lazily built table) is permitted; it must not change results, and
   two calls must return equal data.

## Tests + minimum mutations

* **(g1) parser round-trip** over every bundled glyph (pin 5) — the packet's
  load-bearing test. *Mutation:* perturb one parsed coordinate → dies.
* **(g2) `Close` survives parsing** — *mutation:* drop the trailing `Z` →
  dies.
* **(g3) every pipeline glyph has render data** — the `BRAVURA_METRICS` name
  set all resolve through the new catalog's `render_data`, mirroring
  `render-svg`'s existing `every_pipeline_glyph_has_a_bundled_outline`.
  *Mutation:* return `None` for one bundled glyph → dies.
* **(g4) outline ink fits the declared metrics bbox** — the cross-table
  consistency the tree asserts in prose and tests nowhere: `glyph.rs:107-109`
  claims the metrics and outlines come from the same release "so reserved
  advances/bboxes and the drawn ink agree." Compare each glyph's outline
  extent (staff spaces) against its `BRAVURA_METRICS` bbox (font units, 250
  per staff space), with a stated tolerance for the outlines' 4-decimal
  rounding. **Report the actual worst-case deviation.** *Mutation:* inflate
  one parsed coordinate past the declared box → dies. **If a real glyph fails,
  that is a finding to report — not a reason to widen the tolerance.** It
  would mean engraving reserves the wrong space for that glyph, the same bug
  class that twice bit the vertical metric.
* **(g5) `render-svg`'s bytes do not move** — *mutation:* emit the `d` from
  the typed form instead of the stored string → the goldens die.
* **(g6) absolute, not relative** — *mutation:* treat a `C` as relative →
  round-trip dies.

## Blast radius

New `crates/epiphany-glyphs/**` (including the moved
`outlines_generated.rs`, `tools/extract_bravura_outlines.py`, `tools/OFL.txt`,
and a `DECISIONS.md`); `crates/epiphany-render-svg/src/{lib.rs, outline.rs,
svg.rs}` and its `DECISIONS.md`; the workspace `Cargo.toml` member list.
Nothing else — no `layout-ir` edit (the seam is already there), no
`epiphany-core`, no `epiphany-ops`, no `epiphany-bundle`, no `.tex`, no CI
change (the MSRV job runs `--workspace --exclude epiphany-editor-gui`, so a
new crate joins automatically — which is exactly why it must be MSRV-clean and
dependency-free).

## Gate (actual output)

The standard six; conformance **9/9 with `--features golden-gate`, 8/8
without** (both run); requirement labels reported as observed. Plus the two
W1 byte locks, run as before/after comparisons against the base commit and
reported with their actual sizes:

* **Layout canonical bytes byte-identical** for the reference-suite fixtures
  plus `ten_measure_single_staff(0)` and `ten_measure_with_slurs(0)`. (W1's
  numbers, for reference: 21615 / 6948 / 3839 / 5602 / 2299 / 2299 / 21615 /
  22119.)
* **All five GUI goldens byte-identical.** Nothing here may change a pixel;
  no golden is re-blessed in this packet.
* **`cargo tree -p epiphany-glyphs` shows no third-party dependency.**

## Coordinator deliverable, alongside

`spec/ANALYSIS_TEXT_RUN_PRIMITIVES.md` — W3, the text-run primitive decision
(Ruling A criterion 3: shaping, fallback, bidi, and metrics consistent across
canvas, SVG/PDF export, hit testing, and the accessibility tree). A decision
document, not an implementation, written by Fable while W2 runs, because
getting it wrong forecloses the toolkit choice T4's spike exists to make
freely.

## Report

Per packet, as every tranche: files + summary, exact asserted values
(including g4's worst-case deviation), every mutation with kill evidence, gate
output, deviations flagged explicitly.