epiphany/spec/CONTRACT_EDITOR_T2_SELECTION.md

Contract: Editor T2 — selection v2, the golden gate, and copy/paste

Repo root /home/jeans/Repos/active/epiphany. The plan is spec/PLAN_EDITOR_APP.md (T2 ladder entry; Ruling E for W4). T1a landed at 6be14d2; the Push-4b resolver freeze is over, so epiphany-core is no longer off-limits — but nothing in T2 needs it, and touching it remains forbidden here (tranche 3b may claim it; coordinate through the plan, not by collision). Requirement counts stay 212 / 282 / 282; no .tex moves.

Execution model as T1a: Sonnet subagents per work packet, file-scoped briefs, coordinator line-level review with independent mutation re-runs, user deep-dives at contract sign-off, any golden/baseline change, and the final report. Mutation discipline throughout: anchor-assert before substituting, restore by reversing, never git checkout.

Work packets

Dependency order: W1 → W2, W1 + Ruling-E grant → W4. W3 is independent and runs parallel to W1.

W1 — selection v2 in epiphany-editor-core (dispatchable now)

Blast radius: crates/epiphany-editor-core/** only.

• Option<Selection> becomes a selection set with an anchor: members in paint order, one member the anchor (the reference point for single-target intents and future paste placement). Public surface (names indicative, the crate's idiom wins): selections() -> &[Selection], anchor() -> Option<&Selection>, click(point) = replace-with-single (today's behavior), toggle_at(point) = add/remove a member (anchor = last added), select_within(rect) = the hit-test within(rect) result as the set (anchor = first in paint order), clear_selection().
• Existing single-target intents retarget to the anchor (alter, move, add-chord-note, insert-after, set-duration): behavior with a single selection is byte-identical to today — locked by the existing tests continuing to pass unmodified where they can, and updated mechanically where the accessor changed.
• Batch intents, atomic: delete_selection deletes every member in ONE transaction (all-or-nothing under the commit gate — a member whose delete is refused rolls back the entire batch); alter_selection(±1) likewise over all pitch members. The transaction path is apply_transaction, already atomic.
• Selection preservation across relayout extends to sets: members whose ids survive stay selected; vanished members drop; the anchor falls to the next surviving member (documented rule, tested).
• Proof-of-life tests (value-asserting) + mutations, minimum: (m1) batch delete of N members leaves the score with exactly the expected survivors — mutation: make the batch loop skip the last member → test dies on the survivor count; (m2) atomicity: a range containing one refusal-worthy member (e.g., a tuplet member whose DeleteEvent refuses NotInTuplet) rolls back the whole batch, score byte-identical to before — mutation: drop the transaction wrapper (apply members individually) → test dies; (m3) anchor-fallback rule — mutation: make the anchor fall to a dropped member → test dies; (m4) select_within paint order — mutation: reverse the order → test dies.

W2 — GUI rubber-band select (after W1 review)

Blast radius: crates/epiphany-editor-gui/src/main.rs (+ goldens.rs only if a compile fix is needed — no golden pixel may change; the score raster is untouched by selection, which is egui-overlay-side).

• Drag on the score view → world-space rect via ViewMap → W1's select_within; plain click keeps today's behavior; Ctrl/Cmd-click → toggle_at.
• Overlay draws every member's highlight, the anchor visually distinct; debug panel shows member count + anchor.
• Toolbar/keys unchanged — they now act on anchor (single-target) or the whole set (delete/transpose), matching W1's semantics.
• The T1a goldens must pass unchanged — that is this packet's regression gate, stated in its brief.

W3 — the [9/9] golden conformance gate (dispatchable now, parallel to W1)

Blast radius: crates/epiphany-testkit/** (Cargo.toml + the conformance_suite example + CONFORMANCE.md at repo root), .github/workflows/ci.yml (the conformance job's invocation only), Cargo.lock.

• The MSRV constraint decides the design (probed): the conformance CI job runs on PINNED_STABLE (ci.yml:146-155), but the MSRV test job builds testkit's examples with --all-targets, so resvg must never be an unconditional dependency of testkit. Therefore: a golden-gate feature on epiphany-testkit; resvg as an optional regular dependency enabled only by that feature (dev-dependencies cannot be optional); the gate code inside the conformance_suite example behind #[cfg(feature = "golden-gate")]. Without the feature the suite builds and prints exactly today's 8/8 (byte-identical output — MSRV coverage regresses zero); with it, 9/9.
• The gate itself: re-render the three T1a baseline states headlessly (ten_measure_single_staff(0) as opened; the scripted insert re-derived through the session inverses exactly as goldens.rs does; ten_measure_with_slurs(0)), rasterize via resvg, decode the committed baselines from crates/epiphany-editor-gui/goldens/ (path resolved relative to CARGO_MANIFEST_DIR, the cross-crate coupling documented in both DECISIONS files), and compare decoded RGBA (the Ruling-C contract; compare-only — no bless, no artifacts; on failure the gate message points at cargo test -p epiphany-editor-gui goldens for the diagnostic surface).
• ci.yml: the conformance job's suite invocation gains --features golden-gate. Nothing else in the file moves.
• CONFORMANCE.md: documents gate [9], the feature split, and why (the MSRV closure cannot carry the raster stack).
• Verification: demonstrate resvg is absent from the no-feature dependency graph (cargo tree -p epiphany-testkit vs --features golden-gate); mutations: (m5) tamper one decoded pixel before comparison → gate 9 must fail; (m6) point the gate at a nonexistent baselines dir → must fail loudly, not skip silently.
• The count moves 8/8 → 9/9 deliberately (plan T2). All standing documents that pin 8/8 are historical contracts of landed tranches; the new normative number lives in CONFORMANCE.md, and future contracts pin 9/9.

W4 — copy/paste over the fragment projection (blocked on Ruling E's grant)

Blast radius: crates/epiphany-editor-core/** (fragment encode/decode + copy_selection/paste_at/paste_over_selection), crates/epiphany-editor-gui/src/main.rs (clipboard wiring via egui's text-clipboard output — no new dependency).

Contracted in detail only after Ruling E is granted; its brief will carry the ruling verbatim plus: round-trip value tests (copy→paste reproduces the selected values at the destination with fresh ids), the closure fail-closed tests (partial tuplet refuses; boundary tie/slur dropped-and-reported), the untrusted-input cap tests, and paste atomicity mutations.

Gate (every packet, actual output)

The six standard commands. Expected numbers: counts 212/282/282; conformance 8/8 until W3 lands, 9/9 after (each packet's brief states which applies); T1a's three baselines byte-identical throughout (no re-bless of anything existing); cargo test --workspace 0 failed; clippy 0 warnings.

Do not

• Touch epiphany-core, any .tex, or any crate outside the packet's blast radius. Do not re-bless or alter any T1a baseline. Do not add resvg outside W3's optional feature. Do not start W4 before Ruling E is granted.
• Restore a mutation with git checkout.

Report

Per packet, as T1a: files + diffs summary, value assertions, every mutation with its kill evidence, actual gate output, deviations. Coordinator re-runs mutations independently before any landing.