@heroiclands/package-build 22.9.0 → 22.9.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @heroiclands/package-build
 
+## 22.9.1
+
+### Patch Changes
+
+**A being's age can be computed rather than written.** Beside a dated `born` and no authored `age`, the age follows from the birth date and the package's declared present — a birthday later in the year counts one less than plain subtraction would.
+
+**The present is declared on the world's own `place` note**, in `data.present`. A package that states none computes no age and says nothing about it.
+
+**`content-build lint` warns when an authored `age` disagrees** with what a dated `born` computes to, naming both values; it stays silent beside `born: unknown` or an absent `born`.
+
+**An estimated age keeps its `~` in the compiled document**, with the plain number carried beside it as `ageYears`.
+
 ## 22.9.0
 
 ### Minor Changes

package/docs/api.md

@@ -649,6 +649,19 @@ A calendar is a `lore` note with `subType: calendar`, declaring the months it ke
 | `compileCalendars`   | `compileCalendars(index, opts)`                       | `{calendars, invariants}`                  | building every calendar a package declares, or none where it states no year |
 | `calendariaEnvelope` | `calendariaEnvelope(definition, opts)`                | `object` — the import envelope             | wrapping a definition for a hand import through Calendaria's settings       |
 
+### `engine.beingAge`
+
+The middle state of a being's `age`: absent beside a dated `born`, it is computed against the package's declared present — the two dates compared, not the two years subtracted, so a birthday later in the year than the present counts one less. `applyComputedBeingAge` fills it in on the frontmatter object a pass already holds, never on the note; `checkBeingAge` is `being`'s `NOTE_VOCABULARY` check, raising a warning where an authored `age` disagrees with what a dated `born` computes to. An estimate's `~` is read the way a date's is: the authored string stays verbatim, and `ageYears` carries the magnitude beside it.
+
+| Export                     | Signature                                | Returns                        | Use it when                                                               |
+| -------------------------- | ---------------------------------------- | ------------------------------ | ------------------------------------------------------------------------- |
+| `computeAge`               | `computeAge(bornRaw, presentRaw)`        | `number \| null`               | reading the age two dates imply, in whole years                           |
+| `parseAgeMagnitude`        | `parseAgeMagnitude(raw)`                 | `{approximate, value} \| null` | reading an authored `age`'s `~` mark and its magnitude                    |
+| `applyComputedBeingAge`    | `applyComputedBeingAge(fm, presentRaw)`  | `void` — mutates `fm.data`     | filling in a being's computed `age`, or the `ageYears` beside an estimate |
+| `presentAmongRecords`      | `presentAmongRecords(records)`           | the present, or `null`         | reading the declared present from a batch of flat index records           |
+| `presentAmongFrontmatters` | `presentAmongFrontmatters(frontmatters)` | the present, or `null`         | reading the declared present from a batch of raw frontmatter objects      |
+| `checkBeingAge`            | `checkBeingAge(note, opts)`              | `object[]` — findings          | holding a being's authored `age` to what `born` and the present compute   |
+
 ### `engine.contentAddress`
 
 Where a content note publishes on the web. One rule, in one place, because two builds need the same answer: the knowledgebase build renders the page, and the link manifest records the address other packages link to. Stating it twice is how a manifest comes to assert a URL that resolves at build time and 404s for the reader.

package/docs/content-format.md

@@ -2304,6 +2304,7 @@ Generates a living (or undead, or spirit) being.
 | `born`                      | `YYYY/MM/DD \| unknown`                        | When the being was born; absent, it was never born                                               |
 | `died`                      | `YYYY/MM/DD \| unknown`                        | When the being died; absent, it is alive                                                         |
 | `age`                       | `34 \| ~34`                                    | Age in years, stated only to override what `born` says; `~` marks an estimate                    |
+| `ageYears`                  | `number`                                       | Written by the compiler beside an `age` estimate — the `~` stripped; a note never authors this   |
 | `height`                    | `number`                                       | Height in meters                                                                                 |
 | `weight`                    | `number`                                       | Weight in kilograms                                                                              |
 | `frame`                     | `scant \| light \| medium \| large \| massive` | Relative frame size                                                                              |
@@ -2326,13 +2327,35 @@ three fields are built around.
   unrecorded. Both spellings of `died` mean dead.
 - **`age` is optional and is an override.** Written, it wins over anything the
   dates say. Unwritten beside a dated `born`, it is the age that follows from
-  the date. Unwritten beside `born: unknown` or an absent `born`, the age is
-  unknown.
+  the date and the package's declared present — see below. Unwritten beside
+  `born: unknown` or an absent `born`, the age is unknown.
 
 Most people in a setting do not know their own birth date, so an age beside
 `born: unknown` is an ordinary complete record and not a note working around the
 schema. Where the number is somebody's estimate rather than a fact, write it
-`~34` — the same `~` a date carries.
+`~34` — the same `~` a date carries. The estimate string is kept exactly as
+written; the compiler adds `ageYears` beside it, the plain number with the `~`
+stripped, for anything that needs to sort or filter on the age rather than
+read it.
+
+#### The age a dated `born` computes to
+
+A package states the day its setting stops on `data.present`, on its own
+`world` or `celestial` `place` note — see _What a body states about itself_
+under `type: place`. Against that date, a being with a dated `born` and no
+authored `age` compiles the age it implies: the two dates compared, not the
+two years subtracted, so a birthday that falls later in the year than the
+present counts one less than the years alone would say. A package that
+declares no present computes no age and says nothing about it — the same
+silence a package with no calendar mechanism meets.
+
+**An authored `age` beside a dated `born` is expected to agree with what the
+date computes.** Where it does not, `content-build lint` raises a warning
+naming both values, so a stale age left behind after a `born` was corrected
+does not go unnoticed. The warning is silent beside `born: unknown` or an
+absent `born` — there is nothing there to disagree with — and silent wherever
+the package declares no present, for the same reason no age is computed at
+all.
 
 `birthday:` is the retired spelling of `born:`. Both are read and `born` wins,
 so a note compiles identically either way; the old spelling is reported until

package/engine/base-compiler.mjs

@@ -92,6 +92,10 @@ import { resolveNoteId } from "./note-ids.mjs";
 import { carriesSystemBlock } from "./system-block.mjs";
 import { checkAuthoredSystemData, checkEmittedSystemData } from "./schema-check.mjs";
 import { locateFrontmatterKey } from "./retired-fields.mjs";
+// A being's computed `age`, filled in against the package's own declared
+// present before this pass reads `data:` for anything else — see
+// `engine/being-age.mjs`.
+import { applyComputedBeingAge, presentAmongRecords } from "./being-age.mjs";
 
 /**
  * The tallies one pass accumulates while walking the tree.
@@ -594,6 +598,10 @@ export class BasePackCompiler {
             this.contentDocs = this.corpus.contentDocs;
             this.sqlTables = this.corpus.sqlTables;
         }
+        // The package's declared present, read once from the same corpus — so
+        // a being's computed `age` reaches every compiled document, not only
+        // the content index.
+        this.worldPresent = presentAmongRecords(this.corpus.records);
         this.unresolvedLinks = 0;
     }
 
@@ -1016,6 +1024,7 @@ export class BasePackCompiler {
                 stats.skippedOther++;
                 continue;
             }
+            applyComputedBeingAge(fm, this.worldPresent);
             // The retired frontmatter fields, refused before `selects` so a
             // note is answered whichever pass would have claimed it — and
             // whatever the declared value says.

package/engine/being-age.mjs

@@ -0,0 +1,270 @@
+/*
+ * 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 middle state of `age`: absent beside a dated `born`, it follows from
+ * the date.**
+ *
+ * `age` is a three-state override — authored it wins, absent beside a dated
+ * `born` it is computed, absent beside `born: unknown` or an absent `born` it
+ * stays unknown. This module builds the middle state, which nothing else in
+ * the toolchain does: `born` and `age` are read straight through to every
+ * compiled surface exactly as authored, unless a note's own package states the
+ * day the setting stops.
+ *
+ * ## Where the present comes from
+ *
+ * A world's `present` is a fact about the world, not about a calendar or a
+ * build configuration — it is `data.present` on the package's own `place` note
+ * of `subType: world` (or `celestial`), read through
+ * {@link module:engine/calendar-notes.worldInvariants}. A package with no such
+ * note states no present, computes no age, and says nothing about it: the
+ * absence is silent, exactly as a package that declares no calendar is asked
+ * no calendar questions.
+ *
+ * ## The arithmetic is on two dates, not on two years
+ *
+ * A year subtracted from a year is wrong whenever the birthday has not yet
+ * happened in the present's year — the common shape, not the exception. So
+ * {@link computeAge} compares `born`'s month and day against `present`'s,
+ * **ordinally**, and drops a year where born's has not yet arrived. That
+ * ordinal comparison needs no month-length table: two dates written in one
+ * calendar order the same way whether the comparison counts days-of-year
+ * through the calendar's month lengths or simply reads `(month, day)` as a
+ * pair, because a calendar's months keep the same lengths every year — this
+ * package's calendars carry no leap rule (`calendar-notes.mjs`'s
+ * `years.leapYear` is always `null`). So the comparison is calendar-agnostic
+ * by construction, and correct for a twelve-month calendar of thirty-day
+ * months, a ten-month calendar, or none at all — a bare `born` with no era
+ * names no calendar to consult in the first place.
+ *
+ * ## `~` follows the convention {@link module:engine/note-dates} sets
+ *
+ * A date's `~` marks the value approximate without changing what it parses to,
+ * so a renderer keeps the authored text and a comparison still has a number.
+ * {@link parseAgeMagnitude} draws the same distinction for `age` — the tilde,
+ * the magnitude — without routing through {@link module:engine/note-dates}
+ * itself: `age` is a plain count of years, not a date, so it has no month, no
+ * day, no era, and — unlike a date — no refusal of `0`. Reusing the date
+ * grammar's month/day/era machinery here would accept an age nothing about the
+ * field means, and refuse the one age an infant can have.
+ *
+ * @module
+ */
+
+import { worldInvariants } from "./calendar-notes.mjs";
+import { positionOfFrontmatterPath } from "./diagnostics.mjs";
+import { parseNoteDate } from "./note-dates.mjs";
+// `born`'s retired spelling is still read during its retirement window — see
+// `docs/content-format.md`'s "`birthday:` is the retired spelling of `born:`"
+// — so a being on the old spelling still computes an age rather than reading
+// as never born.
+import { readAliasedField } from "./retired-fields.mjs";
+
+/** The note type this module's derivation and check apply to. */
+const BEING_TYPE = "being";
+
+/** Whether a note's type — read either directly or through its frontmatter — is `being`. */
+function isBeingType(type) {
+    return String(type ?? "").toLowerCase() === BEING_TYPE;
+}
+
+/** The `data:` map of a note's frontmatter, or `undefined` where there is none to read. */
+function dataOf(fm) {
+    const data = fm?.data;
+    return data && typeof data === "object" && !Array.isArray(data) ? data : undefined;
+}
+
+/**
+ * `~34`'s tilde and its magnitude — the same distinction a date's `~` draws,
+ * asked of a plain count of years rather than of a calendar date.
+ *
+ * A whole, non-negative number only: an age is never fractional and never
+ * before an epoch, so neither a date's sign nor its month/day/era grammar
+ * belongs here.
+ *
+ * @type {RegExp}
+ */
+const AGE_MAGNITUDE_PATTERN = /^(~)?\s*(\d+)\s*$/;
+
+/**
+ * Parse an authored `age` into its estimate mark and its magnitude.
+ *
+ * @param {unknown} raw - The authored value — `34`, `"34"` or `"~34"`.
+ * @returns {{approximate: boolean, value: number}|null} The parts, or `null`
+ *   for a value that does not read as a plain count of years.
+ */
+export function parseAgeMagnitude(raw) {
+    if (typeof raw !== "number" && typeof raw !== "string") return null;
+    const match = AGE_MAGNITUDE_PATTERN.exec(String(raw).trim());
+    if (!match) return null;
+    const [, tilde, digits] = match;
+    return { approximate: tilde === "~", value: Number(digits) };
+}
+
+/**
+ * The age two dates imply, in whole years, computed from the dates themselves
+ * rather than from the years alone.
+ *
+ * @param {unknown} bornRaw - The being's authored `born`, or `undefined`/`null`
+ *   where it wrote none.
+ * @param {unknown} presentRaw - The package's `data.present`, as
+ *   {@link module:engine/calendar-notes.worldInvariants} read it, or
+ *   `undefined`/`null` where the package states none.
+ * @returns {number|null} The age, or `null` where `born` is `unknown` or
+ *   absent, where no present is declared, or where either date fails to parse.
+ */
+export function computeAge(bornRaw, presentRaw) {
+    if (bornRaw === undefined || bornRaw === null) return null;
+    if (presentRaw === undefined || presentRaw === null) return null;
+
+    const born = parseNoteDate(bornRaw, { allowUnknown: true }).date;
+    if (!born || !born.known || born.canonicalYear == null) return null;
+
+    const present = parseNoteDate(presentRaw, { allowUnknown: false }).date;
+    if (!present || !present.known || present.canonicalYear == null) return null;
+
+    // Ordinal position within the year, day of year or not: see the module
+    // doc for why `(month, day)` alone orders correctly here. Missing month or
+    // day reads as the year's first day — the earliest a birthday could fall —
+    // so a `born` written to less precision than `present` never counts as
+    // "not yet happened".
+    const bornOrdinal = (born.month ?? 1) * 100 + (born.day ?? 1);
+    const presentOrdinal = (present.month ?? 1) * 100 + (present.day ?? 1);
+    const notYetHappened = bornOrdinal > presentOrdinal;
+
+    return present.canonicalYear - born.canonicalYear - (notYetHappened ? 1 : 0);
+}
+
+/**
+ * Fill in a being's computed `age`, and the numeric companion an estimate
+ * carries beside it — mutating the frontmatter object handed in, never a file
+ * on disk.
+ *
+ * Every caller holds a frontmatter object that was parsed fresh from a note's
+ * text for its own pass — the content index, a compiled document, a rendered
+ * page — and none of those objects round-trips back to the `.md` file. So
+ * patching `data.age` in place here is exactly as safe as reading it, and
+ * reaches every surface that reads `data:` after this runs, with the note
+ * itself untouched.
+ *
+ * @param {object} fm - A note's frontmatter, as freshly parsed.
+ * @param {unknown} presentRaw - The package's declared present, or
+ *   `undefined`/`null` where it states none.
+ * @returns {void}
+ */
+export function applyComputedBeingAge(fm, presentRaw) {
+    if (!isBeingType(fm?.type)) return;
+    const data = dataOf(fm);
+    if (!data) return;
+
+    const authored = data.age;
+    if (authored !== undefined && authored !== null && authored !== "") {
+        // An authored age always wins — the value itself is never touched.
+        // `~34` is kept exactly as written; its normalised number is added
+        // beside it, the way a date's `canonicalYear` sits beside its `text`.
+        const parsed = parseAgeMagnitude(authored);
+        if (parsed?.approximate) data.ageYears = parsed.value;
+        return;
+    }
+
+    const born = readAliasedField(fm, "born", { inData: true });
+    const computed = computeAge(born, presentRaw);
+    if (computed !== null) data.age = computed;
+}
+
+/**
+ * A being's `data.present`, read from every `place` note a batch of records or
+ * frontmatter objects carries.
+ *
+ * Two shapes reach this by way of two thin adapters, because the callers that
+ * need a present hold their notes two different ways: a flat index record
+ * (`type` and `data` at the top level) and a raw walk's `{frontmatter}` pair.
+ * Neither shape is the `{fm, type}` pair {@link worldInvariants} reads, so each
+ * adapter states the one conversion its caller needs rather than asking every
+ * caller to know it.
+ *
+ * @param {readonly object[]|undefined} records - Flat index records — a
+ *   content-index record, or anything else spreading a note's frontmatter to
+ *   its own top level.
+ * @returns {unknown} The present, or `null` where no `place` note in the batch
+ *   declares one.
+ */
+export function presentAmongRecords(records) {
+    return worldInvariants({
+        notes: (records ?? []).map((record) => ({ fm: record, type: record?.type })),
+    }).present;
+}
+
+/**
+ * The present read from a batch of raw frontmatter objects.
+ *
+ * @param {readonly (object|null|undefined)[]|undefined} frontmatters - One
+ *   entry per note walked, as parsed — never a record.
+ * @returns {unknown} The present, or `null` where none is declared.
+ */
+export function presentAmongFrontmatters(frontmatters) {
+    return worldInvariants({
+        notes: (frontmatters ?? []).map((fm) => ({ fm, type: fm?.type })),
+    }).present;
+}
+
+/**
+ * Check a being's authored `age` against what `born` and the package's present
+ * compute.
+ *
+ * Registered as `being`'s whole-note `check` in `note-vocabulary.mjs`, run the
+ * way `checkPlace` and `checkCalendarNote` are — beside every other check the
+ * closed `data:` container earns, with the same `index`.
+ *
+ * Two silences, both deliberate: beside `born: unknown` or an absent `born`
+ * there is nothing to disagree with, and a package that declares no present
+ * computes no age to disagree with either — both cases are read by
+ * {@link computeAge} returning `null`, and neither says a word.
+ *
+ * @param {object} note - The note, as the link index hands it over —
+ *   {@link module:engine/calendar-notes.worldInvariants}'s `index.notes` shape.
+ * @param {object} [opts]
+ * @param {object} [opts.index] - The link index, holding the package's `place`
+ *   notes. Its absence skips the check, the way a reference check with no
+ *   index skips reporting every reference as dead.
+ * @returns {object[]} Findings — at most one `warning`, naming both values.
+ */
+export function checkBeingAge(note, { index } = {}) {
+    if (!isBeingType(note?.type ?? note?.fm?.type)) return [];
+    const data = dataOf(note?.fm);
+    if (!data) return [];
+
+    const bornRaw = readAliasedField(note?.fm, "born", { inData: true });
+    const ageRaw = data.age;
+    if (ageRaw === undefined || ageRaw === null || ageRaw === "") return [];
+    if (!index) return [];
+
+    const present = worldInvariants(index).present;
+    const computed = computeAge(bornRaw, present);
+    if (computed === null) return [];
+
+    const authored = parseAgeMagnitude(ageRaw);
+    if (!authored || authored.value === computed) return [];
+
+    return [
+        {
+            file: note.file,
+            ...positionOfFrontmatterPath(note.raw ?? "", ["data", "age"], { key: true }),
+            severity: "warning",
+            message:
+                `\`data.age: ${JSON.stringify(ageRaw)}\` disagrees with ` +
+                `\`data.born: ${JSON.stringify(bornRaw)}\`, which computes to ${computed}`,
+        },
+    ];
+}

package/engine/content-index.mjs

@@ -137,6 +137,10 @@ import {
     sortKeysDeep,
 } from "./index-records.mjs";
 import { isDraftNote } from "./note-vocabulary.mjs";
+// A being's computed `age` — the middle state between an authored override and
+// an unknown one — filled in against the package's own declared present before
+// a record is built, so the index carries it without the note being written to.
+import { applyComputedBeingAge, presentAmongFrontmatters } from "./being-age.mjs";
 
 export {
     authoredFrontmatter,
@@ -606,10 +610,20 @@ export function collectContentIndex(
     // tree to walk and the index is its asset records. The caller decides
     // whether an absent tree is a mistake; by the time the walk is reached it
     // is simply a package with nothing to compile.
-    const notes = fs.existsSync(contentBase) ? walkMarkdownTree(contentBase, walkOpts) : [];
+    // Materialised rather than consumed lazily: the present is read from this
+    // same walk before the loop below reads it a second time, and
+    // `walkMarkdownTree` is a generator — a single-use one, exhausted the
+    // moment anything else iterates it first.
+    const notes = fs.existsSync(contentBase) ? [...walkMarkdownTree(contentBase, walkOpts)] : [];
+
+    // The package's declared present, read once from whichever `place` note in
+    // this same walk states one — the whole tree is already in memory, so no
+    // second read is needed to answer a question about all of it.
+    const present = presentAmongFrontmatters(notes.map((n) => n.frontmatter));
 
     for (const { frontmatter, body, bodyLine, absPath } of notes) {
         const fm = frontmatter ?? {};
+        applyComputedBeingAge(fm, present);
         // The id the note's document is filed under, resolved before
         // the record is built so the index publishes the address *and* the id
         // that address derives.

package/engine/index.mjs

@@ -133,6 +133,9 @@ export * as noteDates from "./note-dates.mjs";
 /** Calendars as notes: what one may declare, and the definition emitted from it. */
 export * as calendarNotes from "./calendar-notes.mjs";
 
+/** A being's `age`, absent beside a dated `born`: the age the date computes to. */
+export * as beingAge from "./being-age.mjs";
+
 /** The one normalisation this build makes: prose to a URL-safe token. */
 export * as contentSlug from "./content-slug.mjs";
 

package/engine/infobox.mjs

@@ -291,6 +291,12 @@ export const NOTE_FIELD_PRESENTATION = Object.freeze({
     // than as six rows of numbers, exactly as the book prototype sets them.
     // Qualified by type, because `weight` is also what a coin weighs.
     "being.age": Object.freeze({ group: "appearance", phrase: (v) => `Age ${v}` }),
+    // The `~` estimate's numeric companion — beside `age` in the index for a
+    // machine to sort or filter on, not a second row for a reader who already
+    // meets it inside the appearance clause.
+    "being.ageYears": Object.freeze({
+        withheld: "the `age` row's own machinery, not a second fact about the subject",
+    }),
     "being.height": Object.freeze({ group: "appearance", phrase: heightPhrase }),
     "being.weight": Object.freeze({ group: "appearance", phrase: weightPhrase }),
     "being.frame": Object.freeze({ group: "appearance", phrase: (v) => `${v} frame` }),

package/engine/note-vocabulary.mjs

@@ -91,6 +91,10 @@ import {
     checkCalendarNote,
     checkWorldFacts,
 } from "./calendar-notes.mjs";
+// Whether a being's authored `age` disagrees with what `born` and the
+// package's declared present compute — the closed `data:` container's own
+// question, asked the way `checkPlace` and `checkCalendarNote` are.
+import { checkBeingAge } from "./being-age.mjs";
 import { checkHeld } from "./holdings.mjs";
 import { checkCitedPopulations, checkPopulation } from "./populations.mjs";
 // What trade a settlement supports — the scale and the check that holds a
@@ -587,6 +591,9 @@ export const NOTE_VOCABULARY = Object.freeze({
         // lands with. Declared open until it does, because inventing the
         // values here would put a second, weaker answer beside the real one.
         subTypes: null,
+        // Whether an authored `age` disagrees with what `born` and the
+        // package's declared present compute — see `engine/being-age.mjs`.
+        check: checkBeingAge,
         data: Object.freeze([
             TOKEN_ICON,
             TEMPLATE_PRIORITY,
@@ -634,6 +641,13 @@ export const NOTE_VOCABULARY = Object.freeze({
                     "for an estimate. Unstated beside a dated `born` it is computed; unstated " +
                     "beside an unknown or absent `born` the age is unknown.",
             },
+            {
+                name: "ageYears",
+                ...NUM,
+                describe:
+                    "Written by the compiler beside an `age` estimate — the `~` stripped, " +
+                    "the magnitude alone. A note never authors this.",
+            },
             { name: "height", ...NUM, describe: "Height in metres." },
             { name: "weight", ...NUM, describe: "Weight in kilograms." },
             {

package/engine/site-build.mjs

@@ -72,6 +72,9 @@ import { routerFor } from "./pack-router.mjs";
 import { searchableFrontmatter } from "./note-package.mjs";
 // The corpus, from the one pass that derives it.
 import { indexRecordsFor } from "./content-index.mjs";
+// A being's computed `age` — see `engine/being-age.mjs`. `pdf-build.mjs`
+// reuses `collectContentPages`'s pages, so wiring it here reaches the book too.
+import { applyComputedBeingAge, presentAmongRecords } from "./being-age.mjs";
 import { isNoteRecord, noteFile } from "./index-records.mjs";
 // The one statement of what an empty body means, shared with the index.
 import { isStubNote } from "./note-state.mjs";
@@ -166,9 +169,22 @@ export function collectContentPages(contentBase, ctx) {
     const addressFindings = [];
     const fmLinkFindings = [];
 
+    // The package's declared present, read once from the same corpus the site
+    // and the PDF share — see `engine/being-age.mjs`. `pdf-build.mjs` reaches
+    // this through the pages this function returns, so one call covers both.
+    const present = presentAmongRecords(
+        ctx.records ??
+            indexRecordsFor({
+                contentBase,
+                config: ctx.config,
+                skipDirectories: ctx.skipDirectories,
+            }),
+    );
+
     for (const file of siteCorpusFiles(contentBase, ctx)) {
         const note = readNote(file);
         if (!note) continue;
+        applyComputedBeingAge(note.fm, present);
         const { fm, body } = note;
         // The configuration's, never a note's: `package:` is retired, so every
         // note in the tree belongs to the package this repository compiles.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.9.0",
+    "version": "22.9.1",
     "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/engine/base-compiler.d.mts

@@ -378,6 +378,7 @@ export class BasePackCompiler {
     linkIndex: any;
     contentDocs: any;
     sqlTables: any;
+    worldPresent: unknown;
     /**
      * The body {@link BasePackCompiler#buildEntry} receives.
      *

package/types/engine/being-age.d.mts

@@ -0,0 +1,92 @@
+/**
+ * Parse an authored `age` into its estimate mark and its magnitude.
+ *
+ * @param {unknown} raw - The authored value — `34`, `"34"` or `"~34"`.
+ * @returns {{approximate: boolean, value: number}|null} The parts, or `null`
+ *   for a value that does not read as a plain count of years.
+ */
+export function parseAgeMagnitude(raw: unknown): {
+    approximate: boolean;
+    value: number;
+} | null;
+/**
+ * The age two dates imply, in whole years, computed from the dates themselves
+ * rather than from the years alone.
+ *
+ * @param {unknown} bornRaw - The being's authored `born`, or `undefined`/`null`
+ *   where it wrote none.
+ * @param {unknown} presentRaw - The package's `data.present`, as
+ *   {@link module:engine/calendar-notes.worldInvariants} read it, or
+ *   `undefined`/`null` where the package states none.
+ * @returns {number|null} The age, or `null` where `born` is `unknown` or
+ *   absent, where no present is declared, or where either date fails to parse.
+ */
+export function computeAge(bornRaw: unknown, presentRaw: unknown): number | null;
+/**
+ * Fill in a being's computed `age`, and the numeric companion an estimate
+ * carries beside it — mutating the frontmatter object handed in, never a file
+ * on disk.
+ *
+ * Every caller holds a frontmatter object that was parsed fresh from a note's
+ * text for its own pass — the content index, a compiled document, a rendered
+ * page — and none of those objects round-trips back to the `.md` file. So
+ * patching `data.age` in place here is exactly as safe as reading it, and
+ * reaches every surface that reads `data:` after this runs, with the note
+ * itself untouched.
+ *
+ * @param {object} fm - A note's frontmatter, as freshly parsed.
+ * @param {unknown} presentRaw - The package's declared present, or
+ *   `undefined`/`null` where it states none.
+ * @returns {void}
+ */
+export function applyComputedBeingAge(fm: object, presentRaw: unknown): void;
+/**
+ * A being's `data.present`, read from every `place` note a batch of records or
+ * frontmatter objects carries.
+ *
+ * Two shapes reach this by way of two thin adapters, because the callers that
+ * need a present hold their notes two different ways: a flat index record
+ * (`type` and `data` at the top level) and a raw walk's `{frontmatter}` pair.
+ * Neither shape is the `{fm, type}` pair {@link worldInvariants} reads, so each
+ * adapter states the one conversion its caller needs rather than asking every
+ * caller to know it.
+ *
+ * @param {readonly object[]|undefined} records - Flat index records — a
+ *   content-index record, or anything else spreading a note's frontmatter to
+ *   its own top level.
+ * @returns {unknown} The present, or `null` where no `place` note in the batch
+ *   declares one.
+ */
+export function presentAmongRecords(records: readonly object[] | undefined): unknown;
+/**
+ * The present read from a batch of raw frontmatter objects.
+ *
+ * @param {readonly (object|null|undefined)[]|undefined} frontmatters - One
+ *   entry per note walked, as parsed — never a record.
+ * @returns {unknown} The present, or `null` where none is declared.
+ */
+export function presentAmongFrontmatters(frontmatters: readonly (object | null | undefined)[] | undefined): unknown;
+/**
+ * Check a being's authored `age` against what `born` and the package's present
+ * compute.
+ *
+ * Registered as `being`'s whole-note `check` in `note-vocabulary.mjs`, run the
+ * way `checkPlace` and `checkCalendarNote` are — beside every other check the
+ * closed `data:` container earns, with the same `index`.
+ *
+ * Two silences, both deliberate: beside `born: unknown` or an absent `born`
+ * there is nothing to disagree with, and a package that declares no present
+ * computes no age to disagree with either — both cases are read by
+ * {@link computeAge} returning `null`, and neither says a word.
+ *
+ * @param {object} note - The note, as the link index hands it over —
+ *   {@link module:engine/calendar-notes.worldInvariants}'s `index.notes` shape.
+ * @param {object} [opts]
+ * @param {object} [opts.index] - The link index, holding the package's `place`
+ *   notes. Its absence skips the check, the way a reference check with no
+ *   index skips reporting every reference as dead.
+ * @returns {object[]} Findings — at most one `warning`, naming both values.
+ */
+export function checkBeingAge(note: object, { index }?: {
+    index?: object | undefined;
+}): object[];

package/types/engine/index.d.mts

@@ -32,6 +32,7 @@ export * as systems from "./systems.mjs";
 export * as calendars from "./calendars.mjs";
 export * as noteDates from "./note-dates.mjs";
 export * as calendarNotes from "./calendar-notes.mjs";
+export * as beingAge from "./being-age.mjs";
 export * as contentSlug from "./content-slug.mjs";
 export * as contentAddress from "./content-address.mjs";
 export * as subtypeRegistry from "./subtype-registry.mjs";