@libraz/libcantus 0.9.2 → 0.9.3

package/README.md

@@ -10,7 +10,7 @@ dependencies.
 [![codecov](https://codecov.io/gh/libraz/libcantus/branch/main/graph/badge.svg)](https://codecov.io/gh/libraz/libcantus)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/libraz/libcantus/blob/main/LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A522-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-22.x-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![docs](https://img.shields.io/badge/docs-API%20reference-b5892e)](https://libraz.github.io/libcantus/)
 
 ## What can you do with it?
@@ -245,11 +245,12 @@ Seeded, deterministic generators for melody and accompaniment:
 ```ts
 import {
   generateBassLine, generateCounterMelody, generateDrums, generateRhythm,
-  generateMotif, parseTimeSignature,
+  generateMotif, majorKey, parseTimeSignature,
 } from '@libraz/libcantus';
 
 generateRhythm(parseTimeSignature('4/4'), { seed: 1, density: 0.5 }); // strong-beat-weighted onsets
-generateMotif({ key: majorKey(0), length: 4, contour: 'arch', seed: 1 }); // a short melodic cell
+const motif = generateMotif({ key: majorKey(0), bars: 2, contour: 'arch', seed: 1 });
+motif.notes.length > 0; // true — a deterministic short melodic cell
 ```
 
 `humanize`, `extractGrooveTemplate`, and `applyGrooveTemplate` add a meter-aware

package/dist/analyze/index.cjs

@@ -43,6 +43,86 @@ __export(analyze_exports, {
 });
 module.exports = __toCommonJS(analyze_exports);
 
+// src/core/validation/index.ts
+var DEFAULT_GENERATION_BUDGET = 1e6;
+function assertFiniteNumber(value, name) {
+  if (!Number.isFinite(value)) {
+    throw new RangeError(`${name} must be finite; received ${value}`);
+  }
+  return value;
+}
+function assertInteger(value, name, min = Number.MIN_SAFE_INTEGER, max = Number.MAX_SAFE_INTEGER) {
+  assertFiniteNumber(value, name);
+  if (!Number.isSafeInteger(value) || value < min || value > max) {
+    throw new RangeError(`${name} must be an integer in [${min}, ${max}]; received ${value}`);
+  }
+  return value;
+}
+function assertPositiveInt(value, name, max = DEFAULT_GENERATION_BUDGET) {
+  return assertInteger(value, name, 1, max);
+}
+function assertRange(value, min, max, name) {
+  assertFiniteNumber(value, name);
+  if (value < min || value > max) {
+    throw new RangeError(`${name} must be in [${min}, ${max}]; received ${value}`);
+  }
+  return value;
+}
+function assertGenerationBudget(estimated, name, limit = DEFAULT_GENERATION_BUDGET) {
+  assertFiniteNumber(estimated, name);
+  assertPositiveInt(limit, `${name} limit`, Number.MAX_SAFE_INTEGER);
+  if (estimated < 0 || estimated > limit) {
+    throw new RangeError(`${name} exceeds the generation budget ${limit}; received ${estimated}`);
+  }
+  return estimated;
+}
+function assertTimeSignature(ts, name = "time signature") {
+  assertPositiveInt(ts.numerator, `${name}.numerator`);
+  assertPositiveInt(ts.denominator, `${name}.denominator`);
+  if (ts.grouping !== void 0) {
+    if (ts.grouping.length === 0) {
+      throw new RangeError(`${name}.grouping must not be empty`);
+    }
+    let sum = 0;
+    for (let index = 0; index < ts.grouping.length; index += 1) {
+      sum += assertPositiveInt(ts.grouping[index] ?? Number.NaN, `${name}.grouping[${index}]`);
+    }
+    const compound = ts.numerator % 3 === 0 && ts.numerator > 3;
+    const pulses = compound ? ts.numerator / 3 : ts.numerator;
+    if (sum !== pulses) {
+      throw new RangeError(`${name}.grouping must sum to ${pulses}; received ${sum}`);
+    }
+  }
+  return ts;
+}
+function assertNoteEvent(event, name = "note event", options = {}) {
+  assertFiniteNumber(event.pitch, `${name}.pitch`);
+  assertRange(event.startBeat, 0, Number.MAX_SAFE_INTEGER, `${name}.startBeat`);
+  assertRange(
+    event.durationBeat,
+    options.allowNonPositiveDuration ? -Number.MAX_SAFE_INTEGER : Number.MIN_VALUE,
+    Number.MAX_SAFE_INTEGER,
+    `${name}.durationBeat`
+  );
+  if (!options.allowNonPositiveDuration && event.durationBeat <= 0) {
+    throw new RangeError(`${name}.durationBeat must be positive; received ${event.durationBeat}`);
+  }
+  if (event.velocity !== void 0) {
+    assertRange(event.velocity, 0, 127, `${name}.velocity`);
+  }
+  return event;
+}
+function assertNoteEvents(events, name = "note events", options = {}) {
+  assertGenerationBudget(events.length, `${name} count`, options.budget);
+  for (let index = 0; index < events.length; index += 1) {
+    const event = events[index];
+    if (event !== void 0) {
+      assertNoteEvent(event, `${name}[${index}]`, options);
+    }
+  }
+  return events;
+}
+
 // src/core/meter/index.ts
 var EPS = 1e-9;
 function isMultiple(value, unit) {
@@ -59,21 +139,24 @@ function parseTimeSignature(text) {
   }
   const numerator = Number.parseInt(match[1] ?? "", 10);
   const denominator = Number.parseInt(match[2] ?? "", 10);
-  if (numerator <= 0 || denominator <= 0) {
+  if (!Number.isSafeInteger(numerator) || !Number.isSafeInteger(denominator) || numerator <= 0 || denominator <= 0) {
     throw new Error(`Invalid time signature: ${text}`);
   }
   return { numerator, denominator };
 }
 function formatTimeSignature(ts) {
+  assertTimeSignature(ts);
   return `${ts.numerator}/${ts.denominator}`;
 }
 function isCompound(ts) {
+  assertTimeSignature(ts);
   return ts.numerator % 3 === 0 && ts.numerator > 3;
 }
 function unitBeats(ts) {
   return 4 / ts.denominator;
 }
 function beatsPerBar(ts) {
+  assertTimeSignature(ts);
   return ts.numerator * unitBeats(ts);
 }
 function pulseBeats(ts) {
@@ -106,11 +189,14 @@ function isGroupHead(grouping, pulseIndex) {
   return false;
 }
 function beatToBarPosition(beatInQuarters, ts) {
+  assertFiniteNumber(beatInQuarters, "beat");
   const barLen = beatsPerBar(ts);
   const bar = Math.floor(beatInQuarters / barLen);
   return { bar, beat: beatInQuarters - bar * barLen };
 }
 function metricWeight(beatInQuarters, ts) {
+  assertFiniteNumber(beatInQuarters, "beat");
+  assertTimeSignature(ts);
   const { beat } = beatToBarPosition(beatInQuarters, ts);
   const pulse = pulseBeats(ts);
   if (!isMultiple(beat, pulse)) {
@@ -359,6 +445,31 @@ function isLeadingToneResolution(prev, cur, key) {
 // src/theory/safety/index.ts
 var SUGGESTION_WINDOW = 12;
 var MAX_SUGGESTIONS = 3;
+var REASON_SEVERITY = [
+  [2 /* Tension */, 1 /* Warning */, 1 /* Warning */],
+  [4 /* AvoidNote */, 1 /* Warning */, 2 /* Dissonant */],
+  [8 /* ScaleTone */, 1 /* Warning */, 1 /* Warning */],
+  [16 /* NonScale */, 2 /* Dissonant */, 2 /* Dissonant */],
+  [32 /* OutOfRange */, 1 /* Warning */, 1 /* Warning */],
+  [64 /* Tritone */, 2 /* Dissonant */, 2 /* Dissonant */],
+  [128 /* LargeLeap */, 1 /* Warning */, 2 /* Dissonant */],
+  [1024 /* VerticalDissonance */, 2 /* Dissonant */, 2 /* Dissonant */],
+  [2048 /* ParallelPerfect */, 1 /* Warning */, 2 /* Dissonant */],
+  [4096 /* HiddenParallel */, 1 /* Warning */, 2 /* Dissonant */],
+  [8192 /* VoiceCrossing */, 1 /* Warning */, 2 /* Dissonant */],
+  [16384 /* Suspension */, 2 /* Dissonant */, 2 /* Dissonant */],
+  [32768 /* NeedsResolution */, 1 /* Warning */, 2 /* Dissonant */]
+];
+function minimumSafetyForReasons(reasons, profile) {
+  let minimum = 0 /* Safe */;
+  const severityIndex = profile === "strict" ? 2 : 1;
+  for (const entry of REASON_SEVERITY) {
+    if (reasons & entry[0]) {
+      minimum = Math.max(minimum, entry[severityIndex]);
+    }
+  }
+  return minimum;
+}
 function pitchClass4(pitch) {
   return (Math.trunc(pitch) % 12 + 12) % 12;
 }
@@ -383,8 +494,27 @@ function stepResolution(pitch, chord) {
   return void 0;
 }
 function evaluateSafety(q) {
+  assertSafetyContext(q);
+  assertFiniteNumber(q.candidatePitch, "candidatePitch");
   return evaluateInternal(q, true);
 }
+function assertSafetyContext(q) {
+  if (q.prevPitch !== void 0) assertFiniteNumber(q.prevPitch, "prevPitch");
+  if (q.vocalLow !== void 0) assertFiniteNumber(q.vocalLow, "vocalLow");
+  if (q.vocalHigh !== void 0) assertFiniteNumber(q.vocalHigh, "vocalHigh");
+  if (q.vocalLow !== void 0 && q.vocalHigh !== void 0 && q.vocalLow > q.vocalHigh) {
+    throw new RangeError("vocalLow must not exceed vocalHigh");
+  }
+  assertGenerationBudget(q.otherVoices.length, "other voices");
+  for (let index = 0; index < q.otherVoices.length; index += 1) {
+    const voice = q.otherVoices[index];
+    if (!voice) continue;
+    assertFiniteNumber(voice.pitch, `otherVoices[${index}].pitch`);
+    if (voice.prevPitch !== void 0) {
+      assertFiniteNumber(voice.prevPitch, `otherVoices[${index}].prevPitch`);
+    }
+  }
+}
 function evaluateInternal(q, collectSuggestions) {
   let reasons = 0;
   let level = 0 /* Safe */;
@@ -445,9 +575,11 @@ function evaluateInternal(q, collectSuggestions) {
     const pc = Math.abs(pitch - q.prevPitch) % 12;
     if (pc === 6) {
       reasons |= 64 /* Tritone */;
+      raise(2 /* Dissonant */);
     }
     if (isForbiddenMelodicLeap(q.prevPitch, pitch)) {
       reasons |= 128 /* LargeLeap */;
+      raise(parallelSeverity);
     }
     if (pc === 1) {
       reasons |= 256 /* MinorSecond */;
@@ -492,6 +624,7 @@ function evaluateInternal(q, collectSuggestions) {
       }
     }
   }
+  raise(minimumSafetyForReasons(reasons, q.profile));
   const result = { safety: level, reasons, rationale: describe(reasons, q) };
   if (resolveTo !== void 0) {
     result.resolveTo = resolveTo;
@@ -684,11 +817,16 @@ function parseSimpleRoman(text, key) {
   if (canonical !== void 0) {
     return { rootPc, quality: canonical, inversion: 0 };
   }
-  const isDim = /o|°|dim/.test(suffix);
-  const isAug = /\+|aug/.test(suffix);
-  const isHalfDim = /ø/.test(suffix);
-  const explicitMaj7 = /maj7|M7/.test(suffix);
-  const figures = suffix.replace(/maj7|M7/g, "").replace(/[^0-9]/g, "");
+  const parsedSuffix = /^(o|°|dim|ø|\+|aug)?(maj7|M7)?(65|64|43|42|7|6|2)?$/.exec(suffix);
+  if (!parsedSuffix) {
+    throw new Error(`Unsupported suffix "${suffix}" in Roman numeral: ${text}`);
+  }
+  const qualityMarker = parsedSuffix[1] ?? "";
+  const isDim = qualityMarker === "o" || qualityMarker === "\xB0" || qualityMarker === "dim";
+  const isAug = qualityMarker === "+" || qualityMarker === "aug";
+  const isHalfDim = qualityMarker === "\xF8";
+  const explicitMaj7 = parsedSuffix[2] !== void 0;
+  const figures = parsedSuffix[3] ?? "";
   if (figures !== "" && !INVERSION_FIGURES.has(figures)) {
     throw new Error(`Unsupported figured-bass or extension "${figures}" in Roman numeral: ${text}`);
   }
@@ -937,6 +1075,73 @@ function detectCadence(from, to, key) {
   return null;
 }
 
+// src/core/event-index/index.ts
+var EPS2 = 1e-9;
+function upperBound(values, beat) {
+  let low = 0;
+  let high = values.length;
+  while (low < high) {
+    const middle = Math.floor((low + high) / 2);
+    if ((values[middle]?.note.startBeat ?? Number.POSITIVE_INFINITY) <= beat) {
+      low = middle + 1;
+    } else {
+      high = middle;
+    }
+  }
+  return low;
+}
+function createNoteEventIndex(events, options = {}) {
+  assertNoteEvents(events, "note events", options);
+  const notes = events.map((note, originalIndex) => ({
+    note,
+    originalIndex,
+    endBeat: note.startBeat + note.durationBeat
+  })).sort((a, b) => a.note.startBeat - b.note.startBeat || a.originalIndex - b.originalIndex);
+  const prefixMaxEnd = [];
+  let maxEnd = Number.NEGATIVE_INFINITY;
+  for (const indexed of notes) {
+    maxEnd = Math.max(maxEnd, indexed.endBeat);
+    prefixMaxEnd.push(maxEnd);
+  }
+  return {
+    notes,
+    at(beat) {
+      let index = upperBound(notes, beat + EPS2) - 1;
+      while (index >= 0) {
+        if ((prefixMaxEnd[index] ?? Number.NEGATIVE_INFINITY) <= beat + EPS2) {
+          return void 0;
+        }
+        const indexed = notes[index];
+        if (indexed && indexed.note.durationBeat > 0 && indexed.note.startBeat - EPS2 <= beat && beat < indexed.endBeat - EPS2) {
+          return indexed;
+        }
+        index -= 1;
+      }
+      return void 0;
+    },
+    attacksAt(beat) {
+      const firstAfter = upperBound(notes, beat + EPS2);
+      const candidate = notes[firstAfter - 1];
+      return candidate !== void 0 && Math.abs(candidate.note.startBeat - beat) < EPS2;
+    },
+    onsetsBetween(startBeat, endBeat) {
+      const result = [];
+      let index = upperBound(notes, startBeat + EPS2);
+      while (index < notes.length) {
+        const onset = notes[index]?.note.startBeat;
+        if (onset === void 0 || onset >= endBeat - EPS2) {
+          break;
+        }
+        if (result[result.length - 1] !== onset) {
+          result.push(onset);
+        }
+        index += 1;
+      }
+      return result;
+    }
+  };
+}
+
 // src/analyze/detect/index.ts
 function pitchClass5(value) {
   return (Math.trunc(value) % 12 + 12) % 12;
@@ -944,12 +1149,21 @@ function pitchClass5(value) {
 function uniquePitchClasses(pitches) {
   return [...new Set(pitches.map(pitchClass5))].sort((a, b) => a - b);
 }
-function detectChord(pitches) {
+function assertPitches(pitches) {
+  assertGenerationBudget(pitches.length, "detection pitches");
+  for (let index = 0; index < pitches.length; index += 1) {
+    assertFiniteNumber(pitches[index] ?? Number.NaN, `pitches[${index}]`);
+  }
+}
+function detectChord(pitches, opts = {}) {
+  assertPitches(pitches);
+  if (opts.bassPc !== void 0) assertFiniteNumber(opts.bassPc, "bassPc");
   const input = uniquePitchClasses(pitches);
   if (input.length === 0) {
     return [];
   }
-  const bassPc = pitchClass5(Math.min(...pitches));
+  const inputKind = opts.input === void 0 || opts.input === "auto" ? pitches.every((pitch) => Number.isInteger(pitch) && pitch >= 0 && pitch <= 11) ? "pitchClass" : "midi" : opts.input;
+  const bassPc = opts.bassPc !== void 0 ? pitchClass5(opts.bassPc) : inputKind === "midi" ? pitchClass5(pitches.reduce((lowest, pitch) => Math.min(lowest, pitch), Infinity)) : void 0;
   const inputSet = new Set(input);
   const matches = [];
   const qualities = chordQualities();
@@ -964,8 +1178,8 @@ function detectChord(pitches) {
         continue;
       }
       const extraPcs = input.filter((pc) => !toneSet.has(pc));
-      const bassIndex = chord.intervals.findIndex((iv) => pitchClass5(rootPc + iv) === bassPc);
-      const inversion = bassIndex > 0 ? bassIndex : 0;
+      const bassIndex = bassPc === void 0 ? -1 : chord.intervals.findIndex((iv) => pitchClass5(rootPc + iv) === bassPc);
+      const inversion = bassPc === void 0 ? null : bassIndex > 0 ? bassIndex : 0;
       const match = {
         rootPc,
         quality,
@@ -974,7 +1188,7 @@ function detectChord(pitches) {
         exact: extraPcs.length === 0 && missingPcs.length === 0,
         inversion
       };
-      if (inversion > 0) {
+      if (bassPc !== void 0 && bassPc !== rootPc) {
         match.bassPc = bassPc;
       }
       matches.push(match);
@@ -996,8 +1210,8 @@ function detectChord(pitches) {
   });
   return matches;
 }
-function detectChordBest(pitches) {
-  const best = detectChord(pitches)[0];
+function detectChordBest(pitches, opts = {}) {
+  const best = detectChord(pitches, opts)[0];
   if (!best) {
     return null;
   }
@@ -1005,6 +1219,7 @@ function detectChordBest(pitches) {
 }
 var MINOR_MASK_VARIANTS = [NATURAL_MINOR_MASK, HARMONIC_MINOR_MASK, MELODIC_MINOR_MASK];
 function detectKey(pitches) {
+  assertPitches(pitches);
   const input = uniquePitchClasses(pitches);
   if (input.length === 0) {
     return [];
@@ -1056,10 +1271,21 @@ function detectKey(pitches) {
 
 // src/analyze/timeline/index.ts
 function chordTimelineFromChords(chords, totalBeats) {
-  const sorted = [...chords].sort((a, b) => a.startBeat - b.startBeat);
+  assertRange(totalBeats, 0, Number.MAX_SAFE_INTEGER, "timeline totalBeats");
+  assertGenerationBudget(chords.length, "timeline chords");
+  for (let index = 0; index < chords.length; index += 1) {
+    assertRange(
+      chords[index]?.startBeat ?? Number.NaN,
+      0,
+      Number.MAX_SAFE_INTEGER,
+      `chords[${index}].startBeat`
+    );
+  }
+  const sorted = [...chords].filter((chord) => chord.startBeat < totalBeats).sort((a, b) => a.startBeat - b.startBeat);
   const segments = sorted.map((gc, i) => {
     const next = sorted[i + 1];
-    const endBeat = Math.max(gc.startBeat, next ? next.startBeat : totalBeats);
+    const nextBeat = next ? next.startBeat : totalBeats;
+    const endBeat = Math.min(totalBeats, Math.max(gc.startBeat, nextBeat));
     return {
       startBeat: gc.startBeat,
       endBeat,
@@ -1070,6 +1296,7 @@ function chordTimelineFromChords(chords, totalBeats) {
 }
 function segmentLookup(segments) {
   return (beat) => {
+    assertFiniteNumber(beat, "timeline query beat");
     for (const seg of segments) {
       if (beat >= seg.startBeat && beat < seg.endBeat) {
         return seg.chord;
@@ -1078,7 +1305,7 @@ function segmentLookup(segments) {
     return null;
   };
 }
-var EPS2 = 1e-9;
+var EPS3 = 1e-9;
 var NOISE_THRESHOLD_RATIO = 0.2;
 var MAX_DETECTION_PCS = 6;
 var FALLBACK_PCS = 3;
@@ -1120,11 +1347,11 @@ function analyzeWindow(notes, windowStart, windowEnd, ts, key) {
   for (const note of notes) {
     const noteEnd = note.startBeat + note.durationBeat;
     const overlap = Math.min(noteEnd, windowEnd) - Math.max(note.startBeat, windowStart);
-    if (overlap <= EPS2) {
+    if (overlap <= EPS3) {
       continue;
     }
     const velocityFactor = note.velocity !== void 0 ? note.velocity / 127 : 1;
-    const onsetInWindow = note.startBeat >= windowStart - EPS2 && note.startBeat < windowEnd - EPS2;
+    const onsetInWindow = note.startBeat >= windowStart - EPS3 && note.startBeat < windowEnd - EPS3;
     const accent = onsetInWindow ? 1 + metricWeight(note.startBeat, ts) / 3 : 1;
     const pc = pitchClass6(note.pitch);
     weights[pc] = (weights[pc] ?? 0) + overlap * velocityFactor * accent;
@@ -1138,7 +1365,7 @@ function analyzeWindow(notes, windowStart, windowEnd, ts, key) {
     totalWeight += w;
     maxWeight = Math.max(maxWeight, w);
   }
-  if (totalWeight <= EPS2) {
+  if (totalWeight <= EPS3) {
     return null;
   }
   const ranked = weights.map((weight, pc) => ({ pc, weight })).filter(({ weight }) => weight > 0).sort((a, b) => b.weight - a.weight || a.pc - b.pc);
@@ -1171,26 +1398,40 @@ function sameChord(a, b) {
 }
 function chordTimelineFromNotes(notes, opts = {}) {
   const ts = opts.ts ?? parseTimeSignature("4/4");
+  assertTimeSignature(ts);
   const harmonicRhythm = opts.harmonicRhythm ?? beatsPerBar(ts);
-  if (!(harmonicRhythm > 0)) {
-    throw new Error(`Invalid harmonic rhythm: ${harmonicRhythm}`);
-  }
-  const sounding = notes.filter((note) => note.durationBeat > 0);
+  assertRange(harmonicRhythm, Number.MIN_VALUE, Number.MAX_SAFE_INTEGER, "harmonic rhythm");
+  assertNoteEvents(notes, "timeline notes", { allowNonPositiveDuration: true });
+  const soundingIndex = createNoteEventIndex(notes.filter((note) => note.durationBeat > 0));
+  const sounding = soundingIndex.notes.map(({ note }) => note);
   const lastNoteEnd = sounding.reduce((end, n) => Math.max(end, n.startBeat + n.durationBeat), 0);
   const totalBeats = opts.totalBeats ?? lastNoteEnd;
+  assertRange(totalBeats, 0, Number.MAX_SAFE_INTEGER, "timeline totalBeats");
   const key = opts.key ?? detectKey(sounding.map((n) => n.pitch))[0]?.key ?? majorKey(0);
   const segments = [];
   const segmentConfidence = [];
-  const windowCount = Math.max(0, Math.ceil(totalBeats / harmonicRhythm - EPS2));
+  const windowCount = Math.max(0, Math.ceil(totalBeats / harmonicRhythm - EPS3));
+  assertGenerationBudget(windowCount, "timeline windows");
+  const windowNotes = Array.from({ length: windowCount }, () => []);
+  let memberships = 0;
+  for (const indexed of soundingIndex.notes) {
+    const first = Math.max(0, Math.floor(indexed.note.startBeat / harmonicRhythm));
+    const lastExclusive = Math.min(windowCount, Math.ceil(indexed.endBeat / harmonicRhythm));
+    memberships += Math.max(0, lastExclusive - first);
+    assertGenerationBudget(memberships, "timeline note-to-window memberships");
+    for (let window = first; window < lastExclusive; window += 1) {
+      windowNotes[window]?.push(indexed.note);
+    }
+  }
   for (let i = 0; i < windowCount; i += 1) {
     const start = i * harmonicRhythm;
     const end = Math.min(start + harmonicRhythm, totalBeats);
-    const inferred = analyzeWindow(sounding, start, end, ts, key);
+    const inferred = analyzeWindow(windowNotes[i] ?? [], start, end, ts, key);
     if (!inferred) {
       continue;
     }
     const last = segments[segments.length - 1];
-    if (last && sameChord(last.chord, inferred.chord) && Math.abs(last.endBeat - start) < EPS2) {
+    if (last && sameChord(last.chord, inferred.chord) && Math.abs(last.endBeat - start) < EPS3) {
       const lastLength = last.endBeat - last.startBeat;
       const length = end - start;
       const lastConfidence = segmentConfidence[segmentConfidence.length - 1] ?? 0;
@@ -1215,7 +1456,7 @@ function detectCadences(timeline, key) {
     if (!prev || !cur) {
       continue;
     }
-    if (Math.abs(cur.startBeat - prev.endBeat) > EPS2) {
+    if (Math.abs(cur.startBeat - prev.endBeat) > EPS3) {
       continue;
     }
     const type = detectCadence(prev.chord, cur.chord, key);
@@ -1227,9 +1468,9 @@ function detectCadences(timeline, key) {
 }
 
 // src/analyze/arrange/internal.ts
-var EPS3 = 1e-9;
+var EPS4 = 1e-9;
 function covers(note, beat) {
-  return beat >= note.startBeat - EPS3 && beat < note.endBeat - EPS3;
+  return beat >= note.startBeat - EPS4 && beat < note.endBeat - EPS4;
 }
 function poolNotes(tracks) {
   const notes = [];
@@ -1247,7 +1488,7 @@ function splitIntoSubVoices(ordered) {
   for (const note of ordered) {
     const lane = lanes.find((candidate) => {
       const last = candidate[candidate.length - 1];
-      return last !== void 0 && last.startBeat + last.durationBeat <= note.startBeat + EPS3;
+      return last !== void 0 && last.startBeat + last.durationBeat <= note.startBeat + EPS4;
     });
     if (lane) {
       lane.push(note);
@@ -1265,9 +1506,11 @@ function prepareTracks(tracks) {
       voice,
       sounding: voice.map((note, i) => {
         const prev = i > 0 ? voice[i - 1] : void 0;
+        const prevEnd = prev === void 0 ? void 0 : prev.startBeat + prev.durationBeat;
+        const contiguous = prevEnd !== void 0 && Math.abs(prevEnd - note.startBeat) <= EPS4;
         return {
           pitch: note.pitch,
-          prevPitch: prev?.pitch,
+          prevPitch: contiguous ? prev?.pitch : void 0,
           startBeat: note.startBeat,
           endBeat: note.startBeat + note.durationBeat
         };
@@ -1299,11 +1542,16 @@ function clamp01(value) {
 }
 function tensionCurve(tracks, opts = {}) {
   const ts = opts.ts ?? parseTimeSignature("4/4");
+  assertTimeSignature(ts);
+  assertGenerationBudget(tracks.length, "arrangement tracks");
+  for (let index = 0; index < tracks.length; index += 1) {
+    assertNoteEvents(tracks[index]?.notes ?? [], `tracks[${index}].notes`, {
+      allowNonPositiveDuration: true
+    });
+  }
   const profile = opts.profile ?? "pop";
   const step = opts.step ?? 1;
-  if (!(step > 0)) {
-    throw new Error(`Invalid tension sampling step: ${step}`);
-  }
+  assertRange(step, Number.MIN_VALUE, Number.MAX_SAFE_INTEGER, "tension sampling step");
   const pooled = poolNotes(tracks);
   const totalBeats = pooled.reduce((end, n) => Math.max(end, n.startBeat + n.durationBeat), 0);
   const { timeline, key } = chordTimelineFromNotes(pooled, {
@@ -1313,7 +1561,8 @@ function tensionCurve(tracks, opts = {}) {
   });
   const prepared = prepareTracks(tracks);
   const points = [];
-  const sampleCount = Math.max(0, Math.ceil(totalBeats / step - EPS3));
+  const sampleCount = Math.max(0, Math.ceil(totalBeats / step - EPS4));
+  assertGenerationBudget(sampleCount, "tension samples");
   for (let i = 0; i < sampleCount; i += 1) {
     const beat = i * step;
     points.push({ beat, tension: sampleTension(prepared, timeline, key, ts, profile, beat) });
@@ -1383,7 +1632,7 @@ function sampleTension(prepared, timeline, key, ts, profile, beat) {
 }
 
 // src/analyze/voice/index.ts
-var EPS4 = 1e-9;
+var EPS5 = 1e-9;
 function pitchClass8(pitch) {
   return (Math.trunc(pitch) % 12 + 12) % 12;
 }
@@ -1439,6 +1688,7 @@ function stepResolution2(pitch, chord) {
   return void 0;
 }
 function analyzeVoice(voice, chordAtBeat, key, otherVoicesAtBeat) {
+  assertNoteEvents(voice, "voice notes", { allowNonPositiveDuration: true });
   const result = [];
   for (let i = 0; i < voice.length; i += 1) {
     const note = voice[i];
@@ -1447,8 +1697,10 @@ function analyzeVoice(voice, chordAtBeat, key, otherVoicesAtBeat) {
     }
     const prevNote = i > 0 ? voice[i - 1] : void 0;
     const nextNote = i + 1 < voice.length ? voice[i + 1] : void 0;
-    const prev = prevNote !== void 0 && prevNote.startBeat < note.startBeat - EPS4 ? prevNote : void 0;
-    const next = nextNote !== void 0 && nextNote.startBeat > note.startBeat + EPS4 ? nextNote : void 0;
+    const prevEnd = prevNote === void 0 ? Number.NEGATIVE_INFINITY : prevNote.startBeat + prevNote.durationBeat;
+    const noteEnd = note.startBeat + note.durationBeat;
+    const prev = prevNote !== void 0 && Math.abs(prevEnd - note.startBeat) <= EPS5 ? prevNote : void 0;
+    const next = nextNote !== void 0 && Math.abs(noteEnd - nextNote.startBeat) <= EPS5 ? nextNote : void 0;
     const chord = chordAtBeat(note.startBeat);
     const labels = [];
     const member = isChordMember2(note.pitch, chord);
@@ -1588,8 +1840,9 @@ function otherVoicesSounding(prepared, excludeTrack, excludeVoice, beat) {
           continue;
         }
         const snap = { pitch: note.pitch };
-        if (note.prevPitch !== void 0) {
-          snap.prevPitch = note.prevPitch;
+        const previous = Math.abs(note.startBeat - beat) <= EPS4 ? note.prevPitch : note.pitch;
+        if (previous !== void 0) {
+          snap.prevPitch = previous;
         }
         out.push(snap);
       }
@@ -1601,7 +1854,7 @@ function evaluationBeats(note, timeline) {
   const noteEnd = note.startBeat + note.durationBeat;
   const beats = [note.startBeat];
   for (const segment of timeline.segments) {
-    if (segment.startBeat > note.startBeat + EPS3 && segment.startBeat < noteEnd - EPS3) {
+    if (segment.startBeat > note.startBeat + EPS4 && segment.startBeat < noteEnd - EPS4) {
       beats.push(segment.startBeat);
     }
   }
@@ -1609,6 +1862,13 @@ function evaluationBeats(note, timeline) {
 }
 function analyzeArrangement(tracks, opts = {}) {
   const ts = opts.ts ?? parseTimeSignature("4/4");
+  assertTimeSignature(ts);
+  assertGenerationBudget(tracks.length, "arrangement tracks");
+  for (let index = 0; index < tracks.length; index += 1) {
+    assertNoteEvents(tracks[index]?.notes ?? [], `tracks[${index}].notes`, {
+      allowNonPositiveDuration: true
+    });
+  }
   const profile = opts.profile ?? "pop";
   const pooled = poolNotes(tracks);
   const { timeline, key, segmentConfidence } = chordTimelineFromNotes(pooled, {
@@ -1639,11 +1899,18 @@ function analyzeArrangement(tracks, opts = {}) {
           (beat) => otherVoicesSounding(prepared, t, v, beat)
         )
       );
-      for (const note of subVoice.voice) {
+      for (let noteIndex = 0; noteIndex < subVoice.voice.length; noteIndex += 1) {
+        const note = subVoice.voice[noteIndex];
+        const preparedNote = subVoice.sounding[noteIndex];
+        if (note === void 0 || preparedNote === void 0) {
+          continue;
+        }
         for (const beat of evaluationBeats(note, timeline)) {
+          const atOnset = Math.abs(beat - note.startBeat) <= EPS4;
           const result = evaluateSafety({
             profile,
             candidatePitch: note.pitch,
+            prevPitch: atOnset ? preparedNote.prevPitch : note.pitch,
             chord: timeline.at(beat),
             key,
             otherVoices: otherVoicesSounding(prepared, t, v, beat),
@@ -1660,6 +1927,12 @@ function analyzeArrangement(tracks, opts = {}) {
             if (result.rationale !== void 0) {
               conflict.rationale = result.rationale;
             }
+            if (result.resolveTo !== void 0) {
+              conflict.resolveTo = result.resolveTo;
+            }
+            if (result.suggestions !== void 0) {
+              conflict.suggestions = [...result.suggestions];
+            }
             conflicts.push(conflict);
           }
         }