tonus 0.1.8 → 0.5.0

package/dist/engines/chant/chant.js

@@ -1,13 +1,23 @@
-import { OFFICE_LABELS, MODE_LABELS } from "./types.js";
-import { CORPUS_OVERLAP } from "../../data/corpus-overlap.js";
+import { OFFICIA, MODI, CANTUS_QUERY_KEYS } from "./types.js";
+import { CORPUS_OVERLAP, CORPUS_FULL } from "../../data/corpus-overlap.js";
+import { attestationCutoff, chantAdmissible } from "./attest.js";
 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";
 import { NR_DATA, NR_SOURCE } from "../../data/nocturnale-romanum.js";
+// Office books — the antiphons and short responsories that fill weekday
+// office slots; see ChantSource in types.ts for why.
+import { AMS_DATA, AMS_SOURCE } from "../../data/ams.js";
+import { PSM_DATA, PSM_SOURCE } from "../../data/psm.js";
+// Further marked Solesmes books — see ChantSource in types.ts.
+import { CSE_DATA, CSE_SOURCE } from "../../data/cse.js";
+import { COT_DATA, COT_SOURCE } from "../../data/cot.js";
+import { KYRIALE } from "../../data/kyriale.js";
+import { entryToOrdinaryChant } from "./ordinary.js";
 function modusOf(mode) {
-    return mode != null ? (MODE_LABELS[mode] ?? null) : null;
+    return mode != null ? (MODI[mode] ?? null) : null;
 }
 const HEADER_FIELD_REGEX = /([A-Za-z0-9_-]+)\s*:\s*([^;]*);/g;
 function chantFromGABC(query) {
@@ -38,15 +48,29 @@ function chantFromGABC(query) {
     }
     const incipit = query.incipit ?? name ?? "";
     const mode = query.mode != null ? String(query.mode) : headerMode;
+    // The office-part header carries either a code ("in") or a Latin genre name
+    // ("Introitus", any casing) — normalize to the OfficeCode vocabulary so user
+    // chants honour the same contract as corpus chants; unrecognized values fall
+    // to "or" like an absent header.
+    const officeFromHeader = (() => {
+        if (!officePart)
+            return null;
+        const v = officePart.trim().toLowerCase();
+        for (const [code, label] of Object.entries(OFFICIA)) {
+            if (v === code || v === label.toLowerCase())
+                return code;
+        }
+        return null;
+    })();
     const office = (query.office
         ? (Array.isArray(query.office) ? query.office[0] : query.office)
-        : officePart ?? "or");
+        : officeFromHeader ?? "or");
     return [{
             id: `gabc:${incipit.toLowerCase().replace(/\s+/g, "_") || "untitled"}`,
             incipit,
             gabc: body,
             office,
-            genus: OFFICE_LABELS[office] ?? office,
+            genus: OFFICIA[office] ?? office,
             mode: mode ?? null,
             modus: modusOf(mode ?? null),
             pages: [],
@@ -57,7 +81,7 @@ function withLabels(c, source) {
     return {
         ...c,
         source,
-        genus: OFFICE_LABELS[c.office] ?? c.office,
+        genus: OFFICIA[c.office] ?? c.office,
         modus: modusOf(c.mode),
     };
 }
@@ -68,30 +92,145 @@ const CORPUS = [
     ...LH_DATA.map((c) => withLabels(c, LH_SOURCE)),
     ...AM_DATA.map((c) => withLabels(c, AM_SOURCE)),
     ...NR_DATA.map((c) => withLabels(c, NR_SOURCE)),
+    ...AMS_DATA.map((c) => withLabels(c, AMS_SOURCE)),
+    ...PSM_DATA.map((c) => withLabels(c, PSM_SOURCE)),
+    ...CSE_DATA.map((c) => withLabels(c, CSE_SOURCE)),
+    ...COT_DATA.map((c) => withLabels(c, COT_SOURCE)),
 ];
+// The Kyriale, addressable but not shelved — ruled 2026-08-04.
+//
+// It was a row in the ledger, and it should not have been: there is no Kyriale
+// in GregoBase. `ky` and `gr` are the same source id, PARTITIONED by the
+// extractor, which pulls `office-part = 'ky'` out of the Graduale query so the
+// ordinary can be routed to per-ordinary codes. Listing that slice beside its
+// parent counted the Graduale twice, and its `total: null` read as "not yet
+// measured" when there was no separate book to measure.
+//
+// But "not a book" and "not nameable" are different claims, and only the first
+// is true. These chants are sung repertoire, they are censused, and an id must
+// still resolve to exactly one chant — the census contract says so in as many
+// words. So they stay addressable by `id`, by `office: "or"`, and by
+// `ordinary`, and stay out of the shelf's book list and row count.
+const KYRIALE_CHANTS = KYRIALE.map(entryToOrdinaryChant);
+/** Everything nameable: the shelf, plus the ordinary that no shelf holds. */
+const ADDRESSABLE = [...CORPUS, ...KYRIALE_CHANTS];
 let _byId = null;
 function byId() {
     if (!_byId)
-        _byId = new Map(CORPUS.map((c) => [c.id, c]));
+        _byId = new Map(ADDRESSABLE.map((c) => [c.id, c]));
     return _byId;
 }
-const SOURCES = {
+// The book registry, and so the shelf `corpus()` reports. `ky` is deliberately
+// absent: it is a partition of `gr`, not a book (see CORPUS above). Its
+// bibliographic record still rides every kyriale chant's `source` — a caller
+// reading one is told which book it is printed in — but the Kyriale is not a
+// row in the ledger, because the Graduale already is.
+export const SOURCES = {
     gr: GR_SOURCE, lu: LU_SOURCE, la: LA_SOURCE, lh: LH_SOURCE, am: AM_SOURCE, nr: NR_SOURCE,
+    // office books — provenance, not acquisition
+    ams: AMS_SOURCE, psm: PSM_SOURCE,
+    cse: CSE_SOURCE, cot: COT_SOURCE,
 };
 // Tally a book's genre and mode distribution — computed once per code, cached.
 const _corpusCache = new Map();
+export function getCorpus(arg) {
+    if (arg == null)
+        return corpusLedger();
+    if (typeof arg === "object") {
+        const unknown = Object.keys(arg).filter((k) => k !== "book");
+        if (unknown.length) {
+            throw new Error(`corpus: unknown query key(s) ${unknown.map((k) => `"${k}"`).join(", ")} (expected book).`);
+        }
+        if (arg.book == null)
+            return corpusLedger();
+        return oneCorpus(arg.book);
+    }
+    return oneCorpus(arg);
+}
+/** Sort a raw office tally into the GenusCount rows corpus() reports. */
+function generaRows(tally) {
+    return Object.entries(tally)
+        .map(([office, count]) => ({
+        office: office,
+        genus: OFFICIA[office] ?? office,
+        count,
+    }))
+        .sort((a, b) => b.count - a.count || (a.office < b.office ? -1 : 1));
+}
+/** Sort a raw mode tally into ModeCount rows: 1–8 in order, then the rest. */
+function modesRows(tally) {
+    const rows = [];
+    for (const m of ["1", "2", "3", "4", "5", "6", "7", "8"]) {
+        const count = tally[m];
+        if (count)
+            rows.push({ mode: m, modus: MODI[m], count });
+    }
+    // The extractor buckets differentia forms, tonus peregrinus and unlabelled
+    // chants together under "other" — the same bucket the shipped counts report
+    // as `mode: null`, so the two tallies stay comparable row for row.
+    if (tally.other)
+        rows.push({ mode: null, modus: null, count: tally.other });
+    return rows;
+}
 /**
- * Metadata and content breakdown for one corpus book (`tonus.corpus`). Pass a
- * source code; get the book's bibliographic identity plus its genre and mode
- * distributions. Computed on first access from the loaded corpus, then cached.
+ * A book's pre-cut tally, or null where it cannot be measured. Only the
+ * extractor sees the un-cut book — by the time tonus loads, the keep set has
+ * already run — so this is read from the artifact, never derived here.
  */
-export function getCorpus(code) {
+function fullCount(code) {
+    const f = CORPUS_FULL[code];
+    if (!f)
+        return null;
+    return { total: f.total, genera: generaRows(f.genera), modes: modesRows(f.modes) };
+}
+/**
+ * The whole shelf: every book, plus the corpus-wide rollup. No argument
+ * answers the commonest question — what IS this corpus.
+ *
+ * `count` is how many chants tonus holds, each counted once — including the
+ * ordinary, which is addressable but not shelved. `listings` is how many rows
+ * the shelf has, where a melody printed in two books appears under both; the
+ * difference between them is the overlap.
+ */
+let _ledger = null;
+function corpusLedger() {
+    if (_ledger)
+        return _ledger;
+    // SOURCES is the registry — a book added there joins the ledger without an
+    // edit here, which is the failure mode every mirrored book list in this
+    // project has hit at least once.
+    const codes = Object.keys(SOURCES);
+    const books = codes.map((code) => oneCorpus(code));
+    // Tally over what tonus HOLDS, one row per chant — the same population
+    // `count` reports, so the breakdowns sum to the headline instead of to the
+    // listing total. Deduped by id, because a chant in two books is one chant.
+    const genera = {};
+    const modes = {};
+    for (const c of byId().values()) {
+        genera[c.office] = (genera[c.office] ?? 0) + 1;
+        const m = c.mode != null && MODI[c.mode] ? c.mode : "other";
+        modes[m] = (modes[m] ?? 0) + 1;
+    }
+    _ledger = {
+        count: byId().size,
+        listings: CORPUS.length,
+        // Sum only what was measured: a book outside GregoBase reports null rather
+        // than a false zero, and adding null in as 0 would understate the shelf
+        // while looking like a total.
+        total: codes.reduce((n, code) => n + (CORPUS_FULL[code]?.total ?? 0), 0),
+        genera: generaRows(genera),
+        modes: modesRows(modes),
+        books,
+    };
+    return _ledger;
+}
+function oneCorpus(code) {
     const cached = _corpusCache.get(code);
     if (cached)
         return cached;
     const src = SOURCES[code];
     if (!src)
-        throw new Error(`Unknown corpus code: "${code}" (expected gr, lu, la, lh, or am)`);
+        throw new Error(`Unknown corpus code: "${code}" (expected ${Object.keys(SOURCES).join(", ")})`);
     const chants = CORPUS.filter((c) => c.source.code === code);
     // Genre distribution — count by office code, descending by count.
     const officeCounts = new Map();
@@ -100,7 +239,7 @@ export function getCorpus(code) {
     let otherModes = 0;
     for (const c of chants) {
         officeCounts.set(c.office, (officeCounts.get(c.office) ?? 0) + 1);
-        if (c.mode != null && MODE_LABELS[c.mode]) {
+        if (c.mode != null && MODI[c.mode]) {
             modeCounts.set(c.mode, (modeCounts.get(c.mode) ?? 0) + 1);
         }
         else {
@@ -108,22 +247,26 @@ export function getCorpus(code) {
         }
     }
     const genera = [...officeCounts.entries()]
-        .map(([office, count]) => ({ office, genus: OFFICE_LABELS[office] ?? office, count }))
+        .map(([office, count]) => ({ office, genus: OFFICIA[office] ?? office, count }))
         .sort((a, b) => b.count - a.count);
     const modes = [];
     for (const m of ["1", "2", "3", "4", "5", "6", "7", "8"]) {
         const count = modeCounts.get(m);
         if (count)
-            modes.push({ mode: m, modus: MODE_LABELS[m], count });
+            modes.push({ mode: m, modus: MODI[m], count });
     }
     if (otherModes > 0)
         modes.push({ mode: null, modus: null, count: otherModes });
     // Pre-dedup relationships (precomputed in tonus-corpus — tonus can't derive
-    // them, since it stores only one copy of each shared chant).
+    // them, since it stores only one copy of each shared chant). Measured only for
+    // the GregoBase-sourced books; a book outside GregoBase (e.g. `nr`) has no
+    // entry, so overlap is reported as *unmeasured* (null) rather than a false zero.
     const ov = CORPUS_OVERLAP[code];
-    const shared = Object.entries(ov?.shared ?? {})
-        .map(([c, count]) => ({ code: c, count }))
-        .sort((a, b) => b.count - a.count);
+    const shared = ov
+        ? Object.entries(ov.shared)
+            .map(([c, count]) => ({ code: c, count }))
+            .sort((a, b) => b.count - a.count)
+        : null;
     const result = {
         code,
         book: src.book,
@@ -133,11 +276,12 @@ export function getCorpus(code) {
         editor: src.editor,
         scanSource: src.scanSource ?? null,
         count: chants.length,
-        total: ov?.total ?? chants.length,
-        unique: ov?.unique ?? chants.length,
+        total: ov?.total ?? null,
+        unique: ov?.unique ?? null,
         shared,
         genera,
         modes,
+        full: fullCount(code),
     };
     _corpusCache.set(code, result);
     return result;
@@ -155,23 +299,54 @@ export function resolveChant(id) {
 export function resolveChants(ids) {
     return ids.map(resolveChant).filter((c) => c !== null);
 }
+// The key set lives in types.ts (cycle-free); re-exported here for the verbs
+// that extend it (hour.ts).
+export { CANTUS_QUERY_KEYS };
 /**
- * Cross-corpus chant retrieval (`tonus.cantus`) over GR, LA, LH, and LU.
- * A `gabc` field bypasses the corpus and returns a single user
- * chant parsed from raw GABC (body or full file with headers).
+ * Cross-corpus chant retrieval (`tonus.cantus`) over every corpus book
+ * (the codes in SOURCES). A `gabc` field bypasses the corpus and returns a
+ * single user chant parsed from raw GABC (body or full file with headers).
  */
 export function getChants(query) {
-    if (!query || Object.keys(query).length === 0)
-        return [];
+    // A no-match returns []; a malformed query is a caller bug and throws with
+    // guidance (the reconciled query contract — see CODE-STANDARDS → Boundaries).
+    //
+    // An empty query is a MALFORMATION here, not a no-match, and that is
+    // deliberate: the filters below narrow from CORPUS, so an empty query has no
+    // honest answer. Returning [] would claim a search found nothing when none
+    // ran; returning the corpus would dress 2,767 listings as a result. The whole
+    // shelf is `corpus()`, which says so in its name.
+    if (!query || Object.keys(query).length === 0) {
+        throw new Error("cantus: an empty query matches nothing meaningful — pass a filter " +
+            `(one of ${[...CANTUS_QUERY_KEYS].join(", ")}), or a gabc string to parse.`);
+    }
+    const unknown = Object.keys(query).filter((k) => !CANTUS_QUERY_KEYS.has(k));
+    if (unknown.length > 0) {
+        throw new Error(`cantus: unknown query key(s) ${unknown.map((k) => `"${k}"`).join(", ")} ` +
+            `(expected ${[...CANTUS_QUERY_KEYS].join(", ")}).`);
+    }
     if (query.gabc)
         return chantFromGABC(query);
+    // `id` is a fast path, but it must still honour the other filters — returning
+    // a chant that fails them makes `cantus({ source, id })` silently ignore the
+    // source and report an id from any book as belonging to that one.
     const ids = toArray(query.id);
+    const ordinaries = toArray(query.ordinary);
+    // The default pool is the SHELF. The Kyriale is not on it (see KYRIALE_CHANTS
+    // above), so it is reached deliberately: by `id`, which must resolve any
+    // chant tonus holds, or by `ordinary`, which asks for a part of the Mass and
+    // could not mean anything else. A plain `cantus({ mode: 5 })` does not sweep
+    // the ordinary in, because the ordinary is not repertoire of that kind — you
+    // ask for a Kyrie, you do not stumble onto one.
+    let out = ordinaries ? KYRIALE_CHANTS : CORPUS;
     if (ids) {
         const map = byId();
-        const found = ids.map((id) => map.get(id)).filter((c) => !!c);
-        return found;
+        out = ids.map((id) => map.get(id)).filter((c) => !!c);
+    }
+    if (ordinaries) {
+        const set = new Set(ordinaries);
+        out = out.filter((c) => c.ordinary != null && set.has(c.ordinary));
     }
-    let out = CORPUS;
     const sources = toArray(query.source);
     if (sources) {
         const set = new Set(sources);
@@ -191,6 +366,21 @@ export function getChants(query) {
         const needle = query.incipit.toLowerCase();
         out = out.filter((c) => c.incipit.toLowerCase().includes(needle));
     }
+    // ── Attestation: the repertoire AS OF a date ───────────────────────────────
+    // The analogue of `festum({ before })` over the calendar. The corpus ships
+    // 20th-century Solesmes editions, so the BOOK dates nothing; CANTUS's
+    // manuscript index does. `century` is the earliest surviving witness — a
+    // terminus ante quem, so this answers "what is ATTESTED by then", never "what
+    // existed then". A chant CANTUS cannot date is excluded rather than assumed
+    // old: the filter states what is evidenced, and silence is not evidence.
+    // One rule, one door-keeper: the same chantAdmissible() the day verbs use,
+    // so `cantus({ before })` and `proprium({ feast, before })` can never drift.
+    {
+        const cutoff = attestationCutoff(query, "cantus");
+        if (cutoff != null || query.cursus) {
+            out = out.filter((c) => chantAdmissible(c.id, cutoff, query.cursus));
+        }
+    }
     const sort = query.sort ?? "incipit";
     const sorted = [...out].sort((a, b) => {
         if (sort === "id")

package/dist/engines/chant/data/compline.js

@@ -9,7 +9,8 @@
 //
 // Ordo structure after the traditional Roman Compline; seasonal assignment and
 // the Marian rotation follow standard practice, cross-checked against
-// bbloomf/compline (public domain). See docs/chant.md and BIBLIOGRAPHY.md.
+// [biblio: bloomfield-compline] (public domain). See
+// ../../../../docs/api/chant.md and ../../../../BIBLIOGRAPHY.md.
 // Compline's psalmody (Ps 4, 30 vv. 2–6, 90, 133) is not hand-listed here — it
 // comes from the extracted DO Tridentine scheme via
 // `officePsalmPortions("Completorium", …)`. Only the ordo structure and the

package/dist/engines/chant/data/masses.d.ts

@@ -1,18 +1,70 @@
-import { type Season, type Grade } from "../../cal/types.js";
+import { type Grade } from "../../cal/types.js";
+/**
+ * The Kyriale's rubric categories, in the book's own order. A day resolves to
+ * exactly one; the masses carrying that rubric are the masses it may sing.
+ */
+export type MassRubric = "paschal" | "class-i" | "class-ii" | "class-iii" | "bvm" | "sunday" | "commemoration" | "feria" | "sunday-penitential" | "feria-penitential";
+export declare const WHOLE_MASS_RUBRICS: ReadonlySet<MassRubric>;
 export interface MassEntry {
     id: string;
     mass: number;
     title: string;
-    seasons: Season[];
-    grades: Grade[];
-    days: ("dominica" | "feria")[];
+    rubric: MassRubric;
+    heading: string;
     bvm: boolean;
     credos: string[];
     notes: string;
 }
+export declare const CLASS_I_GRADES: readonly Grade[];
+export declare const CLASS_II_GRADES: readonly Grade[];
+export declare const CLASS_III_GRADES: readonly Grade[];
+export declare const FERIA_GRADES: readonly Grade[];
 export declare const AD_LIB: {
     standard: MassEntry;
     bvm: MassEntry;
 };
 export declare const MASSES: Map<number, MassEntry>;
+/** The masses the book appoints under one rubric, in mass-number order. */
+export declare function massesForRubric(rubric: MassRubric): MassEntry[];
+export interface MassCentury {
+    /** Earliest century the editors give (10 = the 900s); null where they print "?". */
+    from: number | null;
+    /** Latest, for a printed span like "XI-XIII. s."; equals `from` for a single. */
+    to: number | null;
+    /** A parenthesized alternative reading, e.g. "(X) XIV-XVI. s." → 10. */
+    alt?: number;
+    /** The part's century was read from position, not from a legible incipit. */
+    inferred?: true;
+    /** The token exactly as printed, so the claim stays auditable. */
+    printed: string;
+}
+/** mass number → ordinary code → what the Kyriale prints. */
+export declare const MASS_CENTURY: Record<number, Partial<Record<string, MassCentury>>>;
+/** Credo number (roman, as the Kyriale names them) → its ascription. */
+export declare const CREDO_CENTURY: Record<string, MassCentury>;
+export declare const ORDINARY_LATEST_YEAR = 1324;
+/**
+ * Whether a Kyriale setting is early enough to sing.
+ *
+ * PER PART, never per mass. The Kyriale is a 19th-c Solesmes GROUPING of chants
+ * from different centuries — which is why its ascriptions are per-part in the
+ * first place. Mass XI "Orbis factor" is a 10th-c Kyrie + 10th Gloria + 10th
+ * Sanctus with a 14th-c Agnus bolted on; a whole-mass test would lose the
+ * ordinary Sunday mass over one late part. The book licenses the per-part
+ * result outright — "chants from one Mass may be used together with those from
+ * others, the Ferial Masses excepted" — so a dropped part simply borrows, which
+ * is the machinery entriesForOffice() already runs.
+ *
+ * `alt` wins where the editors print one. Mass XI's Kyrie reads "(X) XIV-XVI.
+ * s." — the parenthetical is the melody, the late reading is whichever
+ * manuscript they transcribed. Modern scholarship agrees: Corpus Monodicum
+ * (Brill, 2024) dates Orbis factor to the 10th-12th c.
+ *
+ * An undated part (the editors' own "?. s.") is ADMITTED, not excluded —
+ * undated is not late, and excluding it would repeat the mistake that killed
+ * the attestation filter. Same for a part with no entry at all: this rule can
+ * only remove a setting the Kyriale itself dates late, never one it is silent
+ * about.
+ */
+export declare function partWithinEra(mass: number | null | undefined, office: string | null | undefined, toYear?: number): boolean;
 //# sourceMappingURL=masses.d.ts.map