@libraz/libcantus 1.2.0 → 1.4.0

package/dist/{chunk-HYJJ2V2I.js → chunk-UTE5A36R.js}

@@ -1,47 +1,72 @@
 import {
-  HUMANIZE_ADJACENCY,
+  REFERENCE_PROFILE_VERSION,
   adjacent,
+  analyzeRhythm,
   analyzeTimeline,
   analyzeVoice,
   assertChordTimeline,
+  assertReferenceProfile,
+  assertSpansInOrder,
   attachPivots,
   barGridStart,
+  barSpanOf,
+  cadenceSimilarity,
   chordTimelineFromNotes,
+  chordToRoman,
   clamp01,
   combineEvidence,
-  detectCadence,
+  contourSimilarity,
+  densitySimilarity,
   detectCadences,
+  detectModulations,
   dirtySlotsFor,
+  durationSimilarity,
+  extractMotifs,
   firstSoundingBeat,
   floorMod,
   functionOf,
+  functionSimilarity,
   gridForNotes,
   harmonicNovelty,
   hasEnded,
-  isAppliedDominant,
-  isCadentialSixFour,
   keyLookup,
-  keyScaleAt,
+  keyPlanSimilarity,
   keyTimelineFromNotes,
   lastBarOf,
+  latestSoundingEnd,
+  melodicContour,
+  melodicSimilarity,
+  motifGraph,
+  motifStructureSimilarity,
+  onsetSimilarity,
+  orderedNotes,
+  phraseLengthSimilarity,
+  phraseMelody,
   prevailingKeyOf,
+  progressionSimilarity,
+  reduceProgression,
+  registerSimilarity,
+  resolveSpanEnd,
+  rhythmOver,
   sameInstant,
+  sectionSequenceSimilarity,
   segmentStartingAt,
   sliceBars,
+  statedKeyRegions,
+  surfaceSimilarity,
+  syncopationSimilarity,
   weightSimilarity,
+  weightedMean,
   windowWeights
-} from "./chunk-H2KJHBW4.js";
+} from "./chunk-FJFULJZE.js";
 import {
   PROFILE_WEIGHTS,
   chordPitchClasses,
   evaluateSafety,
-  isDominantChordOf,
-  keySignatureFifths,
   majorKey,
   resolveKey,
-  scaleOf,
-  scaleTonesInDegreeOrder
-} from "./chunk-RFIBF2RR.js";
+  scaleOf
+} from "./chunk-H7FVMBUC.js";
 import {
   BEAT_EPS,
   InvalidInputError,
@@ -61,11 +86,9 @@ import {
   beatsPerBarAt,
   describeRejected,
   isStrongBeat,
-  midiToNote,
   pitchClassOf,
-  resolveMeters,
-  spelledInterval
-} from "./chunk-AGOVW7U6.js";
+  resolveMeters
+} from "./chunk-YYVXRV3V.js";
 
 // src/analyze/arrange/internal.ts
 var MAX_LANE_LEAP = 24;
@@ -98,7 +121,7 @@ function assertTrackNotes(tracks, options) {
     const notes = tracks[index]?.notes;
     if (!Array.isArray(notes)) {
       throw new InvalidInputError(
-        `tracks[${index}].notes must be an array; received ${typeof notes}`
+        `tracks[${index}].notes must be an array; received ${describeRejected(notes)}`
       );
     }
     assertNoteEvents(notes, `tracks[${index}].notes`, options);
@@ -136,6 +159,7 @@ function assertGivenKeys(keys, name) {
     }
     resolveKey(region.key);
   }
+  assertSpansInOrder(keys, name);
 }
 function harmonyTrackSet(harmonyTracks, tracks, name = "harmonyTracks") {
   if (harmonyTracks === void 0) {
@@ -321,7 +345,12 @@ function lastStartingAtOrBefore(sounding, beat) {
 function prepareTracks(tracks) {
   let nextId = 0;
   return tracks.map((track, index) => {
-    const ordered = track.notes.map((note, originalIndex) => ({ note, originalIndex })).filter(({ note }) => note.durationBeat > 0).sort((a, b) => a.note.startBeat - b.note.startBeat || a.note.pitch - b.note.pitch).map(({ note, originalIndex }) => ({ ...note, id: nextId++, originalIndex }));
+    const ordered = track.notes.map((note, originalIndex) => ({ note, originalIndex })).filter(({ note }) => note.durationBeat > 0).sort((a, b) => a.note.startBeat - b.note.startBeat || a.note.pitch - b.note.pitch).map(({ note, originalIndex }) => ({
+      ...note,
+      pitch: note.pitch === 0 ? 0 : note.pitch,
+      id: nextId++,
+      originalIndex
+    }));
     const voices = splitIntoSubVoices(ordered).map((voice) => {
       const sounding = voice.map((note, i) => {
         const prev = i > 0 ? voice[i - 1] : void 0;
@@ -362,15 +391,16 @@ function withGivenKeys(result, given) {
   return { ...result, keys: given, prevailingKey: prevailingKeyOf(given) ?? result.prevailingKey };
 }
 function callerTimeline(timeline, key, given, pooled, meters, budget) {
-  const chartEnd = timeline.segments.reduce((end, segment) => Math.max(end, segment.endBeat), 0);
-  const soundingEnd = pooled.reduce(
-    (end, note) => Math.max(end, note.startBeat + note.durationBeat),
-    0
+  const chartEnd = timeline.segments.reduce(
+    (end, segment) => Math.max(end, segment.endBeat),
+    Number.NEGATIVE_INFINITY
   );
-  const totalBeats = Math.max(chartEnd, soundingEnd);
+  const soundingEnd = latestSoundingEnd(pooled, Number.NEGATIVE_INFINITY);
+  const spanEnd = Math.max(chartEnd, soundingEnd);
+  const totalBeats = Number.isFinite(spanEnd) ? spanEnd : 0;
   const { startBeat: musicStart } = gridForNotes(pooled, beatsPerBarAt(0, meters));
   const keys = given ?? attachPivots(
-    key !== void 0 ? [{ startBeat: musicStart, endBeat: totalBeats, key: resolveKey(key), confidence: 1 }] : keyTimelineFromNotes(pooled, { meters, totalBeats, budget }),
+    key !== void 0 ? statedKeyRegions(resolveKey(key), musicStart, totalBeats) : keyTimelineFromNotes(pooled, { meters, totalBeats, budget }),
     timeline.segments
   );
   return {
@@ -721,7 +751,7 @@ function sessionOf(tracks, opts, analysis, evidence) {
         }
         if (!Array.isArray(edit.notes)) {
           throw new InvalidInputError(
-            `edits[${index}].notes must be an array; received ${typeof edit.notes}`
+            `edits[${index}].notes must be an array; received ${describeRejected(edit.notes)}`
           );
         }
         assertNoteEvents(edit.notes, `edits[${index}].notes`, {
@@ -756,6 +786,7 @@ var FUNCTION_WEIGHT = 0.5;
 var DISSONANCE_WEIGHT = 0.35;
 var SPAN_WEIGHT = 0.15;
 var SPAN_SATURATION = 24;
+var MAX_DISTINCT_PITCHES = 128;
 function clamp012(value) {
   return Math.min(1, Math.max(0, value));
 }
@@ -787,19 +818,14 @@ function tensionCurve(tracks, opts = {}) {
   const harmonyTracks = harmonyTrackSet(opts.harmonyTracks, tracks);
   const pooled = poolNotes(tracks, harmonyTracks);
   const all = poolNotes(tracks);
-  const totalBeats = all.reduce((end, n) => Math.max(end, n.startBeat + n.durationBeat), 0);
+  const totalBeats = latestSoundingEnd(all);
   const { origin: sampleStart, startBeat: musicStart } = gridForNotes(all, step);
-  const suppliedKeys = opts.timeline === void 0 ? void 0 : opts.keys ?? (opts.key !== void 0 ? [
-    {
-      // The one region a named key holds starts where the music does,
-      // as the searched regions and the timeline's own key window do:
-      // a key cannot be in force over beats nothing sounds in.
-      startBeat: musicStart,
-      endBeat: totalBeats,
-      key: resolveKey(opts.key),
-      confidence: 1
-    }
-  ] : keyTimelineFromNotes(pooled, { meters, totalBeats, budget }));
+  const suppliedKeys = opts.timeline === void 0 ? void 0 : opts.keys ?? (opts.key !== void 0 ? (
+    // The one region a named key holds starts where the music does, as
+    // the searched regions and the timeline's own key window do: a key
+    // cannot be in force over beats nothing sounds in.
+    statedKeyRegions(resolveKey(opts.key), musicStart, totalBeats)
+  ) : keyTimelineFromNotes(pooled, { meters, totalBeats, budget }));
   const { timeline, keys, prevailingKey } = opts.timeline === void 0 || suppliedKeys === void 0 ? chordTimelineFromNotes(pooled, {
     key: opts.key,
     meters,
@@ -819,7 +845,7 @@ function tensionCurve(tracks, opts = {}) {
   assertGenerationBudget(sampleCount, "tension samples", budget);
   const voiceCount = prepared.reduce((sum, track) => sum + track.voices.length, 0);
   assertGenerationBudget(
-    sampleCount * Math.min(128, voiceCount) * voiceCount,
+    sampleCount * Math.min(MAX_DISTINCT_PITCHES, voiceCount) * voiceCount,
     "tension sample-voice comparisons",
     budget
   );
@@ -827,9 +853,8 @@ function tensionCurve(tracks, opts = {}) {
     const beat = i === 0 ? Math.max(sampleStart, musicStart) : sampleStart + i * step;
     points.push({
       beat,
-      // The pitch classes alone: tension is scored from what sounds against
-      // the tonic, and no reading below here asks how the key is written.
-      tension: sampleTension(prepared, timeline, scaleOf(keyAt(beat)), meters, profile, beat)
+      // The key whole: an augmented sixth is told from a dominant by its letters.
+      tension: sampleTension(prepared, timeline, keyAt(beat), meters, profile, beat)
     });
   }
   return points;
@@ -900,7 +925,7 @@ function sampleTension(prepared, timeline, key, meters, profile, beat) {
       others.pop();
     }
     const result = evaluateSafety(
-      { profile, candidatePitch: pitch, chord, key, otherVoices: others, strongBeat },
+      { profile, candidatePitch: pitch, chord, key: key.scale, otherVoices: others, strongBeat },
       { suggestions: false }
     );
     if (held !== void 0 && tail !== void 0) {
@@ -926,19 +951,34 @@ function sampleTension(prepared, timeline, key, meters, profile, beat) {
 
 // src/analyze/form/hypermeter.ts
 var GROUP_CANDIDATES = [2, 3, 4, 6, 8];
-var GROUP_PRIOR = /* @__PURE__ */ new Map([
+var GROUP_PRIOR_LIST = [
   [2, 0.9],
   [3, 0.75],
   [4, 1],
   [6, 0.7],
   [8, 0.85]
-]);
+];
+var GROUP_PRIOR = new Map(GROUP_PRIOR_LIST);
 var CONTRAST_SHARE = 0.65;
 var CADENCE_SHARE = 0.35;
 var GROUP_FINAL_FIT = 1;
 var ELIDED_FIT = 0.5;
 var MIN_GROUPS = 2;
 var MARGIN_FLOOR = 0.7;
+function cadenceSpans(arrivals, segments) {
+  return arrivals.map(({ atBeat, strength }) => ({
+    atBeat,
+    endBeat: segmentStartingAt(segments, atBeat)?.endBeat ?? atBeat,
+    strength
+  }));
+}
+function cadenceBarsOf(spans, meter) {
+  return spans.map((span) => ({
+    arrival: barIndexAt(span.atBeat, meter),
+    last: lastBarOf(meter, span.atBeat, span.endBeat),
+    strength: span.strength
+  }));
+}
 function accentContrast(novelty, slices, groupBars, phase) {
   let headSum = 0;
   let headCount = 0;
@@ -963,22 +1003,41 @@ function accentContrast(novelty, slices, groupBars, phase) {
   }
   return headSum / headCount - otherSum / otherCount;
 }
-function cadenceFitOf(cadenceBars, slices, groupBars, phase) {
+function cadenceFitOf(cadences, slices, groupBars, phase) {
   const lastBar = slices[slices.length - 1]?.index ?? -1;
+  const closing = /* @__PURE__ */ new Map();
+  const eliding = /* @__PURE__ */ new Map();
+  const credit = (bars, bar, strength) => {
+    bars.set(bar, Math.max(bars.get(bar) ?? 0, strength));
+  };
+  for (const cadence of cadences) {
+    const end = cadence.arrival + floorMod(groupBars - 1 + phase - cadence.arrival, groupBars);
+    if (end <= cadence.last) {
+      credit(closing, end, cadence.strength);
+    } else if (floorMod(cadence.arrival - phase, groupBars) === 0 && // Elision needs a next group to arrive into. Past the last bar the span
+    // holds there is none, so a cadence beat beyond the music is not evidence
+    // about how the music that was read is grouped.
+    cadence.arrival <= lastBar) {
+      credit(eliding, cadence.arrival - 1, cadence.strength);
+    }
+  }
   let ends = 0;
-  let fit = 0;
+  let closed = 0;
+  let weighted = 0;
   for (const slice of slices) {
     if (slice.index < 0 || floorMod(slice.index - phase, groupBars) !== groupBars - 1) {
       continue;
     }
     ends += 1;
-    if (cadenceBars.has(slice.index)) {
-      fit += GROUP_FINAL_FIT;
-    } else if (slice.index < lastBar && cadenceBars.has(slice.index + 1)) {
-      fit += ELIDED_FIT;
-    }
+    const final = closing.get(slice.index);
+    const elided = eliding.get(slice.index);
+    closed += Math.max(
+      final === void 0 ? 0 : GROUP_FINAL_FIT,
+      elided === void 0 ? 0 : ELIDED_FIT
+    );
+    weighted += Math.max(GROUP_FINAL_FIT * (final ?? 0), ELIDED_FIT * (elided ?? 0));
   }
-  return ends === 0 ? 0 : clamp01(fit / ends);
+  return ends === 0 ? { closed: 0, weighted: 0 } : { closed: clamp01(closed / ends), weighted: clamp01(weighted / ends) };
 }
 function undecidedReading(slices) {
   const fullBars = slices.filter((slice) => slice.index >= 0);
@@ -992,6 +1051,17 @@ function undecidedReading(slices) {
   };
 }
 function hypermeter(notes, meter, opts = {}) {
+  return hypermeterOver(
+    notes,
+    meter,
+    opts,
+    (asked) => cadenceSpans(
+      (asked.cadenceBeats ?? []).map((atBeat) => ({ atBeat, strength: 1 })),
+      []
+    )
+  );
+}
+function hypermeterOver(notes, meter, opts, spansOf) {
   const asked = assertOptions(opts, "opts");
   const meters = resolveMeters({ meters: meter }, "meter");
   assertNoteEvents(notes, "hypermeter notes", {
@@ -1000,10 +1070,16 @@ function hypermeter(notes, meter, opts = {}) {
   });
   const sounding = notes.filter((note) => note.durationBeat > 0);
   const firstOnset = firstSoundingBeat(sounding);
-  const lastEnd = sounding.reduce((end, n) => Math.max(end, n.startBeat + n.durationBeat), 0);
-  const spanEnd = asked.totalBeats ?? lastEnd;
-  assertRange(spanEnd, 0, Number.MAX_SAFE_INTEGER, "hypermeter totalBeats");
+  const spanEnd = resolveSpanEnd(
+    asked.totalBeats,
+    firstOnset,
+    latestSoundingEnd(sounding),
+    "hypermeter totalBeats"
+  );
   const spanStart = barGridStart(firstOnset, meters);
+  if (sounding.length === 0 || spanEnd <= spanStart + BEAT_EPS) {
+    return undecidedReading([]);
+  }
   const slices = sliceBars(sounding, meters, spanStart, spanEnd, asked.budget);
   const fullBars = slices.reduce((count, slice) => slice.index >= 0 ? count + 1 : count, 0);
   const candidates = GROUP_CANDIDATES.filter((groupBars) => fullBars >= groupBars * MIN_GROUPS);
@@ -1016,20 +1092,21 @@ function hypermeter(notes, meter, opts = {}) {
     asked.budget
   );
   const novelty = slices.map((_, index) => harmonicNovelty(slices, index));
-  const cadenceBars = new Set((asked.cadenceBeats ?? []).map((beat) => barIndexAt(beat, meters)));
-  const hasCadences = cadenceBars.size > 0;
+  const cadenceBars = cadenceBarsOf(spansOf(asked), meters);
+  const hasCadences = cadenceBars.length > 0;
   const readings = [];
   for (const groupBars of candidates) {
     const phases = Array.from({ length: groupBars }, (_, phase) => ({
       phase,
       contrast: accentContrast(novelty, slices, groupBars, phase),
-      cadenceFit: cadenceFitOf(cadenceBars, slices, groupBars, phase)
+      fit: cadenceFitOf(cadenceBars, slices, groupBars, phase)
     }));
-    const bestFit = phases.reduce((best2, reading) => Math.max(best2, reading.cadenceFit), 0);
-    for (const { phase, contrast, cadenceFit } of phases) {
-      if (hasCadences && cadenceFit < bestFit - BEAT_EPS) {
+    const bestFit = phases.reduce((best2, reading) => Math.max(best2, reading.fit.weighted), 0);
+    for (const { phase, contrast, fit } of phases) {
+      if (hasCadences && fit.weighted < bestFit - BEAT_EPS) {
         continue;
       }
+      const cadenceFit = fit.closed;
       const evidence = clamp01(
         hasCadences ? (
           // Floored at zero rather than summed raw: group heads that restate
@@ -1074,549 +1151,6 @@ function hypermeter(notes, meter, opts = {}) {
   };
 }
 
-// src/analyze/melody/internal.ts
-var RHYTHM_GRID = 64;
-function phraseNotes(phrase) {
-  if (Array.isArray(phrase)) {
-    return phrase;
-  }
-  return assertRecord(phrase, "melodic phrase").notes;
-}
-function orderedNotes(notes, name, budget) {
-  assertNoteEvents(notes, name, { allowNonPositiveDuration: true, budget });
-  const sounding = notes.filter((note) => note.durationBeat > 0).sort((a, b) => a.startBeat - b.startBeat || a.pitch - b.pitch);
-  const line = [];
-  for (const note of sounding) {
-    const previous = line[line.length - 1];
-    if (previous !== void 0 && Math.abs(note.startBeat - previous.startBeat) <= BEAT_EPS) {
-      line[line.length - 1] = note;
-      continue;
-    }
-    line.push(note);
-  }
-  return line;
-}
-function intervalsOf(notes) {
-  const out = [];
-  for (let i = 1; i < notes.length; i += 1) {
-    out.push((notes[i]?.pitch ?? 0) - (notes[i - 1]?.pitch ?? 0));
-  }
-  return out;
-}
-function onsetGaps(notes) {
-  const out = [];
-  for (let i = 1; i < notes.length; i += 1) {
-    out.push((notes[i]?.startBeat ?? 0) - (notes[i - 1]?.startBeat ?? 0));
-  }
-  return out;
-}
-function retrogradeGaps(notes) {
-  const out = [];
-  for (let i = notes.length - 1; i >= 1; i -= 1) {
-    const later = notes[i];
-    const earlier = notes[i - 1];
-    out.push(
-      (later?.startBeat ?? 0) + (later?.durationBeat ?? 0) - ((earlier?.startBeat ?? 0) + (earlier?.durationBeat ?? 0))
-    );
-  }
-  return out;
-}
-function rhythmProfile(gaps) {
-  const unit = gaps[0] ?? 0;
-  if (!(unit > BEAT_EPS)) {
-    return gaps.length === 0 ? [] : null;
-  }
-  return gaps.map((gap) => Math.round(gap / unit * RHYTHM_GRID) / RHYTHM_GRID);
-}
-function sameNumbers(a, b) {
-  if (a.length !== b.length) {
-    return false;
-  }
-  for (let i = 0; i < a.length; i += 1) {
-    if (Math.abs((a[i] ?? 0) - (b[i] ?? 0)) > BEAT_EPS) {
-      return false;
-    }
-  }
-  return true;
-}
-function roundTo(value, digits) {
-  const scale = 10 ** digits;
-  return Math.round(value * scale) / scale;
-}
-function endBeatOf(notes) {
-  let end = 0;
-  for (const note of notes) {
-    end = Math.max(end, note.startBeat + note.durationBeat);
-  }
-  return end;
-}
-function onsetSpan(notes) {
-  if (notes.length < 2) {
-    return 0;
-  }
-  return (notes[notes.length - 1]?.startBeat ?? 0) - (notes[0]?.startBeat ?? 0);
-}
-
-// src/analyze/melody/contour.ts
-var DIRECTIONAL_SHARE = 0.75;
-function extremes(notes) {
-  if (notes.length === 0) {
-    return { peak: -1, trough: -1 };
-  }
-  let peak = 0;
-  let trough = 0;
-  for (let i = 1; i < notes.length; i += 1) {
-    if ((notes[i]?.pitch ?? 0) > (notes[peak]?.pitch ?? 0)) {
-      peak = i;
-    }
-    if ((notes[i]?.pitch ?? 0) < (notes[trough]?.pitch ?? 0)) {
-      trough = i;
-    }
-  }
-  return { peak, trough };
-}
-function melodicContour(notes) {
-  const line = orderedNotes(phraseNotes(notes), "contour notes");
-  const intervals = intervalsOf(line);
-  const directions = intervals.map(
-    (step) => step > 0 ? "up" : step < 0 ? "down" : "same"
-  );
-  const { peak, trough } = extremes(line);
-  const range = (line[peak]?.pitch ?? 0) - (line[trough]?.pitch ?? 0);
-  const motion = intervals.reduce((sum, step) => sum + Math.abs(step), 0);
-  if (motion === 0) {
-    return {
-      directions,
-      shape: "static",
-      peakIndex: peak,
-      troughIndex: trough,
-      range: 0,
-      rationale: line.length < 2 ? "Too short to have a direction, so the line is static" : "Every note at the same pitch, so the line is static"
-    };
-  }
-  const first = line[0]?.pitch ?? 0;
-  const last = line[line.length - 1]?.pitch ?? 0;
-  const net = last - first;
-  const directness = Math.abs(net) / motion;
-  const share = Math.round(directness * 100);
-  if (directness >= DIRECTIONAL_SHARE) {
-    const shape = net > 0 ? "ascending" : "descending";
-    return {
-      directions,
-      shape,
-      peakIndex: peak,
-      troughIndex: trough,
-      range,
-      rationale: `${share}% of the motion runs ${net > 0 ? "up" : "down"}, so the line is ${shape}`
-    };
-  }
-  const peakPitch = line[peak]?.pitch ?? 0;
-  const archMotion = peakPitch - first + (peakPitch - last);
-  if (peak > 0 && peak < line.length - 1 && archMotion >= DIRECTIONAL_SHARE * motion) {
-    return {
-      directions,
-      shape: "arch",
-      peakIndex: peak,
-      troughIndex: trough,
-      range,
-      rationale: `Rises to its peak at note ${peak + 1} of ${line.length} and falls back, so the line is an arch`
-    };
-  }
-  return {
-    directions,
-    shape: "wave",
-    peakIndex: peak,
-    troughIndex: trough,
-    range,
-    rationale: `Changes direction without settling either way (${share}% of the motion nets out), so the line is a wave`
-  };
-}
-
-// src/analyze/melody/motifs.ts
-var MIN_CELL_NOTES = 3;
-var MAX_CELL_NOTES = 8;
-var MIN_OCCURRENCES = 2;
-function windowSignature(notes) {
-  const profile = rhythmProfile(onsetGaps(notes));
-  if (profile === null) {
-    return null;
-  }
-  return `${notes.length}|${intervalsOf(notes).join(",")}|${profile.join(",")}`;
-}
-function nonOverlapping(starts, length) {
-  const picked = [];
-  let lastEnd = Number.NEGATIVE_INFINITY;
-  for (const start of starts) {
-    if (start > lastEnd) {
-      picked.push(start);
-      lastEnd = start + length - 1;
-    }
-  }
-  return picked;
-}
-function subsumes(outer, inner) {
-  let at = 0;
-  for (const start of inner.starts) {
-    while (at + 1 < outer.starts.length && (outer.starts[at + 1] ?? 0) <= start) {
-      at += 1;
-    }
-    const from = outer.starts[at];
-    if (from === void 0 || start < from || start + inner.length > from + outer.length) {
-      return false;
-    }
-  }
-  return true;
-}
-function listBeats(occurrences) {
-  const shown = occurrences.slice(0, 5).map((occurrence) => roundTo(occurrence.startBeat, 3));
-  return occurrences.length > shown.length ? `${shown.join(", ")}, and ${occurrences.length - shown.length} more` : shown.join(", ");
-}
-function motifFromGroup(group, notes) {
-  const first = group.starts[0] ?? 0;
-  const prime = notes.slice(first, first + group.length).map((note) => ({ ...note }));
-  const primePitch = prime[0]?.pitch ?? 0;
-  const primeSpan = onsetSpan(prime);
-  const occurrences = group.starts.map((start) => {
-    const statement = notes.slice(start, start + group.length);
-    const span = onsetSpan(statement);
-    return {
-      noteIndex: start,
-      startBeat: statement[0]?.startBeat ?? 0,
-      endBeat: endBeatOf(statement),
-      transpose: (statement[0]?.pitch ?? 0) - primePitch,
-      timeRatio: primeSpan > BEAT_EPS ? span / primeSpan : 1
-    };
-  });
-  const shape = melodicContour(prime).shape;
-  const transposed = occurrences.some((occurrence) => occurrence.transpose !== 0);
-  const stretched = occurrences.some((occurrence) => Math.abs(occurrence.timeRatio - 1) > BEAT_EPS);
-  const detail = [
-    transposed ? "at more than one pitch level" : "at the same pitch level",
-    stretched ? "and in more than one set of note values" : ""
-  ].filter((part) => part !== "").join(" ");
-  return {
-    notes: prime,
-    intervals: intervalsOf(prime),
-    rhythm: rhythmProfile(onsetGaps(prime)) ?? [],
-    occurrences,
-    rationale: `${group.length}-note ${shape} cell stated ${occurrences.length} ${occurrences.length === 1 ? "time" : "times"} (beats ${listBeats(occurrences)}), ${detail}`
-  };
-}
-function extractMotifs(notes, opts = {}) {
-  const asked = assertOptions(opts, "opts");
-  const minNotes = assertInteger(asked.minNotes ?? MIN_CELL_NOTES, "motif minNotes", 2, 64);
-  const maxNotes = assertInteger(asked.maxNotes ?? MAX_CELL_NOTES, "motif maxNotes", 2, 64);
-  if (maxNotes < minNotes) {
-    throw new InvalidInputError(
-      `motif maxNotes must be at least minNotes ${minNotes}; received ${maxNotes}`
-    );
-  }
-  const minOccurrences = assertInteger(
-    asked.minOccurrences ?? MIN_OCCURRENCES,
-    "motif minOccurrences",
-    2
-  );
-  const sounding = orderedNotes(notes, "melody notes", asked.budget);
-  if (sounding.length < minNotes) {
-    return [];
-  }
-  assertGenerationBudget(
-    sounding.length * (maxNotes - minNotes + 1),
-    "motif windows",
-    asked.budget
-  );
-  const groups = /* @__PURE__ */ new Map();
-  for (let length = minNotes; length <= maxNotes; length += 1) {
-    for (let start = 0; start + length <= sounding.length; start += 1) {
-      const signature = windowSignature(sounding.slice(start, start + length));
-      if (signature === null) {
-        continue;
-      }
-      const group = groups.get(signature);
-      if (group === void 0) {
-        groups.set(signature, { signature, length, starts: [start] });
-      } else {
-        group.starts.push(start);
-      }
-    }
-  }
-  const candidates = [...groups.values()].map((group) => ({ ...group, starts: nonOverlapping(group.starts, group.length) })).filter((group) => group.starts.length >= minOccurrences).sort(
-    (a, b) => b.length - a.length || b.starts.length - a.starts.length || (a.starts[0] ?? 0) - (b.starts[0] ?? 0) || (a.signature < b.signature ? -1 : a.signature > b.signature ? 1 : 0)
-  );
-  const keptByLength = /* @__PURE__ */ new Map();
-  const kept = [];
-  let comparisons = 0;
-  for (const candidate of candidates) {
-    const first = candidate.starts[0] ?? 0;
-    let covered = false;
-    for (let length = candidate.length + 1; length <= maxNotes && !covered; length += 1) {
-      const byStart = keptByLength.get(length);
-      if (byStart === void 0) {
-        continue;
-      }
-      for (let from = Math.max(0, first - (length - candidate.length)); from <= first; from += 1) {
-        comparisons += 1;
-        const outer = byStart.get(from);
-        if (outer === void 0 || outer.starts.length < candidate.starts.length) {
-          continue;
-        }
-        comparisons += outer.starts.length + candidate.starts.length;
-        if (subsumes(outer, candidate)) {
-          covered = true;
-          break;
-        }
-      }
-    }
-    assertGenerationBudget(comparisons, "motif subsumption comparisons", asked.budget);
-    if (!covered) {
-      kept.push(candidate);
-      let byStart = keptByLength.get(candidate.length);
-      if (byStart === void 0) {
-        byStart = /* @__PURE__ */ new Map();
-        keptByLength.set(candidate.length, byStart);
-      }
-      for (const start of candidate.starts) {
-        byStart.set(start, candidate);
-      }
-    }
-  }
-  return kept.map((group) => motifFromGroup(group, sounding));
-}
-function motifFromNotes(notes) {
-  const sounding = orderedNotes(notes, "motif notes").map((note) => ({ ...note }));
-  return motifFromGroup(
-    { signature: windowSignature(sounding) ?? "", length: sounding.length, starts: [0] },
-    sounding
-  );
-}
-
-// src/analyze/melody/relation.ts
-function spellingOf(key) {
-  if (key === void 0) {
-    return "sharp";
-  }
-  return keySignatureFifths(key.tonic, key.scale) < 0 ? "flat" : "sharp";
-}
-function intervalBetween(from, to, key) {
-  const spelling = spellingOf(key);
-  return spelledInterval(midiToNote(from, spelling), midiToNote(to, spelling));
-}
-function intervalName(interval) {
-  return `${interval.descending && interval.semitones !== 0 ? "-" : ""}${interval.quality}${interval.number}`;
-}
-function ladderIndices(notes, key) {
-  const root = pitchClassOf(key.rootPc);
-  const offsets = scaleTonesInDegreeOrder(key).map((pc) => pitchClassOf(pc - root));
-  if (offsets.length === 0) {
-    return null;
-  }
-  const out = [];
-  for (const note of notes) {
-    const semitones = note.pitch - root;
-    const octave = Math.floor(semitones / 12);
-    const degree = offsets.indexOf(semitones - octave * 12);
-    if (degree < 0) {
-      return null;
-    }
-    out.push(octave * offsets.length + degree);
-  }
-  return out;
-}
-function ladderSteps(indices) {
-  const out = [];
-  for (let i = 1; i < indices.length; i += 1) {
-    out.push((indices[i] ?? 0) - (indices[i - 1] ?? 0));
-  }
-  return out;
-}
-function pitchShapes(a, b) {
-  const shapes = [];
-  if (sameNumbers(a, b)) {
-    shapes.push("exact");
-  }
-  if (sameNumbers(
-    b,
-    a.map((step) => -step)
-  )) {
-    shapes.push("inversion");
-  }
-  const reversed = [...a].reverse();
-  if (sameNumbers(
-    b,
-    reversed.map((step) => -step)
-  )) {
-    shapes.push("retrograde");
-  }
-  if (sameNumbers(b, reversed)) {
-    shapes.push("retrogradeInversion");
-  }
-  return shapes;
-}
-function totalGap(gaps) {
-  return gaps.reduce((sum, gap) => sum + gap, 0);
-}
-function stretchRatio(modelGaps, answerGaps) {
-  const span = totalGap(modelGaps);
-  return span > BEAT_EPS ? totalGap(answerGaps) / span : 1;
-}
-function stretchPhrase(ratio) {
-  return `note values ${roundTo(ratio, 3)}x the model's`;
-}
-function relateMotifs(a, b, keyLike) {
-  const key = keyLike === void 0 ? void 0 : resolveKey(keyLike);
-  const model = assertArray(assertRecord(a, "a").notes, "a.notes");
-  const answer = assertArray(assertRecord(b, "b").notes, "b.notes");
-  if (model.length === 0 || model.length !== answer.length) {
-    return null;
-  }
-  const modelGaps = onsetGaps(model);
-  const answerGaps = onsetGaps(answer);
-  const modelProfile = rhythmProfile(modelGaps);
-  const answerProfile = rhythmProfile(answerGaps);
-  const retroGaps = retrogradeGaps(model);
-  const retroProfile = rhythmProfile(retroGaps);
-  if (modelProfile === null || answerProfile === null) {
-    return null;
-  }
-  const forward = sameNumbers(modelProfile, answerProfile);
-  const backward = retroProfile !== null && sameNumbers(retroProfile, answerProfile);
-  const semitones = (answer[0]?.pitch ?? 0) - (model[0]?.pitch ?? 0);
-  const interval = intervalBetween(model[0]?.pitch ?? 0, answer[0]?.pitch ?? 0, key);
-  const gap = (answer[0]?.startBeat ?? 0) - endBeatOf(model);
-  const sequence = gap >= -HUMANIZE_ADJACENCY && gap <= HUMANIZE_ADJACENCY;
-  const timeRatio = stretchRatio(modelGaps, answerGaps);
-  const stretched = Math.abs(timeRatio - 1) > BEAT_EPS;
-  const shapes = pitchShapes(intervalsOf(model), intervalsOf(answer));
-  const base = { sequence, semitones, interval, timeRatio };
-  const backwardBase = { ...base, timeRatio: stretchRatio(retroGaps, answerGaps) };
-  if (forward && shapes.includes("exact")) {
-    if (semitones === 0) {
-      if (!stretched) {
-        return {
-          ...base,
-          kind: "repetition",
-          rationale: "Exact repetition: the same pitches in the same rhythm"
-        };
-      }
-      const augmented = timeRatio > 1;
-      return {
-        ...base,
-        kind: augmented ? "augmentation" : "diminution",
-        rationale: `${augmented ? "Augmentation" : "Diminution"}: the same pitches in ${stretchPhrase(timeRatio)}`
-      };
-    }
-    const name = intervalName(interval);
-    return {
-      ...base,
-      kind: "transposition",
-      rationale: sequence ? `Real sequence: the cell restated ${name} away with every interval kept literally` + (stretched ? `, in ${stretchPhrase(timeRatio)}` : "") : `Transposition by ${name}: every interval kept literally` + (stretched ? `, in ${stretchPhrase(timeRatio)}` : "")
-    };
-  }
-  if (forward && key !== void 0) {
-    const modelLadder = ladderIndices(model, key.scale);
-    const answerLadder = ladderIndices(answer, key.scale);
-    if (modelLadder !== null && answerLadder !== null) {
-      const degrees = (answerLadder[0] ?? 0) - (modelLadder[0] ?? 0);
-      if (degrees !== 0 && sameNumbers(ladderSteps(modelLadder), ladderSteps(answerLadder))) {
-        const direction = degrees > 0 ? "higher" : "lower";
-        const count = Math.abs(degrees);
-        return {
-          ...base,
-          kind: "tonalTransposition",
-          degrees,
-          rationale: `${sequence ? "Tonal sequence" : "Tonal transposition"}: the cell restated ${count} scale ${count === 1 ? "degree" : "degrees"} ${direction} inside the key, so the key resizes its intervals \u2014 a real one would have kept them literal`
-        };
-      }
-    }
-  }
-  if (forward && shapes.includes("inversion")) {
-    return {
-      ...base,
-      kind: "inversion",
-      rationale: "Inversion: every interval turned upside down about the first note" + (stretched ? `, in ${stretchPhrase(timeRatio)}` : "")
-    };
-  }
-  if (backward && shapes.includes("retrograde")) {
-    return {
-      ...backwardBase,
-      kind: "retrograde",
-      rationale: "Retrograde: the cell read back to front, rhythm included"
-    };
-  }
-  if (backward && shapes.includes("retrogradeInversion")) {
-    return {
-      ...backwardBase,
-      kind: "retrogradeInversion",
-      rationale: "Retrograde inversion: the cell read back to front and turned upside down"
-    };
-  }
-  return null;
-}
-
-// src/analyze/melody/similarity.ts
-var INTERVAL_TOLERANCE = 6;
-var PITCH_WEIGHT = 0.75;
-var RHYTHM_WEIGHT = 0.25;
-function gradedEditDistance(a, b, cost) {
-  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
-  for (let i = 1; i <= a.length; i += 1) {
-    const row = new Array(b.length + 1);
-    row[0] = i;
-    for (let j = 1; j <= b.length; j += 1) {
-      const substitution = (previous[j - 1] ?? 0) + cost(a[i - 1] ?? 0, b[j - 1] ?? 0);
-      const deletion = (previous[j] ?? 0) + 1;
-      const insertion = (row[j - 1] ?? 0) + 1;
-      row[j] = Math.min(substitution, deletion, insertion);
-    }
-    previous = row;
-  }
-  return previous[b.length] ?? 0;
-}
-function distanceToSimilarity(distance, a, b) {
-  const longest = Math.max(a, b);
-  if (longest === 0) {
-    return 1;
-  }
-  return Math.min(1, Math.max(0, 1 - distance / longest));
-}
-function intervalCost(x, y) {
-  return Math.min(1, Math.abs(x - y) / INTERVAL_TOLERANCE);
-}
-function gapCost(x, y) {
-  if (!(x > BEAT_EPS) || !(y > BEAT_EPS)) {
-    return Math.abs(x - y) > BEAT_EPS ? 1 : 0;
-  }
-  return Math.min(1, Math.abs(Math.log2(x / y)));
-}
-function compareMelodies(a, b) {
-  const left = orderedNotes(phraseNotes(a), "melody a");
-  const right = orderedNotes(phraseNotes(b), "melody b");
-  const leftIntervals = intervalsOf(left);
-  const rightIntervals = intervalsOf(right);
-  const pitchSimilarity = distanceToSimilarity(
-    gradedEditDistance(leftIntervals, rightIntervals, intervalCost),
-    leftIntervals.length,
-    rightIntervals.length
-  );
-  const leftGaps = rhythmProfile(onsetGaps(left)) ?? onsetGaps(left);
-  const rightGaps = rhythmProfile(onsetGaps(right)) ?? onsetGaps(right);
-  const rhythmSimilarity = distanceToSimilarity(
-    gradedEditDistance(leftGaps, rightGaps, gapCost),
-    leftGaps.length,
-    rightGaps.length
-  );
-  const similarity = PITCH_WEIGHT * pitchSimilarity + RHYTHM_WEIGHT * rhythmSimilarity;
-  return {
-    similarity,
-    pitchSimilarity,
-    rhythmSimilarity,
-    rationale: `Interval shapes ${Math.round(pitchSimilarity * 100)}% alike, rhythms ${Math.round(rhythmSimilarity * 100)}% alike, weighted ${PITCH_WEIGHT}/${RHYTHM_WEIGHT} into ${roundTo(similarity, 3)}`
-  };
-}
-function melodicSimilarity(a, b) {
-  return compareMelodies(a, b).similarity;
-}
-
 // src/analyze/form/phrase.ts
 var CADENCE_BOUNDARY_STRENGTH = {
   authentic: 0.9,
@@ -1644,6 +1178,7 @@ var PHRASE_CUT_COST = 1.3;
 var CLOSING_SHARE = 0.65;
 var FINAL_PHRASE_BONUS = 0.15;
 var HYPERMETRIC_CLOSE_BONUS = 0.1;
+var IMPERFECT_CLOSURE_FACTOR = 0.8;
 var EVADED_FACTOR = 0.6;
 var SIGNAL_ORDER = [
   "cadence",
@@ -1669,16 +1204,22 @@ function readBoundary(boundary) {
   );
   return {
     strength: combineEvidence(signals.map(([, strength]) => strength)),
+    uncredited: combineEvidence(
+      signals.filter(([signal]) => signal !== "cadence").map(([, strength]) => strength)
+    ),
     signals: signals.map(([signal]) => signal)
   };
 }
+function closesPhrase(atBeat, startBeat, endBeat) {
+  return atBeat >= startBeat - BEAT_EPS && atBeat < endBeat - BEAT_EPS;
+}
 function lengthFit(length, expected) {
   if (!(expected > 0)) {
     return 0;
   }
   return Math.max(-1, 1 - Math.abs(length - expected) / expected);
 }
-function choosePhrasePath(beats, strengths, minPhraseBeats, expected) {
+function choosePhrasePath(beats, strengths, minPhraseBeats, expected, held) {
   const value = new Array(beats.length).fill(Number.NEGATIVE_INFINITY);
   const cameFrom = new Array(beats.length).fill(-1);
   value[0] = 0;
@@ -1692,7 +1233,9 @@ function choosePhrasePath(beats, strengths, minPhraseBeats, expected) {
       if (length < minPhraseBeats - BEAT_EPS) {
         continue;
       }
-      const gain = (value[i] ?? 0) + (strengths[j] ?? 0) + lengthFit(length, expected) - PHRASE_CUT_COST;
+      const credited = held === void 0 || closesPhrase(held.arrivals[j] ?? endBeat, beats[i] ?? 0, endBeat);
+      const strength = credited ? strengths[j] ?? 0 : held.uncredited[j] ?? 0;
+      const gain = (value[i] ?? 0) + strength + lengthFit(length, expected) - PHRASE_CUT_COST;
       if (gain > (value[j] ?? Number.NEGATIVE_INFINITY)) {
         value[j] = gain;
         cameFrom[j] = i;
@@ -1711,32 +1254,35 @@ function choosePhrasePath(beats, strengths, minPhraseBeats, expected) {
   }
   return path;
 }
-function arrivalEnd(timeline, atBeat) {
-  return segmentStartingAt(timeline.segments, atBeat)?.endBeat ?? atBeat;
-}
-function barSpanOf(startBeat, endBeat, meters) {
-  const firstBar = barIndexAt(startBeat, meters);
-  const lastBar = barIndexAt(endBeat, meters);
-  const partOf = (beat, bar) => {
-    const barStart = barPositionToBeat({ bar, beat: 0 }, meters);
-    const barLength = beatsPerBarAt(barStart, meters);
-    return barLength > 0 ? (beat - barStart) / barLength : 0;
-  };
-  const bars = lastBar - firstBar + partOf(endBeat, lastBar) - partOf(startBeat, firstBar);
-  return Math.round(bars * 100) / 100;
+function boundaryCadences(timeline, key) {
+  const hits = detectCadences(timeline, key).filter((hit) => hit.cadence.type !== null);
+  const spans = cadenceSpans(
+    hits.map((hit) => ({
+      atBeat: hit.atBeat,
+      strength: CADENCE_BOUNDARY_STRENGTH[hit.cadence.type]
+    })),
+    timeline.segments
+  );
+  return { hits, spans };
 }
-function keyContextFor(opts, notes, meters, totalBeats) {
-  if (opts.key !== void 0) {
-    return opts.key;
+function keyContextFor(key, timeline, meters, totalBeats, budget) {
+  if (key !== void 0) {
+    return key;
   }
-  const regions = keyTimelineFromNotes(notes, {
-    meters,
-    totalBeats,
-    budget: opts.budget
-  });
+  const regions = detectModulations(timeline.segments, { meters, totalBeats, budget });
   const keyAt = keyLookup(regions, prevailingKeyOf(regions) ?? resolveKey(majorKey(0)));
   return (beat) => scaleOf(keyAt(beat));
 }
+function heldCadenceBoundaries(boundaries, hit, span, meters, spanEnd) {
+  const firstLine = barIndexAt(span.atBeat, meters) + 1;
+  const lastLine = barIndexAt(Math.min(span.endBeat, spanEnd), meters);
+  for (let bar = firstLine; bar <= lastLine; bar += 1) {
+    const line = barPositionToBeat({ bar, beat: 0 }, meters);
+    if (line < span.endBeat - BEAT_EPS) {
+      addSignal(boundaries, line, "cadence", span.strength, hit);
+    }
+  }
+}
 function restBoundaries(boundaries, notes, meters, restBeats) {
   const ordered = [...notes].sort((a, b) => a.startBeat - b.startBeat || a.pitch - b.pitch);
   let covered = Number.NEGATIVE_INFINITY;
@@ -1790,7 +1336,7 @@ function structuralWeightOf(cadence, confidence, aligned, isLast) {
     if (result.strength === "perfect") {
       base = 1;
     } else if (result.strength === "imperfect") {
-      base *= 0.8;
+      base *= IMPERFECT_CLOSURE_FACTOR;
     }
   }
   if (result.evaded) {
@@ -1828,17 +1374,18 @@ function phrasesFromTimeline(timeline, notes, opts = {}) {
   const segments = timeline.segments;
   const firstSegment = segments[0];
   const lastSegment = segments[segments.length - 1];
-  const firstOnset = sounding.reduce(
-    (first, n) => Math.min(first, n.startBeat),
-    firstSegment?.startBeat ?? 0
+  const earliest = Math.min(
+    firstSoundingBeat(sounding, Number.POSITIVE_INFINITY),
+    firstSegment?.startBeat ?? Number.POSITIVE_INFINITY
   );
+  const firstOnset = Number.isFinite(earliest) ? earliest : 0;
   const spanStart = barGridStart(firstOnset, meters);
-  const notesEnd = sounding.reduce(
-    (end, n) => Math.max(end, n.startBeat + n.durationBeat),
-    lastSegment?.endBeat ?? 0
+  const latestEnd = Math.max(
+    lastSegment?.endBeat ?? Number.NEGATIVE_INFINITY,
+    latestSoundingEnd(sounding, Number.NEGATIVE_INFINITY)
   );
-  const spanEnd = Math.max(spanStart, opts.totalBeats ?? notesEnd);
-  assertRange(spanEnd, 0, Number.MAX_SAFE_INTEGER, "phrase totalBeats");
+  const notesEnd = Number.isFinite(latestEnd) ? latestEnd : 0;
+  const spanEnd = resolveSpanEnd(opts.totalBeats, spanStart, notesEnd, "phrase totalBeats");
   if (spanEnd <= spanStart + BEAT_EPS) {
     return [];
   }
@@ -1849,13 +1396,9 @@ function phrasesFromTimeline(timeline, notes, opts = {}) {
   assertRange(longNoteBeats, Number.MIN_VALUE, Number.MAX_SAFE_INTEGER, "phrase longNoteBeats");
   const minPhraseBeats = opts.minPhraseBeats ?? barBeats;
   assertRange(minPhraseBeats, Number.MIN_VALUE, Number.MAX_SAFE_INTEGER, "phrase minPhraseBeats");
-  const key = keyContextFor(opts, sounding, meters, spanEnd);
-  const cadences = detectCadences(timeline, key);
-  const grouping = opts.hypermeter ?? hypermeter(sounding, meters, {
-    totalBeats: spanEnd,
-    cadenceBeats: cadences.map((hit) => hit.atBeat),
-    budget: opts.budget
-  });
+  const key = keyContextFor(opts.key, timeline, meters, spanEnd, opts.budget);
+  const { hits: cadences, spans } = boundaryCadences(timeline, key);
+  const grouping = opts.hypermeter ?? hypermeterOver(sounding, meters, { totalBeats: spanEnd, budget: opts.budget }, () => spans);
   const firstBar = barIndexAt(Math.max(0, spanStart), meters);
   const hyperBeats = Math.max(
     barBeats,
@@ -1864,19 +1407,11 @@ function phrasesFromTimeline(timeline, notes, opts = {}) {
   const expected = opts.expectedPhraseBeats ?? hyperBeats;
   assertRange(expected, Number.MIN_VALUE, Number.MAX_SAFE_INTEGER, "phrase expectedPhraseBeats");
   const boundaries = /* @__PURE__ */ new Map();
-  for (const hit of cadences) {
-    const type = hit.cadence.type;
-    if (type === null) {
-      continue;
-    }
-    const strength = CADENCE_BOUNDARY_STRENGTH[type];
-    const chordEnd = arrivalEnd(timeline, hit.atBeat);
-    addSignal(boundaries, chordEnd, "cadence", strength, hit);
-    const barEnd = barPositionToBeat({ bar: barIndexAt(hit.atBeat, meters) + 1, beat: 0 }, meters);
-    if (chordEnd > barEnd + BEAT_EPS) {
-      addSignal(boundaries, barEnd, "cadence", strength, hit);
-    }
-  }
+  cadences.forEach((hit, index) => {
+    const span = spans[index];
+    addSignal(boundaries, span.endBeat, "cadence", span.strength, hit);
+    heldCadenceBoundaries(boundaries, hit, span, meters, spanEnd);
+  });
   restBoundaries(boundaries, sounding, meters, restBeats);
   for (const note of sounding) {
     if (note.durationBeat >= longNoteBeats - BEAT_EPS) {
@@ -1907,7 +1442,11 @@ function phrasesFromTimeline(timeline, notes, opts = {}) {
     stops.map((stop) => stop.beat),
     readings.map((reading) => reading.strength),
     minPhraseBeats,
-    expected
+    expected,
+    {
+      arrivals: stops.map((stop) => stop.cadence?.atBeat ?? stop.beat),
+      uncredited: readings.map((reading) => reading.uncredited)
+    }
   );
   const downbeatKeys = new Set(
     grouping.downbeats.map((downbeat) => Math.round(downbeat / BEAT_EPS))
@@ -1919,14 +1458,15 @@ function phrasesFromTimeline(timeline, notes, opts = {}) {
     const startBeat = stops[from]?.beat ?? spanStart;
     const stop = stops[to];
     const endBeat = stop?.beat ?? spanEnd;
-    const reading = readings[to] ?? { strength: 0, signals: [] };
+    const reading = readings[to] ?? { strength: 0, uncredited: 0, signals: [] };
     const length = endBeat - startBeat;
-    const confidence = clamp01(
-      CLOSING_SHARE * reading.strength + (1 - CLOSING_SHARE) * Math.max(0, lengthFit(length, expected))
-    );
     const isLast = n === path.length - 1;
     const closing = stop?.cadence ?? null;
-    const cadence = closing !== null && closing.atBeat >= startBeat - BEAT_EPS && closing.atBeat < endBeat - BEAT_EPS ? closing : null;
+    const cadence = closing !== null && closesPhrase(closing.atBeat, startBeat, endBeat) ? closing : null;
+    const closingStrength = cadence === null ? reading.uncredited : reading.strength;
+    const confidence = clamp01(
+      CLOSING_SHARE * closingStrength + (1 - CLOSING_SHARE) * Math.max(0, lengthFit(length, expected))
+    );
     const structuralWeight = structuralWeightOf(
       cadence,
       confidence,
@@ -1934,7 +1474,7 @@ function phrasesFromTimeline(timeline, notes, opts = {}) {
       isLast
     );
     const signals = cadence === null ? reading.signals.filter((signal) => signal !== "cadence") : reading.signals;
-    const bars = barSpanOf(startBeat, endBeat, meters);
+    const bars = Math.round(barSpanOf(startBeat, endBeat, meters) * 100) / 100;
     phrases.push({
       startBeat,
       endBeat,
@@ -2000,13 +1540,17 @@ function sectionsFromNotes(notes, opts = {}) {
     budget: opts.budget
   });
   const sounding = notes.filter((note) => note.durationBeat > 0);
+  const firstSounding = firstSoundingBeat(sounding);
+  const firstOnset = barGridStart(firstSounding, meters);
+  const spanEnd = resolveSpanEnd(
+    opts.totalBeats,
+    firstOnset,
+    latestSoundingEnd(sounding),
+    "section totalBeats"
+  );
   if (sounding.length === 0) {
     return [];
   }
-  const firstOnset = barGridStart(firstSoundingBeat(sounding), meters);
-  const lastEnd = sounding.reduce((end, n) => Math.max(end, n.startBeat + n.durationBeat), 0);
-  const spanEnd = Math.max(firstOnset, opts.totalBeats ?? lastEnd);
-  assertRange(spanEnd, 0, Number.MAX_SAFE_INTEGER, "section totalBeats");
   const threshold = opts.threshold ?? DEFAULT_THRESHOLD;
   assertRange(threshold, 0, 1, "section threshold");
   const unitBars = opts.unitBars ?? hypermeter(sounding, meters, { totalBeats: spanEnd, budget: opts.budget }).groupBars;
@@ -2022,8 +1566,9 @@ function sectionsFromNotes(notes, opts = {}) {
     const barStart = startBar + index * unitBars;
     const startBeat = index === 0 ? firstOnset : barPositionToBeat({ bar: barStart, beat: 0 }, meters);
     const endBeat = index === unitCount - 1 ? spanEnd : barPositionToBeat({ bar: barStart + unitBars, beat: 0 }, meters);
+    const fromBeat = index === 0 ? Math.min(firstSounding, startBeat) : startBeat;
     const unitNotes = sounding.filter(
-      (note) => note.startBeat >= startBeat - BEAT_EPS && note.startBeat < endBeat - BEAT_EPS
+      (note) => note.startBeat >= fromBeat - BEAT_EPS && note.startBeat < endBeat - BEAT_EPS
     ).sort((a, b) => a.startBeat - b.startBeat || a.pitch - b.pitch);
     units.push({
       startBeat,
@@ -2120,175 +1665,294 @@ function sectionsFromNotes(notes, opts = {}) {
   return sections;
 }
 
-// src/analyze/reduction/index.ts
-var TONIC_ARRIVING = /* @__PURE__ */ new Set(["authentic", "plagal", "modal", "deceptive"]);
-function signedStep(fromPc, toPc) {
-  return (pitchClassOf(toPc) - pitchClassOf(fromPc) + 18) % 12 - 6;
-}
-function isStep(distance) {
-  const size = Math.abs(distance);
-  return size === 1 || size === 2;
-}
-function touches(before, after) {
-  return Math.abs(after.startBeat - before.endBeat) <= BEAT_EPS;
-}
-function salienceFloors(durations) {
-  const order = durations.map((_, index) => index).sort((a, b) => {
-    const left = durations[a] ?? 0;
-    const right = durations[b] ?? 0;
-    return left - right || a - b;
-  });
-  const rankOf = new Array(durations.length).fill(0);
-  for (let rank = 0; rank < order.length; rank += 1) {
-    rankOf[order[rank] ?? 0] = rank;
-  }
-  const floors = [];
-  const remaining = durations.length - 1;
-  for (let index = 0; index < durations.length; index += 1) {
-    if (remaining <= 0) {
-      floors.push(0);
-      continue;
+// src/analyze/reference/compare.ts
+var RATIONALE_FIELDS = 2;
+function rationaleOf(comparison) {
+  const measured = [];
+  for (const group of [comparison.form, comparison.harmony, comparison.melody, comparison.rhythm]) {
+    for (const [name, value] of Object.entries(group)) {
+      if (value !== null) {
+        measured.push({ name, value, order: measured.length });
+      }
     }
-    const skipped = rankOf[index] ?? 0;
-    const at = (position) => durations[order[position < skipped ? position : position + 1] ?? 0] ?? 0;
-    const middle = remaining >> 1;
-    floors.push(remaining % 2 === 1 ? at(middle) : (at(middle - 1) + at(middle)) / 2);
-  }
-  return floors;
-}
-function isTonicChord(chord, key) {
-  return pitchClassOf(chord.rootPc - key.rootPc) === 0 && !isAppliedDominant(chord, key);
-}
-function functionalReason(segment, before, after, keyAt) {
-  const key = keyAt(segment.startBeat);
-  if (after !== void 0 && isCadentialSixFour(segment.chord, after.chord, key)) {
-    return { kind: "cadentialSixFour" };
-  }
-  if (isTonicChord(segment.chord, key)) {
-    return { kind: "tonic" };
-  }
-  if (isDominantChordOf(segment.chord, key)) {
-    return { kind: "dominant" };
-  }
-  if (before !== void 0) {
-    const arrival = detectCadence(before.chord, segment.chord, key).type;
-    if (arrival !== null) {
-      return { kind: "cadenceArrival", cadence: arrival };
-    }
-  }
-  if (after !== void 0) {
-    const agent = detectCadence(segment.chord, after.chord, keyAt(after.startBeat)).type;
-    if (agent !== null && TONIC_ARRIVING.has(agent)) {
-      return { kind: "cadenceAgent", cadence: agent };
-    }
-  }
-  return null;
-}
-function figureReason(segment, before, after) {
-  if (before === void 0 || after === void 0) {
-    return null;
-  }
-  const incoming = signedStep(before.chord.rootPc, segment.chord.rootPc);
-  const outgoing = signedStep(segment.chord.rootPc, after.chord.rootPc);
-  if (!isStep(incoming) || !isStep(outgoing)) {
-    return null;
-  }
-  if (incoming > 0 === outgoing > 0) {
-    return { kind: "passing" };
-  }
-  return pitchClassOf(before.chord.rootPc) === pitchClassOf(after.chord.rootPc) ? { kind: "neighbor" } : null;
-}
-function describe(reason) {
-  switch (reason.kind) {
-    case "tonic":
-      return "Structural: the tonic of the key, which the progression is heard against";
-    case "dominant":
-      return "Structural: the dominant of the key, the chord its tonic is approached from";
-    case "cadentialSixFour":
-      return "Structural: a tonic six-four on the bass of the dominant that follows, which prolongs that dominant rather than framing the tonic";
-    case "cadenceArrival":
-      return `Structural: the arrival of a ${reason.cadence} cadence`;
-    case "cadenceAgent":
-      return `Structural: the chord that drives a ${reason.cadence} cadence`;
-    case "salient":
-      return "Structural: it holds the harmony longer than the chords around it";
-    case "first":
-      return "Structural: the first chord of the progression frames it";
-    case "last":
-      return "Structural: the last chord of the progression frames it";
-    case "unfigured":
-      return "Structural: its root neither steps through to the next chord nor returns to the last, so it embellishes nothing";
-    case "passing":
-      return "Passing: its root steps in from the previous chord and on to the next in the same direction";
-    case "neighbor":
-      return "Neighbor: its root steps away from the surrounding harmony and returns to it";
-  }
-}
-var BASIS_READINGS = {
-  function: ({ segment, before, after, keyAt }) => functionalReason(segment, before, after, keyAt),
-  duration: ({ segment, salienceFloor }) => segment.endBeat - segment.startBeat > salienceFloor ? { kind: "salient" } : null
-};
-var REDUCTION_BASES = Object.keys(BASIS_READINGS);
-function levelOf(reason) {
-  if (reason.kind === "passing") {
-    return "passing";
   }
-  return reason.kind === "neighbor" ? "neighbor" : "structural";
+  if (measured.length === 0) {
+    return "Nothing to compare: neither profile has material for any field";
+  }
+  const describe = (entries) => entries.map((entry) => `${entry.name} ${Math.round(entry.value * 100)}%`).join(", ");
+  const highest = [...measured].sort((x, y) => y.value - x.value || x.order - y.order);
+  const lowest = [...measured].sort((x, y) => x.value - y.value || x.order - y.order);
+  return `Most alike: ${describe(highest.slice(0, RATIONALE_FIELDS))}; least alike: ${describe(lowest.slice(0, RATIONALE_FIELDS))}`;
+}
+function compareReferences(a, b, opts) {
+  assertReferenceProfile(a, "reference profile a");
+  assertReferenceProfile(b, "reference profile b");
+  const { budget } = assertOptions(opts, "compare options");
+  const structural = (profile) => profile.harmony.chords.filter((chord) => chord.level === "structural");
+  const cadences = (profile) => profile.form.phrases.map((phrase) => phrase.cadence?.type ?? null);
+  const phraseMelodies = (profile) => profile.form.phrases.map((phrase) => phrase.melody);
+  const comparison = {
+    form: {
+      sectionSequenceSimilarity: sectionSequenceSimilarity(
+        a.form.sections.map((section) => section.label),
+        b.form.sections.map((section) => section.label)
+      ),
+      phraseLengthSimilarity: phraseLengthSimilarity(
+        a.form.phrases.map((phrase) => phrase.bars),
+        b.form.phrases.map((phrase) => phrase.bars)
+      )
+    },
+    harmony: {
+      progressionSimilarity: progressionSimilarity(structural(a), structural(b), budget),
+      functionSimilarity: functionSimilarity(a.harmony.chords, b.harmony.chords),
+      cadenceSimilarity: cadenceSimilarity(cadences(a), cadences(b)),
+      keyPlanSimilarity: keyPlanSimilarity(
+        a.harmony.keys.map((region) => region.key),
+        b.harmony.keys.map((region) => region.key)
+      ),
+      harmonicRhythmOnsetSimilarity: onsetSimilarity(a.harmony.rhythm, b.harmony.rhythm),
+      harmonicRhythmDensitySimilarity: densitySimilarity(a.harmony.rhythm, b.harmony.rhythm)
+    },
+    melody: {
+      surfaceSimilarity: surfaceSimilarity(a.melody.motifs, b.melody.motifs),
+      motifStructureSimilarity: motifStructureSimilarity(
+        { graph: a.melody.graph, spanBeats: a.span.endBeat - a.span.startBeat },
+        { graph: b.melody.graph, spanBeats: b.span.endBeat - b.span.startBeat }
+      ),
+      contourSimilarity: contourSimilarity(phraseMelodies(a), phraseMelodies(b)),
+      registerSimilarity: registerSimilarity(
+        { phrases: phraseMelodies(a), mean: a.melody.register?.mean ?? null },
+        { phrases: phraseMelodies(b), mean: b.melody.register?.mean ?? null }
+      )
+    },
+    rhythm: {
+      onsetSimilarity: onsetSimilarity(a.melody.rhythm, b.melody.rhythm),
+      densitySimilarity: densitySimilarity(a.melody.rhythm, b.melody.rhythm),
+      durationSimilarity: durationSimilarity(a.melody.rhythm, b.melody.rhythm),
+      syncopationSimilarity: syncopationSimilarity(a.melody.rhythm, b.melody.rhythm)
+    }
+  };
+  return { ...comparison, rationale: rationaleOf(comparison) };
 }
-function reduceProgression(timeline, key, opts = {}) {
-  assertChordTimeline(timeline);
-  const asked = assertOptions(opts, "opts");
-  const keyAt = keyScaleAt(key);
-  const basis = assertOneOf(asked.basis ?? "function", REDUCTION_BASES, "reduction basis");
-  const reading = BASIS_READINGS[basis];
+
+// src/analyze/reference/profile.ts
+function spanOf(sounding, timeline, meters, totalBeats) {
   const segments = timeline.segments;
-  const floors = basis === "duration" ? salienceFloors(segments.map((segment) => segment.endBeat - segment.startBeat)) : [];
-  const result = [];
-  for (let index = 0; index < segments.length; index += 1) {
-    const segment = segments[index];
-    if (segment === void 0) {
-      continue;
-    }
-    const previous = segments[index - 1];
-    const following = segments[index + 1];
-    const before = previous !== void 0 && touches(previous, segment) ? previous : void 0;
-    const after = following !== void 0 && touches(segment, following) ? following : void 0;
-    let reason = reading({ segment, before, after, keyAt, salienceFloor: floors[index] ?? 0 });
-    if (reason === null && index === 0) {
-      reason = { kind: "first" };
-    }
-    if (reason === null && index === segments.length - 1) {
-      reason = { kind: "last" };
-    }
-    reason ??= figureReason(segment, before, after) ?? { kind: "unfigured" };
-    result.push({
-      chord: segment.chord,
-      startBeat: segment.startBeat,
-      endBeat: segment.endBeat,
-      level: levelOf(reason),
-      rationale: describe(reason)
+  const firstSegment = segments[0];
+  const lastSegment = segments[segments.length - 1];
+  const firstOnset = firstSoundingBeat(sounding, firstSegment?.startBeat ?? 0);
+  const startBeat = barGridStart(
+    Math.min(firstOnset, firstSegment?.startBeat ?? firstOnset),
+    meters
+  );
+  const latestEnd = Math.max(
+    lastSegment?.endBeat ?? Number.NEGATIVE_INFINITY,
+    latestSoundingEnd(sounding, Number.NEGATIVE_INFINITY)
+  );
+  const notesEnd = Number.isFinite(latestEnd) ? latestEnd : 0;
+  return { startBeat, endBeat: Math.max(startBeat, totalBeats ?? notesEnd) };
+}
+function sameKey(a, b) {
+  return pitchClassOf(a.scale.rootPc) === pitchClassOf(b.scale.rootPc) && a.scale.modeMask12 === b.scale.modeMask12;
+}
+function keyIndexAt(regions, beat, prevailing) {
+  const holding = regions.findIndex((region) => region.startBeat <= beat && beat < region.endBeat);
+  if (holding >= 0) {
+    return holding;
+  }
+  return Math.max(
+    0,
+    regions.findIndex((region) => sameKey(region.key, prevailing))
+  );
+}
+function sectionAt(sections, beat) {
+  const index = sections.findIndex(
+    (section) => beat >= section.startBeat - BEAT_EPS && beat < section.endBeat - BEAT_EPS
+  );
+  return index < 0 ? null : index;
+}
+function readingsFor(notes, opts = {}) {
+  const asked = assertOptions(opts, "reference options");
+  const meters = resolveMeters(asked, "reference meters");
+  const budget = asked.budget;
+  if (asked.timeline === void 0) {
+    return chordTimelineFromNotes(notes, {
+      meters,
+      key: asked.key,
+      totalBeats: asked.totalBeats,
+      budget
     });
   }
-  return result;
+  const timeline = assertChordTimeline(asked.timeline, "reference timeline");
+  let keys;
+  if (asked.key === void 0) {
+    keys = keyTimelineFromNotes(notes, { meters, totalBeats: asked.totalBeats, budget });
+  } else {
+    const sounding = assertNoteEvents(notes, "reference notes", {
+      allowNonPositiveDuration: true,
+      budget
+    }).filter((note) => note.durationBeat > 0);
+    const span = spanOf(sounding, timeline, meters, asked.totalBeats);
+    keys = statedKeyRegions(resolveKey(asked.key), span.startBeat, span.endBeat);
+  }
+  return { timeline, keys, prevailingKey: prevailingKeyOf(keys) ?? resolveKey(majorKey(0)) };
+}
+function referenceFromReadings(notes, readings, opts = {}) {
+  const asked = assertOptions(opts, "reference options");
+  const meters = resolveMeters(asked, "reference meters");
+  const budget = asked.budget;
+  const sounding = assertNoteEvents(notes, "reference notes", {
+    allowNonPositiveDuration: true,
+    budget
+  }).filter((note) => note.durationBeat > 0);
+  if (asked.totalBeats !== void 0) {
+    assertRange(asked.totalBeats, 0, Number.MAX_SAFE_INTEGER, "reference totalBeats");
+  }
+  const line = orderedNotes(asked.melody ?? notes, "reference melody", budget).map(
+    (note) => Object.is(note.pitch, -0) ? { ...note, pitch: 0 } : note
+  );
+  const { timeline, prevailingKey } = readings;
+  const span = spanOf(sounding, timeline, meters, asked.totalBeats);
+  const spanEnd = span.endBeat;
+  const keyAt = keyLookup(readings.keys, prevailingKey);
+  const scaleAt = (beat) => scaleOf(keyAt(beat));
+  const cadenceBeats = detectCadences(timeline, scaleAt).map((hit) => hit.atBeat);
+  const grouping = hypermeter(sounding, meters, { cadenceBeats, totalBeats: spanEnd, budget });
+  const phrases = phrasesFromTimeline(timeline, notes, {
+    meters,
+    key: scaleAt,
+    hypermeter: grouping,
+    totalBeats: spanEnd,
+    budget
+  });
+  const cadences = /* @__PURE__ */ new Map();
+  for (const closing of structuralCadences(phrases)) {
+    const type = closing.cadence.type;
+    if (type !== null) {
+      cadences.set(closing.phraseIndex, {
+        atBeat: closing.atBeat,
+        type,
+        weight: closing.weight
+      });
+    }
+  }
+  const sections = sectionsFromNotes(notes, {
+    meters,
+    unitBars: grouping.groupBars,
+    totalBeats: spanEnd,
+    budget
+  });
+  const keys = readings.keys.length === 0 && timeline.segments.length > 0 ? [
+    {
+      startBeat: span.startBeat,
+      endBeat: spanEnd,
+      key: resolveKey(prevailingKey),
+      confidence: 0
+    }
+  ] : readings.keys.map((region) => ({
+    startBeat: region.startBeat,
+    endBeat: region.endBeat,
+    key: resolveKey(region.key),
+    confidence: region.confidence
+  }));
+  const chords = reduceProgression(timeline, scaleAt).map((reduced) => {
+    const index = keyIndexAt(keys, (reduced.startBeat + reduced.endBeat) / 2, prevailingKey);
+    const key = keys[index].key;
+    return {
+      startBeat: reduced.startBeat,
+      endBeat: reduced.endBeat,
+      key: index,
+      roman: chordToRoman(reduced.chord, key),
+      function: functionOf(reduced.chord, key),
+      level: reduced.level
+    };
+  });
+  const chordOnsets = timeline.segments.map((segment) => ({
+    pitch: 60,
+    startBeat: segment.startBeat,
+    durationBeat: segment.endBeat - segment.startBeat
+  }));
+  const harmonyRhythm = analyzeRhythm(chordOnsets, { meters, totalBeats: spanEnd, budget });
+  const motifs = extractMotifs(line, { budget });
+  const graph = motifGraph(line, motifs, { key: prevailingKey, budget });
+  let register = null;
+  if (line.length > 0) {
+    const pitches = line.map((note) => note.pitch);
+    register = {
+      low: Math.min(...pitches),
+      high: Math.max(...pitches),
+      mean: weightedMean(line)
+    };
+  }
+  const lineMean = register?.mean ?? 0;
+  const referenceMotifs = motifs.map((motif) => {
+    const first = motif.occurrences[0];
+    return {
+      intervals: motif.intervals,
+      rhythm: motif.rhythm,
+      unitBeats: motif.notes.length < 2 ? 0 : motif.notes[1].startBeat - motif.notes[0].startBeat,
+      spanBeats: first === void 0 ? 0 : first.endBeat - first.startBeat,
+      occurrences: motif.occurrences.length
+    };
+  });
+  const referencePhrases = phrases.map((phrase, index) => ({
+    startBeat: phrase.startBeat,
+    endBeat: phrase.endBeat,
+    bars: barSpanOf(phrase.startBeat, phrase.endBeat, meters),
+    section: sectionAt(sections, phrase.startBeat),
+    confidence: phrase.confidence,
+    cadence: cadences.get(index) ?? null,
+    melody: phraseMelody(line, phrase.startBeat, phrase.endBeat, lineMean, meters, budget),
+    motifNodes: graph.nodes.flatMap(
+      (node, nodeIndex) => node.startBeat >= phrase.startBeat - BEAT_EPS && node.startBeat < phrase.endBeat - BEAT_EPS ? [nodeIndex] : []
+    )
+  }));
+  return {
+    profileVersion: REFERENCE_PROFILE_VERSION,
+    span: {
+      startBeat: span.startBeat,
+      endBeat: spanEnd,
+      bars: barSpanOf(span.startBeat, spanEnd, meters)
+    },
+    meters,
+    form: {
+      hypermeter: { groupBars: grouping.groupBars, confidence: grouping.confidence },
+      sections,
+      phrases: referencePhrases
+    },
+    harmony: { keys, chords, rhythm: harmonyRhythm },
+    melody: {
+      register,
+      shape: line.length < 2 ? null : melodicContour(line).shape,
+      motifs: referenceMotifs,
+      graph,
+      rhythm: rhythmOver(line, { meters, totalBeats: spanEnd, budget }, span.startBeat)
+    }
+  };
+}
+function analyzeReference(notes, opts) {
+  return referenceFromReadings(notes, readingsFor(notes, opts), opts);
 }
 
 export {
   trackRoleOf,
+  arrangementProfile,
+  assertTrackNotes,
+  harmonyTrackSet,
   analyzePolyphony,
   analyzeArrangement,
   createArrangementSession,
   tensionCurve,
   tensionCurveFrom,
   hypermeter,
-  melodicContour,
-  extractMotifs,
-  motifFromNotes,
-  relateMotifs,
-  compareMelodies,
-  melodicSimilarity,
+  hypermeterOver,
+  boundaryCadences,
+  keyContextFor,
   phrasesFromTimeline,
   structuralCadences,
   sectionsFromNotes,
-  reduceProgression
+  compareReferences,
+  referenceFromReadings,
+  analyzeReference
 };
-//# sourceMappingURL=chunk-HYJJ2V2I.js.map
+//# sourceMappingURL=chunk-UTE5A36R.js.map