tonus 0.1.6 → 0.5.0

package/docs/api/heavens.md

@@ -0,0 +1,346 @@
+# Heavens
+
+`tonus.caelum` computes the classical bodies' places for a single moment, from
+JPL Keplerian elements valid 3000 BC – 3000 AD. `tonus.harmonia` voices those
+bodies through a planetary-harmony doctrine, assigning each visible planet a
+tuned pitch and a Greek vowel. The doctrines and their derived ratios are
+summarized in [Theory & Context](#theory--context).
+
+- [Heavens](#heavens)
+  - [The heavens — `caelum`](#the-heavens--caelum)
+  - [Aspects](#aspects)
+  - [The voiced heavens — `harmonia`](#the-voiced-heavens--harmonia)
+  - [The planetary vowels](#the-planetary-vowels)
+  - [The tabula](#the-tabula)
+  - [Theory \& Context](#theory--context)
+
+## The heavens — `caelum`
+
+`caelum(query?)` returns a `Cosmos` for a single moment and `Cosmos[]` for
+a `from`/`to` range. With `bodies` omitted, all eight are returned, and
+aspects are computed only between requested bodies. A `feast` supplies its
+date; an explicit `date` takes precedence.
+
+```js
+tonus.caelum({ date: new Date("2026-12-25") });
+```
+
+```js
+// bodies[6], Jupiter that morning — retrograde in Leo:
+{ name: "Jupiter", nomen: "Iuppiter", symbol: "♃",
+  helio: { lon: 137.9, lat: 0.79, dist: 5.33 },
+  geo:   { lon: 146.6, … },
+  speed: -0.037, retrograde: true,
+  magnitude: -2.13, elongation: 125.1, phase: 0.99,
+  zodiac: 4, sign: "Leo" }
+```
+
+```js
+tonus.caelum(); // the default epoch (991)
+tonus.caelum({ feast: feasts[0] }); // the feast's date
+tonus.caelum({ bodies: ["Sun", "Moon", "Jupiter"] });
+tonus.caelum({ from: jan1, to: dec31, step: 7 }); // weekly snapshots
+```
+
+The eight bodies:
+
+| `name`  | `nomen`   |     | `name`  | `nomen`  |     |
+| ------- | --------- | --- | ------- | -------- | --- |
+| Sun     | Sol       | ☉   | Earth   | Terra    | ♁   |
+| Moon    | Luna      | ☾   | Mars    | Mars     | ♂   |
+| Mercury | Mercurius | ☿   | Jupiter | Iuppiter | ♃   |
+| Venus   | Venus     | ♀   | Saturn  | Saturnus | ♄   |
+
+```ts
+interface CosmosQuery {
+  date?: Date;
+  feast?: Feast;
+  from?: Date;
+  to?: Date;
+  step?: number; // days, default 1
+  bodies?: BodyName[];
+  orbLimit?: number; // max orb for aspect detection, degrees (default 8)
+}
+
+interface Cosmos {
+  date: Date;
+  bodies: Body[];
+  aspects: Aspect[];
+}
+
+interface Body {
+  name: BodyName; // from the table above
+  nomen: string; // Latin name
+  symbol: string; // Unicode symbol
+  helio: HelioPos;
+  geo: GeoPos;
+  speed: number; // deg/day (negative = retrograde)
+  retrograde: boolean;
+  magnitude: number;
+  elongation: number; // deg from Sun (geocentric)
+  phase: number; // 0–1 illuminated fraction
+  apparentDiameter: number | { equ: number; pol: number }; // arcsec
+  zodiac: number; // sign 0–11 (Aries=0 … Pisces=11)
+  sign: string; // the code: "Aries", "Taurus", …
+  signum: string; // the Latin: "Scorpius", "Capricornus", …
+  distEarthRadii?: number; // Moon only
+}
+
+interface HelioPos {
+  lon: number; // ecliptic longitude, deg (0–360)
+  lat: number; // ecliptic latitude, deg
+  dist: number; // distance from Sun, AU
+}
+
+interface GeoPos {
+  lon: number;
+  lat: number;
+  dist: number;
+  equatorial: {
+    ra: number; // right ascension, deg
+    dec: number; // declination, deg
+    dist: number;
+  };
+}
+```
+
+## Aspects
+
+Aspects are angular relationships between geocentric body
+longitudes, detected within the orb limit. Strength falls linearly from 1
+at the exact angle to 0 at the limit. On Christmas 2026 the sky holds
+eight, led by a Mercury–Jupiter trine 1.1° from exact.
+
+| `type`        | angle |
+| ------------- | ----- |
+| `conjunction` | 0°    |
+| `sextile`     | 60°   |
+| `square`      | 90°   |
+| `trine`       | 120°  |
+| `opposition`  | 180°  |
+
+```ts
+interface Aspect {
+  type: string; // from the table above
+  bodies: [string, string];
+  angle: number; // exact separation, deg
+  orb: number; // degrees from exact aspect angle
+  strength: number; // 0–1
+}
+```
+
+## The voiced heavens — `harmonia`
+
+`harmonia(cosmos, opts?)` gives each body a pitch and a Greek vowel according to
+a **doctrina** (a named historical scheme for who sounds what: Pythagoras,
+Boethius, Pliny, Ptolemy). The result
+is pure data: each visible planet becomes a `VoicedBody` with a tuned pitch and
+a Greek vowel; each aspect gains the `Interval` its angle sounds, with its
+consonance grade. Range input populates `frames`, one per cosmos.
+
+```js
+const sky = tonus.caelum({ date: new Date("2026-12-25") });
+const h = tonus.harmonia(sky); // Boethius, pythagorean A440
+
+h.auctor; // "Anicius Manlius Severinus Boethius"
+
+h.bodies.find((b) => b.name === "Jupiter");
+// { …Body, nota: { pitch: { spn: "F4", hz: 347.65, … },
+//                  performance: { velocity: 0.55, … } },
+//   presence: 0.55, motion: 0.15,
+//   greekName: "parhypate meson", vowel: { name: "Upsilon", phonetic: "u", … } }
+
+h.aspects[0];
+// trine Mercury–Jupiter → interval: Quinta, consonance: "perfect"
+```
+
+The doctrinae:
+
+| `doctrina`     | Source                     | Span      | Notable                                                       |
+| -------------- | -------------------------- | --------- | ------------------------------------------------------------- |
+| `"pythagoras"` | via Plato, _Republic_ X    | 1 octave  | Disjunct diatonic tetrachords (B durum); includes Fixed Stars |
+| `"boethius"`   | _De institutione musica_   | major 7th | Conjunct diatonic tetrachords (B molle); medieval default     |
+| `"pliny"`      | _Naturalis historia_ II.xx | 1 octave  | Chromatic Dorian (distance-based); Earth = proslambanomenos   |
+| `"ptolemy"`    | _Harmonics_ III            | 2 octaves | Fixed tones of the Greater Perfect System                     |
+
+Sphere pitches are computed directly from the doctrina's pure ratios,
+anchored at the temperamentum's A4, so historical coherence holds:
+`temperamentum("ptolemy-intense")` with `harmonia({ doctrina: "ptolemy" })`
+gives pure Ptolemaic intervals throughout — Sun→Jupiter a pure 3/2,
+Sun→Saturn a pure 2/1. The temperamentum's scale governs pitch naming and
+the imprint.
+
+Each voiced body's `nota` carries its velocity as a 0–1 factor: the body's
+presence (visibility and brightness), on the same scale the score engine uses.
+An aspect's interval is graded by class:
+
+| interval class | consonance |
+| -------------- | ---------- |
+| P1, P5, P8     | perfect    |
+| m3, M3, m6, M6 | imperfect  |
+| all others     | dissonant  |
+
+Bodies without a classical vowel are not voiced: Earth and the Fixed
+Stars, Pliny's Earth-as-proslambanomenos among them.
+
+```js
+tonus.harmonia(sky, { doctrina: "ptolemy" });
+tonus.harmonia(sky, { temperamentum: tonus.temperamentum("ptolemy-intense") });
+const h2 = tonus.harmonia(tonus.caelum({ from, to })); // h2.frames populated
+```
+
+```ts
+interface HarmoniaOpts {
+  temperamentum?: Temperamentum; // default: pythagorean A440
+  doctrina?: string; // from the doctrinae table; default "boethius"
+}
+
+interface Harmony {
+  doctrina: string;
+  auctor: string; // full Latin name of the doctrina's author
+  date: Date; // first cosmos's date
+  bodies: VoicedBody[];
+  aspects: VoicedAspect[];
+  frames?: Frame[]; // only when input was an array of cosmos
+
+  tabula: HarmonyTabulaRow[]; // flat iterable view
+  imprint: Imprint; // shared analytical fingerprint — score.md
+}
+
+interface VoicedPitch {
+  pitch: Pitch;
+  performance: Performance; // velocity 0–1, presence-scaled
+}
+
+interface VoicedBody extends Body {
+  nota: VoicedPitch;
+  presence: number; // 0–1 (visibility + brightness)
+  motion: number; // 0–1 (normalized speed)
+  greekName: string; // position in the Greek tonal system
+  vowel: PlanetVowel;
+}
+
+interface VoicedAspect extends Aspect {
+  interval: Interval; // carries the consonance grade
+}
+
+interface Frame {
+  date: Date;
+  bodies: VoicedBody[];
+  aspects: VoicedAspect[];
+}
+```
+
+## The planetary vowels
+
+Each classical planet sounds one of the seven Greek vowels; the
+Moon→Saturn ordering follows Nicomachus (_Excerpta ex Nicomacho_ 6), the
+attestations Godwin's _The Mystery of the Seven Vowels_ (1991).
+
+| Body    | Greek | Name    | Phonetic |
+| ------- | ----- | ------- | -------- |
+| Moon    | Α / α | Alpha   | a        |
+| Mercury | Ε / ε | Epsilon | e        |
+| Venus   | Η / η | Eta     | e        |
+| Sun     | Ι / ι | Iota    | i        |
+| Mars    | Ο / ο | Omicron | o        |
+| Jupiter | Υ / υ | Upsilon | u        |
+| Saturn  | Ω / ω | Omega   | o        |
+
+```ts
+interface PlanetVowel {
+  greek: string; // "Α"
+  greekLower: string; // "α"
+  name: string; // "Alpha"
+  modern: string; // "A"
+  phonetic: "a" | "e" | "i" | "o" | "u";
+  ipa: string;
+}
+```
+
+## The tabula
+
+`harmony.tabula` is the flat iteration surface: one row per voiced body
+(chant scores expose the same surface per note,
+[score.md](score.md#the-tabula)).
+
+```js
+h.tabula.find((r) => r.name === "Jupiter");
+// { name: "Jupiter", nomen: "Iuppiter", greekName: "parhypate meson",
+//   ratio: [64, 81], spn: "F4", hz: 347.7, presence: 0.55, velocity: 0.55,
+//   vowelGreek: "Υ", sign: "Leo", aspectCount: 3, … }
+```
+
+`ratio` is the doctrina's own fraction against the mese, the primary datum of
+the whole scheme — `spn` and `hz` are that ratio sounded against A4, not
+independent claims. Comparing doctrinae means comparing these: the table
+under [Theory & Context](#theory--context) is what the field returns.
+
+```ts
+interface HarmonyTabulaRow {
+  bodyIndex: number;
+  name: BodyName;
+  nomen: string;
+  greekName: string;
+
+  ratio: readonly [number, number]; // the doctrina's fraction against the mese
+  midi: number;
+  pc: number;
+  oct: number;
+  spn: string;
+  hz: number;
+
+  presence: number; // 0–1
+  motion: number; // 0–1
+  velocity: number; // 0–1, presence-scaled
+
+  vowelGreek: string;
+  vowelPhonetic: string;
+  vowelName: string;
+
+  zodiac: number; // 0–11
+  sign: string;
+  retrograde: boolean;
+  elongation: number; // deg from Sun
+  magnitude: number;
+
+  aspectCount: number; // aspects this body participates in
+}
+```
+
+## Theory & Context
+
+The doctrina ratios are reconstructed from the primary texts through
+Joscelyn Godwin's syntheses, mapping each body to a Greek tone-name and
+deriving its ratio by Pythagorean interval arithmetic normalized to the
+mese (Sun = 1/1). The full method, the taxonomy, and the decisions taken
+along the way are documented at the data — see `DOCTRINAE` in
+[`harmonia/data/doctrines.ts`](https://github.com/jeffreypierce/tonus/blob/main/src/engines/harmonia/data/doctrines.ts).
+The same arithmetic is laid out from the tuning side in
+[tuning.md](tuning.md#theory--context).
+
+The resulting ratios, by sphere from the outermost:
+
+| body        | `pythagoras` | `boethius` | `pliny`     | `ptolemy` |
+| ----------- | ------------ | ---------- | ----------- | --------- |
+| Fixed Stars | 3/2          | —          | —           | —         |
+| Saturn      | 3/4          | 3/4        | 4/3         | 2/1       |
+| Jupiter     | 64/81        | 64/81      | 65536/59049 | 3/2       |
+| Mars        | 8/9          | 8/9        | 256/243     | 9/8       |
+| Sun         | 1/1          | 1/1        | 1/1         | 1/1       |
+| Venus       | 9/8          | 256/243    | 16384/19683 | 3/4       |
+| Mercury     | 32/27        | 32/27      | 64/81       | 9/16      |
+| Moon        | 4/3          | 4/3        | 3/4         | 1/2       |
+| Earth       | —            | —          | 2/3         | —         |
+
+The single pitch separating Pythagoras from Boethius is Venus: a whole
+tone above the Sun in the disjunct system (9/8, B durum), a semitone in
+the conjunct (256/243, B molle) — the origin of the durum/molle
+distinction that runs through all of medieval music theory.
+
+## Sources
+
+Sources for this page are in the central [bibliography](https://github.com/jeffreypierce/tonus/blob/main/BIBLIOGRAPHY.md):
+`godwin-harmonies`, `godwin-spheres`, `godwin-vowels`, `boethius-institutione`,
+`doctrina-primaries` (Nicomachus, Plato, Pliny, Ptolemy, and the vowel
+attestations), `standish-jpl`, `schlyter-positions`.

package/docs/api/index.md

@@ -0,0 +1,263 @@
+# tonus API
+
+The technical center of tonus: the full public API, the conventions every method
+obeys, and the error contract. The API is **fourteen methods on the `tonus`
+namespace**, no sub-namespaces.
+
+```js
+import tonus from "tonus";
+```
+
+- [The methods](#the-methods) — by engine
+- [The appendix](#the-appendix) — the canonical constant tables
+- [Full contents](#full-contents) — every method and section
+- [Conventions](#conventions) — Latin/English, dates, determinism, error contracts, bibliography
+
+## The methods
+
+| Method                             | Page                    | Returns                                                 |
+| ---------------------------------- | ----------------------- | ------------------------------------------------------- |
+| `tonus.festum(query?)`             | [calendar](calendar.md) | `Feast[]` — liturgical calendar lookup                  |
+| `tonus.pascha(year)`               | [calendar](calendar.md) | `Pascha` — the movable anchors of a liturgical year     |
+| `tonus.cantus(query?)`             | [chant](chant.md)       | `Chant[]` — cross-corpus chant retrieval / GABC parsing |
+| `tonus.corpus(code?)`              | [chant](chant.md)       | `Corpus` — a book's ledger; no arg → the whole shelf     |
+| `tonus.proprium(query?)`           | [chant](chant.md)       | `Chant[]` — Mass propers                                |
+| `tonus.ordinarium(query?)`         | [chant](chant.md)       | `OrdinaryChant[]` — Kyriale                             |
+| `tonus.officium(query?)`           | [chant](chant.md)       | `Chant[]` — Divine Office hours                         |
+| `tonus.psalmus(query?)`            | [chant](chant.md)       | `Chant[]` — intoned psalm verses                        |
+| `tonus.temperamentum(input?)`      | [tuning](tuning.md)     | `Temperamentum` — tuning context                        |
+| `tonus.notatio(chant, opts?)`      | [score](score.md)       | `Score` — GABC → musical score                          |
+| `tonus.inscriptio(score, opts?)`   | [score](score.md)       | `Inscriptio` — `{ svg, geometry }`, the score drawn     |
+| `tonus.caelum(query?)`             | [heavens](heavens.md)   | `Cosmos \| Cosmos[]` — ephemeris                        |
+| `tonus.harmonia(cosmos, opts?)`    | [heavens](heavens.md)   | `Harmony` — musica universalis                          |
+| `tonus.census(query)`              | [census](census.md)     | `Census` — a chant against the corpus                   |
+
+### Query and builder functions
+
+**Query functions** (`festum`, `pascha`, `cantus`,
+`corpus`, `proprium`, `ordinarium`, `officium`, `psalmus`, `caelum`) name what you want and return arrays. Empty matches
+return `[]`, never `null`. Calendar results sort `day asc, dignity desc`;
+chant results sort by rank then incipit.
+
+**Builder functions** (`temperamentum`,
+`notatio`, `harmonia`, and `inscriptio`) construct and return context objects, and throw
+`Error` on invalid input. Only `Temperamentum` carries methods; `Score` is a
+plain data record, and rendering is the standalone `inscriptio`.
+
+`census` takes the query form but answers for exactly one chant: an id with no
+block throws rather than returning `[]`.
+
+Context objects can be passed back into query functions as filters:
+
+```js
+const feasts = tonus.festum({ season: "pasc" });
+tonus.proprium({ feast: feasts, office: "an" });
+
+const t = tonus.temperamentum({ tuning: "pythagorean" });
+t.nota("D4");
+```
+
+## The appendix
+
+The canonical constant tables ship as named exports beside the namespace.
+Return values are plain data, and the appendix carries tables only, never
+functions. It holds the tables a caller would otherwise transcribe: the mode
+list, the hour list, the valid `by:` values.
+
+```js
+import tonus, { SEASON_LABEL, HORAE, MODES } from "tonus";
+```
+
+Names follow the register rule: a table of Latin values takes a Latin name, a
+table of codes or English keeps English.
+
+**Calendar**
+
+| Export         | What it holds                                                   |
+| -------------- | --------------------------------------------------------------- |
+| `SEASON_LABEL` | season code → English display label (`adv` → "Advent")          |
+| `TEMPORA`      | season code → the Latin tempus name (`adv` → "Tempus Adventus") |
+| `GRADE_ORDER`  | the fourteen grades in precedence order (sort by `indexOf`)     |
+| `GRADUS`       | grade code → the Latin rank name                                |
+
+**Chant**
+
+| Export      | What it holds                                                              |
+| ----------- | -------------------------------------------------------------------------- |
+| `HORAE`     | the eight canonical hours, Matins first — the order is the content         |
+| `OFFICIA`   | office code → the Latin genus (`an` → "Antiphona")                         |
+| `ORDINARIA` | ordinary code → the Latin name (`ky` → "Kyrie eleison")                    |
+| `MODI`      | mode number → the Latin name (`"1"` → "Modus I")                           |
+| `SOURCES`   | book code → its bibliographic record; the codes `cantus({ source })` takes |
+
+**Tuning**
+
+| Export                 | What it holds                                                                                         |
+| ---------------------- | ----------------------------------------------------------------------------------------------------- |
+| `MODES`                | the eight modes' doctrine: final, tenor, ambitus, and the **received** cadence figures                |
+| `TONES`                | the psalm tones (Graduale Romanum appendix), with their differentiae                                  |
+| `CADENTIAE`            | the **mined** cadence families (`CadentiaFamilia`) — shape, arrival, share, finality, per-mode counts |
+| `CADENTIAE_POPULATION` | the denominator behind every `share`: all phrase-ends, and the same total per mode                    |
+
+The two cadence tables answer different questions. `MODES.cadences` is what the
+treatises say a mode closes on (final cadences only); `CADENTIAE` is what the
+corpus was measured doing (any target, so it is the one of the two that
+accounts for medial closes). See [one spine, two
+annotations](score.md#one-spine-two-annotations), and
+[lift](tuning.md#lift--how-mode-bound-a-close-is) for what `CADENTIAE_POPULATION`
+is for.
+
+**Heavens**
+
+| Export  | What it holds                                        |
+| ------- | ---------------------------------------------------- |
+| `SIGNS` | the twelve zodiac signs, English, ecliptic order     |
+| `SIGNA` | the same twelve in Latin (`Scorpius`, `Capricornus`) |
+
+**Census**
+
+| Export          | What it holds                                                                                          |
+| --------------- | ------------------------------------------------------------------------------------------------------ |
+| `CENSUS_GROUPS` | the field groups → `{ offset, count }`; the keys are the valid `by:` values **and** the `profile` keys |
+| `CENSUS_ORDER`  | every censused chant id, in block order — so membership is a lookup, not a `try/catch`                 |
+
+Use these to pool blocks without reproducing the distance rule — see [the census
+contract](census.md#distance-is-cosine-per-field-group).
+
+## Full contents
+
+Every method and every section, page by page, in dependency order. Pages later in
+the list resolve their pitches through the ones before.
+
+**[Tuning](tuning.md)** — the medieval pitch system; depends on nothing else.
+
+- [The context — `temperamentum`](tuning.md#the-context--temperamentum)
+- [Pitch input](tuning.md#pitch-input)
+- [Pitches — `nota`](tuning.md#pitches--nota)
+- [Steps — `gradus`](tuning.md#steps--gradus)
+- [Intervals — `intervallum`](tuning.md#intervals--intervallum)
+- [Neumes — `neuma`](tuning.md#neumes--neuma)
+- [Ratios — `ratio`](tuning.md#ratios--ratio)
+- [The gamut — `gamut`](tuning.md#the-gamut--gamut)
+- [Modes — `modus`](tuning.md#modes--modus) · [Cadence figures](tuning.md#cadence-figures) · [The corpus catalogue](tuning.md#the-corpus-catalogue--cadentiae)
+- [Psalm tones — `tonus`](tuning.md#psalm-tones--tonus)
+- [Theory & Context](tuning.md#theory--context) · [Sources](tuning.md#sources)
+
+**[Calendar](calendar.md)** — the Tridentine calendar against Julian/Gregorian-computus Easter.
+
+- [The day's feasts — `festum`](calendar.md#the-days-feasts--festum)
+- [Rank — `ritus` and `grade`](calendar.md#rank--ritus-and-grade)
+- [Seasons — the temporale](calendar.md#seasons--the-temporale)
+- [The year's anchors — `pascha`](calendar.md#the-years-anchors--pascha)
+- [Theory & Context](calendar.md#theory--context) · [Sources](calendar.md#sources)
+
+**[Chant](chant.md)** — the Solesmes books in GABC.
+
+- [The corpora](chant.md#the-corpora)
+- [The books — `corpus`](chant.md#the-books--corpus)
+- [Retrieval — `cantus`](chant.md#retrieval--cantus) · [Reaching the ordinary](chant.md#reaching-the-ordinary--ordinary)
+- [The repertoire as of a date — the era view](chant.md#the-repertoire-as-of-a-date--the-era-view)
+- [The Mass propers — `proprium`](chant.md#the-mass-propers--proprium)
+- [The ordinary — `ordinarium`](chant.md#the-ordinary--ordinarium)
+- [The Office — `officium`](chant.md#the-office--officium)
+- [Psalms — `psalmus`](chant.md#psalms--psalmus)
+- [Theory & Context](chant.md#theory--context) · [Sources](chant.md#sources)
+
+**[Score](score.md)** — GABC parsed into tuned, rhythmicized, drawable notes.
+
+- [The score — `notatio`](score.md#the-score--notatio)
+- [Interpretation — `pondus` and `accentus`](score.md#interpretation--pondus-and-accentus)
+- [The note](score.md#the-note)
+- [The tabula](score.md#the-tabula)
+- [Rendering — `inscriptio`](score.md#rendering) · [theme](score.md#theme--faces-and-ink) · [The analysis tracks](score.md#the-analysis-tracks)
+- [The imprint](score.md#the-imprint)
+- [Prosody](score.md#prosody)
+- [Cadences](score.md#cadences) · [One spine, two annotations](score.md#one-spine-two-annotations)
+- [Modulations](score.md#modulations)
+- [Theory & Context](score.md#theory--context) · [Sources](score.md#sources)
+
+**[Heavens](heavens.md)** — an ephemeris voiced through the planetary doctrines.
+
+- [The heavens — `caelum`](heavens.md#the-heavens--caelum)
+- [Aspects](heavens.md#aspects)
+- [The voiced heavens — `harmonia`](heavens.md#the-voiced-heavens--harmonia)
+- [The planetary vowels](heavens.md#the-planetary-vowels)
+- [The tabula](heavens.md#the-tabula)
+- [Theory & Context](heavens.md#theory--context) · [Sources](heavens.md#sources)
+
+**[Census](census.md)** — one chant measured against the corpus that holds it.
+
+- [The method](census.md#the-method)
+- [What a block holds](census.md#what-a-block-holds)
+- [How the measurement works](census.md#how-the-measurement-works)
+- [Distance is cosine per field group](census.md#distance-is-cosine-per-field-group)
+- [Profile and typicality](census.md#profile-and-typicality)
+- [Balance — distance and deviance](census.md#balance--distance-and-deviance)
+- [Neighbors, and `by`](census.md#neighbors-and-by)
+- [The era view](census.md#the-era-view)
+- [What the census is not](census.md#what-the-census-is-not)
+
+## Conventions
+
+### Latin and English
+
+The language of a key tells you the register of its value. A Latin key
+returns authentic Latin content; an English key returns a machine code or
+datum. Where a concept has both registers, they form a pair:
+
+| English  | Latin    |
+| -------- | -------- |
+| `season` | `tempus` |
+| `grade`  | `ritus`  |
+| `mode`   | `modus`  |
+| `name`   | `nomen`  |
+
+Other fields carry only one register. Latin-only, _e.g._ `genus`, `ordinarium`,
+`incipit`, `differentia`, `accentus`. English-only, _e.g._ `date`, `velocity`, `hz`.
+
+Display strings live in exported maps (_e.g._ `SEASON_LABEL`),
+never as label fields on objects — the maps are [the appendix](#the-appendix).
+
+### Dates
+
+Dates are UTC-canonical. Local-time constructions like
+`new Date(2026, 0, 6)` resolve to different days depending on the
+machine's timezone. Prefer `new Date("2026-01-06")` instead.
+
+`tonus.festum()` and `tonus.caelum()` default to **1 June 991**, the
+symbolic birthday of Guido d'Arezzo. Pass an explicit `date` for any other
+day.
+
+### Determinism
+
+All pure transforms are deterministic for identical inputs and options.
+No runtime network requests are made. Where variation is wanted (the scatter of
+an ensemble) it is seeded, so the same seed yields byte-identical output.
+
+### Error contract
+
+- Query functions return `[]` on no match, never throw — but an **empty or
+  unknown-key query** throws (a mistyped filter is a bug, not an empty result):
+  `festum({ month: 12 })` and `cantus({})` throw rather than silently resolving a
+  plausible-looking answer.
+- Builder functions throw `Error` with a descriptive message on invalid input.
+- `notatio` throws on invalid `Chant` input.
+- `inscriptio` throws on a non-`Score` argument or an unknown notation species.
+- `temperamentum.tonus()` throws if `mode` is `"auto"` — mode must be set
+  explicitly.
+- Malformed `comma`, ratio, or Scala input throws `RangeError`; custom scales
+  must supply 7 or 12 steps, beginning at `1/1` (a degree list) or ending at
+  `2/1` (Scala convention).
+- `pascha` throws `RangeError` on a non-finite year.
+- `caelum` in range mode (`{ from, to, step }`) throws `RangeError` on a missing
+  bound, `to` before `from`, a non-positive step, or a range exceeding the frame cap.
+- `harmonia` throws `RangeError` on an unknown doctrina.
+- `census` throws on an id with no block (the census covers only the chants
+  tonus ships) and on an unknown query key or field group.
+
+### The bibliography — [`BIBLIOGRAPHY.md`](https://github.com/jeffreypierce/tonus/blob/main/BIBLIOGRAPHY.md)
+
+The single source of truth for citations, each with a stable key. Code
+cites by bracketed key (`[biblio: key]`); each page keeps a short `## Sources`
+line pointing to the keys it draws on. Nothing outside `BIBLIOGRAPHY.md` restates
+a full reference.