@mailwoman/resolver-wof-sqlite 2.1.0

package/out/address-point.js

@@ -0,0 +1,62 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   SQLite implementation of core's `AddressPointLookup` (#476): exact `(street, number)` within a
+ *   postcode (preferred) or locality scope, against a per-state shard built by
+ *   `scripts/build-address-point-shard.ts`. Query-side normalization is THE shared normalizer
+ *   (`street-normalize.ts`) — identical to build-side, by construction.
+ *
+ *   Matching is exact-after-normalization only — no fuzzy street matching in this tier (measure how
+ *   far exact gets first; fuzz is a later, separate decision). Postcode scope is attempted first
+ *   (cheapest, most selective); locality scope is the fallback. Multiple hits (same number,
+ *   units/duplicates) return the first by rowid — coordinates of unit siblings are the same
+ *   building for tier purposes.
+ */
+import { DatabaseSync } from "node:sqlite";
+import { hasTable } from "./sqlite-utils.js";
+import { normalizeLocalityForKey, normalizeStreetForKey } from "./street-normalize.js";
+/**
+ * The 4 columns the reader SELECTs, in the schema's order — referenced by the prepared SELECTs so
+ * the projected `AddressPointRow` stays in lockstep with the shared schema.
+ */
+const SELECT_COLS = "lat, lon, source, release";
+export class AddressPointSqliteLookup {
+    #db;
+    #byPostcode;
+    #byLocality;
+    constructor(dbPath) {
+        this.#db = new DatabaseSync(dbPath, { readOnly: true });
+        // Degrade gracefully on an empty/tableless shard (interrupted build, stray 0-byte file): with no
+        // `address_point` table this lookup is a no-op miss, not a crash that loses the whole state (#568).
+        if (hasTable(this.#db, "address_point")) {
+            this.#byPostcode = this.#db.prepare(`SELECT ${SELECT_COLS} FROM address_point
+				 WHERE postcode = ? AND street_norm = ? AND number = ? LIMIT 1`);
+            this.#byLocality = this.#db.prepare(`SELECT ${SELECT_COLS} FROM address_point
+				 WHERE locality_norm = ? AND street_norm = ? AND number = ? LIMIT 1`);
+        }
+    }
+    find(query) {
+        if (!this.#byPostcode || !this.#byLocality)
+            return null;
+        const streetNorm = normalizeStreetForKey(query.street);
+        const number = query.number.trim().toLowerCase();
+        if (!streetNorm || !number)
+            return null;
+        let row;
+        if (query.postcode) {
+            row = this.#byPostcode.get(query.postcode.trim(), streetNorm, number);
+        }
+        if (!row && query.locality) {
+            row = this.#byLocality.get(normalizeLocalityForKey(query.locality), streetNorm, number);
+        }
+        if (!row)
+            return null;
+        return { lat: row.lat, lon: row.lon, source: row.source, release: row.release };
+    }
+    close() {
+        this.#db.close();
+    }
+}
+//# sourceMappingURL=address-point.js.map

package/out/address-point.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address-point.js","sourceRoot":"","sources":["../address-point.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAK1C,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC5C,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAStF;;;GAGG;AACH,MAAM,WAAW,GAAG,2BAA2B,CAAA;AAE/C,MAAM,OAAO,wBAAwB;IAC3B,GAAG,CAAc;IACjB,WAAW,CAAiD;IAC5D,WAAW,CAAiD;IAErE,YAAY,MAAc;QACzB,IAAI,CAAC,GAAG,GAAG,IAAI,YAAY,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAA;QACvD,iGAAiG;QACjG,oGAAoG;QACpG,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,EAAE,CAAC;YACzC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAClC,UAAU,WAAW;mEAC0C,CAC/D,CAAA;YACD,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAClC,UAAU,WAAW;wEAC+C,CACpE,CAAA;QACF,CAAC;IACF,CAAC;IAED,IAAI,CAAC,KAA+E;QACnF,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,WAAW;YAAE,OAAO,IAAI,CAAA;QACvD,MAAM,UAAU,GAAG,qBAAqB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;QACtD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;QAChD,IAAI,CAAC,UAAU,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAA;QAEvC,IAAI,GAAgC,CAAA;QACpC,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YACpB,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,UAAU,EAAE,MAAM,CAAgC,CAAA;QACrG,CAAC;QACD,IAAI,CAAC,GAAG,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YAC5B,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,uBAAuB,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,UAAU,EAAE,MAAM,CAE1E,CAAA;QACb,CAAC;QACD,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAA;QACrB,OAAO,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,CAAA;IAChF,CAAC;IAED,KAAK;QACJ,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAA;IACjB,CAAC;CACD"}

package/out/ancestry.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The shared ancestor-lineage walk over the WOF `ancestors` table — one place's containment chain
+ *   joined with `spr` for canonical names + centroids, ordered NEAREST-FIRST (deepest placetype
+ *   first, country last).
+ *
+ *   Factored out of `WofSqlitePlaceLookup.ancestors()` (#404) so the reverse geocoder (`reverse.ts`,
+ *   #484) reuses the SAME walk instead of growing a second one. The placetype-specificity ordering
+ *   lives here as `PLACETYPE_DEPTH` — a single TS map instead of the previous SQL CASE, and
+ *   extended below `localadmin` (locality/borough/neighbourhood/microhood now rank correctly
+ *   instead of sorting last; forward resolution rarely saw those as ANCESTOR placetypes, reverse
+ *   geocoding always does).
+ */
+import type { DatabaseSync } from "node:sqlite";
+/**
+ * WOF placetype → containment depth, coarsest = 1. Higher = finer. Placetypes we never resolve
+ * (continent, empire, …) map to 0 and sort last. NOT the same table as the FST's `PLACETYPE_ORDER`
+ * (fst-serialize.ts) — that one is a serialization order, this one is containment depth.
+ */
+export declare const PLACETYPE_DEPTH: Readonly<Record<string, number>>;
+/** Containment depth for a placetype — 0 (sorts coarsest) when unknown. */
+export declare function placetypeDepth(placetype: string): number;
+/** One ancestor row, enriched with the `spr` columns both consumers need. */
+export interface AncestorPlaceRow {
+    id: number;
+    placetype: string;
+    name: string;
+    country: string;
+    lat: number;
+    lon: number;
+}
+/**
+ * The ancestor lineage of `id` — self excluded, nearest-first. Returns `[]` when the place has no
+ * recorded ancestry. NOT memoized here; `WofSqlitePlaceLookup` keeps its own per-id cache.
+ */
+export declare function ancestorLineage(db: DatabaseSync, id: number, schemaName?: string): AncestorPlaceRow[];
+//# sourceMappingURL=ancestry.d.ts.map

package/out/ancestry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ancestry.d.ts","sourceRoot":"","sources":["../ancestry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAY5D,CAAA;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;CACX;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,SAAS,GAAG,gBAAgB,EAAE,CAWrG"}

package/out/ancestry.js

@@ -0,0 +1,53 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The shared ancestor-lineage walk over the WOF `ancestors` table — one place's containment chain
+ *   joined with `spr` for canonical names + centroids, ordered NEAREST-FIRST (deepest placetype
+ *   first, country last).
+ *
+ *   Factored out of `WofSqlitePlaceLookup.ancestors()` (#404) so the reverse geocoder (`reverse.ts`,
+ *   #484) reuses the SAME walk instead of growing a second one. The placetype-specificity ordering
+ *   lives here as `PLACETYPE_DEPTH` — a single TS map instead of the previous SQL CASE, and
+ *   extended below `localadmin` (locality/borough/neighbourhood/microhood now rank correctly
+ *   instead of sorting last; forward resolution rarely saw those as ANCESTOR placetypes, reverse
+ *   geocoding always does).
+ */
+/**
+ * WOF placetype → containment depth, coarsest = 1. Higher = finer. Placetypes we never resolve
+ * (continent, empire, …) map to 0 and sort last. NOT the same table as the FST's `PLACETYPE_ORDER`
+ * (fst-serialize.ts) — that one is a serialization order, this one is containment depth.
+ */
+export const PLACETYPE_DEPTH = {
+    country: 1,
+    macroregion: 2,
+    region: 3,
+    macrocounty: 4,
+    county: 5,
+    localadmin: 6,
+    locality: 7,
+    borough: 8,
+    macrohood: 9,
+    neighbourhood: 10,
+    microhood: 11,
+};
+/** Containment depth for a placetype — 0 (sorts coarsest) when unknown. */
+export function placetypeDepth(placetype) {
+    return PLACETYPE_DEPTH[placetype] ?? 0;
+}
+/**
+ * The ancestor lineage of `id` — self excluded, nearest-first. Returns `[]` when the place has no
+ * recorded ancestry. NOT memoized here; `WofSqlitePlaceLookup` keeps its own per-id cache.
+ */
+export function ancestorLineage(db, id, schemaName = "main") {
+    const rows = db
+        .prepare(`SELECT a.ancestor_id AS id, a.ancestor_placetype AS placetype, s.name AS name,
+				s.country AS country, s.latitude AS lat, s.longitude AS lon
+			FROM ${schemaName}.ancestors a JOIN ${schemaName}.spr s ON s.id = a.ancestor_id
+			WHERE a.id = ? AND a.ancestor_id != a.id`)
+        .all(id);
+    rows.sort((a, b) => placetypeDepth(b.placetype) - placetypeDepth(a.placetype));
+    return rows;
+}
+//# sourceMappingURL=ancestry.js.map

package/out/ancestry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ancestry.js","sourceRoot":"","sources":["../ancestry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAqC;IAChE,OAAO,EAAE,CAAC;IACV,WAAW,EAAE,CAAC;IACd,MAAM,EAAE,CAAC;IACT,WAAW,EAAE,CAAC;IACd,MAAM,EAAE,CAAC;IACT,UAAU,EAAE,CAAC;IACb,QAAQ,EAAE,CAAC;IACX,OAAO,EAAE,CAAC;IACV,SAAS,EAAE,CAAC;IACZ,aAAa,EAAE,EAAE;IACjB,SAAS,EAAE,EAAE;CACb,CAAA;AAED,2EAA2E;AAC3E,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC/C,OAAO,eAAe,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;AACvC,CAAC;AAYD;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,EAAgB,EAAE,EAAU,EAAE,UAAU,GAAG,MAAM;IAChF,MAAM,IAAI,GAAG,EAAE;SACb,OAAO,CACP;;UAEO,UAAU,qBAAqB,UAAU;4CACP,CACzC;SACA,GAAG,CAAC,EAAE,CAAkC,CAAA;IAC1C,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAA;IAC9E,OAAO,IAAI,CAAA;AACZ,CAAC"}

package/out/build-candidate-cli.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman-wof-build-candidate --in <admin.db> --out <candidate.db>`
+ *
+ *   Operator-side one-shot CLI that builds the global byte-range "candidate" lookup DB for the
+ *   browser demo (the FTS-free, single-probe gazetteer). Delegates to
+ *   {@linkcode buildCandidateTable}; the CLI is just argument parsing + stderr progress. The
+ *   TypeScript port of the 2026-06-20 prototype — it lives in the package (not /scripts) so the
+ *   name_key normalizer is the SAME shared `normalizeLocalityForKey` the query-side resolver uses.
+ */
+export declare function main(rawArgv: string[]): Promise<number>;
+//# sourceMappingURL=build-candidate-cli.d.ts.map

package/out/build-candidate-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-candidate-cli.d.ts","sourceRoot":"","sources":["../build-candidate-cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;GAYG;AAiDH,wBAAsB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB7D"}

package/out/build-candidate-cli.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman-wof-build-candidate --in <admin.db> --out <candidate.db>`
+ *
+ *   Operator-side one-shot CLI that builds the global byte-range "candidate" lookup DB for the
+ *   browser demo (the FTS-free, single-probe gazetteer). Delegates to
+ *   {@linkcode buildCandidateTable}; the CLI is just argument parsing + stderr progress. The
+ *   TypeScript port of the 2026-06-20 prototype — it lives in the package (not /scripts) so the
+ *   name_key normalizer is the SAME shared `normalizeLocalityForKey` the query-side resolver uses.
+ */
+import { exit, stderr } from "node:process";
+import { buildCandidateTable } from "./build-candidate.js";
+function printUsageAndExit(code) {
+    stderr.write([
+        "usage: mailwoman-wof-build-candidate --in <admin.db> --out <candidate.db> [--postcodes <pc.db>]...",
+        "",
+        "Builds the global candidate lookup DB (FTS-free, single B-tree probe per resolve) from a",
+        "unified admin WOF DB (needs spr, place_population, place_search, place_abbr, ancestors).",
+        "--postcodes folds a postcode shard (spr placetype='postalcode' + coords, e.g. postalcode-us.db)",
+        "in as postalcode rows so findPlace(postalcode) resolves a ZIP. Name keys use the shared",
+        "normalizeLocalityForKey — the query side MUST match.",
+        "",
+    ].join("\n"));
+    exit(code);
+}
+function parseArgs(argv) {
+    let input;
+    let output;
+    const postcodes = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--in" || a === "--input")
+            input = argv[++i];
+        else if (a === "--out" || a === "--output")
+            output = argv[++i];
+        else if (a === "--postcodes") {
+            const v = argv[++i];
+            if (v)
+                postcodes.push(v);
+        }
+        else if (a === "-h" || a === "--help")
+            printUsageAndExit(0);
+        else {
+            stderr.write(`unknown argument: ${a}\n`);
+            printUsageAndExit(1);
+        }
+    }
+    if (!input || !output)
+        printUsageAndExit(1);
+    return { input, output, postcodes };
+}
+export async function main(rawArgv) {
+    const args = parseArgs(rawArgv);
+    const t0 = Date.now();
+    const result = await buildCandidateTable({
+        input: args.input,
+        output: args.output,
+        postcodes: args.postcodes,
+        onProgress: (phase, message) => stderr.write(`  [${phase}] ${message}\n`),
+    });
+    const secs = ((Date.now() - t0) / 1000).toFixed(1);
+    stderr.write(`done in ${secs}s: ${result.rows.toLocaleString()} rows ` +
+        `(${result.primaries.toLocaleString()} primary, ${result.aliases.toLocaleString()} alias, ` +
+        `${result.abbrevs} abbr, ${result.postcodes.toLocaleString()} postcode) ` +
+        `from ${result.places.toLocaleString()} places → ${args.output}\n`);
+    return 0;
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main(process.argv.slice(2))
+        .then((code) => exit(code))
+        .catch((err) => {
+        stderr.write(`${err instanceof Error ? err.stack : String(err)}\n`);
+        exit(1);
+    });
+}
+//# sourceMappingURL=build-candidate-cli.js.map

package/out/build-candidate-cli.js.map

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

package/out/build-candidate.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Build the global "candidate" lookup DB from a unified admin WOF DB — the byte-range-optimal
+ *   gazetteer the browser demo resolves against. Instead of FTS5 (whose postings for a common name
+ *   scatter across a multi-GB file → hundreds of serial range fetches), this materializes one
+ *   `WITHOUT ROWID` B-tree keyed `(name_key, country_id, region_id, placetype_id, neg_rank,
+ *   spr_id)`: every place's normalized name + distinct aliases + region abbreviations become rows,
+ *   population rank is precomputed into `neg_rank`, and the rows are bulk-loaded PRE-SORTED so a
+ *   resolve is one contiguous B-tree probe (a handful of pages → 1-2 chunk fetches, regardless of
+ *   global volume).
+ *
+ *   Each row is DENORMALIZED — it carries the place's display `name`, centroid (`latitude`/
+ *   `longitude`), and `min/max` bbox — so a resolve is one statement, no FTS, no join to spr:
+ *   SELECT spr_id, name, latitude, longitude, min_lat, ... FROM candidate WHERE name_key = ? AND
+ *   country_id = ? AND placetype_id IN (...) [AND latitude BETWEEN ...] ORDER BY neg_rank ASC LIMIT
+ *   K; The demo cascade resolves a parsed region first (its bbox), then constrains the locality to
+ *   that bbox; `region_id` (the place's region-tier ancestor) is also carried for a future region
+ *   2-step.
+ *
+ *   The name_key normalizer is the SHARED {@link normalizeLocalityForKey} — the query side (the demo
+ *   resolver {@link WofCandidateTableLookup}) MUST use the same function, the one-normalizer
+ *   discipline the address-point shard uses, so build/query stay consistent by construction.
+ *
+ *   Measured (2026-06-20, vs the 2.6 GB full-DB FTS): ~5 M rows; ~12 range fetches per 8-query
+ *   session (the full DB needs 243); US locality 96.8% (region bbox), EU coord parity 88.6%.
+ */
+export interface BuildCandidateOptions {
+    /** Source unified admin DB — needs spr, place_population, place_search, place_abbr, ancestors. */
+    input: string;
+    /** Output candidate DB path (overwritten if present). */
+    output: string;
+    /**
+     * Optional postcode shards (`spr` rows with `placetype='postalcode'` + real coords, e.g.
+     * postalcode-us.db) — folded in as `postalcode` candidate rows so `findPlace(postalcode)`
+     * resolves a ZIP directly (the demo's primary postcode path; the postcode-*.bin anchor stays the
+     * fallback). Matches the slim wof-hot.db, which took one such postcode DB.
+     */
+    postcodes?: string[];
+    /** Optional progress callback for CLI / test introspection. */
+    onProgress?: (phase: string, message: string) => void;
+}
+export interface BuildCandidateResult {
+    rows: number;
+    places: number;
+    primaries: number;
+    aliases: number;
+    abbrevs: number;
+    postcodes: number;
+}
+export declare function buildCandidateTable(opts: BuildCandidateOptions): Promise<BuildCandidateResult>;
+//# sourceMappingURL=build-candidate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build-candidate.d.ts","sourceRoot":"","sources":["../build-candidate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAgBH,MAAM,WAAW,qBAAqB;IACrC,kGAAkG;IAClG,KAAK,EAAE,MAAM,CAAA;IACb,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAA;IACd;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACrD;AAED,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CACjB;AAkBD,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAyOpG"}

package/out/build-candidate.js

@@ -0,0 +1,230 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Build the global "candidate" lookup DB from a unified admin WOF DB — the byte-range-optimal
+ *   gazetteer the browser demo resolves against. Instead of FTS5 (whose postings for a common name
+ *   scatter across a multi-GB file → hundreds of serial range fetches), this materializes one
+ *   `WITHOUT ROWID` B-tree keyed `(name_key, country_id, region_id, placetype_id, neg_rank,
+ *   spr_id)`: every place's normalized name + distinct aliases + region abbreviations become rows,
+ *   population rank is precomputed into `neg_rank`, and the rows are bulk-loaded PRE-SORTED so a
+ *   resolve is one contiguous B-tree probe (a handful of pages → 1-2 chunk fetches, regardless of
+ *   global volume).
+ *
+ *   Each row is DENORMALIZED — it carries the place's display `name`, centroid (`latitude`/
+ *   `longitude`), and `min/max` bbox — so a resolve is one statement, no FTS, no join to spr:
+ *   SELECT spr_id, name, latitude, longitude, min_lat, ... FROM candidate WHERE name_key = ? AND
+ *   country_id = ? AND placetype_id IN (...) [AND latitude BETWEEN ...] ORDER BY neg_rank ASC LIMIT
+ *   K; The demo cascade resolves a parsed region first (its bbox), then constrains the locality to
+ *   that bbox; `region_id` (the place's region-tier ancestor) is also carried for a future region
+ *   2-step.
+ *
+ *   The name_key normalizer is the SHARED {@link normalizeLocalityForKey} — the query side (the demo
+ *   resolver {@link WofCandidateTableLookup}) MUST use the same function, the one-normalizer
+ *   discipline the address-point shard uses, so build/query stay consistent by construction.
+ *
+ *   Measured (2026-06-20, vs the 2.6 GB full-DB FTS): ~5 M rows; ~12 range fetches per 8-query
+ *   session (the full DB needs 243); US locality 96.8% (region bbox), EU coord parity 88.6%.
+ */
+import { DatabaseClient } from "@mailwoman/core/kysley/client";
+import { existsSync, rmSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { CANDIDATE_COLUMNS, createCandidateStagingTables, createCandidateTable, } from "./candidate-schema.js";
+import { normalizeLocalityForKey } from "./street-normalize.js";
+/** Boundary-preserving alias-bag separator (#523, U+E000). */
+const ALIAS_SEP = "\u{E000}";
+export async function buildCandidateTable(opts) {
+    const progress = opts.onProgress ?? (() => { });
+    if (existsSync(opts.output))
+        rmSync(opts.output);
+    const src = new DatabaseSync(opts.input, { readOnly: true });
+    const out = new DatabaseSync(opts.output);
+    // Build-tuning pragmas (raw — Kysely doesn't model PRAGMA). The code dictionaries + the transient
+    // staging table come from the SHARED schema DDL, so they can't drift from {@link CandidateDatabase}.
+    out.exec("PRAGMA page_size=8192; PRAGMA journal_mode=OFF; PRAGMA synchronous=OFF; PRAGMA cache_size=-2000000;");
+    const kdb = new DatabaseClient({ database: out });
+    await createCandidateStagingTables(kdb);
+    // --- compact code maps (country/placetype → small int, shrinks the clustered key). The ids are
+    // assigned here; the rows are bulk-inserted via kdb once the passes have discovered every code. ---
+    const ccodes = new Map();
+    const ptcodes = new Map();
+    const ccId = (code) => {
+        const c = (code || "??").toUpperCase();
+        let id = ccodes.get(c);
+        if (id === undefined) {
+            id = ccodes.size;
+            ccodes.set(c, id);
+        }
+        return id;
+    };
+    const ptId = (pt) => {
+        const p = pt || "";
+        let id = ptcodes.get(p);
+        if (id === undefined) {
+            id = ptcodes.size;
+            ptcodes.set(p, id);
+        }
+        return id;
+    };
+    // --- region_id per place (its region-tier ancestor) for same-name disambiguation ---
+    progress("region", "loading region ancestry");
+    const regionOf = new Map();
+    for (const r of src.prepare("SELECT id, ancestor_id FROM ancestors WHERE ancestor_placetype='region'").iterate()) {
+        regionOf.set(Number(r.id), Number(r.ancestor_id));
+    }
+    progress("region", `${regionOf.size.toLocaleString()} places carry a region`);
+    // The hot path — millions of clustered rows. Kept a single positional prepared statement (the fastest
+    // node:sqlite insert) rather than a per-row query builder. Placeholders come from CANDIDATE_COLUMNS so
+    // the column COUNT can't drift; the positional run() args below MUST stay in CANDIDATE_COLUMNS order.
+    const insStage = out.prepare(`INSERT INTO cand_stage VALUES (${CANDIDATE_COLUMNS.map(() => "?").join(", ")})`);
+    // --- pass 1: primaries (and the per-place attrs the alias/abbrev passes reuse) ---
+    progress("primaries", "indexing place names");
+    const attrs = new Map();
+    let nPrim = 0;
+    out.exec("BEGIN");
+    for (const r of src
+        .prepare(`SELECT s.id AS id, s.name AS name, s.placetype AS placetype, s.country AS country,
+				s.latitude AS lat, s.longitude AS lon,
+				s.min_latitude AS mnlat, s.min_longitude AS mnlon, s.max_latitude AS mxlat, s.max_longitude AS mxlon,
+				COALESCE(pp.population,0) AS pop
+			 FROM spr s LEFT JOIN place_population pp ON pp.id = s.id
+			 WHERE s.is_current != 0 AND s.is_deprecated = 0`)
+        .iterate()) {
+        const sid = Number(r.id);
+        const cid = ccId(r.country);
+        const ptid = ptId(r.placetype);
+        const rid = regionOf.get(sid) ?? 0;
+        const pop = Number(r.pop) || 0;
+        const neg = -Math.log10(pop + 1);
+        const name = String(r.name ?? "");
+        const pkey = normalizeLocalityForKey(name);
+        const a = {
+            cid,
+            rid,
+            ptid,
+            name,
+            lat: r.lat,
+            lon: r.lon,
+            mnLat: r.mnlat,
+            mnLon: r.mnlon,
+            mxLat: r.mxlat,
+            mxLon: r.mxlon,
+            pop,
+            neg,
+            pkey,
+        };
+        attrs.set(sid, a);
+        if (pkey) {
+            insStage.run(pkey, cid, rid, ptid, neg, sid, name, a.lat, a.lon, a.mnLat, a.mnLon, a.mxLat, a.mxLon, pop, 1);
+            nPrim++;
+        }
+    }
+    out.exec("COMMIT");
+    progress("primaries", `${nPrim.toLocaleString()} primaries; ${attrs.size.toLocaleString()} places`);
+    const stageRow = (k, a, sid, isPrimary) => {
+        insStage.run(k, a.cid, a.rid, a.ptid, a.neg, sid, a.name, a.lat, a.lon, a.mnLat, a.mnLon, a.mxLat, a.mxLon, a.pop, isPrimary);
+    };
+    // --- pass 2: distinct normalized aliases from place_search.alt_names ---
+    progress("aliases", "exploding alias bags");
+    let nAlias = 0;
+    out.exec("BEGIN");
+    for (const r of src.prepare("SELECT wof_id, alt_names FROM place_search").iterate()) {
+        const a = attrs.get(Number(r.wof_id));
+        const alt = r.alt_names;
+        if (!a || !alt)
+            continue;
+        const seen = new Set([a.pkey]);
+        for (const piece of alt.split(ALIAS_SEP)) {
+            const k = normalizeLocalityForKey(piece);
+            if (!k || seen.has(k))
+                continue;
+            seen.add(k);
+            stageRow(k, a, Number(r.wof_id), 0);
+            nAlias++;
+        }
+    }
+    out.exec("COMMIT");
+    progress("aliases", `${nAlias.toLocaleString()} aliases`);
+    // --- pass 3: region abbreviations (place_abbr) ---
+    let nAbbr = 0;
+    out.exec("BEGIN");
+    for (const r of src.prepare("SELECT id, abbr FROM place_abbr").iterate()) {
+        const a = attrs.get(Number(r.id));
+        if (!a)
+            continue;
+        const k = normalizeLocalityForKey(String(r.abbr ?? ""));
+        if (!k)
+            continue;
+        stageRow(k, a, Number(r.id), 1);
+        nAbbr++;
+    }
+    out.exec("COMMIT");
+    progress("abbrevs", `${nAbbr.toLocaleString()} abbrevs`);
+    // --- pass 4: postcodes (separate shards: spr placetype='postalcode' with real coords) ---
+    let nPostcode = 0;
+    for (const pcDb of opts.postcodes ?? []) {
+        progress("postcodes", `reading ${pcDb}`);
+        const pc = new DatabaseSync(pcDb, { readOnly: true });
+        const pcPtid = ptId("postalcode");
+        out.exec("BEGIN");
+        for (const r of pc
+            .prepare(`SELECT id, name, country, latitude, longitude,
+					min_latitude AS mnlat, min_longitude AS mnlon, max_latitude AS mxlat, max_longitude AS mxlon
+				 FROM spr WHERE placetype='postalcode' AND latitude != 0 AND longitude != 0`)
+            .iterate()) {
+            const name = String(r.name ?? "");
+            const key = normalizeLocalityForKey(name);
+            if (!key)
+                continue;
+            const lat = r.latitude;
+            const lon = r.longitude;
+            // region_id 0 (a postcode is unique by name+country — no same-name disambiguation); neg_rank 0
+            // (no population). bbox = the postcode's own min/max (falls back to the centroid point).
+            insStage.run(key, ccId(r.country), 0, pcPtid, 0, Number(r.id), name, lat, lon, r.mnlat || lat, r.mnlon || lon, r.mxlat || lat, r.mxlon || lon, 0, 1);
+            nPostcode++;
+        }
+        out.exec("COMMIT");
+        pc.close();
+    }
+    if (nPostcode > 0)
+        progress("postcodes", `${nPostcode.toLocaleString()} postcodes`);
+    // --- code dictionaries: typed batch inserts via kdb (a few hundred rows — Kysely is clean here) ---
+    if (ccodes.size > 0) {
+        await kdb
+            .insertInto("country_codes")
+            .values([...ccodes].map(([code, id]) => ({ id, code })))
+            .execute();
+    }
+    if (ptcodes.size > 0) {
+        await kdb
+            .insertInto("placetype_codes")
+            .values([...ptcodes].map(([placetype, id]) => ({ id, placetype })))
+            .execute();
+    }
+    // --- materialize the clustered WITHOUT ROWID table (sorted insert → contiguous leaves) ---
+    progress("cluster", "building clustered candidate table + VACUUM");
+    // Column list + clustered-key order are sourced from CANDIDATE_COLUMNS (the first 6 ARE the PRIMARY
+    // KEY) so the SELECT, the ORDER BY, and the table can't drift. The table comes from the shared
+    // createCandidateTable().
+    const cols = CANDIDATE_COLUMNS.join(", ");
+    const keyOrder = CANDIDATE_COLUMNS.slice(0, 6).join(", ");
+    await createCandidateTable(kdb);
+    // OR IGNORE: an abbrev/alias can normalize to a place's primary key (same place, same rank) → any one
+    // row. The bulk sorted INSERT…SELECT (clustered materialization) stays raw — a single hot bulk statement.
+    out.exec(`INSERT OR IGNORE INTO candidate (${cols}) SELECT ${cols} FROM cand_stage ORDER BY ${keyOrder};`);
+    await kdb.schema.dropTable("cand_stage").execute();
+    // page_size MUST be set right before VACUUM: node:sqlite initializes the file at the 4096 default on
+    // `new DatabaseSync`, so the creation-time pragma is a no-op — only a VACUUM rebuilds at the new size.
+    // 8192 matches the sql.js-httpvfs 64 KiB request chunk cleanly (8 pages) and shallows the B-tree.
+    out.exec("PRAGMA page_size=8192");
+    out.exec("VACUUM");
+    const { n: rows } = await kdb
+        .selectFrom("candidate")
+        .select((eb) => eb.fn.countAll().as("n"))
+        .executeTakeFirstOrThrow();
+    src.close();
+    await kdb.destroy(); // closes the underlying `out` connection
+    return { rows, places: attrs.size, primaries: nPrim, aliases: nAlias, abbrevs: nAbbr, postcodes: nPostcode };
+}
+//# sourceMappingURL=build-candidate.js.map

package/out/build-candidate.js.map

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

package/out/build-coincident-roles-cli.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman-wof-build-coincident-roles <path-to-admin.db>... [--drop]`
+ *
+ *   Operator-side one-shot CLI (#403, epic #402): derives the `coincident_roles` relation into an
+ *   existing admin gazetteer — the dual-role places (city-states, capital-seat provinces,
+ *   consolidated city-counties) the hierarchy-completion step (#405) consults. Additive +
+ *   idempotent; re-run after refreshing `spr`/`ancestors`. Mirrors `build-fts-cli.ts`. Should also
+ *   be invoked as a post-step of the main `scripts/build-unified-wof.ts`.
+ */
+export declare function main(argv: readonly string[]): number;
+//# sourceMappingURL=build-coincident-roles-cli.d.ts.map

package/out/build-coincident-roles-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-coincident-roles-cli.d.ts","sourceRoot":"","sources":["../build-coincident-roles-cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;GAYG;AAuDH,wBAAgB,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAqBpD"}