tonus 0.11.0 → 0.12.0

package/dist/engines/chant/chant.js

@@ -149,7 +149,19 @@ const CORPUS = [
 // 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);
+//
+// Not shelved, but CITED: each entry carries the books that print it (gr, lu)
+// and their pages, so its by-book map is registered here the same way a corpus
+// record's is. That is what lets `cantus({ id, source: "lu" })` answer with the
+// Liber Usualis's leaf number instead of nothing.
+const KYRIALE_CHANTS = KYRIALE.map((entry) => {
+    const chant = entryToOrdinaryChant(entry);
+    const byBook = entry.pages;
+    if (byBook && !Array.isArray(byBook)) {
+        PAGES_BY_BOOK.set(chant.id, byBook);
+    }
+    return chant;
+});
 /** Everything nameable: the shelf, plus the ordinary that no shelf holds. */
 const ADDRESSABLE = [...CORPUS, ...KYRIALE_CHANTS];
 let _byId = null;

package/dist/engines/chant/ordinary.js

@@ -21,16 +21,20 @@ function resolveMasses(feast) {
         return resolved;
     return [feast.marian ? AD_LIB.bvm : AD_LIB.standard];
 }
-// The numbered kyriale runs 1–18. The book's appendix — ad libitum settings and
-// the like — carries synthetic numbers above that range, which no feast's
-// `masses` list ever names; those settings are therefore reachable only as a
-// last-resort fallback here, or by direct `ordinarium({ mass })` query.
-const NUMBERED_MASS_MAX = 18;
+// Where the Kyriale prints an entry. Only the "mass" section carries a mass
+// number; the others are addressed by section. The appendix used to carry its
+// Graduale page as a "mass" (Clemens Rector was mass 75, the Requiem 94, 101
+// and 102), and the two ad libitum Kyries whose incipits carry a numeral
+// collided with Masses VI and X.
+const KYRIALE_SECTIONS = new Set([
+    "mass", "credo", "sprinkling", "ad-libitum", "requiem",
+]);
+const SPRINKLING_OFFICES = new Set(["as", "va"]);
+// The Cantus ad libitum, which no feast's `masses` list ever names: reachable
+// on the appendix's solemnity turn, as a last-resort fallback here, or by a
+// direct `ordinarium({ section: "ad-libitum" })` query.
 function isAdLibitum(entry) {
-    // Most appendix settings sit above the numbered range, but two ad libitum
-    // Kyries are numbered 6 and 10 in the source data, colliding with the
-    // numbered masses — for those the incipit is the only discriminator.
-    return (entry.mass ?? 0) > NUMBERED_MASS_MAX || /\(ad lib\./i.test(entry.incipit);
+    return entry.section === "ad-libitum";
 }
 /** Prefer a proper numbered setting over an appendix one at equal standing. */
 function adLibLast(a, b) {
@@ -38,12 +42,13 @@ function adLibLast(a, b) {
 }
 // The Missa pro defunctis settings belong to the Requiem, not to the temporal or
 // sanctoral day. They stay out of every calendar-driven pick and remain
-// reachable only by direct `ordinarium({ mass })` query. Note the Requiem's own
-// dismissal carries the bare incipit "Requiescant" — no "(in Miss. def.)"
-// qualifier — so it must be named here explicitly, or it leaks through the
-// last-resort appendix onto every feria whose mass prints no dismissal.
+// reachable only by direct `ordinarium({ section: "requiem" })` query. The
+// Requiem's own dismissal carries the bare incipit "Requiescant", which is why
+// the section is data and not an incipit test: left to the incipit it leaked
+// through the last-resort appendix onto every feria whose mass prints no
+// dismissal.
 function isRequiem(entry) {
-    return /in\s+Miss\.\s*def|defunct|requiescant/i.test(entry.incipit);
+    return entry.section === "requiem";
 }
 /**
  * Deterministic rotation of a preference list by year.
@@ -104,8 +109,14 @@ function appendixLeadsThisYear(rubric, poolSize, year) {
     const n = poolSize + 1;
     return ((year % n) + n) % n === poolSize;
 }
+// The appendix in the book's own order. Its settings carry no mass number, so
+// the Graduale's page orders them: Kyrie I to XI, then the Glorias, and so on.
+function grPage(entry) {
+    const page = /\d+/.exec(entry.pages?.gr?.[0]?.page ?? "")?.[0];
+    return page == null ? Number.POSITIVE_INFINITY : Number(page);
+}
 function appendixFor(office, pool) {
-    return pool.filter((e) => e.office === office && isAdLibitum(e) && !isRequiem(e)).sort((a, b) => (a.mass ?? 0) - (b.mass ?? 0) || (a.id < b.id ? -1 : 1));
+    return pool.filter((e) => e.office === office && isAdLibitum(e) && !isRequiem(e)).sort((a, b) => grPage(a) - grPage(b) || (a.id < b.id ? -1 : 1));
 }
 /**
  * Candidate settings for one ordinary slot, most preferred first.
@@ -183,7 +194,7 @@ function entriesForOffice(office, massNumbers, year, appendixLeads, wholeMass =
     // is the standing answer — its ad libitum variants must NOT rotate against it
     // as equals, or the appendix would be sung more often than the rite itself.
     // They arrive on the appendix turn like every other appendix setting.
-    const unnumbered = pool.filter((e) => e.office === office && e.mass == null && !isRequiem(e));
+    const unnumbered = pool.filter((e) => e.office === office && SPRINKLING_OFFICES.has(office) && !isRequiem(e));
     const plain = unnumbered.filter((e) => !isAdLibitum(e));
     if (plain.length)
         return rotate(plain, year);
@@ -280,11 +291,21 @@ export function entryToOrdinaryChant(entry) {
     const ordinary = ORDINARY_OFFICES.has(entry.office)
         ? entry.office
         : "ke";
+    // The Kyriale's citation. `ky` is a category, not a volume, so it can never
+    // be cited — which is why these chants shipped with books: ["ky"] and no page
+    // at all, and nothing downstream could name where to find them. But they ARE
+    // printed: the extractor now carries the Graduale's and the Liber Usualis's
+    // listings on every entry. `books` is those volumes, owner first; `pages` is
+    // the OWNER's, exactly as chant.ts's withLabels() does for a shelf record —
+    // presentAs() swaps in the asked-for book's when a caller names one. An entry
+    // with no citation still falls back to its own printing, so it stays findable.
+    const books = (entry.books?.length ? entry.books : ["ky"]);
+    const pages = entry.pages?.[books[0]] ?? [];
     return {
         id: entry.id,
         incipit: entry.incipit,
         gabc: entry.gabc,
-        books: ["ky"],
+        books,
         office: "ky",
         // The genus follows the office code, as everywhere else — OFFICIA.ky.
         // It read "Ordinarium" while the office read "or", which was tonus's own
@@ -292,11 +313,15 @@ export function entryToOrdinaryChant(entry) {
         genus: OFFICIA.ky,
         mode: entry.mode ? String(entry.mode) : null,
         modus: entry.mode ? (MODI[String(entry.mode)] ?? null) : null,
-        pages: [],
+        pages,
+        // Still KY_SOURCE: the bibliographic note says a singer is holding the
+        // Kyriale, which is true, and is a different claim from which shelved
+        // volumes print it. `books` carries that.
         source: KY_SOURCE,
         ordinary,
         ordinarium: ORDINARIA[ordinary] ?? entry.incipit,
         mass: entry.mass ?? 0,
+        section: entry.section,
     };
 }
 // Maundy Thursday (In Cena Domini) is a Triduum exception: it retains a full
@@ -441,7 +466,7 @@ function assertFeasts(feasts, method) {
             throw new Error(`${method}: feast must be a Feast (from tonus.festum) — got ${typeof f}`);
     }
 }
-const ORDINARIUM_QUERY_KEYS = new Set([...CANTUS_QUERY_KEYS, "feast", "ordinary", "mass"]);
+const ORDINARIUM_QUERY_KEYS = new Set([...CANTUS_QUERY_KEYS, "feast", "ordinary", "mass", "section"]);
 /**
  * Mass ordinary retrieval (`tonus.ordinarium`) from the Kyriale. A feast
  * drives mass selection; `mass` pins a kyriale number directly.
@@ -459,6 +484,10 @@ export function getOrdinary(query) {
     if (query.ordinary) {
         assertOrdinaryCodes(Array.isArray(query.ordinary) ? query.ordinary : [query.ordinary], "ordinarium");
     }
+    if (query.section != null && !KYRIALE_SECTIONS.has(query.section)) {
+        throw new Error(`ordinarium: unknown section "${query.section}" ` +
+            `(expected ${[...KYRIALE_SECTIONS].join(", ")}).`);
+    }
     const feasts = toArray(query.feast);
     assertFeasts(feasts, "ordinarium");
     // `mode` accepts a scalar or an array, with cantus's semantics: match any.
@@ -480,7 +509,7 @@ export function getOrdinary(query) {
             return ordinaryForFeast(f, query.mass, filterModes, adm);
         });
     }
-    else if (query.mass != null || query.ordinary) {
+    else if (query.mass != null || query.ordinary || query.section) {
         // Direct kyriale query without feast context — same admissibility rule as
         // cantus, so the two doors cannot disagree.
         let entries = KYRIALE.slice();
@@ -490,6 +519,8 @@ export function getOrdinary(query) {
         }
         if (query.mass != null)
             entries = entries.filter((e) => e.mass === query.mass);
+        if (query.section)
+            entries = entries.filter((e) => e.section === query.section);
         if (query.ordinary)
             entries = entries.filter((e) => e.office === query.ordinary);
         if (filterModes)
@@ -502,6 +533,9 @@ export function getOrdinary(query) {
         return [];
     }
     // Apply remaining CantusQuery filters
+    if (feasts && query.section) {
+        results = results.filter((c) => c.section === query.section);
+    }
     if (query.incipit) {
         const needle = query.incipit.toLowerCase();
         results = results.filter((c) => c.incipit.toLowerCase().includes(needle));

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

@@ -1,4 +1,5 @@
 import type { Season, Grade, Feast } from "../cal/types.js";
+import type { KyrialeSection } from "../../data/kyriale.js";
 export type { Season, Grade, Feast };
 export type OfficeCode = "an" | "al" | "ca" | "co" | "gr" | "hy" | "in" | "of" | "ps" | "re" | "rb" | "se" | "tr" | "tp" | "or" | "ky" | "va" | "im" | "pa" | "su";
 export type OrdinaryCode = "ke" | "gl" | "cr" | "sa" | "ag" | "be" | "it" | "as" | "va";
@@ -92,11 +93,14 @@ export interface Chant {
     ordinary?: OrdinaryCode;
     ordinarium?: string;
     mass?: number;
+    section?: KyrialeSection;
 }
 export interface OrdinaryChant extends Chant {
     ordinary: OrdinaryCode;
     ordinarium: string;
+    /** One of Masses I–XVIII; 0 outside the numbered Masses (see `section`). */
     mass: number;
+    section: KyrialeSection;
 }
 export interface GenusCount {
     office: OfficeCode;
@@ -219,7 +223,10 @@ export interface PropriumQuery extends CantusQuery {
 export interface OrdinariumQuery extends CantusQuery {
     feast?: Feast | Feast[];
     ordinary?: OrdinaryCode;
+    /** One of Masses I–XVIII. */
     mass?: number;
+    /** A section of the Kyriale: "mass", "credo", "sprinkling", "ad-libitum", "requiem". */
+    section?: KyrialeSection;
 }
 export interface OfficiumQuery extends CantusQuery {
     feast?: Feast | Feast[];

package/docs/api/chant.md

@@ -311,6 +311,18 @@ The Kyriale is a **partition of the Graduale**, so it is not a `source` and not
 a row in the shelf. It stays nameable by `id` and by the part of the Mass it
 belongs to.
 
+It is not a book, but it is **printed in** books, and it says which: every
+ordinary chant carries `books: ["lu", "gr"]` and the Graduale's and the Liber
+Usualis's pages, so it can be cited like anything else on the shelf.
+
+```js
+tonus.cantus({ id: "gregobase:31", source: "gr" })[0].pages; // [{ page: "28*", … }]
+tonus.cantus({ id: "gregobase:31", source: "lu" })[0].pages; // [{ page: "37",  … }]
+```
+
+`source` stays `ky` when no book is named — the note a singer holding the
+Kyriale would want — and `ky` is still absent from the book registry.
+
 A plain search does not sweep it in: `{ mode: 5 }` returns the shelf. Ask for a
 Kyrie and you get Kyries.
 
@@ -393,8 +405,12 @@ interface PropriumQuery extends CantusQuery {
 `ordinarium(query?)` retrieves the fixed chants of the Mass from the
 Kyriale. A feast drives mass selection through its `masses` list, the
 masses the day's Kyriale RUBRIC appoints, derived as described in
-[calendar.md](calendar.md#the-days-feasts--festum); `mass` pins a kyriale
-number directly. Where the rubric names several masses, the year rotates
+[calendar.md](calendar.md#the-days-feasts--festum); `mass` pins one of the
+eighteen numbered Masses directly, and `section` asks for a part of the book:
+`mass` (Masses I–XVIII), `credo` (Credo I–VI), `sprinkling` (Asperges me,
+Vidi aquam), `ad-libitum` (the Cantus ad libitum) or `requiem` (the Missa pro
+defunctis). Only the `mass` section carries a mass number; every other entry
+reads `mass: 0`. Where the rubric names several masses, the year rotates
 through them (same feast, same year → same answer, every time), and sibling
 printings under one number (Mass I prints two dismissals; Mass XVII prints
 Kyrie A/B/C) rotate with it. Slots resolve independently, which the book
@@ -408,7 +424,7 @@ const [easter] = tonus.festum({ date: new Date("2026-04-05") });
 tonus.ordinarium({ feast: easter });
 // ky  Kyrie I       (mass 1) — Lux et origo, Paschal time, every year
 // gl  Gloria I      (mass 1)
-// cr  Credo III     (mass 3) — the credo rotates on its own cycle
+// cr  Credo III     (mass 0) — the credo rotates on its own cycle
 // sa  Sanctus I     (mass 1)
 // ag  Agnus Dei I   (mass 1)
 // it  Ite Ia        (mass 1)
@@ -425,7 +441,7 @@ sings Mass XVI whole with the Mass II Benedicamus. The ad libitum appendix
 is a **solemnity boost**, reachable only under the festal rubrics (it takes
 its turn in the rotation once every _n + 1_ years); it never reaches a
 penitential day or a feria, and the Requiem settings stay out of every
-calendar-driven pick (reachable by `ordinarium({ mass: 102 })` only). The
+calendar-driven pick (reachable by `ordinarium({ section: "requiem" })` only). The
 Triduum returns no ordinary at all: Good Friday has no Mass, and the
 Vigil's ordinary belongs to Easter. A pinned `mass` overrides the Triduum
 rule and the rotation both.
@@ -440,6 +456,7 @@ me** (`as`) otherwise.
 ```js
 tonus.ordinarium({ ordinary: "ke" }); // every Kyrie
 tonus.ordinarium({ mass: 9, ordinary: "gl" }); // Gloria of Cum jubilo
+tonus.ordinarium({ section: "ad-libitum", ordinary: "ke" }); // the eleven ad libitum Kyries
 ```
 
 | `ordinary` | `ordinarium`                                  |
@@ -458,13 +475,15 @@ tonus.ordinarium({ mass: 9, ordinary: "gl" }); // Gloria of Cum jubilo
 interface OrdinaryChant extends Chant {
   ordinary: OrdinaryCode; // movement code
   ordinarium: string; // Latin movement name, "Kyrie eleison" …
-  mass: number;
+  mass: number; // 1–18, or 0 outside the numbered Masses
+  section: "mass" | "credo" | "sprinkling" | "ad-libitum" | "requiem";
 }
 
 interface OrdinariumQuery extends CantusQuery {
   feast?: Feast | Feast[];
   ordinary?: OrdinaryCode;
-  mass?: number;
+  mass?: number; // 1–18
+  section?: "mass" | "credo" | "sprinkling" | "ad-libitum" | "requiem";
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tonus",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "type": "module",
   "description": "Medieval music analysis: GABC plainchant exports, liturgical calendar, tuning systems, ephemeris, and the harmony of the spheres",
   "author": "Jeffrey Pierce <jeffrey@jeffreypierce.net>",