@heroiclands/package-build 23.12.5 → 23.12.6

package/engine/note-calendars.mjs

@@ -0,0 +1,314 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * **The calendar a note's dates print in.** A note's calendar is the first of:
+ *
+ * 1. its own `data.calendar`, on any type;
+ * 2. its culture's calendar: the culture note its `data.culture` names,
+ *    resolved by these same rules;
+ * 3. for a `place`, its `data.parents`, each resolved by these same rules. Two
+ *    or more distinct calendars among them are an error at the place's
+ *    `data.parents`, fixed by stating `data.calendar` on the place;
+ * 4. the package's configured `defaultCalendar`;
+ * 5. otherwise none, and a date prints as it was written.
+ *
+ * Steps 2 and 3 take only a calendar some note states: a culture or parent
+ * that itself falls through to the default contributes nothing, so parents
+ * that all fall through give the default and raise no error. A note met again
+ * while it is being resolved — a cycle through `data.parents` or
+ * `data.culture` — contributes nothing either, and the chain goes on to the
+ * default.
+ *
+ * The content index writes the result onto each note record as
+ * `resolvedCalendar`, the calendar note's Address, and
+ * every reader of a note's calendar reads it from there: the event views, the
+ * `dateformat` helper and the infobox's dates.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { canonicalKey, isAddressTuple, readCanonicalKey, renderAddress } from "./address.mjs";
+import { isAddressSegment } from "./address-charset.mjs";
+import { AddressLink } from "./address-values.mjs";
+import { formatDiagnostic, positionOfFrontmatterPath, positionOfYamlPath } from "./diagnostics.mjs";
+import { isNoteRecord, noteFile } from "./index-records.mjs";
+import { noteCalendarKey } from "./reckoning-markers.mjs";
+import { NOTE_SYSTEM } from "./systems.mjs";
+
+/** The configuration key naming the calendar of last resort. */
+export const DEFAULT_CALENDAR_KEY = "defaultCalendar";
+
+/**
+ * The canonical key an Address names, without any anchor.
+ *
+ * @param {unknown} value - A tuple, an {@link AddressLink}, or anything else.
+ * @returns {string|undefined} The key, or `undefined` for anything else.
+ */
+function addressKey(value) {
+    const tuple = value instanceof AddressLink ? value.target : value;
+    return isAddressTuple(tuple) ? renderAddress(tuple) : undefined;
+}
+
+/**
+ * Whether a record is a calendar note.
+ *
+ * @param {Record<string, any>|undefined} record - An index record.
+ * @returns {boolean} Whether it is a `lore` note with `subType: calendar`.
+ */
+function isCalendarNote(record) {
+    return record?.type === "lore" && String(record.subType ?? "").toLowerCase() === "calendar";
+}
+
+/**
+ * The canonical key of the calendar `defaultCalendar` names, or why it names none.
+ *
+ * @param {unknown} shortcode - The configured value.
+ * @param {string} contentPackage - The package the shortcode is read in.
+ * @param {(key: string) => Record<string, any>|undefined} recordOf - A local
+ *   note by canonical key.
+ * @returns {{key?: string, problem?: string}} The calendar, or the problem.
+ */
+function defaultCalendarKey(shortcode, contentPackage, recordOf) {
+    if (shortcode === undefined || shortcode === null) return {};
+    const named = String(shortcode);
+    const key =
+        isAddressSegment(named) ?
+            canonicalKey(contentPackage, NOTE_SYSTEM, "lore", named)
+        :   undefined;
+    if (key && isCalendarNote(recordOf(key))) return { key };
+    return {
+        problem:
+            `${DEFAULT_CALENDAR_KEY} ${named} names no calendar note in ${contentPackage}; ` +
+            `name the shortcode of a lore note with subType: calendar`,
+    };
+}
+
+/**
+ * Write each note's resolved calendar into its record, as `resolvedCalendar`.
+ *
+ * Reads each note's authored `data.calendar`, `data.culture` and
+ * `data.parents`, so it runs before the index writes a resolved culture over
+ * `data.culture`. A culture or parent in another package contributes the
+ * calendar its published entry states in `data.calendar`, and nothing else.
+ *
+ * @param {Array<Record<string, any>>} records - Index records, every Address a
+ *   tuple. Records that are not notes are passed over.
+ * @param {object} options - Options.
+ * @param {string} options.contentPackage - The package the records belong to.
+ * @param {string} [options.defaultCalendar] - The configured calendar of last
+ *   resort, a calendar note's shortcode.
+ * @param {string} [options.configFile] - The configuration file, where an
+ *   unknown `defaultCalendar` is reported.
+ * @param {string} [options.contentBase] - The content tree, for opening a note
+ *   to locate a finding.
+ * @param {(key: string) => Record<string, any>|undefined} [options.foreignRecord] -
+ *   Another package's entry for a canonical address.
+ * @param {object[]} [options.problems] - Receives each finding. Omitted, the
+ *   findings are collected and one Error lists them all.
+ * @param {Map<string, {raw: string}>} [options.parsed] - Notes already read, keyed by file.
+ * @returns {Array<Record<string, any>>} The same records.
+ * @throws {Error} When `problems` is omitted and anything is reported.
+ */
+export function resolveNoteCalendars(
+    records,
+    { contentPackage, defaultCalendar, configFile, contentBase, foreignRecord, problems, parsed },
+) {
+    const notes = new Map();
+    for (const record of records) {
+        if (!isNoteRecord(record) || !isAddressSegment(String(record.shortcode ?? ""))) continue;
+        const key = canonicalKey(contentPackage, NOTE_SYSTEM, record.type, record.shortcode);
+        if (!notes.has(key)) notes.set(key, record);
+    }
+    const findings = [];
+
+    const fallback = defaultCalendarKey(defaultCalendar, contentPackage, (key) => notes.get(key));
+    if (fallback.problem) {
+        const file = configFile ?? "package-build.config.yaml";
+        const source =
+            configFile && /\.ya?ml$/.test(configFile) && fs.existsSync(configFile) ?
+                fs.readFileSync(configFile, "utf8")
+            :   undefined;
+        findings.push({
+            file,
+            ...(source ? positionOfYamlPath(source, [DEFAULT_CALENDAR_KEY], { key: true }) : {}),
+            severity: "error",
+            message: fallback.problem,
+        });
+    }
+
+    const memo = new Map();
+    const inProgress = new Set();
+
+    /**
+     * The calendar some note states for a source Address, local or foreign.
+     *
+     * @param {unknown} value - A `data.culture` or `data.parents` Address.
+     * @returns {string|undefined} The calendar's canonical key.
+     */
+    const statedThrough = (value) => {
+        const key = addressKey(value);
+        if (!key) return undefined;
+        const tuple = value instanceof AddressLink ? value.target : value;
+        if (tuple.package === contentPackage) {
+            const record = notes.get(
+                canonicalKey(contentPackage, NOTE_SYSTEM, tuple.type, tuple.shortcode),
+            );
+            return record ? resolve(record) : undefined;
+        }
+        return addressKey(foreignRecord?.(key)?.data?.calendar);
+    };
+
+    /**
+     * Report parents that disagree.
+     *
+     * @param {Record<string, any>} record - The place.
+     * @param {Array<{key: string, via: unknown}>} distinct - The calendars and
+     *   the parent each came through.
+     */
+    const conflict = (record, distinct) => {
+        const file = contentBase ? noteFile(contentBase, record) : record.file?.path;
+        const raw =
+            parsed?.get(file)?.raw ??
+            (contentBase && fs.existsSync(file) ? fs.readFileSync(file, "utf8") : undefined);
+        let position = positionOfFrontmatterPath(raw, ["data", "parents"], { key: true });
+        if (position.line === undefined)
+            position = positionOfFrontmatterPath(raw, ["data"], { key: true });
+        const via = (value) => {
+            const tuple = value instanceof AddressLink ? value.target : value;
+            return tuple.package === contentPackage ? tuple.shortcode : addressKey(tuple);
+        };
+        const named = distinct.map(({ key, via: source }) => `${key} via ${via(source)}`);
+        findings.push({
+            file,
+            ...position,
+            severity: "error",
+            message:
+                `place ${record.shortcode}: data.parents resolve to different calendars ` +
+                `(${named.join(", ")}); state data.calendar`,
+        });
+    };
+
+    /**
+     * The calendar a note states through its own field, its culture or — for a
+     * place — its parents, ignoring the default.
+     *
+     * @param {Record<string, any>} record - The note.
+     * @returns {string|undefined} The calendar's canonical key.
+     */
+    const resolveRecord = (record) => {
+        const own = addressKey(record.data?.calendar);
+        if (own) return own;
+        const culture = statedThrough(record.data?.culture);
+        if (culture) return culture;
+        if (record.type !== "place") return undefined;
+        const parents = Array.isArray(record.data?.parents) ? record.data.parents : [];
+        const distinct = new Map();
+        for (const parent of parents) {
+            const calendar = statedThrough(parent);
+            if (calendar && !distinct.has(calendar)) distinct.set(calendar, parent);
+        }
+        if (distinct.size > 1) {
+            conflict(
+                record,
+                [...distinct].map(([key, via]) => ({ key, via })),
+            );
+            return undefined;
+        }
+        return distinct.keys().next().value;
+    };
+
+    /**
+     * A local note's stated calendar, memoised; a note already being resolved
+     * is a cycle and states nothing.
+     *
+     * @param {Record<string, any>} record - The note.
+     * @returns {string|undefined} The calendar's canonical key.
+     */
+    const resolve = (record) => {
+        if (memo.has(record)) return memo.get(record);
+        if (inProgress.has(record)) return undefined;
+        inProgress.add(record);
+        const result = resolveRecord(record);
+        inProgress.delete(record);
+        memo.set(record, result);
+        return result;
+    };
+
+    // Walked in address order, so which note of a cycle is met first is a fact
+    // about the content rather than about directory-read order.
+    const calendars = new Map();
+    for (const key of [...notes.keys()].sort())
+        calendars.set(key, resolve(notes.get(key)) ?? fallback.key);
+    // A note's second record — an item's documentation journal — is the same
+    // note, and reads in the same calendar.
+    for (const record of records) {
+        if (!isNoteRecord(record) || !isAddressSegment(String(record.shortcode ?? ""))) continue;
+        const calendar = calendars.get(
+            canonicalKey(contentPackage, NOTE_SYSTEM, record.type, record.shortcode),
+        );
+        if (calendar) record.resolvedCalendar = readCanonicalKey(calendar);
+        else delete record.resolvedCalendar;
+    }
+
+    findings.sort(
+        (a, b) =>
+            String(a.file).localeCompare(String(b.file), "en") ||
+            (a.line ?? 0) - (b.line ?? 0) ||
+            (a.column ?? 0) - (b.column ?? 0),
+    );
+    if (problems) problems.push(...findings);
+    else if (findings.length)
+        throw Object.assign(new Error(findings.map(formatDiagnostic).join("\n")), {
+            located: true,
+        });
+    return records;
+}
+
+/**
+ * The configuration file in a package root, where a configured value is
+ * reported.
+ *
+ * @param {string|undefined} rootDir - The package root.
+ * @param {readonly string[]} names - The file names a configuration may take.
+ * @returns {string|undefined} The first that exists.
+ */
+export function configFileIn(rootDir, names) {
+    if (!rootDir) return undefined;
+    for (const name of names) {
+        const file = path.join(rootDir, name);
+        if (fs.existsSync(file)) return file;
+    }
+    return undefined;
+}
+
+/**
+ * The calendar a note's dates print in: the one the content index resolved for
+ * it, where the reckoning context carries it, else the note's own
+ * `data.calendar`.
+ *
+ * @param {object|undefined} fm - The note's frontmatter.
+ * @param {{noteCalendars?: Map<string, string>}} [dates] - The reckoning context.
+ * @returns {string|undefined} The calendar's Address or shortcode.
+ */
+export function noteCalendar(fm, dates) {
+    const key = noteCalendarKey(fm);
+    const resolved = key ? dates?.noteCalendars?.get(key) : undefined;
+    if (resolved) return resolved;
+    const own = fm?.data?.calendar;
+    if (own === undefined || own === null || own === "") return undefined;
+    return addressKey(own) ?? String(own);
+}

package/engine/note-vocabulary.mjs

@@ -1030,6 +1030,17 @@ export const SHARED_DATA_FIELDS = Object.freeze([
         describe:
             "Deliberate cross-references in reading order, with optional glosses; shown on the site, in journals and in books.",
     }),
+    Object.freeze({
+        name: "calendar",
+        ...LINK,
+        ref: "lore",
+        accepts: Object.freeze(["lore"]),
+        check: checkCalendarChoice,
+        describe:
+            "The calendar this note's dates print in, as a calendar lore note. Absent, the " +
+            "note takes its culture's calendar, then — for a place — its parents', then the " +
+            "configured `defaultCalendar`.",
+    }),
     Object.freeze({
         name: "id",
         ...TEXT,
@@ -1596,14 +1607,6 @@ export const NOTE_VOCABULARY = Object.freeze({
                     "When the being was born — a date, or `unknown` where the birth is " +
                     "unrecorded. Absent, the being was never born.",
             },
-            {
-                name: "calendar",
-                ...LINK,
-                ref: "lore",
-                accepts: ["lore"],
-                check: checkCalendarChoice,
-                describe: "Calendar that displays this being's dates.",
-            },
             {
                 name: "died",
                 ...TEXT,
@@ -2281,14 +2284,6 @@ export const NOTE_VOCABULARY = Object.freeze({
         check: checkPlace,
         data: Object.freeze([
             EVENTS_FIELD,
-            {
-                name: "calendar",
-                ...LINK,
-                ref: "lore",
-                accepts: ["lore"],
-                check: checkCalendarChoice,
-                describe: "Calendar that displays this place's dates.",
-            },
             {
                 name: "demonym",
                 ...TEXT,

package/engine/reckoning-markers.mjs

@@ -209,13 +209,69 @@ export function resolveReckoningMarkers(index, daysPerYear) {
     return { eras, markers, findings };
 }
 
+/**
+ * The key a note's resolved calendar is filed under: its type and shortcode.
+ *
+ * @param {object|undefined} fm - A note's frontmatter or record.
+ * @returns {string|undefined} The key.
+ */
+export function noteCalendarKey(fm) {
+    return fm?.type && fm?.shortcode ? `${fm.type}\u0000${fm.shortcode}` : undefined;
+}
+
+/**
+ * A record's `resolvedCalendar` as its canonical Address string: an Address
+ * tuple, as a record in memory carries it, or the string an encoded record
+ * carries.
+ *
+ * @param {unknown} value - The value.
+ * @returns {string|undefined} The Address, or `undefined` for none.
+ */
+export function calendarAddress(value) {
+    if (typeof value === "string") return value || undefined;
+    return value && typeof value === "object" && "shortcode" in value ?
+            renderAddress(/** @type {any} */ (value))
+        :   undefined;
+}
+
+/**
+ * Each note's resolved calendar, by {@link noteCalendarKey}, from the
+ * `resolvedCalendar` the content index writes on a record.
+ *
+ * @param {Iterable<object>|undefined} notes - Index records, or
+ *   `{ fm, resolvedCalendar }` entries.
+ * @returns {Map<string, string>} Note key to the calendar's canonical Address.
+ */
+export function noteCalendarMap(notes) {
+    const out = new Map();
+    for (const note of notes ?? []) {
+        const calendar = calendarAddress(note?.resolvedCalendar);
+        if (!calendar) continue;
+        const key = noteCalendarKey(note?.fm ?? note?.frontmatter ?? note);
+        if (key && !out.has(key)) out.set(key, calendar);
+    }
+    return out;
+}
+
 /** One resolved date context per corpus index. */
 const contexts = new WeakMap();
 
-/** Read the world's year length and resolve every calendar era in one corpus. */
+/**
+ * Read the world's year length and resolve every calendar era in one corpus.
+ *
+ * The context also carries `noteCalendars`, each note's resolved calendar by
+ * note, read from the `resolvedCalendar` the content index writes on a record;
+ * {@link module:engine/note-calendars.noteCalendar} reads it.
+ */
 export function reckoningContext(index) {
     if (!index || typeof index !== "object")
-        return { eras: new Map(), markers: new Map(), daysPerYear: undefined, findings: [] };
+        return {
+            eras: new Map(),
+            markers: new Map(),
+            daysPerYear: undefined,
+            findings: [],
+            noteCalendars: new Map(),
+        };
     const cached = contexts.get(index);
     if (cached) return cached;
     const world = (index.notes ?? []).find((note) => {
@@ -224,7 +280,11 @@ export function reckoningContext(index) {
     });
     const fm = world?.fm ?? world?.frontmatter ?? world;
     const daysPerYear = fm?.data?.year?.days;
-    const context = { ...resolveReckoningMarkers(index, daysPerYear), daysPerYear };
+    const context = {
+        ...resolveReckoningMarkers(index, daysPerYear),
+        daysPerYear,
+        noteCalendars: noteCalendarMap(index.notes),
+    };
     contexts.set(index, context);
     return context;
 }

package/engine/sql-tables.mjs

@@ -31,7 +31,7 @@ import { collectAnchors } from "./anchors.mjs";
 import { expandContentTables } from "./content-tables.mjs";
 import { NOTE_VOCABULARY, isGmNote } from "./note-vocabulary.mjs";
 import { encodeAddresses, flattenPublishedAddresses } from "./address-values.mjs";
-import { EVENT_COLUMNS, EVENT_SORT_COLUMNS, eventRows } from "./event-rows.mjs";
+import { EVENT_COLUMNS, EVENT_SORT_COLUMNS, eventCalendars, eventRows } from "./event-rows.mjs";
 import { reckoningContext } from "./reckoning-markers.mjs";
 import { NAME_COLUMNS, namesRows } from "./name-rows.mjs";
 import {
@@ -552,7 +552,7 @@ async function createRelations(connection, file, records, prefix = "", audience
  */
 async function createEventRelation(connection, file, records, prefix, audience) {
     const visible = audience === "public" ? records.filter((record) => !isGmNote(record)) : records;
-    const rows = eventRows(visible, reckoningContext({ notes: records }));
+    const rows = eventRows(visible, reckoningContext({ notes: records }), eventCalendars(records));
     if (!rows.length) {
         const columns = EVENT_COLUMNS.map((column) => {
             const type = EVENT_SORT_COLUMNS.includes(column) ? "DOUBLE" : "VARCHAR";
@@ -564,7 +564,13 @@ async function createEventRelation(connection, file, records, prefix, audience)
         return;
     }
     fs.writeFileSync(file, rows.map((row) => JSON.stringify(row)).join("\n"));
-    await createTableFromFile(connection, `${prefix}events`, readJsonAuto(file));
+    // `whenIn` and `untilIn` are keyed by calendar Address, and read as structs
+    // whatever their number of keys, so `whenIn['<calendar>']` always binds.
+    await createTableFromFile(
+        connection,
+        `${prefix}events`,
+        readJsonAuto(file).replace(/\)$/, ", map_inference_threshold=-1)"),
+    );
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "23.12.5",
+    "version": "23.12.6",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/content-config.d.mts

@@ -637,6 +637,13 @@ export type ContentBuildConfigInput = {
      * Setting-wide neutral current date; defaults to "720.1".
      */
     currentDate?: string | undefined;
+    /**
+     * Shortcode of the `lore` note with
+     *      `subType: calendar` that prints the
+     *      dates of a note no other rule gives a
+     *      calendar.
+     */
+    defaultCalendar?: string | undefined;
     /**
      * Content package name — the address
      * namespace every note in this
@@ -761,6 +768,11 @@ export type ContentBuildConfig = {
      * Setting-wide neutral current date.
      */
     currentDate: string;
+    /**
+     * The calendar of last resort's
+     * shortcode, `null` when none is named.
+     */
+    defaultCalendar: string | null;
     rootDir: string;
     contentPackage: string;
     /**

package/types/engine/content-index.d.mts

@@ -205,6 +205,10 @@ export function resolveCultures(records: Array<Record<string, any>>, { contentPa
  *   reader receives each as a finding, and the emitter throws once, listing
  *   every one.
  * @param {string} [options.currentDate="720.1"] - Setting-wide neutral current date.
+ * @param {string} [options.defaultCalendar] - The calendar of last resort, a
+ *   calendar note's shortcode; see {@link module:engine/note-calendars}.
+ * @param {string} [options.configFile] - The configuration file, where an
+ *   unknown `defaultCalendar` is reported.
  * @param {(key: string) => ({culture?: unknown}|undefined)} [options.foreignRecord] -
  *   Another package's entry for a canonical address, read for a parent that
  *   package publishes; see {@link resolveCultures}.
@@ -217,7 +221,7 @@ export function resolveCultures(records: Array<Record<string, any>>, { contentPa
  * @returns {Array<Record<string, any>>} The records, in a total order that does
  *   not depend on directory-read order.
  */
-export function collectContentIndex(contentBase: string, { contentPackage, currentDate, skipDirectories, assetsBase, manifest, problems, addressContext, foreignRecord, parsed, sources, syntax, nameTypes, }: {
+export function collectContentIndex(contentBase: string, { contentPackage, currentDate, defaultCalendar, configFile, skipDirectories, assetsBase, manifest, problems, addressContext, foreignRecord, parsed, sources, syntax, nameTypes, }: {
     contentPackage: string;
     skipDirectories: readonly string[];
     assetsBase?: string | undefined;
@@ -225,6 +229,8 @@ export function collectContentIndex(contentBase: string, { contentPackage, curre
     addressContext?: object | undefined;
     problems?: object[] | undefined;
     currentDate?: string | undefined;
+    defaultCalendar?: string | undefined;
+    configFile?: string | undefined;
     foreignRecord?: ((key: string) => ({
         culture?: unknown;
     } | undefined)) | undefined;

package/types/engine/event-rows.d.mts

@@ -1,15 +1,30 @@
+/**
+ * Every calendar a set of records can print an event's date in: each calendar
+ * note's canonical Address, and every calendar a note resolves to.
+ *
+ * @param {Iterable<Record<string, any>>} records - Index records, every
+ *   Address a string.
+ * @returns {string[]} The calendars, sorted.
+ */
+export function eventCalendars(records: Iterable<Record<string, any>>): string[];
 /**
  * The `events` rows of a set of index records.
  *
  * @param {Iterable<Record<string, any>>} records - Index records, every
  *   Address a string, already narrowed to the audience being published to.
  * @param {object} [dates] - The reckoning context the dates are printed in.
+ * @param {readonly string[]} [calendars] - The calendars `whenIn` and
+ *   `untilIn` are keyed by: {@link eventCalendars} of every record of the
+ *   corpus, whatever the audience, so every surface's relation has the same
+ *   keys. Absent, those of `records`.
  * @returns {object[]} One row per event entry, in record then entry order.
  */
-export function eventRows(records: Iterable<Record<string, any>>, dates?: object): object[];
+export function eventRows(records: Iterable<Record<string, any>>, dates?: object, calendars?: readonly string[]): object[];
 /** The sort keys a row carries, after the event's own keys. */
 export const EVENT_SORT_COLUMNS: readonly string[];
 /** The printed dates a row carries, after the sort keys. */
 export const EVENT_TEXT_COLUMNS: readonly string[];
+/** The dates a row carries in every calendar, after the printed ones. */
+export const EVENT_CALENDAR_COLUMNS: readonly string[];
 /** Every column of the `events` relation, in order. */
 export const EVENT_COLUMNS: any;

package/types/engine/event-views.d.mts

@@ -34,7 +34,7 @@ export function eventViewSections(db: object, records: Iterable<object>, fileOf:
  *
  * @type {ReadonlyArray<Readonly<{slug: string, heading: string,
  *   applies: (record: object) => boolean,
- *   query: (self: string[], shape: CorpusShape, columns?: {felt?: boolean}) => {fence: string, own?: string}|null,
+ *   query: (self: string[], shape: CorpusShape, columns?: {felt?: boolean, calendar?: string}) => {fence: string, own?: string}|null,
  *   owners?: (db: object, selves: string[][], shape: CorpusShape) => Promise<Set<string>>,
  *   felt?: (db: object, selves: string[][], shape: CorpusShape) => Promise<Set<string>>}>>}
  */
@@ -44,6 +44,7 @@ export const EVENT_VIEWS: ReadonlyArray<Readonly<{
     applies: (record: object) => boolean;
     query: (self: string[], shape: CorpusShape, columns?: {
         felt?: boolean;
+        calendar?: string;
     }) => {
         fence: string;
         own?: string;

package/types/engine/note-calendars.d.mts

@@ -0,0 +1,60 @@
+/**
+ * Write each note's resolved calendar into its record, as `resolvedCalendar`.
+ *
+ * Reads each note's authored `data.calendar`, `data.culture` and
+ * `data.parents`, so it runs before the index writes a resolved culture over
+ * `data.culture`. A culture or parent in another package contributes the
+ * calendar its published entry states in `data.calendar`, and nothing else.
+ *
+ * @param {Array<Record<string, any>>} records - Index records, every Address a
+ *   tuple. Records that are not notes are passed over.
+ * @param {object} options - Options.
+ * @param {string} options.contentPackage - The package the records belong to.
+ * @param {string} [options.defaultCalendar] - The configured calendar of last
+ *   resort, a calendar note's shortcode.
+ * @param {string} [options.configFile] - The configuration file, where an
+ *   unknown `defaultCalendar` is reported.
+ * @param {string} [options.contentBase] - The content tree, for opening a note
+ *   to locate a finding.
+ * @param {(key: string) => Record<string, any>|undefined} [options.foreignRecord] -
+ *   Another package's entry for a canonical address.
+ * @param {object[]} [options.problems] - Receives each finding. Omitted, the
+ *   findings are collected and one Error lists them all.
+ * @param {Map<string, {raw: string}>} [options.parsed] - Notes already read, keyed by file.
+ * @returns {Array<Record<string, any>>} The same records.
+ * @throws {Error} When `problems` is omitted and anything is reported.
+ */
+export function resolveNoteCalendars(records: Array<Record<string, any>>, { contentPackage, defaultCalendar, configFile, contentBase, foreignRecord, problems, parsed }: {
+    contentPackage: string;
+    defaultCalendar?: string | undefined;
+    configFile?: string | undefined;
+    contentBase?: string | undefined;
+    foreignRecord?: ((key: string) => Record<string, any> | undefined) | undefined;
+    problems?: object[] | undefined;
+    parsed?: Map<string, {
+        raw: string;
+    }> | undefined;
+}): Array<Record<string, any>>;
+/**
+ * The configuration file in a package root, where a configured value is
+ * reported.
+ *
+ * @param {string|undefined} rootDir - The package root.
+ * @param {readonly string[]} names - The file names a configuration may take.
+ * @returns {string|undefined} The first that exists.
+ */
+export function configFileIn(rootDir: string | undefined, names: readonly string[]): string | undefined;
+/**
+ * The calendar a note's dates print in: the one the content index resolved for
+ * it, where the reckoning context carries it, else the note's own
+ * `data.calendar`.
+ *
+ * @param {object|undefined} fm - The note's frontmatter.
+ * @param {{noteCalendars?: Map<string, string>}} [dates] - The reckoning context.
+ * @returns {string|undefined} The calendar's Address or shortcode.
+ */
+export function noteCalendar(fm: object | undefined, dates?: {
+    noteCalendars?: Map<string, string>;
+}): string | undefined;
+/** The configuration key naming the calendar of last resort. */
+export const DEFAULT_CALENDAR_KEY: "defaultCalendar";