epiphany/spikes/editor-toolkit/DECISIONS.md

# T4 toolkit spike — decisions and findings log

Governed by `spec/CONTRACT_EDITOR_T4_SPIKE.md`. This file records
implementation decisions and named deviations, per round.

## Round 0 — accessibility route + desk survey

**Environment prerequisite, not obvious from the contract:** on this
machine (sway, AT-SPI2 via `at-spi-bus-launcher` + `at-spi2-registryd`),
AT-SPI application registration is gated behind two settings that are
*off* by default even though the bus itself is always up:

```
gsettings set org.gnome.desktop.interface toolkit-accessibility true
gdbus call --session --dest org.a11y.Bus --object-path /org/a11y/bus \
  --method org.freedesktop.DBus.Properties.Set org.a11y.Status \
  ScreenReaderEnabled "<true>"
```

Without both, `Atspi.get_desktop(0)` enumerates **zero** applications even
while a probe process is alive, rendering, and actually connected to the
AT-SPI D-Bus (confirmed separately via `busctl --address
unix:path=$XDG_RUNTIME_DIR/at-spi/bus list`). This is a real environment
absence, not a candidate defect, and any later round run in a fresh
sandbox/session must redo both steps before trusting a `NOT RUN` verdict on
accessibility.

**Verifier substitution.** The contract's Round 0 evidence rule allows "a
small verifier binary using the `atspi` crate, **or an equivalent AT-SPI
client**". `a11y-verifier/verify.py` uses `gi.repository.Atspi` (the
official AT-SPI2 GObject-introspection binding — the same library behind
Orca and Accerciser) instead of the Rust `atspi` crate. This was a
deliberate substitution: the Rust crate's async zbus proxy API would have
had to be learned from source rather than from any working example, and
`pyatspi` was already confirmed reachable on this machine. It is a
standalone process, external to every probe, and performs a real tree walk
from the AT-SPI registry — it satisfies "a real client query of the tree",
not "printing your own struct".

**C1 (egui).** First-party route, the full chain being
`eframe` → `egui-winit` → `accesskit_winit` → `accesskit_unix`: `egui-winit`'s
`accesskit` feature is literally `dep:accesskit_winit`
(`egui-winit-0.35.0/Cargo.toml:55`), on by default through `eframe` in 0.35, and
`accesskit_winit` delegates to the platform crate. So C1 gets the
window-lifecycle handling that C3's bypass would have forfeited. No manual
wiring was needed. `probe-egui` draws one button; readback: **PASS**. See
`round0-evidence/c1-egui-readback.txt`.

**Carry forward — C1's frame node is unnamed.** C1's readback path is
`application:'probe-egui' / frame:'' / button:'EpiphanyProbeButton'`, where C2
and C3 both name their frame. The window title does not reach the AT-SPI frame
node under `eframe` 0.35's default wiring. **Non-disqualifying** — round 0
requires one node with a role *and* a name, and the button carries both — but
it is a real gap: a screen-reader user hears an unnamed window. Round 3
(accessibility semantics) must check it, since window identity is part of
navigation, and it should not be rediscovered there as a surprise.

**C2 (vello + winit).** Manual `accesskit_winit` route, exactly as named by
the contract: `probe-vello` builds the accessibility tree by hand
(`accesskit::TreeUpdate`) and drives it through
`accesskit_winit::Adapter::with_event_loop_proxy`, wired into the same
`winit::application::ApplicationHandler` that owns the vello
`RenderContext`/`Renderer`/`Scene` (the vello render pass is real, not a
stub — it draws a filled rounded rect every frame, following vello's own
`examples/simple` pattern at `linebender/vello@main`). Readback: **PASS**.
See `round0-evidence/c2-vello-readback.txt`.

**C3 (iced) — ROUND-0 RESULT: FAIL. Eliminated at round 0, adjudicated
2026-07-28 by coordinator review; no waiver sought or granted.** The initial
report recorded this as "PASS with a flagged deviation". That adjudication was
wrong and is corrected here. Under pin 14(c) C3's disqualifying set is not
passed; keeping it would require an explicit recorded ruling amendment, which
was declined.

**Dual attribution, because the two failures are different in kind.**

*Candidate limitation — this alone fails the round.* iced 0.14 ships **no
accessibility integration at all**: `accesskit` appears in no iced crate
manifest (verified across every `iced*` crate in the 0.14 tree). And its
**stock runner** exposes to application code neither a
`winit::event_loop::ActiveEventLoop` nor a pre-visibility
`winit::window::Window`; both appear only inside `iced_winit`'s own private
`ApplicationHandler` impl, with `create_window` at `iced_winit-0.14.0/src/lib.rs:350`
inside iced's runner. Every `accesskit_winit::Adapter` constructor requires
both and panics if the window is already visible.
**Scope this to the stock runner, deliberately:** `iced_winit`'s own docs offer
a `conversion` module "for users that decide to implement a custom event loop",
so a hand-built shell carrying a real route remains **conceivable but
unproven** — and it would mean owning the shell. Upstream iced #552 remains
open. "Provably closed" applies to the stock runner, not to iced in principle.

*Probe-design defect — why the first report read PASS.*
`accesskit_unix::Adapter::new()` takes **no window handle**, only handlers, and
registers with AT-SPI from process identity
(`accesskit_unix-0.22.1/src/context.rs`; `app_name()` reads
`std::env::current_exe()`). `probe-iced` therefore registered a **hand-built
static tree**, decoupled from iced's window, focus, and event lifecycle, with
every action discarded — while `view()` happened to label its button
identically, which is what made the transcript read as though iced produced it.
**Deleting iced from the probe would produce the identical readback.** That is
the disqualifying fact: round 0 asks whether the *candidate* exposes a route,
and a process-level side channel answers a different question. That
`accesskit_unix` sits one layer beneath `accesskit_winit` does not make it a
route *for the candidate* — that was the reasoning error, and it is recorded as
a probe defect rather than folded into the candidate's result.

Evidence is preserved rather than rewritten: `round0-evidence/c3-iced-readback.txt`
keeps the verifier's factual `READBACK: PASS` under a `ROUND-0 RESULT: FAIL`
annotation, so the false positive stays visible alongside its adjudication.

One consequence survives the corrected verdict and is worth carrying, because
it would apply to any future hand-built route: bypassing `accesskit_winit`
forfeits that crate's window-lifecycle handling — deactivation on window close,
multi-window disambiguation, focus-driven activation. Any real iced integration
would have to build and maintain that wiring itself rather than inheriting it,
which is a maintenance-surface fact, not merely a round-0 curiosity.

## Round 0 — desk survey

All version/date/MSRV figures were fetched live (crates.io API + GitHub
`Cargo.toml` at the released tag), not from memory or the contract's
2026-07-23 snapshot. See the Round 0 report for the full table.

Fill-rule documentation, quoted verbatim from source (not inferred from
behavior — that is round 1's job):

- **C1 (`lyon_tessellation` 1.0.20, via `lyon_path` 1.0.19):**
  `pub enum FillRule { EvenOdd, NonZero }`, with
  `DEFAULT_FILL_RULE: FillRule = FillRule::EvenOdd` and an explicit
  `is_in(winding_number)` implementation for both.
- **C2 (`peniko` 0.6.1, vello's fill-style type):** `pub enum Fill { NonZero, EvenOdd }`,
  each with a full doc comment ("All regions where the winding number of
  the path is not zero will be filled" / "... is odd will be filled").
- **C3 (`iced_graphics` 0.14.0, `geometry::fill`):**
  `pub enum Rule { NonZero, EvenOdd }`, doc pointing at the SVG
  `fill-rule` spec, default `NonZero`.

All three document both rules explicitly. No candidate is eliminated on
this desk-survey item; round 1 is where it is actually tested.

## Round 1 — the precommitted oracle: SUPERSEDED FIRST PASS

> **SUPERSEDED DISCOVERY — NEVER COMMITTED.** This section records the
> four-glyph oracle built against the pre-Revision-6 contract, kept because its
> two findings are what *caused* the amendment. It was never committed and is
> not the oracle any candidate renders against; **the authoritative account is
> the Revision 6 amendment section below** (five glyphs, two check classes,
> explicit status model). In particular, `fClef`'s `background_satisfied =
> false` below is the superseded encoding — under Revision 6 `fClef` is a
> *satisfied* disjoint-component result — and every "committed" in this section
> describes an intent that this pass never reached.

**This is the oracle only — no candidate has rendered against it yet.**
`round1-oracle/` (new spike-workspace member) derives, for `gClef`, `fClef`,
`timeSig8`, `accidentalFlat` from `BravuraGlyphCatalog::render_data`: a
pinned staff-space -> device-pixel transform, Bezier-flattened outlines
(recursive de Casteljau, 0.0005 staff-space flatness tolerance), an even-odd
/ nonzero point-in-path classifier, and a grid search (0.01 staff-space
step) that derives >=3 ink and >=3 bounded-hole background sample points per
glyph, each with >=8 device-px clearance from any outline edge, entirely
programmatically — no coordinate here was chosen by eye. Output:
`round1-oracle/oracle.json` (committed, machine-readable) and
`round1-oracle/ORACLE_SUMMARY.md` (human-readable). **No rendering,
tessellation, or windowing crate is a dependency of this crate** — see its
Cargo.toml and module doc comment.

**Transform (pinned):** `device = (staff.x * scale + tx, ty - staff.y *
scale)`, `scale = 100` device px per staff space, `tx`/`ty` center each
glyph's own flattened bounding box in the pin-4 1920x1080 target — one
uniform rule applied identically to all four glyphs, not a per-glyph fudge.

**Subpath counts.** All four match the contract's recorded starting point
exactly: `gClef` 4, `fClef` 3, `timeSig8` 3, `accidentalFlat` 2 (asserted in
`subpath_counts_match_the_recorded_starting_point`).

**Finding — `fClef` has no bounded hole at all.** Its three subpaths (the
solid clef bowl, area 2.534, plus two disjoint dot subpaths, areas 0.153 and
0.148) are not nested — the search finds **zero** grid hits inside the outer
contour and outside the even-odd fill, at both the main search's resolution
and an independent finer corroboration (0.005 staff-space step, no
clearance floor at all;
`finding_corroboration::fclef_has_no_bounded_hole_at_any_resolution_or_clearance`).
Per Round 1's hole-check clause ("asserted by the derivation, not assumed"), no fallback/relaxed point was substituted:
`fClef`'s oracle carries 3 ink points and **zero** background points, and
`background_satisfied = false` is recorded in `oracle.json` alongside the
diagnostic. The other three glyphs each got 3 ink + 3 background points with
no relaxation needed (thousands of qualifying grid candidates for each).

**Finding — even-odd and nonzero agree on every hole point found.** Mutation
(b) (flip even-odd to nonzero on the selected hole points) was run for
`gClef`, `timeSig8`, `accidentalFlat`'s hole points and **none reclassify**:
Bravura's outer contour and its hole wind in *opposite* directions (the
well-formed-font convention), so nonzero winding cancels to 0 at exactly the
points where the even-odd crossing count is 2 — both rules correctly exclude
the hole. This is real information about the font data (recorded, not
smoothed over), and it means the literal "flip the rule" mutation does not,
for this data, demonstrate that fill-*rule* choice is load-bearing. A
supplementary mutation
(`mutation_b_supplement_hole_points_reclassify_under_naive_outer_only_fill`)
demonstrates the property the check actually needed — that respecting inner
subpaths at all is load-bearing — by showing every selected hole point *is*
inside a naive outer-contour-only fill (what a renderer ignoring holes
entirely would wrongly paint as ink) while being outside the real
whole-outline fill.

Full mutation evidence (a/b/b-supplement/c) is in
`round1-oracle/src/lib.rs`'s `tests` and `finding_corroboration` modules, run
via `cargo test -p round1-oracle -- --nocapture`.

## Round 1 — Revision 6 amendment (five glyphs, two check classes, status model)

**Both findings above changed the contract, not just this oracle.**
`fClef` having no bounded hole and criterion 1's fill-*rule* framing being
moot on Bravura's correctly (oppositely) wound contours were reported as
findings against the pre-Revision-6 contract; the coordinator's response was
to amend `spec/CONTRACT_EDITOR_T4_SPIKE.md` to Revision 6 rather than treat
`fClef` as a shortfall. Round 1 is now **five glyphs in two check classes**,
and this oracle is amended to match (uncommitted diff on top of the original
oracle; the mechanics below are unchanged — same flattening, same
point-in-path classifier, same transform, same clearance floor — only the
requirement model and the glyph set changed):

- **Bounded-hole check** (unchanged mechanics): `gClef`, `timeSig8`,
  `accidentalFlat`, and now **`noteheadHalf`** (new: two subpaths, measured
  `ring_signed_areas = [0.903, -0.368]` — the authoritative figure, now also
  what the contract records; an earlier `[0.902, -0.367]` came from a coarser
  fixed-step flattening). Still >=3 ink + >=3 background points per glyph, every
  background point inside a bounded hole.
- **Disjoint-component check** (new): `fClef` alone, no longer folded into
  the bounded-hole class it never actually belonged to. It carries **no
  background requirement** — that is its design (bowl plus two solid,
  disjoint dots) — and instead requires >=1 ink point inside **each** of its
  three filled subpaths, each point tagged with `subpath_index` so the
  oracle proves coverage of every component rather than three ink points
  that could all land in the bowl. Verified two ways: a finer (0.005
  staff-space step) grid corroboration (renamed
  `fclef_has_zero_bounded_hole_grid_hits_at_a_finer_0_005_grid`, since the
  old name overclaimed "any resolution" for what was actually one grid) and
  a genuinely resolution-independent topological check,
  `subpaths_are_mutually_non_nested` /
  `fclef_subpaths_are_topologically_non_nested`, which asserts no subpath's
  vertices lie inside another subpath — a property of the flattened polygon
  itself, not of any sampling step, and what actually justifies the
  stronger claim.

**Status model.** `GlyphOracle` now carries an explicit `Requirement` enum
(`BoundedHole` / `DisjointComponents`), per-requirement booleans
(`background_required`/`background_satisfied`,
`subpath_coverage_required`/`subpath_coverage_satisfied`), and one overall
`satisfied: bool` — the field to read. `fClef` is `satisfied = true` with
`background_required = false` and zero background points; a bounded-hole
glyph that failed to find enough background points would be
`satisfied = false`. The two are no longer distinguishable only by an absent
field, which was the defect the amendment closes.

**Fill-rule equivalence, now asserted, not merely reported.** The original
oracle's `mutation_b_...` test printed `reclassifies_under_nonzero=false` for
every hole point without asserting on it. `derive_bounded_hole_oracle` now
asserts `!ev.nonzero_filled` for every selected background point at
derivation time (fails loudly if the opposite-winding assumption is ever
false for a glyph's real data), and
`mutation_b_nonzero_rule_equivalence_on_hole_points_is_asserted` asserts the
same independently at the test level. `ring_signed_areas` — the measured
signed area of every subpath, in ring order — is now recorded on every
glyph's oracle output (`oracle.json` and `ORACLE_SUMMARY.md`), not just
observed in this log: `gClef [8.702, -0.691, -1.803, -0.509]`, `timeSig8
[2.674, -0.435, -0.515]`, `accidentalFlat [1.040, -0.257]`, `noteheadHalf
[0.903, -0.368]`, `fClef [2.534, 0.153, 0.148]` — all within measurement
tolerance of the contract's recorded values.

**New kill test.** `mutation_d_largest_contour_only_fill_misses_the_dot_points`
is the disjoint-component analogue of the outer-contour-only mutation kept
from the original oracle: it asserts that filling only `fClef`'s largest
subpath (the bowl) fails to contain either dot's ink point — the literal
"tessellator keeps only the largest contour" scenario Round 1 names as the
reason this check exists. The original outer-contour-only mutation
(`mutation_b_supplement_...`) is unchanged and still runs, now over all four
bounded-hole glyphs including `noteheadHalf`.

**Citations.** Every `pin 13 item N` citation in `round1-oracle/src/lib.rs`,
`src/main.rs`, `ORACLE_SUMMARY.md`, and this file has been replaced with a
direct citation to the Round 1 clause's own wording — pin 13 has no numbered
items in Revision 6 (or any prior revision), so those citations pointed at
nothing.

`oracle.json` and `ORACLE_SUMMARY.md` are regenerated from the amended code
(`cargo run -p round1-oracle` from `spikes/editor-toolkit/round1-oracle/`).