@heroiclands/package-build 19.0.0 → 20.0.0

package/engine/journals.mjs

@@ -30,10 +30,13 @@
  * any other: the macro pass reads the same page independently, and withholds
  * nothing from the journal (#1514).
  *
- * Folder placement is identical to the items pack: `sohl.folder` in
- * frontmatter is the target folder's id (from folders.yaml), resolved
- * against a folders.yaml list via the constructor's `folderResolver`. A
- * documentation entry reuses its document's folder id verbatim.
+ * Folder placement is identical to the items pack: `sohl.packFolder` in
+ * frontmatter is a folder **note's address**, resolved through the shared
+ * address index by the constructor's `folderResolver` (#255, #260). A folder
+ * materialises in every pack holding a document that names it, so a journals
+ * pack needs to declare nothing (#257) — which is what stopped this pass
+ * filing documentation into folders its own pack had never heard of. A
+ * documentation entry reuses its document's folder verbatim.
  *
  * Not a standalone script — exports the `Journals` compiler class, imported
  * and driven by `packages/content-build/engine/generate.mjs` (via `npm run build:compiledb`).
@@ -311,6 +314,20 @@ export class Journals extends BasePackCompiler {
      */
     static requiresId = false;
 
+    /**
+     * **None.** A JournalEntry has no artwork — no `img` property, and no
+     * nested place for one — so a note whose whole document is prose has
+     * nowhere to put an authored path (#349).
+     *
+     * The emptiness is the declaration, in the sense `JOURNAL_ONLY_FIELDS` is:
+     * it is what separates a pass that emits no art from one that has simply
+     * not said, and it is the fact the frontmatter lint reports a `lore` note's
+     * inert `img:` from.
+     *
+     * @type {readonly string[]}
+     */
+    static emitsArt = Object.freeze([]);
+
     /**
      * How many of the compiled entries were documentation for a document
      * compiled elsewhere, for the summary.

package/engine/macros.mjs

@@ -295,6 +295,14 @@ export class Macros extends BasePackCompiler {
      */
     static convertsWikilinks = false;
 
+    /**
+     * A Macro carries an `img` — the tile art Foundry shows on the hotbar —
+     * defaulting to {@link DEFAULT_MACRO_IMG} where the note names none.
+     *
+     * @type {readonly string[]}
+     */
+    static emitsArt = Object.freeze(["img"]);
+
     /**
      * @param {object} fm - The note's frontmatter.
      * @returns {boolean} True for a `macro` note.

package/engine/map-notes.mjs

@@ -56,9 +56,9 @@ import { compendiumUuid, makeId, MAP_SUBTYPES, MAP_TYPES } from "./ids.mjs";
 // bridge (`SohlRegionTriggerBehavior`), so an event this build accepts is
 // exactly one the bridge forwards.
 import { CURATED_REGION_EVENTS, EXCLUDED_REGION_EVENTS } from "./region-events.mjs";
-// A map's background art is `img`, as every other note type's art is; `image`
-// is the retired spelling, still read through the retirement window (#142).
-import { readAliasedField } from "./retired-fields.mjs";
+// A map's background art is `img`, as every other note type's art is. `image`,
+// the spelling a map alone once used, is retired and gone (#149).
+import { sohlField } from "./frontmatter.mjs";
 
 /* -------------------------------------------------------------------- */
 /*  Note types and their canvas profiles                                */
@@ -907,7 +907,7 @@ export function buildScene(fm, ctx) {
     // Read from the note rather than from its `sohl:` block: art is not
     // system-specific, so `img` is authored at the top level like every other
     // type's, and `sohlField` honours the block for anything already there.
-    const img = readAliasedField(fm, "img");
+    const img = sohlField(fm, "img");
     if (!img) throw new Error("a map note needs an `img`");
 
     const warn = (message) => {
@@ -981,11 +981,11 @@ export function buildScene(fm, ctx) {
  * @param {string} sceneId - The owning scene's `_id`.
  * @param {string} [img] - The background art, already resolved from the note.
  *   Passed by {@link buildScene}, which reads it from the note rather than from
- *   the block; defaults to whichever spelling the block itself carries, so a
- *   direct two-argument call still works (#142).
+ *   the block; defaults to the block's own `img`, so a direct two-argument call
+ *   still works.
  * @returns {object} The Level document, keyed for the pack.
  */
-export function buildLevel(sohl, sceneId, img = readAliasedField({ sohl }, "img")) {
+export function buildLevel(sohl, sceneId, img = sohlField({ sohl }, "img")) {
     const level = {
         _id: DEFAULT_LEVEL_ID,
         name: sohl.levelName ?? "Ground",

package/engine/note-ids.mjs

@@ -44,6 +44,11 @@ import { documentId } from "./content-address.mjs";
 import { systemOf } from "./document-subtypes.mjs";
 import { contentPackage } from "./content-package.mjs";
 import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
+// The folder id's derivation, taken from the pass that owns it rather than
+// restated here — see the `folder` branch below. `folder-notes.mjs` reaches
+// only `content-address`, `address-charset`, `ids` and `retired-fields`, none
+// of which reach this module, so the direction closes no cycle.
+import { FOLDER_TYPE, folderDocId } from "./folder-notes.mjs";
 
 /**
  * A frontmatter value read as a non-blank string, or `undefined`.
@@ -64,6 +69,20 @@ function text(value) {
 /**
  * The document id a note compiles under: its pin, or its address.
  *
+ * **One type hashes its address differently, and that is not an exception to
+ * the rule but an application of it.** A `Folder` is a document of its own
+ * class, and its id is hashed under the `folder` namespace so that a folder and
+ * an item sharing a shortcode cannot derive one id — a collision Foundry would
+ * not report, since it keys folders and documents in separate collections
+ * (#258). So the answer for a folder comes from
+ * {@link module:engine/folder-notes.folderDocId}, the pass that emits those
+ * documents, rather than from a second derivation here.
+ *
+ * That this function ever answered differently was invisible from inside a
+ * build — no pass reads a folder's id from here — and surfaced only in the
+ * content index, which is read from outside and had no way to be checked
+ * against what shipped (#310).
+ *
  * Returns `undefined` for a file with **no address** — no `type`, or no
  * `shortcode`. Such a file is not an addressable note, so it has no document
  * and inventing an id for one would file it under nothing. Every caller already
@@ -88,7 +107,12 @@ export function noteDocId(fm, { pkg, maps = KNOWN_DOCUMENT_SUBTYPE_MAPS } = {})
     const type = text(fm.type);
     const shortcode = text(fm.shortcode);
     if (!type || !shortcode) return undefined;
-    return documentId(pkg ?? contentPackage(), systemOf(type, maps), type, shortcode);
+    const owner = pkg ?? contentPackage();
+    // Lowercased because `collectFolderNotes` matches the type that way, and
+    // the two must answer alike about the same note or the divergence this
+    // branch closes reopens under a capitalised `type: Folder`.
+    if (type.toLowerCase() === FOLDER_TYPE) return folderDocId(owner, shortcode);
+    return documentId(owner, systemOf(type, maps), type, shortcode);
 }
 
 /**

package/engine/note-vocabulary.mjs

@@ -422,7 +422,14 @@ export const NOTE_VOCABULARY = Object.freeze({
         // values here would put a second, weaker answer beside the real one.
         subTypes: null,
         data: Object.freeze([
-            { name: "portrait", ...TEXT, describe: "Path to the portrait image." },
+            {
+                name: "portrait",
+                ...TEXT,
+                describe:
+                    "Path to the portrait image. Its first segment says which package owns " +
+                    "the file: `systems/…` and `modules/…` are emitted unchanged, anything " +
+                    "else is this package's own and is rooted under its assets.",
+            },
             TEMPLATE_PRIORITY,
             { name: "archetypes", ...LIST, describe: "Archetypal behaviours the being fits." },
             { name: "occupation", ...TEXT, describe: "What the being does for a living." },
@@ -466,7 +473,14 @@ export const NOTE_VOCABULARY = Object.freeze({
     vehicle: Object.freeze({
         subTypes: null,
         data: Object.freeze([
-            { name: "portrait", ...TEXT, describe: "Path to the portrait image." },
+            {
+                name: "portrait",
+                ...TEXT,
+                describe:
+                    "Path to the portrait image. Its first segment says which package owns " +
+                    "the file: `systems/…` and `modules/…` are emitted unchanged, anything " +
+                    "else is this package's own and is rooted under its assets.",
+            },
             TEMPLATE_PRIORITY,
         ]),
     }),
@@ -577,16 +591,31 @@ export const NOTE_VOCABULARY = Object.freeze({
                 ...TEXT,
                 describe: "Roll formula for the delay between contraction and onset.",
             },
+            {
+                name: "onsetDurationBase",
+                ...NUM,
+                describe: "That delay in seconds, stated outright instead of rolled.",
+            },
             {
                 name: "healingCheckDurationFormula",
                 ...TEXT,
                 describe: "Roll formula for the interval between healing checks.",
             },
+            {
+                name: "healingCheckDurationBase",
+                ...NUM,
+                describe: "That interval in seconds, stated outright instead of rolled.",
+            },
             {
                 name: "resolutionDurationFormula",
                 ...TEXT,
                 describe: "Roll formula for the time from onset to resolution.",
             },
+            {
+                name: "resolutionDurationBase",
+                ...NUM,
+                describe: "That time in seconds, stated outright instead of rolled.",
+            },
         ]),
     }),
 
@@ -719,7 +748,39 @@ export const NOTE_VOCABULARY = Object.freeze({
             "shock",
             "coma",
         ]),
-        data: Object.freeze([TEMPLATE_PRIORITY]),
+        data: Object.freeze([
+            TEMPLATE_PRIORITY,
+            {
+                name: "healingCheckDurationFormula",
+                ...TEXT,
+                describe: "Roll formula for the interval between healing checks.",
+            },
+            {
+                name: "healingCheckDurationBase",
+                ...NUM,
+                describe: "That interval in seconds, stated outright instead of rolled.",
+            },
+            {
+                name: "bloodLossAdvanceDurationFormula",
+                ...TEXT,
+                describe: "Roll formula for the interval between blood-loss advances.",
+            },
+            {
+                name: "bloodLossAdvanceDurationBase",
+                ...NUM,
+                describe: "That interval in seconds. Setting it is what makes the wound bleed.",
+            },
+            {
+                name: "courseDurationFormula",
+                ...TEXT,
+                describe: "Roll formula for the interval between course tests.",
+            },
+            {
+                name: "courseDurationBase",
+                ...NUM,
+                describe: "That interval in seconds, stated outright instead of rolled.",
+            },
+        ]),
     }),
 
     weapongear: Object.freeze({
@@ -809,6 +870,7 @@ export const NOTE_VOCABULARY = Object.freeze({
             "folk",
             "culture",
             "bestiary",
+            "gathering",
         ]),
         // Nothing of its own: a lore note is prose, and what it *is* about is
         // its subType. The specification declares an empty table for it, and
@@ -881,12 +943,17 @@ export const NOTE_VOCABULARY = Object.freeze({
         // derived for them, which is precisely what a subType decides (#174).
         subTypes: Object.freeze(["battlemap", "localmap", "regionalmap"]),
         data: Object.freeze([
-            // The specification spells this `img`, matching every other
-            // note type, while the map compiler reads `image` from
-            // `sohl:` today. It says outright that one of the two has
-            // to move; the container takes the specification's name,
-            // and moving the authored key is the migration's business.
-            { name: "img", ...TEXT, describe: "Path to the map art." },
+            // `img`, as every other note type spells its artwork. A map alone
+            // read `image` out of its `sohl:` block; that spelling is retired
+            // and gone (#149), so the two names are one again.
+            {
+                name: "img",
+                ...TEXT,
+                describe:
+                    "Path to the map art, owned by whichever package its first segment " +
+                    "names — `systems/…` and `modules/…` unchanged, anything else this " +
+                    "package's own.",
+            },
             {
                 name: "dimensions",
                 ...LIST,

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;
 
@@ -410,17 +414,6 @@ export class Scenes extends BasePackCompiler {
         const entryId = hasBody ? itemDocEntryId(fm.id) : undefined;
         const { value: authoredFolder } = folderField(fm);
         const folder = this.folderResolver(authoredFolder, { isAddress: true });
-        // 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 warnings = [];
         const scene = buildScene(fm, {
             packageId: foundryPackageId(),
@@ -471,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: [],