head_music 15.0.0 → 15.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c29fa7f976d16091512b8bdc9eb8befcb4766c4bb70d387a67991e9b9897a5c
-  data.tar.gz: b43c0fed22c3ed7c79a7a0195847740ba7b3bea608a24921893a329f0c66ba7f
+  metadata.gz: d2446af0205d6b751566da4a2cc132032151d5c9b41732938552d12d3f07d05e
+  data.tar.gz: ed75fb7cea9e3a2ea50543bad21d28d0c66b8996cb5d57b4757aa9ef211eb67b
 SHA512:
-  metadata.gz: 47d395cc1709167182e0810c7383120395e927629a2e5e5076e197bdacfd377445546a842a032fecabd9865f62e878f969fec301535758072b45db229c80e8e4
-  data.tar.gz: '0950f0d5a6a2b830a1733d8d0a7d19eb9fcb87815e25d3e562dc6aa94bc95c16a2d7710ca31890e23d1dcc07fc64247030565741d2edf38da6cb177f7e091fb9'
+  metadata.gz: fda48134cdaea328ddcdc1e2e072ea9c94d7a354e99178428969834cab6db36882667f21f7860ba427561d7a70e40eace071a1d4e9a7228e42c6cb92f2749e01
+  data.tar.gz: d2d1bfd02a1b1101932acd435836006e1deaa6e81102f233b9b339dfb56c01effc94691ce30063334e7c61eafffee214075c516ff0d831395a8c91b861cfffb0

data/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [15.2.0] - 2026-07-16
+
+### Added
+
+- `HeadMusic::Content::Composition#to_h` / `.from_h` — lossless, JSON-safe hash serialization of a composition (schema_version 1). The hash captures name, key signature, meter, composer, origin, voices with roles and ordered placements (tick-precise positions, rhythmic values including ties, exact pitch spellings, rests as `null`), sparse per-bar state (mid-piece key and meter changes, repeat and volta structure), and comments. `from_h` rebuilds through the public builder API and raises `ArgumentError` with path context on malformed input; unknown keys are ignored so the format can evolve additively.
+- `HeadMusic::Content::Composition#to_json` / `.from_json` — thin delegates over `to_h`/`from_h`.
+- `#to_h` on `Content::Voice`, `Content::Placement`, `Content::Bar`, and `Content::Comment`.
+
+**Schema v1 is a compatibility surface**: hashes persisted by downstream apps (e.g. in a jsonb column) must keep loading. Additive optional keys are fine within version 1; any change to existing keys' shape or meaning requires a `schema_version` bump.
+
+### Fixed
+
+- `RhythmicValue.get` now parses tied value strings ("half tied to eighth", including chained ties), so tied durations round-trip through `#to_s`.
+- `Bar#key_signature=` and `Bar#meter=` coerce strings via `KeySignature.get` / `Meter.get`, so `change_meter(4, "6/8")` no longer stores a raw String.
+- `Voice` placement ordering is now stable: notes placed at the same position (chords) keep their insertion order.
+- `Composition#change_key_signature` / `#change_meter` no longer raise for a bar earlier than the first placement (e.g. a pickup bar).
+
+## [15.1.0] - 2026-07-07
+
+### Added
+
+- `HeadMusic::Content::Composition.to_musicxml` for MusicXML export
+- `HeadMusic::Content::Composition.to_abc` for ABC Notation export. ABC can round-trip to and from Composition.
+
 ## [15.0.0] - 2026-07-06
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    head_music (15.0.0)
+    head_music (15.2.0)
       activesupport (>= 7.0, < 10)
       humanize (~> 2.0)
       i18n (~> 1.8)
@@ -220,6 +220,7 @@ DEPENDENCIES
   head_music!
   kramdown
   rake (~> 13.0)
+  rexml (~> 3.4)
   rspec (~> 3.0)
   rspec-its (~> 2.0)
   rubocop

data/head_music.gemspec

@@ -37,6 +37,7 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency "i18n", "~> 1.8"
 
   spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rexml", "~> 3.4"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "rspec-its", "~> 2.0"
   spec.add_development_dependency "bundler-audit", "~> 0.9"

data/lib/head_music/content/bar.rb

@@ -5,19 +5,26 @@ module HeadMusic::Content; end
 # 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
-  attr_accessor :key_signature, :meter
+  attr_reader :composition, :ends_repeat_after_num_plays, :plays_on_passes, :key_signature, :meter
   attr_writer :starts_repeat
 
   def initialize(composition, key_signature: nil, meter: nil)
     @composition = composition
-    @key_signature = HeadMusic::Rudiment::KeySignature.get(key_signature) if key_signature
-    @meter = HeadMusic::Rudiment::Meter.get(meter) if meter
+    self.key_signature = key_signature
+    self.meter = meter
     @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
+  end
+
+  def meter=(value)
+    @meter = value ? HeadMusic::Rudiment::Meter.get(value) : nil
+  end
+
   def starts_repeat?
     @starts_repeat
   end
@@ -48,6 +55,19 @@ class HeadMusic::Content::Bar
     ["Bar", key_signature, meter, repeat_summary].compact.join(" ")
   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.
+  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
+    hash
+  end
+
   private
 
   def valid_ends_repeat_after_num_plays?(value)

data/lib/head_music/content/comment.rb

@@ -15,6 +15,10 @@ class HeadMusic::Content::Comment
     text
   end
 
+  def to_h
+    {"text" => text, "position" => position&.to_s}
+  end
+
   private
 
   def ensure_position(position)

data/lib/head_music/content/composition.rb

@@ -3,8 +3,18 @@ module HeadMusic::Content; end
 
 # A composition is musical content.
 class HeadMusic::Content::Composition
+  SCHEMA_VERSION = 1
+
   attr_reader :name, :key_signature, :meter, :voices, :composer, :origin, :comments
 
+  def self.from_h(hash)
+    HashDeserializer.new(hash).composition
+  end
+
+  def self.from_json(json)
+    from_h(JSON.parse(json))
+  end
+
   def initialize(name: nil, key_signature: nil, meter: nil, composer: nil, origin: nil, comments: nil)
     ensure_attributes(name, key_signature, meter)
     @composer = composer
@@ -35,10 +45,11 @@ class HeadMusic::Content::Composition
 
   def bars(last = latest_bar_number)
     @bars ||= []
-    (earliest_bar_number..last).each do |bar_number|
+    first = [earliest_bar_number, last].min
+    (first..last).each do |bar_number|
       @bars[bar_number] ||= HeadMusic::Content::Bar.new(self)
     end
-    @bars[earliest_bar_number..last]
+    @bars[first..last]
   end
 
   def change_key_signature(bar_number, key_signature)
@@ -50,7 +61,7 @@ class HeadMusic::Content::Composition
   end
 
   def earliest_bar_number
-    [voices.map(&:earliest_bar_number), 1].flatten.min
+    [voices.map(&:earliest_bar_number), first_allocated_bar_number, 1].flatten.compact.min
   end
 
   def latest_bar_number
@@ -69,8 +80,40 @@ class HeadMusic::Content::Composition
     "#{name} — #{voices.count} #{(voices.count == 1) ? "voice" : "voices"}"
   end
 
+  def to_abc(**options)
+    HeadMusic::Notation::ABC.render(self, **options)
+  end
+
+  def to_musicxml
+    HeadMusic::Notation::MusicXML.render(self)
+  end
+
+  def to_h
+    {
+      "schema_version" => SCHEMA_VERSION,
+      "name" => name,
+      "key_signature" => key_signature.name,
+      "meter" => meter.to_s,
+      "composer" => composer&.to_s,
+      "origin" => origin&.to_s,
+      "voices" => voices.map(&:to_h),
+      "bars" => bars_to_h,
+      "comments" => comments.map(&:to_h)
+    }
+  end
+
+  def to_json(*_args)
+    to_h.to_json
+  end
+
   private
 
+  # Bars can be allocated below the voices' earliest bar (e.g. a key or meter
+  # change in a pickup bar), so the earliest bar reflects those allocations too.
+  def first_allocated_bar_number
+    (@bars || []).index { |bar| !bar.nil? }
+  end
+
   def ensure_attributes(name, key_signature, meter)
     @name = name || "Composition"
     @key_signature = HeadMusic::Rudiment::KeySignature.get(key_signature) if key_signature
@@ -86,4 +129,191 @@ class HeadMusic::Content::Composition
   def last_key_signature_change(bar_number)
     bars(bar_number)[earliest_bar_number..bar_number].reverse.detect(&:key_signature)
   end
+
+  # Iterates the raw sparse array (not the public #bars slice, which loses the
+  # number offset), pairing each non-default bar with its number.
+  def bars_to_h
+    (@bars || []).each_with_index.filter_map do |bar, number|
+      next if bar.nil?
+
+      bar_hash = bar.to_h
+      next if bar_hash.empty?
+
+      {"number" => number}.merge(bar_hash)
+    end
+  end
+
+  # Rebuilds a composition from a schema v1 hash by replaying the public
+  # builder API in dependency order: meter and key changes first (position
+  # strings roll counts and ticks over via the meter map), then placements,
+  # then repeat flags (a pickup-bar flag needs its bar allocated), then
+  # comments. Validates values at the boundary so corrupted input raises
+  # ArgumentError with path context instead of silently deserializing wrong.
+  class HashDeserializer
+    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 composition
+      @composition ||= build_base_composition.tap do |composition|
+        apply_bar_changes(composition)
+        build_voices(composition)
+        apply_repeat_flags(composition)
+        add_comments(composition)
+      end
+    end
+
+    private
+
+    attr_reader :hash
+
+    def validate_schema_version
+      version = hash["schema_version"]
+      return if version.is_a?(Integer) && version == SCHEMA_VERSION
+
+      raise ArgumentError, "unsupported schema_version: #{version.inspect} (supported: #{SCHEMA_VERSION})"
+    end
+
+    def build_base_composition
+      HeadMusic::Content::Composition.new(
+        name: hash["name"],
+        key_signature: parsed_key_signature(hash["key_signature"], "key_signature"),
+        meter: parsed_meter(hash["meter"], "meter"),
+        composer: hash["composer"],
+        origin: hash["origin"]
+      )
+    end
+
+    def bar_hashes
+      @bar_hashes ||= Array(hash["bars"])
+    end
+
+    def apply_bar_changes(composition)
+      bar_hashes.each_with_index do |bar_hash, index|
+        number = validated_bar_number(bar_hash, index)
+        path = "bars[#{index}]"
+        key_signature = parsed_key_signature(bar_hash["key_signature"], path)
+        meter = parsed_meter(bar_hash["meter"], path)
+        composition.change_key_signature(number, key_signature) if key_signature
+        composition.change_meter(number, meter) if meter
+      end
+    end
+
+    def build_voices(composition)
+      Array(hash["voices"]).each_with_index do |voice_hash, voice_index|
+        voice = composition.add_voice(role: voice_hash["role"])
+        Array(voice_hash["placements"]).each_with_index do |placement_hash, placement_index|
+          path = "voices[#{voice_index}].placements[#{placement_index}]"
+          position = parsed_position(placement_hash["position"], path)
+          rhythmic_value = parsed_rhythmic_value(placement_hash["rhythmic_value"], path)
+          pitch = parsed_pitch(placement_hash["pitch"], path)
+          voice.place(position, rhythmic_value, pitch)
+        end
+      end
+    end
+
+    def apply_repeat_flags(composition)
+      bar_hashes.each_with_index do |bar_hash, index|
+        next unless repeat_state?(bar_hash)
+
+        bar = composition.bars(validated_bar_number(bar_hash, index)).last
+        bar.starts_repeat = true if bar_hash["starts_repeat"]
+        bar.ends_repeat_after_num_plays = bar_hash["ends_repeat_after_num_plays"] if bar_hash["ends_repeat_after_num_plays"]
+        bar.plays_on_passes = bar_hash["plays_on_passes"] if bar_hash["plays_on_passes"]
+      end
+    end
+
+    def add_comments(composition)
+      Array(hash["comments"]).each_with_index do |comment_hash, index|
+        position = parsed_position(comment_hash["position"], "comments[#{index}]") if comment_hash["position"]
+        composition.add_comment(comment_hash["text"], position)
+      end
+    end
+
+    def repeat_state?(bar_hash)
+      bar_hash["starts_repeat"] || bar_hash["ends_repeat_after_num_plays"] || bar_hash["plays_on_passes"]
+    end
+
+    def validated_bar_number(bar_hash, index)
+      number = bar_hash["number"]
+      unless number.is_a?(Integer) && number >= 0
+        raise ArgumentError, "bars[#{index}]: bar number must be an Integer of at least 0, got #{number.inspect}"
+      end
+      number
+    end
+
+    # Position silently coerces garbage strings to "0:1:000", which would
+    # mislocate content with no error, so the shape is validated up front.
+    # Accepts "bar", "bar:count", or "bar:count:tick" with non-negative parts.
+    def parsed_position(value, path)
+      return nil if value.nil?
+
+      unless value.is_a?(String) && value.match?(/\A\d+(:\d+){0,2}\z/)
+        raise ArgumentError, "#{path}: unknown position #{value.inspect}"
+      end
+      value
+    end
+
+    # KeySignature.get returns a hollow object (nil tonic_spelling) for
+    # garbage rather than nil, so presence of the tonic is the real check.
+    def parsed_key_signature(value, path)
+      return nil if value.nil?
+
+      key_signature = begin
+        HeadMusic::Rudiment::KeySignature.get(value)
+      rescue
+        nil
+      end
+      unless key_signature&.tonic_spelling
+        raise ArgumentError, "#{path}: unknown key signature #{value.inspect}"
+      end
+      key_signature
+    end
+
+    def parsed_meter(value, path)
+      return nil if value.nil?
+
+      meter = begin
+        HeadMusic::Rudiment::Meter.get(value)
+      rescue
+        nil
+      end
+      unless meter&.top_number&.positive? && meter.bottom_number.positive?
+        raise ArgumentError, "#{path}: unknown meter #{value.inspect}"
+      end
+      meter
+    end
+
+    def parsed_rhythmic_value(value, path)
+      rhythmic_value = HeadMusic::Rudiment::RhythmicValue.get(value)
+      unless valid_rhythmic_value?(rhythmic_value)
+        raise ArgumentError, "#{path}: unknown rhythmic value #{value.inspect}"
+      end
+      rhythmic_value
+    end
+
+    # RhythmicValue.get returns a hollow object (nil unit) for garbage rather
+    # than nil, and a tied tail can be hollow while the head parses, so the
+    # whole tie chain is checked.
+    def valid_rhythmic_value?(rhythmic_value)
+      return false unless rhythmic_value.is_a?(HeadMusic::Rudiment::RhythmicValue)
+      return false unless rhythmic_value.unit
+
+      rhythmic_value.tied_value.nil? || valid_rhythmic_value?(rhythmic_value.tied_value)
+    end
+
+    # A nil pitch is a rest; a non-nil string that fails to parse would
+    # otherwise silently deserialize as a rest.
+    def parsed_pitch(value, path)
+      return nil if value.nil?
+
+      pitch = HeadMusic::Rudiment::Pitch.get(value)
+      raise ArgumentError, "#{path}: unknown pitch #{value.inspect}" unless pitch
+
+      pitch
+    end
+  end
 end

data/lib/head_music/content/placement.rb

@@ -38,6 +38,14 @@ class HeadMusic::Content::Placement
     "#{rhythmic_value} #{pitch || "rest"} at #{position}"
   end
 
+  def to_h
+    {
+      "position" => position.to_s,
+      "rhythmic_value" => rhythmic_value.to_s,
+      "pitch" => pitch&.to_s
+    }
+  end
+
   private
 
   def starts_during?(other_placement)

data/lib/head_music/content/voice.rb

@@ -118,17 +118,46 @@ class HeadMusic::Content::Voice
     last_placement ? last_placement.next_position : HeadMusic::Content::Position.new(composition, 1, 1, 0)
   end
 
+  # Returns nil if placements are contiguous, or [expected_position, found_placement]
+  # for the first gap: either the first placement not starting its bar, or the
+  # first pair of consecutive placements where the second doesn't begin where
+  # the first one ends.
+  def first_gap
+    first = placements.first
+    return unless first
+
+    return [bar_start_position(first), first] unless first.position.count == 1 && first.position.tick.zero?
+
+    placements.each_cons(2) do |previous, current|
+      return [previous.next_position, current] unless current.position == previous.next_position
+    end
+    nil
+  end
+
   def to_s
     return pitches_string if role.to_s.strip == ""
 
     [role, pitches_string].join(": ")
   end
 
+  def to_h
+    {
+      "role" => role&.to_s,
+      "placements" => placements.map(&:to_h)
+    }
+  end
+
   private
 
+  def bar_start_position(placement)
+    HeadMusic::Content::Position.new(composition, placement.position.bar_number, 1, 0)
+  end
+
+  # Stable insertion: co-positioned placements (chords) keep their insertion order,
+  # which serialization round-trips depend on.
   def insert_into_placements(placement)
-    @placements << placement
-    @placements = @placements.sort
+    index = @placements.index { |existing| existing > placement } || @placements.length
+    @placements.insert(index, placement)
   end
 
   def pitches_string

data/lib/head_music/notation/abc/duration_writer.rb

@@ -0,0 +1,63 @@
+# Parses and renders ABC notation as HeadMusic::Content compositions
+module HeadMusic::Notation::ABC
+  # Converts a HeadMusic::Rudiment::RhythmicValue back into the ABC note-length
+  # multiplier string relative to the tune's unit note length — the inverse of
+  # DurationResolver.
+  class DurationWriter
+    attr_reader :unit_note_length
+
+    def initialize(unit_note_length)
+      @unit_note_length = Rational(unit_note_length)
+    end
+
+    def multiplier_string(rhythmic_value)
+      fraction = total_fraction(rhythmic_value)
+      validate_fraction!(fraction, rhythmic_value)
+      format_multiplier(fraction / unit_note_length)
+    end
+
+    private
+
+    # RhythmicValue's own value methods return Floats; rebuild the fraction
+    # from integer parts so the multiplier arithmetic stays exact. A tied
+    # chain collapses to one multiplier, round-tripping tokens like "A5".
+    def total_fraction(rhythmic_value)
+      fraction = single_fraction(rhythmic_value)
+      tied_value = rhythmic_value.tied_value
+      fraction += total_fraction(tied_value) if tied_value
+      fraction
+    end
+
+    def single_fraction(rhythmic_value)
+      unit = rhythmic_value.unit
+      dots = rhythmic_value.dots
+      # A value with d dots spans (2^(d+1) - 1) / 2^d of its unit.
+      Rational(unit.numerator, unit.denominator) * Rational((2**(dots + 1)) - 1, 2**dots)
+    end
+
+    def validate_fraction!(fraction, rhythmic_value)
+      max_fraction = DurationResolver::MAX_FRACTION
+      if fraction > max_fraction
+        raise_error("note length exceeds #{max_fraction.to_i} whole notes", rhythmic_value)
+      end
+      return if power_of_two?(fraction.denominator)
+
+      raise_error("note length #{fraction} is not expressible in binary note values", rhythmic_value)
+    end
+
+    def format_multiplier(multiplier)
+      return "" if multiplier == 1
+      return multiplier.numerator.to_s if multiplier.denominator == 1
+
+      "#{multiplier.numerator}/#{multiplier.denominator}"
+    end
+
+    def power_of_two?(integer)
+      (integer & (integer - 1)).zero?
+    end
+
+    def raise_error(message, rhythmic_value)
+      raise HeadMusic::Notation::ABC::RenderError, "#{message}: #{rhythmic_value}"
+    end
+  end
+end

data/lib/head_music/notation/abc/key_mapper.rb

@@ -20,6 +20,51 @@ class HeadMusic::Notation::ABC::KeyMapper
     "loc" => "locrian"
   }.freeze
 
+  # MODE_NAMES_BY_PREFIX is many-to-one, so rendering uses this explicit
+  # inverse map. Every suffix here parses back to an equal key signature
+  # (ionian/aeolian differ from major/minor only in name, not alterations).
+  ABC_SUFFIXES_BY_MODE = {
+    "major" => "",
+    "ionian" => "",
+    "minor" => "m",
+    "aeolian" => "m",
+    "dorian" => "dor",
+    "phrygian" => "phr",
+    "lydian" => "lyd",
+    "mixolydian" => "mix",
+    "locrian" => "loc"
+  }.freeze
+
+  # Returns the ABC K: field value for a key signature.
+  def self.abc_value(key_signature)
+    key_signature = HeadMusic::Rudiment::KeySignature.get(key_signature)
+    "#{tonic_string(key_signature)}#{mode_suffix(key_signature)}"
+  end
+
+  def self.tonic_string(key_signature)
+    spelling = key_signature.tonic_spelling
+    alteration = spelling.alteration
+    if alteration && (alteration.double_sharp? || alteration.double_flat?)
+      raise_render_error("Cannot render double-altered tonic #{spelling} in an ABC K: field")
+    end
+
+    # ABC convention uses ASCII "#"/"b" rather than the unicode signs
+    # that Spelling#to_s produces.
+    "#{spelling.letter_name}#{alteration&.ascii}"
+  end
+  private_class_method :tonic_string
+
+  def self.mode_suffix(key_signature)
+    ABC_SUFFIXES_BY_MODE[key_signature.scale_type.name.to_s] ||
+      raise_render_error("Cannot render scale type #{key_signature.scale_type} in an ABC K: field")
+  end
+  private_class_method :mode_suffix
+
+  def self.raise_render_error(message)
+    raise HeadMusic::Notation::ABC::RenderError, message
+  end
+  private_class_method :raise_render_error
+
   attr_reader :value, :line_number
 
   def initialize(value, line_number: nil)

data/lib/head_music/notation/abc/pitch_writer.rb

@@ -0,0 +1,72 @@
+# A namespace for ABC-notation parsing helpers
+module HeadMusic::Notation::ABC
+  # Converts pitches into ABC note tokens, emitting the minimal accidental
+  # marks required under the key signature and ABC's bar-persistent rules.
+  #
+  # A live PitchBuilder acts as an oracle: if an unmarked token would already
+  # parse back to the target pitch, no accidental is written. Emitted tokens
+  # are fed back through the oracle so its bar state matches what a parser
+  # will accumulate when re-reading the output.
+  class PitchWriter
+    attr_reader :key_signature
+
+    def initialize(key_signature)
+      @key_signature = HeadMusic::Rudiment::KeySignature.get(key_signature)
+      @oracle = PitchBuilder.new(@key_signature)
+    end
+
+    # Returns the ABC note token for the pitch, without any duration multiplier.
+    def token(pitch)
+      pitch = HeadMusic::Rudiment::Pitch.get(pitch)
+      letter = letter_token(pitch)
+      octave_marks = octave_marks(pitch)
+      return "#{letter}#{octave_marks}" if oracle.pitch(letter, octave_marks) == pitch
+
+      marks = accidental_marks(pitch)
+      commit_and_verify(pitch, letter, octave_marks, marks)
+      "#{marks}#{letter}#{octave_marks}"
+    end
+
+    # In ABC, accidentals persist only to the end of the bar.
+    def start_new_bar
+      oracle.start_new_bar
+    end
+
+    private
+
+    attr_reader :oracle
+
+    def letter_token(pitch)
+      letter = pitch.letter_name.to_s
+      (pitch.register >= 5) ? letter.downcase : letter
+    end
+
+    def octave_marks(pitch)
+      if pitch.register >= 5
+        "'" * (pitch.register - 5)
+      else
+        "," * (4 - pitch.register)
+      end
+    end
+
+    def accidental_marks(pitch)
+      fragment = pitch.alteration&.ascii.to_s
+      accidental_marks_by_fragment.fetch(fragment) do
+        raise RenderError, "cannot express #{pitch} in ABC notation"
+      end
+    end
+
+    def accidental_marks_by_fragment
+      @accidental_marks_by_fragment ||= PitchBuilder::ACCIDENTAL_FRAGMENTS.invert
+    end
+
+    # Feeding the marked token through the oracle updates its bar state
+    # exactly as a parser reading the output would — this call is load-bearing,
+    # not just a verification; later unmarked notes depend on the state it writes.
+    def commit_and_verify(pitch, letter, octave_marks, marks)
+      return if oracle.pitch(letter, octave_marks, marks) == pitch
+
+      raise RenderError, "cannot express #{pitch} in ABC notation"
+    end
+  end
+end