Levi Neuwirth
86635e43e1
ENGRAVER_VERSION 11 -> 12. The inter-staff solve now closes a slack pair as well
as opening a crowded one, realizing the InterStaffGap band's declared height
exactly. SYSTEM_STAFF_PITCH is demoted from a floor to an initial arrangement the
solve fully renegotiates. This is what vertical_density_penalty was reporting: an
un-pressured multi-staff system sat at 0.739, honest sprawl against the declared
gap, because the axis is symmetric and the solve only ever expanded.
The band's height had no agreed meaning, so pin it: it is an INK CLEARANCE -- the
separation between the two staves' outermost content, exactly the unit
req:qmc:vertical measures. preferred 2.0 -> 5.0, min 1.0 -> 2.0. The old 2.0 was
a placeholder reconciled with nothing: neither the 8.0 staff-box gap the fixed
pitch of 12 produces, nor the ~6.4 ink clearance it leaves for plain content.
Realizing it would have crushed a relaxed system to a pitch of ~7.6. At 5.0 plain
ledgered content settles near a pitch of 10.6.
Making the solve two-sided immediately exposed a CASCADE DEFECT latent since v11.
The recurrence subtracted the upper staff's shift from the measured gap and then
added it back through the accumulator, so every pair below the first was
over-separated by exactly the shift above it. Both staves move; the relation is
shift_lower = shift_upper + target - (upper_lo - lower_hi), the UNSHIFTED gap.
three_staff_close_content's lower pair realized 21.06 against a declared 4.0. It
was invisible on two-staff fixtures (shift_upper = 0) and invisible to
inter_staff_shifts_cascade_down_three_staves, which asserted only s2 > s1 -- true
under both the correct and the double-counting recurrence.
What caught it was the metric measuring realized clearance back from the BAKED
output instead of the solve's own extents. Reading back solver intent would have
reported 0 and shipped the over-separation again. That design choice was made one
commit earlier for exactly this reason; the catalog rationale now recommends it to
any conforming implementation.
Once the solve realizes each declared clearance exactly, every inter-staff unit is
0 on a healthy solve -- the axis becomes a solver self-check, and its MEAN can no
longer distinguish "measured every realization" from "measured one". So
vertical_raw is split into vertical_units and the regressions assert the unit SET.
Four mutations verified: the double-counting recurrence, expand-only, the
glyph-members band filter, and first-system-only measurement each fail a named test.
No normative change, no version move: QMC formula, units, anchors, thresholds all
untouched; only its non-normative rationale is refreshed. Churn is the two
multi-staff engrave goldens: two_staff grew by exactly 3.0 (the target change, no
cascade); three_staff SHRANK by 9.06 -- the same +3 per pair, less the 17.06 of
over-separation the defect was adding. Single-staff and every stub golden are
byte-stable.
The 5.0 was the user's call. 4.0 ("one staff height") was chosen first and
withdrawn once its true consequence -- pitch 9.57, not the 11.04 an arithmetic slip
of mine had projected -- was measured rather than inferred. The slip: deriving
plain-content ink clearance from an aggregate metric by assuming two contributing
units when it had three.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
||
|---|---|---|
| .. | ||
| src | ||
| Cargo.toml | ||
| DECISIONS.md | ||
| README.md | ||
README.md
epiphany-layout-ir
The Epiphany layout intermediate representation and constraint-solver
interface, implementing the normative requirements of Chapter 7 ("Layout
Intermediate Representation") and the interface of Chapter 9
("Constraint-Solver Interface") of the core specification
(spec/core_spec.pdf). This is Agent E's crate per spec/QUICKSTART.md — it
lands last among the implementation crates, building on Agent A's
epiphany-determinism and Agent B's epiphany-core (and on Agent C's
OperationKindTag for the edit-barrier types — see DECISIONS.md).
The IR sits between the score graph and two downstream consumers: the constraint solver, which resolves spacing and positioning, and the renderer, which produces final visual output. — Chapter 7
The score graph is the canonical truth about the music; this crate is a downstream projection of it. The transformation is a pipeline of four stages, each with its own type and a deterministic, provenance-preserving contract for the next.
What's here
| Area | Items | Spec |
|---|---|---|
| Stage 1 — logical | LogicalLayoutIR, LayoutRegion, composite LayoutObject, overrides/cross-region objects, to_logical |
Ch. 7 §"LogicalLayoutIR" |
| Stage 2 — constrained | ConstrainedLayoutIR, SpringSlot, LayoutConstraint, GlyphObject, to_constrained |
Ch. 7 §"ConstrainedLayoutIR" |
| Stage 3 — resolved | ResolvedLayoutIR, pages/systems/staves/measures, ResolvedGlyph |
Ch. 7 §"ResolvedLayoutIR" |
| Stage 4 — render (interface only) | RenderIR, RenderPrimitive, RenderIRProducer, to_render |
Ch. 7 §"RenderIR" |
| Time axis | canonical TimeAxisModel plus dynamic TimeAxis, including registered payload preservation |
Ch. 7 §"Layout Regions" |
| Provenance | Provenance, LayoutObjectId, SynthesisKind, stable_layout_id (a pure function of the source — stable across relayouts) |
Ch. 7 §"Provenance" |
| Engraving decisions | EngravingDecision/EngravingDecisionId/EngravingDecisionKind, DecisionSource |
Ch. 7 §"Engraving Decisions" |
| Vertical bands | VerticalBand/VerticalBandId/VerticalBandKind |
Ch. 7 §"Vertical Bands" |
| Incremental cache | LayoutCache, DependencyIndex, granular stage caches and invalidation |
Ch. 7 §"Incremental Layout and Caching" |
| Glyph catalog | GlyphCatalog (metric-lookup interface) + in-tree BravuraCatalog, GlyphCatalogIdentity, SmuflVersion, FontId, GlyphMetric/GlyphAnchor, BRAVURA_METRICS/BRAVURA_VERSION, metrics_hash_for (MUSCFNTM-tagged) |
Ch. 7 §"Glyph Catalog Interface" / §7.3.2 |
| Edit barriers | EditBarrier, BarrierScope, BarrierCondition, ObjectKind, EditContext (precise scope evaluation), keyed on Agent C's OperationKindTag |
Ch. 8 §"Edit Barriers" |
| Solver interface | ConstraintSolver (solve/solve_incremental, Send + Sync), SolverConfig/SolverBudget, SolverState, InvalidationSet, SolveReport, SolveStatus, SolverTier/SolverVersion, the v0 StubSolver |
Ch. 9 |
| Round-trip | round_trip, RoundTripReport, laid_out_object_ids |
Ch. 7 (v0 acceptance criterion 6) |
The stub solver
Per the QUICKSTART, the v0 constraint solver is a stub: StubSolver returns
SolveStatus::Solved with the input geometry verbatim (each glyph's resolved
position is exactly its constrained baseline), preserves provenance, and reports
all hard constraints satisfied. The real solver — Cassowary or otherwise — comes
later (Chapter 9 specifies the interface, not the algorithm); v0 only needs to
round-trip IR through the solver interface to prove the contracts hold. The one
stub validates the full Chapter 7 §7.3.2 catalog identity and all slot, band,
and geometry cross-references before reporting Solved. Explicit constraints
are rejected because this interface-only solver cannot honestly evaluate them.
The round-trip (v0 acceptance criterion 6)
round_trip runs graph → LogicalLayoutIR → ConstrainedLayoutIR →
stub-solved ResolvedLayoutIR → RenderIR and asserts the contract every stage
must satisfy:
- the stub solver reports
Solvedwith all hard constraints satisfied; - the complete
Provenanceof every object —source,synthesis,dependencies, andstable_id— survives every stage unchanged; - no two objects ever share a
stable_id, so manifestation multiplicity is preserved (a source manifested in two regions stays two layout objects); - the stub solver returns the input geometry verbatim;
- the set of score-graph sources recovered from the
RenderIRis exactly the set laid out — a surjection onto graph identity (one source may back several manifestations, each with its own stable id).
Agent F's testkit drives this same entry point (layout_stub::round_trip) on the
10-measure single-staff hand-off fixture and the rich multi-region generator.
Algorithmic scope
Per the QUICKSTART ("a prototype baseline, not the product"), this crate implements the Chapter 7 IR contracts and interface types, not a production engraving engine. The real spacing and casting-off algorithms, quality-metric computation, constraint solver, and renderer remain later implementations of these interfaces.
Determinism
IR coordinates are single-precision staff spaces (StaffSpace(f32),
Chapter 7 §7.2); the canonical ResolvedLayoutIR output quantizes them to
the 1/1024 grid at serialization time
(ResolvedLayoutIR::canonical_bytes), exactly as Appendix D §"Quantized Layout
Coordinates" prescribes — quantization absorbs all f32 variation below 1/2048
staff space, so the canonical output is independent of the floating-point
environment. The glyph-catalog identity hashes its consulted metrics (advance,
bounding box, named anchors) under the MUSCFNTM domain tag, and the
edit-barrier types carry a canonical encoding with set-valued fields emitted in
canonical byte order (sorted and de-duplicated). See DECISIONS.md.
Tests
cargo test -p epiphany-layout-ir covers each module plus the round-trip on
Agent B's valid_score / valid_score_rich generators. The end-to-end v0
acceptance gate (criterion 6) lives in the testkit.