@heroiclands/package-build 19.0.0 → 20.0.0

package/sohl/actors.mjs

@@ -63,6 +63,14 @@ import { SOHL_DOCUMENT_SUBTYPES } from "./document-subtypes.mjs";
 // verbatim, and `sohl.img` / `sohl.effects` / `sohl.flags` overriding their
 // shared top-level forms for this system alone (#58).
 import { blockProperty, mergeSystemData } from "../engine/system-block.mjs";
+import { readField, retiredTopLevelKey } from "../engine/field-spec.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 system this pass compiles for — the block its notes write.
@@ -81,6 +89,38 @@ const DEFAULT_IMG = {
     being: "systems/sohl/assets/icons/game-icons/delapouite/person.svg",
 };
 
+/**
+ * The being's sheet portrait — the one row of the content format's actor
+ * mapping table that is authored rather than derived.
+ *
+ * **Declared, because the position is not a spelling anyone can guess.** This
+ * was read with `blockProperty(fm, SYSTEM, "portrait")`, which knows the block
+ * and the note's top level and nothing else — so `data.portrait`, the position
+ * the specification names and `sohl-thalorna` writes on 646 beings, was
+ * invisible, and `?? defaultImg` on the next line turned every miss into the
+ * generic person icon rather than into a complaint (#332). Going through
+ * {@link module:engine/field-spec.readField} is what makes the mapping table
+ * executable here as it already is for HM3's `data.species`.
+ *
+ * `img` is deliberately **not** declared beside it: the mapping table keeps a
+ * note's token art at the top level, so `blockProperty` is the whole of its
+ * resolution and there is no `data.img` to reach for.
+ *
+ * @type {import("../engine/field-spec.mjs").FieldSpec}
+ */
+const PORTRAIT_FIELD = Object.freeze({
+    name: "data.portrait",
+    legacyKey: "portrait",
+    to: "portrait",
+    shape: "path",
+    // The two empties survive, because the caller's `?? defaultImg` is what
+    // tells them apart: `null` and an absent key mean "no art named, default
+    // me", `""` means "ship blank on purpose" (#218).
+    read: (raw) => resolveImg(raw),
+    default: null,
+    describe: "Path to the portrait image.",
+});
+
 /**
  * The default art for an actor subtype.
  *
@@ -206,21 +246,48 @@ export class Actors extends SystemActorCompiler {
                     this.errorCount++;
                     return;
                 }
-                const { shortcode, type, ...rest } = entry;
-                if (!type) {
-                    this.noteError(`${ctx}: sohl.items[${index}] missing type`);
+                const { model, shortcode, type, ...rest } = entry;
+                if (shortcode !== undefined) {
+                    this.noteError(
+                        `${ctx}: sohl.items[${index}] carries a top-level ` +
+                            `\`shortcode\` — that key is retired. Name the item ` +
+                            `this entry copies with \`model:\` (an address, e.g. ` +
+                            `\`${type ?? "skill"}-${shortcode}\`), and use ` +
+                            `\`system.shortcode\` for this item's own identity.`,
+                    );
+                    this.errorCount++;
+                    return;
+                }
+                const read = model === undefined ? null : this.readModel(model, index, ctx);
+                if (model !== undefined && !read) return;
+                if (read && type !== undefined) {
+                    this.noteError(
+                        `${ctx}: sohl.items[${index}] states both \`model\` and ` +
+                            `\`type\` — the model's address already names the ` +
+                            `type, so the second is a place to be wrong. Drop \`type\`.`,
+                    );
+                    this.errorCount++;
+                    return;
+                }
+                const effectiveType = read ? read.type : type;
+                if (!effectiveType) {
+                    this.noteError(
+                        `${ctx}: sohl.items[${index}] names no \`model\` and no ` +
+                            `\`type\` — an entry that copies nothing must state ` +
+                            `\`name\`, \`type\` and \`system.shortcode\`.`,
+                    );
                     this.errorCount++;
                     return;
                 }
                 const embedded = this.resolveEmbedded(
                     itemsMap,
                     actorId,
-                    type,
-                    shortcode || null,
+                    effectiveType,
+                    read ? read.shortcode : null,
                     rest,
                     `items:${index}`,
                     ctx,
-                    { fmKey: "items" },
+                    { fmKey: "items", modelPackage: read?.package ?? null },
                 );
                 if (embedded) items.push(embedded);
             });
@@ -298,6 +365,36 @@ export class Actors extends SystemActorCompiler {
         const { value: authoredFolder, isAddress } = folderField(fm);
         const folder = this.folderResolver(authoredFolder, { isAddress });
 
+        // The two retiring positions a declared field may be read from (#305,
+        // #332). **Warnings**, on the pattern every retirement in this package
+        // follows: the note compiles to the correct document either way, so
+        // reddening a tree over one would refuse before the sweep rather than
+        // after it. What they buy is a count — the whole reason #332 was
+        // invisible for so long is that nothing said which position a value
+        // had come from, and a default is indistinguishable from a miss.
+        const portraitReports = {
+            block: SYSTEM,
+            onLegacyKey: (field) =>
+                this.noteWarn(
+                    legacyKeyMessage(SYSTEM, field),
+                    locateFrontmatterKey(this.currentNote?.absPath, field.legacyKey),
+                ),
+            // Anchored at column 1: the two positions share a spelling here —
+            // `sohl.portrait` and `portrait` — so a locator that took the first
+            // match would point at the block key while the message named the
+            // top-level one.
+            onRetiredTopLevel: (field) =>
+                this.noteWarn(
+                    retiredTopLevelMessage(field),
+                    locateFrontmatterKey(
+                        this.currentNote?.absPath,
+                        retiredTopLevelKey(field),
+                        undefined,
+                        { topLevel: true },
+                    ),
+                ),
+        };
+
         const system = {
             // The frontmatter shortcode is the actor's stable `(type, shortcode)`
             // key — and, for a being that is an archetype, its archetype
@@ -311,7 +408,9 @@ export class Actors extends SystemActorCompiler {
             templatePriority: systemTemplatePriority(fm, ctx),
             // Nullish, not `||` (#218): a note that names no portrait gets the
             // subtype's default, one that writes `""` ships blank on purpose.
-            portrait: resolveImg(blockProperty(fm, SYSTEM, "portrait")) ?? defaultImg,
+            // Resolved through the declaration so `data.portrait` is reached at
+            // all — see {@link PORTRAIT_FIELD} (#332).
+            portrait: readField(PORTRAIT_FIELD, fm, portraitReports) ?? defaultImg,
             appearance: renderSection(body || "", "appearance"),
             dossier: renderSection(body || "", "dossier"),
         };

package/sohl/item-fields.mjs

@@ -103,6 +103,40 @@ function noteContext(fm, type) {
     return `${type} "${fm?.name?.full ?? fm?.shortcode ?? "?"}"`;
 }
 
+/**
+ * A timed phase's duration **formula** — what is rolled to seed the interval.
+ *
+ * SoHL's own field is a nullable, non-blank `StringField`, and the interval it
+ * yields is in **seconds** (`"432000"` is the five days the world setting
+ * defaults to). A bare number is as valid as a dice expression, and both are
+ * stringified here so a note may write either — which is also why no `kind` is
+ * declared: a lint claiming this must be a string would report `86400` as an
+ * authoring mistake when it is the commonest thing to write.
+ *
+ * Blank reads as unset rather than as `""`, matching the field's `blank: false`
+ * — but a field declaring {@link FieldSpec.omitWhenAbsent} skips before this
+ * runs when the note carries nothing, so the `null` is only ever reached by a
+ * note that cleared the key on purpose.
+ */
+const DURATION_FORMULA = Object.freeze({
+    shape: "roll formula, or a whole number of seconds",
+    read: (raw) => (raw == null || raw === "" ? null : String(raw)),
+});
+
+/**
+ * A timed phase's rolled duration, in **seconds** — the fact, where the formula
+ * above is the definition.
+ *
+ * Authoring it states the interval outright instead of leaving it to a roll,
+ * which is what a fixed-cadence phase wants. Non-numeric reads `0` rather than
+ * `NaN`, as every other count in this vocabulary does.
+ */
+const DURATION_BASE = Object.freeze({
+    shape: "whole number of seconds",
+    kind: "number",
+    read: (raw) => (raw == null || raw === "" ? null : Number(raw) || 0),
+});
+
 /** Aptitude weights per skill selector, validated as whole numbers. */
 const SKILL_APTITUDES = Object.freeze({
     shape: "map of skill selector → whole number",
@@ -414,6 +448,104 @@ export const ITEM_FIELDS = Object.freeze({
             describe:
                 "What running the course to the end does to the host: `death`, or the benign default `cured`.",
         },
+        // The two **authored** thirds of each timed-phase triplet (#329). Every
+        // one omits its key when the note does not carry it, because the value
+        // that stands otherwise is the DataModel's `initial: null` — writing a
+        // compile-time `null` over it would say "this phase takes no time",
+        // which is a different claim from "this note does not set the phase",
+        // and `AfflictionLogic.rollDuration()` opens `if (!formula) return 0`.
+        //
+        // Until they were declared here the only way to author one was the raw
+        // `system:` passthrough — undocumented, uncoerced, and absent from the
+        // field list every author-facing surface is built from — so no note in
+        // any tree wrote one and every shipped affliction had zero-length
+        // phases.
+        // Spelled out, one entry per field, for the reason the dates below are:
+        // a name assembled from a phase argument is not in the source, so it
+        // cannot be grepped, and each phase's prose differs anyway — which is
+        // the whole content of the declaration.
+        {
+            name: "onsetDurationFormula",
+            to: "onsetDurationFormula",
+            ...DURATION_FORMULA,
+            omitWhenAbsent: true,
+            describe:
+                "Interval from contracting the affliction to the start of onset. Omitted when unset, leaving no incubation.",
+        },
+        {
+            name: "onsetDurationBase",
+            to: "onsetDurationBase",
+            ...DURATION_BASE,
+            omitWhenAbsent: true,
+            describe:
+                "The onset interval in seconds, standing in for a roll of the formula. Omitted when unset.",
+        },
+        {
+            name: "healingCheckDurationFormula",
+            to: "healingCheckDurationFormula",
+            ...DURATION_FORMULA,
+            omitWhenAbsent: true,
+            describe:
+                "Interval between healing checks, once the affliction is symptomatic. Omitted when unset.",
+        },
+        {
+            name: "healingCheckDurationBase",
+            to: "healingCheckDurationBase",
+            ...DURATION_BASE,
+            omitWhenAbsent: true,
+            describe:
+                "The healing-check interval in seconds, standing in for a roll of the formula. Omitted when unset.",
+        },
+        {
+            name: "resolutionDurationFormula",
+            to: "resolutionDurationFormula",
+            ...DURATION_FORMULA,
+            omitWhenAbsent: true,
+            describe:
+                "Interval from onset to the affliction running its course. Omitted when unset.",
+        },
+        {
+            name: "resolutionDurationBase",
+            to: "resolutionDurationBase",
+            ...DURATION_BASE,
+            omitWhenAbsent: true,
+            describe:
+                "The resolution interval in seconds, standing in for a roll of the formula. Omitted when unset.",
+        },
+        // The `…Date` third of every timed-phase triplet, declared as **runtime
+        // state** (#330). A phase is authored as its `…DurationFormula`; the
+        // `…DurationBase` records what that rolled to; the date records *when
+        // it happened*, and only play can know that. All four are
+        // `worldTimeDateField()`s in SoHL's schema — nullable rather than
+        // sentinelled precisely because `0` is itself a valid world time — so
+        // there is no blank an author could honestly write either.
+        //
+        // Declaring them does two things at once: the key is left out of the
+        // compiled document, so SoHL's own `initial: null` stands, and a note
+        // authoring one is refused with a message naming the field and its
+        // reason. Written out rather than generated from a phase name, as the
+        // schema they mirror now is: a field name assembled from an argument is
+        // not in the source, and cannot be grepped, read or reported on.
+        {
+            to: "contractDate",
+            runtimeOnly: "the world time the host contracted the affliction",
+            describe: "When the host contracted it. Play state, never authored.",
+        },
+        {
+            to: "onsetDate",
+            runtimeOnly: "the world time onset fired at",
+            describe: "When onset fired. Play state, never authored.",
+        },
+        {
+            to: "treatmentDate",
+            runtimeOnly: "the world time the affliction was last treated",
+            describe: "When it was last treated. Play state, never authored.",
+        },
+        {
+            to: "resolutionDate",
+            runtimeOnly: "the world time the affliction ran its course",
+            describe: "When it resolved. Play state, never authored.",
+        },
     ]),
 
     armorgear: Object.freeze([
@@ -817,6 +949,77 @@ export const ITEM_FIELDS = Object.freeze({
             default: null,
             describe: "Shortcode of the body location injured. Unset on a descriptive condition.",
         },
+        // A trauma's three timed phases (#329). Its healing check and course
+        // both fall back to a **world setting** when the trauma sets neither
+        // half, which is the sharper reason these omit rather than default: a
+        // compile-time `null` written here is still a value, and the seeding in
+        // `TraumaDataModel._preCreate` reads `data.courseDurationFormula == null`
+        // to decide whether the GM's configured interval applies. A default
+        // would answer that question for every trauma in every world.
+        //
+        // `bloodLossAdvance*` is the one an author reaches for most: a trauma
+        // that sets it bleeds, and one that leaves it unset does not.
+        {
+            name: "healingCheckDurationFormula",
+            to: "healingCheckDurationFormula",
+            ...DURATION_FORMULA,
+            omitWhenAbsent: true,
+            describe:
+                "Interval between healing checks. Omitted when unset, leaving the world's configured interval to apply.",
+        },
+        {
+            name: "healingCheckDurationBase",
+            to: "healingCheckDurationBase",
+            ...DURATION_BASE,
+            omitWhenAbsent: true,
+            describe:
+                "The healing-check interval in seconds, standing in for a roll of the formula. Omitted when unset.",
+        },
+        {
+            name: "bloodLossAdvanceDurationFormula",
+            to: "bloodLossAdvanceDurationFormula",
+            ...DURATION_FORMULA,
+            omitWhenAbsent: true,
+            describe:
+                "Interval between blood-loss advances. Omitted when unset, leaving the world's configured interval to apply.",
+        },
+        {
+            name: "bloodLossAdvanceDurationBase",
+            to: "bloodLossAdvanceDurationBase",
+            ...DURATION_BASE,
+            omitWhenAbsent: true,
+            describe:
+                "The blood-loss interval in seconds. Setting it is what makes the wound bleed; omitted when unset, and the wound does not.",
+        },
+        {
+            name: "courseDurationFormula",
+            to: "courseDurationFormula",
+            ...DURATION_FORMULA,
+            omitWhenAbsent: true,
+            describe:
+                "Interval between course tests, for a condition that runs one — shock, coma, infection. Omitted when unset.",
+        },
+        {
+            name: "courseDurationBase",
+            to: "courseDurationBase",
+            ...DURATION_BASE,
+            omitWhenAbsent: true,
+            describe:
+                "The course-test interval in seconds, standing in for a roll of the formula. Omitted when unset.",
+        },
+        // Runtime state, for the reason `affliction`'s four are (#330): a
+        // trauma's dates are crystallized when the phase fires, and world time
+        // does not exist while content is compiled.
+        {
+            to: "contractDate",
+            runtimeOnly: "the world time the injury was taken",
+            describe: "When the injury was taken. Play state, never authored.",
+        },
+        {
+            to: "treatmentDate",
+            runtimeOnly: "the world time the injury was last treated",
+            describe: "When it was last treated. Play state, never authored.",
+        },
     ]),
 
     weapongear: Object.freeze([

package/sohl/note-schemas.mjs

@@ -148,8 +148,8 @@ const BEING_FIELDS = Object.freeze([
  *
  * `img` is the one required field — the compiler refuses a map note without it,
  * since a scene with no background is not a map. It was spelled `image` and
- * read from the `sohl:` block until #142; both spellings still compile, and the
- * retired one is reported rather than refused.
+ * read from the `sohl:` block until #142, which read both while the trees were
+ * swept; that retirement has since completed and `image` is gone (#149).
  *
  * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
  */
@@ -161,7 +161,10 @@ const MAP_FIELDS = Object.freeze([
         // Art is not system-specific — a Scene is a core Foundry document, and
         // every other note type carries its `img` at the note's top level.
         shared: true,
-        describe: "The scene's background image.",
+        describe:
+            "The scene's background image. Owned by whichever package its first segment " +
+            "names — `systems/…` and `modules/…` are emitted unchanged, anything else is " +
+            "this package's own and is rooted under its assets.",
     },
     {
         name: "dimensions",

package/types/engine/actor-compiler.d.mts

@@ -41,6 +41,54 @@ export function deepMerge(base: any, overlay: any): any;
  * @returns {string} The address, `subType:shortcode`.
  */
 export function itemAddress(subType: string, shortcode: string): string;
+/**
+ * The key one predefined item is held under **for the package that publishes
+ * it** — the address a `model:` naming that package resolves through (#334).
+ *
+ * The unqualified {@link itemAddress} stays beside it, and the two answer
+ * different questions. A `model` that names no package means *this* one and
+ * takes the unqualified key, where a local definition still shadows a
+ * dependency's. A `model` that names a package takes this one, which nothing
+ * can shadow: that is the whole point of writing the package down.
+ *
+ * Not the canonical wikilink address, because this map is keyed in the
+ * **document's** vocabulary — a Foundry Item subtype — while a canonical address
+ * carries the *note* type. The two differ wherever a system maps a type to a
+ * differently-named subtype, and translating here would put the translation in
+ * two places.
+ *
+ * @param {string} pkg - The content package that publishes the item.
+ * @param {string} subType - The Foundry Item subtype.
+ * @param {string} shortcode - The item's `system.shortcode`.
+ * @returns {string} The address, `package:subType:shortcode`.
+ */
+export function packagedItemAddress(pkg: string, subType: string, shortcode: string): string;
+/**
+ * The key one predefined item is held under **in the catalogue**, with the
+ * shortcode folded to lower case.
+ *
+ * A shortcode is case-sensitive and routinely mixed — `Clb`, `LtShoe`,
+ * `HsTunic` — while an **address** is not: `readQualifier` normalises what it
+ * reads, and every canonical address is lowercase. So the moment a `model:` is
+ * read as an address (#334), `weapongear-clb` has to find the document whose
+ * `system.shortcode` is `Clb`, and an exact match cannot (#346).
+ *
+ * Folding is safe because the fold is already the address: no two items in any
+ * published tree differ only by the case of their shortcode, and #340 will make
+ * that impossible rather than merely true.
+ *
+ * **This is not {@link itemAddress}, and must not become it.** That one seeds
+ * {@link embeddedItemId}, so folding there would change the `_id` of every
+ * embedded item whose identity carries a capital — a silent re-identification of
+ * documents nothing about which had changed. The catalogue is a lookup table;
+ * an id is a promise.
+ *
+ * @param {string} subType - The Foundry Item subtype.
+ * @param {string} shortcode - The item's `system.shortcode`, in any case.
+ * @param {string} [pkg] - The publishing package, for the qualified form.
+ * @returns {string} The catalogue key.
+ */
+export function catalogueKey(subType: string, shortcode: string, pkg?: string): string;
 /**
  * What identifies one embedded item on its actor.
  *
@@ -136,6 +184,13 @@ export class SystemActorCompiler extends BasePackCompiler {
     /** @type {readonly string[]} */
     itemsSourceDirs: readonly string[];
     foreignSourceDirs: any;
+    /**
+     * Every package a `model:` may name besides this one — the dependencies
+     * whose item catalogues were supplied (#334).
+     *
+     * @returns {Set<string>} The dependency package ids.
+     */
+    get foreignPackages(): Set<string>;
     /**
      * This pass's system map, or a message naming the class that forgot it.
      *
@@ -195,9 +250,34 @@ export class SystemActorCompiler extends BasePackCompiler {
      * @returns {object|null} The embedded item, or null when it resolved to
      *   nothing — always with a finding emitted.
      */
-    resolveEmbedded(itemsMap: Map<string, object>, actorId: string, type: string, shortcode: string | null, overlay?: object, indexKey: string, ctx: string, { fmKey }?: {
-        fmKey?: string | undefined;
-    }): object | null;
+    /**
+     * Read an entry's `model:` — the address of the item it is a copy of.
+     *
+     * The address grammar is the wikilink one (#336), so a `model` is written at
+     * whatever length says what it means: `skill-wpnc` within this package,
+     * `sohl-sohl-skill-wpnc` to reach another. The system segment defaults from
+     * the block the entry sits in — `<system>.items` — which is what makes the
+     * short form name an *Item* here while the same string in body prose names
+     * a page.
+     *
+     * It replaced a top-level `shortcode:` that meant something different from
+     * the `system.shortcode` beside it and could not say which package a
+     * template came from (#334).
+     *
+     * @param {unknown} model - The authored value.
+     * @param {number} index - The entry's position, for the message.
+     * @param {string} ctx - Diagnostic context (the actor's label).
+     * @returns {{type: string, shortcode: string, package: string|null}|null}
+     *   The parsed address, or `null` after reporting why it is not one.
+     */
+    readModel(model: unknown, index: number, ctx: string): {
+        type: string;
+        shortcode: string;
+        package: string | null;
+    } | null;
+    resolveEmbedded(itemsMap: any, actorId: any, type: any, shortcode: any, overlay: any, indexKey: any, ctx: any, { fmKey, modelPackage }?: {
+        modelPackage?: null | undefined;
+    }): any;
     #private;
 }
 import { BasePackCompiler } from "./base-compiler.mjs";

package/types/engine/address-charset.d.mts

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

package/types/engine/base-compiler.d.mts

@@ -99,14 +99,42 @@ export class BasePackCompiler {
      * @type {boolean}
      */
     static requiresSystemBlock: boolean;
+    /**
+     * The **art fields** this pass reads off a note and writes onto its
+     * document — `img`, `portrait`, whichever of them reaches the output.
+     *
+     * Empty by default, and every shipped pass states its own, for the reason
+     * {@link BasePackCompiler.readsPackOutputOf} does: the fact belongs to the
+     * class that does the writing, and a second list of it somewhere else is a
+     * list free to disagree with what is actually emitted.
+     *
+     * The reader is the frontmatter lint. `img` is a *shared top-level* field —
+     * legal on every note whatever its type, because
+     * `BLOCK_DOCUMENT_PROPERTIES` maps it onto `document.img` — so a note whose
+     * document has no such property authors it, validates, compiles, and loses
+     * the value with nothing said. That is #349: `Parrot` in `sohl-thalorna`
+     * had declared `img:` since long before the art rule existed and compiled
+     * `img: null` exactly as a note declaring nothing does. Naming the fields
+     * here is what lets the lint tell an inert key from a live one.
+     *
+     * A pass that emits art **anywhere** in its document declares it, not only
+     * one that writes a top-level `img`: the scenes pass puts the path on the
+     * scene's background rather than on a property called `img`, and the value
+     * is no less live for it. The question this answers is whether the authored
+     * path reaches the output at all.
+     *
+     * @type {readonly string[]}
+     */
+    static emitsArt: readonly string[];
     /**
      * @param {object} options
      * @param {string} options.contentBase - Root of the content tree.
      * @param {string} options.dest - Where this pass writes its JSON.
      * @param {readonly string[]} options.skipDirectories - Directories the walk
      *   never descends into. Required: see {@link assertStatedScope}.
-     * @param {(path: string|null) => string|null} [options.folderResolver] -
-     *   Resolves a `sohl.folder` id against this pack's folder hierarchy.
+     * @param {(address: string|null) => string|null} [options.folderResolver] -
+     *   Resolves a `packFolder` — a folder note's address — to the Foundry
+     *   folder id it materialises as in this pack (#255, #257).
      * @param {string} [options.packName] - The pack this pass writes.
      * @param {string} [options.docType] - The Foundry document type it holds.
      * @param {{resolve: Function}} [options.router] - The pack router. Omit it
@@ -118,7 +146,7 @@ export class BasePackCompiler {
         contentBase: string;
         dest: string;
         skipDirectories: readonly string[];
-        folderResolver?: ((path: string | null) => string | null) | undefined;
+        folderResolver?: ((address: string | null) => string | null) | undefined;
         packName?: string | undefined;
         docType?: string | undefined;
         router?: {
@@ -236,6 +264,29 @@ export class BasePackCompiler {
      *   the note's own file can be read.
      */
     eligibleFor(fm: object): boolean;
+    /**
+     * A refusal only this pass can make, because its subject is the note's
+     * **type** (#330).
+     *
+     * The `assertNo*Field` family above it in the walk is type-agnostic by
+     * construction: it runs before `selects`, so that a note declaring a
+     * retired field is answered whichever pass would have claimed it. A rule
+     * about what a *`trauma`* may write cannot live there — it needs the type's
+     * field declaration, which only the pass that compiles the type can reach.
+     *
+     * So it is a hook, called once the note is known to be this pass's, and its
+     * throw is counted and located exactly as the family's is: the note is
+     * declined rather than skipped, and the build fails naming the line.
+     *
+     * The default refuses nothing, which is the honest position for a pass
+     * whose documents have no schema to have opinions about.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @returns {void}
+     * @throws {Error} When the note authors something its type forbids. The
+     *   error may carry a `position` for the diagnostic.
+     */
+    assertAuthorable(fm: object): void;
     /**
      * Whether this pass claims a note. **Required.**
      *