neuwirth
/
epiphany
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
epiphany/crates/epiphany-core
History
Levi Neuwirth 6369d331f1 A transposition moves the authored spelling; recording Propagated is not enough 
Audit finding 2, reproduced and fixed. The Propagated attachment met the letter
of req:opcat:transpose-interval-spelling and none of its purpose.

The repro: a C4 the author deliberately spelled "C", sharpened to C#4. Both
attachments present -- the stale UserChosen and the new Propagated -- and
resolve_spelling returns Authored(UserChosen) with accidentals []. The notehead
draws a C natural for a pitch sounding C#. The accidental vanishes. Default
precedence ranks UserChosen and Imported above Propagated, so the attachment
this operation writes is always outranked exactly when it is needed.

Per the ratified call, authored spellings are MOVED, not left and not
discarded. A spelling moves by its NOMINAL, because the nominal is what carries
the author's enharmonic decision: someone who wrote B#3 rather than C4 chose
the letter B, so a perfect fifth up is F##4, not G. The accidental is then
whatever the transposed pitch requires at that staff position -- the chromatic
component never touches the spelling except through the pitch. Source,
priority, and layer are preserved: a transposed UserChosen spelling is still
the user's choice. Imported moves too; import fidelity is a property of the
file on disk, which a transposition does not touch.

An authored spelling that cannot be written at the transposed position refuses
the whole operation (TranspositionOutOfRange), resolved before anything is
written, like every other refusal. The two application passes are ordered so
that every index-addressed rewrite lands before the propagated upsert can push
and shift the indices.

The Propagated attachment keeps its purpose: it is the record for pitches with
no authored spelling, where the pre-pass would otherwise re-infer.

Three mutations verified. One of them, S2, SURVIVED the first version of the
enharmonic test and exposed it as a false lock: I had spelled a C#4 pitch as
"C#", so the authored nominal coincided with the pitch's own, and re-inferring
from the pitch gave the same answer. The test proved nothing about keeping the
author's choice. Rewritten around B#3-sounding-C4, where moving the nominal
gives F##4 and re-inference gives G, it now fails under S2 as it must.

Gate: fmt clean, clippy 0, 30 targets / 990 passed / 0 failed, docs 0 under
-D warnings, conformance 8/8, zero golden churn, catalog rebuilds clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
 		2026-07-09 16:40:06 -04:00
..
src A transposition moves the authored spelling; recording Propagated is not enough 2026-07-09 16:40:06 -04:00
tests Schema major 2 Phase B: snapshot side + honest stamps (data-model fills) 2026-07-07 16:30:07 -04:00
Cargo.toml A B C D F 2026-06-19 12:42:31 -04:00
DECISIONS.md Transposition must refuse an extreme interval, not panic on it 2026-07-09 16:33:42 -04:00
README.md Phase 2: spelling + decomposition pre-passes (Agent H) with F merge gate 2026-06-23 16:33:39 -04:00

README.md

epiphany-core

The Epiphany score graph: the in-memory representation of all musical content in a score, implementing the normative requirements of Chapters 2–5 of the core specification (spec/core_spec.pdf). This is Agent B's crate per spec/QUICKSTART.md — the largest scope — building only on Agent A's epiphany-determinism.

The graph is the canonical truth about the music; layout, serialization, and editing operations are downstream projections and consumers of it. — Chapter 5, Design Principles

What's here

Area Items Spec
Identifiers ReplicaId (+ SYSTEM_DERIVED), OperationId, the typed 128-bit family (EventId, PitchId, VoiceId, …), TypedObjectId, IdentityContext, derive_system_id Ch. 5 §"Identifiers"; Ch. 6 §"Operation Identity"
Time RationalTime (inline-or-promoted), MusicalPosition/MusicalDuration (typed algebra), WallClockTime/WallClockDuration, TimeAnchor/AnchorOffset, EventPosition/EventDuration/ConcreteDuration, TimeSignature/BeatGroup, NotatedComponent/NoteValue Ch. 3
Tempo TempoMap, Tempo, TempoSegment, TempoShape with closed-form musical_to_wallclock/wallclock_to_musical over constant/linear/exponential segments (curve deferred → TempoError) Ch. 3 §"Tempo Map"
Pitch Pitch, ScalePosition, IdentifiedPitch, PitchSpelling, the spelling-attachment subsystem, ReferencePitch, spell (single-pitch simplest spelling), all three equivalences (scale_position_equivalent, enharmonic_equivalent, sounding_equivalent) Ch. 2; Ch. 4 registry ids
Pre-passes derive_annotations: the real spelling pre-pass (Temperley line-of-fifths) + notational-decomposition pre-pass (metric greedy-aligned splitting) as canonical derived annotations (not stored), the eligibility TaxonomyReport, and resolve_spelling (authored-override precedence) Ch. 2 §"Spelling Pre-Pass"; Ch. 3 §"Notational Decomposition"
Events the Event taxonomy (7 variants) and the slotmap-backed EventArena Ch. 5 §"The Event Arena"
Graph Canvas, Region, Staff vs StaffInstance, Voice/VoiceOrigin, Measure, BarlineAlignmentGroup, aleatoric EventOrderingDAG (acyclic by construction), the full cross-cutting registry, the full top-level Score Ch. 5
Indexes ScoreIndexes: the four mandatory indexes (event-time, cross-cutting-reference, measure, spelling-attachment) Ch. 5 §"Indexes"
Invariants check_invariants over all 19 enumerated graph invariants, with a typed InvariantViolation witness per check Ch. 5 §"Graph Invariants"
Generators generators::valid_score/valid_score_rich (positive), violating_score (negative, per invariant), shrink (witness minimizer) QUICKSTART, Agent B hand-off

The identity discipline this crate enforces

  1. Replica + counter, big-endian canonical bytes. Every typed identifier is (replica << 64) | counter; its canonical 16-byte form is to_be_bytes() (8-byte replica, 8-byte counter) and the numeric Ord is the Appendix-D lexicographic byte order. Identity is exact, never tolerant.
  2. A reserved system namespace. ReplicaId::SYSTEM_DERIVED is rejected by ReplicaId::generate/from_entropy; system-derived ids (derive_system_id, derive_promoted_voice_id) live only in that namespace, with counters trunc64(BLAKE3(domain_tag || canonical_inputs)) via epiphany-determinism.
  3. Cross-kind confusion is a compile error. Each object kind has its own newtype; TypedObjectId tags them apart with a discriminant that is part of canonical content.

Graph invariants as property tests

The Chapter 5 invariants are property tests in CI, not runtime assertions in release builds (QUICKSTART). check_invariants returns every violation with a small witness. For each invariant generators provides:

  • a positive generator (valid_score / arbitrary_graph_corpus) whose output passes every check, and
  • a negative generator (violating_score) plus a shrinker (shrink) that minimizes a violating graph to a small witness while retaining only the structure the violation needs.

Generation is deterministic (a vendored SplitMix64), so a failing case reproduces from its seed — no platform entropy enters generation (Appendix D §"Randomness").

Implementation decisions

Per QUICKSTART "Decisions you'll need to make" (full rationale in DECISIONS.md):

  • Replica entropy: getrandom (decision 1). ReplicaId::generate re-draws until the value is not the reserved namespace.
  • Event-arena storage: slotmap (decision 2) plus a hash index for the required O(1) EventId lookup and generation-checked stale handles.
  • Sync only (decision 4): no async anywhere.
  • Current stable Rust (decision 5); MSRV pinned at the workspace's 1.77.
  • RationalTime's promoted arm uses num-rational's BigRational, the spec's reference design (Ch. 3 §"Recommended Implementation").
  • unsafe is forbidden crate-wide (#![forbid(unsafe_code)]).

Hand-off criteria (QUICKSTART, Agent B)

  • Every invariant has both a generator and a shrinker (generators::{valid_score, violating_score, shrink}; one per invariant, property-tested), plus targeted tests for the cross-cutting/anchor/tie sub-rules.
  • The arbitrary-graph corpus runs clean (generators::tests::positive_corpus_runs_clean, 500 graphs), and a breadth corpus (valid_score_rich: concurrent metric/proportional/ aleatoric regions, measures, triplet, tie, spanner, marker, chord symbol, decomposition, tombstones) runs clean over 200 seeds.
  • cargo test -p epiphany-core clean (69 unit + 5 integration).
  • cargo clippy --all-targets -- -D warnings clean; cargo doc clean under RUSTDOCFLAGS="-D warnings".

Depth of the invariant checks

The checks are not surface-level. In particular: invariant 3 computes per-clock event intervals and detects both disorder and overlap; invariant 7 resolves region extents to absolute wall-clock coordinates (wall-clock leaves, plus event/region/measure-start anchors — an event anchor is its region origin plus its region-relative position) and only skips pairs that can't be placed without the deferred tempo map; invariant 9 sweeps every reachable anchor (region extents, meter changes, measure starts, clef/key changes, user breaks, spanners, spelling ranges); invariant 10 resolves all graph references — cross-cutting anchor targets, annotation layers, tuplet parents, graphic objects, and event-internal references (indeterminate alternatives, trajectory event-pitches, graphic-event objects, cue sources); invariant 11 covers every id kind, plus tombstone/live collisions, SYSTEM_DERIVED misuse (including the score's own identity context), and arena index/well-formedness integrity (catching post-get_mut corruption); invariant 17 validates explicit and implicit (pitch-id-ascending) tie pairings, per-class adjacency, and the cross-voice position rule; invariant 18 recomputes the deterministic promoted-voice derivation. Enharmonic equivalence is a sounding notion (octave matters: C4 ≠ C5). Empty pitched events are rejected at the arena boundary and re-checked; IdentityContext::try_new rejects the reserved replica and counters use checked_add so a counter is never silently reused.

Known bounded limitations (deferred dependencies)

  • Tempo conversion integrates the piecewise map in closed form for Constant/Linear/Exponential segments (Chapter 3 §"Conversion"); only TempoShape::Curve is deferred to the open numerical algorithm (TempoError::CurveIntegrationUnsupported). Segment boundaries that cannot be placed without the score graph, and malformed segment sequences, return a TempoError, never a wrong answer. The inverse round-trips ordinary rhythms via a documented continued-fraction approximation (DECISIONS P11-7).
  • Region time-overlap (invariant 7) resolves extents to absolute wall-clock, now including musical event positions placed through the region's effective tempo map (its local_tempo_map, else the score map). Extents that still cannot be placed (no tempo defined, or a deferred curve) are skipped rather than rejected. Sound (no false positives), incomplete (DECISIONS P11-4).
  • System-promoted voice derivation (invariant 18) retains the winning and losing operation ids on VoiceOrigin::SystemPromoted; the checker recomputes the exact four-input derivation used by epiphany-ops.
  • The Chapter 4 tuning catalog — PitchSpace/TuningSystem/ AccidentalRegistry definitions, the built-in catalog, the hierarchical resolver, and the position→frequency resolution function — is not an Agent B deliverable (the QUICKSTART lists those as referenced-by-id). This crate models the identifiers and the score-level ScoreTuningContext; Pitch::sounding_equivalent takes a caller-supplied frequency resolver. See DECISIONS P11-5.

Scope boundaries

The full Chapter 5 top-level Score shape is modeled (metadata, instruments, staff groups, parts, tuning context, tempo map, analysis layers, views) along with the complete CrossCuttingRegistry (slurs, ties, beams, tuplets, spanners, markers, repeats, analytical annotations, comments, graphic gestures, lyrics, chord symbols). The reference- and identity-bearing fields are modeled in depth; deeper bodies (tuning resolution, tempo-curve integration, part layout, view recipes, glyph/engraving detail) are Chapters 3/4/7 and later companions.

Engraving-display detail (StemConfiguration, ClefChange, KeySignatureChange, articulations, dynamics, line styles, spanner/marker visual kinds) is introduced informally here and fully defined in Chapter 7 — it belongs to Agent E (epiphany-layout-ir), and this crate carries minimal, clearly-marked placeholders for it. Operation envelopes, stamps (HLC), causal contexts, the canonical reduction, tombstone tracking, and conflict records are Chapter 6 / Agent C (epiphany-ops); epiphany-core defines only the OperationId they hang off and the tombstone-aware invariants.

Ambiguities discovered while building are not resolved in code — they are batched as Pass 11 candidates in DECISIONS.md (QUICKSTART, Process notes).