@heroiclands/package-build 9.0.0 → 10.0.1

package/sohl/items.mjs

@@ -41,7 +41,7 @@ import {
     resolveName,
     resolveImg,
     defaultStats,
-    withArchetypeFlag,
+    systemArchetype,
 } from "../engine/helpers.mjs";
 import { BasePackCompiler } from "../engine/base-compiler.mjs";
 // Per-type default art lives in one framework-free module shared with the
@@ -56,6 +56,15 @@ import { itemDocEntryId, itemDocPointer } from "../engine/item-docs.mjs";
 // them with are one table — the consuming repository's, not this package's
 // (#1504/#1563).
 import { itemTypes, itemBuilder, itemArt } from "../engine/item-registry.mjs";
+// Which Foundry Item subtype a note's `type` compiles into. Looked up in the
+// system's declared map, never inferred from the type itself (#79).
+import { documentSubtype, subtypeRow } from "../engine/document-subtypes.mjs";
+import { SOHL_DOCUMENT_SUBTYPES } from "./document-subtypes.mjs";
+// The note-level `sohl:` block: `sohl.system` onto the document's `system`
+// verbatim, and `sohl.img` / `sohl.effects` / `sohl.flags` overriding their
+// shared top-level forms for this system alone (#58).
+import { blockProperty, claimedPaths, mergeSystemData } from "../engine/system-block.mjs";
+import { itemFields } from "../engine/item-registry.mjs";
 
 /**
  * The description an item carries: a pointer to its **item doc**, the
@@ -86,11 +95,19 @@ function itemDescription(markdown, fm, name) {
 
 /**
  * Build the `system.*` fields shared by every item type:
- *   shortcode, actionDefs, notes, docHtml.
+ *   shortcode, archetype, actionDefs, notes, docHtml.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} description - The item's documentation pointer.
+ * @param {string} label - Human-readable context for error messages.
+ * @returns {object} The shared `system` fields.
  */
-function commonSystem(fm, description) {
+function commonSystem(fm, description, label) {
     return {
         shortcode: fm.shortcode,
+        // Required nullable number: a priority, or `null` for a document that
+        // is not an archetype (#126 / archetype contract #604).
+        archetype: systemArchetype(fm, label),
         actionDefs: Array.isArray(fm.actionDefs) ? fm.actionDefs : [],
         notes: "",
         docHtml: description || "",
@@ -105,10 +122,27 @@ function commonSystem(fm, description) {
 /*  Compiler                                                            */
 /* -------------------------------------------------------------------- */
 
+/**
+ * The system this pass compiles for — the block its notes write, and the
+ * registry its builders come from.
+ *
+ * Read from the map rather than spelled here, so the block name, the subtype
+ * map and the registry key are one statement (#58/#79).
+ *
+ * @type {string}
+ */
+const SYSTEM = SOHL_DOCUMENT_SUBTYPES.block;
+
 export class Items extends BasePackCompiler {
     static id = "items";
     static label = "item";
 
+    /**
+     * An Item **is** a system's data, so this pack takes only notes carrying
+     * this system's block (#58).
+     */
+    static requiresSystemBlock = true;
+
     /**
      * How many of each item type this pass wrote, for the summary. Every type
      * is present from the start so the tally reads as a census of the
@@ -121,11 +155,47 @@ export class Items extends BasePackCompiler {
     /**
      * Every content type that compiles into an item.
      *
+     * The whitelist is the consuming repository's `itemBuilders` keys (#1504),
+     * and the system's own map is a second filter on top of it: a type SoHL
+     * maps onto some *other* document class is not an item however a registry
+     * spells it, which is the "no wrongly-typed document" half of #79. A type
+     * the map does not name at all is left to the registry — see
+     * {@link Items#itemSubtype}.
+     *
      * @param {object} fm - The note's frontmatter.
      * @returns {boolean} True for a whitelisted item type.
      */
     selects(fm) {
-        return Boolean(fm.type) && itemTypes().has(fm.type);
+        if (!fm.type || !itemTypes().has(fm.type)) return false;
+        const row = subtypeRow(SOHL_DOCUMENT_SUBTYPES, fm.type);
+        return !row || row.document === "Item";
+    }
+
+    /**
+     * The Foundry Item subtype a note compiles into.
+     *
+     * **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).
+     *
+     * **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
+     * its own writes it once, in the `itemBuilders` table of its
+     * `package-build.config.yaml`, and that key is what the document is a
+     * 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 SoHL has
+     * no opinion about (#7/#1563).
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @returns {string} The document's `type`.
+     */
+    itemSubtype(fm) {
+        const declared = documentSubtype(SOHL_DOCUMENT_SUBTYPES, fm.type, fm, {
+            absPath: this.currentNote?.absPath,
+        });
+        return declared ?? fm.type;
     }
 
     /** An item is named by its own type in the log, not by "item". */
@@ -147,26 +217,52 @@ export class Items extends BasePackCompiler {
         const name = resolveName(fm);
         const description = itemDescription(markdown, fm, name);
         const id = fm.id;
+        const subType = this.itemSubtype(fm);
         const system = {
-            ...commonSystem(fm, description),
-            ...itemBuilder(type)(fm),
+            ...commonSystem(fm, description, `item "${name}"`),
+            ...itemBuilder(type, SYSTEM)(fm),
         };
+        // Whatever the note authors under `sohl.system`, at the DataModel's own
+        // paths. A path a declared field already writes is left to that field:
+        // its value came from the same authored place and went through the
+        // field's own coercion (#58).
+        mergeSystemData(system, fm, {
+            block: SYSTEM,
+            claimed: claimedPaths(itemFields(type, SYSTEM)),
+        });
+        this.reportUndeclaredSystemData(fm, SYSTEM, "Item", subType);
+        // And what *this* pass wrote on its own initiative — `shortcode`,
+        // `archetype`, `actionDefs`, `notes`, `docHtml` — which no field
+        // declaration states and so no other check can see (#155). Read off the
+        // assembled block, so a key added to `commonSystem` is checked without
+        // anyone remembering to list it.
+        this.reportEmittedSystemData(system, {
+            fm,
+            block: SYSTEM,
+            documentType: "Item",
+            subType,
+            type,
+            fields: itemFields(type, SYSTEM),
+        });
 
-        const effects = Array.isArray(fm.effects) ? [...fm.effects] : [];
-
+        const effects = blockProperty(fm, SYSTEM, "effects");
         const folderId = sohlField(fm, "folder", null);
         const folder = this.folderResolver(folderId);
 
         return {
             name,
-            type,
-            img: resolveImg(fm.img) || itemArt(type),
+            // The note's `type` addresses the builder and the default art —
+            // both registries are keyed by content type — while the document's
+            // own subtype comes from the system's map (#79).
+            type: subType,
+            img: resolveImg(blockProperty(fm, SYSTEM, "img")) || itemArt(type, SYSTEM),
             _id: id,
             system,
-            effects,
-            // `sohl.archetype` (required nullable number) drives
-            // `flags.sohl.docArchetype` (#640 / archetype contract #604).
-            flags: withArchetypeFlag(fm, fm.flags, `item "${name}"`),
+            effects: Array.isArray(effects) ? [...effects] : [],
+            // Whatever the note authors, and nothing else. `archetype` used to
+            // be spliced in here as `flags.sohl.docArchetype`; it is a schema
+            // field now and sits in `system` (#126).
+            flags: blockProperty(fm, SYSTEM, "flags", {}),
             _stats: this.stats,
             ownership: { default: 0 },
             folder,

package/sohl/note-schemas.mjs

@@ -122,23 +122,29 @@ const BEING_FIELDS = Object.freeze([
 ]);
 
 /**
- * A map note — `battlemap`, `localmap` or `regionalmap`, each compiled into a
+ * A map note — one type whose `battlemap` / `localmap` / `regionalmap`
+ * subType decides the derived canvas (#174). Compiled into a
  * Foundry Scene.
  *
  * The three differ only in derived canvas defaults, which is the map compiler's
  * business; their authored vocabulary is the same, so they share one
  * declaration rather than three copies that could drift.
  *
- * `image` is the one required field — the compiler refuses a map note without
- * it, since a scene with no background is not a map.
+ * `img` is the one required field — the compiler refuses a map note without it,
+ * since a scene with no background is not a map. It was spelled `image` and
+ * read from the `sohl:` block until #142; both spellings still compile, and the
+ * retired one is reported rather than refused.
  *
  * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
  */
 const MAP_FIELDS = Object.freeze([
     {
-        name: "image",
+        name: "img",
         ...STRING,
         required: true,
+        // Art is not system-specific — a Scene is a core Foundry document, and
+        // every other note type carries its `img` at the note's top level.
+        shared: true,
         describe: "The scene's background image.",
     },
     {
@@ -324,7 +330,5 @@ export const NOTE_SCHEMAS = Object.freeze({
     doc: DOC_FIELDS,
     macro: MACRO_FIELDS,
     being: Object.freeze([...BEING_FIELDS, ...PRESENTATION_FIELDS.being]),
-    battlemap: MAP_FIELDS,
-    localmap: MAP_FIELDS,
-    regionalmap: MAP_FIELDS,
+    map: MAP_FIELDS,
 });

package/types/content-config.d.mts

@@ -527,6 +527,23 @@ export type ItemBuilderEntry = ((fm: object) => object) | {
     img?: string;
     fields?: readonly object[];
 };
+/**
+ * One **registry** of a declared set, and the system it belongs to (#58).
+ *
+ * A repository shipping content for two systems declares one of these per
+ * system: the accepted type vocabulary is their union, and a type both declare
+ * keeps a builder on each side rather than one of them winning in silence.
+ */
+export type ItemRegistrySpec = {
+    /**
+     * The system id whose vocabulary this registry is.
+     */
+    system: string;
+    /**
+     * The registry itself.
+     */
+    builders: Record<string, ItemBuilderEntry>;
+};
 /**
  * The configuration a consumer writes.
  */
@@ -566,9 +583,13 @@ export type ContentBuildConfigInput = {
      * note of that type gets when it sets no
      * `img:` of its own. Default `{}` — a
      * content module that ships no items
-     * declares none.
+     * declares none. A repository feeding
+     * two systems declares a **list** of
+     * `{ system, builders }` registries
+     * instead, and the accepted type
+     * vocabulary is their union (#58).
      */
-    itemBuilders?: Record<string, ItemBuilderEntry> | undefined;
+    itemBuilders?: Record<string, ItemBuilderEntry> | readonly ItemRegistrySpec[] | undefined;
     /**
      * Packs to compile. More than one entry
      * may share a `type`: a note then names
@@ -657,11 +678,34 @@ export type ContentBuildConfig = {
      * simply undocumented (#22).
      */
     itemFields: Readonly<Record<string, readonly object[]>>;
+    /**
+     *                                     Derived: the same builders, kept per
+     *                                     declaring system. `{}` for the single
+     *                                     registry form, which names no system
+     *                                     (#58).
+     */
+    itemBuildersBySystem: Readonly<Record<string, Readonly<Record<string, Function>>>>;
+    /**
+     *                                     Derived: the default art, per system.
+     */
+    itemArtBySystem: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    /**
+     *                                     Derived: the declared fields, per system.
+     */
+    itemFieldsBySystem: Readonly<Record<string, Readonly<Record<string, readonly object[]>>>>;
+    /**
+     * Derived: the types
+     * more than one registry declares — the
+     * ones the flat tables cannot answer for
+     * without choosing a system for the caller.
+     */
+    itemTypesBySeveralSystems: ReadonlySet<string>;
     /**
      * Derived: the keys of
      * {@link ContentBuildConfigInput.itemBuilders},
-     * so the accepted item types and the builder
-     * table are one list (#1504).
+     * unioned across every declared registry, so
+     * the accepted item types and the builder
+     * tables are one list (#1504).
      */
     itemTypes: ReadonlySet<string>;
     /**

package/types/engine/address-charset.d.mts

@@ -0,0 +1,45 @@
+/**
+ * Whether a value is a well-formed address segment.
+ *
+ * A blank value is **not** valid: this answers "is this an acceptable segment",
+ * never "is a segment present". Presence is a separate question, asked
+ * wherever the value is required, and conflating the two would report a missing
+ * key as a charset violation.
+ *
+ * @param {unknown} value - The candidate segment.
+ * @returns {boolean} `true` when it matches {@link ADDRESS_SEGMENT_PATTERN}.
+ */
+export function isAddressSegment(value: unknown): boolean;
+/**
+ * The one charset every segment of a canonical address is held to (#59).
+ *
+ * An address is a hyphen-joined tuple — `sohl-skill-clmb` — and it is read back
+ * by **counting segments**, with a fixed meaning per position. That is sound
+ * for exactly one reason: the hyphen is *purely* a separator, because no
+ * segment may contain one. Take that away and reading an address needs a
+ * vocabulary to match against, a longest-match rule, and an answer for every
+ * name that is a prefix of another — none of which exist.
+ *
+ * So the charset is not a tidiness rule. It is the premise the address grammar
+ * rests on, and the issue's word for how it should be held is **enforced rather
+ * than assumed**: a value that breaks it is refused where it is written, not
+ * discovered later as addresses that fail to parse and report nothing about
+ * why. `harn-adventures` was that case — its keys read as four segments and
+ * failed as a `null` return.
+ *
+ * This module is a **leaf with no local imports**, so the validator a
+ * consumer's `package-build.config.mjs` reaches (`content-config.mjs`) can name
+ * it without closing a cycle around that file.
+ *
+ * @module
+ */
+/**
+ * The shape every address segment must match: ASCII letters and digits only.
+ *
+ * Case is deliberately **not** constrained. Hundreds of authored shortcodes are
+ * mixed-case and collide with nothing, and case has no bearing on the
+ * separator, which is the whole of what this pattern is protecting.
+ *
+ * @type {RegExp}
+ */
+export const ADDRESS_SEGMENT_PATTERN: RegExp;

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

@@ -0,0 +1,122 @@
+/**
+ * The **alias** namespace: what a note can be called, and who may claim a name.
+ *
+ * A wikilink resolves through one of two namespaces, and the pipe chooses
+ * which (#131): `[[x|…]]` is an *address*, parsed by the address grammar;
+ * `[[x]]` is an *alias*, looked up here. This module owns the second half —
+ * what goes into the index, how a key is spelled, and what happens when two
+ * notes claim one name.
+ *
+ * **An alias is scoped to the claiming note's own type.** The key is
+ * `(type, alias)`, so `Shock` may be a `skill` in one place and a `trauma` in
+ * another without the two ever meeting. A link resolves against the *source*
+ * note's type, which is why a bare name reaches a sibling and never a
+ * cross-type target — that one is written as an address.
+ *
+ * **Three sources, all authored.** `aliases`, `name.aliases`, and `name.full`.
+ * Each is something a person wrote down as a name for the note, which is
+ * exactly what a bare `[[…]]` cites.
+ *
+ * **The filename is deliberately not one of them**, and it used to be — every
+ * one of the three copies of this index added `basename(file, ".md")` with
+ * underscores turned to spaces. That admitted keys no author could ever cite
+ * and no author had ever written:
+ *
+ * - `_Introduction.md` yields the alias `" introduction"`, *with a leading
+ *   space*. A wikilink target is trimmed, so nothing can ever match it. In one
+ *   repository thirteen notes — one per documentation section — claimed that
+ *   key, making it the largest alias collision in the corpus and every one of
+ *   its claimants blameless.
+ * - `README.md` yields `readme`, claimed once per section for the same reason.
+ *
+ * Since a collision is now a build failure rather than a silent deletion, an
+ * index entry that cannot be cited can only ever *cause* one. Removing the
+ * source was measured first, across all five content trees: not one link that
+ * resolves today resolves through the filename alone, so nothing loses a
+ * target — while the collision count falls without a note being edited.
+ *
+ * @module
+ */
+/**
+ * Every alias a note claims, in the order the sources are consulted.
+ *
+ * @param {object} fm - Parsed frontmatter.
+ * @returns {string[]} The claimed aliases, each a non-empty string.
+ */
+export function aliasesOf(fm: object): string[];
+/**
+ * The index key one note's claim on one alias is filed under.
+ *
+ * Stated here so the three indexes — the pack build's, the site build's and
+ * the link checker's — cannot spell it differently. All three already used
+ * `type|alias`, lowercased; the risk was never that they disagreed today.
+ *
+ * @param {string} type - The claiming note's content type.
+ * @param {string} alias - The alias, as authored.
+ * @returns {string} The key.
+ */
+export function aliasKey(type: string, alias: string): string;
+/**
+ * One alias claimed by more than one note of a single type.
+ *
+ * @typedef {object} AliasCollision
+ * @property {string} key - The index key, `type|alias`.
+ * @property {string} type - The type both claimants share.
+ * @property {string} alias - The alias, as the first claimant wrote it.
+ * @property {unknown[]} claimants - Every note claiming it, in walk order.
+ */
+/**
+ * Build the type-scoped alias index, and report every collision in it.
+ *
+ * **A collision resolves to nothing, and is reported naming every claimant.**
+ * Both halves matter. Resolving to whichever note happened to be walked first
+ * makes a link silently point at the wrong document, and which one it is
+ * depends on directory order. Reporting it at the *citing* note blames a file
+ * whose author did nothing wrong — whoever added the second claimant broke
+ * every existing citation (#13) — so the claimants are kept rather than
+ * discarded along with the entry.
+ *
+ * @template T
+ * @param {Iterable<{type: string, aliases: Iterable<string>, value: T}>} entries
+ *   One per note: the type that scopes its claims, the aliases it claims, and
+ *   whatever the caller wants an alias to resolve to.
+ * @param {object} [opts]
+ * @param {(a: T, b: T) => boolean} [opts.same] - Whether two values are the
+ *   same note. Defaults to identity; a caller whose values are freshly built
+ *   records supplies its own.
+ * @returns {{byKey: Map<string, T>, claims: Map<string, T[]>,
+ *   collisions: AliasCollision[]}} `byKey` omits every colliding key, so a
+ *   lookup in it can never resolve an ambiguous alias.
+ */
+export function indexAliases<T>(entries: Iterable<{
+    type: string;
+    aliases: Iterable<string>;
+    value: T;
+}>, { same }?: {
+    same?: ((a: T, b: T) => boolean) | undefined;
+}): {
+    byKey: Map<string, T>;
+    claims: Map<string, T[]>;
+    collisions: AliasCollision[];
+};
+/**
+ * One alias claimed by more than one note of a single type.
+ */
+export type AliasCollision = {
+    /**
+     * - The index key, `type|alias`.
+     */
+    key: string;
+    /**
+     * - The type both claimants share.
+     */
+    type: string;
+    /**
+     * - The alias, as the first claimant wrote it.
+     */
+    alias: string;
+    /**
+     * - Every note claiming it, in walk order.
+     */
+    claimants: unknown[];
+};

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

@@ -11,8 +11,9 @@
  * @property {number} compiled - Notes that became a document.
  * @property {number} skippedNoId - Notes with no `id`, where that is tolerated.
  * @property {number} skippedOther - Notes this pass does not claim.
- * @property {number} declined - Notes refused because they declare a retired
- *   frontmatter field. Counted as errors, never as skips.
+ * @property {number} declined - Notes this pack **refused** — one declaring a
+ *   retired frontmatter field, or one routed to a system pack whose system it
+ *   says nothing about (#58). Counted as errors, never as skips.
  */
 /**
  * The shared walk → filter → expand → convert → build → write → count loop.
@@ -79,6 +80,25 @@ export class BasePackCompiler {
      * @type {readonly string[]}
      */
     static readsPackOutputOf: readonly string[];
+    /**
+     * Whether this pass's document **is** a system's data, and therefore takes
+     * only notes that carry that system's block (#58).
+     *
+     * A pack may declare a `system:` — `harn-ensemble` ships an `actors-hm3`
+     * and an `actors-sohl` from one tree — and the note-side half of that is
+     * the block named after the system. A note carrying no such block has
+     * nothing to say about it, so compiling it there would emit a **hollow
+     * document**: a subtype, and none of the fields the subtype exists for.
+     *
+     * False by default, because most passes write documents that are not
+     * system data at all. A JournalEntry of prose is the same document under
+     * either system, and a journals pack that declared one must not turn every
+     * doc note in the tree into a finding. The Item and Actor passes say so;
+     * anything else that genuinely writes a system's data says so too.
+     *
+     * @type {boolean}
+     */
+    static requiresSystemBlock: boolean;
     /**
      * @param {object} options
      * @param {string} options.contentBase - Root of the content tree.
@@ -111,6 +131,21 @@ export class BasePackCompiler {
     folderResolver: (path: string | null) => string | null;
     /** @type {number} */
     errorCount: number;
+    /**
+     * Emitted-`system` findings, one per `documentType|subtype|field` (#155).
+     *
+     * A key the compiler writes is on **every** document of a subtype, so
+     * reporting it where it is found would print the same sentence 3,126 times
+     * and bury the one that is not systemic. Collected here instead and flushed
+     * once at the end of the pass, keyed so the class of defect is reported
+     * once and the first document carrying it names a file a reader can open.
+     *
+     * @type {Map<string, {message: string, file: string|undefined}>}
+     */
+    emittedFindings: Map<string, {
+        message: string;
+        file: string | undefined;
+    }>;
     /**
      * The pack this pass writes, and the Foundry document type it holds.
      *
@@ -178,6 +213,22 @@ export class BasePackCompiler {
      *   routes to no pack at all — a build failure, never a silent drop.
      */
     routesHere(fm: object): boolean;
+    /**
+     * Whether a claimed, routed note may become this pack's document at all.
+     *
+     * The pack-eligibility gate, and it fails rather than skipping: a note that
+     * routed *here* and carries nothing for this pack's system is an authoring
+     * mistake with a hollow document at the end of it, not a note that belongs
+     * to another pass. Skipping it quietly is how a whole tree compiles to
+     * documents nobody can use — the failure mode #1502 and #56 are both
+     * instances of.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @returns {boolean} True when the note may be compiled here.
+     * @throws {Error} When this pack's system is absent from the note. The
+     *   error carries a `position` where the note's own file can be read.
+     */
+    eligibleFor(fm: object): boolean;
     /**
      * Whether this pass claims a note. **Required.**
      *
@@ -265,6 +316,82 @@ export class BasePackCompiler {
         line?: number;
         column?: number;
     }): void;
+    /**
+     * Report every `<system>.system` key the receiving subtype does not declare
+     * (#58).
+     *
+     * An **error**, not a warning: Foundry drops an unknown `system` key at
+     * construction without a word, so the alternative is a document shipped
+     * with a field the author wrote and nobody will ever see. Each finding is
+     * located at the offending key where the file can be read, so it points at
+     * a line rather than at a note.
+     *
+     * Silent where nothing can answer — no published schema, or a subtype the
+     * artifact does not name. `content-build lint` says that out loud once for
+     * the whole build rather than once per note.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} block - The system block to read.
+     * @param {string} documentType - `Item`, `Actor`, …
+     * @param {string} subType - The subtype this note compiles into.
+     * @returns {number} How many findings were reported.
+     */
+    reportUndeclaredSystemData(fm: object, block: string, documentType: string, subType: string): number;
+    /**
+     * Record every `system` key the *compiled document* carries that the
+     * receiving subtype does not declare (#155).
+     *
+     * The sibling of {@link BasePackCompiler#reportUndeclaredSystemData}, and
+     * the half that sees what no declaration states. A compiler writes keys of
+     * its own alongside the declared fields — `shortcode`, `actionDefs`,
+     * `notes`, `docHtml`, `archetype` — and neither the field-declaration check
+     * nor the authored-`system` check can see them, so until this nothing
+     * compared them at all. Foundry's discard is the same silent one either
+     * way.
+     *
+     * Called with the block **after** the builder, the authored merge and any
+     * conditional fields have all written into it, so what is checked is what
+     * the pack file receives.
+     *
+     * Recorded rather than reported: see {@link BasePackCompiler#emittedFindings}
+     * for why, and {@link BasePackCompiler#reportEmittedFindings} for where they
+     * come out.
+     *
+     * @param {object} system - The `system` block just assembled.
+     * @param {object} opts
+     * @param {object} opts.fm - The note's frontmatter.
+     * @param {string} opts.block - The system block the note writes.
+     * @param {string} opts.documentType - `Item`, `Actor`, …
+     * @param {string} opts.subType - The subtype this note compiles into.
+     * @param {string} opts.type - The note's content type.
+     * @param {readonly {to?: string}[]} [opts.fields] - The type's field
+     *   declaration, which tells a builder emission from a compiler one.
+     * @param {object} [opts.config] - The resolved build configuration.
+     * @returns {number} How many findings were new to this pass.
+     */
+    reportEmittedSystemData(system: object, { fm, block, documentType, subType, type, fields, config }: {
+        fm: object;
+        block: string;
+        documentType: string;
+        subType: string;
+        type: string;
+        fields?: readonly {
+            to?: string;
+        }[] | undefined;
+        config?: object | undefined;
+    }): number;
+    /**
+     * Emit the collected emitted-`system` findings, once each.
+     *
+     * An **error**, for the reason #60 made its sibling one: the value is gone
+     * at load and the build says nothing, and severity that varied by *which
+     * part of the build wrote the key* would make the less fixable half the
+     * quieter one. What varies is the message, which says whose fix it is —
+     * see {@link module:engine/schema-check.emittedUndeclaredMessage}.
+     *
+     * @returns {number} How many were reported.
+     */
+    reportEmittedFindings(): number;
     /**
      * One note → one document. **Required.**
      *
@@ -367,8 +494,9 @@ export type PassStats = {
      */
     skippedOther: number;
     /**
-     * - Notes refused because they declare a retired
-     * frontmatter field. Counted as errors, never as skips.
+     * - Notes this pack **refused** — one declaring a
+     * retired frontmatter field, or one routed to a system pack whose system it
+     * says nothing about (#58). Counted as errors, never as skips.
      */
     declined: number;
 };

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

@@ -2,11 +2,11 @@
  * The URL section a note routes to.
  *
  * A `doc` is narrative content whose only identity is its subtype label, so it
- * routes by `category`; every other type names its own section.
+ * routes by `subType`; every other type names its own section.
  *
  * @param {object} fm - Parsed frontmatter.
  * @returns {string|undefined} The section, or `undefined` when the note has
- *   none — a `doc` with no category has no address and is not published.
+ *   none — a `doc` with no subtype has no address and is not published.
  */
 export function sectionOf(fm: object): string | undefined;
 /**