tonus 0.1.6 → 0.5.0

package/dist/engines/census/census.js

@@ -0,0 +1,179 @@
+// ---------------------------------------------------------------------------
+// engines/census — where a chant sits against the corpus that holds it
+// ---------------------------------------------------------------------------
+// The corpus repo censuses every shipped chant into a block of 221 float32s:
+// modal behaviour, degree histogram, interval bigrams, trigram and cadence
+// vocabulary, chironomy, text setting, formula hits. This engine reads those
+// blocks and answers one question — how typical is this chant, and what is it
+// near?
+//
+// DISTANCE IS COSINE PER FIELD GROUP, never over the flat 221. 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, and `all` is the
+// equal-weight mean of those — every dimension one vote, no tunable weights.
+import { CENSUS_BLOCKS_B64, CENSUS_BLOCK_FLOATS, CENSUS_GROUPS, CENSUS_ORDER, } from "../../data/census.js";
+import { attestationCutoff, chantAdmissible } from "../chant/attest.js";
+const GROUP_NAMES = Object.keys(CENSUS_GROUPS);
+// ── The blocks, decoded once ────────────────────────────────────────────────
+// Base64 in a .ts is how the blocks ride in the package (no fs, no fetch, works
+// in a browser). Decoding is deferred so importing tonus does not pay for a
+// census nobody asked for.
+let _blocks = null;
+function blocks() {
+    if (_blocks)
+        return _blocks;
+    const bin = typeof Buffer !== "undefined"
+        ? Buffer.from(CENSUS_BLOCKS_B64, "base64")
+        : Uint8Array.from(atob(CENSUS_BLOCKS_B64), (c) => c.charCodeAt(0));
+    // The bytes are float32 little-endian. A DataView read is used rather than a
+    // Float32Array view over the buffer because the base64 decode gives no
+    // alignment guarantee, and because a big-endian host would silently
+    // byte-swap an aligned view.
+    const view = new DataView(bin.buffer, bin.byteOffset, bin.byteLength);
+    const out = new Float32Array(bin.byteLength / 4);
+    for (let i = 0; i < out.length; i++)
+        out[i] = view.getFloat32(i * 4, true);
+    _blocks = out;
+    return out;
+}
+let _index = null;
+function index() {
+    if (!_index)
+        _index = new Map(CENSUS_ORDER.map((id, i) => [id, i]));
+    return _index;
+}
+/** One group's slice of a chant's block. */
+function slice(blockIndex, group) {
+    const { offset, count } = CENSUS_GROUPS[group];
+    const start = blockIndex * CENSUS_BLOCK_FLOATS + offset;
+    return blocks().subarray(start, start + count);
+}
+/**
+ * Cosine similarity, 0–1. Two all-zero vectors are IDENTICAL (1), not
+ * undefined: two chants that both sit silent in a dimension agree perfectly
+ * about it. One zero vector against a non-zero one shares nothing, so 0.
+ */
+function cosine(a, b) {
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        const x = a[i];
+        const y = b[i];
+        dot += x * y;
+        na += x * x;
+        nb += y * y;
+    }
+    if (na === 0 && nb === 0)
+        return 1;
+    if (na === 0 || nb === 0)
+        return 0;
+    const c = dot / (Math.sqrt(na) * Math.sqrt(nb));
+    // Guard the float edge: a chant against itself must be exactly 1.
+    return c > 1 ? 1 : c < -1 ? -1 : c;
+}
+// ── The corpus mean, per group, computed once ───────────────────────────────
+// Typicality is measured against the whole SHIPPED corpus, not against the
+// filtered pool: `before` restricts who may be a neighbor, it does not
+// move the mean.
+let _means = null;
+function means() {
+    if (_means)
+        return _means;
+    const out = {};
+    const n = CENSUS_ORDER.length;
+    for (const g of GROUP_NAMES) {
+        const { count } = CENSUS_GROUPS[g];
+        const acc = new Float32Array(count);
+        for (let i = 0; i < n; i++) {
+            const s = slice(i, g);
+            for (let k = 0; k < count; k++)
+                acc[k] += s[k];
+        }
+        for (let k = 0; k < count; k++)
+            acc[k] /= n;
+        out[g] = acc;
+    }
+    _means = out;
+    return out;
+}
+const VALID_KEYS = new Set(["id", "k", "by", "before"]);
+/**
+ * The census of one chant: its profile against the corpus, where it is
+ * unusual, and what it is near.
+ */
+export function getCensus(query) {
+    if (!query || typeof query !== "object") {
+        throw new Error('census requires a query: census({ id: "gregobase:1210" }).');
+    }
+    const unknown = Object.keys(query).filter((k) => !VALID_KEYS.has(k));
+    if (unknown.length) {
+        throw new Error(`census: unknown query key(s) ${unknown.map((k) => `"${k}"`).join(", ")} ` +
+            `(expected ${[...VALID_KEYS].join(", ")}).`);
+    }
+    const { id } = query;
+    if (typeof id !== "string" || !id) {
+        throw new Error("census requires an id (a string), e.g. census({ id: \"gregobase:1210\" }).");
+    }
+    const self = index().get(id);
+    if (self == null) {
+        throw new Error(`census: no block for "${id}". The census covers the ${CENSUS_ORDER.length} chants ` +
+            "tonus ships; an id from a catalogue at large will not be among them.");
+    }
+    const by = query.by ?? "all";
+    if (by !== "all" && !GROUP_NAMES.includes(by)) {
+        throw new Error(`census: unknown field group "${by}" ` +
+            `(expected all, ${GROUP_NAMES.join(", ")}).`);
+    }
+    const k = query.k ?? 8;
+    if (!Number.isInteger(k) || k < 0) {
+        throw new Error(`census: k must be a non-negative integer, got ${String(query.k)}.`);
+    }
+    // The shared rule, not a local one — same door as cantus and the day verbs,
+    // so `before: 1098` means the same thing here as everywhere else.
+    const cutoff = attestationCutoff({ before: query.before }, "census");
+    // ── profile: each group against the corpus mean ──────────────────────────
+    const mean = means();
+    const profile = {};
+    for (const g of GROUP_NAMES) {
+        const s = slice(self, g);
+        profile[g] = {
+            values: Array.from(s),
+            typicality: cosine(s, mean[g]),
+        };
+    }
+    // ── balance: how far from the corpus mean, and where ─────────────────────
+    const typicalities = GROUP_NAMES.map((g) => profile[g].typicality);
+    const meanTypicality = typicalities.reduce((a, b) => a + b, 0) / typicalities.length;
+    const distance = 1 - meanTypicality;
+    // "Deviant" is relative to this chant's OWN mean, not an absolute threshold:
+    // the question is where a chant is unlike itself elsewhere, which is what
+    // makes it legible. Ties → alphabetical, so the answer is deterministic.
+    const deviantGroups = GROUP_NAMES.filter((g) => profile[g].typicality < meanTypicality).sort((a, b) => profile[a].typicality - profile[b].typicality ||
+        (a < b ? -1 : a > b ? 1 : 0));
+    // ── neighbors ────────────────────────────────────────────────────────────
+    const neighbors = [];
+    if (k > 0) {
+        const groupsToUse = by === "all" ? GROUP_NAMES : [by];
+        const selfSlices = groupsToUse.map((g) => slice(self, g));
+        const scored = [];
+        for (let i = 0; i < CENSUS_ORDER.length; i++) {
+            if (i === self)
+                continue;
+            const otherId = CENSUS_ORDER[i];
+            if (cutoff != null && !chantAdmissible(otherId, cutoff))
+                continue;
+            let sum = 0;
+            for (let gi = 0; gi < groupsToUse.length; gi++) {
+                sum += cosine(selfSlices[gi], slice(i, groupsToUse[gi]));
+            }
+            scored.push({ id: otherId, similarity: sum / groupsToUse.length });
+        }
+        // Ties → lower id, so the same question always has the same answer.
+        scored.sort((a, b) => b.similarity - a.similarity || (a.id < b.id ? -1 : 1));
+        neighbors.push(...scored.slice(0, k));
+    }
+    return { id, profile, balance: { distance, deviantGroups }, neighbors, by };
+}
+//# sourceMappingURL=census.js.map

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

@@ -0,0 +1,55 @@
+/** A field group census() can measure similarity on. */
+export type CensusGroup = "modal" | "degreeHist" | "melodic" | "trigram" | "cadenceFinal" | "cadenceMedial" | "chironomy" | "textual";
+/** `all` = the equal-weight mean of every group's cosine. */
+export type CensusBy = CensusGroup | "all";
+export interface CensusQuery {
+    /** The chant to census. Exactly one block per id (blocks are deduped by id). */
+    id: string;
+    /** How many neighbors to return. Default 8; 0 returns none. */
+    k?: number;
+    /** Which field group similarity is measured on. Default "all". */
+    by?: CensusBy;
+    /**
+     * Restrict neighbors to chants attested by this year. Unattested chants are
+     * EXCLUDED, not assumed old — the same rule as `cantus({ before })`.
+     */
+    before?: number;
+}
+/** One field group's reading for a chant, beside the corpus norm. */
+export interface CensusGroupProfile {
+    /** The chant's values for this group. */
+    values: readonly number[];
+    /**
+     * Cosine of this group against the corpus mean, 0–1. Low means the chant
+     * uses this dimension unlike the rest of the corpus.
+     */
+    typicality: number;
+}
+export interface CensusNeighbor {
+    id: string;
+    /** Cosine similarity on the chosen group(s), 0–1. Higher is nearer. */
+    similarity: number;
+}
+export interface Census {
+    /** The chant censused. */
+    id: string;
+    /** Per-group readings, keyed by group name. */
+    profile: Readonly<Record<CensusGroup, CensusGroupProfile>>;
+    balance: {
+        /**
+         * Mean cosine distance from the corpus centre across all groups, 0–1.
+         * 0 is a chant at the corpus mean; 1 has nothing in common with it.
+         */
+        distance: number;
+        /**
+         * Groups whose typicality falls furthest below the chant's own mean —
+         * where this chant is unusual, named. Most deviant first.
+         */
+        deviantGroups: readonly CensusGroup[];
+    };
+    /** Nearest chants on the chosen group, nearest first. Ties → lower id. */
+    neighbors: readonly CensusNeighbor[];
+    /** Which group the neighbor sweep measured on. */
+    by: CensusBy;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/engines/census/types.js

@@ -0,0 +1,8 @@
+// ---------------------------------------------------------------------------
+// engines/census/types — the census verb's shapes
+// ---------------------------------------------------------------------------
+// The field names are English by design. The census is measurement, not
+// repertoire: it says how a chant sits against the corpus it belongs to, and
+// the vocabulary for that is arithmetic, not liturgy.
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,39 @@
+/**
+ * A year → the latest century wholly attested by it, on the same scale as
+ * `Attestation.century` (10 = the 900s).
+ *
+ * CANTUS dates a manuscript only to its century, so `before: 1098` cannot mean
+ * "witnessed before 1098" — a book dated "11th century" may have been written
+ * in 1099. Admitting the whole 11th century would let a caller asking for 1098
+ * receive chants first written down after it, which is the one thing this
+ * filter exists to prevent. So a year admits only centuries that CLOSED before
+ * it: 1098 → 10 (through the 900s), 1100 → 11.
+ */
+export declare function centuryOf(year: number): number;
+/**
+ * The attestation cutoff a query asks for, as a century number — or null when
+ * the query carries no era view.
+ */
+export declare function attestationCutoff(query: {
+    before?: number;
+}, method: string): number | null;
+/**
+ * The cutoff a DAY verb serves under: the query's own view wins; otherwise the
+ * view `festum({ before })` stamped on the Feast rides along, so one argument
+ * at the calendar door carries through the whole day. Feasts resolved together
+ * came from one festum call and share one view — the first stamp speaks for
+ * the set.
+ */
+export declare function eraCutoff(query: {
+    before?: number;
+}, feasts: readonly {
+    before?: number;
+}[] | null | undefined, method: string): number | null;
+/**
+ * ONE admissibility rule for every door — the book (`cantus`) and the day
+ * verbs (`proprium`, `ordinarium`, `officium`) alike. Evidence, not
+ * existence: an undated chant is excluded under any cutoff rather than
+ * assumed old, and `both` satisfies either cursus.
+ */
+export declare function chantAdmissible(id: string, cutoff: number | null, cursus?: "monastic" | "secular"): boolean;
+//# sourceMappingURL=attest.d.ts.map

package/dist/engines/chant/attest.js

@@ -0,0 +1,90 @@
+// ---------------------------------------------------------------------------
+// engines/chant/attest — the era view's one admissibility rule
+//
+// A LEAF module, importing data only: every chant verb (cantus, proprium,
+// ordinarium, officium) draws its attestation filtering from here, so no verb
+// needs to import another verb's module to share the rule — the chant ↔
+// ordinary import cycle this replaces died of exactly that (a TDZ
+// ReferenceError whenever ordinary.js loaded first).
+//
+// ── A FILTER THAT LEFT AND CAME BACK ───────────────────────────────────────
+// This filter was once retired because its data had a genre-shaped hole: 31%
+// of the corpus undated, 93% of RESPONSORIES among them, so `before: 1098`
+// deleted the Hartker repertory from Epiphany Matins — wrong about the
+// liturgy on the exact question the library exists to answer. The rule was
+// never the problem; the coverage was. The corpus side closed it (crosswalk
+// gap-fill + matcher v2: composite respond+verse, the incipit-entry rule,
+// containment, genre disambiguation — all gold-gated): 85% of shipped records
+// now carry a dated witness and responsories are 92% DATED. What remains
+// undated is deliberate (psalter, formulas) or editorial territory (hymns,
+// modern propers) — not a genre bias. So the evidence law stands: an undated
+// chant is EXCLUDED under any cutoff. Silence is not evidence.
+//
+// A `century` option is deliberately absent. It was always `before: N * 100`
+// in different clothes — one cutoff internally, two spellings at the door —
+// so the two spellings converged on the one that is a year.
+// ---------------------------------------------------------------------------
+import { ATTESTATION } from "../../data/attestation.js";
+/**
+ * A year → the latest century wholly attested by it, on the same scale as
+ * `Attestation.century` (10 = the 900s).
+ *
+ * CANTUS dates a manuscript only to its century, so `before: 1098` cannot mean
+ * "witnessed before 1098" — a book dated "11th century" may have been written
+ * in 1099. Admitting the whole 11th century would let a caller asking for 1098
+ * receive chants first written down after it, which is the one thing this
+ * filter exists to prevent. So a year admits only centuries that CLOSED before
+ * it: 1098 → 10 (through the 900s), 1100 → 11.
+ */
+export function centuryOf(year) {
+    // floor, not ceil−1: the two agree everywhere except exact century
+    // multiples, where ceil−1 wrongly excluded the century that had just CLOSED
+    // (1100 → 10, so `before: 1100` refused the 1000s) — and the round inputs
+    // callers actually reach for are precisely the multiples that were wrong.
+    return Math.floor(year / 100);
+}
+/**
+ * The attestation cutoff a query asks for, as a century number — or null when
+ * the query carries no era view.
+ */
+export function attestationCutoff(query, method) {
+    if (query.before == null)
+        return null;
+    const cutoff = centuryOf(query.before);
+    if (!Number.isFinite(cutoff)) {
+        throw new Error(`${method}: before must be a year — the cutoff is the latest century number ` +
+            `(10 = the 900s) wholly closed by it; e.g. ${method}({ before: 1098 })`);
+    }
+    return cutoff;
+}
+/**
+ * The cutoff a DAY verb serves under: the query's own view wins; otherwise the
+ * view `festum({ before })` stamped on the Feast rides along, so one argument
+ * at the calendar door carries through the whole day. Feasts resolved together
+ * came from one festum call and share one view — the first stamp speaks for
+ * the set.
+ */
+export function eraCutoff(query, feasts, method) {
+    const own = attestationCutoff(query, method);
+    if (own != null)
+        return own;
+    const stamped = feasts?.find((f) => f?.before != null);
+    return stamped ? centuryOf(stamped.before) : null;
+}
+/**
+ * ONE admissibility rule for every door — the book (`cantus`) and the day
+ * verbs (`proprium`, `ordinarium`, `officium`) alike. Evidence, not
+ * existence: an undated chant is excluded under any cutoff rather than
+ * assumed old, and `both` satisfies either cursus.
+ */
+export function chantAdmissible(id, cutoff, cursus) {
+    if (cutoff == null && !cursus)
+        return true;
+    const a = ATTESTATION[id];
+    if (cutoff != null && (a == null || a.century > cutoff))
+        return false;
+    if (cursus && !(a?.cursus === cursus || a?.cursus === "both"))
+        return false;
+    return true;
+}
+//# sourceMappingURL=attest.js.map

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

@@ -1,10 +1,28 @@
-import type { Chant, CantusQuery } from "./types.js";
+import type { Chant, CantusQuery, ChantSource, Corpus, CorpusLedger, CorpusQuery } from "./types.js";
+import { CANTUS_QUERY_KEYS } from "./types.js";
+export declare const SOURCES: Record<ChantSource, Chant["source"]>;
+/**
+ * Metadata and content breakdown for one corpus book (`tonus.corpus`). Pass a
+ * source code; get the book's bibliographic identity plus its genre and mode
+ * distributions. Computed on first access from the loaded corpus, then cached.
+ */
+/**
+ * One book's ledger, or the whole shelf's.
+ *
+ * `corpus("am")` and `corpus({ book: "am" })` are the same question — the bare
+ * code came first and keeps working, the object form matches every other verb.
+ * `corpus()` with no argument returns the rollup.
+ */
+export declare function getCorpus(): CorpusLedger;
+export declare function getCorpus(code: ChantSource): Corpus;
+export declare function getCorpus(query: CorpusQuery): Corpus;
 export declare function resolveChant(id: string | null): Chant | null;
 export declare function resolveChants(ids: string[]): Chant[];
+export { CANTUS_QUERY_KEYS };
 /**
- * Cross-corpus chant retrieval (`tonus.cantus`) over GR, LA, LH, and LU.
- * A `gabc` field bypasses the corpus and returns a single user
- * chant parsed from raw GABC (body or full file with headers).
+ * Cross-corpus chant retrieval (`tonus.cantus`) over every corpus book
+ * (the codes in SOURCES). A `gabc` field bypasses the corpus and returns a
+ * single user chant parsed from raw GABC (body or full file with headers).
  */
 export declare function getChants(query?: CantusQuery): Chant[];
 //# sourceMappingURL=chant.d.ts.map