@libraz/libcantus 1.3.0 → 1.4.0

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

@@ -6,6 +6,7 @@ import {
   analyzeVoice,
   assertChordTimeline,
   assertReferenceProfile,
+  assertSpansInOrder,
   attachPivots,
   barGridStart,
   barSpanOf,
@@ -17,6 +18,7 @@ import {
   contourSimilarity,
   densitySimilarity,
   detectCadences,
+  detectModulations,
   dirtySlotsFor,
   durationSimilarity,
   extractMotifs,
@@ -31,6 +33,7 @@ import {
   keyPlanSimilarity,
   keyTimelineFromNotes,
   lastBarOf,
+  latestSoundingEnd,
   melodicContour,
   melodicSimilarity,
   motifGraph,
@@ -43,16 +46,19 @@ import {
   progressionSimilarity,
   reduceProgression,
   registerSimilarity,
+  resolveSpanEnd,
+  rhythmOver,
   sameInstant,
   sectionSequenceSimilarity,
   segmentStartingAt,
   sliceBars,
+  statedKeyRegions,
   surfaceSimilarity,
   syncopationSimilarity,
   weightSimilarity,
   weightedMean,
   windowWeights
-} from "./chunk-GNVN4PPJ.js";
+} from "./chunk-FJFULJZE.js";
 import {
   PROFILE_WEIGHTS,
   chordPitchClasses,
@@ -60,7 +66,7 @@ import {
   majorKey,
   resolveKey,
   scaleOf
-} from "./chunk-RFIBF2RR.js";
+} from "./chunk-H7FVMBUC.js";
 import {
   BEAT_EPS,
   InvalidInputError,
@@ -82,7 +88,7 @@ import {
   isStrongBeat,
   pitchClassOf,
   resolveMeters
-} from "./chunk-AGOVW7U6.js";
+} from "./chunk-YYVXRV3V.js";
 
 // src/analyze/arrange/internal.ts
 var MAX_LANE_LEAP = 24;
@@ -115,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);
@@ -153,6 +159,7 @@ function assertGivenKeys(keys, name) {
     }
     resolveKey(region.key);
   }
+  assertSpansInOrder(keys, name);
 }
 function harmonyTrackSet(harmonyTracks, tracks, name = "harmonyTracks") {
   if (harmonyTracks === void 0) {
@@ -338,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;
@@ -379,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 {
@@ -738,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`, {
@@ -773,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));
 }
@@ -804,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,
@@ -836,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
   );
@@ -844,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;
@@ -917,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) {
@@ -943,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;
@@ -980,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);
@@ -1009,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", {
@@ -1017,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);
@@ -1033,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
@@ -1118,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",
@@ -1143,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;
@@ -1166,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;
@@ -1185,21 +1254,35 @@ function choosePhrasePath(beats, strengths, minPhraseBeats, expected) {
   }
   return path;
 }
-function arrivalEnd(timeline, atBeat) {
-  return segmentStartingAt(timeline.segments, atBeat)?.endBeat ?? atBeat;
+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;
@@ -1253,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) {
@@ -1291,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 [];
   }
@@ -1312,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,
@@ -1327,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) {
@@ -1370,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))
@@ -1382,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,
@@ -1463,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;
@@ -1485,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,
@@ -1663,10 +1745,11 @@ function spanOf(sounding, timeline, meters, totalBeats) {
     Math.min(firstOnset, firstSegment?.startBeat ?? firstOnset),
     meters
   );
-  const notesEnd = sounding.reduce(
-    (end, note) => Math.max(end, note.startBeat + note.durationBeat),
-    lastSegment?.endBeat ?? 0
+  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) {
@@ -1710,14 +1793,7 @@ function readingsFor(notes, opts = {}) {
       budget
     }).filter((note) => note.durationBeat > 0);
     const span = spanOf(sounding, timeline, meters, asked.totalBeats);
-    keys = [
-      {
-        startBeat: span.startBeat,
-        endBeat: span.endBeat,
-        key: resolveKey(asked.key),
-        confidence: 1
-      }
-    ];
+    keys = statedKeyRegions(resolveKey(asked.key), span.startBeat, span.endBeat);
   }
   return { timeline, keys, prevailingKey: prevailingKeyOf(keys) ?? resolveKey(majorKey(0)) };
 }
@@ -1732,7 +1808,9 @@ function referenceFromReadings(notes, readings, opts = {}) {
   if (asked.totalBeats !== void 0) {
     assertRange(asked.totalBeats, 0, Number.MAX_SAFE_INTEGER, "reference totalBeats");
   }
-  const line = orderedNotes(asked.melody ?? notes, "reference melody", budget);
+  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;
@@ -1848,7 +1926,7 @@ function referenceFromReadings(notes, readings, opts = {}) {
       shape: line.length < 2 ? null : melodicContour(line).shape,
       motifs: referenceMotifs,
       graph,
-      rhythm: analyzeRhythm(line, { meters, totalBeats: spanEnd, budget })
+      rhythm: rhythmOver(line, { meters, totalBeats: spanEnd, budget }, span.startBeat)
     }
   };
 }
@@ -1858,12 +1936,18 @@ function analyzeReference(notes, opts) {
 
 export {
   trackRoleOf,
+  arrangementProfile,
+  assertTrackNotes,
+  harmonyTrackSet,
   analyzePolyphony,
   analyzeArrangement,
   createArrangementSession,
   tensionCurve,
   tensionCurveFrom,
   hypermeter,
+  hypermeterOver,
+  boundaryCadences,
+  keyContextFor,
   phrasesFromTimeline,
   structuralCadences,
   sectionsFromNotes,
@@ -1871,4 +1955,4 @@ export {
   referenceFromReadings,
   analyzeReference
 };
-//# sourceMappingURL=chunk-MLBPXA4Z.js.map
+//# sourceMappingURL=chunk-UTE5A36R.js.map