@heroiclands/package-build 8.1.0 → 10.0.0

package/content-config.mjs

@@ -66,9 +66,10 @@
 
 import path from "node:path";
 
-// A leaf with no local imports of its own, so naming it here cannot close a
-// cycle around a consumer's config file (see `engine/pack-config.mjs`).
-import { MAP_TYPES } from "./engine/ids.mjs";
+// Leaves with no local imports of their own, so naming them here cannot close
+// a cycle around a consumer's config file (see `engine/pack-config.mjs`).
+import { isAddressSegment } from "./engine/address-charset.mjs";
+import { MAP_TYPES, PACK_BY_TYPE } from "./engine/ids.mjs";
 
 /**
  * The two kinds of Foundry package a content module can be built into. The
@@ -470,6 +471,18 @@ export function publishesContentPages(config) {
  * @typedef {((fm: object) => object)|{system: (fm: object) => object, img?: string, fields?: readonly object[]}} ItemBuilderEntry
  */
 
+/**
+ * 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.
+ *
+ * @typedef {object} ItemRegistrySpec
+ * @property {string} system  The system id whose vocabulary this registry is.
+ * @property {Record<string, ItemBuilderEntry>} builders  The registry itself.
+ */
+
 /**
  * The configuration a consumer writes.
  *
@@ -485,7 +498,8 @@ export function publishesContentPages(config) {
  *                                          `system.json` / `module.json`.
  * @property {PackageKind} packageKind      Whether the package is a system or a module.
  * @property {StatsSpec} stats              Identity stamped into every document's `_stats`.
- * @property {Record<string, ItemBuilderEntry>} [itemBuilders]  The consumer's
+ * @property {Record<string, ItemBuilderEntry>|readonly ItemRegistrySpec[]} [itemBuilders]
+ *                                          The consumer's
  *                                          item-type registry: each content `type`
  *                                          that compiles into an Item, paired with
  *                                          the builder producing its `system` block
@@ -493,7 +507,11 @@ export function publishesContentPages(config) {
  *                                          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).
  * @property {PackSpec[]} packs             Packs to compile. More than one entry
  *                                          may share a `type`: a note then names
  *                                          the pack it belongs in with its
@@ -547,10 +565,24 @@ export function publishesContentPages(config) {
  *                                     declared. Sparse, like `itemArt` — a type
  *                                     absent here compiles normally and is
  *                                     simply undocumented (#22).
+ * @property {Readonly<Record<string, Readonly<Record<string, Function>>>>} itemBuildersBySystem
+ *                                     Derived: the same builders, kept per
+ *                                     declaring system. `{}` for the single
+ *                                     registry form, which names no system
+ *                                     (#58).
+ * @property {Readonly<Record<string, Readonly<Record<string, string>>>>} itemArtBySystem
+ *                                     Derived: the default art, per system.
+ * @property {Readonly<Record<string, Readonly<Record<string, readonly object[]>>>>} itemFieldsBySystem
+ *                                     Derived: the declared fields, per system.
+ * @property {ReadonlySet<string>} itemTypesBySeveralSystems  Derived: the types
+ *                                     more than one registry declares — the
+ *                                     ones the flat tables cannot answer for
+ *                                     without choosing a system for the caller.
  * @property {ReadonlySet<string>} itemTypes       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).
  * @property {ReadonlySet<string>} docEntryTypes   Derived: every type whose prose
  *                                     compiles into a JournalEntry of its own —
  *                                     the item types, plus `macro`, plus the map
@@ -608,14 +640,9 @@ const SITE_TREE_KEYS = ["from", "section"];
 const SECTION_META_KEYS = ["title", "banner", "description"];
 const DOC_PAGE_KEYS = ["title", "out", "preamble"];
 const RELATIONSHIP_KINDS = ["systems", "requires", "recommends", "conflicts"];
-const RELATIONSHIP_KEYS = [
-    "id",
-    "type",
-    "manifest",
-    "compatibility",
-    "itemCatalog",
-];
+const RELATIONSHIP_KEYS = ["id", "type", "manifest", "compatibility", "itemCatalog"];
 const ITEM_BUILDER_KEYS = ["system", "img", "fields"];
+const ITEM_REGISTRY_KEYS = ["system", "builders"];
 const PACK_KEYS = [
     "name",
     "type",
@@ -644,9 +671,7 @@ const STATS_KEYS = ["lastModifiedBy"];
  *
  * @type {symbol}
  */
-export const DERIVED_SYSTEM_VERSION = Symbol.for(
-    "package-build.derivedSystemVersion",
-);
+export const DERIVED_SYSTEM_VERSION = Symbol.for("package-build.derivedSystemVersion");
 const PUBLISH_KEYS = ["site", "manifests", "address"];
 const MANIFEST_KEYS = ["publish", "consume"];
 const ADDRESS_KEYS = ["prefix", "landing"];
@@ -672,10 +697,7 @@ function isPlainObject(value) {
  * @returns {never}
  */
 function fail(field, problem) {
-    throw Object.assign(
-        new TypeError(`package-build config: \`${field}\` ${problem}.`),
-        { field },
-    );
+    throw Object.assign(new TypeError(`package-build config: \`${field}\` ${problem}.`), { field });
 }
 
 /**
@@ -706,6 +728,65 @@ function requireNonEmptyString(value, field) {
     return /** @type {string} */ (value);
 }
 
+/**
+ * The `contentPackage`, checked against the two rules an address puts on it.
+ *
+ * It is the first segment of every canonical address this repository publishes
+ * (`sohl-skill-clmb`), and an address is read by counting hyphen-separated
+ * segments. So the value carries two obligations that the rest of the
+ * configuration does not, and #59 asks for both to be **enforced rather than
+ * assumed** — the alternative is a package whose addresses are simply
+ * unreadable, reported nowhere and discovered as links that resolve to nothing.
+ *
+ * 1. _Alphanumeric_, so the hyphen stays purely a separator. `harn-adventures`
+ *    was the one violator, and its keys read as four segments and failed as a
+ *    `null` return from `readCanonicalKey` — a silence, not an error.
+ * 2. _Not a note type_, because the package and the type are adjacent segments
+ *    drawn from two vocabularies. Keeping them disjoint is what lets a reader
+ *    take a name at face value instead of deciding which slot it is filling.
+ *    One such collision is structural and cannot be fixed — `sohl` is both a
+ *    content package and a system id, because Foundry requires a system
+ *    package's id to *be* its system id — which is the reason to prevent the
+ *    ones that are avoidable.
+ *
+ * @param {unknown} value - The configured `contentPackage`.
+ * @param {ReadonlySet<string>} docEntryTypes - Every type whose prose compiles
+ *   to a documentation entry: the item types plus `macro` and the map types.
+ *   With {@link PACK_BY_TYPE} and the `doc`-prefixed forms, this is the whole
+ *   type vocabulary an address may write.
+ * @returns {string} The value, unchanged.
+ */
+function requireContentPackage(value, docEntryTypes) {
+    const pkg = requireNonEmptyString(value, "contentPackage");
+    if (!isAddressSegment(pkg)) {
+        fail(
+            "contentPackage",
+            `is \`${pkg}\`, which is not alphanumeric. It is the first ` +
+                `segment of every address this package publishes ` +
+                `(\`${pkg}-<type>-<shortcode>\`), and an address is read by ` +
+                `counting hyphen-separated segments — so anything outside ` +
+                "`[A-Za-z0-9]` here makes those addresses unreadable rather " +
+                "than merely ugly. `harn-adventures` became `harnadventures`",
+        );
+    }
+    const typeNames = new Set([
+        ...Object.keys(PACK_BY_TYPE),
+        ...docEntryTypes,
+        ...[...docEntryTypes].map((type) => `doc${type}`),
+    ]);
+    if (typeNames.has(pkg)) {
+        fail(
+            "contentPackage",
+            `is \`${pkg}\`, which is also a note type — \`${pkg}-<shortcode>\` ` +
+                "already addresses one. The package and the type are adjacent " +
+                "segments of an address, and the two vocabularies are kept " +
+                "disjoint so a reader never has to decide which slot a name " +
+                "is filling. Rename the package",
+        );
+    }
+    return pkg;
+}
+
 /**
  * @param {unknown} value
  * @param {string} field
@@ -752,10 +833,7 @@ function normalizePack(value, where, nested = false) {
         typeof type !== "string" ||
         !(/** @type {readonly string[]} */ (PACK_DOCUMENT_TYPES).includes(type))
     ) {
-        fail(
-            `${where}.type`,
-            `must be one of: ${PACK_DOCUMENT_TYPES.join(", ")}`,
-        );
+        fail(`${where}.type`, `must be one of: ${PACK_DOCUMENT_TYPES.join(", ")}`);
     }
 
     if (pack.folders !== undefined && pack.folders !== null) {
@@ -837,20 +915,14 @@ function normalizePack(value, where, nested = false) {
         name,
         type: /** @type {PackDocumentType} */ (type),
         label:
-            pack.label === undefined ?
-                name
-            :   requireNonEmptyString(pack.label, `${where}.label`),
+            pack.label === undefined ? name : requireNonEmptyString(pack.label, `${where}.label`),
         private: optionalBoolean(pack.private, `${where}.private`, false),
         folders:
             pack.folders === undefined || pack.folders === null ?
                 null
             :   /** @type {string} */ (pack.folders),
         companions: Object.freeze(companions),
-        mayBeEmpty: optionalBoolean(
-            pack.mayBeEmpty,
-            `${where}.mayBeEmpty`,
-            false,
-        ),
+        mayBeEmpty: optionalBoolean(pack.mayBeEmpty, `${where}.mayBeEmpty`, false),
         // Which pack of a type receives a note that declares none. Validated
         // across the whole list in `defineConfig` — at most one per type.
         default: optionalBoolean(pack.default, `${where}.default`, false),
@@ -938,10 +1010,7 @@ function normalizeStats(value, derived) {
         // the package-wide answer for everything that has no pack in hand.
         systemId: derived.systemId,
         systemVersion: derived.systemVersion,
-        lastModifiedBy: requireNonEmptyString(
-            input.lastModifiedBy,
-            "stats.lastModifiedBy",
-        ),
+        lastModifiedBy: requireNonEmptyString(input.lastModifiedBy, "stats.lastModifiedBy"),
     });
 }
 
@@ -1056,10 +1125,7 @@ function normalizeSectionMeta(value, where) {
         out.banner = requireNonEmptyString(input.banner, `${where}.banner`);
     }
     if (input.description !== undefined) {
-        out.description = requireNonEmptyString(
-            input.description,
-            `${where}.description`,
-        );
+        out.description = requireNonEmptyString(input.description, `${where}.description`);
     }
     return Object.freeze(out);
 }
@@ -1075,9 +1141,7 @@ function normalizeSectionMap(value, where) {
     if (value === undefined) return Object.freeze({});
     if (!isPlainObject(value)) fail(where, "must be a mapping");
     const out = {};
-    for (const [name, meta] of Object.entries(
-        /** @type {Record<string, unknown>} */ (value),
-    )) {
+    for (const [name, meta] of Object.entries(/** @type {Record<string, unknown>} */ (value))) {
         out[name] = normalizeSectionMeta(meta, `${where}.${name}`);
     }
     return Object.freeze(out);
@@ -1124,10 +1188,7 @@ function normalizeSite(value) {
             trees.push(
                 Object.freeze({
                     from: requireNonEmptyString(tree.from, `${where}.from`),
-                    section: requireNonEmptyString(
-                        tree.section,
-                        `${where}.section`,
-                    ),
+                    section: requireNonEmptyString(tree.section, `${where}.section`),
                     // The tree's own path, POSIX-separated — what a
                     // repository-relative link inside it is resolved against.
                     rel: String(tree.from).split(path.sep).join("/"),
@@ -1141,9 +1202,7 @@ function normalizeSite(value) {
         if (!Array.isArray(input.packages)) {
             fail("site.packages", "must be a list");
         }
-        packages = input.packages.map((p, i) =>
-            requireNonEmptyString(p, `site.packages[${i}]`),
-        );
+        packages = input.packages.map((p, i) => requireNonEmptyString(p, `site.packages[${i}]`));
     }
 
     let landing = null;
@@ -1157,35 +1216,19 @@ function normalizeSite(value) {
     }
 
     return Object.freeze({
-        out:
-            input.out === undefined ?
-                ""
-            :   requireNonEmptyString(input.out, "site.out"),
-        base:
-            input.base === undefined ?
-                ""
-            :   requireNonEmptyString(input.base, "site.base"),
+        out: input.out === undefined ? "" : requireNonEmptyString(input.out, "site.out"),
+        base: input.base === undefined ? "" : requireNonEmptyString(input.base, "site.base"),
         packages: Object.freeze(packages),
         sections: normalizeSectionMap(input.sections, "site.sections"),
-        readmeSections: normalizeSectionMap(
-            input.readmeSections,
-            "site.readmeSections",
-        ),
+        readmeSections: normalizeSectionMap(input.readmeSections, "site.readmeSections"),
         landing,
         trees: Object.freeze(trees),
-        pass:
-            input.pass === undefined ?
-                ""
-            :   requireNonEmptyString(input.pass, "site.pass"),
+        pass: input.pass === undefined ? "" : requireNonEmptyString(input.pass, "site.pass"),
         passOptions:
             input.passOptions === undefined ?
                 Object.freeze({})
             :   Object.freeze({ ...input.passOptions }),
-        backfillSections: optionalBoolean(
-            input.backfillSections,
-            "site.backfillSections",
-            false,
-        ),
+        backfillSections: optionalBoolean(input.backfillSections, "site.backfillSections", false),
     });
 }
 
@@ -1213,10 +1256,7 @@ function normalizeCompatibility(value, where, requireMinimum = true) {
         out.minimum = requireNonEmptyString(input.minimum, `${where}.minimum`);
     }
     if (input.verified !== undefined) {
-        out.verified = requireNonEmptyString(
-            input.verified,
-            `${where}.verified`,
-        );
+        out.verified = requireNonEmptyString(input.verified, `${where}.verified`);
     }
     return Object.freeze(out);
 }
@@ -1255,8 +1295,7 @@ function normalizeCompatibility(value, where, requireMinimum = true) {
  */
 function normalizeSystems(value) {
     if (value === undefined || value === null) return Object.freeze({});
-    if (!isPlainObject(value))
-        fail("systems", "must be a mapping of id to spec");
+    if (!isPlainObject(value)) fail("systems", "must be a mapping of id to spec");
     const input = /** @type {Record<string, unknown>} */ (value);
 
     const out = {};
@@ -1276,10 +1315,7 @@ function normalizeSystems(value) {
         // `verified` is required because it is the value a pack stamps. A
         // declaration that cannot answer "which version was this built
         // against" is the gap this block exists to close.
-        const verified = requireNonEmptyString(
-            compat.verified,
-            `${at}.compatibility.verified`,
-        );
+        const verified = requireNonEmptyString(compat.verified, `${at}.compatibility.verified`);
 
         out[id] = Object.freeze({
             manifest:
@@ -1290,10 +1326,7 @@ function normalizeSystems(value) {
                 minimum:
                     compat.minimum === undefined || compat.minimum === null ?
                         null
-                    :   requireNonEmptyString(
-                            compat.minimum,
-                            `${at}.compatibility.minimum`,
-                        ),
+                    :   requireNonEmptyString(compat.minimum, `${at}.compatibility.minimum`),
                 verified,
             }),
         });
@@ -1346,10 +1379,7 @@ function normalizeRelationships(value) {
                 };
                 for (const key of ["type", "manifest"]) {
                     if (rel[key] !== undefined) {
-                        spec[key] = requireNonEmptyString(
-                            rel[key],
-                            `${at}.${key}`,
-                        );
+                        spec[key] = requireNonEmptyString(rel[key], `${at}.${key}`);
                     }
                 }
                 const compat = normalizeCompatibility(
@@ -1367,10 +1397,7 @@ function normalizeRelationships(value) {
                         fail(`${at}.itemCatalog`, "must be true or false");
                     }
                     if (rel.itemCatalog && spec.manifest === undefined) {
-                        fail(
-                            `${at}.itemCatalog`,
-                            "needs a `manifest` naming the package to fetch",
-                        );
+                        fail(`${at}.itemCatalog`, "needs a `manifest` naming the package to fetch");
                     }
                     spec.itemCatalog = rel.itemCatalog;
                 }
@@ -1397,9 +1424,7 @@ function normalizePackageBuild(value) {
                 "reads, and that package validates what is inside it",
         );
     }
-    return /** @type {Readonly<PackageBuildSection>} */ (
-        deepFreeze(structuredClone(value))
-    );
+    return /** @type {Readonly<PackageBuildSection>} */ (deepFreeze(structuredClone(value)));
 }
 
 /**
@@ -1427,19 +1452,18 @@ function normalizePackageBuild(value) {
  * Art now travels with the builder it belongs to, which is the one place a type
  * is already declared.
  *
- * @param {unknown} value
- * @returns {{itemBuilders: Readonly<Record<string, Function>>,
- *            itemArt: Readonly<Record<string, string>>}}
+ * @param {unknown} value - One registry: type → entry.
+ * @param {string} at - The configuration path to report against.
+ * @returns {{itemBuilders: Record<string, Function>,
+ *            itemArt: Record<string, string>,
+ *            itemFields: Record<string, readonly object[]>}}
  *   The `system` builder for each type, and the default art for those types
  *   that paired one. The art table is deliberately *sparse*: a bare-function
  *   entry contributes no key, which is what distinguishes "no default art" from
  *   an empty one.
  */
-function normalizeItemBuilders(value) {
-    if (value === undefined) {
-        return { itemBuilders: Object.freeze({}), itemArt: Object.freeze({}) };
-    }
-    if (!isPlainObject(value)) fail("itemBuilders", "must be an object");
+function normalizeOneRegistry(value, at) {
+    if (!isPlainObject(value)) fail(at, "must be an object");
     const input = /** @type {Record<string, unknown>} */ (value);
 
     /** @type {Record<string, Function>} */
@@ -1456,46 +1480,167 @@ function normalizeItemBuilders(value) {
         }
         if (!isPlainObject(entry)) {
             fail(
-                `itemBuilders.${type}`,
+                `${at}.${type}`,
                 "must be a builder function, or an object with a `system` builder",
             );
         }
         const paired = /** @type {Record<string, unknown>} */ (entry);
-        rejectUnknownKeys(paired, ITEM_BUILDER_KEYS, `itemBuilders.${type}.`);
+        rejectUnknownKeys(paired, ITEM_BUILDER_KEYS, `${at}.${type}.`);
         if (typeof paired.system !== "function") {
-            fail(`itemBuilders.${type}.system`, "must be a function");
+            fail(`${at}.${type}.system`, "must be a function");
         }
         itemBuilders[type] = /** @type {Function} */ (paired.system);
         if (paired.img !== undefined) {
-            itemArt[type] = requireNonEmptyString(
-                paired.img,
-                `itemBuilders.${type}.img`,
-            );
+            itemArt[type] = requireNonEmptyString(paired.img, `${at}.${type}.img`);
         }
         if (paired.fields !== undefined) {
             if (!Array.isArray(paired.fields)) {
-                fail(`itemBuilders.${type}.fields`, "must be an array");
+                fail(`${at}.${type}.fields`, "must be an array");
             }
             for (const [index, field] of paired.fields.entries()) {
                 if (!isPlainObject(field)) {
-                    fail(
-                        `itemBuilders.${type}.fields[${index}]`,
-                        "must be a field declaration object",
-                    );
+                    fail(`${at}.${type}.fields[${index}]`, "must be a field declaration object");
                 }
                 requireNonEmptyString(
                     /** @type {Record<string, unknown>} */ (field).to,
-                    `itemBuilders.${type}.fields[${index}].to`,
+                    `${at}.${type}.fields[${index}].to`,
                 );
             }
             itemFields[type] = Object.freeze([...paired.fields]);
         }
     }
 
+    return { itemBuilders, itemArt, itemFields };
+}
+
+/**
+ * The declared item-builder registries, and the vocabulary their union gives
+ * (#58).
+ *
+ * **One registry is a ceiling, not a default.** The accepted type list is the
+ * registry's keys, which is what makes a type impossible to accept without a
+ * builder behind it (#1504) — and, with one registry, impossible to accept a
+ * type a *second* system declares. A tree feeding two systems has both:
+ * `spell`, `invocation` and `psionic` are HM3's, `mysticalability` and
+ * `projectilegear` are SoHL's, and `skill` is both systems' under one name and
+ * two data models.
+ *
+ * So `itemBuilders` accepts either form:
+ *
+ * - **A registry** — `{ skill: fn, … }`. Unchanged, and what every existing
+ *   configuration declares. It names no system, because there is only one.
+ * - **A list of registries** — `[{ system: "sohl", builders: {…} }, …]`. The
+ *   vocabulary is the **union** of their keys; a type more than one declares
+ *   keeps a builder per system, so nothing is chosen for the build silently.
+ *
+ * The **flat** tables — `itemBuilders`, `itemArt`, `itemFields` — are the union
+ * with the first declaring registry winning a collision. They answer a
+ * single-system build, where a collision cannot arise; a build with two systems
+ * asks by system, and `itemTypesBySeveralSystems` names the types where asking
+ * flatly would be answering the wrong question. See `engine/item-registry.mjs`,
+ * which refuses exactly those without a system.
+ *
+ * @param {unknown} value - The declared `itemBuilders`.
+ * @returns {{itemBuilders: Readonly<Record<string, Function>>,
+ *            itemArt: Readonly<Record<string, string>>,
+ *            itemFields: Readonly<Record<string, readonly object[]>>,
+ *            itemBuildersBySystem: Readonly<Record<string, Readonly<Record<string, Function>>>>,
+ *            itemArtBySystem: Readonly<Record<string, Readonly<Record<string, string>>>>,
+ *            itemFieldsBySystem: Readonly<Record<string, Readonly<Record<string, readonly object[]>>>>,
+ *            itemTypesBySeveralSystems: ReadonlySet<string>}}
+ *   The flat tables, the per-system ones, and the contested types.
+ */
+function normalizeItemBuilders(value) {
+    const empty = Object.freeze({});
+    if (value === undefined) {
+        return {
+            itemBuilders: empty,
+            itemArt: empty,
+            itemFields: empty,
+            itemBuildersBySystem: empty,
+            itemArtBySystem: empty,
+            itemFieldsBySystem: empty,
+            itemTypesBySeveralSystems: Object.freeze(new Set()),
+        };
+    }
+
+    /** @type {{system: string|null, tables: ReturnType<typeof normalizeOneRegistry>}[]} */
+    const registries = [];
+
+    if (Array.isArray(value)) {
+        const seen = new Set();
+        for (const [index, entry] of value.entries()) {
+            const at = `itemBuilders[${index}]`;
+            if (!isPlainObject(entry)) {
+                fail(
+                    at,
+                    "must be `{ system, builders }` — a registry and the system it belongs to",
+                );
+            }
+            const declared = /** @type {Record<string, unknown>} */ (entry);
+            rejectUnknownKeys(declared, ITEM_REGISTRY_KEYS, `${at}.`);
+            const system = requireNonEmptyString(declared.system, `${at}.system`);
+            if (seen.has(system)) {
+                fail(
+                    at,
+                    `declares a second registry for \`${system}\` — a system has one ` +
+                        `item vocabulary, so merge them at their source`,
+                );
+            }
+            seen.add(system);
+            registries.push({
+                system,
+                tables: normalizeOneRegistry(declared.builders, `${at}.builders`),
+            });
+        }
+    } else {
+        registries.push({ system: null, tables: normalizeOneRegistry(value, "itemBuilders") });
+    }
+
+    /** @type {Record<string, Function>} */
+    const itemBuilders = {};
+    /** @type {Record<string, string>} */
+    const itemArt = {};
+    /** @type {Record<string, readonly object[]>} */
+    const itemFields = {};
+    /** @type {Record<string, Readonly<Record<string, Function>>>} */
+    const itemBuildersBySystem = {};
+    /** @type {Record<string, Readonly<Record<string, string>>>} */
+    const itemArtBySystem = {};
+    /** @type {Record<string, Readonly<Record<string, readonly object[]>>>} */
+    const itemFieldsBySystem = {};
+    /** @type {Map<string, number>} */
+    const declaringSystems = new Map();
+
+    for (const { system, tables } of registries) {
+        for (const [type, builder] of Object.entries(tables.itemBuilders)) {
+            declaringSystems.set(type, (declaringSystems.get(type) ?? 0) + 1);
+            if (!(type in itemBuilders)) itemBuilders[type] = builder;
+        }
+        for (const [type, art] of Object.entries(tables.itemArt)) {
+            if (!(type in itemArt)) itemArt[type] = art;
+        }
+        for (const [type, fields] of Object.entries(tables.itemFields)) {
+            if (!(type in itemFields)) itemFields[type] = fields;
+        }
+        if (system === null) continue;
+        itemBuildersBySystem[system] = Object.freeze(tables.itemBuilders);
+        itemArtBySystem[system] = Object.freeze(tables.itemArt);
+        itemFieldsBySystem[system] = Object.freeze(tables.itemFields);
+    }
+
     return {
         itemBuilders: Object.freeze(itemBuilders),
         itemArt: Object.freeze(itemArt),
         itemFields: Object.freeze(itemFields),
+        itemBuildersBySystem: Object.freeze(itemBuildersBySystem),
+        itemArtBySystem: Object.freeze(itemArtBySystem),
+        itemFieldsBySystem: Object.freeze(itemFieldsBySystem),
+        itemTypesBySeveralSystems: Object.freeze(
+            new Set(
+                [...declaringSystems.entries()].filter(([, count]) => count > 1).map(([t]) => t),
+            ),
+        ),
     };
 }
 
@@ -1556,9 +1701,7 @@ function normalizePublish(value) {
     if (manifestsInput !== undefined && !isPlainObject(manifestsInput)) {
         fail("publish.manifests", "must be an object");
     }
-    const manifests = /** @type {Record<string, unknown>} */ (
-        manifestsInput ?? {}
-    );
+    const manifests = /** @type {Record<string, unknown>} */ (manifestsInput ?? {});
     rejectUnknownKeys(manifests, MANIFEST_KEYS, "publish.manifests.");
 
     const addressInput = publish.address;
@@ -1589,26 +1732,15 @@ function normalizePublish(value) {
             DEFAULT_ADDRESS_SCHEME.landing
         :   optionalString(address.landing, "publish.address.landing");
     if (!LANDING_RULES.includes(landing)) {
-        fail(
-            "publish.address.landing",
-            `must be one of ${LANDING_RULES.join(", ")}`,
-        );
+        fail("publish.address.landing", `must be one of ${LANDING_RULES.join(", ")}`);
     }
 
     return Object.freeze({
         site: normalizeSiteMode(publish.site),
         address: Object.freeze({ prefix, landing }),
         manifests: Object.freeze({
-            publish: optionalBoolean(
-                manifests.publish,
-                "publish.manifests.publish",
-                false,
-            ),
-            consume: optionalBoolean(
-                manifests.consume,
-                "publish.manifests.consume",
-                false,
-            ),
+            publish: optionalBoolean(manifests.publish, "publish.manifests.publish", false),
+            consume: optionalBoolean(manifests.consume, "publish.manifests.consume", false),
         }),
     });
 }
@@ -1629,13 +1761,9 @@ function normalizePublish(value) {
  */
 export function defineConfig(config) {
     if (!isPlainObject(config)) {
-        throw new TypeError(
-            "package-build config: expected a configuration object.",
-        );
+        throw new TypeError("package-build config: expected a configuration object.");
     }
-    const input = /** @type {Record<string, unknown>} */ (
-        /** @type {unknown} */ (config)
-    );
+    const input = /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (config));
     rejectUnknownKeys(input, CONFIG_KEYS, "");
 
     const rootDir = requireNonEmptyString(input.rootDir, "rootDir");
@@ -1650,21 +1778,14 @@ export function defineConfig(config) {
     const packageKind = input.packageKind;
     if (
         typeof packageKind !== "string" ||
-        !(
-            /** @type {readonly string[]} */ (PACKAGE_KINDS).includes(
-                packageKind,
-            )
-        )
+        !(/** @type {readonly string[]} */ (PACKAGE_KINDS).includes(packageKind))
     ) {
         fail("packageKind", `must be one of: ${PACKAGE_KINDS.join(", ")}`);
     }
 
     if (!Array.isArray(input.packs)) fail("packs", "must be an array");
-    if (input.packs.length === 0)
-        fail("packs", "must declare at least one pack");
-    const packs = input.packs.map((pack, index) =>
-        normalizePack(pack, `packs[${index}]`),
-    );
+    if (input.packs.length === 0) fail("packs", "must declare at least one pack");
+    const packs = input.packs.map((pack, index) => normalizePack(pack, `packs[${index}]`));
 
     // One list, so the compile order and the directory list cannot disagree —
     // they used to be `PACK_CONFIGS` and `SOURCE_PACKS`, maintained apart (#1508).
@@ -1686,9 +1807,7 @@ export function defineConfig(config) {
     const declaredSystems = new Set(Object.keys(systems));
     /** `relationships.systems`, for the derivations that still consult it. */
     const relationshipSystems = /** @type {{id?: string}[]} */ (
-        (isPlainObject(input.relationships) ?
-            input.relationships.systems
-        :   null) ?? []
+        (isPlainObject(input.relationships) ? input.relationships.systems : null) ?? []
     );
 
     // A name that resolves to nothing is a build error rather than a
@@ -1747,32 +1866,33 @@ export function defineConfig(config) {
         defaultsByType.set(pack.type, pack.name);
     }
 
-    if (
-        input.skipDirectories !== undefined &&
-        !Array.isArray(input.skipDirectories)
-    ) {
+    if (input.skipDirectories !== undefined && !Array.isArray(input.skipDirectories)) {
         fail("skipDirectories", "must be an array");
     }
     const skipDirectories = (input.skipDirectories ?? []).map((name, index) =>
         requireNonEmptyString(name, `skipDirectories[${index}]`),
     );
 
-    const foundryPackage = requireNonEmptyString(
-        input.foundryPackage,
-        "foundryPackage",
-    );
+    const foundryPackage = requireNonEmptyString(input.foundryPackage, "foundryPackage");
 
-    const { itemBuilders, itemArt, itemFields } = normalizeItemBuilders(
-        input.itemBuilders,
-    );
+    const {
+        itemBuilders,
+        itemArt,
+        itemFields,
+        itemBuildersBySystem,
+        itemArtBySystem,
+        itemFieldsBySystem,
+        itemTypesBySeveralSystems,
+    } = normalizeItemBuilders(input.itemBuilders);
+    // The union across every declared registry (#58) — the flat table already
+    // holds every key any of them declares, so this stays "the registry's keys"
+    // rather than becoming a second list to keep in step (#1504).
     const itemTypes = Object.freeze(new Set(Object.keys(itemBuilders)));
+    const docEntryTypes = Object.freeze(new Set([...itemTypes, "macro", ...MAP_TYPES]));
 
     return Object.freeze({
         rootDir,
-        contentPackage: requireNonEmptyString(
-            input.contentPackage,
-            "contentPackage",
-        ),
+        contentPackage: requireContentPackage(input.contentPackage, docEntryTypes),
         foundryPackage,
         packageKind: /** @type {PackageKind} */ (packageKind),
         // Foundry serves a package's files from `<kind>/<id>/`, so this is the
@@ -1798,9 +1918,8 @@ export function defineConfig(config) {
                     // which is the duplication this whole change exists to
                     // remove. Several entries have no single answer and get
                     // none.
-                : relationshipSystems.length === 1 ?
-                    (relationshipSystems[0]?.id ?? null)
-                :   null,
+                : relationshipSystems.length === 1 ? (relationshipSystems[0]?.id ?? null)
+                : null,
             // Derived here where the answer is pure data — the `verified` of
             // whichever system the package-wide block takes — and supplied by
             // the loader otherwise. The loader is the half that may do I/O, and
@@ -1811,21 +1930,19 @@ export function defineConfig(config) {
                 (() => {
                     const id =
                         requiresSystem ??
-                        (Object.keys(systems).length === 1 ?
-                            Object.keys(systems)[0]
-                        :   null);
-                    return id ?
-                            (systems[id]?.compatibility?.verified ?? null)
-                        :   null;
+                        (Object.keys(systems).length === 1 ? Object.keys(systems)[0] : null);
+                    return id ? (systems[id]?.compatibility?.verified ?? null) : null;
                 })() ??
-                (isPlainObject(input.stats) ?
-                    input.stats[DERIVED_SYSTEM_VERSION]
-                :   null) ??
+                (isPlainObject(input.stats) ? input.stats[DERIVED_SYSTEM_VERSION] : null) ??
                 null,
         }),
         itemBuilders,
         itemArt,
         itemFields,
+        itemBuildersBySystem,
+        itemArtBySystem,
+        itemFieldsBySystem,
+        itemTypesBySeveralSystems,
         // Resolved once, here, and read everywhere through
         // `loadPackConfig()`. The doc-entry *concept* is the engine's —
         // a note that carries documentation is not a SoHL idea — but the
@@ -1833,18 +1950,13 @@ export function defineConfig(config) {
         // runtime. Two would drift, which is the whole reason the composition
         // was written down in one place to begin with.
         itemTypes,
-        docEntryTypes: Object.freeze(
-            new Set([...itemTypes, "macro", ...MAP_TYPES]),
-        ),
+        docEntryTypes,
         skipDirectories: Object.freeze(skipDirectories),
         packs: Object.freeze(packs),
         packDirectories: Object.freeze(packDirectories),
         docs: normalizeDocs(input.docs),
         site: normalizeSite(input.site),
-        compatibility: normalizeCompatibility(
-            input.compatibility,
-            "compatibility",
-        ),
+        compatibility: normalizeCompatibility(input.compatibility, "compatibility"),
         relationships: normalizeRelationships(input.relationships),
         systems,
         requiresSystem,