@heroiclands/package-build 22.9.1 → 22.10.0

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,26 @@ 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 and the emitted one is its Shortcode.** 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 +540,31 @@ 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 and the emitted one is its Shortcode.** 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[],

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

@@ -1,97 +1,3 @@
-/**
- * What one system block accepts beyond the keys every block carries.
- *
- * @typedef {object} SystemBlockSpec
- * @property {readonly string[]} [known] - Keys stated outright.
- * @property {boolean} [fieldVocabulary] - Whether the note type's declared field
- *   names, as the caller's `schemas` state them, are keys of this block.
- * @property {Readonly<Record<string, readonly object[]>>} [fields] - Type → this
- *   system's own declared fields. A type it does not name is a type this system
- *   says nothing about, and its block is left unchecked on such a note rather
- *   than reported wholesale.
- */
-/**
- * Every system a configuration says its tree carries.
- *
- * **Which systems a package ships for is already declared**, in three places
- * that answer different questions, so this reads all three rather than asking a
- * new one:
- *
- * - `systems:` declares them without requiring one, which is how a
- *   package ships for several;
- * - a **pack's** `system:` is the same statement made per pack, and it is the
- *   one some trees make: `harn-ensemble` declares an `actors-sohl` and an
- *   `actors-hm3` and nothing else about either system. It is already
- *   authoritative elsewhere — `eligibleFor` fails a note for want of the block
- *   a pack's `system:` names — so a lint that did not read it would refuse a
- *   note at compile for a block it never checked;
- * - `stats.systemId` is the package-wide answer where there is one, and it has
- *   already absorbed every way of spelling that: a system package is its own
- *   system, and a module takes `requiresSystem`, its lone `systems:` entry, or
- *   its lone system relationship.
- *
- * A package naming a system in none of them is system-agnostic on purpose — its
- * packs are core document types carrying no system data — so it carries no
- * system block and naming one would invent it.
- *
- * @param {object} [config] - A resolved configuration from `defineConfig`.
- * @returns {string[]} The system ids, deduplicated, in declared order.
- */
-export function declaredSystems(config?: object): string[];
-/**
- * The system blocks a configuration says its tree carries, and what each
- * accepts.
- *
- * The lint checks the blocks its caller names, and for as long as there was one
- * system the only caller named none — so every tree took the `sohl:` of
- * {@link DEFAULT_SYSTEM_BLOCKS}, a constant, in a module whose whole discipline
- * is that it states no vocabulary of its own. That is wrong in both directions
- * the moment a second system exists, and the second direction is the worse:
- *
- * - a package shipping for `hm3` had its `hm3:` block **never looked at**, so
- *   every key in it was discarded at compile without a word — the silent-drop
- *   family this check exists to close;
- * - and the block that *was* checked was named after a system that package does
- *   not ship for, so the one finding it could make was about nothing.
- *
- * **A block's vocabulary has two sources, and a system may have both.**
- *
- * - The **note schemas** the caller hands in as `schemas`. Those belong to one
- *   system — the CLI imports `sohl/note-schemas.mjs` — and `schemaSystem` is the
- *   caller naming which, because only the caller knows. It is the only source
- *   that reaches a type no item registry declares, which is to say `being`: the
- *   2,512 notes `harn-ensemble` is made of, and the reason this is not an
- *   optional refinement.
- * - The system's **own registry**, `itemFieldsBySystem`, keyed by system and
- *   until now read by nothing. This is what a *second* system's block is held
- *   to, since the note schemas describe its neighbour.
- *
- * A system with neither is left out: nothing can state what its block may
- * carry, and holding it to an empty vocabulary would report every key in a
- * correct tree. **That is a check that does not run**, which is
- * indistinguishable from one that passed, so the caller says it out loud —
- * {@link declaredSystems} is the other half of that comparison. `harn-ensemble`
- * is the tree it names: two systems, and an `itemBuilders` registry for
- * neither, so its `hm3:` block is unchecked until it declares one.
- *
- * An earlier draft of this took the note schemas for a system's vocabulary only
- * where the package declared **one** system, on the reasoning that with several
- * there is nothing to say which one they describe. There is: the caller, which
- * chose them. The guess cost `harn-ensemble` its whole `sohl:` check — two
- * systems declared, so the fallback never fired — which is the coverage this
- * change exists to widen rather than narrow.
- *
- * @param {object} [config] - A resolved configuration from `defineConfig`.
- * @param {object} [options] - Options.
- * @param {string} [options.schemaSystem] - The system whose vocabulary the
- *   caller's `schemas` state. There are two systems, not an open set, so this is
- *   one word from the caller rather than a mechanism.
- * @returns {Readonly<Record<string, SystemBlockSpec>>} The blocks to check, in
- *   declared order. A system nothing states the vocabulary of is absent.
- */
-export function systemBlocksFor(config?: object, { schemaSystem }?: {
-    schemaSystem?: string | undefined;
-}): Readonly<Record<string, SystemBlockSpec>>;
 /**
  * Whether a value satisfies a declared {@link FieldSpec.kind}.
  *
@@ -103,9 +9,10 @@ export function systemBlocksFor(config?: object, { schemaSystem }?: {
  *
  * @param {unknown} value - The authored value.
  * @param {string} kind - The declared kind.
+ * @param {object} [context] - Complete Address defaults and known type vocabulary.
  * @returns {boolean} Whether it is acceptable.
  */
-export function matchesKind(value: unknown, kind: string): boolean;
+export function matchesKind(value: unknown, kind: string, context?: object): boolean;
 /**
  * Check one note against its type's schema.
  *
@@ -113,7 +20,7 @@ export function matchesKind(value: unknown, kind: string): boolean;
  * @param {object} opts
  * @param {Record<string, readonly object[]>} opts.schemas - Type → declaration.
  * @param {object} [opts.index] - The link index, for the reference check, which
- *   runs through its `referenceHit`. Its absence skips that check rather than
+ *   runs through its `shortcodeHit`. Its absence skips that check rather than
  *   reporting every reference as dead.
  * @param {Record<string, object>} [opts.vocabulary] - Type → the closed regions
  *   it declares, as `engine/note-vocabulary.mjs` states them. Supplied
@@ -132,13 +39,14 @@ export function matchesKind(value: unknown, kind: string): boolean;
  *   for the same reason `schemas` is — a build derives them from its
  *   configuration through {@link systemBlocksFor}, and this module states no
  *   system name of its own. See {@link DEFAULT_SYSTEM_BLOCKS} for the fallback.
+ * @param {object} [opts.addressContext] - Builder package and Address type vocabulary.
  * @param {readonly string[]} [opts.packs] - The pack names this package
  *   declares, for a `data:` field whose map is keyed by pack. Supplied by the
  *   caller like `schemas` and `vocabulary`, and absent it no claim is made
  *   about those keys.
  * @returns {object[]} Findings, each with a locator where one is obtainable.
  */
-export function lintNote(note: object, { schemas, index, vocabulary, packs, emittedArt, systems }: {
+export function lintNote(note: object, { schemas, index, vocabulary, packs, emittedArt, addressContext, systems, }: {
     schemas: Record<string, readonly object[]>;
     index?: object | undefined;
     vocabulary?: Record<string, object> | undefined;
@@ -147,6 +55,7 @@ export function lintNote(note: object, { schemas, index, vocabulary, packs, emit
         art: readonly string[];
     } | null) | undefined;
     systems?: Readonly<Record<string, SystemBlockSpec>> | undefined;
+    addressContext?: object | undefined;
     packs?: readonly string[] | undefined;
 }): object[];
 /**
@@ -280,3 +189,4 @@ export type SystemBlockSpec = {
      */
     fields?: Readonly<Record<string, readonly object[]>> | undefined;
 };
+export { declaredSystems, systemBlocksFor } from "./system-vocabulary.mjs";

package/types/engine/frontmatter.d.mts

@@ -32,16 +32,31 @@ export function sohlField(fm: any, key: any, defaultValue?: undefined): any;
  * has to be told both. It is the same split `FieldSpec.name`/`legacyKey` makes,
  * for the same reason — one name cannot key two positions.
  *
+ * `shared` is the field's declared shared source, and it completes the order the
+ * three other positions are two thirds of. A field whose source is a path into
+ * `data:` is authored there by the specification's own mapping tables, and a
+ * reader that knew the destination, the block and the top level alone skipped
+ * straight past the container: every authored value read as unset, and the
+ * document shipped the field's default with nothing said. It sits **between**
+ * the block and the top level, exactly where
+ * {@link module:engine/system-block.resolveFieldValue} puts it — the block is the
+ * position a tree still writes and wins while it does, and the bare top-level
+ * key is the spelling `data:` gathered the fact off.
+ *
  * @param {object} fm - The note's frontmatter.
  * @param {string} to - The key at the destination, dotted for a nested one.
  * @param {any} [defaultValue] - What an unauthored field reads as.
  * @param {object} [options] - Options.
  * @param {string} [options.legacyKey] - The key the block still carries, when
  *   it is not spelled `to`. Defaults to `to`.
+ * @param {string} [options.shared] - The field's declared shared source, when it
+ *   is a path into a container (`data.relations`). Omitted by a field whose
+ *   shared position is the note's top level, which `sohlField` already reads.
  * @returns {any} The value.
  */
-export function sohlSystemField(fm: object, to: string, defaultValue?: any, { legacyKey }?: {
+export function sohlSystemField(fm: object, to: string, defaultValue?: any, { legacyKey, shared }?: {
     legacyKey?: string | undefined;
+    shared?: string | undefined;
 }): any;
 /**
  * Resolve the `charges` block shared by Mystery and Mystical Ability items.

package/types/engine/helpers.d.mts

@@ -10,7 +10,7 @@
  * `{ frontmatter: null, body: "", description: "" }` with a warn log, and no
  * position: there is no body to have one.
  */
-export function parseMarkdownFile(filePath: any): {
+export function parseMarkdownFile(filePath: any, { addressContext }?: {}): {
     frontmatter: null;
     body: string;
     description: string;
@@ -85,7 +85,7 @@ export function assertSuppliedCorpus(records: readonly object[] | undefined, who
  * @throws {Error} When `skipDirectories` is not stated — see
  *   {@link assertStatedScope}.
  */
-export function walkMarkdownTree(rootDir: string, { skipDirectories }?: {
+export function walkMarkdownTree(rootDir: string, { skipDirectories, addressContext }?: {
     skipDirectories: readonly string[];
 }): Generator<{
     file: string & NonSharedBuffer;

package/types/engine/infobox.d.mts

@@ -5,6 +5,12 @@
  * `<type>.<field>` wins over the bare name, so a spelling two types use for two
  * quantities can be said differently on each without splitting the overlay.
  *
+ * **Keyed by the key an author writes, not by the path a declaration names.**
+ * One fact has two declarations — the note vocabulary's `weight` and an item
+ * field's `data.weight` — and the overlay says what a *reader* is shown, which
+ * is one word either way. So the container is dropped before the lookup, and
+ * `GEAR_UNITS` answers for both sides with one entry.
+ *
  * @param {Readonly<Record<string, object>>} presentation - The overlay.
  * @param {string|undefined} type - The note's type.
  * @param {string} name - The field's declared name.