@mailwoman/core 4.12.0 → 4.14.0

package/out/resolver/types.d.ts

@@ -7,7 +7,7 @@
  *   lookup backend.
  *
  *   The interface is deliberately decoupled from any specific resolver implementation. The first
- *   shipped impl is `@mailwoman/resolver-wof-sqlite`, but the same contract supports a future
+ *   shipped impl is `@mailwoman/core/resolver-wof-sqlite`, but the same contract supports a future
  *   `RemoteResolver` adapter (Phase 4.4 — Pelias / BAN / Nominatim) without a public-API break.
  *
  *   See `docs/plan/phases/PHASE_4_3_resolver_integration.md` for the design intent.
@@ -15,8 +15,8 @@
 import type { AddressTree, ComponentTag } from "../decoder/types.js";
 /**
  * One candidate place returned by a resolver. Mirrors the shape used by
- * `@mailwoman/resolver-wof-sqlite`'s `PlaceCandidate` — kept structurally compatible so a callsite
- * holding a `PlaceCandidate` can be passed where a `ResolvedPlace` is expected.
+ * `@mailwoman/core/resolver-wof-sqlite`'s `PlaceCandidate` — kept structurally compatible so a
+ * callsite holding a `PlaceCandidate` can be passed where a `ResolvedPlace` is expected.
  */
 export interface ResolvedPlace {
     /** Resolver-specific place identifier (e.g. WOF id). */
@@ -69,8 +69,8 @@ export interface ResolvedPlace {
  * Pull-based contract for a single resolver query. The resolver knows nothing about `AddressTree` —
  * it just answers "what place is named X, optionally constrained by Y?"
  *
- * Structurally compatible with `PlaceLookup` from `@mailwoman/resolver-wof-sqlite` so the latter
- * satisfies this interface without an adapter shim.
+ * Structurally compatible with `PlaceLookup` from `@mailwoman/core/resolver-wof-sqlite` so the
+ * latter satisfies this interface without an adapter shim.
  */
 export interface ResolverBackend {
     findPlace(query: {
@@ -254,6 +254,19 @@ export interface ResolveOpts {
      * the harness swept). Only consulted when `anchorPosterior` is set.
      */
     anchorWeight?: number;
+    /**
+     * #743/#194 — a CONFIDENT coarse-placer country applied as a HARD candidate filter
+     * (`query.country`), not the soft {@link anchorPosterior} boost. This collapses the off-continent
+     * tail for LOW-population places the soft prior can't move (FI/PL — their towns lose to a
+     * high-pop namesake in the population-first gazetteer even when the country is pinned). On a miss
+     * the node is left UNRESOLVED ("in-region or 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 fallback just re-admits the wrong-continent guess (measured: it collapses
+     * back to the soft-prior baseline). The win is coverage-bounded: tail collapse at a recall cost
+     * set by how complete the country's gazetteer is (PL −9.5pp, FI −32pp). Undefined (default) →
+     * byte-stable. Ignored when a resolved parent or {@link defaultCountry} already pins the country.
+     */
+    hardCountry?: string;
     /**
      * Recover the dropped locality in a DUAL-ROLE-place address (#405, epic #402). Many places occupy
      * multiple admin tiers under one name — city-states (Berlin/Hamburg/Bremen = city == state),
@@ -303,6 +316,39 @@ export interface ResolveOpts {
      * Report: docs/articles/evals/2026-06-14-interp-radius-calibration.md.
      */
     interpolationRadiusCalibration?: number;
+    /**
+     * Span-rescore tier (#370). When set, AND the tree resolved nothing, recover a dropped/fragmented
+     * locality from the raw text: enumerate raw-token spans, exact-match the same-country gazetteer
+     * (longest-wins + postcode-consistency gate), and inject the recovered locality as a resolved
+     * node. Targets the EU no-result tail the model leaves when it fragments an accented locality
+     * token ("Grudziądz" → "Grudzi"+"dz", #555). Default-off + byte-stable when unset; never disturbs
+     * a tree that already resolved (the #685 brake). Validated in
+     * `docs/articles/evals/2026-06-23-370-span-rescore.mdx`.
+     */
+    spanRescore?: boolean;
+    /**
+     * Postcode-consistency gate radius (km) for the span-rescore tier — reject a recovered locality
+     * farther than this from where the postcode resolves. Only bites when the backend has postcode
+     * coverage (else no anchor, no gate). Default 50.
+     */
+    spanRescoreGateKm?: number;
+    /**
+     * Postcode-disambiguated locality selection (#370 "Lever A"). When set, AND a locality resolves
+     * far from a resolved sibling postcode, re-pick the same-named candidate (from the lookup's
+     * already- captured `alternatives`) nearest the postcode; if none reconciles within the gate,
+     * fall the coordinate back to the postcode point and flag `postcode_city_mismatch`. Targets the
+     * dominant failure mode on the EU/AU panel — a same-named town resolved to the wrong instance
+     * while the postcode that would disambiguate it sits resolved in the same tree (e.g. "06260
+     * Saint-Pierre" → 617 km off, postcode 06260 correct). Only bites where the backend resolved the
+     * postcode to a point (so it composes with postcode coverage, #193). Default-off + byte-stable
+     * when unset.
+     */
+    postcodeConsistency?: boolean;
+    /**
+     * Gate radius (km) for {@link postcodeConsistency} — a locality farther than this from the
+     * resolved postcode is re-picked or demoted. Default 50.
+     */
+    postcodeConsistencyGateKm?: number;
     hierarchyCompletion?: boolean;
     /** @deprecated Renamed to {@link hierarchyCompletion} (#405 generalized #387). Still honored. */
     cityStateFallback?: boolean;
@@ -358,9 +404,10 @@ export declare const DEFAULT_PLACETYPE_MAP: PlacetypeMap;
  *   candidate (which is QA-visible). Same exact-type preference applies.
  *
  * This table is the single source of truth for that expansion, shared by every lookup backend
- * (`@mailwoman/resolver-wof-sqlite`, `@mailwoman/resolver-wof-wasm`, and the demo's httpvfs lookup)
- * so the Node and browser resolvers can't drift. Keyed by the REQUESTED placetype. Placetypes
- * without an entry pass through unchanged — an explicit `placetype: "borough"` query stays narrow.
+ * (`@mailwoman/core/resolver-wof-sqlite`, `@mailwoman/core/resolver-wof-wasm`, and the demo's
+ * httpvfs lookup) so the Node and browser resolvers can't drift. Keyed by the REQUESTED placetype.
+ * Placetypes without an entry pass through unchanged — an explicit `placetype: "borough"` query
+ * stays narrow.
  */
 export declare const PLACETYPE_FILTER_GROUPS: Readonly<Record<string, readonly string[]>>;
 /**

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

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

package/out/resolver/types.js

@@ -7,7 +7,7 @@
  *   lookup backend.
  *
  *   The interface is deliberately decoupled from any specific resolver implementation. The first
- *   shipped impl is `@mailwoman/resolver-wof-sqlite`, but the same contract supports a future
+ *   shipped impl is `@mailwoman/core/resolver-wof-sqlite`, but the same contract supports a future
  *   `RemoteResolver` adapter (Phase 4.4 — Pelias / BAN / Nominatim) without a public-API break.
  *
  *   See `docs/plan/phases/PHASE_4_3_resolver_integration.md` for the design intent.
@@ -50,9 +50,10 @@ export const DEFAULT_PLACETYPE_MAP = {
  *   candidate (which is QA-visible). Same exact-type preference applies.
  *
  * This table is the single source of truth for that expansion, shared by every lookup backend
- * (`@mailwoman/resolver-wof-sqlite`, `@mailwoman/resolver-wof-wasm`, and the demo's httpvfs lookup)
- * so the Node and browser resolvers can't drift. Keyed by the REQUESTED placetype. Placetypes
- * without an entry pass through unchanged — an explicit `placetype: "borough"` query stays narrow.
+ * (`@mailwoman/core/resolver-wof-sqlite`, `@mailwoman/core/resolver-wof-wasm`, and the demo's
+ * httpvfs lookup) so the Node and browser resolvers can't drift. Keyed by the REQUESTED placetype.
+ * Placetypes without an entry pass through unchanged — an explicit `placetype: "borough"` query
+ * stays narrow.
  */
 export const PLACETYPE_FILTER_GROUPS = {
     locality: ["locality", "borough", "localadmin"],

package/out/resolver/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../resolver/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAkUH,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IAClD,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,UAAU;IACpB,kBAAkB,EAAE,UAAU;IAC9B,SAAS,EAAE,QAAQ;IACnB,0FAA0F;IAC1F,6FAA6F;IAC7F,2FAA2F;IAC3F,QAAQ,EAAE,YAAY;CACtB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAgD;IACnF,QAAQ,EAAE,CAAC,UAAU,EAAE,SAAS,EAAE,YAAY,CAAC;IAC/C,MAAM,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,MAAM,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC;CACjC,CAAA;AAUD,MAAM,UAAU,qBAAqB,CAAC,UAAoC;IACzE,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAA;IAC5B,MAAM,GAAG,GAAa,EAAE,CAAA;IACxB,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACpC,KAAK,MAAM,QAAQ,IAAI,uBAAuB,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAC1E,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QAChD,CAAC;IACF,CAAC;IACD,OAAO,GAAG,CAAA;AACX,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,yBAAyB,GAAwB,IAAI,GAAG,CAAC,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC,CAAA;AAE9F;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,kBAA0B,EAAE,kBAA0B;IACzF,MAAM,KAAK,GAAG,uBAAuB,CAAC,kBAAkB,CAAC,CAAA;IACzD,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAA;IACxB,IAAI,kBAAkB,KAAK,kBAAkB;QAAE,OAAO,KAAK,CAAA;IAC3D,OAAO,yBAAyB,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAA;AAC/F,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../resolver/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAgXH,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IAClD,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,UAAU;IACpB,kBAAkB,EAAE,UAAU;IAC9B,SAAS,EAAE,QAAQ;IACnB,0FAA0F;IAC1F,6FAA6F;IAC7F,2FAA2F;IAC3F,QAAQ,EAAE,YAAY;CACtB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAgD;IACnF,QAAQ,EAAE,CAAC,UAAU,EAAE,SAAS,EAAE,YAAY,CAAC;IAC/C,MAAM,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,MAAM,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC;CACjC,CAAA;AAUD,MAAM,UAAU,qBAAqB,CAAC,UAAoC;IACzE,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAA;IAC5B,MAAM,GAAG,GAAa,EAAE,CAAA;IACxB,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACpC,KAAK,MAAM,QAAQ,IAAI,uBAAuB,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAC1E,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QAChD,CAAC;IACF,CAAC;IACD,OAAO,GAAG,CAAA;AACX,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,yBAAyB,GAAwB,IAAI,GAAG,CAAC,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC,CAAA;AAE9F;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,kBAA0B,EAAE,kBAA0B;IACzF,MAAM,KAAK,GAAG,uBAAuB,CAAC,kBAAkB,CAAC,CAAA;IACzD,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAA;IACxB,IAAI,kBAAkB,KAAK,kBAAkB;QAAE,OAAO,KAAK,CAAA;IAC3D,OAAO,yBAAyB,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAA;AAC/F,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailwoman/core",
-  "version": "4.12.0",
+  "version": "4.14.0",
   "description": "Mailwoman core: tokenization, classification primitives, solver, formatter, resources, filters, solvers, utils.",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -66,7 +66,7 @@
     "pino-pretty": "^13.1.3",
     "pluralize": "^8.0.0",
     "regenerate": "^1.4.2",
-    "spliterator": "^2.0.0",
+    "spliterator": "^2.2.1",
     "table": "^6.9.0"
   },
   "devDependencies": {

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

@@ -1,56 +0,0 @@
-/**
- * @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 "../decoder/types.js";
-import type { ResolveOpts, Resolver } from "./types.js";
-/** `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/resolver/remote-resolver.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"remote-resolver.d.ts","sourceRoot":"","sources":["../../resolver/remote-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAEvD,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/resolver/remote-resolver.js

@@ -1,68 +0,0 @@
-/**
- * @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/resolver/remote-resolver.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"remote-resolver.js","sourceRoot":"","sources":["../../resolver/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/resolver/resolve.d.ts

@@ -1,21 +0,0 @@
-/**
- * @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 "./types.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 declare function createWofResolver(backend: ResolverBackend): Resolver;
-//# sourceMappingURL=resolve.d.ts.map

package/out/resolver/resolve.d.ts.map

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