@heroiclands/package-build 19.0.0 → 20.0.0

package/engine/content-index.mjs

@@ -490,9 +490,9 @@ export function buildIndexRecord({
  * **Lean, and deliberately not the note's frontmatter.** The item's `sohl:`
  * block describes the *item*; copying it onto the journal would assert things
  * about the journal that are not true, and double the file to do it. What the
- * journal has of its own is its addresses, its name, and the file it came from
- * — plus `documents`, naming the record it is the documentation for, so the
- * link is navigable in both directions.
+ * journal has of its own is its addresses, its **id**, its name, and the file
+ * it came from — plus `documents`, naming the record it is the documentation
+ * for, so the link is navigable in both directions.
  *
  * On the web both addresses resolve to one page — the item note renders as the
  * page that *is* its documentation — so the slug is shared and only the
@@ -514,6 +514,11 @@ function buildDocRecord({ frontmatter, address, entry, file, contentPackage, anc
             type: `doc${frontmatter.type}`,
             shortcode: frontmatter.shortcode,
             name: frontmatter.name,
+            // The journal's own `_id`, taken from the entry rather than
+            // re-derived: every entry the index gives an identity to publishes
+            // both the id and the UUID, computed once by whatever owns that
+            // entry's derivation (#310).
+            id: entry.id,
             nameAscii: asciiName(frontmatter?.name?.full),
             address: { slug: address.slug, canonical: entry.key },
             // The record this is the documentation *for*. `documentation` is
@@ -595,15 +600,13 @@ export function collectContentIndex(
         }
     }
 
-    // Content path, then the note id. The walk yields in directory-read order,
-    // which is not a fact about the content, and a rebuild that reorders lines
-    // would make every regeneration look like a change.
     // Content path, then the canonical address, then the note id. The walk
     // yields in directory-read order, which is not a fact about the content,
     // and a rebuild that reordered lines would make every regeneration look
     // like a change. The address comes before the id because an item note's two
-    // records share a file and only one of them carries an id — ordering on the
-    // id first would put the documentation ahead of the item it documents.
+    // records share a file and carry two different ids — ordering on the id
+    // first would sort the documentation against the item it documents by a
+    // pair of hashes, which is no order at all.
     records.sort(
         (a, b) =>
             String(a.file.path).localeCompare(String(b.file.path), "en") ||

package/engine/content-links.mjs

@@ -70,7 +70,13 @@ import { NO_SYSTEM, systemOf } from "./document-subtypes.mjs";
 import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./note-claims.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { searchableFrontmatter } from "./note-package.mjs";
-import { canonicalKey, PACKAGE_BASE, readCanonicalKey } from "./content-address.mjs";
+import {
+    blockSystem,
+    canonicalKey,
+    expandAddress,
+    PACKAGE_BASE,
+    readCanonicalKey,
+} from "./content-address.mjs";
 import { loadForeignIndexes } from "./metadata-index.mjs";
 import { frontmatterWikilinks, slugify } from "./web-wikilinks.mjs";
 import { homepageAddresses, isHomepage } from "./homepage.mjs";
@@ -195,9 +201,14 @@ export function buildLinkIndex(
         anchors.set(note, new Set((record.anchors ?? []).map((a) => a.slug)));
 
         if (typeof fm.shortcode === "string" && fm.shortcode) {
-            byKey.set(`${type}/${fm.shortcode}`.toLowerCase(), note);
-            // The canonical, fully qualified address alongside the short one,
-            // so a package-qualified link checks the same way a bare one does.
+            // Canonical addresses only. Every written target expands to one
+            // before lookup (#336), so there is nothing left for a short key to
+            // answer — and the short key was harmful: `type/shortcode` is
+            // system-blind, set with a plain `Map.set`, so two notes in one
+            // package sharing a `(type, shortcode)` across systems silently
+            // overwrote each other in that slot while both canonical keys sat
+            // correctly beside it.
+            //
             // Taken from the record, which is where the address rule is applied
             // once for the whole build.
             const canonical =
@@ -205,7 +216,6 @@ export function buildLinkIndex(
                 canonicalKey(pkg, systemOf(type, KNOWN_DOCUMENT_SUBTYPE_MAPS), type, fm.shortcode);
             byKey.set(canonical, note);
             if (hasDocEntry(type)) {
-                byKey.set(`doc${type}/${fm.shortcode}`.toLowerCase(), note);
                 // A documentation journal is `none`: no game system defines a
                 // JournalEntry, and one note has one of them however many
                 // system blocks it carries.
@@ -341,23 +351,19 @@ export function buildLinkIndex(
         return matchAddress([...byKey], q).map(([, v]) => v);
     }
 
-    function resolveAddress(target) {
+    function resolveAddress(target, keyPath) {
         const qualified = readQualifier(target, types, packages);
         if (!qualified || qualified.reason) return undefined;
-        // A target naming neither package nor system stays the system-blind
-        // short key, which is already the wildcard an author writing
-        // `[[skill-melee]]` means.
+        // Every omitted segment defaults from where the link is written (#336),
+        // so the target expands to exactly one canonical address and this is a
+        // plain lookup. There is no candidate set, and therefore no single-hit
+        // rule and no ambiguity to report.
         //
-        // Anything that *does* state one is matched by the segments it supplied
-        // rather than by an exact key (#59), and exactly one hit is required —
-        // two systems' documents legitimately share a
-        // `(package, type, shortcode)`, so a target that names no system may
-        // name two notes, and naming two is not resolving.
-        if (!qualified.package && !qualified.system) {
-            return byKey.get(`${qualified.type}/${qualified.shortcode}`.toLowerCase());
-        }
-        const hits = matchLocal(qualified);
-        return hits.length === 1 ? hits[0] : undefined;
+        // It replaced a system-blind short key, `type/shortcode`, populated by
+        // plain `Map.set` — so two notes in one package sharing a
+        // `(type, shortcode)` across systems silently overwrote each other, and
+        // a bare link resolved to whichever was indexed second.
+        return byKey.get(expandAddress(qualified, { package: pkg, system: blockSystem(keyPath) }));
     }
 
     /**
@@ -375,10 +381,20 @@ export function buildLinkIndex(
      * @param {string} target - The link target.
      * @returns {object[]} The foreign entries, each carrying its `package`.
      */
-    function foreignHits(target) {
+    function foreignHits(target, keyPath) {
         const q = readQualifier(target, types, packages);
         if (!q || q.reason) return [];
-        return matchAddress([...foreign.index], q).map(([, v]) => v);
+        // An omitted package means *this* package (#336), so a short form
+        // addresses nothing foreign and never reaches a dependency's index.
+        // Reaching another package is the fully qualified form's job, and
+        // saying so is the whole point: a link that resolved into `sohl` only
+        // because no local note claimed the address was resolving by accident,
+        // and would have retargeted silently the day one did.
+        if (!q.package) return [];
+        const hit = foreign.index.get(
+            expandAddress(q, { package: q.package, system: blockSystem(keyPath) }),
+        );
+        return hit ? [hit] : [];
     }
 
     /**

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

@@ -666,7 +666,10 @@ export function foreignItemCatalogDirs(config) {
         // (#272).
         const items = itemsDir(newestVersionDir(cached));
         for (const name of fs.readdirSync(items)) {
-            dirs.push(path.join(items, name));
+            // 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, 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,
         },