@heroiclands/package-build 17.1.0 → 18.0.0

package/engine/helpers.mjs

@@ -37,7 +37,13 @@ import { loadPackConfig } from "./pack-config.mjs";
 import { packRouter } from "./pack-router.mjs";
 import { contentPackage, foundryPackageId } from "./content-package.mjs";
 import { searchableFrontmatter } from "./note-package.mjs";
-import { loadForeignManifests, PACKAGE_BASE } from "./kb-manifest.mjs";
+import { PACKAGE_BASE } from "./content-address.mjs";
+import { resolveNoteId } from "./note-ids.mjs";
+import { loadForeignIndexes } from "./metadata-index.mjs";
+// The record accessors only — deriving records reaches the pack router and the
+// manifest emitter, which reach the compilers, which load this module. Reading
+// a record needs none of that (#243).
+import { authoredFrontmatter, isNoteRecord, noteFile } from "./index-records.mjs";
 import { buildWikilinkIndex, convertWikilinks } from "./wikilinks.mjs";
 // One vocabulary of link findings, and one message per class, so the three
 // resolvers cannot word the same defect differently (#184).
@@ -54,6 +60,7 @@ import { getFrontmatter } from "./frontmatter.mjs";
 export {
     getFrontmatter,
     sohlField,
+    folderField,
     resolveCharges,
     resolveSkillAptitudes,
     resolveRelation,
@@ -120,10 +127,74 @@ export function parseMarkdownFile(filePath) {
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore.
  *   Defaults to the configured list.
  */
-export function* walkMarkdownTree(
-    rootDir,
-    { skipDirectories = loadPackConfig().skipDirectories } = {},
-) {
+/**
+ * Refuse a corpus read whose scope its caller did not state.
+ *
+ * The rule of #243 in one place, so every reader of the tree refuses the same
+ * way and says so in the same words. It is shared rather than repeated because
+ * the corpus is no longer read only by {@link walkMarkdownTree}: a pass that
+ * reads the content index instead is making the identical claim about which
+ * files it is looking at, and must be held to the identical requirement — a
+ * scope that quietly defaulted there would reintroduce exactly the second
+ * answer the walk's requirement removed.
+ *
+ * @param {readonly string[]|undefined} skipDirectories - The stated scope.
+ * @param {string} who - The reader, named in the message.
+ * @throws {Error} When no scope was stated.
+ * @returns {void}
+ */
+export function assertStatedScope(skipDirectories, who) {
+    if (skipDirectories === undefined) {
+        throw new Error(
+            `${who} requires \`skipDirectories\`: the scope is the ` +
+                "caller's to state, so two passes cannot disagree about which " +
+                "files are the corpus",
+        );
+    }
+}
+
+/**
+ * Refuse a corpus read whose records its caller did not supply.
+ *
+ * The sibling of {@link assertStatedScope}, and required for the same reason
+ * one step further on. These two readers cannot derive the corpus themselves:
+ * deriving it reaches the pack router and the manifest emitter, which reach the
+ * compilers, which load this module — so importing the index here closes a
+ * cycle. They take the records their caller already holds.
+ *
+ * That is not a workaround dressed up as a rule. A compile runs several passes
+ * over one tree, and the whole of #243 is that they must not each answer "which
+ * files are the corpus?" for themselves. Requiring the answer to be handed in
+ * makes the sharing structural rather than remembered.
+ *
+ * @param {readonly object[]|undefined} records - The supplied corpus.
+ * @param {string} who - The reader, named in the message.
+ * @throws {Error} When no corpus was supplied.
+ * @returns {void}
+ */
+export function assertSuppliedCorpus(records, who) {
+    if (!records) {
+        throw new Error(
+            `${who} requires \`records\`: the corpus is derived once per ` +
+                "compile and handed to every pass, so no two passes can " +
+                "disagree about which files it holds",
+        );
+    }
+}
+
+export function* walkMarkdownTree(rootDir, { skipDirectories } = {}) {
+    // Stated by the caller, never resolved here. The default this used to carry
+    // — `loadPackConfig().skipDirectories` — read whichever configuration
+    // resolved from the working directory rather than the one the caller was
+    // working under. In an ordinary build those are the same object and nothing
+    // shows; they are not the same when a test injects a configuration, when
+    // `PACKAGE_BUILD_CONFIG` names one, or when the command runs from a
+    // worktree. Six of this function's twelve callers were on that default, so
+    // "which files are the corpus?" had two answers depending on who asked
+    // (#243) — the same defect class as `entriesForNote` reading
+    // `docEntryTypes` from the ambient config, fixed in #240 after a fixture
+    // had been passing on the leak for as long as it existed.
+    assertStatedScope(skipDirectories, "walkMarkdownTree");
     if (!fs.existsSync(rootDir)) return;
     const stack = [rootDir];
     while (stack.length > 0) {
@@ -152,65 +223,168 @@ export function* walkMarkdownTree(
 }
 
 /**
- * Resolve the required `sohl.archetype` frontmatter for an Item/Actor entry
+ * Every position a note may state its template priority at, for one system
+ * block, in the order they answer — and whichever of them the note actually
+ * wrote (#266).
+ *
+ * Three places, in the order the migration runs. The specification calls this
+ * `data.templatePriority`; `sohl-thalorna` already writes it there on 941
+ * notes, beside the `archetype` the build reads — so a tree that has authored
+ * forward is read from the key it authored, and only then does the retiring
+ * spelling answer.
+ *
+ * **The block is a parameter because the value is shared, not per-system.** One
+ * `data.templatePriority` is the note's statement that it is a template; SoHL
+ * records it as `system.templatePriority` and HM3 as `flags.hm3.templatePriority`.
+ * The legacy in-block position is therefore read from *the block being compiled*
+ * rather than always from `sohl:`, so an HM3-only note is not asked to author a
+ * SoHL block to be read.
+ *
+ * @param {object} fm     Parsed frontmatter.
+ * @param {string} block  The system block being compiled.
+ * @returns {{found: [object, string]|undefined, retiring: [object, string]|undefined,
+ *   NEW: string, OLD: string}} The answering position, the retiring spelling's
+ *   position if the note also carries it, and the two key names.
+ */
+function findTemplatePriority(fm, block) {
+    const inBlock =
+        fm != null && typeof fm[block] === "object" && fm[block] !== null ? fm[block] : null;
+    const data = fm != null && typeof fm.data === "object" && fm.data !== null ? fm.data : null;
+
+    const NEW = "templatePriority";
+    const OLD = "archetype";
+    const sources = /** @type {[object|null, string][]} */ ([
+        [data, NEW],
+        [inBlock, NEW],
+        [fm, NEW],
+        [inBlock, OLD],
+        [fm, OLD],
+    ]);
+    const found = sources.find(([where, key]) => where != null && key in where);
+    // A note part-way through the rename may carry both spellings, and they may
+    // *disagree*: 145 of `sohl-thalorna`'s 941 dual-spelled notes say
+    // `templatePriority: null` where `archetype: 0` says the opposite — "not a
+    // template" against "a template at priority 0". Preferring the new key
+    // silently would flip those documents, and preferring the old would ignore
+    // what an author wrote most recently. Neither is a decision this function
+    // gets to make quietly, so a contradiction is refused and named.
+    const retiring = sources
+        .slice(sources.findIndex(([, key]) => key === OLD))
+        .find(([where, key]) => where != null && key in where);
+    return {
+        found: /** @type {[object, string]|undefined} */ (found),
+        retiring: /** @type {[object, string]|undefined} */ (retiring),
+        NEW,
+        OLD,
+    };
+}
+
+/**
+ * The template priority a note states, for a system that treats an unstated one
+ * as "not a template" rather than as an authoring error (#266).
+ *
+ * Reads exactly the positions {@link resolveTemplatePriority} reads, including
+ * the retiring `archetype` spelling, and refuses the same contradiction — so
+ * the two systems cannot disagree about what a note said. It differs only in
+ * what silence means: SoHL requires the statement, while HM3 keeps the value in
+ * a flag it simply omits, so there is no tri-state for an absent value to
+ * corrupt and nothing to demand.
+ *
+ * @param {object} fm      Parsed frontmatter.
+ * @param {string} label   Human-readable context for error messages.
+ * @param {object} [options] Options.
+ * @param {string} [options.block="sohl"] The system block being compiled.
+ * @returns {number|null}  The priority, or `null` when the note is not a
+ *   template or states nothing.
+ * @throws {Error} When both spellings are present and disagree.
+ */
+export function statedTemplatePriority(fm, label, { block = "sohl" } = {}) {
+    const { found, retiring, NEW, OLD } = findTemplatePriority(fm, block);
+    if (found && retiring && found[1] !== OLD && found[0][found[1]] !== retiring[0][OLD]) {
+        throw new Error(
+            `Conflicting ${NEW} for ${label}: ` +
+                `${NEW} is ${JSON.stringify(found[0][found[1]])} and the retiring ` +
+                `${OLD} is ${JSON.stringify(retiring[0][OLD])}. Both are read and ` +
+                `${NEW} wins, so they must agree — delete ${OLD}, or correct it`,
+        );
+    }
+    if (!found) return null;
+    const raw = found[0][found[1]];
+    return raw === null || raw === "" || raw === undefined ? null : raw;
+}
+
+/**
+ * Resolve the required `templatePriority` frontmatter for an Item/Actor entry
  * (the archetype contract, #604). The property is a nullable number that
  * authors must state explicitly:
- *   - a number → the document is an archetype of that priority.
- *   - `null`   → the document is not an archetype.
- *   - absent   → an authoring error (throws), so "not an archetype" is never
+ *   - a number → the document is a template of that priority.
+ *   - `null`   → the document is not a template.
+ *   - absent   → an authoring error (throws), so "not a template" is never
  *                silently assumed.
  *
- * Reads `sohl.archetype`, falling back to a top-level `archetype` key to match
- * {@link sohlField}'s nested-then-top-level resolution.
+ * Reads the positions {@link findTemplatePriority} lists: `data.templatePriority`
+ * first — the specified home — then the system block and the top level, and
+ * finally the retiring `archetype` spelling in the same two places (#266).
  *
  * @param {object} fm      Parsed frontmatter.
  * @param {string} label   Human-readable context for error messages.
- * @returns {number|undefined}  The archetype priority, or `undefined` when null.
- * @throws {Error} When `sohl.archetype` is absent or is not a number/null.
+ * @param {object} [options] Options.
+ * @param {string} [options.block="sohl"] The system block being compiled.
+ * @returns {number|undefined}  The template priority, or `undefined` when null.
+ * @throws {Error} When the property is absent, is not a number/null, or both
+ *   spellings are present and disagree.
  */
-export function resolveArchetype(fm, label) {
-    const sohl = fm != null && typeof fm.sohl === "object" ? fm.sohl : null;
-    const inSohl = sohl != null && "archetype" in sohl;
-    const inTop = fm != null && typeof fm === "object" && "archetype" in fm;
-    if (!inSohl && !inTop) {
+export function resolveTemplatePriority(fm, label, { block = "sohl" } = {}) {
+    const { found, retiring, NEW, OLD } = findTemplatePriority(fm, block);
+
+    if (found && retiring && found[1] !== OLD && found[0][found[1]] !== retiring[0][OLD]) {
+        throw new Error(
+            `Conflicting ${NEW} for ${label}: ` +
+                `${NEW} is ${JSON.stringify(found[0][found[1]])} and the retiring ` +
+                `${OLD} is ${JSON.stringify(retiring[0][OLD])}. Both are read and ` +
+                `${NEW} wins, so they must agree — delete ${OLD}, or correct it`,
+        );
+    }
+    if (!found) {
         throw new Error(
-            `Missing required sohl.archetype for ${label} — set a number (this is an archetype) or null (it is not)`,
+            `Missing required ${NEW} for ${label} — set a number (this is a template, at that priority) or null (it is not)`,
         );
     }
-    const raw = inSohl ? sohl.archetype : fm.archetype;
+    const raw = found[0][found[1]];
     if (raw === null) return undefined;
     if (typeof raw !== "number" || !Number.isFinite(raw)) {
         throw new Error(
-            `Invalid sohl.archetype for ${label}: expected a number or null, got ${JSON.stringify(raw)}`,
+            `Invalid ${found[1]} for ${label}: expected a number or null, got ${JSON.stringify(raw)}`,
         );
     }
     return raw;
 }
 
 /**
- * The value a document's `system.archetype` carries, from the required
- * `sohl.archetype` frontmatter (#126, sohl#1780).
+ * The value a document's `system.templatePriority` carries, from the required
+ * `templatePriority` frontmatter (#126, sohl#1780, renamed off `archetype` by
+ * #266 / sohl#1836).
  *
  * A **schema field**, so the tri-state is written out in full rather than
- * expressed by a key's presence: a number is an archetype at that priority,
- * and `null` is not an archetype. This is where {@link resolveArchetype}'s
+ * expressed by a key's presence: a number is a template at that priority, and
+ * `null` is not a template. This is where {@link resolveTemplatePriority}'s
  * `undefined` becomes the field's `null` — an emitted `undefined` would be
  * dropped by `JSON.stringify`, leaving the compiled document with no
- * `archetype` at all and the tri-state readable as two.
+ * `templatePriority` at all and the tri-state readable as two.
  *
- * **`0` is an archetype.** It is the priority SoHL's own archetypes ship at,
- * and it is falsy, so this returns it unchanged and every caller must ask
+ * **`0` is a template.** It is the priority SoHL's own templates ship at, and
+ * it is falsy, so this returns it unchanged and every caller must ask
  * `typeof v === "number"` rather than testing truthiness.
  *
  * @param {object} fm      Parsed frontmatter.
  * @param {string} label   Human-readable context for error messages.
- * @returns {number|null}  The archetype priority, or `null` for a document
- *   that is not an archetype.
- * @throws {Error} When `sohl.archetype` is absent or invalid.
+ * @returns {number|null}  The template priority, or `null` for a document that
+ *   is not a template.
+ * @throws {Error} When the property is absent or invalid.
  */
-export function systemArchetype(fm, label) {
-    const archetype = resolveArchetype(fm, label);
-    return archetype === undefined ? null : archetype;
+export function systemTemplatePriority(fm, label) {
+    const priority = resolveTemplatePriority(fm, label);
+    return priority === undefined ? null : priority;
 }
 
 /**
@@ -434,6 +608,7 @@ export { makeId } from "./ids.mjs";
 // The content-type → document-type map, which decides *which* pack list a
 // note's own document is routed against.
 import { assertTypeNotRetired, packForType } from "./ids.mjs";
+import { collectAnchors } from "./anchors.mjs";
 
 /* ------------------------------------------------------------------------ */
 /*  Wikilink resolution: the content-wide link index                        */
@@ -461,16 +636,39 @@ import { assertTypeNotRetired, packForType } from "./ids.mjs";
  *   this repository's own.
  * @returns {{byShortcode: Map, types: Set}} From `buildWikilinkIndex`.
  */
-export function buildContentLinkIndex(contentBase, router = packRouter()) {
+export function buildContentLinkIndex(
+    contentBase,
+    router = packRouter(),
+    { skipDirectories, config, records, problems } = {},
+) {
     const docs = [];
-    for (const { frontmatter: fm, absPath } of walkMarkdownTree(contentBase)) {
+    const resolved = config ?? loadPackConfig();
+    assertSuppliedCorpus(records, "buildContentLinkIndex");
+    for (const record of records) {
+        // A documentation journal is a document this tree emits, not a note in
+        // it; the note it documents is indexed here and carries its address.
+        if (!isNoteRecord(record)) continue;
+        // The note as its author wrote it — the router, the draft tag and the
+        // retired-type check all read authored fields, and none of them may be
+        // handed the keys the index derived.
+        const fm = authoredFrontmatter(record);
+        const absPath = noteFile(contentBase, record);
+        // The id a note's document is filed under: its authored pin, or the
+        // one derived from its canonical address (#270). Derived by the index
+        // against the configuration this build resolved — it used to be
+        // derived here through `resolveNoteId(fm)` with no package, which falls
+        // back to the ambient `contentPackage()` and so to whichever
+        // configuration the working directory answers with (#243).
+        // What is left after that is a file with **no address** — no type, or
+        // no shortcode — which is not an addressable note and has no document
+        // to link to.
         if (!fm?.id) continue;
         // The first walk of every note in the tree, and the only one holding
         // both the declared type and the file that declares it — so a note
         // left on a retired type is reported here, by name, rather than
         // several frames deeper with nothing to go on (SoHL#1580).
         assertTypeNotRetired(fm.type, absPath);
-        const base = path.basename(absPath, ".md").replace(/_/g, " ");
+        const base = String(record.file.name).replace(/_/g, " ");
         docs.push({
             type: fm.type,
             id: fm.id,
@@ -485,32 +683,40 @@ export function buildContentLinkIndex(contentBase, router = packRouter()) {
             // *into* this note renders marked. It takes no part in resolution,
             // so the note is indexed, compiled and published as any other.
             draft: isDraftNote(fm),
+            // The anchors this note declares, carried so the *builds* can check
+            // a `#section` link and not only the checker (#193). A foreign
+            // anchor has always been checked, because a fetched index
+            // publishes the map; a local one was not, because the set was
+            // discarded here — the walk yields the body and nothing read it.
+            // Read from the record rather than from a second reading of the
+            // note's headings — the one-anchor-reader rule (#243).
+            anchors: new Set((record.anchors ?? []).map((anchor) => anchor.slug)),
         });
     }
-    // Packages this build links *into* but does not publish. Their manifests
-    // are vendored and committed, so a contributor without every repository
-    // checked out resolves the same links CI does (#1446, #1499).
-    // Packages this repository links into but does not publish; their vendored
-    // manifests live at the configured location (#1446, #1499).
-    const { index: foreign, stale } = loadForeignManifests(
-        loadPackConfig().paths.manifests,
-        [contentPackage()],
+    // Packages this build links *into* but does not publish. Each publishes
+    // its own content index and this build fetched the ones it depends on, so
+    // a contributor without every repository checked out resolves the same
+    // links CI does — from an artifact the producer shipped rather than a copy
+    // this repository committed (#239).
+    const { index: foreign, stale } = loadForeignIndexes(
+        resolved,
+        [resolved.contentPackage],
         PACKAGE_BASE,
     );
     if (stale.length) {
         for (const st of stale) {
-            log.error(`Unusable link manifest for "${st.package}": ${st.reason}`);
+            log.error(`Unusable content index for "${st.package}": ${st.reason}`);
         }
         throw new Error(
-            "Cross-package links cannot be resolved from a stale manifest; " +
-                "re-vendor it from that package's build.",
+            "Cross-package links cannot be resolved from an unusable index; " +
+                "re-run `content-build deps fetch`.",
         );
     }
     log.debug(
         `Wikilink index: ${docs.length} local document(s), ` +
             `${foreign.size} foreign address(es)`,
     );
-    return buildWikilinkIndex(docs, foundryPackageId(), foreign, contentPackage());
+    return buildWikilinkIndex(docs, resolved.foundryPackage, foreign, resolved.contentPackage);
 }
 
 /**
@@ -609,16 +815,25 @@ export function convertNoteWikilinks(
  * @returns {Array<{fm: object, path: string, tld: string, folder: string,
  *   absPath: string}>}
  */
-export function collectContentDocs(contentBase) {
+export function collectContentDocs(
+    contentBase,
+    { skipDirectories, config, records, problems } = {},
+) {
     const docs = [];
-    for (const { frontmatter: fm, absPath } of walkMarkdownTree(contentBase)) {
-        if (!fm) continue;
-        const segments = path.relative(contentBase, absPath).split(path.sep);
+    const resolved = config ?? loadPackConfig();
+    assertSuppliedCorpus(records, "collectContentDocs");
+    for (const record of records) {
+        if (!isNoteRecord(record)) continue;
+        const fm = authoredFrontmatter(record);
+        const absPath = noteFile(contentBase, record);
+        const segments = String(record.file.path).split("/");
         docs.push({
             // With its package supplied for a `WHERE … package = "…"` query —
-            // synthesised from the configuration, since no note declares it
-            // (#56).
-            fm: searchableFrontmatter(fm),
+            // synthesised from the configuration this build resolved, since no
+            // note declares it (#56) and the ambient one is a different
+            // configuration in a worktree or under `PACKAGE_BUILD_CONFIG`
+            // (#243).
+            fm: searchableFrontmatter(fm, resolved.contentPackage),
             // POSIX-separated and relative to the content root — what a
             // `path:` search term globs, on every platform.
             path: segments.join("/"),
@@ -670,7 +885,7 @@ const packLinkable = (doc) => Boolean(doc.fm?.shortcode) && Boolean(doc.fm?.type
  *   compile rather than shipping a table-shaped hole. The error carries
  *   `position`, the directive's own line.
  */
-export function expandNoteTables(body, { docs, name, fm, bodyLine }) {
+export function expandNoteTables(body, { docs, name, fm, bodyLine, sqlTables }) {
     const self =
         fm ?
             (docs.find((d) => d.fm?.id && d.fm.id === fm.id) ?? {
@@ -682,6 +897,7 @@ export function expandNoteTables(body, { docs, name, fm, bodyLine }) {
         linkable: packLinkable,
         source: name,
         self,
+        sqlTables,
     });
     if (errors.length) {
         const err = new Error(errors.map((e) => `content table — ${e.reason}`).join("; "));
@@ -767,14 +983,27 @@ export function buildFolderResolver(folders) {
         siblings.add(f.name);
     }
 
-    function resolver(folderId) {
-        if (folderId == null || folderId === "") return null;
-        const id = String(folderId).trim();
-        if (!id) return null;
-        if (!byId.has(id)) {
-            throw new Error(`Unknown folder id "${id}"`);
+    /**
+     * The folder id a note names, by id.
+     *
+     * **Only by id.** This resolver answers for `folder:` alone; `packFolder:`
+     * names a folder *note* and is resolved through the address index instead
+     * (#255). The path lookup that briefly lived here is gone with the path
+     * spelling it served — it was never released, so there is nothing to
+     * deprecate.
+     *
+     * @param {string|null|undefined} value - As authored.
+     * @returns {string|null} The id, or `null` for an absent value.
+     * @throws {Error} When the id is not one this pack declares.
+     */
+    function resolver(value) {
+        if (value == null || value === "") return null;
+        const authored = String(value).trim();
+        if (!authored) return null;
+        if (!byId.has(authored)) {
+            throw new Error(`Unknown folder id "${authored}"`);
         }
-        return id;
+        return authored;
     }
 
     return { resolver, folders };

package/engine/ids.mjs

@@ -64,6 +64,28 @@ export const MAP_TYPES = Object.freeze(new Set(["map"]));
  */
 export const MAP_SUBTYPES = Object.freeze(["battlemap", "localmap", "regionalmap"]);
 
+/**
+ * Content types whose whole document **is** a JournalEntry.
+ *
+ * Prose, and nothing else: each compiles into one journal entry of its own,
+ * with no second document to point at. That is what separates them from the
+ * doc-carrying types in `item-docs.mjs`, whose prose becomes a journal *beside*
+ * an item, a macro or a scene — those are two documents, and the pair is
+ * addressed as `<type>` and `doc<type>`. These are one, so there is no
+ * `docplace` and nothing synthesizes one.
+ *
+ * `doc` was the only member until #241. `place`, `lore` and `scenario` are in
+ * the published content format and were declared for validation in #233, but
+ * nothing routed them: a note of one lint-ed clean and then compiled into
+ * nothing, because {@link PACK_BY_TYPE} did not name it and the open-set
+ * default sent it to the items pack. `sohl-thalorna` could not compile a single
+ * pack for exactly this reason — 450 notes, and the same 450 the linter had
+ * reported before it learned the types.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const JOURNAL_TYPES = Object.freeze(new Set(["doc", "place", "lore", "scenario"]));
+
 /**
  * Content type → the pack its documents compile into, and the document type
  * that pack holds.
@@ -78,9 +100,17 @@ export const MAP_SUBTYPES = Object.freeze(["battlemap", "localmap", "regionalmap
  * @type {Readonly<Record<string, {pack: string, docType: string}>>}
  */
 export const PACK_BY_TYPE = Object.freeze({
-    doc: { pack: "journals", docType: "JournalEntry" },
+    ...Object.fromEntries(
+        [...JOURNAL_TYPES].map((type) => [type, { pack: "journals", docType: "JournalEntry" }]),
+    ),
     macro: { pack: "macros", docType: "Macro" },
     being: { pack: "actors", docType: "Actor" },
+    // A bundle is Foundry's `Adventure` — a set of document *copies* packaged
+    // for one-shot import (#259). The conventional name is `adventures`, which
+    // is also what the scenes pass calls its **companion**; the two are
+    // different packs and a repository shipping both names them apart, since
+    // the router refuses a note that addresses a companion.
+    bundle: { pack: "adventures", docType: "Adventure" },
     ...Object.fromEntries(
         [...MAP_TYPES].map((type) => [type, { pack: "scenes", docType: "Scene" }]),
     ),
@@ -134,6 +164,106 @@ export function assertTypeNotRetired(type, where) {
     );
 }
 
+/* -------------------------------------------------------------------- */
+/*  Renamed in favour of another type — the retirement window            */
+/* -------------------------------------------------------------------- */
+
+/**
+ * Content types that were **renamed**, and what each is called now.
+ *
+ * A retired type and a renamed one are different cases, and only the first can
+ * be refused. `character` above was retired *outright* — nothing a note wrote
+ * made it right, so {@link assertTypeNotRetired} throws. A renamed type has a
+ * replacement, the two spellings mean the same thing, and a note carrying the
+ * old one compiles into exactly the document it always did: refusing it would
+ * fail a build over a note that is not wrong.
+ *
+ * So these retire in the three steps `package:` took (#56), and this table is
+ * the **first**: both spellings resolve, the current one is canonical, and the
+ * retired one is *reported* — never refused. The sweep of the content trees and
+ * the refusal come after, once no tree writes the old name. That is the same
+ * rule `RETIRED_FIELD_ALIASES` states for a renamed *field*, and for the same
+ * reason: a consumer must be able to adopt the new toolchain before its content
+ * moves, and there are some 31,000 references to move.
+ *
+ * **Why these three (#78).** `armorgear`, `concoctiongear` and `projectilegear`
+ * named the *SoHL document subtype* a note happened to compile into rather than
+ * the thing the note is about. A note's `type` sits outside the `sohl:` and
+ * `hm3:` blocks precisely because it belongs to no system, and HM3 already
+ * compiles a `projectile` into a `missilegear` — so the suffix was never a fact
+ * about the note. `weapongear` keeps its name: SoHL and HM3 both call the
+ * document that, and #78's table has no row for it.
+ *
+ * **Keyed by the retired spelling**, which is the opposite of
+ * `RETIRED_FIELD_ALIASES`. The direction follows the operation: a field alias
+ * is scoped by the schema that declares the *current* name, so that is what a
+ * reader asks with; a type alias is applied to a value read off a note, so what
+ * a reader has in hand is the retired spelling and what it needs is the
+ * replacement.
+ *
+ * **The address is not normalised.** A note's canonical address — and therefore
+ * its document id — carries its `type` as authored, so both spellings keep the
+ * addresses they already publish and a tree that has not swept compiles
+ * byte-identically. Renaming the type in a note *is* an address move, which is
+ * the sweep's business and not this table's.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const RENAMED_TYPES = Object.freeze({
+    armorgear: "armor",
+    concoctiongear: "concoction",
+    projectilegear: "projectile",
+});
+
+/**
+ * The current spelling of a content type: itself, or what it was renamed to.
+ *
+ * Every table keyed by note type is keyed by the **current** name, and every
+ * lookup goes through this — which is the whole of the window's behaviour, in
+ * one function, so no two readers can disagree about which vocabulary a note
+ * is held to.
+ *
+ * A non-string passes through untouched: callers hand this whatever the
+ * frontmatter carried, and inventing a type for a number would hide the
+ * missing-`type:` finding that belongs to the linter.
+ *
+ * @param {any} type - The type as authored, or as a link spells it.
+ * @returns {any} The current spelling.
+ */
+export function currentType(type) {
+    if (typeof type !== "string") return type;
+    return RENAMED_TYPES[type] ?? type;
+}
+
+/**
+ * What a note declaring a renamed type is told, in one place.
+ *
+ * Shared by every reporter, because an author meets whichever runs first and
+ * they should read the same. It names the type to write rather than a value to
+ * correct — no value makes the retired spelling right — and it says the note
+ * compiles either way, so a reader knows this is a rename to schedule rather
+ * than a build to unbreak.
+ *
+ * @param {string} retired - The spelling the note used.
+ * @param {string} current - What to write instead.
+ * @param {string} [where] - What carries it — a file path, a link target —
+ *   appended to the message. Omit it where the caller emits through a
+ *   diagnostic, whose locator already starts the line.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function renamedTypeMessage(retired, current, where) {
+    return (
+        `content type "${retired}" was renamed to "${current}" — the suffix ` +
+        `named a SoHL document subtype rather than the thing the note is ` +
+        `about` +
+        (where ? ` — ${where}` : "") +
+        `. Both spellings compile to the same document, so the note is not ` +
+        `wrong; write "${current}", and move every \`(type, shortcode)\` ` +
+        `reference and wikilink to it in the same change. "${retired}" is ` +
+        `refused in a later release`
+    );
+}
+
 /** Where every other content type compiles: the items pack. */
 export const ITEM_PACK = Object.freeze({ pack: "items", docType: "Item" });
 
@@ -162,7 +292,12 @@ export const ITEM_PACK = Object.freeze({ pack: "items", docType: "Item" });
  */
 export function packForType(type) {
     assertTypeNotRetired(type);
-    return PACK_BY_TYPE[type] ?? ITEM_PACK;
+    // Through {@link currentType} like every other type-keyed lookup, so the
+    // rule holds without exception. None of today's renamed types is named in
+    // `PACK_BY_TYPE` — all three are items and take the default — but a router
+    // that read the authored spelling would be the one table left to remember
+    // when the next rename lands.
+    return PACK_BY_TYPE[currentType(type)] ?? ITEM_PACK;
 }
 
 /**