tonus 0.1.4 → 0.1.6

package/dist/data/office-psalms-monastic.d.ts

@@ -0,0 +1,3 @@
+import type { OfficePsalmEntry } from "./office-psalms-roman.js";
+export declare const OFFICE_PSALMS_MONASTIC: OfficePsalmEntry[];
+//# sourceMappingURL=office-psalms-monastic.d.ts.map

package/dist/data/office-psalms-monastic.js

@@ -0,0 +1,21 @@
+export const OFFICE_PSALMS_MONASTIC = [
+    { hour: "Prima", weekday: 0, festis: false, psalms: [{ psalm: 118, from: 1, to: 8 }, { psalm: 118, from: 9, to: 16 }, { psalm: 118, from: 17, to: 24 }, { psalm: 118, from: 25, to: 32 }] },
+    { hour: "Prima", weekday: 1, festis: false, psalms: [{ psalm: 1 }, { psalm: 2 }, { psalm: 6 }] },
+    { hour: "Prima", weekday: 2, festis: false, psalms: [{ psalm: 7 }, { psalm: 8 }, { psalm: 9, from: 2, to: 19 }] },
+    { hour: "Prima", weekday: 3, festis: false, psalms: [{ psalm: 9, from: 20, to: 39 }, { psalm: 10 }, { psalm: 11 }] },
+    { hour: "Prima", weekday: 4, festis: false, psalms: [{ psalm: 12 }, { psalm: 13 }, { psalm: 14 }] },
+    { hour: "Prima", weekday: 5, festis: false, psalms: [{ psalm: 15 }, { psalm: 16 }, { psalm: 17, from: 2, to: 25 }] },
+    { hour: "Prima", weekday: 6, festis: false, psalms: [{ psalm: 17, from: 26, to: 51 }, { psalm: 18 }, { psalm: 19 }] },
+    { hour: "Prima", weekday: null, festis: true, psalms: [{ psalm: 118, from: 1, to: 8 }, { psalm: 118, from: 9, to: 16 }, { psalm: 118, from: 17, to: 24 }, { psalm: 118, from: 25, to: 32 }] },
+    { hour: "Tertia", weekday: 0, festis: false, psalms: [{ psalm: 118, from: 33, to: 40 }, { psalm: 118, from: 41, to: 48 }, { psalm: 118, from: 49, to: 56 }] },
+    { hour: "Tertia", weekday: 1, festis: false, psalms: [{ psalm: 118, from: 105, to: 112 }, { psalm: 118, from: 113, to: 120 }, { psalm: 118, from: 121, to: 128 }] },
+    { hour: "Tertia", weekday: null, festis: false, psalms: [{ psalm: 119 }, { psalm: 120 }, { psalm: 121 }] },
+    { hour: "Sexta", weekday: 0, festis: false, psalms: [{ psalm: 118, from: 57, to: 64 }, { psalm: 118, from: 65, to: 72 }, { psalm: 118, from: 73, to: 80 }] },
+    { hour: "Sexta", weekday: 1, festis: false, psalms: [{ psalm: 118, from: 129, to: 136 }, { psalm: 118, from: 137, to: 144 }, { psalm: 118, from: 145, to: 152 }] },
+    { hour: "Sexta", weekday: null, festis: false, psalms: [{ psalm: 122 }, { psalm: 123 }, { psalm: 124 }] },
+    { hour: "Nona", weekday: 0, festis: false, psalms: [{ psalm: 118, from: 81, to: 88 }, { psalm: 118, from: 89, to: 96 }, { psalm: 118, from: 97, to: 104 }] },
+    { hour: "Nona", weekday: 1, festis: false, psalms: [{ psalm: 118, from: 153, to: 160 }, { psalm: 118, from: 161, to: 168 }, { psalm: 118, from: 169, to: 176 }] },
+    { hour: "Nona", weekday: null, festis: false, psalms: [{ psalm: 125 }, { psalm: 126 }, { psalm: 127 }] },
+    { hour: "Completorium", weekday: null, festis: false, psalms: [{ psalm: 4 }, { psalm: 90 }, { psalm: 133 }] }
+];
+//# sourceMappingURL=office-psalms-monastic.js.map

package/dist/data/{office-psalms.d.ts → office-psalms-roman.d.ts}

@@ -12,4 +12,4 @@ export interface OfficePsalmEntry {
     psalms: OfficePsalmPortion[];
 }
 export declare const OFFICE_PSALMS: OfficePsalmEntry[];
-//# sourceMappingURL=office-psalms.d.ts.map
+//# sourceMappingURL=office-psalms-roman.d.ts.map

package/dist/data/{office-psalms.js → office-psalms-roman.js}

@@ -1,7 +1,7 @@
-// office-psalms.ts — little-hours psalmody (Prime, Terce, Sext, None, Compline)
+// office-psalms-roman.ts — Roman little-hours psalmody (Prime, Terce, Sext, None, Compline)
 // Extracted from Divinum Officium (Psalterium, [Tridentinum] section) by
 // scripts/extract-office-psalms.mjs
-// Generated: 2026-07-05T01:25:28.943Z
+// Generated: 2026-07-08T04:45:29.223Z
 // Entries: 15
 //
 // The traditional (pre-1911) Roman little-hours psalm distribution. Each entry
@@ -25,4 +25,4 @@ export const OFFICE_PSALMS = [
     { hour: "Nona", weekday: null, festis: false, psalms: [{ psalm: 118, from: 129, to: 144 }, { psalm: 118, from: 145, to: 160 }, { psalm: 118, from: 161, to: 176 }] },
     { hour: "Completorium", weekday: null, festis: false, psalms: [{ psalm: 4 }, { psalm: 30, from: 2, to: 6 }, { psalm: 90 }, { psalm: 133 }] }
 ];
-//# sourceMappingURL=office-psalms.js.map
+//# sourceMappingURL=office-psalms-roman.js.map

package/dist/engines/cal/calendar.js

@@ -1,8 +1,23 @@
 // ---------------------------------------------------------------------------
 // engines/cal/calendar — liturgical feast lookup
 // ---------------------------------------------------------------------------
+// The era, and why it is what it is. The calendar's *structure* is medieval —
+// the temporale from Advent through the season after Pentecost (Septuagesima
+// included), the eight-hour office cursus, the duplex/semiduplex/simplex
+// dignity system. The *data* is the Tridentine codification (1570–1962) drawn
+// from Divinum Officium [biblio: divinum-officium], substantially continuous
+// with late-medieval Roman usage but carrying feasts instituted as late as the
+// 1950s (Queenship of Mary 1954, Immaculate Heart 1944).
+//
+// Decision: those post-medieval feasts are KEPT, not pruned. Pruning would
+// break the DO data's integrity and demand per-feast historical adjudication;
+// instead tonus states its actual era plainly. The honest description is
+// "Tridentine Roman, continuous with medieval practice" — not "a medieval
+// calendar." (Per-feast era metadata — medieval / tridentine / modern — is
+// noted as future work.) The rank system this data carries is documented at
+// `ritus`/`Grade` in ./types.ts; Easter reckoning at pascha() in ./date.ts.
 import { CAL } from "../../data/cal.js";
-import { MASSES } from "../../data/masses.js";
+import { MASSES } from "../chant/data/masses.js";
 import { isoDate, startOfDay, addDays, subDays, firstSundayOnOrAfter, nextSunday, pascha, resolveEntryId, DEFAULT_EPOCH, } from "./date.js";
 import { TEMPUS_NAMES, entryGrade, gradeOrder, BVM_FEAST_IDS, APOSTOLIC_FEAST_IDS, } from "./types.js";
 const _calCache = new Map();

package/dist/engines/cal/date.js

@@ -37,6 +37,11 @@ export function parseMonthDay(year, mmdd) {
     return new Date(Date.UTC(year, m - 1, d));
 }
 // ── Easter ──
+// Split at the Gregorian reform (1583): from 1583 on, the Gauss/Butcher
+// Gregorian computus; before it, the classical 19-year Julian cycle with a
+// Julian→Gregorian day-number conversion [biblio: computus]. This keeps Easter
+// correct for date queries reaching back into the medieval period — the era the
+// calendar is built for (see the era note in ./calendar.ts).
 export function pascha(year) {
     if (year < 1583)
         return paschaJulian(year);

package/dist/engines/chant/chant.js

@@ -3,6 +3,7 @@ import { GR_DATA, GR_SOURCE } from "../../data/gr.js";
 import { LU_DATA, LU_SOURCE } from "../../data/lu.js";
 import { LA_DATA, LA_SOURCE } from "../../data/la.js";
 import { LH_DATA, LH_SOURCE } from "../../data/lh.js";
+import { AM_DATA, AM_SOURCE } from "../../data/am.js";
 function modusOf(mode) {
     return mode != null ? (MODE_LABELS[mode] ?? null) : null;
 }
@@ -63,6 +64,7 @@ const CORPUS = [
     ...LU_DATA.map((c) => withLabels(c, LU_SOURCE)),
     ...LA_DATA.map((c) => withLabels(c, LA_SOURCE)),
     ...LH_DATA.map((c) => withLabels(c, LH_SOURCE)),
+    ...AM_DATA.map((c) => withLabels(c, AM_SOURCE)),
 ];
 let _byId = null;
 function byId() {

package/dist/{data → engines/chant/data}/compline.d.ts

@@ -1,4 +1,4 @@
-import type { Season } from "../engines/cal/types.js";
+import type { Season } from "../../cal/types.js";
 /** The invariable spine — chants sung the same every night. */
 export declare const COMPLINE_ORDINARY: {
     /** Deus in adjutorium — the opening versicle. */

package/dist/{data → engines/chant/data}/masses.d.ts

@@ -1,4 +1,4 @@
-import { type Season, type Grade } from "../engines/cal/types.js";
+import { type Season, type Grade } from "../../cal/types.js";
 export interface MassEntry {
     id: string;
     mass: number;

package/dist/{data → engines/chant/data}/masses.js

@@ -2,7 +2,7 @@
 //
 // Describes which masses are appropriate for a given season, grade, and day.
 // Mass 0 has two ad-lib variants (index 0a/0b); all others are single entries.
-import { GRADE_ORDER, } from "../engines/cal/types.js";
+import { GRADE_ORDER, } from "../../cal/types.js";
 // Inclusive slice of GRADE_ORDER from `high` (more solemn) to `low`.
 // e.g. gradesFrom("duplex-i", "duplex-ii") lists every grade between them.
 function gradesFrom(high, low) {

package/dist/{data → engines/chant/data}/prime.d.ts

@@ -1,4 +1,4 @@
-import type { Season } from "../engines/cal/types.js";
+import type { Season } from "../../cal/types.js";
 /** The invariable spine. */
 export declare const PRIME_ORDINARY: {
     /** Deus in adjutorium — the opening versicle. */

package/dist/{data → engines/chant/data}/prime.js

@@ -8,7 +8,7 @@
 // Solesmes chant and are not in the corpus, so they are out of scope; this is a
 // chant ordo, not a full Breviary Prime.
 //
-// Like data/compline.ts and data/masses.ts this is a hand-authored table that
+// Like compline.ts and masses.ts (its siblings here) this is a hand-authored table that
 // references chants already in the corpus by id; it carries no GABC of its own.
 // See docs/chant.md and BIBLIOGRAPHY.md.
 // Prime's psalmody (Ps 53 + a weekday-proper psalm + Ps 118 in two sections,

package/dist/engines/chant/hour.js

@@ -6,10 +6,17 @@ import { intonePortion, officePsalmPortions } from "./psalm.js";
 import { temporaSundayId } from "../cal/date.js";
 import { getFeast } from "../cal/calendar.js";
 import { OFFICE_ROMAN } from "../../data/office-roman.js";
-import { COMPLINE_ORDINARY, COMPLINE_SEASONAL, marianAntiphonFor, } from "../../data/compline.js";
-import { PRIME_ORDINARY, PRIME_SEASONAL } from "../../data/prime.js";
+import { OFFICE_MONASTIC } from "../../data/office-monastic.js";
+import { COMPLINE_ORDINARY, COMPLINE_SEASONAL, marianAntiphonFor, } from "./data/compline.js";
+import { PRIME_ORDINARY, PRIME_SEASONAL } from "./data/prime.js";
 let _roman = null;
-function romanMap() {
+let _monastic = null;
+function officeMap(rite) {
+    if (rite === "monasticum") {
+        if (!_monastic)
+            _monastic = new Map(OFFICE_MONASTIC.map((d) => [d.feastId, d]));
+        return _monastic;
+    }
     if (!_roman)
         _roman = new Map(OFFICE_ROMAN.map((d) => [d.feastId, d]));
     return _roman;
@@ -29,14 +36,17 @@ const SEASONAL_ORDO_HOURS = new Set([
 // tables at all. The ordo is assembled from the season (Te lucis, In manus
 // tuas), the fixed psalms (from the extracted DO scheme), the invariable spine
 // (Deus in adjutorium, Nunc dimittis), and the date-driven Marian antiphon.
-// See data/compline.ts.
-function complineForFeast(feast) {
+// See ./data/compline.ts.
+function complineForFeast(feast, rite) {
     const seasonal = COMPLINE_SEASONAL[feast.season];
     const results = [];
     const opening = resolveChant(COMPLINE_ORDINARY.opening);
     if (opening)
         results.push(opening);
-    for (const p of officePsalmPortions("Completorium", feast.weekday)) {
+    // Monastic Compline uses a fixed three-psalm set (4, 90, 133); the Roman rite
+    // adds Ps 30 vv. 2–6. The difference is entirely in the psalm scheme — the
+    // rest of the ordo (spine, hymn, In manus tuas, Marian antiphon) is shared.
+    for (const p of officePsalmPortions("Completorium", feast.weekday, rite)) {
         results.push(...intonePortion(p));
     }
     const hymn = seasonal && resolveChant(seasonal.teLucis);
@@ -54,9 +64,9 @@ function complineForFeast(feast) {
     return results;
 }
 // Prime, like Compline, is a fixed+seasonal ordo, not per-feast. Covers the
-// sung parts only (see data/prime.ts): opening, fixed psalms, the hymn Iam
+// sung parts only (see ./data/prime.ts): opening, fixed psalms, the hymn Iam
 // lucis, and the seasonal short responsory Christe Fili Dei.
-function primeForFeast(feast) {
+function primeForFeast(feast, rite) {
     const seasonal = PRIME_SEASONAL[feast.season];
     const results = [];
     const opening = resolveChant(PRIME_ORDINARY.opening);
@@ -65,7 +75,9 @@ function primeForFeast(feast) {
     const hymn = resolveChant(PRIME_ORDINARY.hymn);
     if (hymn)
         results.push(hymn);
-    for (const p of officePsalmPortions("Prima", feast.weekday)) {
+    // The monastic Prime psalmody is weekday-varied across the psalter (vs. the
+    // Roman Ps-118 pattern) — a psalm-scheme difference; the ordo spine is shared.
+    for (const p of officePsalmPortions("Prima", feast.weekday, rite)) {
         results.push(...intonePortion(p));
     }
     const responsory = seasonal && resolveChant(seasonal.responsory);
@@ -73,12 +85,12 @@ function primeForFeast(feast) {
         results.push(responsory);
     return results;
 }
-function chantsForFeastHour(feast, hour) {
+function chantsForFeastHour(feast, hour, rite) {
     if (hour === "completorium")
-        return complineForFeast(feast);
+        return complineForFeast(feast, rite);
     if (hour === "prima")
-        return primeForFeast(feast);
-    const map = romanMap();
+        return primeForFeast(feast, rite);
+    const map = officeMap(rite);
     const sunday = temporaSundayId(feast.id);
     const day = map.get(feast.id) ?? (sunday ? (map.get(sunday) ?? null) : null);
     if (!day)
@@ -111,7 +123,7 @@ function chantsForFeastHour(feast, hour) {
         // repeat the psalms once per feast).
         if (feast.date) {
             const hourName = hour === "tertia" ? "Tertia" : hour === "sexta" ? "Sexta" : "Nona";
-            for (const p of officePsalmPortions(hourName, feast.weekday)) {
+            for (const p of officePsalmPortions(hourName, feast.weekday, rite)) {
                 results.push(...intonePortion(p));
             }
         }
@@ -147,34 +159,37 @@ export function getHour(query) {
         return [];
     const feasts = toArray(query.feast);
     const hour = query.hora;
+    const rite = query.rite ?? "romanum";
     let results;
     if (feasts && hour) {
         // Prime and Compline are seasonal/weekday ordos, identical for every feast
         // of the day — so concurrent feasts collapse to a single ordo rather than
         // repeating it. The other hours are genuinely per-feast.
         results = SEASONAL_ORDO_HOURS.has(hour)
-            ? feasts[0] ? chantsForFeastHour(feasts[0], hour) : []
-            : feasts.flatMap((f) => chantsForFeastHour(f, hour));
+            ? feasts[0] ? chantsForFeastHour(feasts[0], hour, rite) : []
+            : feasts.flatMap((f) => chantsForFeastHour(f, hour, rite));
     }
     else if (feasts) {
         const hours = [
             "matutinum", "laudes", "prima", "tertia", "sexta", "nona",
             "vesperae", "completorium",
         ];
-        results = feasts.flatMap((f) => hours.flatMap((h) => chantsForFeastHour(f, h)));
+        results = feasts.flatMap((f) => hours.flatMap((h) => chantsForFeastHour(f, h, rite)));
     }
     else if (hour && SEASONAL_ORDO_HOURS.has(hour)) {
         // Prime and Compline are seasonal ordos, not per-feast. With no feast,
         // resolve for the default epoch (Guido d'Arezzo's era) — festum()'s anchor.
         const [feast] = getFeast();
-        results = feast ? chantsForFeastHour(feast, hour) : [];
+        results = feast ? chantsForFeastHour(feast, hour, rite) : [];
     }
     else if (hour) {
-        // Hour without feast — survey per-feast content across all office entries.
-        // mockFeast has no date, so the little hours return only their responsories.
-        results = OFFICE_ROMAN.flatMap((day) => {
+        // Hour without feast — survey per-feast content across the office entries of
+        // the chosen rite. mockFeast has no date, so the little hours return only
+        // their responsories.
+        const table = rite === "monasticum" ? OFFICE_MONASTIC : OFFICE_ROMAN;
+        results = table.flatMap((day) => {
             const mockFeast = { id: day.feastId };
-            return chantsForFeastHour(mockFeast, hour);
+            return chantsForFeastHour(mockFeast, hour, rite);
         });
     }
     else {

package/dist/engines/chant/intone.js

@@ -1,8 +1,13 @@
 // ---------------------------------------------------------------------------
 // engines/chant/intone — GABC generation for psalm verses sung to psalm tones
 // ---------------------------------------------------------------------------
+// Psalmody structure follows the Liber Usualis rules [biblio: liber-usualis]:
+// each verse is intonation → tenor (reciting note) → mediation → final cadence,
+// with the flex a subdivision of a long first half. The intonation is sung on
+// the first verse only (unless repeated, as in the Magnificat) — see the
+// `intonation` option; `inDirectum` recites straight through with no mediant.
 import { syllabifyPhrase } from "./syllabify.js";
-import { getTone, getDifferentia } from "../../data/tones.js";
+import { getTone, getDifferentia } from "../temper/data/tones.js";
 import { midiToGabc } from "../temper/gabc.js";
 const DEFAULT_CLEF = "c4";
 const CLEF = `(${DEFAULT_CLEF}) `;

package/dist/engines/chant/ordinary.js

@@ -1,7 +1,7 @@
 // ---------------------------------------------------------------------------
 // engines/chant/ordinary — Mass ordinary (kyriale) selection
 // ---------------------------------------------------------------------------
-import { MASSES, AD_LIB } from "../../data/masses.js";
+import { MASSES, AD_LIB } from "./data/masses.js";
 import { KYRIALE } from "../../data/kyriale.js";
 import { MODE_LABELS, ORDINARY_LABELS, } from "./types.js";
 import { gradeOrder, PENITENTIAL_SEASONS, } from "../cal/types.js";

package/dist/engines/chant/psalm.d.ts

@@ -1,5 +1,5 @@
-import { type OfficePsalmEntry, type OfficePsalmPortion } from "../../data/office-psalms.js";
-import { type Chant, type PsalmusQuery } from "./types.js";
+import { type OfficePsalmEntry, type OfficePsalmPortion } from "../../data/office-psalms-roman.js";
+import { type Chant, type PsalmusQuery, type Rite } from "./types.js";
 /**
  * Psalm and canticle retrieval (`tonus.psalmus`) from the Psalterium,
  * intoned to the psalm tones (modes 1-8 plus tonus peregrinus) as GABC.
@@ -16,9 +16,9 @@ export declare function getPsalmRange(psalm: number, lo: number, hi: number, mod
 export declare function intonePortion(p: OfficePsalmPortion, mode?: number): Chant[];
 /**
  * The little-hours psalmody for one hour on a given weekday (0 = Sunday), from
- * the extracted DO Tridentine scheme (`office-psalms.ts`). Prefers the
+ * the extracted DO Tridentine scheme (`office-psalms-roman.ts`). Prefers the
  * weekday-specific entry, then the ferial default (weekday null), then the
  * feast set; returns the psalm portions (not yet intoned).
  */
-export declare function officePsalmPortions(hour: OfficePsalmEntry["hour"], weekday: number): OfficePsalmPortion[];
+export declare function officePsalmPortions(hour: OfficePsalmEntry["hour"], weekday: number, rite?: Rite): OfficePsalmPortion[];
 //# sourceMappingURL=psalm.d.ts.map

package/dist/engines/chant/psalm.js

@@ -2,7 +2,8 @@
 // engines/chant/psalm — psalm and canticle retrieval as intoned Chant[]
 // ---------------------------------------------------------------------------
 import { PSALMS } from "../../data/psalms.js";
-import { OFFICE_PSALMS, } from "../../data/office-psalms.js";
+import { OFFICE_PSALMS, } from "../../data/office-psalms-roman.js";
+import { OFFICE_PSALMS_MONASTIC } from "../../data/office-psalms-monastic.js";
 import { intone } from "./intone.js";
 import { MODE_LABELS } from "./types.js";
 const CANTICLE_NAMES = {
@@ -82,12 +83,13 @@ export function intonePortion(p, mode = 8) {
 }
 /**
  * The little-hours psalmody for one hour on a given weekday (0 = Sunday), from
- * the extracted DO Tridentine scheme (`office-psalms.ts`). Prefers the
+ * the extracted DO Tridentine scheme (`office-psalms-roman.ts`). Prefers the
  * weekday-specific entry, then the ferial default (weekday null), then the
  * feast set; returns the psalm portions (not yet intoned).
  */
-export function officePsalmPortions(hour, weekday) {
-    const forHour = OFFICE_PSALMS.filter((e) => e.hour === hour);
+export function officePsalmPortions(hour, weekday, rite = "romanum") {
+    const scheme = rite === "monasticum" ? OFFICE_PSALMS_MONASTIC : OFFICE_PSALMS;
+    const forHour = scheme.filter((e) => e.hour === hour);
     const exact = forHour.find((e) => e.weekday === weekday && !e.festis);
     const ferial = forHour.find((e) => e.weekday === null && !e.festis);
     const festis = forHour.find((e) => e.festis);

package/dist/engines/chant/types.d.ts

@@ -2,7 +2,7 @@ import type { Season, Grade, Feast } from "../cal/types.js";
 export type { Season, Grade, Feast };
 export type OfficeCode = "an" | "al" | "ca" | "co" | "gr" | "hy" | "in" | "of" | "ps" | "re" | "rb" | "se" | "tr" | "tp" | "or";
 export type OrdinaryCode = "ky" | "gl" | "cr" | "sa" | "ag" | "be" | "it" | "as" | "va";
-export type ChantSource = "gr" | "lu" | "la" | "lh";
+export type ChantSource = "gr" | "lu" | "la" | "lh" | "am";
 export type CanonicalHour = "matutinum" | "laudes" | "prima" | "tertia" | "sexta" | "nona" | "vesperae" | "completorium";
 export declare const MODE_LABELS: Readonly<Record<string, string>>;
 export declare const OFFICE_LABELS: Readonly<Record<OfficeCode, string>>;
@@ -54,9 +54,13 @@ export interface OrdinariumQuery extends CantusQuery {
     ordinary?: OrdinaryCode;
     mass?: number;
 }
+/** Which rite's Office to assemble. `romanum` (default) is the Tridentine Roman
+ *  cursus; `monasticum` is the Benedictine cursus (Antiphonale Monasticum). */
+export type Rite = "romanum" | "monasticum";
 export interface OfficiumQuery extends CantusQuery {
     feast?: Feast | Feast[];
     hora?: CanonicalHour;
+    rite?: Rite;
 }
 export interface PsalmusQuery {
     psalm?: number | string;

package/dist/engines/harmonia/api.js

@@ -20,6 +20,14 @@ function resolveScale(temper) {
     }
     return buildRatios();
 }
+// Reduce a time range's per-frame voicings to one aggregate body list for the
+// top-level `bodies`. Note the deliberate asymmetry: the DYNAMICS (presence,
+// motion) are mean-averaged across the range, but the REPRESENTATIVE identity —
+// pitch, vowel, zodiac, retrograde — is taken from the first frame, not averaged
+// (a pitch has no meaningful mean, and averaging a wrapping zodiac longitude is
+// nonsense). So an aggregate body sounds the range's *starting* pitch with its
+// *mean* loudness. Callers wanting the pitch to track the range should read the
+// per-frame `frames` instead. (Aspects are likewise taken from frame 0; see below.)
 function averageBodies(frames) {
     if (frames.length === 0)
         return [];
@@ -71,6 +79,9 @@ export function buildHarmonia(input, opts = {}) {
         frames.push({ date: cosmos.date, bodies: vb, aspects: va });
     }
     const aggregateBodies = averageBodies(perCosmosBodies);
+    // Aspects are the first frame's, not merged across the range — an aspect forms
+    // and dissolves over time, so there is no meaningful "average" set. Like the
+    // representative pitch above, this reflects the range's start.
     const aggregateAspects = frames[0]?.aspects ?? [];
     const imprint = computeImprintFromBodies(aggregateBodies, scale);
     const harmony = {

package/dist/engines/harmonia/data/doctrines.js

@@ -10,12 +10,38 @@
 // center, not a voiced body (except Pliny, where Earth is a boundary tone).
 // The Sun holds the mese position in all four systems.
 //
-// Source: Joscelyn Godwin, "Harmonies of Heaven and Earth" (1987), Part Three;
+// The ratios are reconstructed from the primary texts [biblio:
+// doctrina-primaries] through Godwin's syntheses [biblio: godwin-harmonies,
+// godwin-spheres]: for each author the Greek tonal framework is identified
+// (conjunct/disjunct tetrachords, or the fixed Greater Perfect System),
+// bodies are mapped to Greek tone-names from the source's explicit
+// assignments, and ratios are derived by Pythagorean interval arithmetic
+// (tone 9/8, limma 256/243, fourth 4/3, fifth 3/2) normalized to the mese
+// (Sun = 1/1), then verified computationally for span and closure.
 //
 // Taxonomy follows Godwin's classification:
 //   Type A — intervals represent distances between spheres
 //   Type B — intervals represent speeds/symbolic scale degrees
 //   Type C — intervals map to fixed tones of the Greater Perfect System
+//
+// Decisions recorded from the derivation:
+//   1. Boethius transmits Nicomachus's ratios; tonus credits the doctrina to
+//      Boethius as the medieval authority.
+//   2. Pliny's Sun sits at hypate meson, not the Greek mese; tonus keeps the
+//      Sun as the structural center regardless, and greekName reflects
+//      Pliny's actual position.
+//   3. Ptolemy's aspect–consonance mapping carries into interval grading — a
+//      Jupiter–Sun aspect sounds a fifth, Mars–Sun a tone.
+//   4. Pythagoras's Fixed Stars complete the octave in the data but are never
+//      voiced: no caelum body, no classical vowel.
+//   5. Voices are stored in sphere order, outermost first; sort by ratio for
+//      scale views.
+//
+// The single pitch that separates Pythagoras from Boethius is Venus — the
+// diagnostic of the whole tradition: a whole tone above the Sun in the
+// disjunct system (9/8, B durum), a semitone in the conjunct (256/243, B
+// molle). This is the same durum/molle distinction the GABC parser tracks as
+// the `bmolle` accidental. See the per-doctrina notes below.
 // ---------------------------------------------------------------------------
 // ── Pythagoras ──
 //

package/dist/engines/imprint.js

@@ -1,6 +1,9 @@
 import { toPitch } from "./temper/pitch.js";
 import { computeModalAffinity } from "./temper/modality.js";
 const DEFAULT_TOP = 5;
+// Attractors are pitch *classes*; they're rendered at a fixed octave (4) purely
+// so they carry a concrete Pitch for display. The octave is not meaningful — do
+// not read it as register.
 const DEFAULT_MIDI_OCTAVE = 4;
 const VOWELS = ["a", "e", "i", "o", "u"];
 function pitchForPc(pc, scale) {
@@ -70,7 +73,10 @@ function computeVowelAttractors(phrases, scale) {
 // A note's contribution to the pc-distribution is raised where it carries more
 // structural weight: on an ictus (the rhythmic footfall) and, above all, when it
 // is a cadence's resolution. Cadence notes are passed in — the imprint sits below
-// the score engine, so it cannot detect them itself.
+// the score engine, so it cannot detect them itself. The principle that ictus and
+// cadence notes are the modally load-bearing ones is Solesmes doctrine [biblio:
+// mocquereau-nombre]; the magnitudes (1.5×, 2×) are a tuned editorial weighting,
+// not a figure from any source — cadence weighted above ictus by intent.
 const ICTUS_WEIGHT = 1.5;
 const CADENCE_WEIGHT = 2;
 /** Build an Imprint from chant phrases, weighting structural notes more. */

package/dist/engines/planet/position.js

@@ -1,12 +1,33 @@
 // ---------------------------------------------------------------------------
 // engines/planet/position — Julian date, astro state, helio/geo position engine
 // ---------------------------------------------------------------------------
+// Two source models sit side by side, and which one runs depends on the body:
+//
+//   • Planets — the JPL/Standish Keplerian element tables [biblio: standish-jpl]
+//     in orbital.ts, solved with the iterative Newton kepler() solver. See
+//     planetPos.
+//   • Sun and Moon — Paul Schlyter's tutorial formulae [biblio:
+//     schlyter-positions], a lighter model with its own constants, a one-step
+//     eccentric-anomaly approximation (the Sun), and a named perturbation series
+//     (the Moon). See sunPos / moonPos.
+//
+// The split is deliberate: the JPL tables don't include the Moon, and Schlyter's
+// Sun is accurate enough at the Sun's tiny eccentricity to skip Newton iteration.
+// So the reader should not expect the same constants or solver across bodies.
+//
+// A few time-scale models here are standard astronomy but not yet catalogued in
+// BIBLIOGRAPHY.md (marked "source TBD" at each): the ΔT (TT−UT) polynomial and
+// the mean-obliquity expansion.
 import { sinDeg, cosDeg, atan2Deg, kepler, wrapAngle, toAu, toCartesian, toSpherical, toEquatorial } from "./math.js";
 import { ORBITAL_ELEMENTS } from "./orbital.js";
 const MS_PER_DAY = 86400000;
 // Precomputed Earth radius in AU (used for Moon distance conversion)
 const EARTH_ELEM = ORBITAL_ELEMENTS.get("Earth");
 export const EARTH_RADIUS_AU = toAu(EARTH_ELEM.radius);
+// Mean obliquity of the ecliptic (the tilt used to rotate ecliptic → equatorial
+// coordinates), in degrees. eps0 is the J2000 value 23°26′21.406″; the arcsecond
+// series is the standard IAU 2006 expansion in Julian centuries T from J2000.
+// (Standard astronomy; source not yet catalogued — TBD.)
 function meanObliquity(T) {
     const eps0 = 23 + 26 / 60 + 21.406 / 3600;
     const sec = -46.836769 * T -
@@ -17,8 +38,14 @@ function meanObliquity(T) {
     return eps0 + sec / 3600;
 }
 export function getState(ts) {
+    // 2440587.5 is the Julian Date of the Unix epoch; 2451545 is J2000.0 and 36525
+    // days is a Julian century — so _T is centuries from J2000 in UT.
     const JD = 2440587.5 + ts / MS_PER_DAY;
     const _T = (JD - 2451545) / 36525;
+    // ΔT (TT − UT), in seconds: the drift between civil UT and the uniform
+    // Terrestrial Time the ephemerides are reckoned in. This is a coarse local fit
+    // valid near the present, not a long-baseline model — a limitation for deep
+    // medieval dates. (Standard-form polynomial; source not yet catalogued — TBD.)
     const dT = 64.7 + 64.7 * _T - 0.6 * _T * _T; // seconds
     const TT = JD + dT / 86400;
     const J = TT - 2451545.0;
@@ -26,12 +53,16 @@ export function getState(ts) {
     const eps = meanObliquity(T);
     return { JD, TT, TS: ts, J, T, eps };
 }
-// ── Sun position ──
+// ── Sun position ── (Schlyter's solar elements [biblio: schlyter-positions])
 export function sunPos(state) {
     const { J, eps } = state;
+    // omega = longitude of perihelion, e = eccentricity, M = mean anomaly, all as
+    // Schlyter's linear-in-J elements (J = days from J2000).
     const omega = 282.9404 + 4.70935e-5 * J;
     const e = 0.016709 - 1.151e-9 * J;
     const M = 356.047 + 0.9856002585 * J;
+    // Eccentric anomaly by a single first-order step, not Newton iteration: the
+    // Sun's eccentricity is small enough (~0.017) that one correction suffices.
     const E = M + (180 / Math.PI) * e * sinDeg(M) * (1 + e * cosDeg(M));
     const xp = cosDeg(E) - e;
     const yp = Math.sqrt(1 - e * e) * sinDeg(E);
@@ -54,9 +85,13 @@ export function sunPos(state) {
         },
     };
 }
-// ── Moon position ──
+// ── Moon position ── (Schlyter's lunar elements [biblio: schlyter-positions])
 export function moonPos(state, sun) {
     const { J, eps } = state;
+    // Orbital elements (J = days from J2000): Omega = ascending node, I =
+    // inclination, omega = argument of perigee, a = semi-major axis IN EARTH RADII
+    // (not AU — the Moon is measured from Earth; the AU conversion happens at the
+    // end via EARTH_RADIUS_AU), e = eccentricity, M = mean anomaly.
     const Omega = wrapAngle(125.1228 - 0.0529538083 * J);
     const I = 5.1454;
     const omega = wrapAngle(318.0634 + 0.1643573223 * J);
@@ -73,12 +108,18 @@ export function moonPos(state, sun) {
     const y = (cw * sO + sw * cO * cI) * xh + (-sw * sO + cw * cO * cI) * yh;
     const z = sw * sI * xh + cw * sI * yh;
     const [lonE, latE, distE] = toSpherical(x, y, z);
+    // The perturbation arguments: Lm = Moon's mean longitude, Ms/Ls = Sun's mean
+    // anomaly/longitude, D = mean elongation (Moon − Sun), F = argument of latitude
+    // (Moon − node). The Sun's disturbing pull is expressed as sines of these.
     const Lm = wrapAngle(Omega + omega + M);
     const Ms = sun.orbit.M;
     const Ls = sun.orbit.L;
     const D = wrapAngle(Lm - Ls);
     const F = wrapAngle(Lm - Omega);
-    // Lunar perturbations
+    // Lunar perturbations, in degrees — Schlyter's truncated series of the classical
+    // named terms. The three largest in longitude are the evection (−1.274·sin(M−2D),
+    // the Sun stretching the Moon's ellipse), the variation (+0.658·sin(2D)), and
+    // the annual equation (−0.186·sin Ms); the remainder are smaller corrections.
     const lonPerturb = -1.274 * sinDeg(M - 2 * D) + 0.658 * sinDeg(2 * D) - 0.186 * sinDeg(Ms) -
         0.059 * sinDeg(2 * M - 2 * D) - 0.057 * sinDeg(M - 2 * D + Ms) +
         0.053 * sinDeg(M + 2 * D) + 0.046 * sinDeg(2 * D - Ms) +
@@ -116,12 +157,17 @@ export function planetPos(name, state, sun) {
         throw new Error(`Unknown body: ${name}`);
     const { J, T, eps } = state;
     const oe = body.datasets;
-    // Use higher-precision dataset (1800–2050) if in range, otherwise long-range dataset
+    // Two Standish element sets per body (see orbital.ts): [1] is fitted tightly
+    // for 1800–2050, [0] trades accuracy for 3000 BC–3000 AD coverage. The bounds
+    // are J (days from J2000): −73048.5 ≈ 1800, 18626.5 ≈ 2050. Inside the window
+    // use the precise set, outside fall back to the long-range one.
     const dataset = J > -73048.5 && J < 18626.5 ? oe[1] : oe[0];
     const [a, e, I, L, wBar, Omega] = dataset.map(([x0, x1]) => x0 + x1 * T);
     const omega = wBar - Omega; // argument of periapsis
     let M = L - wBar; // mean anomaly
-    // Perturbation correction for outer planets
+    // Standish's great-inequality correction for the outer planets (Jupiter–Neptune):
+    // a secular b·T² plus a long-period cos/sin term at frequency f. Only bodies
+    // that carry a datasets[2] (see orbital.ts) get it. [biblio: standish-jpl]
     if (oe[2]) {
         const [b, c, s, f] = oe[2];
         M += b * T * T + c * cosDeg(f * T) + s * sinDeg(f * T);