@heroiclands/package-build 19.0.0 → 20.0.0

package/engine/schema-check.mjs

@@ -68,6 +68,9 @@ import path from "node:path";
 import { cachedSchemaPath, SCHEMA_ARTIFACT_FILE } from "./foreign-catalog.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { systemData, systemDataPaths, undeclaredPaths } from "./system-block.mjs";
+// A field the document writes for itself in play: declared by the schema,
+// emitted by no builder, and authored by no note (#330).
+import { runtimeOnlyFields } from "./field-spec.mjs";
 
 /**
  * The artifact version this module reads.
@@ -133,12 +136,21 @@ export function declaredFields(artifact, documentType, subtype) {
  * the path beneath it separately, so a comparison that knew only the leaf would
  * report the container as unemitted and the leaf as undeclared.
  *
- * @param {readonly {to: string}[]} fields - A type's field declaration.
+ * **A runtime-only field is not in it** (#330). It declares a `to` in order to
+ * *claim* the path — so the verbatim passthrough leaves it alone and the
+ * refusal has something to name — and `buildFromFields` deliberately skips it,
+ * because the document writes that field in play. Counting it here would make
+ * the check assert the builder writes a key it never writes; the *unemitted*
+ * direction handles it instead, in {@link compareFields}.
+ *
+ * @param {readonly {to: string, runtimeOnly?: string}[]} fields - A type's
+ *   field declaration.
  * @returns {Set<string>} The paths, parents included.
  */
 export function emittedFields(fields) {
     const out = new Set();
     for (const field of fields ?? []) {
+        if (field?.runtimeOnly) continue;
         if (typeof field?.to !== "string" || !field.to) continue;
         const parts = field.to.split(".");
         for (let i = 1; i <= parts.length; i++) {
@@ -221,6 +233,15 @@ export function compareFields({
         }
 
         const emitted = emittedFields(fields);
+        // Paths the declaration says the *document* writes in play (#330). They
+        // are neither emitted nor a defect, so they answer the unemitted
+        // question below rather than appearing in it: "every compiled document
+        // will carry the field's initial value" is exactly what a runtime-only
+        // field is for, and reporting it would leave a permanent warning that
+        // the correct declaration cannot clear.
+        const runtimeOnly = new Set(
+            runtimeOnlyFields(/** @type {never} */ (fields)).map((field) => field.to),
+        );
         for (const path of emitted) {
             if (declared.all.has(path)) continue;
             undeclared.push({
@@ -238,6 +259,7 @@ export function compareFields({
             // on a type that populates them correctly — two findings, both
             // false, on the first real schema this was run against.
             if (coveredByAncestor(path, emitted)) continue;
+            if (runtimeOnly.has(path)) continue;
             unemitted.push({
                 type,
                 subtype,

package/engine/site-index.mjs

@@ -52,6 +52,7 @@
 import path from "node:path";
 
 import { canonicalKey, readCanonicalKey } from "./content-address.mjs";
+import { NO_SYSTEM } from "./systems.mjs";
 import { systemOf } from "./document-subtypes.mjs";
 import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./note-claims.mjs";
 import { hasDocEntry } from "./item-docs.mjs";
@@ -266,6 +267,17 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
             if (hasDocEntry(type)) {
                 contentTypes.add(`doc${type}`);
                 index.set(`doc${type}/${shortcode}`.toLowerCase(), value);
+                // The canonical documentation address too, so the page answers
+                // to the address a bare prose link expands to (#336): body
+                // prose is under no system block, so it defaults to `none`, and
+                // a system-bearing type's `none` address is its `doc<type>`
+                // one. In Foundry that names a second document; here it names
+                // this same page, which is what makes one authored link correct
+                // in both builds.
+                index.set(
+                    canonicalKey(e.pkg ?? ownPackage, NO_SYSTEM, `doc${type}`, shortcode),
+                    value,
+                );
             }
         }
     }
@@ -316,6 +328,11 @@ export function wikiContext(built, { src, file, type = null, errors, foreignInde
         sections: built.sections,
         contentTypes: built.contentTypes,
         packages: built.packages,
+        // The package a link written on this page defaults to when it names
+        // none (#336). Taken from the resolved configuration, the same source
+        // the index's own addresses are built from, so a bare link cannot
+        // resolve against a package the index never keyed.
+        contentPackage: contentPackage(),
         type,
         errors,
         src,

package/engine/subtype-registry.mjs

@@ -64,6 +64,36 @@ export const KNOWN_DOCUMENT_SUBTYPE_MAPS = Object.freeze([
     HM3_DOCUMENT_SUBTYPES,
 ]);
 
+/**
+ * Every note type any shipped map compiles into an **Actor**.
+ *
+ * Derived from the maps rather than written out, so a system that adds an actor
+ * type is covered without a second list to keep in step — the same reason
+ * {@link KNOWN_DOCUMENT_SUBTYPE_MAPS} exists rather than a hand-kept table.
+ *
+ * It exists because an actor note publishes documentation like every other
+ * system-bearing note (#337). `docEntryTypes` was `itemTypes` plus `macro` and
+ * the map types, which left a being as the one system-bearing note with no
+ * `none` address — nothing a prose link could land on, since its only address
+ * named the Actor. Composing that set needs to know which types are actors, and
+ * this is where the maps that know already live.
+ *
+ * **Not an item type.** This widens what carries *documentation*; it must never
+ * widen what the items pass compiles, or a being note would be compiled into an
+ * Item beside its Actor.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const ACTOR_TYPES = Object.freeze(
+    new Set(
+        KNOWN_DOCUMENT_SUBTYPE_MAPS.flatMap((map) =>
+            Object.entries(map.types)
+                .filter(([, row]) => row?.document === "Actor")
+                .map(([noteType]) => noteType),
+        ),
+    ),
+);
+
 /**
  * The map one system ships, by its id.
  *

package/engine/system-block.mjs

@@ -50,6 +50,8 @@
  *    kept until #126 moves it;
  * 3. the shared top-level property the field **declares** as its source, which
  *    may be a dotted path (`data.portrait`) rather than a sibling key;
+ * 3b. for a `data.` source, the bare top-level key that container gathered it
+ *    off — the retiring *shared* position, derived rather than declared;
  * 4. the field's own default.
  *
  * ## Steps 2 and 3 are two declarations, because they are two positions
@@ -75,6 +77,29 @@
  * that declares one is mid-sweep by construction, which is what
  * {@link module:engine/field-spec.readsLegacyKey} reports on.
  *
+ * ## Step 3 has a retiring position too, and it is derived (#332)
+ *
+ * `legacyKey` retires the *in-block* position, and for a while that looked like
+ * the whole of what `data:` left behind. It is not. The facts `data:` holds
+ * were not invented by it — #128 **gathered** them out of the note's open top
+ * level, where `portrait:` sat beside `img:` and `shortcode:` — so a field that
+ * declares `data.portrait` has two shared spellings to read, not one, and
+ * reading only the current one is the same silent miss `legacyKey` exists to
+ * prevent. It is worse here, because the caller's `?? default` cannot tell a
+ * value that is absent from one that is merely unreachable: 646 `sohl-thalorna`
+ * beings shipped the generic person icon over an authored path, and no tree
+ * that still writes the top-level spelling — `sohl`'s own bestiary does —
+ * looked any different from one that names no art at all.
+ *
+ * So step 3b reads it, and unlike `legacyKey` it is **derived**: the retiring
+ * spelling of `data.<key>` is `<key>`, mechanically, because that is precisely
+ * what the move did. A second declaration would be a second place for the same
+ * fact to be stated, and the retirement it describes is one rule rather than a
+ * per-field decision. {@link retiredTopLevelKey} is that derivation, and it
+ * answers for `data.` sources alone — `protection.blunt` is a path into a
+ * container notes have always written at the top level, never a `blunt:` that
+ * moved.
+ *
  * ## A name that collides across the two vocabularies skips step 3
  *
  * A field's `name` is both its identity and the shared property it draws from,
@@ -90,8 +115,10 @@
  * `"null"` in fifteen documents (#218).
  *
  * So a field may declare `topLevelMeans`: what the top-level key of that name
- * means *instead*. Declaring it removes step 3 for that field, leaving the two
- * positions that describe the document rather than the note. It is deliberately
+ * means *instead*. Declaring it removes the whole shared level — step 3 and the
+ * retiring 3b alike, since both read the note's top level and the objection is
+ * to that level, not to a spelling — leaving the two positions that describe
+ * the document rather than the note. It is deliberately
  * a per-field opt-out rather than a change to the order — step 3 is right
  * wherever the two levels state the same quantity, which is nearly everywhere —
  * and its value is the reason rather than a bare flag, so the collision is
@@ -356,6 +383,43 @@ export function legacyKeyOf(field) {
     return field?.legacyKey ?? field?.name;
 }
 
+/**
+ * The `data:` container's prefix, as a shared source spells it.
+ *
+ * @type {string}
+ */
+const DATA_PREFIX = "data.";
+
+/**
+ * The bare top-level key a `data:`-sourced field is being swept off — step 3b.
+ *
+ * `data:` (#128) did not invent the facts it holds; it *gathered* them, out of
+ * the note's open top level where each was a sibling of `img` and `shortcode`.
+ * So the retiring spelling of `data.portrait` is not a second declaration
+ * anyone has to write — it is `portrait`, mechanically, and the same holds for
+ * every other key that move relocated. Deriving it is what keeps the two
+ * spellings of one field from disagreeing the way two declarations would.
+ *
+ * **Only a `data.` source has one.** `protection.blunt` and `impact.die` are
+ * paths into containers a note has always written at the top level; they were
+ * never `blunt:` or `die:`, and reading those would invent a position rather
+ * than remember one.
+ *
+ * A field declaring {@link module:engine/field-spec.FieldSpec `topLevelMeans`}
+ * has no shared position at all, retiring or otherwise — the resolver checks
+ * that before asking.
+ *
+ * @param {{name?: string}} field - The declaration.
+ * @returns {string|undefined} The retiring top-level path, or `undefined` for a
+ *   field whose shared source never lived there.
+ */
+export function retiredTopLevelKey(field) {
+    const name = field?.name;
+    if (typeof name !== "string" || !name.startsWith(DATA_PREFIX)) return undefined;
+    const rest = name.slice(DATA_PREFIX.length);
+    return rest === "" ? undefined : rest;
+}
+
 /**
  * Where a declared field's value came from.
  *
@@ -363,7 +427,7 @@ export function legacyKeyOf(field) {
  * can distinguish a value an author wrote from one a default supplied, which
  * the value alone never says.
  *
- * @typedef {"system"|"block"|"shared"|"default"|"value"} FieldSource
+ * @typedef {"system"|"block"|"shared"|"topLevel"|"default"|"value"} FieldSource
  */
 
 /**
@@ -422,6 +486,20 @@ export function resolveFieldValue(field, fm, { block = "sohl" } = {}) {
     if (field.topLevelMeans === undefined) {
         const shared = getFrontmatter(fm, field.name, undefined);
         if (shared !== undefined) return { value: shared, from: "shared" };
+
+        // 3b. The bare top-level key the `data:` source was gathered off — the
+        //     retiring *shared* position, exactly as `legacyKey` is the
+        //     retiring *in-block* one (#332). Without it a field declaring
+        //     `data.portrait` cannot see the `portrait:` every tree still
+        //     writes, and the miss arrives at the caller's `?? default` as an
+        //     ordinary absence: 646 `sohl-thalorna` beings compiled the generic
+        //     person icon over an authored path, deterministically and with
+        //     nothing said.
+        const retiring = retiredTopLevelKey(field);
+        if (retiring !== undefined) {
+            const legacy = getFrontmatter(fm, retiring, undefined);
+            if (legacy !== undefined) return { value: legacy, from: "topLevel" };
+        }
     }
 
     // 4. The field's own default.

package/engine/web-wikilinks.mjs

@@ -46,7 +46,8 @@ import { replaceOutsideCode } from "./code-fences.mjs";
 // The canonical `package-system-type-shortcode` key, so a package-qualified
 // address is matched the way a vendored manifest publishes it — by the
 // segments the target supplies, with the system wildcarded unless stated (#59).
-import { canonicalKey, readCanonicalKey } from "./content-address.mjs";
+import { canonicalKey, expandAddress, readCanonicalKey } from "./content-address.mjs";
+import { NO_SYSTEM } from "./systems.mjs";
 // The one rule about a link's shape both builds share: it carries a label, and
 // {@link unlabelledLinkMessage} is the one place that says so (#180).
 import { unlabelledLinkMessage } from "./wikilink-syntax.mjs";
@@ -85,32 +86,33 @@ import { authoredLabel, WIKILINK, isSamePage, parseWikilink } from "./wikilink-s
  * @param {object|null} read - From {@link readQualifier}.
  * @returns {string | null} The index key, or `null` when not an address.
  */
-function lookupRead(index, read) {
+function lookupRead(index, read, contentPackage) {
     if (!read || read.reason) return undefined;
-    // An unqualified address stays the system-blind short key, which is the
-    // wildcard an author writing `[[skill-melee]]` means, and resolves within
-    // this package only.
-    if (!read.package) return index.get(`${read.type}/${read.shortcode}`.toLowerCase());
+    // Every omitted segment defaults from where the link is written (#336) —
+    // package from the citing package, system from the block, which on a page
+    // body is `none` — so the target expands to exactly one canonical address
+    // and this is a plain lookup. No filter, no single-hit rule, and no
+    // ambiguity: one key names one entry.
+    //
+    // It replaced a system-blind short key for the unqualified form, which
+    // could be silently overwritten by a second note of the same
+    // `(type, shortcode)` under another system.
+    const key = expandAddress(read, { package: contentPackage, system: NO_SYSTEM });
+    const found = index.get(key);
+    if (found || read.package) return found;
 
-    // A package-qualified one is matched by the segments it supplies, with the
-    // system wildcarded unless stated (#59) — an exact `get` cannot express
-    // that, and would silently miss every address whose system it did not
-    // guess. Exactly one hit resolves; two are an ambiguity for the caller to
-    // report rather than a pick to make here.
-    const type = String(read.type).toLowerCase();
-    const shortcode = String(read.shortcode).toLowerCase();
-    const pkg = String(read.package).toLowerCase();
-    let found;
-    for (const [key, value] of index) {
-        const parts = readCanonicalKey(key);
-        if (!parts) continue;
-        if (parts.package !== pkg) continue;
-        if (read.system && parts.system !== String(read.system).toLowerCase()) continue;
-        if (parts.type !== type || parts.shortcode !== shortcode) continue;
-        if (found) return undefined;
-        found = value;
-    }
-    return found;
+    // A local target may also be keyed by its short form. On the KB that is not
+    // a second answer: an item note renders as **one page** which is its own
+    // documentation, so `skill/climb`, `docskill/climb` and both canonical
+    // addresses are all the same value (#1362) — the fallback cannot pick
+    // differently, only earlier. It stays because an index built before the
+    // canonical documentation key was added still carries the short one, and
+    // because a page collision here is caught by the site index's own
+    // `ambiguous` set rather than by silent overwrite as in the pack index.
+    return (
+        index.get(`${read.itemDoc ? "doc" : ""}${read.type}/${read.shortcode}`.toLowerCase()) ??
+        undefined
+    );
 }
 
 /**
@@ -366,7 +368,7 @@ export function resolveWebWikilinks(body, ctx) {
         const read = readQualifier(target, ctx.contentTypes ?? new Set(), ctx.packages);
         const rawKey = target.toLowerCase();
         const hit =
-            lookupRead(ctx.index, read) ??
+            lookupRead(ctx.index, read, ctx.contentPackage) ??
             // `section/slug` is the site's own address for a page, and it is in
             // the same map. Admitted only when the target carries a slash, so
             // a page's bare slug cannot answer for an address.
@@ -375,7 +377,11 @@ export function resolveWebWikilinks(body, ctx) {
             // local one (#1446), so a cross-package hit needs no special case
             // below. Local wins: a live build is authoritative and a vendored
             // manifest can only be staler.
-            (ctx.foreign ? lookupRead(ctx.foreign, read) : undefined);
+            // A short form names *this* package (#336), so it never reaches a
+            // vendored manifest; only a fully qualified address does.
+            (ctx.foreign && read?.package ?
+                lookupRead(ctx.foreign, read, ctx.contentPackage)
+            :   undefined);
         if (hit) {
             // An address with an *empty* label has no prose to show (a
             // shortcode is not display text), so the document's **current**

package/engine/wikilink-syntax.mjs

@@ -182,6 +182,7 @@ export const LINK_FINDING_REASONS = Object.freeze(
     new Set([
         "unlabelled",
         "not-an-address",
+        "not-lowercase",
         "unknown-type",
         "unresolved",
         "ambiguous",
@@ -276,6 +277,12 @@ export function linkFindingMessage({ reason, target, packages, anchor }) {
                 `[[package-system-type-shortcode|Text]] for a note in another ` +
                 `package`
             );
+        case "not-lowercase":
+            return (
+                `address [[${target}]] capitalises a package, system or type ` +
+                `segment — those three are lowercase, and only the shortcode ` +
+                `keeps its case`
+            );
         case "unknown-type":
             return `address [[${target}]] names no known content type`;
         case "ambiguous":

package/engine/wikilinks.mjs

@@ -87,7 +87,9 @@ import crypto from "crypto";
 
 import { compendiumUuid, ITEM_PACK, packForType, pageUuid, PACK_BY_TYPE } from "./ids.mjs";
 import { readCanonicalKey } from "./content-address.mjs";
-import { isSystemSegment } from "./systems.mjs";
+import { isSystemSegment, NO_SYSTEM } from "./systems.mjs";
+import { systemOf } from "./document-subtypes.mjs";
+import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { replaceOutsideCode } from "./code-fences.mjs";
 // The syntax lives in `./wikilink-syntax.mjs`, so the web resolver and this
@@ -207,6 +209,48 @@ export function resolveItemDocType(qualifier, types) {
  *   but names no known type; or `null` when it is not an address at all.
  */
 export function readQualifier(target, types, packages) {
+    // **Package, system and type are lowercase; the shortcode is not.** A
+    // shortcode is case-sensitive and routinely mixed — `Clb`, `LtShoe`,
+    // `HsTunic` — so it is written as the note declares it. The three segments
+    // in front of it are closed vocabularies with one spelling each, and
+    // accepting `Skill` beside `skill` would bless two ways of writing one
+    // address. Reported rather than folded, so the corpus has one form.
+    //
+    // Tested only once the target *parses*: a note name is full of capitals
+    // (`[[Shock State]]`), and calling that a badly-cased address rather than
+    // not an address would name the wrong mistake. Neither tree carries a
+    // violation — 10,538 authored targets — so this pins a rule already kept.
+    const read = readQualifierCased(target, types, packages);
+    if (read && !read.reason && qualifyingSegments(target).some((s) => /[A-Z]/.test(s))) {
+        return { reason: "not-lowercase" };
+    }
+    return read;
+}
+
+/**
+ * The segments of a target that must be lowercase — everything but the
+ * shortcode, which is case-sensitive and keeps whatever the note declares.
+ *
+ * @param {string} target - The link target, anchor already removed.
+ * @returns {string[]} The package / system / type segments, as written.
+ */
+function qualifyingSegments(target) {
+    const slash = target.lastIndexOf("/");
+    // The legacy `type/shortcode` form states only a type.
+    if (slash > 0) return [target.slice(0, slash)];
+    const parts = target.split("-");
+    return parts.slice(0, -1);
+}
+
+/**
+ * {@link readQualifier} without the lowercase rule — the grammar alone.
+ *
+ * @param {string} target
+ * @param {Set<string>} types
+ * @param {Set<string>} [packages]
+ * @returns {object|null}
+ */
+function readQualifierCased(target, types, packages) {
     // The slash form is legacy and states neither package nor system, so it is
     // read first and separately. A slash is unconditionally a qualifier —
     // nothing else uses one — which is why an unknown type before it is
@@ -440,25 +484,24 @@ function foreignHits(index, read) {
     const wanted = norm(read.itemDoc ? `doc${read.type}` : read.type);
     const shortcode = norm(read.shortcode);
 
-    // One filter for every reading, because an address is matched **by the
-    // segments it supplies** and wildcarded on the ones it does not (#59). A
-    // package-qualified target used to take a separate exact-`get` path, which
-    // is what let this function carry its own copy of the key grammar — a
-    // hand-built `${package}-${type}-${shortcode}` and a literal segment count
-    // — and drift from `readCanonicalKey` the moment the grammar gained a
-    // system segment. There is one reader now.
+    // **An omitted package means this package** (#336), so a short form
+    // addresses nothing foreign and never reaches a dependency's index. A link
+    // that resolved into another package only because no local note claimed the
+    // address was resolving by accident, and would have retargeted silently the
+    // day one did. Reaching another package is the fully qualified form's job.
     //
-    // The system is a wildcard unless the target states one: most authored
-    // links name none, and defaulting it to `none` would exclude every link to
-    // an item, which is the majority — 1,632 of `sohl`'s own resolve into the
-    // items pack. Ambiguity is caught by the caller's single-hit rule rather
-    // than pre-empted by a guess here.
+    // The system likewise comes from where the link is written — `none` in a
+    // body — so both segments are known here and this is an exact lookup rather
+    // than a filter. That is what makes a cross-package `ambiguous` impossible:
+    // one key, one entry.
+    if (!read.package) return [];
+    const wantedSystem = norm(read.system ?? NO_SYSTEM);
     const hits = [];
     for (const [key, entry] of index.foreign) {
         const parts = readCanonicalKey(key);
         if (!parts) continue;
-        if (read.package && parts.package !== norm(read.package)) continue;
-        if (read.system && parts.system !== norm(read.system)) continue;
+        if (parts.package !== norm(read.package)) continue;
+        if (parts.system !== wantedSystem) continue;
         if (parts.type !== wanted || parts.shortcode !== shortcode) continue;
         hits.push(entry);
     }
@@ -616,7 +659,22 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
                 });
                 return unresolvedLink(text || target, target);
             }
-            itemDoc = qualified.itemDoc;
+            // An omitted system defaults from where the link is written (#336),
+            // and a body is under no system block, so it is `none`. Under
+            // `none` a system-bearing type addresses its *documentation* — a
+            // note's `none` address IS its `doc<type>` entry — which is what a
+            // prose link almost always means. Stating the system is how prose
+            // reaches the Item instead.
+            //
+            // Only a type whose *own* document carries a system is redirected.
+            // A `macro` and the map types have documentation journals too, but
+            // their own documents are core ones already at `none`, so
+            // `macro-autoattack` names the Macro and `docmacro-autoattack` its
+            // journal — two live addresses the redirect would collapse.
+            itemDoc =
+                qualified.itemDoc ||
+                ((qualified.system ?? NO_SYSTEM) === NO_SYSTEM &&
+                    systemOf(qualified.type, KNOWN_DOCUMENT_SUBTYPE_MAPS) !== NO_SYSTEM);
             doc = index.byShortcode.get(`${qualified.type}/${qualified.shortcode}`);
         }
         if (!doc) {

package/hm3/actors.mjs

@@ -29,10 +29,11 @@
  * **What is emitted, and what is deliberately not.** Four rows of the content
  * format's `being` mapping table give HM3 a destination — `data.portrait` →
  * `system.bioImage`, `data.species`, `data.gender`, `data.occupation`, and
- * `data.templatePriority` → `flags.hm3.templatePriority` — and, since #305,
- * three of them are *declared as those sources* rather than as the bare key the
- * corpus writes, so the specification's mapping is executable rather than
- * aspirational. Plus the two anchored prose sections: `{#appearance}` is HM3's `description` and `{#dossier}` its
+ * `data.templatePriority` → `flags.hm3.templatePriority` — and every one of
+ * them is *declared as that source* rather than as the bare key the corpus
+ * writes, so the specification's mapping is executable rather than
+ * aspirational. Three were declared by #305; `data.portrait` was still read by
+ * hand until #332, and so was the one row that did not work. Plus the two anchored prose sections: `{#appearance}` is HM3's `description` and `{#dossier}` its
  * `biography`. Everything else an HM3 actor carries — the thirteen abilities,
  * the sunsign, `move`, `fatigue`, `shockIndex`, a creature's `loadRating` — has
  * no shared source stated anywhere, so it is authored at its own path under
@@ -49,15 +50,19 @@
  */
 
 import { resolveName, resolveImg } from "../engine/helpers.mjs";
-import { buildFromFields, STRING } from "../engine/field-spec.mjs";
+import { buildFromFields, readField, retiredTopLevelKey, STRING } from "../engine/field-spec.mjs";
 import { SystemActorCompiler } from "../engine/actor-compiler.mjs";
 import { renderSection } from "../engine/anchored-sections.mjs";
 import { documentSubtype } from "../engine/document-subtypes.mjs";
 import { HM3_DOCUMENT_SUBTYPES } from "./document-subtypes.mjs";
 import { templateFlags } from "./template-priority.mjs";
-// The retirement window's report, shared with the frontmatter lint so the
-// two cannot say different things about the same key (#305).
-import { legacyKeyMessage, locateFrontmatterKey } from "../engine/retired-fields.mjs";
+// The retirement window's reports, shared with the frontmatter lint so the
+// two cannot say different things about the same key (#305, #332).
+import {
+    legacyKeyMessage,
+    locateFrontmatterKey,
+    retiredTopLevelMessage,
+} from "../engine/retired-fields.mjs";
 // The note-level `hm3:` block: `hm3.system` onto the document's `system`
 // verbatim, and `hm3.img` / `hm3.items` / `hm3.effects` / `hm3.flags`
 // overriding their shared top-level forms for this system alone (#58).
@@ -94,6 +99,33 @@ const ACTOR_FIELDS = Object.freeze([
     },
 ]);
 
+/**
+ * The actor's bio image — the fourth row of the specification's `being` table,
+ * and the last one that was still read by hand.
+ *
+ * Declared for the reason {@link ACTOR_FIELDS} is, and fixed for the reason
+ * `data.species` was: read with `blockProperty(fm, block, "portrait")` it saw
+ * the block and the note's top level and nothing else, so the `data.portrait`
+ * the specification names never reached the document and the `?? defaultImg`
+ * beside it dressed the miss up as "this note names no art" (#332).
+ *
+ * It is **not** in `ACTOR_FIELDS`, because `buildFromFields` has no seam for
+ * the subtype default that has to follow it — the `?? defaultImg` is the whole
+ * of what distinguishes an unnamed portrait from a deliberately blank one
+ * (#218), and it needs a subtype the coercion is not handed.
+ *
+ * @type {import("../engine/field-spec.mjs").FieldSpec}
+ */
+const BIO_IMAGE_FIELD = Object.freeze({
+    name: "data.portrait",
+    legacyKey: "portrait",
+    to: "bioImage",
+    shape: "path",
+    read: (raw) => resolveImg(raw),
+    default: null,
+    describe: "Path to the portrait image.",
+});
+
 /**
  * The two `data:` facts HM3 declares on a `character` and not on a `creature`.
  *
@@ -259,6 +291,24 @@ export class Hm3Actors extends SystemActorCompiler {
                 locateFrontmatterKey(this.currentNote?.absPath, field.legacyKey),
             );
 
+        // The shared level's own retiring position — the top-level key `data:`
+        // gathered the field off (#332). Same signal, same severity, separate
+        // callback: a note may have moved one position and not the other.
+        // Anchored at column 1, because the two spellings coincide — `portrait`
+        // names a block key and a top-level one — and a locator that took the
+        // first match would point at the wrong line.
+        const onRetiredTopLevel = (field) =>
+            this.noteWarn(
+                retiredTopLevelMessage(field),
+                locateFrontmatterKey(
+                    this.currentNote?.absPath,
+                    retiredTopLevelKey(field),
+                    undefined,
+                    { topLevel: true },
+                ),
+            );
+        const reports = { block, onLegacyKey, onRetiredTopLevel };
+
         // One spelling, as everywhere else: `packFolder` names a folder note
         // by its address. This pass once read only the Foundry id, so an HM3
         // tree could not file an actor by address at all — which its own sweep
@@ -270,15 +320,15 @@ export class Hm3Actors extends SystemActorCompiler {
         const system = {
             // Nullish, not `||` (#218): a note that names no portrait gets the
             // subtype's default, one that writes `""` ships blank on purpose.
-            bioImage: resolveImg(blockProperty(fm, block, "portrait")) ?? defaultImg,
+            // Resolved through the declaration so `data.portrait` is reached at
+            // all — see {@link BIO_IMAGE_FIELD} (#332).
+            bioImage: readField(BIO_IMAGE_FIELD, fm, reports) ?? defaultImg,
             description: renderSection(body || "", "appearance"),
             biography: renderSection(body || "", "dossier"),
-            ...buildFromFields(ACTOR_FIELDS, { block, onLegacyKey })(fm),
+            ...buildFromFields(ACTOR_FIELDS, reports)(fm),
             // Declared on `character` alone, so written there alone — see the
             // module note.
-            ...(subType === "character" ?
-                buildFromFields(CHARACTER_FIELDS, { block, onLegacyKey })(fm)
-            :   {}),
+            ...(subType === "character" ? buildFromFields(CHARACTER_FIELDS, reports)(fm) : {}),
         };
 
         // Whatever the note authors under `hm3.system`, at the DataModel's own

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "19.0.0",
+    "version": "20.0.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",
@@ -155,7 +155,7 @@
     "devDependencies": {
         "@changesets/cli": "^3.0.0",
         "@types/node": "^26.2.0",
-        "vitest": "^4.1.10"
+        "vitest": "^5.0.0"
     },
     "scripts": {
         "test": "vitest run",