@heroiclands/package-build 20.3.1 → 20.5.0

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

@@ -2,7 +2,7 @@
  * Every `{#anchor}` a note declares on a heading.
  *
  * **Read from the content index's reader, not a second one.** This module kept
- * its own until #243, and the two disagreed: it matched `{#([a-z0-9-]+)}` while
+ * its own, and the two disagreed: it matched `{#([a-z0-9-]+)}` while
  * {@link module:engine/content-index.collectAnchors} matches `{#([^}]+)}`, so
  * an anchor with a capital in it — `{#CalendarFormat}` — existed for the index
  * and for the compiler and did not exist for the link checker. Nothing links to
@@ -21,7 +21,7 @@ export function anchorsOf(body: string): Set<string>;
  * Read a content tree into the index a link resolves against.
  *
  * **The corpus comes from the content index, not from a walk of this module's
- * own** (#243). Every pass used to answer "which files are the content?" for
+ * own**. Every pass used to answer "which files are the content?" for
  * itself and throw the answer away; this one now reads
  * {@link module:engine/content-index.indexRecordsFor}, which is the same
  * derivation the published artifact and the compilers are driven from. So a
@@ -29,7 +29,7 @@ export function anchorsOf(body: string): Set<string>;
  * anchors it resolves against are the ones every other pass will emit — rather
  * than a second derivation that agrees with them only by inspection. That was
  * not hypothetical: this module carried its own anchor reader until the anchor
- * half of #243, and the two disagreed about which anchors existed.
+ * anchor half, and the two disagreed about which anchors existed.
  *
  * **The file is opened for its bytes and nothing else.** The index deliberately
  * carries no note *body*, and a link lives in the body — so each note is read
@@ -49,7 +49,7 @@ export function anchorsOf(body: string): Set<string>;
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
  * @param {object} [opts.config] - The resolved build configuration, whose
- *   fetched dependency indexes foreign addresses resolve through (#239), and
+ *   fetched dependency indexes foreign addresses resolve through, and
  *   whose `contentPackage` every local address is built from. Omitted, the
  *   ambient configuration is resolved and no cross-package address resolves.
  * @param {readonly string[]} [opts.skipDirectories] - The walk's scope, passed
@@ -87,13 +87,13 @@ export function buildLinkIndex(contentBase: string, { config, skipDirectories, s
  * **What is checkable, stated plainly.** Only an address into this site is, and
  * only against facts this build already holds:
  *
- * - A **retired content type** in the path. The engine knows what used to exist
+ * - A **retired content type** in the path. The engine knows the retired names
  *   and what replaced it, so this is a fact rather than a guess — and it is
  *   exactly the SoHL defect.
  * - A **hardcoded absolute URL** into this package's own prefix, or into one a
  *   a fetched index names. Every one of them has a better form to write, which
  *   is why every one is reported — including a bare `/<package>/`, which names
- *   another package's landing (#87).
+ *   another package's landing.
  *
  *   That last case was exempt until the better form was identified, on the
  *   reasoning that a landing is in no link manifest so nothing could resolve it.
@@ -133,7 +133,7 @@ export function auditHomepageLinks(index: ReturnType<typeof buildLinkIndex>): Ar
  *
  * **How the link is *written* is a separate finding from where it points**, and
  * the two are kept apart because the corrections differ. An unlabelled link
- * (#180) has to become `[[type-shortcode|Text]]`; a labelled one whose target
+ * has to become `[[type-shortcode|Text]]`; a labelled one whose target
  * resolves nowhere has a shortcode to fix. Reporting a bare `[[Name]]` as a
  * dead address would send an author hunting for a note that was never named.
  *
@@ -145,7 +145,7 @@ export function auditHomepageLinks(index: ReturnType<typeof buildLinkIndex>): Ar
  *   carries a `reason` from {@link LINK_FINDING_REASONS} —
  *   `"not-an-address"`, `"unknown-type"`, `"ambiguous"` (with the claiming
  *   `packages`), or `"unresolved"` — and every one of them is an **error**:
- *   the three resolvers agree on severity for every class (#184).
+ *   the three resolvers agree on severity for every class.
  */
 export function auditLinks(index: ReturnType<typeof buildLinkIndex>): {
     deadAnchors: object[];

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

@@ -21,7 +21,7 @@ export function isValidShortcode(value: unknown): boolean;
  * @param {object} [opts.config] - The resolved build configuration, which the
  *   corpus is derived against.
  * @param {readonly object[]} [opts.records] - Index records the caller already
- *   derived, so a command reads one corpus (#243).
+ *   derived, so a command reads one corpus.
  * @param {object[]} [opts.problems] - Collects the notes the index cannot
  *   record, instead of letting one of them silence the lint.
  * @returns {{findings: Array<{file: string, line?: number, column?: number,
@@ -46,17 +46,19 @@ export function lintContentTree(contentBase: string, { skipDirectories, contentP
     keys: number;
 };
 /**
- * The shape every `shortcode` must match: ASCII letters and digits only.
+ * The shape every `shortcode` must match: lowercase ASCII letters and digits
+ * only.
  *
  * This is {@link ADDRESS_SEGMENT_PATTERN}, not a second copy of it. A shortcode
  * is the last segment of a canonical address, and the rule it is held to is the
  * rule *every* segment is held to — so the two are one constant rather than two
- * free to drift apart (#59). The name survives because this is where the rule
+ * free to drift apart. The name survives because this is where the rule
  * is applied to a note.
  *
- * Case is deliberately **not** constrained: hundreds of authored shortcodes are
- * mixed-case and collide with nothing, so tightening that is a separate
- * decision from this one.
+ * Case is held to that rule with no exception: two shortcodes differing only
+ * in case are two names nobody can tell apart, and `canonicalKey` lowercases
+ * every address it builds regardless, so a mixed-case shortcode addresses the
+ * same document as its lowercase spelling.
  *
  * A consuming system's *runtime* keeps its own copy of this pattern — it cannot
  * import a build-time dependency into shipped code — and is expected to pin the

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

@@ -9,13 +9,11 @@
  * repository's identity in the address space, not a switch — and never dead
  * configuration, whatever else changes.
  *
- * It was also, until #56, a **selector**: a note declared the same value in its
- * `package:` frontmatter and the compilers kept the ones that matched. Every
- * content tree is single-package — each is single-sourced in the repository that
- * ships it — so the field restated this constant once per note while a value
- * that matched nothing filtered the whole tree out in silence. That field is
- * retired and declaring it now fails the build; this value stays, here, where
- * it is declared once.
+ * It is not a **selector**. Every content tree is single-package — each is
+ * single-sourced in the repository that ships it — so a `package:` field on a
+ * note would restate this constant once per note, and a value matching nothing
+ * would filter the whole tree out in silence. That field is refused, and this
+ * value stays here, declared once.
  *
  * Stable across compilation targets. If this content were ever compiled for a
  * second game system, it would still be published as `sohl` — only the Foundry
@@ -36,7 +34,7 @@ export function contentPackage(): string;
  * here: a note is published under `sohl` and its documents are addressed as
  * `Compendium.sohl.<pack>.<Type>.<id>`. In `sohl-thalorna` the two differ
  * (`thalorna` vs `sohl-thalorna`), which is why they are separate values rather
- * than one — treating them as interchangeable is what #1498 was.
+ * than one — treating them as interchangeable is the mistake.
  *
  * Configured rather than read from the manifest so the link resolver stays
  * filesystem-free and unit-testable. `assertPackageIdMatchesManifestFile` in

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

@@ -73,34 +73,65 @@ export function selectRows(spec: object, docs: Array<ContentTableDoc>, self?: Co
  * @returns {string} The markdown table (no trailing newline).
  */
 export function renderContentTable(spec: object, rows: Array<ContentTableDoc>, linkable: (doc: ContentTableDoc) => boolean, self?: ContentTableDoc): string;
-export function expandContentTables(markdown: any, { docs, linkable, source, self, sqlTables, }?: {
-    docs?: never[] | undefined;
-    linkable?: (() => boolean) | undefined;
+/**
+ * Expand every fenced `dataview` and `sql` block in a markdown body.
+ *
+ * A block that cannot be honoured — malformed or unsupported — is left in the
+ * body verbatim and reported in `errors`, so the failure is visible in the
+ * output as well as on the console. Every other code fence, and every code
+ * span, is left alone (that is how the syntax is documented).
+ *
+ * A query that selects **no** note is an error unless the fence says
+ * `allow-empty`, which states that an empty table is the intended result.
+ *
+ * @param {string} markdown - The note body, frontmatter already stripped.
+ * @param {object} ctx
+ * @param {Array<ContentTableDoc>} ctx.docs - The searchable universe: every
+ *   content note the caller considers in scope.
+ * @param {(doc: ContentTableDoc) => boolean} [ctx.linkable] - Whether a note can
+ *   be linked to from a cell; defaults to never.
+ * @param {string} [ctx.source] - The note being expanded, for error reports.
+ * @param {ContentTableDoc} [ctx.self] - The note being expanded, as a searchable
+ *   doc: what a query's `this` reads.
+ * @param {object[]} [ctx.sqlTables] - This note's prepared `sql` results, in
+ *   document order, from
+ *   {@link module:engine/sql-tables.prepareSqlTables}. An `sql` directive with
+ *   no prepared result is an error: nothing here runs a query.
+ * @returns {{markdown: string, errors: Array<{source: string, directive: string,
+ *   reason: string, line: number, column?: number}>,
+ *   warnings: Array<{source: string, line: number, column: number,
+ *   reason: string}>, lineMap: Array<{line: number, generated: boolean}>}}
+ *   `lineMap` is parallel to the emitted lines and says which authored line
+ *   each came from, so a diagnostic about the expanded body can name an
+ *   authored position. An `errors` entry carries the 0-based line of the
+ *   directive that failed, for the same reason. `warnings` holds one entry per
+ *   `dataview` directive the body still authors.
+ */
+export function expandContentTables(markdown: string, { docs, linkable, source, self, sqlTables, }?: {
+    docs: Array<ContentTableDoc>;
+    linkable?: ((doc: ContentTableDoc) => boolean) | undefined;
     source?: string | undefined;
-    self?: undefined;
-    sqlTables?: undefined;
+    self?: ContentTableDoc | undefined;
+    sqlTables?: object[] | undefined;
 }): {
     markdown: string;
-    errors: ({
-        source: string;
-        directive: string;
-        reason: any;
-        line: number;
-        column: number;
-    } | {
+    errors: Array<{
         source: string;
         directive: string;
-        reason: any;
+        reason: string;
         line: number;
-        column?: undefined;
-    })[];
-    warnings: {
+        column?: number;
+    }>;
+    warnings: Array<{
         source: string;
         line: number;
         column: number;
         reason: string;
-    }[];
-    lineMap: any[];
+    }>;
+    lineMap: Array<{
+        line: number;
+        generated: boolean;
+    }>;
 };
 /**
  * One content note as a content build hands it to the expander: its parsed

package/types/engine/derived-fields.d.mts

@@ -0,0 +1,101 @@
+/**
+ * What a note authoring a derived key is told, in one place.
+ *
+ * Shared by every caller that can meet one, so an author meets the same
+ * sentence whichever runs first. It names the correction rather than only the
+ * fault, because "delete this" is not the fix here: the text is wanted, and
+ * there is somewhere it belongs.
+ *
+ * @param {string} key - The **whole key the note wrote**, from the region it
+ *   sits in down to the field: `sohl.system.docHtml`. Composed by the caller,
+ *   because only it knows where it found the value.
+ * @param {string} from - Where the compiler reads the value from, completing
+ *   "the compiler writes it from …". The declaration carries it.
+ * @param {string} [file] - The note's path, named in the message. Omit it where
+ *   the caller emits through a diagnostic, whose locator already starts the
+ *   line — repeating it prints the path twice.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function derivedMessage(key: string, from: string, file?: string): string;
+/**
+ * The derived keys a note actually writes, in declaration order.
+ *
+ * **Presence is the whole test**, as it is for a retired or a runtime-only
+ * field: an authored empty string is as much a claim on the key as prose is,
+ * and it is the same belief the message exists to correct. So the question is
+ * whether the path resolves to anything at all, never whether the value is a
+ * usable one.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {readonly {key: string, from: string}[]} [keys] - What the compiler
+ *   derives. A pass that derives nothing passes.
+ * @param {object} options - Options.
+ * @param {string} options.block - The system block to look in.
+ * @returns {{key: string, from: string}[]} The offending declarations.
+ */
+export function authoredDerivedKeys(fm: object | null | undefined, keys?: readonly {
+    key: string;
+    from: string;
+}[], { block }?: {
+    block: string;
+}): {
+    key: string;
+    from: string;
+}[];
+/**
+ * The same question asked of a `system` block directly.
+ *
+ * A note's own block is reached through {@link authoredDerivedKeys}, but it is
+ * not the only place an author writes one: an actor note's `items:` entries
+ * carry a `system:` overlay that is deep-merged onto the template verbatim,
+ * with no field declaration in the path at all. That overlay is a `system`
+ * block by every meaning except where it sits, and a `docHtml` written there
+ * ships exactly as one written on the item's own note.
+ *
+ * @param {Record<string, unknown>|null|undefined} data - The authored `system`
+ *   data.
+ * @param {readonly {key: string, from: string}[]} [keys] - What the compiler
+ *   derives.
+ * @returns {{key: string, from: string}[]} The offending declarations.
+ */
+export function derivedIn(data: Record<string, unknown> | null | undefined, keys?: readonly {
+    key: string;
+    from: string;
+}[]): {
+    key: string;
+    from: string;
+}[];
+/**
+ * Refuse a note that authors any key its compiler derives.
+ *
+ * Refused rather than reported, for the reason its two siblings are: the note
+ * is not compiled, so nothing it would have emitted reaches a pack, and each
+ * caller counts the refused note and emits a located diagnostic — a refusal is
+ * never a silent skip.
+ *
+ * The **first** offending key is thrown on. A note authoring two of them is one
+ * mistake with one fix, and the build stops on this note either way.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
+ *   could not be parsed.
+ * @param {readonly {key: string, from: string}[]} [keys] - What the compiler
+ *   derives.
+ * @param {object} options - Options.
+ * @param {string} options.block - The system block to look in.
+ * @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.
+ * @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 authors one.
+ */
+export function assertNoDerivedFields(fm: object | null | undefined, keys?: readonly {
+    key: string;
+    from: string;
+}[], { block, file, absPath }?: {
+    block: string;
+    file?: string | undefined;
+    absPath?: string | undefined;
+}): void;

package/types/engine/diagnostics.d.mts

@@ -115,7 +115,7 @@ export function positionInBody(body: string, offset: number, { bodyLine, bodyCol
  * same name answers when no top-level one is present — which is usually what a
  * reader wants, the key being unique in nearly every note. Pass `topLevel` where
  * it is not: `aliases` is both a retired top-level field and a **permitted**
- * `name.aliases` (#180), and a finding about the first must never open on the
+ * `name.aliases`, and a finding about the first must never open on the
  * second, which would tell an author to delete a field they are allowed to
  * write.
  *
@@ -232,7 +232,7 @@ export function yamlKeyPath(field: string): Array<string | number>;
  * the same name is legal in two regions — `data.weight` and a top-level
  * `weight` are different keys, and a search finds whichever comes first.
  *
- * So this is the located form for the closed regions (#128). It reuses
+ * So this is the located form for the closed regions. It reuses
  * {@link positionOfYamlPath} rather than repeating its parse, which is what
  * keeps a finding about `data.weight` pointing at `data.weight`.
  *

package/types/engine/document-subtypes.d.mts

@@ -58,7 +58,7 @@ export function defineDocumentSubtypes({ system, block, types }?: {
  * {@link mapsNoteType}, {@link noteTypesFor}'s consumers and
  * {@link systemOf} all arrive here. A note still spelling `armorgear` finds the
  * `armor` row, compiles into the `armorgear` document it always did, and keeps
- * the address it publishes at; only the *report* tells it to move (#78).
+ * the address it publishes at; only the *report* tells it to move.
  *
  * @param {DocumentSubtypeMap} map - The system's map.
  * @param {string|undefined} noteType - The note's declared `type`.
@@ -127,7 +127,7 @@ export function documentSubtype(map: DocumentSubtypeMap, noteType: string | unde
  * @property {string} [problem] - Why the reference names no document subtype.
  */
 /**
- * The document subtype a `(type, shortcode)` **reference** addresses (#140).
+ * The document subtype a `(type, shortcode)` **reference** addresses.
  *
  * A being's frontmatter names each embedded item by the *note's* type — the
  * vocabulary an author writes — while the predefined items it resolves against
@@ -164,7 +164,7 @@ export function documentSubtype(map: DocumentSubtypeMap, noteType: string | unde
  * retirement exists to stop.
  *
  * A **renamed** spelling is the opposite case and resolves normally, through
- * the same {@link currentType} every other lookup goes through (#78). It has to
+ * the same {@link currentType} every other lookup goes through. It has to
  * be this side as much as the note's own `type:`: the overwhelming majority of
  * the 31,000 occurrences of the old names are `(type, shortcode)` references
  * inside a being's `items:` list, so a window that resolved notes but not

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

@@ -8,7 +8,7 @@
  *
  * **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 #126's corpus
+ * 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.
@@ -19,7 +19,7 @@
 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 (#332).
+ * 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
@@ -42,7 +42,7 @@ export function readsRetiredTopLevel(field: FieldSpec, from: import("./system-bl
  *
  * The *position* is resolved by {@link resolveFieldValue} — `<system>.system`
  * first, then the legacy in-block key, then the declared shared source, then
- * the default (#58). The **coercion** is applied here, once, wherever the value
+ * 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.
@@ -54,12 +54,12 @@ export function readsRetiredTopLevel(field: FieldSpec, from: import("./system-bl
  *   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 (#305). A callback
+ *   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 (#332). The
+ *   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
@@ -78,7 +78,7 @@ export function readField(field: FieldSpec, fm: object, options?: {
  * every caller wants. A builder has one further question — *should the key be
  * written at all* — and it cannot be answered from the value: `null` from a
  * note and `null` from a declared default are the same value and opposite
- * facts (#329).
+ * facts.
  *
  * So the position rides back beside the value, resolved **once**. The
  * alternative is a builder that calls {@link resolveFieldValue} for the source
@@ -111,7 +111,7 @@ export function readFieldEntry(field: FieldSpec, fm: object, { block, onLegacyKe
  * The question {@link FieldSpec.omitWhenAbsent} turns on, asked of the
  * *position* rather than of the value — which cannot answer it, since a
  * declared `default: null` and an authored `null` are indistinguishable once
- * the value is in hand (#329).
+ * the value is in hand.
  *
  * `undefined` counts as absent whatever position reported it, because writing
  * the key then emits a value `JSON.stringify` drops — the key present in the
@@ -139,10 +139,10 @@ export function isAuthored(from: import("./system-block.mjs").FieldSource, value
  *   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 (#305).
+ *   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 (#332).
+ *   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 }?: {
@@ -166,8 +166,8 @@ export function authoredFields(fields: readonly FieldSpec[]): FieldSpec[];
  * The fields of a declaration a note may **never** write.
  *
  * The complement of {@link authoredFields} in the direction that matters: those
- * are the fields an author may write, these are the ones authoring is an error
- * (#330). Everything else in a declaration — a constant, a derived value — is
+ * are the fields an author may write, these are the ones authoring is an error.
+ * Everything else in a declaration — a constant, a derived value — is
  * simply not authored, which is a statement about the *builder* rather than
  * about the author, and says nothing about what happens if a note writes the
  * path anyway.
@@ -179,19 +179,19 @@ export function runtimeOnlyFields(fields: readonly FieldSpec[]): FieldSpec[];
 /**
  * @typedef {object} FieldSpec
  * @property {string} to - Dotted path in the emitted `system` block — and,
- *   since #58, the path a note authors the field at directly:
+ *   the path a note authors the field at directly:
  *   `<system>.system.<to>`.
  * @property {string} [name] - The **shared, top-level property this field draws
  *   from** when the note authors no value at `<system>.system.<to>`. Dotted for
  *   a path into a shared container (`data.portrait`), which is now the ordinary
- *   case: `data:` (#128) puts every type-specific fact under one.
+ *   case: `data:` puts every type-specific fact under one.
  *
- *   It used to mean "frontmatter key under `sohl:`", and that reading is the
+ *   Read as "frontmatter key under `sohl:`", that meaning is the
  *   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 (#58). The in-block position is
- *   still read, second, until #126 moves the corpus off it — keyed on
+ *   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.
  *
  *   Absent means the value is not authored at all — see `value`.
@@ -199,8 +199,8 @@ export function runtimeOnlyFields(fields: readonly FieldSpec[]): FieldSpec[];
  *   the system block** — the second position of the resolution order — when
  *   that is not `name`. Absent, the position is keyed on `name`.
  *
- *   The two were one property until #305, which held only while a field's
- *   shared source and its in-block key were the same word. `data:` (#128) ended
+ *   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"`
@@ -216,7 +216,7 @@ export function runtimeOnlyFields(fields: readonly FieldSpec[]): FieldSpec[];
  * @property {string} [topLevelMeans] - **What the note's top-level key of this
  *   name means instead** — declared only where it means something else, and
  *   stating it removes the shared top-level position from this field's
- *   resolution order (#218).
+ *   resolution order.
  *
  *   A field's `name` doubles as its identity and as the shared property it
  *   draws from, which is right wherever the two levels state the same quantity
@@ -243,7 +243,7 @@ export function runtimeOnlyFields(fields: readonly FieldSpec[]): FieldSpec[];
  *   if the two positions hold unrelated quantities then the *in-block* position
  *   is not the note-level field either, so a check about the note-level field
  *   reads past it. `engine/frontmatter-lint.mjs` resolves that through
- *   `collidingBlockKeys`. Read for the emitted field alone until #312, which is
+ *   `collidingBlockKeys`. Reading it for the emitted field alone is
  *   how an affiliation's office style came to answer for its page heading.
  * @property {string} [shape] - Human-readable shape, for documentation. Comes
  *   paired with `read` from one of the coercion constants below.
@@ -259,10 +259,9 @@ export function runtimeOnlyFields(fields: readonly FieldSpec[]): FieldSpec[];
  *   third step of {@link module:engine/system-block.resolveFieldValue}'s order,
  *   so the value resolves whichever region carries it. What it tells the
  *   author-facing surfaces is which of the two is the field's *home*, so a
- *   message about it names `img` rather than sending an author to `sohl.img`
- *   (#142).
+ *   message about it names `img` rather than sending an author to `sohl.img`.
  * @property {"string"|"number"|"boolean"|"list"|"map"} [kind] - The value's
- *   shape, for the frontmatter linter (#19). Distinct from `shape`, which is
+ *   shape, for the frontmatter linter. Distinct from `shape`, which is
  *   prose for a reader, and from `read`, which is what the compiler does: a
  *   field may declare `kind` without changing a byte of what it emits, and
  *   several do — `weight` is coerced leniently but is still a number, and
@@ -275,7 +274,7 @@ export function runtimeOnlyFields(fields: readonly FieldSpec[]): FieldSpec[];
  * @property {any|((fm: object) => any)} [value] - For a field with no `name`:
  *   the constant, or a function deriving it from the frontmatter.
  * @property {boolean} [omitWhenAbsent] - **The key is left out entirely when
- *   the note does not carry the field** (#329), rather than written from a
+ *   the note does not carry the field**, rather than written from a
  *   declared default.
  *
  *   Every other field answers absence with a value: an unauthored `weight` is
@@ -310,7 +309,7 @@ export function runtimeOnlyFields(fields: readonly FieldSpec[]): FieldSpec[];
  *   which the generated reference states in the field's own row.
  * @property {string} [runtimeOnly] - **What the field holds once play has
  *   started** — declared on a field the *document* writes for itself, which no
- *   note may author (#330).
+ *   note may author.
  *
  *   A schema declares plenty of fields a compiled document has no business
  *   carrying: an affliction's `onsetDate` is the world time its onset fired
@@ -404,7 +403,7 @@ export const BLANK_IS_DEFAULT: Readonly<{
 export type FieldSpec = {
     /**
      * - Dotted path in the emitted `system` block — and,
-     * since #58, the path a note authors the field at directly:
+     * the path a note authors the field at directly:
      * `<system>.system.<to>`.
      */
     to: string;
@@ -412,14 +411,14 @@ export type FieldSpec = {
      * - The **shared, top-level property this field draws
      * from** when the note authors no value at `<system>.system.<to>`. Dotted for
      * a path into a shared container (`data.portrait`), which is now the ordinary
-     * case: `data:` (#128) puts every type-specific fact under one.
+     * case: `data:` puts every type-specific fact under one.
      *
-     * It used to mean "frontmatter key under `sohl:`", and that reading is the
+     * Read as "frontmatter key under `sohl:`", that meaning is the
      * 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 (#58). The in-block position is
-     * still read, second, until #126 moves the corpus off it — keyed on
+     * 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.
      *
      * Absent means the value is not authored at all — see `value`.
@@ -430,8 +429,8 @@ export type FieldSpec = {
      * the system block** — the second position of the resolution order — when
      * that is not `name`. Absent, the position is keyed on `name`.
      *
-     * The two were one property until #305, which held only while a field's
-     * shared source and its in-block key were the same word. `data:` (#128) ended
+     * 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"`
@@ -450,7 +449,7 @@ export type FieldSpec = {
      * - **What the note's top-level key of this
      * name means instead** — declared only where it means something else, and
      * stating it removes the shared top-level position from this field's
-     * resolution order (#218).
+     * resolution order.
      *
      * A field's `name` doubles as its identity and as the shared property it
      * draws from, which is right wherever the two levels state the same quantity
@@ -477,7 +476,7 @@ export type FieldSpec = {
      * if the two positions hold unrelated quantities then the *in-block* position
      * is not the note-level field either, so a check about the note-level field
      * reads past it. `engine/frontmatter-lint.mjs` resolves that through
-     * `collidingBlockKeys`. Read for the emitted field alone until #312, which is
+     * `collidingBlockKeys`. Reading it for the emitted field alone is
      * how an affiliation's office style came to answer for its page heading.
      */
     topLevelMeans?: string | undefined;
@@ -511,13 +510,12 @@ export type FieldSpec = {
      * third step of {@link module :engine/system-block.resolveFieldValue}'s order,
      * so the value resolves whichever region carries it. What it tells the
      * author-facing surfaces is which of the two is the field's *home*, so a
-     * message about it names `img` rather than sending an author to `sohl.img`
-     * (#142).
+     * message about it names `img` rather than sending an author to `sohl.img`.
      */
     shared?: boolean | undefined;
     /**
      * - The value's
-     * shape, for the frontmatter linter (#19). Distinct from `shape`, which is
+     * shape, for the frontmatter linter. Distinct from `shape`, which is
      * prose for a reader, and from `read`, which is what the compiler does: a
      * field may declare `kind` without changing a byte of what it emits, and
      * several do — `weight` is coerced leniently but is still a number, and
@@ -539,7 +537,7 @@ export type FieldSpec = {
     value?: any | ((fm: object) => any);
     /**
      * - **The key is left out entirely when
-     * the note does not carry the field** (#329), rather than written from a
+     * the note does not carry the field**, rather than written from a
      * declared default.
      *
      * Every other field answers absence with a value: an unauthored `weight` is
@@ -577,7 +575,7 @@ export type FieldSpec = {
     /**
      * - **What the field holds once play has
      * started** — declared on a field the *document* writes for itself, which no
-     * note may author (#330).
+     * note may author.
      *
      * A schema declares plenty of fields a compiled document has no business
      * carrying: an affliction's `onsetDate` is the world time its onset fired