@mailwoman/resolver-wof-sqlite 2.1.0

package/out/street-normalize.js

@@ -0,0 +1,176 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   THE street normalizer for the address-point tier (#476). One function, used by BOTH the shard
+ *   builder (`scripts/build-address-point-shard.ts`) and the lookup tier (`address-point.ts`) —
+ *   never two implementations (the PLACETYPE_ORDER lesson: parallel copies silently corrupt).
+ *
+ *   Normalization contract (deliberately aggressive — both sides apply the same function, so
+ *   collisions only need to be _consistent_, not linguistically perfect):
+ *
+ *   1. Lowercase, NFKD-fold diacritics, collapse whitespace, strip punctuation (periods, commas,
+ *        apostrophes).
+ *   2. Expand USPS directional abbreviations at the FIRST and LAST token position (`n` → `north`, `se` →
+ *        `southeast`) — Overture sources abbreviate inconsistently.
+ *   3. Canonicalize a trailing USPS street-type token via the codex suffix table to its canonical full
+ *        form (`st`/`str`/`street` → `street`).
+ *
+ *   Numbered streets are left as digits (`5th` stays `5th`); a SPELLED ordinal before a street suffix
+ *   folds to its digit form (`tenth street` → `10th street`, #723) so the grid-city ordinal
+ *   cross-streets the source data spells with digits become reachable.
+ */
+import { AbbreviationToDirectional, US_STREET_SUFFIX_LOOKUP } from "@mailwoman/codex/us";
+/**
+ * Spelled ordinal street names → their digit-ordinal form ("tenth" → "10th"), applied ONLY when a
+ * street-type suffix follows (#723 admin-tail) — so the ordinal cross-streets common in grid cities
+ * ("Tenth Street", "Fifth Avenue") match the shards' digit keys, WITHOUT rewriting ordinal-WORD
+ * names where the next token is not a suffix ("First National Bank Rd" stays "first national …").
+ * Digit-source shards are unaffected (a digit token isn't in this map), so the existing keys need
+ * no rebuild; a future rebuild folds any spelled-source key the same way (the one-function
+ * discipline).
+ */
+const SPELLED_ORDINAL_TO_DIGIT = new Map([
+    ["first", "1st"],
+    ["second", "2nd"],
+    ["third", "3rd"],
+    ["fourth", "4th"],
+    ["fifth", "5th"],
+    ["sixth", "6th"],
+    ["seventh", "7th"],
+    ["eighth", "8th"],
+    ["ninth", "9th"],
+    ["tenth", "10th"],
+    ["eleventh", "11th"],
+    ["twelfth", "12th"],
+    ["thirteenth", "13th"],
+    ["fourteenth", "14th"],
+    ["fifteenth", "15th"],
+    ["sixteenth", "16th"],
+    ["seventeenth", "17th"],
+    ["eighteenth", "18th"],
+    ["nineteenth", "19th"],
+    ["twentieth", "20th"],
+    ["thirtieth", "30th"],
+    ["fortieth", "40th"],
+    ["fiftieth", "50th"],
+    ["sixtieth", "60th"],
+    ["seventieth", "70th"],
+    ["eightieth", "80th"],
+    ["ninetieth", "90th"],
+    ["hundredth", "100th"],
+]);
+/** Lowercase + diacritic-fold + punctuation strip + whitespace collapse. */
+function fold(input) {
+    return input
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        .replace(/[.,'’]/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/**
+ * Normalize a street name for address-point keying. Same function at build time and lookup time —
+ * see module docstring for the contract.
+ */
+export function normalizeStreetForKey(street) {
+    const tokens = fold(street).split(" ");
+    if (tokens.length === 0)
+        return "";
+    // Spelled-ordinal street names → digit form when a street suffix follows ("Tenth Street" →
+    // "10th street", #723). Gated on the next token being a suffix so ordinal-WORD names are untouched.
+    for (let i = 0; i < tokens.length - 1; i++) {
+        const digit = SPELLED_ORDINAL_TO_DIGIT.get(tokens[i]);
+        if (digit && US_STREET_SUFFIX_LOOKUP.has(tokens[i + 1]))
+            tokens[i] = digit;
+    }
+    // Directional expansion at the edges only ("N Main St" / "Main St N" — never interior
+    // tokens, where "W" may be an initial in a person-named street). The codex expands
+    // compounds to two words ("SE" → "SOUTH EAST"); we key on the spaceless form
+    // ("southeast"), and also merge an already-written two-token pair ("South East …").
+    const edgeDirectional = (raw) => AbbreviationToDirectional.get(raw.toUpperCase())?.toLowerCase().replace(" ", "");
+    const mergePair = (a, b) => a && b && /^(north|south)$/.test(a) && /^(east|west)$/.test(b) ? a + b : undefined;
+    const leadPair = mergePair(tokens[0], tokens[1]);
+    if (leadPair && tokens.length > 2)
+        tokens.splice(0, 2, leadPair);
+    const first = edgeDirectional(tokens[0]);
+    if (first && tokens.length > 1)
+        tokens[0] = first;
+    const tailPair = mergePair(tokens[tokens.length - 2], tokens[tokens.length - 1]);
+    if (tailPair && tokens.length > 3)
+        tokens.splice(tokens.length - 2, 2, tailPair);
+    if (tokens.length > 2) {
+        const last = edgeDirectional(tokens[tokens.length - 1]);
+        if (last)
+            tokens[tokens.length - 1] = last;
+    }
+    // Street-type canonicalization via the codex table (lowercase keys, UPPER canonical
+    // values). The suffix is usually the last token, but sits second-to-last when a trailing
+    // directional follows ("Main St N") — check both positions, canonicalize the first hit.
+    for (const at of [tokens.length - 1, tokens.length - 2]) {
+        if (at < 1)
+            continue; // never canonicalize the only/first token ("Street Road" exists)
+        const canonical = US_STREET_SUFFIX_LOOKUP.get(tokens[at]);
+        if (canonical) {
+            tokens[at] = canonical.toLowerCase();
+            break;
+        }
+    }
+    return tokens.join(" ");
+}
+/** Normalize a locality name for address-point keying (fold only — no street semantics). */
+export function normalizeLocalityForKey(locality) {
+    return fold(locality);
+}
+/**
+ * Strip a locality QUALIFIER for a query-side fallback — when an OA locality's exact normalized
+ * name misses the gazetteer's canonical name, retry with the qualifier removed. OA address data
+ * carries disambiguating qualifiers the gazetteer's canonical name omits: Austrian `Kraubath/Mur`
+ * and `Hart b.Graz` → `Hart`; Swiss `Lenk im Simmental` → `Lenk`, `Roche VD` → `Roche`; Danish
+ * `Odense S`, `Hurup Thy`. A FALLBACK ONLY — the exact name is tried first, and the region-bbox
+ * disambiguation resolves any base-name ambiguity downstream. The candidate table is unchanged
+ * (this is purely query-side); feed the result back through {@link normalizeLocalityForKey}. Returns
+ * "" when nothing was stripped (no point re-probing the identical key).
+ *
+ * Measured (`scripts/eval/candidate-recall.ts --strip-fallback`, EU OA holdouts): recovers AT
+ * 74.1→88.2% (+14.1pp), DK 91.5→96.2%, CH 90.4→92.6%; +1.3pp overall (diluted by the already-100%
+ * locales). Conservative by design — only the qualifier forms above; FI/PT/SI misses are
+ * untouched.
+ */
+export function stripLocalityQualifier(locality) {
+    let s = locality.trim();
+    if (s.includes("/"))
+        s = s.split("/")[0].trim(); // "Kraubath/Mur", "St.Kanzian/Klopeiner See"
+    s = s.replace(/\s+[a-zà-ÿ]\.\s*\S.*$/iu, ""); // abbreviated " b.Graz" / " o.Bleiburg" / " a.d. …"
+    s = s.replace(/\s+(im|an der|ob|bei|in der|unter|vor)\s+\S.*$/iu, ""); // " im Simmental", " bei Graz"
+    s = s.replace(/\s+(S|N|E|W|V|Ø|Sø|Fyn|Thy|Sjælland|Jylland|[A-ZÅÄÖ]{2})$/u, ""); // " S", " VD", " Thy"
+    s = s.trim();
+    return s === locality.trim() ? "" : s;
+}
+/**
+ * Fold numbered-route designators to a canonical key, applied AFTER {@link normalizeStreetForKey}.
+ * Sources disagree systematically on how they spell a route: TIGER says `State Rte 100` / `US Hwy
+ * 5` where E911/Overture say `VT ROUTE 100` / `US ROUTE 5` — the dominant street-name miss class in
+ * the #483 interpolation eval (rural addresses live on routes). `us <designator> N…` folds to `us
+ * route N…`; `state <designator> N…` and `<2-letter-prefix> <designator> N…` (the state
+ * abbreviation form) fold to `state route N…`. Only digit-leading route numbers fold — `State
+ * Street` and friends never match.
+ *
+ * Used by BOTH the segment-shard builder (`scripts/build-interpolation-shard.ts`) and the
+ * interpolation lookup — same one-function discipline as {@link normalizeStreetForKey}. The
+ * address-point tier (#476) does NOT apply it yet: adopting it there requires a shard rebuild
+ * (noted on #483).
+ *
+ * A same-numbered US and state route stay DISTINCT keys (`us route 5` vs `state route 5`); only the
+ * BARE `route N` form is ambiguous (designator unknown) and it stays unfolded — a bare-route query
+ * therefore misses rather than guessing a designator.
+ */
+export function canonicalizeRouteKey(streetNorm) {
+    const match = /^(us|state|[a-z]{2}) (?:route|rte|rt|highway|hwy) (\d.*)$/.exec(streetNorm);
+    if (!match)
+        return streetNorm;
+    return `${match[1] === "us" ? "us" : "state"} route ${match[2]}`;
+}
+//# sourceMappingURL=street-normalize.js.map

package/out/street-normalize.js.map

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

package/out/street-segment-schema.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for the TIGER STREET-SEGMENT interpolation shards (`street-segments-<cc>-<st>.db`,
+ *   built by `scripts/build-interpolation-shard.ts` from TIGER EDGES) — the #483 Method-3 fallback
+ *   the resolver drops to when the address-point tier (Method 2) can't bracket. Single source of
+ *   truth for the columns the BUILDER writes and the READER ({@link StreetInterpolator}) probes, so
+ *   a column rename in one is a compile error in the other.
+ *
+ *   The builder reads geometry from shapefiles via DuckDB's spatial extension (raw `ST_Read` — see
+ *   AGENTS.md "Database / inline SQL") and writes here through `node:sqlite`. The hot positional
+ *   INSERT (a county's worth of edges) stays raw; its column list is derived from
+ *   {@link STREET_SEGMENT_COLUMNS} so it can't drift from the DDL.
+ */
+import type { Kysely } from "kysely";
+/**
+ * One TIGER street-segment edge: a `(from_hn, to_hn)` house-number range on one `side` of a named
+ * street, with the geometry the interpolator walks. `min_hn`/`max_hn` are the sorted bounds (the
+ * probe filters on them); `parity` is `odd`/`even`/`mixed`.
+ */
+export interface StreetSegmentTable {
+    /** Shared {@link normalizeStreetForKey} of the street — the build/query-consistent probe key. */
+    street_norm: string;
+    /** `L` or `R` — the TIGER side the address range sits on. */
+    side: string;
+    from_hn: number;
+    to_hn: number;
+    /** Sorted lower bound of `(from_hn, to_hn)` — the probe filters `min_hn <= n <= max_hn`. */
+    min_hn: number;
+    /** Sorted upper bound of `(from_hn, to_hn)`. */
+    max_hn: number;
+    /** `odd` | `even` | `mixed` — the house-number parity along the range. */
+    parity: string;
+    postcode: string | null;
+    /** 5-digit state+county FIPS the edge came from. */
+    county_fips: string;
+    /** The street as it appeared in TIGER (kept for display / debugging). */
+    street_raw: string;
+    /** GeoJSON LineString text (no SpatiaLite — read back with `JSON.parse`). */
+    geometry: string;
+    /** Provenance: the dataset this edge came from (e.g. `tiger:edges`). */
+    source: string;
+    /** The pinned TIGER release the edge was ingested from. */
+    release: string;
+}
+/** The street-segment database schema for `new DatabaseClient<StreetSegmentDatabase>(...)`. */
+export interface StreetSegmentDatabase {
+    street_segment: StreetSegmentTable;
+}
+/**
+ * The `street_segment` columns in INSERT order. The builder's positional prepared statement derives
+ * its placeholder list from this, so the positional order can't drift from the DDL / the reader.
+ */
+export declare const STREET_SEGMENT_COLUMNS: readonly ["street_norm", "side", "from_hn", "to_hn", "min_hn", "max_hn", "parity", "postcode", "county_fips", "street_raw", "geometry", "source", "release"];
+/** Create the `street_segment` table — called before the streaming bulk load. */
+export declare function createStreetSegmentTable(db: Kysely<StreetSegmentDatabase>): Promise<void>;
+/** Create the two probe indexes the reader relies on (postcode-scope, street-scope). */
+export declare function createStreetSegmentIndexes(db: Kysely<StreetSegmentDatabase>): Promise<void>;
+//# sourceMappingURL=street-segment-schema.d.ts.map

package/out/street-segment-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"street-segment-schema.d.ts","sourceRoot":"","sources":["../street-segment-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEpC;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC,iGAAiG;IACjG,WAAW,EAAE,MAAM,CAAA;IACnB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,4FAA4F;IAC5F,MAAM,EAAE,MAAM,CAAA;IACd,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAA;IACd,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAA;IACnB,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAA;IAClB,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAA;IAChB,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAA;IACd,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAA;CACf;AAED,+FAA+F;AAC/F,MAAM,WAAW,qBAAqB;IACrC,cAAc,EAAE,kBAAkB,CAAA;CAClC;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,8JAczB,CAAA;AAEV,iFAAiF;AACjF,wBAAsB,wBAAwB,CAAC,EAAE,EAAE,MAAM,CAAC,qBAAqB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB/F;AAED,wFAAwF;AACxF,wBAAsB,0BAA0B,CAAC,EAAE,EAAE,MAAM,CAAC,qBAAqB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAOjG"}

package/out/street-segment-schema.js

@@ -0,0 +1,64 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for the TIGER STREET-SEGMENT interpolation shards (`street-segments-<cc>-<st>.db`,
+ *   built by `scripts/build-interpolation-shard.ts` from TIGER EDGES) — the #483 Method-3 fallback
+ *   the resolver drops to when the address-point tier (Method 2) can't bracket. Single source of
+ *   truth for the columns the BUILDER writes and the READER ({@link StreetInterpolator}) probes, so
+ *   a column rename in one is a compile error in the other.
+ *
+ *   The builder reads geometry from shapefiles via DuckDB's spatial extension (raw `ST_Read` — see
+ *   AGENTS.md "Database / inline SQL") and writes here through `node:sqlite`. The hot positional
+ *   INSERT (a county's worth of edges) stays raw; its column list is derived from
+ *   {@link STREET_SEGMENT_COLUMNS} so it can't drift from the DDL.
+ */
+/**
+ * The `street_segment` columns in INSERT order. The builder's positional prepared statement derives
+ * its placeholder list from this, so the positional order can't drift from the DDL / the reader.
+ */
+export const STREET_SEGMENT_COLUMNS = [
+    "street_norm",
+    "side",
+    "from_hn",
+    "to_hn",
+    "min_hn",
+    "max_hn",
+    "parity",
+    "postcode",
+    "county_fips",
+    "street_raw",
+    "geometry",
+    "source",
+    "release",
+];
+/** Create the `street_segment` table — called before the streaming bulk load. */
+export async function createStreetSegmentTable(db) {
+    await db.schema
+        .createTable("street_segment")
+        .addColumn("street_norm", "text", (c) => c.notNull())
+        .addColumn("side", "text", (c) => c.notNull())
+        .addColumn("from_hn", "integer", (c) => c.notNull())
+        .addColumn("to_hn", "integer", (c) => c.notNull())
+        .addColumn("min_hn", "integer", (c) => c.notNull())
+        .addColumn("max_hn", "integer", (c) => c.notNull())
+        .addColumn("parity", "text", (c) => c.notNull())
+        .addColumn("postcode", "text")
+        .addColumn("county_fips", "text", (c) => c.notNull())
+        .addColumn("street_raw", "text", (c) => c.notNull())
+        .addColumn("geometry", "text", (c) => c.notNull())
+        .addColumn("source", "text", (c) => c.notNull())
+        .addColumn("release", "text", (c) => c.notNull())
+        .execute();
+}
+/** Create the two probe indexes the reader relies on (postcode-scope, street-scope). */
+export async function createStreetSegmentIndexes(db) {
+    await db.schema
+        .createIndex("idx_seg_postcode")
+        .on("street_segment")
+        .columns(["postcode", "street_norm", "min_hn"])
+        .execute();
+    await db.schema.createIndex("idx_seg_street").on("street_segment").columns(["street_norm", "min_hn"]).execute();
+}
+//# sourceMappingURL=street-segment-schema.js.map

package/out/street-segment-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"street-segment-schema.js","sourceRoot":"","sources":["../street-segment-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAwCH;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACrC,aAAa;IACb,MAAM;IACN,SAAS;IACT,OAAO;IACP,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,UAAU;IACV,aAAa;IACb,YAAY;IACZ,UAAU;IACV,QAAQ;IACR,SAAS;CACA,CAAA;AAEV,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,EAAiC;IAC/E,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,gBAAgB,CAAC;SAC7B,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACpD,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC7C,SAAS,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACnD,SAAS,CAAC,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACjD,SAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAClD,SAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAClD,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/C,SAAS,CAAC,UAAU,EAAE,MAAM,CAAC;SAC7B,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACpD,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACnD,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACjD,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/C,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAChD,OAAO,EAAE,CAAA;AACZ,CAAC;AAED,wFAAwF;AACxF,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,EAAiC;IACjF,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,kBAAkB,CAAC;SAC/B,EAAE,CAAC,gBAAgB,CAAC;SACpB,OAAO,CAAC,CAAC,UAAU,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC;SAC9C,OAAO,EAAE,CAAA;IACX,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAC,gBAAgB,CAAC,CAAC,OAAO,CAAC,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE,CAAA;AAChH,CAAC"}

package/out/types.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Public surface for the WOF SQLite resolver — types only, no runtime.
+ *
+ *   These mirror the conceptual model described in `docs/plan/phases/PHASE_4_2_wof_sqlite.md`. Phase
+ *   4.3 will extend `PlaceCandidate` with the resolver-decorated fields that flow into
+ *   `AddressNode.source` / `sourceId` (e.g. an explicit `wofUri: "wof-admin:101751113"` form).
+ */
+/**
+ * The placetype taxonomy used by Who's On First. Ordered roughly from coarsest (country) to finest
+ * (address). See https://github.com/whosonfirst/whosonfirst-placetypes for the authoritative
+ * definitions of each.
+ *
+ * Phase 4.2 only emits the ones we actually look up; the union is open enough to extend later.
+ */
+export type WofPlacetype = "country" | "macroregion" | "region" | "macrocounty" | "county" | "localadmin" | "locality" | "borough" | "neighbourhood" | "microhood" | "postalcode" | "venue" | "campus" | "address";
+/**
+ * One candidate match for a place lookup.
+ *
+ * `score` is the post-boost ranking number — higher is better, but the scale is implementation-
+ * defined. Callers should treat it as ordinal, not absolute.
+ *
+ * `id` is the WOF place id. It's named generically (not `wof_id`) so the shape stays structurally
+ * compatible with `@mailwoman/resolver`'s `ResolvedPlace` — `WofSqlitePlaceLookup` satisfies the
+ * generic `ResolverBackend` contract without an adapter shim.
+ *
+ * `distanceKm` is populated only when the query carried `near` (and the place has a centroid).
+ * Useful for downstream UIs that want to show "X km from you" alongside the result.
+ */
+export interface PlaceCandidate {
+    id: number;
+    name: string;
+    placetype: WofPlacetype;
+    /** ISO 3166-1 alpha-2 country code. */
+    country: string;
+    lat: number;
+    lon: number;
+    parent_id?: number;
+    score: number;
+    distanceKm?: number;
+    /**
+     * True when this candidate's name OR an alias EXACTLY equals the query (the exact-match tier from
+     * {@link RankingWeights.exactMatchTiering}). Surfaced so a downstream country re-rank (#369's
+     * postcode anchor in `resolveTree`) can pin the country without crossing the tier — see the
+     * `exactMatch` field on `@mailwoman/core`'s `ResolvedPlace`.
+     */
+    exactMatch?: boolean;
+    /**
+     * Population from WOF's `wof:population` property. Only present when the candidate has it on
+     * record — WOF carries population for ~15% of localities (mostly larger ones). Absent does NOT
+     * mean zero, just unknown.
+     */
+    population?: number;
+    /**
+     * Bounding box from WOF's `spr.{min,max}_{latitude,longitude}` columns. Coarse outline for the
+     * place — a city's bbox is the city's full extent, a postcode's is roughly the postcode polygon's
+     * envelope. Optional because not all callers ask for it; implementations are free to omit when
+     * the underlying schema lacks the columns.
+     */
+    bbox?: GeoBbox;
+    /**
+     * Set by the coordinate-first path when the chosen locality and the sibling postcode's containing
+     * locality are geographically far apart — the postcode and the parsed city name disagree (a
+     * transposed / wrong-for-the-city postcode). The candidate is still returned (the name wins for
+     * the locality), but the flag lets callers lower confidence / surface the conflict rather than
+     * silently mislocate. A retrieval/BM25 geocoder can't raise this — it's the falsehood-detection
+     * differentiator.
+     */
+    mismatch?: boolean;
+}
+/**
+ * A WGS-84 lat/lon point. Used as a proximity hint for `FindPlaceQuery.near`.
+ */
+export interface GeoPoint {
+    lat: number;
+    lon: number;
+}
+/**
+ * A WGS-84 bounding box. Used as a hard filter via `FindPlaceQuery.bbox`.
+ */
+export interface GeoBbox {
+    minLat: number;
+    maxLat: number;
+    minLon: number;
+    maxLon: number;
+}
+/**
+ * Query against the resolver.
+ *
+ * `text` is the only required field; everything else narrows the search. When `country` and
+ * `parentId` are both set, `parentId` wins (it's more specific).
+ *
+ * `near` and `bbox` are independent. `near` is a soft signal — candidates close to the point get a
+ * ranking boost but distant candidates aren't dropped. `bbox` is a hard filter — only candidates
+ * whose bbox intersects the query bbox are returned (uses the package-built R*Tree index when
+ * present; if the index is missing the option is silently ignored to preserve backwards
+ * compatibility).
+ *
+ * `near` may carry `maxDistanceKm` to escalate from a boost to a hard filter — candidates further
+ * than that distance from the point are dropped at the SQL level via an R*Tree pre-filter.
+ */
+export interface FindPlaceQuery {
+    text: string;
+    placetype?: WofPlacetype | WofPlacetype[];
+    /** ISO 3166-1 alpha-2 — narrows to one country. */
+    country?: string;
+    /** WOF place id — narrows to descendants of this place. */
+    parentId?: number;
+    /**
+     * Sibling postcode. When set on a `locality` query AND a `postcode_locality` table is present,
+     * triggers the coordinate-first soft-score path: postcode→candidate localities are injected and
+     * scored `0.6·S_pc + 0.3·S_name + 0.1·S_pop` against the FTS name-match set, recovering small
+     * localities the name-match alone misses. Ignored when no postcode_locality shard is present.
+     */
+    postcode?: string;
+    /** Proximity hint — candidates close to this point get a ranking boost. */
+    near?: GeoPoint & {
+        maxDistanceKm?: number;
+    };
+    /** Bounding-box filter — only candidates whose bbox intersects this box are returned. */
+    bbox?: GeoBbox;
+    /** Default 10. */
+    limit?: number;
+}
+/**
+ * The pull-based lookup surface. Implementations resolve a `FindPlaceQuery` to a ranked list of
+ * `PlaceCandidate`s. The interface is async even though `node:sqlite` is sync — leaves room for
+ * `Worker`-backed implementations later without a public API break.
+ */
+export interface PlaceLookup {
+    findPlace(query: FindPlaceQuery): Promise<PlaceCandidate[]>;
+    close(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/out/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GACrB,SAAS,GACT,aAAa,GACb,QAAQ,GACR,aAAa,GACb,QAAQ,GACR,YAAY,GACZ,UAAU,GACV,SAAS,GACT,eAAe,GACf,WAAW,GACX,YAAY,GACZ,OAAO,GACP,QAAQ,GACR,SAAS,CAAA;AAEZ;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,YAAY,CAAA;IACvB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;CACX;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,YAAY,GAAG,YAAY,EAAE,CAAA;IACzC,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,QAAQ,GAAG;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5C,yFAAyF;IACzF,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,kBAAkB;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAA;IAC3D,KAAK,IAAI,IAAI,CAAA;CACb"}

package/out/types.js

@@ -0,0 +1,13 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Public surface for the WOF SQLite resolver — types only, no runtime.
+ *
+ *   These mirror the conceptual model described in `docs/plan/phases/PHASE_4_2_wof_sqlite.md`. Phase
+ *   4.3 will extend `PlaceCandidate` with the resolver-decorated fields that flow into
+ *   `AddressNode.source` / `sourceId` (e.g. an explicit `wofUri: "wof-admin:101751113"` form).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/out/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/out/unified-schema.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Schema for the unified WOF SQLite database we build from cloned WOF GeoJSON repos
+ *   (`scripts/build-unified-wof.ts`). This is the CANONICAL gazetteer — we never use the
+ *   off-the-shelf geocode.earth prebuilt dumps (they assign different WOF ids to the same place;
+ *   see the `feedback-custom-wof-db-only` memory). The table/column names match the resolver's
+ *   expectations (`lookup.ts`) so `WofSqlitePlaceLookup` works unchanged, INCLUDING the `ancestors`
+ *   table (which lookup.ts's parent-constraint subquery needs) — see `populateAncestors`. The
+ *   `place_search` FTS5 + `place_bbox` R*Tree are built separately by `build-fts` (fts.ts).
+ */
+import { DatabaseSync } from "node:sqlite";
+export declare function createUnifiedSchema(db: DatabaseSync): Promise<void>;
+/**
+ * Populate the `ancestors` table by walking each place's `parent_id` chain in `spr` (transitive
+ * closure, including the place itself). Idempotent: drops + rebuilds the table contents. Returns
+ * the row count. Run after `spr` is fully ingested (build-unified-wof freeze phase) or standalone
+ * on an existing unified DB (`scripts/add-ancestors.ts`). Sentinel/negative parent_ids and cycles
+ * terminate the walk. ~4 rows/place average; a transaction keeps the ~5M inserts fast.
+ */
+export declare function populateAncestors(db: DatabaseSync): number;
+export declare function createUnifiedIndexes(db: DatabaseSync): Promise<void>;
+//# sourceMappingURL=unified-schema.d.ts.map

package/out/unified-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unified-schema.d.ts","sourceRoot":"","sources":["../unified-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAG1C,wBAAsB,mBAAmB,CAAC,EAAE,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAyEzE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,YAAY,GAAG,MAAM,CA6B1D;AAED,wBAAsB,oBAAoB,CAAC,EAAE,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB1E"}