@heroiclands/package-build 23.1.0 → 23.2.0

package/types/engine/field-spec.d.mts

@@ -1,48 +1,9 @@
-/**
- * Whether a resolution read a field from the position it is being swept off.
- *
- * The sweep's progress signal, in one predicate so the compile-time report and
- * the frontmatter lint cannot disagree about what counts — the role
- * {@link module:engine/retired-fields.declaresRetiredAlias} plays for a renamed
- * field.
- *
- * **Only for a field that declares a `legacyKey`.** Every other field's
- * in-block position is simply where it lives; reporting those would put a
- * finding on every field of every note in every tree, which is the corpus
- * migration rather than a signal anyone could act on.
- *
- * @param {FieldSpec} field - The declaration.
- * @param {import("./system-block.mjs").FieldSource} from - Where
- *   {@link resolveFieldValue} said the value came from.
- * @returns {boolean} True when the value came from the retiring position.
- */
-export function readsLegacyKey(field: FieldSpec, from: import("./system-block.mjs").FieldSource): boolean;
-/**
- * Whether a resolution read a field from the top-level key `data:` gathered it
- * off — the shared level's retiring position.
- *
- * {@link readsLegacyKey}'s sibling, and the same signal: a finding here counts
- * one note still on the pre-`data:` spelling, so the sweep has something to
- * count down instead of a corpus nobody has surveyed.
- *
- * The `from` tag already carries the whole answer — step 3b is the only thing
- * that produces it, and it produces it only for a `data.` source — so this is a
- * name for the question rather than a second test of it. Named all the same,
- * because a compile-time report and the frontmatter lint both ask it and must
- * not drift apart about what counts.
- *
- * @param {FieldSpec} field - The declaration.
- * @param {import("./system-block.mjs").FieldSource} from - Where
- *   {@link resolveFieldValue} said the value came from.
- * @returns {boolean} True when the value came from the retiring top-level key.
- */
-export function readsRetiredTopLevel(field: FieldSpec, from: import("./system-block.mjs").FieldSource): boolean;
 /**
  * Read one declared field out of a note's frontmatter.
  *
  * The *position* is resolved by {@link resolveFieldValue} — `<system>.system`
- * first, then the legacy in-block key, then the declared shared source, then
- * the default. The **coercion** is applied here, once, wherever the value
+ * first, then the in-block key, then the declared shared source, then the
+ * default. The **coercion** is applied here, once, wherever the value
  * came from: a field's `read` is a statement about the field, not about where
  * an author happened to write it, so `weight: "7"` reads as `7` at every one of
  * those positions.
@@ -53,23 +14,10 @@ export function readsRetiredTopLevel(field: FieldSpec, from: import("./system-bl
  * @param {string} [options.block="sohl"] - Which system's block to resolve
  *   against. The default is the one block every existing tree authors; a
  *   second system passes its own.
- * @param {(field: FieldSpec) => void} [options.onLegacyKey] - Called with each
- *   field read from the position it is being swept off. A callback
- *   rather than a returned list because the caller is a compiler, which already
- *   knows the note and how to locate a key in it; this module knows neither and
- *   would have to invent a finding shape to say so.
- * @param {(field: FieldSpec) => void} [options.onRetiredTopLevel] - Called with
- *   each field read from the top-level key `data:` gathered it off. The
- *   shared level's counterpart to `onLegacyKey`, and a separate callback
- *   because it is a separate position: a note may have moved one of the two and
- *   not the other, and a caller that conflated them would tell its author to
- *   fix the wrong line.
  * @returns {any} The value to emit.
  */
 export function readField(field: FieldSpec, fm: object, options?: {
     block?: string | undefined;
-    onLegacyKey?: ((field: FieldSpec) => void) | undefined;
-    onRetiredTopLevel?: ((field: FieldSpec) => void) | undefined;
 }): any;
 /**
  * The same read, reporting **where the value came from** as well.
@@ -90,17 +38,11 @@ export function readField(field: FieldSpec, fm: object, options?: {
  * @param {object} [options] - Options, as {@link readField} takes them.
  * @param {string} [options.block="sohl"] - Which system's block to resolve
  *   against.
- * @param {(field: FieldSpec) => void} [options.onLegacyKey] - See
- *   {@link readField}.
- * @param {(field: FieldSpec) => void} [options.onRetiredTopLevel] - See
- *   {@link readField}.
  * @returns {{value: any, from: import("./system-block.mjs").FieldSource}} The
  *   value to emit, and the position it was read from.
  */
-export function readFieldEntry(field: FieldSpec, fm: object, { block, onLegacyKey, onRetiredTopLevel }?: {
+export function readFieldEntry(field: FieldSpec, fm: object, { block }?: {
     block?: string | undefined;
-    onLegacyKey?: ((field: FieldSpec) => void) | undefined;
-    onRetiredTopLevel?: ((field: FieldSpec) => void) | undefined;
 }): {
     value: any;
     from: import("./system-block.mjs").FieldSource;
@@ -137,18 +79,10 @@ export function isAuthored(from: import("./system-block.mjs").FieldSource, value
  * @param {string} [options.block="sohl"] - Which system's block the builder
  *   reads. One declaration compiles against any block, which is what lets two
  *   systems declare the same shared source and different destinations.
- * @param {(field: FieldSpec) => void} [options.onLegacyKey] - Passed through to
- *   {@link readField}: called with each field the note authored at the position
- *   it is being swept off.
- * @param {(field: FieldSpec) => void} [options.onRetiredTopLevel] - Passed
- *   through to {@link readField}: called with each field the note authored at
- *   the top-level key `data:` gathered it off.
  * @returns {(fm: object) => object} A `system`-block builder.
  */
-export function buildFromFields(fields: readonly FieldSpec[], { block, onLegacyKey, onRetiredTopLevel }?: {
+export function buildFromFields(fields: readonly FieldSpec[], { block }?: {
     block?: string | undefined;
-    onLegacyKey?: ((field: FieldSpec) => void) | undefined;
-    onRetiredTopLevel?: ((field: FieldSpec) => void) | undefined;
 }): (fm: object) => object;
 /**
  * The fields of a declaration an author actually writes.
@@ -176,6 +110,7 @@ export function authoredFields(fields: readonly FieldSpec[]): FieldSpec[];
  * @returns {FieldSpec[]} Only the fields declaring `runtimeOnly`.
  */
 export function runtimeOnlyFields(fields: readonly FieldSpec[]): FieldSpec[];
+export { setPath };
 /**
  * @typedef {object} FieldSpec
  * @property {string} to - Dotted path in the emitted `system` block — and,
@@ -190,29 +125,10 @@ export function runtimeOnlyFields(fields: readonly FieldSpec[]): FieldSpec[];
  *   degenerate case where the shared source and the system destination happen
  *   to share a name. They constantly do not — one shared `data.portrait` feeds
  *   `sohl.system.portrait` *and* `hm3.system.bioImage` — so the source is
- *   declared rather than matched by spelling. The in-block position is
- *   still read, second, until the corpus moves off it — keyed on
- *   `legacyKey` where the two spellings differ.
+ *   declared rather than matched by spelling. A name that is not a path into
+ *   `data:` is also read inside the system block, second.
  *
  *   Absent means the value is not authored at all — see `value`.
- * @property {string} [legacyKey] - **The key this field is authored at inside
- *   the system block** — the second position of the resolution order — when
- *   that is not `name`. Absent, the position is keyed on `name`.
- *
- *   As one property the two would hold only while a field's
- *   shared source and its in-block key were the same word. `data:` ended
- *   that: a shared source is a path into a container, so `data.species` and
- *   `species` name two different places and no single value reached both.
- *   `name: "species"` could not see `data.species`; `name: "data.species"`
- *   could not see `hm3.species`; and each yielded the field's **default**
- *   wherever only the other position was authored, with the note compiling and
- *   the value simply gone.
- *
- *   Declaring both restores the shape every other retirement in this package
- *   uses — read both spellings, let the current one win, and *report* the
- *   retiring one — so a field can move into `data:` while the corpus catches
- *   up, instead of on a flag day across four repositories. A declaration that
- *   names one is mid-sweep by construction; see {@link readsLegacyKey}.
  * @property {string} [topLevelMeans] - **Why the note's top-level key of this
  *   name is not this field's source** — declared wherever that key's spelling
  *   means something else at the note level, or the closed top-level
@@ -238,7 +154,7 @@ export function runtimeOnlyFields(fields: readonly FieldSpec[]): FieldSpec[];
  *
  *   The exempted field is still authorable, at both of the positions that
  *   describe the *document* rather than the note: `<system>.system.<to>` and
- *   the legacy in-block `<system>.<name>`. Absent means the ordinary case —
+ *   the in-block `<system>.<name>`. Absent means the ordinary case —
  *   the top level is read, as the third step.
  *
  *   **It is read from the other side too**, because the statement is symmetric:
@@ -340,7 +256,7 @@ export function runtimeOnlyFields(fields: readonly FieldSpec[]): FieldSpec[];
  *   itself a valid world time, which is why such a field is nullable rather
  *   than sentinelled and why a default cannot stand in for one.
  *
- *   Nothing used to stop a note writing one. The three checks that might have
+ *   Nothing else stops a note writing one. The three checks that might have
  *   each declined for its own correct reason —
  *   {@link module:engine/system-block.unknownBlockKeys} reads the block's top
  *   level and never descends into `system:`;
@@ -439,34 +355,12 @@ export type FieldSpec = {
      * degenerate case where the shared source and the system destination happen
      * to share a name. They constantly do not — one shared `data.portrait` feeds
      * `sohl.system.portrait` *and* `hm3.system.bioImage` — so the source is
-     * declared rather than matched by spelling. The in-block position is
-     * still read, second, until the corpus moves off it — keyed on
-     * `legacyKey` where the two spellings differ.
+     * declared rather than matched by spelling. A name that is not a path into
+     * `data:` is also read inside the system block, second.
      *
      * Absent means the value is not authored at all — see `value`.
      */
     name?: string | undefined;
-    /**
-     * - **The key this field is authored at inside
-     * the system block** — the second position of the resolution order — when
-     * that is not `name`. Absent, the position is keyed on `name`.
-     *
-     * As one property the two would hold only while a field's
-     * shared source and its in-block key were the same word. `data:` ended
-     * that: a shared source is a path into a container, so `data.species` and
-     * `species` name two different places and no single value reached both.
-     * `name: "species"` could not see `data.species`; `name: "data.species"`
-     * could not see `hm3.species`; and each yielded the field's **default**
-     * wherever only the other position was authored, with the note compiling and
-     * the value simply gone.
-     *
-     * Declaring both restores the shape every other retirement in this package
-     * uses — read both spellings, let the current one win, and *report* the
-     * retiring one — so a field can move into `data:` while the corpus catches
-     * up, instead of on a flag day across four repositories. A declaration that
-     * names one is mid-sweep by construction; see {@link readsLegacyKey}.
-     */
-    legacyKey?: string | undefined;
     /**
      * - **Why the note's top-level key of this
      * name is not this field's source** — declared wherever that key's spelling
@@ -493,7 +387,7 @@ export type FieldSpec = {
      *
      * The exempted field is still authorable, at both of the positions that
      * describe the *document* rather than the note: `<system>.system.<to>` and
-     * the legacy in-block `<system>.<name>`. Absent means the ordinary case —
+     * the in-block `<system>.<name>`. Absent means the ordinary case —
      * the top level is read, as the third step.
      *
      * **It is read from the other side too**, because the statement is symmetric:
@@ -634,7 +528,7 @@ export type FieldSpec = {
      * itself a valid world time, which is why such a field is nullable rather
      * than sentinelled and why a default cannot stand in for one.
      *
-     * Nothing used to stop a note writing one. The three checks that might have
+     * Nothing else stops a note writing one. The three checks that might have
      * each declined for its own correct reason —
      * {@link module :engine/system-block.unknownBlockKeys} reads the block's top
      * level and never descends into `system:`;
@@ -668,7 +562,4 @@ export type FieldSpec = {
      */
     describe: string;
 };
-import { legacyKeyOf } from "./system-block.mjs";
-import { retiredTopLevelKey } from "./system-block.mjs";
 import { setPath } from "./system-block.mjs";
-export { legacyKeyOf, retiredTopLevelKey, setPath };

package/types/engine/folder-notes.d.mts

@@ -96,45 +96,6 @@ export function buildFolderNoteIndex(folders: FolderNote[]): {
  * @returns {object} The Folder document.
  */
 export function folderDocument(folder: FolderNote, parent: FolderNote | null, documentType: string, stats: object): object;
-/**
- * Refuse a note that declares the retired `folder:` spelling.
- *
- * `folder:` named a compendium folder by the raw Foundry id declared in a
- * per-pack `*-folders.yaml`. Both halves are retired together: the id
- * spelling has nothing left to resolve against once the YAML is gone, and the
- * YAML has no reader once the spelling is refused.
- *
- * **Presence is the whole test.** An empty `folder:` — which parses as `null`
- * — is still the field, and a value that happens to match a folder note's id
- * is still the retired spelling. There is no value that makes writing it
- * correct, so the message says what to write instead rather than which value
- * to change.
- *
- * **Both positions**, because notes wrote it both ways: top-level, and inside
- * the `sohl:` block. Checking only the more common one is how a sweep leaves
- * a tail behind.
- *
- * Refused rather than ignored, on the pattern `package:` set: a retired field
- * left ignored reads to its author as though it still works — the note says
- * one thing and the build does another, and nothing says so.
- *
- * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
- *   could not be parsed.
- * @param {object} [options] - Options.
- * @param {string} [options.file] - The note's path, named in the message. Omit
- *   it where the caller emits through a diagnostic, which puts the locator at
- *   the start of the line already — repeating it prints the path twice.
- * @param {string} [options.absPath] - The note's file on disk, read only on
- *   the failing path to locate the offending line and column. The position
- *   rides on the thrown error as `position`, for a caller that emits a
- *   diagnostic.
- * @returns {void}
- * @throws {Error} When the note declares the field.
- */
-export function assertNoDeclaredFolder(fm: object | null | undefined, { file, absPath }?: {
-    file?: string | undefined;
-    absPath?: string | undefined;
-}): void;
 /**
  * The note type a folder is authored as.
  *

package/types/engine/foreign-catalog.d.mts

@@ -191,7 +191,8 @@ export function fetchMetadataFromPath(config: object, rel: {
  * Fetch every declared dependency's content index.
  *
  * A wider set than {@link fetchAllCatalogs}: an index is fetched for *every*
- * dependency, a catalogue only for those declaring `itemCatalog: true`. See
+ * dependency, plus every other relationship declaring `itemCatalog: true`; a
+ * catalogue only for those declaring `itemCatalog: true`. See
  * {@link metadataRelationships} for why the two sets differ.
  *
  * @param {object} config - The resolved build configuration.

package/types/engine/foundry-entries.d.mts

@@ -44,11 +44,10 @@ export function entriesForNote(fm: object, name: string, address: string, body:
  * Every note this package publishes, as manifest entries.
  *
  * Every note in the tree is this package's, so nothing here selects by package:
- * the key's first segment is `contentPackage`. A note still declaring the
- * retired `package:` or `draft:` field **throws** rather than being skipped —
- * skipping one silently is how a whole tree came to be filtered out of a
- * manifest that then claimed the package published nothing, and it is what let
- * a drafted note's inbound links look like links to a note that never existed.
+ * the key's first segment is `contentPackage`. A note declaring `package:`
+ * **throws** rather than being skipped — skipping one silently is how a whole
+ * tree came to be filtered out of a manifest that then claimed the package
+ * published nothing.
  *
  * A note that has no address is **reported, not guessed** — the finding carries
  * the file and the reason, so a caller can print it or fail on it. Inventing an

package/types/engine/frontmatter-lint.d.mts

@@ -112,10 +112,10 @@ export function lintFrontmatter(index: object, { schemas, vocabulary, packs, emi
  * declaration and both would otherwise be reported as unknown on every note
  * that uses them.
  *
- * - `folder` — the compendium folder the document is filed in.
+ * - `packFolder` — the folder note the document is filed in.
  * - `pack` — which compendium of the note's document type receives it, for a
  *   repository shipping several.
- * - `archetype` — the archetype flag, read for any note by the walk itself.
+ * - `templatePriority` — which of several templates the Create dialog offers.
  * - `kbcat` — the knowledgebase category a note is grouped under.
  *
  * `kbcat` is the one that matters for what this check *is*. **The pack build is

package/types/engine/frontmatter.d.mts

@@ -26,44 +26,33 @@ export function sohlField(fm: object | null | undefined, key: string, defaultVal
  * `relations` and a projectile's impact die — because each validates a *shape
  * spread over several keys* rather than coercing one scalar.
  *
- * That was equivalent while every note authored inside the block, and stopped
- * being so once a note may author at `sohl.system.<to>` instead: {@link
- * sohlField} sees `sohl.<key>` and the top level, never inside `sohl.system`.
- * So those five read as unset and shipped their empty value — a missing
- * `subType` is a thrown build error, and the other four ship empty in silence,
- * which is the failure class the passthrough exists to prevent.
+ * {@link sohlField} sees `sohl.<key>` and the top level, never inside
+ * `sohl.system`, so this reads the destination first: a note may author at
+ * `sohl.system.<to>`, and a reader that could not see it would ship the
+ * field's empty value in silence.
  *
  * The **destination wins**, matching every other field's resolution order.
  *
- * `legacyKey` is for the one pair whose two positions are spelled differently:
- * a projectile authors `impact.die` and stores `impactBase.die`, so the reader
- * has to be told both. It is the same split `FieldSpec.name`/`legacyKey` makes,
- * for the same reason — one name cannot key two positions.
- *
- * `shared` is the field's declared shared source, and it completes the order the
- * three other positions are two thirds of. A field whose source is a path into
- * `data:` is authored there by the specification's own mapping tables, and a
- * reader that knew the destination, the block and the top level alone skipped
- * straight past the container: every authored value read as unset, and the
- * document shipped the field's default with nothing said. It sits **between**
- * the block and the top level, exactly where
- * {@link module:engine/system-block.resolveFieldValue} puts it — the block is the
- * position a tree still writes and wins while it does, and the bare top-level
- * key is the spelling `data:` gathered the fact off.
+ * `name` is for the one pair whose two positions are spelled differently: a
+ * projectile authors `impact.die` and stores `impactBase.die`, so the reader
+ * has to be told both.
+ *
+ * `shared` is the field's declared shared source when it is a path into
+ * `data:`. Such a field is authored in that container and nowhere else, so the
+ * block and the top level are not consulted.
  *
  * @param {object} fm - The note's frontmatter.
  * @param {string} to - The key at the destination, dotted for a nested one.
  * @param {any} [defaultValue] - What an unauthored field reads as.
  * @param {object} [options] - Options.
- * @param {string} [options.legacyKey] - The key the block still carries, when
- *   it is not spelled `to`. Defaults to `to`.
+ * @param {string} [options.name] - The key the block carries, when it is not
+ *   spelled `to`. Defaults to `to`.
  * @param {string} [options.shared] - The field's declared shared source, when it
- *   is a path into a container (`data.relations`). Omitted by a field whose
- *   shared position is the note's top level, which `sohlField` already reads.
+ *   is a path into a container (`data.relations`).
  * @returns {any} The value.
  */
-export function sohlSystemField(fm: object, to: string, defaultValue?: any, { legacyKey, shared }?: {
-    legacyKey?: string | undefined;
+export function sohlSystemField(fm: object, to: string, defaultValue?: any, { name, shared }?: {
+    name?: string | undefined;
     shared?: string | undefined;
 }): any;
 /**
@@ -76,9 +65,6 @@ export function sohlSystemField(fm: object, to: string, defaultValue?: any, { le
  * so absent frontmatter must resolve to `null` — coercing it to `0` would ship
  * every item as an uncapped charge-user.
  *
- * A legacy `usesCharges` flag in authored frontmatter is ignored: it was inert
- * and has been dropped from the schema.
- *
  * @param {object} fm - The item frontmatter.
  * @returns {{value: number|null, max: number|null}} The persisted charges block.
  */
@@ -108,7 +94,7 @@ export function resolveCharges(fm: object): {
  */
 export function resolveSkillAptitudes(fm: object, ctx?: string): Record<string, number>;
 /**
- * Resolve an affiliation's `relation` map — the shortcode of another
+ * Resolve an affiliation's `relations` map — the shortcode of another
  * affiliation → this one's standing toward it.
  *
  * An unrecognized standing would fail the schema's `choices` validation at load
@@ -159,20 +145,8 @@ export function parseValueDesc(raw: unknown): Array<{
  *
  * `data.packFolder` is a folder note's **address**
  * (`folder-poisonsandtoxins`), resolved through the address index the whole
- * build shares. The `folder:` Foundry-id spelling this function once read
- * beside it, and the per-pack `*-folders.yaml` that id was resolved against,
- * are retired together — a note declaring `folder:` is refused by
- * {@link module:engine/folder-notes.assertNoDeclaredFolder} rather than
- * reaching here, so there is no second source for a value to come from.
- *
- * **`packFolder` was a path for one release** (`Possessions/Misc_Gear/Cooking`)
- * and is an address now. A path encoded the hierarchy *in the value*, so
- * reparenting a folder made every note naming it wrong — a structural edit
- * became a corpus-wide rewrite. An address is stable under reparenting, which
- * is exactly why a note is addressed by `(type, shortcode)` and never by
- * `file.path`. The path form is **removed rather than deprecated**: it had no
- * authors to migrate, which is the whole reason the change was cheap enough to
- * make.
+ * build shares. An address is stable under reparenting, which is exactly why a
+ * note is addressed by `(type, shortcode)` and never by `file.path`.
  *
  * @param {object|null|undefined} fm - Parsed frontmatter.
  * @returns {{value: string|null, isAddress: boolean}} The authored value, and

package/types/engine/generate.d.mts

@@ -58,7 +58,7 @@ export function compilerFor(docType: string, system?: string | null): Function |
  * @param {string} type - The note's content type.
  * @returns {{document: string|null, art: readonly string[]}|null} What the type
  *   compiles into and the art it carries there, or `null` where no claim can be
- *   made — a retired type, which is reported as retired instead.
+ *   made.
  */
 export function emittedArtFor(type: string): {
     document: string | null;

package/types/engine/helpers.d.mts

@@ -52,7 +52,7 @@ export function parseMarkdownFile(filePath: string, { addressContext }?: {
  *
  * The rule 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
+ * the corpus is read by more than {@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
@@ -130,12 +130,11 @@ export function walkMarkdownTree(rootDir: string, { skipDirectories, addressCont
  * The template priority a note states, for a system that treats an unstated one
  * as "not a template" rather than as an authoring error.
  *
- * 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.
+ * Reads exactly the positions {@link resolveTemplatePriority} reads, 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.
@@ -143,7 +142,6 @@ export function walkMarkdownTree(rootDir: string, { skipDirectories, addressCont
  * @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: object, label: string, { block }?: {
     block?: string | undefined;
@@ -158,23 +156,21 @@ export function statedTemplatePriority(fm: object, label: string, { block }?: {
  *                silently assumed.
  *
  * 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.
+ * first — the specified home — then the system block and the top level.
  *
  * @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|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.
+ * @throws {Error} When the property is absent or is not a number/null.
  */
 export function resolveTemplatePriority(fm: object, label: string, { block }?: {
     block?: string | undefined;
 }): number | undefined;
 /**
  * The value a document's `system.templatePriority` carries, from the required
- * `templatePriority` frontmatter (`archetype` is the legacy spelling).
+ * `templatePriority` frontmatter.
  *
  * A **schema field**, so the tri-state is written out in full rather than
  * expressed by a key's presence: a number is a template at that priority, and
@@ -211,15 +207,11 @@ export function makeFilename(name: string, id: string): string;
  * and nothing else, and because the default a caller applies to an unset one is
  * domain-specific — actors default differently from items, and gear differently
  * again — so each compiler owns its default and applies it with **nullish**
- * coalescing: `resolveImg(fm.img) ?? <default>`. Not `||`, which would collapse
- * a deliberate blank back into the default.
+ * coalescing: `resolveImg(fm.img) ?? <default>`.
  *
- * **Two empties, and they mean opposite things.** `null` — or an absent key,
- * which reaches here as `undefined` — means _unset_: the note names no art and
- * the caller's default applies. `""` means _blank on purpose_: the note names
- * no art **and wants none**, so no default may replace it. Both come back
- * distinguishable, `null` and `""` respectively, and neither is invented from
- * the other.
+ * `null` — or an absent key, which reaches here as `undefined` — means _unset_:
+ * the note names no art and the caller's default applies. An empty string is
+ * not a pathname and is refused like any other value that names no file.
  *
  * **`title` does not follow this rule**, and must not be made to. On a
  * `type: affiliation` note `title` is a declared item field with its own
@@ -242,11 +234,11 @@ export function makeFilename(name: string, id: string): string;
  * @param {string | null | undefined} raw - The pathname from frontmatter.
  * @param {{assetRoot: string|null}} [config] - The resolved build configuration.
  *   Defaults to this repository's.
- * @returns {string | null} the Foundry-relative path; `""` for a deliberate
- *   blank, and `null` when the note names no art at all.
- * @throws {Error} When no Foundry address can be derived — a `documentation`
- *   package, which Foundry installs nothing of, or a pathname naming a package
- *   this build declares no relationship with.
+ * @returns {string | null} the Foundry-relative path, and `null` when the
+ *   note names no art at all.
+ * @throws {Error} When the pathname is empty, or when no Foundry address can
+ *   be derived — a `documentation` package, which Foundry installs nothing of,
+ *   or a pathname naming a package this build declares no relationship with.
  */
 export function resolveImg(raw: string | null | undefined, config?: {
     assetRoot: string | null;
@@ -269,10 +261,8 @@ export function resolveName(fm: object | null | undefined, defaultValue?: string
  * every v14 build and so left all shipped content permanently eligible for
  * every v14 migration.
  *
- * **Read from the configuration, not from the shipped manifest.** It used to
- * open `paths.packageManifest` and take `compatibility.minimum` out of it,
- * because the configuration had no way to state the fact. Now that it does, the
- * manifest is generated *from* the configuration — so reading it back would be
+ * **Read from the configuration, not from the shipped manifest.** The
+ * manifest is generated *from* the configuration, so reading it back would be
  * a round trip through an artifact that need not exist yet: `build:db` can run
  * before the manifest is written.
  *
@@ -293,9 +283,7 @@ export function supportedCoreVersion(config?: {
 /**
  * Default `_stats` block for compiled compendium entries.
  *
- * Every stamped identity is configuration: four compilers used to pass
- * the same frozen `"0.6.0"` literal, and `systemId` / `lastModifiedBy` were
- * written into this function. `coreVersion` alone is *not* configuration — it
+ * Every stamped identity is configuration. `coreVersion` alone is *not* configuration — it
  * comes from {@link supportedCoreVersion}, the configured Foundry floor,
  * so a document never claims to predate the migrations that would rewrite it.
  *
@@ -344,11 +332,9 @@ export function statsForPack(packSystem: string | null | undefined, config?: obj
 /**
  * The `_stats` block every compiler stamps on an entry it emits, built once.
  *
- * Each compiler used to hoist `const STATS = buildStats()` at module scope,
- * which read the shipped package manifest the moment the module was imported —
- * so importing a compiler required a manifest to exist even when nothing was
- * going to be compiled. Deferred to first use and memoised here, the
- * cost and the identity are what they always were; only the moment moved.
+ * Built on first use and memoised, not at module scope: building it reads the
+ * shipped package manifest, and importing a compiler must not require a
+ * manifest to exist when nothing is going to be compiled.
  *
  * @returns {object} The default `_stats` block, shared by every compiler.
  */
@@ -364,10 +350,7 @@ export function defaultStats(): object;
  * would otherwise address every one of them as the first. A note whose
  * declaration is unroutable is indexed against the conventional name and left
  * for the compile pass to report — the index has no business failing a build,
- * and the pass fails it with a far better message. The one exception is a
- * **retired** content type: this walk is the first to see every
- * note together with its path, and unlike an unroutable declaration there is
- * no pass that would ever claim such a note and report it.
+ * and the pass fails it with a far better message.
  *
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [router] - The pack router. Supplied by the calling pass so

package/types/engine/homepage.d.mts

@@ -25,8 +25,7 @@ export function isHomepage(fm: object | null | undefined): boolean;
  *
  * Each finding carries the `locator` key to position it at, because the two
  * things that would resolve one — the raw note text and the position helper —
- * belong to the caller. This mirrors {@link module:engine/retired-fields},
- * whose retired-field messages are likewise positioned by whoever reports them.
+ * belong to the caller.
  *
  * **A refused field must be one the note *wrote*.** `resolveNoteId` fills
  * `fm.id` **in place** so every downstream reader sees one derived value —
@@ -134,8 +133,7 @@ export function homepageTitle(fm: object | null | undefined, config: object): st
  *
  * The note's own, plus the two derived values every emitted page carries: the
  * resolved `title`, and the package the build derived — no note declares one
- * (`package:` is retired) and the theme's breadcrumb partial reads
- * `.Params.package`.
+ * and the theme's breadcrumb partial reads `.Params.package`.
  *
  * **No `url` and no `slug`.** Hugo publishes the `home` kind at `baseURL`,
  * whose path is already where the package is served, so the page has no
@@ -144,8 +142,7 @@ export function homepageTitle(fm: object | null | undefined, config: object): st
  *
  * An authored `aliases` is dropped for the same reason it is on every other
  * page: Hugo reads it as URL redirects, so passing it through would publish a
- * redirect stub at each one. The field is retired and refused before a
- * build reaches here, which makes this a guard rather than a working path.
+ * redirect stub at each one.
  *
  * `related` is derived like every other page's — what links to the homepage
  * is a fact about the rest of the tree — so an authored value is dropped and
@@ -251,10 +248,6 @@ export const HOMEPAGE_DESTINATION: string;
  * closed vocabulary, so repeating that judgement per type would be a second
  * answer to one question.
  *
- * `aliases` is deliberately not in the class: it is a **retired** field, refused
- * on every note whatever its type, so it is answered there rather than
- * here.
- *
  * @type {ReadonlyMap<string, string>}
  */
 export const HOMEPAGE_REFUSED_FIELDS: ReadonlyMap<string, string>;