@libraz/libcantus 0.9.2 → 0.9.3

package/src/generate/harmonize/index.ts

@@ -1,6 +1,10 @@
+import { isDiatonic, parallelKey } from '../../analyze/functional/index.js';
+import { createNoteEventIndex } from '../../core/event-index/index.js';
 import type { TimeSignature } from '../../core/meter/index.js';
 import { isStrongBeat } from '../../core/meter/index.js';
+import { createRng } from '../../core/random/index.js';
 import type { KeyScale, NoteEvent } from '../../core/types.js';
+import { assertGenerationBudget, assertRange } from '../../core/validation/index.js';
 import type { Chord, ChordQuality } from '../../theory/chord/index.js';
 import { chordPitchClasses, diatonicTriad, makeChord } from '../../theory/chord/index.js';
 import type { HarmonyRole } from '../../theory/harmony/index.js';
@@ -86,17 +90,6 @@ function pitchClass(pitch: number): number {
   return ((Math.trunc(pitch) % 12) + 12) % 12;
 }
 
-function mulberry32(seed: number): () => number {
-  let state = seed >>> 0;
-  return () => {
-    state = (state + 0x6d2b79f5) >>> 0;
-    let t = state;
-    t = Math.imul(t ^ (t >>> 15), t | 1);
-    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-  };
-}
-
 /**
  * Estimate the best-fit key from a melody's pitch-class weighting.
  *
@@ -151,7 +144,6 @@ function buildCandidates(key: KeyScale, reharmonize: HarmonizeOptions['reharmoni
     base: 0,
   }));
 
-  const tonic = tones[0] ?? 0;
   if (reharmonize !== 'diatonic') {
     for (const target of [1, 3, 4, 5]) {
       const targetRoot = tones[target] ?? 0;
@@ -166,27 +158,30 @@ function buildCandidates(key: KeyScale, reharmonize: HarmonizeOptions['reharmoni
   }
 
   if (reharmonize === 'borrowed') {
-    candidates.push({
-      rootPc: (tonic + 10) % 12,
-      quality: 'maj',
-      secondaryDominant: false,
-      base: 2,
-    }); // bVII
-    candidates.push({
-      rootPc: (tonic + 8) % 12,
-      quality: 'maj',
-      secondaryDominant: false,
-      base: 2,
-    }); // bVI
-    candidates.push({
-      rootPc: (tonic + 5) % 12,
-      quality: 'min',
-      secondaryDominant: false,
-      base: 2,
-    }); // iv
+    const parallel = parallelKey(key);
+    const parallelTones = scaleTonesInDegreeOrder(parallel);
+    for (let degree = 0; degree < parallelTones.length; degree += 1) {
+      const chord = diatonicTriad(degree, parallel);
+      if (!isDiatonic(chord, key)) {
+        candidates.push({
+          rootPc: chord.rootPc,
+          quality: chord.quality,
+          secondaryDominant: false,
+          base: 1.25,
+        });
+      }
+    }
   }
 
-  return candidates;
+  const seen = new Set<string>();
+  return candidates.filter((candidate) => {
+    const id = `${candidate.rootPc}:${candidate.quality}`;
+    if (seen.has(id)) {
+      return false;
+    }
+    seen.add(id);
+    return true;
+  });
 }
 
 /**
@@ -361,24 +356,40 @@ function harmonizeOnce(
  * @category Reharmonization
  */
 export function harmonizeMelody(opts: HarmonizeOptions): HarmonizeResult {
+  const noteIndex = createNoteEventIndex(opts.melody);
   const key = opts.key === 'infer' ? inferKey(opts.melody) : opts.key;
   const candidates = buildCandidates(key, opts.reharmonize);
   const candAt = (i: number): Candidate => candidates[i] ?? FALLBACK;
-  const rng = mulberry32(opts.seed ?? 0);
-  const jitter = candidates.map(() => rng() * TIE_BREAK_JITTER);
+  const rng = createRng(opts.seed ?? 0);
+  const jitter = candidates.map(() => rng.next() * TIE_BREAK_JITTER);
 
-  const melodyEnd = opts.melody.reduce((m, n) => Math.max(m, n.startBeat + n.durationBeat), 0);
-  const hr = Math.max(0.25, opts.harmonicRhythm);
+  const melodyEnd = noteIndex.notes.reduce((m, n) => Math.max(m, n.endBeat), 0);
+  const requestedHr = assertRange(
+    opts.harmonicRhythm,
+    Number.MIN_VALUE,
+    Number.MAX_SAFE_INTEGER,
+    'harmonic rhythm',
+  );
+  const hr = Math.max(0.25, requestedHr);
   const segCount = Math.max(1, Math.ceil(melodyEnd / hr));
-  const segments: Segment[] = [];
-  for (let s = 0; s < segCount; s += 1) {
-    const startBeat = s * hr;
-    const endBeat = startBeat + hr;
-    const noteIndices = opts.melody
-      .map((n, i) => ({ n, i }))
-      .filter(({ n }) => n.startBeat < endBeat && n.startBeat + n.durationBeat > startBeat)
-      .map(({ i }) => i);
-    segments.push({ startBeat, endBeat, noteIndices });
+  assertGenerationBudget(segCount, 'harmonic segments');
+  assertGenerationBudget(segCount * candidates.length * candidates.length, 'harmonization search');
+  const segments: Segment[] = Array.from({ length: segCount }, (_, s) => ({
+    startBeat: s * hr,
+    endBeat: (s + 1) * hr,
+    noteIndices: [],
+  }));
+  // Associate each note only with the windows it actually spans. This replaces
+  // the former per-window full melody scan and creates no temporary note objects.
+  let memberships = 0;
+  for (const indexed of noteIndex.notes) {
+    const first = Math.max(0, Math.floor(indexed.note.startBeat / hr));
+    const lastExclusive = Math.min(segCount, Math.ceil(indexed.endBeat / hr - Number.EPSILON));
+    memberships += Math.max(0, lastExclusive - first);
+    assertGenerationBudget(memberships, 'note-to-segment memberships');
+    for (let segment = first; segment < lastExclusive; segment += 1) {
+      segments[segment]?.noteIndices.push(indexed.originalIndex);
+    }
   }
 
   const transposes: number[] = [0];

package/src/generate/index.ts

@@ -33,7 +33,6 @@ export type {
 } from './motif/index.js';
 export { developMotif, generateMotif, transformMotif } from './motif/index.js';
 export type {
-  ChordSpan,
   ProgFunction,
   ProgressionOptions,
   ProgressionPreset,

package/src/generate/motif/index.ts

@@ -1,5 +1,13 @@
 import type { ChordTimeline } from '../../analyze/timeline/index.js';
+import { createRng } from '../../core/random/index.js';
 import type { KeyScale } from '../../core/types.js';
+import {
+  assertFiniteNumber,
+  assertGenerationBudget,
+  assertInteger,
+  assertNoteEvents,
+  assertPositiveInt,
+} from '../../core/validation/index.js';
 import type { Chord } from '../../theory/chord/index.js';
 import { chordPitchClasses } from '../../theory/chord/index.js';
 import { isScaleTone, nearestScaleTone } from '../../theory/scale/index.js';
@@ -133,7 +141,20 @@ function nearestChordTone(pitch: number, chord: Chord): number {
 
 /** Earliest onset in a cell; the time origin for timing transforms. */
 function cellOrigin(notes: MotifNote[]): number {
-  return notes.length === 0 ? 0 : Math.min(...notes.map((n) => n.startBeat));
+  let origin = Number.POSITIVE_INFINITY;
+  for (const note of notes) {
+    origin = Math.min(origin, note.startBeat);
+  }
+  return Number.isFinite(origin) ? origin : 0;
+}
+
+/** Latest offset in a cell, without spreading an unbounded caller array. */
+function cellEnd(notes: MotifNote[]): number {
+  let end = Number.NEGATIVE_INFINITY;
+  for (const note of notes) {
+    end = Math.max(end, note.startBeat + note.durationBeat);
+  }
+  return Number.isFinite(end) ? end : 0;
 }
 
 /** Total beat span covered by a cell (from first onset to last offset). */
@@ -142,7 +163,7 @@ function cellSpan(cell: MotifCell): number {
     return 0;
   }
   const start = cellOrigin(cell.notes);
-  const end = Math.max(...cell.notes.map((n) => n.startBeat + n.durationBeat));
+  const end = cellEnd(cell.notes);
   return end - start;
 }
 
@@ -150,18 +171,6 @@ function clone(cell: MotifCell): MotifCell {
   return { notes: cell.notes.map((n) => ({ ...n })) };
 }
 
-/** Deterministic 32-bit PRNG in [0, 1). */
-function mulberry32(seed: number): () => number {
-  let state = seed >>> 0;
-  return () => {
-    state = (state + 0x6d2b79f5) >>> 0;
-    let t = state;
-    t = Math.imul(t ^ (t >>> 15), t | 1);
-    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-  };
-}
-
 /** Diatonic scale-degree offsets shaping a contour of `count` notes. */
 function contourOffsets(contour: MotifContour, count: number): number[] {
   const offsets: number[] = [];
@@ -209,12 +218,14 @@ function contourOffsets(contour: MotifContour, count: number): number[] {
  */
 export function generateMotif(opts: MotifOptions): MotifCell {
   const contour = opts.contour ?? 'arch';
-  const bars = Math.max(1, Math.trunc(opts.bars));
+  const bars = assertPositiveInt(opts.bars, 'motif bars');
   const totalBeats = bars * 4;
   const noteCount = Math.max(3, bars * 2);
+  assertGenerationBudget(noteCount, 'motif notes');
   const beatsPerNote = totalBeats / noteCount;
-  const rng = mulberry32(opts.seed ?? 0);
-  const jitterProb = Math.min(1, Math.max(0, opts.jitter ?? 0));
+  const rng = createRng(opts.seed ?? 0);
+  const requestedJitter = assertFiniteNumber(opts.jitter ?? 0, 'motif jitter');
+  const jitterProb = Math.min(1, Math.max(0, requestedJitter));
   const tonic = pitchClass(opts.key.rootPc) + 60;
   const offsets = contourOffsets(contour, noteCount);
 
@@ -224,8 +235,8 @@ export function generateMotif(opts: MotifOptions): MotifCell {
     // preserved exactly. When enabled it nudges up or down with equal odds,
     // avoiding the upward bias that used to drift arch/wave tails off the tonic.
     let jitter = 0;
-    if (jitterProb > 0 && rng() < jitterProb) {
-      jitter = rng() < 0.5 ? 1 : -1;
+    if (jitterProb > 0 && rng.next() < jitterProb) {
+      jitter = rng.next() < 0.5 ? 1 : -1;
     }
     let pitch = stepDiatonic(tonic, (offsets[i] ?? 0) + jitter, opts.key);
     const startBeat = i * beatsPerNote;
@@ -271,6 +282,16 @@ export function transformMotif(
   amount?: number,
   key?: KeyScale,
 ): MotifCell {
+  assertNoteEvents(cell.notes, 'motif notes');
+  if (amount !== undefined) {
+    assertFiniteNumber(amount, 'motif transform amount');
+  }
+  if ((t === 'transposeDiatonic' || t === 'sequence') && amount !== undefined) {
+    assertInteger(amount, 'diatonic transform amount');
+  }
+  if ((t === 'augment' || t === 'diminish') && amount !== undefined && amount <= 0) {
+    throw new RangeError('time transform amount must be positive');
+  }
   const notes = cell.notes;
   switch (t) {
     case 'transposeChromatic': {
@@ -297,7 +318,7 @@ export function transformMotif(
         return { notes: [] };
       }
       const start = cellOrigin(notes);
-      const end = Math.max(...notes.map((n) => n.startBeat + n.durationBeat));
+      const end = cellEnd(notes);
       return {
         notes: notes.map((n) => ({
           pitch: n.pitch,
@@ -363,8 +384,10 @@ export function developMotif(
   key: KeyScale,
   bars: number,
 ): MotifCell {
+  assertPositiveInt(bars, 'development bars');
+  assertNoteEvents(cell.notes, 'motif notes');
   const span = cellSpan(cell);
-  const totalBeats = Math.max(1, Math.trunc(bars)) * 4;
+  const totalBeats = bars * 4;
   const origin = cellOrigin(cell.notes);
   const out: MotifNote[] = [];
 
@@ -376,6 +399,7 @@ export function developMotif(
   // the offset multiplicatively so rounding error cannot accumulate over tiles.
   const tileSpan = Math.max(span, MIN_TILE_SPAN);
   const tileCount = Math.ceil(totalBeats / tileSpan);
+  assertGenerationBudget(tileCount * cell.notes.length, 'developed motif notes');
   for (let k = 0; k < tileCount; k += 1) {
     const offset = k * tileSpan;
     for (const n of cell.notes) {

package/src/generate/progression/index.ts

@@ -1,4 +1,6 @@
+import { createRng } from '../../core/random/index.js';
 import type { KeyScale } from '../../core/types.js';
+import { assertGenerationBudget, assertPositiveInt } from '../../core/validation/index.js';
 import type { ChordQuality, ChordSpan } from '../../theory/chord/index.js';
 import { diatonicTriad } from '../../theory/chord/index.js';
 import { scaleTonesInDegreeOrder } from '../../theory/scale/index.js';
@@ -237,18 +239,6 @@ export function progressionsByStyle(style: ProgStyle): ProgressionPreset[] {
   return progressions().filter((p) => p.styles.includes(style));
 }
 
-/** Deterministic 32-bit PRNG producing a float in [0, 1). */
-function mulberry32(seed: number): () => number {
-  let state = seed >>> 0;
-  return () => {
-    state = (state + 0x6d2b79f5) >>> 0;
-    let t = state;
-    t = Math.imul(t ^ (t >>> 15), t | 1);
-    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-  };
-}
-
 /** Root pitch class of a scale degree in the given key, including borrowed degrees. */
 function degreeToRootPc(degree: number, key: KeyScale): number {
   if (degree >= 0 && degree <= 6) {
@@ -307,6 +297,8 @@ function autoQuality(degree: number, key: KeyScale): ChordQuality {
  * @category Composition
  */
 export function generateProgression(opts: ProgressionOptions): ChordSpan[] {
+  assertPositiveInt(opts.bars, 'progression bars');
+  assertGenerationBudget(opts.bars, 'progression chords');
   const seed = opts.seed ?? 0;
   let preset: ProgressionPreset | undefined;
   if (opts.presetId !== undefined) {
@@ -318,8 +310,8 @@ export function generateProgression(opts: ProgressionOptions): ChordSpan[] {
   if (preset === undefined) {
     const pool = PRESETS.filter((p) => p.styles.includes(opts.style));
     const candidates = pool.length > 0 ? pool : PRESETS;
-    const rng = mulberry32(seed);
-    const index = Math.floor(rng() * candidates.length) % candidates.length;
+    const rng = createRng(seed);
+    const index = Math.floor(rng.next() * candidates.length) % candidates.length;
     preset = candidates[index] ?? PRESETS[0];
   }
   const degrees = preset?.degrees ?? [0];
@@ -339,7 +331,7 @@ export function generateProgression(opts: ProgressionOptions): ChordSpan[] {
 
   if (opts.reharmonize) {
     const tonicPc = (((opts.key.rootPc % 12) + 12) % 12) as number;
-    const rrng = mulberry32((seed ^ 0x9e3779b9) >>> 0);
+    const rrng = createRng((seed ^ 0x9e3779b9) >>> 0);
     for (let i = 0; i < chords.length - 1; i += 1) {
       const cur = chords[i];
       const next = chords[i + 1];
@@ -355,7 +347,7 @@ export function generateProgression(opts: ProgressionOptions): ChordSpan[] {
       if (targetsTonic || alreadySecondary || isResolutionTarget) {
         continue;
       }
-      if (rrng() < 0.5) {
+      if (rrng.next() < 0.5) {
         chords[i] = {
           rootPc: domRoot,
           quality: 'dom7',

package/src/generate/reharmony/index.ts

@@ -91,13 +91,6 @@ function isStableTarget(chord: Chord): boolean {
   return hasFifth && hasThird && !isDominantType(chord);
 }
 
-/** The triad pitch classes (root, third, fifth) implied by a chord's template. */
-function triadPitchClasses(chord: Chord): number[] {
-  const third = hasInterval(chord, 4) ? 4 : hasInterval(chord, 3) ? 3 : 4;
-  const fifth = hasInterval(chord, 8) ? 8 : hasInterval(chord, 6) ? 6 : 7;
-  return [mod12(chord.rootPc), mod12(chord.rootPc + third), mod12(chord.rootPc + fifth)];
-}
-
 /** Count the pitch classes shared between two pitch-class sets. */
 function commonToneCount(a: number[], b: number[]): number {
   const set = new Set(b);
@@ -157,7 +150,7 @@ export function substituteChord(
   key: KeyScale,
   opts?: SubstituteOptions,
 ): Substitution[] {
-  const original = triadPitchClasses(chord);
+  const original = chordPitchClasses(chord);
   const candidates: { chord: Chord; type: SubstitutionType }[] = [];
 
   // Tritone substitution: only for dominant-type chords.

package/src/generate/rhythm/index.ts

@@ -13,6 +13,11 @@
 
 import { beatsPerBar, metricWeight, type TimeSignature } from '../../core/meter/index.js';
 import { createRng } from '../../core/random/index.js';
+import {
+  assertFiniteNumber,
+  assertGenerationBudget,
+  assertPositiveInt,
+} from '../../core/validation/index.js';
 
 /**
  * A single rhythmic note: an onset position and how long it sounds.
@@ -113,12 +118,17 @@ export function generateRhythm(ts: TimeSignature, opts: RhythmOptions = {}): Rhy
   const seed = opts.seed ?? 0;
   const bars = opts.bars ?? DEFAULT_BARS;
   const subdivision = opts.subdivision ?? DEFAULT_SUBDIVISION;
-  const density = Math.min(1, Math.max(0, opts.density ?? DEFAULT_DENSITY));
+  const requestedDensity = assertFiniteNumber(opts.density ?? DEFAULT_DENSITY, 'rhythm density');
+  const density = Math.min(1, Math.max(0, requestedDensity));
+
+  assertPositiveInt(bars, 'rhythm bars');
+  assertPositiveInt(subdivision, 'rhythm subdivision');
 
   const barBeats = beatsPerBar(ts);
   const spanBeats = barBeats * bars;
   const step = 1 / subdivision;
   const slotCount = Math.round(spanBeats * subdivision);
+  assertGenerationBudget(slotCount, 'rhythm grid slots');
   const slotsPerBar = Math.round(barBeats * subdivision);
   const rng = createRng(seed);
 

package/src/index.ts

@@ -1,247 +1,13 @@
-export type {
-  ArrangementAnalysis,
-  ArrangementOptions,
-  ArrangementTrack,
-  Conflict,
-  TensionPoint,
-  TrackAnalysis,
-  TrackRole,
-} from './analyze/arrange/index.js';
-export { analyzeArrangement, tensionCurve } from './analyze/arrange/index.js';
-export type { ChordMatch, KeyMatch } from './analyze/detect/index.js';
-export { detectChord, detectChordBest, detectKey } from './analyze/detect/index.js';
-export type {
-  BorrowedSource,
-  Cadence,
-  ChordAnalysis,
-  HarmonicFunction,
-} from './analyze/functional/index.js';
-export {
-  analyzeChord,
-  borrowedSource,
-  chordToRoman,
-  detectCadence,
-  functionOf,
-  isBorrowedChord,
-  isDiatonic,
-  isMinorKey,
-  parallelKey,
-  romanToChord,
-  secondaryDominant,
-} from './analyze/functional/index.js';
-export type {
-  CadenceHit,
-  ChordSegment,
-  ChordTimeline,
-  ChordTimelineOptions,
-  ChordTimelineResult,
-} from './analyze/timeline/index.js';
-export {
-  chordTimelineFromChords,
-  chordTimelineFromNotes,
-  detectCadences,
-} from './analyze/timeline/index.js';
-export type { AnalyzedNote, TheoryLabel, VoiceNote } from './analyze/voice/index.js';
-export { analyzeVoice } from './analyze/voice/index.js';
-export {
-  classifyInterval,
-  IntervalQuality,
-  isConsonantInterval,
-  isPerfectInterval,
-} from './core/interval/index.js';
-export type { BarPosition, TimeSignature } from './core/meter/index.js';
-export {
-  barPositionToBeat,
-  beatsPerBar,
-  beatToBarPosition,
-  formatTimeSignature,
-  isCompound,
-  isStrongBeat,
-  metricWeight,
-  parseTimeSignature,
-  pulsesPerBar,
-  tuplet,
-} from './core/meter/index.js';
-export type { Note as NoteData, SpelledInterval } from './core/pitch/index.js';
-export {
-  formatNote,
-  midiToNote,
-  noteToMidi,
-  noteToPitchClass,
-  parseNote,
-  spelledInterval,
-} from './core/pitch/index.js';
-export type { Rng } from './core/random/index.js';
-export { createRng } from './core/random/index.js';
-export type { Tuning } from './core/tuning/index.js';
-export {
-  centsBetweenFreq,
-  centsOfSteps,
-  edo,
-  frequencyOf,
-  JUST_RATIOS,
-  justDeviationCents,
-  nearestStep,
-  ratioToCents,
-  TWELVE_TET,
-} from './core/tuning/index.js';
-export type { KeyScale, NoteEvent } from './core/types.js';
-export type { BassLineOptions, BassSegment, BassStyle } from './generate/bass/index.js';
-export { generateBassLine } from './generate/bass/index.js';
-export type { CounterMelodyOptions } from './generate/countermelody/index.js';
-export { generateCounterMelody } from './generate/countermelody/index.js';
-export type {
-  DrumHit,
-  DrumRole,
-  DrumsOptions,
-  EuclideanKick,
-  GrooveFeel,
-  GrooveStyle,
-  Section,
-} from './generate/drums/index.js';
-export { generateDrums } from './generate/drums/index.js';
-export type { GrooveSlot, GrooveTemplate, HumanizeOptions } from './generate/groove/index.js';
-export { applyGrooveTemplate, extractGrooveTemplate, humanize } from './generate/groove/index.js';
-export type {
-  HarmonizeOptions,
-  HarmonizeResult,
-  MelodyNote,
-} from './generate/harmonize/index.js';
-export { harmonizeMelody } from './generate/harmonize/index.js';
-export type {
-  MotifCell,
-  MotifContour,
-  MotifNote,
-  MotifOptions,
-  MotifTransform,
-} from './generate/motif/index.js';
-export { developMotif, generateMotif, transformMotif } from './generate/motif/index.js';
-export type {
-  ChordSpan,
-  ProgFunction,
-  ProgressionOptions,
-  ProgressionPreset,
-  ProgStyle,
-} from './generate/progression/index.js';
-export {
-  generateProgression,
-  progressions,
-  progressionsByStyle,
-} from './generate/progression/index.js';
-export type {
-  BorrowedChord,
-  SubstituteOptions,
-  Substitution,
-  SubstitutionType,
-} from './generate/reharmony/index.js';
-export {
-  modalInterchangePalette,
-  negativeHarmonyMirror,
-  substituteChord,
-} from './generate/reharmony/index.js';
-export type { RhythmEvent, RhythmOptions } from './generate/rhythm/index.js';
-export { generateRhythm, onsetWeightCurve, rhythmDensity } from './generate/rhythm/index.js';
-export { Chord, Interval, Key, Note, Progression } from './model/index.js';
-export type { Chord as ChordData, ChordQuality } from './theory/chord/index.js';
-export {
-  chordFromDegree,
-  chordPitchClasses,
-  chordQualities,
-  chordToneRole,
-  diatonicSeventh,
-  diatonicTriad,
-  makeChord,
-} from './theory/chord/index.js';
-export type {
-  ChordScaleMatch,
-  ChordScaleReportEntry,
-  ScaleChoice,
-} from './theory/chordscale/index.js';
-export {
-  availableTensions,
-  avoidNotes,
-  chordScaleReport,
-  chordScales,
-  scaleMatchesChord,
-  scalesForChanges,
-} from './theory/chordscale/index.js';
-export {
-  createsHiddenParallelPerfect,
-  createsParallelOctave,
-  createsParallelPerfect,
-  createsParallelUnison,
-  createsVerticalDissonance,
-  createsVoiceCrossing,
-  createsVoiceOverlap,
-  exceedsSpacing,
-  isForbiddenMelodicLeap,
-  isLeadingToneResolution,
-} from './theory/counterpoint/index.js';
-export type { HarmonyRole, LockLevel, VoicedRole } from './theory/harmony/index.js';
-export { roleOf } from './theory/harmony/index.js';
-export type {
-  SafetyProfile,
-  SafetyQuery,
-  SafetyResult,
-  VoiceSnapshot,
-} from './theory/safety/index.js';
-export {
-  enumerateSafePitches,
-  evaluateSafety,
-  NoteSafety,
-  ReasonFlag,
-} from './theory/safety/index.js';
-export {
-  BLUES_MASK,
-  CHROMATIC_MASK,
-  DORIAN_MASK,
-  diatonicPitchClasses,
-  HARMONIC_MINOR_MASK,
-  isScaleTone,
-  LOCRIAN_MASK,
-  LYDIAN_MASK,
-  MAJOR_MASK,
-  MAJOR_PENTATONIC_MASK,
-  MELODIC_MINOR_MASK,
-  MINOR_PENTATONIC_MASK,
-  MIXOLYDIAN_MASK,
-  majorKey,
-  maskFromOffsets,
-  minorKey,
-  NAMED_SCALES,
-  NATURAL_MINOR_MASK,
-  nearestScaleTone,
-  OCTATONIC_HALF_WHOLE_MASK,
-  OCTATONIC_WHOLE_HALF_MASK,
-  PHRYGIAN_MASK,
-  pitchToScaleDegree,
-  scaleByName,
-  scaleTonesInDegreeOrder,
-  WHOLE_TONE_MASK,
-} from './theory/scale/index.js';
-export {
-  noteNames,
-  spellChord,
-  spellPitchClass,
-  spellPitchClasses,
-  spellScale,
-} from './theory/spelling/index.js';
-export {
-  formatChordSymbol,
-  parseChordSymbol,
-  transposeChordSymbol,
-} from './theory/symbol/index.js';
-export type {
-  StyledVoicingOptions,
-  VoiceRange,
-  VoicingOptions,
-  VoicingStyle,
-} from './theory/voicing/index.js';
-export {
-  nextVoicing,
-  SATB_RANGES,
-  voiceChord,
-  voiceChordStyled,
-  voiceLeadingCost,
-  voiceProgression,
-} from './theory/voicing/index.js';
+/**
+ * Complete public API.
+ *
+ * Each layer barrel is the canonical source of that layer's runtime and type
+ * exports. The package root composes those barrels so a symbol added to a
+ * public layer cannot silently disappear from the root entry point.
+ */
+
+export * from './analyze/index.js';
+export * from './core/index.js';
+export * from './generate/index.js';
+export * from './model/index.js';
+export * from './theory/index.js';