tonus 0.1.8 → 0.5.0

package/dist/engines/cal/calendar.d.ts

@@ -14,8 +14,9 @@ export declare function buildCalendar(year: number): Map<string, CalEntry[]>;
  * Calendar lookup (`tonus.festum`). Returns matching feasts sorted
  * `day asc, rank desc` — for a date, the primary feast plus concurrent
  * feasts; for a `from`/`to` range, every day flattened; with no query,
- * the current liturgical year. Dates are UTC-canonical: build them from
- * ISO strings or `Date.UTC`.
+ * the default-epoch day (Guido d'Arezzo's era); for a filter-only query,
+ * the liturgical year containing that epoch. Dates are UTC-canonical:
+ * build them from ISO strings or `Date.UTC`.
  */
 export declare function getFeast(query?: FeastQuery): Feast[];
 //# sourceMappingURL=calendar.d.ts.map

package/dist/engines/cal/calendar.js

@@ -17,15 +17,12 @@
 // 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 "../chant/data/masses.js";
+import { feastKeptBy } from "./data/eras.js";
+import { massesForRubric, CLASS_I_GRADES, CLASS_II_GRADES, CLASS_III_GRADES, } 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";
+import { TEMPORA, entryGrade, gradeOrder, BVM_FEAST_IDS, APOSTOLIC_FEAST_IDS, PENITENTIAL_SEASONS, } from "./types.js";
 const _calCache = new Map();
 const _anchorCache = new Map();
-// Preferred mass order; ad libitum (mass 0) is handled separately in ordinary.ts.
-const DEFAULT_MASSES = [
-    8, 9, 11, 1, 2, 3, 4, 5, 6, 7, 10, 12, 13, 14, 15, 16, 17, 18,
-];
 export function getAnchors(year) {
     if (_anchorCache.has(year))
         return _anchorCache.get(year);
@@ -142,29 +139,68 @@ function findSeason(date) {
         return s("quad", a.ashWednesday, a.easter);
     if (date >= a.easter && date < trinitySunday(a))
         return s("pasc", a.easter, trinitySunday(a));
-    if (date >= trinitySunday(a) && date < next.adventFirstSunday)
-        return s("pent", trinitySunday(a), next.adventFirstSunday);
+    // Advent of THIS year closes the season after Pentecost — the `adv` branch
+    // above has already claimed those days, so reaching for next year's Advent
+    // put the end date sixteen months out and made the season 547 days long.
+    if (date >= trinitySunday(a) && date < a.adventFirstSunday)
+        return s("pent", trinitySunday(a), a.adventFirstSunday);
     return s("epi", epiphanySunday(a), a.septuagesima);
 }
-function selectMasses(id, grade, season, date) {
-    const dowCode = date.getUTCDay() === 0 ? "dominica" : "feria";
-    const requireBvm = BVM_FEAST_IDS.has(id);
-    const matches = [];
-    for (const num of DEFAULT_MASSES) {
-        const mass = MASSES.get(num);
-        if (!mass)
-            continue;
-        if (requireBvm !== mass.bvm)
-            continue;
-        if (!mass.seasons.includes(season))
-            continue;
-        if (!mass.grades.includes(grade))
-            continue;
-        if (!mass.days.includes(dowCode))
-            continue;
-        matches.push(num);
+// The Sunday-as-such grades. Per the canonical grade table, an ordinary Sunday is
+// `semiduplex`, an Advent Sunday `semiduplex-ii`, a Lent Sunday `semiduplex-i` —
+// so a day that is merely a Sunday is recognised by carrying one of these, while
+// a feast that outranks the Sunday carries a duplex grade and takes its class.
+const SUNDAY_GRADES = [
+    "semiduplex-i",
+    "semiduplex-ii",
+    "semiduplex",
+];
+/**
+ * The Kyriale rubric this day falls under — the book classifies by RANK and
+ * appoints one category per day [biblio: liber-usualis, Kyriale].
+ *
+ * Order matters. "In Paschal Time" is a season rubric and governs inside
+ * Paschaltide. The Sunday categories must be tested before the class tiers,
+ * because the Sunday grades are the semiduplex variants — which would otherwise
+ * be claimed by the I, II and III class tiers and hand a Lent Sunday a
+ * first-class mass.
+ *
+ * An open editorial question: should a I class feast inside Paschaltide
+ * (Ascension, Pentecost) reach for the I-class pair II/III instead of Lux et
+ * Origo? The book's heading is unqualified, so Paschaltide wins here.
+ */
+function rubricForDay(id, grade, season, date) {
+    const isSunday = date.getUTCDay() === 0;
+    const penitential = PENITENTIAL_SEASONS.has(season);
+    // The book's own subject category outranks the season: a BVM feast in
+    // Paschaltide is "For feasts of the Blessed Virgin", not "In Paschal Time" —
+    // paschal-first left Cum jubilo unreachable for the whole of Eastertide.
+    if (BVM_FEAST_IDS.has(id))
+        return "bvm";
+    if (season === "pasc")
+        return "paschal";
+    if (isSunday && SUNDAY_GRADES.includes(grade)) {
+        return penitential ? "sunday-penitential" : "sunday";
     }
-    return matches;
+    if (CLASS_I_GRADES.includes(grade))
+        return "class-i";
+    if (CLASS_II_GRADES.includes(grade))
+        return "class-ii";
+    if (CLASS_III_GRADES.includes(grade))
+        return "class-iii";
+    if (grade === "simplex")
+        return "commemoration";
+    return penitential ? "feria-penitential" : "feria";
+}
+// The masses the day may sing: those the Kyriale appoints under its rubric, in
+// the book's own numbering. Where a rubric names several — II class 1–5 — that
+// numbering IS the invitation to choose, and ordinary.ts rotates among them.
+//
+// This replaced a `seasons ∩ grades ∩ days` intersection that returned every
+// mass not positively excluded, which is how Easter came to be offered masses IV
+// and V (appointed for the II class). See the header of chant/data/masses.ts.
+function selectMasses(id, grade, season, date) {
+    return massesForRubric(rubricForDay(id, grade, season, date)).map((m) => m.mass);
 }
 function calEntryToFeast(entry, season, d) {
     const id = entry.id ?? "";
@@ -177,7 +213,7 @@ function calEntryToFeast(entry, season, d) {
         ritus,
         grade,
         season: season.code,
-        tempus: TEMPUS_NAMES[season.code],
+        tempus: TEMPORA[season.code],
         seasonStart: season.start,
         seasonEnd: season.end,
         date: d,
@@ -208,19 +244,41 @@ function feastsForDate(date) {
     const season = findSeason(d);
     return entries.map((e) => calEntryToFeast(e, season, d));
 }
+const FEAST_QUERY_KEYS = new Set([
+    "date", "from", "to", "nomen", "season", "grade", "marian", "apostolic",
+    "before",
+]);
 /**
  * Calendar lookup (`tonus.festum`). Returns matching feasts sorted
  * `day asc, rank desc` — for a date, the primary feast plus concurrent
  * feasts; for a `from`/`to` range, every day flattened; with no query,
- * the current liturgical year. Dates are UTC-canonical: build them from
- * ISO strings or `Date.UTC`.
+ * the default-epoch day (Guido d'Arezzo's era); for a filter-only query,
+ * the liturgical year containing that epoch. Dates are UTC-canonical:
+ * build them from ISO strings or `Date.UTC`.
  */
 export function getFeast(query) {
+    // A bare Date is the natural guess, and it has no own enumerable keys — so
+    // without this it would read as "no query" and quietly return the default
+    // epoch, the same plausible-looking wrong answer the unknown-key guard below
+    // exists to prevent. Say what was meant instead.
+    if (query instanceof Date) {
+        throw new Error(`festum: pass the date as a query — festum({ date }), not festum(date)`);
+    }
     if (!query || Object.keys(query).length === 0) {
         return feastsForDate(DEFAULT_EPOCH);
     }
+    // Reject unknown keys rather than silently falling through to the default
+    // epoch — `festum({ month: 12, day: 25 })` (a natural guess) would otherwise
+    // return a plausible-looking wrong answer. Fail loudly on the typo instead.
+    const unknown = Object.keys(query).filter((k) => !FEAST_QUERY_KEYS.has(k));
+    if (unknown.length > 0) {
+        throw new Error(`festum: unknown query key(s) ${unknown.map((k) => `"${k}"`).join(", ")} ` +
+            `(expected ${[...FEAST_QUERY_KEYS].join(", ")})`);
+    }
     let results;
     if (query.date) {
+        if (!(query.date instanceof Date) || Number.isNaN(query.date.getTime()))
+            throw new Error(`festum: date must be a Date — e.g. new Date("2026-12-25") (UTC-canonical)`);
         results = feastsForDate(query.date);
     }
     else if (query.from != null || query.to != null) {
@@ -256,6 +314,24 @@ export function getFeast(query) {
             d = addDays(d, 1);
         }
     }
+    // `before` resolves the day AS OF a year: feasts instituted later step aside,
+    // and whatever ranked behind them — usually the temporale or the feria — wins
+    // instead. The calendar DATA is untouched; this is a view over it, so a caller
+    // asking for 1350 and a caller asking for 1962 read the same shipped table.
+    // A day whose every candidate is later than `before` returns empty, which is
+    // the honest answer: that day had no feast yet.
+    if (query.before != null) {
+        if (!Number.isFinite(query.before)) {
+            throw new Error(`festum: before must be a year — e.g. festum({ date, before: 1350 })`);
+        }
+        results = results
+            .filter((f) => feastKeptBy(f.id, query.before))
+            // Stamp the view on the survivors. The chant verbs read it back, so one
+            // `before` at the calendar door carries through the whole day — the
+            // calendar as of 1100 serves the repertoire attested by 1100, without
+            // the caller saying the year twice. A `before` of their own overrides.
+            .map((f) => ({ ...f, before: query.before }));
+    }
     if (query.nomen) {
         const n = query.nomen.toLowerCase();
         results = results.filter((f) => f.nomen.toLowerCase().includes(n));

package/dist/engines/cal/data/eras.d.ts

@@ -0,0 +1,35 @@
+export interface FeastEra {
+    /** Year of universal Roman observance — the year it starts winning days. */
+    year: number;
+    /** Earlier local/regional observance, where one is well attested. */
+    local?: number;
+    /** Why the date is what it is, and where it is shaky. */
+    note?: string;
+}
+/**
+ * Feast id → when it entered the universal calendar. Ids are the calendar's own
+ * (`MM-DD` for the sanctorale, season-relative for the temporale).
+ *
+ * INTERNAL, ruled 2026-08-04. This table does not join the public appendix and
+ * is not re-exported from the index, though it is the last table that could
+ * plausibly have. The appendix carries measurements and vocabularies; these are
+ * forty-three liturgical-historical CLAIMS, and the distinction between `year`
+ * (universal Roman observance) and `local` is a judgement about what a caller
+ * is modelling rather than a fact about the calendar — see the banner above.
+ * Publishing it would invite callers to cite dates tonus is not in a position
+ * to defend. The behaviour it drives, `festum({ before })`, is public and
+ * documented; the reckoning behind it stays here.
+ */
+export declare const FEAST_ERAS: Readonly<Record<string, FeastEra>>;
+/**
+ * Was this feast kept by `year`? A feast the table does not mention is treated
+ * as old enough — the table lists arrivals, not the whole calendar.
+ */
+export declare function feastKeptBy(feastId: string, year: number): boolean;
+/**
+ * The same question asked of a LOCAL observance: a feast kept somewhere by
+ * `year`, even if Rome had not yet taken it up. Use this when modelling a house
+ * rather than the universal calendar.
+ */
+export declare function feastKeptLocallyBy(feastId: string, year: number): boolean;
+//# sourceMappingURL=eras.d.ts.map

package/dist/engines/cal/data/eras.js

@@ -0,0 +1,128 @@
+// ---------------------------------------------------------------------------
+// engines/cal/data/eras — when a feast entered the calendar
+// ---------------------------------------------------------------------------
+// The shipped calendar is Tridentine, so it carries feasts instituted centuries
+// after the repertoire tonus models. This table dates the late arrivals so a
+// caller can ask for the day AS OF a chosen year — `festum({ date, before })` —
+// and let the temporale or the feria win where a later feast would have taken
+// the day.
+//
+// tonus-corpus keeps shipping every calendar day; nothing is cut from the data.
+// This is a VIEW over it. A feast absent from this table is treated as old
+// enough to keep, so the table only ever needs the late arrivals.
+//
+// ── EVERY DATE HERE WANTS A HISTORIAN'S RED PEN ─────────────────────────────
+// These are liturgical-historical claims, not measurements. `year` is the date
+// of UNIVERSAL observance in the Roman calendar (the point at which the feast
+// would displace a feria everywhere), because that is what a day-resolution
+// question actually turns on. Where a local observance long predates the
+// universal one, `local` records it — several feasts are genuinely medieval in
+// one diocese and early-modern in Rome, and which one you want is a judgement
+// about what you are modelling, not a fact.
+//
+// Deliberately NOT listed, though a name-pattern sweep flagged them:
+//   · 05-08 In Apparitione S. Michaëlis — the Monte Gargano apparition is 5th c.
+//     and the feast early medieval. Old; keep.
+//   · 02-01 S. Ignatii Episcopi et Martyris — Ignatius of ANTIOCH, d. c. 107.
+//     Not Ignatius Loyola. Keep.
+//   · 09-11 Ss. Proti et Hyacinthi — ancient Roman martyrs. Not Hyacinth of
+//     Poland (who is listed, at 08-17). Keep.
+// Those three are the traps in dating this list by name.
+//
+// ── KEPT DELIBERATELY, AGAINST THE STRICT READING ───────────────────────────
+//   · 08-06 In Transfiguratione Domini — Callixtus III made it universal in 1457,
+//     but it is an ancient Eastern feast with local Western observance long
+//     before. Old school; keep.
+//   · 07-02 In Visitatione BMV — 1389 is Urban VI's UNIVERSAL extension (prayed
+//     for the end of the Great Schism). St Bonaventure had already instituted it
+//     for the Franciscans in 1263 — genuinely inside a pre-1350 line, so the
+//     keep is supported by the record, not only by instinct.
+//   · 02-08 S. Joannis de Matha and 11-20 S. Felicis de Valois — the Trinitarian
+//     founders, both dead c. 1212–13. Their cult was confirmed late, but the
+//     saints and their veneration are medieval. Keep.
+// Each of these would come back under a stricter reading of "universal
+// observance"; they are out because the feast, not the paperwork, is what a
+// singing calendar is modelling.
+/**
+ * Feast id → when it entered the universal calendar. Ids are the calendar's own
+ * (`MM-DD` for the sanctorale, season-relative for the temporale).
+ *
+ * INTERNAL, ruled 2026-08-04. This table does not join the public appendix and
+ * is not re-exported from the index, though it is the last table that could
+ * plausibly have. The appendix carries measurements and vocabularies; these are
+ * forty-three liturgical-historical CLAIMS, and the distinction between `year`
+ * (universal Roman observance) and `local` is a judgement about what a caller
+ * is modelling rather than a fact about the calendar — see the banner above.
+ * Publishing it would invite callers to cite dates tonus is not in a position
+ * to defend. The behaviour it drives, `festum({ before })`, is public and
+ * documented; the reckoning behind it stays here.
+ */
+export const FEAST_ERAS = Object.freeze({
+    // ── Devotional feasts of the Lord and of Our Lady ──────────────────────────
+    "Nat2-0": { year: 1721, local: 1530, note: "Holy Name of Jesus; Franciscan/local 16th c." },
+    "Epi1-0": { year: 1921, local: 1893, note: "Holy Family; Leo XIII then Benedict XV" },
+    "02-11": { year: 1907, note: "Apparition of the Immaculate Virgin (Lourdes)" },
+    "Quad5-5": { year: 1727, local: 1423, note: "Seven Sorrows, Friday of Passion week; Cologne 1423" },
+    "Pent02-5": { year: 1856, local: 1765, note: "Sacred Heart; Clement XIII grant 1765, Pius IX universal" },
+    "07-01": { year: 1849, note: "Precious Blood (Pius IX)" },
+    "07-16": { year: 1726, local: 1376, note: "Our Lady of Mount Carmel; Carmelite from c. 1376" },
+    "08-22": { year: 1944, note: "Immaculate Heart (Pius XII)" },
+    "09-15": { year: 1727, local: 1423, note: "Seven Sorrows (September)" },
+    "09-24": { year: 1696, note: "Our Lady of Ransom / de Mercede" },
+    "10-02": { year: 1670, local: 1608, note: "Guardian Angels (Clement X)" },
+    "10-07": { year: 1716, local: 1573, note: "Rosary; Gregory XIII 1573 after Lepanto, Clement XI universal" },
+    "10-11": { year: 1931, note: "Divine Maternity (Pius XI, Ephesus centenary)" },
+    "11-21": { year: 1585, local: 1372, note: "Presentation of Our Lady; Avignon papal court 1372" },
+    "09-17": { year: 1585, note: "Stigmata of St Francis" },
+    // ── Saints venerated after ~1350 ───────────────────────────────────────────
+    // Dated by canonization or by entry into the universal calendar, whichever is
+    // the later — again, these want checking against the sources.
+    "03-04": { year: 1521, note: "Casimir of Poland, d. 1484" },
+    "08-17": { year: 1594, note: "Hyacinth of Poland, d. 1257 — cult approved late" },
+    "05-05": { year: 1712, note: "Pius V, d. 1572" },
+    "10-15": { year: 1622, note: "Teresa of Ávila, d. 1582" },
+    "11-24": { year: 1726, note: "John of the Cross, d. 1591" },
+    "07-31": { year: 1622, note: "Ignatius Loyola, d. 1556" },
+    "12-03": { year: 1622, note: "Francis Xavier, d. 1552" },
+    "05-26": { year: 1622, note: "Philip Neri, d. 1595 — id verified against the calendar" },
+    "01-29": { year: 1665, note: "Francis de Sales, d. 1622" },
+    "07-19": { year: 1737, note: "Vincent de Paul, d. 1660" },
+    "08-02": { year: 1839, note: "Alphonsus Liguori, d. 1787" },
+    "06-21": { year: 1726, note: "Aloysius Gonzaga, d. 1591" },
+    "05-13": { year: 1930, note: "Robert Bellarmine, d. 1621" },
+    "04-27": { year: 1925, note: "Peter Canisius, d. 1597" },
+    "08-07": { year: 1671, note: "Cajetan, d. 1547" },
+    "03-08": { year: 1690, note: "John of God, d. 1550" },
+    "07-18": { year: 1746, note: "Camillus de Lellis, d. 1614" },
+    "08-27": { year: 1767, note: "Joseph Calasanz, d. 1648" },
+    "08-19": { year: 1925, note: "John Eudes, d. 1680" },
+    "04-28": { year: 1867, note: "Paul of the Cross, d. 1775" },
+    "05-17": { year: 1690, note: "Paschal Baylon, d. 1592" },
+    "10-20": { year: 1767, note: "John Cantius, d. 1473" },
+    "11-14": { year: 1867, note: "Josaphat, d. 1623" },
+    "10-17": { year: 1920, note: "Margaret Mary Alacoque, d. 1690" },
+    "01-31": { year: 1934, note: "John Bosco, d. 1888" },
+    "02-27": { year: 1920, note: "Gabriel of Our Lady of Sorrows, d. 1862" },
+    "09-03": { year: 1954, note: "Pius X, d. 1914" },
+    "03-24": { year: 1921, note: "St Gabriel Archangel as a separate feast; the archangel is of course ancient" },
+});
+/**
+ * Was this feast kept by `year`? A feast the table does not mention is treated
+ * as old enough — the table lists arrivals, not the whole calendar.
+ */
+export function feastKeptBy(feastId, year) {
+    const era = FEAST_ERAS[feastId];
+    return !era || era.year <= year;
+}
+/**
+ * The same question asked of a LOCAL observance: a feast kept somewhere by
+ * `year`, even if Rome had not yet taken it up. Use this when modelling a house
+ * rather than the universal calendar.
+ */
+export function feastKeptLocallyBy(feastId, year) {
+    const era = FEAST_ERAS[feastId];
+    if (!era)
+        return true;
+    return Math.min(era.year, era.local ?? era.year) <= year;
+}
+//# sourceMappingURL=eras.js.map

package/dist/engines/cal/date.js

@@ -91,6 +91,50 @@ export function resolveEntryId(id, year, anchors) {
     if (/^\d{2}-\d{2}$/.test(id)) {
         return [place(startOfDay(parseMonthDay(year, id)))];
     }
+    // The Christmas-octave days are DATE-stemmed, not week-stemmed:
+    // Nat26–Nat31 = Dec 26–31 ("Diei VI infra Octavam Nativitatis"). Dec 30
+    // has no saint, so without Nat30 the date resolved to nothing at all.
+    const nat = id.match(/^Nat(2[6-9]|3[01])$/);
+    if (nat) {
+        return [place(startOfDay(new Date(Date.UTC(year, 11, Number(nat[1])))))];
+    }
+    const m = id.match(/^([A-Za-z]+)(\d+)-(\d+)$/);
+    if (!m)
+        throw new Error(`Unrecognized tempora stem: ${id}`);
+    const prefix = m[1];
+    const week = parseInt(m[2], 10);
+    const weekday = parseInt(m[3], 10);
+    // The season after Pentecost is ELASTIC (23–28 Sundays), and the book's
+    // rule is not linear: DO's Pent24 is "Dominica XXIV et ultima" — ALWAYS
+    // the last Sunday before Advent — and the surplus Sundays between the 23rd
+    // and the last resume the post-Epiphany Sundays omitted in January, in
+    // their order, ending at the sixth. Linear placement stranded the November
+    // tail with no tempora at all (the 11-18 / 11-27 / 11-28 holes of 2026).
+    const lastSunday = addDays(anchors.adventFirstSunday, -7);
+    const sundaysAfterPentecost = Math.round((lastSunday.getTime() - anchors.pentecost.getTime()) / (7 * 86400000));
+    if (prefix === "Pent") {
+        // Dominica ultima: anchored to Advent, not to Pentecost.
+        if (week === 24)
+            return [place(addDays(lastSunday, weekday))];
+        // In a 23-Sunday year the ultima falls ON the 23rd slot and sings the
+        // 24th's mass — the 23rd steps aside rather than double-booking the day.
+        if (week >= sundaysAfterPentecost)
+            return [];
+        return [place(addDays(anchors.pentecost, week * 7 + weekday))];
+    }
+    if (prefix === "Epi") {
+        // Always the January placement…
+        const placements = [place(resolveTemporaStem(id, anchors))];
+        // …and, in a long year, the autumn resumption: with S Sundays after
+        // Pentecost, the surplus g = S − 24 weeks between the 23rd and the
+        // ultima take Epi(7−g) … Epi6, in their order.
+        const surplus = sundaysAfterPentecost - 24;
+        if (surplus > 0 && week >= 7 - surplus && week <= 6) {
+            const sundayIndex = 24 + (week - (7 - surplus));
+            placements.push(place(addDays(anchors.pentecost, sundayIndex * 7 + weekday)));
+        }
+        return placements;
+    }
     return [place(resolveTemporaStem(id, anchors))];
 }
 function resolveTemporaStem(stem, anchors) {

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

@@ -1,10 +1,10 @@
 export type Season = "adv" | "nat" | "epi" | "quadp" | "quad" | "pasc" | "pent";
-export declare const SEASON_LABELS: Readonly<Record<Season, string>>;
-export declare const TEMPUS_NAMES: Readonly<Record<Season, string>>;
+export declare const SEASON_LABEL: Readonly<Record<Season, string>>;
+export declare const TEMPORA: Readonly<Record<Season, string>>;
 export declare const PENITENTIAL_SEASONS: ReadonlySet<Season>;
 export type Grade = "triduum" | "duplex-i" | "duplex-majus-i" | "semiduplex-i" | "feria-privilegiata" | "duplex-ii" | "semiduplex-ii" | "duplex-majus" | "duplex" | "semiduplex" | "simplex" | "feria-major" | "vigilia" | "feria";
 export declare const GRADE_ORDER: readonly Grade[];
-export declare const GRADE_NAMES: Readonly<Record<Grade, string>>;
+export declare const GRADUS: Readonly<Record<Grade, string>>;
 export declare const RITUS_TO_GRADE: Readonly<Record<string, Grade>>;
 /** Reduce a Tridentine ritus string to its canonical Grade. */
 export declare function ritusToGrade(ritus: string): Grade;
@@ -34,6 +34,11 @@ export interface Feast {
     masses: number[];
     marian: boolean;
     apostolic: boolean;
+    /** The era view this feast was resolved under — the `before` year given to
+     *  festum. Carried on the feast so the chant verbs (proprium, ordinarium,
+     *  officium) serve the SAME view without being told twice; a `before` on
+     *  their own query overrides. Absent on a present-day resolution. */
+    before?: number;
 }
 export interface FeastQuery {
     date?: Date;
@@ -44,6 +49,13 @@ export interface FeastQuery {
     grade?: Grade;
     marian?: boolean;
     apostolic?: boolean;
+    /**
+     * Resolve the day AS OF this year: feasts instituted later step aside and
+     * whatever ranked behind them wins — usually the temporale or the feria. A
+     * view over the shipped calendar, which keeps every day either way. Dates
+     * live in cal/data/eras.ts.
+     */
+    before?: number;
 }
 export interface Pascha {
     year: number;

package/dist/engines/cal/types.js

@@ -1,7 +1,7 @@
 // ---------------------------------------------------------------------------
 // engines/cal/types — calendar types and constants
 // ---------------------------------------------------------------------------
-export const SEASON_LABELS = Object.freeze({
+export const SEASON_LABEL = Object.freeze({
     adv: "Advent",
     nat: "Christmastide",
     epi: "Time after Epiphany",
@@ -11,8 +11,8 @@ export const SEASON_LABELS = Object.freeze({
     pent: "Time after Pentecost",
 });
 // Authentic Latin season names (the books' own headings). Feast.tempus
-// carries these; SEASON_LABELS above is the English reference map.
-export const TEMPUS_NAMES = Object.freeze({
+// carries these; SEASON_LABEL above is the English reference map.
+export const TEMPORA = Object.freeze({
     adv: "Tempus Adventus",
     nat: "Tempus Nativitatis",
     epi: "Tempus post Epiphaniam",
@@ -46,12 +46,12 @@ export const GRADE_ORDER = [
     "vigilia",
     "feria",
 ];
-// Canonical Latin name per grade (display reference map, like SEASON_LABELS).
+// Canonical Latin name per grade (display reference map, like SEASON_LABEL).
 // Feast objects don't carry this — `ritus` is the on-object Latin carrier;
 // use this map when the canonical grade name is wanted instead (it differs
 // from ritus only for octave compounds, the Triduum, and the privileged-
 // Sunday overrides).
-export const GRADE_NAMES = Object.freeze({
+export const GRADUS = Object.freeze({
     triduum: "Triduum Sacrum",
     "duplex-i": "Duplex I classis",
     "duplex-majus-i": "Duplex majus I classis",

package/dist/engines/census/census.d.ts

@@ -0,0 +1,7 @@
+import type { Census, CensusQuery } from "./types.js";
+/**
+ * The census of one chant: its profile against the corpus, where it is
+ * unusual, and what it is near.
+ */
+export declare function getCensus(query: CensusQuery): Census;
+//# sourceMappingURL=census.d.ts.map