@heroiclands/package-build 23.1.1 → 23.2.0

package/e2e.mjs

@@ -46,13 +46,16 @@ import path from "node:path";
 import process from "node:process";
 import { spawnSync } from "node:child_process";
 
-import { deployStage } from "./deploy.mjs";
+import { deployStage, isRemoteTarget, packageSubpath } from "./deploy.mjs";
+import { emitDiagnostic } from "./engine/diagnostics.mjs";
 import {
     containerAction,
     containerExists,
+    containerTreeRemover,
     dataEnvVar,
     resolveContainer,
     resolveDataRoot,
+    runDataRootScript,
     runDocker,
     runningFoundryContainers,
 } from "./container.mjs";
@@ -365,24 +368,41 @@ export function parseFastArgs(argv, build) {
  *
  * Writes `world.json` and compiles each LevelDB collection from JSON, so the
  * result is a genuine world Foundry launches without migration or setup. The
- * world directory is wiped and rewritten each time, which is what makes a run
- * repeatable.
+ * world directory is replaced each time, which is what makes a run repeatable.
+ *
+ * The world is built in a staging directory beside the worlds, then moved into
+ * place and handed to the Foundry container's user by a throwaway container
+ * mounting the same data root. Replacing the old world happens there too. Both
+ * halves matter: a database the host user wrote cannot be locked by the
+ * container's user, and a directory the container's user wrote (such as the
+ * `lost/` folder Foundry's repair makes) cannot be unlinked by the host user.
  *
  * @param {object} opts
  * @param {object} opts.config - The resolved package-build configuration.
  * @param {object} opts.packageJson - The repository's `package.json`.
  * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read.
  * @param {(message: string) => void} [opts.log] - Progress reporting.
+ * @param {(opts: object) => string} [opts.runScript] - Runs a shell script in a
+ *   throwaway container on the data root; replaceable for tests.
  * @returns {Promise<{worldDir: string, world: E2EWorld}>} Where it landed.
  */
-export async function seedTestWorld({ config, packageJson, env = process.env, log = () => {} }) {
+export async function seedTestWorld({
+    config,
+    packageJson,
+    env = process.env,
+    log = () => {},
+    runScript = runDataRootScript,
+}) {
     const stage = config.e2eStage;
     const dataRoot = requireIsolatedDataRoot(stage, env);
     const world = resolveE2EWorld(config, env);
 
     const worldDir = path.join(dataRoot, "Data", "worlds", world.worldId);
-    await fs.rm(worldDir, { recursive: true, force: true });
-    await fs.mkdir(worldDir, { recursive: true });
+    // Beside `Data/`, not inside it, so Foundry never sees a half-built world.
+    const stagingName = `.seed-${world.worldId}`;
+    const stagingDir = path.join(dataRoot, stagingName);
+    await fs.rm(stagingDir, { recursive: true, force: true });
+    await fs.mkdir(stagingDir, { recursive: true });
 
     const coreVersion = String(config.compatibilityMinimum ?? "").split(".")[0];
     if (!coreVersion) {
@@ -394,7 +414,7 @@ export async function seedTestWorld({ config, packageJson, env = process.env, lo
     }
 
     await fs.writeFile(
-        path.join(worldDir, "world.json"),
+        path.join(stagingDir, "world.json"),
         JSON.stringify(
             worldManifest({
                 ...world,
@@ -427,7 +447,7 @@ export async function seedTestWorld({ config, packageJson, env = process.env, lo
     }
 
     const { compilePack } = await import("@foundryvtt/foundryvtt-cli");
-    const sourceRoot = path.join(worldDir, ".seed-src");
+    const sourceRoot = path.join(stagingDir, ".seed-src");
     for (const [collection, documents] of Object.entries(collections)) {
         const sourceDir = path.join(sourceRoot, collection);
         await fs.mkdir(sourceDir, { recursive: true });
@@ -453,18 +473,126 @@ export async function seedTestWorld({ config, packageJson, env = process.env, lo
     for (const collection of await fs.readdir(sourceRoot)) {
         await compilePack(
             path.join(sourceRoot, collection),
-            path.join(worldDir, "data", collection),
+            path.join(stagingDir, "data", collection),
             { log: false },
         );
     }
     await fs.rm(sourceRoot, { recursive: true, force: true });
 
+    // Hand the world to the user Foundry runs as.
+    const container = resolveContainer({ stage, config, env });
+    const owner = containerOwner({ container, dataRoot, runScript });
+    runScript({
+        image: container.image,
+        dataRoot,
+        user: "0:0",
+        script: [
+            "set -e",
+            'rm -rf "/data/Data/worlds/$1"',
+            "mkdir -p /data/Data/worlds",
+            'mv "/data/$2" "/data/Data/worlds/$1"',
+            'chown -R "$3" "/data/Data/worlds/$1"',
+        ].join("\n"),
+        args: [world.worldId, stagingName, owner],
+    });
+
     log(`Seeded world '${world.worldId}' at ${worldDir}`);
     log(`  GM user:  ${world.gmName} (id ${world.gmId})`);
     log(`  password: ${world.gmPassword}`);
     return { worldDir, world };
 }
 
+/**
+ * The `uid:gid` the Foundry container runs as, asked of the container's own
+ * user so it is right whatever `--user` or the image says.
+ *
+ * @param {object} opts
+ * @param {import("./container.mjs").ResolvedContainer} opts.container - The stage's container.
+ * @param {string} opts.dataRoot - The stage's local data root.
+ * @param {(opts: object) => string} opts.runScript - Throwaway-container runner.
+ * @returns {string} For example `1000:1000`.
+ * @throws {Error} When the answer is not a numeric pair.
+ */
+function containerOwner({ container, dataRoot, runScript }) {
+    const owner = runScript({
+        image: container.image,
+        dataRoot,
+        user: container.user,
+        script: 'echo "$(id -u):$(id -g)"',
+    }).trim();
+    if (!/^\d+:\d+$/.test(owner)) {
+        throw new Error(`Could not determine the container's user: '${owner}'.`);
+    }
+    return owner;
+}
+
+/**
+ * Deploy the staged package to the end-to-end stage so the container's user
+ * can run it.
+ *
+ * The package's databases (compendium packs) are written by the host user, and
+ * Foundry cannot lock them unless it owns them; a pack Foundry has repaired
+ * holds directories the host user cannot unlink. So the previous install is
+ * removed, and the new one handed over, by a throwaway container on the same
+ * data root. A remote destination is deployed as {@link deployStage} does.
+ *
+ * @param {object} opts
+ * @param {object} opts.config - The resolved package-build configuration.
+ * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read.
+ * @param {(message: string) => void} [opts.log] - Progress reporting.
+ * @param {(opts: object) => string} [opts.runScript] - Throwaway-container runner.
+ * @returns {Promise<void>}
+ */
+export async function deployForContainer({
+    config,
+    env = process.env,
+    log = () => {},
+    runScript = runDataRootScript,
+}) {
+    const stage = config.e2eStage;
+    const target = env[dataEnvVar(stage)]?.trim() ?? "";
+    const local = target !== "" && !isRemoteTarget(target);
+    const relative = packageSubpath(config.packageKind, config.packageId).join("/");
+    const container = resolveContainer({ stage, config, env });
+
+    if (local) {
+        runScript({
+            image: container.image,
+            dataRoot: target,
+            user: "0:0",
+            script: 'rm -rf "/data/$1"',
+            args: [relative],
+        });
+    }
+    const { leftovers } = await deployStage({
+        stage,
+        source: path.join(config.rootDir, config.stageDir),
+        packageKind: config.packageKind,
+        packageId: config.packageId,
+        env,
+        prefix: config.envPrefix,
+        log,
+        removeTree: containerTreeRemover({ container, runScript }),
+    });
+    for (const leftover of leftovers) {
+        emitDiagnostic({
+            file: leftover.path,
+            severity: "warning",
+            message: `the new package is installed, but this previous tree could not be removed (${leftover.reason})`,
+        });
+    }
+    if (local) {
+        const owner = containerOwner({ container, dataRoot: target, runScript });
+        runScript({
+            image: container.image,
+            dataRoot: target,
+            user: "0:0",
+            script: 'chown -R "$2" "/data/$1"',
+            args: [relative, owner],
+        });
+    }
+}
+
 /**
  * The end-to-end stage's data root, refused when it is another stage's.
  *
@@ -543,7 +671,7 @@ export async function waitForWorld({ url, container, stage, timeoutMs = 180_000,
     }
     throw new Error(
         `Timed out after ${Math.round(timeoutMs / 1000)}s waiting for the ` +
-            `world to activate. Check \`package-build container logs\`.`,
+            `world to activate. Check \`package-build container ${stage} logs\`.`,
     );
 }
 
@@ -944,15 +1072,7 @@ export async function e2eRun({
     }
 
     log(`▸ deploy ${stage}`);
-    await deployStage({
-        stage,
-        source: path.join(config.rootDir, config.stageDir),
-        packageKind: config.packageKind,
-        packageId: config.packageId,
-        env,
-        prefix: config.envPrefix,
-        log,
-    });
+    await deployForContainer({ config, env, log });
 
     log("▸ seed");
     const { world } = await seedTestWorld({ config, packageJson, env, log });
@@ -1044,15 +1164,7 @@ export async function e2eFast({ config, argv = [], env = process.env, log = () =
     const exists = containerExists(container.name);
 
     log(`▸ deploy ${stage}`);
-    await deployStage({
-        stage,
-        source: path.join(config.rootDir, config.stageDir),
-        packageKind: config.packageKind,
-        packageId: config.packageId,
-        env,
-        prefix: config.envPrefix,
-        log,
-    });
+    await deployForContainer({ config, env, log });
 
     const action = !exists || recreate ? "recreate" : "restart";
     log(`▸ container ${action}`);

package/engine/actor-compiler.mjs

@@ -52,7 +52,7 @@ import log from "loglevel";
 
 import { isAddressTuple, parseAddress, renderAddress } from "./address.mjs";
 import { makeId } from "./helpers.mjs";
-import { emitDiagnostic } from "./diagnostics.mjs";
+import { emitDiagnostic, locateFrontmatterKey } from "./diagnostics.mjs";
 // The `{#appearance}` / `{#dossier}` convention is the note format's, so the
 // extraction is shared; which field a section lands in stays the system's.
 export { extractAnchorSection, renderSection } from "./anchored-sections.mjs";
@@ -64,13 +64,12 @@ import { contentPackage } from "./content-package.mjs";
 // types are actors at all. Looked up in the system's declared map, never
 // inferred from the type itself.
 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 the
 // fields the document is supposed to write for itself in play. `itemArt` is
 // the same table the Item pass defaults from, so an entry that copies no
 // template and names no art of its own carries what a note of its type would.
-import { itemArt, itemFields } from "./item-registry.mjs";
+import { itemArt, itemFields, itemTypes } 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,
 // so an author writes one form and meets one set of messages.
@@ -326,7 +325,7 @@ export function loadItemsMap(itemsSourceDirs, foreignSourceDirs = [], system = n
             // so a whole-package build cannot reach this. What can is a run
             // restricted to this one pack, or a caller constructing the
             // compiler itself — neither of which reordering a pack list fixes,
-            // so the message no longer suggests it.
+            // so the message does not suggest it.
             throw new Error(
                 `Items source directory ${itemsSourceDir} does not exist — ` +
                     `an actor resolves its embedded items against the Item ` +
@@ -467,8 +466,7 @@ export class SystemActorCompiler extends BasePackCompiler {
         const address = beingDefaultArt(fm);
         const byTag = address ? this.artPathOf(address, "icon", "icon") : null;
         const base = byTag ?? fallback;
-        // Nullish, not `||`: a note that names no art takes the default, one
-        // that writes `""` ships blank on purpose.
+        // A note that names no art takes the default.
         const img = this.artPath(fm, "icon") ?? base;
         return { img, token: this.artPath(fm, "tokenIcon") ?? img };
     }
@@ -574,26 +572,20 @@ export class SystemActorCompiler extends BasePackCompiler {
         // configuration, and a consumer may put them anywhere. Every
         // Item pack, because a repository may ship more than one.
         //
-        // **Optional, and empty is a legitimate package.** This used to
-        // throw unless at least one Item pack was declared, which asked a
-        // package to declare the very thing it may exist not to have. An Item
-        // pack is system-bound by construction — Foundry requires `system` on
-        // Item packs — so a deliberately system-agnostic module could satisfy
-        // the guard only by naming a system. `harn-ensemble` is the case:
-        // 2,512 beings whose embedded items address the `sohl` and `hm3`
-        // catalogues, and five affiliation notes of its own.
+        // **Optional, and empty is a legitimate package.** An Item pack is
+        // system-bound by construction — Foundry requires `system` on Item
+        // packs — so a deliberately system-agnostic module could satisfy a
+        // requirement to declare one only by naming a system. `harn-ensemble`
+        // is the case: its beings' embedded items address the `sohl` and `hm3`
+        // catalogues, and it has a few affiliation notes of its own.
         //
-        // The guard also did not test what it claimed. It counted *declared
-        // directories*, not resolvable items, so an empty Item pack satisfied
-        // it while a being naming a missing item still failed later. The
-        // condition actually cared about is checked where it can be reported
-        // precisely: {@link SystemActorCompiler#resolveEmbedded} already errors
-        // per unresolved `(type, shortcode)`, naming the actor. A package whose
+        // The condition that matters is checked where it can be reported
+        // precisely: {@link SystemActorCompiler#resolveEmbedded} errors per
+        // unresolved `(type, shortcode)`, naming the actor. A package whose
         // actors embed nothing, or whose every address resolves against a
-        // dependency catalogue through `foreignSourceDirs`, now compiles with
-        // no Item pack at all — and one that is genuinely missing an item
-        // still fails, saying which item and which actor rather than which
-        // pack is absent.
+        // dependency catalogue through `foreignSourceDirs`, compiles with no
+        // Item pack at all — and one that is genuinely missing an item fails,
+        // saying which item and which actor rather than which pack is absent.
         Object.defineProperty(this, "itemsSourceDirs", {
             value: Object.freeze([...itemsSourceDirs]),
             writable: false,
@@ -679,7 +671,7 @@ export class SystemActorCompiler extends BasePackCompiler {
      *   subtype, or why the reference names none.
      */
     embeddedSubtype(type) {
-        return referencedSubtype(this.documentSubtypes, type, "Item");
+        return referencedSubtype(this.documentSubtypes, type, "Item", { declared: itemTypes() });
     }
 
     /**
@@ -742,13 +734,13 @@ export class SystemActorCompiler extends BasePackCompiler {
         const read = parseAddress(
             model,
             { types, packages, package: contentPackage(), system: this.system },
-            { declared: true, legacyShortcodeCase: true },
+            { declared: true },
         );
         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 === "shortcode-not-lowercase" ?
+                    `spells its shortcode \`${read.shortcode}\` with a capital — ` +
+                    "a shortcode is lowercase"
                 : 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";
@@ -892,8 +884,7 @@ export class SystemActorCompiler extends BasePackCompiler {
         // The two art rules an item note compiles under, applied to an entry
         // that is one in every respect but where it is written: the address it
         // names wins, the template it copies answers next, and the type's own
-        // default answers last. Nullish coalescing throughout, so `icon: ""`
-        // ships blank on purpose rather than collecting a default.
+        // default answers last.
         merged.img =
             this.artPath(overlay ?? {}, "icon") ??
             merged.img ??

package/engine/address-charset.mjs

@@ -42,26 +42,13 @@
  * The shape every address segment must match: **lowercase** ASCII letters and
  * digits only.
  *
- * Case *was* deliberately unconstrained, on the reasoning that case has no
- * bearing on the separator — which is true, and beside the point.
- *
  * **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 forces two exceptions elsewhere:
- * the shortcode has to be exempted from the lowercase rule pinned on every
- * other segment, and its case has to be folded 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.
+ * distinction you cannot say out loud and can only see by looking twice. So the
+ * shortcode is held to the same rule as every other segment: a note declaring
+ * `shortcode: Dgr` is refused, and so is a declared Address spelling one with a
+ * capital.
  *
  * @type {RegExp}
  */

package/engine/address-fields.mjs

@@ -307,7 +307,7 @@ function isMapping(value) {
  * `data.seat` — and the note writes `seat:` one level inside it. The finding
  * names that key for two reasons at once: it is the word on the line the
  * diagnostic opens, and it is what {@link
- * module:engine/retired-fields.locateFrontmatterKey} matches when the authored
+ * module:engine/diagnostics.locateFrontmatterKey} matches when the authored
  * value cannot be found in the fence, which a dotted path never would.
  *
  * @param {object} field - The declaration.

package/engine/address-render.mjs

@@ -1,4 +1,15 @@
-/* SPDX-License-Identifier: GPL-3.0-or-later */
+/*
+ * 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
+ */
 
 import { assertSystemSegment } from "./systems.mjs";
 

package/engine/address-values.mjs

@@ -2,6 +2,12 @@
  * 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
  */
 

package/engine/address.mjs

@@ -138,7 +138,7 @@ import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
 // `ids.mjs` is a leaf with no local imports, and `pack-config.mjs` reaches only
 // the configuration loader and the diagnostics writer — neither reads an
 // address, so the grammar sits below everything that consumes it.
-import { currentType, ITEM_PACK, JOURNAL_TYPES, packForType } from "./ids.mjs";
+import { ITEM_PACK, JOURNAL_TYPES, packForType } from "./ids.mjs";
 import { HOMEPAGE_TYPE } from "./homepage.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 
@@ -167,7 +167,7 @@ export const CANONICAL_KEY_SEGMENTS = 4;
 /** The accepted `doc<type>` input prefix for readable note links. */
 export const ITEM_DOC_PREFIX = "doc";
 
-/** Package, system and type are one spelling each, so they fold to lowercase. */
+/** Package, system and type are read lowercased; a capital in one is refused as `not-lowercase`. */
 const norm = (s) => String(s).toLowerCase().trim();
 
 /**
@@ -194,11 +194,16 @@ const norm = (s) => String(s).toLowerCase().trim();
  * - `no-content-index` — the package named publishes no content index, so there
  *   is nothing to resolve the rest of the target against.
  * - `not-lowercase` — a package, system or type segment carries a capital.
+ * - `shortcode-not-lowercase` — the Address spells its shortcode with a
+ *   capital and is otherwise well formed. `shortcode` carries the segment as
+ *   written, and `lowercase` the reading of the lowercase spelling: complete
+ *   for a declared Address, and as partial as the written value otherwise.
  * - `invalid-segment` — a declared Address contains a malformed segment.
  * - `no-package` — a declared Address cannot supply its package.
  * - `invalid-system` — a declared Address cannot supply a registered system.
  *
- * @typedef {{reason: string, package?: string}} AddressProblem
+ * @typedef {{reason: string, package?: string, shortcode?: string,
+ *   lowercase?: AddressTuple}} AddressProblem
  */
 
 /**
@@ -220,12 +225,9 @@ export function docEntryTypes() {
  *   `macro`; false for `doc`.
  */
 export function hasDocEntry(type) {
-    // Through {@link currentType}, because the set is derived from the item
-    // registry's keys and those are the *current* spelling of a note type. A
-    // note still on a renamed one carries its documentation journal exactly as
-    // before — this is the one lookup between an item compiling and its prose
-    // silently compiling into nothing.
-    return docEntryTypes().has(String(currentType(type)));
+    // The set is derived from the item registry's keys: the one lookup between
+    // an item compiling and its prose silently compiling into nothing.
+    return docEntryTypes().has(String(type));
 }
 
 /** The segment of a note's own document. */
@@ -294,32 +296,34 @@ export function resolveItemDocType(qualifier, types) {
  *   label already removed.
  * @param {AddressDefaults} [defaults] - The position's defaults and the tree's
  *   vocabularies.
- * @param {{declared?: boolean, legacyShortcodeCase?: boolean}} [options] - A declared Address validates every
- *   segment and requires complete defaults. Package membership is a separate
- *   resolution question in this mode; prose recognition keeps its vocabulary checks.
- *   `legacyShortcodeCase` accepts case-insensitive model Shortcodes while the
- *   completed tuple contains their canonical lowercase identity.
+ * @param {{declared?: boolean}} [options] - A declared Address is validated as
+ *   written: every segment, the shortcode included, is lowercase, and the
+ *   defaults must be complete. Package membership is a separate resolution
+ *   question in this mode; prose recognition keeps its vocabulary checks.
  * @returns {AddressTuple|AddressProblem} The complete Address, or why there is
  *   none.
  */
-export function parseAddress(
-    written,
-    defaults = {},
-    { declared = false, legacyShortcodeCase = false } = {},
-) {
+export function parseAddress(written, defaults = {}, { declared = false } = {}) {
     if (isAddressTuple(written)) return written;
     if (declared) {
         if (typeof written !== "string") return { reason: "not-an-address" };
-        const segments =
-            written.includes("/") ? written.split("/") : written.split(ADDRESS_SEPARATOR);
-        if (
-            !segments.every((segment, index) =>
-                isAddressSegment(
-                    legacyShortcodeCase && index === segments.length - 1 ? norm(segment) : segment,
-                ),
-            )
-        )
-            return { reason: "invalid-segment" };
+        const separator = written.includes("/") ? "/" : ADDRESS_SEPARATOR;
+        const segments = written.split(separator);
+        const shortcode = segments.at(-1);
+        if (!segments.slice(0, -1).every(isAddressSegment)) return { reason: "invalid-segment" };
+        if (!isAddressSegment(shortcode)) {
+            if (!/[A-Z]/.test(shortcode) || !isAddressSegment(shortcode.toLowerCase()))
+                return { reason: "invalid-segment" };
+            const lowercase = parseAddress(
+                [...segments.slice(0, -1), shortcode.toLowerCase()].join(separator),
+                defaults,
+                { declared },
+            );
+            // A value that is no Address even in lowercase is refused for that,
+            // the more basic fault, rather than for its case.
+            if (!isAddressTuple(lowercase)) return lowercase;
+            return { reason: "shortcode-not-lowercase", shortcode, lowercase };
+        }
     }
     const read = readWritten(written, defaults, declared);
     if (read.reason) return read;
@@ -565,15 +569,24 @@ function readWritten(written, vocabulary, declared = false) {
     const target = typeof written === "string" ? written : String(written ?? "");
     if (!target) return { reason: "not-an-address" };
     const read = readWrittenCased(target, vocabulary, declared);
-    if (!read.reason && qualifyingSegments(target).some((s) => /[A-Z]/.test(s))) {
+    if (read.reason) return read;
+    if (qualifyingSegments(target).some((s) => /[A-Z]/.test(s))) {
         return { reason: "not-lowercase" };
     }
+    if (/[A-Z]/.test(read.shortcode)) {
+        return {
+            reason: "shortcode-not-lowercase",
+            shortcode: read.shortcode,
+            lowercase: { ...read, shortcode: read.shortcode.toLowerCase() },
+        };
+    }
     return read;
 }
 
 /**
- * The segments of a written value that must be lowercase — everything but the
- * shortcode, which keeps whatever the note declares.
+ * The package, system and type segments of a written value, which carry the
+ * `not-lowercase` finding. The shortcode is checked on its own, so its finding
+ * can name the segment and the lowercase spelling.
  *
  * @param {string} target - The value as authored.
  * @returns {string[]} The package / system / type segments, as written.
@@ -666,7 +679,7 @@ function readWrittenCased(target, vocabulary, declared = false) {
  *   `null` when the segment names no known type, or the shortcode is empty.
  */
 function readTypeAndCode(rawType, rawCode, types) {
-    const shortcode = norm(rawCode);
+    const shortcode = String(rawCode).trim();
     if (!shortcode) return null;
 
     const type = norm(rawType);

package/engine/art-fields.mjs

@@ -196,7 +196,8 @@ export function assetImageInfoByPathname(records = []) {
  *   slot's. Omitted, any asset type is taken, which is an embed's rule: it
  *   draws a file, and every asset type is a file.
  * @returns {{record: {package: string, asset: {path: string}}, pathname: string}
- *   |{record: null, reason: string, type?: string}} The asset and the pathname
+ *   |{record: null, reason: string, type?: string, shortcode?: string,
+ *   declared?: string}} The asset and the pathname
  *   it is at, or a reason from
  *   {@link module:engine/wikilink-syntax.LINK_FINDING_REASONS}, or `not-accepted`
  *   when `accepts` is given and the parsed type falls outside it.
@@ -214,6 +215,31 @@ export function readAssetAddress(index, value, defaultType, accepts) {
     if (read.reason === "not-accepted") {
         return { record: null, reason: "not-accepted", type: read.type };
     }
+    if (read.reason === "shortcode-not-lowercase") {
+        // Refused, never lowercased; the lowercase spelling is looked up only
+        // to name it in the finding.
+        const written = String(value);
+        const lower = artTarget(
+            `${written.slice(0, -read.shortcode.length)}${read.lowercase.shortcode}`,
+            defaultType,
+            accepts,
+            {
+                system: ASSET_SYSTEM,
+                package: index?.contentPackage ?? index?.packageId,
+                types: index?.types,
+                packages: index?.packages,
+            },
+        );
+        const canonical = lower.reason ? undefined : renderAddress(lower);
+        const declared =
+            canonical && (index?.assets?.get(canonical) ?? index?.foreign?.get(canonical));
+        return {
+            record: null,
+            reason: read.reason,
+            shortcode: read.shortcode,
+            ...(declared ? { declared: read.lowercase.shortcode } : {}),
+        };
+    }
     if (read.reason) return { record: null, reason: read.reason, type: read.type };
     // **Asset types only**, where the position declares no narrower set. An
     // address may name any type the vocabulary holds, and most of them name a
@@ -322,9 +348,9 @@ export function checkArtSlotSizes(records = [], { config, assetsBase = "" } = {}
  * The pathname an art value names, in the form an authored one takes.
  *
  * Handing the result to {@link module:engine/helpers.resolveImg} is what puts an
- * art address and a body image through one ownership rule. The two empties
- * survive it unchanged: `null` and an absent key mean *no art named, apply the
- * default*, and `""` means *ship blank on purpose*.
+ * art address and a body image through one ownership rule. `null` and an
+ * absent key mean *no art named, apply the default*; an empty string names
+ * nothing and is unresolved like any other address nothing answers.
  *
  * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex}.
  * @param {unknown} value - The value as authored.
@@ -339,7 +365,6 @@ export function checkArtSlotSizes(records = [], { config, assetsBase = "" } = {}
  */
 export function artPathname(index, value, defaultType, accepts) {
     if (value == null) return { pathname: null, resolved: true };
-    if (value === "") return { pathname: "", resolved: true };
     const read = readAssetAddress(index, value, defaultType, accepts);
     if (!read.record) {
         return { pathname: null, resolved: false, reason: read.reason, type: read.type };