head_music 20.1.0 → 21.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3714d51858bd368308d14a5f12544e6f4fb9dbecf0f0eacc1ad795c5e4b3d1e
-  data.tar.gz: 99345ffa2b44dfbdc27836b7b7350a38af1665770a74490f52e22bd1a0aa3602
+  metadata.gz: 3adeb7e3fa4f5422977916729f285e9ebb50309409927b25b284dbbb35d2932d
+  data.tar.gz: 78f4b8b6922142b56e185cc23da551576ba3ffd375d51eb6aa34f3382e30530f
 SHA512:
-  metadata.gz: d95aa74479fe498564dc7e1bc5427660b9687e286a31a4b5cbbb1c0a274bebe9413ae18e2176dbbf38c351e4b1517275d5bf8dce590642c88c2301ea83f038b6
-  data.tar.gz: 4446808775faf30ef42dceca7de10248a88d8c8265ab4faa3c11589bd6ddb7dd60ff9c10ce2cb34a68f9e039061bc3633484e01b2002f649bb3f885bd5d7e968
+  metadata.gz: 444f66354a57746f2c9acf747462bf3f2396f76b8b9c7fe16d4c2bc93020bbe178349f437d7135141e587ffb9fef09c57bdf6a9145159b47a88af908960b608b
+  data.tar.gz: 4c38611fa5aea3b2530310dc33644ab29af9c81c523eb37e39fe94298d79c71ee982791e1278c449cd4d91c99623e21f1a2f3c9f4882e648c8b1783f6ff94a7c

data/CHANGELOG.md

@@ -7,6 +7,104 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [21.0.0] - 2026-09-06
+
+The [organizing content](https://github.com/roberthead/head_music/tree/main/user-stories/epics/organizing-content.md) epic's first story. `Content::Composition` was the document, the movement, the timeline, and the credits at once, and its `Voice` was a bare melodic line with no instrument, no staff, and no performer — a shape adequate for two-voice species counterpoint and for almost nothing else. Content is now `Project` → `Flow` → `Part` → `Voice` → `Placement`, and a voice can cross between the staves of its part.
+
+This is a breaking release. `Composition` is removed rather than deprecated, and the serialization schema goes to 4.
+
+**Migrating from 20.1.0**, in the order a consumer will hit them:
+
+1. **`HeadMusic::Content::Composition` is `HeadMusic::Content::Flow`.** The constant is gone, not aliased. `Flow.new` takes the same keyword arguments, and `#add_voice`, `#voices`, `#bars`, `#to_h`, `#to_abc`, `#to_lilypond`, and `#to_musicxml` all behave as they did, so most call sites need only the constant renamed. `#add_voice` now mints a `Part` per voice behind the scenes; every document this gem produced before still renders byte-identically.
+
+2. **`LilyPond.parse` and `ABC.parse` return a `Flow`.** So do `ABC::BookParser#flows` (was `#compositions`) and `LilyPond::FlowBuilder` (was `CompositionBuilder`). These changed return type five days after the LilyPond reader shipped in 20.1.0; they are named individually here because a reader scanning for "Composition" will not otherwise notice that `parse` moved.
+
+3. **Persisted schema-3 documents need one read-and-re-save.** `Flow.from_h` rejects a v3 hash with an error naming `Flow.from_v3_h`, which is retained read-only for this reason and removed in 22.0.0. The previous bumps shipped a key-rename recipe — v2 to v3 was "rename each placement's `pitches` key to `sounds`", doable in SQL against a jsonb column — but v3 to v4 restructures the container, so no equivalent recipe can be written. **20.1.0 is the last version that reads v3 directly.**
+
+4. **`HeadMusic::Content::Staff` is a different class under the same name.** The 20.x `Content::Staff` was dead code, referenced by nothing but its own spec, and has been deleted; the constant is now the instance-layer staff described below. The new one takes only keyword arguments, so `Content::Staff.new(:bass_clef)` raises `ArgumentError` rather than quietly reading the clef as something else — but the readers changed too: `#default_clef` is `#clef` (and answers `nil` where none was authored, rather than falling back to treble), and `#instrument` is `#instruments_staff`, which references the catalog staff instead of an instrument.
+
+5. **`Time::MusicalPosition#beat` is `#count`**, and `FIRST_BEAT` is `FIRST_COUNT`. `Meter` already distinguished the two — 6/8 has two beats and six counts — so a position was misnamed against the gem's own vocabulary.
+
+6. **Grades do not move.** Every guide assesses every voice of the pinned corpus to the fitness it produced before the refactor began, which is asserted rather than assumed. Stored fitness from 20.x remains comparable.
+
+### Added
+
+- **`HeadMusic::Content::Project`, `Flow`, `Part`, and `Player`.** A `Project` is the document: players and flows. A `Flow` is a continuous span of music owning its own timeline — a movement, a song, a cue, an exercise. A `Player` is a chair in the project ("Flute 1", "Piano"); a `Part` is that chair's music within one flow. Pairing them that way is what makes "the flute plays in movements 1 and 3" expressible without a nullable join — there is simply no `Part` for that player in movement 2 — and what makes an instrument change *within* a part honest, since conceptually it is still the same player.
+
+  **Containment is total; context is optional.** A voice is always in a part, always in a flow, so `voice.part.staff_system_at(bar)` never needs a nil check. What is optional is the upward reference: `Flow#project` and `Part#player` may be absent. A flow with no project is how a chunk of music lives outside a document — a cantus firmus, a scale, a parsed snippet — and it renders to ABC, LilyPond, and MusicXML with no project at all. `Project#add_flow` adopts such a flow, minting a player for each part that has none.
+
+- **Voices orthogonal to staves.** A voice belongs to a part and *has* a staff at any given moment, so a piano voice can start in the bass staff and cross into the treble without leaving its part:
+
+  ```ruby
+  left_hand.cross_to(treble_staff, from: 5)
+  left_hand.cross_to(bass_staff, from: 9)
+  left_hand.staff_at(6)   # => the treble staff
+  left_hand.staff_at(9)   # => back to the bass staff
+  ```
+
+  A crossing is one event, not a span: a left hand that rises for four bars and comes back down is two crossings, each authored where it happens, and a single cross-staff note is a crossing and, a bar later, another. There is no note-level special case, and nothing to overlap.
+
+  MusicXML renders the part as one `<score-part>` with `<staves>`, a numbered `<clef>` per staff, `<voice>` per voice separated by `<backup>`, and `<staff>` per note. LilyPond renders a `\new PianoStaff` (or `\new StaffGroup` for a bracket) with one named `\new Staff` per staff and `\change Staff` at the span boundaries. Both elements are omitted for a one-voice, one-staff part, so existing output is unchanged.
+
+- **`HeadMusic::Content::Staff` and `StaffSystem`** — the instance layer. A content staff has a line count, a clef map, and an optional reference to an `Instruments::Staff` for percussion mapping; the catalog class already owns the position-to-instrument mappings, so the instance layer references rather than re-implements it. A `StaffSystem` is an ordered set of staves with a brace, a bracket, or neither; `StaffSystem.grand_staff` and `.single_staff` are the two shapes almost everything uses.
+
+- **`HeadMusic::Time::EventMap`** — an ordered list of `(position, value)` events answering what is in force at a position. Everything that changes partway through a flow is this shape, and it is now written once: meter, tempo, and key signature on `Flow::Timeline`; instrument and staff system on `Part`; clef on `Staff`; staff assignment on `Voice`. Lookup is a binary search over tuples computed at insert. `#change_at` answers whether a change *starts* at a position, as distinct from what is in force there, which is what a writer needs in order to decide whether to print a signature.
+
+- **`HeadMusic::Time::KeySignatureEvent`**, carrying a signature as fifths and, optionally, the interpretation of it. Neither derives the other. A signature underdetermines its interpretation — two sharps is D major, B minor, E dorian, or A mixolydian — and an interpretation does not fix its signature either, because the two legitimately diverge: C dorian written in cantus mollis takes the parallel minor's three flats and naturalizes the sixth.
+
+  Fifths rather than a `KeySignature` because a `KeySignature` cannot be built from a bare signature: `KeySignature.get("3 flats")` raises, so naming three flats means naming an interpretation of it, after which the stored tonic and quality are wrong whenever the interpretation disagrees. Fifths is also exactly what MusicXML stores.
+
+- **`HeadMusic::Rudiment::Key.for_fifths(n)`** — the conventional reading of a signature that carries no interpretation of its own, for the two consumers that cannot proceed without a tonic: LilyPond's `\key`, and the `Diatonic` guideline. Signatures themselves are unbounded, since a theoretical key such as G♯ major counts each double accidental twice and reaches eight; the table stops at ±7, because past that there is no conventional major key to name. So past ±7 a `tonal_context` is required, and `change_key_signature` raises at authoring time rather than leaving every reader that needs a tonic to raise later.
+
+- **`HeadMusic::Content::CantusFirmus::Example#to_flow(rhythmic_value:, meter:)`.** An example was a catalog datum — a pitch list with a mode and a citation — that nothing in the gem turned into music. It now realizes as a standalone flow with one part, no player, and one note per bar. Rhythm and meter are the realization's choice rather than the datum's, so they are parameters.
+
+- **`Project#to_h` / `.from_h` / `#to_json` / `.from_json`**, and `Flow.from_v3_h`. Schema 4 round-trips players, flows, parts, voices, staff assignments, instrument changes, staff systems and their changes, clef changes, tempo and tempo changes, subtick-precise positions, and repeat structure, and round-trips a standalone flow as its own document. A tempo serializes as `{"beat_value", "beats_per_minute"}` rather than as a `"quarter = 72"` string, because `Tempo.get` reads the number by stripping non-digits and would turn 72.5 into 725.
+- **`Flow.new(tempo:)`, `Flow#tempo`, and `Flow#change_tempo`**, alongside the meter and key signature equivalents. A tempo change allocates its bar the way a meter change does, and accepts a `Tempo`, a tempo name, or a `"quarter = 96"` string.
+- **`Flow#remove_meter_change`, `#remove_key_signature_change`, and `#remove_tempo_change`** un-author a change, answering the removed value. 20.x cleared a change by passing `nil` to `change_*`; that now raises an `ArgumentError` naming the remover, rather than reaching a rudiment getter that would raise something unrelated.
+
+- `Flow#position`, `Content::Position#subtick`, `Voice#assign_staff`, `Part#instrument_at` / `#staff_system_at` / `#instruments`, `Player#instruments` / `#primary_instrument` (derived from the parts, so they cannot drift from the instrument changes authored on them).
+
+### Changed
+
+- **Schema version 4.** `Flow#to_h` carries a `timeline` (opening meter and key signature, plus the changes to each) and `parts` (each with its instrument, instrument changes, staff system, and voices). Key and meter changes are no longer serialized per bar; a bar's own state is its repeat structure.
+
+- **`Content::Bar` keeps only what is bar-shaped** — barlines, repeat structure, volta brackets. Its `#key_signature` and `#meter` are now derived reads of the change *authored in that bar*, and the writers `#key_signature=` and `#meter=` are gone; use `Flow#change_key_signature` and `#change_meter`. The bar had been carrying these in parallel with `Time::MeterMap` doing the same job properly and unused by `Content`.
+
+- **`Clef.get(:tenor_clef)` is the C clef on the fourth line**, as in every theory text. It had been an alias of `vocal_tenor_clef`, the octave-down G clef of vocal scores, which won the lookup by appearing first in the catalog; that clef keeps its own name and its `tenor_g_clef` alias. `tenor_c_clef` still names the C clef too.
+- **Meter and key signature changes take a bar number, and reject anything else.** Both are bar-aligned by definition, so `flow.change_meter("2:3", "3/4")` raises rather than rounding into a bar.
+
+- **`Content::Position` wraps a `Time::MusicalPosition`.** It gains a subtick, and is normalized once at construction and then frozen — it is a sort key that `Voice#place` binary-searches over, and a mutable sort key is a wrong-note bug that raises nothing. `#eql?` and `#hash` are defined on the component tuple alongside `#<=>`; the flow deliberately takes no part in comparison, preserving the behavior `Voice#placement_at` has always guarded with. `#values` is removed in favor of `#to_a`, which now has four components. `#code` emits a subtick only when there is one, so the everyday `"bar:count:tick"` form is unchanged.
+
+- **`Notation::RenderPlan#key_value` receives a key signature event** rather than a key signature, because the two formats want different things from it. `MusicXML::KeyMapper.mode` now takes a tonal context and returns `nil` where there is none, and the writer omits `<mode>` rather than inventing a major. LilyPond renders what is printed at the clef: the interpretation where it agrees with the signature, so a D dorian flow still prints `\key d \dorian`, and the signature where they diverge, so cantus mollis prints `\key c \minor`.
+
+- **`Notation::ClefSelector` is demoted to a fallback.** When a staff has an authored clef the writers use it; the selector infers one from a voice's pitch range only for a part whose staves were never authored — an ABC import, a bare counterpoint exercise. The fallback stays in the writers rather than moving onto `Staff`, because it reads a *voice's* range and a staff has no back-reference to one.
+
+- `Time::PPQN` is an alias of `Rudiment::Rhythm::PPQN` rather than a second literal 960.
+
+### Removed
+
+- `HeadMusic::Content::Composition`, and the dead `HeadMusic::Content::Staff` (see migration note 4).
+- `HeadMusic::Time::EventMapSupport`, superseded by `Time::EventMap`.
+- `Time::MusicalPosition#to_total_subticks` and its `#to_i` alias, `TempoMap#normalize_position`, and `TempoMap#meter=` — all of which existed to support the comparator fixed below.
+
+### Fixed
+
+- **`Time::MusicalPosition#normalize!` destroyed the last count of every bar.** `RadixCarry#carry` used `divmod`, which is correct for the 0-indexed tick and subtick and wrong for the 1-indexed count: in 3/4, `1:3:0:0` normalized to the invalid `2:0:0:0`, and so did `1:4:0:0` in 4/4 and `1:6:0:0` in 6/8. A 1-indexed component is now shifted into 0-indexed space and back.
+
+- **`Time::MusicalPosition#<=>` was not a total order across a meter change.** It converted both positions to elapsed subticks through a single stored meter, assuming every prior bar had it, so a position in bar 4 of 4/4 compared *greater* than one in bar 5 of 7/8. Positions now compare their component tuple lexically, which needs no meter at all.
+
+  Both bugs were latent in 20.x only because `Time` was unused by `Content`. They are on the path every note travels now.
+
+- **A `Content::Position` rolled across a meter change kept the origin bar's count unit.** The tick carry ran under the meter of the bar the position started in, so a quarter after `1:4:480` in 4/4 landed in a 6/8 bar spelled `2:1:480`, where the same instant is `2:2:000`; the two compared unequal, so a placement rolled into the bar and one authored there did not merge. A position is now carried again under the destination bar's meter until it lands in a bar it was carried under.
+
+- **MusicXML `<backup>` rewound a whole measure regardless of what the preceding voice wrote.** In a multi-voice part whose earlier voice ended mid-bar, the cursor went negative -- invalid MusicXML, with no error. It now rewinds by the duration actually written. Whole-measure filler rests also carry `<voice>` and `<staff>`, where before a reader stacked them onto voice 1 of staff 1 and left a grand staff's bass staff empty.
+
+- **Every clef the gem knows renders to LilyPond** by its LilyPond name -- alto, tenor, soprano, mezzosoprano, baritone, varbaritone, french, subbass, percussion, and the quoted octave clefs `"treble_8"` and `"treble^8"` -- where an authored clef other than bass had rendered as treble.
+
+- **A part with no voices renders**, in both writers, as a staff of whole-measure rests under its clef, key, and time, so a tacet chair keeps its line in the score. LilyPond had dropped the part; MusicXML had raised `NoMethodError`.
+
+- **A one-staff part holding several voices renders in LilyPond as one staff** with a `\new Voice` per voice in parallel, named for its part, as MusicXML already rendered it. It had rendered as one staff per voice.
+
 ## [20.1.0] - 2026-09-05
 
 The other half of the LilyPond export released in 20.0.0. A document written by the writer, or by hand, now reads back into a composition, so `parse(render(composition))` reproduces the music. Nothing in 20.0.0 changed shape; a consumer upgrades by upgrading.
@@ -731,7 +829,8 @@ note = HeadMusic::Rudiment::Note.get("F#4 dotted-quarter")
 
 For changes in versions prior to 0.28.0, please refer to the git history.
 
-[Unreleased]: https://github.com/roberthead/head_music/compare/v20.1.0...HEAD
+[Unreleased]: https://github.com/roberthead/head_music/compare/v21.0.0...HEAD
+[21.0.0]: https://github.com/roberthead/head_music/compare/v20.1.0...v21.0.0
 [20.1.0]: https://github.com/roberthead/head_music/compare/v20.0.0...v20.1.0
 [20.0.0]: https://github.com/roberthead/head_music/compare/v19.0.0...v20.0.0
 [19.0.0]: https://github.com/roberthead/head_music/compare/v18.0.0...v19.0.0

data/CLAUDE.md

@@ -10,42 +10,18 @@ HeadMusic is a Ruby gem for Western music theory. It provides a comprehensive to
 
 ### Essential Commands
 
-```bash
-# Install dependencies
-bin/setup
-
-# Run tests with coverage
-bundle exec rake
-
-# Run tests without coverage
-bundle exec rspec
-
-# Run a specific test file
-bundle exec rspec spec/head_music/rudiments/pitch_spec.rb
-
-# Run linting
-bundle exec rubocop
-
-# Run all validation checks (tests, linting, security)
-bundle exec rake validate
-
-# Open interactive console with gem loaded
-bin/console
-# or
-bundle exec rake console
+`rake -T` lists the custom tasks. Two distinctions it does not make obvious:
 
-# Generate documentation
-bundle exec rake doc
-
-# Check documentation coverage
-bundle exec rake doc_stats
+```bash
+bundle exec rake     # tests WITH coverage (the default task)
+bundle exec rspec    # tests WITHOUT coverage
 ```
 
 ### Git Etiquette
 
 **IMPORTANT: Do not make a commit unless I explicitly ask you to.** Wait for explicit instruction before running `git commit`.
 
-When composing git commit messages, follow best-practices. However, do not mention yourself (claude) or list yourself as a co-author.
+When composing git commit messages, follow best-practices. Describe the change itself — do not narrate the assistant's process in the message body. Attribution trailers (`Co-Authored-By`, `Claude-Session`) are added when the session's attribution setting asks for them.
 
 This project uses a rebase flow and `main` as the mainline branch.
 
@@ -130,9 +106,7 @@ The codebase follows a domain-driven design with clear module boundaries:
 
 ### Entry Points
 
-- Main file: `lib/head_music.rb`
-- Module loading order is important and defined in the main file
-- Constants like GOLDEN_RATIO are defined at the top level
+Module loading order matters and is defined in `lib/head_music.rb`.
 
 ## Important Implementation Details
 
@@ -186,22 +160,6 @@ This project deliberately deprioritizes formal documentation in favor of clear,
 - Prefer delegation over inheritance
 - Always run `bundle exec rubocop -a` after editing ruby code
 
-## Common Development Tasks
-
-### Adding a New Musical Concept
-
-1. Create the class in the appropriate module
-2. Include `HeadMusic::Named` if it needs internationalization
-3. Add factory method `.get()` if appropriate
-4. Create corresponding spec file
-5. Add translations to locale files if using Named
-
-### Modifying Existing Classes
-
-1. Check for dependent classes that might be affected
-2. Run tests for the specific module: `bundle exec rspec spec/head_music/[module_name]`
-3. Ensure translations are updated if names change
-
 ## Reference Documents
 
 Domain reference materials live in `references/`.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    head_music (20.1.0)
+    head_music (21.0.0)
       activesupport (>= 7.0, < 10)
       humanize (>= 2, < 4)
       i18n (~> 1.8)

data/Rakefile

@@ -67,4 +67,11 @@ namespace :style do
     File.write(path, snapshot.to_yaml)
     puts "Wrote #{snapshot.values.sum(&:size)} strings to #{path}"
   end
+
+  desc "Regenerate the pinned corpus grading (spec/fixtures/style/corpus_fitness.json)"
+  task :snapshot_corpus_fitness do
+    path = File.expand_path("spec/fixtures/style/corpus_fitness.json", __dir__)
+    sh "bundle exec ruby bin/guide_grade_corpus.rb #{path}"
+    puts "Wrote #{path}"
+  end
 end

data/bin/guide_grade_corpus.rb

@@ -4,15 +4,15 @@
 #
 #   bundle exec ruby bin/guide_grade_corpus.rb out.json
 #
-# Written to run UNMODIFIED on both sides of a grading change. At the merge-base
-# `assessable?` does not exist and the harmony guides raise on a solo voice, so
-# the one is asked for conditionally and the other is recorded as a value rather
-# than being allowed to stop the run. Everything else is common to both trees.
+# Written to run on both sides of a grading change: the corpus and the grading
+# live in spec/support/guide_grading.rb, and this script is only the file-writing
+# wrapper around them. `rake style:snapshot_corpus_fitness` writes the pinned
+# snapshot; this script exists for capturing a second one to diff against it.
 #
-# The invariant that sentence protects is that each column is the same
-# measurement made again -- not that the file is never edited. When a change
-# needs a seam this script does not yet have, the edit lands BEFORE both
-# captures and is proven a no-op by diffing a capture from either side of it.
+# The invariant is that each column is the same measurement made again -- not
+# that the file is never edited. When a change needs a seam this script does not
+# yet have, the edit lands BEFORE both captures and is proven a no-op by diffing
+# a capture from either side of it.
 #
 # Loading the fixture exercises means loading spec_helper, which starts
 # SimpleCov and rewrites coverage/.last_run.json. That file is restored on the
@@ -34,91 +34,13 @@ at_exit do
 end
 
 require "head_music"
-require "composition_context"
+require "flow_context"
 require "spec_helper"
 
-LADDER = %w[D4 F4 E4 G4 F4 A4 G4 F4].freeze
-REPEATED = Array.new(8, "E4").freeze
-CANTUS = %w[D4 F4 E4 D4 G4 F4 E4 D4].freeze
+rows = GuideGrading.rows
 
-def composition(key: "D dorian")
-  HeadMusic::Content::Composition.new(name: "corpus", key_signature: key)
-end
-
-def place(voice, pitches)
-  pitches.each_with_index { |pitch, bar| voice.place("#{bar + 1}:1", :whole, pitch) }
-  voice
-end
-
-# A voice alone in its composition: no companion, so the harmony guides have
-# nothing to be set against.
-def solo(pitches)
-  place(composition.add_voice(role: :counterpoint), pitches)
-end
-
-# A counterpoint voice with a companion, which may itself be empty.
-def accompanied(pitches, companion_pitches)
-  comp = composition
-  place(comp.add_voice(role: "Cantus Firmus"), companion_pitches)
-  place(comp.add_voice(role: :counterpoint), pitches)
-end
-
-def corpus
-  entries = []
-  (0..8).each { |n| entries << ["solo-ascending-#{n}", solo(LADDER.first(n))] }
-  (0..8).each { |n| entries << ["solo-repeated-#{n}", solo(REPEATED.first(n))] }
-  [0, 1, 2, 4, 8].each { |n| entries << ["against-empty-#{n}", accompanied(LADDER.first(n), [])] }
-  [0, 1, 2, 4, 8].each { |n| entries << ["against-cantus-#{n}", accompanied(LADDER.first(n), CANTUS)] }
-
-  %w[
-    fux_cantus_firmus_examples clendinning_cantus_firmus_examples
-    schoenberg_cantus_firmus_examples davis_and_lybbert_cantus_firmus_examples
-    fux_cantus_firmus_examples_with_errors fux_first_species_examples
-    clendinning_first_species_examples davis_and_lybbert_first_species_examples
-    doubled_octave_examples
-  ].each do |source|
-    Array(send(source)).each_with_index do |context, index|
-      context.composition.voices.each_with_index do |voice, position|
-        entries << ["#{source}-#{index}-v#{position}", voice]
-      end
-    end
-  end
-  entries
-end
-
-def grade(guide, voice)
-  # Through the guide, not GuideAssessment.new: a composite guide grades its
-  # members separately and refuses that constructor, and the rescue below would
-  # have recorded the refusal as a per-row error while the run still exited 0.
-  # Identical for every leaf guide -- Guides::Base.assess and Configured#assess
-  # are both GuideAssessment.new(self, voice) -- so this edit was made before
-  # either capture was taken and proven a byte-identical no-op on the before
-  # tree.
-  assessment = guide.assess(voice)
-  items = assessment.guide_item_assessments
-  {
-    fitness: assessment.fitness.round(12),
-    adherent: assessment.adherent?,
-    message_count: assessment.messages.length,
-    item_count: items.length,
-    assessable: assessment.assessable?,
-    failed_gates: items.select { |item| item.gate? && !item.adherent? }.map { |item| item.guideline.name.split("::").last }.sort
-  }
-rescue => error
-  {fitness: nil, adherent: nil, message_count: nil, item_count: nil, assessable: nil,
-   failed_gates: [], error: error.class.name}
-end
-
-rows = corpus.flat_map do |label, voice|
-  HeadMusic::Style::Guide::ALL.map do |guide|
-    {
-      corpus: label,
-      notes: voice.notes.length,
-      guide: HeadMusic::Style::Guide.key_for(guide)
-    }.merge(grade(guide, voice))
-  end
-end
-
-File.write(ARGV.fetch(0), JSON.pretty_generate(rows))
-warn "rows=#{rows.length} corpus=#{corpus.length} guides=#{HeadMusic::Style::Guide::ALL.length} " \
+# One row per line: valid JSON, but a third the size of a pretty-printed dump
+# and diffable a row at a time, which is how the snapshot is read.
+File.write(ARGV.fetch(0), "[\n#{rows.map { |row| JSON.generate(row) }.join(",\n")}\n]\n")
+warn "rows=#{rows.length} guides=#{HeadMusic::Style::Guide::ALL.length} " \
      "errors=#{rows.count { |row| row[:error] }}"

data/bin/guide_grade_table.rb

@@ -167,7 +167,7 @@ def composite_members(capture)
 end
 
 # Only assessable rows carry information. Every solo entry and every cantus
-# firmus fixture is a single-voice composition, so its harmony member gates out
+# firmus fixture is a single-voice flow, so its harmony member gates out
 # and the composite reads 0.000 by construction.
 def composite_rows(capture)
   members = composite_members(capture)

data/lib/head_music/analysis/harmonic_interval.rb

@@ -8,7 +8,7 @@ class HeadMusic::Analysis::HarmonicInterval
   def initialize(voice1, voice2, position)
     @voice1 = voice1
     @voice2 = voice2
-    @position = position.is_a?(String) ? HeadMusic::Content::Position.new(voice1.composition, position) : position
+    @position = position.is_a?(String) ? HeadMusic::Content::Position.new(voice1.flow, position) : position
   end
 
   def diatonic_interval

data/lib/head_music/content/bar.rb

@@ -1,28 +1,30 @@
 # A module for musical content
 module HeadMusic::Content; end
 
-# Representation of a bar in a composition
+# Representation of a bar in a flow
 # Encapsulates meter and key signature changes
 # and repeat structure (repeat barlines and volta brackets) as content semantics
 class HeadMusic::Content::Bar
-  attr_reader :composition, :ends_repeat_after_num_plays, :plays_on_passes, :key_signature, :meter
+  attr_reader :flow, :number, :ends_repeat_after_num_plays, :plays_on_passes
   attr_writer :starts_repeat
 
-  def initialize(composition, key_signature: nil, meter: nil)
-    @composition = composition
-    self.key_signature = key_signature
-    self.meter = meter
+  def initialize(flow, number: HeadMusic::Time::MusicalPosition::DEFAULT_FIRST_BAR)
+    @flow = flow
+    @number = number
     @starts_repeat = false
     @ends_repeat_after_num_plays = nil
     @plays_on_passes = nil
   end
 
-  def key_signature=(value)
-    @key_signature = value ? HeadMusic::Rudiment::KeySignature.get(value) : nil
+  # The key signature and meter a bar reports are the changes authored here,
+  # read from the flow's timeline rather than stored -- nil where nothing was
+  # authored, which is what a writer reads to decide whether to print one.
+  def key_signature
+    flow.timeline.key_signature_change_at(number)&.key_signature
   end
 
-  def meter=(value)
-    @meter = value ? HeadMusic::Rudiment::Meter.get(value) : nil
+  def meter
+    flow.timeline.meter_change_at(number)
   end
 
   def starts_repeat?
@@ -56,12 +58,11 @@ class HeadMusic::Content::Bar
   end
 
   # Sparse serialization: only non-default state, so a default bar is {}.
-  # KeySignature serializes via #name ("F♯ minor") because #to_s ("3 sharps")
-  # cannot be parsed back by KeySignature.get.
+  #
+  # Key and meter changes are not here: they belong to the flow's timeline, and
+  # a bar merely reports the ones authored in it.
   def to_h
     hash = {}
-    hash["key_signature"] = key_signature.name if key_signature
-    hash["meter"] = meter.to_s if meter
     hash["starts_repeat"] = true if starts_repeat?
     hash["ends_repeat_after_num_plays"] = ends_repeat_after_num_plays if ends_repeat?
     hash["plays_on_passes"] = plays_on_passes.dup if plays_on_passes

data/lib/head_music/content/cantus_firmus/example.rb

@@ -52,6 +52,31 @@ module HeadMusic
           pitches.length
         end
 
+        # Realize the example as a standalone flow: one part, no player, one
+        # voice, one note per bar.
+        #
+        # An example is a catalog datum -- a pitch list with a mode and a
+        # citation -- not content, so rhythm and meter are the realization's
+        # choice rather than the datum's, and are parameters.
+        #
+        # The example's tonal center and mode land on the flow's opening key
+        # signature with no loss: the mode is carried by the tonal context, not
+        # inferred from the signature, which is what lets an example in
+        # E phrygian and one in D dorian share a signature of zero without
+        # collapsing into each other.
+        def to_flow(rhythmic_value: :whole, meter: "4/4")
+          flow = HeadMusic::Content::Flow.new(name: to_s, key_signature: key_signature_name, meter: meter)
+          voice = flow.add_voice(role: "cantus firmus")
+          pitches.each_with_index { |pitch, index| voice.place("#{index + 1}:1", rhythmic_value, pitch) }
+          flow
+        end
+
+        # The mode named on its own tonal center, which KeySignature reads as a
+        # collection while retaining the scale type.
+        def key_signature_name
+          [tonal_center, mode].compact.join(" ")
+        end
+
         def to_s
           "#{tonal_center} #{mode} (#{source})"
         end

data/lib/head_music/content/comment.rb

@@ -1,12 +1,12 @@
 # A module for musical content
 module HeadMusic::Content; end
 
-# A comment is a free-text annotation, optionally anchored to a position in a composition.
+# A comment is a free-text annotation, optionally anchored to a position in a flow.
 class HeadMusic::Content::Comment
-  attr_reader :composition, :text, :position
+  attr_reader :flow, :text, :position
 
-  def initialize(composition, text, position = nil)
-    @composition = composition
+  def initialize(flow, text, position = nil)
+    @flow = flow
     @text = text
     ensure_position(position)
   end
@@ -25,12 +25,12 @@ class HeadMusic::Content::Comment
     return if position.nil?
 
     @position = if position.is_a?(HeadMusic::Content::Position)
-      unless position.composition.equal?(composition)
-        raise ArgumentError, "position belongs to a different composition"
+      unless position.flow.equal?(flow)
+        raise ArgumentError, "position belongs to a different flow"
       end
       position
     else
-      HeadMusic::Content::Position.new(composition, position)
+      HeadMusic::Content::Position.new(flow, position)
     end
   end
 end

data/lib/head_music/content/flow/deserializer.rb

@@ -0,0 +1,98 @@
+class HeadMusic::Content::Flow
+  # What every schema version's reader does the same way: check the version,
+  # build the base flow, and replay placements, repeat flags, and comments
+  # through the public builder API. A subclass names its SCHEMA_VERSION, says
+  # where the opening timeline values live, and walks its own containers.
+  #
+  # Raw values are validated at the boundary by SchemaValues, so corrupted
+  # input raises ArgumentError with path context instead of silently
+  # deserializing wrong.
+  class Deserializer
+    def initialize(hash)
+      raise ArgumentError, "expected a Hash, got #{hash.class}" unless hash.is_a?(Hash)
+
+      @hash = hash.deep_transform_keys(&:to_s)
+      validate_schema_version
+    end
+
+    def flow
+      @flow ||= build_base_flow.tap { |flow| build(flow) }
+    end
+
+    private
+
+    attr_reader :hash
+
+    def values
+      @values ||= SchemaValues.new
+    end
+
+    def validate_schema_version
+      version = hash["schema_version"]
+      return if version.is_a?(Integer) && version == self.class::SCHEMA_VERSION
+
+      raise ArgumentError, unsupported_version_message(version)
+    end
+
+    def unsupported_version_message(version)
+      "unsupported schema_version: #{version.inspect} (supported: #{self.class::SCHEMA_VERSION})"
+    end
+
+    def build_base_flow
+      HeadMusic::Content::Flow.new(
+        name: hash["name"],
+        key_signature: values.key_signature(timeline_hash["key_signature"], timeline_path("key_signature")),
+        meter: values.meter(timeline_hash["meter"], timeline_path("meter")),
+        tempo: values.tempo(timeline_hash["tempo"], timeline_path("tempo")),
+        composer: hash["composer"],
+        origin: hash["origin"]
+      )
+    end
+
+    def bar_hashes
+      @bar_hashes ||= Array(hash["bars"])
+    end
+
+    # A list of bar-keyed changes, each yielded with its validated bar number
+    # and its path for error messages.
+    def each_change(list, base)
+      Array(list).each_with_index do |change, index|
+        yield values.bar_number(change, index, base), change, "#{base}[#{index}]"
+      end
+    end
+
+    def build_placements(voice, voice_hash, voice_path)
+      Array(voice_hash["placements"]).each_with_index do |placement_hash, placement_index|
+        path = "#{voice_path}.placements[#{placement_index}]"
+        placement = voice.place(
+          values.position(placement_hash["position"], path),
+          values.rhythmic_value(placement_hash["rhythmic_value"], path),
+          values.placement_sounds(placement_hash, path)
+        )
+        placement.beam_break_before = placement_hash["beam_break_before"] if placement_hash.key?("beam_break_before")
+        values.placement_syllables(placement_hash, path).each do |syllable|
+          placement.sing(syllable.text, verse: syllable.verse, hyphen_after: syllable.hyphen_after)
+        end
+      end
+    end
+
+    def apply_repeat_flags(flow)
+      each_change(bar_hashes, "bars") do |bar_number, bar_hash, _path|
+        bar = flow.bars(bar_number).last
+        bar.starts_repeat = true if bar_hash["starts_repeat"]
+        ends_repeat = bar_hash["ends_repeat_after_num_plays"]
+        bar.ends_repeat_after_num_plays = ends_repeat if ends_repeat
+        plays_on_passes = bar_hash["plays_on_passes"]
+        bar.plays_on_passes = plays_on_passes if plays_on_passes
+      end
+    end
+
+    def add_comments(flow)
+      Array(hash["comments"]).each_with_index do |comment_hash, index|
+        raw_position = comment_hash["position"]
+        position = values.position(raw_position, "comments[#{index}]") if raw_position
+        flow.add_comment(comment_hash["text"], position)
+      end
+    end
+  end
+end