@heroiclands/package-build 22.9.1 → 22.10.0

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

@@ -1,38 +1,3 @@
-/**
- * Every content type whose **prose compiles into a JournalEntry of its own**,
- * addressed by the virtual `doc<type>` qualifier.
- *
- * Every item type, every actor type, every map type, plus `macro` — a macro
- * note's body documents the script the note also compiles into a Macro, which
- * is the same shape as an item and its description: one note, two documents,
- * the prose living in the journals pack.
- *
- * **One set, read by the compiler and the emitter alike.** The journals pass
- * decides what to compile from it, and the link manifest decides what to
- * publish a `doc<type>` entry for. Held apart, the two drift into a manifest
- * that asserts documentation nothing compiled — or a compiled entry no
- * consumer can address. It is composed exactly once, in `defineConfig`, and
- * read from there — never recomposed at a call site.
- *
- * `doc` notes are absent, for the reason that applies to them alone: a `doc`
- * note's single document *is* its prose, so there is no second document for a
- * `doc<type>` address to name.
- *
- * An accessor rather than a hoisted constant, so that importing this module
- * needs no configuration (#2).
- *
- * @returns {ReadonlySet<string>} The configured doc-carrying types.
- */
-export function docEntryTypes(): ReadonlySet<string>;
-/**
- * Whether a content note's type is one whose prose becomes a JournalEntry of
- * its own.
- *
- * @param {string} type - The note's `type` frontmatter.
- * @returns {boolean} True for an item type, an actor type, a map type and
- *   `macro`; false for `doc`.
- */
-export function hasDocEntry(type: string): boolean;
 /**
  * The id of the JournalEntry a note's prose compiles into — an item's, or a
  * macro's.
@@ -72,3 +37,4 @@ export function itemDocEntryId(itemId: string): string;
 export function itemDocPointer(packageId: string, itemId: string, name: string, firstPageId: string): string;
 export { itemTypes };
 import { itemTypes } from "./item-registry.mjs";
+export { docEntryTypes, hasDocEntry } from "./address.mjs";

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

@@ -161,12 +161,12 @@ export function buildScene(fm: object, ctx: object): object;
  *   `bgImage` address by {@link buildScene}. Passed rather than resolved here,
  *   because an address is answered by the compile's index and this function
  *   takes none.
- * @param {(value: unknown, key: string, type: string) => string|null} [art] -
+ * @param {(value: unknown, key: string, type: string, accepts?: Iterable<string>) => string|null} [art] -
  *   The art resolver, for the foreground overlay. Omitted, a note naming one
  *   gets no overlay rather than a path nothing serves.
  * @returns {object} The Level document, keyed for the pack.
  */
-export function buildLevel(sohl: object, sceneId: string, img: string, art?: (value: unknown, key: string, type: string) => string | null): object;
+export function buildLevel(sohl: object, sceneId: string, img: string, art?: (value: unknown, key: string, type: string, accepts?: Iterable<string>) => string | null): object;
 /**
  * Compile the `walls:` and `doors:` blocks into Wall documents.
  *

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

@@ -0,0 +1,41 @@
+/**
+ * All declared Address positions of a note, including embedded notes.
+ * @param {object} fm - The note.
+ * @returns {object[]} Position descriptors with container shape and defaults.
+ */
+export function addressPositions(fm: object, context?: {}): object[];
+/**
+ * Decode declared properties at the note boundary. Raw mappings cannot impersonate tuples.
+ * @param {object} fm - Parsed YAML or an index record.
+ * @param {object} context - The builder's package and known types.
+ * @returns {object} The same note carrying typed Address properties.
+ */
+export function decodeNoteAddresses(fm: object, context: object): object;
+/**
+ * Read context supplied by the package configuration.
+ * @param {object} config - Resolved package configuration.
+ * @returns {object} Builder defaults and system declarations.
+ */
+export function noteAddressContext(config: object): object;
+/**
+ * Decode Address properties contributed by an index record.
+ * @param {object} record - The record.
+ * @param {object} context - Builder defaults.
+ * @returns {object} The typed record.
+ */
+export function decodeIndexAddresses(record: object, context: object): object;
+/** Structured positions whose Address is nested inside a declared container. */
+export const STRUCTURED_ADDRESSES: readonly ({
+    path: string[];
+    shape: string;
+    type: string;
+    accepts: string[];
+    noteType?: undefined;
+} | {
+    noteType: string;
+    path: string[];
+    shape: string;
+    type: string;
+    accepts: string[];
+})[];
+export { AddressEntries, encodeAddresses, cloneAddressState } from "./address-values.mjs";

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

@@ -279,7 +279,23 @@ 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" | "list" | "scalar-or-map" | undefined;
+    kind?: "string" | "number" | "boolean" | "map" | "list" | "scalar-or-map" | "address" | "shortcode" | undefined;
+    /**
+     * - Type of each list or pack-map value.
+     */
+    entryKind?: "address" | "shortcode" | undefined;
+    /**
+     * - Type of each map key.
+     */
+    keyKind?: "address" | "shortcode" | undefined;
+    /**
+     * - An alternative `subType:<skill-subtype>` key.
+     */
+    keySelector?: "subType" | undefined;
+    /**
+     * - Allowed Address types, separate from `ref`.
+     */
+    accepts?: readonly string[] | undefined;
     /**
      * - Human-readable shape, for a finding and for
      * documentation.
@@ -293,10 +309,11 @@ export type DataFieldSpec = {
      */
     entryShape?: string | undefined;
     /**
-     * - The type a bare value takes. An art slot declares
+     * - The Address's default type, an art slot declares
      * one — `icon` for `icon` and `tokenIcon`, `image` for `bgImage` and
      * `banner` — so `icon: anvil` names `icon-anvil` while a value carrying the
-     * separator states its own address.
+     * separator states its own address. Distinct from a `FieldSpec`'s `code`
+     * ({@link module :engine/field-spec}), which names a **Shortcode** instead.
      */
     ref?: string | undefined;
     /**

package/types/engine/place-relations.d.mts

@@ -9,7 +9,7 @@ export function oppositeBearing(bearing: unknown): string | undefined;
 /**
  * Check a place note's `data.borders`.
  *
- * Every `to` is a shortcode a place declares, every `bearing` is one of the
+ * Every `to` is an Address a place declares, every `bearing` is one of the
  * eight, no pair is listed twice, no target is the note's own parent or child,
  * and the other end states the pair back at the opposite bearing — a missing
  * reciprocal is a warning naming both notes, a wrong one an error.
@@ -38,6 +38,17 @@ export function checkBorders(note: object, { index }?: {
 export function checkRoutes(note: object, { index }?: {
     index?: object | undefined;
 }): object[];
+/**
+ * The type a border's or a route's `to` names.
+ *
+ * It is both the default its `<type>` segment takes when an author omits it and
+ * the whole of the set the position accepts, which is what makes `vylar` and
+ * `place-vylar` the same Address and a `to` naming a `lore` note an error rather
+ * than a lookup that quietly finds nothing.
+ *
+ * @type {string}
+ */
+export const RELATION_TYPE: string;
 /**
  * The eight compass bearings, clockwise from north.
  *

package/types/engine/populations.d.mts

@@ -1,3 +1,14 @@
+/**
+ * Read a fetched index entry into a node, or `null` where it takes no part.
+ *
+ * A fetched entry carries the structure its record stated and no figure, so
+ * a dependency's place sits in the geography and counts nobody.
+ *
+ * @param {string} canonical - The entry's address.
+ * @param {object} entry - The entry.
+ * @returns {PopulationNode|null} The node.
+ */
+export function foreignNode(canonical: string, entry: object): PopulationNode | null;
 /**
  * Check a place's population against the corpus around it.
  *
@@ -114,8 +125,12 @@ export type Corpus = {
      */
     holdersOf: Map<string, string[]>;
     /**
-     * `type-shortcode` → the node,
-     * for the citation rule.
+     * `type/shortcode` → the
+     * node, for the citation rule.
+     * Package-blind by design: a
+     * local note shadows a
+     * dependency's, so this is
+     * never a canonical Address.
      */
     byAddress: Map<string, PopulationNode>;
 };

package/types/engine/reference-targets.d.mts

@@ -0,0 +1,9 @@
+/**
+ * Names and published destinations for reference presentation.
+ * Stubs contribute names, never pages or documents. The published index
+ * remains separate so body-link validation retains its publication rules.
+ * @param {readonly object[]} records - Decoded local or fetched records.
+ * @param {Map<string, object>} [published] - Actual published link destinations.
+ * @returns {Map<string, object>} Canonical lookup keys and presentation values.
+ */
+export function buildReferenceTargets(records: readonly object[], published?: Map<string, object>): Map<string, object>;

package/types/engine/shortcode-references.d.mts

@@ -0,0 +1,14 @@
+/**
+ * Present a native Shortcode using its unique system/type target.
+ * Address properties never use this lookup. Multiple packages claiming the
+ * same native identity remain ambiguous. Documentation supplies links; the
+ * native target supplies a name even when its documentation is unpublished.
+ * @param {readonly Map<string, object>[]} indexes - Published identity indexes.
+ * @param {unknown} code - Native Shortcode.
+ * @param {{type: string, system: string}} hint - Its declared native namespace.
+ * @returns {object|undefined} Documentation presentation, or no unique target.
+ */
+export function resolveShortcodeReference(indexes: readonly Map<string, object>[], code: unknown, hint: {
+    type: string;
+    system: string;
+}): object | undefined;

package/types/engine/site-build.d.mts

@@ -111,7 +111,7 @@ export function writeHomepages(outRoot: string, pages: readonly object[], config
  * @param {object} options.config - The resolved build configuration.
  * @returns {object} The gate results and, when they pass, the built index.
  */
-export function siteGates(pages: object[], findings: object, { config }: {
+export function siteGates(pages: object[], findings: object, { config, records }: {
     config: object;
 }): object;
 /**
@@ -185,7 +185,7 @@ export function tableUniverse(pages: object[]): Map<string, object[]>;
  * @param {object} options
  * @param {(data: object, page: object) => void} [options.decorate] - Called
  *   with each page's frontmatter, for whatever a consumer's own pass adds.
- * @param {(value: unknown, type: string) => string|null} [options.artSrc] -
+ * @param {(value: unknown, type: string, accepts?: Iterable<string>) => string|null} [options.artSrc] -
  *   Translates an art address into the pathname the website resolver takes, or
  *   `null` where nothing answers it.
  * @param {(src: string) => string} [options.webSrc] - Translates an authored
@@ -196,7 +196,7 @@ export function tableUniverse(pages: object[]): Map<string, object[]>;
  */
 export function pageFrontmatter(page: object, { decorate, webSrc, artSrc }: {
     decorate?: ((data: object, page: object) => void) | undefined;
-    artSrc?: ((value: unknown, type: string) => string | null) | undefined;
+    artSrc?: ((value: unknown, type: string, accepts?: Iterable<string>) => string | null) | undefined;
     webSrc?: ((src: string) => string) | undefined;
 }): object;
 /**

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

@@ -13,7 +13,7 @@
  *   ordinary dead address.
  * @returns {SiteIndex} The index, and what could not be addressed unambiguously.
  */
-export function buildSiteIndex(entries: readonly SiteEntry[], { foreignIndex, noIndexPackages }?: {
+export function buildSiteIndex(entries: readonly SiteEntry[], { foreignIndex, noIndexPackages, package: builderPackage, records, foreignReferences, }?: {
     foreignIndex?: Map<string, {
         package: string;
         type?: string;
@@ -62,36 +62,15 @@ export function wikiContext(built: SiteIndex, { src, file, type, errors, foreign
     resolved?: object[] | undefined;
 }): object;
 /**
- * Resolve one infobox reference against a site index.
- *
- * A note writes a reference three ways and all three reach here: a bare
- * **shortcode** (`slntlncmpny`), a short **address** (`affiliation-slntlncmpny`)
- * and a **canonical** one (`sohl-sohl-skill-melee`). The first is the ordinary
- * case and the ambiguous one — a shortcode is unique within a type and not
- * across a tree — so a caller that knows what it expects passes `hint.type`
- * and the lookup is narrowed to it.
- *
- * **Without a hint the types are tried in sorted order**, so two trees holding
- * the same note resolve it the same way. A shortcode two types both claim
- * answers with the first alphabetically, which is a stable wrong answer rather
- * than an unstable one; a caller that cares supplies the hint.
- *
- * The `address` on the answer is the slug form — `type-shortcode` — because
- * that is what the book's own link map is keyed by and what a wikilink is
- * written as.
- *
- * @param {SiteIndex} siteIndex - The index.
- * @param {unknown} ref - The reference, as authored.
- * @param {object} [hint] - `{type}`, where the caller knows it.
- * @returns {{name?: string, url?: string, address?: string, subType?: string}|undefined}
- *   The page, or `undefined` where nothing answers.
+ * Resolve one Address against the site's canonical identity index.
+ * A bare Shortcode requires a declared default type. The returned Address is
+ * the complete tuple; URL and display name are presentation values.
+ * @param {SiteIndex} siteIndex - The site index.
+ * @param {unknown} ref - Tuple or authored reference.
+ * @param {object} [hint] - A declared default type.
+ * @returns {object|undefined} The matching page and tuple.
  */
-export function resolveInfoboxRef(siteIndex: SiteIndex, ref: unknown, hint?: object): {
-    name?: string;
-    url?: string;
-    address?: string;
-    subType?: string;
-} | undefined;
+export function resolveInfoboxRef(siteIndex: SiteIndex, ref: unknown, hint?: object): object | undefined;
 /**
  * One page the site will publish, as the index needs to see it.
  */

package/types/engine/sql-tables.d.mts

@@ -63,7 +63,7 @@ export function findSqlBlocks(markdown: string): Array<{
  * @returns {Promise<{query: (sql: string) => Promise<object[]>,
  *   close: () => Promise<void>}>} The open database.
  */
-export function openNotesDatabase(records: object[], { dir, dependencies }?: {
+export function openNotesDatabase(records: object[], { dir, dependencies, addressContext }?: {
     dir?: string | undefined;
     dependencies?: {
         id: string;
@@ -111,7 +111,7 @@ export function runSqlQuery(db: object, sql: string): Promise<{
 export function renderSqlTable(result: {
     columns: string[];
     rows: object[];
-}, { linkable, sectionLevel }?: {
+}, { linkable, sectionLevel, addressContext }?: {
     linkable?: ((ref: string) => boolean) | undefined;
     sectionLevel?: number | undefined;
 }): string;

package/types/engine/system-block.d.mts

@@ -140,6 +140,23 @@ export function legacyKeyOf(field: {
 export function retiredTopLevelKey(field: {
     name?: string;
 }): string | undefined;
+/**
+ * A shared source as the key an author writes, without the container holding it.
+ *
+ * `data.weight` is authored as `weight:` one level inside `data:`, so every
+ * question about the *note* rather than about the resolution order asks it under
+ * that spelling: which presentation overlay a row takes, which key a finding
+ * names, and whether two statements of one fact are the same fact. The
+ * specification's mapping tables write the whole path and a `data:` vocabulary
+ * writes the key, and this is what makes the two comparable.
+ *
+ * It takes a **name** rather than a declaration because both sides of that
+ * comparison reach it: one holds a field, the other a row of a table.
+ *
+ * @param {string|undefined} name - The shared source, as either side spells it.
+ * @returns {string} The key, without the container.
+ */
+export function authoredKey(name: string | undefined): string;
 /**
  * Where a declared field's value came from.
  *

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

@@ -0,0 +1,16 @@
+/**
+ * Systems named by package declarations and pack targets.
+ * @param {object} [config] - Resolved build configuration.
+ * @returns {string[]} Declared system identifiers.
+ */
+export function declaredSystems(config?: object): string[];
+/**
+ * System field vocabularies supplied by the configuration and caller.
+ * @param {object} [config] - Resolved build configuration.
+ * @param {object} [options] - Caller schema context.
+ * @param {string} [options.schemaSystem] - Owner of the caller's schemas.
+ * @returns {object} System block declarations.
+ */
+export function systemBlocksFor(config?: object, { schemaSystem }?: {
+    schemaSystem?: string | undefined;
+}): object;

package/types/engine/wikilink-syntax.d.mts

@@ -167,6 +167,13 @@ export function linkFindingMessage({ reason, target, packages, anchor, type, stu
  * @returns {boolean} True when the link is same-page.
  */
 export function isSamePage({ target, anchor }: ParsedWikilink): boolean;
+/**
+ * Read an operational link target in its enclosing Address context.
+ * @param {string} inner - Lexical link contents.
+ * @param {object} context - Builder defaults and type vocabulary.
+ * @returns {object} Typed target and diagnostic source spelling.
+ */
+export function readWikilink(inner: string, context: object): object;
 /**
  * What a `[[…]]` **is**, before anything decides where it points.
  *

package/types/engine/wikilinks.d.mts

@@ -1,108 +1,3 @@
-/**
- * Reads a qualifier as the **virtual `doc<type>`** form, or reports that it is
- * not one.
- *
- * A document and its documentation are two documents in two packs, so they
- * need two addresses. `skill/wpnc` is the item; `docskill/wpnc` is the
- * JournalEntry its prose compiled into, and `docmacro/autoattack` is the same
- * arrangement for a macro.
- *
- * The virtual form exists for a type that carries separate documentation
- * ({@link sohl.utils.packs.docEntryTypes} — the set the journals compiler and
- * the link manifest read too), **or** for one that routes to the items pack.
- * The second clause is the older rule and stays: types that compile into items
- * are the open, unenumerated set, and a foreign package may publish an
- * item type this build has never heard of. Dropping it would silently unlink
- * every `doc<type>` address into such a package.
- *
- * A **real** type of the same name always wins: the virtual reading is only
- * consulted for a qualifier no authored note claims.
- *
- * @param {string} qualifier - The already-normalised text before the `/`.
- * @param {Set<string>} types - Every type the content tree contains.
- * @returns {string|null} The underlying document type, or `null` when the
- *   qualifier is not a virtual one.
- */
-export function resolveItemDocType(qualifier: string, types: Set<string>): string | null;
-/**
- * Read a link target as a **qualified** `type-shortcode` reference, or report
- * that it does not parse as one.
- *
- * Two separators are accepted, and they are **not** interchangeable in how
- * confidently they mark a target as qualified:
- *
- * - **`type-shortcode`** and its qualified forms — the canonical spelling.
- * Obsidian reads `/` inside a wikilink as a *path* and resolves it
- *   against the vault's folders, so a slash-qualified link is a broken link in
- *   the editor where the content is now authored.
- * - **`type/shortcode`** — the legacy form, still resolved so that a link
- *   written before the vault migrated does not silently die. A slash is
- *   *unconditionally* a qualifier: nothing else uses one, so an unknown type
- *   before it is reported rather than guessed at. The split is at the **last**
- *   slash, as it always was.
- *
- * **The grammar is strict, and omission runs left to right**:
- *
- * ```text
- * [[[[<package>-]<system>-]<type>-]<shortcode>]
- * ```
- *
- * So the written forms are exactly the suffixes of the canonical address —
- * `type-shortcode`, `system-type-shortcode`, `package-system-type-shortcode` —
- * and **`package-type-shortcode` is not one of them**. A link into another
- * package must therefore be fully qualified, which is the price of the segment
- * being positional rather than tagged.
- *
- * **Parsing is plain positional counting**, the same rule
- * {@link readCanonicalKey} follows, and it is sound for the same reason: every
- * segment matches `ADDRESS_SEGMENT_PATTERN` (enforced on shortcodes by
- * `content-lint.mjs`), so the hyphen is purely a
- * separator and the count alone determines every field. Verified across the
- * four content trees: 138,204 authored shortcodes, none carrying a separator.
- *
- * That replaced a first-hyphen split which let a shortcode contain a hyphen
- * (`trauma-self-pro` → `trauma` + `self-pro`). The tolerance predates the
- * charset rule and
- * outlived it; no tree has used it, and keeping it would make a three-segment
- * target ambiguous between a system and a hyphenated shortcode.
- *
- * **`sohl` is both a package and a system**, and positional counting is what
- * makes that harmless: three segments is `<system>-<type>-<shortcode>` whatever
- * the first segment could also have named, and four is the full form. Nothing
- * has to guess which sense was meant.
- *
- * **A partial address states what it states, and the rest is not invented.** An
- * omitted **system** is a *wildcard* — most links target items, which belong to
- * a system — so the caller matches on the segments supplied and requires
- * exactly one hit. An omitted **package** is instead *defaulted* to the citing
- * note's own, so an unqualified link resolves locally and only locally.
- *
- * @param {string} target - The link target, anchor already removed.
- * @param {Set<string>} types - Every type the content tree contains.
- * @param {Set<string>} [packages] - Every package an address may name. Omitted
- *   by callers that resolve within one package, where the form cannot occur.
- * @param {Set<string>} [noIndexPackages] - Packages declared `contentIndex:
- *   false` — a Foundry dependency only, with no fetched index. A fully
- *   qualified target naming one is refused with `no-content-index` before its
- *   type is even considered, since there is no index to resolve it against.
- * @returns {{type: string, shortcode: string, itemDoc: boolean,
- *   package?: string, system?: string, reason?: undefined}
- *   | {reason: "unknown-type"|"no-content-index", package?: string} | null}
- *   The resolved qualifier; a `reason` when the target is definitely qualified
- *   but names no known type or no fetched index; or `null` when it is not an
- *   address at all.
- */
-export function readQualifier(target: string, types: Set<string>, packages?: Set<string>, noIndexPackages?: Set<string>): {
-    type: string;
-    shortcode: string;
-    itemDoc: boolean;
-    package?: string;
-    system?: string;
-    reason?: undefined;
-} | {
-    reason: "unknown-type" | "no-content-index";
-    package?: string;
-} | null;
 /**
  * The deterministic JournalEntryPage id for one anchor: SHA-256 of
  * `"<noteId>-<anchorSlug>"`, base64-encoded, reduced to the 16 alphanumeric
@@ -157,7 +52,7 @@ export function buildWikilinkIndex(docs: Array<{
     docPack?: string;
     none?: boolean;
     draft?: boolean;
-}>, packageId: string, foreign?: Map<string, object>, contentPackage?: string, { assets, noIndexPackages }?: {
+}>, packageId: string, foreign?: Map<string, object>, contentPackage?: string, { assets, noIndexPackages, referenceTargets, foreignReferences }?: {
     assets?: Map<string, object> | undefined;
     noIndexPackages?: Set<string> | undefined;
 }): {
@@ -232,16 +127,18 @@ export function convertWikilinks(markdown: string, { type, id, pack, docPack, in
  * @param {object} index - From {@link buildWikilinkIndex}.
  * @param {unknown} ref - The reference, as authored.
  * @param {object} [hint] - `{type}`, where the caller knows what it expects.
- * @returns {{name?: string, uuid?: string, address?: string, subType?: string}|undefined}
+ * @returns {{name?: string, uuid?: string, address?: import("./address.mjs").AddressTuple, subType?: string}|undefined}
  *   The target, or `undefined` where nothing answers.
  */
 export function resolveReference(index: object, ref: unknown, hint?: object): {
     name?: string;
     uuid?: string;
-    address?: string;
+    address?: import("./address.mjs").AddressTuple;
     subType?: string;
 } | undefined;
 import { ITEM_PACK } from "./ids.mjs";
 import { PACK_BY_TYPE } from "./ids.mjs";
 import { packForType } from "./ids.mjs";
-export { ITEM_PACK, PACK_BY_TYPE, packForType };
+import { readQualifier } from "./address.mjs";
+import { resolveItemDocType } from "./address.mjs";
+export { ITEM_PACK, PACK_BY_TYPE, packForType, readQualifier, resolveItemDocType };

package/types/hm3/item-fields.d.mts

@@ -7,6 +7,11 @@
  * a registry is addressed by what a note calls itself. What the document is
  * called is the map's answer, and only the map's.
  *
+ * Each field names both of its authored positions, as
+ * {@link module:hm3/actors} does and for the same reason: `name` is the shared
+ * source the content format's mapping tables state, and `legacyKey` is the key
+ * the `hm3:` block still carries.
+ *
  * @type {Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>}
  */
 export const HM3_ITEM_FIELDS: Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>;

package/types/sohl/infobox.d.mts

@@ -2,11 +2,10 @@
  * What one entry of `sohl.items` names.
  *
  * An entry addresses its item three ways and every tree uses all three: a
- * `model` address whose last two hyphen-separated segments are always
- * `<type>-<shortcode>`, explicit `type` / `shortcode` keys, or a locally
- * authored item stating its type with the shortcode inside its own `system`
- * block. One decode covers all of them, so nothing downstream has to know
- * which form a note happened to use.
+ * `model` address, explicit `type` / `shortcode` keys, or a locally authored
+ * item stating its type with the shortcode inside its own `system` block. One
+ * decode covers all of them, so nothing downstream has to know which form a
+ * note happened to use.
  *
  * @param {object} entry - One `sohl.items` entry.
  * @returns {{type: string, shortcode: string, name: string, system: object}|undefined}

package/types/sohl/item-fields.d.mts

@@ -2,6 +2,14 @@
  * Every item type's frontmatter vocabulary, in the order the `system` block
  * emits it.
  *
+ * **A field whose shared source is a path into `data:` names both positions.**
+ * `name` is the source the content format's mapping tables state — `data.seat`,
+ * `data.weight` — and `legacyKey` is the key the system block still carries, which
+ * wins while a tree writes it. Naming only the source would move the in-block
+ * read to a key spelled `data.seat`, which nothing authors; naming only the key
+ * leaves the container the specification points at unread, and the field then
+ * compiles its default over an authored value with nothing said.
+ *
  * @type {Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>}
  */
 export const ITEM_FIELDS: Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>;