tonus 0.1.4 → 0.1.8

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);

package/dist/engines/score/articulation.js

@@ -1,35 +1,92 @@
 // ---------------------------------------------------------------------------
 // engines/score/articulation — note-level articulation profiles
 // ---------------------------------------------------------------------------
+// The pondus ("weight") tables. Each GABC performance mark — episema, quilisma,
+// liquescent, strophicus, oriscus, ictus — carries a weight delta and a
+// duration delta that the parser folds into a note's rhythmicShape (see the
+// tanh compressor in parse.ts). The signs encode the semiological reading of
+// the mark [biblio: cardine-semiology], and the durational values the Solesmes
+// rhythmic tradition [biblio: desrocquettes-values, liber-usualis]: POSITIVE
+// lengthens/stresses, NEGATIVE lightens/shortens. So an episema lengthens
+// (+0.9 duration), a liquescent is a passing lightening (−0.4 weight), an
+// uppercase-syllable note is de-stressed (−0.7).
+//
+// Four profiles select how strongly those rules speak, from a semiological
+// restraint to full Solesmes-rule fidelity:
+//   restrained — Cardine's semiological reading: rules present but soft-spoken.
+//   balanced   — the default; BASE_WEIGHTS unaltered.
+//   expressive — rules pushed (stronger ictus and accent, wider contour).
+//   strict     — maximal Solesmes-rule fidelity (episema to a full double, a
+//                sharper quilisma). The differences live in the per-profile
+//                weight overrides below.
+// The curve params (weightBase/Gain/Saturation) shape the tanh knee, not the
+// marks; they are documented at the profile block. These magnitudes are tuned
+// by ear, not taken from a table — the sources fix the direction, not the value.
 const BASE_WEIGHTS = {
+    // Ictus — the rhythmic footfall (parse.ts's three-rule assignment): a stress
+    // and a slight broadening.
     ictusWeight: 0.9,
     ictusDuration: 0.35,
+    // Episema — the horizontal episema is the Solesmes lengthening mark; the note
+    // is broadened but only lightly stressed. Double episema broadens further.
     episemaWeight: 0.6,
     episemaDuration: 0.9,
     episemaDoubleDuration: 0.6,
+    // Strophicus — repeated notes (distropha/tristropha); a soft repercussion
+    // that broadens; the triple adds duration.
     strophicusWeight: 0.4,
     strophicusDuration: 0.8,
     strophicusTripleDuration: 0.6,
+    // Quilisma — the mark itself is a light, tremulous passing note (−0.3), but
+    // the rule is that the *preceding* note receives the stress and lengthening.
+    // Hence prev is positive and the quilisma negative — not a sign error.
     quilismaPrevWeight: 0.6,
     quilismaWeight: -0.3,
+    // Liquescent — a diminished, half-voiced note easing a consonant cluster:
+    // lighter and shorter.
     liquescentWeight: -0.4,
     liquescentDuration: -0.35,
+    // Initio — the first note of a group/melisma gets a gentle onset stress.
     initioWeight: 0.6,
     initioMelismaWeight: 0.3,
     initioMelismaDuration: 0.1,
+    // Accent — a tonic word-accent lands a stress.
     accentWeight: 0.4,
+    // Uppercase — an emphasized-capital syllable in GABC is conventionally the
+    // quiet incipit letter of a chant, so it is de-stressed and slightly quickened.
     uppercaseWeight: -0.7,
     uppercaseDuration: -0.2,
+    // Repercussion (pressus) — like the quilisma, the weight falls on the note
+    // *before* the repercussed unison; the oriscus element itself is light.
     repercussionPrevWeight: 0.5,
     repercussionPrevDuration: 0.4,
     repercussionOriscusWeight: -0.5,
-    oriscusWeight: -0.3, // soft, light note
-    oriscusDuration: -0.15, // taken slightly faster (accelerando)
-    oriscusPrevWeight: 0.3, // rhythmic support on the preceding note
+    // Oriscus — a soft, light note taken slightly faster (accelerando); its
+    // rhythmic support sits on the preceding note.
+    oriscusWeight: -0.3,
+    oriscusDuration: -0.15,
+    oriscusPrevWeight: 0.3,
+    // Break (a neume-internal division `!`/`/`) marks a fresh onset → a stress;
+    // dash (a bare context, e.g. an unaccented syllable) lightens and quickens.
     breakWeight: 0.6,
     dashWeight: -0.8,
     dashDuration: -0.2,
 };
+// Curve params (same fields on every profile below). They shape how the summed
+// weight becomes a velocity, not what each mark contributes:
+//   weightBase       — the velocity a note centres on; the tanh term swings ±gain
+//                      around it, so output sits roughly in [base−gain, base+gain].
+//   weightGain       — how loudly the rules speak: scales the tanh output (also
+//                      multiplied by ruleGain). Rises restrained→expressive as rules
+//                      gain authority (2.3 → 3 → 3.5), strict slightly under expressive.
+//   weightSaturation — the tanh knee divisor: larger = later compression, so louder
+//                      peaks survive; expressive lowers it (2.8) for a sharper dynamic.
+//   durationBase/Gain/Min/Max — the same shape applied to duration deltas, clamped.
+//   ruleGain         — global authority of the mark rules vs. positional shaping.
+//   contourScale     — how much melodic contour (rise/fall) colours velocity.
+//   neumeArch/durArch— the within-neume rise-and-fall (see phrasing.ts's arch).
+//   ictusBoost       — a final multiplier on ictus notes.
+// All tuned by ear; the ordering across profiles is the doctrine, the values are not.
 const ARTICULATION_PROFILES = {
     restrained: {
         weights: { ...BASE_WEIGHTS, accentWeight: 0.25, ictusDuration: 0.2 },

package/dist/engines/score/cadence.js

@@ -1,6 +1,6 @@
-// Cadence formulae run four to ten notes (Homan, Cadence in Gregorian Chant,
-// 1961, p. xiii). Take a window at the upper end so the longest figures fit,
-// with room for the approach; tail-matching ignores the extra leading notes.
+// Cadence formulae run four to ten notes [biblio: homan-cadence, p. xiii]. Take
+// a window at the upper end so the longest figures fit, with room for the
+// approach; tail-matching ignores the extra leading notes.
 const WINDOW = 8;
 /** Last up-to-WINDOW notes of a phrase, resolution note last. */
 function phraseFinalWindow(phrase) {

package/dist/engines/score/emitters/midi.js

@@ -1,5 +1,9 @@
-// Divisio → rest duration (in the same beat units as note durations). Mirrors
-// DIVISIO_DURATIONS in parse.ts; a phrase's terminal divisio becomes a rest.
+// Divisio → rest duration (in the same beat units as note durations); a phrase's
+// terminal divisio becomes a rest of this length. This is the *durational*
+// reading of the divisio hierarchy (canonical table in docs/score.md), distinct
+// from prosody.ts's analytic weights and phrasing.ts's shaping strengths — three
+// readings of the same bar-lines, each for its own purpose. Values mirror
+// DIVISIO_DURATIONS in parse.ts (the source of the fractional beat lengths).
 const DIVISIO_REST = {
     ",": 0.54, "`": 0.33, ";": 0.8, ":": 1.1, "::": 1.8,
 };

package/dist/engines/score/infer.js

@@ -1,5 +1,9 @@
 import { OFFICE_LABELS } from "../chant/types.js";
 import { MODES } from "../temper/modes.js";
+// Identify an ordinary chant by its opening words. Two movements have a second,
+// interior incipit because they are conventionally intoned from their second
+// phrase: the Gloria's "Et in terra pax" (the celebrant sings "Gloria in
+// excelsis") and the Credo's "Patrem omnipotentem" ("Credo in unum Deum").
 const ORDINARY_INCIPITS = [
     [/^kyrie/i, "ky"],
     [/^gloria/i, "gl"],
@@ -38,6 +42,9 @@ export function inferMode(ir) {
     }
     if (midis.length === 0)
         return undefined;
+    // The finalis is the last note of the chant — the fundamental assumption of
+    // modal analysis: a chant comes to rest on its mode's final [biblio:
+    // liber-usualis]. That pitch class picks the maneria (mode pair).
     const finalisPc = ((midis[midis.length - 1] % 12) + 12) % 12;
     const candidates = [];
     for (const [num, data] of MODES) {
@@ -48,7 +55,12 @@ export function inferMode(ir) {
         return undefined;
     if (candidates.length === 1)
         return candidates[0];
-    // Authentic vs plagal: melody mean above finalis → authentic
+    // Within a maneria the authentic mode ranges a fifth-and-more ABOVE the final,
+    // the plagal one straddles it (roughly a fourth below to a fifth above) [biblio:
+    // sunol-textbook]. So the mean pitch's height above the final separates them.
+    // The thresholds are asymmetric and tuned: a melody must sit a clear +3
+    // semitones above the final to read authentic, but only dip −1 below to read
+    // plagal (plagal melodies dip under the final; authentic ones rarely do).
     const finalisStep = midis[midis.length - 1];
     const mean = midis.reduce((s, v) => s + v, 0) / midis.length;
     const offset = mean - finalisStep;

package/dist/engines/score/ir.d.ts

@@ -1,4 +1,5 @@
-import type { Score, ParseResult } from "./types.js";
+import type { CompoundBeat, RhythmicType, Score, ParseResult } from "./types.js";
 import type { Scale } from "../temper/scale.js";
+export declare function classifyRhythmicType(beats: CompoundBeat[]): RhythmicType;
 export declare function buildIR(parsed: ParseResult, chant: Score["chant"], scale: Scale): Score;
 //# sourceMappingURL=ir.d.ts.map

package/dist/engines/score/ir.js

@@ -24,13 +24,13 @@ function rawToNote(raw, scale) {
             liquescent: raw.liquescent,
             strophicus: raw.strophicus,
             oriscus: raw.oriscus,
-            doubleEpisema: raw.doubleEpisema,
+            mora: raw.mora,
             weight: raw.weight,
         },
     };
 }
-// The salicus ictus note (its second-to-last ascending note) is prolonged —
-// Suñol, Textbook Ch. V. Modest, in the spirit of an episema lengthening.
+// The salicus ictus note (its second-to-last ascending note) is prolonged
+// [biblio: sunol-textbook, Ch. V]. Modest, in the spirit of an episema.
 const SALICUS_PROLONGATION = 1.3;
 function makeSyllable(lyric, notes) {
     const neume = classifyNeume(notes);
@@ -46,16 +46,16 @@ function partitionByIctus(annotated) {
     let currentIctusMidi;
     const closeGroup = (items, ictusMidi) => {
         const neumeTypes = new Set();
-        let hasDoubleEpisema = false;
+        let hasDoubleMora = false;
         for (const a of items) {
             neumeTypes.add(a.neumeType);
-            if (a.note.context.doubleEpisema)
-                hasDoubleEpisema = true;
+            if (a.note.context.mora === 2)
+                hasDoubleMora = true;
         }
         return {
             notes: items.map((a) => a.note),
             neumeTypes,
-            hasDoubleEpisema,
+            hasDoubleMora,
             ictusMidi,
             shape: "arsic",
         };
@@ -85,7 +85,7 @@ function classifyGroup(group, prev, apexMidi) {
     // regardless of melodic context.
     if (group.neumeTypes.has("salicus"))
         return "arsic";
-    if (group.hasDoubleEpisema && group.neumeTypes.has("clivis"))
+    if (group.hasDoubleMora && group.neumeTypes.has("clivis"))
         return "thetic";
     const groupIctusMidi = group.ictusMidi ?? group.notes[0].pitch.midi;
     // Rule 1: incise unity — at or after the apex, everything thetic.
@@ -111,14 +111,18 @@ function classifyGroup(group, prev, apexMidi) {
     // Tie-breaker: alternate from previous.
     return prev.shape === "arsic" ? "thetic" : "arsic";
 }
+// Classify each compound beat, stamp its notes, and return the beat sequence —
+// the A/T shape of the incise, which the rhythmic-type classifier and (later)
+// the chironomy renderer both read.
 function classifyCompoundBeats(annotated) {
     if (annotated.length === 0)
-        return;
+        return [];
     const groups = partitionByIctus(annotated);
     // Apex = highest-pitched ictus in the incise.
     const apexMidi = annotated
         .filter((a) => a.note.context.ictus)
         .reduce((max, a) => Math.max(max, a.note.pitch.midi), -Infinity);
+    const beats = [];
     for (let gi = 0; gi < groups.length; gi++) {
         const group = groups[gi];
         const prev = gi > 0 ? groups[gi - 1] : null;
@@ -127,7 +131,44 @@ function classifyCompoundBeats(annotated) {
             group.notes[ni].performance.rhythmicShape = group.shape;
             group.notes[ni].performance.rhythmicIndex = ni + 1;
         }
+        beats.push({ shape: group.shape, noteCount: group.notes.length });
     }
+    return beats;
+}
+// Le Guennant's rhythmic types (IV–VIII) from the beat sequence — how the incise's
+// compound beats chain [biblio: carroll-chironomy, pp. 22–26]. A type is emitted
+// only when the sequence genuinely fits; ambiguous shapes stay null (a wrong
+// analytic label is worse than none). Contraction (Type VIII) is Suñol's local
+// reading [biblio: sunol-textbook]: a thesis immediately followed by an arsis
+// mid-incise means two simple rhythms overlap at a shared ictus.
+export function classifyRhythmicType(beats) {
+    if (beats.length < 2)
+        return null; // a lone beat has no chaining; needs ≥ A–T
+    const seq = beats.map((b) => b.shape);
+    if (seq[0] !== "arsic")
+        return null; // an incise never begins thetic (Carroll p. 43)
+    const hasSeam = seq.some((s, i) => i > 0 && seq[i - 1] === "thetic" && s === "arsic");
+    if (!hasSeam) {
+        // A single rise-and-fall: arses, then theses, no interior thesis→arsis.
+        const arses = seq.filter((s) => s === "arsic").length;
+        const theses = seq.length - arses;
+        if (theses === 0)
+            return null; // all arsic, no resolution
+        if (arses === 1 && theses === 1)
+            return "IV"; // A–T
+        if (arses >= 2 && theses === 1)
+            return "V"; // A–A…–T
+        if (arses === 1 && theses >= 2)
+            return "VI"; // A–T–T…
+        return null;
+    }
+    // There is at least one thesis→arsis seam, so the incise chains multiple simple
+    // rhythms. Strict alternation A–T–A–T(…) is Carroll's Type VII; any other seam
+    // pattern is a contraction (Suñol) — Carroll's Type VIII.
+    const alternating = seq.every((s, i) => s === (i % 2 === 0 ? "arsic" : "thetic"));
+    if (alternating && seq.length >= 4)
+        return "VII";
+    return "VIII";
 }
 function applyCompoundBeats(phrases) {
     for (const phrase of phrases) {
@@ -137,12 +178,13 @@ function applyCompoundBeats(phrases) {
                 annotated.push({ note, neumeType: syl.neume.type });
             }
         }
-        classifyCompoundBeats(annotated);
+        phrase.beats = classifyCompoundBeats(annotated);
+        phrase.rhythmicType = classifyRhythmicType(phrase.beats);
     }
 }
 export function buildIR(parsed, chant, scale) {
     const phrases = [];
-    let currentPhrase = { syllables: [] };
+    let currentPhrase = { syllables: [], beats: [], rhythmicType: null };
     let currentNotes = [];
     let currentLyric = null;
     for (const event of parsed.events) {
@@ -167,7 +209,7 @@ export function buildIR(parsed, chant, scale) {
             }
             currentPhrase.divisio = event;
             phrases.push(currentPhrase);
-            currentPhrase = { syllables: [] };
+            currentPhrase = { syllables: [], beats: [], rhythmicType: null };
         }
     }
     if (currentLyric !== null && currentNotes.length > 0) {

package/dist/engines/score/modulation.js

@@ -1,8 +1,8 @@
 import { computeModalAffinity } from "../temper/modality.js";
 // How much a foreign mode must outscore the home mode (in normalised affinity)
 // before a phrase counts as leaning away. Calibrated against Suñol's worked
-// examples: at 0.25 the modulations he names in Christus resurgens (to mode 3)
-// register, while incidental modal colouring below that does not.
+// examples [biblio: sunol-textbook]: at 0.25 the modulations he names in Christus
+// resurgens (to mode 3) register, while incidental colouring below that does not.
 const MARGIN = 0.25;
 /** The pitch-class distribution of one phrase's notes (fractions summing to 1). */
 function phrasePcDistribution(phrase) {

package/dist/engines/score/parse.js

@@ -5,6 +5,11 @@ const DEFAULT_OPTIONS = {
     oct: 3,
     useVowelAccent: true,
 };
+// Per-clef diatonic-step offset. A GABC clef names the staff line it sits on
+// (c1–c4, f1–f4; the `b` variants also declare a flat), which fixes which pitch
+// the letters a–m read as. The value is subtracted from the letter's position
+// when anchoring it onto the gamut (see `pos` below), so the same letter reads
+// higher or lower depending on the clef in force.
 const CLEF_OFFSETS = new Map([
     ["c1", -3],
     ["c2", -1],
@@ -84,7 +89,7 @@ function parseNeume(notation, context) {
         let isLiquescent = false;
         let isStrophicus = false;
         let isOriscus = false;
-        let isDoubleEpisema = false;
+        let mora = 0;
         // Dash prefix (weak note)
         if (token[0] === "-") {
             token = token.slice(1);
@@ -143,16 +148,19 @@ function parseNeume(notation, context) {
             durWeight += weights.ictusDuration;
             ictus = true;
         }
-        // Episema (horizontal lengthening '.')
+        // Mora vocis — the GABC dot '.' lengthens THIS note (a held note before a
+        // pause). A double dot '..' is the double mora (a stronger lengthening at a
+        // major cadence); it adds to this note's duration, not the neume's first
+        // note — the dots belong to the note that carries them. (The horizontal
+        // episema is '_', handled with the ictus markers above.)
         if (modifiers.includes(".")) {
             w += weights.episemaWeight;
             durWeight += weights.episemaDuration;
             ictus = true;
-            // Double episema '..' — boost first note of neume
+            mora = 1;
             if (modifiers.includes("..")) {
-                isDoubleEpisema = true;
-                if (intermed[0])
-                    intermed[0]._durWeight += weights.episemaDoubleDuration;
+                mora = 2;
+                durWeight += weights.episemaDoubleDuration;
             }
         }
         // Strophicus (ss or vv = repeated/tremolo notes)
@@ -233,7 +241,7 @@ function parseNeume(notation, context) {
             liquescent: isLiquescent,
             strophicus: isStrophicus,
             oriscus: isOriscus,
-            doubleEpisema: isDoubleEpisema,
+            mora,
             _weight: w,
             _durWeight: durWeight,
         });
@@ -288,7 +296,7 @@ function parseNeume(notation, context) {
             liquescent: note.liquescent,
             strophicus: note.strophicus,
             oriscus: note.oriscus,
-            doubleEpisema: note.doubleEpisema,
+            mora: note.mora,
         };
     });
     return result;

package/dist/engines/score/phrasing.js

@@ -62,6 +62,9 @@ export function buildPhrasing(type = "lyrical", options = {}) {
         ...(options.overrides ?? {}),
     };
 }
+// Authentic modes reach a fifth or more above the final and pull harder toward
+// their tenor/reciting note; plagal modes straddle the final and pull less
+// [biblio: sunol-textbook]. These nudge the tenor and cadence gains accordingly.
 const MODE_TYPE_TENOR_MULTIPLIER = {
     authentic: 1.08,
     plagal: 0.92,
@@ -70,12 +73,20 @@ const MODE_TYPE_CADENCE_MULTIPLIER = {
     authentic: 1.05,
     plagal: 0.95,
 };
+// A more melismatic mode leans into its cadences; a syllabic one under-plays them.
 const MODE_TENDENCY_CADENCE_MULTIPLIER = {
     melismatic: 1.06,
     neumatic: 1.0,
     syllabic: 0.96,
     neutral: 1.0,
 };
+// The modal ethos → performance mapping. Each mode carries a mood epithet (the
+// Niedermeyer & d'Ortigue tradition [biblio: niedermeyer-ortigue], stored on
+// ModeProfile in modes.ts); these translate that mood into small shaping deltas.
+// The interpretation is tonus's own — the epithets are sourced, these numbers
+// are a tuned editorial gesture, deliberately small. Note the coherence: sadder
+// moods drop the velocity floor AND deepen the phrase curve (below), so they
+// read quieter and more arched; brighter moods do the reverse.
 const MODE_MOOD_BASE_VELOCITY_DELTA = {
     neutral: 0,
     serious: -0.01,
@@ -144,9 +155,17 @@ const DURATION_ARCH_FACTOR = 0.2;
 const DURATION_MIN = 0.2;
 const DURATION_MAX = 4.0;
 const TENOR_GAIN = 0.05;
+// Tenor pull falls linearly with pitch-class distance from the reciting tone and
+// reaches zero at 6 semitones (a tritone) — the far side of the octave, past
+// which a note no longer reads as gravitating to the tenor.
 const TENOR_DISTANCE_DIVISOR = 6;
 const CADENCE_VELOCITY_FACTOR = 0.5;
 const CADENCE_DURATION_FACTOR = 0.6;
+// The phrasing-side reading of the divisio (bar-line) hierarchy. This is the same
+// bar hierarchy tabulated canonically in docs/score.md and weighted for analysis
+// by prosody.ts's cadenceWeight ladder — but here the weights differ on purpose:
+// this is a *shaping* factor, so the virgula (`) gets 0 (a breath, no cadential
+// stress), where the analytic ladder still counts it. Do not unify the three.
 const DIVISIO_STRENGTH = {
     "::": 1.0,
     ":": 0.7,
@@ -214,8 +233,15 @@ export function applyPhrasing(events, profile, tenorPc) {
             const arsis = note.context.weight;
             const arsisRelative = (arsis - minArsis) / arsisSpan;
             const contourRelative = (note.pitch.midi - minStep) / stepSpan;
+            // A raised-cosine (Hann) window over the phrase: 0 at the ends, 1 at the
+            // middle, so each phrase swells and subsides — the Solesmes grand rythme,
+            // the phrase-arch [biblio: mocquereau-nombre]. `t` is the note's fractional
+            // position through the phrase.
             const t = (order + 0.5) / (noteEntries.length + 0.0001);
             const arch = 0.5 - 0.5 * Math.cos(2 * Math.PI * t);
+            // Blend the note's intrinsic arsic weight against its positional arch;
+            // `curve` is the mix knob (0 = follow the note's own weight, 1 = follow the
+            // phrase arch). The result is then re-centred on 0.5 and spread by velSpread.
             let velocity = arsisRelative * (1 - profile.curve) + arch * profile.curve;
             velocity += (contourRelative - VELOCITY_CENTER) * profile.contourVel;
             velocity =