@mailwoman/resolver 4.13.0

package/out/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/resolver` — the address resolver implementation, lifted out of `@mailwoman/core`
+ *   (#215) so it can depend on `@mailwoman/spatial` (haversine) + `@mailwoman/codex` (USPS
+ *   directionals) instead of reinventing them. The TYPE contract stays in
+ *   `@mailwoman/core/resolver` (so the `core/pipeline` composes the resolver structurally without a
+ *   package cycle); this barrel re-exports it, so `@mailwoman/resolver` is a complete drop-in for
+ *   what used to be `@mailwoman/core/resolver`.
+ */
+export { RemoteResolver, serializableResolveOpts } from "./remote-resolver.js";
+export type { RemoteResolverOpts, ResolveTreeRequest, ResolveTreeResponse, SerializableResolveOpts, } from "./remote-resolver.js";
+export { createWofResolver } from "./resolve.js";
+export { findRescoreCandidate, hasResolvedPlace } from "./span-rescore.js";
+export type { RescoreCandidate, SpanRescoreOptions } from "./span-rescore.js";
+export * from "@mailwoman/core/resolver";
+//# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAA;AAC9E,YAAY,EACX,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,GACvB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAChD,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAC1E,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAI7E,cAAc,0BAA0B,CAAA"}

package/out/index.js

@@ -0,0 +1,19 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/resolver` — the address resolver implementation, lifted out of `@mailwoman/core`
+ *   (#215) so it can depend on `@mailwoman/spatial` (haversine) + `@mailwoman/codex` (USPS
+ *   directionals) instead of reinventing them. The TYPE contract stays in
+ *   `@mailwoman/core/resolver` (so the `core/pipeline` composes the resolver structurally without a
+ *   package cycle); this barrel re-exports it, so `@mailwoman/resolver` is a complete drop-in for
+ *   what used to be `@mailwoman/core/resolver`.
+ */
+export { RemoteResolver, serializableResolveOpts } from "./remote-resolver.js";
+export { createWofResolver } from "./resolve.js";
+export { findRescoreCandidate, hasResolvedPlace } from "./span-rescore.js";
+// The type contract + placetype helpers live in core (pure types, keep core a leaf). Re-export so
+// consumers get the whole surface from `@mailwoman/resolver`.
+export * from "@mailwoman/core/resolver";
+//# sourceMappingURL=index.js.map

package/out/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAA;AAO9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAChD,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAG1E,kGAAkG;AAClG,8DAA8D;AAC9D,cAAc,0BAA0B,CAAA"}

package/out/remote-resolver.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `RemoteResolver` — the `Resolver` interface (`resolveTree`) over HTTP. The adapter the interface
+ *   docstring anticipated (Phase 4.4): a client POSTs a parsed `AddressTree` + the serializable
+ *   `ResolveOpts` to a resolver service, which owns the gazetteer + situs/interpolation shards,
+ *   runs the cascade, and returns the resolved tree. Two payoffs:
+ *
+ *   1. **Multi-instance** — stateless parser nodes (the ~30 MB ONNX model) talk to ONE resolver service
+ *        (the multi-GB gazetteer + shards). `parse` locally, `new RemoteResolver(...).resolveTree`
+ *        remotely — same interface the in-process `WofResolver` satisfies, so it's a drop-in.
+ *   2. **Canary** — point it at a second resolver build (or an adapter fronting Pelias/Nominatim/BAN)
+ *        and diff the resolved trees through the identical contract.
+ *
+ *   Pure transport: `fetch` only, no node-specific deps (runs in the browser too). The
+ *   `addressPoints` / `interpolation` opts are LIVE SQLite handles — not serializable — so they're
+ *   stripped before the POST; the resolver service supplies its own from the tree's region (the
+ *   data lives server-side, which is the whole point). All other opts (defaultCountry, calibration,
+ *   hierarchyCompletion, …) ride along.
+ */
+import type { AddressTree } from "@mailwoman/core/decoder";
+import type { ResolveOpts, Resolver } from "@mailwoman/core/resolver";
+/** `ResolveOpts` minus the non-serializable live lookup handles. What actually crosses the wire. */
+export type SerializableResolveOpts = Omit<ResolveOpts, "addressPoints" | "interpolation">;
+/** Strip the live lookup handles from `ResolveOpts` so the rest can be JSON-serialized over HTTP. */
+export declare function serializableResolveOpts(opts?: ResolveOpts): SerializableResolveOpts | undefined;
+export interface RemoteResolverOpts {
+    /**
+     * Full URL of the resolver service's resolve-tree endpoint, e.g.
+     * `http://resolver:7081/api/resolve-tree`.
+     */
+    endpoint: string;
+    /** Injectable fetch (tests / custom agents). Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Per-request timeout in ms. Default 10000. */
+    timeoutMs?: number;
+    /** Extra headers (auth, tracing). `Content-Type: application/json` is always set. */
+    headers?: Record<string, string>;
+}
+/** The wire request body `POST <endpoint>` expects (and the matching server handler parses). */
+export interface ResolveTreeRequest {
+    tree: AddressTree;
+    opts?: SerializableResolveOpts;
+}
+/** The wire response body the server returns. */
+export interface ResolveTreeResponse {
+    tree: AddressTree;
+}
+export declare class RemoteResolver implements Resolver {
+    #private;
+    constructor(opts: RemoteResolverOpts);
+    resolveTree(tree: AddressTree, opts?: ResolveOpts): Promise<AddressTree>;
+}
+//# sourceMappingURL=remote-resolver.d.ts.map

package/out/remote-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-resolver.d.ts","sourceRoot":"","sources":["../remote-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AAErE,oGAAoG;AACpG,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,WAAW,EAAE,eAAe,GAAG,eAAe,CAAC,CAAA;AAE1F,qGAAqG;AACrG,wBAAgB,uBAAuB,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,uBAAuB,GAAG,SAAS,CAI/F;AAED,MAAM,WAAW,kBAAkB;IAClC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB,gFAAgF;IAChF,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAChC;AAED,gGAAgG;AAChG,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,WAAW,CAAA;IACjB,IAAI,CAAC,EAAE,uBAAuB,CAAA;CAC9B;AAED,iDAAiD;AACjD,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,WAAW,CAAA;CACjB;AAED,qBAAa,cAAe,YAAW,QAAQ;;gBAMlC,IAAI,EAAE,kBAAkB;IAQ9B,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;CAuB9E"}

package/out/remote-resolver.js

@@ -0,0 +1,68 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `RemoteResolver` — the `Resolver` interface (`resolveTree`) over HTTP. The adapter the interface
+ *   docstring anticipated (Phase 4.4): a client POSTs a parsed `AddressTree` + the serializable
+ *   `ResolveOpts` to a resolver service, which owns the gazetteer + situs/interpolation shards,
+ *   runs the cascade, and returns the resolved tree. Two payoffs:
+ *
+ *   1. **Multi-instance** — stateless parser nodes (the ~30 MB ONNX model) talk to ONE resolver service
+ *        (the multi-GB gazetteer + shards). `parse` locally, `new RemoteResolver(...).resolveTree`
+ *        remotely — same interface the in-process `WofResolver` satisfies, so it's a drop-in.
+ *   2. **Canary** — point it at a second resolver build (or an adapter fronting Pelias/Nominatim/BAN)
+ *        and diff the resolved trees through the identical contract.
+ *
+ *   Pure transport: `fetch` only, no node-specific deps (runs in the browser too). The
+ *   `addressPoints` / `interpolation` opts are LIVE SQLite handles — not serializable — so they're
+ *   stripped before the POST; the resolver service supplies its own from the tree's region (the
+ *   data lives server-side, which is the whole point). All other opts (defaultCountry, calibration,
+ *   hierarchyCompletion, …) ride along.
+ */
+/** Strip the live lookup handles from `ResolveOpts` so the rest can be JSON-serialized over HTTP. */
+export function serializableResolveOpts(opts) {
+    if (!opts)
+        return undefined;
+    const { addressPoints: _ap, interpolation: _ip, ...rest } = opts;
+    return rest;
+}
+export class RemoteResolver {
+    #endpoint;
+    #fetch;
+    #timeoutMs;
+    #headers;
+    constructor(opts) {
+        if (!opts.endpoint)
+            throw new Error("RemoteResolver: `endpoint` is required");
+        this.#endpoint = opts.endpoint;
+        this.#fetch = opts.fetch ?? globalThis.fetch;
+        this.#timeoutMs = opts.timeoutMs ?? 10_000;
+        this.#headers = opts.headers ?? {};
+    }
+    async resolveTree(tree, opts) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.#timeoutMs);
+        try {
+            const body = { tree, opts: serializableResolveOpts(opts) };
+            const res = await this.#fetch(this.#endpoint, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", ...this.#headers },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                throw new Error(`RemoteResolver: ${this.#endpoint} → HTTP ${res.status} ${res.statusText}`);
+            }
+            const json = (await res.json());
+            if (!json || !json.tree || !Array.isArray(json.tree.roots)) {
+                throw new Error("RemoteResolver: malformed response (missing `tree.roots`)");
+            }
+            return json.tree;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=remote-resolver.js.map

package/out/remote-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-resolver.js","sourceRoot":"","sources":["../remote-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAQH,qGAAqG;AACrG,MAAM,UAAU,uBAAuB,CAAC,IAAkB;IACzD,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAA;IAC3B,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAA;IAChE,OAAO,IAAI,CAAA;AACZ,CAAC;AA2BD,MAAM,OAAO,cAAc;IACjB,SAAS,CAAQ;IACjB,MAAM,CAAc;IACpB,UAAU,CAAQ;IAClB,QAAQ,CAAwB;IAEzC,YAAY,IAAwB;QACnC,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAA;QAC7E,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAA;QAC9B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAA;QAC5C,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,SAAS,IAAI,MAAM,CAAA;QAC1C,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,CAAA;IACnC,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,IAAiB,EAAE,IAAkB;QACtD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;QACxC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,UAAU,CAAC,CAAA;QACnE,IAAI,CAAC;YACJ,MAAM,IAAI,GAAuB,EAAE,IAAI,EAAE,IAAI,EAAE,uBAAuB,CAAC,IAAI,CAAC,EAAE,CAAA;YAC9E,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE;gBAC7C,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE;gBACjE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;gBAC1B,MAAM,EAAE,UAAU,CAAC,MAAM;aACzB,CAAC,CAAA;YACF,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACb,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,CAAC,SAAS,WAAW,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC,CAAA;YAC5F,CAAC;YACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAiC,CAAA;YAC/D,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC5D,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAA;YAC7E,CAAC;YACD,OAAO,IAAI,CAAC,IAAI,CAAA;QACjB,CAAC;gBAAS,CAAC;YACV,YAAY,CAAC,KAAK,CAAC,CAAA;QACpB,CAAC;IACF,CAAC;CACD"}

package/out/resolve.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `resolveTree` — walk an `AddressTree` top-down and decorate matched nodes with resolver- supplied
+ *   attribution + coordinates.
+ *
+ *   The walk is parent-constraint-aware: when a parent node resolves to a place id, its children's
+ *   lookups are scoped to descendants of that parent. This dramatically narrows the search space
+ *   for ambiguous names — `Springfield` under a resolved `Illinois` parent resolves to the IL one,
+ *   not the MA one.
+ */
+import { type Resolver, type ResolverBackend } from "@mailwoman/core/resolver";
+/**
+ * Build a `Resolver` backed by a `ResolverBackend`. The backend can be any concrete impl
+ * structurally compatible with `PlaceLookup` — e.g. `new WofSqlitePlaceLookup({ databasePath
+ * }).asResolverBackend()` or a fake for tests.
+ */
+export declare function createWofResolver(backend: ResolverBackend): Resolver;
+//# sourceMappingURL=resolve.d.ts.map

package/out/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EASN,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,MAAM,0BAA0B,CAAA;AAIjC;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,eAAe,GAAG,QAAQ,CAEpE"}

package/out/resolve.js

@@ -0,0 +1,570 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `resolveTree` — walk an `AddressTree` top-down and decorate matched nodes with resolver- supplied
+ *   attribution + coordinates.
+ *
+ *   The walk is parent-constraint-aware: when a parent node resolves to a place id, its children's
+ *   lookups are scoped to descendants of that parent. This dramatically narrows the search space
+ *   for ambiguous names — `Springfield` under a resolved `Illinois` parent resolves to the IL one,
+ *   not the MA one.
+ */
+import { isStreetDirectionalToken } from "@mailwoman/codex/us";
+import { DEFAULT_PLACETYPE_MAP, isPlacetypeFallback, } from "@mailwoman/core/resolver";
+import { haversineKm } from "@mailwoman/spatial";
+import { findRescoreCandidate, hasResolvedPlace } from "./span-rescore.js";
+/**
+ * Build a `Resolver` backed by a `ResolverBackend`. The backend can be any concrete impl
+ * structurally compatible with `PlaceLookup` — e.g. `new WofSqlitePlaceLookup({ databasePath
+ * }).asResolverBackend()` or a fake for tests.
+ */
+export function createWofResolver(backend) {
+    return new WofResolver(backend);
+}
+/**
+ * Pick the completion locality when an admin maps to several coincident same-name candidates
+ * (#405). Population is the PRIMARY signal — the principal city is the populous one, and it can sit
+ * FARTHER from the admin centroid than a tiny same-name hamlet (the Niigata case from #403).
+ * Nearest centroid breaks a population tie; a genuine tie (same population AND distance) ABSTAINS
+ * rather than guess.
+ */
+function pickCompletion(candidates) {
+    if (candidates.length === 0)
+        return null;
+    if (candidates.length === 1)
+        return candidates[0];
+    const ranked = [...candidates].sort((a, b) => b.population - a.population || a.distanceKm - b.distanceKm);
+    const [first, second] = ranked;
+    if (first.population === second.population && first.distanceKm === second.distanceKm)
+        return null;
+    return first;
+}
+/**
+ * Find the first postcode value anywhere in the tree (a one-shot pre-scan; postcode and locality
+ * are siblings, so the top-down walk wouldn't otherwise let the locality lookup see it).
+ */
+function firstPostcodeValue(roots) {
+    const stack = [...roots];
+    while (stack.length > 0) {
+        const n = stack.pop();
+        if (n.tag === "postcode" && n.value.trim().length > 0)
+            return n.value.trim();
+        stack.push(...n.children);
+    }
+    return undefined;
+}
+/** Street-name component tags that, with the street node itself, reconstruct the full street string. */
+const STREET_NAME_TAGS = new Set(["street", "street_prefix", "street_prefix_particle", "street_suffix"]);
+/**
+ * Reassemble the full street string from the street node's subtree (#483 coverage fix). The parser
+ * nests the directional/suffix as `street_prefix`/`street_suffix` CHILDREN of `street`
+ * (containment.ts), so `street.value` alone is the bare base name ("Sheldon" for "East Sheldon Rd")
+ * — which misses the coordinate shards keyed on the FULL normalized name. Collect street + its
+ * prefix/particle/suffix descendants (NOT house_number/unit, which also nest under street), order
+ * by span offset, and join.
+ */
+function assembleStreetValue(streetNode, directionalUnit) {
+    const parts = [];
+    const stack = [streetNode];
+    while (stack.length > 0) {
+        const n = stack.pop();
+        if (STREET_NAME_TAGS.has(n.tag) && n.value.trim())
+            parts.push(n);
+        stack.push(...n.children);
+    }
+    // #718 admin-tail: a directional quadrant the model mis-tagged `unit` ("1532 Taylor Street NE" →
+    // [unit] "NE") folds back into the street key by span order, so the situs/interp lookup matches the
+    // shard's "taylor street northeast" (the lookup normalizer expands the abbreviation). Lookup-key
+    // only — the parse output and admin resolution are untouched. Byte-stable when absent (undefined).
+    if (directionalUnit && directionalUnit.value.trim())
+        parts.push(directionalUnit);
+    parts.sort((a, b) => a.start - b.start);
+    return parts.map((n) => n.value.trim()).join(" ");
+}
+/**
+ * Directional quadrant values the model sometimes emits as a `unit` node instead of inside the
+ * street subtree (#718 admin-tail diagnostic: ~19% of the admin-fallback tail, 83% of DC). Folded
+ * into the street lookup key by {@link assembleStreetValue}; the situs/interp lookup normalizer
+ * expands the abbreviation ("ne" → "northeast") so the shard's full street name matches.
+ */
+// The 8 USPS cardinals/intercardinals (abbrev or name) — @codex/us owns the canonical table (#215).
+const isDirectionalUnit = (value) => isStreetDirectionalToken(value.replace(/\./g, ""));
+/**
+ * Address-point tier (#476): find `street` + `house_number` in the tree (first occurrence,
+ * depth-first), scope by the tree's postcode/locality values, and on an exact hit stamp the point
+ * onto the STREET node's metadata. Additive only — admin resolution is never altered.
+ */
+function applyAddressPoint(roots, lookup) {
+    let street;
+    let houseNumber;
+    let directionalUnit;
+    let locality;
+    let postcode;
+    const stack = [...roots];
+    while (stack.length > 0) {
+        const n = stack.pop();
+        if (n.tag === "street" && !street)
+            street = n;
+        if (n.tag === "house_number" && !houseNumber)
+            houseNumber = n;
+        if (n.tag === "unit" && !directionalUnit && isDirectionalUnit(n.value))
+            directionalUnit = n;
+        if (n.tag === "locality" && !locality && n.value.trim())
+            locality = n.value.trim();
+        if (n.tag === "postcode" && !postcode && n.value.trim())
+            postcode = n.value.trim();
+        stack.push(...n.children);
+    }
+    if (!street || !houseNumber)
+        return;
+    const hit = lookup.find({
+        street: assembleStreetValue(street, directionalUnit),
+        number: houseNumber.value,
+        postcode,
+        locality,
+    });
+    if (!hit)
+        return;
+    street.metadata = {
+        ...street.metadata,
+        address_point: { lat: hit.lat, lon: hit.lon, source: hit.source, release: hit.release },
+        resolution_tier: "address_point",
+    };
+}
+/**
+ * House-number interpolation tier (#483): the third rung, consulted ONLY when the exact
+ * address-point tier ({@link applyAddressPoint}) did NOT already stamp the street node
+ * (`resolution_tier === "address_point"`). That gate IS the "after the exact-point fall-through" —
+ * an estimate never overwrites a real situs point. Postcode-scoped (no locality — the interpolators
+ * abstain statewide without a postcode). Stamps a DISTINCT metadata key (`interpolated_point`,
+ * never `address_point`). Additive only — admin resolution is untouched.
+ */
+function applyInterpolation(roots, lookup, radiusCalibration) {
+    let street;
+    let houseNumber;
+    let directionalUnit;
+    let postcode;
+    const stack = [...roots];
+    while (stack.length > 0) {
+        const n = stack.pop();
+        if (n.tag === "street" && !street)
+            street = n;
+        if (n.tag === "house_number" && !houseNumber)
+            houseNumber = n;
+        if (n.tag === "unit" && !directionalUnit && isDirectionalUnit(n.value))
+            directionalUnit = n;
+        if (n.tag === "postcode" && !postcode && n.value.trim())
+            postcode = n.value.trim();
+        stack.push(...n.children);
+    }
+    if (!street || !houseNumber)
+        return;
+    // The fall-through gate: an exact situs point already won — never override it with an estimate.
+    if (street.metadata?.["resolution_tier"] === "address_point")
+        return;
+    const hit = lookup.find({ street: assembleStreetValue(street, directionalUnit), number: houseNumber.value, postcode });
+    if (!hit)
+        return;
+    // Conformal-calibrated radius when the caller supplies a multiplier (#374): the raw half-segment
+    // heuristic underestimates the true spread (~72% coverage on Travis); ×1.70 → a 90% bound. Default
+    // (no multiplier) keeps the raw value, byte-stable. Preserve the raw radius for transparency.
+    const calibrated = radiusCalibration ? Math.round(hit.uncertaintyM * radiusCalibration) : hit.uncertaintyM;
+    street.metadata = {
+        ...street.metadata,
+        interpolated_point: { lat: hit.lat, lon: hit.lon, source: hit.source, release: hit.release },
+        resolution_tier: "interpolated",
+        uncertainty_m: calibrated,
+        ...(radiusCalibration ? { uncertainty_raw_m: hit.uncertaintyM, uncertainty_calibration: radiusCalibration } : {}),
+        interpolation_method: hit.method,
+        ...(hit.parityMatched !== undefined ? { parity_matched: hit.parityMatched } : {}),
+        ...(hit.bracket !== undefined ? { interpolation_bracket: hit.bracket } : {}),
+    };
+}
+/**
+ * Span-rescore tier (#370): opt-in last-resort locality recovery. Runs ONLY when the tree resolved
+ * NOTHING (the #685 brake — never disturb a working coordinate). Enumerates raw-token spans, exact-
+ * matches the same-country gazetteer (longest-wins + postcode-consistency gate; see
+ * `span-rescore.ts`), and on a hit INJECTS a resolved `locality` node decorated exactly like a
+ * normally-resolved one. Byte-stable when `opts.spanRescore` is unset. Async (it queries the
+ * backend), so it's awaited.
+ */
+async function applySpanRescore(roots, raw, backend, opts) {
+    if (hasResolvedPlace(roots))
+        return; // already resolved — never second-guess a working coordinate
+    const hit = await findRescoreCandidate(raw, roots, backend, {
+        country: opts.defaultCountry,
+        postcode: firstPostcodeValue(roots),
+        gateKm: opts.spanRescoreGateKm,
+    });
+    if (!hit)
+        return;
+    const node = {
+        tag: "locality",
+        value: hit.text,
+        start: hit.start,
+        end: hit.end,
+        // No model confidence for a post-hoc recovery; a mid-tier value marks it as recovered, not asserted.
+        confidence: 0.5,
+        children: [],
+    };
+    decorateNode(node, hit.place, []);
+    // `rescore_gated` carries the gate's precision signal as an EXPLICIT handle — NOT folded into the
+    // calibrated `confidence`, which would break the isotonic guarantee (a true calibrated 0.83 must not
+    // be confused with a rescore plug-in estimate; DeepSeek 2026-06-23). true = postcode gate fired
+    // (high-precision); false = ungated (no postcode→point coverage for this country, ~83%-precision).
+    node.metadata = { ...(node.metadata ?? {}), span_rescore: true, rescore_gated: hit.gated };
+    roots.push(node);
+}
+/** A resolved node carries a real coordinate (placeId set + non-zero lat/lon). */
+function isResolvedWithCoord(n) {
+    return !!(n.placeId && typeof n.lat === "number" && typeof n.lon === "number" && (n.lat !== 0 || n.lon !== 0));
+}
+/**
+ * Postcode-disambiguated locality selection (#370 "Lever A"). The single biggest miss on the EU/AU
+ * panel is a same-named town resolved to the WRONG instance — "06260 Saint-Pierre" lands 617 km off
+ * — while the postcode that would disambiguate it (06260 → Alpes-Maritimes) sits resolved in the
+ * same tree, discarded because the coordinate-picker prefers the (wrong) locality node and never
+ * cross- checks it. This post-walk pass closes that loop, backend-agnostically and with no extra
+ * query:
+ *
+ * 1. Find the resolved postcode's coordinate (the trustworthy anchor — a postcode is unambiguous
+ *    within a country in a way a town name is not).
+ * 2. For each resolved locality node farther than `gateKm` from it: re-pick the same-named candidate
+ *    from the node's already-captured `alternatives` that is NEAREST the postcode and within the
+ *    gate. This keeps locality granularity at the CORRECT instance.
+ * 3. If no alternative reconciles, the locality instance is unreliable — fall its coordinate back to
+ *    the postcode point (right area, the safe answer) and flag `postcode_city_mismatch`.
+ *
+ * Only fires where the postcode resolved to a point, so it composes with postcode coverage (#193) —
+ * add a country's postcodes and this immediately disambiguates its same-named towns. Default-off
+ * via `opts.postcodeConsistency`; byte-stable when unset.
+ */
+function applyPostcodeConsistency(roots, gateKm) {
+    // The resolved postcode anchor (first one with a real coordinate).
+    let anchor = null;
+    const findAnchor = [...roots];
+    while (findAnchor.length > 0) {
+        const n = findAnchor.pop();
+        if (n.tag === "postcode" && isResolvedWithCoord(n)) {
+            anchor = { lat: n.lat, lon: n.lon };
+            break;
+        }
+        findAnchor.push(...n.children);
+    }
+    if (!anchor)
+        return; // no postcode→point — nothing to disambiguate against (gate can't fire)
+    const stack = [...roots];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        stack.push(...node.children);
+        if ((node.tag !== "locality" && node.tag !== "dependent_locality") || !isResolvedWithCoord(node))
+            continue;
+        if (haversineKm(anchor.lat, anchor.lon, node.lat, node.lon) <= gateKm)
+            continue; // already consistent
+        // Re-pick: the same-named candidate nearest the postcode, within the gate. `alternatives` is
+        // typed `unknown[]` on the node (decoder/types.ts can't import resolver types) — they ARE the
+        // `ResolvedPlace` runner-ups decorateNode attached, so the cast is sound.
+        const alts = node.alternatives ?? [];
+        const reconciling = alts
+            .filter((a) => a.lat !== 0 || a.lon !== 0)
+            .map((a) => ({ a, d: haversineKm(anchor.lat, anchor.lon, a.lat, a.lon) }))
+            .filter((x) => x.d <= gateKm)
+            .sort((x, y) => x.d - y.d)[0];
+        if (reconciling) {
+            // Swap to the consistent instance; the displaced winner becomes an alternative.
+            const displaced = {
+                id: 0,
+                name: String(node.metadata?.["resolver_name"] ?? node.value),
+                placetype: "locality",
+                country: reconciling.a.country,
+                lat: node.lat,
+                lon: node.lon,
+                score: 0,
+            };
+            const rest = alts.filter((a) => a !== reconciling.a);
+            decorateNode(node, reconciling.a, [displaced, ...rest]);
+            node.metadata = { ...(node.metadata ?? {}), postcode_repicked: true };
+            continue;
+        }
+        // No same-named instance near the postcode → the town is unreliable; trust the postcode's area.
+        node.lat = anchor.lat;
+        node.lon = anchor.lon;
+        node.metadata = { ...(node.metadata ?? {}), postcode_city_mismatch: true, coordinate_source: "postcode_fallback" };
+    }
+}
+class WofResolver {
+    #backend;
+    constructor(backend) {
+        this.#backend = backend;
+    }
+    async resolveTree(tree, opts = {}) {
+        const state = {
+            lookupsRemaining: opts.maxLookups ?? 10,
+            // Full replacement when `placetypeMap` is supplied — callers that want to extend rather
+            // than replace should spread DEFAULT_PLACETYPE_MAP themselves.
+            placetypeMap: opts.placetypeMap ?? DEFAULT_PLACETYPE_MAP,
+            minWinningScore: opts.minWinningScore ?? 0,
+            candidatesPerLookup: opts.candidatesPerLookup ?? 5,
+            defaultCountry: opts.defaultCountry,
+            parentFallback: opts.parentFallback ?? true,
+            postcode: firstPostcodeValue(tree.roots),
+            anchorPosterior: opts.anchorPosterior,
+            anchorWeight: opts.anchorWeight ?? 2.0,
+            hardCountry: opts.hardCountry,
+            // Default-ON (#402): completion only fires for a dual-role region whose locality the parser
+            // dropped, and no-ops entirely when the backend has no relation (the browser WASM resolver, or
+            // a gazetteer without `coincident_roles`). Pass `hierarchyCompletion: false` to opt out.
+            // `cityStateFallback` is the #387 alias that #405 generalized — still honored.
+            hierarchyCompletion: opts.hierarchyCompletion ?? opts.cityStateFallback ?? true,
+            includeAncestors: opts.includeAncestors ?? false,
+            localityNodePresent: false,
+            resolvedRegion: null,
+            resolvedRegionNode: null,
+        };
+        const newRoots = [];
+        for (const root of tree.roots) {
+            newRoots.push(await this.#walk(root, /* parentResolved */ null, state));
+        }
+        // Dual-role hierarchy completion (#405/#415). Only when enabled, a region resolved, and the parser
+        // emitted NO locality — record the dropped locality as a SECONDARY ROLE (an interpretation) on the
+        // resolved region node, from the backend's precomputed coincident-roles relation (#403). One node,
+        // one span, two roles — no synthesized sibling. See ResolveOpts.hierarchyCompletion.
+        if (state.hierarchyCompletion && state.resolvedRegion && state.resolvedRegionNode && !state.localityNodePresent) {
+            this.#completeRegionRole(state.resolvedRegion, state.resolvedRegionNode);
+        }
+        // Postcode-consistency (#370 "Lever A"): opt-in. After the admin walk (needs both the locality
+        // and the postcode resolved) and before the street tiers (which key off the postcode/street, not
+        // the locality coordinate this adjusts). Byte-stable when opts.postcodeConsistency is unset.
+        if (opts.postcodeConsistency) {
+            applyPostcodeConsistency(newRoots, opts.postcodeConsistencyGateKm ?? 50);
+        }
+        // Address-point tier (#476): opt-in street-level exact match. After the admin walk so the
+        // tier can never disturb admin attribution — it only ADDS the precise coordinate. Byte-stable
+        // when opts.addressPoints is absent.
+        if (opts.addressPoints) {
+            applyAddressPoint(newRoots, opts.addressPoints);
+        }
+        // Interpolation tier (#483): strictly AFTER the exact-point block so an estimate can never
+        // override a real situs point (applyInterpolation also gates on resolution_tier). Opt-in;
+        // byte-stable when opts.interpolation is absent.
+        if (opts.interpolation) {
+            applyInterpolation(newRoots, opts.interpolation, opts.interpolationRadiusCalibration);
+        }
+        // Span-rescore tier (#370): opt-in, last (so it only fires when every other tier left the tree
+        // unresolved). Byte-stable when opts.spanRescore is unset.
+        if (opts.spanRescore) {
+            await applySpanRescore(newRoots, tree.raw, this.#backend, opts);
+        }
+        return { raw: tree.raw, roots: newRoots };
+    }
+    /**
+     * Record a dropped dual-role locality as a `locality` INTERPRETATION on the resolved region node
+     * (#415, generalizes #405's synthesized node). Consults `coincidentLocalitiesFor(regionId)` (O(1)
+     * map lookup — no distance math, no backend query), picks the principal city
+     * ({@link pickCompletion}: population-primary, distance tiebreak, abstain on a genuine tie), and
+     * appends an interpretation to `regionNode.interpretations`. No-op when the backend has no
+     * relation, the region isn't a dual-role place, or it abstains. The region node's primary role
+     * stays `region`; the locality rides alongside.
+     */
+    #completeRegionRole(region, regionNode) {
+        if (typeof region.id !== "number" || !this.#backend.coincidentLocalitiesFor)
+            return;
+        const loc = pickCompletion(this.#backend.coincidentLocalitiesFor(region.id));
+        if (!loc)
+            return;
+        const interpretation = {
+            tag: "locality",
+            placeId: `wof:${loc.id}`,
+            sourceId: `${loc.placetype}:${loc.id}`,
+            lat: loc.lat,
+            lon: loc.lon,
+            confidence: 0,
+            metadata: { relationship_type: loc.relationshipType, resolver_completed: true, resolver_name: loc.name },
+        };
+        regionNode.interpretations = [...(regionNode.interpretations ?? []), interpretation];
+    }
+    async #walk(node, parentResolved, state) {
+        // Always clone — never mutate input nodes.
+        const decorated = { ...node, children: [] };
+        const placetype = state.placetypeMap[node.tag];
+        // Track locality presence for hierarchy completion (#405): completion must NOT fire if the parser
+        // already emitted a locality node (even one that failed to resolve) — it only fills a genuine
+        // gap. Cheap and always-on; only consulted when hierarchyCompletion is set.
+        if (placetype === "locality")
+            state.localityNodePresent = true;
+        let resolved = null;
+        if (placetype && state.lookupsRemaining > 0 && node.value.trim().length > 0) {
+            const picked = await this.#lookupAndPick(node, placetype, parentResolved, state);
+            if (picked) {
+                resolved = picked.top;
+                decorateNode(decorated, picked.top, picked.alternatives);
+                // Lineage attachment (#404): stamp the resolved place's ancestor chain onto metadata. Opt-in
+                // + only when the backend supplies it, so the default stays byte-identical (no extra query).
+                if (state.includeAncestors && this.#backend.ancestors) {
+                    decorated.metadata = { ...(decorated.metadata ?? {}), ancestors: this.#backend.ancestors(picked.top.id) };
+                }
+                // Capture the first resolved region (place + node) for hierarchy completion — the locality
+                // interpretation is pushed onto this node in the post-walk pass.
+                if (placetype === "region" && state.resolvedRegion === null) {
+                    state.resolvedRegion = picked.top;
+                    state.resolvedRegionNode = decorated;
+                }
+            }
+        }
+        const carryParent = resolved ?? parentResolved;
+        for (const child of node.children) {
+            decorated.children.push(await this.#walk(child, carryParent, state));
+        }
+        return decorated;
+    }
+    async #lookupAndPick(node, placetype, parentResolved, state) {
+        state.lookupsRemaining--;
+        const query = {
+            text: node.value,
+            placetype,
+            limit: state.candidatesPerLookup,
+        };
+        // Pass the inherited parent constraint to the backend when available — `parentId` scopes to
+        // the resolved parent's descendants. For `country`: a resolved parent's country wins, else
+        // fall back to the caller's `defaultCountry`. Without this top-level hint a bare "IL" over a
+        // multi-country gazetteer fuzzy-matches a foreign place (e.g. a French region) — see the
+        // Direction-C resolver eval.
+        if (parentResolved && typeof parentResolved.id === "number")
+            query.parentId = parentResolved.id;
+        // #194: a resolved parent's country wins, then the caller's `defaultCountry`, then the confident
+        // placer `hardCountry`. All three are a HARD candidate filter. The placer's `hardCountry` is gated
+        // upstream on high confidence (so it only fires when the model is sure), and on a miss the node is
+        // left UNRESOLVED rather than re-resolved globally: the off-continent rows are precisely the ones
+        // whose locality isn't in the country's gazetteer slice, so a global retry would just re-admit the
+        // wrong-continent guess the hard filter exists to drop ("in-region or unresolved"). Measured: a
+        // global fallback collapses back to the soft-prior baseline (FI p90 3050, PL p90 1078); pure-hard
+        // collapses the tail (FI 18 km, PL p99 8172→494) at a coverage-bounded recall cost.
+        const country = parentResolved?.country ?? state.defaultCountry ?? state.hardCountry;
+        if (country)
+            query.country = country;
+        // Coordinate-first: hand the sibling postcode to locality lookups so the backend can inject
+        // postcode-proximal candidates the name-match would miss. Only for locality (the placetype both
+        // `locality` and `dependent_locality` map to); other placetypes ignore it.
+        if (placetype === "locality" && state.postcode)
+            query.postcode = state.postcode;
+        let candidates;
+        try {
+            candidates = await this.#backend.findPlace(query);
+            // Parent soft-gating: `parentId` is a HARD descendant filter in the backend, which wrongly
+            // zeroes the result when the parent resolved wrong OR the gazetteer hierarchy is incomplete
+            // (a real locality whose `ancestors` chain is missing its region). Rather than turn a
+            // resolvable node into an unresolved one, retry once WITHOUT the parent constraint — we
+            // prefer a parent-scoped hit but never sacrifice recall. The country constraint is kept, so
+            // this still can't wander to a foreign place. Same logical resolution → no extra budget.
+            if (candidates.length === 0 && state.parentFallback && query.parentId !== undefined) {
+                delete query.parentId;
+                candidates = await this.#backend.findPlace(query);
+            }
+        }
+        catch {
+            // Defensive: a backend failure should not abort the whole tree walk. Leave the node with
+            // its classifier attribution intact.
+            return null;
+        }
+        if (candidates.length === 0)
+            return null;
+        // Postcode-anchor re-rank (#369): when a country posterior is supplied (from the address's
+        // postcode), boost candidates by `anchorWeight * posterior[candidate.country]` and re-sort, so a
+        // postcode that pins the country pulls the right-country place over a higher-BM25 foreign namesake
+        // (the "Berlin DE vs Berlin US" class the #59 harness measured). No-op when `anchorPosterior` is
+        // undefined (the default) → byte-identical resolution.
+        //
+        // Applied to BOTH region and locality — the two placetypes that suffer cross-country namesake/
+        // abbreviation collisions a country posterior can break. The region case is the one #447's window
+        // fix couldn't reach: a bare 2-letter abbreviation is shared across countries ("VT" is
+        // both Vermont and Viterbo; "ME" both Maine and Messina), so with no country signal the score
+        // picks the wrong one — and because resolveTree resolves region FIRST and inherits its country
+        // down, a wrong region poisons the locality too. The postcode posterior breaks the tie at the
+        // region, and the right country then flows to the locality. (Country/macroregion/county are
+        // excluded: they don't exhibit this collision class and carry country via `parentId` when nested.)
+        //
+        // Tier-SAFE ordering: the candidate's exact-match flag is the PRIMARY key, so the country pin
+        // never crosses the exact/partial boundary. WITHIN a tier, `score + anchorWeight * posterior`
+        // applies the (soft) country boost. So a confident US postcode keeps the US EXACT region
+        // ("ME" → Maine) ahead of a more-populous US PARTIAL match (Missouri) AND, within the exact
+        // tier, ahead of a foreign exact match (Messina IT); a soft posterior still blends with score.
+        // (A plain additive re-rank loses the tier — it isn't encoded in `score` — and flips
+        // "ME" → Missouri / "PA" → Alabama. Backends that don't set `exactMatch` degrade to additive.)
+        const anchorEligible = placetype === "region" || placetype === "locality";
+        let ranked = candidates;
+        if (state.anchorPosterior && anchorEligible && candidates.length > 1) {
+            const post = state.anchorPosterior;
+            const w = state.anchorWeight;
+            ranked = [...candidates].sort((a, b) => Number(b.exactMatch ?? false) - Number(a.exactMatch ?? false) ||
+                b.score + w * (post[b.country] ?? 0) - (a.score + w * (post[a.country] ?? 0)));
+        }
+        // Exact-type preference (#718): when the placetype-equivalence group let a broader admin tier
+        // (`macroregion`/`macrocounty`) into the candidate pool, prefer a candidate of the EXACT
+        // requested type over the macro fallback — a real `region` (US state, DE Bundesland, ES
+        // provincia) must win over a same-name macroregion namesake, so no real region silently
+        // downgrades to a macro. STABLE partition: exact-type candidates keep their (already-ranked)
+        // relative order ahead of fallbacks, so the score / anchor re-rank survives WITHIN each tier.
+        // No-op for placetypes without a macro fallback (the byte-stable default) and when every
+        // candidate is the same tier.
+        const hasFallbackCandidate = ranked.some((c) => isPlacetypeFallback(placetype, c.placetype));
+        if (hasFallbackCandidate && ranked.length > 1) {
+            ranked = [
+                ...ranked.filter((c) => !isPlacetypeFallback(placetype, c.placetype)),
+                ...ranked.filter((c) => isPlacetypeFallback(placetype, c.placetype)),
+            ];
+        }
+        const top = ranked[0];
+        if (top.score < state.minWinningScore)
+            return null;
+        // Fallback-observability (#718): if the winner is a macro-type AND no exact-type candidate
+        // existed for this span, annotate that a broader tier stood in for the true one. Additive —
+        // identity/coordinate are unchanged; only `metadata.resolution_quality` is stamped downstream.
+        if (isPlacetypeFallback(placetype, top.placetype)) {
+            top.resolutionQuality = "fallback";
+        }
+        return { top, alternatives: ranked.slice(1) };
+    }
+}
+/**
+ * Stamp a node with resolver-supplied attribution. Displaces any prior classifier `source` /
+ * `sourceId` into `metadata.classifier_source` / `metadata.classifier_source_id` so debugging tools
+ * can still see who made the original assertion. Surfaces the runner-up candidates on
+ * `alternatives` so callers can disambiguate (Springfield-class failures, [#8 in the failure
+ * catalogue]).
+ */
+function decorateNode(node, resolved, alternatives) {
+    if (node.source !== undefined || node.sourceId !== undefined) {
+        const meta = { ...(node.metadata ?? {}) };
+        if (node.source !== undefined)
+            meta["classifier_source"] = node.source;
+        if (node.sourceId !== undefined)
+            meta["classifier_source_id"] = node.sourceId;
+        node.metadata = meta;
+    }
+    node.source = "resolver";
+    node.sourceId = `${resolved.placetype}:${resolved.id}`;
+    node.lat = resolved.lat;
+    node.lon = resolved.lon;
+    node.placeId = `wof:${resolved.id}`; // v1: only WOF resolvers; the URI scheme stays this simple
+    // Record the resolver's ranking score AND the resolved place's CANONICAL name. The name is the
+    // gazetteer's truth for the place we picked — distinct from `node.value` (the raw input span). It
+    // lets consumers display the canonical name and lets the end-to-end eval check the resolver chose
+    // the right PLACE (gazetteer-name vs ground-truth) rather than merely echoing the parser's text.
+    node.metadata = { ...(node.metadata ?? {}), resolver_score: resolved.score, resolver_name: resolved.name };
+    // The postcode/locality conflict flag (the falsehood differentiator): the postcode pointed to a
+    // geographically different place than the parsed city name. Surface it so callers can warn rather
+    // than silently trust the resolved point.
+    if (resolved.mismatch)
+        node.metadata["postcode_city_mismatch"] = true;
+    // Fallback-observability (#718): a broader admin tier (macroregion/macrocounty) stood in for the
+    // true region/county because no exact-type candidate existed. Additive annotation only — the
+    // resolved coordinate/identity above is untouched; this just lets a consumer / QA pass see it.
+    if (resolved.resolutionQuality)
+        node.metadata["resolution_quality"] = resolved.resolutionQuality;
+    if (alternatives.length > 0) {
+        node.alternatives = alternatives;
+    }
+}
+//# sourceMappingURL=resolve.js.map

package/out/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AAE9D,OAAO,EAGN,qBAAqB,EAErB,mBAAmB,GAMnB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAE1E;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAwB;IACzD,OAAO,IAAI,WAAW,CAAC,OAAO,CAAC,CAAA;AAChC,CAAC;AAyCD;;;;;;GAMG;AACH,SAAS,cAAc,CAAC,UAAyC;IAChE,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACxC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC,CAAC,CAAE,CAAA;IAClD,MAAM,MAAM,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAA;IACzG,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,MAAM,CAAA;IAC9B,IAAI,KAAM,CAAC,UAAU,KAAK,MAAO,CAAC,UAAU,IAAI,KAAM,CAAC,UAAU,KAAK,MAAO,CAAC,UAAU;QAAE,OAAO,IAAI,CAAA;IACrG,OAAO,KAAM,CAAA;AACd,CAAC;AAED;;;GAGG;AACH,SAAS,kBAAkB,CAAC,KAA6B;IACxD,MAAM,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,CAAA;IACxB,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,EAAG,CAAA;QACtB,IAAI,CAAC,CAAC,GAAG,KAAK,UAAU,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAA;QAC5E,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAA;IAC1B,CAAC;IACD,OAAO,SAAS,CAAA;AACjB,CAAC;AAED,wGAAwG;AACxG,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,eAAe,EAAE,wBAAwB,EAAE,eAAe,CAAC,CAAC,CAAA;AAExG;;;;;;;GAOG;AACH,SAAS,mBAAmB,CAAC,UAAuB,EAAE,eAA6B;IAClF,MAAM,KAAK,GAAkB,EAAE,CAAA;IAC/B,MAAM,KAAK,GAAG,CAAC,UAAU,CAAC,CAAA;IAC1B,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,EAAG,CAAA;QACtB,IAAI,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE;YAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QAChE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAA;IAC1B,CAAC;IACD,iGAAiG;IACjG,oGAAoG;IACpG,iGAAiG;IACjG,mGAAmG;IACnG,IAAI,eAAe,IAAI,eAAe,CAAC,KAAK,CAAC,IAAI,EAAE;QAAE,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAA;IAChF,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAA;IACvC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAClD,CAAC;AAED;;;;;GAKG;AACH,oGAAoG;AACpG,MAAM,iBAAiB,GAAG,CAAC,KAAa,EAAW,EAAE,CAAC,wBAAwB,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAA;AAExG;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,KAAoB,EAAE,MAA0B;IAC1E,IAAI,MAA+B,CAAA;IACnC,IAAI,WAAoC,CAAA;IACxC,IAAI,eAAwC,CAAA;IAC5C,IAAI,QAA4B,CAAA;IAChC,IAAI,QAA4B,CAAA;IAChC,MAAM,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,CAAA;IACxB,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,EAAG,CAAA;QACtB,IAAI,CAAC,CAAC,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM;YAAE,MAAM,GAAG,CAAC,CAAA;QAC7C,IAAI,CAAC,CAAC,GAAG,KAAK,cAAc,IAAI,CAAC,WAAW;YAAE,WAAW,GAAG,CAAC,CAAA;QAC7D,IAAI,CAAC,CAAC,GAAG,KAAK,MAAM,IAAI,CAAC,eAAe,IAAI,iBAAiB,CAAC,CAAC,CAAC,KAAK,CAAC;YAAE,eAAe,GAAG,CAAC,CAAA;QAC3F,IAAI,CAAC,CAAC,GAAG,KAAK,UAAU,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE;YAAE,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAA;QAClF,IAAI,CAAC,CAAC,GAAG,KAAK,UAAU,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE;YAAE,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAA;QAClF,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAA;IAC1B,CAAC;IACD,IAAI,CAAC,MAAM,IAAI,CAAC,WAAW;QAAE,OAAM;IACnC,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC;QACvB,MAAM,EAAE,mBAAmB,CAAC,MAAM,EAAE,eAAe,CAAC;QACpD,MAAM,EAAE,WAAW,CAAC,KAAK;QACzB,QAAQ;QACR,QAAQ;KACR,CAAC,CAAA;IACF,IAAI,CAAC,GAAG;QAAE,OAAM;IAChB,MAAM,CAAC,QAAQ,GAAG;QACjB,GAAG,MAAM,CAAC,QAAQ;QAClB,aAAa,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE;QACvF,eAAe,EAAE,eAAe;KAChC,CAAA;AACF,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,kBAAkB,CAAC,KAAoB,EAAE,MAA2B,EAAE,iBAA0B;IACxG,IAAI,MAA+B,CAAA;IACnC,IAAI,WAAoC,CAAA;IACxC,IAAI,eAAwC,CAAA;IAC5C,IAAI,QAA4B,CAAA;IAChC,MAAM,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,CAAA;IACxB,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,EAAG,CAAA;QACtB,IAAI,CAAC,CAAC,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM;YAAE,MAAM,GAAG,CAAC,CAAA;QAC7C,IAAI,CAAC,CAAC,GAAG,KAAK,cAAc,IAAI,CAAC,WAAW;YAAE,WAAW,GAAG,CAAC,CAAA;QAC7D,IAAI,CAAC,CAAC,GAAG,KAAK,MAAM,IAAI,CAAC,eAAe,IAAI,iBAAiB,CAAC,CAAC,CAAC,KAAK,CAAC;YAAE,eAAe,GAAG,CAAC,CAAA;QAC3F,IAAI,CAAC,CAAC,GAAG,KAAK,UAAU,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE;YAAE,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAA;QAClF,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAA;IAC1B,CAAC;IACD,IAAI,CAAC,MAAM,IAAI,CAAC,WAAW;QAAE,OAAM;IACnC,gGAAgG;IAChG,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC,iBAAiB,CAAC,KAAK,eAAe;QAAE,OAAM;IACpE,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,mBAAmB,CAAC,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAA;IACtH,IAAI,CAAC,GAAG;QAAE,OAAM;IAChB,iGAAiG;IACjG,mGAAmG;IACnG,8FAA8F;IAC9F,MAAM,UAAU,GAAG,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,YAAY,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAA;IAC1G,MAAM,CAAC,QAAQ,GAAG;QACjB,GAAG,MAAM,CAAC,QAAQ;QAClB,kBAAkB,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE;QAC5F,eAAe,EAAE,cAAc;QAC/B,aAAa,EAAE,UAAU;QACzB,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,GAAG,CAAC,YAAY,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjH,oBAAoB,EAAE,GAAG,CAAC,MAAM;QAChC,GAAG,CAAC,GAAG,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,GAAG,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjF,GAAG,CAAC,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,qBAAqB,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5E,CAAA;AACF,CAAC;AAED;;;;;;;GAOG;AACH,KAAK,UAAU,gBAAgB,CAC9B,KAAoB,EACpB,GAAW,EACX,OAAwB,EACxB,IAAiB;IAEjB,IAAI,gBAAgB,CAAC,KAAK,CAAC;QAAE,OAAM,CAAC,6DAA6D;IACjG,MAAM,GAAG,GAAG,MAAM,oBAAoB,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE;QAC3D,OAAO,EAAE,IAAI,CAAC,cAAc;QAC5B,QAAQ,EAAE,kBAAkB,CAAC,KAAK,CAAC;QACnC,MAAM,EAAE,IAAI,CAAC,iBAAiB;KAC9B,CAAC,CAAA;IACF,IAAI,CAAC,GAAG;QAAE,OAAM;IAChB,MAAM,IAAI,GAAgB;QACzB,GAAG,EAAE,UAAU;QACf,KAAK,EAAE,GAAG,CAAC,IAAI;QACf,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,GAAG,EAAE,GAAG,CAAC,GAAG;QACZ,qGAAqG;QACrG,UAAU,EAAE,GAAG;QACf,QAAQ,EAAE,EAAE;KACZ,CAAA;IACD,YAAY,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;IACjC,kGAAkG;IAClG,qGAAqG;IACrG,gGAAgG;IAChG,mGAAmG;IACnG,IAAI,CAAC,QAAQ,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,CAAC,KAAK,EAAE,CAAA;IAC1F,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACjB,CAAC;AAED,kFAAkF;AAClF,SAAS,mBAAmB,CAAC,CAAc;IAC1C,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC,CAAC,GAAG,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,GAAG,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;AAC/G,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAS,wBAAwB,CAAC,KAA6B,EAAE,MAAc;IAC9E,mEAAmE;IACnE,IAAI,MAAM,GAAwC,IAAI,CAAA;IACtD,MAAM,UAAU,GAAkB,CAAC,GAAG,KAAK,CAAC,CAAA;IAC5C,OAAO,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,UAAU,CAAC,GAAG,EAAG,CAAA;QAC3B,IAAI,CAAC,CAAC,GAAG,KAAK,UAAU,IAAI,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC;YACpD,MAAM,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,GAAI,EAAE,GAAG,EAAE,CAAC,CAAC,GAAI,EAAE,CAAA;YACrC,MAAK;QACN,CAAC;QACD,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAA;IAC/B,CAAC;IACD,IAAI,CAAC,MAAM;QAAE,OAAM,CAAC,wEAAwE;IAE5F,MAAM,KAAK,GAAkB,CAAC,GAAG,KAAK,CAAC,CAAA;IACvC,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,EAAG,CAAA;QACzB,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAA;QAC5B,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,UAAU,IAAI,IAAI,CAAC,GAAG,KAAK,oBAAoB,CAAC,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC;YAAE,SAAQ;QAC1G,IAAI,WAAW,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,GAAI,EAAE,IAAI,CAAC,GAAI,CAAC,IAAI,MAAM;YAAE,SAAQ,CAAC,qBAAqB;QAEvG,6FAA6F;QAC7F,8FAA8F;QAC9F,0EAA0E;QAC1E,MAAM,IAAI,GAAI,IAAI,CAAC,YAA4C,IAAI,EAAE,CAAA;QACrE,MAAM,WAAW,GAAG,IAAI;aACtB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC;aACzC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC,MAAO,CAAC,GAAG,EAAE,MAAO,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;aAC3E,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC;aAC5B,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QAC9B,IAAI,WAAW,EAAE,CAAC;YACjB,gFAAgF;YAChF,MAAM,SAAS,GAAkB;gBAChC,EAAE,EAAE,CAAC;gBACL,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,eAAe,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC;gBAC5D,SAAS,EAAE,UAAU;gBACrB,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,OAAO;gBAC9B,GAAG,EAAE,IAAI,CAAC,GAAI;gBACd,GAAG,EAAE,IAAI,CAAC,GAAI;gBACd,KAAK,EAAE,CAAC;aACR,CAAA;YACD,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,WAAW,CAAC,CAAC,CAAC,CAAA;YACpD,YAAY,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,CAAC,CAAA;YACvD,IAAI,CAAC,QAAQ,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAA;YACrE,SAAQ;QACT,CAAC;QACD,gGAAgG;QAChG,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAA;QACrB,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAA;QACrB,IAAI,CAAC,QAAQ,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,sBAAsB,EAAE,IAAI,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,CAAA;IACnH,CAAC;AACF,CAAC;AAED,MAAM,WAAW;IACP,QAAQ,CAAiB;IAElC,YAAY,OAAwB;QACnC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAA;IACxB,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,IAAiB,EAAE,OAAoB,EAAE;QAC1D,MAAM,KAAK,GAAoB;YAC9B,gBAAgB,EAAE,IAAI,CAAC,UAAU,IAAI,EAAE;YACvC,wFAAwF;YACxF,+DAA+D;YAC/D,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,qBAAqB;YACxD,eAAe,EAAE,IAAI,CAAC,eAAe,IAAI,CAAC;YAC1C,mBAAmB,EAAE,IAAI,CAAC,mBAAmB,IAAI,CAAC;YAClD,cAAc,EAAE,IAAI,CAAC,cAAc;YACnC,cAAc,EAAE,IAAI,CAAC,cAAc,IAAI,IAAI;YAC3C,QAAQ,EAAE,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC;YACxC,eAAe,EAAE,IAAI,CAAC,eAAe;YACrC,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,GAAG;YACtC,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,4FAA4F;YAC5F,+FAA+F;YAC/F,yFAAyF;YACzF,+EAA+E;YAC/E,mBAAmB,EAAE,IAAI,CAAC,mBAAmB,IAAI,IAAI,CAAC,iBAAiB,IAAI,IAAI;YAC/E,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,IAAI,KAAK;YAChD,mBAAmB,EAAE,KAAK;YAC1B,cAAc,EAAE,IAAI;YACpB,kBAAkB,EAAE,IAAI;SACxB,CAAA;QAED,MAAM,QAAQ,GAAkB,EAAE,CAAA;QAClC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC/B,QAAQ,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,oBAAoB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAA;QACxE,CAAC;QAED,mGAAmG;QACnG,mGAAmG;QACnG,mGAAmG;QACnG,qFAAqF;QACrF,IAAI,KAAK,CAAC,mBAAmB,IAAI,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC,kBAAkB,IAAI,CAAC,KAAK,CAAC,mBAAmB,EAAE,CAAC;YACjH,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAA;QACzE,CAAC;QAED,+FAA+F;QAC/F,iGAAiG;QACjG,6FAA6F;QAC7F,IAAI,IAAI,CAAC,mBAAmB,EAAE,CAAC;YAC9B,wBAAwB,CAAC,QAAQ,EAAE,IAAI,CAAC,yBAAyB,IAAI,EAAE,CAAC,CAAA;QACzE,CAAC;QACD,0FAA0F;QAC1F,8FAA8F;QAC9F,qCAAqC;QACrC,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,iBAAiB,CAAC,QAAQ,EAAE,IAAI,CAAC,aAAa,CAAC,CAAA;QAChD,CAAC;QACD,2FAA2F;QAC3F,0FAA0F;QAC1F,iDAAiD;QACjD,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,kBAAkB,CAAC,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,8BAA8B,CAAC,CAAA;QACtF,CAAC;QACD,+FAA+F;QAC/F,2DAA2D;QAC3D,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,MAAM,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;QAChE,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAA;IAC1C,CAAC;IAED;;;;;;;;OAQG;IACH,mBAAmB,CAAC,MAAqB,EAAE,UAAuB;QACjE,IAAI,OAAO,MAAM,CAAC,EAAE,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,uBAAuB;YAAE,OAAM;QACnF,MAAM,GAAG,GAAG,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,uBAAuB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAA;QAC5E,IAAI,CAAC,GAAG;YAAE,OAAM;QAChB,MAAM,cAAc,GAAmB;YACtC,GAAG,EAAE,UAAU;YACf,OAAO,EAAE,OAAO,GAAG,CAAC,EAAE,EAAE;YACxB,QAAQ,EAAE,GAAG,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,EAAE,EAAE;YACtC,GAAG,EAAE,GAAG,CAAC,GAAG;YACZ,GAAG,EAAE,GAAG,CAAC,GAAG;YACZ,UAAU,EAAE,CAAC;YACb,QAAQ,EAAE,EAAE,iBAAiB,EAAE,GAAG,CAAC,gBAAgB,EAAE,kBAAkB,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,CAAC,IAAI,EAAE;SACxG,CAAA;QACD,UAAU,CAAC,eAAe,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,eAAe,IAAI,EAAE,CAAC,EAAE,cAAc,CAAC,CAAA;IACrF,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAiB,EAAE,cAAoC,EAAE,KAAsB;QAC1F,2CAA2C;QAC3C,MAAM,SAAS,GAAgB,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAA;QAExD,MAAM,SAAS,GAAG,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,GAAmB,CAAC,CAAA;QAC9D,kGAAkG;QAClG,8FAA8F;QAC9F,4EAA4E;QAC5E,IAAI,SAAS,KAAK,UAAU;YAAE,KAAK,CAAC,mBAAmB,GAAG,IAAI,CAAA;QAC9D,IAAI,QAAQ,GAAyB,IAAI,CAAA;QACzC,IAAI,SAAS,IAAI,KAAK,CAAC,gBAAgB,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7E,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,cAAc,EAAE,KAAK,CAAC,CAAA;YAChF,IAAI,MAAM,EAAE,CAAC;gBACZ,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAA;gBACrB,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,YAAY,CAAC,CAAA;gBACxD,6FAA6F;gBAC7F,6FAA6F;gBAC7F,IAAI,KAAK,CAAC,gBAAgB,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC;oBACvD,SAAS,CAAC,QAAQ,GAAG,EAAE,GAAG,CAAC,SAAS,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAA;gBAC1G,CAAC;gBACD,2FAA2F;gBAC3F,iEAAiE;gBACjE,IAAI,SAAS,KAAK,QAAQ,IAAI,KAAK,CAAC,cAAc,KAAK,IAAI,EAAE,CAAC;oBAC7D,KAAK,CAAC,cAAc,GAAG,MAAM,CAAC,GAAG,CAAA;oBACjC,KAAK,CAAC,kBAAkB,GAAG,SAAS,CAAA;gBACrC,CAAC;YACF,CAAC;QACF,CAAC;QAED,MAAM,WAAW,GAAG,QAAQ,IAAI,cAAc,CAAA;QAC9C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC,CAAA;QACrE,CAAC;QACD,OAAO,SAAS,CAAA;IACjB,CAAC;IAED,KAAK,CAAC,cAAc,CACnB,IAAiB,EACjB,SAAiB,EACjB,cAAoC,EACpC,KAAsB;QAEtB,KAAK,CAAC,gBAAgB,EAAE,CAAA;QAExB,MAAM,KAAK,GAAgD;YAC1D,IAAI,EAAE,IAAI,CAAC,KAAK;YAChB,SAAS;YACT,KAAK,EAAE,KAAK,CAAC,mBAAmB;SAChC,CAAA;QACD,4FAA4F;QAC5F,2FAA2F;QAC3F,6FAA6F;QAC7F,yFAAyF;QACzF,6BAA6B;QAC7B,IAAI,cAAc,IAAI,OAAO,cAAc,CAAC,EAAE,KAAK,QAAQ;YAAE,KAAK,CAAC,QAAQ,GAAG,cAAc,CAAC,EAAE,CAAA;QAC/F,iGAAiG;QACjG,mGAAmG;QACnG,mGAAmG;QACnG,kGAAkG;QAClG,mGAAmG;QACnG,gGAAgG;QAChG,kGAAkG;QAClG,oFAAoF;QACpF,MAAM,OAAO,GAAG,cAAc,EAAE,OAAO,IAAI,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC,WAAW,CAAA;QACpF,IAAI,OAAO;YAAE,KAAK,CAAC,OAAO,GAAG,OAAO,CAAA;QACpC,4FAA4F;QAC5F,gGAAgG;QAChG,2EAA2E;QAC3E,IAAI,SAAS,KAAK,UAAU,IAAI,KAAK,CAAC,QAAQ;YAAE,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAA;QAE/E,IAAI,UAA2B,CAAA;QAC/B,IAAI,CAAC;YACJ,UAAU,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;YACjD,2FAA2F;YAC3F,4FAA4F;YAC5F,sFAAsF;YACtF,wFAAwF;YACxF,4FAA4F;YAC5F,yFAAyF;YACzF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;gBACrF,OAAO,KAAK,CAAC,QAAQ,CAAA;gBACrB,UAAU,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;YAClD,CAAC;QACF,CAAC;QAAC,MAAM,CAAC;YACR,yFAAyF;YACzF,qCAAqC;YACrC,OAAO,IAAI,CAAA;QACZ,CAAC;QAED,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAA;QACxC,2FAA2F;QAC3F,iGAAiG;QACjG,mGAAmG;QACnG,iGAAiG;QACjG,uDAAuD;QACvD,EAAE;QACF,+FAA+F;QAC/F,kGAAkG;QAClG,uFAAuF;QACvF,8FAA8F;QAC9F,+FAA+F;QAC/F,8FAA8F;QAC9F,4FAA4F;QAC5F,mGAAmG;QACnG,EAAE;QACF,8FAA8F;QAC9F,8FAA8F;QAC9F,yFAAyF;QACzF,4FAA4F;QAC5F,+FAA+F;QAC/F,qFAAqF;QACrF,+FAA+F;QAC/F,MAAM,cAAc,GAAG,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,UAAU,CAAA;QACzE,IAAI,MAAM,GAAG,UAAU,CAAA;QACvB,IAAI,KAAK,CAAC,eAAe,IAAI,cAAc,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtE,MAAM,IAAI,GAAG,KAAK,CAAC,eAAe,CAAA;YAClC,MAAM,CAAC,GAAG,KAAK,CAAC,YAAY,CAAA;YAC5B,MAAM,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC,IAAI,CAC5B,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACR,MAAM,CAAC,CAAC,CAAC,UAAU,IAAI,KAAK,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,UAAU,IAAI,KAAK,CAAC;gBAC7D,CAAC,CAAC,KAAK,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAC9E,CAAA;QACF,CAAC;QAED,8FAA8F;QAC9F,yFAAyF;QACzF,wFAAwF;QACxF,wFAAwF;QACxF,6FAA6F;QAC7F,8FAA8F;QAC9F,yFAAyF;QACzF,8BAA8B;QAC9B,MAAM,oBAAoB,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,mBAAmB,CAAC,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAA;QAC5F,IAAI,oBAAoB,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC/C,MAAM,GAAG;gBACR,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,mBAAmB,CAAC,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;gBACrE,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,mBAAmB,CAAC,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;aACpE,CAAA;QACF,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAE,CAAA;QACtB,IAAI,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,eAAe;YAAE,OAAO,IAAI,CAAA;QAClD,2FAA2F;QAC3F,4FAA4F;QAC5F,+FAA+F;QAC/F,IAAI,mBAAmB,CAAC,SAAS,EAAE,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACnD,GAAG,CAAC,iBAAiB,GAAG,UAAU,CAAA;QACnC,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAA;IAC9C,CAAC;CACD;AAED;;;;;;GAMG;AACH,SAAS,YAAY,CAAC,IAAiB,EAAE,QAAuB,EAAE,YAA6B;IAC9F,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC9D,MAAM,IAAI,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,CAAA;QACzC,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAAC,MAAM,CAAA;QACtE,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;YAAE,IAAI,CAAC,sBAAsB,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAA;QAC7E,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAA;IACrB,CAAC;IACD,IAAI,CAAC,MAAM,GAAG,UAAU,CAAA;IACxB,IAAI,CAAC,QAAQ,GAAG,GAAG,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAA;IACtD,IAAI,CAAC,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAA;IACvB,IAAI,CAAC,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAA;IACvB,IAAI,CAAC,OAAO,GAAG,OAAO,QAAQ,CAAC,EAAE,EAAE,CAAA,CAAC,2DAA2D;IAC/F,+FAA+F;IAC/F,kGAAkG;IAClG,kGAAkG;IAClG,iGAAiG;IACjG,IAAI,CAAC,QAAQ,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,cAAc,EAAE,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAA;IAC1G,gGAAgG;IAChG,kGAAkG;IAClG,0CAA0C;IAC1C,IAAI,QAAQ,CAAC,QAAQ;QAAE,IAAI,CAAC,QAAQ,CAAC,wBAAwB,CAAC,GAAG,IAAI,CAAA;IACrE,iGAAiG;IACjG,6FAA6F;IAC7F,+FAA+F;IAC/F,IAAI,QAAQ,CAAC,iBAAiB;QAAE,IAAI,CAAC,QAAQ,CAAC,oBAAoB,CAAC,GAAG,QAAQ,CAAC,iBAAiB,CAAA;IAChG,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAA;IACjC,CAAC;AACF,CAAC"}

package/out/span-rescore.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   #370 span-rescore — recover a dropped/fragmented locality from the RAW text when a parse fails to
+ *   resolve. The model sometimes fragments an accented or non-ASCII locality token ("Grudziądz"
+ *   splits into "Grudzi" + "dz" on the ą combining mark, #555), so neither fragment resolves and
+ *   the address comes back with no coordinate. But the whole word sits intact in the raw input — a
+ *   whitespace tokenizer sees it where the model's subword tokenizer didn't.
+ *
+ *   This module is the PURE, backend-agnostic core: enumerate contiguous raw-token spans, exact-match
+ *   them against the same-country gazetteer, and return the best locality candidate. The resolver
+ *   (`resolve.ts` → `applySpanRescore`) owns the integration: it runs this ONLY on an unresolved
+ *   tree (the #685 brake — never second-guess a working coordinate) and injects the recovered
+ *   locality as a resolved node. Opt-in via `ResolveOpts.spanRescore`; default-off + byte-stable
+ *   when unset.
+ *
+ *   The design + thresholds are validated on a 7-locale coordinate panel
+ *   (`scripts/eval/span-rescore-validate.ts`, eval
+ *   `docs/articles/evals/2026-06-23-370-span-rescore.mdx`): longest-exact-match-wins (the gold
+ *   locality is usually the LONGER, more-specific name — shortest- wins grabs the ambiguous prefix
+ *   "Tomaszów" of "Tomaszów Mazowiecki", 135 km off), and a postcode- consistency gate that rejects
+ *   a match far from where the postcode resolves (kills coverage-gap false-positives where the
+ *   backend has postcode coverage).
+ */
+import type { AddressNode } from "@mailwoman/core/decoder";
+import type { ResolvedPlace, ResolverBackend } from "@mailwoman/core/resolver";
+export interface SpanRescoreOptions {
+    /**
+     * ISO-3166 alpha-2 country to constrain the gazetteer match (the parse's detected/ default
+     * country).
+     */
+    country?: string;
+    /**
+     * Sibling postcode — used both as the backend disambiguation hint AND the consistency-gate
+     * anchor.
+     */
+    postcode?: string;
+    /**
+     * Reject a candidate whose coordinate is farther than this (km) from the postcode anchor. The
+     * gate only fires when the postcode resolves to a point in the backend; otherwise it can't and
+     * the match is accepted (so it never penalizes a backend without postcode coverage). 0 disables.
+     * Default 50.
+     */
+    gateKm?: number;
+    /** Max contiguous raw tokens to treat as one locality span. Default 4. */
+    maxSpanTokens?: number;
+    /**
+     * Min confidence for a street/house_number/postcode node to count as a span-blocking constituent.
+     * Default 0.7.
+     */
+    confidentThreshold?: number;
+}
+/** The recovered locality: the raw span and the gazetteer place it resolved to. */
+export interface RescoreCandidate {
+    /** The raw text of the winning span. */
+    text: string;
+    /** Char offsets of the span in the raw input. */
+    start: number;
+    end: number;
+    /** The resolved gazetteer place (decorate a node with this). */
+    place: ResolvedPlace;
+    /**
+     * Whether the postcode-consistency gate FIRED for this recovery — i.e. the postcode resolved to a
+     * point and the match was validated within `gateKm` of it. `true` = high-precision (postcode-
+     * consistent); `false` = ungated (no postcode→point coverage for this country, so the match
+     * wasn't geo-validated — the ~83%-precision case). The caller surfaces this as
+     * `metadata.rescore_gated` so a consumer can threshold on it WITHOUT a hidden per-country
+     * coverage map. Deliberately NOT folded into the calibrated `confidence` — that would break the
+     * isotonic guarantee (a true calibrated 0.83 must not be confused with a rescore plug-in
+     * estimate).
+     */
+    gated: boolean;
+}
+/** True if any node in the tree already carries a resolved place id — the #685 brake. */
+export declare function hasResolvedPlace(roots: readonly AddressNode[]): boolean;
+/**
+ * Find the best locality the raw text exact-matches in the gazetteer. Returns null when nothing
+ * matches (or the postcode gate rejects every match). Callers gate on `hasResolvedPlace` first.
+ */
+export declare function findRescoreCandidate(raw: string, roots: readonly AddressNode[], backend: ResolverBackend, opts?: SpanRescoreOptions): Promise<RescoreCandidate | null>;
+//# sourceMappingURL=span-rescore.d.ts.map

package/out/span-rescore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-rescore.d.ts","sourceRoot":"","sources":["../span-rescore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAG9E,MAAM,WAAW,kBAAkB;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,mFAAmF;AACnF,MAAM,WAAW,gBAAgB;IAChC,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAA;IACZ,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,gEAAgE;IAChE,KAAK,EAAE,aAAa,CAAA;IACpB;;;;;;;;;OASG;IACH,KAAK,EAAE,OAAO,CAAA;CACd;AAyBD,yFAAyF;AACzF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,OAAO,CAQvE;AAwBD;;;GAGG;AACH,wBAAsB,oBAAoB,CACzC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,OAAO,EAAE,eAAe,EACxB,IAAI,GAAE,kBAAuB,GAC3B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAoDlC"}

package/out/span-rescore.js

@@ -0,0 +1,125 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   #370 span-rescore — recover a dropped/fragmented locality from the RAW text when a parse fails to
+ *   resolve. The model sometimes fragments an accented or non-ASCII locality token ("Grudziądz"
+ *   splits into "Grudzi" + "dz" on the ą combining mark, #555), so neither fragment resolves and
+ *   the address comes back with no coordinate. But the whole word sits intact in the raw input — a
+ *   whitespace tokenizer sees it where the model's subword tokenizer didn't.
+ *
+ *   This module is the PURE, backend-agnostic core: enumerate contiguous raw-token spans, exact-match
+ *   them against the same-country gazetteer, and return the best locality candidate. The resolver
+ *   (`resolve.ts` → `applySpanRescore`) owns the integration: it runs this ONLY on an unresolved
+ *   tree (the #685 brake — never second-guess a working coordinate) and injects the recovered
+ *   locality as a resolved node. Opt-in via `ResolveOpts.spanRescore`; default-off + byte-stable
+ *   when unset.
+ *
+ *   The design + thresholds are validated on a 7-locale coordinate panel
+ *   (`scripts/eval/span-rescore-validate.ts`, eval
+ *   `docs/articles/evals/2026-06-23-370-span-rescore.mdx`): longest-exact-match-wins (the gold
+ *   locality is usually the LONGER, more-specific name — shortest- wins grabs the ambiguous prefix
+ *   "Tomaszów" of "Tomaszów Mazowiecki", 135 km off), and a postcode- consistency gate that rejects
+ *   a match far from where the postcode resolves (kills coverage-gap false-positives where the
+ *   backend has postcode coverage).
+ */
+import { haversineKm } from "@mailwoman/spatial";
+/** Normalize for exact comparison: lowercase, strip diacritics + punctuation, collapse whitespace. */
+const norm = (s) => s
+    .toLowerCase()
+    .normalize("NFD")
+    .replace(/[^a-z0-9 ]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+/** Whitespace/punctuation tokenization of the raw input, char offsets preserved, diacritics intact. */
+function tokenizeRaw(raw) {
+    const toks = [];
+    const re = /[^\s,;/]+/g;
+    let m;
+    while ((m = re.exec(raw)) !== null)
+        toks.push({ text: m[0], start: m.index, end: m.index + m[0].length });
+    return toks;
+}
+/** True if any node in the tree already carries a resolved place id — the #685 brake. */
+export function hasResolvedPlace(roots) {
+    const stack = [...roots];
+    while (stack.length) {
+        const n = stack.pop();
+        if (n.placeId)
+            return true;
+        if (n.children?.length)
+            stack.push(...n.children);
+    }
+    return false;
+}
+/**
+ * Char ranges of confident street/house_number/postcode constituents — a locality span must not
+ * overlap them.
+ */
+function confidentRanges(roots, threshold) {
+    const out = [];
+    const stack = [...roots];
+    while (stack.length) {
+        const n = stack.pop();
+        if ((n.tag === "postcode" || n.tag === "house_number" || n.tag === "street") &&
+            (n.confidence ?? 0) >= threshold &&
+            Number.isFinite(n.start) &&
+            Number.isFinite(n.end)) {
+            out.push([n.start, n.end]);
+        }
+        if (n.children?.length)
+            stack.push(...n.children);
+    }
+    return out;
+}
+/**
+ * Find the best locality the raw text exact-matches in the gazetteer. Returns null when nothing
+ * matches (or the postcode gate rejects every match). Callers gate on `hasResolvedPlace` first.
+ */
+export async function findRescoreCandidate(raw, roots, backend, opts = {}) {
+    const gateKm = opts.gateKm ?? 50;
+    const maxSpan = opts.maxSpanTokens ?? 4;
+    const threshold = opts.confidentThreshold ?? 0.7;
+    const country = opts.country;
+    const postcode = opts.postcode?.trim() || undefined;
+    // Postcode-consistency anchor: where does the postcode itself resolve? (No-op when the backend has
+    // no postcode coverage — findPlace returns nothing → no anchor → gate can't fire → match accepted.)
+    let anchor = null;
+    if (postcode && gateKm > 0) {
+        const pcHits = await backend.findPlace({ text: postcode, country, limit: 2 });
+        const a = pcHits.find((h) => h.lat !== 0 || h.lon !== 0);
+        if (a)
+            anchor = { lat: a.lat, lon: a.lon };
+    }
+    const toks = tokenizeRaw(raw);
+    const avoid = confidentRanges(roots, threshold);
+    const overlapsAvoid = (s, e) => avoid.some(([as, ae]) => s < ae && as < e);
+    const spans = [];
+    for (let len = Math.min(maxSpan, toks.length); len >= 1; len--) {
+        for (let i = 0; i + len <= toks.length; i++) {
+            const start = toks[i].start;
+            const end = toks[i + len - 1].end;
+            if (overlapsAvoid(start, end))
+                continue;
+            spans.push({ text: raw.slice(start, end), start, end, len });
+        }
+    }
+    spans.sort((a, b) => b.len - a.len);
+    for (const sp of spans) {
+        const key = norm(sp.text);
+        if (key.length < 2 || /^\d+$/.test(key))
+            continue; // skip bare numbers / empties
+        const hits = await backend.findPlace({ text: sp.text, country, postcode, placetype: "locality", limit: 5 });
+        const exact = hits.filter((h) => h.exactMatch && norm(h.name) === key && (h.lat !== 0 || h.lon !== 0));
+        for (const h of exact) {
+            if (anchor && gateKm > 0 && haversineKm(anchor.lat, anchor.lon, h.lat, h.lon) > gateKm)
+                continue;
+            // gated = the postcode anchor existed AND validated this match (within gateKm). When no anchor
+            // (no postcode→point coverage), the match is ungated — returned, but flagged lower-precision.
+            return { text: sp.text, start: sp.start, end: sp.end, place: h, gated: anchor !== null };
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=span-rescore.js.map

package/out/span-rescore.js.map

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

package/out/vitest.config.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Per-package vitest config for @mailwoman/resolver. The resolver's OWN files run from source
+ *   (vitest transpiles ./resolve.ts etc.); its workspace deps — @mailwoman/core, /spatial, /codex —
+ *   resolve to their compiled `out/` (built by `tsc -b`). vitest's default resolution doesn't
+ *   traverse a sibling workspace's package-exports for a transitive import (e.g. spatial →
+ *   @mailwoman/core/ objects), so the aliases below pin them explicitly. Most subpaths are
+ *   directories (→ `<dir>/ index.js`); the handful that are bare files (`objects`) get a
+ *   more-specific alias FIRST.
+ */
+declare const _default: import("vite").UserConfig;
+export default _default;
+//# sourceMappingURL=vitest.config.d.ts.map

package/out/vitest.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest.config.d.ts","sourceRoot":"","sources":["../vitest.config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;;AASH,wBAiBE"}

package/out/vitest.config.js

@@ -0,0 +1,37 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Per-package vitest config for @mailwoman/resolver. The resolver's OWN files run from source
+ *   (vitest transpiles ./resolve.ts etc.); its workspace deps — @mailwoman/core, /spatial, /codex —
+ *   resolve to their compiled `out/` (built by `tsc -b`). vitest's default resolution doesn't
+ *   traverse a sibling workspace's package-exports for a transitive import (e.g. spatial →
+ *   @mailwoman/core/ objects), so the aliases below pin them explicitly. Most subpaths are
+ *   directories (→ `<dir>/ index.js`); the handful that are bare files (`objects`) get a
+ *   more-specific alias FIRST.
+ */
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "vitest/config";
+const here = fileURLToPath(new URL(".", import.meta.url));
+const out = (pkg, sub) => resolve(here, `../${pkg}/out/${sub}`);
+export default defineConfig({
+    resolve: {
+        alias: [
+            // Order matters — file-subpaths (objects.ts → objects.js) before the directory regex.
+            { find: /^@mailwoman\/core\/objects$/, replacement: out("core", "objects.js") },
+            { find: /^@mailwoman\/core\/(.+)$/, replacement: resolve(here, "../core/out/$1/index.js") },
+            { find: /^@mailwoman\/core$/, replacement: out("core", "index.js") },
+            { find: /^@mailwoman\/spatial\/(.+)$/, replacement: resolve(here, "../spatial/out/$1/index.js") },
+            { find: /^@mailwoman\/spatial$/, replacement: out("spatial", "index.js") },
+            { find: /^@mailwoman\/codex\/(.+)$/, replacement: resolve(here, "../codex/out/$1/index.js") },
+            { find: /^@mailwoman\/codex$/, replacement: out("codex", "index.js") },
+        ],
+    },
+    test: {
+        isolate: true,
+        exclude: ["**/node_modules/**", "**/out/**", "**/dist/**"],
+    },
+});
+//# sourceMappingURL=vitest.config.js.map

package/out/vitest.config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest.config.js","sourceRoot":"","sources":["../vitest.config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAE5C,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;AACzD,MAAM,GAAG,GAAG,CAAC,GAAW,EAAE,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,EAAE,CAAC,CAAA;AAE/E,eAAe,YAAY,CAAC;IAC3B,OAAO,EAAE;QACR,KAAK,EAAE;YACN,sFAAsF;YACtF,EAAE,IAAI,EAAE,6BAA6B,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE;YAC/E,EAAE,IAAI,EAAE,0BAA0B,EAAE,WAAW,EAAE,OAAO,CAAC,IAAI,EAAE,yBAAyB,CAAC,EAAE;YAC3F,EAAE,IAAI,EAAE,oBAAoB,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE;YACpE,EAAE,IAAI,EAAE,6BAA6B,EAAE,WAAW,EAAE,OAAO,CAAC,IAAI,EAAE,4BAA4B,CAAC,EAAE;YACjG,EAAE,IAAI,EAAE,uBAAuB,EAAE,WAAW,EAAE,GAAG,CAAC,SAAS,EAAE,UAAU,CAAC,EAAE;YAC1E,EAAE,IAAI,EAAE,2BAA2B,EAAE,WAAW,EAAE,OAAO,CAAC,IAAI,EAAE,0BAA0B,CAAC,EAAE;YAC7F,EAAE,IAAI,EAAE,qBAAqB,EAAE,WAAW,EAAE,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE;SACtE;KACD;IACD,IAAI,EAAE;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,CAAC,oBAAoB,EAAE,WAAW,EAAE,YAAY,CAAC;KAC1D;CACD,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@mailwoman/resolver",
+  "version": "4.13.0",
+  "description": "The address resolver: walk an AddressTree, decorate nodes with gazetteer-supplied coordinates + attribution. Backend-agnostic (any ResolverBackend), with the span-rescore + postcode-consistency levers. Lifted out of @mailwoman/core so it can depend on @mailwoman/spatial (haversine) + @mailwoman/codex (USPS directionals) instead of reinventing them; the type contract stays in core so the pipeline composes it without a cycle.",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sister-software/mailwoman.git",
+    "directory": "resolver"
+  },
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./out/index.js"
+  },
+  "dependencies": {
+    "@mailwoman/codex": "4.13.0",
+    "@mailwoman/core": "4.13.0",
+    "@mailwoman/spatial": "4.13.0"
+  },
+  "files": [
+    "out/**/*.js",
+    "out/**/*.js.map",
+    "out/**/*.d.ts",
+    "out/**/*.d.ts.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}