@mailwoman/resolver-wof-sqlite 2.1.0

package/out/build-slim.js

@@ -0,0 +1,267 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Build a "slim" Who's On First SQLite distribution that's small enough to ship as a static asset
+ *   for the browser-side mailwoman demo (Path B of the demo plan). The full admin distribution is
+ *   ~2 GB; the slim variant aims for the ~50–100 MB range by keeping only the places a public demo
+ *   will actually query for.
+ *
+ *   Selection policy (v1, US-focused):
+ *
+ *   - All countries / regions / counties / boroughs in the configured `countries` set, so the ancestor
+ *       chain a locality / postcode reports through `parent_id` stays intact.
+ *   - Top-K localities by population (read from the source's pre-built `place_population` aux table) in
+ *       those countries.
+ *   - All postcodes in those countries — they're small and addressing-relevant.
+ *   - All `names` + `place_population` rows for selected place IDs.
+ *   - The `coincident_roles` dual-role relation (#402), filtered to surviving spr ids.
+ *
+ *   No geojson, by design. The upstream WOF GeoJSON bodies live ONLY in the raw `whosonfirst-data-*`
+ *   repos; `scripts/build-unified-wof.ts` extracts `wof:population` straight into
+ *   `place_population` (and the bbox into `spr`) at ingest and never persists a `geojson` table. So
+ *   the source admin DB carries population in `place_population`, and this builder consumes it
+ *   directly — there is nothing to extract from, and nothing to drop.
+ *
+ *   The output DB has the resolver-facing schema: `spr`, `names`, `place_population`, plus the
+ *   `place_search` FTS5 / `place_bbox` R*Tree virtual tables rebuilt against the trimmed row set
+ *   (both derive purely from `spr` + `names` — see `fts.ts`). That means `WofSqlitePlaceLookup`
+ *   opens the slim DB without any code change — it sees a smaller universe, nothing more.
+ *
+ *   Multi-shard inputs (e.g. admin + postcode) are processed in sequence; selected rows accumulate
+ *   into the single output DB. The postcode shard contributes only postcodes; admin contributes
+ *   everything else. Empty / missing input paths are skipped (callers pass `""` when a shard, such
+ *   as a custom postcode DB, isn't built yet).
+ */
+import { SqliteDialect } from "@mailwoman/core/kysley/dialect";
+import { Kysely, sql } from "kysely";
+import { copyFileSync, existsSync, mkdtempSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { buildPlaceSearchFts, PLACE_BBOX_TABLE, PLACE_POPULATION_TABLE, PLACE_SEARCH_TABLE } from "./fts.js";
+/** Placetypes that we always keep so the ancestor chain a selected locality reports stays valid. */
+const ANCESTOR_PLACETYPES = ["country", "region", "county", "borough", "macroregion"];
+/** Tables copied verbatim (schema + filtered rows) from each source DB. Anything else is dropped. */
+const COPIED_TABLES = ["spr", "names", PLACE_POPULATION_TABLE];
+/** Fallback DDL for `place_population` when the first source predates the aux table (defensive). */
+const PLACE_POPULATION_DDL = `CREATE TABLE ${PLACE_POPULATION_TABLE} (id INTEGER PRIMARY KEY, population INTEGER NOT NULL DEFAULT 0)`;
+export async function buildSlimWofDatabase(opts) {
+    const countries = (opts.countries ?? ["US"]).map((c) => c.toUpperCase());
+    const topLocalities = opts.topLocalitiesPerCountry ?? 1000;
+    const progress = opts.onProgress ?? (() => { });
+    // Callers pass `""` for shards that don't exist yet (e.g. a not-yet-built custom postcode DB).
+    // Skip empties up front; require every remaining path to exist.
+    const inputs = opts.inputs.filter((p) => p.length > 0);
+    if (inputs.length === 0)
+        throw new Error("no input WOF dbs provided");
+    for (const input of inputs) {
+        if (!existsSync(input))
+            throw new Error(`input WOF db not found: ${input}`);
+    }
+    progress("init", `${inputs.length} input(s) → ${opts.output}`);
+    if (existsSync(opts.output))
+        rmSync(opts.output);
+    // Open the output DB and create the empty schema. We discover the schema from the FIRST input
+    // (raw sqlite_master read — Kysely doesn't model that) so the output mirrors source column
+    // ordering / types. `CREATE TABLE AS SELECT` flattens types to dynamic, which would break
+    // callers that rely on column-affinity behavior.
+    const out = new DatabaseSync(opts.output);
+    try {
+        const firstSource = new DatabaseSync(inputs[0], { readOnly: true });
+        try {
+            progress("schema", "copying spr / names / place_population schemas from first input");
+            for (const table of COPIED_TABLES) {
+                const createSql = firstSource
+                    .prepare(`SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?`)
+                    .get(table);
+                if (createSql?.sql) {
+                    // Raw DDL by design (introspect-and-replay): we exec the SOURCE DB's own CREATE TABLE
+                    // string read from sqlite_master, so a static Kysely builder can't express it. See AGENTS.md.
+                    out.exec(createSql.sql);
+                }
+                else if (table === PLACE_POPULATION_TABLE) {
+                    // Older source builds may predate the aux table — create it empty so the per-source
+                    // copy + ranking have somewhere to land. Sparse-by-design; missing rows are fine.
+                    out.exec(PLACE_POPULATION_DDL);
+                }
+                else {
+                    throw new Error(`source DB ${inputs[0]} is missing required table '${table}'`);
+                }
+            }
+            // PRIMARY KEY on spr.id + place_population.id come from the schemas we copied; an explicit
+            // index on names.id helps the per-id INSERT SELECT later.
+            out.exec(`CREATE INDEX IF NOT EXISTS names_id_idx ON names(id);`);
+        }
+        finally {
+            firstSource.close();
+        }
+        const kysely = new Kysely({ dialect: new SqliteDialect({ database: out }) });
+        // Pull rows from each input.
+        for (const inputPath of inputs) {
+            await copyFromSource(out, kysely, inputPath, countries, topLocalities, progress);
+        }
+        // Build the resolver virtual tables on the trimmed row set. Both place_search (FTS5) and
+        // place_bbox (R*Tree) derive purely from spr + names — no geojson needed (see fts.ts). The
+        // population aux table is NOT rebuilt here: it was copied verbatim above, and fts.ts only
+        // (re)builds it when a `geojson` table is present, which the slim DB intentionally has not.
+        progress("fts", "building place_search / place_bbox on slim DB");
+        buildPlaceSearchFts(out, {
+            drop: true, // schema we copied had no FTS tables, but be explicit
+            onProgress: (phase, name) => progress("fts", `${phase} ${name}`),
+        });
+        // Materialize region/state ABBREVIATIONS into a standalone `place_abbr (id, abbr)` table BEFORE
+        // `names` is (optionally) dropped. The full DB lets the resolver tier an exact-abbrev match by
+        // querying `names` (`#exactMatchIds`), but the slim DB drops `names` for size — so the
+        // browser resolver gets its own tiny lookup (~hundreds of rows) to do the same data-driven
+        // exact-abbrev tiering ("VT" → Vermont, not a token-matching foreign region) instead of the
+        // demo's hardcoded `expandUsRegion` map. Sourced from the `language='abbr'` rows
+        // `add-region-abbrevs.ts` wrote, already filtered to surviving spr ids via the names copy. The
+        // table is always created (empty when the source predates the abbrev enrichment) so the
+        // resolver can query it unconditionally.
+        progress("place_abbr", "materializing region abbreviations");
+        out.exec(`CREATE TABLE IF NOT EXISTS place_abbr (id INTEGER NOT NULL, abbr TEXT NOT NULL)`);
+        out.exec(`INSERT INTO place_abbr (id, abbr) SELECT id, name FROM names WHERE language = 'abbr'`);
+        out.exec(`CREATE INDEX IF NOT EXISTS place_abbr_by_abbr ON place_abbr (abbr COLLATE NOCASE)`);
+        out.exec(`CREATE INDEX IF NOT EXISTS place_abbr_by_id ON place_abbr (id)`);
+        // Capture the names count BEFORE any drop so the build report stays informative.
+        const namesRows = countRows(out, "names");
+        // Optionally drop `names` (+ its index) now that the self-contained FTS5 index no longer needs
+        // it. The resolver never reads `names` at query time, so this is pure size reduction.
+        if (opts.dropNames) {
+            progress("vacuum", `dropping names table (${namesRows} rows; FTS5 is self-contained)`);
+            out.exec(`DROP INDEX IF EXISTS names_id_idx;`);
+            out.exec(`DROP TABLE IF EXISTS names;`);
+        }
+        // VACUUM the output so the on-disk file reflects just the trimmed row count. Without it the
+        // file size stays inflated from the in-flight INSERT churn.
+        progress("vacuum", "VACUUM (final size reduction)");
+        out.exec("VACUUM;");
+        const rowCounts = {
+            spr: countRows(out, "spr"),
+            names: namesRows,
+            placeSearch: countRows(out, PLACE_SEARCH_TABLE),
+            placeBbox: countRows(out, PLACE_BBOX_TABLE),
+            placePopulation: countRows(out, PLACE_POPULATION_TABLE),
+        };
+        progress("done", JSON.stringify(rowCounts));
+        return {
+            outputPath: opts.output,
+            outputBytes: statSync(opts.output).size,
+            rowCounts,
+        };
+    }
+    finally {
+        out.close();
+    }
+}
+async function copyFromSource(out, kysely, inputPath, countries, topLocalities, progress) {
+    // ATTACH avoids any "load source into memory" step — SQLite walks both files in place. We need
+    // a fresh temp copy because some WOF distributions ship as read-only filesystem mounts and
+    // ATTACH will still want a writable journal on the side; copying to /tmp dodges that without
+    // mutating the canonical files in /mnt/playpen/mailwoman-data/wof/. ATTACH / DETACH stay raw
+    // — Kysely doesn't model them.
+    const tmpScratch = mkdtempSync(join(tmpdir(), "mailwoman-slim-src-"));
+    const scratchPath = join(tmpScratch, "src.db");
+    copyFileSync(inputPath, scratchPath);
+    try {
+        out.exec(`ATTACH DATABASE '${scratchPath.replace(/'/g, "''")}' AS src;`);
+        try {
+            // Does this shard carry the pre-built population aux table? The admin source does; a bare
+            // postcode shard might not. The locality ranking + population copy below adapt accordingly.
+            const srcHasPopulation = Boolean(out.prepare(`SELECT 1 FROM src.sqlite_master WHERE type = 'table' AND name = '${PLACE_POPULATION_TABLE}'`).get());
+            // The SELECT-INSERT queries below go through Kysely. The cross-schema FROM is the only
+            // "interesting" bit: by declaring `src.spr` / `src.names` / `src.place_population` in
+            // `BuildSchema`, Kysely lets us write `selectFrom("src.spr")` with the same column-type
+            // checking as the regular schema. SQLite parses the dotted identifier as a schema-name
+            // qualifier, so this works directly without any aliasing trick.
+            // 1. Ancestor placetypes (country / region / county / etc.) — always-kept.
+            progress("country", `${inputPath}: ancestor placetypes in (${countries.join(",")})`);
+            await kysely
+                .insertInto("spr")
+                .expression((eb) => eb
+                .selectFrom("src.spr")
+                .selectAll()
+                .where("is_current", "!=", 0)
+                .where("is_deprecated", "=", 0)
+                .where("country", "in", countries)
+                .where("placetype", "in", [...ANCESTOR_PLACETYPES]))
+                .onConflict((oc) => oc.doNothing())
+                .execute();
+            // 2. Top-K localities by population. Population lives in the pre-built `place_population`
+            // aux table — left-join it so localities without a population row still qualify (sorted
+            // last). If the shard has no population table, fall back to a deterministic id ordering.
+            progress("locality", `${inputPath}: top-${topLocalities} localities by population`);
+            await kysely
+                .insertInto("spr")
+                .expression((eb) => eb
+                .selectFrom("src.spr as s")
+                .$if(srcHasPopulation, (qb) => qb.leftJoin("src.place_population as p", "p.id", "s.id"))
+                .selectAll("s")
+                .where("s.is_current", "!=", 0)
+                .where("s.is_deprecated", "=", 0)
+                .where("s.country", "in", countries)
+                .where("s.placetype", "=", "locality")
+                .orderBy(srcHasPopulation ? sql `COALESCE(p.population, 0)` : sql `s.id`, "desc")
+                .limit(topLocalities))
+                .onConflict((oc) => oc.doNothing())
+                .execute();
+            // 3. All postcodes in scope.
+            progress("postcode", `${inputPath}: all postcodes`);
+            await kysely
+                .insertInto("spr")
+                .expression((eb) => eb
+                .selectFrom("src.spr")
+                .selectAll()
+                .where("is_current", "!=", 0)
+                .where("is_deprecated", "=", 0)
+                .where("country", "in", countries)
+                .where("placetype", "=", "postalcode"))
+                .onConflict((oc) => oc.doNothing())
+                .execute();
+            // 4. Pull names for the IDs we just selected.
+            progress("names", `${inputPath}: names rows for selected IDs`);
+            await kysely
+                .insertInto("names")
+                .expression((eb) => eb.selectFrom("src.names").selectAll().where("id", "in", eb.selectFrom("spr").select("id")))
+                .onConflict((oc) => oc.doNothing())
+                .execute();
+            // 5. Pull population rows for the selected IDs (sparse — only the places WOF has a count for).
+            if (srcHasPopulation) {
+                progress("place_population", `${inputPath}: population rows for selected IDs`);
+                await kysely
+                    .insertInto("place_population")
+                    .expression((eb) => eb.selectFrom("src.place_population").selectAll().where("id", "in", eb.selectFrom("spr").select("id")))
+                    .onConflict((oc) => oc.doNothing())
+                    .execute();
+            }
+            // 6. Carry the coincident_roles relation (#402) when this source has it (the admin DB), so the
+            // slim/demo DB supports dual-role hierarchy completion (on by default). Filtered to surviving
+            // spr ids → no orphans. Tiny (~hundreds of rows). `ancestors` is intentionally NOT copied (huge
+            // + build-only), so we copy the derived table rather than rebuild it. Raw SQL — conditional +
+            // not in the Kysely build schema.
+            const relationSchema = out
+                .prepare(`SELECT sql FROM src.sqlite_master WHERE type = 'table' AND name = 'coincident_roles'`)
+                .get();
+            if (relationSchema?.sql) {
+                progress("coincident_roles", `${inputPath}: copying dual-role relation`);
+                out.exec(relationSchema.sql.replace(/CREATE TABLE/i, "CREATE TABLE IF NOT EXISTS"));
+                out.exec(`INSERT OR IGNORE INTO coincident_roles SELECT * FROM src.coincident_roles
+						WHERE admin_id IN (SELECT id FROM spr) AND locality_id IN (SELECT id FROM spr)`);
+                out.exec(`CREATE INDEX IF NOT EXISTS coincident_roles_by_admin ON coincident_roles (admin_id)`);
+            }
+        }
+        finally {
+            out.exec(`DETACH DATABASE src;`);
+        }
+    }
+    finally {
+        rmSync(tmpScratch, { recursive: true, force: true });
+    }
+}
+function countRows(db, table) {
+    const row = db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get();
+    return Number(row?.n ?? 0);
+}
+//# sourceMappingURL=build-slim.js.map

package/out/build-slim.js.map

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

package/out/candidate-lookup.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Node-side {@link PlaceLookup} over the byte-range CANDIDATE table (`build-candidate.ts`) — the
+ *   SAME gazetteer the browser demo resolves against ({@link WofCandidateTableLookup} in
+ *   `docs/src/shared/httpvfs-resolver.ts`), but reading a LOCAL `candidate.db` via `node:sqlite`
+ *   instead of sql.js-httpvfs. This is what makes the server/CLI resolver match the demo: one
+ *   lookup surface, one artifact, one ranking.
+ *
+ *   The query is a single contiguous probe on the `WITHOUT ROWID` B-tree keyed `(name_key,
+ *   country_id, region_id, placetype_id, neg_rank, spr_id)`. `name_key` is the SHARED
+ *   {@link normalizeLocalityForKey} (build- and query-consistent), each row is denormalized (display
+ *   `name`, centroid, bbox), and population rank is precomputed into `neg_rank` — so the result is
+ *   POPULATION-FIRST and COUNTRY-AGNOSTIC (when no `country` filter is given), exactly like the
+ *   demo. That's the deliberate divergence from {@link WofSqlitePlaceLookup}'s FTS/bm25 ranking: a
+ *   bare "Moscow" resolves to the 10.4 M-pop Russian city, not whichever same-name US township bm25
+ *   floats to the top.
+ *
+ *   Disambiguation rides the same mechanism the cascade already uses: a parsed region resolves to its
+ *   stored bbox and the locality query is point-in-bbox-filtered on the candidate centroid (the
+ *   `bbox` field on {@link FindPlaceQuery}).
+ */
+import { DatabaseSync } from "node:sqlite";
+import type { FindPlaceQuery, PlaceCandidate, PlaceLookup } from "./types.js";
+export interface WofCandidateTableLookupOpts {
+    /** Path to a `candidate.db` built by `build-candidate.ts`. Opened read-only. */
+    databasePath?: string;
+    /** Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`. */
+    database?: DatabaseSync;
+}
+/**
+ * Node {@link PlaceLookup} over `candidate.db`. Drop-in for {@link WofSqlitePlaceLookup} in
+ * `createWofResolver(backend)` — same `findPlace` contract, population-first ranking.
+ */
+export declare class WofCandidateTableLookup implements PlaceLookup {
+    #private;
+    constructor(opts: WofCandidateTableLookupOpts);
+    findPlace(query: FindPlaceQuery): Promise<PlaceCandidate[]>;
+    close(): void;
+}
+//# sourceMappingURL=candidate-lookup.d.ts.map

package/out/candidate-lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate-lookup.d.ts","sourceRoot":"","sources":["../candidate-lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAK1C,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAgB,MAAM,YAAY,CAAA;AAE3F,MAAM,WAAW,2BAA2B;IAC3C,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,YAAY,CAAA;CACvB;AAsBD;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,WAAW;;gBAc9C,IAAI,EAAE,2BAA2B;IAyCvC,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IA0GjE,KAAK,IAAI,IAAI;CAGb"}

package/out/candidate-lookup.js

@@ -0,0 +1,191 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Node-side {@link PlaceLookup} over the byte-range CANDIDATE table (`build-candidate.ts`) — the
+ *   SAME gazetteer the browser demo resolves against ({@link WofCandidateTableLookup} in
+ *   `docs/src/shared/httpvfs-resolver.ts`), but reading a LOCAL `candidate.db` via `node:sqlite`
+ *   instead of sql.js-httpvfs. This is what makes the server/CLI resolver match the demo: one
+ *   lookup surface, one artifact, one ranking.
+ *
+ *   The query is a single contiguous probe on the `WITHOUT ROWID` B-tree keyed `(name_key,
+ *   country_id, region_id, placetype_id, neg_rank, spr_id)`. `name_key` is the SHARED
+ *   {@link normalizeLocalityForKey} (build- and query-consistent), each row is denormalized (display
+ *   `name`, centroid, bbox), and population rank is precomputed into `neg_rank` — so the result is
+ *   POPULATION-FIRST and COUNTRY-AGNOSTIC (when no `country` filter is given), exactly like the
+ *   demo. That's the deliberate divergence from {@link WofSqlitePlaceLookup}'s FTS/bm25 ranking: a
+ *   bare "Moscow" resolves to the 10.4 M-pop Russian city, not whichever same-name US township bm25
+ *   floats to the top.
+ *
+ *   Disambiguation rides the same mechanism the cascade already uses: a parsed region resolves to its
+ *   stored bbox and the locality query is point-in-bbox-filtered on the candidate centroid (the
+ *   `bbox` field on {@link FindPlaceQuery}).
+ */
+import { expandPlacetypeFilter } from "@mailwoman/resolver";
+import { DatabaseSync } from "node:sqlite";
+import { POSTAL_CITY_CANDIDATE_TABLE } from "./postal-city-candidate-schema.js";
+import { hasTable } from "./sqlite-utils.js";
+import { normalizeLocalityForKey, stripLocalityQualifier } from "./street-normalize.js";
+/**
+ * Node {@link PlaceLookup} over `candidate.db`. Drop-in for {@link WofSqlitePlaceLookup} in
+ * `createWofResolver(backend)` — same `findPlace` contract, population-first ranking.
+ */
+export class WofCandidateTableLookup {
+    #db;
+    #ownsDb;
+    #countryToId = new Map();
+    #idToCountry = new Map();
+    #placetypeToId = new Map();
+    #idToPlacetype = new Map();
+    /**
+     * Prepared `(name_key, postcode)` probe for the #741 postal-city side-index — `undefined` when
+     * the `postal_city_candidate` table isn't present, so a candidate.db built without it is
+     * byte-stable.
+     */
+    #postalCityProbe;
+    constructor(opts) {
+        if (opts.database) {
+            this.#db = opts.database;
+            this.#ownsDb = false;
+        }
+        else if (opts.databasePath) {
+            this.#db = new DatabaseSync(opts.databasePath, { readOnly: true });
+            this.#ownsDb = true;
+        }
+        else {
+            throw new Error("WofCandidateTableLookup needs `databasePath` or `database`");
+        }
+        // The code tables are tiny (country/placetype dictionaries) — load them once at construction so
+        // `findPlace` is a single B-tree probe with no dictionary round-trip.
+        for (const r of this.#db.prepare("SELECT id, code FROM country_codes").all()) {
+            const code = String(r.code).toUpperCase();
+            this.#countryToId.set(code, Number(r.id));
+            this.#idToCountry.set(Number(r.id), code);
+        }
+        for (const r of this.#db
+            .prepare("SELECT id, placetype FROM placetype_codes")
+            .all()) {
+            this.#placetypeToId.set(String(r.placetype), Number(r.id));
+            this.#idToPlacetype.set(Number(r.id), String(r.placetype));
+        }
+        // #741 postal-city side-index: prepare the exact probe only if the table is present. Absent →
+        // `#postalCityProbe` stays undefined → findPlace skips the postal-city path → byte-stable.
+        if (hasTable(this.#db, POSTAL_CITY_CANDIDATE_TABLE)) {
+            this.#postalCityProbe = this.#db.prepare(`SELECT spr_id, name, latitude, longitude FROM ${POSTAL_CITY_CANDIDATE_TABLE} WHERE name_key = ? AND postcode = ? LIMIT 1`);
+        }
+    }
+    /** Does this query want a locality-tier place? Postal-city aliases (#741) are all localities. */
+    #wantsLocality(placetype) {
+        if (!placetype)
+            return true;
+        const want = Array.isArray(placetype) ? placetype : [placetype];
+        return expandPlacetypeFilter(want).includes("locality");
+    }
+    async findPlace(query) {
+        const text = (query.text ?? "").trim();
+        if (!text)
+            return [];
+        const nameKey = normalizeLocalityForKey(text);
+        if (!nameKey)
+            return [];
+        // #741: postcode-keyed postal-city alias. An exact `(name_key, postcode)` hit resolves a
+        // user-typed POSTAL city ("Antioch", 37013) to the geographic locality the postcode sits in
+        // ("Nashville"), bypassing the population/region ranking that can't see the postcode. Gated on
+        // the side-index being present, a postcode in the query, and a locality-tier request — so the
+        // common (no-postcode / non-locality) path is untouched. A hit short-circuits: the postcode is
+        // an exact, high-confidence disambiguator, so we return the single geographic locality.
+        if (query.postcode && this.#postalCityProbe && this.#wantsLocality(query.placetype)) {
+            const hit = this.#postalCityProbe.get(nameKey, query.postcode.trim());
+            if (hit) {
+                return [
+                    {
+                        id: Number(hit.spr_id),
+                        name: String(hit.name ?? ""),
+                        placetype: "locality",
+                        country: query.country?.toUpperCase() ?? "",
+                        lat: Number(hit.latitude),
+                        lon: Number(hit.longitude),
+                        score: 1,
+                        exactMatch: true,
+                    },
+                ];
+            }
+        }
+        const limit = Math.max(1, query.limit ?? 10);
+        // Filter conds shared by the exact-key + strip-fallback probes (everything but name_key).
+        const filters = [];
+        const filterParams = [];
+        if (query.country) {
+            const cid = this.#countryToId.get(query.country.toUpperCase());
+            if (cid === undefined)
+                return []; // a country the candidate table doesn't carry
+            filters.push("country_id = ?");
+            filterParams.push(cid);
+        }
+        if (query.placetype) {
+            // Shared placetype-equivalence expansion (a `locality` query must also reach borough /
+            // localadmin). `postalcode` maps to no admin placetype here → empty → no rows.
+            const want = Array.isArray(query.placetype) ? query.placetype : [query.placetype];
+            const ids = expandPlacetypeFilter(want)
+                .map((t) => this.#placetypeToId.get(t))
+                .filter((v) => v !== undefined);
+            if (ids.length === 0)
+                return [];
+            filters.push(`placetype_id IN (${ids.map(() => "?").join(",")})`);
+            filterParams.push(...ids);
+        }
+        if (query.bbox) {
+            const b = query.bbox;
+            filters.push("latitude BETWEEN ? AND ? AND longitude BETWEEN ? AND ?");
+            filterParams.push(b.minLat, b.maxLat, b.minLon, b.maxLon);
+        }
+        const probe = (nk) => {
+            const conds = ["name_key = ?", ...filters];
+            const sql = "SELECT spr_id, name, country_id, placetype_id, latitude, longitude, min_lat, min_lon, max_lat, max_lon, neg_rank " +
+                `FROM candidate WHERE ${conds.join(" AND ")} ORDER BY neg_rank ASC LIMIT ?`;
+            return this.#db.prepare(sql).all(nk, ...filterParams, limit);
+        };
+        let rows = probe(nameKey);
+        if (rows.length === 0) {
+            // Query-side qualifier-strip fallback: an OA locality with a qualifier the gazetteer's
+            // canonical name omits ("Lenk im Simmental" → "Lenk", "Roche VD"). Tried ONLY on an exact
+            // miss; the cascade's region bbox disambiguates any base-name ambiguity.
+            const strippedKey = normalizeLocalityForKey(stripLocalityQualifier(text));
+            if (strippedKey && strippedKey !== nameKey)
+                rows = probe(strippedKey);
+        }
+        return rows.map((row) => {
+            const hasBbox = row.min_lat != null && row.max_lat != null && row.min_lon != null && row.max_lon != null;
+            return {
+                id: Number(row.spr_id),
+                name: String(row.name ?? ""),
+                placetype: (this.#idToPlacetype.get(Number(row.placetype_id)) ?? ""),
+                // Surfaced so the cascade can country-gate a postcode by the resolved locality (an ambiguous
+                // international postcode like 10115 = Berlin DE AND New York US must not out-resolve the city).
+                country: this.#idToCountry.get(Number(row.country_id)) ?? "",
+                lat: Number(row.latitude),
+                lon: Number(row.longitude),
+                score: -Number(row.neg_rank),
+                // Every candidate row IS an exact normalized-name (or alias/abbrev) match — the cascade's
+                // exact tier accepts alias-exact hits ("New York City" → New York) the same as canonical.
+                exactMatch: true,
+                ...(hasBbox
+                    ? {
+                        bbox: {
+                            minLat: Number(row.min_lat),
+                            maxLat: Number(row.max_lat),
+                            minLon: Number(row.min_lon),
+                            maxLon: Number(row.max_lon),
+                        },
+                    }
+                    : {}),
+            };
+        });
+    }
+    close() {
+        if (this.#ownsDb)
+            this.#db.close();
+    }
+}
+//# sourceMappingURL=candidate-lookup.js.map

package/out/candidate-lookup.js.map

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

package/out/candidate-schema.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for the byte-range CANDIDATE gazetteer (`candidate.db`) — the single source of truth
+ *   for the columns shared by the BUILDER ({@link buildCandidateTable}) and the READERS (the Node
+ *   {@link WofCandidateTableLookup} + the browser `httpvfs-resolver.ts`). Before this module each
+ *   side hand-wrote the column list; a rename in one place broke the other at runtime. Now the
+ *   contract is a Kysely `Database` interface (`new DatabaseClient<CandidateDatabase>(...)` for
+ *   typed inserts) plus the table DDL as strings — so a column change is a compile error on every
+ *   consumer.
+ *
+ *   `cand_stage` is the transient staging table the builder bulk-loads; `candidate` is the clustered
+ *   `WITHOUT ROWID` B-tree it's materialized into (same columns). The reader queries `candidate`.
+ */
+import { type Kysely } from "kysely";
+/**
+ * One candidate row. `name_key` + the four small int keys + `neg_rank` + `spr_id` form the
+ * clustered primary key; the rest is denormalized so a resolve is one probe (no join to `spr`).
+ * Coordinates + bbox + name are nullable at the SQL level (a postcode shard row may lack a bbox).
+ */
+export interface CandidateTable {
+    /** The shared {@link normalizeLocalityForKey} of the name/alias — the probe key. */
+    name_key: string;
+    /** Small int from {@link CountryCodeTable} (shrinks the clustered key). */
+    country_id: number;
+    /** The place's region-tier ancestor id, or 0 (carried for the future region 2-step). */
+    region_id: number;
+    /** Small int from {@link PlacetypeCodeTable}. */
+    placetype_id: number;
+    /**
+     * `-log10(population + 1)` — ASC order = highest-population first. 0 for postcodes (no
+     * population).
+     */
+    neg_rank: number;
+    /** WOF id of the place this row resolves to. */
+    spr_id: number;
+    name: string | null;
+    latitude: number | null;
+    longitude: number | null;
+    min_lat: number | null;
+    min_lon: number | null;
+    max_lat: number | null;
+    max_lon: number | null;
+    population: number | null;
+    /** 1 when the row is the place's canonical name (vs an alias/abbrev). */
+    is_primary: number | null;
+}
+/** `(id → ISO country code)` dictionary. */
+export interface CountryCodeTable {
+    id: number;
+    code: string;
+}
+/** `(id → placetype)` dictionary. */
+export interface PlacetypeCodeTable {
+    id: number;
+    placetype: string;
+}
+/** The candidate database schema for `new DatabaseClient<CandidateDatabase>(...)`. */
+export interface CandidateDatabase {
+    /** The clustered `WITHOUT ROWID` lookup table the reader probes. */
+    candidate: CandidateTable;
+    /** Transient staging table (same columns); dropped once `candidate` is materialized. */
+    cand_stage: CandidateTable;
+    country_codes: CountryCodeTable;
+    placetype_codes: PlacetypeCodeTable;
+}
+/**
+ * The `candidate`/`cand_stage` columns in clustered-key order. The materialization `INSERT INTO
+ * candidate SELECT … FROM cand_stage` derives its column list from this, so the two tables can't
+ * drift. Keep in sync with {@link CandidateTable}.
+ */
+export declare const CANDIDATE_COLUMNS: readonly ["name_key", "country_id", "region_id", "placetype_id", "neg_rank", "spr_id", "name", "latitude", "longitude", "min_lat", "min_lon", "max_lat", "max_lon", "population", "is_primary"];
+/**
+ * Create the code dictionaries + the transient staging table — called before the build's load
+ * passes. `cand_stage` mirrors {@link CandidateTable} but every column is nullable (the loader fills
+ * them positionally). Pass a {@link DatabaseClient} (or any `Kysely`) over the candidate DB.
+ */
+export declare function createCandidateStagingTables(db: Kysely<CandidateDatabase>): Promise<void>;
+/**
+ * Create the clustered `WITHOUT ROWID` lookup table — called after staging, before the VACUUM. The
+ * first six columns form the clustered primary key (population-ranked via `neg_rank`).
+ */
+export declare function createCandidateTable(db: Kysely<CandidateDatabase>): Promise<void>;
+//# sourceMappingURL=candidate-schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"candidate-schema.d.ts","sourceRoot":"","sources":["../candidate-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAO,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEzC;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,oFAAoF;IACpF,QAAQ,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAA;IAClB,wFAAwF;IACxF,SAAS,EAAE,MAAM,CAAA;IACjB,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,yEAAyE;IACzE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAED,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;CACZ;AAED,qCAAqC;AACrC,MAAM,WAAW,kBAAkB;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,CAAA;CACjB;AAED,sFAAsF;AACtF,MAAM,WAAW,iBAAiB;IACjC,oEAAoE;IACpE,SAAS,EAAE,cAAc,CAAA;IACzB,wFAAwF;IACxF,UAAU,EAAE,cAAc,CAAA;IAC1B,aAAa,EAAE,gBAAgB,CAAA;IAC/B,eAAe,EAAE,kBAAkB,CAAA;CACnC;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,iMAgBpB,CAAA;AAEV;;;;GAIG;AACH,wBAAsB,4BAA4B,CAAC,EAAE,EAAE,MAAM,CAAC,iBAAiB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CA6B/F;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,EAAE,EAAE,MAAM,CAAC,iBAAiB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CA6BvF"}