@heroiclands/package-build 22.9.2 → 22.10.0

package/sohl/infobox.mjs

@@ -51,6 +51,8 @@
  * @module
  */
 
+import { parseAddress, isAddressTuple, completeAddress } from "../engine/address.mjs";
+import { contentPackage } from "../engine/content-package.mjs";
 import {
     DURATION_LABELS,
     GEAR_UNITS,
@@ -63,6 +65,8 @@ import {
 import { currentType } from "../engine/ids.mjs";
 import { subTypes } from "../engine/note-vocabulary.mjs";
 import { systemBlock, systemData } from "../engine/system-block.mjs";
+import { readCanonicalKey } from "../engine/content-address.mjs";
+import { readQualifier } from "../engine/address.mjs";
 import { NOTE_SCHEMAS } from "./note-schemas.mjs";
 import { GEAR_TYPE_TO_KEY } from "./being-info.mjs";
 
@@ -174,15 +178,45 @@ function isMapping(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
+/**
+ * Every content type `model:` may name — the note vocabulary this system
+ * declares, engine types included.
+ *
+ * @type {ReadonlySet<string>}
+ */
+const MODEL_TYPES = new Set(Object.keys(NOTE_SCHEMAS));
+
+/**
+ * The `(type, shortcode)` an entry's `model:` names, or `undefined`.
+ *
+ * `model` is an Address, read by the same grammar every wikilink is —
+ * `type-shortcode` within this package, `package-system-type-shortcode` to
+ * name a dependency's catalogue. This decode answers neither of the two
+ * questions {@link module:engine/address} asks about the package: a runtime
+ * lookup among one actor's embedded items resolves by `(type, shortcode)`
+ * alone, where packages do not exist, so a fully qualified `model` is read for
+ * its last two segments exactly as a bare one is.
+ *
+ * @param {unknown} model - The authored value.
+ * @returns {{type: string, shortcode: string}|undefined} What it names.
+ */
+function modelAddress(model) {
+    const target = parseAddress(
+        model,
+        { package: contentPackage(), system: "sohl", types: MODEL_TYPES },
+        { declared: true, legacyShortcodeCase: true },
+    );
+    return target.reason ? undefined : target;
+}
+
 /**
  * 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}
@@ -190,19 +224,21 @@ function isMapping(value) {
  */
 export function decodeItem(entry) {
     if (!isMapping(entry)) return undefined;
+    const address = entry.model ? modelAddress(entry.model) : undefined;
     let type = typeof entry.type === "string" ? entry.type : "";
     let shortcode = typeof entry.shortcode === "string" ? entry.shortcode : "";
-    if (!type && typeof entry.model === "string") {
-        const segments = entry.model.split("-");
-        if (segments.length >= 2) {
-            type = segments[segments.length - 2];
-            if (!shortcode) shortcode = segments[segments.length - 1];
+    if (!type) {
+        const named = address;
+        if (named) {
+            type = named.type;
+            if (!shortcode) shortcode = named.shortcode;
         }
     }
     const system = isMapping(entry.system) ? entry.system : {};
     if (!shortcode && typeof system.shortcode === "string") shortcode = system.shortcode;
     if (!type) return undefined;
     return {
+        ...(address ? { address } : {}),
         type: currentType(type),
         shortcode,
         name: typeof entry.name === "string" ? entry.name : "",
@@ -222,6 +258,32 @@ function itemsOf(fm, block) {
     return (Array.isArray(declared) ? declared : []).map(decodeItem).filter(Boolean);
 }
 
+/**
+ * A model's documentation presentation, with its native name as plain text
+ * when no documentation is published. The model keeps its native identity.
+ * @param {object} item - Decoded native item.
+ * @param {Function} resolve - The medium's reference resolver.
+ * @param {string} block - The native system.
+ * @returns {object|undefined} Documentation links and display metadata.
+ */
+function itemPresentation(item, resolve, block) {
+    if (!item.shortcode) return undefined;
+    if (!item.address)
+        return resolve?.(item.shortcode, { kind: "shortcode", type: item.type, system: block });
+    const documentation = completeAddress({ ...item.address, system: "none" });
+    const found = resolve?.(documentation, { type: documentation.type });
+    const native =
+        !found?.name || !found?.subType ? resolve?.(item.address, { type: item.type }) : undefined;
+    if (!found && !native) return undefined;
+    return {
+        name: found?.name ?? native?.name,
+        subType: found?.subType ?? native?.subType,
+        address: documentation,
+        ...(found?.url ? { url: found.url } : {}),
+        ...(found?.uuid ? { uuid: found.uuid } : {}),
+    };
+}
+
 /**
  * One item as a value a renderer can draw: its name, and a link where the
  * index reached it.
@@ -229,10 +291,11 @@ function itemsOf(fm, block) {
  * @param {object} item - A decoded item.
  * @param {(ref: unknown, hint?: object) => object|undefined} resolve - The
  *   medium's resolver.
- * @returns {{text: string, url?: string, uuid?: string, address?: string}} The value.
+ * @param {string} block - The native system.
+ * @returns {{text: string, url?: string, uuid?: string, address?: import("../engine/address.mjs").AddressTuple}} The value.
  */
-function itemValue(item, resolve) {
-    const found = item.shortcode ? resolve?.(item.shortcode, { type: item.type }) : undefined;
+function itemValue(item, resolve, block) {
+    const found = itemPresentation(item, resolve, block);
     const value = { text: item.name || found?.name || humanizeValue(item.shortcode) };
     if (found?.url) value.url = found.url;
     if (found?.uuid) value.uuid = found.uuid;
@@ -277,9 +340,9 @@ export function beingSections(fm, { block, resolve }) {
         if (item.type !== "skill") continue;
         const mastery = item.system.masteryLevelBase;
         if (!hasValue(mastery)) continue;
-        const found = item.shortcode ? resolve?.(item.shortcode, { type: "skill" }) : undefined;
+        const found = itemPresentation(item, resolve, block);
         const family = item.system.subType ?? found?.subType;
-        const value = itemValue(item, resolve);
+        const value = itemValue(item, resolve, block);
         const entry = { ...value, text: `${value.text} ${mastery}` };
         if (family && families.has(family)) families.get(family).push(entry);
         else unplaced.push(entry);
@@ -298,7 +361,7 @@ export function beingSections(fm, { block, resolve }) {
     const mystical = [];
     for (const item of items) {
         if (item.type !== "mysticalability") continue;
-        mystical.push(itemValue(item, resolve));
+        mystical.push(itemValue(item, resolve, block));
     }
     if (mystical.length) {
         sections.push({
@@ -313,7 +376,7 @@ export function beingSections(fm, { block, resolve }) {
     for (const item of items) {
         const key = GEAR_TYPE_TO_KEY[item.type];
         if (!key) continue;
-        gear.get(key).push(itemValue(item, resolve));
+        gear.get(key).push(itemValue(item, resolve, block));
     }
     const gearGroups = [];
     for (const [key, entries] of gear) {

package/sohl/item-fields.mjs

@@ -35,6 +35,7 @@
  * @module
  */
 
+import { isAddressTuple } from "../engine/address.mjs";
 import {
     AS_AUTHORED,
     BLANK_IS_DEFAULT,
@@ -143,14 +144,48 @@ const SKILL_APTITUDES = Object.freeze({
     read: (_raw, { fm }) => resolveSkillAptitudes(fm, noteContext(fm, "mystery")),
 });
 
+/* --------------------------------------------------------------------- */
+/*  The Address positions                                                 */
+/* --------------------------------------------------------------------- */
+
+/*
+ * An affiliation names other notes in four of its fields, and each of those
+ * values is an **Address** — written at whatever length says what it means —
+ * while the compiled Item holds the **Shortcode** the runtime resolves among
+ * one actor's items. `engine/address-fields.mjs` is the step between them, and
+ * these are the positions it reads.
+ *
+ * Each states two things, and they are not the same statement: `type` is the
+ * default an omitted `<type>` segment takes, and `accepts` is the set of types
+ * the field takes at all. They coincide at all four, which is the common case
+ * rather than the rule — an art slot defaults to `icon` and accepts `icon` or
+ * `image` — so each is written out rather than derived from the other.
+ */
+
+/** One place: an affiliation's seat. */
+const PLACE_VALUE = Object.freeze({ type: "place", accepts: Object.freeze(["place"]) });
+
+/** A list of places: the ones an affiliation holds sway over. */
+const PLACE_ITEMS = Object.freeze({ ...PLACE_VALUE, holds: "items" });
+
+/** A list of affiliations: the ones this affiliation answers to. */
+const AFFILIATION_ITEMS = Object.freeze({
+    type: "affiliation",
+    accepts: Object.freeze(["affiliation"]),
+    holds: "items",
+});
+
+/** A map keyed by affiliation: this one's standing toward each. */
+const AFFILIATION_KEYS = Object.freeze({ ...AFFILIATION_ITEMS, holds: "keys" });
+
 /** Standings toward other affiliations, validated against the closed list. */
 const RELATION = Object.freeze({
-    shape: "map of affiliation shortcode → standing",
+    shape: "map of affiliation address → standing",
     read: (_raw, { fm }) => resolveRelation(fm, noteContext(fm, "affiliation")),
 });
 
 /**
- * A list of references, each a bare shortcode.
+ * A list of references, each an address.
  *
  * Blank entries are dropped rather than emitted: a list that has been edited
  * down in a property editor keeps its empty rows, and an empty string is not a
@@ -158,15 +193,15 @@ const RELATION = Object.freeze({
  * value here — a sovereign polity is subordinate to nobody — rather than an
  * unset one.
  */
-const SHORTCODE_LIST = Object.freeze({
-    shape: "list of shortcodes",
+const ADDRESS_LIST = Object.freeze({
+    shape: "list of addresses",
     kind: "list",
     read: (raw) =>
         (Array.isArray(raw) ? raw
         : raw == null || raw === "" ? []
         : [raw]
         )
-            .map((entry) => String(entry ?? "").trim())
+            .map((entry) => (isAddressTuple(entry) ? entry : String(entry ?? "").trim()))
             .filter((entry) => entry !== ""),
 });
 
@@ -237,7 +272,8 @@ const GEAR_COMMON = Object.freeze([
         describe: "How many the stack holds. A compendium article ships one.",
     },
     {
-        name: "weight",
+        name: "data.weight",
+        legacyKey: "weight",
         to: "weightBase",
         ...AS_AUTHORED,
         kind: "number",
@@ -245,7 +281,8 @@ const GEAR_COMMON = Object.freeze([
         describe: "Weight of one, in pounds.",
     },
     {
-        name: "value",
+        name: "data.value",
+        legacyKey: "value",
         to: "valueBase",
         ...AS_AUTHORED,
         kind: "number",
@@ -253,7 +290,8 @@ const GEAR_COMMON = Object.freeze([
         describe: "Worth of one, in pence.",
     },
     {
-        name: "quality",
+        name: "data.quality",
+        legacyKey: "quality",
         to: "qualityBase",
         ...AS_AUTHORED,
         kind: "number",
@@ -261,7 +299,8 @@ const GEAR_COMMON = Object.freeze([
         describe: "Craftsmanship, as a modifier to what the article does.",
     },
     {
-        name: "durability",
+        name: "data.durability",
+        legacyKey: "durability",
         to: "durabilityBase",
         ...AS_AUTHORED,
         kind: "number",
@@ -293,6 +332,14 @@ const GEAR_COMMON = Object.freeze([
  * 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 = Object.freeze({
@@ -341,9 +388,11 @@ export const ITEM_FIELDS = Object.freeze({
         {
             // Plural because the field holds a map of many standings, one per
             // affiliation — the singular reads as a misnomer.
-            name: "relations",
+            name: "data.relations",
+            legacyKey: "relations",
             to: "relations",
             ...RELATION,
+            address: AFFILIATION_KEYS,
             default: {},
             describe: "How this society regards others: aligned, unaligned, rival or nemesis.",
         },
@@ -351,21 +400,25 @@ export const ITEM_FIELDS = Object.freeze({
             // The organisational relation: which bodies this one answers to.
             // A list, because an affiliation may sit under more than one at
             // once — an arcane tradition within an order, say.
-            name: "parents",
+            name: "data.parents",
+            legacyKey: "parents",
             to: "parents",
-            ...SHORTCODE_LIST,
+            ...ADDRESS_LIST,
+            address: AFFILIATION_ITEMS,
             default: [],
-            describe: "Affiliations this one is subordinate to, by shortcode.",
+            describe: "Affiliations this one is subordinate to, by address.",
         },
         {
             // Not `capital` or `headquarters`: each fits about half the eleven
             // subTypes, while a seat covers a polity, a guild, an order and a
             // faith alike.
-            name: "seat",
+            name: "data.seat",
+            legacyKey: "seat",
             to: "seat",
             ...BLANK_IS_NULL,
+            address: PLACE_VALUE,
             default: null,
-            describe: "Where the affiliation's authority sits, by place shortcode.",
+            describe: "Where the affiliation's authority sits, by place address.",
         },
         {
             // The geographic relation, kept apart from the organisational one
@@ -375,11 +428,13 @@ export const ITEM_FIELDS = Object.freeze({
             // mapping row states (`data.domains` → `system.domain`). The two
             // spellings are deliberate rather than a slip, so the declaration
             // carries both rather than either side guessing.
-            name: "domains",
+            name: "data.domains",
+            legacyKey: "domains",
             to: "domain",
-            ...SHORTCODE_LIST,
+            ...ADDRESS_LIST,
+            address: PLACE_ITEMS,
             default: [],
-            describe: "Places this affiliation holds sway over, by shortcode.",
+            describe: "Places this affiliation holds sway over, by address.",
         },
     ]),
 
@@ -418,14 +473,16 @@ export const ITEM_FIELDS = Object.freeze({
             describe: "How readily the host throws it off.",
         },
         {
-            name: "contagionIndex",
+            name: "data.contagionIndex",
+            legacyKey: "contagionIndex",
             to: "contagionIndexBase",
             ...NUMBER,
             default: 0,
             describe: "How readily it passes to someone else.",
         },
         {
-            name: "transmission",
+            name: "data.transmission",
+            legacyKey: "transmission",
             to: "transmission",
             ...AS_AUTHORED,
             default: "none",
@@ -440,7 +497,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "Days from contracting to onset, rolled by the receiving actor. Unset means no incubation.",
         },
         {
-            name: "outcome",
+            name: "data.outcome",
+            legacyKey: "outcome",
             to: "outcome",
             ...BLANK_IS_DEFAULT,
             default: "cured",
@@ -464,7 +522,8 @@ export const ITEM_FIELDS = Object.freeze({
         // cannot be grepped, and each phase's prose differs anyway — which is
         // the whole content of the declaration.
         {
-            name: "onsetDurationFormula",
+            name: "data.onsetDurationFormula",
+            legacyKey: "onsetDurationFormula",
             to: "onsetDurationFormula",
             ...DURATION_FORMULA,
             omitWhenAbsent: true,
@@ -472,7 +531,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "Interval from contracting the affliction to the start of onset. Omitted when unset, leaving no incubation.",
         },
         {
-            name: "onsetDurationBase",
+            name: "data.onsetDurationBase",
+            legacyKey: "onsetDurationBase",
             to: "onsetDurationBase",
             ...DURATION_BASE,
             omitWhenAbsent: true,
@@ -480,7 +540,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "The onset interval in seconds, standing in for a roll of the formula. Omitted when unset.",
         },
         {
-            name: "healingCheckDurationFormula",
+            name: "data.healingCheckDurationFormula",
+            legacyKey: "healingCheckDurationFormula",
             to: "healingCheckDurationFormula",
             ...DURATION_FORMULA,
             omitWhenAbsent: true,
@@ -488,7 +549,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "Interval between healing checks, once the affliction is symptomatic. Omitted when unset.",
         },
         {
-            name: "healingCheckDurationBase",
+            name: "data.healingCheckDurationBase",
+            legacyKey: "healingCheckDurationBase",
             to: "healingCheckDurationBase",
             ...DURATION_BASE,
             omitWhenAbsent: true,
@@ -496,7 +558,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "The healing-check interval in seconds, standing in for a roll of the formula. Omitted when unset.",
         },
         {
-            name: "resolutionDurationFormula",
+            name: "data.resolutionDurationFormula",
+            legacyKey: "resolutionDurationFormula",
             to: "resolutionDurationFormula",
             ...DURATION_FORMULA,
             omitWhenAbsent: true,
@@ -504,7 +567,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "Interval from onset to the affliction running its course. Omitted when unset.",
         },
         {
-            name: "resolutionDurationBase",
+            name: "data.resolutionDurationBase",
+            legacyKey: "resolutionDurationBase",
             to: "resolutionDurationBase",
             ...DURATION_BASE,
             omitWhenAbsent: true,
@@ -711,7 +775,7 @@ export const ITEM_FIELDS = Object.freeze({
         {
             name: "assocSkillCode",
             to: "assocSkillCode",
-            ref: "skill",
+            code: "skill",
             ...BLANK_IS_NULL,
             default: null,
             describe: "Shortcode of the skill the mystery is tested against.",
@@ -719,7 +783,7 @@ export const ITEM_FIELDS = Object.freeze({
         {
             name: "assocAffiliationCode",
             to: "assocAffiliationCode",
-            ref: "affiliation",
+            code: "affiliation",
             ...BLANK_IS_NULL,
             default: null,
             describe:
@@ -733,14 +797,16 @@ export const ITEM_FIELDS = Object.freeze({
             describe: "The mystery's level before any modifier.",
         },
         {
-            name: "skillAptitudes",
+            name: "data.skillAptitudes",
+            legacyKey: "skillAptitudes",
             to: "skillAptitudes",
             ...SKILL_APTITUDES,
             default: {},
             describe: "Aptitude the mystery grants, per skill selector.",
         },
         {
-            name: "charges",
+            name: "data.charges",
+            legacyKey: "charges",
             to: "charges",
             ...CHARGES,
             default: { value: null, max: null },
@@ -760,7 +826,7 @@ export const ITEM_FIELDS = Object.freeze({
         {
             name: "assocSkillCode",
             to: "assocSkillCode",
-            ref: "skill",
+            code: "skill",
             ...AS_AUTHORED,
             default: "",
             describe: "Shortcode of the skill the ability is tested against.",
@@ -768,7 +834,7 @@ export const ITEM_FIELDS = Object.freeze({
         {
             name: "assocAffiliationCode",
             to: "assocAffiliationCode",
-            ref: "affiliation",
+            code: "affiliation",
             ...BLANK_IS_NULL,
             default: null,
             describe:
@@ -796,7 +862,8 @@ export const ITEM_FIELDS = Object.freeze({
             describe: "The ability's level before any modifier.",
         },
         {
-            name: "charges",
+            name: "data.charges",
+            legacyKey: "charges",
             to: "charges",
             ...CHARGES,
             default: { value: null, max: null },
@@ -884,7 +951,7 @@ export const ITEM_FIELDS = Object.freeze({
         {
             name: "parentSkillCode",
             to: "parentSkillCode",
-            ref: "skill",
+            code: "skill",
             ...AS_AUTHORED,
             default: "",
             describe: "Shortcode of the skill this one specialises, for a specialisation.",
@@ -959,7 +1026,8 @@ export const ITEM_FIELDS = Object.freeze({
         // `bloodLossAdvance*` is the one an author reaches for most: a trauma
         // that sets it bleeds, and one that leaves it unset does not.
         {
-            name: "healingCheckDurationFormula",
+            name: "data.healingCheckDurationFormula",
+            legacyKey: "healingCheckDurationFormula",
             to: "healingCheckDurationFormula",
             ...DURATION_FORMULA,
             omitWhenAbsent: true,
@@ -967,7 +1035,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "Interval between healing checks. Omitted when unset, leaving the world's configured interval to apply.",
         },
         {
-            name: "healingCheckDurationBase",
+            name: "data.healingCheckDurationBase",
+            legacyKey: "healingCheckDurationBase",
             to: "healingCheckDurationBase",
             ...DURATION_BASE,
             omitWhenAbsent: true,
@@ -975,7 +1044,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "The healing-check interval in seconds, standing in for a roll of the formula. Omitted when unset.",
         },
         {
-            name: "bloodLossAdvanceDurationFormula",
+            name: "data.bloodLossAdvanceDurationFormula",
+            legacyKey: "bloodLossAdvanceDurationFormula",
             to: "bloodLossAdvanceDurationFormula",
             ...DURATION_FORMULA,
             omitWhenAbsent: true,
@@ -983,7 +1053,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "Interval between blood-loss advances. Omitted when unset, leaving the world's configured interval to apply.",
         },
         {
-            name: "bloodLossAdvanceDurationBase",
+            name: "data.bloodLossAdvanceDurationBase",
+            legacyKey: "bloodLossAdvanceDurationBase",
             to: "bloodLossAdvanceDurationBase",
             ...DURATION_BASE,
             omitWhenAbsent: true,
@@ -991,7 +1062,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "The blood-loss interval in seconds. Setting it is what makes the wound bleed; omitted when unset, and the wound does not.",
         },
         {
-            name: "courseDurationFormula",
+            name: "data.courseDurationFormula",
+            legacyKey: "courseDurationFormula",
             to: "courseDurationFormula",
             ...DURATION_FORMULA,
             omitWhenAbsent: true,
@@ -999,7 +1071,8 @@ export const ITEM_FIELDS = Object.freeze({
                 "Interval between course tests, for a condition that runs one — shock, coma, infection. Omitted when unset.",
         },
         {
-            name: "courseDurationBase",
+            name: "data.courseDurationBase",
+            legacyKey: "courseDurationBase",
             to: "courseDurationBase",
             ...DURATION_BASE,
             omitWhenAbsent: true,

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

@@ -0,0 +1,90 @@
+/**
+ * An Address position, as a field declaration states it.
+ *
+ * @typedef {object} AddressPosition
+ * @property {string} type - The type an omitted `<type>` segment takes.
+ * @property {readonly string[]} accepts - Every type the position accepts.
+ * @property {"value"|"items"|"keys"} [holds] - Where the Addresses are.
+ *   Defaults to `value`.
+ */
+/**
+ * What a reduction could not do, for a caller to report.
+ *
+ * @typedef {object} AddressFinding
+ * @property {string} key - The field, named as an author writes it.
+ * @property {string} written - The authored value, so the caller can locate the
+ *   finding at the line carrying it rather than at the key.
+ * @property {string} message - One sentence, naming the fix.
+ */
+/**
+ * The declarations that state an Address position.
+ *
+ * @param {readonly object[]} fields - A field declaration.
+ * @returns {object[]} Only the fields carrying an `address` statement.
+ */
+export function addressFields(fields: readonly object[]): object[];
+/**
+ * Reduce every Address a compiled block holds to the Shortcode it names.
+ *
+ * The block is edited in place, as {@link
+ * module:engine/system-block.mergeSystemData} edits it: what the caller holds is
+ * the document being assembled, and a field the reduction cannot read is left
+ * exactly as authored — the findings stop the build, so nothing ships either
+ * way, and an untouched value is what a reader of the failing note sees.
+ *
+ * @param {object} emitted - The `system` block, already built.
+ * @param {readonly object[]} fields - The type's field declaration.
+ * @param {import("./address.mjs").AddressVocabulary & {package?: string}}
+ *   vocabulary - The tree's vocabularies and the package the values are written
+ *   in.
+ * @returns {AddressFinding[]} Every value that could not be reduced.
+ */
+export function reduceAddressFields(emitted: object, fields: readonly object[], vocabulary?: import("./address.mjs").AddressVocabulary & {
+    package?: string;
+}): AddressFinding[];
+/**
+ * How many values a position holds.
+ *
+ * - `value` — the field's value is one Address.
+ * - `items` — every element of a list is one.
+ * - `keys` — every **key** of a map is one, and the values are untouched.
+ *
+ * @type {readonly string[]}
+ */
+export const ADDRESS_FIELD_SHAPES: readonly string[];
+/**
+ * An Address position, as a field declaration states it.
+ */
+export type AddressPosition = {
+    /**
+     * - The type an omitted `<type>` segment takes.
+     */
+    type: string;
+    /**
+     * - Every type the position accepts.
+     */
+    accepts: readonly string[];
+    /**
+     * - Where the Addresses are.
+     * Defaults to `value`.
+     */
+    holds?: "keys" | "value" | "items" | undefined;
+};
+/**
+ * What a reduction could not do, for a caller to report.
+ */
+export type AddressFinding = {
+    /**
+     * - The field, named as an author writes it.
+     */
+    key: string;
+    /**
+     * - The authored value, so the caller can locate the
+     * finding at the line carrying it rather than at the key.
+     */
+    written: string;
+    /**
+     * - One sentence, naming the fix.
+     */
+    message: string;
+};