@heroiclands/package-build 8.1.0 → 10.0.0

package/engine/generate.mjs

@@ -48,16 +48,12 @@ import { Journals } from "./journals.mjs";
 import { Actors } from "../sohl/actors.mjs";
 import { Macros } from "./macros.mjs";
 import { Scenes } from "./scenes.mjs";
-import {
-    statsForPack,
-    loadFolders,
-    buildFolderResolver,
-    writeFolderDocs,
-} from "./helpers.mjs";
+import { statsForPack, loadFolders, buildFolderResolver, writeFolderDocs } from "./helpers.mjs";
 import { countContentNotes } from "./content-tree.mjs";
 import { emitDiagnostic } from "./diagnostics.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { routerFor } from "./pack-router.mjs";
+import { unclaimedNoteFindings } from "./note-claims.mjs";
 
 /**
  * The compiler class for each Foundry document type a pack may hold.
@@ -99,16 +95,30 @@ export const packJsonDir = (name, config = loadPackConfig()) =>
  * order among packs of one type — and every one of them is written before the
  * actors pass that reads them.
  *
+ * **Scoped to one system when the caller has one (#58).** A being addresses an
+ * item by `(type, shortcode)`, and that address is unique within one system and
+ * not across two: `skill:sword` is an HM3 skill *and* a SoHL skill, with
+ * different data models behind them. The reference itself is unambiguous — it
+ * sits inside a system block, so position says which it means — but the
+ * resolver has to know which catalogue it is searching, or it resolves the pair
+ * by whichever pack was read first. So an Actor pass reads the Item packs of
+ * **its own** system plus the system-neutral ones, which belong to every
+ * system. Asking for no system reads them all, which is every single-system
+ * build and the behaviour this always had.
+ *
  * @param {object} [config] - The resolved build configuration. Defaults to this
  *   repository's.
+ * @param {string|null} [system] - The system whose catalogue is wanted. Omitted
+ *   or `null`, every Item pack is read.
  * @returns {string[]} Each Item pack's JSON directory. Empty when the
  *   repository ships no items at all, which is a legitimate package: the actors
  *   pass accepts an empty list and reports an item it cannot resolve per
  *   `(type, shortcode)` instead, naming the being (#49).
  */
-export function itemPackJsonDirs(config = loadPackConfig()) {
+export function itemPackJsonDirs(config = loadPackConfig(), system = null) {
     return config.packs
         .filter((pack) => pack.type === "Item")
+        .filter((pack) => system == null || !pack.system || pack.system === system)
         .map((pack) => packJsonDir(pack.name, config));
 }
 
@@ -170,10 +180,7 @@ export function orderPassesByDependency(packs) {
         readsOutputOf(pack.type).every(
             (dependency) =>
                 !declared.has(dependency) ||
-                packs.every(
-                    (other) =>
-                        other.type !== dependency || emitted.has(other.name),
-                ),
+                packs.every((other) => other.type !== dependency || emitted.has(other.name)),
         );
 
     while (remaining.length) {
@@ -269,8 +276,7 @@ async function generatePack(
     let folderList;
     let resolver;
     try {
-        folderList =
-            folders ? loadFolders(path.join(contentBase, folders)) : [];
+        folderList = folders ? loadFolders(path.join(contentBase, folders)) : [];
         ({ resolver } = buildFolderResolver(folderList));
     } catch (err) {
         log.error(`${name} ${folders} validation failed: ${err.message}`);
@@ -305,7 +311,9 @@ async function generatePack(
         // the Item packs, so the dependency is stated rather than assumed
         // (#1508) — and it is every Item pack, since a repository may ship more
         // than one (#1566).
-        itemsSourceDirs: itemPackJsonDirs(config),
+        // Scoped to this pack's system, so a being resolves `(type, shortcode)`
+        // against its own system's catalogue and the neutral one (#58).
+        itemsSourceDirs: itemPackJsonDirs(config, system ?? null),
         // The catalogue of a package this repository depends on but does
         // not contain, for a repository that authors beings without
         // holding the items they are assembled from. Cache-only: a cold
@@ -365,10 +373,7 @@ export function emptyPassErrors(passes) {
  * @throws {Error} If the configured Foundry package id has drifted from the
  *   shipped manifest's `id` (see `package-manifest.mjs`).
  */
-export async function generatePacksJson({
-    only,
-    config = loadPackConfig(),
-} = {}) {
+export async function generatePacksJson({ only, config = loadPackConfig() } = {}) {
     // Before anything is generated: every UUID written below is addressed to
     // the configured `foundryPackage`, so a value that has drifted from the shipped
     // manifest's `id` produces a whole pack of links that resolve nowhere.
@@ -393,6 +398,17 @@ export async function generatePacksJson({
         return 1;
     }
     log.info(`Content tree: ${noteCount} note(s) at ${contentBase}`);
+
+    // A note whose `type:` no configured pack claims compiles into nothing, and
+    // used to say nothing (#146) — no pass got far enough to reject it, so the
+    // silence had no owner. Asked once, of the whole configuration, because
+    // that is the only place it can be answered: a per-pass check would report
+    // every type a system deliberately does not map, which is exactly the
+    // silence #79 requires. Independent of `only`, since it is a fact about the
+    // configured pack list rather than about which passes this run executes.
+    const unclaimed = unclaimedNoteFindings(config);
+    for (const finding of unclaimed) emitDiagnostic(finding);
+
     fs.mkdirSync(config.paths.packJson, { recursive: true });
 
     // A companion pack has no pass of its own — naming it selects the pass that
@@ -431,10 +447,10 @@ export async function generatePacksJson({
         for (const message of unsatisfied) {
             emitDiagnostic({ severity: "error", message });
         }
-        return unsatisfied.length;
+        return unsatisfied.length + unclaimed.length;
     }
 
-    let totalErrors = 0;
+    let totalErrors = unclaimed.length;
     const passes = [];
     for (const pack of ordered) {
         const { errors, compiled } = await generatePack(

package/engine/helpers.mjs

@@ -39,6 +39,8 @@ import { contentPackage, foundryPackageId } from "./content-package.mjs";
 import { searchableFrontmatter } from "./note-package.mjs";
 import { loadForeignManifests, PACKAGE_BASE } from "./kb-manifest.mjs";
 import { buildWikilinkIndex, convertWikilinks } from "./wikilinks.mjs";
+// The alias sources every index shares (#131).
+import { aliasesOf } from "./alias-index.mjs";
 import { expandContentTables } from "./content-tables.mjs";
 import { emitDiagnostic, positionInBody } from "./diagnostics.mjs";
 // The pure `sohl:` frontmatter readers live in a leaf module so the item-type
@@ -89,8 +91,7 @@ export function parseMarkdownFile(filePath) {
     // be reported as a file position (#17). The frontmatter's lines and the
     // blank lines `trim()` removes both sit in between, and the trim can take
     // indentation off the first line as well — hence a column, not just a line.
-    const bodyStart =
-        content.length - raw.length + (raw.length - raw.trimStart().length);
+    const bodyStart = content.length - raw.length + (raw.length - raw.trimStart().length);
     const before = content.slice(0, bodyStart);
     const bodyLine = before.split("\n").length;
     const bodyColumn = bodyStart - before.lastIndexOf("\n");
@@ -148,8 +149,8 @@ export function* walkMarkdownTree(
 
 /**
  * Resolve the required `sohl.archetype` frontmatter for an Item/Actor entry
- * (see the archetype contract, #604 — `flags.sohl.docArchetype`). The property
- * is a nullable number that authors must state explicitly:
+ * (the archetype contract, #604). The property is a nullable number that
+ * authors must state explicitly:
  *   - a number → the document is an archetype of that priority.
  *   - `null`   → the document is not an archetype.
  *   - absent   → an authoring error (throws), so "not an archetype" is never
@@ -183,30 +184,29 @@ export function resolveArchetype(fm, label) {
 }
 
 /**
- * Merge the required `sohl.archetype` frontmatter into a document's `flags`,
- * returning a new object (the input is never mutated). A numeric archetype
- * seeds `flags.sohl.docArchetype`; `null` omits the flag (and clears any stale
- * `docArchetype` while preserving sibling `sohl` flags); an absent value
- * throws. See {@link resolveArchetype}.
- *
- * @param {object} fm              Parsed frontmatter.
- * @param {object} [flags]         The entry's existing flags (e.g. `fm.flags`).
- * @param {string} label           Human-readable context for error messages.
- * @returns {object}               The flags object with the archetype applied.
+ * The value a document's `system.archetype` carries, from the required
+ * `sohl.archetype` frontmatter (#126, sohl#1780).
+ *
+ * A **schema field**, so the tri-state is written out in full rather than
+ * expressed by a key's presence: a number is an archetype at that priority,
+ * and `null` is not an archetype. This is where {@link resolveArchetype}'s
+ * `undefined` becomes the field's `null` — an emitted `undefined` would be
+ * dropped by `JSON.stringify`, leaving the compiled document with no
+ * `archetype` at all and the tri-state readable as two.
+ *
+ * **`0` is an archetype.** It is the priority SoHL's own archetypes ship at,
+ * and it is falsy, so this returns it unchanged and every caller must ask
+ * `typeof v === "number"` rather than testing truthiness.
+ *
+ * @param {object} fm      Parsed frontmatter.
+ * @param {string} label   Human-readable context for error messages.
+ * @returns {number|null}  The archetype priority, or `null` for a document
+ *   that is not an archetype.
  * @throws {Error} When `sohl.archetype` is absent or invalid.
  */
-export function withArchetypeFlag(fm, flags, label) {
+export function systemArchetype(fm, label) {
     const archetype = resolveArchetype(fm, label);
-    const out = { ...(flags || {}) };
-    const sohl = { ...(out.sohl || {}) };
-    if (archetype === undefined) {
-        delete sohl.docArchetype;
-    } else {
-        sohl.docArchetype = archetype;
-    }
-    if (Object.keys(sohl).length > 0) out.sohl = sohl;
-    else delete out.sohl;
-    return out;
+    return archetype === undefined ? null : archetype;
 }
 
 /**
@@ -321,10 +321,7 @@ export function supportedCoreVersion(config = loadPackConfig()) {
  *   The resolved build configuration. Defaults to this repository's.
  * @returns {object} The `_stats` block.
  */
-export function buildStats(
-    systemVersion = undefined,
-    config = loadPackConfig(),
-) {
+export function buildStats(systemVersion = undefined, config = loadPackConfig()) {
     return {
         systemId: config.stats.systemId,
         systemVersion: systemVersion ?? config.stats.systemVersion,
@@ -453,12 +450,10 @@ export function buildContentLinkIndex(contentBase, router = packRouter()) {
             docPack: router.resolveOrNull(fm, "JournalEntry"),
             shortcode: fm.shortcode ?? null,
             name: fm.name?.full ?? base,
-            aliases: [
-                ...(Array.isArray(fm.aliases) ? fm.aliases : []),
-                ...(fm.name?.full ? [fm.name.full] : []),
-                ...(Array.isArray(fm.name?.aliases) ? fm.name.aliases : []),
-                base,
-            ].filter(Boolean),
+            // The shared alias sources (#131): `aliases`, `name.aliases` and
+            // `name.full`, and deliberately not the filename — see
+            // {@link aliasesOf} for what that admitted and why it went.
+            aliases: aliasesOf(fm),
         });
     }
     // Packages this build links *into* but does not publish. Their manifests
@@ -473,9 +468,7 @@ export function buildContentLinkIndex(contentBase, router = packRouter()) {
     );
     if (stale.length) {
         for (const st of stale) {
-            log.error(
-                `Unusable link manifest for "${st.package}": ${st.reason}`,
-            );
+            log.error(`Unusable link manifest for "${st.package}": ${st.reason}`);
         }
         throw new Error(
             "Cross-package links cannot be resolved from a stale manifest; " +
@@ -486,12 +479,7 @@ export function buildContentLinkIndex(contentBase, router = packRouter()) {
         `Wikilink index: ${docs.length} local document(s), ` +
             `${foreign.size} foreign address(es)`,
     );
-    return buildWikilinkIndex(
-        docs,
-        foundryPackageId(),
-        foreign,
-        contentPackage(),
-    );
+    return buildWikilinkIndex(docs, foundryPackageId(), foreign, contentPackage());
 }
 
 /**
@@ -518,18 +506,7 @@ export function buildContentLinkIndex(contentBase, router = packRouter()) {
  */
 export function convertNoteWikilinks(
     body,
-    {
-        type,
-        id,
-        pack,
-        docPack,
-        index,
-        name,
-        file,
-        bodyLine,
-        bodyColumn,
-        lineMap,
-    },
+    { type, id, pack, docPack, index, name, file, bodyLine, bodyColumn, lineMap },
 ) {
     const result = convertWikilinks(body ?? "", {
         type,
@@ -580,9 +557,7 @@ export function convertNoteWikilinks(
             const claims = u.candidates ?? [];
             const named =
                 claims.length ?
-                    claims
-                        .map((c) => `"${c.name}" (${c.type}-${c.shortcode})`)
-                        .join(" and ")
+                    claims.map((c) => `"${c.name}" (${c.type}-${c.shortcode})`).join(" and ")
                 :   "two or more notes";
             fail(
                 u,
@@ -591,6 +566,19 @@ export function convertNoteWikilinks(
                     `as [[type-shortcode|Text]].`,
             );
         }
+        // The author wrote a pipe, so they meant an address — and this target
+        // is not one. Its own message, because the correction is its own: a
+        // note *name* has to become an address, which is not the same job as
+        // fixing a shortcode that resolves nowhere (#131).
+        if (u.reason === "not-an-address") {
+            fail(
+                u,
+                `wikilink ${u.link} in "${name}" is written as an address — ` +
+                    `the "|" says so — but "${u.target}" is not one. Write ` +
+                    `[[type-shortcode|Text]], or drop the "|" to name it as ` +
+                    `an alias within this note's own type.`,
+            );
+        }
         // A qualified address resolving nowhere is a typo, now that every
         // linkable package is either built here or vendored (#1499) — so it
         // fails the note rather than degrading to text. A bare alias stays a
@@ -613,9 +601,7 @@ export function convertNoteWikilinks(
                 `unresolved wikilink ${u.link} (${u.reason}) in "${name}"` +
                 // A link this build wrote is not at any authored position, so
                 // say where it came from instead of implying an edit site.
-                (at.generated ?
-                    " — emitted by the content table on this line"
-                :   ""),
+                (at.generated ? " — emitted by the content table on this line" : ""),
         });
     }
     return result;
@@ -668,8 +654,7 @@ export function collectContentDocs(contentBase) {
  * unlinkable; a note missing either renders as plain text rather than shipping a
  * literal wikilink into a journal.
  */
-const packLinkable = (doc) =>
-    Boolean(doc.fm?.shortcode) && Boolean(doc.fm?.type);
+const packLinkable = (doc) => Boolean(doc.fm?.shortcode) && Boolean(doc.fm?.type);
 
 /**
  * Expand the fenced `dataview` tables in one note's markdown, before wikilinks
@@ -710,9 +695,7 @@ export function expandNoteTables(body, { docs, name, fm, bodyLine }) {
         self,
     });
     if (errors.length) {
-        const err = new Error(
-            errors.map((e) => `content table — ${e.reason}`).join("; "),
-        );
+        const err = new Error(errors.map((e) => `content table — ${e.reason}`).join("; "));
         // The first failing directive's line. Reporting one position for a
         // message that may name several is honest here: a caller opens the
         // file at the first thing to fix, and the message lists the rest.
@@ -735,18 +718,14 @@ export function expandNoteTables(body, { docs, name, fm, bodyLine }) {
  */
 export function loadFolders(foldersFile) {
     if (!fs.existsSync(foldersFile)) {
-        log.warn(
-            `No folders.yaml at ${foldersFile}; no folders will be emitted`,
-        );
+        log.warn(`No folders.yaml at ${foldersFile}; no folders will be emitted`);
         return [];
     }
     const raw = fs.readFileSync(foldersFile, "utf8");
     const parsed = yaml.parse(raw);
     if (parsed == null) return [];
     if (!Array.isArray(parsed)) {
-        throw new Error(
-            `folders.yaml must contain a YAML list; got ${typeof parsed}`,
-        );
+        throw new Error(`folders.yaml must contain a YAML list; got ${typeof parsed}`);
     }
     return parsed;
 }
@@ -818,10 +797,7 @@ export function buildFolderResolver(folders) {
  * underscores.
  */
 export function folderFilename(name, id) {
-    return (
-        `folder_${unidecode(name)}_${id}`.replace(/[^0-9a-zA-Z]+/g, "_") +
-        ".json"
-    );
+    return `folder_${unidecode(name)}_${id}`.replace(/[^0-9a-zA-Z]+/g, "_") + ".json";
 }
 
 /**
@@ -843,10 +819,7 @@ export function writeFolderDocs(folders, stats, destDir, documentType) {
             _stats: stats,
             _key: `!folders!${folder.id}`,
         };
-        const outPath = path.join(
-            destDir,
-            folderFilename(folder.name, folder.id),
-        );
+        const outPath = path.join(destDir, folderFilename(folder.name, folder.id));
         fs.writeFileSync(outPath, JSON.stringify(doc, null, 2), "utf8");
     }
     log.info(`Emitted ${folders.length} folder document(s) to ${destDir}`);

package/engine/homepage.mjs

@@ -262,9 +262,7 @@ export function checkHomepageCount(found, { contentBase, contentPackage }) {
     if (pages.length === 1) return [];
 
     return pages.map((page) => {
-        const others = pages
-            .filter((p) => p !== page)
-            .map((p) => formatLocator({ file: p.file }));
+        const others = pages.filter((p) => p !== page).map((p) => formatLocator({ file: p.file }));
         return {
             file: page.file,
             ...positionOfType(page.file),
@@ -292,11 +290,7 @@ export function checkHomepageCount(found, { contentBase, contentPackage }) {
  */
 function positionOfType(file) {
     try {
-        return positionInFrontmatter(
-            fs.readFileSync(file, "utf8"),
-            "type",
-            HOMEPAGE_TYPE,
-        );
+        return positionInFrontmatter(fs.readFileSync(file, "utf8"), "type", HOMEPAGE_TYPE);
     } catch {
         return {};
     }
@@ -325,9 +319,7 @@ export function homepageTitle(fm, config) {
         config?.packageBuild?.manifest
     );
     const title = manifest?.title;
-    return typeof title === "string" && title.trim() ?
-            title
-        :   config.contentPackage;
+    return typeof title === "string" && title.trim() ? title : config.contentPackage;
 }
 
 /**
@@ -394,10 +386,7 @@ export const HOMEPAGE_ADDRESS_KEYS = Object.freeze(new Set(["url", "href"]));
  */
 function collectProse(text, field, kind, out, skipCode = false) {
     const pattern = new RegExp(MARKDOWN_LINK.source, "g");
-    const matches =
-        skipCode ?
-            matchAllOutsideCode(text, pattern)
-        :   [...text.matchAll(pattern)];
+    const matches = skipCode ? matchAllOutsideCode(text, pattern) : [...text.matchAll(pattern)];
     for (const m of matches) out.push({ field, url: m[1], kind });
 }
 

package/engine/ids.mjs

@@ -36,11 +36,7 @@ import crypto from "crypto";
  * @returns {string} A 16-character hexadecimal Foundry id.
  */
 export function makeId(namespace, value) {
-    return crypto
-        .createHash("sha1")
-        .update(`${namespace}:${value}`)
-        .digest("hex")
-        .slice(0, 16);
+    return crypto.createHash("sha1").update(`${namespace}:${value}`).digest("hex").slice(0, 16);
 }
 
 /**
@@ -55,9 +51,18 @@ export function makeId(namespace, value) {
  *
  * @type {ReadonlySet<string>}
  */
-export const MAP_TYPES = Object.freeze(
-    new Set(["battlemap", "localmap", "regionalmap"]),
-);
+export const MAP_TYPES = Object.freeze(new Set(["map"]));
+
+/**
+ * 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
+ * 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.
+ *
+ * @type {readonly string[]}
+ */
+export const MAP_SUBTYPES = Object.freeze(["battlemap", "localmap", "regionalmap"]);
 
 /**
  * Content type → the pack its documents compile into, and the document type
@@ -77,10 +82,7 @@ export const PACK_BY_TYPE = Object.freeze({
     macro: { pack: "macros", docType: "Macro" },
     being: { pack: "actors", docType: "Actor" },
     ...Object.fromEntries(
-        [...MAP_TYPES].map((type) => [
-            type,
-            { pack: "scenes", docType: "Scene" },
-        ]),
+        [...MAP_TYPES].map((type) => [type, { pack: "scenes", docType: "Scene" }]),
     ),
 });
 
@@ -104,6 +106,13 @@ export const PACK_BY_TYPE = Object.freeze({
 export const RETIRED_TYPES = Object.freeze({
     character: "being",
     creature: "being",
+    // The three map spellings, retired in favour of the single `map` whose
+    // subType they became (#174). Recorded rather than deleted for the same
+    // reason as the two above: an unnamed type falls through to the open item
+    // set, so a note or link left on one would be routed to the items pack.
+    battlemap: "map",
+    localmap: "map",
+    regionalmap: "map",
 });
 
 /**

package/engine/index.mjs

@@ -36,6 +36,9 @@
 /** Deterministic document ids, the conventional pack map, and compendium UUIDs. */
 export * as ids from "./ids.mjs";
 
+/** The per-system frontmatter block, and the declared shared→system mapping. */
+export * as systemBlock from "./system-block.mjs";
+
 /** Fenced-code detection, so a rewrite never edits a code block. */
 export * as codeFences from "./code-fences.mjs";
 
@@ -51,6 +54,9 @@ export * as packConfig from "./pack-config.mjs";
 /** Which pack of a document type a note's document lands in (#1566). */
 export * as packRouter from "./pack-router.mjs";
 
+/** Which note types a configuration compiles, and the notes nothing claims (#146). */
+export * as noteClaims from "./note-claims.mjs";
+
 /** The content package a build compiles, and the Foundry package it ships in. */
 export * as contentPackage from "./content-package.mjs";
 
@@ -66,6 +72,9 @@ export * as homepage from "./homepage.mjs";
 /** The note types the engine itself declares, whatever a consumer registers. */
 export * as noteSchemas from "./note-schemas.mjs";
 
+/** The closed frontmatter regions: the `data:` container and each type's `subType`. */
+export * as noteVocabulary from "./note-vocabulary.mjs";
+
 /** The shipped Foundry manifest: locating it, reading it, guarding its id. */
 
 /** The URL a content note is published at — the one web-address rule. */
@@ -104,6 +113,9 @@ export * as helpers from "./helpers.mjs";
 /** The consumer's resolved item-type registry: the whitelist and its builders. */
 export * as itemRegistry from "./item-registry.mjs";
 
+/** The per-system note-type → document-subtype map, and looking a note up in it. */
+export * as documentSubtypes from "./document-subtypes.mjs";
+
 /** Which types carry documentation of their own, and where it is addressed. */
 export * as itemDocs from "./item-docs.mjs";
 
@@ -113,6 +125,9 @@ export * as wikilinks from "./wikilinks.mjs";
 /** What a `[[…]]` is, before either resolver decides where it points. */
 export * as wikilinkSyntax from "./wikilink-syntax.mjs";
 
+/** The alias namespace: what a note may be called, and who may claim a name. */
+export * as aliasIndex from "./alias-index.mjs";
+
 /** The address index a site build resolves its wikilinks against. */
 export * as siteIndex from "./site-index.mjs";
 

package/engine/item-registry.mjs

@@ -18,7 +18,11 @@
  * Both are read from the one resolved configuration, so they are literally the
  * same object's keys and values: a type cannot be whitelisted for compilation
  * without the builder that compiles it, which is the guarantee #1504 exists
- * for. The Item compiler dispatches through {@link itemBuilder}, so the table a
+ * for. Where a consumer declares **several** registries, one per system (#58),
+ * the vocabulary is their union and every lookup below takes the system that is
+ * asking — a type both systems declare has two builders, and answering with one
+ * of them because it was declared first is the silent-wrong-output failure this
+ * package spends its time removing. The Item compiler dispatches through {@link itemBuilder}, so the table a
  * consumer configured is the table its notes compile with — the whitelist and
  * the dispatch used to come from different places, and a consumer supplying its
  * own registry got the types it asked for and the builders it did not (#1563).
@@ -60,6 +64,43 @@ export function itemTypes() {
     return loadPackConfig().itemTypes;
 }
 
+/**
+ * Look one type up in the table a system declared, or in the flat one.
+ *
+ * The flat table is the union with the first declaring registry winning, which
+ * is the right answer for every single-system build and no answer at all where
+ * two systems declare the type. So a contested type without a system **throws**
+ * rather than resolving: the alternative is a document built by one system's
+ * builder and stamped with another's, which is exactly the shape of defect the
+ * document-subtype map exists to stop (#79).
+ *
+ * @param {string} what - What is being looked up, for the message.
+ * @param {"itemBuilders"|"itemArt"|"itemFields"} table - Which table.
+ * @param {string} type - The item type.
+ * @param {string} [system] - The system asking, where a build has more than one.
+ * @returns {any} The entry, or `undefined`.
+ * @throws {Error} When several systems declare the type and none is named.
+ */
+function lookup(what, table, type, system) {
+    const config = loadPackConfig();
+    if (system !== undefined) {
+        const perSystem = /** @type {Record<string, Record<string, unknown>>} */ (
+            config[`${table}BySystem`]
+        );
+        // A consumer declaring one, system-less registry keeps answering for
+        // every system: it *is* the only vocabulary in the build.
+        if (Object.keys(perSystem).length) return perSystem[system]?.[type];
+    } else if (config.itemTypesBySeveralSystems.has(type)) {
+        throw new Error(
+            `More than one declared registry defines the item type "${type}", so ` +
+                `the ${what} of a "${type}" depends on which system is asking. ` +
+                `Name the system at the call site, or stop declaring the type ` +
+                `twice.`,
+        );
+    }
+    return /** @type {Record<string, unknown>} */ (config[table])[type];
+}
+
 /**
  * The builder the consuming repository registered for an item type.
  *
@@ -68,13 +109,16 @@ export function itemTypes() {
  * failing as an anonymous `is not a function` (#1504).
  *
  * @param {string} type - The note's `type` frontmatter.
+ * @param {string} [system] - The system compiling it, where a build declares
+ *   more than one registry. Omitted, a type only one registry declares still
+ *   resolves; a contested one throws rather than picking a side.
  * @returns {(fm: object) => object} The builder for that type.
  * @throws {Error} When the configuration registers no builder for `type`.
  */
-export function itemBuilder(type) {
-    const builder = /** @type {Record<string, Function>} */ (
-        loadPackConfig().itemBuilders
-    )[type];
+export function itemBuilder(type, system) {
+    const builder = /** @type {Function|undefined} */ (
+        lookup("builder", "itemBuilders", type, system)
+    );
     if (typeof builder !== "function") {
         throw new Error(
             `No builder registered for item type "${type}" — add one to the ` +
@@ -85,6 +129,25 @@ export function itemBuilder(type) {
     return /** @type {(fm: object) => object} */ (builder);
 }
 
+/**
+ * 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,
+ * which has to know which paths a declared field already writes before it
+ * writes the rest (#58).
+ *
+ * @param {string} type - The item type.
+ * @param {string} [system] - The system compiling it, where a build declares
+ *   more than one registry.
+ * @returns {readonly object[]|undefined} The declaration, or `undefined`.
+ */
+export function itemFields(type, system) {
+    return /** @type {readonly object[]|undefined} */ (
+        lookup("field declaration", "itemFields", type, system)
+    );
+}
+
 /**
  * The default art for an item type — the image a note of that type is given
  * when it carries no `img:` of its own.
@@ -108,13 +171,13 @@ export function itemBuilder(type) {
  * One spelling, one meaning, wherever it is written.
  *
  * @param {string} type - the item type.
+ * @param {string} [system] - The system compiling it, where a build declares
+ *   more than one registry.
  * @returns {string} The default image path for that type.
  * @throws {Error} When the type's registry entry pairs no `img`.
  */
-export function itemArt(type) {
-    const art = /** @type {Record<string, string|undefined>} */ (
-        loadPackConfig().itemArt
-    )[type];
+export function itemArt(type, system) {
+    const art = /** @type {string|undefined} */ (lookup("default art", "itemArt", type, system));
     if (!art) {
         throw new Error(
             `No default art for item type "${type}" — the note carries no ` +