epiphany/spec/CONTRACT_EDITOR_T1A_GOLDENS.md

# Contract: Editor T1a — the visual golden harness

Repo root `/home/jeans/Repos/active/epiphany`. The plan is
`spec/PLAN_EDITOR_APP.md`; read its §Ruling C (granted, as amended), §Ruling A
(granted as amended 2026-07-23), and §5 in full before editing anything.
Ruling C independently authorizes this tranche. Ruling B remains blocked and
Ruling D remains conditional — **nothing in this contract touches a document,
a bundle, or `editor-core`**.

This tranche closes the repo's last unverified surface: the GUI's rendered
output has never been seen by any gate (plan Fact 1). It adds **pixel-level
golden baselines of the resvg-rasterized score** — the exact surface the demo
GUI displays — as ordinary `#[test]`s in `epiphany-editor-gui`, compared as
**decoded pixels, never encoded files**, with reviewable failure artifacts in
CI. The resolver tranche (`CONTRACT_PUSH4B_RESOLVER.md`) is in flight; plan
§5's parallel-safety rules are binding on every commit.

## Execution model — who does what

Implementation is dispatched to **subagents (Sonnet-tier), one per work
packet** (§Work packets), each with a file-scoped brief quoting this
contract's relevant section verbatim. The **coordinator (Fable)** reviews
every packet at line level before anything lands: re-runs the gate itself,
verifies each mutation's evidence (a worker's own report is never sufficient),
checks that every cited file:line says what the code claims, and rejects any
packet that drifts outside its blast radius. The **user's deep-dive points**,
named in advance:

1. **This contract's sign-off** (precedes any dispatch).
2. **Baseline review.** The four PNGs are the first visual record of this
   editor's output in the project's history, and a golden locks whatever it
   sees — **bugs included**. Before the blessing commit, the user visually
   inspects each baseline: clef and staff lines present, ledger lines correct,
   noteheads on the intended positions, slur curves plausible, system breaks
   where casting-off put them. An unreviewed baseline is an unverified claim
   wearing a checkmark.
3. **The final report** (§Report).

## Blast radius

* `crates/epiphany-editor-gui/src/main.rs` — minimal: a `#[cfg(test)] mod
  goldens;` declaration and, if needed, `pub(crate)` visibility on the
  existing `rasterize` helper (`main.rs:160`). No behavior change to the
  running binary.
* `crates/epiphany-editor-gui/src/goldens.rs` — NEW, `#[cfg(test)]`-only: the
  comparator, bless machinery, and the golden tests.
* `crates/epiphany-editor-gui/goldens/*.png` — NEW baseline images.
* `crates/epiphany-editor-gui/DECISIONS.md` — NEW (this crate's first):
  records this tranche's calls (§What to build, item 4).
* `crates/epiphany-editor-gui/Cargo.toml` + `Cargo.lock` — ONLY if the `png`
  dev-dependency fallback proves necessary (§prohibitions).
* `.github/workflows/ci.yml` — exactly **one additive step** in the existing
  `editor-gui` job (`ci.yml:109`): upload `target/golden-failures/**` with
  `if: failure()`. Nothing else in the file moves.

You touch no other crate and no other file. In particular
`crates/epiphany-core/**` is being worked in parallel by the resolver tranche
— do not go near it — and `epiphany-testkit` is frozen for this tranche
(gate promotion is T2, deliberately).

## Central prohibitions

* **Counts do not move.** Requirement labels stay **212 / 282 / 282**
  (`requirement_labels.rs:12-14`); the conformance suite stays **8/8**
  (`conformance_suite.rs:202`). If either moves, stop and report.
* **No existing golden or fuzz digest is re-blessed.** This tranche *adds*
  new PNG baselines; it modifies nothing that exists. The resolver's
  zero-churn tripwire must stay unambiguous.
* **Comparison is decoded pixels only** — dimensions + raw RGBA. Comparing
  encoded PNG bytes is the exact defect Ruling C's amendment exists to
  prevent (it locks encoder behavior and churns while pixels are identical).
* **No new runtime dependencies.** PNG encode/decode goes through the
  resvg-bundled tiny-skia (`png` is already in `Cargo.lock` via that tree).
  If the feature is not exposed through resvg's re-export, the fallback is a
  `png` **dev-dependency** (the version already in the lock) — never `image`,
  never a runtime dep.
* **Never bless to make a test pass.** A diff is a finding: it is reviewed
  (user deep-dive point 2 for new baselines; ordinary review for changes)
  before any re-bless. The bless mechanism exists for *deliberate* baseline
  updates only.
* Land only green (`cargo test --workspace` clean); whoever lands second
  rebases.

## What to build

### 1. The comparator and bless machinery (`src/goldens.rs`)

* **Rasterize** through the binary's existing `rasterize` fn (`main.rs:160`)
  — the same code path the GUI displays, `GlyphMode::PathOutline` (the
  default; no fonts), `RenderOptions { px_per_staff_space: 12.0, .. }` (the
  demo's default).
* **Compare**: decode the committed baseline PNG; assert dimensions equal,
  then raw RGBA bytes equal. On mismatch, write `actual.png`,
  `expected.png`, and `diff.png` (per-pixel highlight) to
  `target/golden-failures/<test_name>/` and name all three paths in the
  panic message.
* **Bless**: `EPIPHANY_BLESS_GOLDENS=1` writes/overwrites the baseline
  instead of comparing. Policy stated in a comment at the definition: a
  bless is a reviewed decision, never a fix.
* **The comparator's own unit tests** (value-asserting):
  * identical pixmaps pass;
  * a single altered pixel fails AND produces all three artifacts at the
    named paths;
  * **re-encoding the baseline PNG with different encoder settings still
    passes** — the decoded-pixel contract made executable;
  * mismatched dimensions fail before any pixel comparison.

### 2. The four golden states

Each test builds its session headlessly — `EditorSession::open(fixture,
Box::new(Engraver::default()))`, exactly the demo's open path (`main.rs:197`)
— asserts the *session-level values* first, then locks the pixels. Each
state renders **twice**, asserting the two SVG strings and the two pixmaps
are identical (the determinism double) before comparing to the baseline.

* **G1 — as opened**: `ten_measure_single_staff(0)`, rasterized, compared to
  `goldens/ten_measure_open.png`.
* **G2 — after a scripted pencil insert**: the target is derived through the
  session's own inverses, never a magic constant — pick the world point via
  `staff_pitch_at` / `position_at` / `default_grid_at`, **assert the resolved
  pitch and snapped beat values** (e.g., the intended nominal/octave and
  position as exact rationals), then `insert_note_at`, re-render, compare to
  `goldens/ten_measure_insert.png`.
* **G3 — after undo of that insert**: **no third baseline.** Assert the
  post-undo raster equals **G1's baseline** byte-for-byte in decoded RGBA —
  undo returns the pixels, not just the model. This is the strongest test in
  the tranche; it must reuse G1's file, not a copy.
* **G4 — casting-off**: `ten_measure_with_slurs(0)`
  (`fixtures.rs:777`) — multi-system layout **and** the
  cross-system slur-split path (`casting.rs:2262`), the layout path real
  documents take. Compared to `goldens/ten_measure_slurs_castoff.png`. The
  test additionally asserts the resolved layout actually produced **more
  than one system** (value assertion — if casting-off stops triggering, this
  must fail as a value error, not as a mysterious pixel diff).

### 3. The CI step

One additive step in the `editor-gui` job, after the test step:

```yaml
- name: Upload golden failure artifacts
  if: failure()
  uses: actions/upload-artifact@v4
  with:
    name: golden-failures
    path: target/golden-failures/
    if-no-files-found: ignore
```

Nothing else in `ci.yml` changes. (Match the `actions/upload-artifact`
major version already used elsewhere in the file, if any; otherwise v4.)

### 4. `DECISIONS.md` (the crate's first)

Record: the decoded-pixel comparison contract and why (Ruling C amendment);
the bless mechanism and its policy; the G3-reuses-G1 design; the casting-off
fixture choice (`ten_measure_with_slurs` for the slur-split coverage); the
determinism basis (PathOutline = no fonts; pure-Rust resvg/tiny-skia; Linux
CI and dev) — and the standing consequence: **baselines pin the raster
stack**, so any `Cargo.lock` movement of `resvg`/`tiny-skia`/`png` is a
golden-review event, never a silent re-bless.

## Work packets (subagent dispatch)

Sequential where stated; each packet's brief includes this contract's
matching section verbatim, the blast-radius list, and the prohibitions.

* **W1 — comparator + bless + its unit tests** (`goldens.rs` scaffolding;
  no baselines yet). Sonnet. Exit: comparator tests green, mutations
  verified (§Verification), no other file touched.
* **W2 — the four golden states + determinism doubles** (depends on W1).
  Sonnet. Exit: tests written and value-asserting; baselines generated via
  the bless mechanism but **committed only after user review** (deep-dive
  point 2); mutations verified.
* **W3 — CI step + DECISIONS.md** (after W2's baselines are blessed).
  Sonnet. Exit: the single-step `ci.yml` diff; DECISIONS.md complete.

The coordinator reviews each packet's diff line-by-line, independently
re-runs its tests and mutations, and only then stages it. Baselines go to
the user between W2 and W3.

## Verification

**Mutation-verify every new test.** Assert the anchor text is present before
substituting (a no-match substitution is a no-op mutation indistinguishable
from a passing test); restore by reversing the exact substitution — **never
`git checkout`**. Report each mutation and the test that died. The named
mutations, minimum set:

1. Comparator → compare encoded PNG bytes instead of decoded RGBA: the
   re-encoding unit test must die.
2. Comparator → skip the dimension check: the dimension-mismatch test must
   die.
3. Comparator → suppress artifact writing on mismatch: the
   artifacts-produced test must die.
4. G2 → skip the `insert_note_at` call (render the unedited session): G2
   must die on pixels AND its pitch/beat value assertions must be shown to
   still pass (proving the pixel lock catches what value assertions cannot).
5. G3 → skip the `undo()` call: G3 must die.
6. G4 → substitute `ten_measure_single_staff(0)` for the slurs fixture: G4
   must die (on the system-count value assertion or pixels — report which).
7. Determinism double → perturb the second render (a different
   `px_per_staff_space`, or append a byte to its SVG string before
   rasterizing): the double's equality assertions must die. (An earlier
   draft said "make the second render reuse the first's output" — that
   mutation passes vacuously and proves nothing; corrected at W2 dispatch.)

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` → counts
   unchanged at 212 / 282 / 282.

**Expected churn: three NEW PNG files and nothing else** (four golden states,
but G3 reuses G1's baseline by design). If any existing
golden, digest, count, or gate number moves, stop and report rather than
re-blessing.

CI pins clippy at 1.95.0 and the MSRV at 1.85; `epiphany-editor-gui` is
excluded from the MSRV jobs and checked on pinned stable (`ci.yml:99,109`) —
this tranche keeps that structure untouched.

## Citations

This is product-side work; it adds no requirement labels and should cite no
`req:*` string. If a doc comment nonetheless cites one, read the requirement
first and confirm it says what the sentence claims (the P13-S9 rule). Plan
citations (`PLAN_EDITOR_APP.md` §Ruling C, §5, Fact 1, Fact 7) are the
governing references.

## Do not

* Touch `epiphany-core`, `epiphany-testkit`, any `.tex`, any other crate, or
  any `DECISIONS.md` but the new `epiphany-editor-gui/DECISIONS.md`.
* Promote a conformance gate, move 8/8 or 212/282/282, or re-bless anything
  existing.
* Compare encoded PNG bytes; add `image` or any runtime dependency.
* Commit a baseline the user has not visually reviewed.
* Change the demo binary's behavior, its egui pin, or its rendering path —
  this tranche observes; it does not refactor.
* Restore a mutation with `git checkout`. Reverse the substitution.

## Report

State: the comparator contract and its unit tests; each golden state's value
assertions and file; the G3=G1 equality design; every mutation and the test
that died (including mutation 4's two-part evidence); the baseline images'
human-review record; the exact `ci.yml` diff; whether the `png` dev-dep
fallback was needed; actual gate output; confirmation that no existing
golden, digest, or count moved; and anything you chose not to do and why.

## Next: T2 promotion, and what this tranche feeds

Promotion of this harness to a numbered `[9/9]` conformance gate is **T2**,
after the resolver lands (the 8/8 count is frozen until then). The baselines
also become the Ruling-A cross-check for the T4 canvas — as geometry/scene
equivalence plus a bounded visual differential, NOT pixel equality (plan
§Ruling A). T1b remains blocked per the plan; nothing here may anticipate it.