@heroiclands/package-build 20.3.1 → 20.4.0

package/types/engine/helpers.d.mts

@@ -5,7 +5,7 @@
  * `body` is the trimmed raw markdown after the frontmatter block, and
  * `description` is `body` rendered to HTML. `bodyLine` / `bodyColumn` are the
  * 1-based **file** position of the body's first character, which is what turns
- * an offset within `body` into a position a diagnostic can name (#17) — see
+ * an offset within `body` into a position a diagnostic can name — see
  * {@link positionInBody}. If the file has no frontmatter block, returns
  * `{ frontmatter: null, body: "", description: "" }` with a warn log, and no
  * position: there is no body to have one.
@@ -28,13 +28,13 @@ export function parseMarkdownFile(filePath: any): {
  * Yields `{ frontmatter, body, description, file, absPath, bodyLine,
  * bodyColumn }` for each match — the last two from
  * {@link parseMarkdownFile}, so a caller can report a position inside the
- * body as a position in the file (#17).
+ * body as a position in the file.
  * Silently skips directories that don't exist.
  *
  * Directory names in `skipDirectories` are ignored wherever they appear. The
  * walk itself knows nothing about what they mean: `Templates/` is an Obsidian
  * templater convention this repository's vault happens to use, not a property
- * of a content tree, so it is configured rather than hard-coded (#1508).
+ * of a content tree, so it is configured rather than hard-coded.
  *
  * @param {string} rootDir - Root of the tree to walk.
  * @param {object} [opts]
@@ -44,7 +44,7 @@ export function parseMarkdownFile(filePath: any): {
 /**
  * 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
+ * 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
  * reads the content index instead is making the identical claim about which
@@ -68,7 +68,7 @@ export function assertStatedScope(skipDirectories: readonly string[] | undefined
  * 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
+ * over one tree, and the whole point 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.
  *
@@ -97,7 +97,7 @@ export function walkMarkdownTree(rootDir: any, { skipDirectories }?: {}): Genera
 }, void, unknown>;
 /**
  * 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).
+ * 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
@@ -119,7 +119,7 @@ export function statedTemplatePriority(fm: object, label: string, { block }?: {
 }): number | null;
 /**
  * Resolve the required `templatePriority` frontmatter for an Item/Actor entry
- * (the archetype contract, #604). The property is a nullable number that
+ * (the archetype contract). The property is a nullable number that
  * authors must state explicitly:
  *   - a number → the document is a template of that priority.
  *   - `null`   → the document is not a template.
@@ -128,7 +128,7 @@ export function statedTemplatePriority(fm: object, label: string, { block }?: {
  *
  * 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).
+ * finally the retiring `archetype` spelling in the same two places.
  *
  * @param {object} fm      Parsed frontmatter.
  * @param {string} label   Human-readable context for error messages.
@@ -143,8 +143,7 @@ export function resolveTemplatePriority(fm: object, label: string, { block }?: {
 }): number | undefined;
 /**
  * The value a document's `system.templatePriority` carries, from the required
- * `templatePriority` frontmatter (#126, sohl#1780, renamed off `archetype` by
- * #266 / sohl#1836).
+ * `templatePriority` frontmatter (`archetype` is the legacy spelling).
  *
  * 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
@@ -174,7 +173,7 @@ export function makeFilename(name: any, id: any): string;
  *
  * Content frontmatter (`img` / `portrait`) authors a single path that has to
  * work for Foundry, the knowledgebase, and the website. **Its first segment
- * says which package owns the file** (#331), and there are exactly three
+ * says which package owns the file**, and there are exactly three
  * answers:
  *
  * | Authored path starts with | Owner                 | Emitted              |
@@ -186,7 +185,7 @@ export function makeFilename(name: any, id: any): string;
  * So `icons/relic.svg` compiles to `systems/sohl/assets/icons/relic.svg` here
  * and to `modules/sohl-thalorna/assets/icons/relic.svg` in a module — the asset
  * root is derived from the configuration, and is the one place `systems/sohl`
- * is ever spelled (#1508). An authored
+ * is ever spelled. An authored
  * `systems/sohl/assets/icons/noun/shield.svg` is left exactly as written,
  * whichever package is compiling it.
  *
@@ -197,13 +196,13 @@ export function makeFilename(name: any, id: any): string;
  * `assets/artwork/`, so an authored `artwork/deity.webp` would have shipped
  * unprefixed: a 404 in Foundry, reported by nothing. That a package owns its
  * own tree is the fact; the directory names inside it are that package's
- * business (#331).
+ * business.
  *
  * **Off-install addresses pass through too**, which is the same rule rather
  * than a fourth: a URL, a `data:` URI, or a `/`-rooted path names something no
  * package owns. See {@link addressesAnotherPackage}.
  *
- * **`banner:` does not follow this rule, deliberately (#331).** It is not an
+ * **`banner:` does not follow this rule, deliberately.** It is not an
  * asset path inside a Foundry install at all: it reaches no compiled document,
  * and its only consumer is the Hugo theme, which prefixes a relative value with
  * `images/` and joins it onto `params.cdnBaseURL`. The two fields look alike
@@ -211,7 +210,7 @@ export function makeFilename(name: any, id: any): string;
  * the CDN serves — so they are documented apart rather than reconciled into one
  * rule that would be true of neither.
  *
- * **Two empties, and they mean opposite things (#218).** `null` — or an absent
+ * **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
@@ -230,7 +229,7 @@ export function makeFilename(name: any, id: any): string;
  * is `""` (`sohl/item-fields.mjs`), resolved from the very same shared top-level
  * key the site emitter reads as the page title — so `title: null` stringifies
  * into the compiled document as the literal `"null"`. One key, two destinations
- * that disagree about what empty means; see #218.
+ * that disagree about what empty means; see.
  *
  * This is translation only: the default for an unset path is domain-specific
  * (actors default differently from items, and gear differently again), so each
@@ -263,7 +262,7 @@ export function resolveName(fm: any, defaultValue?: string): any;
  * its migration shims on: a record stamped older than a shim is rewritten by it
  * on load. Every pack once shipped `coreVersion: "14"`, which sorts *below*
  * every v14 build and so left all shipped content permanently eligible for
- * every v14 migration (#1533).
+ * 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,
@@ -289,7 +288,7 @@ export function supportedCoreVersion(config?: {
 /**
  * Default `_stats` block for compiled compendium entries.
  *
- * Every stamped identity is configuration (#1508): four compilers used to pass
+ * 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
  * comes from {@link supportedCoreVersion}, the configured Foundry floor,
@@ -313,13 +312,12 @@ export function buildStats(systemVersion?: string, config?: {
     };
 }): object;
 /**
- * The `_stats` block for one pack, stamped with the system that pack is for
- * (#48).
+ * The `_stats` block for one pack, stamped with the system that pack is for.
  *
  * **`systemId` travels with `systemVersion`.** They are one decision, so where
  * one is omitted both are. Stamping a per-pack version against a package-wide
  * id would emit `systemId: sohl, systemVersion: 1.6.3` on HM3 documents — a
- * *plausible lie*, which is worse than the missing value #43 fixed, because
+ * *plausible lie*, which is worse than a missing value, because
  * nothing about it looks wrong.
  *
  * Resolution, in order:
@@ -358,11 +356,11 @@ export function defaultStats(): object;
  *
  * Each note's pack is resolved here, once, and stored on its index entry: a
  * UUID carries a pack name, so a repository shipping several packs of one type
- * (#1566) would otherwise address every one of them as the first. A note whose
+ * 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 (SoHL#1580): this walk is the first to see every
+ * **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.
  *
@@ -381,7 +379,7 @@ export function buildContentLinkIndex(contentBase: string, router?: object, { sk
  * target in the content tree. Every compiler funnels through this so the
  * diagnostic text and the leave-it-alone fallback are identical everywhere.
  *
- * Each report names the **file, line and column** the link sits on (#17), so
+ * Each report names the **file, line and column** the link sits on, so
  * it can be opened and fixed — and so two identical links on one note are
  * tellable apart. That needs `file` and the note's `bodyLine` / `bodyColumn`;
  * without them the diagnostic still reports, one field shorter, rather than
@@ -426,7 +424,7 @@ export function collectContentDocs(contentBase: string, { skipDirectories, confi
  * A table searches the whole tree, which is one package's notes and nothing
  * else — so there is no longer a package to scope on. It used to filter, back
  * when a tree could hold several packages' notes and `package:` said which was
- * which; that field is retired and the filter with it (#56).
+ * which; that field is retired and the filter with it.
  *
  * @param {string} body - The note's markdown body.
  * @param {object} ctx
@@ -439,7 +437,7 @@ export function collectContentDocs(contentBase: string, { skipDirectories, confi
  * @returns {{markdown: string, lineMap: Array<{line: number,
  *   generated: boolean}>}} The body with every table expanded, and where each
  *   emitted line came from — which is what lets a diagnostic about the
- *   expanded body name an authored position (#17).
+ *   expanded body name an authored position.
  * @throws {Error} When a query is malformed or unsupported — the note fails to
  *   compile rather than shipping a table-shaped hole. The error carries
  *   `position`, the directive's own line.
@@ -468,7 +466,7 @@ export function folderFilename(name: any, id: any): string;
  * `html: true` is long-standing and load-bearing — notes carry raw blocks — and
  * it is also why {@link module:engine/content-icons} exists rather than an
  * instruction to write `<i class="fa-solid …">` by hand: that would render on
- * the two HTML surfaces and be silently dropped by the third (#378).
+ * the two HTML surfaces and be silently dropped by the third.
  */
 export const md: import("markdown-it").MarkdownIt;
 export { slugify } from "./content-slug.mjs";

package/types/engine/homepage.d.mts

@@ -2,7 +2,7 @@
  * The file a homepage is written to, relative to the package's site root.
  *
  * Its **address**, flat at the package root, and stated in the page's own `url`
- * — the same separation every other page has since #181, where the directory
+ * — the same separation every other page has, where the directory
  * decides the Hugo section and the front matter decides the URL. Flat rather
  * than inside a `homepage/` section directory, because a homepage is not one of
  * a kind: a section holding exactly one page would publish a landing at
@@ -45,8 +45,8 @@ export function isHomepage(fm: object | null | undefined): boolean;
  * **A refused field must be one the note *wrote*.** `resolveNoteId` fills
  * `fm.id` **in place** so every downstream reader sees one derived value —
  * deliberately, and documented as such — and this ran over the same object, so
- * a homepage that authors no `id` was told to delete one that is not there
- * (#319). Since the caller already owns the raw note text, it also answers
+ * a homepage that authors no `id` was told to delete one that is not there.
+ * Since the caller already owns the raw note text, it also answers
  * which keys the note actually declared; without an answer every key in `fm`
  * counts, which is the old behaviour and right for a caller holding authored
  * frontmatter only.
@@ -70,19 +70,17 @@ export function checkHomepageAddressFields(fm: object | null | undefined, { isAu
     message: string;
 }>;
 /**
- * Require exactly one homepage note in a content tree (#52).
+ * Require exactly one homepage note in a content tree.
  *
  * "Exactly one" is two rules, and they are **one severity** because they are
  * one defect: a package whose front page is not the page a person chose.
  *
  * - _None_ and the package serves nothing at `/<package>/`. That is the failure
- *   #50 exists to prevent, and it is silent — the site build reports `wrote 0
+ *   this exists to prevent, and it is silent — the site build reports `wrote 0
  *   homepage(s)` and exits 0.
  * - _Two_ and it serves a page nobody chose. **This is a cardinality rule, and
- *   since #182 it is only that.** It used to rest on the fixed destination
- *   every homepage shared — the second overwrote the first — so the address
- *   rule enforced it as a side effect. A homepage is written at its own address
- *   now, so two of them publish two pages and collide over nothing; the
+ *   only that.** A homepage is written at its own address, so two of them
+ *   publish two pages and collide over nothing; the
  *   duplicate-address check catches only the pair that happen to share a
  *   shortcode, and says nothing at all about a `homepage-root` beside a
  *   `homepage-front`. Which of the two the redirect at `/<package>/` should
@@ -153,17 +151,17 @@ export function homepageTitle(fm: object | null | undefined, config: object): st
  *
  * The note's own, plus the derived values every emitted page carries: the
  * resolved `title`, the package the build derived — no note declares one
- * (`package:` is retired, #56) and the theme's breadcrumb partial reads
+ * (`package:` is retired) and the theme's breadcrumb partial reads
  * `.Params.package` — and its **address**.
  *
  * The address is stated as `url` for the same reason every other page states
- * one (#181): Hugo publishes a page where its file sits unless told otherwise,
+ * one: Hugo publishes a page where its file sits unless told otherwise,
  * and a homepage's file sits at the package's site root. `slug` is written
  * beside it because it is the last segment of that address and Hugo's own key
  * for one; it decides nothing while `url` is present, but a page carrying only
  * `url` would report a slug Hugo had inferred from the filename.
  *
- * **Site-root relative, and so carrying no package base** (#217), exactly as
+ * **Site-root relative, and so carrying no package base**, exactly as
  * `pageFrontmatter` states a content page's: Hugo resolves a `url`
  * against `baseURL`, whose path is already where the package is served, so a
  * stated base was written twice and published the landing at
@@ -172,7 +170,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 (#180) and refused before 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.
  *
  * @param {object} fm - The note's frontmatter.
@@ -252,14 +250,14 @@ export const HOMEPAGE_FIELDS: readonly import("./field-spec.mjs").FieldSpec[];
  */
 export const HOMEPAGE_SHORTCODE: string;
 /**
- * The top-level field a homepage refuses, and what it would decide (#53).
+ * The top-level field a homepage refuses, and what it would decide.
  *
- * **One field, where there used to be three.** `name` and `shortcode` were
+ * **One field rather than three.** `name` and `shortcode` are
  * refused because a page's URL derived from `name.full` while a homepage's
  * destination was fixed, so the address a `shortcode` computed named a page the
- * site build never wrote. A page's URL is its address now (#181) and a homepage
+ * site build never wrote. A page's URL is its address now and a homepage
  * publishes at its own, so both fields decide exactly what they decide
- * everywhere else and are permitted (#182).
+ * everywhere else and are permitted.
  *
  * `id` is untouched by that, and stays: it is the Foundry document id a
  * compendium UUID is built from, and a homepage compiles into no document.
@@ -272,7 +270,7 @@ export const HOMEPAGE_SHORTCODE: string;
  * package-build release.
  *
  * `aliases` is deliberately not in the class: it is a **retired** field, refused
- * on every note whatever its type (#180), so it is answered there rather than
+ * on every note whatever its type, so it is answered there rather than
  * here.
  *
  * @type {ReadonlyMap<string, string>}

package/types/engine/ids.d.mts

@@ -56,12 +56,12 @@ export function renamedTypeMessage(retired: string, current: string, where?: str
  * Item types are the open set — a new one is added whenever the system grows a
  * document type — so they are the **default** rather than an enumerated list. A
  * hand-maintained list is what made an entire content directory silently
- * unlinkable once (#1276); nothing to maintain, nothing to forget.
+ * unlinkable once; nothing to maintain, nothing to forget.
  *
  * The `docType` is the authority: it is a property of the *content type* and
  * holds however a repository names or splits its packs. The `pack` is the
  * conventional name only — a repository may rename its packs, or ship several
- * of one type (#1566), in which case the pack a particular note's document
+ * of one type, in which case the pack a particular note's document
  * lands in comes from `engine/pack-router.mjs` and is passed to
  * {@link compendiumUuid} explicitly. This module stays free of the
  * configuration so the link resolver above it can stay pure.
@@ -89,8 +89,8 @@ export function packForType(type: string): {
  * @param {string} id - The document's id.
  * @param {string} [packName] - The pack the document actually landed in, from
  *   the pack router. Supplied wherever the note is known, because a repository
- *   may ship several packs of one type and a UUID carries the pack name
- *   (#1566). Omitted only where there is no note to route — the conventional
+ *   may ship several packs of one type and a UUID carries the pack name.
+ * Omitted only where there is no note to route — the conventional
  *   name from {@link packForType} then stands in.
  * @returns {string} `Compendium.<packageId>.<pack>.<DocumentType>.<id>`
  */
@@ -105,8 +105,8 @@ export function compendiumUuid(packageId: string, type: string, id: string, pack
  */
 export function pageUuid(entryUuid: string, pageId: string): string;
 /**
- * Every content type that compiles into a Foundry `Scene` — a **map note**
- * (#1525). The three differ only in derived canvas defaults, which is the map
+ * Every content type that compiles into a Foundry `Scene` — a **map note**.
+ * The three differ only in derived canvas defaults, which is the map
  * compiler's business; everything else treats them alike.
  *
  * Declared in this leaf module because several passes that must not depend on
@@ -120,7 +120,7 @@ export const MAP_TYPES: ReadonlySet<string>;
 /**
  * The map subTypes, which differ only in the canvas defaults derived for them.
  *
- * They were three *types* until #174, which cost three entries in the pack
+ * As three *types* they would cost three entries in the pack
  * router, three in the claims set and three in every consumer's section config
  * — for one idea that the specification had always described as one type.
  *
@@ -137,8 +137,8 @@ export const MAP_SUBTYPES: readonly string[];
  * 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
+ * `doc` was the only member until. `place`, `lore` and `scenario` are in
+ * the published content format and are declared for validation, 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
@@ -157,7 +157,7 @@ export const JOURNAL_TYPES: ReadonlySet<string>;
  * building and not of the content: the same notes compiled by a different
  * repository belong to a different package. Baking the package into these
  * values is what made every link emitted by `sohl-thalorna` address the `sohl`
- * system (#1498) — correct here only by coincidence.
+ * system — correct here only by coincidence.
  *
  * @type {Readonly<Record<string, {pack: string, docType: string}>>}
  */
@@ -169,7 +169,7 @@ export const PACK_BY_TYPE: Readonly<Record<string, {
  * Content types that no longer exist, and what replaced each one.
  *
  * `character` and `creature` were retired in favour of the single `being` they
- * had always compiled into (SoHL#1580). They are recorded here rather than
+ * had always compiled into. They are recorded here rather than
  * simply deleted because deleting them is the one change that fails *quietly*:
  * every type not named in {@link PACK_BY_TYPE} falls through to the open item
  * set below, so a note or a link left on the old spelling would be routed to
@@ -193,7 +193,7 @@ export const RETIRED_TYPES: Readonly<Record<string, string>>;
  * 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
+ * So these retire in the three steps `package:` took, 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
@@ -201,7 +201,7 @@ export const RETIRED_TYPES: Readonly<Record<string, string>>;
  * 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, and why the other way round now.** #78 renamed
+ * **Why these three, and why this way round.** The specification renamed
  * `armorgear`, `concoctiongear` and `projectilegear` to `armor`, `concoction`
  * and `projectile`, on the argument that the suffix named the *SoHL document
  * subtype* a note compiled into rather than the thing the note is about. That

package/types/engine/index-records.d.mts

@@ -6,9 +6,9 @@
  * the machine that built the index, would differ between two checkouts of the
  * same tree, and would put someone's home directory in a published artifact. So
  * every pass that reads the index and then needs to open a note has to compose
- * the absolute form, and each of the readers converted for #243 had written its
+ * the absolute form, and each converted reader had written its
  * own `path.join(base, ...record.file.path.split("/"))`. Four copies of one
- * rule is what #243 exists to remove, so here it is once.
+ * rule is what this exists to remove, so here it is once.
  *
  * The split is on `"/"` rather than `path.sep` because the recorded path is
  * always POSIX — that is what makes the index identical on every platform.
@@ -54,7 +54,7 @@ export function isNoteRecord(record: Record<string, any>): boolean;
  * carry itself.
  *
  * `package` is the note's distribution unit — the configured `contentPackage`,
- * since a note declaring its own is a hard error (#56) — and it matches what
+ * since a note declaring its own is a hard error — and it matches what
  * the content-table expander puts on the same field, so a query reads the same
  * value from either. `file` namespaces the note's place in the tree, again
  * matching the expander's `file.*`.

package/types/engine/index.d.mts

@@ -11,6 +11,7 @@ export * as contentPackage from "./content-package.mjs";
 export * as notePackage from "./note-package.mjs";
 export * as retiredFields from "./retired-fields.mjs";
 export * as runtimeOnlyFields from "./runtime-only-fields.mjs";
+export * as derivedFields from "./derived-fields.mjs";
 export * as homepage from "./homepage.mjs";
 export * as noteSchemas from "./note-schemas.mjs";
 export * as noteVocabulary from "./note-vocabulary.mjs";
@@ -27,6 +28,7 @@ export * as siteBuild from "./site-build.mjs";
 export * as contentLint from "./content-lint.mjs";
 export * as contentCharset from "./content-charset.mjs";
 export * as contentIcons from "./content-icons.mjs";
+export * as contentHtml from "./content-html.mjs";
 export * as contentLinks from "./content-links.mjs";
 export * as webWikilinks from "./web-wikilinks.mjs";
 export * as contentTables from "./content-tables.mjs";

package/types/engine/item-compiler.d.mts

@@ -1,6 +1,6 @@
 /**
  * The description an item carries: a pointer to its **item doc**, the
- * JournalEntry the journals pass compiles this same body into (#1348).
+ * JournalEntry the journals pass compiles this same body into.
  *
  * The prose is not rendered into the item at all. Carrying it would duplicate
  * it onto every actor holding the item — 7.59 MB of copies across the actors
@@ -40,6 +40,22 @@ export class SystemItemCompiler extends BasePackCompiler {
      * @type {import("./document-subtypes.mjs").DocumentSubtypeMap|undefined}
      */
     static documentSubtypes: import("./document-subtypes.mjs").DocumentSubtypeMap | undefined;
+    /**
+     * The `system` keys this pass writes for itself, and where each is read
+     * from.
+     *
+     * A note authoring one is refused, because the compiler writes the key
+     * unconditionally: the authored value is overwritten, or survives as the
+     * wrong type in a shipped document. Declared here rather than named in the
+     * refusal so that a second system states its own — see
+     * {@link module:engine/derived-fields}.
+     *
+     * @type {readonly {key: string, from: string}[]}
+     */
+    static derivedSystemKeys: readonly {
+        key: string;
+        from: string;
+    }[];
     /**
      * The frontmatter block this pass reads, and the registry it addresses.
      *
@@ -60,7 +76,7 @@ export class SystemItemCompiler extends BasePackCompiler {
      * **Looked up, not inferred.** For every type this system declares, the
      * emitted subtype is the map's, so the note vocabulary and the document
      * vocabulary are two separately-stated things rather than one string
-     * written twice (#79).
+     * written twice.
      *
      * **A type the map does not name belongs to the consumer**, and its
      * registry entry is the declaration: a repository shipping an item type of
@@ -69,7 +85,7 @@ export class SystemItemCompiler extends BasePackCompiler {
      * subtype of. That is an authored statement in the consumer's own
      * configuration, not a coincidence inside this package's source — and
      * refusing it here would silently drop every document of a type this system
-     * has no opinion about (#7/#1563).
+     * has no opinion about.
      *
      * @param {object} fm - The note's frontmatter.
      * @returns {string} The document's `type`.
@@ -84,7 +100,7 @@ export class SystemItemCompiler extends BasePackCompiler {
      * Nothing by default, which is the honest position for a system that has
      * not said otherwise: a key written here lands on every document of every
      * type, so inventing one that the receiving DataModel does not declare
-     * would be a finding on the whole pack (#155).
+     * would be a finding on the whole pack.
      *
      * @param {object} fm - The note's frontmatter.
      * @param {object} at - What the pass already knows about this note.
@@ -111,7 +127,7 @@ export class SystemItemCompiler extends BasePackCompiler {
      * field for it and an undeclared `system` key is discarded at load without
      * a word.
      *
-     * **This is the one emitted key nothing else can check** (#283). A `system`
+     * **This is the one emitted key nothing else can check**. A `system`
      * key this pass invents is caught by the emitted-`system` check against the
      * receiving schema, but a flag is declared by no schema — so an omission
      * here is silent, and was: the Actor pass wrote the priority and this one

package/types/engine/item-docs.d.mts

@@ -3,7 +3,7 @@
  * addressed by the virtual `doc<type>` qualifier.
  *
  * Every item type, plus `macro` — a macro note's body documents the script the
- * note also compiles into a Macro (#1514), which is the same shape as an item
+ * note also compiles into a Macro, which is the same shape as an item
  * and its description: one note, two documents, the prose living in the
  * journals pack.
  *
@@ -59,7 +59,7 @@ export function itemDocEntryId(itemId: string): string;
  * happens to contain a link, which the runtime would then show verbatim.
  *
  * @param {string} packageId - The Foundry package shipping the journals pack.
- *   Supplied rather than assumed (#1498).
+ *   Supplied rather than assumed.
  * @param {string} itemId - The item note's `id` frontmatter.
  * @param {string} name - The item's name, used as the link's label. It shows
  *   only if the target ever fails to resolve, where a broken link naming the

package/types/engine/item-registry.d.mts

@@ -6,9 +6,9 @@
  * **Derived, never authored.** These are the keys of the consuming
  * repository's `itemBuilders` registry, so the whitelist and the builder table
  * are the same list and cannot drift apart. They already had: `trait` was
- * whitelisted long after the item type was retired (#651), with no builder
+ * whitelisted long after the item type was retired, with no builder
  * behind it, so every `type: trait` note passed the gate and then failed to
- * compile (#1504).
+ * compile.
  *
  * An accessor rather than a hoisted constant, so that importing this module
  * needs no configuration (#2).
@@ -21,7 +21,7 @@ export function itemTypes(): ReadonlySet<string>;
  *
  * Unreachable through the compiler — its whitelist *is* this registry's keys —
  * so a throw here means a caller invented a type. It names the type rather than
- * failing as an anonymous `is not a function` (#1504).
+ * failing as an anonymous `is not a function`.
  *
  * @param {string} type - The note's `type` frontmatter.
  * @param {string} [system] - The system compiling it, where a build declares
@@ -35,9 +35,9 @@ export function itemBuilder(type: string, system?: string): (fm: object) => obje
  * The frontmatter fields a type's registry entry declares, if any.
  *
  * Sparse by design: a type whose entry declares none compiles normally and is
- * simply undocumented (#22). What reads it is the `system`-block passthrough,
+ * simply undocumented. What reads it is the `system`-block passthrough,
  * which has to know which paths a declared field already writes before it
- * writes the rest (#58).
+ * writes the rest.
  *
  * @param {string} type - The item type.
  * @param {string} [system] - The system compiling it, where a build declares
@@ -51,7 +51,7 @@ export function itemFields(type: string, system?: string): readonly object[] | u
  *
  * Read from the consuming repository's `itemBuilders` registry, the same place
  * the type itself is declared, so a consumer's own type can bring art a
- * SoHL-owned table could never hold. Art used to be looked up in
+ * SoHL-owned table could never hold. Art is not looked up in
  * `sohl/default-item-art.mjs` instead: a type was configurable while its
  * default art was not, so a second consumer's items compiled only if every one
  * of its notes set `img:` (#7).

package/types/engine/journals.d.mts

@@ -29,7 +29,7 @@ export function splitPages(body: any, leadName?: string): {
  * on an identity alone:
  *
  * - **An anchor**, declared twice, has always collided.
- * - **A name**, repeated among the unanchored pages, collides since #268 took
+ * - **A name**, repeated among the unanchored pages, collides once
  *   the index out of the key. `MD024` with `siblings_only` already makes two
  *   sibling headings with the same text a lint error, so this is the same rule
  *   restated where the build can enforce it — a lint is a separate command, and
@@ -69,7 +69,7 @@ export function assertUniqueAnchors(rawPages: Array<{
  * doc's first page without having compiled it (see
  * {@link sohl.utils.packs.itemDocPointer}).
  *
- * **It takes no index** (#268). A page used to be keyed by position *and* name,
+ * **It takes no index**. Keying a page by position *and* name,
  * so inserting a heading renumbered every page after it and a re-import created
  * new pages beside the old ones — while nothing about those pages had changed.
  * The anchored case above never took one, and is the shape this now shares.
@@ -134,7 +134,7 @@ export function buildPages(rawPages: Array<object>, entryId: string, noteName: s
  * @param {object} [params.stats] - The `_stats` block to stamp. Passed by the
  *   caller because it is a property of the *pack* being written, not of the
  *   entry: a module may ship the same content for two systems, and each pack's
- *   documents record the system version they were built against (#48). A
+ *   documents record the system version they were built against. A
  *   caller with no pack in hand gets the package-wide block.
  * @returns {object} The JournalEntry document, keyed for the pack.
  */

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

@@ -8,7 +8,7 @@ export function isMapType(type?: string): boolean;
 /**
  * The canvas profile for a map subType.
  *
- * Keyed on the subType rather than the type since #174: every map note is
+ * Keyed on the subType rather than the type: every map note is
  * `type: map`, and which canvas it derives is the one thing the three
  * spellings ever decided.
  *
@@ -253,7 +253,7 @@ export const MAP_SUBTYPE_PROFILES: Readonly<Record<string, object>>;
  */
 export const DEFAULT_LEVEL_ID: "defaultLevel0000";
 /**
- * The behaviour types a map note may carry (issue #1525, v1).
+ * The behaviour types a map note may carry (v1).
  *
  * @type {ReadonlySet<string>}
  */