@heroiclands/package-build 18.2.0 → 20.0.0

package/engine/retired-fields.mjs

@@ -80,10 +80,19 @@
  * still compiles, correctly, and refusing it would fail a build over a document
  * that is not wrong. Those retire in the three steps `package:` took (#56), and
  * this module carries the **first**: both spellings are read, the current one
- * wins, and the retired one is *reported* rather than refused. The sweep and
- * the refusal come later, once no tree writes it. See
+ * wins, and the retired one is *reported* rather than refused. See
  * {@link RETIRED_FIELD_ALIASES}.
  *
+ * **The third step is deletion, and it needs no code (#149).** `image`, a map's
+ * background art, is the first rename to have run all three: reported (#142),
+ * swept (SoHL#1801 and the position move that followed), then dropped from the
+ * table. Removing the entry is the whole of it — with no alias, the spelling is
+ * an ordinary unknown key in the `sohl:` block, which the frontmatter lint
+ * already refuses as an error alongside the required field it failed to supply.
+ * So nothing here *records* a finished retirement: the absence of an entry is
+ * the record, and a retirement that needed a standing refusal would mean the
+ * replacement never arrived. Do not keep a tombstone for one.
+ *
  * **A retired *position* is the same case, and reads the same (#305).** A field
  * whose shared source moved under `data:` is not renamed — `data.species` and
  * `hm3.species` are one field written in two places — but the retirement has
@@ -93,6 +102,14 @@
  * {@link module:engine/system-block.resolveFieldValue}'s answer; this module
  * only says what an author is told about it.
  *
+ * **A field has two retiring positions, not one (#332).** The in-block key is
+ * the obvious one; the other is the note's **top level**, because #128 did not
+ * invent the facts `data:` holds — it gathered them from exactly there. So
+ * `portrait:` beside `img:` is the pre-`data:` spelling of `data.portrait`,
+ * read for the same reason and reported by {@link retiredTopLevelMessage}. Both
+ * are needed, and separately: a note may have moved one and not the other, and
+ * a single finding covering both would name the wrong line half the time.
+ *
  * @module
  */
 
@@ -100,6 +117,7 @@ import fs from "node:fs";
 
 import { positionInFrontmatter } from "./diagnostics.mjs";
 import { sohlField } from "./frontmatter.mjs";
+import { retiredTopLevelKey } from "./system-block.mjs";
 
 /**
  * What a note declaring `draft:` is told, in one place.
@@ -417,8 +435,8 @@ export function locateFrontmatterKey(absPath, key, value = undefined, { topLevel
  * and what every reader asks for; the value is the spelling still honoured.
  * The table is therefore scoped by the schema without saying so twice: an alias
  * applies to a note only where that note's type declares the current field, so
- * `image` is retired on a map — which declares `img` — and remains an unknown
- * key anywhere else.
+ * `relation` is retired on an affiliation — which declares `relations` — and
+ * remains an unknown key anywhere else.
  *
  * **`templatePriority` (#266).** The number that decides which of several
  * competing templates the Create dialog offers was called `archetype`, and
@@ -433,18 +451,9 @@ export function locateFrontmatterKey(absPath, key, value = undefined, { topLevel
  * read past. Only `affiliation` declares the field, so the alias is reported
  * there and the old spelling stays an ordinary unknown key everywhere else.
  *
- * **`img` (#142).** Every note type names its artwork `img`, at the note's top
- * level, and resolves it the same way. A map alone named its background art
- * `image` and read it out of the `sohl:` block — two spellings for one idea,
- * with nothing to reconcile them, and a specification that had to hedge rather
- * than state a rule. Art is not system-specific: a Scene is a core Foundry
- * document and HM3 would want the identical one, so the field belongs beside
- * every other note's `img`, not inside a system block.
- *
  * @type {Readonly<Record<string, string>>}
  */
 export const RETIRED_FIELD_ALIASES = Object.freeze({
-    img: "image",
     templatePriority: "archetype",
     relations: "relation",
 });
@@ -507,6 +516,38 @@ export function legacyKeyMessage(block, field, file) {
     );
 }
 
+/**
+ * What a note writing a field at the **top-level key `data:` gathered it off**
+ * is told (#332).
+ *
+ * {@link legacyKeyMessage}'s counterpart for the other retiring position. #128
+ * did not invent the facts `data:` holds — it collected them out of the note's
+ * open top level — so `portrait:` beside `img:` is the *pre-`data:`* spelling
+ * of `data.portrait`, and both are read for the same reason both in-block
+ * spellings are: a package moves its corpus when it is ready, not on a flag day.
+ *
+ * It says nothing about which value is emitted, because that is not what an
+ * author needs from it. The value is the same either way; what the finding
+ * counts is one more note still on the old position.
+ *
+ * @param {{name?: string}} field - The declaration, which names the current
+ *   position; the retiring one is derived from it.
+ * @param {string} [file] - The note's path, named in the message. Omit it where
+ *   the caller emits through a diagnostic, whose locator already starts the
+ *   line — repeating it prints the path twice.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function retiredTopLevelMessage(field, file) {
+    const retiring = retiredTopLevelKey(field);
+    return (
+        `top-level \`${retiring}:\` is the pre-\`data:\` position of the shared ` +
+        `\`${field.name}:\` — move it under \`data:\` instead` +
+        (file ? ` — ${file}` : "") +
+        `. Both are read and \`${field.name}\` wins, so the note compiles ` +
+        `identically either way; the top-level key is removed in a later release`
+    );
+}
+
 /**
  * Whether a note writes the retired spelling of a field, wherever it put it.
  *
@@ -539,9 +580,9 @@ export function declaresRetiredAlias(fm, current) {
  * first, then the note's top level — so a renamed field keeps working wherever
  * it was already written while the canonical home is the top level.
  *
- * A blank value counts as absent: `img:` cleared in an editor means the note
- * names no art there, and falling through to the retired spelling is what an
- * author part-way through the rename means by it.
+ * A blank value counts as absent: `relations:` cleared in an editor means the
+ * note records no standings there, and falling through to the retired spelling
+ * is what an author part-way through the rename means by it.
  *
  * @param {object|null|undefined} fm - Parsed frontmatter.
  * @param {string} current - The field's current name.

package/engine/runtime-only-fields.mjs

@@ -0,0 +1,204 @@
+/*
+ * 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
+ */
+
+/**
+ * Schema fields a note may **never** author, because the document writes them
+ * in play (#330).
+ *
+ * `retired-fields.mjs` refuses a field a note may no longer declare; this
+ * refuses one it never could. The two read alike deliberately — a note says one
+ * thing, the build does another, and nothing says so — but they are different
+ * facts, and only one of them is ever swept: a retired field goes away, while
+ * `onsetDate` is a permanent part of `affliction`'s schema that simply is not
+ * content.
+ *
+ * ## What was going wrong
+ *
+ * A DataModel declares plenty of fields a *compiled* document has no business
+ * carrying. SoHL's timed phases are the case that prompted this: each phase of
+ * an `affliction` or a `trauma` stores a `{…DurationFormula, …DurationBase,
+ * …Date}` triplet, and the third of them is instance state, crystallized when
+ * the phase fires. World time does not exist while content is compiled, and `0`
+ * is itself a valid world time — which is why the field is nullable rather than
+ * sentinelled, and why no default could stand in for the missing value.
+ *
+ * Nothing stopped a note writing one, and the build emitted it. Three checks
+ * each declined to catch it, every one of them for its own correct reason:
+ *
+ * - {@link module:engine/system-block.unknownBlockKeys} inspects the **top
+ *   level** of a system block and deliberately never descends into `system:`,
+ *   which is a passthrough for the system's own vocabulary.
+ * - {@link module:engine/system-block.mergeSystemData} writes every authored
+ *   `system.*` path that no declared field claims — and no field claimed
+ *   `contractDate`, so it passed through verbatim.
+ * - The schema check's fatal direction is *undeclared* — emitting a key the
+ *   system does not define. `contractDate` **is** in the schema, so as far as
+ *   that check can see the emitted key is legitimate.
+ *
+ * The gap was that no rule expressed "declared by the system, but never
+ * authorable". This module is that rule, and it is **declarative**: it knows no
+ * field names, only the {@link module:engine/field-spec.FieldSpec} property
+ * `runtimeOnly`, so it holds for any future runtime-only field of any system
+ * without being taught about it.
+ *
+ * ## Why a refusal rather than a drop
+ *
+ * Declaring the field claims its path, so the passthrough would leave it alone
+ * and the authored value would simply vanish — which is the silent-disagreement
+ * failure this package spends its time removing. And the consequence of getting
+ * it wrong is not a missing value but a shipped one: a compiled document
+ * carrying a world-time stamp is one world's play state, installed into every
+ * world that loads the pack.
+ *
+ * @module
+ */
+
+import { runtimeOnlyFields } from "./field-spec.mjs";
+import { getFrontmatter } from "./frontmatter.mjs";
+import { locateFrontmatterKey } from "./retired-fields.mjs";
+import { SYSTEM_DATA_KEY, systemData } from "./system-block.mjs";
+
+/**
+ * What a note authoring a runtime-only field is told, in one place.
+ *
+ * Shared by every caller that can meet one, because an author meets whichever
+ * runs first and they should read the same. It says what the field holds and
+ * that deleting the key is the whole fix — there is no value to correct, which
+ * is what separates this from an out-of-range one.
+ *
+ * The reason comes from the declaration rather than from here: this module
+ * knows no field names, and a message written per field would be a second
+ * statement of the fact the declaration already carries.
+ *
+ * @param {string} key - The **whole key the note wrote**, from the region it
+ *   sits in down to the field: `sohl.system.onsetDate` on the item's own note,
+ *   `sohl.items[2].system.contractDate` on an actor's embedded entry. Composed
+ *   by the caller, because only it knows where it found the value — and a
+ *   message naming the leaf alone leaves an author a note to search.
+ * @param {import("./field-spec.mjs").FieldSpec} field - The declaration, which
+ *   carries the reason.
+ * @param {string} [file] - The note's path, named in the message. Omit it where
+ *   the caller emits through a diagnostic, whose locator already starts the
+ *   line — repeating it prints the path twice.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function runtimeOnlyMessage(key, field, file) {
+    return (
+        `\`${key}:\` is runtime state, not ` +
+        `content — delete it` +
+        (file ? ` — ${file}` : "") +
+        `. It holds ${field.runtimeOnly}, so no value for it exists at compile ` +
+        `time, and a compiled document carrying one ships a fact about a world ` +
+        `the pack has never been loaded into. The key is left out of the ` +
+        `document entirely, so the DataModel's own initial value stands`
+    );
+}
+
+/**
+ * The runtime-only fields a note actually writes, in declaration order.
+ *
+ * **Presence is the whole test**, as it is for every retired field: an authored
+ * `onsetDate: null` is as much a claim about play state as a number is, and it
+ * is exactly the belief the message exists to correct. So the question is
+ * whether the path resolves to anything at all, never whether the value is a
+ * usable one.
+ *
+ * Only `<block>.system.<to>` is searched, because it is the only position a
+ * runtime-only field is reachable at. Such a declaration carries no `name`, so
+ * it has neither a legacy in-block key nor a shared top-level source — and a
+ * bare `<block>.onsetDate` is an unrecognized block key, which
+ * {@link module:engine/system-block.unknownBlockKeys} already reports as an
+ * error naming the note and the line.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {readonly import("./field-spec.mjs").FieldSpec[]} [fields] - The
+ *   type's field declaration.
+ * @param {object} options - Options.
+ * @param {string} options.block - The system block to look in.
+ * @returns {import("./field-spec.mjs").FieldSpec[]} The offending declarations.
+ */
+export function authoredRuntimeOnlyFields(fm, fields, { block } = {}) {
+    if (!fm || typeof fm !== "object" || !block) return [];
+    return runtimeOnlyIn(systemData(fm, block), fields);
+}
+
+/**
+ * The same question asked of a `system` block directly.
+ *
+ * A note's own block is reached through {@link authoredRuntimeOnlyFields}, but
+ * it is not the only place an author writes one: an actor note's `items:`
+ * entries carry a `system:` overlay that is deep-merged onto the template
+ * verbatim, with no field declaration in the path at all. That overlay is a
+ * `system` block by every meaning except where it sits, and a `contractDate`
+ * written there ships exactly as one written on the trauma's own note.
+ *
+ * @param {Record<string, unknown>|null|undefined} data - The authored `system`
+ *   data.
+ * @param {readonly import("./field-spec.mjs").FieldSpec[]} [fields] - The
+ *   type's field declaration.
+ * @returns {import("./field-spec.mjs").FieldSpec[]} The offending declarations.
+ */
+export function runtimeOnlyIn(data, fields) {
+    if (!data || typeof data !== "object") return [];
+    return runtimeOnlyFields(fields).filter(
+        (field) =>
+            typeof field.to === "string" &&
+            field.to !== "" &&
+            getFrontmatter(data, field.to, undefined) !== undefined,
+    );
+}
+
+/**
+ * Refuse a note that authors any of its type's runtime-only fields.
+ *
+ * Refused rather than reported: the note is not compiled, so nothing it would
+ * have emitted reaches a pack. What that costs is the caller's to decide — each
+ * of them counts the refused note and emits a located diagnostic, so a refusal
+ * is never a silent skip.
+ *
+ * The **first** offending field is thrown on. A note authoring a whole phase
+ * triplet would otherwise produce three findings that are one mistake, and the
+ * build stops on this note either way; the fix for the first is the fix for all
+ * of them.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
+ *   could not be parsed.
+ * @param {readonly import("./field-spec.mjs").FieldSpec[]} [fields] - The
+ *   type's field declaration. A type that declares none — or declares no
+ *   runtime-only field — passes.
+ * @param {object} options - Options.
+ * @param {string} options.block - The system block to look in.
+ * @param {string} [options.file] - The note's path, named in the message. Omit
+ *   it where the caller emits through a diagnostic, which puts the locator at
+ *   the start of the line already — repeating it prints the path twice.
+ * @param {string} [options.absPath] - The note's file on disk, read only on the
+ *   failing path to locate the offending line and column. The position rides on
+ *   the thrown error as `position`, for a caller that emits a diagnostic.
+ * @returns {void}
+ * @throws {Error} When the note authors one.
+ */
+export function assertNoRuntimeOnlyFields(fm, fields, { block, file, absPath } = {}) {
+    const [field] = authoredRuntimeOnlyFields(fm, fields, { block });
+    if (!field) return;
+
+    const key = `${block}.${SYSTEM_DATA_KEY}.${field.to}`;
+    const err = new Error(`${runtimeOnlyMessage(key, field, file)}.`);
+    // The **leaf** of the destination path, which is the key as the note writes
+    // it: `to` is dotted for a nested field, and a locator handed
+    // `charges.value` would find nothing. Deliberately not anchored at column 1
+    // — the key lives two levels in, under `<block>.system`.
+    const leaf = /** @type {string} */ (field.to).split(".").pop();
+    const position = locateFrontmatterKey(absPath, /** @type {string} */ (leaf));
+    if (position) err.position = position;
+    throw err;
+}

package/engine/scenes.mjs

@@ -73,13 +73,6 @@ import { packRouter } from "./pack-router.mjs";
 import { foundryPackageId } from "./content-package.mjs";
 import { itemDocEntryId } from "./item-docs.mjs";
 import { behaviorDocId, buildScene, isMapType, regionDocId } from "./map-notes.mjs";
-import {
-    RETIRED_FIELD_ALIASES,
-    declaresRetiredAlias,
-    locateFrontmatterKey,
-    readAliasedField,
-    retiredAliasMessage,
-} from "./retired-fields.mjs";
 
 /**
  * Every SoHL action name this build knows about, for the `action:` warning on a
@@ -127,6 +120,17 @@ export class Scenes extends BasePackCompiler {
     static id = "scenes";
     static label = "map";
 
+    /**
+     * A map note's `img` is its background art, and it is **required**: the map
+     * compiler refuses a note without one. It lands on the scene's level rather
+     * than on a property spelled `img`, which makes no difference to the
+     * question this declaration answers — the authored path reaches the output
+     * (#349). The place Adventure this pass bundles carries it too.
+     *
+     * @type {readonly string[]}
+     */
+    static emitsArt = Object.freeze(["img"]);
+
     /** @type {string} */
     adventureDir;
 
@@ -408,19 +412,8 @@ export class Scenes extends BasePackCompiler {
         // shared `docEntryTypes` arrangement (#1514) — so neither
         // pass has to read the other's output.
         const entryId = hasBody ? itemDocEntryId(fm.id) : undefined;
-        const { value: authoredFolder, isAddress: folderIsAddress } = folderField(fm);
-        const folder = this.folderResolver(authoredFolder, { isAddress: folderIsAddress });
-        // The retired spelling of the background art, reported where an author
-        // meets it soonest — every consumer runs the compile, and not every
-        // one runs the lint (#142). Located by reading the note back, which is
-        // what the other retired-field reports do: this is the one path that
-        // needs the position, so it is paid for only here.
-        if (declaresRetiredAlias(fm, "img")) {
-            this.noteWarn(
-                retiredAliasMessage(RETIRED_FIELD_ALIASES.img, "img"),
-                locateFrontmatterKey(this.currentNote?.absPath, RETIRED_FIELD_ALIASES.img),
-            );
-        }
+        const { value: authoredFolder } = folderField(fm);
+        const folder = this.folderResolver(authoredFolder, { isAddress: true });
         const warnings = [];
         const scene = buildScene(fm, {
             packageId: foundryPackageId(),
@@ -457,13 +450,11 @@ export class Scenes extends BasePackCompiler {
                     name,
                     markdown,
                     leadName: name,
-                    // As in the journals pass: an id crosses packs verbatim,
-                    // an address resolves in the pack that emits it — which is
-                    // what makes the folder materialise there too (#257).
-                    folder:
-                        folderIsAddress ?
-                            this.folderResolver(authoredFolder, { isAddress: true })
-                        :   authoredFolder,
+                    // As in the journals pass: an address resolves in the
+                    // pack that emits it, which is what makes the folder
+                    // materialise there too (#257). The id spelling that used
+                    // to cross packs verbatim is retired (#260).
+                    folder: this.folderResolver(authoredFolder, { isAddress: true }),
                     flags: fm.flags,
                 })
             :   null;
@@ -473,7 +464,7 @@ export class Scenes extends BasePackCompiler {
             this.places.set(placeKey, {
                 key: placeKey,
                 name: sohlField(fm, "placeName", null) || name,
-                img: readAliasedField(fm, "img") ?? null,
+                img: sohlField(fm, "img", null),
                 pinned: false,
                 scenes: [],
                 journal: [],

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.