tonus 0.1.8 → 0.5.0

package/docs/api/calendar.md

@@ -0,0 +1,279 @@
+# Calendar
+
+`tonus.festum` resolves a date to its place in the liturgical year. It
+returns the feasts that fall on the day, ordered by precedence, each
+carrying its rank in the rubrics' own vocabulary, its season, and the
+kyriale masses appropriate to it. The calendar is the Tridentine
+Roman rite (1570–1962), extracted from
+[Divinum Officium](https://github.com/DivinumOfficium/divinum-officium):
+650 entries across the sanctorale (fixed feasts) and the temporale
+(movable feasts), resolved against Easter computed by the Gregorian computus
+from 1583 and the Julian computus before it.
+
+- [Calendar](#calendar)
+  - [The day's feasts — `festum`](#the-days-feasts--festum)
+    - [The day as of a year — `before`](#the-day-as-of-a-year--before)
+  - [Rank — `ritus` and `grade`](#rank--ritus-and-grade)
+  - [Seasons — the temporale](#seasons--the-temporale)
+  - [The year's anchors — `pascha`](#the-years-anchors--pascha)
+  - [Theory \& Context](#theory--context)
+    - [The calendar's era](#the-calendars-era)
+
+## The day's feasts — `festum`
+
+`festum(query?)` returns `Feast[]`. A date query returns every entry that
+falls on the day: the primary feast first, concurrent feasts after it, in
+order of dignity. A range query (`from`/`to`) walks each day and flattens
+the results. A query with filters but no date scans the default liturgical
+year, Advent to Advent. With no argument at all, the day resolves to
+tonus's default epoch, **1 June 991**, the symbolic birthday of Guido
+d'Arezzo (see [the conventions note](index.md#conventions)).
+Empty matches return `[]`; an invalid range throws.
+
+```js
+tonus.festum({ date: new Date("2026-12-25") });
+```
+
+```js
+[
+  {
+    id: "12-25",
+    nomen: "In Nativitate Domini",
+    ritus: "Duplex I classis",
+    grade: "duplex-i",
+    season: "nat",
+    tempus: "Tempus Nativitatis",
+    seasonStart: "2026-12-25",
+    seasonEnd: "2027-01-10",
+    date: "2026-12-25",
+    weekday: 5,
+    masses: [2, 3],
+    marian: false,
+    apostolic: false,
+  },
+  {
+    id: "Adv4-5",
+    nomen: "Feria VI infra Hebdomadam IV Adventus",
+    ritus: "Feria major",
+    grade: "feria-major",
+    season: "nat",
+    tempus: "Tempus Nativitatis",
+    seasonStart: "2026-12-25",
+    seasonEnd: "2027-01-10",
+    date: "2026-12-25",
+    weekday: 5,
+    masses: [16],
+    marian: false,
+    apostolic: false,
+  },
+];
+```
+
+The privileged feast leads; the concurrent Advent feria follows, carrying only
+the ferial rubric's mass (`masses: [16]`).
+
+Precedence decides what comes first when feasts collide. On November 30,
+2025, St. Andrew falls on the first Sunday of Advent; the privileged
+Sunday wins the day and the Apostle follows it:
+
+```js
+tonus.festum({ date: new Date("2025-11-30") });
+// Dominica I Adventus  [semiduplex-i]
+// S. Andreæ Apostoli   [duplex-ii]
+```
+
+The other query forms:
+
+```js
+tonus.festum({ from: advent1, to: epiphany }); // range, day by day
+tonus.festum({ nomen: "Dominica I Adventus" }); // partial match, case-insensitive
+tonus.festum({ season: "pasc" }); // liturgical-year scan, filtered
+tonus.festum({ grade: "duplex-i", marian: true });
+```
+
+### The day as of a year — `before`
+
+`before` resolves the day as it stood in a given year: the calendar holds
+only the feasts instituted by then, and precedence runs over those. On most
+days that returns the temporale or the feria in place of a modern feast.
+Institution dates are in `cal/data/eras.ts`. A day with no feast yet
+instituted returns `[]`.
+
+```js
+tonus.festum({ date: new Date("2026-07-01"), before: 1100 });
+// the feria — the Precious Blood was not instituted until 1849
+```
+
+The feast returned **carries the view** (`feast.before`), and every chant
+verb reads it back: `proprium`, `ordinarium`, and `officium`
+serve only chants attested by the same year, without being told the year
+twice. One `before` at the calendar door views the whole day. The chant side
+— what "attested" means, and what a slot the view excludes does — is in
+[chant.md](chant.md#the-repertoire-as-of-a-date--the-era-view).
+
+```ts
+interface FeastQuery {
+  date?: Date;
+  from?: Date;
+  to?: Date;
+  nomen?: string; // partial match, case-insensitive
+  season?: Season;
+  grade?: Grade;
+  marian?: boolean;
+  apostolic?: boolean;
+  before?: number; // the era view: the day as of this year
+}
+
+interface Feast {
+  id: string; // "MM-DD" (sancti) or DO stem, e.g. "Adv1-0" (tempora)
+  nomen: string; // Latin feast name, "In Nativitate Domini"
+  ritus: string; // the Tridentine rank verbatim, incl. octave detail
+  grade: Grade; // canonical grade code; precedence via GRADE_ORDER
+  season: Season; // machine code (DO Tempora stem)
+  tempus: string; // Latin season name, "Tempus Adventus"
+  seasonStart: Date;
+  seasonEnd: Date;
+  date: Date;
+  weekday: number; // 0 = Sunday (UTC)
+  masses: number[]; // the masses the day's Kyriale rubric appoints
+  marian: boolean;
+  apostolic: boolean;
+  before?: number; // the era view this feast was resolved under, if any
+}
+```
+
+The `masses` list is derived from the Kyriale's own printed rubric — one
+category per mass, by RANK: "In Paschal Time", "For feasts of the I class",
+"For Sundays throughout the Year", "For ferias". A day resolves to exactly
+one rubric (a BVM feast is "of the Blessed Virgin" even in Paschaltide),
+and the masses carrying that rubric are the masses it may sing, in the
+book's own numbering — where a rubric names several (II class 1–5), that
+numbering is the book's invitation to choose, and `ordinarium` rotates
+among them by year. The book's per-mass nicknames (_Orbis factor_ for
+Sundays, and so on) record customary use, which disagrees with the rubric for 9
+of the 18; `ordinarium` selects on the rubric.
+
+## Rank — `ritus` and `grade`
+
+`ritus` is the rank string verbatim
+from the Divinum Officium `[Rank]` line (`"Duplex majus"`, `"Semiduplex
+II classis"`, `"Duplex I classis cum Octava privilegiata I ordinis"`).
+It preserves the
+octave detail, if present. `grade` is the canonical code the ritus reduces to for
+sorting, filtering, and mass selection.
+
+The order is classis-primary. A first-class day outranks any
+non-first-class feast regardless of the duplex/semiduplex axis, so a plain
+Duplex feast never displaces a Lent Sunday:
+
+| #   | `grade`              | reduces from `ritus`                 | who it is                                                   |
+| --- | -------------------- | ------------------------------------ | ----------------------------------------------------------- |
+| 1   | `triduum`            | Feria privilegiata Duplex I classis  | Maundy Thu, Good Fri, Holy Sat                              |
+| 2   | `duplex-i`           | Duplex I classis (+ octave variants) | Christmas, Easter, Pentecost                                |
+| 3   | `duplex-majus-i`     | Duplex majus I classis               | Low Sunday                                                  |
+| 4   | `semiduplex-i`       | Semiduplex I classis                 | Lent Sundays, Palm Sunday, Easter/Pentecost octave weekdays |
+| 5   | `feria-privilegiata` | Feria privilegiata                   | Ash Wednesday, Holy Week Mon–Wed                            |
+| 6   | `duplex-ii`          | Duplex II classis (+ octave)         | second-class feasts                                         |
+| 7   | `semiduplex-ii`      | Semiduplex II classis                | later Advent Sundays, octave days                           |
+| 8   | `duplex-majus`       | Duplex majus                         |                                                             |
+| 9   | `duplex`             | Duplex                               |                                                             |
+| 10  | `semiduplex`         | Semiduplex                           | Sundays throughout the year, semiduplex feasts              |
+| 11  | `simplex`            | Simplex                              |                                                             |
+| 12  | `feria-major`        | Feria major                          | Advent/Lent ferias, Ember days                              |
+| 13  | `vigilia`            | Vigilia                              |                                                             |
+| 14  | `feria`              | Feria                                | weekdays with no feast                                      |
+
+Four Sundays are graded above their Divinum Officium rank, which marks Advent I
+and the three Septuagesima-block Sundays plain `"Semiduplex"`. Advent I resolves
+to `semiduplex-i`; Septuagesima, Sexagesima, and Quinquagesima to
+`semiduplex-ii`, matching the classes DO gives the Lent and late-Advent Sundays.
+`ritus` stays verbatim.
+
+## Seasons — the temporale
+
+Each feast carries the pair `season` (code) and `tempus` (the Latin
+season name). The codes are one-to-one with the Divinum Officium Tempora
+stems, so a date's season and the stem of any Tempora feast on it agree by
+construction.
+
+| `season` | `tempus`                | English              | Span                                                |
+| -------- | ----------------------- | -------------------- | --------------------------------------------------- |
+| `adv`    | Tempus Adventus         | Advent               | Advent I Sunday → Christmas                         |
+| `nat`    | Tempus Nativitatis      | Christmastide        | Christmas → 1st Sunday after Epiphany               |
+| `epi`    | Tempus post Epiphaniam  | Time after Epiphany  | there → Septuagesima                                |
+| `quadp`  | Tempus Septuagesimæ     | Septuagesima         | Septuagesima Sunday → Ash Wednesday                 |
+| `quad`   | Tempus Quadragesimæ     | Lent                 | Ash Wednesday → Easter                              |
+| `pasc`   | Tempus Paschale         | Paschaltide          | Easter → Trinity Sunday (Pentecost octave included) |
+| `pent`   | Tempus post Pentecosten | Time after Pentecost | Trinity Sunday → next Advent                        |
+
+A feast's `id` carries a nominal week number, but `season` is always
+derived from the date; overflow entries, such as the Epiphany weeks
+resumed before Septuagesima, take the season of the day they fall on.
+
+Season drives real liturgy in the ordinary: in the penitential seasons
+(`adv`, `quadp`, `quad`) the Gloria is omitted, and the Ite with it — the
+Benedicamus dismissal appears only where the selected mass carries a
+setting ([chant.md](chant.md#the-ordinary--ordinarium)).
+
+## The year's anchors — `pascha`
+
+`pascha(year)` returns the movable anchors of one liturgical year as
+UTC-midnight dates. Easter is computed by the Gregorian (Gauss/Butcher)
+computus from 1583, and by the Julian computus with Julian→Gregorian
+day-number conversion before that, so years reaching into the medieval
+period stay correct. Everything else anchors to Easter, except Advent,
+which anchors to the first Sunday on or after November 27, and the fixed
+Christmas-cycle dates. A non-finite year throws.
+
+```js
+tonus.pascha(2026);
+```
+
+```js
+{ year: 2026,
+  septuagesima:      2026-02-01,  ashWednesday:  2026-02-18,
+  firstLentSunday:   2026-02-22,  palmSunday:    2026-03-29,
+  goodFriday:        2026-04-03,  easter:        2026-04-05,
+  ascension:         2026-05-14,  pentecost:     2026-05-24,
+  trinitySunday:     2026-05-31,  corpusChristi: 2026-06-04,
+  adventFirstSunday: 2026-11-29,  gaudete:       2026-12-13,
+  christmas:         2026-12-25,  epiphany:      2026-01-06,
+  baptism:           2026-01-11 }
+```
+
+```ts
+interface Pascha {
+  year: number;
+  septuagesima: Date;
+  ashWednesday: Date;
+  firstLentSunday: Date;
+  palmSunday: Date;
+  goodFriday: Date;
+  easter: Date;
+  ascension: Date;
+  pentecost: Date;
+  trinitySunday: Date;
+  corpusChristi: Date;
+  adventFirstSunday: Date;
+  gaudete: Date;
+  christmas: Date;
+  epiphany: Date;
+  baptism: Date;
+}
+```
+
+## Theory & Context
+
+### The calendar's era
+
+The calendar's structure is medieval: the temporale from Advent through the
+season after Pentecost (Septuagesima included), the eight-hour office cursus,
+and the duplex/semiduplex/simplex dignity system. The data is the Tridentine
+codification (1570–1962) via Divinum Officium, continuous with late-medieval
+usage and carrying feasts as recent as the 1950s. tonus describes this calendar
+as Tridentine Roman, continuous with medieval practice.
+
+## Sources
+
+Sources for this page are in the central [bibliography](https://github.com/jeffreypierce/tonus/blob/main/BIBLIOGRAPHY.md):
+`divinum-officium`, `computus`, `liber-usualis`.

package/docs/api/census.md

@@ -0,0 +1,288 @@
+# Census
+
+`census` measures one chant against the corpus that holds it: how typical it
+is, where it is unusual, and what it is near.
+
+- [Census](#census)
+  - [The method](#the-method)
+  - [What a block holds](#what-a-block-holds)
+  - [How the measurement works](#how-the-measurement-works)
+  - [Distance is cosine per field group](#distance-is-cosine-per-field-group)
+  - [Profile and typicality](#profile-and-typicality)
+  - [Balance — distance and deviance](#balance--distance-and-deviance)
+  - [Neighbors, and `by`](#neighbors-and-by)
+  - [The era view](#the-era-view)
+  - [What the census is not](#what-the-census-is-not)
+
+## The method
+
+```js
+tonus.census({ id: "gregobase:1210" });
+```
+
+Everything comes back in one call — profile, balance, neighbors:
+
+```js
+{
+  id: "gregobase:1210",
+  by: "all",
+  profile: {
+    modal:         { values: [...12], typicality: 0.99 },
+    degreeHist:    { values: [...15], typicality: … },
+    melodic:       { values: [...121], typicality: 0.70 },
+    trigram:       { values: [...16], typicality: … },
+    cadenceFinal:  { values: [...16], typicality: … },
+    cadenceMedial: { values: [...16], typicality: … },
+    chironomy:     { values: [...6],  typicality: … },
+    textual:       { values: [...7],  typicality: … },
+  },
+  balance: {
+    distance: 0.091,
+    deviantGroups: ["degreeHist", "melodic"],
+  },
+  neighbors: [
+    { id: "gregobase:34", similarity: 0.999 },
+    …
+  ],
+}
+```
+
+```ts
+interface CensusQuery {
+  id: string; // the chant to census
+  k?: number; // how many neighbors, default 8; 0 returns none
+  by?: CensusBy; // which field group similarity is measured on, default "all"
+  before?: number; // restrict neighbors to chants attested by this year
+}
+```
+
+The census covers the **2,187 chants tonus ships** — the same population
+`cantus({ id })` addresses, one block per chant. An id with no block throws
+rather than returning an empty answer, because a silent nothing reads as "this
+chant is unlike everything," which is a different claim.
+
+## What a block holds
+
+The corpus pipeline censuses every shipped chant into 221 float32s, grouped by
+what they describe:
+
+| group           | floats | what it measures                                                                  |
+| --------------- | -----: | --------------------------------------------------------------------------------- |
+| `modal`         |     12 | affinity to each of the eight modes, the final's and tenor's pitch-class, ambitus |
+| `degreeHist`    |     15 | how long the melody dwells on each scale degree, final-relative                   |
+| `melodic`       |    121 | the interval bigram table — which step follows which                              |
+| `trigram`       |     16 | three-note motifs, against the corpus's commonest                                 |
+| `cadenceFinal`  |     16 | how the chant closes, keyed by cadence signature                                  |
+| `cadenceMedial` |     16 | how its interior phrases land                                                     |
+| `chironomy`     |      6 | the melodic arc in quarters, phrase length, melisma density                       |
+| `textual`       |      7 | vowel distribution by sung duration, accent rate, melisma mean                    |
+
+Four more fields ride in the block and are **not** similarity dimensions:
+`flags` (a bitfield), `attest` (dating — that is what `before` reads),
+`extras`, and `reserve`. `by` will not accept them.
+
+## How the measurement works
+
+Every number in a block reads off a single `notatio()` parse — the same parse
+`score` gives you — so the census can never disagree with the library about
+what a chant is.
+
+Each float is a named measurement, not a learned one: time spent on the
+subfinal, how often a rising second follows a falling third. When the census
+calls two chants near, the profile says in what respect.
+
+Most groups are normalized to sum to one, so a group holds a distribution —
+where the melody's time goes, not how much of it there is; length is not a
+similarity. The trigram and cadence groups count against dictionaries mined
+from the corpus itself — its commonest motifs, its commonest closing gestures,
+one bucket for the rest — so the corpus supplies the vocabulary and the chant
+supplies the usage.
+
+The reference is the mean block over all 2,187 chants, group by group. Because
+blocks are sums of durations and counts, they add: a season's blocks, summed and
+divided by their count, are the season's mean profile in the same 221 slots.
+
+## Distance is cosine per field group
+
+**This is a contract, not an implementation note.** The census answers about
+one chant at a time; grouping — "all Communions," "this season," "this
+manuscript" — is yours to do. The moment you pool blocks yourself you are
+computing a distance, and if you compute it differently from the rule below
+your numbers will not agree with `census()`'s. Nothing will error.
+
+The rule, in three lines:
+
+1. Cosine **per field group**, never over the flat 221.
+2. `by: "all"` is the **equal-weight mean** of the per-group cosines — every
+   dimension one vote, no tunable weights.
+3. Ties break to the lower id, so the same question always has the same answer.
+
+Cosine on the whole vector is dominated by the 121-float `melodic` block and by
+sheer magnitude, so a long Tract would neighbor other long chants for being
+long. Per-group cosine asks about **shape within each dimension**.
+
+[`CENSUS_GROUPS`](index.md#the-appendix) gives you the group names and their
+field counts, and [`CENSUS_ORDER`](index.md#the-appendix) every censused id —
+so you can pool a set without guessing at either.
+
+### Reading the numbers
+
+**Similarity is not comparable across `by` values.** A 0.94 on `cadenceFinal`
+and a 0.94 on `melodic` are not the same amount of alike: the groups have
+different widths and different natural spreads. Rank within one `by`; never
+threshold across two.
+
+**A centroid must be pooled per group, then compared per group.** Averaging the
+flat 221 and taking one cosine is the exact mistake rule 1 exists to prevent.
+Pooling the 178 Communions both ways gives different winners, and the flat
+version collapses the top of the field into a tie around 0.99 where the
+per-group version spreads from about 0.85 down to 0.65. That compression comes
+from one wide block outvoting the other eight.
+
+**`before` filters before ranking.** It restricts the candidate pool, then
+ranks — so `k` stays satisfiable, and a filtered list is *not* a subset of the
+unfiltered one. Chants that were ranked out by later material rise into it.
+Typicality is unaffected: it is always measured against the whole shipped
+corpus (see [Profile and typicality](#profile-and-typicality)).
+
+### Worked example — pooling a genus
+
+Reproducing the rule in full. This gives the same numbers `census()` gives,
+which is the point of printing it:
+
+```js
+import tonus, { CENSUS_GROUPS, CENSUS_ORDER } from "tonus";
+
+const GROUPS = Object.keys(CENSUS_GROUPS);
+
+const cosine = (a, b) => {
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i]; na += a[i] ** 2; nb += b[i] ** 2;
+  }
+  return na && nb ? dot / Math.sqrt(na * nb) : 0;
+};
+
+// Pool a set of chants into a centroid — per group, never the flat 221.
+function centroid(ids) {
+  const sums = Object.fromEntries(
+    GROUPS.map((g) => [g, new Array(CENSUS_GROUPS[g].count).fill(0)]),
+  );
+  for (const id of ids) {
+    const { profile } = tonus.census({ id, k: 0 });   // k: 0 — profile only
+    for (const g of GROUPS) profile[g].values.forEach((v, i) => { sums[g][i] += v; });
+  }
+  for (const g of GROUPS) sums[g] = sums[g].map((v) => v / ids.length);
+  return sums;
+}
+
+// Compare against it the same way: cosine per group, then the mean for `all`.
+function similarity(id, c) {
+  const { profile } = tonus.census({ id, k: 0 });
+  const per = Object.fromEntries(GROUPS.map((g) => [g, cosine(profile[g].values, c[g])]));
+  per.all = GROUPS.reduce((s, g) => s + per[g], 0) / GROUPS.length;
+  return per;
+}
+
+// Every censused Communion, pooled — then: which Communion is most a Communion?
+const ids = CENSUS_ORDER.filter((id) => tonus.cantus({ id })[0]?.office === "co");
+const c = centroid(ids);                              // 178 chants
+const ranked = ids
+  .map((id) => ({ id, s: similarity(id, c) }))
+  .sort((a, b) => b.s.all - a.s.all);
+
+// 0.953  Quinque prudentes
+// 0.951  Domus mea
+// 0.944  Joseph fili David
+//   …
+// 0.746  Exiit sermo
+// 0.735  Tollite hostias
+```
+
+The per-group breakdown is where the answer becomes legible. _Quinque
+prudentes_ leads on `textual`, `cadenceMedial` and `trigram`, at about 0.99 on
+each — it sets its text and turns its phrases the way Communions do — while its
+`cadenceFinal` is only about 0.82, so the one thing it does unlike a typical
+Communion is end. A chant is typical of its genus in some dimensions and not
+others.
+
+## Profile and typicality
+
+Each group's `typicality` is its cosine against the corpus mean for that group:
+1.0 is "uses this dimension exactly as the corpus does on average," lower means
+"unlike the rest."
+
+The two numbers above are a fair illustration. _Ab occultis meis_ is a mode-2
+Gradual whose `modal` typicality is about 0.99 — modally it is a typical
+mode-2 chant — while its `melodic` typicality is about 0.70, because its
+interval
+vocabulary is its own. One chant can be conventional in one dimension and
+distinctive in another, which is the reason the groups are kept apart.
+
+Typicality is always measured against the **whole shipped corpus**, never the
+filtered pool: `before` restricts who may be a neighbor, it does not move
+the mean.
+
+## Balance — distance and deviance
+
+```js
+balance: { distance: 0.091, deviantGroups: ["degreeHist", "melodic"] }
+```
+
+`distance` is 1 minus the mean typicality across all groups: 0 is a chant at
+the corpus mean, 1 has nothing in common with it.
+
+`deviantGroups` names where a chant is unusual **relative to its own mean**,
+most deviant first — not against an absolute threshold. The question it answers
+is "given how typical this chant is overall, where does it depart from
+itself?", which is what makes the answer legible for a chant that is unusual
+everywhere or nowhere.
+
+## Neighbors, and `by`
+
+```js
+tonus.census({ id: "gregobase:1210", k: 3 });
+// Ab occultis meis (Graduale, mode 2) →
+//   Justus ut palma   Graduale, mode 2
+//   Requiem           Graduale, mode 2
+//   Domine refugium   Graduale, mode 2
+```
+
+Nothing tells the census what genre or mode a chant is. It recovers them from
+melodic shape alone.
+
+`by` changes what _near_ means:
+
+```js
+tonus.census({ id: "gregobase:1210", k: 3, by: "cadenceFinal" });
+// chants that CLOSE the same way — crossing genre and mode freely
+```
+
+Asked on `all`, a mode-2 Gradual finds mode-2 Graduals. Asked on
+`cadenceFinal`, it finds an Alleluia, an Introit and a Communion in modes 1
+and 4 that happen to end with the same gesture. Both answers are correct; they
+are answers to different questions.
+
+`k` bounds the result (default 8, `0` returns none, larger than the corpus
+returns all 2,186 others).
+
+## The era view
+
+```js
+tonus.census({ id: "gregobase:1210", before: 1100 });
+```
+
+Restricts neighbors to chants a manuscript of the 11th century or earlier
+already holds — 1,790 of the 2,186 candidates. This is the same rule as
+[`cantus({ before })`](chant.md#the-repertoire-as-of-a-date--the-era-view),
+through the same admissibility door: **evidence, not existence**, so a chant
+with no dated witness is excluded rather than assumed old.
+
+The seed chant itself is never filtered — you asked about it by name.
+
+## What the census is not
+
+It is not a similarity search over Gregorian chant at large. The blocks
+describe the chants tonus ships, which is the assignment-driven corpus: what
+some day of the calendar calls for. A melody's neighbors are its neighbors
+_within that repertoire_.