@libraz/libcantus 0.9.2 → 0.9.3

package/dist/theory/index.d.cts

@@ -1,10 +1,10 @@
-import { C as Chord } from '../index-BOBXBNwP.cjs';
-export { a as ChordQuality, c as chordFromDegree, d as chordPitchClasses, e as chordQualities, f as chordToneRole, g as diatonicSeventh, h as diatonicTriad, m as makeChord } from '../index-BOBXBNwP.cjs';
-import { d as VoicingOptions } from '../styled-BjXtOFNk.cjs';
-export { C as ChordScaleMatch, a as ChordScaleReportEntry, S as SATB_RANGES, b as ScaleChoice, c as StyledVoicingOptions, V as VoiceRange, e as VoicingStyle, f as availableTensions, g as avoidNotes, h as chordScaleReport, i as chordScales, s as scaleMatchesChord, j as scalesForChanges, v as voiceChord, k as voiceChordStyled, l as voiceProgression } from '../styled-BjXtOFNk.cjs';
+import { C as Chord } from '../index-BNlGP86A.cjs';
+export { a as ChordQuality, b as ChordSpan, P as PitchSpelling, c as chordFromDegree, d as chordPitchClasses, e as chordQualities, f as chordToneRole, g as diatonicSeventh, h as diatonicTriad, m as makeChord } from '../index-BNlGP86A.cjs';
+import { d as VoicingOptions } from '../styled-ZTbdaVFM.cjs';
+export { C as ChordScaleMatch, a as ChordScaleReportEntry, S as SATB_RANGES, b as ScaleChoice, c as StyledVoicingOptions, V as VoiceRange, e as VoicingStyle, f as availableTensions, g as avoidNotes, h as chordScaleReport, i as chordScales, s as scaleMatchesChord, j as scalesForChanges, v as voiceChord, k as voiceChordStyled, l as voiceProgression } from '../styled-ZTbdaVFM.cjs';
 import { K as KeyScale } from '../types-MGP29r3t.cjs';
-export { H as HarmonyRole, L as LockLevel, V as VoicedRole, r as roleOf } from '../index-BdeQ1r_p.cjs';
-export { N as NoteSafety, R as ReasonFlag, S as SafetyProfile, a as SafetyQuery, b as SafetyResult, V as VoiceSnapshot, e as enumerateSafePitches, c as evaluateSafety } from '../index-DZ1M21do.cjs';
+export { H as HarmonyRole, L as LockLevel, V as VoicedRole, r as roleOf } from '../index-Dikst44v.cjs';
+export { N as NoteSafety, R as ReasonFlag, S as SafetyProfile, a as SafetyQuery, b as SafetyResult, V as VoiceSnapshot, e as enumerateSafePitches, c as evaluateSafety } from '../index-CxqBQtH1.cjs';
 import { N as Note } from '../index-CGMZNCx6.cjs';
 
 /**

package/dist/theory/index.d.ts

@@ -1,10 +1,10 @@
-import { C as Chord } from '../index-CM5W4rcm.js';
-export { a as ChordQuality, c as chordFromDegree, d as chordPitchClasses, e as chordQualities, f as chordToneRole, g as diatonicSeventh, h as diatonicTriad, m as makeChord } from '../index-CM5W4rcm.js';
-import { d as VoicingOptions } from '../styled-D7BAx3S3.js';
-export { C as ChordScaleMatch, a as ChordScaleReportEntry, S as SATB_RANGES, b as ScaleChoice, c as StyledVoicingOptions, V as VoiceRange, e as VoicingStyle, f as availableTensions, g as avoidNotes, h as chordScaleReport, i as chordScales, s as scaleMatchesChord, j as scalesForChanges, v as voiceChord, k as voiceChordStyled, l as voiceProgression } from '../styled-D7BAx3S3.js';
+import { C as Chord } from '../index-Bt4tOUD9.js';
+export { a as ChordQuality, b as ChordSpan, P as PitchSpelling, c as chordFromDegree, d as chordPitchClasses, e as chordQualities, f as chordToneRole, g as diatonicSeventh, h as diatonicTriad, m as makeChord } from '../index-Bt4tOUD9.js';
+import { d as VoicingOptions } from '../styled-DZ7GjShb.js';
+export { C as ChordScaleMatch, a as ChordScaleReportEntry, S as SATB_RANGES, b as ScaleChoice, c as StyledVoicingOptions, V as VoiceRange, e as VoicingStyle, f as availableTensions, g as avoidNotes, h as chordScaleReport, i as chordScales, s as scaleMatchesChord, j as scalesForChanges, v as voiceChord, k as voiceChordStyled, l as voiceProgression } from '../styled-DZ7GjShb.js';
 import { K as KeyScale } from '../types-MGP29r3t.js';
-export { H as HarmonyRole, L as LockLevel, V as VoicedRole, r as roleOf } from '../index-CP3wAfEH.js';
-export { N as NoteSafety, R as ReasonFlag, S as SafetyProfile, a as SafetyQuery, b as SafetyResult, V as VoiceSnapshot, e as enumerateSafePitches, c as evaluateSafety } from '../index-BreoJRw0.js';
+export { H as HarmonyRole, L as LockLevel, V as VoicedRole, r as roleOf } from '../index-Bg5dYMmZ.js';
+export { N as NoteSafety, R as ReasonFlag, S as SafetyProfile, a as SafetyQuery, b as SafetyResult, V as VoiceSnapshot, e as enumerateSafePitches, c as evaluateSafety } from '../index-Jc0Ryi79.js';
 import { N as Note } from '../index-CGMZNCx6.js';
 
 /**

package/dist/theory/index.js

@@ -1,12 +1,13 @@
+import "../chunk-N6IHQUOX.js";
 import {
   roleOf
-} from "../chunk-SDM3VJJ5.js";
+} from "../chunk-2ZWMSJH6.js";
 import {
   NoteSafety,
   ReasonFlag,
   enumerateSafePitches,
   evaluateSafety
-} from "../chunk-A4532ZFR.js";
+} from "../chunk-EH6EM37U.js";
 import {
   SATB_RANGES,
   availableTensions,
@@ -28,7 +29,7 @@ import {
   voiceChordStyled,
   voiceLeadingCost,
   voiceProgression
-} from "../chunk-XTC3X6MS.js";
+} from "../chunk-C5XYKUVG.js";
 import "../chunk-DYWFNC4A.js";
 import {
   BLUES_MASK,
@@ -74,8 +75,8 @@ import {
   pitchToScaleDegree,
   scaleByName,
   scaleTonesInDegreeOrder
-} from "../chunk-7Y7WF64D.js";
-import "../chunk-CCBLVAPK.js";
+} from "../chunk-MIWO425M.js";
+import "../chunk-FBQK3ZQN.js";
 export {
   BLUES_MASK,
   CHROMATIC_MASK,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libraz/libcantus",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "Pure-TypeScript music-theory and composition primitives (intervals, scales, chords).",
   "type": "module",
   "license": "Apache-2.0",
@@ -35,34 +35,64 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     },
     "./core": {
-      "types": "./dist/core/index.d.ts",
-      "import": "./dist/core/index.js",
-      "require": "./dist/core/index.cjs"
+      "import": {
+        "types": "./dist/core/index.d.ts",
+        "default": "./dist/core/index.js"
+      },
+      "require": {
+        "types": "./dist/core/index.d.cts",
+        "default": "./dist/core/index.cjs"
+      }
     },
     "./theory": {
-      "types": "./dist/theory/index.d.ts",
-      "import": "./dist/theory/index.js",
-      "require": "./dist/theory/index.cjs"
+      "import": {
+        "types": "./dist/theory/index.d.ts",
+        "default": "./dist/theory/index.js"
+      },
+      "require": {
+        "types": "./dist/theory/index.d.cts",
+        "default": "./dist/theory/index.cjs"
+      }
     },
     "./analyze": {
-      "types": "./dist/analyze/index.d.ts",
-      "import": "./dist/analyze/index.js",
-      "require": "./dist/analyze/index.cjs"
+      "import": {
+        "types": "./dist/analyze/index.d.ts",
+        "default": "./dist/analyze/index.js"
+      },
+      "require": {
+        "types": "./dist/analyze/index.d.cts",
+        "default": "./dist/analyze/index.cjs"
+      }
     },
     "./generate": {
-      "types": "./dist/generate/index.d.ts",
-      "import": "./dist/generate/index.js",
-      "require": "./dist/generate/index.cjs"
+      "import": {
+        "types": "./dist/generate/index.d.ts",
+        "default": "./dist/generate/index.js"
+      },
+      "require": {
+        "types": "./dist/generate/index.d.cts",
+        "default": "./dist/generate/index.cjs"
+      }
     },
     "./model": {
-      "types": "./dist/model/index.d.ts",
-      "import": "./dist/model/index.js",
-      "require": "./dist/model/index.cjs"
+      "import": {
+        "types": "./dist/model/index.d.ts",
+        "default": "./dist/model/index.js"
+      },
+      "require": {
+        "types": "./dist/model/index.d.cts",
+        "default": "./dist/model/index.cjs"
+      }
     }
   },
   "files": [
@@ -83,6 +113,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "bench:timeline": "yarn build && node --expose-gc benchmark/timeline-index.mjs",
     "docs": "typedoc",
     "prepare": "[ -d node_modules/typescript ] && tsup || true",
     "prepublishOnly": "yarn build"

package/src/analyze/arrange/internal.ts

@@ -108,9 +108,11 @@ export function prepareTracks(tracks: ArrangementTrack[]): PreparedTrack[] {
       voice,
       sounding: voice.map((note, i) => {
         const prev = i > 0 ? voice[i - 1] : undefined;
+        const prevEnd = prev === undefined ? undefined : prev.startBeat + prev.durationBeat;
+        const contiguous = prevEnd !== undefined && Math.abs(prevEnd - note.startBeat) <= EPS;
         return {
           pitch: note.pitch,
-          prevPitch: prev?.pitch,
+          prevPitch: contiguous ? prev?.pitch : undefined,
           startBeat: note.startBeat,
           endBeat: note.startBeat + note.durationBeat,
         };

package/src/analyze/arrange/tension.ts

@@ -7,6 +7,12 @@
 
 import { isStrongBeat, parseTimeSignature, type TimeSignature } from '../../core/meter/index.js';
 import type { KeyScale } from '../../core/types.js';
+import {
+  assertGenerationBudget,
+  assertNoteEvents,
+  assertRange,
+  assertTimeSignature,
+} from '../../core/validation/index.js';
 import { chordPitchClasses } from '../../theory/chord/index.js';
 import { evaluateSafety, NoteSafety, type SafetyProfile } from '../../theory/safety/index.js';
 import { functionOf } from '../functional/index.js';
@@ -84,11 +90,16 @@ export function tensionCurve(
   opts: ArrangementOptions & { step?: number } = {},
 ): TensionPoint[] {
   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: SafetyProfile = 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);
@@ -101,6 +112,7 @@ export function tensionCurve(
   const prepared = prepareTracks(tracks);
   const points: TensionPoint[] = [];
   const sampleCount = Math.max(0, Math.ceil(totalBeats / step - EPS));
+  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) });

package/src/analyze/arrange/tracks.ts

@@ -7,6 +7,11 @@
 
 import { isStrongBeat, parseTimeSignature, type TimeSignature } from '../../core/meter/index.js';
 import type { KeyScale, NoteEvent } from '../../core/types.js';
+import {
+  assertGenerationBudget,
+  assertNoteEvents,
+  assertTimeSignature,
+} from '../../core/validation/index.js';
 import {
   evaluateSafety,
   NoteSafety,
@@ -65,6 +70,10 @@ export type Conflict = {
   safety: NoteSafety;
   /** {@link import('../safety/index.js').SafetyResult.reasons} bitmask. */
   reasons: number;
+  /** Preferred stepwise resolution, when the safety evaluator provides one. */
+  resolveTo?: number;
+  /** Nearby fully safe replacement pitches, nearest first. */
+  suggestions?: number[];
   rationale?: string;
 };
 
@@ -143,8 +152,12 @@ function otherVoicesSounding(
           continue;
         }
         const snap: VoiceSnapshot = { pitch: note.pitch };
-        if (note.prevPitch !== undefined) {
-          snap.prevPitch = note.prevPitch;
+        // Motion reasons compare one real transition shared by both voices.
+        // A voice attacking exactly here contributes its adjacent predecessor;
+        // a sustained voice contributes the same pitch (oblique motion).
+        const previous = Math.abs(note.startBeat - beat) <= EPS ? note.prevPitch : note.pitch;
+        if (previous !== undefined) {
+          snap.prevPitch = previous;
         }
         out.push(snap);
       }
@@ -211,6 +224,13 @@ export function analyzeArrangement(
   opts: ArrangementOptions = {},
 ): ArrangementAnalysis {
   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: SafetyProfile = opts.profile ?? 'pop';
   const pooled = poolNotes(tracks);
 
@@ -242,11 +262,18 @@ export function analyzeArrangement(
         ),
       );
 
-      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 === undefined || preparedNote === undefined) {
+          continue;
+        }
         for (const beat of evaluationBeats(note, timeline)) {
+          const atOnset = Math.abs(beat - note.startBeat) <= EPS;
           const result = evaluateSafety({
             profile,
             candidatePitch: note.pitch,
+            prevPitch: atOnset ? preparedNote.prevPitch : note.pitch,
             chord: timeline.at(beat),
             key,
             otherVoices: otherVoicesSounding(prepared, t, v, beat),
@@ -263,6 +290,12 @@ export function analyzeArrangement(
             if (result.rationale !== undefined) {
               conflict.rationale = result.rationale;
             }
+            if (result.resolveTo !== undefined) {
+              conflict.resolveTo = result.resolveTo;
+            }
+            if (result.suggestions !== undefined) {
+              conflict.suggestions = [...result.suggestions];
+            }
             conflicts.push(conflict);
           }
         }

package/src/analyze/detect/index.ts

@@ -5,6 +5,7 @@
  */
 
 import type { KeyScale } from '../../core/types.js';
+import { assertFiniteNumber, assertGenerationBudget } from '../../core/validation/index.js';
 import type { Chord, ChordQuality } from '../../theory/chord/index.js';
 import { chordPitchClasses, chordQualities, makeChord } from '../../theory/chord/index.js';
 import {
@@ -30,12 +31,24 @@ export type ChordMatch = {
   extraPcs: number[];
   /** True when the input pitch-class set equals the chord exactly. */
   exact: boolean;
-  /** Inversion implied by the lowest note: 0 root position, 1 first, ... */
-  inversion: number;
+  /** Inversion implied by a known bass, or null for an unordered pitch-class set. */
+  inversion: number | null;
   /** Bass pitch class when inverted (the lowest note is not the root). */
   bassPc?: number;
 };
 
+/** Input interpretation for {@link detectChord} and {@link detectChordBest}. */
+export type DetectChordOptions = {
+  /**
+   * `midi` uses the numerically lowest pitch as bass; `pitchClass` treats the
+   * input as unordered. `auto` (default) selects pitch-class mode only when all
+   * values lie in 0..11.
+   */
+  input?: 'auto' | 'midi' | 'pitchClass';
+  /** Explicit bass pitch class, including for an unordered pitch-class set. */
+  bassPc?: number;
+};
+
 /**
  * A candidate key interpretation of a pitch-class set.
  *
@@ -58,6 +71,13 @@ function uniquePitchClasses(pitches: number[]): number[] {
   return [...new Set(pitches.map(pitchClass))].sort((a, b) => a - b);
 }
 
+function assertPitches(pitches: number[]): void {
+  assertGenerationBudget(pitches.length, 'detection pitches');
+  for (let index = 0; index < pitches.length; index += 1) {
+    assertFiniteNumber(pitches[index] ?? Number.NaN, `pitches[${index}]`);
+  }
+}
+
 /**
  * Identify chords matching a set of pitches.
  *
@@ -78,12 +98,25 @@ function uniquePitchClasses(pitches: number[]): number[] {
  * ```
  * @category Recognition
  */
-export function detectChord(pitches: number[]): ChordMatch[] {
+export function detectChord(pitches: number[], opts: DetectChordOptions = {}): ChordMatch[] {
+  assertPitches(pitches);
+  if (opts.bassPc !== undefined) assertFiniteNumber(opts.bassPc, 'bassPc');
   const input = uniquePitchClasses(pitches);
   if (input.length === 0) {
     return [];
   }
-  const bassPc = pitchClass(Math.min(...pitches));
+  const inputKind =
+    opts.input === undefined || opts.input === 'auto'
+      ? pitches.every((pitch) => Number.isInteger(pitch) && pitch >= 0 && pitch <= 11)
+        ? 'pitchClass'
+        : 'midi'
+      : opts.input;
+  const bassPc =
+    opts.bassPc !== undefined
+      ? pitchClass(opts.bassPc)
+      : inputKind === 'midi'
+        ? pitchClass(pitches.reduce((lowest, pitch) => Math.min(lowest, pitch), Infinity))
+        : undefined;
   const inputSet = new Set(input);
   const matches: ChordMatch[] = [];
   const qualities = chordQualities();
@@ -100,8 +133,11 @@ export function detectChord(pitches: number[]): ChordMatch[] {
         continue;
       }
       const extraPcs = input.filter((pc) => !toneSet.has(pc));
-      const bassIndex = chord.intervals.findIndex((iv) => pitchClass(rootPc + iv) === bassPc);
-      const inversion = bassIndex > 0 ? bassIndex : 0;
+      const bassIndex =
+        bassPc === undefined
+          ? -1
+          : chord.intervals.findIndex((iv) => pitchClass(rootPc + iv) === bassPc);
+      const inversion = bassPc === undefined ? null : bassIndex > 0 ? bassIndex : 0;
       const match: ChordMatch = {
         rootPc,
         quality,
@@ -110,7 +146,7 @@ export function detectChord(pitches: number[]): ChordMatch[] {
         exact: extraPcs.length === 0 && missingPcs.length === 0,
         inversion,
       };
-      if (inversion > 0) {
+      if (bassPc !== undefined && bassPc !== rootPc) {
         match.bassPc = bassPc;
       }
       matches.push(match);
@@ -146,8 +182,8 @@ export function detectChord(pitches: number[]): ChordMatch[] {
  * ```
  * @category Recognition
  */
-export function detectChordBest(pitches: number[]): Chord | null {
-  const best = detectChord(pitches)[0];
+export function detectChordBest(pitches: number[], opts: DetectChordOptions = {}): Chord | null {
+  const best = detectChord(pitches, opts)[0];
   if (!best) {
     return null;
   }
@@ -183,6 +219,7 @@ const MINOR_MASK_VARIANTS = [NATURAL_MINOR_MASK, HARMONIC_MINOR_MASK, MELODIC_MI
  * @category Recognition
  */
 export function detectKey(pitches: number[]): KeyMatch[] {
+  assertPitches(pitches);
   const input = uniquePitchClasses(pitches);
   if (input.length === 0) {
     return [];

package/src/analyze/functional/roman.ts

@@ -161,11 +161,20 @@ function parseSimpleRoman(
     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, '');
+  // Non-canonical spellings are limited to a complete quality marker followed
+  // by an optional major-seventh marker and a recognized figured bass. Never
+  // search substrings: `Vfoo` must not become diminished merely because it
+  // contains an "o", and unknown trailing text must be rejected in full.
+  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 === '°' || qualityMarker === 'dim';
+  const isAug = qualityMarker === '+' || qualityMarker === 'aug';
+  const isHalfDim = qualityMarker === 'ø';
+  const explicitMaj7 = parsedSuffix[2] !== undefined;
+  const figures = parsedSuffix[3] ?? '';
 
   // Reject figure strings that are neither a known figured-bass inversion nor a
   // canonical quality suffix rather than silently degrading to a root triad.

package/src/analyze/index.ts

@@ -12,7 +12,7 @@ export type {
   TrackRole,
 } from './arrange/index.js';
 export { analyzeArrangement, tensionCurve } from './arrange/index.js';
-export type { ChordMatch, KeyMatch } from './detect/index.js';
+export type { ChordMatch, DetectChordOptions, KeyMatch } from './detect/index.js';
 export { detectChord, detectChordBest, detectKey } from './detect/index.js';
 export type {
   BorrowedSource,

package/src/analyze/timeline/index.ts

@@ -1,6 +1,14 @@
+import { createNoteEventIndex } from '../../core/event-index/index.js';
 import type { TimeSignature } from '../../core/meter/index.js';
 import { beatsPerBar, metricWeight, parseTimeSignature } from '../../core/meter/index.js';
 import type { KeyScale, NoteEvent } from '../../core/types.js';
+import {
+  assertFiniteNumber,
+  assertGenerationBudget,
+  assertNoteEvents,
+  assertRange,
+  assertTimeSignature,
+} from '../../core/validation/index.js';
 import type { Chord, ChordSpan } from '../../theory/chord/index.js';
 import { chordPitchClasses, makeChord } from '../../theory/chord/index.js';
 import { isScaleTone, majorKey } from '../../theory/scale/index.js';
@@ -45,11 +53,24 @@ export type ChordTimeline = {
  * @category Arrangement & Analysis
  */
 export function chordTimelineFromChords(chords: ChordSpan[], totalBeats: number): ChordTimeline {
-  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: ChordSegment[] = 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,
@@ -64,6 +85,7 @@ export function chordTimelineFromChords(chords: ChordSpan[], totalBeats: number)
 /** Build the `at(beat)` lookup over a segment list. */
 function segmentLookup(segments: ChordSegment[]): (beat: number) => Chord | null {
   return (beat) => {
+    assertFiniteNumber(beat, 'timeline query beat');
     for (const seg of segments) {
       if (beat >= seg.startBeat && beat < seg.endBeat) {
         return seg.chord;
@@ -317,23 +339,37 @@ export function chordTimelineFromNotes(
   opts: ChordTimelineOptions = {},
 ): ChordTimelineResult {
   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}`);
-  }
+  assertRange(harmonicRhythm, Number.MIN_VALUE, Number.MAX_SAFE_INTEGER, 'harmonic rhythm');
+  assertNoteEvents(notes, 'timeline notes', { allowNonPositiveDuration: true });
   // Zero/negative-length notes never sound; drop them before any inference.
-  const sounding = notes.filter((note) => note.durationBeat > 0);
+  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: ChordSegment[] = [];
   const segmentConfidence: number[] = [];
   const windowCount = Math.max(0, Math.ceil(totalBeats / harmonicRhythm - EPS));
+  assertGenerationBudget(windowCount, 'timeline windows');
+  const windowNotes: NoteEvent[][] = 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;
     }

package/src/analyze/voice/index.ts

@@ -1,4 +1,5 @@
 import type { KeyScale, NoteEvent } from '../../core/types.js';
+import { assertNoteEvents } from '../../core/validation/index.js';
 import type { Chord } from '../../theory/chord/index.js';
 import { chordPitchClasses, chordToneRole } from '../../theory/chord/index.js';
 import {
@@ -165,6 +166,7 @@ export function analyzeVoice(
   key: KeyScale,
   otherVoicesAtBeat: (beat: number) => VoiceSnapshot[],
 ): AnalyzedNote[] {
+  assertNoteEvents(voice, 'voice notes', { allowNonPositiveDuration: true });
   const result: AnalyzedNote[] = [];
 
   for (let i = 0; i < voice.length; i += 1) {
@@ -177,10 +179,17 @@ export function analyzeVoice(
     // A neighboring note sharing this note's onset is a simultaneous cluster
     // member, not a melodic predecessor/successor; treating it as one would
     // fabricate passing/suspension figures, so it is dropped here.
+    const prevEnd =
+      prevNote === undefined
+        ? Number.NEGATIVE_INFINITY
+        : prevNote.startBeat + prevNote.durationBeat;
+    const noteEnd = note.startBeat + note.durationBeat;
     const prev =
-      prevNote !== undefined && prevNote.startBeat < note.startBeat - EPS ? prevNote : undefined;
+      prevNote !== undefined && Math.abs(prevEnd - note.startBeat) <= EPS ? prevNote : undefined;
     const next =
-      nextNote !== undefined && nextNote.startBeat > note.startBeat + EPS ? nextNote : undefined;
+      nextNote !== undefined && Math.abs(noteEnd - nextNote.startBeat) <= EPS
+        ? nextNote
+        : undefined;
     const chord = chordAtBeat(note.startBeat);
     const labels: TheoryLabel[] = [];
     const member = isChordMember(note.pitch, chord);