@heroiclands/package-build 19.0.0 → 20.2.0

package/e2e.mjs

@@ -40,6 +40,7 @@
  */
 
 import crypto from "node:crypto";
+import { readdirSync, statSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
@@ -557,6 +558,253 @@ function captureContainerLog(container) {
     return `${result.stdout ?? ""}${result.stderr ?? ""}`;
 }
 
+/**
+ * Programs a package runner is only a way of *naming*.
+ *
+ * `npx cypress run` does not fail when Cypress is gone. `npx` is a way of
+ * saying "find `cypress`", and what it does when it cannot find one is fetch
+ * some other copy from the registry — so the executable the harness checks has
+ * to be the tool, not the runner, or the only thing it ever verifies is the one
+ * program that is never missing.
+ *
+ * @type {readonly string[]}
+ */
+const DIRECT_RUNNERS = Object.freeze(["npx", "pnpx", "bunx"]);
+
+/**
+ * The same idea spelled as a subcommand: `pnpm dlx cypress`, `npm exec
+ * cypress`. The subcommand matters — `npm run e2e` names a *script*, not a
+ * program, and there is nothing there for the harness to resolve.
+ *
+ * @type {Readonly<Record<string, readonly string[]>>}
+ */
+const SUBCOMMAND_RUNNERS = Object.freeze({
+    npm: ["exec"],
+    pnpm: ["dlx", "exec"],
+    yarn: ["dlx"],
+    bun: ["x"],
+});
+
+/**
+ * Runner flags that name the package themselves instead of taking it from the
+ * first bare word. Meeting one means the harness cannot read this command, and
+ * a guess would put the wrong name in the diagnostic — which is worse than
+ * checking the runner alone.
+ *
+ * @type {readonly string[]}
+ */
+const OPAQUE_RUNNER_FLAGS = Object.freeze(["-p", "--package", "-c", "--call"]);
+
+/**
+ * A program's lookup name: its basename, minus a Windows executable extension,
+ * lower-cased. `C:\\…\\npx.cmd` and `npx` are the same question.
+ *
+ * @param {string} program - The program as the command line spells it.
+ * @returns {string} The name to compare against the runner tables.
+ */
+function executableName(program) {
+    return path
+        .basename(program)
+        .replace(/\.(cmd|exe|bat|ps1)$/i, "")
+        .toLowerCase();
+}
+
+/**
+ * Every executable that must exist for a suite command to run at all.
+ *
+ * One name for a plain command, two when a package runner is standing in for a
+ * tool. This is deliberately a *reading* of the command rather than a guess:
+ * anything it cannot read reduces to the program alone, because naming the
+ * wrong missing thing would send someone after a dependency they already have.
+ *
+ * @param {readonly string[]} command - The program and its arguments.
+ * @returns {string[]} The executables to resolve, in the order to report them.
+ */
+export function suiteExecutables(command) {
+    const [program, ...rest] = command;
+    if (!program) return [];
+    const name = executableName(program);
+
+    let args = rest;
+    const subcommands = SUBCOMMAND_RUNNERS[name];
+    if (subcommands) {
+        if (args.length === 0 || !subcommands.includes(args[0])) return [program];
+        args = args.slice(1);
+    } else if (!DIRECT_RUNNERS.includes(name)) return [program];
+
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--") return args[i + 1] ? [program, args[i + 1]] : [program];
+        if (OPAQUE_RUNNER_FLAGS.includes(arg)) return [program];
+        if (arg.startsWith("--package=") || arg.startsWith("--call=")) return [program];
+        if (arg.startsWith("-")) continue;
+        return [program, arg];
+    }
+    return [program];
+}
+
+/**
+ * @param {string} candidate - An absolute path.
+ * @returns {boolean} Whether it is there and is a file.
+ */
+function isExecutableFile(candidate) {
+    return statSync(candidate, { throwIfNoEntry: false })?.isFile() ?? false;
+}
+
+/**
+ * Find an executable the way the child process will: a path is a path, and a
+ * bare name is looked for in the repository's `node_modules/.bin` first, then
+ * along `PATH`.
+ *
+ * @param {string} name - The program, as the command line spells it.
+ * @param {object} [opts]
+ * @param {string} [opts.cwd] - The repository root, for `node_modules/.bin`.
+ * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read `PATH` from.
+ * @returns {string|null} Where it is, or `null` if it is nowhere.
+ */
+export function findExecutable(name, { cwd, env = process.env } = {}) {
+    if (name.includes("/") || name.includes(path.sep)) {
+        const candidate = path.resolve(cwd ?? process.cwd(), name);
+        return isExecutableFile(candidate) ? candidate : null;
+    }
+    const directories = cwd ? [path.join(cwd, "node_modules", ".bin")] : [];
+    directories.push(...(env.PATH ?? "").split(path.delimiter).filter(Boolean));
+    const extensions =
+        process.platform === "win32" ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";") : [""];
+    for (const directory of directories) {
+        for (const extension of extensions) {
+            const candidate = path.join(directory, `${name}${extension}`);
+            if (isExecutableFile(candidate)) return candidate;
+        }
+    }
+    return null;
+}
+
+/**
+ * Which of a suite command's executables are not there.
+ *
+ * Asked twice per run, and the second asking is the point: an install running
+ * alongside the suite can take the runner out from under it mid-flight, which
+ * is precisely the failure that reported itself as green (#153).
+ *
+ * @param {object} opts
+ * @param {readonly string[]} opts.command - The program and its arguments.
+ * @param {string} [opts.cwd] - The repository root.
+ * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read.
+ * @returns {string[]} The names that resolve to nothing.
+ */
+export function missingExecutables({ command, cwd, env = process.env }) {
+    return suiteExecutables(command).filter((name) => findExecutable(name, { cwd, env }) === null);
+}
+
+/**
+ * Names, quoted, for a diagnostic.
+ *
+ * @param {readonly string[]} names - What to list.
+ * @returns {string} A comma-separated list, back-quoted.
+ */
+function quotedList(names) {
+    return names.map((name) => `\`${name}\``).join(", ");
+}
+
+/**
+ * Filesystem timestamps are not all millisecond-precise, and a suite can write
+ * its first result in the same tick the harness spawned it. A second of slack
+ * costs nothing: a *stale* result is one from a previous run, minutes or days
+ * old, not one written a moment early.
+ */
+const RESULT_MTIME_SLACK_MS = 1000;
+
+/**
+ * Which declared result paths the suite actually wrote to during this run.
+ *
+ * Existence is not the test. A results directory left behind by the previous
+ * run exists, and reading that as evidence would make the check agree with
+ * exactly the thing it was built to catch. What counts is a file modified since
+ * the spawn.
+ *
+ * @param {object} opts
+ * @param {readonly string[]} opts.paths - Declared result paths, repo-relative.
+ * @param {number} opts.since - Milliseconds since the epoch, at spawn time.
+ * @param {string} [opts.cwd] - The repository root.
+ * @returns {string[]} The declared paths carrying something new.
+ */
+export function freshResults({ paths, since, cwd }) {
+    const floor = since - RESULT_MTIME_SLACK_MS;
+
+    /**
+     * @param {string} candidate - An absolute path.
+     * @returns {boolean} Whether it, or anything under it, is newer than the floor.
+     */
+    const touched = (candidate) => {
+        const stats = statSync(candidate, { throwIfNoEntry: false });
+        if (!stats) return false;
+        if (stats.isFile()) return stats.mtimeMs >= floor;
+        if (!stats.isDirectory()) return false;
+        return readdirSync(candidate, { withFileTypes: true }).some((entry) =>
+            touched(path.join(candidate, entry.name)),
+        );
+    };
+
+    return paths.filter((declared) => touched(path.resolve(cwd ?? process.cwd(), declared)));
+}
+
+/**
+ * What the harness reports for a finished suite.
+ *
+ * @typedef {object} SuiteVerdict
+ * @property {number} status        The exit status to hand back.
+ * @property {string|null} message  What to say about it, if anything.
+ */
+
+/**
+ * Decide what a finished suite is worth, given what it exited with and what it
+ * left behind.
+ *
+ * The point of the e2e suite is to be *evidence*: `compatibility.verified`
+ * moves on a green run, and a sweep exists to produce a citable result. So an
+ * exit status on its own cannot call a run green, because every way of stopping
+ * a runner before it starts — a corrupt install, a missing browser, a killed
+ * process, the concurrent `npm ci` that surfaced this — produces a run that
+ * executed nothing, and nothing is not a pass (#153).
+ *
+ * This can only ever make a verdict worse. A suite that failed keeps its own
+ * status; a suite that passed on no evidence loses the claim. Never the other
+ * way round — a harness that could *upgrade* a result would be a second way to
+ * report a green that did not happen.
+ *
+ * @param {object} opts
+ * @param {number} opts.status - What the suite process exited with.
+ * @param {readonly string[]} [opts.vanished] - Executables gone since it started.
+ * @param {readonly string[]} [opts.declared] - Result paths the repository declares.
+ * @param {readonly string[]} [opts.fresh] - Those of them it wrote to.
+ * @returns {SuiteVerdict} The status to report, and why.
+ */
+export function suiteVerdict({ status, vanished = [], declared = [], fresh = [] }) {
+    if (vanished.length > 0) {
+        return {
+            status: status || 1,
+            message:
+                `✗ ${quotedList(vanished)} disappeared while the suite was ` +
+                `running, so it cannot have finished. Something reinstalled ` +
+                `\`node_modules\` underneath it — \`npm ci\` removes the tree ` +
+                `before it rebuilds it. Reporting the run as failed: whatever ` +
+                `status it exited with, it ran nothing to completion.`,
+        };
+    }
+    if (declared.length > 0 && fresh.length === 0) {
+        return {
+            status: status || 1,
+            message:
+                `✗ The suite exited ${status} but wrote nothing to ` +
+                `${quotedList(declared)} while it ran, so there is no evidence ` +
+                `it executed anything. Reporting the run as failed: a run that ` +
+                `produced no results is not a pass.`,
+        };
+    }
+    return { status, message: null };
+}
+
 /**
  * Run the repository's suite.
  *
@@ -565,19 +813,51 @@ function captureContainerLog(container) {
  * runner launches as plain Node, rejects its own flags, and dies with a
  * `MODULE_NOT_FOUND` naming nothing relevant.
  *
+ * The suite is bracketed by checks rather than trusted on its exit status,
+ * because a run that never started used to report as green (#153):
+ *
+ * - **Before.** Every executable the command needs is resolved, and a missing
+ *   one is an error naming it — rather than a container stood up, a world
+ *   seeded, and a failure three minutes later that names nothing.
+ * - **After.** The same question again, because the reported failure was an
+ *   install pulling the runner out from under a run already in progress; and,
+ *   where the repository declares where its results land, whether anything was
+ *   written there while the suite ran.
+ *
  * @param {object} opts
- * @param {string[]} opts.command - The program and its arguments.
+ * @param {readonly string[]} opts.command - The program and its arguments.
  * @param {string[]} [opts.args] - Extra arguments, appended verbatim.
  * @param {string} opts.cwd - The repository root.
+ * @param {readonly string[]} [opts.results] - Declared result paths to check.
  * @param {NodeJS.ProcessEnv} [opts.env] - Environment for the child.
  * @param {(message: string) => void} [opts.log] - Progress reporting.
  * @returns {number} The suite's exit status.
+ * @throws {Error} When the command names an executable that is not installed.
  */
-export function runSuite({ command, args = [], cwd, env = process.env, log = () => {} }) {
+export function runSuite({
+    command,
+    args = [],
+    cwd,
+    results = [],
+    env = process.env,
+    log = () => {},
+}) {
+    const missing = missingExecutables({ command, cwd, env });
+    if (missing.length > 0) {
+        throw new Error(
+            `The end-to-end suite cannot start: ${quotedList(missing)} ` +
+                `${missing.length === 1 ? "is" : "are"} not installed — ` +
+                `nothing of that name is in \`node_modules/.bin\` or on ` +
+                `\`PATH\`. The declared command is \`${command.join(" ")}\`. ` +
+                `Install the repository's dependencies and run again.`,
+        );
+    }
+
     const [program, ...rest] = command;
     const childEnv = { ...env };
     delete childEnv.ELECTRON_RUN_AS_NODE;
     log(`▸ ${[...command, ...args].join(" ")}`);
+    const startedAt = Date.now();
     const result = spawnSync(/** @type {string} */ (program), [...rest, ...args], {
         stdio: "inherit",
         cwd,
@@ -585,7 +865,15 @@ export function runSuite({ command, args = [], cwd, env = process.env, log = ()
         shell: process.platform === "win32",
     });
     if (result.error) throw result.error;
-    return result.status ?? 1;
+
+    const verdict = suiteVerdict({
+        status: result.status ?? 1,
+        vanished: missingExecutables({ command, cwd, env }),
+        declared: results,
+        fresh: freshResults({ paths: results, since: startedAt, cwd }),
+    });
+    if (verdict.message) log(verdict.message);
+    return verdict.status;
 }
 
 /**
@@ -696,6 +984,11 @@ export async function e2eRun({
             command,
             args: suiteArgs,
             cwd: config.rootDir,
+            // Only a headless run makes a claim worth checking. `open` hands
+            // the runner to a person, who decides what to execute and when to
+            // close it; "it wrote no results" is a description of that session,
+            // not a fault in it.
+            results: mode === "run" ? config.e2eResults : [],
             env: runEnv,
             log,
         });
@@ -781,6 +1074,7 @@ export async function e2eFast({ config, argv = [], env = process.env, log = () =
         command,
         args: suiteArgs,
         cwd: config.rootDir,
+        results: config.e2eResults,
         env,
         log,
     });

package/engine/actor-compiler.mjs

@@ -63,6 +63,14 @@ import { contentPackage } from "./content-package.mjs";
 // inferred from the type itself (#79).
 import { mapsNoteType, noteTypesFor, referencedSubtype } from "./document-subtypes.mjs";
 import { locateFrontmatterKey } from "./retired-fields.mjs";
+// An `items:` entry's `system:` overlay is merged verbatim, so it reaches the
+// document by a path no field declaration sits on — including, until #330, the
+// fields the document is supposed to write for itself in play.
+import { itemFields } from "./item-registry.mjs";
+import { runtimeOnlyIn, runtimeOnlyMessage } from "./runtime-only-fields.mjs";
+// A `model:` is an address, read by the same grammar every wikilink is (#336),
+// so an author writes one form and meets one set of messages.
+import { readQualifier } from "./wikilinks.mjs";
 
 /**
  * Strip compendium-only fields from a predefined item before embedding it
@@ -134,6 +142,61 @@ export function itemAddress(subType, shortcode) {
     return `${subType}:${shortcode}`;
 }
 
+/**
+ * The key one predefined item is held under **for the package that publishes
+ * it** — the address a `model:` naming that package resolves through (#334).
+ *
+ * The unqualified {@link itemAddress} stays beside it, and the two answer
+ * different questions. A `model` that names no package means *this* one and
+ * takes the unqualified key, where a local definition still shadows a
+ * dependency's. A `model` that names a package takes this one, which nothing
+ * can shadow: that is the whole point of writing the package down.
+ *
+ * Not the canonical wikilink address, because this map is keyed in the
+ * **document's** vocabulary — a Foundry Item subtype — while a canonical address
+ * carries the *note* type. The two differ wherever a system maps a type to a
+ * differently-named subtype, and translating here would put the translation in
+ * two places.
+ *
+ * @param {string} pkg - The content package that publishes the item.
+ * @param {string} subType - The Foundry Item subtype.
+ * @param {string} shortcode - The item's `system.shortcode`.
+ * @returns {string} The address, `package:subType:shortcode`.
+ */
+export function packagedItemAddress(pkg, subType, shortcode) {
+    return `${pkg}:${subType}:${shortcode}`;
+}
+
+/**
+ * The key one predefined item is held under **in the catalogue**, with the
+ * shortcode folded to lower case.
+ *
+ * A shortcode is case-sensitive and routinely mixed — `Clb`, `LtShoe`,
+ * `HsTunic` — while an **address** is not: `readQualifier` normalises what it
+ * reads, and every canonical address is lowercase. So the moment a `model:` is
+ * read as an address (#334), `weapongear-clb` has to find the document whose
+ * `system.shortcode` is `Clb`, and an exact match cannot (#346).
+ *
+ * Folding is safe because the fold is already the address: no two items in any
+ * published tree differ only by the case of their shortcode, and #340 will make
+ * that impossible rather than merely true.
+ *
+ * **This is not {@link itemAddress}, and must not become it.** That one seeds
+ * {@link embeddedItemId}, so folding there would change the `_id` of every
+ * embedded item whose identity carries a capital — a silent re-identification of
+ * documents nothing about which had changed. The catalogue is a lookup table;
+ * an id is a promise.
+ *
+ * @param {string} subType - The Foundry Item subtype.
+ * @param {string} shortcode - The item's `system.shortcode`, in any case.
+ * @param {string} [pkg] - The publishing package, for the qualified form.
+ * @returns {string} The catalogue key.
+ */
+export function catalogueKey(subType, shortcode, pkg) {
+    const folded = String(shortcode).toLowerCase();
+    return pkg ? packagedItemAddress(pkg, subType, folded) : itemAddress(subType, folded);
+}
+
 /**
  * What identifies one embedded item on its actor.
  *
@@ -243,7 +306,7 @@ export function loadItemsMap(itemsSourceDirs, foreignSourceDirs = []) {
             }
             const shortcode = doc?.system?.shortcode;
             if (!doc?.type || !shortcode) continue;
-            const address = itemAddress(doc.type, shortcode);
+            const address = catalogueKey(doc.type, shortcode);
             const owner = source.get(address);
             if (owner && owner !== itemsSourceDir) {
                 throw new Error(
@@ -257,9 +320,17 @@ export function loadItemsMap(itemsSourceDirs, foreignSourceDirs = []) {
             // eslint-disable-next-line no-unused-vars
             const { _key, ...rest } = doc;
             map.set(address, rest);
+            // And under this package's own name, so a `model:` that names this
+            // package explicitly resolves to the same item (#334).
+            map.set(catalogueKey(doc.type, shortcode, contentPackage()), rest);
         }
     }
-    for (const foreignDir of foreignSourceDirs) {
+    for (const foreignEntry of foreignSourceDirs) {
+        // Each dependency's directory arrives with the package that published
+        // it (#334), so a foreign template gets its own canonical address
+        // rather than sharing the local address space.
+        const foreignDir = typeof foreignEntry === "string" ? foreignEntry : foreignEntry.dir;
+        const foreignPackage = typeof foreignEntry === "string" ? null : foreignEntry.package;
         for (const name of fs.readdirSync(foreignDir)) {
             if (!name.endsWith(".json")) continue;
             if (name.startsWith("folder_")) continue;
@@ -277,14 +348,19 @@ export function loadItemsMap(itemsSourceDirs, foreignSourceDirs = []) {
             }
             const shortcode = doc?.system?.shortcode;
             if (!doc?.type || !shortcode) continue;
-            const address = itemAddress(doc.type, shortcode);
+            const address = catalogueKey(doc.type, shortcode);
+            // eslint-disable-next-line no-unused-vars
+            const { _key, ...rest } = doc;
+            // Its own package-qualified address, which a `model:` naming that
+            // package resolves through and nothing local can shadow (#334).
+            if (foreignPackage) {
+                map.set(catalogueKey(doc.type, shortcode, foreignPackage), rest);
+            }
             if (map.has(address)) {
                 // Deliberate: this repository defines it, so its version wins.
                 if (source.has(address)) shadowed.push(address);
                 continue;
             }
-            // eslint-disable-next-line no-unused-vars
-            const { _key, ...rest } = doc;
             map.set(address, rest);
         }
     }
@@ -310,6 +386,21 @@ export class SystemActorCompiler extends BasePackCompiler {
     static id = "actors";
     static label = "actor";
 
+    /**
+     * **Both**, and they are two independent pictures: `img` is the actor's
+     * token art — written onto `document.img` and the prototype token's texture
+     * — and `portrait` is the sheet portrait, a declared field each system
+     * lands under its own name (`system.portrait` for SoHL,
+     * `system.bioImage` for HM3).
+     *
+     * Declared on the shared class because both subclasses emit both. A system
+     * whose actor genuinely carried only one would override it here rather than
+     * leave the claim standing.
+     *
+     * @type {readonly string[]}
+     */
+    static emitsArt = Object.freeze(["img", "portrait"]);
+
     /**
      * Which `(actor, subType:identity)` each resolved entry claimed, and the
      * entry that claimed it first.
@@ -356,6 +447,20 @@ export class SystemActorCompiler extends BasePackCompiler {
     itemsSourceDirs;
     foreignSourceDirs;
 
+    /**
+     * Every package a `model:` may name besides this one — the dependencies
+     * whose item catalogues were supplied (#334).
+     *
+     * @returns {Set<string>} The dependency package ids.
+     */
+    get foreignPackages() {
+        return new Set(
+            (this.foreignSourceDirs ?? [])
+                .map((entry) => (typeof entry === "string" ? null : entry?.package))
+                .filter(Boolean),
+        );
+    }
+
     constructor({ itemsSourceDirs = [], foreignSourceDirs = [], ...options }) {
         super(options);
         // Where the items passes wrote their JSON. Stated by the caller rather
@@ -498,7 +603,66 @@ export class SystemActorCompiler extends BasePackCompiler {
      * @returns {object|null} The embedded item, or null when it resolved to
      *   nothing — always with a finding emitted.
      */
-    resolveEmbedded(itemsMap, actorId, type, shortcode, overlay, indexKey, ctx, { fmKey } = {}) {
+    /**
+     * Read an entry's `model:` — the address of the item it is a copy of.
+     *
+     * The address grammar is the wikilink one (#336), so a `model` is written at
+     * whatever length says what it means: `skill-wpnc` within this package,
+     * `sohl-sohl-skill-wpnc` to reach another. The system segment defaults from
+     * the block the entry sits in — `<system>.items` — which is what makes the
+     * short form name an *Item* here while the same string in body prose names
+     * a page.
+     *
+     * It replaced a top-level `shortcode:` that meant something different from
+     * the `system.shortcode` beside it and could not say which package a
+     * template came from (#334).
+     *
+     * @param {unknown} model - The authored value.
+     * @param {number} index - The entry's position, for the message.
+     * @param {string} ctx - Diagnostic context (the actor's label).
+     * @returns {{type: string, shortcode: string, package: string|null}|null}
+     *   The parsed address, or `null` after reporting why it is not one.
+     */
+    readModel(model, index, ctx) {
+        const key = `${this.documentSubtypes.block}.items`;
+        const where = () =>
+            locateFrontmatterKey(this.currentNote?.absPath, "items", String(model ?? ""));
+        if (typeof model !== "string" || !model.trim()) {
+            this.noteError(`${ctx}: ${key}[${index}] \`model\` must be an address`, where());
+            this.errorCount++;
+            return null;
+        }
+        // The types this system maps, which are the ones a `model` may name, and
+        // every package one may reach: this repository's own plus each
+        // dependency whose item catalogue was loaded.
+        const types = new Set(Object.keys(this.documentSubtypes.types));
+        const packages = new Set([contentPackage(), ...this.foreignPackages]);
+        const read = readQualifier(model.trim(), types, packages);
+        if (!read || read.reason) {
+            const why =
+                read?.reason === "not-lowercase" ?
+                    "capitalises a package, system or type segment — those three " +
+                    "are lowercase, and only the shortcode keeps its case"
+                : read?.reason === "unknown-type" ? "names no known content type"
+                : "is not an address — write `type-shortcode`, or " +
+                    "`package-system-type-shortcode` for another package's item";
+            this.noteError(`${ctx}: ${key}[${index}] \`model: ${model}\` ${why}`, where());
+            this.errorCount++;
+            return null;
+        }
+        return { type: read.type, shortcode: read.shortcode, package: read.package ?? null };
+    }
+
+    resolveEmbedded(
+        itemsMap,
+        actorId,
+        type,
+        shortcode,
+        overlay,
+        indexKey,
+        ctx,
+        { fmKey, modelPackage = null } = {},
+    ) {
         // Where a finding about this reference points. The value locates the
         // exact entry in a list; the key is the fallback when it cannot be
         // found, which still beats naming the note alone.
@@ -511,7 +675,33 @@ export class SystemActorCompiler extends BasePackCompiler {
             this.errorCount++;
             return null;
         }
-        const address = itemAddress(/** @type {string} */ (subType), shortcode ?? "");
+        // A `model:` may name the package its template comes from (#334). Where
+        // it does, the packaged address is used and nothing local can shadow
+        // it; where it does not, the unqualified one is, and a local definition
+        // still wins over a dependency's as it always has.
+        const address = catalogueKey(
+            /** @type {string} */ (subType),
+            shortcode ?? "",
+            modelPackage ?? undefined,
+        );
+
+        // The entry's `system:` overlay is merged verbatim, so it reaches the
+        // document without passing a single field declaration — which left it
+        // the one position a runtime-only field stayed authorable at once #330
+        // closed the item note's own. Asked of the **overlay** rather than of
+        // the merged result: the template it merges onto is a compiled
+        // document, which by then carries none, and a finding has to name what
+        // this note wrote.
+        const [runtimeOnly] = runtimeOnlyIn(overlay?.system, itemFields(type, this.system));
+        if (runtimeOnly) {
+            this.noteError(
+                `${ctx}: ${indexKey}: ` +
+                    `${runtimeOnlyMessage(`${indexKey}.system.${runtimeOnly.to}`, runtimeOnly)}.`,
+                where(),
+            );
+            this.errorCount++;
+            return null;
+        }
 
         let base = null;
         if (shortcode) {

package/engine/address-charset.mjs

@@ -39,15 +39,33 @@
  */
 
 /**
- * The shape every address segment must match: ASCII letters and digits only.
+ * The shape every address segment must match: **lowercase** ASCII letters and
+ * digits only.
  *
- * Case is deliberately **not** constrained. Hundreds of authored shortcodes are
- * mixed-case and collide with nothing, and case has no bearing on the
- * separator, which is the whole of what this pattern is protecting.
+ * Case *was* deliberately unconstrained, on the reasoning that case has no
+ * bearing on the separator — which is true, and beside the point (#340).
+ *
+ * **Two names that differ only in case are two names nobody can tell apart.** A
+ * shortcode is how a person names a thing when writing a reference —
+ * `model: weapongear-dgr`, `[[skill-melee|…]]` — and `Dgr` beside `dgr` is a
+ * distinction you cannot say out loud and can only see by looking twice.
+ *
+ * The toolchain had already half-decided it: {@link canonicalKey} lowercases the
+ * address it builds, so a note declaring `Clb` published
+ * `sohl-sohl-weapongear-clb` and its `_id` derived from that. The authored name
+ * and its address disagreed, and everything downstream keys on the address —
+ * which left two notes differing only in case sharing one address, one `_id` and
+ * one URL, with nothing to report it. It also forced two exceptions elsewhere:
+ * #336 had to exempt the shortcode from the lowercase rule it pinned on every
+ * other segment, and #346 had to fold the shortcode's case in the item catalogue
+ * because an address is lowercased when read.
+ *
+ * One case, one spelling, no exceptions. Every tree already complies but two,
+ * and nothing in any of them collides when folded.
  *
  * @type {RegExp}
  */
-export const ADDRESS_SEGMENT_PATTERN = /^[A-Za-z0-9]+$/;
+export const ADDRESS_SEGMENT_PATTERN = /^[a-z0-9]+$/;
 
 /**
  * Whether a value is a well-formed address segment.