@heroiclands/package-build 22.9.2 → 22.11.0

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

@@ -1,3 +1,4 @@
+/** @typedef {import("./art-slots.mjs").ArtSlot} ArtSlot */
 /**
  * The art slot one key names, or `undefined`.
  *
@@ -6,13 +7,30 @@
  */
 export function artSlot(key: unknown): ArtSlot | undefined;
 /**
- * The address an authored art value names.
+ * The Address an authored art value names, checked against what this position
+ * accepts.
  *
- * @param {string} value - The value as authored.
- * @param {string} defaultType - The type the field declares.
- * @returns {string} A written address, which may be partial.
+ * The two questions {@link module:engine/address} keeps separate: does the
+ * value parse, and is what it names acceptable *here*. {@link parseAddress}
+ * answers the first, taking the slot's own `type` as the default an omitted
+ * segment fills in; {@link acceptsType} answers the second, against the set
+ * the position declares rather than against that same default.
+ *
+ * @param {unknown} value - The value as authored.
+ * @param {string} defaultType - The type a bare value takes.
+ * @param {Iterable<string>|undefined} accepts - The types this position
+ *   accepts, or `undefined` to accept whatever parses.
+ * @param {import("./address.mjs").AddressDefaults} [vocabulary] - The
+ *   position's remaining defaults and the tree's vocabularies.
+ * @returns {import("./address.mjs").AddressTuple
+ *   |import("./address.mjs").AddressProblem
+ *   |{reason: "not-accepted", type: string}} The Address; a reason it does
+ *   not parse; or `not-accepted` when it parses to a type outside `accepts`.
  */
-export function artTarget(value: string, defaultType: string): string;
+export function artTarget(value: unknown, defaultType: string, accepts: Iterable<string> | undefined, vocabulary?: import("./address.mjs").AddressDefaults): import("./address.mjs").AddressTuple | import("./address.mjs").AddressProblem | {
+    reason: "not-accepted";
+    type: string;
+};
 /**
  * The address space an asset reference resolves against, from a corpus.
  *
@@ -60,12 +78,17 @@ export function assetAddressIndex(records?: readonly object[], { config, foreign
  *   or the equivalent the site and the book build.
  * @param {unknown} value - The value as authored.
  * @param {string} defaultType - The type a bare value takes.
+ * @param {Iterable<string>} [accepts] - The types this position accepts, for a
+ *   position that declares a set narrower than "every asset type" — an art
+ *   slot's. Omitted, any asset type is taken, which is an embed's rule: it
+ *   draws a file, and every asset type is a file.
  * @returns {{record: {package: string, asset: {path: string}}, pathname: string}
  *   |{record: null, reason: string, type?: string}} The asset and the pathname
  *   it is at, or a reason from
- *   {@link module:engine/wikilink-syntax.LINK_FINDING_REASONS}.
+ *   {@link module:engine/wikilink-syntax.LINK_FINDING_REASONS}, or `not-accepted`
+ *   when `accepts` is given and the parsed type falls outside it.
  */
-export function readAssetAddress(index: object, value: unknown, defaultType: string): {
+export function readAssetAddress(index: object, value: unknown, defaultType: string, accepts?: Iterable<string>): {
     record: {
         package: string;
         asset: {
@@ -84,9 +107,10 @@ export function readAssetAddress(index: object, value: unknown, defaultType: str
  * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex}.
  * @param {unknown} value - The value as authored.
  * @param {string} defaultType - The type the field declares.
+ * @param {Iterable<string>} [accepts] - The types this position accepts.
  * @returns {{package: string, asset: {path: string}}|null} The record.
  */
-export function resolveArtRecord(index: object, value: unknown, defaultType: string): {
+export function resolveArtRecord(index: object, value: unknown, defaultType: string, accepts?: Iterable<string>): {
     package: string;
     asset: {
         path: string;
@@ -103,13 +127,19 @@ export function resolveArtRecord(index: object, value: unknown, defaultType: str
  * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex}.
  * @param {unknown} value - The value as authored.
  * @param {string} defaultType - The type the field declares.
- * @returns {{pathname: string|null, resolved: boolean}} The pathname, and
- *   whether an address was actually answered — which tells a caller applying a
- *   default apart from one whose address named nothing.
+ * @param {Iterable<string>} [accepts] - The types this position accepts.
+ * @returns {{pathname: string|null, resolved: boolean, reason?: string,
+ *   type?: string}} The pathname, and whether an address was actually
+ *   answered — which tells a caller applying a default apart from one whose
+ *   address named nothing. `reason` and `type` carry why, unresolved — in
+ *   particular `not-accepted`, which the caller reports as an error rather
+ *   than falling back silently.
  */
-export function artPathname(index: object, value: unknown, defaultType: string): {
+export function artPathname(index: object, value: unknown, defaultType: string, accepts?: Iterable<string>): {
     pathname: string | null;
     resolved: boolean;
+    reason?: string;
+    type?: string;
 };
 /**
  * The default art address a being's own tags choose, or `null`.
@@ -126,34 +156,30 @@ export function beingDefaultArt(fm: object): string | null;
  * What an unresolved art address is reported as.
  *
  * One wording, so the four compilers that can meet the case do not each invent
- * their own.
+ * their own. A **warning**: nothing in this package or a fetched index answers
+ * the address, so the document falls back to its default art rather than
+ * shipping a path that installs nowhere.
  *
  * @param {string} key - The key that was authored.
- * @param {unknown} value - The value it carried.
- * @param {string} defaultType - The type the field declares.
+ * @param {unknown} value - The value it carried, named exactly as written.
  * @returns {string} The message.
  */
-export function unresolvedArtMessage(key: string, value: unknown, defaultType: string): string;
+export function unresolvedArtMessage(key: string, value: unknown): string;
 /**
- * One art slot: the key a note authors, and the type a bare value takes.
+ * What an art address naming a type this slot does not accept is reported as.
  *
- * @typedef {object} ArtSlot
- * @property {string} key - The key under `data:`.
- * @property {string} type - The asset type a bare shortcode defaults to.
- * @property {boolean} document - Whether the slot reaches a compiled document.
- * @property {string} describe - One line, for the author-facing reference.
- */
-/**
- * The four art slots, in the order the specification tabulates them.
- *
- * `banner` is the one that reaches no compiled document: it is the page's hero
- * image, read by the site and by the book's section plates and by nothing else.
- * That is what `document: false` states, and it is why the inert-art check
- * skips it — a key that is *meant* to reach no document is not an inert key.
+ * An **error**, not a warning: unlike an address nothing answers, this one
+ * names a real type, and no default art repairs an author asking for a sound
+ * where the slot takes an icon or an image.
  *
- * @type {readonly ArtSlot[]}
+ * @param {string} key - The key that was authored.
+ * @param {unknown} value - The value it carried, named exactly as written.
+ * @param {string} type - The type the address named.
+ * @param {Iterable<string>} accepts - The types this slot accepts.
+ * @returns {string} The message.
  */
-export const ART_SLOTS: readonly ArtSlot[];
+export function unacceptedArtMessage(key: string, value: unknown, type: string, accepts: Iterable<string>): string;
+export { ART_SLOTS } from "./art-slots.mjs";
 /**
  * The art a being falls back to, by the kind it is tagged.
  *
@@ -169,24 +195,4 @@ export const ART_SLOTS: readonly ArtSlot[];
  * @type {Readonly<Record<string, string>>}
  */
 export const BEING_DEFAULT_ART: Readonly<Record<string, string>>;
-/**
- * One art slot: the key a note authors, and the type a bare value takes.
- */
-export type ArtSlot = {
-    /**
-     * - The key under `data:`.
-     */
-    key: string;
-    /**
-     * - The asset type a bare shortcode defaults to.
-     */
-    type: string;
-    /**
-     * - Whether the slot reaches a compiled document.
-     */
-    document: boolean;
-    /**
-     * - One line, for the author-facing reference.
-     */
-    describe: string;
-};
+export type ArtSlot = import("./art-slots.mjs").ArtSlot;

package/types/engine/art-slots.d.mts

@@ -0,0 +1,40 @@
+/**
+ * The four art slots, in the order the specification tabulates them.
+ *
+ * `banner` is the one that reaches no compiled document: it is the page's hero
+ * image, read by the site and by the book's section plates and by nothing else.
+ * That is what `document: false` states, and it is why the inert-art check
+ * skips it — a key that is *meant* to reach no document is not an inert key.
+ *
+ * @type {readonly ArtSlot[]}
+ */
+export const ART_SLOTS: readonly ArtSlot[];
+/**
+ * One art slot: the key a note authors, and the type a bare value takes.
+ */
+export type ArtSlot = {
+    /**
+     * - The key under `data:`.
+     */
+    key: string;
+    /**
+     * - The asset type a bare shortcode defaults to.
+     */
+    type: string;
+    /**
+     * - The types an authored value may
+     * name. **Not the default** — a faith tradition's profile art is a full
+     * illustration rather than a game icon, so an `icon` slot's default stays
+     * `icon` while its accepted set also takes `image`. A value naming a type
+     * outside it is an error, against this set rather than against `type`.
+     */
+    accepts: readonly string[];
+    /**
+     * - Whether the slot reaches a compiled document.
+     */
+    document: boolean;
+    /**
+     * - One line, for the author-facing reference.
+     */
+    describe: string;
+};

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

@@ -403,15 +403,37 @@ export class BasePackCompiler {
      *
      * An address nothing answers is reported against the note and treated as
      * unnamed, so the document takes its default rather than shipping a path
-     * that installs nowhere.
+     * that installs nowhere. **A type this slot does not accept is different**:
+     * the address is real, so no default repairs it, and it is an error rather
+     * than a fallback.
      *
      * @param {unknown} value - The value as authored.
      * @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.
      */
-    artPathOf(value: unknown, key: string, type: string): string | null;
+    artPathOf(value: unknown, key: string, type: string, accepts?: Iterable<string>): string | null;
+    /**
+     * Reduce every Address an assembled `system` block holds to the Shortcode
+     * the document reads.
+     *
+     * The positions come from the type's own field declarations, so a system
+     * adding a field that names a note gets the reduction by declaring it; see
+     * {@link module:engine/address-fields}.
+     *
+     * Called **after** the builder and the authored merge have both written, so
+     * one step reduces a value the field read and a value authored straight at
+     * the destination alike. Each finding is located at the value inside the
+     * note, which for a list or a map is the entry that is wrong rather than the
+     * key that introduces it.
+     *
+     * @param {object} emitted - The `system` block, assembled.
+     * @param {readonly object[]} [fields] - The type's field declaration.
+     * @returns {number} How many findings were reported.
+     */
+    reduceEmittedAddresses(emitted: object, fields?: readonly object[]): number;
     /**
      * The Foundry path one art slot of a note names, or `null`.
      *

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

@@ -18,8 +18,8 @@ export function stripAdventureKeys(value: any): any;
 /**
  * An authored address with any wikilink brackets and label stripped.
  *
- * The specification types `contents` as a `WikiLink[]`, and a frontmatter link
- * is written as a bare address — but `[[address]]` is what an author reaches
+ * The specification types `contents` as an `Address[]`, written bare — but
+ * `[[address]]` is what an author reaches
  * for, and it is what a folder note's `parent` already accepts. Accepting both
  * costs one regex and removes a failure whose message would have to explain the
  * difference.

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

@@ -2,7 +2,7 @@
  * The single path segment a note is addressed by: `type-shortcode`.
  *
  * Lowercased and hyphen-joined by the same rule as the note's canonical key
- * ({@link canonicalKey}, below, lowercases too), so it is that
+ * ({@link canonicalKey} lowercases too), so it is that
  * key's **last two segments** — which is what makes a manifest entry's `path`
  * derivable from the key it is filed under rather than transported beside it.
  *
@@ -64,55 +64,6 @@ export function addressSlug(fm: object): string;
  *   dead entry in the manifest.
  */
 export function packageAddress(fm: object): string;
-/**
- * The **canonical** address of a note: fully qualified, one spelling per
- * document, and globally unique.
- *
- * The written form of a link is a **partial** address: it may omit leading
- * segments, and each one it omits is filled in by rule rather than left
- * unconstrained. An omitted package (`[[skill-lang]]`) defaults to the citing
- * note's own, so an unqualified link resolves locally and only locally, and a
- * link into another package must name it. An omitted **system** is a
- * *wildcard*, not a default — most links target items, which belong to a
- * system — and the resolver requires exactly one match: none is a dead link,
- * more than one is an ambiguity reported with every candidate named.
- * Everything internal — index keys, cache keys, every lookup — uses this fully
- * qualified form instead, so no consumer has to know what a short form
- * defaulted to or matched.
- *
- * Global uniqueness is what lets a dependency's index merge straight into a
- * local one: the keys cannot collide by accident, so a key already present on
- * merge is a real conflict rather than an artefact of two packages sharing a
- * namespace. `(type, shortcode)` alone is unique only *within* a package, and
- * two independently authored packages reaching for the same short string is a
- * matter of time.
- *
- * **The system segment.** A package may ship content for more than one
- * system, and one note then compiles into a document per system — an actor in
- * `actors-sohl` *and* an actor in `actors-hm3`. Without a system segment both
- * land on one key, so the address cannot name either of them. `harn-ensemble`
- * carries 2,497 such notes.
- *
- * The value is a system id, or the literal **`none`** for a document no game
- * system defines: a journal, a macro, a scene, and an item's documentation
- * journal — which is `none` however many systems the item itself declares,
- * because it is one journal.
- *
- * `none` rather than `any`: every segment of an address is an exact literal,
- * and `any` reads as a wildcard — "matches under any system" — which is not
- * what it does. A resolver written to that misreading would fail silently,
- * since a lookup miss already returns nothing rather than erroring. And not
- * `null` or `~`, both of which are YAML nulls that parse to an absent value and
- * drop the segment entirely.
- *
- * @param {string} pkg - The owning **content** package (`sohl`, `thalorna`) —
- *   not the Foundry package, which varies per compilation target.
- * @param {string} system - The system whose document this addresses, or `none`.
- * @param {string} type - The note's `type`.
- * @param {string} shortcode - The note's `shortcode`.
- * @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.
  *
@@ -122,7 +73,7 @@ export function canonicalKey(pkg: string, system: string, type: string, shortcod
  * 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
+ * It is the block rather than the field, so an `Address` 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:
@@ -134,83 +85,6 @@ export function canonicalKey(pkg: string, system: string, type: string, shortcod
  * @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** — 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.
- *
- * Parsing is plain positional counting: split on the separator, require
- * {@link CANONICAL_KEY_SEGMENTS} of them, and assign each position its field.
- * **The charset rule is what makes that sound** — every segment matches
- * `ADDRESS_SEGMENT_PATTERN` (`engine/address-charset.mjs`), so the hyphen is
- * purely a separator and the count alone determines every field. That is
- * enforced at each of the three sources rather than assumed of
- * the data: shortcodes by `content-lint.mjs`, `contentPackage` by
- * `defineConfig`, and types are bare words. Were any of them free to
- * carry a hyphen, no amount of counting would recover the fields and the reader
- * would need a vocabulary to match against instead.
- *
- * **Nothing to read and nothing readable are different answers.** A key that
- * cannot be canonical — `harn-adventures-sohl-skill-melee`, five segments,
- * because the package name carries the separator — yields `null`, while an
- * absent or blank input yields `undefined`. Both are falsy, so
- * every call site (all of which test the result for truthiness) is unaffected;
- * the distinction is there so a caller reporting "this key is unreadable" can
- * tell that it has a key to report about.
- *
- * @param {unknown} key - A canonical key, or nothing.
- * @returns {{package: string, system: string, type: string, shortcode: string}
- *   |null|undefined}
- *   The parts; `null` when there is a string that is not in canonical form;
- *   `undefined` when there is no key at all.
- */
-export function readCanonicalKey(key: unknown): {
-    package: string;
-    system: string;
-    type: string;
-    shortcode: string;
-} | null | undefined;
 /**
  * Asserts a base is usable as a prefix and returns it.
  *
@@ -280,17 +154,6 @@ export function resolvePackageUrl(rel: string, base: string): string;
 export function documentId(pkg: string, system: string, type: string, shortcode: string): string;
 /** The knowledgebase's mount within this package's site. */
 export const KB_PREFIX: "kb/";
-/**
- * How many segments a canonical key has, and therefore how many the reader
- * below counts.
- *
- * Named rather than written as a literal because it is the *grammar*, not an
- * implementation detail of one function: it is the number a change to the
- * address form would move, and the thing a reader of that change has to find.
- *
- * @type {number}
- */
-export const CANONICAL_KEY_SEGMENTS: number;
 /**
  * Where this build serves each package, keyed by package name.
  *
@@ -324,3 +187,4 @@ export const DOCUMENT_ID_NAMESPACE: string;
 import { DEFAULT_ADDRESS_SCHEME } from "../content-config.mjs";
 import { NO_SYSTEM } from "./systems.mjs";
 export { DEFAULT_ADDRESS_SCHEME, NO_SYSTEM };
+export { canonicalKey, expandAddress, readCanonicalKey, CANONICAL_KEY_SEGMENTS } from "./address.mjs";

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

@@ -24,7 +24,7 @@
  * @param {string} body - The note's markdown, without its frontmatter.
  * @returns {ParsedEmbed[]} One entry per embed.
  */
-export function embedsIn(body: string): ParsedEmbed[];
+export function embedsIn(body: string, context: any): ParsedEmbed[];
 /**
  * What one embed resolves to, or why it does not.
  *

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

@@ -105,6 +105,31 @@ export function measureCorpus(notes: Iterable<object>, format: import("./content
  * @returns {string} The message.
  */
 export function fieldDriftMessage({ noteType, source, target, name, to }: object): string;
+/**
+ * The declaration that compiles one mapping row, and what is left over.
+ *
+ * The longest declared name the row's source sits under: a field declared
+ * `impact.die` claims `data.impact.die` ahead of any field declared `impact`,
+ * and a field declared `charges` claims `data.charges.max` with `.max` left
+ * over. Compared on the normalized spelling, so a field naming its source under
+ * `data:` matches at the same length a bare one does.
+ *
+ * Exported because two readers ask it and must agree: {@link
+ * checkDeclaredFields}, which holds the row's target to the declaration's, and
+ * the guard that holds the declaration's *source* to the row's — a second copy
+ * of the match would let the two disagree about which declaration a row is even
+ * about.
+ *
+ * @param {string} source - The row's shared source, as either side spells it.
+ * @param {readonly object[]} fields - The type's authored declarations.
+ * @returns {{field: object, rest: string}|undefined} The declaration and the
+ *   remainder of the source beneath its name, or nothing where no declaration
+ *   names it.
+ */
+export function declarationFor(source: string, fields: readonly object[]): {
+    field: object;
+    rest: string;
+} | undefined;
 /**
  * Check the specification's per-type tables against the field declarations that
  * compile them.

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

@@ -112,7 +112,7 @@ export function asciiAliases(aliases: unknown): Array<string>;
  *   otherwise be overwritten without a word. `file` and, where the file was
  *   read, `position` ride on the error.
  */
-export function buildIndexRecord({ frontmatter, relPath, absPath, contentPackage, body, bodyLine, manifest, }: {
+export function buildIndexRecord({ frontmatter, relPath, absPath, contentPackage, body, bodyLine, manifest, addressContext, }: {
     frontmatter: Record<string, any>;
     relPath: string;
     absPath?: string | undefined;
@@ -152,7 +152,7 @@ export function buildIndexRecord({ frontmatter, relPath, absPath, contentPackage
  * @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 }: {
+export function collectContentIndex(contentBase: string, { contentPackage, skipDirectories, assetsBase, manifest, problems, addressContext }: {
     contentPackage: string;
     skipDirectories: readonly string[];
     assetsBase?: string | undefined;

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

@@ -131,11 +131,12 @@ export function auditHomepageLinks(index: ReturnType<typeof buildLinkIndex>): Ar
  *   unlabelledLinks: object[], frontmatterLinks: object[],
  *   homepageLinks: object[], usedManifest: Set<string>}} The findings, and
  *   which addresses a foreign manifest answered. Each `deadAddresses` entry
- *   carries a `reason` from {@link LINK_FINDING_REASONS} —
- *   `"not-an-address"`, `"unknown-type"`, `"ambiguous"` (with the claiming
- *   `packages`), `"no-content-index"`, `"stub"` (with the stub's path) or
- *   `"unresolved"` — and every one of them is an **error**: the three
- *   resolvers agree on severity for every class.
+ *   carries a `reason` from {@link LINK_FINDING_REASONS} — `"not-an-address"`,
+ *   `"unknown-type"`, `"no-content-index"`, `"stub"` (with the stub's path) or
+ *   `"unresolved"`, never `"ambiguous"`: every target here expands to one
+ *   canonical address before anything is looked up, so there is no candidate
+ *   set for two packages to claim — and every reason is an **error**: the
+ *   three resolvers agree on severity for every class.
  */
 export function auditLinks(index: ReturnType<typeof buildLinkIndex>): {
     deadAnchors: object[];

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

@@ -267,10 +267,27 @@ export function runtimeOnlyFields(fields: readonly FieldSpec[]): FieldSpec[];
  *   several do — `weight` is coerced leniently but is still a number, and
  *   `weight: heavy` is an authoring mistake worth reporting where it was made.
  *   Absent means the lint makes no claim about the value.
- * @property {string} [ref] - The content type a value addresses by shortcode,
- *   for the linter's dead-reference check. Only for references to a **note**:
- *   `bodyLocationCode` names a part inside a being's own body structure, not a
- *   note, so it declares none.
+ * @property {string} [code] - The content type a value names by **Shortcode**,
+ *   for the linter's dead-reference check. The authored value is one segment —
+ *   held to {@link module:engine/address-charset.ADDRESS_SEGMENT_PATTERN} —
+ *   persisted verbatim into the emitted field and resolved at runtime among
+ *   the items embedded on one actor, where packages do not exist; the linter
+ *   still forms the `type-shortcode` pair to check it against the index. Only
+ *   for references to a **note**: `bodyLocationCode` names a part inside a
+ *   being's own body structure, not a note, so it declares none. Distinct
+ *   from a `DataFieldSpec`'s `ref` ({@link module:engine/note-vocabulary}),
+ *   which names an **Address** instead.
+ * @property {import("./address-fields.mjs").AddressPosition} [address] - The
+ *   authored value is an Address. The emitted value is its Shortcode, or the
+ *   exact published Item UUID when `emit: "uuid"` is declared. The
+ *   statement carries the default type an omitted `<type>` segment takes, the
+ *   set of types the position accepts — two separate things, which coincide at
+ *   most positions — and where the Addresses sit: the value itself, every
+ *   element of a list, or every key of a map.
+ *   {@link module:engine/address-fields.reduceAddressFields} performs the
+ *   reduction once the block is assembled, so a value authored at the
+ *   destination is reduced along with one this field read. Distinct from `code`,
+ *   which is a Shortcode at both ends and resolves nothing.
  * @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
@@ -524,12 +541,32 @@ export type FieldSpec = {
      */
     kind?: "string" | "number" | "boolean" | "map" | "list" | undefined;
     /**
-     * - The content type a value addresses by shortcode,
-     * for the linter's dead-reference check. Only for references to a **note**:
-     * `bodyLocationCode` names a part inside a being's own body structure, not a
-     * note, so it declares none.
+     * - The content type a value names by **Shortcode**,
+     * for the linter's dead-reference check. The authored value is one segment —
+     * held to {@link module :engine/address-charset.ADDRESS_SEGMENT_PATTERN} —
+     * persisted verbatim into the emitted field and resolved at runtime among
+     * the items embedded on one actor, where packages do not exist; the linter
+     * still forms the `type-shortcode` pair to check it against the index. Only
+     * for references to a **note**: `bodyLocationCode` names a part inside a
+     * being's own body structure, not a note, so it declares none. Distinct
+     * from a `DataFieldSpec`'s `ref` ({@link module :engine/note-vocabulary}),
+     * which names an **Address** instead.
      */
-    ref?: string | undefined;
+    code?: string | undefined;
+    /**
+     * - The
+     * authored value is an Address. The emitted value is its Shortcode, or the
+     * exact published Item UUID when `emit: "uuid"` is declared. The
+     * statement carries the default type an omitted `<type>` segment takes, the
+     * set of types the position accepts — two separate things, which coincide at
+     * most positions — and where the Addresses sit: the value itself, every
+     * element of a list, or every key of a map.
+     * {@link module :engine/address-fields.reduceAddressFields} performs the
+     * reduction once the block is assembled, so a value authored at the
+     * destination is reduced along with one this field read. Distinct from `code`,
+     * which is a Shortcode at both ends and resolves nothing.
+     */
+    address?: import("./address-fields.mjs").AddressPosition | undefined;
     /**
      * - For a field with no `name`:
      * the constant, or a function deriving it from the frontmatter.

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

@@ -1,8 +1,8 @@
 /**
  * An authored `parent` with any wikilink brackets and label stripped.
  *
- * The specification types `parent` as a `WikiLink`, and a frontmatter link is
- * written as a bare address — but `[[address]]` is what an author reaches for,
+ * The specification types `parent` as an `Address`, written bare — but
+ * `[[address]]` is what an author reaches for,
  * and Obsidian wrote that form for years. Accepting both costs one regex and
  * removes a failure whose message would have to explain the difference.
  *
@@ -56,14 +56,15 @@ export function collectFolderNotes(notes: Iterable<{
     absPath: string;
 }>, pkg: string): FolderNote[];
 /**
- * Index folder notes by every form an author may address one by, and check the
- * invariants that make the index sound.
- *
- * Three keys per folder, and no more: the canonical address, the
- * `folder-<shortcode>` short form, and the bare shortcode. They are the
- * suffixes of the canonical address the grammar admits — a `packFolder`
- * or `parent` field supplies the type itself, so a bare shortcode is a complete
- * address there.
+ * Index folder notes by their canonical address, and check the invariants
+ * that make the index sound.
+ *
+ * A folder reference is resolved by {@link parseAddress}, taking `folder` as
+ * the type an omitted segment fills in — the same suffix ladder every other
+ * position climbs, so `cooking`, `folder-cooking` and the full address all
+ * expand to the one key this index holds. A `packFolder` or `parent` field
+ * supplies no type of its own; the position's default is what makes a bare
+ * shortcode a complete address there.
  *
  * @param {FolderNote[]} folders - From {@link collectFolderNotes}.
  * @returns {{byKey: Map<string, FolderNote>, folders: FolderNote[],