@heroiclands/package-build 19.0.0 → 20.2.0

package/engine/field-reference.mjs

@@ -34,7 +34,7 @@
  * @module
  */
 
-import { authoredFields } from "./field-spec.mjs";
+import { authoredFields, runtimeOnlyFields } from "./field-spec.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 
 /**
@@ -104,7 +104,15 @@ function fieldTable(fields) {
             `\`${field.name}\``,
             cell(field.shape ?? "as authored"),
             field.required ? "**yes**" : "no",
-            field.required ? "—" : renderDefault(field.default),
+            // Three different answers, and the third is not a value (#329). A
+            // required field has no default because omitting it fails the
+            // build; an `omitWhenAbsent` field has none because omitting it
+            // omits the *key*, leaving the data model to answer. Rendering
+            // both as the em dash a missing default already prints would put
+            // two opposite behaviours in one cell.
+            field.required ? "—"
+            : field.omitWhenAbsent ? "_omitted_"
+            : renderDefault(field.default),
             cell(field.describe ?? ""),
         ]),
     ];
@@ -139,6 +147,40 @@ function sharedExemptions(fields) {
     ]);
 }
 
+/**
+ * The fields of one type that a note may **never** write (#330).
+ *
+ * A type's table lists what an author writes, and says nothing about the rest
+ * of its schema — which is right for a constant or a derived value, since
+ * nothing happens if a note writes the path anyway. A runtime-only field is
+ * different in the way that matters to a reader: it is a real part of the
+ * document, it is spelled beside fields they *do* write — `onsetDate` sits next
+ * to `onsetDurationFormula` — and authoring it fails the build. Leaving it
+ * unmentioned means an author meets the rule as an error rather than as
+ * documentation.
+ *
+ * Rendered from each field's own reason, for the same purpose
+ * {@link sharedExemptions} renders `topLevelMeans` for: the declaration already
+ * states it, and a page restating it in other words is a second copy to keep
+ * true.
+ *
+ * @param {readonly object[]} fields - The type's declaration.
+ * @returns {string[]} Markdown lines, empty when the type declares none.
+ */
+function runtimeState(fields) {
+    const runtime = runtimeOnlyFields(/** @type {never} */ (fields));
+    if (!runtime.length) return [];
+    return [
+        "**Never authored.** These fields are part of the document and are " +
+            "written during play, so a note that declares one fails the build. " +
+            "Left out of the compiled document entirely, they carry the data " +
+            "model's own initial value until play writes them.",
+        "",
+        ...runtime.map((field) => `- \`${field.to}\` — ${cell(field.runtimeOnly)}`),
+        "",
+    ];
+}
+
 /**
  * A minimal note for one type: the frontmatter envelope every note carries,
  * plus exactly the `sohl:` fields the type requires.
@@ -168,7 +210,13 @@ function workedExample(type, fields) {
         // No `package:`. A note's package is the repository's configured
         // `contentPackage`, and declaring the field is a build error (#56) —
         // this example is the smallest note that compiles.
-        "id: <16-character id>",
+        //
+        // No `id:` either, for the same reason it is not shown optional-first:
+        // a note's document `_id` derives from its canonical address (#270,
+        // #277), and the authored field is the escape hatch for keeping a
+        // document's identity across a shortcode rename, not part of the
+        // envelope. This block is the one an author copies as a template, so
+        // showing the field taught every note in the tree to write it (#314).
         "sohl:",
         "  templatePriority: null",
     ];
@@ -221,8 +269,11 @@ export function renderItemFieldReference({
             `repository compiles declare their frontmatter below. Every field ` +
             `is written under a note's \`sohl:\` block; a dotted name such as ` +
             `\`impact.die\` is a nested key. A field a note does not carry ` +
-            `takes the default shown, and a **required** field has none — ` +
-            `omitting it fails the build rather than guessing.`,
+            `takes the default shown; a **required** field has none — omitting ` +
+            `it fails the build rather than guessing — and one shown as ` +
+            `_omitted_ has none either, because leaving it out leaves the key ` +
+            `out of the compiled document, so the data model's own initial ` +
+            `value stands.`,
         "",
     );
 
@@ -233,6 +284,7 @@ export function renderItemFieldReference({
             ...fieldTable(declared[type]),
             "",
             ...sharedExemptions(declared[type]),
+            ...runtimeState(declared[type]),
             ...workedExample(type, declared[type]),
             "",
         );

package/engine/field-spec.mjs

@@ -43,9 +43,9 @@
  * @module
  */
 
-import { legacyKeyOf, resolveFieldValue, setPath } from "./system-block.mjs";
+import { legacyKeyOf, resolveFieldValue, retiredTopLevelKey, setPath } from "./system-block.mjs";
 
-export { legacyKeyOf, setPath };
+export { legacyKeyOf, retiredTopLevelKey, setPath };
 
 /**
  * @typedef {object} FieldSpec
@@ -109,6 +109,13 @@ export { legacyKeyOf, setPath };
  *   describe the *document* rather than the note: `<system>.system.<to>` and
  *   the legacy in-block `<system>.<name>`. Absent means the ordinary case —
  *   the top level is read, as the third step.
+ *
+ *   **It is read from the other side too**, because the statement is symmetric:
+ *   if the two positions hold unrelated quantities then the *in-block* position
+ *   is not the note-level field either, so a check about the note-level field
+ *   reads past it. `engine/frontmatter-lint.mjs` resolves that through
+ *   `collidingBlockKeys`. Read for the emitted field alone until #312, which is
+ *   how an affiliation's office style came to answer for its page heading.
  * @property {string} [shape] - Human-readable shape, for documentation. Comes
  *   paired with `read` from one of the coercion constants below.
  * @property {(raw: any, ctx: {fm: object, field: FieldSpec}) => any} [read] -
@@ -138,6 +145,78 @@ export { legacyKeyOf, setPath };
  *   note, so it declares none.
  * @property {any|((fm: object) => any)} [value] - For a field with no `name`:
  *   the constant, or a function deriving it from the frontmatter.
+ * @property {boolean} [omitWhenAbsent] - **The key is left out entirely when
+ *   the note does not carry the field** (#329), rather than written from a
+ *   declared default.
+ *
+ *   Every other field answers absence with a value: an unauthored `weight` is
+ *   `0`, an unauthored `seat` is `null`. That is right wherever the type has an
+ *   opinion about the empty case. It is wrong wherever the **DataModel** is the
+ *   one holding the answer — an affliction's `onsetDurationFormula` has no
+ *   compile-time value, and writing `null` over it does not merely fail to
+ *   help: it makes "the author said none" and "the author said nothing"
+ *   indistinguishable to every reader downstream, and it overwrites an
+ *   `initial` the system chose on purpose.
+ *
+ *   It is the other conditional row of the same table
+ *   {@link FieldSpec.runtimeOnly} completes, and the two differ only in what
+ *   they do about an *authored* value:
+ *
+ *   | declaration      | authored | absent |
+ *   | --- | --- | --- |
+ *   | ordinary         | emitted  | default written |
+ *   | `omitWhenAbsent` | emitted  | key omitted |
+ *   | `runtimeOnly`    | refused  | key omitted |
+ *
+ *   **A field declaring it must declare no `default`**, and the two are
+ *   contradictory rather than merely redundant — a default is a value for the
+ *   absent case, which is the case this says has none. Nor may it be combined
+ *   with `required` (which fails the build on absence, so nothing is ever
+ *   omitted) or with `runtimeOnly` (which is never emitted at all). The shipped
+ *   declarations are checked for all three in `tests/item-fields.test.ts`.
+ *
+ *   Unlike `runtimeOnly` this is a flag rather than a reason, because there is
+ *   only ever one reason and no message prints it: the DataModel's `initial`
+ *   stands. What an author needs to know is *that* the field has no default,
+ *   which the generated reference states in the field's own row.
+ * @property {string} [runtimeOnly] - **What the field holds once play has
+ *   started** — declared on a field the *document* writes for itself, which no
+ *   note may author (#330).
+ *
+ *   A schema declares plenty of fields a compiled document has no business
+ *   carrying: an affliction's `onsetDate` is the world time its onset fired
+ *   at, crystallized when the phase runs. World time does not exist while
+ *   content is compiled, so there is no authoring-time value — and `0` is
+ *   itself a valid world time, which is why such a field is nullable rather
+ *   than sentinelled and why a default cannot stand in for one.
+ *
+ *   Nothing used to stop a note writing one. The three checks that might have
+ *   each declined for its own correct reason —
+ *   {@link module:engine/system-block.unknownBlockKeys} reads the block's top
+ *   level and never descends into `system:`;
+ *   {@link module:engine/system-block.mergeSystemData} passes through every
+ *   authored path no declared field claims; and the schema check's fatal
+ *   direction is *undeclared*, which a field the schema really does declare
+ *   satisfies. What was missing was a rule saying "declared by the system,
+ *   but never authorable", and this is it.
+ *
+ *   Declaring it does two things, which are the two directions of one fact:
+ *
+ *   | declaration | authored | absent |
+ *   | --- | --- | --- |
+ *   | ordinary | emitted | default written |
+ *   | runtime-only | **refused** | key omitted |
+ *
+ *   The refusal is {@link module:engine/runtime-only-fields.assertNoRuntimeOnlyFields}'s;
+ *   the omission is {@link buildFromFields}'s. A runtime-only entry declares a
+ *   `to` and **no `name`**, so it stays out of {@link authoredFields} and every
+ *   author-facing surface built on it, while still giving `mergeSystemData` a
+ *   claimed path and the refusal something to name.
+ *
+ *   **The value is the reason**, as {@link FieldSpec.topLevelMeans}'s is: a
+ *   boolean would record the decision and lose the case for it, and the reason
+ *   is what the refusal's message and the generated reference both print. It
+ *   completes the sentence "it holds …".
  * @property {string} describe - One line, for the author-facing reference.
  */
 
@@ -228,6 +307,29 @@ export function readsLegacyKey(field, from) {
     return field?.legacyKey !== undefined && from === "block";
 }
 
+/**
+ * Whether a resolution read a field from the top-level key `data:` gathered it
+ * off — the shared level's retiring position (#332).
+ *
+ * {@link readsLegacyKey}'s sibling, and the same signal: a finding here counts
+ * one note still on the pre-`data:` spelling, so the sweep has something to
+ * count down instead of a corpus nobody has surveyed.
+ *
+ * The `from` tag already carries the whole answer — step 3b is the only thing
+ * that produces it, and it produces it only for a `data.` source — so this is a
+ * name for the question rather than a second test of it. Named all the same,
+ * because a compile-time report and the frontmatter lint both ask it and must
+ * not drift apart about what counts.
+ *
+ * @param {FieldSpec} field - The declaration.
+ * @param {import("./system-block.mjs").FieldSource} from - Where
+ *   {@link resolveFieldValue} said the value came from.
+ * @returns {boolean} True when the value came from the retiring top-level key.
+ */
+export function readsRetiredTopLevel(field, from) {
+    return from === "topLevel" && retiredTopLevelKey(field) !== undefined;
+}
+
 /**
  * Read one declared field out of a note's frontmatter.
  *
@@ -249,13 +351,77 @@ export function readsLegacyKey(field, from) {
  *   rather than a returned list because the caller is a compiler, which already
  *   knows the note and how to locate a key in it; this module knows neither and
  *   would have to invent a finding shape to say so.
+ * @param {(field: FieldSpec) => void} [options.onRetiredTopLevel] - Called with
+ *   each field read from the top-level key `data:` gathered it off (#332). The
+ *   shared level's counterpart to `onLegacyKey`, and a separate callback
+ *   because it is a separate position: a note may have moved one of the two and
+ *   not the other, and a caller that conflated them would tell its author to
+ *   fix the wrong line.
  * @returns {any} The value to emit.
  */
-export function readField(field, fm, { block = "sohl", onLegacyKey } = {}) {
+export function readField(field, fm, options = {}) {
+    return readFieldEntry(field, fm, options).value;
+}
+
+/**
+ * The same read, reporting **where the value came from** as well.
+ *
+ * {@link readField} answers "what does this field hold", which is what almost
+ * every caller wants. A builder has one further question — *should the key be
+ * written at all* — and it cannot be answered from the value: `null` from a
+ * note and `null` from a declared default are the same value and opposite
+ * facts (#329).
+ *
+ * So the position rides back beside the value, resolved **once**. The
+ * alternative is a builder that calls {@link resolveFieldValue} for the source
+ * and {@link readField} for the value, which resolves the position twice and
+ * states in two places the rule that a field is authored in exactly one.
+ *
+ * @param {FieldSpec} field - The declaration.
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} [options] - Options, as {@link readField} takes them.
+ * @param {string} [options.block="sohl"] - Which system's block to resolve
+ *   against.
+ * @param {(field: FieldSpec) => void} [options.onLegacyKey] - See
+ *   {@link readField}.
+ * @param {(field: FieldSpec) => void} [options.onRetiredTopLevel] - See
+ *   {@link readField}.
+ * @returns {{value: any, from: import("./system-block.mjs").FieldSource}} The
+ *   value to emit, and the position it was read from.
+ */
+export function readFieldEntry(field, fm, { block = "sohl", onLegacyKey, onRetiredTopLevel } = {}) {
     const { value, from } = resolveFieldValue(field, fm, { block });
-    if (from === "value") return value;
+    if (from === "value") return { value, from };
     if (onLegacyKey && readsLegacyKey(field, from)) onLegacyKey(field);
-    return field.read ? field.read(value, { fm, field }) : value;
+    if (onRetiredTopLevel && readsRetiredTopLevel(field, from)) onRetiredTopLevel(field);
+    return { value: field.read ? field.read(value, { fm, field }) : value, from };
+}
+
+/**
+ * Whether a note supplied a value for a field, as opposed to a default doing it.
+ *
+ * The question {@link FieldSpec.omitWhenAbsent} turns on, asked of the
+ * *position* rather than of the value — which cannot answer it, since a
+ * declared `default: null` and an authored `null` are indistinguishable once
+ * the value is in hand (#329).
+ *
+ * `undefined` counts as absent whatever position reported it, because writing
+ * the key then emits a value `JSON.stringify` drops — the key present in the
+ * object and absent from the pack, which is the sort of disagreement this
+ * package exists to remove. It arrives from one place: the in-block step
+ * answers `value ?? field.default` for a key authored as `null`, so a field
+ * declaring no default resolves through "authored" to nothing at all. A field
+ * that also declares a `read` never reaches this, since its coercion has by
+ * then turned the `undefined` into whatever it makes of an absent value —
+ * ordinarily `null`, which is a value the note asked for and is emitted.
+ *
+ * @param {import("./system-block.mjs").FieldSource} from - Where
+ *   {@link resolveFieldValue} said the value came from.
+ * @param {any} value - The value it gave back.
+ * @returns {boolean} True when the note wrote one.
+ */
+export function isAuthored(from, value) {
+    return from !== "default" && value !== undefined;
 }
 
 /**
@@ -269,13 +435,37 @@ export function readField(field, fm, { block = "sohl", onLegacyKey } = {}) {
  * @param {(field: FieldSpec) => void} [options.onLegacyKey] - Passed through to
  *   {@link readField}: called with each field the note authored at the position
  *   it is being swept off (#305).
+ * @param {(field: FieldSpec) => void} [options.onRetiredTopLevel] - Passed
+ *   through to {@link readField}: called with each field the note authored at
+ *   the top-level key `data:` gathered it off (#332).
  * @returns {(fm: object) => object} A `system`-block builder.
  */
-export function buildFromFields(fields, { block = "sohl", onLegacyKey } = {}) {
+export function buildFromFields(fields, { block = "sohl", onLegacyKey, onRetiredTopLevel } = {}) {
     return function buildDeclaredSystem(fm) {
         const out = {};
         for (const field of fields) {
-            setPath(out, field.to, readField(field, fm, { block, onLegacyKey }));
+            // A runtime-only field is not this builder's to write (#330). It is
+            // declared so that the path is *claimed* — so the verbatim
+            // passthrough leaves it alone and the refusal has a name — not so
+            // that a compile-time answer is invented for a question only play
+            // can answer. Omitting the key is what leaves the DataModel's own
+            // `initial` standing; writing the `undefined` a source-less
+            // declaration resolves to would put the key in the document.
+            if (field.runtimeOnly) continue;
+            const { value, from } = readFieldEntry(field, fm, {
+                block,
+                onLegacyKey,
+                onRetiredTopLevel,
+            });
+            // The other conditional row: a field whose *absence* is meaningful
+            // (#329). Writing a declared default would answer a question the
+            // note did not ask — "this affliction's onset takes `null` days" —
+            // and would make the field's unset state indistinguishable from an
+            // authored one for every reader downstream. Omitting the key leaves
+            // the DataModel's own `initial` to say it instead, which is the one
+            // place the answer actually lives.
+            if (field.omitWhenAbsent && !isAuthored(from, value)) continue;
+            setPath(out, field.to, value);
         }
         return out;
     };
@@ -295,3 +485,20 @@ export function buildFromFields(fields, { block = "sohl", onLegacyKey } = {}) {
 export function authoredFields(fields) {
     return fields.filter((field) => field.name !== undefined);
 }
+
+/**
+ * The fields of a declaration a note may **never** write.
+ *
+ * The complement of {@link authoredFields} in the direction that matters: those
+ * are the fields an author may write, these are the ones authoring is an error
+ * (#330). Everything else in a declaration — a constant, a derived value — is
+ * simply not authored, which is a statement about the *builder* rather than
+ * about the author, and says nothing about what happens if a note writes the
+ * path anyway.
+ *
+ * @param {readonly FieldSpec[]} fields - The declaration.
+ * @returns {FieldSpec[]} Only the fields declaring `runtimeOnly`.
+ */
+export function runtimeOnlyFields(fields) {
+    return (fields ?? []).filter((field) => Boolean(field?.runtimeOnly));
+}

package/engine/folder-notes.mjs

@@ -185,6 +185,29 @@ export function folderAddress(pkg, shortcode) {
     return canonicalKey(pkg, NO_SYSTEM, FOLDER_TYPE, shortcode);
 }
 
+/**
+ * The Foundry `_id` a folder note's documents are filed under.
+ *
+ * **The one derivation, because two passes need the same answer.** The folder
+ * pass hashes it here on its way to emitting the `Folder` documents; the
+ * content index publishes it, through `noteDocId`, for a consumer who will
+ * never run this build. Deriving it twice is how the index came to publish a
+ * plausible-looking id that resolved to nothing — the general id rule hashes a
+ * note's address under the `document` namespace, and a folder's is hashed under
+ * {@link FOLDER_ID_NAMESPACE} (#310).
+ *
+ * An **authored `id` still wins**, and is applied by the caller: this is the
+ * derivation, not the resolution, so the pin rule stays stated once, where
+ * every other note type states it ({@link module:engine/note-ids.noteDocId}).
+ *
+ * @param {string} pkg - The content package.
+ * @param {string} shortcode - The folder's shortcode.
+ * @returns {string} The folder's 16-character Foundry id.
+ */
+export function folderDocId(pkg, shortcode) {
+    return makeId(FOLDER_ID_NAMESPACE, folderAddress(pkg, shortcode));
+}
+
 /**
  * Collect every folder note in a content tree.
  *
@@ -246,7 +269,7 @@ export function collectFolderNotes(notes, pkg) {
             // stable one from its address (#258). Keeping the authored id is
             // what makes this a build change rather than a world migration: a
             // world already holding these folders goes on resolving them.
-            id: authoredId || makeId(FOLDER_ID_NAMESPACE, address),
+            id: authoredId || folderDocId(pkg, shortcode),
             derivedId: !authoredId,
             absPath,
         });

package/engine/foreign-catalog.mjs

@@ -1,3 +1,16 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
 /**
  * @file The item catalogue of a package this repository depends on but does not
  * contain.
@@ -151,13 +164,73 @@ function cacheSchemaArtifact(root, dir) {
     return true;
 }
 
+/**
+ * What each extracted pack is, written beside the items rather than inferred
+ * from the directory it landed in (#58).
+ *
+ * A dependency may ship a pack per system — `items-sohl` and `items-hm3` — and
+ * the two hold documents of the *same* `(type, shortcode)` addresses with
+ * different data models: `skill:awar` exists in both vocabularies and means two
+ * different documents. So a consumer compiling an `hm3` pack has to read the
+ * `hm3` half of the catalogue and no other, and the only place that says which
+ * half a directory is, is the dependency's own manifest at fetch time.
+ *
+ * Held as a manifest at the cache root rather than a marker inside each pack
+ * directory, because those directories are walked as JSON trees: a file dropped
+ * in one would be loaded as though it were a document.
+ *
+ * @type {string}
+ */
+const ITEM_PACKS = "item-packs.json";
+
+/**
+ * What to record about the packs being extracted.
+ *
+ * Exported so the pair is one fact: {@link foreignItemCatalogDirs} reads what
+ * this writes, and a test that hand-wrote the file would prove the reader
+ * against a transcription of the format rather than against the format.
+ *
+ * A pack declaring no `system` records `null` — Foundry requires the field on
+ * an Item pack, so this is the shape of a manifest that is wrong rather than a
+ * case with a meaning, and `null` reads as "neutral", which is the safe way to
+ * be wrong: a neutral pack is read by every system rather than by none.
+ *
+ * @param {readonly object[]} itemPacks - The manifest's Item pack entries.
+ * @returns {Array<{name: string, system: string|null}>} What each one is.
+ */
+export function itemPackManifest(itemPacks) {
+    return itemPacks.map((pack) => ({ name: pack.name, system: pack.system ?? null }));
+}
+
+/**
+ * The system each extracted pack was published for.
+ *
+ * @param {string} dir - The dependency's cache directory.
+ * @returns {Map<string, string|null>} Pack name → its declared system, `null`
+ *   for a pack that declares none.
+ */
+function cachedItemPacks(dir) {
+    const file = path.join(dir, ITEM_PACKS);
+    const declared = JSON.parse(fs.readFileSync(file, "utf8"));
+    return new Map(declared.map((pack) => [pack.name, pack.system ?? null]));
+}
+
 /**
  * Whether a dependency's cache is present and complete.
  *
+ * **A cache without its pack manifest is incomplete**, not merely unlabelled.
+ * One written before #58 holds the items and not what they are, and the two
+ * ways of proceeding without it are both wrong: reading every pack resolves an
+ * `hm3` reference against `sohl` documents — the silent-wrong-output failure
+ * this scoping exists to remove — and reading none fails a build that was
+ * working. Treating it as incomplete makes `content-build deps fetch` refill
+ * it, which is a command the cold-cache path already tells anyone to run.
+ *
  * @param {string} dir - The dependency's cache directory.
  * @returns {boolean} True when it was fetched to completion.
  */
-const isComplete = (dir) => fs.existsSync(path.join(dir, STAMP));
+const isComplete = (dir) =>
+    fs.existsSync(path.join(dir, STAMP)) && fs.existsSync(path.join(dir, ITEM_PACKS));
 
 /**
  * Read a dependency's manifest.
@@ -230,8 +303,18 @@ async function extractItemPacks(id, version, manifest, root, dir) {
         const out = path.join(dir, "items", pack.name);
         fs.mkdirSync(out, { recursive: true });
         await extractPack(src, out, { log: false });
-        log.info(`${id}@${version}: extracted pack "${pack.name}"`);
+        log.info(
+            `${id}@${version}: extracted pack "${pack.name}"` +
+                (pack.system ? ` (system: ${pack.system})` : ""),
+        );
     }
+    // What each pack is, from the only place that knows: the manifest that
+    // declared it (#58). Written before the stamp, so the stamp continues to
+    // mean the cache is whole.
+    fs.writeFileSync(
+        path.join(dir, ITEM_PACKS),
+        `${JSON.stringify(itemPackManifest(itemPacks), null, 4)}\n`,
+    );
     // Last, so a fetch that died partway is never mistaken for a complete one.
     fs.writeFileSync(path.join(dir, STAMP), `${version}\n`);
 }
@@ -637,10 +720,24 @@ export async function fetchAllCatalogs(config) {
  * Reads the cache only. A cold cache is an error naming the command that fills
  * it, rather than a download nobody asked for.
  *
+ * **Scoped to one system when the caller compiles for one (#58)**, exactly as
+ * {@link module:engine/generate.itemPackJsonDirs} scopes the local half. The
+ * two halves answer the same lookup — `loadItemsMap` merges them into one
+ * address space keyed by `subType:shortcode` — so scoping only the local one
+ * leaves the collision it was meant to remove: `skill:awar` is a real address
+ * in both vocabularies, and a `harn-ensemble` actor compiled for `hm3` would
+ * resolve three quarters of its references against whichever document the
+ * dependency's `sohl` pack happened to supply. A pack that declares no system
+ * is neutral and always read; asking for no system reads every pack, which is
+ * every single-system build.
+ *
  * @param {object} config - The resolved build configuration.
- * @returns {string[]} Every cached dependency's item directories.
+ * @param {string|null} [system] - The system the caller is compiling for.
+ *   Omitted or `null`, every cached pack is read.
+ * @returns {Array<{dir: string, package: string}>} Every cached dependency's
+ *   item directories, each with the package that published it.
  */
-export function foreignItemCatalogDirs(config) {
+export function foreignItemCatalogDirs(config, system = null) {
     const dirs = [];
     for (const rel of itemCatalogRelationships(config)) {
         const root = config.paths.foreignCache;
@@ -664,9 +761,17 @@ export function foreignItemCatalogDirs(config) {
         // rewritten: a plain string sort would put `0.8.10` before `0.8.2` and
         // silently resolve every embedded item against the older catalogue
         // (#272).
-        const items = itemsDir(newestVersionDir(cached));
-        for (const name of fs.readdirSync(items)) {
-            dirs.push(path.join(items, name));
+        const newest = newestVersionDir(cached);
+        const packSystems = cachedItemPacks(newest);
+        const items = itemsDir(newest);
+        for (const entry of fs.readdirSync(items, { withFileTypes: true })) {
+            if (!entry.isDirectory()) continue;
+            const packSystem = packSystems.get(entry.name) ?? null;
+            if (system != null && packSystem != null && packSystem !== system) continue;
+            // The dependency's own id travels with its directory (#334): a
+            // being's `model:` names the package its template comes from, and
+            // the address cannot be built from the path.
+            dirs.push({ dir: path.join(items, entry.name), package: rel.id });
         }
     }
     return dirs;

package/engine/foundry-entries.mjs

@@ -133,6 +133,12 @@ export function anchorsOf(entryUuid, entryId, body, name) {
  * @param {string} name - The note's display name.
  * @param {string} address - The note's package-relative address.
  * @param {string} body - The note's markdown body.
+ * **Each entry carries the `id` of the document it addresses**, not only its
+ * UUID. The two are one fact — a UUID ends in the id — but only the entry knows
+ * which derivation produced it: an item's is its note's `fm.id`, and its
+ * documentation journal's is {@link itemDocEntryId} of that. Stating it here is
+ * what lets the content index publish an identity it did not re-derive (#310).
+ *
  * @param {object} ctx - Resolved identities: `{ contentPackage,
  *   foundryPackageId, packRouter }`.
  * @returns {Array<object>} One or two entries, in {@link buildManifest}'s shape.
@@ -201,6 +207,7 @@ export function entriesForNote(fm, name, address, body, ctx) {
                 fm,
                 name,
                 url,
+                id: fm.id,
                 uuid: uuidFor(fm.type, fm.id, fm),
                 doc: docKey,
             },
@@ -211,6 +218,12 @@ export function entriesForNote(fm, name, address, body, ctx) {
                 // On the web the item note renders as one page which *is* its
                 // documentation, so both addresses resolve to the same URL.
                 url,
+                // The journal's **own** id, which is not the item's: the
+                // content index publishes it beside the UUID, so an entry the
+                // index gives an identity to states both halves of it rather
+                // than leaving a consumer to parse the id back out of the
+                // UUID's last segment (#310).
+                id: docEntryId,
                 uuid: docUuid,
                 anchors: docUuid ? anchorsOf(docUuid, docEntryId, body ?? "", name) : undefined,
             },
@@ -226,6 +239,7 @@ export function entriesForNote(fm, name, address, body, ctx) {
             fm,
             name,
             url,
+            id: fm.id,
             uuid: own,
             anchors: own && fm.type === "doc" ? anchorsOf(own, fm.id, body ?? "", name) : undefined,
         },