@heroiclands/package-build 23.1.0 → 23.2.0

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

@@ -298,14 +298,14 @@ export class BasePackCompiler {
      * A refusal only this pass can make, because its subject is the note's
      * **type**.
      *
-     * 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
+     * The `assertNoDeclaredPackage` check above it in the walk is type-agnostic
+     * by construction: it runs before `selects`, so that a note declaring
+     * `package:` 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
+     * throw is counted and located exactly as that check'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
@@ -404,12 +404,10 @@ export class BasePackCompiler {
     /**
      * The Foundry path one authored art address names, or `null`.
      *
-     * **The two empties survive.** `null` and an absent key mean *no art named*,
-     * so the caller's own default applies with nullish coalescing; `""` means
-     * *ship blank on purpose* and no default may replace it. That is
-     * {@link module:engine/helpers.resolveImg}'s rule, reached through it rather
-     * than restated, which is also what puts an art address and a body image
-     * through one ownership rule.
+     * `null` and an absent key mean *no art named*, so the caller's own default
+     * applies with nullish coalescing. The address goes through
+     * {@link module:engine/helpers.resolveImg}, which puts an art address and a
+     * body image through one ownership rule.
      *
      * An address nothing answers is reported against the note and treated as
      * unnamed, so the document takes its default rather than shipping a path
@@ -421,8 +419,8 @@ export class BasePackCompiler {
      * @param {string} key - The key it was authored at, for the message.
      * @param {string} type - The asset type a bare value takes.
      * @param {Iterable<string>} [accepts] - The types this slot accepts.
-     * @returns {string|null} The Foundry-relative path, `""` for a deliberate
-     *   blank, or `null` where the note names none.
+     * @returns {string|null} The Foundry-relative path, or `null` where the
+     *   note names none.
      */
     artPathOf(value: unknown, key: string, type: string, accepts?: Iterable<string>): string | null;
     /**
@@ -636,8 +634,8 @@ export class BasePackCompiler {
  * The tallies one pass accumulates while walking the tree.
  *
  * `declined` and `skippedOther` are deliberately separate numbers. A declined
- * note is one this build **refused** — it declares a retired frontmatter field
- * — and it is an error; a skipped one legitimately belongs to another pass, and
+ * note is one this build **refused** — it declares `package:` — and it is an
+ * error; a skipped one legitimately belongs to another pass, and
  * there are thousands of those. Folding the first into the second is what let a
  * whole tree be filtered out in silence.
  */
@@ -655,9 +653,9 @@ export type PassStats = {
      */
     skippedOther: number;
     /**
-     * - Notes this pack **refused** — one declaring a
-     * retired frontmatter field, or one routed to a system pack whose system it
-     * says nothing about. Counted as errors, never as skips.
+     * - Notes this pack **refused** — one declaring
+     * `package:`, or one routed to a system pack whose system it says nothing
+     * about. Counted as errors, never as skips.
      */
     declined: number;
 };

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

@@ -49,12 +49,10 @@ export function addressSlug(fm: object): string;
  * docs, neither of which contains a hyphen or names a type.
  *
  * **It is a pure function of the frontmatter**, and takes no options. Nothing
- * about the file the note was read from reaches it: the `README.md` convention
- * that made one note address a whole section is retired with the section itself,
- * so every note is addressed alike and there is one rule and no branch.
- * It takes no address scheme; the `landing` rule it once validated is
- * discarded; with that key retired, `prefix` was the only thing left in the
- * scheme and the paragraph above is the reason it never applied.
+ * about the file the note was read from reaches it, so every note is addressed
+ * alike and there is one rule and no branch. It takes no address scheme:
+ * `prefix` is the whole scheme and the paragraph above is the reason it never
+ * applies here.
  *
  * @param {object} fm - Parsed frontmatter.
  * @returns {string} The package-relative address, with a trailing slash and no
@@ -124,13 +122,12 @@ export function resolvePackageUrl(rel: string, base: string): string;
  * The Foundry `_id` of the document a note compiles into, derived from its
  * canonical address.
  *
- * A note used to author this — an opaque 16-character string, one per note,
- * that said nothing its address did not and that no check guaranteed. The
- * address is the identity that *is* guaranteed: `content-lint` refuses a
+ * An authored id would be an opaque string that says nothing its address
+ * does not and that no check guarantees. The address is the identity that
+ * *is* guaranteed: `content-lint` refuses a
  * duplicate `(type, shortcode)` across every pack of a document type, which is
  * exactly the scope a primary document's id must be unique within. So the
- * derived id inherits a guard that already exists, where the authored one had
- * none.
+ * derived id inherits that guard.
  *
  * **The coupling this creates, stated plainly.** The address carries the
  * shortcode, so renaming a shortcode moves the document's id — where an
@@ -139,7 +136,7 @@ export function resolvePackageUrl(rel: string, base: string): string;
  * note, so it is a breaking change either way; and a note that must keep its
  * identity across a rename pins an `id`, which is what the pin is for. One
  * thing genuinely degrades — `engine/address-diff.mjs` tells a rename from a
- * withdrawal by matching document ids, and can no longer do so for a note that
+ * withdrawal by matching document ids, and cannot do so for a note that
  * authors none. Its module note records that.
  *
  * @param {string} pkg - The owning **content** package.

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

@@ -35,8 +35,8 @@ export function embedsIn(body: string, context: any): ParsedEmbed[];
  * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex},
  *   or the equivalent the site and the book build.
  * @param {ParsedEmbed} embed - The embed.
- * @returns {{pathname: string}|{reason: string, target: string, type?: string}}
- *   The authored pathname the picture is at, or the finding.
+ * @returns {{pathname: string}|{reason: string, target: string, type?: string,
+ *   shortcode?: string, declared?: string}} The authored pathname the picture is at, or the finding.
  */
 export function resolveEmbed(index: object, embed: ParsedEmbed): {
     pathname: string;
@@ -44,6 +44,8 @@ export function resolveEmbed(index: object, embed: ParsedEmbed): {
     reason: string;
     target: string;
     type?: string;
+    shortcode?: string;
+    declared?: string;
 };
 /**
  * The role an address's asset declares, read through the same resolution an

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

@@ -56,55 +56,6 @@ export function checkSchemaTargets({ format, schemas }: {
     checked: number;
     unchecked: Record<string, number>;
 };
-/**
- * The systems the specification names.
- *
- * Taken from the columns of its mapping tables rather than from a list written
- * here, so a system added to the document is measured with no code change.
- * Cached per parsed document, since the answer is the same for every note.
- *
- * @param {import("./content-format.mjs").ContentFormat} format - The parsed
- *   specification.
- * @returns {ReadonlySet<string>} The system ids.
- */
-export function systemsNamed(format: import("./content-format.mjs").ContentFormat): ReadonlySet<string>;
-/**
- * Measure one note against the vocabulary the format declares for its type.
- *
- * @param {object} note - `{file, raw, fm}` — as the link index hands one over.
- * @param {import("./content-format.mjs").ContentFormat} format - The parsed
- *   specification.
- * @param {object} [opts]
- * @param {"warning"|"error"} [opts.severity="warning"] - What the findings are.
- *   A report by default; `--strict` raises it.
- * @returns {object[]} Findings, each carrying the `class` it belongs to
- *   alongside the fields `emitDiagnostic` reads.
- */
-export function measureNote(note: object, format: import("./content-format.mjs").ContentFormat, { severity }?: {
-    severity?: "error" | "warning" | undefined;
-}): object[];
-/**
- * Measure a corpus, and count what it finds by class.
- *
- * The counts are the point as much as the findings: a class is promoted to
- * fatal when its count reaches zero, so a run that prints them is the
- * migration's progress bar.
- *
- * @param {Iterable<object>} notes - `{file, raw, fm}` for each authored note.
- * @param {import("./content-format.mjs").ContentFormat} format - The parsed
- *   specification.
- * @param {object} [opts]
- * @param {boolean} [opts.strict=false] - Report the findings as errors rather
- *   than warnings. Turned on one slice at a time.
- * @returns {{findings: object[], notes: number, byClass: Record<string, number>}}
- */
-export function measureCorpus(notes: Iterable<object>, format: import("./content-format.mjs").ContentFormat, { strict }?: {
-    strict?: boolean | undefined;
-}): {
-    findings: object[];
-    notes: number;
-    byClass: Record<string, number>;
-};
 /**
  * What an author is told when the specification and the declaration disagree.
  *
@@ -177,21 +128,6 @@ export function checkDeclaredFields({ format, itemFields, system, severity }: {
     };
     fields: number;
 };
-/**
- * Top-level keys the format names as the note's own, whatever its type.
- *
- * The top-level vocabulary itself, read rather than restated: this set exists
- * to keep a note's own identity fields from being mistaken for a misplaced
- * `data` property where the two share a name, and the keys that are a note's
- * own are exactly the ones the region declares. `type` and `subType` are the
- * pair that matters — several mapping tables name `subType` as a shared source,
- * and it is authored at top level by design. A key the region does *not*
- * declare, such as `id` beside `data.id`, is reported as the misplaced `data`
- * property it is.
- *
- * @type {ReadonlySet<string>}
- */
-export const NOTE_LEVEL_KEYS: ReadonlySet<string>;
 /**
  * Where one declared field sends one authored value.
  */

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

@@ -143,6 +143,62 @@ export function indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absP
     dateContext: any;
     resolveRole: any;
 }): object[];
+/**
+ * Write each note's resolved culture into its record, as `data.culture`.
+ *
+ * A note's culture is:
+ *
+ * - its own `data.culture`, when it states one;
+ * - for a `lore` note of `subType: culture`, its own canonical Address;
+ * - for a `place` or an `affiliation`, else the resolved cultures of its
+ *   `data.parents`;
+ * - for a `polity` affiliation, else the resolved cultures of its places: its
+ *   `data.seat` pooled with every place whose `data.government` names it, as
+ *   one set;
+ * - else nothing. A `being`, a `doc` and any other `lore` note have their own
+ *   value only; every other type has none.
+ *
+ * A parent's culture is its own resolved culture, found recursively; a parent
+ * resolving to nothing is ignored, as is one in another package that its index
+ * gives none. Sources that agree give that culture. Sources that differ, on a
+ * note with no value of its own, give it none and one error finding, at
+ * `data.parents`, or for a polity's places at `data.seat`, else at its `data:`
+ * line. A note whose parent raised that error treats the parent as resolving to
+ * nothing, so a disagreement is reported once, where it is. A cycle resolves to
+ * nothing.
+ *
+ * A parent in another package is read through `foreignRecord`, whose published
+ * entry already carries that parent's resolved culture, so a foreign chain is
+ * never walked.
+ *
+ * The record's `data` is replaced by a copy carrying the culture, never
+ * assigned into, because the note's parsed frontmatter shares that object. The
+ * record then carries the resolved culture to every pass that reads it — lint,
+ * compile and site alike. A note resolving to nothing gains no `culture` key.
+ *
+ * @param {Array<Record<string, any>>} records - Index records, every Address a
+ *   tuple. Records that are not notes are passed over.
+ * @param {object} options - Options.
+ * @param {string} options.contentPackage - The package the records belong to.
+ * @param {string} [options.contentBase] - The content tree, for opening a
+ *   conflicting note to locate the finding. Without it a finding names the
+ *   note's path within the tree and no position.
+ * @param {(key: string) => ({culture?: unknown}|undefined)} [options.foreignRecord] -
+ *   Another package's entry for a canonical address. Asked only for an
+ *   immediate parent whose package is not this one.
+ * @param {object[]} [options.problems] - Receives each conflict as a finding.
+ *   Omitted, every conflict is collected and one Error lists them all.
+ * @returns {Array<Record<string, any>>} The same records.
+ * @throws {Error} When `problems` is omitted and any note's sources disagree.
+ */
+export function resolveCultures(records: Array<Record<string, any>>, { contentPackage, contentBase, foreignRecord, problems }: {
+    contentPackage: string;
+    contentBase?: string | undefined;
+    foreignRecord?: ((key: string) => ({
+        culture?: unknown;
+    } | undefined)) | undefined;
+    problems?: object[] | undefined;
+}): Array<Record<string, any>>;
 /**
  * Read a content tree into index records, in the order they will be written.
  *
@@ -171,17 +227,32 @@ export function indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absP
  * @param {object[]} [options.problems] - Supplied by a **reader**: a note that
  *   cannot be recorded is pushed here as a diagnostic and skipped. Omitted, the
  *   note throws — the contract the emitter needs, since an index missing a note
- *   asserts that it does not exist.
+ *   asserts that it does not exist. The same holds for a culture conflict: a
+ *   reader receives each as a finding, and the emitter throws once, listing
+ *   every one.
+ * @param {(key: string) => ({culture?: unknown}|undefined)} [options.foreignRecord] -
+ *   Another package's entry for a canonical address, read for a parent that
+ *   package publishes; see {@link resolveCultures}.
+ * @param {Map<string, {body: string, frontmatter: object|null}>} [options.parsed] -
+ *   Filled with each note's body and its frontmatter as authored, keyed by the
+ *   note's file, so a later pass reads the notes this walk already parsed.
  * @returns {Array<Record<string, any>>} The records, in a total order that does
  *   not depend on directory-read order.
  */
-export function collectContentIndex(contentBase: string, { contentPackage, skipDirectories, assetsBase, manifest, problems, addressContext }: {
+export function collectContentIndex(contentBase: string, { contentPackage, skipDirectories, assetsBase, manifest, problems, addressContext, foreignRecord, parsed, }: {
     contentPackage: string;
     skipDirectories: readonly string[];
     assetsBase?: string | undefined;
     manifest?: object | undefined;
     addressContext?: object | undefined;
     problems?: object[] | undefined;
+    foreignRecord?: ((key: string) => ({
+        culture?: unknown;
+    } | undefined)) | undefined;
+    parsed?: Map<string, {
+        body: string;
+        frontmatter: object | null;
+    }> | undefined;
 }): Array<Record<string, any>>;
 /**
  * Serialize records as JSON Lines.
@@ -218,14 +289,22 @@ export function serializeContentIndex(records: Array<Record<string, any>>): stri
  *   aborting the derivation. Omitted, the note throws — which is the contract
  *   the emitter needs, since an index missing a note asserts that it does not
  *   exist.
+ * @param {Map<string, {body: string, frontmatter: object|null}>} [opts.parsed] -
+ *   Filled with each note's body and authored frontmatter, keyed by the note's
+ *   file. Handed to {@link module:engine/sql-tables.prepareTreeSqlTables}, it
+ *   spares that pass reading and parsing every note again.
  * @returns {object[]} One record per note, plus one per documentation entry.
  */
-export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectories, problems, }?: {
+export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectories, problems, parsed, }?: {
     contentBase?: string | undefined;
     assetsBase?: string | undefined;
     config?: object | undefined;
     skipDirectories?: readonly string[] | undefined;
     problems?: object[] | undefined;
+    parsed?: Map<string, {
+        body: string;
+        frontmatter: object | null;
+    }> | undefined;
 }): object[];
 /**
  * Emit this package's content index.

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

@@ -21,8 +21,8 @@ export function anchorsOf(body: string): Set<string>;
  * Read a content tree into the index a link resolves against.
  *
  * **The corpus comes from the content index, not from a walk of this module's
- * own**. Every pass used to answer "which files are the content?" for
- * itself and throw the answer away; this one now reads
+ * own**. Passes do not each answer "which files are the content?" for
+ * themselves; this one reads
  * {@link module:engine/content-index.indexRecordsFor}, which is the same
  * derivation the published artifact and the compilers are driven from. So a
  * note the index records is a note the link check sees, and the addresses and
@@ -81,8 +81,6 @@ export function buildLinkIndex(contentBase: string, { config, skipDirectories, s
  * **What is checkable, stated plainly.** Only an address into this site is, and
  * only against facts this build already holds:
  *
- * - A **retired content type** in the path. The engine knows the retired names
- *   and what replaced it, so this is a fact rather than a guess.
  * - A **hardcoded absolute URL** into this package's own prefix, or into one a
  *   fetched index names. Every one of them has a better form to write, which
  *   is why every one is reported — including a bare `/<package>/`, which names

package/types/engine/culture-choice.d.mts

@@ -1,14 +1,57 @@
 /**
- * Require a being's primary culture to address a culture lore note.
+ * Whether a `data.culture` value names the note that carries it.
+ *
+ * The comparison is between canonical Addresses, so a culture note's shortcode,
+ * any longer form of its Address and a decoded tuple all name it alike. A note
+ * with no shortcode has no Address to compare against and names nothing.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {unknown} value - The `data.culture` value, as written or decoded.
+ * @param {object} [index] - The package and vocabularies a written value is
+ *   read against, and the package the note's own Address is in.
+ * @returns {boolean} Whether the value is the note's own Address.
+ */
+export function cultureNamesItself(fm: object, value: unknown, index?: object): boolean;
+/**
+ * Require a note's `data.culture` to address a culture lore note.
+ *
+ * A value that is not a `lore` Address, or names nothing, is left to the
+ * reference check, which reports it in its own terms. A culture note's own
+ * value is {@link checkCultureSubType}'s to judge, since it names only the note
+ * itself.
+ *
  * @param {object} note
  * @param {{index?: object}} [options]
+ * @returns {object[]} One error at the value when it names lore of another subType.
  */
 export function checkCultureChoice(note: object, { index }?: {
     index?: object;
-}): {
-    severity: string;
-    message: string;
-    line?: number;
-    column?: number;
-    file: any;
-}[];
+}): object[];
+/**
+ * Scope `data.culture` to the subtypes that take it.
+ *
+ * A `doc` of `subType: settingguide` introduces one culture's setting and must
+ * name it; a missing value is an error at the `subType:` line. Every other `doc`
+ * subType refuses a written value, as an error at the key.
+ *
+ * A `lore` note of `subType: culture` is itself the culture. It may omit the
+ * field or name itself, in any form the Address parser reads; a value naming any
+ * other Address is an error at the value. A note with no shortcode has no
+ * Address to compare against, and the shortcode check reports it.
+ *
+ * @param {object} note - The note, as the link index hands it over.
+ * @param {{index?: object}} [options] - The link index, for the package and
+ *   vocabularies a written value is read against.
+ * @returns {object[]} Findings.
+ */
+export function checkCultureSubType(note: object, { index }?: {
+    index?: object;
+}): object[];
+/**
+ * The `data.culture` field, declared once and spread into each type that takes
+ * it. A type gives its own `describe` where the field means something narrower
+ * there.
+ *
+ * @type {Readonly<object>}
+ */
+export const CULTURE_FIELD: Readonly<object>;

package/types/engine/data-keys.d.mts

@@ -5,7 +5,7 @@
  * @property {string} name - The key as an author writes it.
  * @property {string} [kind] - Its value's shape: `string`, `date`, `number`,
  *   `integer`, `boolean`, `address`, `list`, `map`, `scalar-or-map`,
- *   `list-or-map` or `string-or-list` — see {@link fitsKind}. Absent, the check
+ *   or `string-or-list` — see {@link fitsKind}. Absent, the check
  *   makes no claim about the value.
  * @property {readonly string[]} [allowed] - The closed set a present value is
  *   one of, where the key takes a fixed word.
@@ -94,7 +94,7 @@ export type InnerKeySpec = {
     /**
      * - Its value's shape: `string`, `date`, `number`,
      * `integer`, `boolean`, `address`, `list`, `map`, `scalar-or-map`,
-     * `list-or-map` or `string-or-list` — see {@link fitsKind}. Absent, the check
+     * or `string-or-list` — see {@link fitsKind}. Absent, the check
      * makes no claim about the value.
      */
     kind?: string | undefined;

package/types/engine/derived-fields.d.mts

@@ -20,8 +20,7 @@ export function derivedMessage(key: string, from: string, file?: string): string
 /**
  * The derived keys a note actually writes, in declaration order.
  *
- * **Presence is the whole test**, as it is for a retired or a runtime-only
- * field: an authored empty string is as much a claim on the key as prose is,
+ * **Presence is the whole test**, as it is for a runtime-only field: an authored empty string is as much a claim on the key as prose is,
  * and it is the same 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.

package/types/engine/diagnostics.d.mts

@@ -114,10 +114,8 @@ export function positionInBody(body: string, offset: number, { bodyLine, bodyCol
  * The key match tolerates leading whitespace by default, so a nested key of the
  * same name answers when no top-level one is present — which is usually what a
  * reader wants, the key being unique in nearly every note. Pass `topLevel` where
- * it is not: `aliases` is both a retired top-level field and a **permitted**
- * `name.aliases`, and a finding about the first must never open on the
- * second, which would tell an author to delete a field they are allowed to
- * write.
+ * it is not: a finding about a top-level key must never open on a nested key
+ * of the same name.
  *
  * @param {string} raw - The file's full contents, frontmatter included.
  * @param {string} key - The top-level frontmatter key.
@@ -137,6 +135,31 @@ export function positionInFrontmatter(raw: string, key: string, value?: string,
     line?: number;
     column?: number;
 };
+/**
+ * A frontmatter key's position in a note's file, or nothing.
+ *
+ * {@link positionInFrontmatter} answers the same question from the file's
+ * *text*; this reads the file to ask it.
+ *
+ * @param {string|undefined} absPath - The note's file.
+ * @param {string} key - The frontmatter key.
+ * @param {string} [value] - When given, prefer the occurrence whose line also
+ *   carries this text — so a finding about one entry of a block opens on that
+ *   entry rather than on the key that introduces it.
+ * @param {object} [options] - Options, forwarded to
+ *   {@link positionInFrontmatter}.
+ * @param {boolean} [options.topLevel=false] - Require the key at column 1, so
+ *   an identically named nested key cannot answer for it.
+ * @returns {{line?: number, column?: number}|undefined} Spreadable position
+ *   fields, dropped rather than guessed when the file cannot be read or the key
+ *   cannot be found — as `formatDiagnostic` requires.
+ */
+export function locateFrontmatterKey(absPath: string | undefined, key: string, value?: string, { topLevel }?: {
+    topLevel?: boolean | undefined;
+}): {
+    line?: number;
+    column?: number;
+} | undefined;
 /**
  * Where a literal sits in a text, so a finding about it can be opened.
  *

package/types/engine/document-subtypes.d.mts

@@ -53,12 +53,9 @@ export function defineDocumentSubtypes({ system, block, types }?: {
 /**
  * The row a system declares for a note type, or nothing.
  *
- * The **one** place a map is indexed, so the retirement window for a renamed
- * type is honoured everywhere a row is asked for — {@link documentSubtype},
- * {@link mapsNoteType}, {@link noteTypesFor}'s consumers and
- * {@link systemOf} all arrive here. A note still spelling `armorgear` finds the
- * `armor` row, compiles into the `armorgear` document it always did, and keeps
- * the address it publishes at; only the *report* tells it to move.
+ * The **one** place a map is indexed — {@link documentSubtype},
+ * {@link mapsNoteType}, {@link noteTypesFor}'s consumers and {@link systemOf}
+ * all arrive here.
  *
  * @param {DocumentSubtypeMap} map - The system's map.
  * @param {string|undefined} noteType - The note's declared `type`.
@@ -114,18 +111,6 @@ export function documentSubtype(map: DocumentSubtypeMap, noteType: string | unde
     file?: string | undefined;
     absPath?: string | undefined;
 }): string | undefined;
-/**
- * The answer {@link referencedSubtype} gives: a subtype, or why there is none.
- *
- * Exactly one of the two fields is set. A `problem` is a sentence a caller
- * prefixes with its own context and emits as a finding — it never throws,
- * because the caller resolving a reference is walking a list and has to report
- * this one and carry on.
- *
- * @typedef {object} ReferencedSubtype
- * @property {string} [subType] - The document subtype the reference addresses.
- * @property {string} [problem] - Why the reference names no document subtype.
- */
 /**
  * The document subtype a `(type, shortcode)` **reference** addresses.
  *
@@ -165,26 +150,22 @@ export function documentSubtype(map: DocumentSubtypeMap, noteType: string | unde
  *   only the row has no block to read a discriminator from, so nothing here
  *   can choose, and choosing anyway would be right about half the time.
  *
- * A **retired** spelling is refused by name before any of that. Without it a
- * reference left behind by a merge would take the unmapped fallback and address
- * a document of the old name — resolving silently, which is precisely what a
- * retirement exists to stop.
- *
- * A **renamed** spelling is the opposite case and resolves normally, through
- * the same {@link currentType} every other lookup goes through. It has to
- * be this side as much as the note's own `type:`: the overwhelming majority of
- * the 31,000 occurrences of the old names are `(type, shortcode)` references
- * inside a being's `items:` list, so a window that resolved notes but not
- * references would silently drop 30,000 embedded items rather than compile them
- * unchanged.
+ * A type that no row names, that no row produces as a subtype and that the
+ * consumer does not declare is refused: stamping the authored spelling on it
+ * would address a document that cannot exist.
  *
  * @param {DocumentSubtypeMap} map - The system's map.
  * @param {string|undefined} noteType - The type the reference names.
  * @param {string} document - The Foundry document class the reference must
  *   address — `"Item"` for a being's embedded items.
+ * @param {object} [options] - Options.
+ * @param {ReadonlySet<string>} [options.declared] - The item types the
+ *   consuming repository declares itself, which the map does not name.
  * @returns {ReferencedSubtype} The subtype, or why there is none.
  */
-export function referencedSubtype(map: DocumentSubtypeMap, noteType: string | undefined, document: string): ReferencedSubtype;
+export function referencedSubtype(map: DocumentSubtypeMap, noteType: string | undefined, document: string, { declared }?: {
+    declared?: ReadonlySet<string> | undefined;
+}): ReferencedSubtype;
 /**
  * Which system defines the document a note of this type compiles into.
  *

package/types/engine/event-views.d.mts

@@ -1,3 +1,11 @@
+/**
+ * Every form an event may name a note by: its Address in the `note` system,
+ * and in its own document's system where that differs.
+ *
+ * @param {object} record - The note's index record.
+ * @returns {string[]} The forms, the `note` one first.
+ */
+export function selfForms(record: object): string[];
 /**
  * The views each note is given, by section.
  *
@@ -20,11 +28,14 @@ export function eventViewSections(db: object, records: Iterable<object>, fileOf:
  * index record, and the `query` it writes for a note — given the note's
  * Address in each form an event may name it by, and the shape of the corpus —
  * or `null` where the corpus states nothing the view could select. A view's
- * `own` query, where it has one, is what decides whether the view has rows.
+ * `own` query, where it has one, is what decides whether the view has rows;
+ * a view with `owners` answers that for many notes in one query, given each
+ * note's Address forms.
  *
  * @type {ReadonlyArray<Readonly<{slug: string, heading: string,
  *   applies: (record: object) => boolean,
- *   query: (self: string[], shape: CorpusShape) => {fence: string, own?: string}|null}>>}
+ *   query: (self: string[], shape: CorpusShape) => {fence: string, own?: string}|null,
+ *   owners?: (db: object, selves: string[][], shape: CorpusShape) => Promise<Set<string>>}>>}
  */
 export const EVENT_VIEWS: ReadonlyArray<Readonly<{
     slug: string;
@@ -34,6 +45,7 @@ export const EVENT_VIEWS: ReadonlyArray<Readonly<{
         fence: string;
         own?: string;
     } | null;
+    owners?: (db: object, selves: string[][], shape: CorpusShape) => Promise<Set<string>>;
 }>>;
 export type CorpusShape = {
     /**

package/types/engine/exported-scene.d.mts

@@ -2,8 +2,9 @@
  * Compile a Foundry Scene export into a pack document.
  *
  * The Scene passes through as exported. Only the note-derived Scene ID,
- * compendium metadata, `data.fixup` and pins marked `#anchor` change; nothing
- * else inside the Scene is read or checked.
+ * compendium metadata, the fixups — `data.fixup` and the map fields that
+ * declare a Scene property, such as `data.thumbnail` — and pins marked
+ * `#anchor` change; nothing else inside the Scene is read or checked.
  *
  * @param {object} fm - The map note's frontmatter.
  * @param {string} markdown - Its converted Markdown body.