@heroiclands/package-build 22.6.0 → 22.8.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @heroiclands/package-build
 
+## 22.8.0
+
+### Minor Changes
+
+**A being's dates**
+
+- A being says when it was born and when it died: `born:` takes over from `birthday:`, and `died:` sits beside it.
+- Either date may read `unknown` where it was never recorded; an absent `born` says the being was never born, and an absent `died` says it is alive.
+- `age:` is optional, and is an override — write it only where the number should win over the date, and write it `~34` where it is somebody's estimate.
+- A note still writing `birthday:` compiles identically and is told once what to write instead.
+- A profile reads its two dates ahead of the line describing the being's appearance.
+
+### Patch Changes
+
+**Dates**
+
+- A package can state how its year is divided — how many months, and how many
+  days to a month — and the date it treats as the present.
+- A refused `BF`/`AF` date now states the replacement rule instead of a computed value, which was wrong for `AF`.
+
+**The book**
+
+- A numbered or bulleted point whose text runs to more than one paragraph now
+  sets every paragraph flush under the point, so it reads as one block hanging
+  off its number instead of a stray indented paragraph beneath it.
+
+**A draft entry's notice**
+
+- The sentence sets in italic, with `Draft.` in bold ahead of it, on the page, in a journal entry and on an actor's dossier alike: the entry speaking about its own state rather than about the world.
+- In the book the notice's mark sits in a column of its own, so a sentence that runs to two lines sets both of them clear of it.
+- The mark is a filled disc with the exclamation knocked out of it, in the book's accent.
+- The sentence sets at the size, face and ink of the entry's prose; the rule down its edge and the mark are what set it apart.
+
+## 22.7.0
+
+### Minor Changes
+
+**Draft notes say so.** A note tagged `draft` states that it is unfinished and
+that nothing in it is settled, at the head of its compendium entry, on the
+character sheet a referee opens, and on its page in the book. A finished note
+carries nothing.
+
 ## 22.6.0
 
 ### Minor Changes

package/CONTENT.md

@@ -1113,6 +1113,11 @@ page, no address and no link target. A note with a body and the `draft` tag is a
 **draft**, and one with a body and no tag is **full**.
 `docs/content-format.md` states the rule; this is what the lint does with it.
 
+A draft says so on every surface it reaches — its journal entry, the Actor a
+being compiles into, its page in the book — in one sentence at the head of the
+entry, above the infobox and the prose. A stub says nothing anywhere, because it
+publishes nothing to say it on.
+
 **A document that would be empty is not created**, and the index then names no
 artefact — `uuid`, `path` and `address` are `null`. An unwritten note still
 compiles every document derived from `data:`, so an arcane talent is still its

package/content-config.mjs

@@ -76,6 +76,7 @@ import { EMPTY_ICON_REGISTRY, checkIconRegistry } from "./engine/content-icons.m
 import { MAP_TYPES, NO_PACK, PACK_BY_TYPE } from "./engine/ids.mjs";
 import { ACTOR_TYPES } from "./engine/subtype-registry.mjs";
 import { NOTE_VOCABULARY } from "./engine/note-vocabulary.mjs";
+import { UNKNOWN_DATE, parseNoteDate } from "./engine/note-dates.mjs";
 
 /**
  * What kind of package this is.
@@ -725,6 +726,10 @@ export function publishesContentPages(config) {
  * @property {readonly string[]} packDirectories  Derived: every pack directory
  *                                     the build produces, in compile order —
  *                                     each pack followed by its companions.
+ * @property {Readonly<{months: number|null, monthDays: number|null, present: string|null}>} calendar
+ *                                     How this package's year is divided, and
+ *                                     the date it calls the present. Every
+ *                                     value `null` when none is declared.
  * @property {Readonly<PackageBuildSection>} packageBuild  Passed through
  *                                     frozen, uninterpreted. `{}` when absent.
  * @property {Readonly<DocsSpec>} docs   Frozen; `{}` when absent.
@@ -754,11 +759,13 @@ const CONFIG_KEYS = [
     "relationships",
     "systems",
     "requiresSystem",
+    "calendar",
     "packageBuild",
     "publish",
     "changelog",
 ];
 const SYSTEM_KEYS = ["manifest", "compatibility"];
+const CALENDAR_KEYS = ["months", "monthDays", "present"];
 const COMPATIBILITY_KEYS = ["minimum", "verified"];
 const DOCS_KEYS = ["itemFields"];
 const CHANGELOG_KEYS = ["labels"];
@@ -2070,6 +2077,76 @@ function normalizeRequiresSystem(value) {
     return requireNonEmptyString(value, "requiresSystem");
 }
 
+/**
+ * How this package's year is divided, and the date it calls the present.
+ *
+ * **Nothing here is about which people count from what.** A reckoning is an
+ * era, declared by the affiliation that proclaimed it, and its epoch is the
+ * `start` written on that note — so the only things configuration states are
+ * the ones no note could.
+ *
+ * `months` and `monthDays` bound a written month and day. Both are optional,
+ * and an absent one is checked against nothing: a toolchain that assumed a
+ * Gregorian year here would refuse `667/2/30`, an ordinary date in a year of
+ * twelve thirty-day months. One subdivision to a package — an era moves where
+ * year 1 sits, it does not divide the year differently.
+ *
+ * `present` is the date the package computes an age against, written in the
+ * same grammar a note's dates use, so a package whose present is best said in
+ * an era says it that way. A package that states none computes no age, which
+ * is the right answer for a corpus that has no present.
+ *
+ * @param {unknown} value - The declared `calendar:` mapping.
+ * @returns {Readonly<{months: number|null, monthDays: number|null, present: string|null}>}
+ *   Frozen; every value `null` when absent.
+ */
+function normalizeCalendar(value) {
+    if (value === undefined || value === null) {
+        return Object.freeze({ months: null, monthDays: null, present: null });
+    }
+    if (!isPlainObject(value)) fail("calendar", "must be a mapping");
+    const input = /** @type {Record<string, unknown>} */ (value);
+    rejectUnknownKeys(input, CALENDAR_KEYS, "calendar.");
+
+    const bound = (key) => {
+        const held = input[key];
+        if (held === undefined || held === null) return null;
+        if (!Number.isInteger(held) || /** @type {number} */ (held) < 1) {
+            fail(`calendar.${key}`, "must be a positive integer");
+        }
+        return /** @type {number} */ (held);
+    };
+    const months = bound("months");
+    const monthDays = bound("monthDays");
+
+    // Read through the parser the notes use rather than a second grammar, and
+    // against this package's own bounds — a present outside the year it
+    // declares is the one date nothing downstream would report.
+    let present = null;
+    if (input.present !== undefined && input.present !== null) {
+        if (typeof input.present !== "string" && typeof input.present !== "number") {
+            fail("calendar.present", "must be a date written as a string");
+        }
+        if (String(input.present).trim() === UNKNOWN_DATE) {
+            fail(
+                "calendar.present",
+                `must be a date — a package that states no present computes no age, ` +
+                    `so leave the key out rather than writing \`${UNKNOWN_DATE}\``,
+            );
+        }
+        const { date, findings } = parseNoteDate(input.present, {
+            calendar: { months, monthDays },
+            allowUnknown: false,
+        });
+        const refused = findings.find((finding) => finding.severity === "error");
+        if (refused)
+            fail("calendar.present", `is not a date this package can read — ${refused.message}`);
+        present = /** @type {{text: string}} */ (date).text;
+    }
+
+    return Object.freeze({ months, monthDays, present });
+}
+
 /**
  * Validate the declared relationships.
  *
@@ -2801,6 +2878,7 @@ export function defineConfig(config) {
         relationships: normalizeRelationships(input.relationships),
         systems,
         requiresSystem,
+        calendar: normalizeCalendar(input.calendar),
         packageBuild: normalizePackageBuild(input.packageBuild),
         publish: normalizePublish(input.publish),
         changelog: normalizeChangelog(input.changelog),

package/docs/api.md

@@ -427,6 +427,23 @@ The three states of a note — **stub**, **draft**, **full** — and the one obs
 | `placeholderBody`     | `placeholderBody(body)`                     | `Array<{phrase: string, line: number}>` | finding a body that reduces to nothing but placeholders, which is an abandoned draft rather than a stub                    |
 | `bodyWordCount`       | `bodyWordCount(body)`                       | `number`                                | counting the prose a reader meets, with a wikilink counting as the one word it renders                                     |
 
+### `engine.draftNotice`
+
+What a draft note says about itself, in one sentence, on every surface it reaches. The words are stated once and each renderer composes its own markup around them, so a reader meeting the note on a page, in a compendium and in the book meets one statement. The mark is a notice rather than a hazard, and the book draws it rather than setting a glyph, because a face missing one is silent in Typst.
+
+| Export                    | Signature                            | Returns  | Use it when                                                                        |
+| ------------------------- | ------------------------------------ | -------- | ---------------------------------------------------------------------------------- |
+| `DRAFT_NOTICE`            | `const DRAFT_NOTICE`                 | `string` | reading the sentence itself, which is the floor every surface degrades to          |
+| `DRAFT_NOTICE_LABEL`      | `const DRAFT_NOTICE_LABEL`           | `string` | reading the label that opens the notice                                            |
+| `DRAFT_NOTICE_ICON`       | `const DRAFT_NOTICE_ICON`            | `string` | naming the Font Awesome mark the HTML surfaces draw                                |
+| `DRAFT_NOTICE_CLASS`      | `const DRAFT_NOTICE_CLASS`           | `string` | styling the HTML notice from a package that wants to                               |
+| `BOOK_DRAFT_NOTICE`       | `const BOOK_DRAFT_NOTICE`            | `string` | naming the Typst function the book's notice calls                                  |
+| `draftNoticeHtml`         | `draftNoticeHtml()`                  | `string` | drawing the notice for a JournalEntry page or an Actor's prose field               |
+| `draftNoticeFor`          | `draftNoticeFor(frontmatter)`        | `string` | asking whether a note has earned a notice, which is the one place the tag is asked |
+| `withDraftNotice`         | `withDraftNotice(frontmatter, html)` | `string` | leading a system's own prose field with the notice where one is due                |
+| `draftNoticeTypst`        | `draftNoticeTypst()`                 | `string` | drawing the notice for a leaf of the book                                          |
+| `bookDraftNoticePreamble` | `bookDraftNoticePreamble()`          | `string` | emitting the Typst definition the book's notice is drawn by                        |
+
 ### `engine.stubLint`
 
 An empty body must be deliberate. Four rules hold the state honest — a stub states what it is, a stub is not tagged `draft`, a body that renders to nothing is an abandoned draft, and a short unmarked body is asked whether it forgot its marker — and two reports say what the rules cannot decide.
@@ -587,6 +604,28 @@ The closed registry of system ids, and the `none` that stands for no system at a
 | `assertSystemSegment`  | `assertSystemSegment(value, where)`    | `string` — the value, unchanged | refusing a value the `<system>` segment may not hold, validating inline                      |
 | `assertSystemCharset`  | `assertSystemCharset(segments, where)` | throws                          | refusing a registry declaration whose id could not be an address segment                     |
 
+### `engine.calendars`
+
+The axis every date normalises onto, and the one function that puts a reckoning on it. A reckoning is an **era** declared by the affiliation that proclaimed it, and its epoch is the `start` written on that note — nothing is registered in configuration. The conversion is piecewise on the sign, because the authored numbering has no year zero while the normalised value does: authored `-1` is `0`, and `-1` and `1` are adjacent.
+
+| Export              | Signature                       | Returns                                       | Use it when                                                                     |
+| ------------------- | ------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------- |
+| `CANONICAL_EPOCH`   | `const CANONICAL_EPOCH`         | —                                             | naming where the canonical axis's own year 1 sits                               |
+| `canonicalYear`     | `canonicalYear(year, epoch?)`   | `number` — the signed year on the axis        | converting a year written in one reckoning to the number everything compares on |
+| `dateSortKey`       | `dateSortKey(year, month, day)` | `number`                                      | ordering mixed-precision dates against a single number                          |
+| `calendarStructure` | `calendarStructure(calendar)`   | `{months, monthDays}` — `null` where unstated | reading the month bounds a package declares, before phrasing a finding          |
+
+### `engine.noteDates`
+
+A date on a note is one authored string — `[~][-]YYYY[/MM[/DD]] [<affiliation shortcode>.<era shortcode>]` — and every field holding one parses through a single grammar into a single record. Print `text`, order on `sort`, do arithmetic on `canonicalYear`. A bare value sits on the canonical axis and carries `era: null`; one naming an era carries the qualifier and no `canonicalYear` or `sort` keys at all until the era is resolved against the corpus. The literal `unknown` parses to the same record with the year half empty, carrying a null `sort` and a null `canonicalYear`, so nothing can order it to one end of a list.
+
+| Export                  | Signature                       | Returns                                            | Use it when                                                   |
+| ----------------------- | ------------------------------- | -------------------------------------------------- | ------------------------------------------------------------- |
+| `UNKNOWN_DATE`          | `const UNKNOWN_DATE`            | —                                                  | naming the literal that says a date is not recorded           |
+| `NOTE_DATE_PATTERN`     | `const NOTE_DATE_PATTERN`       | —                                                  | matching the date grammar directly                            |
+| `ERA_QUALIFIER_PATTERN` | `const ERA_QUALIFIER_PATTERN`   | —                                                  | checking that a string is an era qualifier a date could carry |
+| `parseNoteDate`         | `parseNoteDate(value, options)` | `{date, findings}` — `date` is `null` when refused | reading a note's authored date, with every finding it earned  |
+
 ### `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/configuration.md

@@ -48,7 +48,7 @@ around its own evaluation.
 
 ### Quick reference
 
-21 top-level keys. `rootDir` is not one of them — a data configuration never
+22 top-level keys. `rootDir` is not one of them — a data configuration never
 writes it — and is documented under [Derived values](#derived-values) instead,
 alongside `foundryPackage`, `homepage`, `author` and `itemBuilders`, whose
 data-configuration behaviour is also derivation rather than ordinary
@@ -74,13 +74,14 @@ authoring.
 | [`relationships`](#relationships)           | object                                                                     | no; refused in a `documentation` package                                                           | `{}`                                        |
 | [`systems`](#systems)                       | object                                                                     | no; refused in a `documentation` package                                                           | `{}`                                        |
 | [`requiresSystem`](#requiressystem)         | string                                                                     | no; refused in a `documentation` package                                                           | `null`                                      |
+| [`calendar`](#calendar)                     | object                                                                     | no                                                                                                 | no bounds, no present                       |
 | [`packageBuild`](#the-packagebuild-section) | object                                                                     | no                                                                                                 | `{}`                                        |
 | [`publish`](#publish)                       | object                                                                     | no; **required**, with `site: content`, in a `documentation` package                               | `{site: "homepage", address: {prefix: ""}}` |
 | [`changelog`](#changelog)                   | object                                                                     | no                                                                                                 | `{labels: null}`                            |
 
 Any key outside this list is refused:
 
-> `` `<key>` is not a recognized option (expected one of: rootDir, contentPackage, foundryPackage, homepage, author, packageKind, stats, itemBuilders, paths, skipDirectories, icons, packs, docs, site, pdf, compatibility, relationships, systems, requiresSystem, packageBuild, publish, changelog). ``
+> `` `<key>` is not a recognized option (expected one of: rootDir, contentPackage, foundryPackage, homepage, author, packageKind, stats, itemBuilders, paths, skipDirectories, icons, packs, docs, site, pdf, compatibility, relationships, systems, requiresSystem, calendar, packageBuild, publish, changelog). ``
 
 (`rootDir` appears in that list because it is a key `defineConfig` itself
 accepts — an `.mjs` configuration authors it directly. A YAML configuration
@@ -290,7 +291,7 @@ Unlike the first three, authoring `itemBuilders` is not an error — it is
 
 ---
 
-## The 21 keys
+## The 22 keys
 
 ### `contentPackage`
 
@@ -1297,6 +1298,59 @@ With one, naming what it does declare instead:
 
 > ``package-build config: `requiresSystem` must be a non-empty string.``
 
+### `calendar`
+
+**Type:** object · **Optional** · default: no bounds and no present.
+
+How this package's year is divided, and the date it calls the present:
+
+```yaml
+calendar:
+  months: 12
+  monthDays: 30
+  present: 720/6/19
+```
+
+**Nothing here is about which people count from what.** A reckoning is an
+**era**, declared by the affiliation that proclaimed it, and its epoch is the
+`start` written on that note — so the only things this block states are the ones
+no note could.
+
+| Key (under `calendar`) | Type             | Required | Default |
+| ---------------------- | ---------------- | -------- | ------- |
+| `calendar.months`      | positive integer | no       | `null`  |
+| `calendar.monthDays`   | positive integer | no       | `null`  |
+| `calendar.present`     | date string      | no       | `null`  |
+
+`months` and `monthDays` bound a written month and day. **Both are optional, and
+an absent one is checked against nothing** — a year of twelve thirty-day months
+is as ordinary here as a Gregorian one, so the bound is declared or it is not
+applied. One subdivision to a package: an era moves where year 1 sits, it does
+not divide the year differently.
+
+`present` is the date an age is computed against. It is written in the same
+grammar a note's dates use — `[~][-]YYYY[/MM[/DD]] [<affiliation shortcode>.<era
+shortcode>]` — so a package whose present is best said in an era says it that
+way, and one that states no present computes no age at all.
+
+An age is a function of two **dates**, not two years: subtracting years alone
+reds every note whose birthday falls later in the year than the present date, so
+the day is part of what is declared.
+
+> ``package-build config: `calendar` must be a mapping.``
+
+> ``package-build config: `calendar.months` must be a positive integer.``
+
+> ``package-build config: `calendar.monthDays` must be a positive integer.``
+
+> ``package-build config: `calendar.present` must be a date written as a string.``
+
+> ``package-build config: `calendar.present` must be a date — a package that states no present computes no age, so leave the key out rather than writing `unknown`.``
+
+> ``package-build config: `calendar.present` is not a date this package can read — `720/13/1` writes month 13, and `calendar.months` declares a year of 12.``
+
+> ``package-build config: `calendar.<key>` is not a recognized option (expected one of: months, monthDays, present).``
+
 ### `packageBuild`
 
 Reserved for `@heroiclands/package-build`'s own packaging half — see

package/docs/content-format.md

@@ -320,16 +320,51 @@ is declared, so a near miss is a finding that names what you probably meant.
 | **being kind**      | `being`                | `character`, `creature`                                                                                                                                                                                                                                                                                              |
 | **state**           | any                    | `draft`                                                                                                                                                                                                                                                                                                              |
 
-**`draft` is the one tag either build reads.** A note tagged `draft` exists so a
-link into it is not dead, and a link into it renders marked — as
+**`draft` is the one tag either build reads.** It does two things and nothing
+else: a link _into_ a draft note renders marked, and the note itself states that
+it is unfinished wherever a reader meets it.
+
+A link into it renders as
 `<span class="sohl-draft-link" title="Draft — not yet written">…</span>` in a
 compiled journal and on the website alike, with the appearance supplied by the
-consuming system's stylesheet or the site theme. **Nothing else changes**: the
-note compiles, validates, publishes and resolves exactly as any other, and it
-stays in the packs, in the link manifest and on the site. That is what separates
-the tag from the retired `draft:` field, whose whole effect was to move a note
-from published to unresolvable without saying so — and which is refused, by name,
-if you write it.
+consuming system's stylesheet or the site theme.
+
+The note's own statement is the **draft notice**, and it reads the same on every
+surface:
+
+> **Draft.** This entry is unfinished. What it states may change, and nothing in
+> it is settled.
+
+It leads the entry — above the infobox and above the prose — because a reader
+deciding whether to rely on an entry has to be told before they read it. Where
+it lands:
+
+| Surface      | What carries it                                                      |
+| ------------ | -------------------------------------------------------------------- |
+| JournalEntry | a `blockquote.sohl-draft-notice` at the head of the first page       |
+| Actor        | the dossier the sheet draws — SoHL's `dossier`, HM3's `biography`    |
+| The book     | a drawn mark and a left rule between the entry's plate and its panel |
+| The website  | the theme's own notice, above the infobox rail and the prose         |
+
+**An Actor carries it once.** A being's prose reaches two fields, and a document
+saying the same thing twice teaches a reader to skip it — a printed sheet draws
+both in turn — so the dossier carries the notice and the appearance is
+untouched. The two systems pair by the authored section each field reads rather
+than by its name, so `dossier` and `biography` carry it while `appearance` and
+`description` do not.
+
+**The mark is a notice, not a hazard** — `fa-circle-exclamation`, which Foundry
+bundles, so a journal page carries it with no module stylesheet loaded. The book
+draws its own, because a consumer declaring no icon family is the ordinary case
+and a glyph a face lacks is silent in Typst. Stripped of mark and rule the
+sentence still states the whole thing, which is the floor every surface is built
+to.
+
+**Nothing else changes**: the note compiles, validates, publishes and resolves
+exactly as any other, and it stays in the packs, in the link manifest and on the
+site. That is what separates the tag from the retired `draft:` field, whose whole
+effect was to move a note from published to unresolvable without saying so — and
+which is refused, by name, if you write it.
 
 **The group's scope is what makes the check work.** A group names the types it
 applies to, and a place's kinds are only ever checked on a place. Without that
@@ -1677,11 +1712,11 @@ convention rather than declared in a field — see
 A note has three states, and two of them are nothing but conventions the format
 already carried.
 
-| State     | Body    | Marker          | Page        | Document                          | Link target |
-| --------- | ------- | --------------- | ----------- | --------------------------------- | ----------- |
-| **stub**  | empty   | none            | no          | yes, where one would not be empty | no          |
-| **draft** | written | `tags: [draft]` | yes, marked | yes                               | yes         |
-| **full**  | written | none            | yes         | yes                               | yes         |
+| State     | Body    | Marker          | Page         | Document                          | Link target |
+| --------- | ------- | --------------- | ------------ | --------------------------------- | ----------- |
+| **stub**  | empty   | none            | no           | yes, where one would not be empty | no          |
+| **draft** | written | `tags: [draft]` | yes, noticed | yes, noticed                      | yes         |
+| **full**  | written | none            | yes          | yes                               | yes         |
 
 "Document" here is the document a note's frontmatter earns. A system's Actor or
 Item is earned by that system's block, in every state —
@@ -2266,8 +2301,9 @@ Generates a living (or undead, or spirit) being.
 | `affiliations`              | `WikiLink[]`                                   | Affilliations (e.g., arcane/divine traditions, polities, etc)                                    |
 | `gender`                    | `male \| female \| other`                      | Gender of the character                                                                          |
 | `species`                   | `WikiLink`                                     | Being's species (lore)                                                                           |
-| `age`                       | `number`                                       | Age of the character                                                                             |
-| `birthday`                  | `YYYY/MM/DD`                                   | Date of birth of the character                                                                   |
+| `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                    |
 | `height`                    | `number`                                       | Height in meters                                                                                 |
 | `weight`                    | `number`                                       | Weight in kilograms                                                                              |
 | `frame`                     | `scant \| light \| medium \| large \| massive` | Relative frame size                                                                              |
@@ -2277,6 +2313,31 @@ Generates a living (or undead, or spirit) being.
 | `appearance.complexion`     | `string`                                       | Complexion                                                                                       |
 | `appearance.extra_features` | `string[]`                                     | Extra features                                                                                   |
 
+#### When a being was born, when it died, and how old it is
+
+**Absence asserts a fact rather than recording a gap**, and that is what these
+three fields are built around.
+
+- **`born` absent** says the being was **never born** — a construct, a spirit,
+  an elemental, a thing that was made. **`born: unknown`** says it was born and
+  the date is unrecorded, which is the commonest shape in a tree.
+- **`died` absent** says the being is **alive**, which is the common case and so
+  takes the cheapest form. **`died: unknown`** says it is dead and the date is
+  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.
+
+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.
+
+`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
+every tree has moved.
+
 #### The lead image
 
 **A being's portrait is the first thing inside its `{#appearance}` section,

package/engine/calendars.mjs

@@ -0,0 +1,132 @@
+/*
+ * 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 axis every date normalises onto, and the one function that puts a
+ * reckoning on it.**
+ *
+ * A setting keeps several counts of years at once, each proclaimed by a body
+ * that has a note — a founding, a first occasion, a reign. A date either names
+ * one of them or names none, in which case it sits on the **canonical axis**.
+ *
+ * ## The canonical axis is an authoring device, not a calendar
+ *
+ * The axis is the line of integers dates written by peoples who never met are
+ * compared on. Nobody in a setting keeps it, no body stands behind it, and no
+ * shortcode addresses it: a date is on the axis exactly when it names no era.
+ * A reckoning whose year 1 happens to sit where the axis's year 1 sits
+ * coincides with it numerically and is still that people's own count.
+ *
+ * ## There is no year zero, and one function converts
+ *
+ * The authored numbering skips zero — `-1` sits immediately before `1` — while
+ * the normalised value does not, so that arithmetic across an epoch is one
+ * subtraction rather than a special case somebody forgets.
+ *
+ * ```text
+ * authored        …  -3   -2   -1    1    2    3  …
+ * canonicalYear   …  -2   -1    0    1    2    3  …
+ * ```
+ *
+ * ```text
+ * canonicalYear(y, E) = E + (y > 0 ? y - 1 : y)
+ * ```
+ *
+ * `E` is where a reckoning's year 1 sits on the axis — the `canonicalYear` of
+ * an era's own `start`. The axis is the same function with `E` of
+ * {@link CANONICAL_EPOCH}, which holds by definition: the axis's year 1 is the
+ * axis's year 1.
+ *
+ * **The conversion is piecewise on the sign**, and that is the property worth
+ * guarding. Collapsed to a single branch it is correct on one side of an epoch
+ * and off by one on the other, which is invisible in any list that does not
+ * span it.
+ *
+ * ## The month structure is the package's, and an absent bound checks nothing
+ *
+ * An era moves where year 1 sits; it does not divide the year differently. So
+ * the subdivision is declared once for the package, in `calendar.months` and
+ * `calendar.monthDays`, and a package that declares neither is bounded below
+ * and not above — a toolchain that invented twelve Gregorian months would
+ * refuse `667/2/30`, which is an ordinary date in a year of twelve thirty-day
+ * months.
+ *
+ * @module
+ */
+
+/**
+ * Where the canonical axis's own year 1 sits — on itself.
+ *
+ * It takes no configuration entry and no era row, because it is true by
+ * definition rather than by declaration.
+ *
+ * @type {number}
+ */
+export const CANONICAL_EPOCH = 1;
+
+/**
+ * The year on the canonical axis that a written year lands on.
+ *
+ * The whole of the conversion. A reckoning differs from its neighbours in
+ * where its year 1 sits and in nothing else, so an era states one number and
+ * this states what to do with it.
+ *
+ * The two branches are the year-zero hole: the authored numbering has no year
+ * 0, so a positive year is one place closer to the epoch than its magnitude
+ * suggests and a negative year is exactly its magnitude below it.
+ *
+ * @param {number} year - The year as authored, signed, within its own
+ *   reckoning. Never 0 — the authored numbering has no such year.
+ * @param {number} [epoch] - Where that reckoning's year 1 sits on the axis.
+ *   Omitted, the axis itself.
+ * @returns {number} The signed year on the axis — authored `-1` is `0`.
+ */
+export function canonicalYear(year, epoch = CANONICAL_EPOCH) {
+    return epoch + (year > 0 ? year - 1 : year);
+}
+
+/**
+ * The total-order key a date sorts on.
+ *
+ * Month and day fold into the fraction, so a mixed-precision list sorts stably
+ * against a single number instead of a three-key comparator. The arithmetic is
+ * done in ten-thousandths and divided once, because `year + 6 / 100 + 19 /
+ * 10000` accumulates a rounding error and `689.0619` is a value a reader
+ * compares against by eye.
+ *
+ * A coarser value sorts **before** the finer values inside it: `689` precedes
+ * `689/1`, which is the ordering a reader expects of a year whose month nobody
+ * wrote.
+ *
+ * @param {number} year - The year on the canonical axis.
+ * @param {number|null} month - The month, or `null`.
+ * @param {number|null} day - The day, or `null`.
+ * @returns {number} The sort key.
+ */
+export function dateSortKey(year, month, day) {
+    return (year * 10000 + (month ?? 0) * 100 + (day ?? 0)) / 10000;
+}
+
+/**
+ * The bounds a package states for a month, or `null` where it states none.
+ *
+ * Separate from the check that reads it so a caller can ask what a package
+ * declares without phrasing a finding about it.
+ *
+ * @param {{months?: number|null, monthDays?: number|null}} [calendar] - The
+ *   resolved `calendar:` block.
+ * @returns {{months: number|null, monthDays: number|null}} What it declares.
+ */
+export function calendarStructure(calendar) {
+    return { months: calendar?.months ?? null, monthDays: calendar?.monthDays ?? null };
+}

package/engine/content-format-check.mjs

@@ -102,6 +102,7 @@ import { currentType } from "./ids.mjs";
 import { SCHEMA_ARTIFACT_VERSION } from "./schema-check.mjs";
 import { authoredFields } from "./field-spec.mjs";
 import { positionInFrontmatter } from "./diagnostics.mjs";
+import { RETIRED_FIELD_ALIASES } from "./retired-fields.mjs";
 
 /**
  * Every field path any subtype of a published schema declares.
@@ -357,8 +358,16 @@ export function measureNote(note, format, { severity = "warning" } = {}) {
 
     // `data:` is closed: every key it carries must be one the type declares.
     const data = isBlock(fm.data) ? fm.data : undefined;
+    // The retired spelling of a key the format states is measured as the key it
+    // will be written as, exactly as a note still on a renamed *type* is
+    // measured against the section it will move to. The rename itself is the
+    // frontmatter lint's finding, and reporting it here as well would count one
+    // note twice in a migration whose counts are the point.
+    const renamedDataKeys = new Set(
+        [...spec.dataKeys].map((key) => RETIRED_FIELD_ALIASES[key]).filter(Boolean),
+    );
     for (const key of Object.keys(data ?? {})) {
-        if (spec.dataKeys.has(key)) continue;
+        if (spec.dataKeys.has(key) || renamedDataKeys.has(key)) continue;
         const guess = nearest(key, spec.dataKeys);
         add(
             "unknown-data-key",