@mailwoman/core 4.0.0 → 4.1.0

package/out/classification/Classification.d.ts

@@ -9,12 +9,12 @@ import type { LibPostalLanguageCode } from "../resources/libpostal.js";
 /**
  * Classification recognized by Mailwoman.
  */
-export declare const Classifications: Set<"country" | "region" | "locality" | "postcode" | "house_number" | "street" | "street_prefix" | "street_suffix" | "unit" | "venue" | "adjacent" | "alpha" | "alphanumeric" | "area" | "chain" | "dependency" | "directional" | "end_token_single_character" | "end_token" | "given_name" | "intersection" | "level_designator" | "level" | "middle_initial" | "multistreet" | "numeric" | "ordinal" | "person" | "personal_suffix" | "personal_title" | "place" | "punctuation" | "road_type" | "start_token" | "stop_word" | "street_name" | "street_proper_name" | "surname" | "toponym" | "unit_designator" | "unknown">;
+export declare const Classifications: Set<"adjacent" | "alpha" | "alphanumeric" | "area" | "chain" | "country" | "dependency" | "directional" | "end_token_single_character" | "end_token" | "given_name" | "house_number" | "intersection" | "level_designator" | "level" | "locality" | "middle_initial" | "multistreet" | "numeric" | "ordinal" | "person" | "personal_suffix" | "personal_title" | "place" | "postcode" | "punctuation" | "region" | "road_type" | "start_token" | "stop_word" | "street_name" | "street_prefix" | "street_proper_name" | "street_suffix" | "street" | "surname" | "toponym" | "unit_designator" | "unit" | "unknown" | "venue">;
 export type Classification = typeof Classifications extends Set<infer T> ? T : never;
 /**
  * Public classification labels.
  */
-declare const VisibleClassification: Set<"country" | "region" | "locality" | "postcode" | "house_number" | "street" | "unit" | "venue" | "dependency" | "level_designator" | "level" | "unit_designator">;
+declare const VisibleClassification: Set<"country" | "dependency" | "house_number" | "level_designator" | "level" | "locality" | "postcode" | "region" | "street" | "unit_designator" | "unit" | "venue">;
 /**
  * Classification labels that are exposed to API consumers.
  */

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

@@ -10,9 +10,9 @@
  *   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). 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.
+ *        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.
@@ -22,6 +22,7 @@
  *   Source order is still preserved in the `start`/`end` fields, which the XML serializer exposes
  *   as attributes.
  */
+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
@@ -39,6 +40,13 @@ export interface BuildTreeOpts {
      * 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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,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;CACtB;AAqHD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,IAAI,GAAE,aAAkB,GAAG,WAAW,CAe3G"}
+{"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

@@ -10,9 +10,9 @@
  *   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). 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.
+ *        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.
@@ -53,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;

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

@@ -44,5 +44,5 @@ export declare function containmentFor(_system?: AddressSystem): Partial<Record<
  * in new code so the system parameter threads through; this export remains for existing call
  * sites.
  */
-export declare const PARENT_OF: Partial<Record<"country" | "region" | "locality" | "dependent_locality" | "postcode" | "subregion" | "house_number" | "street" | "street_prefix" | "street_prefix_particle" | "street_suffix" | "intersection_a" | "intersection_b" | "unit" | "venue" | "attention" | "po_box" | "cedex" | "prefecture" | "municipality" | "district" | "block" | "sub_block" | "building_number" | "building_name", ("country" | "region" | "locality" | "dependent_locality" | "postcode" | "subregion" | "house_number" | "street" | "street_prefix" | "street_prefix_particle" | "street_suffix" | "intersection_a" | "intersection_b" | "unit" | "venue" | "attention" | "po_box" | "cedex" | "prefecture" | "municipality" | "district" | "block" | "sub_block" | "building_number" | "building_name")[]>>;
+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/index.d.ts

@@ -4,6 +4,7 @@
  * @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";

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;AAC1B,cAAc,oBAAoB,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,6 +4,7 @@
  * @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";

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;AAC1B,cAAc,oBAAoB,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":"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"}

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.

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../decoder/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEnE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAA;AAEtC;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC5B,+FAA+F;IAC/F,KAAK,EAAE,MAAM,CAAA;IACb,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAA;IACb,0DAA0D;IAC1D,GAAG,EAAE,MAAM,CAAA;IACX,2CAA2C;IAC3C,KAAK,EAAE,QAAQ,CAAA;IACf,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC3B,GAAG,EAAE,YAAY,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,WAAW,EAAE,CAAA;IACvB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iGAAiG;IACjG,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,kGAAkG;IAClG,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;CACrC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC3B,0FAA0F;IAC1F,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,WAAW,EAAE,CAAA;IACpB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,aAAa,CAAA;CACtB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,UAAU,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../decoder/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEnE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAA;AAEtC;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC5B,+FAA+F;IAC/F,KAAK,EAAE,MAAM,CAAA;IACb,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAA;IACb,0DAA0D;IAC1D,GAAG,EAAE,MAAM,CAAA;IACX,2CAA2C;IAC3C,KAAK,EAAE,QAAQ,CAAA;IACf,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC3B,GAAG,EAAE,YAAY,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,WAAW,EAAE,CAAA;IACvB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iGAAiG;IACjG,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,kGAAkG;IAClG,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;IACrC;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,CAAA;CAC/C;AAED,yFAAyF;AACzF,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,YAAY,CAAA;IACjB,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,wFAAwF;IACxF,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC3B,0FAA0F;IAC1F,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,WAAW,EAAE,CAAA;IACpB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,aAAa,CAAA;CACtB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,UAAU,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA"}

package/out/pipeline/runtime-pipeline.d.ts

@@ -11,7 +11,9 @@
  *
  *   Implementation contract per `docs/articles/plan/reference/STAGES.md`.
  */
-import type { PipelineOpts, PipelineResult, RuntimePipelineStages } from "./types.js";
+import type { AddressTree } from "../decoder/types.js";
+import type { ClassifierCandidate } from "./reconcile.js";
+import type { PhraseProposal, PipelineOpts, PipelineResult, RuntimePipelineStages } from "./types.js";
 /**
  * Run the runtime pipeline.
  *
@@ -26,4 +28,18 @@ import type { PipelineOpts, PipelineResult, RuntimePipelineStages } from "./type
  * Per-stage timing recorded on `result.timing`. Fast-path stages are absent from the timing map.
  */
 export declare function runPipeline(raw: string, stages: RuntimePipelineStages, opts?: PipelineOpts): Promise<PipelineResult>;
+/**
+ * Post-classification audit: for each phrase-grouper proposal whose span is entirely unlabeled
+ * (all-O) in the classifier output, inject a provisional node using the grouper's structural
+ * hypothesis. This rescues spans the neural model couldn't type — primarily venue text.
+ *
+ * When `classifierTopK` is supplied (the joint-reconcile path), the audit defers to the
+ * classifier's own verdict for the orphaned span: if the classifier confidently typed it as a
+ * DIFFERENT component than the phrase kind, we inject the classifier's tag rather than the
+ * structural guess. Without this, a reconciler that leaves a street-prefix word like `Via` orphaned
+ * (because it picked the single `Trento` street span) would see the audit promote `Via`'s
+ * LOCALITY_PHRASE to a spurious `locality` node — burying the real trailing city. The classifier
+ * said `street:0.73` for `Via`; trust it (#425).
+ */
+export declare function grouperAudit(tree: AddressTree, proposals: PhraseProposal[], text: string, classifierTopK?: ClassifierCandidate[]): AddressTree;
 //# sourceMappingURL=runtime-pipeline.d.ts.map

package/out/pipeline/runtime-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-pipeline.d.ts","sourceRoot":"","sources":["../../pipeline/runtime-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EAQX,YAAY,EACZ,cAAc,EAGd,qBAAqB,EACrB,MAAM,YAAY,CAAA;AA4HnB;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAChC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,qBAAqB,EAC7B,IAAI,CAAC,EAAE,YAAY,GACjB,OAAO,CAAC,cAAc,CAAC,CAqJzB"}
+{"version":3,"file":"runtime-pipeline.d.ts","sourceRoot":"","sources":["../../pipeline/runtime-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAe,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEnE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AAGzD,OAAO,KAAK,EAOX,cAAc,EACd,YAAY,EACZ,cAAc,EAGd,qBAAqB,EACrB,MAAM,YAAY,CAAA;AA4HnB;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAChC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,qBAAqB,EAC7B,IAAI,CAAC,EAAE,YAAY,GACjB,OAAO,CAAC,cAAc,CAAC,CA8JzB;AA2DD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC3B,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,cAAc,EAAE,EAC3B,IAAI,EAAE,MAAM,EACZ,cAAc,CAAC,EAAE,mBAAmB,EAAE,GACpC,WAAW,CA2Eb"}

package/out/pipeline/runtime-pipeline.js

@@ -190,13 +190,16 @@ export async function runPipeline(raw, stages, opts) {
         timing["phrase-grouper"] = performance.now() - tGroup;
     }
     let tree = { raw: normalized.normalized, roots: [] };
-    // Joint-reconcile path: opt-in until phrase-grouper proposal quality supports it as default.
-    // The reconciler produces single-token spans when phrase proposals don't cover multi-word
-    // streets/localities — needs grouper improvements before becoming the default path.
-    const useJointReconcile = opts?.forceJointReconcile &&
-        phraseProposals.length > 0 &&
-        stages.classifier &&
-        "parseWithLogits" in stages.classifier;
+    // Captured from the joint-reconcile path so the grouper-audit can defer to the classifier's
+    // per-span verdict on orphaned spans (see the assignment + grouperAudit below).
+    let auditClassifierTopK;
+    // Joint-reconcile path: DEFAULT as of Route A Phase II (#427). It beats argmax on every measured
+    // locale with per-field regression under 0.5% (report: docs/articles/evals/2026-06-07-route-a-
+    // phase-ii-regate.md). Set `jointReconcile: false` (or the deprecated `forceJointReconcile: false`)
+    // to force the legacy argmax sort. Still requires a phrase grouper + a `parseWithLogits` classifier;
+    // without either, the pipeline falls back to argmax regardless of the flag.
+    const jointEnabled = opts?.jointReconcile ?? opts?.forceJointReconcile ?? true;
+    const useJointReconcile = jointEnabled && phraseProposals.length > 0 && stages.classifier && "parseWithLogits" in stages.classifier;
     if (useJointReconcile) {
         const classifierWithLogits = stages.classifier;
         throwIfAborted(opts);
@@ -208,7 +211,7 @@ export async function runPipeline(raw, stages, opts) {
         // The classifier must expose its label vocabulary so the aggregation can strip BIO prefixes.
         // NeuralAddressClassifier surfaces this as `cfg.labels` — extracted via structural typing here.
         const labels = "labels" in classifierWithLogits ? classifierWithLogits.labels : [];
-        const classifierTopK = aggregateSpanLogits(logits, pieces, phraseProposals.map((p) => ({ start: p.span.start, end: p.span.end })), { labels });
+        const classifierTopK = aggregateSpanLogits(logits, pieces, phraseProposals.map((p) => ({ start: p.span.start, end: p.span.end })), { labels, text: normalized.normalized });
         if (classifierTopK.length > 0) {
             const result = reconcileSpans({
                 raw: normalized.normalized,
@@ -216,6 +219,12 @@ export async function runPipeline(raw, stages, opts) {
                 classifierTopK,
             });
             tree = result.tree;
+            // The reconciler can leave a span uncovered (e.g. it picked the single-token street
+            // `Trento` over `Via Trento`, orphaning `Via`). The grouper-audit below would then promote
+            // that orphan's LOCALITY_PHRASE proposal to a `locality` node — even though the classifier
+            // confidently typed it `street`. Hand the audit the classifier's per-span verdict so it
+            // respects that opinion instead of trusting the structural phrase kind (#425 re-gate).
+            auditClassifierTopK = classifierTopK;
         }
         else {
             tree = argmaxTree;
@@ -230,7 +239,7 @@ export async function runPipeline(raw, stages, opts) {
     }
     if (phraseProposals.length > 0 && tree.roots.length >= 0) {
         const tAudit = performance.now();
-        tree = grouperAudit(tree, phraseProposals, normalized.normalized);
+        tree = grouperAudit(tree, phraseProposals, normalized.normalized, auditClassifierTopK);
         timing["grouper-audit"] = performance.now() - tAudit;
     }
     if (stages.resolver) {
@@ -298,8 +307,16 @@ const PHRASE_KIND_TO_TAG = new Map([
  * Post-classification audit: for each phrase-grouper proposal whose span is entirely unlabeled
  * (all-O) in the classifier output, inject a provisional node using the grouper's structural
  * hypothesis. This rescues spans the neural model couldn't type — primarily venue text.
+ *
+ * When `classifierTopK` is supplied (the joint-reconcile path), the audit defers to the
+ * classifier's own verdict for the orphaned span: if the classifier confidently typed it as a
+ * DIFFERENT component than the phrase kind, we inject the classifier's tag rather than the
+ * structural guess. Without this, a reconciler that leaves a street-prefix word like `Via` orphaned
+ * (because it picked the single `Trento` street span) would see the audit promote `Via`'s
+ * LOCALITY_PHRASE to a spurious `locality` node — burying the real trailing city. The classifier
+ * said `street:0.73` for `Via`; trust it (#425).
  */
-function grouperAudit(tree, proposals, text) {
+export function grouperAudit(tree, proposals, text, classifierTopK) {
     if (proposals.length === 0)
         return tree;
     const roots = [...tree.roots];
@@ -312,15 +329,47 @@ function grouperAudit(tree, proposals, text) {
         }
     };
     collectNodes(roots);
+    // Index the classifier's single best tag per exact span (start:end) so the audit can defer to it.
+    const CLASSIFIER_OVERRIDE_MIN = 0.4;
+    const bestTagBySpan = new Map();
+    for (const c of classifierTopK ?? []) {
+        const k = `${c.span.start}:${c.span.end}`;
+        const cur = bestTagBySpan.get(k);
+        if (!cur || c.score > cur.score)
+            bestTagBySpan.set(k, { tag: c.tag, score: c.score });
+    }
+    // Tags that may appear AT MOST ONCE per address. On the joint path, the reconciler has already
+    // placed the confident locality/region/postcode; a SECOND one injected here is almost always a
+    // street-name word the OOD model mistyped ("Via Francesca Nord" → `Francesca`) or an area-line
+    // prefix ("LUGAR …" / "URBANIZACION …"). Suppressing the duplicate keeps the real trailing city
+    // from being shadowed by an earlier-positioned spurious node in `decodeAsJson` (#425 residual tail).
+    const SINGLETON_TAGS = new Set(["locality", "region", "postcode", "country"]);
+    const presentSingletons = new Set();
+    const collectSingletons = (nodes) => {
+        for (const n of nodes) {
+            if (SINGLETON_TAGS.has(n.tag))
+                presentSingletons.add(n.tag);
+            if (n.children)
+                collectSingletons(n.children);
+        }
+    };
+    collectSingletons(roots);
+    const dedupeSingletons = classifierTopK !== undefined; // joint path only — argmax stays byte-stable
     for (const proposal of proposals) {
-        const tag = PHRASE_KIND_TO_TAG.get(proposal.kindHypothesis);
-        if (!tag)
+        const phraseTag = PHRASE_KIND_TO_TAG.get(proposal.kindHypothesis);
+        if (!phraseTag)
             continue;
         const pStart = proposal.span.start;
         const pEnd = pStart + proposal.span.body.length;
         const covered = allNodes.some((node) => node.start < pEnd && pStart < node.end);
         if (covered)
             continue;
+        // Defer to the classifier when it confidently typed this exact span as something else.
+        const classifierVerdict = bestTagBySpan.get(`${proposal.span.start}:${proposal.span.end}`);
+        const tag = classifierVerdict && classifierVerdict.score >= CLASSIFIER_OVERRIDE_MIN ? classifierVerdict.tag : phraseTag;
+        // Don't inject a second singleton-tag node when the reconciler already produced one.
+        if (dedupeSingletons && SINGLETON_TAGS.has(tag) && presentSingletons.has(tag))
+            continue;
         const provisionalNode = {
             tag,
             value: text.slice(pStart, pEnd),
@@ -332,6 +381,8 @@ function grouperAudit(tree, proposals, text) {
             sourceId: `grouper:${proposal.kindHypothesis}`,
         };
         roots.push(provisionalNode);
+        if (SINGLETON_TAGS.has(tag))
+            presentSingletons.add(tag);
     }
     roots.sort((a, b) => a.start - b.start);
     return { raw: tree.raw, roots };