@mailwoman/core 3.0.0 → 4.1.0

package/out/decoder/build-tree.d.ts

@@ -8,9 +8,11 @@
  *   Two passes:
  *
  *   1. Span emission — walk the token stream, group `B-X` followed by `I-X*` into one span. Lenient on
- *        hanging `I-X` (treat as new span). Span `value` is sliced from `raw` by [start, end), NOT
- *        concatenated from `piece` — this avoids SentencePiece's synthetic leading-space markers in
- *        the output.
+ *        hanging `I-X` (treat as new span). A `B-X` that is whitespace-adjacent to an already-open
+ *        `X` span is also folded in (spurious-boundary repair for multi-word values the model
+ *        fragments, e.g. "Saint Paul" → B-locality B-locality); a comma/separator between them
+ *        keeps them distinct. Span `value` is sliced from `raw` by [start, end), NOT concatenated
+ *        from `piece` — this avoids SentencePiece's synthetic leading-space markers in the output.
  *   2. Parent attachment — for each span, find the nearest labeled span whose tag is the
  *        highest-priority entry in this span's `PARENT_OF` list. Distance is the tiebreaker only.
  *        Spans with no found parent become roots.
@@ -20,7 +22,8 @@
  *   Source order is still preserved in the `start`/`end` fields, which the XML serializer exposes
  *   as attributes.
  */
-import type { AddressTree, DecoderToken } from "./types.js";
+import type { Calibrator } from "./calibration.js";
+import type { AddressSystem, AddressTree, DecoderToken } from "./types.js";
 /**
  * Optional caller-supplied attribution stamped on every emitted node. The BIO stream comes from a
  * single model, so there's no per-span variation — one source for the whole tree.
@@ -30,6 +33,20 @@ import type { AddressTree, DecoderToken } from "./types.js";
 export interface BuildTreeOpts {
     source?: string;
     sourceId?: string;
+    /**
+     * Addressing system to decode under — selects the containment hierarchy via `containmentFor`.
+     * Stamped onto the returned `AddressTree.system`. Omit for the default Western hierarchy. Today
+     * all systems share one map, so this only records intent + threads the discriminator; it becomes
+     * behavioral when a system-specific map lands (Phase 6 JP). See `containment.ts`.
+     */
+    system?: AddressSystem;
+    /**
+     * Optional confidence calibrator (task #59). When provided, each span's mean-of-token-softmax
+     * confidence is mapped through it before being stamped on the node, so `conf=` reports a
+     * calibrated probability of correctness rather than the raw softmax. OPT-IN — omit for the
+     * byte-stable default. Build one via `createCalibrator` (`./calibration.ts`).
+     */
+    calibrate?: Calibrator;
 }
 /**
  * Build an `AddressTree` from a raw input string and the token stream produced by the model.

package/out/decoder/build-tree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-tree.d.ts","sourceRoot":"","sources":["../../decoder/build-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,KAAK,EAAe,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAExE;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;CACjB;AA4FD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,IAAI,GAAE,aAAkB,GAAG,WAAW,CAY3G"}
+{"version":3,"file":"build-tree.d.ts","sourceRoot":"","sources":["../../decoder/build-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,OAAO,KAAK,EAAe,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEvF;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,UAAU,CAAA;CACtB;AAsHD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,IAAI,GAAE,aAAkB,GAAG,WAAW,CAe3G"}

package/out/decoder/build-tree.js

@@ -8,9 +8,11 @@
  *   Two passes:
  *
  *   1. Span emission — walk the token stream, group `B-X` followed by `I-X*` into one span. Lenient on
- *        hanging `I-X` (treat as new span). Span `value` is sliced from `raw` by [start, end), NOT
- *        concatenated from `piece` — this avoids SentencePiece's synthetic leading-space markers in
- *        the output.
+ *        hanging `I-X` (treat as new span). A `B-X` that is whitespace-adjacent to an already-open
+ *        `X` span is also folded in (spurious-boundary repair for multi-word values the model
+ *        fragments, e.g. "Saint Paul" → B-locality B-locality); a comma/separator between them
+ *        keeps them distinct. Span `value` is sliced from `raw` by [start, end), NOT concatenated
+ *        from `piece` — this avoids SentencePiece's synthetic leading-space markers in the output.
  *   2. Parent attachment — for each span, find the nearest labeled span whose tag is the
  *        highest-priority entry in this span's `PARENT_OF` list. Distance is the tiebreaker only.
  *        Spans with no found parent become roots.
@@ -20,7 +22,7 @@
  *   Source order is still preserved in the `start`/`end` fields, which the XML serializer exposes
  *   as attributes.
  */
-import { PARENT_OF } from "./containment.js";
+import { containmentFor } from "./containment.js";
 function bioParts(label) {
     if (label === "O")
         return { prefix: "O", tag: null };
@@ -51,7 +53,8 @@ function flush(open, raw, out, attribution) {
     if (start >= end)
         return null;
     const value = raw.slice(start, end);
-    const confidence = open.confidences.reduce((a, b) => a + b, 0) / open.confidences.length;
+    const rawConfidence = open.confidences.reduce((a, b) => a + b, 0) / open.confidences.length;
+    const confidence = attribution.calibrate ? attribution.calibrate(rawConfidence) : rawConfidence;
     const node = { tag: open.tag, start, end, value, confidence, children: [] };
     if (attribution.source !== undefined)
         node.source = attribution.source;
@@ -66,10 +69,32 @@ function emitSpans(raw, tokens, attribution) {
     for (const tok of tokens) {
         const { prefix, tag } = bioParts(tok.label);
         if (prefix === "O") {
+            // A zero-width or whitespace-only `O` piece is a tokenizer artifact — SentencePiece emits a
+            // standalone `▁` word-boundary marker between words and the model labels it `O` (e.g.
+            // "Saint Paul" → "▁Saint"[B-loc], "▁"[O, zero-width], "Paul"[B-loc]). It is NOT a real
+            // component boundary, so it must not flush the open span; keeping the span alive lets the
+            // following same-tag `B-` token merge in (see the spurious-boundary repair below). A
+            // non-whitespace `O` (comma, slash, …) is a genuine separator and still flushes.
+            if (open !== null && /^\s*$/.test(raw.slice(tok.start, tok.end)))
+                continue;
             open = flush(open, raw, out, attribution);
             continue;
         }
         if (prefix === "B" || open === null || open.tag !== tag) {
+            // Spurious-boundary repair: a `B-X` token that is whitespace-adjacent to an already-open
+            // `X` span is the model fragmenting a multi-word value — e.g. "Saint Paul" emitted as
+            // B-locality B-locality instead of B-locality I-locality (a real, decode-agnostic
+            // emission bug; see scripts/diag-saintalbans.ts). Fold it into the open span.
+            //
+            // Guard: only merge when the text in `raw` between the two spans is whitespace-only. A
+            // comma or any other separator keeps them distinct, and an intervening O/different-tag
+            // token already nulls/replaces `open` above — so two genuinely separate same-tag spans
+            // (e.g. "Springfield, Chicago") are never merged.
+            if (prefix === "B" && open !== null && open.tag === tag && /^\s*$/.test(raw.slice(open.end, tok.start))) {
+                open.end = tok.end;
+                open.confidences.push(tok.confidence);
+                continue;
+            }
             open = flush(open, raw, out, attribution);
             open = { tag: tag, start: tok.start, end: tok.end, confidences: [tok.confidence] };
             continue;
@@ -88,8 +113,8 @@ function distance(a, b) {
         return a.start - b.end;
     return 0;
 }
-function findParent(span, all) {
-    const candidates = PARENT_OF[span.tag] ?? [];
+function findParent(span, all, parentOf) {
+    const candidates = parentOf[span.tag] ?? [];
     for (const parentTag of candidates) {
         const matches = all.filter((s) => s !== span && s.tag === parentTag);
         if (matches.length === 0)
@@ -115,14 +140,18 @@ function sortByStart(nodes) {
 export function buildAddressTree(raw, tokens, opts = {}) {
     const spans = emitSpans(raw, tokens, opts);
     const roots = [];
+    const parentOf = containmentFor(opts.system);
     for (const span of spans) {
-        const parent = findParent(span, spans);
+        const parent = findParent(span, spans, parentOf);
         if (parent)
             parent.children.push(span);
         else
             roots.push(span);
     }
     sortByStart(roots);
-    return { raw, roots };
+    const tree = { raw, roots };
+    if (opts.system !== undefined)
+        tree.system = opts.system;
+    return tree;
 }
 //# sourceMappingURL=build-tree.js.map

package/out/decoder/build-tree.js.map

@@ -1 +1 @@
-{"version":3,"file":"build-tree.js","sourceRoot":"","sources":["../../decoder/build-tree.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"build-tree.js","sourceRoot":"","sources":["../../decoder/build-tree.ts"],"names":[],"mappings":"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"}

package/out/decoder/calibration.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Opt-in confidence calibration for decoded spans.
+ *
+ *   The decoder emits a per-span `confidence` that is the mean of the span's per-token softmax
+ *   probabilities (`build-tree.ts`). Softmax probabilities are NOT calibrated — a CE-trained model
+ *   is systematically over/under-confident in bands. Task #59 fits an isotonic-regression
+ *   calibrator on a held-out OpenAddresses + corpus set
+ *   (`scripts/eval/fit-isotonic-calibration.py`) and ships the result as a 20-bin lookup table
+ *   (`data/eval/calibration/isotonic-<locale>-<version>.json`).
+ *
+ *   This module turns that table into a pure `(rawConfidence) => calibratedConfidence` function. It
+ *   is deliberately decoupled from the table source: pass the PARSED JSON object so this stays
+ *   browser-safe (no `node:fs`) — the demo imports the JSON directly, Node scripts `JSON.parse`
+ *   it.
+ *
+ *   Wiring is OPT-IN. The default decode path is unchanged (byte-stable `conf=` output). A caller
+ *   that wants calibrated confidences builds a `Calibrator` here and passes it via
+ *   `ParseOpts.calibrate` (neural) / `BuildTreeOpts.calibrate` (decoder), which `build-tree.ts`
+ *   applies in `flush()`.
+ */
+/** One row of the lookup table: a confidence bin and the calibrated value at its center. */
+export interface CalibrationBin {
+    lo: number;
+    hi: number;
+    center: number;
+    calibrated: number;
+}
+/** The full calibration artifact emitted by `fit-isotonic-calibration.py`. */
+export interface CalibrationTable {
+    model: string;
+    model_version: string;
+    method: string;
+    bins: number;
+    table: CalibrationBin[];
+    [key: string]: unknown;
+}
+/** Maps a raw span confidence in [0, 1] to its calibrated probability of correctness. */
+export type Calibrator = (rawConfidence: number) => number;
+/**
+ * Build a calibrator from an isotonic lookup table. The mapping is piecewise-linear between bin
+ * centers and clamped to the table's range outside it (the table is monotone non-decreasing by
+ * construction, so the interpolation is monotone too). Accepts either the full `CalibrationTable`
+ * or a bare `CalibrationBin[]`.
+ */
+export declare function createCalibrator(table: CalibrationTable | CalibrationBin[]): Calibrator;
+//# sourceMappingURL=calibration.d.ts.map

package/out/decoder/calibration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calibration.d.ts","sourceRoot":"","sources":["../../decoder/calibration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,4FAA4F;AAC5F,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;CAClB;AAED,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,cAAc,EAAE,CAAA;IACvB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACtB;AAED,yFAAyF;AACzF,MAAM,MAAM,UAAU,GAAG,CAAC,aAAa,EAAE,MAAM,KAAK,MAAM,CAAA;AAE1D;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG,cAAc,EAAE,GAAG,UAAU,CA8BvF"}

package/out/decoder/calibration.js

@@ -0,0 +1,74 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Opt-in confidence calibration for decoded spans.
+ *
+ *   The decoder emits a per-span `confidence` that is the mean of the span's per-token softmax
+ *   probabilities (`build-tree.ts`). Softmax probabilities are NOT calibrated — a CE-trained model
+ *   is systematically over/under-confident in bands. Task #59 fits an isotonic-regression
+ *   calibrator on a held-out OpenAddresses + corpus set
+ *   (`scripts/eval/fit-isotonic-calibration.py`) and ships the result as a 20-bin lookup table
+ *   (`data/eval/calibration/isotonic-<locale>-<version>.json`).
+ *
+ *   This module turns that table into a pure `(rawConfidence) => calibratedConfidence` function. It
+ *   is deliberately decoupled from the table source: pass the PARSED JSON object so this stays
+ *   browser-safe (no `node:fs`) — the demo imports the JSON directly, Node scripts `JSON.parse`
+ *   it.
+ *
+ *   Wiring is OPT-IN. The default decode path is unchanged (byte-stable `conf=` output). A caller
+ *   that wants calibrated confidences builds a `Calibrator` here and passes it via
+ *   `ParseOpts.calibrate` (neural) / `BuildTreeOpts.calibrate` (decoder), which `build-tree.ts`
+ *   applies in `flush()`.
+ */
+/**
+ * Build a calibrator from an isotonic lookup table. The mapping is piecewise-linear between bin
+ * centers and clamped to the table's range outside it (the table is monotone non-decreasing by
+ * construction, so the interpolation is monotone too). Accepts either the full `CalibrationTable`
+ * or a bare `CalibrationBin[]`.
+ */
+export function createCalibrator(table) {
+    const bins = Array.isArray(table) ? table : table.table;
+    if (!bins || bins.length === 0) {
+        throw new Error("createCalibrator: empty calibration table");
+    }
+    // Sort by center and extract parallel arrays for interpolation.
+    const sorted = [...bins].sort((a, b) => a.center - b.center);
+    const centers = sorted.map((b) => b.center);
+    const cals = sorted.map((b) => clamp01(b.calibrated));
+    const n = centers.length;
+    return (raw) => {
+        const x = clamp01(raw);
+        if (x <= centers[0])
+            return cals[0];
+        if (x >= centers[n - 1])
+            return cals[n - 1];
+        // Binary search for the interval [centers[i], centers[i+1]] containing x.
+        let lo = 0;
+        let hi = n - 1;
+        while (hi - lo > 1) {
+            const mid = (lo + hi) >> 1;
+            if (centers[mid] <= x)
+                lo = mid;
+            else
+                hi = mid;
+        }
+        const x0 = centers[lo];
+        const x1 = centers[hi];
+        const y0 = cals[lo];
+        const y1 = cals[hi];
+        const t = x1 === x0 ? 0 : (x - x0) / (x1 - x0);
+        return y0 + t * (y1 - y0);
+    };
+}
+function clamp01(v) {
+    if (Number.isNaN(v))
+        return 0;
+    if (v < 0)
+        return 0;
+    if (v > 1)
+        return 1;
+    return v;
+}
+//# sourceMappingURL=calibration.js.map

package/out/decoder/calibration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calibration.js","sourceRoot":"","sources":["../../decoder/calibration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAuBH;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAA0C;IAC1E,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAA;IACvD,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAA;IAC7D,CAAC;IACD,gEAAgE;IAChE,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAA;IAC5D,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;IAC3C,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAA;IACrD,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAA;IAExB,OAAO,CAAC,GAAW,EAAU,EAAE;QAC9B,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;QACtB,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,CAAE;YAAE,OAAO,IAAI,CAAC,CAAC,CAAE,CAAA;QACrC,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,GAAG,CAAC,CAAE;YAAE,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,CAAE,CAAA;QAC7C,0EAA0E;QAC1E,IAAI,EAAE,GAAG,CAAC,CAAA;QACV,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,CAAA;QACd,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;YACpB,MAAM,GAAG,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,CAAA;YAC1B,IAAI,OAAO,CAAC,GAAG,CAAE,IAAI,CAAC;gBAAE,EAAE,GAAG,GAAG,CAAA;;gBAC3B,EAAE,GAAG,GAAG,CAAA;QACd,CAAC;QACD,MAAM,EAAE,GAAG,OAAO,CAAC,EAAE,CAAE,CAAA;QACvB,MAAM,EAAE,GAAG,OAAO,CAAC,EAAE,CAAE,CAAA;QACvB,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,CAAE,CAAA;QACpB,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,CAAE,CAAA;QACpB,MAAM,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAA;QAC9C,OAAO,EAAE,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAA;IAC1B,CAAC,CAAA;AACF,CAAC;AAED,SAAS,OAAO,CAAC,CAAS;IACzB,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAA;IAC7B,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,CAAA;IACnB,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,CAAA;IACnB,OAAO,CAAC,CAAA;AACT,CAAC"}

package/out/decoder/containment.d.ts

@@ -11,9 +11,38 @@
  *   distance wins. Spans whose tag is absent from this map (or has no labeled parent) become
  *   roots.
  *
- *   Tags absent from this map are treated as root-only (no parent ever accepted).
+ *   Tags absent from a map are treated as root-only (no parent ever accepted).
+ *
+ *   ## Per-system containment (anti-lock-in)
+ *
+ *   Addressing _systems_ disagree on hierarchy: a US street address nests `house_number → street →
+ *   locality`, while a Japanese block address nests `building_number → sub_block → block →
+ *   district` — there is no `street` parent at all. Today a single global map suffices only because
+ *   the tag sets don't collide, but the moment the resolver or tree builder hardcodes the Western
+ *   shape, retrofitting a second system gets expensive (DeepSeek resolver consult, 2026-05-30).
+ *
+ *   The cheap insurance is this indirection: callers ask `containmentFor(system)` rather than
+ *   importing one global constant. Today every system resolves to `WESTERN_PARENT_OF` (the
+ *   historical map, behavior-identical), and `PARENT_OF` is kept as an alias so existing imports
+ *   don't break. When a genuinely distinct system map lands (Phase 6 JP), it slots in here with
+ *   zero call-site churn. See `AddressSystem` in `./types.ts`.
  */
 import type { ComponentTag } from "../types/component.js";
+import type { AddressSystem } from "./types.js";
 /** Preferred-parent ordering for each tag. Empty / missing = always root. */
-export declare const PARENT_OF: Partial<Record<ComponentTag, ComponentTag[]>>;
+export declare const WESTERN_PARENT_OF: Partial<Record<ComponentTag, ComponentTag[]>>;
+/**
+ * The containment map for a given addressing system.
+ *
+ * Currently every system maps to {@link WESTERN_PARENT_OF} — the indirection exists so a future
+ * system-specific map (e.g. Japanese block addressing) can be introduced without touching the tree
+ * builder or validator. `undefined` (the common case — system not yet detected) uses the default.
+ */
+export declare function containmentFor(_system?: AddressSystem): Partial<Record<ComponentTag, ComponentTag[]>>;
+/**
+ * Backwards-compatible alias for the default (Western) containment map. Prefer `containmentFor()`
+ * in new code so the system parameter threads through; this export remains for existing call
+ * sites.
+ */
+export declare const PARENT_OF: Partial<Record<"country" | "house_number" | "locality" | "postcode" | "region" | "street_prefix" | "street_suffix" | "street" | "unit" | "venue" | "attention" | "municipality" | "district" | "dependent_locality" | "subregion" | "street_prefix_particle" | "intersection_a" | "intersection_b" | "po_box" | "cedex" | "prefecture" | "block" | "sub_block" | "building_number" | "building_name", ("country" | "house_number" | "locality" | "postcode" | "region" | "street_prefix" | "street_suffix" | "street" | "unit" | "venue" | "attention" | "municipality" | "district" | "dependent_locality" | "subregion" | "street_prefix_particle" | "intersection_a" | "intersection_b" | "po_box" | "cedex" | "prefecture" | "block" | "sub_block" | "building_number" | "building_name")[]>>;
 //# sourceMappingURL=containment.d.ts.map

package/out/decoder/containment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"containment.d.ts","sourceRoot":"","sources":["../../decoder/containment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEzD,6EAA6E;AAC7E,eAAO,MAAM,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,YAAY,EAAE,CAAC,CAgCnE,CAAA"}
+{"version":3,"file":"containment.d.ts","sourceRoot":"","sources":["../../decoder/containment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,YAAY,EAAE,CAAC,CAiC3E,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,YAAY,EAAE,CAAC,CAAC,CAIrG;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,mwBAAoB,CAAA"}

package/out/decoder/containment.js

@@ -11,10 +11,24 @@
  *   distance wins. Spans whose tag is absent from this map (or has no labeled parent) become
  *   roots.
  *
- *   Tags absent from this map are treated as root-only (no parent ever accepted).
+ *   Tags absent from a map are treated as root-only (no parent ever accepted).
+ *
+ *   ## Per-system containment (anti-lock-in)
+ *
+ *   Addressing _systems_ disagree on hierarchy: a US street address nests `house_number → street →
+ *   locality`, while a Japanese block address nests `building_number → sub_block → block →
+ *   district` — there is no `street` parent at all. Today a single global map suffices only because
+ *   the tag sets don't collide, but the moment the resolver or tree builder hardcodes the Western
+ *   shape, retrofitting a second system gets expensive (DeepSeek resolver consult, 2026-05-30).
+ *
+ *   The cheap insurance is this indirection: callers ask `containmentFor(system)` rather than
+ *   importing one global constant. Today every system resolves to `WESTERN_PARENT_OF` (the
+ *   historical map, behavior-identical), and `PARENT_OF` is kept as an alias so existing imports
+ *   don't break. When a genuinely distinct system map lands (Phase 6 JP), it slots in here with
+ *   zero call-site churn. See `AddressSystem` in `./types.ts`.
  */
 /** Preferred-parent ordering for each tag. Empty / missing = always root. */
-export const PARENT_OF = {
+export const WESTERN_PARENT_OF = {
     // Universal coarse — containment follows geographic granularity.
     region: ["country"],
     subregion: ["region", "country"],
@@ -35,7 +49,8 @@ export const PARENT_OF = {
     venue: ["street", "locality"],
     attention: ["venue"],
     po_box: ["locality", "subregion", "region"],
-    // JP — declared for forward-compat; mapping is provisional and will be revisited in Phase 6.
+    // JP — declared for forward-compat; mapping is provisional and will be revisited in Phase 6, when
+    // a dedicated `japanese` system map likely supersedes these entries with a no-street hierarchy.
     prefecture: ["country"],
     municipality: ["prefecture"],
     district: ["municipality"],
@@ -44,4 +59,22 @@ export const PARENT_OF = {
     building_number: ["sub_block", "block"],
     building_name: ["building_number", "sub_block", "block"],
 };
+/**
+ * The containment map for a given addressing system.
+ *
+ * Currently every system maps to {@link WESTERN_PARENT_OF} — the indirection exists so a future
+ * system-specific map (e.g. Japanese block addressing) can be introduced without touching the tree
+ * builder or validator. `undefined` (the common case — system not yet detected) uses the default.
+ */
+export function containmentFor(_system) {
+    // Single system today. The parameter is intentionally consumed lazily — adding `case "japanese":`
+    // here is the entire surface area for a new system's hierarchy.
+    return WESTERN_PARENT_OF;
+}
+/**
+ * Backwards-compatible alias for the default (Western) containment map. Prefer `containmentFor()`
+ * in new code so the system parameter threads through; this export remains for existing call
+ * sites.
+ */
+export const PARENT_OF = WESTERN_PARENT_OF;
 //# sourceMappingURL=containment.js.map

package/out/decoder/containment.js.map

@@ -1 +1 @@
-{"version":3,"file":"containment.js","sourceRoot":"","sources":["../../decoder/containment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,SAAS,GAAkD;IACvE,iEAAiE;IACjE,MAAM,EAAE,CAAC,SAAS,CAAC;IACnB,SAAS,EAAE,CAAC,QAAQ,EAAE,SAAS,CAAC;IAChC,QAAQ,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,SAAS,CAAC;IAC5C,kBAAkB,EAAE,CAAC,UAAU,CAAC;IAChC,QAAQ,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,CAAC;IACxD,KAAK,EAAE,CAAC,UAAU,EAAE,UAAU,CAAC;IAE/B,mGAAmG;IACnG,MAAM,EAAE,CAAC,oBAAoB,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,CAAC;IACjE,aAAa,EAAE,CAAC,QAAQ,CAAC;IACzB,sBAAsB,EAAE,CAAC,eAAe,EAAE,QAAQ,CAAC;IACnD,aAAa,EAAE,CAAC,QAAQ,CAAC;IACzB,YAAY,EAAE,CAAC,QAAQ,CAAC;IACxB,IAAI,EAAE,CAAC,QAAQ,EAAE,cAAc,CAAC;IAChC,cAAc,EAAE,CAAC,QAAQ,EAAE,UAAU,CAAC;IACtC,cAAc,EAAE,CAAC,QAAQ,EAAE,UAAU,CAAC;IAEtC,8EAA8E;IAC9E,KAAK,EAAE,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC7B,SAAS,EAAE,CAAC,OAAO,CAAC;IACpB,MAAM,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,QAAQ,CAAC;IAE3C,6FAA6F;IAC7F,UAAU,EAAE,CAAC,SAAS,CAAC;IACvB,YAAY,EAAE,CAAC,YAAY,CAAC;IAC5B,QAAQ,EAAE,CAAC,cAAc,CAAC;IAC1B,KAAK,EAAE,CAAC,UAAU,CAAC;IACnB,SAAS,EAAE,CAAC,OAAO,CAAC;IACpB,eAAe,EAAE,CAAC,WAAW,EAAE,OAAO,CAAC;IACvC,aAAa,EAAE,CAAC,iBAAiB,EAAE,WAAW,EAAE,OAAO,CAAC;CACxD,CAAA"}
+{"version":3,"file":"containment.js","sourceRoot":"","sources":["../../decoder/containment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAKH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,iBAAiB,GAAkD;IAC/E,iEAAiE;IACjE,MAAM,EAAE,CAAC,SAAS,CAAC;IACnB,SAAS,EAAE,CAAC,QAAQ,EAAE,SAAS,CAAC;IAChC,QAAQ,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,SAAS,CAAC;IAC5C,kBAAkB,EAAE,CAAC,UAAU,CAAC;IAChC,QAAQ,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,CAAC;IACxD,KAAK,EAAE,CAAC,UAAU,EAAE,UAAU,CAAC;IAE/B,mGAAmG;IACnG,MAAM,EAAE,CAAC,oBAAoB,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,CAAC;IACjE,aAAa,EAAE,CAAC,QAAQ,CAAC;IACzB,sBAAsB,EAAE,CAAC,eAAe,EAAE,QAAQ,CAAC;IACnD,aAAa,EAAE,CAAC,QAAQ,CAAC;IACzB,YAAY,EAAE,CAAC,QAAQ,CAAC;IACxB,IAAI,EAAE,CAAC,QAAQ,EAAE,cAAc,CAAC;IAChC,cAAc,EAAE,CAAC,QAAQ,EAAE,UAAU,CAAC;IACtC,cAAc,EAAE,CAAC,QAAQ,EAAE,UAAU,CAAC;IAEtC,8EAA8E;IAC9E,KAAK,EAAE,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC7B,SAAS,EAAE,CAAC,OAAO,CAAC;IACpB,MAAM,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,QAAQ,CAAC;IAE3C,kGAAkG;IAClG,gGAAgG;IAChG,UAAU,EAAE,CAAC,SAAS,CAAC;IACvB,YAAY,EAAE,CAAC,YAAY,CAAC;IAC5B,QAAQ,EAAE,CAAC,cAAc,CAAC;IAC1B,KAAK,EAAE,CAAC,UAAU,CAAC;IACnB,SAAS,EAAE,CAAC,OAAO,CAAC;IACpB,eAAe,EAAE,CAAC,WAAW,EAAE,OAAO,CAAC;IACvC,aAAa,EAAE,CAAC,iBAAiB,EAAE,WAAW,EAAE,OAAO,CAAC;CACxD,CAAA;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,OAAuB;IACrD,kGAAkG;IAClG,gEAAgE;IAChE,OAAO,iBAAiB,CAAA;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,iBAAiB,CAAA"}

package/out/decoder/index.d.ts

@@ -4,10 +4,12 @@
  * @author Teffen Ellis, et al.
  */
 export * from "./build-tree.js";
+export * from "./calibration.js";
 export * from "./containment.js";
 export * from "./proposals-to-tree.js";
 export * from "./serialize-json.js";
 export * from "./serialize-tuples.js";
 export * from "./serialize-xml.js";
 export * from "./types.js";
+export * from "./validate-tree.js";
 //# sourceMappingURL=index.d.ts.map

package/out/decoder/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../decoder/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,wBAAwB,CAAA;AACtC,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../decoder/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,kBAAkB,CAAA;AAChC,cAAc,wBAAwB,CAAA;AACtC,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,oBAAoB,CAAA"}

package/out/decoder/index.js

@@ -4,10 +4,12 @@
  * @author Teffen Ellis, et al.
  */
 export * from "./build-tree.js";
+export * from "./calibration.js";
 export * from "./containment.js";
 export * from "./proposals-to-tree.js";
 export * from "./serialize-json.js";
 export * from "./serialize-tuples.js";
 export * from "./serialize-xml.js";
 export * from "./types.js";
+export * from "./validate-tree.js";
 //# sourceMappingURL=index.js.map

package/out/decoder/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../decoder/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,wBAAwB,CAAA;AACtC,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../decoder/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,kBAAkB,CAAA;AAChC,cAAc,wBAAwB,CAAA;AACtC,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,oBAAoB,CAAA"}

package/out/decoder/serialize-json.d.ts

@@ -7,6 +7,10 @@
  *
  *   Flattens the tree to `{ tag: value }`. First-occurrence wins for repeated tags — matches
  *   libpostal's behavior. Use `decodeAsTuples` if order or repetition matters.
+ *
+ *   A multi-role node (#413 — a city-state span tagged `region` that also plays `locality`) emits one
+ *   entry per role from its `interpretations`, so `out.locality` still surfaces for a completed
+ *   city-state. The shared span means every role gets the same `value`.
  */
 import type { ComponentTag } from "../types/component.js";
 import type { AddressTree } from "./types.js";

package/out/decoder/serialize-json.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serialize-json.d.ts","sourceRoot":"","sources":["../../decoder/serialize-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACzD,OAAO,KAAK,EAAe,WAAW,EAAE,MAAM,YAAY,CAAA;AAO1D,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAIrF"}
+{"version":3,"file":"serialize-json.d.ts","sourceRoot":"","sources":["../../decoder/serialize-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACzD,OAAO,KAAK,EAAe,WAAW,EAAE,MAAM,YAAY,CAAA;AAY1D,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAIrF"}

package/out/decoder/serialize-json.js

@@ -7,10 +7,20 @@
  *
  *   Flattens the tree to `{ tag: value }`. First-occurrence wins for repeated tags — matches
  *   libpostal's behavior. Use `decodeAsTuples` if order or repetition matters.
+ *
+ *   A multi-role node (#413 — a city-state span tagged `region` that also plays `locality`) emits one
+ *   entry per role from its `interpretations`, so `out.locality` still surfaces for a completed
+ *   city-state. The shared span means every role gets the same `value`.
  */
 function visit(node, out) {
     if (!(node.tag in out))
         out[node.tag] = node.value;
+    if (node.interpretations) {
+        for (const interp of node.interpretations) {
+            if (!(interp.tag in out))
+                out[interp.tag] = node.value;
+        }
+    }
     for (const child of node.children)
         visit(child, out);
 }

package/out/decoder/serialize-json.js.map

@@ -1 +1 @@
-{"version":3,"file":"serialize-json.js","sourceRoot":"","sources":["../../decoder/serialize-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,SAAS,KAAK,CAAC,IAAiB,EAAE,GAA0C;IAC3E,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC;QAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAA;IAClD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;QAAE,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;AACrD,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,YAAY,CAAC,IAAiB;IAC7C,MAAM,GAAG,GAA0C,EAAE,CAAA;IACrD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;IAC/C,OAAO,GAAG,CAAA;AACX,CAAC"}
+{"version":3,"file":"serialize-json.js","sourceRoot":"","sources":["../../decoder/serialize-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,SAAS,KAAK,CAAC,IAAiB,EAAE,GAA0C;IAC3E,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC;QAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAA;IAClD,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;QAC1B,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YAC3C,IAAI,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC;gBAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAA;QACvD,CAAC;IACF,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;QAAE,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;AACrD,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,YAAY,CAAC,IAAiB;IAC7C,MAAM,GAAG,GAA0C,EAAE,CAAA;IACrD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;IAC/C,OAAO,GAAG,CAAA;AACX,CAAC"}

package/out/decoder/serialize-xml.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serialize-xml.d.ts","sourceRoot":"","sources":["../../decoder/serialize-xml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAe,WAAW,EAAE,MAAM,YAAY,CAAA;AAE1D,MAAM,WAAW,gBAAgB;IAChC,mEAAmE;IACnE,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,iEAAiE;IACjE,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,oEAAoE;IACpE,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,0FAA0F;IAC1F,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,iGAAiG;IACjG,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,qFAAqF;IACrF,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC7B;AAoFD,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,GAAE,gBAAqB,GAAG,MAAM,CAelF"}
+{"version":3,"file":"serialize-xml.d.ts","sourceRoot":"","sources":["../../decoder/serialize-xml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAe,WAAW,EAAE,MAAM,YAAY,CAAA;AAE1D,MAAM,WAAW,gBAAgB;IAChC,mEAAmE;IACnE,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,iEAAiE;IACjE,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,oEAAoE;IACpE,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,0FAA0F;IAC1F,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,iGAAiG;IACjG,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,qFAAqF;IACrF,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC7B;AA0FD,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,GAAE,gBAAqB,GAAG,MAAM,CAelF"}

package/out/decoder/serialize-xml.js

@@ -65,6 +65,12 @@ function attrs(node, opts) {
     if (opts.includePlace && node.placeId !== undefined) {
         parts.push(`place="${escapeXml(node.placeId)}"`);
     }
+    // Multi-role node (#413): a city-state span tagged `region` that also plays `locality` lists every
+    // role it holds, primary first — `roles="region locality"`. Emitted only when extra roles exist.
+    if (node.interpretations && node.interpretations.length > 0) {
+        const roles = [node.tag, ...node.interpretations.map((i) => i.tag)];
+        parts.push(`roles="${escapeXml(roles.join(" "))}"`);
+    }
     return parts.length === 0 ? "" : " " + parts.join(" ");
 }
 function serializeAlternatives(node, indent) {

package/out/decoder/serialize-xml.js.map

@@ -1 +1 @@
-{"version":3,"file":"serialize-xml.js","sourceRoot":"","sources":["../../decoder/serialize-xml.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"serialize-xml.js","sourceRoot":"","sources":["../../decoder/serialize-xml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AA2BH,SAAS,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;AACpG,CAAC;AAED,SAAS,YAAY,CAAC,IAAiB;IACtC,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ;QAAE,OAAO,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAA;IAC1E,IAAI,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC,MAAM,CAAA;IACnC,IAAI,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC,QAAQ,CAAA;IACvC,OAAO,IAAI,CAAA;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,aAAa,GAAG,CAAC,CAAA;AAEvB,SAAS,KAAK,CAAC,IAAiB,EAAE,IAAgC;IACjE,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,IAAI,IAAI,CAAC,cAAc;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,KAAK,GAAG,EAAE,QAAQ,IAAI,CAAC,GAAG,GAAG,CAAC,CAAA;IACjF,IAAI,IAAI,CAAC,WAAW;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IACxE,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACrB,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,CAAA;QAC9B,IAAI,GAAG,KAAK,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACxD,CAAC;IACD,+FAA+F;IAC/F,wEAAwE;IACxE,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QACzE,KAAK,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,GAAG,EAAE,QAAQ,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,CAAA;IACnG,CAAC;IACD,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACrD,KAAK,CAAC,IAAI,CAAC,UAAU,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IACjD,CAAC;IACD,mGAAmG;IACnG,iGAAiG;IACjG,IAAI,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7D,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;QACnE,KAAK,CAAC,IAAI,CAAC,UAAU,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAA;IACpD,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACvD,CAAC;AAWD,SAAS,qBAAqB,CAAC,IAAiB,EAAE,MAAc;IAC/D,IAAI,CAAC,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IACnE,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QAC3C,MAAM,GAAG,GAAG,GAAsB,CAAA;QAClC,MAAM,KAAK,GAAG,OAAO,GAAG,CAAC,EAAE,EAAE,CAAA;QAC7B,MAAM,KAAK,GAAG;YACb,UAAU,SAAS,CAAC,KAAK,CAAC,GAAG;YAC7B,SAAS,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG;YAC/B,cAAc,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG;YACzC,QAAQ,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,GAAG;YACzC,QAAQ,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,GAAG;YACzC,UAAU,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;SACjC,CAAA;QACD,OAAO,GAAG,MAAM,gBAAgB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAA;IACrD,CAAC,CAAC,CAAA;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACxB,CAAC;AAED,SAAS,aAAa,CAAC,IAAiB,EAAE,MAAc,EAAE,IAAgC;IACzF,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IAC3B,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAClC,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAA;IAClC,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,CAAA;IAEpD,MAAM,SAAS,GAAG,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC,qBAAqB,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IAC1F,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAA;IAC5C,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,CAAA;IAEpC,IAAI,CAAC,WAAW,IAAI,CAAC,OAAO,EAAE,CAAC;QAC9B,OAAO,GAAG,MAAM,IAAI,IAAI,CAAC,GAAG,GAAG,CAAC,IAAI,IAAI,KAAK,IAAI,CAAC,GAAG,GAAG,CAAA;IACzD,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAC1F,MAAM,KAAK,GAAG,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAC/D,OAAO,GAAG,MAAM,IAAI,IAAI,CAAC,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,EAAE,GAAG,KAAK,GAAG,EAAE,GAAG,MAAM,KAAK,IAAI,CAAC,GAAG,GAAG,CAAA;AACpF,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,WAAW,CAAC,IAAiB,EAAE,OAAyB,EAAE;IACzE,MAAM,IAAI,GAA+B;QACxC,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,IAAI;QAC3B,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,IAAI;QACrC,cAAc,EAAE,IAAI,CAAC,cAAc,IAAI,IAAI;QAC3C,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,IAAI;QACnC,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,IAAI;QACnC,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,IAAI;QACvC,mBAAmB,EAAE,IAAI,CAAC,mBAAmB,IAAI,KAAK;KACtD,CAAA;IACD,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACnC,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAA;IAClC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAA;IACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAC/E,OAAO,iBAAiB,OAAO,KAAK,EAAE,GAAG,QAAQ,GAAG,EAAE,YAAY,CAAA;AACnE,CAAC"}

package/out/decoder/types.d.ts

@@ -100,6 +100,31 @@ export interface AddressNode {
      * `@mailwoman/core/resolver`.
      */
     alternatives?: ReadonlyArray<unknown>;
+    /**
+     * ADDITIONAL roles this single span plays, beyond `tag` (#413). A place can hold multiple admin
+     * tiers under one name — a city-state (Berlin is region AND locality) or a capital-seat province
+     * (Milano province ~ Milano comune). Rather than synthesize a second node with a borrowed span,
+     * the resolver records the extra role(s) here, so one node = one span = many roles (the model
+     * Google's `address_components[].types` uses). `tag`/`placeId`/`lat`/`lon` remain the PRIMARY
+     * role; each interpretation is a distinct secondary role with its own resolved place. Serializers
+     * surface every role (a city-state emits both `region` and `locality`). Distinct from
+     * `alternatives` — those are same-role runner-up places (Springfield IL vs MA); interpretations
+     * are DIFFERENT tags, same span. Empty / absent for the common single-role node. Both completion
+     * (#415) and a future concordance decode write into this one slot.
+     */
+    interpretations?: ReadonlyArray<Interpretation>;
+}
+/** One additional role a span plays (#413) — see {@link AddressNode.interpretations}. */
+export interface Interpretation {
+    tag: ComponentTag;
+    /** Resolver-supplied normalized place URI for this role (e.g. `wof:101909779`). */
+    placeId?: string;
+    sourceId?: string;
+    /** Centroid for this role's place (a capital-seat comune differs from its province). */
+    lat?: number;
+    lon?: number;
+    confidence?: number;
+    metadata?: Record<string, unknown>;
 }
 /**
  * The full decoded tree for one parsed address.
@@ -112,5 +137,26 @@ export interface AddressTree {
     /** The original raw input text — preserved for round-trip and XML root @raw attribute. */
     raw: string;
     roots: AddressNode[];
+    /**
+     * The addressing SYSTEM this tree was decoded under, which selects the containment hierarchy
+     * (`containmentFor(system)` in `./containment.ts`). Absent means the default Western hierarchy
+     * (`house_number → street → locality → …`).
+     *
+     * This is forward-compat insurance, not yet a behavioral switch: every system currently resolves
+     * to the same map, so an absent or present `system` produces identical trees today. It exists so
+     * that when a genuinely distinct system lands (e.g. Japanese block addressing, where
+     * `building_number` nests under `sub_block`/`block` with no `street` parent), consumers and the
+     * tree builder already carry the discriminator — no `AddressTree` shape change later. A locale
+     * pre-classifier (Phase 6+) is the intended source of this value.
+     */
+    system?: AddressSystem;
 }
+/**
+ * The addressing system a tree was decoded under — selects the containment hierarchy. Western
+ * covers US/EU/most-Latin-script street addressing (`house_number → street → locality`). `japanese`
+ * is declared for forward-compat (block addressing: `building_number → sub_block → block →
+ * district`, no street); it currently shares the Western map until Phase 6 gives it a distinct one.
+ * Open string union so a new system can be added without a breaking enum change.
+ */
+export type AddressSystem = "western" | "japanese" | (string & {});
 //# sourceMappingURL=types.d.ts.map