@heroiclands/package-build 23.1.0 → 23.2.0

package/types/engine/ids.d.mts

@@ -14,48 +14,6 @@ export function makeId(namespace: string, value: string): string;
  * @returns {boolean} True for a map type.
  */
 export function isMapType(type?: string): boolean;
-/**
- * Throw if `type` names a retired content type.
- *
- * @param {string} type - The note's declared `type`, or a link's qualifier.
- * @param {string} [where] - What carries it — a file path, a link target —
- *   appended to the message so the reader can go straight to it.
- * @throws {Error} Naming the replacement type.
- */
-export function assertTypeNotRetired(type: string, where?: string): void;
-/**
- * The current spelling of a content type: itself, or what it was renamed to.
- *
- * Every table keyed by note type is keyed by the **current** name, and every
- * lookup goes through this — which is the whole of the window's behaviour, in
- * one function, so no two readers can disagree about which vocabulary a note
- * is held to.
- *
- * A non-string passes through untouched: callers hand this whatever the
- * frontmatter carried, and inventing a type for a number would hide the
- * missing-`type:` finding that belongs to the linter.
- *
- * @param {any} type - The type as authored, or as a link spells it.
- * @returns {any} The current spelling.
- */
-export function currentType(type: any): any;
-/**
- * What a note declaring a renamed type is told, in one place.
- *
- * Shared by every reporter, because an author meets whichever runs first and
- * they should read the same. It names the type to write rather than a value to
- * correct — no value makes the retired spelling right — and it says the note
- * compiles either way, so a reader knows this is a rename to schedule rather
- * than a build to unbreak.
- *
- * @param {string} retired - The spelling the note used.
- * @param {string} current - What to write instead.
- * @param {string} [where] - What carries it — a file path, a link target —
- *   appended to the message. Omit it where the caller emits through a
- *   diagnostic, whose locator already starts the line.
- * @returns {string} The message, unpunctuated at the end as a finding is.
- */
-export function renamedTypeMessage(retired: string, current: string, where?: string): string;
 /**
  * The pack a type's documents live in, in the conventional one-pack-per-type
  * layout.
@@ -75,9 +33,6 @@ export function renamedTypeMessage(retired: string, current: string, where?: str
  *
  * @param {string} type - The target note's `type`.
  * @returns {{pack: string, docType: string}} The pack and document type.
- * @throws {Error} If `type` names a retired content type — see
- *   {@link RETIRED_TYPES}. The open-set default would otherwise route it to the
- *   items pack and say nothing.
  */
 export function packForType(type: string): {
     pack: string;
@@ -179,75 +134,6 @@ export const PACK_BY_TYPE: Readonly<Record<string, {
     pack: string;
     docType: string;
 }>>;
-/**
- * Content types that no longer exist, and what replaced each one.
- *
- * `character` and `creature` were retired in favour of the single `being` they
- * had always compiled into. They are recorded here rather than
- * simply deleted because deleting them is the one change that fails *quietly*:
- * every type not named in {@link PACK_BY_TYPE} falls through to the open item
- * set below, so a note or a link left on the old spelling would be routed to
- * the items pack — a wrong answer, arrived at silently, which is exactly the
- * failure mode the open-set default exists to avoid for real item types.
- *
- * Keeping the names lets {@link assertTypeNotRetired} say what happened and
- * what to write instead. Entries stay for as long as content in the wild might
- * still carry them.
- *
- * @type {Readonly<Record<string, string>>}
- */
-export const RETIRED_TYPES: Readonly<Record<string, string>>;
-/**
- * Content types that were **renamed**, and what each is called now.
- *
- * A retired type and a renamed one are different cases, and only the first can
- * be refused. `character` above was retired *outright* — nothing a note wrote
- * made it right, so {@link assertTypeNotRetired} throws. A renamed type has a
- * replacement, the two spellings mean the same thing, and a note carrying the
- * old one compiles into exactly the document it always did: refusing it would
- * fail a build over a note that is not wrong.
- *
- * So these retire in the three steps `package:` took, and this table is
- * the **first**: both spellings resolve, the current one is canonical, and the
- * retired one is *reported* — never refused. The sweep of the content trees and
- * the refusal come after, once no tree writes the old name. That is the same
- * rule `RETIRED_FIELD_ALIASES` states for a renamed *field*, and for the same
- * reason: a consumer must be able to adopt the new toolchain before its content
- * moves, and there are some 31,000 references to move.
- *
- * **Why these three, and why this way round.** The specification renamed
- * `armorgear`, `concoctiongear` and `projectilegear` to `armor`, `concoction`
- * and `projectile`, on the argument that the suffix named the *SoHL document
- * subtype* a note compiled into rather than the thing the note is about. That
- * rename is **reversed**: the gear-suffixed spellings are the vocabulary, and
- * the bare ones are what retires.
- *
- * Nothing had adopted the bare spellings, which is what makes the reversal
- * cheap and the direction obvious: across all five content trees, **every note
- * still authors the suffix** — 331 `armorgear` and 18 `projectilegear` in
- * `sohl`, 71 `concoctiongear` in `thalorna`, and not one note anywhere writes
- * `armor`, `concoction` or `projectile`. The rename produced 349 warnings and
- * zero adopters.
- *
- * `weapongear` never moved, and the reversal restores the consistency its
- * staying put had broken: all five gear types spell the suffix again.
- *
- * **Keyed by the retired spelling**, which is the opposite of
- * `RETIRED_FIELD_ALIASES`. The direction follows the operation: a field alias
- * is scoped by the schema that declares the *current* name, so that is what a
- * reader asks with; a type alias is applied to a value read off a note, so what
- * a reader has in hand is the retired spelling and what it needs is the
- * replacement.
- *
- * **The address is not normalised.** A note's canonical address — and therefore
- * its document id — carries its `type` as authored, so both spellings keep the
- * addresses they already publish and a tree that has not swept compiles
- * byte-identically. Renaming the type in a note *is* an address move, which is
- * the sweep's business and not this table's.
- *
- * @type {Readonly<Record<string, string>>}
- */
-export const RENAMED_TYPES: Readonly<Record<string, string>>;
 /** Where every other content type compiles: the items pack. */
 export const ITEM_PACK: Readonly<{
     pack: "items";

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

@@ -29,15 +29,17 @@ export function sortKeysDeep(value: unknown): unknown;
  */
 export function noteFile(contentBase: string, record: object): string;
 /**
- * The note's own frontmatter, as authored, from an index record.
+ * The note's frontmatter from an index record, without the keys the index
+ * derives.
  *
  * The inverse of the record's spread, and exact rather than best-effort: a
  * record is the note's frontmatter plus {@link DERIVED_KEYS}, and a note that
  * authors one of those keys fails the walk — so removing them cannot remove
  * anything the note wrote. That enforced pairing is what lets a pass read the
- * corpus from the index and still lint, route or compile what the *author*
- * typed, rather than reasoning about `address:` and `anchors:` as though
- * someone had written them.
+ * corpus from the index without reasoning about `address:` and `anchors:` as
+ * though someone had written them. The record's `data.culture` is the note's
+ * resolved culture, so a pass reading the frontmatter sees an inherited culture
+ * as well as a written one.
  *
  * Lives beside the list it is the inverse of, so the two cannot drift.
  *

package/types/engine/index.d.mts

@@ -10,7 +10,6 @@ export * as noteClaims from "./note-claims.mjs";
 export * as folderNotes from "./folder-notes.mjs";
 export * as contentPackage from "./content-package.mjs";
 export * as notePackage from "./note-package.mjs";
-export * as retiredFields from "./retired-fields.mjs";
 export * as runtimeOnlyFields from "./runtime-only-fields.mjs";
 export * as derivedFields from "./derived-fields.mjs";
 export * as homepage from "./homepage.mjs";

package/types/engine/infobox-render.d.mts

@@ -62,9 +62,15 @@ export function sectionHasContent(section: object): boolean;
  * @param {Map<string, string>} links - Address slug → the book's anchor.
  * @param {(anchor: string) => string} labelFor - The anchor's Typst label.
  * @param {string} [site] - The absolute address this book's pages are served at.
+ * @param {{get: (key: string) => (object|undefined)}} [elsewhere] - The notes
+ *   another book is home to. One of them is not a link — a PDF link cannot
+ *   leave its file — and is set as
+ *   {@link module:engine/pdf-render.crossBookReference}.
  * @returns {string} Typst markup.
  */
-export function linkToTypst(value: object, links: Map<string, string>, labelFor: (anchor: string) => string, site?: string): string;
+export function linkToTypst(value: object, links: Map<string, string>, labelFor: (anchor: string) => string, site?: string, elsewhere?: {
+    get: (key: string) => (object | undefined);
+}): string;
 /**
  * Every box as one Typst panel each, breaking between sections.
  *

package/types/engine/infobox.d.mts

@@ -109,7 +109,7 @@ export function valueKindOf(field: object, value: unknown): string;
  *
  * The declared string is appended **verbatim**, which is what lets a symbol
  * hug its number (`160d`) and a word stand off it (`1.1 lbs`). The row's kind
- * becomes `text`: a number with a unit on it is no longer a number, and saying
+ * becomes `text`: a number with a unit on it is not a number, and saying
  * otherwise would invite a medium to format it as one.
  *
  * @param {string} kind - The row's kind.
@@ -149,7 +149,8 @@ export function linkValue(ref: unknown, resolve: (ref: unknown, hint?: object) =
  * order, minus what {@link NOTE_FIELD_PRESENTATION} withholds and minus every
  * field the note left empty. A being's top-level `subType` adds its profile
  * type. A type that declares no `data:` fields still gets the box, because
- * `Name` is a fact about every note.
+ * `Name` is a fact about every note. `data.culture` is the resolved culture,
+ * inherited ones included, and is left out where it names the note itself.
  *
  * @param {object} fm - The note's frontmatter.
  * @param {object} [options] - Options.

package/types/engine/item-docs.d.mts

@@ -32,7 +32,7 @@ export function itemDocEntryId(itemId: string): string;
  *   item beats a bare UUID.
  * @param {string} pageId - The id of the selected entry page, from
  *   {@link journalPageId}.
- * @param {object} [fm] - The source note, used to route GM-only prose.
+ * @param {object} [fm] - The source note, which routes GM-only prose.
  * @returns {string} The pointer to store in `system.docHtml`.
  */
 export function itemDocPointer(packageId: string, itemId: string, name: string, pageId: string, fm?: object): string;

package/types/engine/item-registry.d.mts

@@ -5,10 +5,8 @@
  *
  * **Derived, never authored.** These are the keys of the consuming
  * repository's `itemBuilders` registry, so the whitelist and the builder table
- * are the same list and cannot drift apart. They already had: `trait` was
- * whitelisted long after the item type was retired, with no builder
- * behind it, so every `type: trait` note passed the gate and then failed to
- * compile.
+ * are the same list and cannot drift apart. A whitelist naming a type with no builder would
+ * let every note of that type pass the gate and then fail to compile.
  *
  * An accessor rather than a hoisted constant, so that importing this module
  * needs no configuration.

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

@@ -22,7 +22,7 @@ export function checkLiteratureNote(note: object): object[];
 /** The `lore` subType whose notes are works of literature. */
 export const LITERATURE_SUBTYPE: "literature";
 /**
- * The fields a `literature` note may state. Every one is optional.
+ * The fields only a `literature` note may state. Every one is optional.
  *
  * @type {ReadonlyArray<object>}
  */

package/types/engine/markdownlint-run.d.mts

@@ -0,0 +1,40 @@
+/**
+ * Lint markdown under a root with the `markdownlint` library.
+ *
+ * @param {object} params
+ * @param {string} params.directory - Repository root.
+ * @param {readonly string[]} [params.globs] - Globs selecting the files; when
+ *   absent, `defaults.globs` plus the root options file's `globs`.
+ * @param {object} params.defaults - Options the root options file overrides:
+ *   `config`, `ignores`, `gitignore` and `globs`.
+ * @param {boolean} [params.fix=false] - Repair what markdownlint can, then
+ *   report what remains.
+ * @returns {Promise<{results: object[]}>} markdownlint results, each with its
+ *   `fileName` relative to `directory`, ordered by file, line and rule.
+ * @throws {MarkdownConfigError} A configuration file the contract refuses.
+ */
+export function runMarkdownlint(params: {
+    directory: string;
+    globs?: readonly string[] | undefined;
+    defaults: object;
+    fix?: boolean | undefined;
+}): Promise<{
+    results: object[];
+}>;
+/** Keys an options file may declare at the repository root. */
+export const ROOT_OPTION_KEYS: readonly string[];
+/** A configuration problem, located as far as the source allows. */
+export class MarkdownConfigError extends Error {
+    /**
+     * @param {string} file - Absolute path of the configuration file.
+     * @param {string} message - What is wrong.
+     * @param {{line?: number, column?: number}} [where] - Position, when known.
+     */
+    constructor(file: string, message: string, where?: {
+        line?: number;
+        column?: number;
+    });
+    file: string;
+    line: number | undefined;
+    column: number | undefined;
+}

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

@@ -9,6 +9,12 @@
  * and needing no items is the mirror of it. Gating the index on the catalogue
  * flag would serve neither.
  *
+ * **Includes a relationship of any kind declaring `itemCatalog: true`.** The
+ * compile resolves an embedded item through that catalogue however the
+ * relationship is declared — a `recommends` entry keeps a module installable
+ * under any system and still supplies the items its beings embed — so the lint
+ * resolves the same addresses through the same package's index.
+ *
  * **Excludes a relationship declaring `contentIndex: false`.** That opts a
  * dependency out of both edges at once: it is a Foundry dependency only, cited
  * by neither a wikilink nor an item reference, so there is nothing here for
@@ -224,7 +230,9 @@ export { metadataFileName };
  * `conflicts` are declarations *about* other packages rather than dependencies
  * on them, so an address resolved through one would emit a link into a package
  * the consumer does not require — a defect in the citing note, not a lookup to
- * satisfy.
+ * satisfy. A relationship of either kind that declares `itemCatalog: true` is
+ * the exception: its items are embedded in this package's own documents, so
+ * its index is read whatever its kind (see {@link metadataRelationships}).
  *
  * @type {readonly string[]}
  */

package/types/engine/note-addresses.d.mts

@@ -6,9 +6,19 @@
 export function addressPositions(fm: object, context?: {}): object[];
 /**
  * Decode declared properties at the note boundary. Raw mappings cannot impersonate tuples.
+ *
+ * A declared Address is read as written. A shortcode spelled with a capital is
+ * refused, and every such value in the note is collected before the decode
+ * throws, so each reference is reported at its own position: the thrown error
+ * describes the first, and its `findings` carry all of them.
+ *
  * @param {object} fm - Parsed YAML or an index record.
- * @param {object} context - The builder's package and known types.
+ * @param {object} context - The builder's package and known types, and
+ *   optionally `declaresAddress`, which names the lowercase spelling of a
+ *   refused shortcode when it is declared.
  * @returns {object} The same note carrying typed Address properties.
+ * @throws {Error} When a declared Address is refused; `keyPath` locates it, and
+ *   `findings`, where present, lists every refused shortcode.
  */
 export function decodeNoteAddresses(fm: object, context: object): object;
 /**
@@ -25,11 +35,26 @@ export function noteAddressContext(config: object): object;
  * {@link AddressLink} where it carries an anchor, before the declared
  * positions are read.
  *
+ * With a `source`, the record is a dependency's, read from its cached index.
+ * Every decode failure then leaves as a located finding that names the
+ * dependency, the cached file, the record, the field and the remedy, because
+ * the shape of a published index is the dependency's to correct and no note in
+ * the reading tree is at fault.
+ *
  * @param {object} record - The record.
  * @param {object} context - Builder defaults.
+ * @param {{package: string, file: string, line?: number}} [source] - The
+ *   dependency and the cached index file the record was read from, with the
+ *   record's 1-based line when known.
  * @returns {object} The typed record.
+ * @throws {Error} A located finding (`located: true`) when `source` is given
+ *   and the record cannot be decoded; otherwise the decode error itself.
  */
-export function decodeIndexAddresses(record: object, context: object): object;
+export function decodeIndexAddresses(record: object, context: object, source?: {
+    package: string;
+    file: string;
+    line?: number;
+}): object;
 /** Structured positions whose Address is nested inside a declared container. */
 export const STRUCTURED_ADDRESSES: readonly ({
     path: string[];

package/types/engine/note-claims.d.mts

@@ -54,7 +54,7 @@ export function noteTypesClaimedBy(docType: string, sources?: ClaimSources): Rea
  * the answer is the type's full potential — every document such a note *could*
  * produce — which is what a caller asking about a type rather than a note wants.
  *
- * @param {string} type - The note's declared `type`, current spelling.
+ * @param {string} type - The note's declared `type`.
  * @param {ClaimSources} [sources] - What to answer from.
  * @param {object} [opts] - Options.
  * @param {(() => boolean)|boolean} [opts.hasProse] - Whether *this note* carries
@@ -109,12 +109,10 @@ export function noteTypeVocabulary(sources?: ClaimSources): ReadonlySet<string>;
  * note's type and of a note's systems, and a note can fail either while passing
  * the other — see {@link discardedSystemBlockFindings}.
  *
- * Read-only: it walks the tree and reports, and writes nothing. Three kinds of
+ * Read-only: it walks the tree and reports, and writes nothing. Two kinds of
  * note are passed over, each for a stated reason rather than by omission — a
  * file with no frontmatter is not a note; a note with no `type:` is the
- * frontmatter linter's finding, which can say what a type is *for*; and a
- * retired type is answered by `assertTypeNotRetired` in `ids.mjs`, which names the
- * replacement.
+ * frontmatter linter's finding, which can say what a type is *for*.
  *
  * @param {object} [config] - The resolved build configuration. Defaults to this
  *   repository's.

package/types/engine/note-ids.d.mts

@@ -17,10 +17,8 @@
  *
  * Returns `undefined` for a file with **no address** — no `type`, or no
  * `shortcode`. Such a file is not an addressable note, so it has no document
- * and inventing an id for one would file it under nothing. Every caller already
- * had to handle an absent id (that is what the authored field's absence meant),
- * so this reports the same thing rather than throwing where a walk used to
- * skip; whether an id is *required* stays each pass's own decision
+ * and inventing an id for one would file it under nothing. This reports the
+ * absence rather than throwing, so a walk skips such a file; whether an id is *required* stays each pass's own decision
  * (`BasePackCompiler.requiresId`).
  *
  * @param {object|null|undefined} fm - Parsed frontmatter.

package/types/engine/note-package.d.mts

@@ -9,7 +9,7 @@ export function searchableFrontmatter(fm: object | null | undefined, configured?
  * Refuse a note that declares `package:` at all.
  *
  * Presence is the whole test — a declaration that *agrees* with the
- * configuration is as retired as one that disagrees, and an empty one
+ * configuration is refused like one that disagrees, and an empty one
  * (`package:`, which parses as `null`) is still the field.
  *
  * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it

package/types/engine/note-state.d.mts

@@ -13,9 +13,7 @@
  * either state.
  *
  * An HTML comment is deliberately not empty. An invisible marker deciding
- * whether a page exists is the failure the retired `draft:` field was removed
- * for, and reintroducing it in comment form would be worse, because nothing
- * would report it.
+ * whether a page exists would be a failure nothing reports.
  *
  * @param {string|null|undefined} body - The note body, frontmatter stripped.
  * @returns {boolean} Whether the body is empty.

package/types/engine/note-vocabulary.d.mts

@@ -65,11 +65,8 @@ export function isGmNote(fm: any): boolean;
  * What a note carrying a subType outside the address charset is told.
  *
  * **Why the charset holds for a subType, which reaches no address.** The rule
- * said
- * "the hyphen separates the segments of an address", and that was true of a
- * subType when it shipped: `sectionOf` returned a `doc`'s subType, so the value
- * was a URL path segment. Sections are retired and it is not one. The rule
- * stays, on its own footing: a subType is a vocabulary term the whole toolchain
+ * says "the hyphen separates the segments of an address", and a subType is not
+ * one. The rule stands on its own footing: a subType is a vocabulary term the whole toolchain
  * keys on, and it is one closed set away from being an address segment again —
  * so the reason to spell it in the address charset is that a charset holding
  * for a type, a shortcode and a `contentPackage` but not for a subType is a
@@ -99,7 +96,7 @@ export function typeCharsetMessage(type: string): string;
  *
  * The message states the reason **per key**, as {@link typeCharsetMessage} and
  * {@link subTypeCharsetMessage} do: a type is an address segment, and a subType
- * is not one, since sections are retired, so a single claim covering both
+ * is not one, so a single claim covering both
  * would be half wrong.
  *
  * @param {Readonly<Record<string, TypeVocabulary>>} vocabulary - The registry.
@@ -208,13 +205,10 @@ export const NOTE_TOP_LEVEL_KEY_SET: ReadonlySet<string>;
  * row in twenty-five tables would be twenty-five chances for one of them to
  * disagree with the rest.
  *
- * Both are art slots, and they are legal everywhere for different reasons.
- * `icon` is the document's profile art and most types compile into a document
- * that carries one; where a type's passes emit none, the frontmatter lint says
- * so as a warning rather than the vocabulary refusing the key, because the
- * value may still be read by a page template. `banner` reaches no compiled
- * document at all — it is the page's hero image — and a page is what every note
- * publishes.
+ * `banner` is an art slot legal everywhere: it reaches no compiled document, it
+ * is the page's hero image, and a page is what every note publishes. `icon` is
+ * not shared; it is declared by {@link ICON_FIELD} for the types whose
+ * document carries art.
  *
  * @type {readonly DataFieldSpec[]}
  */
@@ -228,9 +222,7 @@ export const SHARED_DATA_FIELDS: readonly DataFieldSpec[];
  *
  * It is a **presentation** fact and nothing more. A draft note compiles,
  * validates, publishes and resolves like any other; only a link *into* it
- * renders marked. What it emphatically is not is the retired `draft:` field,
- * whose entire effect was to move a note from published to unresolvable — see
- * {@link draftRetiredMessage}.
+ * renders marked.
  */
 export const DRAFT_TAG: "draft";
 /** A note intended for the GM rather than the player-facing outputs. */
@@ -362,16 +354,13 @@ export type DataFieldSpec = {
      * value — which is the honest answer wherever the specification's stated
      * shape and the shape notes are authored in today disagree.
      */
-    kind?: "string" | "number" | "boolean" | "map" | "address" | "list" | "shortcode" | "list-or-map" | "scalar-or-map" | undefined;
+    kind?: "string" | "number" | "boolean" | "map" | "address" | "list" | "scalar-or-map" | "shortcode" | undefined;
     /**
      * - Type of each list or pack-map value.
      */
     entryKind?: "address" | "shortcode" | undefined;
     /**
-     * - Type of each map key. On a
-     * `list-or-map` field it describes the map form alone, and `entryKind` the
-     * list form alone: reading both of one value would check a map's entries as
-     * if they were its keys.
+     * - Type of each map key.
      */
     keyKind?: "address" | "shortcode" | undefined;
     /**
@@ -393,6 +382,12 @@ export type DataFieldSpec = {
      * - Allowed Address types, separate from `ref`.
      */
     accepts?: readonly string[] | undefined;
+    /**
+     * - The literal value that declines the art this
+     * Address field names. It is not an Address, is never resolved, and is not
+     * reported as unresolved.
+     */
+    declines?: string | undefined;
     /**
      * - The anchor kinds an
      * Address here may name with `#<anchor>`. Absent, an anchor is refused.
@@ -426,6 +421,13 @@ export type DataFieldSpec = {
      * ({@link module :engine/field-spec}), which names a **Shortcode** instead.
      */
     ref?: string | undefined;
+    /**
+     * - On a map, the exported Scene property an
+     * Address field's resolved path is written into, as a `data.fixup` path. The
+     * Scene compile applies the field as one more fixup — see
+     * {@link module :engine/exported-scene}.
+     */
+    sceneProperty?: string | undefined;
     /**
      * - For a `scalar-or-map` field, what its keys name.
      * `"pack"` means each is a pack this package declares, so a key naming none
@@ -460,6 +462,11 @@ export type DataFieldSpec = {
      * is, where the keys are data rather than declared names.
      */
     values?: object | undefined;
+    /**
+     * - The closed set a present string
+     * value is one of; any other word is a finding at the value.
+     */
+    allowed?: readonly string[] | undefined;
     /**
      * - One line, for the author-facing reference.
      */

package/types/engine/pack-config.d.mts

@@ -3,7 +3,7 @@
  *
  * **Two of them in one directory is an error.** Picking one by precedence would
  * mean a repository mid-conversion silently builds from the file its author is
- * no longer editing, and the build would look entirely healthy while doing it.
+ * not editing, and the build would look entirely healthy while doing it.
  * The walk continues past a directory holding none, so a repository may still
  * sit inside one that has its own.
  *
@@ -137,11 +137,7 @@ export const CONFIG_BASENAME: "package-build.config";
  * the order the names are *reported* in, which is the order a reader should
  * reach for them: YAML first, `.mjs` last.
  *
- * The `package-build.config.*` stem this package read before the two toolchains
- * merged is **not** resolved. 3.0.0 renames the file rather than accepting both:
- * a deprecation window here would mean a repository could sit indefinitely on a
- * name for a package that no longer exists, and the upgrade already requires
- * touching the consumer's manifest and imports.
+ * Only the `package-build.config.*` stem is resolved.
  *
  * @type {readonly string[]}
  */

package/types/engine/pack-router.d.mts

@@ -62,10 +62,10 @@ export class PackRoutingError extends Error {
 /**
  * The frontmatter field a note declares its pack in.
  *
- * Deliberately close to the retired `package:` and deliberately not the same
- * word: `package:` said which *distribution* owned a note — now the
- * repository's `contentPackage`, and no longer authorable — while `pack:`
- * says which *compendium* receives its document.
+ * Deliberately close to `package:` and deliberately not the same word:
+ * `package:` would say which *distribution* owns a note — that is the
+ * repository's `contentPackage`, and not authorable — while `pack:` says which
+ * *compendium* receives its document.
  */
 export const PACK_FIELD: "pack";
 export { NO_PACK };

package/types/engine/pathnames.d.mts

@@ -138,10 +138,10 @@ export type PathnameForms = {
      */
     authored: string;
     /**
-     * `blank` for `""`, `external`
-     * for an address no package owns, `package` for an owned file.
+     * `external` for an address no
+     * package owns, `package` for an owned file.
      */
-    state: "blank" | "external" | "package";
+    state: "external" | "package";
     /**
      * The content package that owns the file, or
      * `null` when no package does.