@libraz/libcantus 1.1.0 → 1.3.0

package/dist/{chunk-R5VUXQMP.js → chunk-CPMB7P75.js}

@@ -1,16 +1,40 @@
 import {
+  CADENCE_TYPES,
+  DEFAULT_VARIATION_THRESHOLD,
   HUMANIZE_ADJACENCY,
+  MELODIC_CONTOUR_SHAPES,
+  MOTIF_RELATION_KINDS,
+  RHYTHM_IOI_BINS,
+  analyzeRhythm,
+  analyzeVoice,
   assertChordTimeline,
+  assertReferenceProfile,
+  barSpanOf,
   borrowedSource,
+  chordTimelineFromChords,
   chordToRoman,
+  contourSimilarity,
+  densitySimilarity,
   detectChordBest,
+  durationSimilarity,
   functionOf,
+  ioiBinIndex,
   isDiatonic,
   isMinorKey,
-  parallelKey
-} from "./chunk-VLE5R7PF.js";
+  keyLookup,
+  melodicSimilarity,
+  onsetSimilarity,
+  parallelKey,
+  phraseMelody,
+  registerSimilarity,
+  rhythmLevel,
+  romanToChord,
+  syncopationSimilarity
+} from "./chunk-GNVN4PPJ.js";
 import {
+  ALGORITHM_VERSION,
   LIMBS,
+  MIN_ALGORITHM_VERSION,
   canSound,
   createPositionalRng,
   deriveSeed,
@@ -19,14 +43,14 @@ import {
   instrumentRange,
   resolveAlgorithmVersion,
   toStringedProfile
-} from "./chunk-X6RJAHII.js";
+} from "./chunk-7KG3RTYS.js";
 import {
   createNoteEventIndex
-} from "./chunk-7GOKQJTQ.js";
+} from "./chunk-PUKJP2Z5.js";
 import {
   chordScales,
   roleOf
-} from "./chunk-H66ARFU5.js";
+} from "./chunk-NB25P3EH.js";
 import {
   chordPitchClasses,
   chordQualities,
@@ -50,26 +74,33 @@ import {
   resolveKey,
   scaleLadderPitch,
   scaleLadderPosition,
+  scaleOf,
   scaleSystemOf,
   scaleTonesInDegreeOrder,
   shiftByScaleDegrees,
   soundsDominantSeventh,
+  spanFromChord,
   spellPitchClass,
   toChordData,
   toKeyScale,
   tonicizableDegrees
-} from "./chunk-FPBZFNCD.js";
+} from "./chunk-RFIBF2RR.js";
 import {
   ARTICULATIONS,
   BEAT_EPS,
   InvalidInputError,
+  NoSolutionError,
+  allocateCandidateTable,
+  allocateChoiceTable,
   assertArray,
   assertDegree,
   assertFiniteNumber,
   assertFiniteSemitones,
+  assertFlag,
   assertFunction,
   assertGenerationBudget,
   assertInteger,
+  assertMeterMap,
   assertMidiPitch,
   assertNoteEvents,
   assertOneOf,
@@ -78,7 +109,9 @@ import {
   assertRange,
   assertRecord,
   assertTimeSignature,
+  barStartBeat,
   beatsPerBar,
+  beatsPerBarAt,
   clampToMidi,
   describeRejected,
   dropSilentNotes,
@@ -92,10 +125,12 @@ import {
   pulseBeats,
   resolveMeters,
   soundingNotesOnly,
+  spelledInterval,
   toMeterData,
   toSpelledInterval,
+  transposeByInterval,
   transposeNote
-} from "./chunk-PQL7E5F6.js";
+} from "./chunk-AGOVW7U6.js";
 
 // src/generate/context/draw.ts
 var DRAW_METHODS = ["at", "prob", "range", "float"];
@@ -4837,6 +4872,1063 @@ function developMotif(cell, timeline, key, bars, ts) {
   return inTimeOrder({ notes: out });
 }
 
+// src/generate/plan/internal.ts
+var STRONG_WEIGHT = 2;
+function positionClass(beat, meters) {
+  const weight = metricWeight(beat, meters);
+  return weight >= STRONG_WEIGHT ? "strong" : weight > 0 ? "weak" : "off";
+}
+
+// src/generate/plan/types.ts
+var COMPOSITION_PLAN_VERSION = 1;
+function tent(t, apex) {
+  if (t <= apex) {
+    return apex === 0 ? 1 : -1 + 2 * t / apex;
+  }
+  return apex === 1 ? 1 : 1 - 2 * (t - apex) / (1 - apex);
+}
+function plannedContourAt(shape, peakPosition, t) {
+  switch (shape) {
+    case "arch":
+      return tent(t, peakPosition);
+    case "ascending":
+      return -1 + 2 * t;
+    case "descending":
+      return 1 - 2 * t;
+    case "wave":
+      return t < 0.5 ? tent(2 * t, 0.5) : tent(2 * t - 1, 0.5);
+    case "static":
+      return 0;
+  }
+}
+
+// src/generate/plan/validate.ts
+var MASS_TOLERANCE = 1e-9;
+function assertString(value, name) {
+  if (typeof value !== "string") {
+    throw new InvalidInputError(`${name} must be a string; received ${describeRejected(value)}`);
+  }
+  return value;
+}
+function assertSpanOrder(startBeat, endBeat, name) {
+  if (endBeat < startBeat) {
+    throw new InvalidInputError(
+      `${name}.endBeat must be at least ${name}.startBeat; received ${endBeat} < ${startBeat}`
+    );
+  }
+}
+function assertNullable(value, name, validate) {
+  if (value === void 0) {
+    throw new InvalidInputError(`${name} must be present; received undefined`);
+  }
+  return value === null ? null : validate(value, name);
+}
+function assertMassDistribution(value, length, name) {
+  const shares = assertArray(value, name);
+  if (shares.length !== length) {
+    throw new InvalidInputError(`${name} must have length ${length}; received ${shares.length}`);
+  }
+  let sum = 0;
+  for (let index = 0; index < shares.length; index += 1) {
+    const share = assertFiniteNumber(shares[index], `${name}[${index}]`);
+    if (share < 0) {
+      throw new InvalidInputError(`${name}[${index}] must be at least 0; received ${share}`);
+    }
+    sum += share;
+  }
+  if (Math.abs(sum - 1) > MASS_TOLERANCE) {
+    throw new InvalidInputError(`${name} must sum to 1; received ${sum}`);
+  }
+  return shares;
+}
+function assertResolvedKeyField(value, name) {
+  const read = assertRecord(value, name);
+  try {
+    resolveKey(read);
+  } catch (error) {
+    if (error instanceof InvalidInputError) {
+      throw new InvalidInputError(`${name} must be a valid key: ${error.message}`);
+    }
+    throw error;
+  }
+  return read;
+}
+function assertPlannedSection(value, name) {
+  const read = assertRecord(value, name);
+  assertString(read.label, `${name}.label`);
+  const startBeat = assertFiniteNumber(read.startBeat, `${name}.startBeat`);
+  const endBeat = assertFiniteNumber(read.endBeat, `${name}.endBeat`);
+  assertSpanOrder(startBeat, endBeat, name);
+  return read;
+}
+function assertPlannedPhrase(value, name, sectionCount, motifCount) {
+  const read = assertRecord(value, name);
+  const startBeat = assertFiniteNumber(read.startBeat, `${name}.startBeat`);
+  const endBeat = assertFiniteNumber(read.endBeat, `${name}.endBeat`);
+  assertSpanOrder(startBeat, endBeat, name);
+  assertNullable(
+    read.section,
+    `${name}.section`,
+    (v, n) => assertInteger(v, n, 0, Math.max(sectionCount - 1, 0))
+  );
+  assertNullable(read.cadence, `${name}.cadence`, (v, n) => assertOneOf(v, CADENCE_TYPES, n));
+  assertOneOf(read.shape, MELODIC_CONTOUR_SHAPES, `${name}.shape`);
+  assertRange(read.peakPosition, 0, 1, `${name}.peakPosition`);
+  const register = assertRecord(
+    read.register,
+    `${name}.register`
+  );
+  assertMidiPitch(register.low, `${name}.register.low`);
+  assertMidiPitch(register.high, `${name}.register.high`);
+  assertRange(register.mean, 0, 127, `${name}.register.mean`);
+  assertRange(read.onsetDensity, 0, Number.MAX_SAFE_INTEGER, `${name}.onsetDensity`);
+  const motifs = assertArray(read.motifs, `${name}.motifs`);
+  for (let index = 0; index < motifs.length; index += 1) {
+    assertInteger(
+      motifs[index],
+      `${name}.motifs[${index}]`,
+      0,
+      Math.max(motifCount - 1, 0)
+    );
+  }
+  return read;
+}
+function assertPlannedChord(value, name, keys) {
+  const read = assertRecord(value, name);
+  const startBeat = assertFiniteNumber(read.startBeat, `${name}.startBeat`);
+  const endBeat = assertFiniteNumber(read.endBeat, `${name}.endBeat`);
+  assertSpanOrder(startBeat, endBeat, name);
+  const keyIndex = assertInteger(read.key, `${name}.key`, 0, Math.max(keys.length - 1, 0));
+  const roman = assertString(read.roman, `${name}.roman`);
+  try {
+    romanToChord(roman, keys[keyIndex]);
+  } catch (error) {
+    if (error instanceof InvalidInputError) {
+      throw new InvalidInputError(
+        `${name}.roman must be readable by romanToChord; received ${describeRejected(roman)}: ${error.message}`
+      );
+    }
+    throw error;
+  }
+  return read;
+}
+function assertPlannedMotifRelation(value, name) {
+  const read = assertRecord(value, name);
+  assertOneOf(read.kind, MOTIF_RELATION_KINDS, `${name}.kind`);
+  assertFlag(read.sequence, `${name}.sequence`);
+  assertFiniteNumber(read.semitones, `${name}.semitones`);
+  if (read.kind === "tonalTransposition") {
+    assertFiniteNumber(read.degrees, `${name}.degrees`);
+  } else if (read.degrees !== void 0) {
+    assertFiniteNumber(read.degrees, `${name}.degrees`);
+  }
+  const timeRatio = assertFiniteNumber(read.timeRatio, `${name}.timeRatio`);
+  if (timeRatio <= 0) {
+    throw new InvalidInputError(`${name}.timeRatio must be positive; received ${timeRatio}`);
+  }
+  return read;
+}
+function assertPlannedMotif(value, name, ownIndex, motifCount, phraseCount) {
+  const read = assertRecord(value, name);
+  assertInteger(read.phrase, `${name}.phrase`, 0, Math.max(phraseCount - 1, 0));
+  const startBeat = assertFiniteNumber(read.startBeat, `${name}.startBeat`);
+  const endBeat = assertFiniteNumber(read.endBeat, `${name}.endBeat`);
+  assertSpanOrder(startBeat, endBeat, name);
+  assertPositiveInt(read.notes, `${name}.notes`);
+  const from = assertNullable(
+    read.from,
+    `${name}.from`,
+    (v, n) => assertInteger(v, n, 0, Math.max(motifCount - 1, 0))
+  );
+  if (from !== null && from >= ownIndex) {
+    throw new InvalidInputError(
+      `${name}.from must be less than this motif's own index (${ownIndex}); received ${from}`
+    );
+  }
+  const relation = assertNullable(read.relation, `${name}.relation`, assertPlannedMotifRelation);
+  if (from === null && relation !== null) {
+    throw new InvalidInputError(
+      `${name}.relation must be null for a root motif (from = null); received a relation`
+    );
+  }
+  const rhythm = assertNullable(read.rhythm, `${name}.rhythm`, (v, n) => assertArray(v, n));
+  if (rhythm !== null) {
+    if (from !== null) {
+      throw new InvalidInputError(`${name}.rhythm must be null for a derived statement`);
+    }
+    if (rhythm.length !== read.notes - 1) {
+      throw new InvalidInputError(
+        `${name}.rhythm must hold notes - 1 (${read.notes - 1}) gaps; received ${rhythm.length}`
+      );
+    }
+    let total = 0;
+    for (let index = 0; index < rhythm.length; index += 1) {
+      const gap = assertFiniteNumber(rhythm[index], `${name}.rhythm[${index}]`);
+      if (gap <= 0) {
+        throw new InvalidInputError(`${name}.rhythm[${index}] must be positive; received ${gap}`);
+      }
+      total += gap;
+    }
+    if (total >= endBeat - startBeat - BEAT_EPS) {
+      throw new InvalidInputError(
+        `${name}.rhythm must sum to less than the statement's length (${endBeat - startBeat}); received ${total}`
+      );
+    }
+  }
+  return read;
+}
+function assertPlannedRhythm(value, name) {
+  const read = assertRecord(value, name);
+  assertMassDistribution(read.onsetLevels, 6, `${name}.onsetLevels`);
+  assertMassDistribution(read.interOnsetShares, RHYTHM_IOI_BINS.length, `${name}.interOnsetShares`);
+  assertRange(read.syncopation, 0, 1, `${name}.syncopation`);
+  return read;
+}
+function assertCompositionPlan(value, name = "composition plan") {
+  const read = assertRecord(value, name);
+  if (read.planVersion !== COMPOSITION_PLAN_VERSION) {
+    throw new InvalidInputError(
+      `${name}.planVersion must be ${COMPOSITION_PLAN_VERSION}; received ${describeRejected(read.planVersion)}`
+    );
+  }
+  assertInteger(read.seed, `${name}.seed`, 0, 4294967295);
+  assertInteger(
+    read.algorithmVersion,
+    `${name}.algorithmVersion`,
+    MIN_ALGORITHM_VERSION,
+    ALGORITHM_VERSION
+  );
+  const keys = assertArray(read.keys, `${name}.keys`);
+  if (keys.length === 0) {
+    throw new InvalidInputError(`${name}.keys must hold at least one key; received an empty array`);
+  }
+  for (let index = 0; index < keys.length; index += 1) {
+    assertResolvedKeyField(keys[index], `${name}.keys[${index}]`);
+  }
+  assertMeterMap(read.meters, `${name}.meters`);
+  const span = assertRecord(
+    read.span,
+    `${name}.span`
+  );
+  const spanStart = assertFiniteNumber(span.startBeat, `${name}.span.startBeat`);
+  const spanEnd = assertFiniteNumber(span.endBeat, `${name}.span.endBeat`);
+  assertSpanOrder(spanStart, spanEnd, `${name}.span`);
+  assertRange(span.bars, 0, Number.MAX_SAFE_INTEGER, `${name}.span.bars`);
+  const sections = assertArray(read.sections, `${name}.sections`);
+  for (let index = 0; index < sections.length; index += 1) {
+    assertPlannedSection(sections[index], `${name}.sections[${index}]`);
+  }
+  const phrases = assertArray(read.phrases, `${name}.phrases`);
+  const motifs = assertArray(read.motifs, `${name}.motifs`);
+  for (let index = 0; index < phrases.length; index += 1) {
+    assertPlannedPhrase(
+      phrases[index],
+      `${name}.phrases[${index}]`,
+      sections.length,
+      motifs.length
+    );
+  }
+  const harmony = assertArray(read.harmony, `${name}.harmony`);
+  for (let index = 0; index < harmony.length; index += 1) {
+    assertPlannedChord(harmony[index], `${name}.harmony[${index}]`, keys);
+  }
+  for (let index = 0; index < motifs.length; index += 1) {
+    assertPlannedMotif(
+      motifs[index],
+      `${name}.motifs[${index}]`,
+      index,
+      motifs.length,
+      phrases.length
+    );
+  }
+  assertPlannedRhythm(read.rhythm, `${name}.rhythm`);
+  return read;
+}
+
+// src/generate/plan/timeline.ts
+function planTimeline(plan) {
+  return planChordTimeline(assertCompositionPlan(plan));
+}
+function planChordTimeline(plan) {
+  const spans = plan.harmony.map((chord) => {
+    const key = plan.keys[chord.key];
+    return spanFromChord(romanToChord(chord.roman, key), chord.startBeat);
+  });
+  return chordTimelineFromChords(spans, plan.span.endBeat);
+}
+
+// src/generate/plan/harmony.ts
+var HARMONY_OK_KINDS = /* @__PURE__ */ new Set([
+  "chordTone",
+  "tension",
+  "suspension",
+  "appoggiatura",
+  "anticipation",
+  "passing",
+  "neighbor"
+]);
+var CADENCE_DEGREES = {
+  authentic: [1, 3],
+  plagal: [1, 3],
+  half: [2, 5, 7],
+  phrygian: [2, 5, 7],
+  modal: [1]
+};
+function planKeyAt(plan) {
+  const regions = [...plan.harmony].sort((a, b) => a.startBeat - b.startBeat).map((chord) => ({
+    startBeat: chord.startBeat,
+    endBeat: chord.endBeat,
+    key: plan.keys[chord.key],
+    confidence: 1
+  }));
+  return keyLookup(regions, plan.keys[0]);
+}
+function cadencePitchClasses(plan, timeline, cadence, beat) {
+  if (cadence === "deceptive") {
+    const chord = timeline.at(beat);
+    return chord === null ? null : chordPitchClasses(chord);
+  }
+  const entry = plan.harmony.find((chord) => beat >= chord.startBeat && beat < chord.endBeat);
+  const tones = scaleTonesInDegreeOrder(scaleOf(plan.keys[entry?.key ?? 0]));
+  return CADENCE_DEGREES[cadence].map((degree) => tones[degree - 1]).filter((pc) => pc !== void 0);
+}
+function planHarmonyMisfits(plan, timeline = planChordTimeline(plan)) {
+  const keyAt = planKeyAt(plan);
+  const scaleAt2 = (beat) => scaleOf(keyAt(beat));
+  return (line) => {
+    const analyzed = analyzeVoice(line, timeline.at, scaleAt2);
+    return line.map((note2, index) => {
+      const position = positionClass(note2.startBeat, plan.meters);
+      if (position === "off") {
+        return null;
+      }
+      const kinds = (analyzed[index]?.labels ?? []).map((label) => label.kind);
+      if (kinds.some((kind) => HARMONY_OK_KINDS.has(kind))) {
+        return null;
+      }
+      return position === "weak" && isScaleTone(note2.pitch, scaleAt2(note2.startBeat)) ? null : kinds;
+    });
+  };
+}
+
+// src/generate/melody/pitch-dp.ts
+var NO_LEAP = 0;
+var LEAP_UP = 1;
+var LEAP_DOWN = 2;
+var LEAP_STATES = 3;
+var SEARCH_LABEL = "melody pitch search";
+var WIDEST_THIRD = 4;
+var LEAP_CONTINUATION_COST = 0.5;
+function intervalCost(size) {
+  if (size === 0) {
+    return 0.2;
+  }
+  if (size <= 2) {
+    return 0;
+  }
+  if (size <= WIDEST_THIRD) {
+    return 0.3;
+  }
+  if (size <= 7) {
+    return 0.6;
+  }
+  return 1;
+}
+function leapOf(delta) {
+  if (Math.abs(delta) <= WIDEST_THIRD) {
+    return NO_LEAP;
+  }
+  return delta > 0 ? LEAP_UP : LEAP_DOWN;
+}
+function stepCost(from, to, leap, bothFixed) {
+  const delta = to - from;
+  const size = Math.abs(delta);
+  if (!bothFixed && isForbiddenMelodicLeap(from, to)) {
+    return Number.POSITIVE_INFINITY;
+  }
+  let cost = intervalCost(size);
+  if (leap === LEAP_UP && delta > 0 || leap === LEAP_DOWN && delta < 0) {
+    cost += LEAP_CONTINUATION_COST;
+  }
+  return cost;
+}
+function searchPitches(slots, budget, extra) {
+  const first = slots[0];
+  if (first === void 0) {
+    return [];
+  }
+  let previous = allocateCandidateTable(
+    first.candidates.length,
+    LEAP_STATES,
+    SEARCH_LABEL,
+    budget
+  ).fill(Number.POSITIVE_INFINITY);
+  for (let j = 0; j < first.candidates.length; j += 1) {
+    previous[j * LEAP_STATES + NO_LEAP] = first.cost(first.candidates[j]);
+  }
+  const backs = [];
+  for (let k = 1; k < slots.length; k += 1) {
+    const before = slots[k - 1];
+    const slot = slots[k];
+    const unary = slot.candidates.map((pitch) => slot.cost(pitch));
+    const current = allocateCandidateTable(
+      slot.candidates.length,
+      LEAP_STATES,
+      SEARCH_LABEL,
+      budget
+    ).fill(Number.POSITIVE_INFINITY);
+    const back = allocateChoiceTable(
+      slot.candidates.length,
+      LEAP_STATES,
+      SEARCH_LABEL,
+      budget
+    ).fill(-1);
+    const bothFixed = before.fixed && slot.fixed;
+    for (let state2 = 0; state2 < previous.length; state2 += 1) {
+      const reached = previous[state2];
+      if (reached === Number.POSITIVE_INFINITY) {
+        continue;
+      }
+      const from = before.candidates[Math.floor(state2 / LEAP_STATES)];
+      const leap = state2 % LEAP_STATES;
+      for (let j = 0; j < slot.candidates.length; j += 1) {
+        const to = slot.candidates[j];
+        const step = stepCost(from, to, leap, bothFixed);
+        if (step === Number.POSITIVE_INFINITY) {
+          continue;
+        }
+        const total = reached + step + unary[j] + (extra ? extra(k, from, to) : 0);
+        const index = j * LEAP_STATES + leapOf(to - from);
+        if (total < current[index]) {
+          current[index] = total;
+          back[index] = state2;
+        }
+      }
+    }
+    backs.push(back);
+    previous = current;
+  }
+  let best = -1;
+  for (let state2 = 0; state2 < previous.length; state2 += 1) {
+    if (previous[state2] < Number.POSITIVE_INFINITY && (best < 0 || previous[state2] < previous[best])) {
+      best = state2;
+    }
+  }
+  if (best < 0) {
+    return null;
+  }
+  const pitches = new Array(slots.length);
+  let state = best;
+  for (let k = slots.length - 1; k >= 0; k -= 1) {
+    pitches[k] = slots[k].candidates[Math.floor(state / LEAP_STATES)];
+    if (k > 0) {
+      state = backs[k - 1][state];
+    }
+  }
+  return pitches;
+}
+
+// src/generate/melody/derive.ts
+var VARIATION_STEP_COST = 0.2;
+var OCTAVE = 12;
+var LEVEL_TARGET_COST = 0.1;
+var LEVEL_PLAN_COST = 0.02;
+var LEVEL_REACH = 24;
+var TONAL_LEVEL_REACH = 14;
+function stretched(cell, timeRatio) {
+  return timeRatio === 1 ? cell : transformMotif(cell, "augment", timeRatio);
+}
+function shaped(cell, relation) {
+  switch (relation.kind) {
+    case "repetition":
+    case "tonalTransposition":
+      return cell;
+    case "transposition":
+      return stretched(cell, relation.timeRatio);
+    case "inversion":
+      return stretched(transformMotif(cell, "invert"), relation.timeRatio);
+    case "retrograde":
+      return transformMotif(cell, "retrograde");
+    case "retrogradeInversion":
+      return transformMotif(transformMotif(cell, "invert"), "retrograde");
+    case "augmentation":
+      return transformMotif(cell, "augment", relation.timeRatio);
+    case "diminution":
+      return transformMotif(cell, "diminish", 1 / relation.timeRatio);
+  }
+}
+function relationLevels(kind, low = -LEVEL_REACH, high = LEVEL_REACH) {
+  const between = (from, to, skipZero) => {
+    const levels = [];
+    for (let level = Math.ceil(from); level <= to; level += 1) {
+      if (!(skipZero && level === 0)) levels.push(level);
+    }
+    return levels;
+  };
+  switch (kind) {
+    case "repetition":
+    case "augmentation":
+    case "diminution":
+      return [-OCTAVE, 0, OCTAVE];
+    case "transposition":
+      return between(low, high, true);
+    case "tonalTransposition":
+      return between(-TONAL_LEVEL_REACH, TONAL_LEVEL_REACH, true);
+    case "inversion":
+    case "retrograde":
+    case "retrogradeInversion":
+      return between(low, high, false);
+  }
+}
+function replayAt(source, relation, level, startBeat, key) {
+  const head = source[0];
+  const cell = shaped({ notes: source.map((n) => ({ ...n })) }, relation);
+  const first = cell.notes[0];
+  const offset = startBeat - first.startBeat;
+  const shift = head.pitch + level - first.pitch;
+  return cell.notes.map((n) => ({
+    ...n,
+    pitch: relation.kind === "tonalTransposition" ? shiftByScaleDegrees(n.pitch, level, key) : n.pitch + shift,
+    startBeat: n.startBeat + offset
+  }));
+}
+function clipStatement(notes, endBeat) {
+  return notes.filter((n) => n.startBeat < endBeat - BEAT_EPS).map((n) => ({ ...n, durationBeat: Math.min(n.durationBeat, endBeat - n.startBeat) }));
+}
+function outsideCount(notes, frame) {
+  return notes.filter((n) => n.pitch < frame.low || n.pitch > frame.high).length;
+}
+function nearerLevel(level, best, planned) {
+  const distance = Math.abs(level - planned);
+  const bestDistance = Math.abs(best - planned);
+  return distance < bestDistance || distance === bestDistance && level < best;
+}
+function repairStatement(notes, forced, frame) {
+  const slots = notes.map(
+    (n, index) => forced[index] ? {
+      candidates: frame.candidatesAt(n.startBeat),
+      cost: frame.costAt(n.startBeat),
+      fixed: false
+    } : { candidates: [n.pitch], cost: () => 0, fixed: true }
+  );
+  const pitches = searchPitches(slots, frame.budget);
+  if (pitches === null) {
+    throw new NoSolutionError(
+      `no repair fits the statement into the register ${frame.low}..${frame.high}`,
+      { at: frame.at }
+    );
+  }
+  return notes.map((n, index) => ({ ...n, pitch: pitches[index] }));
+}
+function placeDerived(source, relation, startBeat, endBeat, key, frame, before) {
+  const planned = relation.kind === "tonalTransposition" ? relation.degrees ?? 0 : relation.semitones;
+  const replay = (level) => clipStatement(replayAt(source, relation, level, startBeat, key), endBeat);
+  const base = replay(0).map((n) => n.pitch);
+  const levels = relationLevels(
+    relation.kind,
+    Math.max(-LEVEL_REACH, frame.low - Math.min(...base)),
+    Math.min(LEVEL_REACH, frame.high - Math.max(...base))
+  );
+  let best = null;
+  for (const level of levels) {
+    const notes2 = replay(level);
+    if (outsideCount(notes2, frame) > 0) {
+      continue;
+    }
+    const distance = notes2.reduce((sum, n) => sum + Math.abs(n.pitch - frame.targetAt(n.startBeat)), 0) / notes2.length;
+    const cost = frame.misfits(notes2, before) + LEVEL_TARGET_COST * distance + LEVEL_PLAN_COST * Math.abs(level - planned);
+    if (best === null || cost < best.cost || cost === best.cost && nearerLevel(level, best.level, planned)) {
+      best = { level, notes: notes2, cost };
+    }
+  }
+  if (best !== null) {
+    return best.notes;
+  }
+  let fallback = null;
+  for (const level of relationLevels(relation.kind)) {
+    const notes2 = replay(level);
+    const outside = outsideCount(notes2, frame);
+    if (fallback === null || outside < fallback.outside || outside === fallback.outside && nearerLevel(level, fallback.level, planned)) {
+      fallback = { level, notes: notes2, outside };
+    }
+  }
+  const notes = fallback.notes;
+  return repairStatement(
+    notes,
+    notes.map((n) => n.pitch < frame.low || n.pitch > frame.high),
+    frame
+  );
+}
+function varyStatement(source, startBeat, frame) {
+  const offset = startBeat - source[0].startBeat;
+  const last = source.length - 1;
+  const inside = (pitch) => pitch >= frame.low && pitch <= frame.high;
+  const outer = [source[0].pitch, source[last].pitch];
+  const shift = [0, OCTAVE, -OCTAVE].find((s) => outer.every((pitch) => inside(pitch + s)));
+  const notes = source.map((n) => ({ ...n, startBeat: n.startBeat + offset }));
+  const slots = notes.map(
+    (n, index) => (index === 0 || index === last) && shift !== void 0 ? { candidates: [n.pitch + shift], cost: () => 0, fixed: true } : {
+      candidates: frame.candidatesAt(n.startBeat),
+      cost: frame.costAt(n.startBeat),
+      fixed: false
+    }
+  );
+  const pitches = searchPitches(
+    slots,
+    frame.budget,
+    (index, from, to) => VARIATION_STEP_COST * Math.abs(
+      to - from - (source[index].pitch - source[index - 1].pitch)
+    )
+  );
+  if (pitches === null) {
+    throw new NoSolutionError(`no variation line fits the register ${frame.low}..${frame.high}`, {
+      at: frame.at
+    });
+  }
+  return notes.map((n, index) => ({ ...n, pitch: pitches[index] }));
+}
+
+// src/generate/melody/index.ts
+var RHYTHM_SUBDIVISION = 4;
+var OFF_SCALE_COST = 1;
+var TARGET_COST = 0.1;
+var TIE_BREAK = 1e-6;
+var SEARCH_STATES_SQUARED = 9;
+function melodyContext(plan, input) {
+  const fromPlan = { seed: plan.seed, algorithmVersion: plan.algorithmVersion };
+  if (input === void 0) {
+    return resolveContext(fromPlan);
+  }
+  if (typeof input === "number") {
+    return resolveContext({ ...fromPlan, seed: input });
+  }
+  const read = assertRecord(input, "ctx");
+  if (read.rng !== void 0) {
+    throw new InvalidInputError(
+      "ctx.rng cannot drive a melody: every onset and tie-break is drawn at an address of phrase and beat under a seed; pass a seed instead"
+    );
+  }
+  return resolveContext({
+    ...read,
+    seed: read.seed ?? plan.seed,
+    algorithmVersion: read.algorithmVersion ?? plan.algorithmVersion
+  });
+}
+function chordEntryAt(plan, beat) {
+  return plan.harmony.find((chord) => beat >= chord.startBeat && beat < chord.endBeat);
+}
+function scaleAt(scene, beat) {
+  return scene.scales[chordEntryAt(scene.plan, beat)?.key ?? 0];
+}
+function targetPitch(phrase, beat) {
+  const length = phrase.endBeat - phrase.startBeat;
+  const t = length > 0 ? Math.min(Math.max((beat - phrase.startBeat) / length, 0), 1) : 0;
+  const { low, high, mean } = phrase.register;
+  return mean + (high - low) / 2 * plannedContourAt(phrase.shape, phrase.peakPosition, t);
+}
+function registerPitches(phrase) {
+  const pitches = [];
+  for (let pitch = phrase.register.low; pitch <= phrase.register.high; pitch += 1) {
+    pitches.push(pitch);
+  }
+  return pitches;
+}
+function frameOf(scene, index) {
+  const phrase = scene.plan.phrases[index];
+  const { low, high } = phrase.register;
+  const register = registerPitches(phrase);
+  const draw = scene.ctx.part("melody");
+  return {
+    low,
+    high,
+    at: phrase.startBeat,
+    budget: scene.budget,
+    candidatesAt: (beat) => {
+      const position = positionClass(beat, scene.plan.meters);
+      const chord = scene.timeline.at(beat);
+      const tones = position === "strong" && chord !== null ? chordPitchClasses(chord) : null;
+      const scale = scaleAt(scene, beat);
+      const candidates = position === "off" ? register : tones !== null ? register.filter((pitch) => tones.includes(pitchClassOf(pitch))) : register.filter((pitch) => isScaleTone(pitch, scale));
+      if (candidates.length === 0) {
+        throw new NoSolutionError(
+          `no ${position} pitch at beat ${beat} fits the register ${low}..${high}`,
+          { at: phrase.startBeat }
+        );
+      }
+      return candidates;
+    },
+    costAt: (beat) => {
+      const off = positionClass(beat, scene.plan.meters) === "off";
+      const scale = scaleAt(scene, beat);
+      const target = targetPitch(phrase, beat);
+      return (pitch) => {
+        let cost = TARGET_COST * Math.abs(pitch - target);
+        if (off && !isScaleTone(pitch, scale)) {
+          cost += OFF_SCALE_COST;
+        }
+        return cost + draw.float(0, TIE_BREAK, index, "tie", beat, pitch);
+      };
+    },
+    targetAt: (beat) => targetPitch(phrase, beat),
+    misfits: (notes, before) => scene.harmonyMisfits([...before, ...notes]).slice(before.length).filter((kinds) => kinds !== null).length
+  };
+}
+function membersOf(plan) {
+  return plan.phrases.map((phrase, index) => {
+    const found = new Set(phrase.motifs);
+    plan.motifs.forEach((motif, m) => {
+      if (motif.phrase === index) {
+        found.add(m);
+      }
+    });
+    return [...found].sort(
+      (a, b) => (plan.motifs[a]?.startBeat ?? 0) - (plan.motifs[b]?.startBeat ?? 0) || a - b
+    );
+  });
+}
+function segmentsOf(scene, index) {
+  const phrase = scene.plan.phrases[index];
+  const segments = [];
+  let cursor = phrase.startBeat;
+  for (const m of scene.members[index]) {
+    const motif = scene.plan.motifs[m];
+    if (motif === void 0) {
+      continue;
+    }
+    if (motif.startBeat > cursor + BEAT_EPS) {
+      segments.push({ startBeat: cursor, endBeat: motif.startBeat, motif: null });
+    }
+    segments.push({ startBeat: motif.startBeat, endBeat: motif.endBeat, motif: m });
+    cursor = Math.max(cursor, motif.endBeat);
+  }
+  if (phrase.endBeat > cursor + BEAT_EPS) {
+    segments.push({ startBeat: cursor, endBeat: phrase.endBeat, motif: null });
+  }
+  return segments;
+}
+function notesAt(onsets, endBeat) {
+  return onsets.map((startBeat, i) => ({
+    pitch: 0,
+    startBeat,
+    durationBeat: (onsets[i + 1] ?? endBeat) - startBeat
+  }));
+}
+function onsetSlots(scene, startBeat, endBeat) {
+  const { meters } = scene.plan;
+  const slots = [startBeat];
+  let bar2 = barStartBeat(startBeat, meters);
+  while (bar2 < endBeat - BEAT_EPS) {
+    const barEnd = bar2 + beatsPerBarAt(bar2, meters);
+    for (let k = 0; bar2 + k / RHYTHM_SUBDIVISION < barEnd - BEAT_EPS; k += 1) {
+      const beat = bar2 + k / RHYTHM_SUBDIVISION;
+      if (beat > startBeat + BEAT_EPS && beat < endBeat - BEAT_EPS) {
+        slots.push(beat);
+      }
+    }
+    bar2 = barEnd;
+  }
+  return slots;
+}
+function drawOnsets(scene, phraseIndex, startBeat, endBeat, count) {
+  const slots = onsetSlots(scene, startBeat, endBeat);
+  assertGenerationBudget(slots.length * Math.max(1, count - 1), "melody onset slots", scene.budget);
+  if (count - 1 > slots.length - 1) {
+    throw new NoSolutionError(
+      `${count} onsets do not fit the sixteenth grid of beats ${startBeat}..${endBeat}`,
+      { at: scene.plan.phrases[phraseIndex].startBeat }
+    );
+  }
+  const levels = slots.map((beat) => rhythmLevel(beat, scene.plan.meters));
+  const perLevel = /* @__PURE__ */ new Map();
+  for (const level of levels) {
+    perLevel.set(level, (perLevel.get(level) ?? 0) + 1);
+  }
+  const levelWeight = levels.map(
+    (level) => (scene.plan.rhythm.onsetLevels[level] ?? 0) / perLevel.get(level)
+  );
+  const draw = scene.ctx.part("melody");
+  const onsets = [startBeat];
+  let current = 0;
+  for (let k = 1; k < count; k += 1) {
+    const last = slots.length - 1 - (count - 1 - k);
+    const candidates = [];
+    for (let j = current + 1; j <= last; j += 1) candidates.push(j);
+    const gapShare = (j) => scene.plan.rhythm.interOnsetShares[ioiBinIndex(slots[j] - slots[current])] ?? 0;
+    let weights = candidates.map((j) => levelWeight[j] * gapShare(j));
+    if (!weights.some((w) => w > 0)) weights = candidates.map((j) => levelWeight[j]);
+    if (!weights.some((w) => w > 0)) weights = candidates.map(() => 1);
+    const total = weights.reduce((sum, w) => sum + w, 0);
+    let target = draw.float(0, 1, phraseIndex, "onset", startBeat, k) * total;
+    let pick = candidates.length - 1;
+    for (let c = 0; c < candidates.length; c += 1) {
+      target -= weights[c];
+      if (target < 0) {
+        pick = c;
+        break;
+      }
+    }
+    current = candidates[pick];
+    onsets.push(slots[current]);
+  }
+  return notesAt(onsets, endBeat);
+}
+function placeRhythm(scene, motif) {
+  const { rhythm, startBeat, endBeat, notes } = motif;
+  if (rhythm === null) {
+    return drawOnsets(scene, motif.phrase, startBeat, endBeat, notes);
+  }
+  const onsets = [startBeat];
+  for (const gap of rhythm) {
+    onsets.push(onsets.at(-1) + gap);
+  }
+  return notesAt(onsets, endBeat);
+}
+function searchedLine(rhythm, frame) {
+  const slots = rhythm.map((note2) => ({
+    candidates: frame.candidatesAt(note2.startBeat),
+    cost: frame.costAt(note2.startBeat),
+    fixed: false
+  }));
+  const pitches = searchPitches(slots, frame.budget);
+  if (pitches === null) {
+    throw new NoSolutionError(`no pitch line fits the register ${frame.low}..${frame.high}`, {
+      at: frame.at
+    });
+  }
+  return rhythm.map((note2, i) => ({ ...note2, pitch: pitches[i] }));
+}
+function statementOf(scene, m) {
+  const known = scene.statements.get(m);
+  if (known !== void 0) {
+    return known;
+  }
+  scene.inProgress.add(m);
+  const motif = scene.plan.motifs[m];
+  const frame = scene.frames[motif.phrase];
+  let notes;
+  if (motif.from === null) {
+    if (motif.endBeat - motif.startBeat <= BEAT_EPS) {
+      throw new NoSolutionError(`root motif ${m} spans no time to place its notes in`, {
+        at: frame.at
+      });
+    }
+    notes = searchedLine(placeRhythm(scene, motif), frame);
+  } else {
+    const source = statementOf(scene, motif.from);
+    notes = motif.relation === null ? varyStatement(source, motif.startBeat, frame) : placeDerived(
+      source,
+      motif.relation,
+      motif.startBeat,
+      motif.endBeat,
+      scaleAt(scene, motif.startBeat),
+      frame,
+      lineBefore(scene, motif.phrase, motif.startBeat)
+    );
+  }
+  scene.inProgress.delete(m);
+  scene.statements.set(m, notes);
+  return notes;
+}
+function freeNoteCount(scene, index, segment) {
+  const phrase = scene.plan.phrases[index];
+  const bars = barSpanOf(segment.startBeat, segment.endBeat, scene.plan.meters);
+  return Math.max(1, Math.round(phrase.onsetDensity * bars));
+}
+function freeSpan(scene, index, segment) {
+  const key = `${index}:${segment.startBeat}`;
+  const known = scene.free.get(key);
+  if (known !== void 0) {
+    return known;
+  }
+  const rhythm = drawOnsets(
+    scene,
+    index,
+    segment.startBeat,
+    segment.endBeat,
+    freeNoteCount(scene, index, segment)
+  );
+  const notes = searchedLine(rhythm, scene.frames[index]);
+  scene.free.set(key, notes);
+  return notes;
+}
+function lineBefore(scene, index, beat) {
+  const line = [];
+  for (const segment of segmentsOf(scene, index)) {
+    if (segment.endBeat > beat + BEAT_EPS) {
+      break;
+    }
+    if (segment.motif === null) {
+      line.push(...freeSpan(scene, index, segment));
+    } else if (!scene.inProgress.has(segment.motif)) {
+      line.push(...statementOf(scene, segment.motif));
+    }
+  }
+  return line.sort((a, b) => a.startBeat - b.startBeat);
+}
+function finalDownbeat(scene, index) {
+  const phrase = scene.plan.phrases[index];
+  const { meters } = scene.plan;
+  let downbeat = barStartBeat(phrase.startBeat, meters);
+  while (downbeat + beatsPerBarAt(downbeat, meters) < phrase.endBeat - BEAT_EPS) {
+    downbeat += beatsPerBarAt(downbeat, meters);
+  }
+  return Math.max(downbeat, phrase.startBeat);
+}
+function heldNoteIndex(scene, index, line, downbeat) {
+  const phrase = scene.plan.phrases[index];
+  const sounding2 = line.findIndex(
+    (note2) => note2.startBeat <= downbeat + BEAT_EPS && note2.startBeat + note2.durationBeat > downbeat + BEAT_EPS
+  );
+  return sounding2 >= 0 ? sounding2 : line.findIndex(
+    (note2) => note2.startBeat >= downbeat - BEAT_EPS && note2.startBeat < phrase.endBeat - BEAT_EPS
+  );
+}
+function repairCadence(scene, index, line, held) {
+  const phrase = scene.plan.phrases[index];
+  if (phrase.cadence === null) {
+    return;
+  }
+  let target = held;
+  for (let i = line.length - 1; target < 0 && i >= 0; i -= 1) {
+    if (positionClass(line[i].startBeat, scene.plan.meters) !== "off") {
+      target = i;
+    }
+  }
+  if (target < 0) {
+    return;
+  }
+  const note2 = line[target];
+  const allowed = cadencePitchClasses(scene.plan, scene.timeline, phrase.cadence, note2.startBeat);
+  if (allowed === null) {
+    return;
+  }
+  const frame = scene.frames[index];
+  const candidates = registerPitches(phrase).filter(
+    (pitch) => allowed.includes(pitchClassOf(pitch))
+  );
+  if (candidates.length === 0) {
+    throw new NoSolutionError(
+      `no pitch in the register ${frame.low}..${frame.high} can end the ${phrase.cadence} cadence`,
+      { at: frame.at }
+    );
+  }
+  if (allowed.includes(pitchClassOf(note2.pitch))) {
+    return;
+  }
+  const slots = line.map(
+    (n, i) => i === target ? { candidates, cost: frame.costAt(n.startBeat), fixed: false } : { candidates: [n.pitch], cost: () => 0, fixed: true }
+  );
+  const pitches = searchPitches(slots, frame.budget);
+  if (pitches === null) {
+    throw new NoSolutionError(`no cadence pitch joins its neighbours without an augmented step`, {
+      at: frame.at
+    });
+  }
+  note2.pitch = pitches[target];
+}
+function repickCutOnset(scene, index, line, held) {
+  const note2 = line[held];
+  const derived = scene.plan.motifs.some(
+    (motif) => motif.from !== null && note2.startBeat >= motif.startBeat - BEAT_EPS && note2.startBeat < motif.endBeat - BEAT_EPS
+  );
+  if (scene.plan.phrases[index].cadence !== null || derived) {
+    return;
+  }
+  const frame = scene.frames[index];
+  const candidates = frame.candidatesAt(note2.startBeat);
+  if (candidates.includes(note2.pitch)) {
+    return;
+  }
+  const slots = line.map(
+    (n, i) => i === held ? { candidates, cost: frame.costAt(n.startBeat), fixed: false } : { candidates: [n.pitch], cost: () => 0, fixed: true }
+  );
+  const pitches = searchPitches(slots, frame.budget);
+  if (pitches === null) {
+    throw new NoSolutionError(`no pitch at the final downbeat joins its neighbours`, {
+      at: frame.at
+    });
+  }
+  line[held] = { ...note2, pitch: pitches[held] };
+}
+function phraseLine(scene, index) {
+  const line = [];
+  for (const segment of segmentsOf(scene, index)) {
+    line.push(
+      ...segment.motif === null ? freeSpan(scene, index, segment) : statementOf(scene, segment.motif)
+    );
+  }
+  return line.sort((a, b) => a.startBeat - b.startBeat);
+}
+function chargePitchSearch(scene) {
+  const { plan } = scene;
+  let estimate = 0;
+  plan.phrases.forEach((phrase, index) => {
+    let searched = 0;
+    for (const segment of segmentsOf(scene, index)) {
+      const motif = segment.motif === null ? void 0 : plan.motifs[segment.motif];
+      if (motif === void 0) {
+        searched += freeNoteCount(scene, index, segment);
+      } else if (motif.relation === null) {
+        searched += motif.notes;
+      } else {
+        estimate += motif.notes * relationLevels(motif.relation.kind).length;
+      }
+    }
+    const register = Math.max(0, phrase.register.high - phrase.register.low + 1);
+    estimate += searched * SEARCH_STATES_SQUARED * register * register;
+  });
+  assertGenerationBudget(estimate, "melody pitch search", scene.budget);
+}
+function generateMelody(plan, opts) {
+  assertCompositionPlan(plan);
+  const asked = assertOptions(opts, "opts");
+  if (asked.budget !== void 0) {
+    assertPositiveInt(asked.budget, "budget", Number.MAX_SAFE_INTEGER);
+  }
+  const timeline = planChordTimeline(plan);
+  const scene = {
+    plan,
+    ctx: melodyContext(plan, asked.ctx),
+    budget: asked.budget,
+    timeline,
+    harmonyMisfits: planHarmonyMisfits(plan, timeline),
+    scales: plan.keys.map((key) => scaleOf(key)),
+    members: membersOf(plan),
+    frames: [],
+    statements: /* @__PURE__ */ new Map(),
+    free: /* @__PURE__ */ new Map(),
+    inProgress: /* @__PURE__ */ new Set()
+  };
+  scene.frames = plan.phrases.map((_, index) => frameOf(scene, index));
+  chargePitchSearch(scene);
+  const melody = [];
+  plan.phrases.forEach((_, index) => {
+    const line = phraseLine(scene, index);
+    const downbeat = finalDownbeat(scene, index);
+    let held = heldNoteIndex(scene, index, line, downbeat);
+    if (held >= 0) {
+      line.length = held + 1;
+      const note2 = line[held];
+      if (note2.startBeat < downbeat - BEAT_EPS) {
+        const cut = downbeat - note2.startBeat;
+        line[held] = { ...note2, durationBeat: cut };
+        line.push({ ...note2, startBeat: downbeat, durationBeat: note2.durationBeat - cut });
+        held += 1;
+        repickCutOnset(scene, index, line, held);
+      }
+    }
+    repairCadence(scene, index, line, held);
+    if (held >= 0) {
+      const note2 = line[held];
+      const phraseEnd = plan.phrases[index].endBeat;
+      line[held] = { ...note2, durationBeat: phraseEnd - note2.startBeat };
+    }
+    melody.push(...line);
+  });
+  melody.sort((a, b) => a.startBeat - b.startBeat);
+  return motifToNoteEvents({ notes: melody });
+}
+
 // src/generate/ornament/index.ts
 var ORNAMENT_STYLES = Object.freeze(["ghost", "flam", "drag", "slide", "accent"]);
 var DEFAULT_TS5 = { numerator: 4, denominator: 4 };
@@ -4961,6 +6053,878 @@ function strokeGaps(ordered) {
   return gaps;
 }
 
+// src/generate/plan/derive.ts
+var PRESERVE_ASPECTS = [
+  "form",
+  "phraseLengths",
+  "harmonicFunction",
+  "harmonicRhythm",
+  "motifRelations",
+  "registerShape",
+  "rhythm"
+];
+var NEUTRAL_SHAPE = "arch";
+var NEUTRAL_PEAK_POSITION = 0.6;
+var SHAPE_KEEP_THRESHOLD = 0.5;
+var NEUTRAL_ONSET_LEVELS = Object.freeze([0, 1, 2, 3, 4, 5].map((level) => level / 15));
+var FUNCTION_DEGREES = {
+  tonic: [1, 6, 3],
+  subdominant: [4, 2],
+  dominant: [5, 7]
+};
+var STRONG_WEIGHT2 = 2;
+var HEPTATONIC_DEGREES = 7;
+function mod12(value) {
+  return (value % 12 + 12) % 12;
+}
+function lerp(weight, reference, neutral) {
+  return weight * reference + (1 - weight) * neutral;
+}
+function readPreserve(value) {
+  const read = value === void 0 ? {} : assertRecord(value, "opts.preserve");
+  const weights = {};
+  for (const aspect of PRESERVE_ASPECTS) {
+    const weight = read[aspect];
+    weights[aspect] = weight === void 0 ? 1 : assertRange(weight, 0, 1, `opts.preserve.${aspect}`);
+  }
+  return weights;
+}
+function readRegister(value) {
+  const read = assertRecord(value, "opts.register");
+  const low = assertMidiPitch(read.low, "opts.register.low");
+  const high = assertMidiPitch(read.high, "opts.register.high");
+  if (low > high) {
+    throw new InvalidInputError(
+      `opts.register.low must not exceed opts.register.high; received ${low} > ${high}`
+    );
+  }
+  return { low, high };
+}
+function rejectSuppliedRng(ctx) {
+  if (typeof ctx === "object" && ctx !== null && ctx.rng !== void 0) {
+    throw new InvalidInputError(
+      "opts.ctx.rng is not accepted: a composition plan records its seed, not a source"
+    );
+  }
+}
+function plannedKeys(profile, requested) {
+  const regions = profile.harmony.keys.map(
+    ({ key }) => ({
+      scale: { ...key.scale },
+      tonic: { ...key.tonic },
+      variant: key.variant
+    })
+  );
+  const home = regions[0];
+  if (requested === void 0) {
+    return regions;
+  }
+  const target = resolveKey(requested);
+  if (target.variant !== home.variant || target.scale.modeMask12 !== home.scale.modeMask12) {
+    throw new InvalidInputError(
+      "opts.key must be in the same mode as the reference's home key; a key change moves the tonic only"
+    );
+  }
+  const step = spelledInterval(
+    { letter: home.tonic.letter, alter: home.tonic.alter },
+    { letter: target.tonic.letter, alter: target.tonic.alter }
+  );
+  const moved = regions.map(
+    (key) => ({
+      scale: {
+        rootPc: mod12(key.scale.rootPc + step.semitones),
+        modeMask12: key.scale.modeMask12
+      },
+      tonic: transposeByInterval({ letter: key.tonic.letter, alter: key.tonic.alter }, step),
+      variant: key.variant
+    })
+  );
+  moved[0] = target;
+  return moved;
+}
+function nearestBoundary(beat, boundaries) {
+  let best = beat;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (const boundary of boundaries) {
+    const distance = Math.abs(boundary - beat);
+    if (distance < bestDistance - BEAT_EPS) {
+      best = boundary;
+      bestDistance = distance;
+    }
+  }
+  return best;
+}
+function plannedSections(profile, weight, draw) {
+  const sections = profile.form.sections;
+  const boundaries = [profile.span.startBeat, profile.span.endBeat];
+  for (const phrase of profile.form.phrases) {
+    boundaries.push(phrase.startBeat, phrase.endBeat);
+  }
+  boundaries.sort((a, b) => a - b);
+  const planned = [];
+  sections.forEach((section, index) => {
+    const keep = sections.length < 2 || draw.prob(weight, "form", index);
+    const neighbour = index + 1 < sections.length ? index + 1 : index - 1;
+    const startBeat = nearestBoundary(section.startBeat, boundaries);
+    const endBeat = nearestBoundary(section.endBeat, boundaries);
+    if (endBeat - startBeat > BEAT_EPS) {
+      planned.push({
+        label: keep ? section.label : sections[neighbour]?.label ?? section.label,
+        startBeat,
+        endBeat
+      });
+    }
+  });
+  return planned;
+}
+function beatAfterBars(startBeat, bars, meters) {
+  let beat = startBeat;
+  let left = bars;
+  while (left > BEAT_EPS) {
+    const step = Math.min(1, left);
+    beat += step * beatsPerBarAt(beat, meters);
+    left -= step;
+  }
+  return beat;
+}
+function barsBetween(startBeat, endBeat, meters) {
+  let beat = startBeat;
+  let bars = 0;
+  while (beat < endBeat - BEAT_EPS) {
+    const barBeats = beatsPerBarAt(beat, meters);
+    const step = Math.min(barStartBeat(beat, meters) + barBeats, endBeat) - beat;
+    bars += step / barBeats;
+    beat += step;
+  }
+  return bars;
+}
+function spanSegments(profile, sections) {
+  const { startBeat, endBeat } = profile.span;
+  const cuts = [startBeat, endBeat];
+  for (const section of sections) {
+    for (const beat of [section.startBeat, section.endBeat]) {
+      if (beat > startBeat + BEAT_EPS && beat < endBeat - BEAT_EPS) cuts.push(beat);
+    }
+  }
+  cuts.sort((a, b) => a - b);
+  const segments = [];
+  for (let index = 1; index < cuts.length; index += 1) {
+    const from = cuts[index - 1];
+    const to = cuts[index];
+    if (to - from > BEAT_EPS) segments.push([from, to]);
+  }
+  return segments;
+}
+function plannedPhraseSpans(profile, sections, weight, draw) {
+  const segments = spanSegments(profile, sections);
+  const pieces = profile.form.phrases.map((phrase, source) => ({
+    startBeat: phrase.startBeat,
+    endBeat: phrase.endBeat,
+    source,
+    cadence: phrase.cadence?.type ?? null
+  }));
+  const replaced = pieces.map((_, index) => !draw.prob(weight, "phraseLengths", index));
+  const spans = [];
+  for (const [segmentStart, segmentEnd] of segments) {
+    const members = pieces.map((piece, index) => ({ piece, index })).filter(
+      ({ piece }) => piece.startBeat >= segmentStart - BEAT_EPS && piece.startBeat < segmentEnd - BEAT_EPS
+    );
+    const laid = [];
+    let cursor = segmentStart;
+    for (const { piece, index } of members) {
+      const lengths = [];
+      if (replaced[index]) {
+        const bars = barsBetween(piece.startBeat, piece.endBeat, profile.meters);
+        const rounded = 2 ** Math.round(Math.log2(bars));
+        const overflows = beatAfterBars(cursor, rounded, profile.meters) > segmentEnd + BEAT_EPS;
+        let partStart = cursor;
+        for (const part of overflows ? [rounded / 2, rounded / 2] : [rounded]) {
+          const partEnd = beatAfterBars(partStart, part, profile.meters);
+          lengths.push(partEnd - partStart);
+          partStart = partEnd;
+        }
+      } else {
+        lengths.push(piece.endBeat - piece.startBeat);
+      }
+      lengths.forEach((length, part) => {
+        if (cursor >= segmentEnd - BEAT_EPS) return;
+        const end = cursor + length;
+        laid.push({
+          startBeat: cursor,
+          endBeat: Math.min(end, segmentEnd),
+          source: piece.source,
+          cadence: part === lengths.length - 1 ? piece.cadence : null
+        });
+        cursor = end;
+      });
+    }
+    const last = laid.at(-1);
+    if (last) {
+      last.endBeat = segmentEnd;
+    } else {
+      laid.push({
+        startBeat: segmentStart,
+        endBeat: segmentEnd,
+        source: spans.at(-1)?.source ?? (profile.form.phrases.length > 0 ? 0 : -1),
+        cadence: null
+      });
+    }
+    spans.push(...laid);
+  }
+  return spans;
+}
+function sectionAt(sections, beat) {
+  const index = sections.findIndex(
+    (section) => beat >= section.startBeat - BEAT_EPS && beat < section.endBeat - BEAT_EPS
+  );
+  return index < 0 ? null : index;
+}
+function phraseHolding(phrases, startBeat, endBeat) {
+  return phrases.findIndex(
+    (phrase) => startBeat >= phrase.startBeat - BEAT_EPS && endBeat <= phrase.endBeat + BEAT_EPS
+  );
+}
+function better(a, b) {
+  for (let field = 0; field < a.length; field += 1) {
+    if (a[field] !== b[field]) return a[field] > b[field];
+  }
+  return false;
+}
+function scheduleMotifs(candidates, meters) {
+  const order = [...candidates].sort((a, b) => a.startBeat - b.startBeat || a.node - b.node);
+  const count = order.length;
+  const firstFrom = (from, beat) => {
+    let low = from;
+    let high = count;
+    while (low < high) {
+      const mid = low + high >> 1;
+      if (order[mid].startBeat < beat - BEAT_EPS) low = mid + 1;
+      else high = mid;
+    }
+    return low;
+  };
+  const next = order.map((candidate, index2) => firstFrom(index2 + 1, candidate.endBeat));
+  const own = order.map(
+    (candidate) => [
+      candidate.notes,
+      metricWeight(candidate.startBeat, meters) < STRONG_WEIGHT2 ? -1 : 0,
+      1
+    ]
+  );
+  const taking = (index2) => {
+    const rest = best[next[index2]];
+    const mine = own[index2];
+    return [mine[0] + rest[0], mine[1] + rest[1], mine[2] + rest[2]];
+  };
+  const best = new Array(count + 1).fill([0, 0, 0]);
+  for (let index2 = count - 1; index2 >= 0; index2 -= 1) {
+    const taken = taking(index2);
+    const skipped = best[index2 + 1];
+    best[index2] = better(taken, skipped) ? taken : skipped;
+  }
+  const chosen = [];
+  let index = 0;
+  while (index < count) {
+    if (!better(best[index], taking(index))) {
+      chosen.push(order[index]);
+      index = next[index];
+    } else {
+      index += 1;
+    }
+  }
+  return chosen.sort((a, b) => a.node - b.node);
+}
+function selectedDerivation(graph, parentEdge, selectedAt, node) {
+  let plain = true;
+  let semitones = 0;
+  let steps = 0;
+  for (let edge = parentEdge.get(node); edge !== void 0; edge = parentEdge.get(edge.from)) {
+    const relation = edge.relation;
+    steps += 1;
+    plain &&= relation !== null && (relation.kind === "repetition" || relation.kind === "transposition" && Math.abs(relation.timeRatio - 1) <= BEAT_EPS);
+    semitones += relation?.semitones ?? 0;
+    const from = selectedAt.get(edge.from);
+    if (from === void 0) continue;
+    if (steps === 1) {
+      return { from, relation: relation === null ? null : { ...relation } };
+    }
+    if (!plain) {
+      return { from: null, relation: null };
+    }
+    const gap = (graph.nodes[node]?.startBeat ?? 0) - (graph.nodes[edge.from]?.endBeat ?? 0);
+    return {
+      from,
+      relation: {
+        kind: semitones === 0 ? "repetition" : "transposition",
+        sequence: gap >= -HUMANIZE_ADJACENCY && gap <= HUMANIZE_ADJACENCY,
+        semitones,
+        timeRatio: 1
+      }
+    };
+  }
+  return { from: null, relation: null };
+}
+function functionCandidates(fn, key) {
+  if (scaleTonesInDegreeOrder(key).length !== HEPTATONIC_DEGREES) {
+    return null;
+  }
+  return FUNCTION_DEGREES[fn].map((degree) => chordToRoman(diatonicTriad(degree, key), key));
+}
+function plannedHarmony(profile, keys, preserve, draw) {
+  const chords = profile.harmony.chords;
+  const romans = chords.map((chord, index) => {
+    if (chord.level !== "structural" || draw.prob(preserve.harmonicFunction, "harmonicFunction", index)) {
+      return chord.roman;
+    }
+    const candidates = functionCandidates(chord.function, keys[chord.key]);
+    if (candidates === null) {
+      return chord.roman;
+    }
+    const pick = draw.range(0, candidates.length - 1, "harmonicFunction", index, "pick");
+    return candidates[pick];
+  });
+  const starts = [];
+  chords.forEach((chord, index) => {
+    const keep = index === 0 || draw.prob(preserve.harmonicRhythm, "harmonicRhythm", index);
+    const start = keep ? chord.startBeat : barStartBeat(chord.startBeat, profile.meters);
+    starts.push(index === 0 ? start : Math.max(start, starts[index - 1]));
+  });
+  const planned = [];
+  chords.forEach((chord, index) => {
+    const next = chords[index + 1];
+    const nextStart = starts[index + 1];
+    let endBeat = chord.endBeat;
+    if (next !== void 0 && nextStart !== void 0) {
+      endBeat = Math.abs(chord.endBeat - next.startBeat) <= BEAT_EPS ? nextStart : Math.min(chord.endBeat, nextStart);
+    }
+    const startBeat = starts[index];
+    if (endBeat - startBeat > BEAT_EPS) {
+      planned.push({ startBeat, endBeat, key: chord.key, roman: romans[index] });
+    }
+  });
+  return planned;
+}
+function plannedRhythm(profile, weight) {
+  const reference = profile.melody.rhythm;
+  return {
+    onsetLevels: reference.onsetLevels.map(
+      (share, level) => lerp(weight, share, NEUTRAL_ONSET_LEVELS[level])
+    ),
+    interOnsetShares: [...reference.interOnsetShares],
+    syncopation: lerp(weight, reference.syncopation, 0)
+  };
+}
+function deriveCompositionPlan(reference, opts) {
+  const profile = assertReferenceProfile(reference, "reference");
+  const asked = assertOptions(opts, "opts");
+  const preserve = readPreserve(asked.preserve);
+  const requestedRegister = asked.register === void 0 ? void 0 : readRegister(asked.register);
+  rejectSuppliedRng(asked.ctx);
+  const ctx = resolveContext(asked.ctx);
+  const draw = ctx.part("plan");
+  const melodyRegister = profile.melody.register;
+  if (profile.melody.rhythm.onsets === 0 || melodyRegister === null) {
+    throw new InvalidInputError("reference must carry melody onsets to derive a plan from");
+  }
+  const keys = plannedKeys(profile, asked.key);
+  const homeShift = mod12(
+    keys[0].scale.rootPc - (profile.harmony.keys[0]?.key.scale.rootPc ?? 0)
+  );
+  const shift = homeShift >= 6 ? homeShift - 12 : homeShift;
+  const source = { low: melodyRegister.low + shift, high: melodyRegister.high + shift };
+  if (source.low < 0 || source.high > 127) {
+    throw new InvalidInputError(
+      `the reference melody range moved to the new key leaves the MIDI range; received ${source.low}..${source.high}`
+    );
+  }
+  const target = requestedRegister ?? source;
+  const scale = source.high === source.low ? 0 : (target.high - target.low) / (source.high - source.low);
+  const offset = source.high === source.low ? (target.low + target.high) / 2 : target.low - source.low * scale;
+  const mapPitch = (pitch) => (pitch + shift) * scale + offset;
+  const neutralRegister = {
+    low: target.low,
+    high: target.high,
+    mean: (target.low + target.high) / 2
+  };
+  const sections = plannedSections(profile, preserve.form, draw);
+  const shapeWeight = preserve.registerShape;
+  const spans = plannedPhraseSpans(profile, sections, preserve.phraseLengths, draw);
+  const phrases = spans.map((span) => {
+    const melody = profile.form.phrases[span.source]?.melody ?? null;
+    const register = melody ? {
+      low: Math.round(lerp(shapeWeight, mapPitch(melody.low), neutralRegister.low)),
+      high: Math.round(lerp(shapeWeight, mapPitch(melody.high), neutralRegister.high)),
+      mean: lerp(shapeWeight, mapPitch(melody.mean), neutralRegister.mean)
+    } : { ...neutralRegister };
+    return {
+      startBeat: span.startBeat,
+      endBeat: span.endBeat,
+      section: sectionAt(sections, span.startBeat),
+      cadence: span.cadence,
+      shape: melody && shapeWeight >= SHAPE_KEEP_THRESHOLD ? melody.shape : NEUTRAL_SHAPE,
+      peakPosition: melody ? lerp(shapeWeight, melody.peakPosition, NEUTRAL_PEAK_POSITION) : NEUTRAL_PEAK_POSITION,
+      register,
+      onsetDensity: melody ? melody.onsetDensity : profile.melody.rhythm.onsetDensity,
+      motifs: []
+    };
+  });
+  const graph = profile.melody.graph;
+  const noteCount = (node) => (profile.melody.motifs[graph.nodes[node]?.motif ?? -1]?.intervals.length ?? 0) + 1;
+  assertGenerationBudget(graph.nodes.length * phrases.length, "plan motif selection", asked.budget);
+  const candidates = [];
+  graph.nodes.forEach((node, index) => {
+    const phrase = phraseHolding(phrases, node.startBeat, node.endBeat);
+    if (phrase >= 0) {
+      candidates.push({
+        node: index,
+        phrase,
+        startBeat: node.startBeat,
+        endBeat: node.endBeat,
+        notes: noteCount(index)
+      });
+    }
+  });
+  const selected = scheduleMotifs(candidates, profile.meters);
+  const selectedAt = new Map(selected.map((candidate, index) => [candidate.node, index]));
+  const parentEdge = new Map(graph.edges.map((edge) => [edge.to, edge]));
+  const motifs = selected.map((candidate, index) => {
+    const { from, relation } = selectedDerivation(graph, parentEdge, selectedAt, candidate.node);
+    const keepRelation = draw.prob(preserve.motifRelations, "motifRelations", index);
+    const keepRhythm = from === null && draw.prob(preserve.rhythm, "rhythm", index);
+    const cell = profile.melody.motifs[graph.nodes[candidate.node]?.motif ?? -1];
+    phrases[candidate.phrase]?.motifs.push(index);
+    return {
+      phrase: candidate.phrase,
+      startBeat: candidate.startBeat,
+      endBeat: candidate.endBeat,
+      notes: candidate.notes,
+      rhythm: keepRhythm && cell !== void 0 ? cell.rhythm.map((ratio) => ratio * cell.unitBeats) : null,
+      from,
+      relation: keepRelation ? relation : null
+    };
+  });
+  return {
+    planVersion: COMPOSITION_PLAN_VERSION,
+    seed: ctx.seed,
+    algorithmVersion: ctx.algorithmVersion,
+    keys,
+    meters: profile.meters.map((entry) => ({
+      startBeat: entry.startBeat,
+      ts: entry.ts.grouping === void 0 ? { ...entry.ts } : { ...entry.ts, grouping: [...entry.ts.grouping] }
+    })),
+    span: { ...profile.span },
+    sections,
+    phrases,
+    harmony: plannedHarmony(profile, keys, preserve, draw),
+    motifs,
+    rhythm: plannedRhythm(profile, preserve.rhythm)
+  };
+}
+
+// src/generate/plan/evaluate.ts
+var PEAK_POSITION_TOLERANCE = 0.2;
+var OUTLINE_POINTS = 8;
+var HELD_NOTE_BEATS = 1;
+function interiorBoundaries(plan) {
+  const beats = /* @__PURE__ */ new Set();
+  for (const phrase of plan.phrases) {
+    for (const beat of [phrase.startBeat, phrase.endBeat]) {
+      if (beat > plan.span.startBeat + BEAT_EPS && beat < plan.span.endBeat - BEAT_EPS) {
+        beats.add(beat);
+      }
+    }
+  }
+  return [...beats].sort((a, b) => a - b);
+}
+function restsOf(melody, plan) {
+  const rests = [];
+  let reach = plan.span.startBeat;
+  for (const note2 of [...melody].sort((a, b) => a.startBeat - b.startBeat)) {
+    if (note2.startBeat > reach + BEAT_EPS) {
+      rests.push({ startBeat: reach, endBeat: note2.startBeat });
+    }
+    reach = Math.max(reach, note2.startBeat + note2.durationBeat);
+  }
+  if (plan.span.endBeat > reach + BEAT_EPS) {
+    rests.push({ startBeat: reach, endBeat: plan.span.endBeat });
+  }
+  return rests;
+}
+function phraseBoundaryViolations(melody, plan) {
+  const rests = restsOf(melody, plan);
+  const violations = [];
+  for (const beat of interiorBoundaries(plan)) {
+    const pulse2 = pulseBeats(meterAt(beat, plan.meters));
+    const held = melody.some(
+      (note2) => note2.durationBeat >= HELD_NOTE_BEATS - BEAT_EPS && Math.abs(note2.startBeat + note2.durationBeat - beat) <= pulse2 + BEAT_EPS
+    );
+    const rested = rests.some(
+      (rest) => rest.endBeat - rest.startBeat >= pulse2 - BEAT_EPS && rest.startBeat <= beat + pulse2 + BEAT_EPS && rest.endBeat >= beat - pulse2 - BEAT_EPS
+    );
+    if (!held && !rested) {
+      violations.push({
+        kind: "phraseBoundary",
+        severity: "error",
+        atBeat: beat,
+        expected: `a note of at least ${HELD_NOTE_BEATS} beat(s) ending, or a rest of at least ${pulse2} beat(s), within ${pulse2} beat(s)`,
+        actual: "neither",
+        rationale: `the plan places a phrase boundary at beat ${beat}, which the candidate does not mark`
+      });
+    }
+  }
+  return violations;
+}
+function spanViolation(melody, plan) {
+  const end = melody.reduce((max, note2) => Math.max(max, note2.startBeat + note2.durationBeat), 0);
+  if (end <= plan.span.endBeat + BEAT_EPS) {
+    return [];
+  }
+  return [
+    {
+      kind: "span",
+      severity: "error",
+      atBeat: plan.span.endBeat,
+      expected: `ending by beat ${plan.span.endBeat}`,
+      actual: `ending at beat ${end}`,
+      rationale: "the candidate's last note runs past the plan's span"
+    }
+  ];
+}
+function phraseLines(melody, plan) {
+  return plan.phrases.map(
+    (phrase) => melody.flatMap(
+      (note2, index) => note2.startBeat >= phrase.startBeat - BEAT_EPS && note2.startBeat < phrase.endBeat - BEAT_EPS ? [index] : []
+    )
+  );
+}
+function cadenceViolations(melody, plan, timeline, lines) {
+  const violations = [];
+  plan.phrases.forEach((phrase, index) => {
+    if (phrase.cadence === null) {
+      return;
+    }
+    const last = lines[index]?.at(-1);
+    const note2 = last === void 0 ? void 0 : melody[last];
+    const allowed = note2 === void 0 ? [] : cadencePitchClasses(plan, timeline, phrase.cadence, note2.startBeat);
+    if (note2 !== void 0 && (allowed === null || allowed.includes(pitchClassOf(note2.pitch)))) {
+      return;
+    }
+    violations.push({
+      kind: "cadence",
+      severity: "error",
+      atBeat: phrase.endBeat,
+      expected: `a closing note on pitch class ${(allowed ?? []).join(" or ")} for a ${phrase.cadence} cadence`,
+      actual: note2 === void 0 ? "no note" : `pitch ${note2.pitch}`,
+      rationale: `the phrase ending at beat ${phrase.endBeat} is planned to close on a ${phrase.cadence} cadence`
+    });
+  });
+  return violations;
+}
+function harmonyViolations(melody, plan, timeline, lines) {
+  const misfits = planHarmonyMisfits(plan, timeline);
+  const violations = [];
+  for (const line of lines) {
+    const read = misfits(line.map((index) => melody[index]));
+    read.forEach((kinds, at2) => {
+      if (kinds === null) {
+        return;
+      }
+      const note2 = melody[line[at2]];
+      const derived = plan.motifs.some(
+        (motif) => motif.from !== null && note2.startBeat >= motif.startBeat - BEAT_EPS && note2.startBeat < motif.endBeat - BEAT_EPS
+      );
+      const strong = positionClass(note2.startBeat, plan.meters) === "strong";
+      violations.push({
+        kind: "harmony",
+        severity: derived ? "warning" : "error",
+        atBeat: note2.startBeat,
+        expected: strong ? "a chord tone or an ornamental tone" : "a chord tone, an ornamental tone, or a scale tone",
+        actual: kinds.length === 0 ? "no harmonic label" : kinds.join(", "),
+        rationale: derived ? `the note at beat ${note2.startBeat} sits in a derived statement, whose transformation takes precedence over the harmony` : `the note at beat ${note2.startBeat} does not fit the planned harmony`
+      });
+    });
+  }
+  return violations;
+}
+function notesInRange(melody, startBeat, endBeat) {
+  return melody.filter(
+    (note2) => note2.startBeat >= startBeat - BEAT_EPS && note2.startBeat < endBeat - BEAT_EPS
+  );
+}
+function replayLevel(source, derived, statement, sourceEnd, plan, key, closing) {
+  const relation = statement.relation;
+  const planned = relation.kind === "tonalTransposition" ? relation.degrees ?? 0 : relation.semitones;
+  const { low, high } = plan.phrases[statement.phrase].register;
+  const outside = (pitch) => pitch < low || pitch > high;
+  const backward = relation.kind === "retrograde" || relation.kind === "retrogradeInversion";
+  const cell = clipStatement(
+    source.map((note2) => ({
+      pitch: note2.pitch,
+      startBeat: note2.startBeat,
+      durationBeat: note2.durationBeat
+    })),
+    sourceEnd
+  );
+  const replays = relationLevels(relation.kind).map((level) => {
+    const notes = clipStatement(
+      replayAt(cell, relation, level, statement.startBeat, key),
+      statement.endBeat
+    );
+    return { level, notes, outside: notes.filter((note2) => outside(note2.pitch)).length };
+  });
+  const fewestOutside = Math.min(...replays.map((replay) => replay.outside));
+  let best = null;
+  for (const { level, notes: expected, outside: away } of replays) {
+    if (expected.length !== derived.length) {
+      continue;
+    }
+    let forced = 0;
+    let holds = true;
+    for (let i = 0; holds && i < expected.length; i += 1) {
+      const want = expected[i];
+      const got = derived[i];
+      if (i > 0) {
+        const gap = got.startBeat - derived[i - 1].startBeat;
+        holds = Math.abs(gap - (want.startBeat - expected[i - 1].startBeat)) <= BEAT_EPS;
+      }
+      if (!holds || got.pitch === want.pitch) {
+        continue;
+      }
+      const origin = source[backward ? cell.length - 1 - i : i];
+      forced += 1;
+      holds = closing.has(got) || origin !== void 0 && closing.has(origin) || away === fewestOutside && outside(want.pitch);
+    }
+    const distance = Math.abs(level - planned);
+    const nearer = best === null || distance < Math.abs(best.level - planned) || distance === Math.abs(best.level - planned) && level < best.level;
+    if (holds && nearer) {
+      best = { level, forced };
+    }
+  }
+  return best;
+}
+function motifDerivationViolations(melody, plan, closing) {
+  const keyAt = planKeyAt(plan);
+  const errors = [];
+  const warnings = [];
+  for (const statement of plan.motifs) {
+    if (statement.from === null) {
+      continue;
+    }
+    const source = plan.motifs[statement.from];
+    const sourceNotes = notesInRange(melody, source.startBeat, source.endBeat);
+    const derivedNotes = notesInRange(melody, statement.startBeat, statement.endBeat);
+    const relation = statement.relation;
+    const rationale = `the statement at beat ${statement.startBeat} does not derive from its source the way the plan names`;
+    if (sourceNotes.length === 0 || derivedNotes.length === 0) {
+      errors.push({
+        kind: "motifDerivation",
+        severity: "error",
+        atBeat: statement.startBeat,
+        expected: relation === null ? "a variation" : relation.kind,
+        actual: "no notes to compare",
+        rationale
+      });
+      continue;
+    }
+    if (relation === null) {
+      const similarity = melodicSimilarity(sourceNotes, derivedNotes);
+      if (similarity < DEFAULT_VARIATION_THRESHOLD) {
+        errors.push({
+          kind: "motifDerivation",
+          severity: "error",
+          atBeat: statement.startBeat,
+          expected: `a variation (melodicSimilarity >= ${DEFAULT_VARIATION_THRESHOLD})`,
+          actual: `melodicSimilarity ${similarity.toFixed(3)}`,
+          rationale
+        });
+      }
+      continue;
+    }
+    const replay = replayLevel(
+      sourceNotes,
+      derivedNotes,
+      statement,
+      source.endBeat,
+      plan,
+      scaleOf(keyAt(statement.startBeat)),
+      closing
+    );
+    const planned = relation.kind === "tonalTransposition" ? relation.degrees ?? 0 : relation.semitones;
+    if (replay === null) {
+      errors.push({
+        kind: "motifDerivation",
+        severity: "error",
+        atBeat: statement.startBeat,
+        expected: relation.kind,
+        actual: "no pitch level replays the source",
+        rationale
+      });
+    } else if (replay.level !== planned || replay.forced > 0) {
+      warnings.push({
+        kind: "motifDisplaced",
+        severity: "warning",
+        atBeat: statement.startBeat,
+        expected: `${relation.kind} at level ${planned} with every pitch replayed`,
+        actual: `level ${replay.level}, ${replay.forced} excused note(s)`,
+        rationale: `the statement at beat ${statement.startBeat} carries out its planned derivation at another pitch level or with notes excused`
+      });
+    }
+  }
+  return { errors, warnings };
+}
+function phraseAt(plan, beat) {
+  return plan.phrases.find(
+    (phrase) => beat >= phrase.startBeat - BEAT_EPS && beat < phrase.endBeat - BEAT_EPS
+  );
+}
+function registerViolations(melody, plan) {
+  const violations = [];
+  for (const note2 of melody) {
+    const phrase = phraseAt(plan, note2.startBeat);
+    if (phrase === void 0) {
+      continue;
+    }
+    if (note2.pitch < phrase.register.low || note2.pitch > phrase.register.high) {
+      violations.push({
+        kind: "register",
+        severity: "error",
+        atBeat: note2.startBeat,
+        expected: `a pitch within [${phrase.register.low}, ${phrase.register.high}]`,
+        actual: `pitch ${note2.pitch}`,
+        rationale: `the note at beat ${note2.startBeat} falls outside its phrase's planned register`
+      });
+    }
+  }
+  return violations;
+}
+function planOutline(phrase) {
+  const amplitude = (phrase.register.high - phrase.register.low) / 2;
+  const outline = [];
+  for (let k = 0; k < OUTLINE_POINTS; k += 1) {
+    const t = (k + 0.5) / OUTLINE_POINTS;
+    outline.push(
+      phrase.register.mean + plannedContourAt(phrase.shape, phrase.peakPosition, t) * amplitude
+    );
+  }
+  return outline;
+}
+function planContourPhrase(phrase) {
+  return {
+    shape: phrase.shape,
+    low: phrase.register.low,
+    high: phrase.register.high,
+    outline: planOutline(phrase)
+  };
+}
+function planRegisterPlan(plan) {
+  const phrases = plan.phrases.map((phrase) => ({
+    low: phrase.register.low,
+    high: phrase.register.high,
+    mean: phrase.register.mean,
+    peakPosition: phrase.peakPosition
+  }));
+  let weighted = 0;
+  let weight = 0;
+  for (const phrase of plan.phrases) {
+    const length = phrase.endBeat - phrase.startBeat;
+    weighted += phrase.register.mean * length;
+    weight += length;
+  }
+  return { phrases, mean: weight > 0 ? weighted / weight : null };
+}
+function planRhythmReading(plan) {
+  const hasOnsets = plan.rhythm.onsetLevels.some((share) => share > 0);
+  return {
+    onsets: hasOnsets ? 1 : 0,
+    onsetLevels: plan.rhythm.onsetLevels,
+    barPositions: [],
+    interOnsetShares: plan.rhythm.interOnsetShares,
+    syncopation: plan.rhythm.syncopation
+  };
+}
+function peakPositionWarnings(plan, readings) {
+  const violations = [];
+  plan.phrases.forEach((phrase, index) => {
+    const reading = readings[index];
+    if (reading == null) {
+      return;
+    }
+    const drift = Math.abs(reading.peakPosition - phrase.peakPosition);
+    if (drift > PEAK_POSITION_TOLERANCE) {
+      violations.push({
+        kind: "peakPosition",
+        severity: "warning",
+        atBeat: phrase.startBeat,
+        expected: `a peak position within ${PEAK_POSITION_TOLERANCE} of ${phrase.peakPosition}`,
+        actual: `${reading.peakPosition}`,
+        rationale: `the phrase starting at beat ${phrase.startBeat} places its melodic peak further from the planned position than the tolerance allows`
+      });
+    }
+  });
+  return violations;
+}
+function lineMeanOf(melody) {
+  let weighted = 0;
+  let total = 0;
+  for (const note2 of melody) {
+    weighted += note2.pitch * note2.durationBeat;
+    total += note2.durationBeat;
+  }
+  return total > 0 ? weighted / total : null;
+}
+function planDensity(plan) {
+  let weighted = 0;
+  let bars = 0;
+  for (const phrase of plan.phrases) {
+    const span = barSpanOf(phrase.startBeat, phrase.endBeat, plan.meters);
+    weighted += phrase.onsetDensity * span;
+    bars += span;
+  }
+  return { onsets: 1, onsetDensity: bars > 0 ? weighted / bars : 0 };
+}
+function evaluateComposition(melody, plan, opts) {
+  assertCompositionPlan(plan, "evaluated plan");
+  const { budget } = assertOptions(opts, "evaluate options");
+  const notes = [
+    ...assertNoteEvents(melody, "evaluated melody", { budget, allowNonPositiveDuration: true })
+  ].sort((a, b) => a.startBeat - b.startBeat);
+  const timeline = planChordTimeline(plan);
+  const lines = phraseLines(notes, plan);
+  const closing = new Set(
+    lines.flatMap((line) => line.length === 0 ? [] : [notes[line.at(-1)]])
+  );
+  const derivations = motifDerivationViolations(notes, plan, closing);
+  const lineMean = lineMeanOf(notes);
+  const readings = plan.phrases.map(
+    (phrase) => phraseMelody(notes, phrase.startBeat, phrase.endBeat, lineMean ?? 0, plan.meters, budget)
+  );
+  const violations = [
+    ...spanViolation(notes, plan),
+    ...phraseBoundaryViolations(notes, plan),
+    ...cadenceViolations(notes, plan, timeline, lines),
+    ...harmonyViolations(notes, plan, timeline, lines),
+    ...registerViolations(notes, plan),
+    ...derivations.errors,
+    ...derivations.warnings,
+    ...peakPositionWarnings(plan, readings)
+  ];
+  const rhythm = analyzeRhythm(notes, {
+    meters: plan.meters,
+    totalBeats: plan.span.endBeat,
+    budget
+  });
+  const target = planRhythmReading(plan);
+  const fit = {
+    contour: contourSimilarity(plan.phrases.map(planContourPhrase), readings),
+    register: registerSimilarity(planRegisterPlan(plan), { phrases: readings, mean: lineMean }),
+    onset: onsetSimilarity(target, rhythm),
+    duration: durationSimilarity(target, rhythm),
+    syncopation: syncopationSimilarity(target, rhythm),
+    density: densitySimilarity(planDensity(plan), rhythm)
+  };
+  return { violations, fit };
+}
+
 // src/generate/progression/index.ts
 var DEFAULT_TS6 = { numerator: 4, denominator: 4 };
 var PROG_STYLES = Object.freeze(["minimal", "dance", "idol", "rock"]);
@@ -5603,8 +7567,14 @@ export {
   motifToNoteEvents,
   transformMotif,
   developMotif,
+  COMPOSITION_PLAN_VERSION,
+  assertCompositionPlan,
+  planTimeline,
+  generateMelody,
   ORNAMENT_STYLES,
   ornament,
+  deriveCompositionPlan,
+  evaluateComposition,
   BORROWED_DEGREES,
   progressions,
   progressionsByStyle,
@@ -5618,4 +7588,4 @@ export {
   generateRhythm,
   rhythmDensity
 };
-//# sourceMappingURL=chunk-R5VUXQMP.js.map
+//# sourceMappingURL=chunk-CPMB7P75.js.map