@heroiclands/package-build 19.0.0 → 20.0.0

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

@@ -113,6 +113,70 @@ export function packageAddress(fm: object): string;
  * @returns {string} `package-system-type-shortcode`, lowercased.
  */
 export function canonicalKey(pkg: string, system: string, type: string, shortcode: string): string;
+/**
+ * Which system a frontmatter key path is written under.
+ *
+ * The **enclosing system block** decides, at any depth within it, and nothing
+ * else does: `sohl.items[3].model` and `sohl.system.body.structure` are both
+ * `sohl` because both sit under `sohl:`. Everywhere else is {@link NO_SYSTEM} —
+ * top-level frontmatter, the shared `data:` container, and body prose, which has
+ * no key path at all and passes `undefined`.
+ *
+ * It is the block rather than the field, so a `WikiLink` field needs no opinion
+ * about systems and no per-field table has to be kept in step with the schema.
+ *
+ * The first segment must **be** a declared system, not merely look like one:
+ * `sohlish.items` is a key called `sohlish`, and `notes.sohl.thing` names no
+ * block at all.
+ *
+ * @param {string} [keyPath] - The dotted frontmatter key path, or `undefined`
+ *   for body prose.
+ * @returns {string} The system id, or `none`.
+ */
+export function blockSystem(keyPath?: string): string;
+/**
+ * Expand a written address to the one canonical address it names.
+ *
+ * **An omitted segment defaults from where the link is written** (#336) — it is
+ * not a wildcard, and resolution is not a search. Package omitted means the
+ * citing note's own; system omitted means {@link blockSystem} of the key path it
+ * was written under. So every short form has exactly one expansion, computed
+ * before anything is looked up, and there is no candidate set to disambiguate.
+ *
+ * **Under `none`, a system-bearing type addresses its documentation journal.**
+ * A note's `none` address *is* its `doc<type>` entry — the Item is the one with
+ * a system — so a prose `[[affiliation-sirvadar|…]]` names the page, which is
+ * almost always what prose means. A link that means the Item states the system
+ * and gets it. This is the defaulting rule applied, not an exception carved out
+ * of it.
+ *
+ * **Only a type whose own document carries a system is redirected.** A `macro`
+ * and the map types have documentation journals too, but their own documents
+ * are core ones and already live at `none` — so `<pkg>-none-macro-x` names the
+ * Macro and `<pkg>-none-docmacro-x` its journal, two live addresses that the
+ * redirect would collapse into one. The test is the note type's own system,
+ * not merely whether it has a doc entry.
+ *
+ * A `doc<type>` written explicitly is `none` **wherever** it appears, even
+ * inside a system block: no game system defines a JournalEntry, so there is no
+ * other system for one to belong to.
+ *
+ * @param {{type: string, shortcode: string, package?: string, system?: string,
+ *   itemDoc?: boolean}} read - A qualifier, as `readQualifier` returns one.
+ * @param {{package: string, system?: string}} where - The citing context: the
+ *   tree's own content package, and the system of the block the link sits in.
+ * @returns {string} The canonical `package-system-type-shortcode`.
+ */
+export function expandAddress(read: {
+    type: string;
+    shortcode: string;
+    package?: string;
+    system?: string;
+    itemDoc?: boolean;
+}, where: {
+    package: string;
+    system?: string;
+}): string;
 /**
  * Reads a canonical key back into its parts.
  *

package/types/engine/content-format.d.mts

@@ -40,6 +40,9 @@ export const CONTENT_FORMAT_PATH: string;
  *   property — what a note actually writes. `appearance.eye_color` is authored
  *   as `appearance`, so that is the key recorded.
  * @property {Set<string>} dataPaths - The declared paths, whole.
+ * @property {string[]} subTypes - The `subType` values the section enumerates,
+ *   in document order — empty when it states none, which is the ordinary case
+ *   for a type that has no `subType` at all.
  */
 /**
  * One `system.*` target the specification names for one note type.
@@ -99,6 +102,12 @@ export type TypeSpec = {
      * - The declared paths, whole.
      */
     dataPaths: Set<string>;
+    /**
+     * - The `subType` values the section enumerates,
+     * in document order — empty when it states none, which is the ordinary case
+     * for a type that has no `subType` at all.
+     */
+    subTypes: string[];
 };
 /**
  * One `system.*` target the specification names for one note type.

package/types/engine/field-spec.d.mts

@@ -17,6 +17,26 @@
  * @returns {boolean} True when the value came from the retiring position.
  */
 export function readsLegacyKey(field: FieldSpec, from: import("./system-block.mjs").FieldSource): boolean;
+/**
+ * Whether a resolution read a field from the top-level key `data:` gathered it
+ * off — the shared level's retiring position (#332).
+ *
+ * {@link readsLegacyKey}'s sibling, and the same signal: a finding here counts
+ * one note still on the pre-`data:` spelling, so the sweep has something to
+ * count down instead of a corpus nobody has surveyed.
+ *
+ * The `from` tag already carries the whole answer — step 3b is the only thing
+ * that produces it, and it produces it only for a `data.` source — so this is a
+ * name for the question rather than a second test of it. Named all the same,
+ * because a compile-time report and the frontmatter lint both ask it and must
+ * not drift apart about what counts.
+ *
+ * @param {FieldSpec} field - The declaration.
+ * @param {import("./system-block.mjs").FieldSource} from - Where
+ *   {@link resolveFieldValue} said the value came from.
+ * @returns {boolean} True when the value came from the retiring top-level key.
+ */
+export function readsRetiredTopLevel(field: FieldSpec, from: import("./system-block.mjs").FieldSource): boolean;
 /**
  * Read one declared field out of a note's frontmatter.
  *
@@ -38,12 +58,77 @@ export function readsLegacyKey(field: FieldSpec, from: import("./system-block.mj
  *   rather than a returned list because the caller is a compiler, which already
  *   knows the note and how to locate a key in it; this module knows neither and
  *   would have to invent a finding shape to say so.
+ * @param {(field: FieldSpec) => void} [options.onRetiredTopLevel] - Called with
+ *   each field read from the top-level key `data:` gathered it off (#332). The
+ *   shared level's counterpart to `onLegacyKey`, and a separate callback
+ *   because it is a separate position: a note may have moved one of the two and
+ *   not the other, and a caller that conflated them would tell its author to
+ *   fix the wrong line.
  * @returns {any} The value to emit.
  */
-export function readField(field: FieldSpec, fm: object, { block, onLegacyKey }?: {
+export function readField(field: FieldSpec, fm: object, options?: {
     block?: string | undefined;
     onLegacyKey?: ((field: FieldSpec) => void) | undefined;
+    onRetiredTopLevel?: ((field: FieldSpec) => void) | undefined;
 }): any;
+/**
+ * The same read, reporting **where the value came from** as well.
+ *
+ * {@link readField} answers "what does this field hold", which is what almost
+ * every caller wants. A builder has one further question — *should the key be
+ * written at all* — and it cannot be answered from the value: `null` from a
+ * note and `null` from a declared default are the same value and opposite
+ * facts (#329).
+ *
+ * So the position rides back beside the value, resolved **once**. The
+ * alternative is a builder that calls {@link resolveFieldValue} for the source
+ * and {@link readField} for the value, which resolves the position twice and
+ * states in two places the rule that a field is authored in exactly one.
+ *
+ * @param {FieldSpec} field - The declaration.
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} [options] - Options, as {@link readField} takes them.
+ * @param {string} [options.block="sohl"] - Which system's block to resolve
+ *   against.
+ * @param {(field: FieldSpec) => void} [options.onLegacyKey] - See
+ *   {@link readField}.
+ * @param {(field: FieldSpec) => void} [options.onRetiredTopLevel] - See
+ *   {@link readField}.
+ * @returns {{value: any, from: import("./system-block.mjs").FieldSource}} The
+ *   value to emit, and the position it was read from.
+ */
+export function readFieldEntry(field: FieldSpec, fm: object, { block, onLegacyKey, onRetiredTopLevel }?: {
+    block?: string | undefined;
+    onLegacyKey?: ((field: FieldSpec) => void) | undefined;
+    onRetiredTopLevel?: ((field: FieldSpec) => void) | undefined;
+}): {
+    value: any;
+    from: import("./system-block.mjs").FieldSource;
+};
+/**
+ * Whether a note supplied a value for a field, as opposed to a default doing it.
+ *
+ * The question {@link FieldSpec.omitWhenAbsent} turns on, asked of the
+ * *position* rather than of the value — which cannot answer it, since a
+ * declared `default: null` and an authored `null` are indistinguishable once
+ * the value is in hand (#329).
+ *
+ * `undefined` counts as absent whatever position reported it, because writing
+ * the key then emits a value `JSON.stringify` drops — the key present in the
+ * object and absent from the pack, which is the sort of disagreement this
+ * package exists to remove. It arrives from one place: the in-block step
+ * answers `value ?? field.default` for a key authored as `null`, so a field
+ * declaring no default resolves through "authored" to nothing at all. A field
+ * that also declares a `read` never reaches this, since its coercion has by
+ * then turned the `undefined` into whatever it makes of an absent value —
+ * ordinarily `null`, which is a value the note asked for and is emitted.
+ *
+ * @param {import("./system-block.mjs").FieldSource} from - Where
+ *   {@link resolveFieldValue} said the value came from.
+ * @param {any} value - The value it gave back.
+ * @returns {boolean} True when the note wrote one.
+ */
+export function isAuthored(from: import("./system-block.mjs").FieldSource, value: any): boolean;
 /**
  * Turn a field declaration into the builder it declares.
  *
@@ -55,11 +140,15 @@ export function readField(field: FieldSpec, fm: object, { block, onLegacyKey }?:
  * @param {(field: FieldSpec) => void} [options.onLegacyKey] - Passed through to
  *   {@link readField}: called with each field the note authored at the position
  *   it is being swept off (#305).
+ * @param {(field: FieldSpec) => void} [options.onRetiredTopLevel] - Passed
+ *   through to {@link readField}: called with each field the note authored at
+ *   the top-level key `data:` gathered it off (#332).
  * @returns {(fm: object) => object} A `system`-block builder.
  */
-export function buildFromFields(fields: readonly FieldSpec[], { block, onLegacyKey }?: {
+export function buildFromFields(fields: readonly FieldSpec[], { block, onLegacyKey, onRetiredTopLevel }?: {
     block?: string | undefined;
     onLegacyKey?: ((field: FieldSpec) => void) | undefined;
+    onRetiredTopLevel?: ((field: FieldSpec) => void) | undefined;
 }): (fm: object) => object;
 /**
  * The fields of a declaration an author actually writes.
@@ -73,6 +162,20 @@ export function buildFromFields(fields: readonly FieldSpec[], { block, onLegacyK
  * @returns {FieldSpec[]} Only the fields with a frontmatter `name`.
  */
 export function authoredFields(fields: readonly FieldSpec[]): FieldSpec[];
+/**
+ * The fields of a declaration a note may **never** write.
+ *
+ * The complement of {@link authoredFields} in the direction that matters: those
+ * are the fields an author may write, these are the ones authoring is an error
+ * (#330). Everything else in a declaration — a constant, a derived value — is
+ * simply not authored, which is a statement about the *builder* rather than
+ * about the author, and says nothing about what happens if a note writes the
+ * path anyway.
+ *
+ * @param {readonly FieldSpec[]} fields - The declaration.
+ * @returns {FieldSpec[]} Only the fields declaring `runtimeOnly`.
+ */
+export function runtimeOnlyFields(fields: readonly FieldSpec[]): FieldSpec[];
 /**
  * @typedef {object} FieldSpec
  * @property {string} to - Dotted path in the emitted `system` block — and,
@@ -135,6 +238,13 @@ export function authoredFields(fields: readonly FieldSpec[]): FieldSpec[];
  *   describe the *document* rather than the note: `<system>.system.<to>` and
  *   the legacy in-block `<system>.<name>`. Absent means the ordinary case —
  *   the top level is read, as the third step.
+ *
+ *   **It is read from the other side too**, because the statement is symmetric:
+ *   if the two positions hold unrelated quantities then the *in-block* position
+ *   is not the note-level field either, so a check about the note-level field
+ *   reads past it. `engine/frontmatter-lint.mjs` resolves that through
+ *   `collidingBlockKeys`. Read for the emitted field alone until #312, which is
+ *   how an affiliation's office style came to answer for its page heading.
  * @property {string} [shape] - Human-readable shape, for documentation. Comes
  *   paired with `read` from one of the coercion constants below.
  * @property {(raw: any, ctx: {fm: object, field: FieldSpec}) => any} [read] -
@@ -164,6 +274,78 @@ export function authoredFields(fields: readonly FieldSpec[]): FieldSpec[];
  *   note, so it declares none.
  * @property {any|((fm: object) => any)} [value] - For a field with no `name`:
  *   the constant, or a function deriving it from the frontmatter.
+ * @property {boolean} [omitWhenAbsent] - **The key is left out entirely when
+ *   the note does not carry the field** (#329), rather than written from a
+ *   declared default.
+ *
+ *   Every other field answers absence with a value: an unauthored `weight` is
+ *   `0`, an unauthored `seat` is `null`. That is right wherever the type has an
+ *   opinion about the empty case. It is wrong wherever the **DataModel** is the
+ *   one holding the answer — an affliction's `onsetDurationFormula` has no
+ *   compile-time value, and writing `null` over it does not merely fail to
+ *   help: it makes "the author said none" and "the author said nothing"
+ *   indistinguishable to every reader downstream, and it overwrites an
+ *   `initial` the system chose on purpose.
+ *
+ *   It is the other conditional row of the same table
+ *   {@link FieldSpec.runtimeOnly} completes, and the two differ only in what
+ *   they do about an *authored* value:
+ *
+ *   | declaration      | authored | absent |
+ *   | --- | --- | --- |
+ *   | ordinary         | emitted  | default written |
+ *   | `omitWhenAbsent` | emitted  | key omitted |
+ *   | `runtimeOnly`    | refused  | key omitted |
+ *
+ *   **A field declaring it must declare no `default`**, and the two are
+ *   contradictory rather than merely redundant — a default is a value for the
+ *   absent case, which is the case this says has none. Nor may it be combined
+ *   with `required` (which fails the build on absence, so nothing is ever
+ *   omitted) or with `runtimeOnly` (which is never emitted at all). The shipped
+ *   declarations are checked for all three in `tests/item-fields.test.ts`.
+ *
+ *   Unlike `runtimeOnly` this is a flag rather than a reason, because there is
+ *   only ever one reason and no message prints it: the DataModel's `initial`
+ *   stands. What an author needs to know is *that* the field has no default,
+ *   which the generated reference states in the field's own row.
+ * @property {string} [runtimeOnly] - **What the field holds once play has
+ *   started** — declared on a field the *document* writes for itself, which no
+ *   note may author (#330).
+ *
+ *   A schema declares plenty of fields a compiled document has no business
+ *   carrying: an affliction's `onsetDate` is the world time its onset fired
+ *   at, crystallized when the phase runs. World time does not exist while
+ *   content is compiled, so there is no authoring-time value — and `0` is
+ *   itself a valid world time, which is why such a field is nullable rather
+ *   than sentinelled and why a default cannot stand in for one.
+ *
+ *   Nothing used to stop a note writing one. The three checks that might have
+ *   each declined for its own correct reason —
+ *   {@link module:engine/system-block.unknownBlockKeys} reads the block's top
+ *   level and never descends into `system:`;
+ *   {@link module:engine/system-block.mergeSystemData} passes through every
+ *   authored path no declared field claims; and the schema check's fatal
+ *   direction is *undeclared*, which a field the schema really does declare
+ *   satisfies. What was missing was a rule saying "declared by the system,
+ *   but never authorable", and this is it.
+ *
+ *   Declaring it does two things, which are the two directions of one fact:
+ *
+ *   | declaration | authored | absent |
+ *   | --- | --- | --- |
+ *   | ordinary | emitted | default written |
+ *   | runtime-only | **refused** | key omitted |
+ *
+ *   The refusal is {@link module:engine/runtime-only-fields.assertNoRuntimeOnlyFields}'s;
+ *   the omission is {@link buildFromFields}'s. A runtime-only entry declares a
+ *   `to` and **no `name`**, so it stays out of {@link authoredFields} and every
+ *   author-facing surface built on it, while still giving `mergeSystemData` a
+ *   claimed path and the refusal something to name.
+ *
+ *   **The value is the reason**, as {@link FieldSpec.topLevelMeans}'s is: a
+ *   boolean would record the decision and lose the case for it, and the reason
+ *   is what the refusal's message and the generated reference both print. It
+ *   completes the sentence "it holds …".
  * @property {string} describe - One line, for the author-facing reference.
  */
 /** Whatever the author wrote, unconverted. */
@@ -290,6 +472,13 @@ export type FieldSpec = {
      * describe the *document* rather than the note: `<system>.system.<to>` and
      * the legacy in-block `<system>.<name>`. Absent means the ordinary case —
      * the top level is read, as the third step.
+     *
+     * **It is read from the other side too**, because the statement is symmetric:
+     * if the two positions hold unrelated quantities then the *in-block* position
+     * is not the note-level field either, so a check about the note-level field
+     * reads past it. `engine/frontmatter-lint.mjs` resolves that through
+     * `collidingBlockKeys`. Read for the emitted field alone until #312, which is
+     * how an affiliation's office style came to answer for its page heading.
      */
     topLevelMeans?: string | undefined;
     /**
@@ -348,11 +537,90 @@ export type FieldSpec = {
      * the constant, or a function deriving it from the frontmatter.
      */
     value?: any | ((fm: object) => any);
+    /**
+     * - **The key is left out entirely when
+     * the note does not carry the field** (#329), rather than written from a
+     * declared default.
+     *
+     * Every other field answers absence with a value: an unauthored `weight` is
+     * `0`, an unauthored `seat` is `null`. That is right wherever the type has an
+     * opinion about the empty case. It is wrong wherever the **DataModel** is the
+     * one holding the answer — an affliction's `onsetDurationFormula` has no
+     * compile-time value, and writing `null` over it does not merely fail to
+     * help: it makes "the author said none" and "the author said nothing"
+     * indistinguishable to every reader downstream, and it overwrites an
+     * `initial` the system chose on purpose.
+     *
+     * It is the other conditional row of the same table
+     * {@link FieldSpec.runtimeOnly} completes, and the two differ only in what
+     * they do about an *authored* value:
+     *
+     * | declaration      | authored | absent |
+     * | --- | --- | --- |
+     * | ordinary         | emitted  | default written |
+     * | `omitWhenAbsent` | emitted  | key omitted |
+     * | `runtimeOnly`    | refused  | key omitted |
+     *
+     * **A field declaring it must declare no `default`**, and the two are
+     * contradictory rather than merely redundant — a default is a value for the
+     * absent case, which is the case this says has none. Nor may it be combined
+     * with `required` (which fails the build on absence, so nothing is ever
+     * omitted) or with `runtimeOnly` (which is never emitted at all). The shipped
+     * declarations are checked for all three in `tests/item-fields.test.ts`.
+     *
+     * Unlike `runtimeOnly` this is a flag rather than a reason, because there is
+     * only ever one reason and no message prints it: the DataModel's `initial`
+     * stands. What an author needs to know is *that* the field has no default,
+     * which the generated reference states in the field's own row.
+     */
+    omitWhenAbsent?: boolean | undefined;
+    /**
+     * - **What the field holds once play has
+     * started** — declared on a field the *document* writes for itself, which no
+     * note may author (#330).
+     *
+     * A schema declares plenty of fields a compiled document has no business
+     * carrying: an affliction's `onsetDate` is the world time its onset fired
+     * at, crystallized when the phase runs. World time does not exist while
+     * content is compiled, so there is no authoring-time value — and `0` is
+     * itself a valid world time, which is why such a field is nullable rather
+     * than sentinelled and why a default cannot stand in for one.
+     *
+     * Nothing used to stop a note writing one. The three checks that might have
+     * each declined for its own correct reason —
+     * {@link module :engine/system-block.unknownBlockKeys} reads the block's top
+     * level and never descends into `system:`;
+     * {@link module :engine/system-block.mergeSystemData} passes through every
+     * authored path no declared field claims; and the schema check's fatal
+     * direction is *undeclared*, which a field the schema really does declare
+     * satisfies. What was missing was a rule saying "declared by the system,
+     * but never authorable", and this is it.
+     *
+     * Declaring it does two things, which are the two directions of one fact:
+     *
+     * | declaration | authored | absent |
+     * | --- | --- | --- |
+     * | ordinary | emitted | default written |
+     * | runtime-only | **refused** | key omitted |
+     *
+     * The refusal is {@link module :engine/runtime-only-fields.assertNoRuntimeOnlyFields}'s;
+     * the omission is {@link buildFromFields}'s. A runtime-only entry declares a
+     * `to` and **no `name`**, so it stays out of {@link authoredFields} and every
+     * author-facing surface built on it, while still giving `mergeSystemData` a
+     * claimed path and the refusal something to name.
+     *
+     * **The value is the reason**, as {@link FieldSpec.topLevelMeans}'s is: a
+     * boolean would record the decision and lose the case for it, and the reason
+     * is what the refusal's message and the generated reference both print. It
+     * completes the sentence "it holds …".
+     */
+    runtimeOnly?: string | undefined;
     /**
      * - One line, for the author-facing reference.
      */
     describe: string;
 };
 import { legacyKeyOf } from "./system-block.mjs";
+import { retiredTopLevelKey } from "./system-block.mjs";
 import { setPath } from "./system-block.mjs";
-export { legacyKeyOf, setPath };
+export { legacyKeyOf, retiredTopLevelKey, setPath };

package/types/engine/folder-notes.d.mts

@@ -18,6 +18,26 @@ export function bareAddress(value: string | null): string | null;
  * @returns {string} `<pkg>-none-folder-<shortcode>`.
  */
 export function folderAddress(pkg: string, shortcode: string): string;
+/**
+ * The Foundry `_id` a folder note's documents are filed under.
+ *
+ * **The one derivation, because two passes need the same answer.** The folder
+ * pass hashes it here on its way to emitting the `Folder` documents; the
+ * content index publishes it, through `noteDocId`, for a consumer who will
+ * never run this build. Deriving it twice is how the index came to publish a
+ * plausible-looking id that resolved to nothing — the general id rule hashes a
+ * note's address under the `document` namespace, and a folder's is hashed under
+ * {@link FOLDER_ID_NAMESPACE} (#310).
+ *
+ * An **authored `id` still wins**, and is applied by the caller: this is the
+ * derivation, not the resolution, so the pin rule stays stated once, where
+ * every other note type states it ({@link module:engine/note-ids.noteDocId}).
+ *
+ * @param {string} pkg - The content package.
+ * @param {string} shortcode - The folder's shortcode.
+ * @returns {string} The folder's 16-character Foundry id.
+ */
+export function folderDocId(pkg: string, shortcode: string): string;
 /**
  * Collect every folder note in a content tree.
  *

package/types/engine/foundry-entries.d.mts

@@ -29,6 +29,12 @@ export function anchorsOf(entryUuid: string, entryId: string, body: string, name
  * @param {string} name - The note's display name.
  * @param {string} address - The note's package-relative address.
  * @param {string} body - The note's markdown body.
+ * **Each entry carries the `id` of the document it addresses**, not only its
+ * UUID. The two are one fact — a UUID ends in the id — but only the entry knows
+ * which derivation produced it: an item's is its note's `fm.id`, and its
+ * documentation journal's is {@link itemDocEntryId} of that. Stating it here is
+ * what lets the content index publish an identity it did not re-derive (#310).
+ *
  * @param {object} ctx - Resolved identities: `{ contentPackage,
  *   foundryPackageId, packRouter }`.
  * @returns {Array<object>} One or two entries, in {@link buildManifest}'s shape.

package/types/engine/frontmatter-lint.d.mts

@@ -26,6 +26,12 @@ export function matchesKind(value: unknown, kind: string): boolean;
  *   note against whatever its type declares and knows no type names of its
  *   own. Its absence skips the `data:` and `subType` checks rather than
  *   reporting every key as unknown.
+ * @param {(type: string) => {document: string|null, art: readonly string[]}|null} [opts.emittedArt]
+ *   What art a note of one type reaches its document through — the passes' own
+ *   declaration, asked through `engine/generate.mjs`'s `emittedArtFor`.
+ *   Supplied by the caller like `schemas`, so this module states no list of
+ *   iconless types of its own; absent it, an inert `img:` goes unreported
+ *   rather than every note's being (#349).
  * @param {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>} [opts.systems]
  *   The system blocks to check, and what each accepts. See
  *   {@link DEFAULT_SYSTEM_BLOCKS}.
@@ -35,10 +41,14 @@ export function matchesKind(value: unknown, kind: string): boolean;
  *   about those keys.
  * @returns {object[]} Findings, each with a locator where one is obtainable.
  */
-export function lintNote(note: object, { schemas, index, vocabulary, packs, systems }: {
+export function lintNote(note: object, { schemas, index, vocabulary, packs, emittedArt, systems }: {
     schemas: Record<string, readonly object[]>;
     index?: object | undefined;
     vocabulary?: Record<string, object> | undefined;
+    emittedArt?: ((type: string) => {
+        document: string | null;
+        art: readonly string[];
+    } | null) | undefined;
     systems?: Readonly<Record<string, {
         known?: readonly string[];
         fieldVocabulary?: boolean;
@@ -58,10 +68,12 @@ export function lintNote(note: object, { schemas, index, vocabulary, packs, syst
  *   The system blocks to check. See {@link DEFAULT_SYSTEM_BLOCKS}.
  * @param {readonly string[]} [opts.packs] - The declared pack names; see
  *   {@link lintNote}.
+ * @param {(type: string) => {document: string|null, art: readonly string[]}|null} [opts.emittedArt]
+ *   What art a type reaches its document through; see {@link lintNote}.
  * @returns {{findings: object[], notes: number}} The findings, and how many
  *   notes were inspected.
  */
-export function lintFrontmatter(index: object, { schemas, vocabulary, packs, references, systems }: {
+export function lintFrontmatter(index: object, { schemas, vocabulary, packs, emittedArt, references, systems }: {
     schemas: Record<string, readonly object[]>;
     vocabulary?: Record<string, object> | undefined;
     references?: boolean | undefined;
@@ -70,6 +82,10 @@ export function lintFrontmatter(index: object, { schemas, vocabulary, packs, ref
         fieldVocabulary?: boolean;
     }>> | undefined;
     packs?: readonly string[] | undefined;
+    emittedArt?: ((type: string) => {
+        document: string | null;
+        art: readonly string[];
+    } | null) | undefined;
 }): {
     findings: object[];
     notes: number;

package/types/engine/frontmatter.d.mts

@@ -132,13 +132,15 @@ export function parseValueDesc(raw: any): {
     maxValue: number;
 }[];
 /**
- * The compendium folder a note names, and how it named it.
+ * The compendium folder a note names.
  *
- * Two spellings, deliberately not merged into one value: `packFolder:` is a
- * folder note's **address** (`folder-poisonsandtoxins`) and `folder:` is a
- * Foundry **id** (`ONXsqZAIZr2qzxTb`). Which one a value is cannot be told from
- * the string — both are alphanumeric — so the field it was written in is what
- * says, and that answer is carried rather than re-derived (#251).
+ * **There is one spelling.** `packFolder:` is a folder note's **address**
+ * (`folder-poisonsandtoxins`), resolved through the address index the whole
+ * build shares. The `folder:` Foundry-id spelling this function once read
+ * beside it, and the per-pack `*-folders.yaml` that id was resolved against,
+ * are retired together (#260) — a note declaring `folder:` is refused by
+ * {@link module:engine/folder-notes.assertNoDeclaredFolder} rather than
+ * reaching here, so there is no second source for a value to come from.
  *
  * **`packFolder` was a path for one release** (`Possessions/Misc_Gear/Cooking`)
  * and is an address now (#255). A path encoded the hierarchy *in the value*, so
@@ -149,13 +151,11 @@ export function parseValueDesc(raw: any): {
  * authors to migrate, which is the whole reason the change was cheap enough to
  * make.
  *
- * `packFolder` wins where both are present. Nothing about `folder` changes: a
- * note that names one is read, resolved and emitted exactly as before, until
- * #260 retires it.
- *
  * @param {object|null|undefined} fm - Parsed frontmatter.
  * @returns {{value: string|null, isAddress: boolean}} The authored value, and
- *   whether it is a folder note's address.
+ *   whether it is a folder note's address. `isAddress` is always `true` and is
+ *   kept so a caller reads the same shape it always did; it distinguished the
+ *   two spellings, and there is only one left to be.
  */
 export function folderField(fm: object | null | undefined): {
     value: string | null;

package/types/engine/generate.d.mts

@@ -8,6 +8,33 @@
  *   rather than defaulting past.
  */
 export function compilerFor(docType: string, system?: string | null): Function | undefined;
+/**
+ * The art fields a note of one content type reaches its document through, and
+ * the document it reaches (#349).
+ *
+ * **Derived, never listed.** A note's type routes to a document type
+ * ({@link packForType}), a document type routes to the pass that compiles it
+ * ({@link compilerFor}), and the pass declares which art it emits
+ * ({@link BasePackCompiler.emitsArt}). So the answer is assembled from the same
+ * three statements the compile itself follows, and a pass that starts or stops
+ * emitting art changes this by changing its own declaration. A second table of
+ * "types with no image" would be a table free to drift from what is emitted,
+ * which is the defect this exists to report rather than to reproduce.
+ *
+ * **The union across systems**, because a note is compiled by whichever pack
+ * claims it: a tree feeding both SoHL and HM3 has two Actor passes, and a field
+ * either of them emits is live for the note. Only a field *no* pass emits is
+ * inert, and that is the finding this supports.
+ *
+ * @param {string} type - The note's content type.
+ * @returns {{document: string|null, art: readonly string[]}|null} What the type
+ *   compiles into and the art it carries there, or `null` where no claim can be
+ *   made — a retired type, which is reported as retired instead.
+ */
+export function emittedArtFor(type: string): {
+    document: string | null;
+    art: readonly string[];
+} | null;
 /**
  * The generated JSON of **every** configured Item pack — what the actors pass
  * reads its predefined items from.

package/types/engine/helpers.d.mts

@@ -169,19 +169,47 @@ export function systemTemplatePriority(fm: object, label: string): number | null
  * alphanumeric runs replaced by underscores.
  */
 export function makeFilename(name: any, id: any): string;
-/**
- * Standardize a name into a slug: lowercase, apostrophes removed,
- * non-alphanumerics collapsed to single hyphens.
- */
 /**
  * Translate a content-relative image path into its Foundry-relative form.
  *
  * Content frontmatter (`img` / `portrait`) authors a single path that has to
- * work for Foundry, the knowledgebase, and the website. For Foundry the bundled
- * asset roots — `icons/...` and `images/...` — are served from the package
- * directory, so they are rewritten to `<assetRoot>/<path>` — `systems/sohl/assets`
- * for this repository, `modules/<id>/assets` for a module (#1508). Any other
- * path (already package-rooted, an absolute URL) is returned unchanged.
+ * work for Foundry, the knowledgebase, and the website. **Its first segment
+ * says which package owns the file** (#331), and there are exactly three
+ * answers:
+ *
+ * | Authored path starts with | Owner                 | Emitted              |
+ * | ------------------------- | --------------------- | -------------------- |
+ * | `systems/`                | a separate **system** | unchanged            |
+ * | `modules/`                | a separate **module** | unchanged            |
+ * | anything else             | **this package**      | `<assetRoot>/<path>` |
+ *
+ * So `icons/relic.svg` compiles to `systems/sohl/assets/icons/relic.svg` here
+ * and to `modules/sohl-thalorna/assets/icons/relic.svg` in a module — the asset
+ * root is derived from the configuration, and is the one place `systems/sohl`
+ * is ever spelled (#1508). An authored
+ * `systems/sohl/assets/icons/noun/shield.svg` is left exactly as written,
+ * whichever package is compiling it.
+ *
+ * **This is a rule about ownership, not an allowlist of directories.** It used
+ * to prefix `icons/…` and `images/…` and pass everything else through — the
+ * same answer for every path any tree authors today, and the wrong one for the
+ * next directory a package ships. `sohl-kethira-basic` keeps art under
+ * `assets/artwork/`, so an authored `artwork/deity.webp` would have shipped
+ * unprefixed: a 404 in Foundry, reported by nothing. That a package owns its
+ * own tree is the fact; the directory names inside it are that package's
+ * business (#331).
+ *
+ * **Off-install addresses pass through too**, which is the same rule rather
+ * than a fourth: a URL, a `data:` URI, or a `/`-rooted path names something no
+ * package owns. See {@link addressesAnotherPackage}.
+ *
+ * **`banner:` does not follow this rule, deliberately (#331).** It is not an
+ * asset path inside a Foundry install at all: it reaches no compiled document,
+ * and its only consumer is the Hugo theme, which prefixes a relative value with
+ * `images/` and joins it onto `params.cdnBaseURL`. The two fields look alike
+ * and address different places — `img:` a file Foundry serves, `banner:` a file
+ * the CDN serves — so they are documented apart rather than reconciled into one
+ * rule that would be true of neither.
  *
  * **Two empties, and they mean opposite things (#218).** `null` — or an absent
  * key, which reaches here as `undefined` — means _unset_: the note names no art