head_music 21.0.0 → 21.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3adeb7e3fa4f5422977916729f285e9ebb50309409927b25b284dbbb35d2932d
-  data.tar.gz: 78f4b8b6922142b56e185cc23da551576ba3ffd375d51eb6aa34f3382e30530f
+  metadata.gz: eadecb642354dfc4c70cf00303a0c1c27513fdd38b13d8bc81fe9c8e7fd3214b
+  data.tar.gz: b534a1e194b0bd6ba4dae42433e92091812e434ec0fddb03c7617e47147207ab
 SHA512:
-  metadata.gz: 444f66354a57746f2c9acf747462bf3f2396f76b8b9c7fe16d4c2bc93020bbe178349f437d7135141e587ffb9fef09c57bdf6a9145159b47a88af908960b608b
-  data.tar.gz: 4c38611fa5aea3b2530310dc33644ab29af9c81c523eb37e39fe94298d79c71ee982791e1278c449cd4d91c99623e21f1a2f3c9f4882e648c8b1783f6ff94a7c
+  metadata.gz: aa22ebc311f8ebe62590e99f90f0d65d639b250626f9668520cd604e0f2fec4c1ea7af4d9b944a19585c52ea1b941906f12d2910888e0a4005a7f582936547ec
+  data.tar.gz: fde9ba8d894229bc349c861b24a0e56108f2a718526b67465c7b8631c9401a8d243196d4f632d1ebce890726c718b4371d2110fcc4e80eef39747d7ec1e610a1

data/.claude/skills/release/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: release
+description: Prepare and publish a head_music release. Verifies the previous version actually shipped, settles the bump with the user, moves Unreleased into a dated CHANGELOG section, bumps version.rb and Gemfile.lock, runs the suite, writes the release commit, and stops before tagging and publishing. Use when the user asks to release, cut a version, bump the version, or publish the gem.
+---
+
+# Release
+
+The version bump and the release are one transaction. The bump commit is the
+release commit, and a version that is bumped but never tagged and pushed is a
+defect, not an intermediate state. This skill prepares everything, then stops
+before the irreversible step.
+
+## 1. Preflight
+
+Run these before touching anything. Stop and report if any fails.
+
+- On `main`, clean working tree, up to date with `origin/main`.
+- The previous version shipped. Compare `lib/head_music/version.rb` with
+  `gem search -r -a head_music`. If the version file is already ahead of
+  RubyGems and its CHANGELOG section carries a date, a bump was committed but
+  never published. Say so. The fix is usually to fold the new entries into
+  that section and release it, not to bump again.
+- The `## [Unreleased]` section of `CHANGELOG.md` has entries. If it is
+  empty, there is nothing to release.
+- `bundle exec rake` passes with coverage and `bundle exec rubocop` is clean.
+
+## 2. Choose the bump
+
+Read the Unreleased subsections and put the choice to the user. Do not decide
+alone when a Changed or Removed subsection is present. The project's
+convention so far:
+
+- Additive only (Added, and Fixed): minor.
+- Behavior changes with no signature change, such as a grading rule that
+  regrades existing melodies: minor, called out in the release intro.
+- A removed class or method, a serialization schema bump, or a document that
+  needs migration: major. 21.0.0 is the model.
+- Fixes only: patch.
+
+## 3. Prepare
+
+- In `CHANGELOG.md`, rename `## [Unreleased]` to `## [X.Y.Z] - YYYY-MM-DD`
+  with today's date, and insert a fresh empty `## [Unreleased]` above it with
+  blank lines around both headings. Subsections stay in Keep a Changelog
+  order: Added, Changed, Deprecated, Removed, Fixed, Security.
+- For a minor or major release, open the section with a short intro
+  paragraph the way 21.0.0 and 21.1.0 do: what the release is for, and a bold
+  sentence naming the bump and what a consumer must do to upgrade.
+- Set `VERSION` in `lib/head_music/version.rb`.
+- Run `bundle install` so `Gemfile.lock` records the new version.
+- Run `bundle exec rake` and `bundle exec rubocop` again.
+- Show the user the diff: CHANGELOG, version file, lockfile, nothing else.
+
+## 4. Commit and push
+
+Only when the user asks. Subject is `Release X.Y.Z`. Add a body only when the
+number needs explaining, such as why a release is major or which behavior
+changed. Push `main`.
+
+## 5. Tag
+
+Stop here. Do not tag without the user's explicit go in this conversation.
+Pushing the tag starts the publish, and a published version cannot be
+withdrawn.
+
+```bash
+bundle exec rake release:source_control_push
+```
+
+This creates the annotated tag `vX.Y.Z` and pushes it. It does not push the
+gem. The tag push triggers `.github/workflows/release.yml`, which runs the
+suite and linter, builds the gem, creates the GitHub Release, and publishes to
+RubyGems through trusted publishing. Do not run plain `rake release`: its gem
+push would race the workflow's, and one of them would be rejected as a
+re-push.
+
+Prerequisite, once: the workflow must be registered as a trusted publisher at
+rubygems.org/gems/head_music/trusted_publishers, with repository
+`roberthead/head_music` and workflow file `release.yml`.
+
+## 6. Verify
+
+- `gh run watch` on the run that the tag started, or
+  `gh run list --workflow=release.yml --limit 1`. Report its status. Do not
+  assume it passed. The workflow failed on every run before 2026-09-10, first
+  on a denied API key and then on an action version that did not exist.
+- `gem search -r head_music` lists the new version.
+- `gh release view vX.Y.Z` shows the GitHub Release with the gem attached.
+
+If the workflow fails after the tag is pushed, the fallback is
+`bundle exec rake release:rubygem_push`, which needs a RubyGems one-time
+password and so is the user's to run with the `!` prefix.

data/.github/workflows/release.yml

@@ -43,8 +43,10 @@ jobs:
     # short-lived credential, so there is no API key to store or rotate.
     # Requires head_music to have this workflow registered as a trusted
     # publisher at rubygems.org/gems/head_music/trusted_publishers.
+    # The action publishes full version tags only, no v2 alias, so it is
+    # pinned to a release.
     - name: Configure RubyGems credentials
-      uses: rubygems/configure-rubygems-credentials@v2
+      uses: rubygems/configure-rubygems-credentials@v2.1.0
 
     - name: Publish to RubyGems
       run: gem push *.gem

data/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [21.1.0] - 2026-09-10
+
+The [organizing content](https://github.com/roberthead/head_music/tree/main/user-stories/epics/organizing-content.md) epic's second story. 21.0.0 separated the document from the music; this separates the music from what it *is* and from how it is *shown*. A flow may now cite a `Work` — the piece, with its catalog number and its people — while a project credits whoever made *this version* of it, so Bach is credited for the work and Segovia for the arrangement. A `Layout` is a view of a project: which flows, which players, concert or written pitch, under what title. Two layouts over one project — a transposed score and a flute part book — are two documents from one body of music.
+
+**This is a minor release.** Everything below is additive: no public method changes signature or return type, `Flow#composer` is still a `String` or nil, `Flow.new`'s keywords are only extended, every writer's new option defaults to what it did before, and `Flow#to_abc`, `#to_lilypond`, and `#to_musicxml` are byte-identical for every flow that existed in 21.0.0. The serialization schema stays at 4 (see the last entry). The one behavioral change is the contour grading under Changed, which alters no signature but does regrade some melodies. A consumer upgrades by upgrading.
+
+### Added
+
+- **`HeadMusic::Content::Work`, with `Person`, `Credit`, `Credits`, and `Role`.** A work is the catalog identity of a composition — a title, a catalog number, a year, and its people — independent of any one notated version of it. A `Flow` may cite one, or cite none, and flows in one project may cite different works: a sonata is one project whose four flows cite one work, a fake book is one project whose eighty flows cite eighty, and a counterpoint exercise cites none. Putting the identity on the project instead would have made the model lie in exactly the cases this gem is most used for.
+
+  **Credits are constrained by the level they attach to**, so the model cannot record a publisher as having composed the music:
+
+  | Level | Roles |
+  |---|---|
+  | `Work` | composer, songwriter, lyricist, librettist |
+  | `Project` | arranger, transcriber, orchestrator, reconstructor |
+  | `Publication` | author, editor, engraver, publisher |
+
+  `Credits.new(level)` is the single place that constraint is enforced — `credits.add(person, :arranger)` on a work raises `ArgumentError` naming both levels — and `Credit` itself is level-agnostic. `Role` is `Named` and translated like the rest of the gem's vocabulary, but unlike a rudiment getter an unrecognized identifier raises rather than minting a role: the twelve are the whole vocabulary. `Person` is one identity rather than one spelling of a name, requiring a full name, with an optional sort name and independently optional birth and death years; `Work`, `Person`, `Credit`, and `Credits` are all frozen values, so two flows citing the same work hold two equal objects and `project.works` deduplicates them.
+
+- **`Flow#work` and `Flow#source`, and `Project#credits`.** `Flow#composer` now answers the cited work's composer and falls back to the authored string, which is what the ABC `C:` and LilyPond `composer =` readers fill with text like "Trad." or "arr. J. Smith" — not a person, and never minting a work. A work with no composer credit falls through to the string too, so a lyricist-only work still prints the name it was authored with, and `Flow#to_h` writes the derived string, so **every existing document renders exactly as it did**. `origin` stays a plain string: ABC's `O:` is geographic provenance, which nothing at the work level holds. `Project#add_credit(person, role)` records this version's people.
+
+- **`HeadMusic::Content::Publication`**, the edition a flow cites as its `source` — the book, treatise, or score, with its own credits, distinct from the work it publishes. `CantusFirmus::Source` is now a `Publication` carrying a catalog key: `Source.get`, `.all`, `.keys`, `#publication_name`, `#publication_edition`, `#author_names`, `#abbreviation`, and `#notes` are all unchanged, and their specs pass unedited. `Example#to_flow` cites its source on the flow it builds, so the citation is a fact about the music rather than only about the catalog, and a serialized source round-trips through its key back into the catalog entry itself. `author` joins the publication-level roles because these sources are treatises, whose people are authors rather than editors.
+
+- **`HeadMusic::Content::Layout`.** A layout selects flows and players (`nil` means all of them), renders in concert or written pitch, and titles the document with `title_override` — which changes what is displayed without touching `work.title` or `flow.name`. A selected flow that no selected player has a part in is skipped rather than rendered empty: a flute part book has two movements, not a silent third. A layout refuses a flow or player its project does not hold, so a stray selection fails when it is made rather than serializing as an absence, and `add_layout(kind: :score)` answers a `Score`, so every layout reads back as the class it was written as.
+
+  ```ruby
+  score = project.add_score(ensemble_type: :orchestral, concert_pitch: false)
+  book  = project.add_layout(kind: :part, players: [flutist], title_override: "Flute")
+  ```
+
+  Each format renders a document of the shape that format has for a book: `#to_abc` writes a tune book, one numbered `X:` per flow separated by a blank line, which `ABC.parse_book` reads back; `#to_lilypond` writes one document with one `\header` and one `\score` per flow, each headed with its movement's own `piece`, via the new `LilyPond::BookWriter`; and because MusicXML holds one flow per document, `#to_musicxml_documents` answers one string per flow and `#to_musicxml` raises for more than one, naming the plural method. Rendering goes through a realized flow rather than through writer options, so the writers, both render plans, and both preflights know nothing about selection — and an all-flows, all-players, concert-pitch layout of one flow renders byte-identically to that flow's own output, in all three formats.
+
+- **`HeadMusic::Content::Score`,** the layout that shows the players together. `#ordered_players` is a permutation of the layout's players in the ensemble's conventional order, and `#player_groups` splits them into the sections a score brackets. Neither is the score's own knowledge: `Instruments::ScoreOrder` already carried it per ensemble type and now exposes `#position_of(instrument)`, `#section_key_of(instrument)`, and `#group(instruments)`, sharing one section index with `#order` so ordering and grouping cannot disagree. Ties keep authored order, so two clarinets stay first and second, and a chair with an unknown instrument or none at all sorts last under a `nil` section key rather than disappearing. `ensemble_type` must be a `ScoreOrder` key or nil, which is authored order.
+
+- **Transposition to written pitch.** A transposed layout renders each part at the pitch its player reads. The move is spelled rather than counted — the semitones decompose into a diatonic interval plus whole octaves — so a clarinet's sounding D is a written E and never an F♭, and a key signature moves by moving its tonic spelling and keeping its scale type rather than by arithmetic on fifths.
+
+  **Each part gets its own written key**, so a mixed ensemble renders as one document: a transposed score of flute, B♭ clarinet, and horn in F carries three key signatures, and a part that picks up an A clarinet at bar 9 gains a key change there that no other part sees. The written key is derived at render time by `Notation::RenderPlan`, whose `#first_measure_key` and `#measure_key_changes` now take the part; it is a rendering fact, not content, so it reaches no model field and no schema key. MusicXML gains `<transpose>` after `<clef>`, LilyPond a `\transposition` per staff, and ABC writes the written key into `K:`. Concert pitch means sounding pitch for every part, octave transposers included. A written key needing more than seven sharps or flats raises `RenderError` naming the enharmonic to write the part in instead, rather than failing midway through assembly.
+
+- **Writer options, each defaulting to prior behavior**: `transposed:` on `ABC.render`, `LilyPond.render`, and `MusicXML.render`; `work_title:` and `movement_number:` on `MusicXML.render`, which emit `<movement-title>` and `<movement-number>` only when a document names a whole this flow is one movement of; and `arranger:` on `LilyPond.render` and `MusicXML.render`, which emit `arranger = "..."` and `<creator type="arranger">`. A `Layout` fills the last of these from `project.credits`, which is what makes the story's arranger visible on the page; `Flow#to_*` passes none of them, so its output is unchanged. ABC has no arranger field and no book title, so a multi-tune layout's title is not rendered there.
+
+- **Optional document keys**: `"work"` and `"source"` on a flow, `"credits"` and `"layouts"` on a project, all absent-means-none. **The schema stays 4.** The rule, now written into `references/content-schema.md`: a rename or a container restructure bumps the schema version, because an old reader would read such a document *wrongly*; a new optional key does not, because the readers look up the keys they know and never enumerate the hash. A 21.0.0 reader accepts a 21.1.0 document and ignores what it has no home for — and `"composer"` still carries the derived name, so even that loss does not reach the page. Bumping to 5 would only have made 21.0.0 reject documents it reads perfectly well.
+
+### Changed
+
+- **`Style::Guidelines::Contoured` judges arch and valley by the whole line.** An arch is now a melody whose trend directions are exactly ascending then descending, one rise past the reversal threshold and one fall, and a valley is the mirror. Before, an interior climax alone made an arch, so a line that rose a third, plunged a sixth, and climbed back passed arch, valley, and wave at once. Arch, valley, and wave are now mutually exclusive. Neighbor-note motion stays under the threshold, so an arch with a passing dip on the way up, or a 7-1 step at the close, still reads as an arch. **Some melodies previously graded as arch or valley now grade as wave, or as no contour at all**: in the pinned corpus, 47 of the 63 voices that passed `arch_contour_melody` and 23 of the 26 that passed `valley_contour_melody` now fail it. Nearly all of those are published cantus firmi and first-species lines that rise and fall more than once and now read as waves; a few that climb without a real reversal read as ascending only. `ascending`, `descending`, `static`, and `wave` are unchanged, as are the registered contour guides and their gates.
+
 ## [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.

data/Gemfile.lock

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

data/README.md

@@ -194,21 +194,7 @@ bundle exec rake doc
 
 ### Releasing a New Version
 
-1. Update the version number in `lib/head_music/version.rb`
-2. Commit the version change: `git commit -am "Bump version to X.Y.Z"`
-3. Push to main: `git push origin main`
-4. Release the gem:
-
-```bash
-bundle exec rake release
-```
-
-This will:
-- Build the gem
-- Create and push a git tag (e.g., `vX.Y.Z`)
-- Push the gem to RubyGems
-
-The git tag push also triggers a GitHub Actions workflow that creates a GitHub Release with auto-generated release notes.
+The release checklist lives in [`.claude/skills/release/SKILL.md`](.claude/skills/release/SKILL.md). Run `/release` in Claude Code, or follow it by hand. In short: move the Unreleased changelog entries under a dated heading, bump `lib/head_music/version.rb`, refresh `Gemfile.lock`, commit as `Release X.Y.Z`, and then `bundle exec rake release:source_control_push` tags the release. The tag push runs the release workflow, which publishes the gem to RubyGems and creates the GitHub Release.
 
 ## Contributing
 

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

@@ -2,7 +2,6 @@ module HeadMusic
   module Content
     module CantusFirmus
       # Sample cantus firmus examples from various pedagogical sources.
-      # These are traditional melodies used for teaching counterpoint.
       class Example
         EXAMPLES_DATA = YAML.load_file(File.expand_path("examples.yml", __dir__)).freeze
 
@@ -52,20 +51,12 @@ 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)
+          flow.source = source
           voice = flow.add_voice(role: "cantus firmus")
           pitches.each_with_index { |pitch, index| voice.place("#{index + 1}:1", rhythmic_value, pitch) }
           flow

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

@@ -1,12 +1,12 @@
 module HeadMusic
   module Content
     module CantusFirmus
-      # A pedagogical source of cantus firmus examples.
-      # Sources include books and treatises on counterpoint.
-      class Source
+      # A pedagogical source of cantus firmus examples: a Publication with a
+      # catalog key, the same noun any flow may cite.
+      class Source < HeadMusic::Content::Publication
         SOURCES_DATA = YAML.load_file(File.expand_path("sources.yml", __dir__)).freeze
 
-        attr_reader :key, :publication_name, :abbreviation, :publication_edition, :author_names, :notes
+        attr_reader :key
 
         class << self
           def all
@@ -28,8 +28,6 @@ module HeadMusic
 
           private
 
-          # Normalize various source name formats to the YAML key format
-          # e.g., "Fux" -> "fux", "Clendinning & Marvin" -> "clendinning_and_marvin"
           def normalize_key(identifier)
             identifier.to_s
               .downcase
@@ -39,20 +37,35 @@ module HeadMusic
           end
         end
 
+        # The key is assigned before the superclass freezes the object.
         def initialize(key:, data:)
           @key = key.to_sym
-          @publication_name = data["publication_name"]
-          @abbreviation = data["abbreviation"]
-          @publication_edition = data["publication_edition"]
-          @author_names = data["author_names"] || []
-          @notes = data["notes"]&.strip
+          super(
+            title: data["publication_name"],
+            edition: data["publication_edition"],
+            abbreviation: data["abbreviation"],
+            notes: data["notes"]&.strip,
+            credits: author_credits(data["author_names"])
+          )
         end
 
-        def to_s
-          publication_name
+        alias_method :publication_name, :title
+        alias_method :publication_edition, :edition
+        alias_method :author_names, :authors
+
+        def to_h
+          super.merge("key" => key.to_s)
         end
 
         private_class_method :new
+
+        private
+
+        def author_credits(names)
+          Array(names).map do |name|
+            HeadMusic::Content::Credit.new(person: HeadMusic::Content::Person.new(full_name: name), role: :author)
+          end
+        end
       end
     end
   end

data/lib/head_music/content/credit.rb

@@ -0,0 +1,32 @@
+# A module for musical content
+module HeadMusic::Content; end
+
+# One person credited in one role. Level-agnostic: the Credits collection that
+# holds it is what constrains which roles are admissible.
+HeadMusic::Content::Credit = Data.define(:person, :role) do
+  def self.from_h(hash)
+    values = hash.transform_keys(&:to_s)
+    new(person: values["person"], role: values["role"])
+  end
+
+  def initialize(person:, role:)
+    super(person: ensure_person(person), role: HeadMusic::Content::Role.get(role))
+  end
+
+  def to_s
+    "#{person} (#{role})"
+  end
+
+  def to_h
+    {"role" => role.key.to_s, "person" => person.to_h}
+  end
+
+  private
+
+  def ensure_person(person)
+    return person if person.is_a?(HeadMusic::Content::Person)
+    return HeadMusic::Content::Person.from_h(person) if person.is_a?(Hash)
+
+    HeadMusic::Content::Person.new(full_name: person.to_s)
+  end
+end

data/lib/head_music/content/credits.rb

@@ -0,0 +1,76 @@
+# A module for musical content
+module HeadMusic::Content; end
+
+# The credits attaching at one level — work, project, or publication — and the
+# single place the level constraint is enforced.
+class HeadMusic::Content::Credits
+  include Enumerable
+
+  LEVELS = HeadMusic::Content::Role::LEVELS
+
+  def self.from_h(array, level:)
+    new(level, Array(array))
+  end
+
+  attr_reader :level, :credits
+
+  def initialize(level, credits = [])
+    @level = level&.to_sym
+    raise ArgumentError, "unknown credit level: #{level.inspect}" unless LEVELS.include?(@level)
+
+    @credits = Array(credits).map { |credit| ensure_credit(credit) }.freeze
+    freeze
+  end
+
+  def each(&)
+    credits.each(&)
+  end
+
+  def add(person, role)
+    self.class.new(level, credits + [HeadMusic::Content::Credit.new(person: person, role: role)])
+  end
+
+  def for(role)
+    wanted = HeadMusic::Content::Role.get(role)
+    credits.select { |credit| credit.role == wanted }
+  end
+
+  def names(role)
+    self.for(role).map { |credit| credit.person.full_name }
+  end
+
+  def empty?
+    credits.empty?
+  end
+
+  def size
+    credits.size
+  end
+
+  def to_h
+    credits.map(&:to_h)
+  end
+
+  def ==(other)
+    other.is_a?(self.class) && level == other.level && credits == other.credits
+  end
+  alias_method :eql?, :==
+
+  def hash
+    [self.class, level, credits].hash
+  end
+
+  private
+
+  def ensure_credit(credit)
+    credit = HeadMusic::Content::Credit.from_h(credit) if credit.is_a?(Hash)
+    validate_level(credit)
+    credit
+  end
+
+  def validate_level(credit)
+    return if credit.role.level == level
+
+    raise ArgumentError, "#{credit.role.key} is a #{credit.role.level} role, not a #{level} role"
+  end
+end

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

@@ -1,20 +1,16 @@
 class HeadMusic::Content::Flow
-  # Rebuilds a flow from a schema v4 hash.
-  #
-  # The order is the model's own dependency order: the timeline first, because
-  # a position string rolls its counts and ticks over through the meter map;
-  # then parts, with their instrument and staff-system changes, because a
-  # voice's staff assignment names a staff of its part's system; then
-  # placements; then repeat flags, which need their bar allocated; then
-  # comments.
+  # Rebuilds a flow from a schema v4 hash, in dependency order: the timeline
+  # first, because a position string rolls its counts and ticks over through the
+  # meter map; then parts, because a voice's staff assignment names a staff of
+  # its part's system; then placements; then repeat flags, which need their bar
+  # allocated.
   class HashDeserializer < Deserializer
     SCHEMA_VERSION = HeadMusic::Content::Flow::SCHEMA_VERSION
 
     private
 
-    # A v3 document names 20.1.0 rather than merely being rejected, because the
-    # reader that understands it still ships and a caller needs to be told
-    # where to find it.
+    # A v3 document is told where 20.1.0 still reads it, rather than merely
+    # rejected, because that reader still ships.
     def unsupported_version_message(version)
       message = super
       message += "; read it with Flow.from_v3_h, which is retained in 21.x and removed in 22.0.0" if version == 3
@@ -30,12 +26,29 @@ class HeadMusic::Content::Flow
     end
 
     def build(flow)
+      apply_citations(flow)
       apply_timeline_changes(flow)
       build_parts(flow)
       apply_repeat_flags(flow)
       add_comments(flow)
     end
 
+    # Read here rather than on the shared base, so the v3 reader gains nothing.
+    # A document written before these keys existed has neither, and reads.
+    def apply_citations(flow)
+      work = hash["work"]
+      flow.work = HeadMusic::Content::Work.from_h(work) if work
+      source = hash["source"]
+      flow.source = publication_from_h(source) if source
+    end
+
+    # A source written from the cantus firmus catalog carries its key, and
+    # reads back as the catalog entry itself rather than as a copy of its fields.
+    def publication_from_h(source_hash)
+      key = source_hash["key"]
+      (key && HeadMusic::Content::CantusFirmus::Source.get(key)) || HeadMusic::Content::Publication.from_h(source_hash)
+    end
+
     def apply_timeline_changes(flow)
       each_timeline_change("meter_changes") do |bar_number, change, path|
         flow.change_meter(bar_number, values.meter(change["meter"], path))
@@ -91,8 +104,8 @@ class HeadMusic::Content::Flow
       end
     end
 
-    # Assignments are replayed as bare map entries, which is what they are: a
-    # crossing is one event, and the serialized form is the map.
+    # Replayed as bare map entries: a crossing is one event, and the serialized
+    # form is the map.
     def apply_staff_assignments(voice, part, voice_hash)
       each_change(voice_hash["staff_assignments"], "staff_assignments") do |bar_number, assignment, _path|
         staff = part.staff_system_at(bar_number).staves[assignment["staff"].to_i]

data/lib/head_music/content/flow.rb

@@ -2,18 +2,19 @@
 module HeadMusic::Content; end
 
 # A flow is a continuous span of music with its own timeline: a movement, a
-# song, a cue, or a single exercise.
-#
-# A flow may stand alone. Its project is optional, which is what lets a cantus
-# firmus, a scale, or a parsed snippet be content without inventing a noun for
-# it. What is not optional is containment below: every voice is in a part, and
-# every part is in a flow.
+# song, a cue, or a single exercise. Its project is optional, so a flow may
+# stand alone; containment below is not: every voice is in a part, and every
+# part is in a flow.
 class HeadMusic::Content::Flow
   SCHEMA_VERSION = 4
 
-  attr_reader :name, :parts, :composer, :origin, :comments, :timeline
+  attr_reader :name, :parts, :origin, :comments, :timeline
   attr_accessor :project
 
+  # The catalog identity this flow is one notation of, and the publication it
+  # was taken from. Both optional: a parsed snippet cites neither.
+  attr_accessor :work, :source
+
   delegate :meter_at, :key_signature_at, :tempo_at, to: :timeline
   delegate :meter_changes, :key_signature_changes, :tempo_changes, :meter_change_at, :tempo_change_at, to: :timeline
   delegate :remove_meter_change, :remove_key_signature_change, :remove_tempo_change, to: :timeline
@@ -22,8 +23,6 @@ class HeadMusic::Content::Flow
     HashDeserializer.new(hash).flow
   end
 
-  # Read a schema v3 document.
-  #
   # Retained read-only through 21.x so that persisted v3 data can be migrated
   # by reading and re-saving. Removed in 22.0.0.
   def self.from_v3_h(hash)
@@ -34,21 +33,29 @@ class HeadMusic::Content::Flow
     from_h(JSON.parse(json))
   end
 
-  def initialize(name: nil, key_signature: nil, meter: nil, tempo: nil, composer: nil, origin: nil, comments: nil)
+  def initialize(
+    name: nil, key_signature: nil, meter: nil, tempo: nil,
+    composer: nil, origin: nil, comments: nil, work: nil, source: nil
+  )
     ensure_attributes(name, key_signature, meter, tempo)
     @composer = composer
     @origin = origin
+    @work = ensure_work(work)
+    @source = ensure_source(source)
     @parts = []
     @comments = Array(comments).map { |text| HeadMusic::Content::Comment.new(self, text) }
   end
 
-  # The voices of every part, in part order.
+  # The cited work's composer wins over the authored string, which stays as the
+  # fallback for the parsed documents that have a name but no work.
+  def composer
+    work&.composer || @composer
+  end
+
   def voices
     parts.flat_map(&:voices)
   end
 
-  # @param player [HeadMusic::Content::Player, nil] the chair this part fills;
-  #   a part with no player is simply a staff of music
   def add_part(player: nil, instrument: nil, staff_system: nil)
     HeadMusic::Content::Part
       .new(flow: self, player: player, instrument: instrument, staff_system: staff_system)
@@ -66,14 +73,13 @@ class HeadMusic::Content::Flow
     @comments.last
   end
 
-  # A position in this flow, from a "bar:count:tick" code or its components.
   def position(code_or_bar, count = nil, tick = nil, subtick = nil)
     HeadMusic::Content::Position.new(self, code_or_bar, count, tick, subtick)
   end
 
-  # The signature and meter the flow opens in. Both are the timeline's, so a
-  # change at bar 1 is a change like any other rather than a rewrite of the
-  # flow's own attributes.
+  # The opening signature, meter, and tempo are the timeline's, so a change at
+  # bar 1 is a change like any other rather than a rewrite of the flow's own
+  # attributes.
   def key_signature
     timeline.opening_key_signature_event.key_signature
   end
@@ -160,6 +166,8 @@ class HeadMusic::Content::Flow
       "name" => name,
       "composer" => composer&.to_s,
       "origin" => origin&.to_s,
+      "work" => work&.to_h,
+      "source" => source&.to_h,
       "timeline" => timeline_to_h,
       "parts" => parts.map(&:to_h),
       "bars" => bars_to_h,
@@ -195,6 +203,18 @@ class HeadMusic::Content::Flow
     (@bars || []).index { |bar| !bar.nil? }
   end
 
+  def ensure_work(work)
+    return HeadMusic::Content::Work.from_h(work) if work.is_a?(Hash)
+
+    work
+  end
+
+  def ensure_source(source)
+    return HeadMusic::Content::Publication.from_h(source) if source.is_a?(Hash)
+
+    source
+  end
+
   def ensure_attributes(name, key_signature, meter, tempo)
     @name = name || "Composition"
     @timeline = Timeline.new(key_signature: key_signature, meter: meter, tempo: tempo)
@@ -206,10 +226,9 @@ class HeadMusic::Content::Flow
     {"beat_value" => tempo.beat_value.to_s, "beats_per_minute" => tempo.beats_per_minute}
   end
 
-  # Iterates the raw sparse array (not the public #bars slice, which loses the
-  # number offset), pairing each non-default bar with its number. Key and meter
-  # changes are the timeline's now, so a bar serializes its repeat structure
-  # and nothing else.
+  # Iterates the raw sparse array rather than the public #bars slice, which
+  # loses the number offset. Key and meter changes are the timeline's, so a bar
+  # serializes its repeat structure and nothing else.
   def bars_to_h
     (@bars || []).each_with_index.filter_map do |bar, number|
       next if bar.nil?