@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/out/address/point.js

@@ -0,0 +1,206 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file SQLite implementation of core's `AddressPointLookup`.
+ */
+import { DatabaseClient } from "@mailwoman/sqlite/client";
+import { hasTable, prepareGet } from "#sqlite-utils";
+import { normalizeHouseNumberForKey, normalizeLocalityForKey, normalizeLocalityForKeyLocale, streetKeyVariants, streetLocaleForSurface, stripArrondissement, } from "#street/normalize";
+/**
+ * The column list every prepared SELECT uses.
+ * It must match the fields of `AddressPointRow`.
+ */
+const SELECT_COLS = "lat, lon, source, release, locality_norm, postcode";
+/**
+ * Finds an address point by exact normalized `(street, number)` within a postcode,
+ * a locality, or a bounding box.
+ *
+ * Query normalization uses the extract's `streetLocale`, which must match the
+ * locale the extract was built with.
+ * Street matching is exact after normalization.
+ *
+ * Scopes are tried from most to least selective: postcode, locality, locality suffix, then bounding box.
+ * When several rows match, any one of them can answer, because unit siblings share the building coordinate.
+ */
+export class AddressPointSqliteLookup {
+    #db;
+    #locale;
+    #localityKeys;
+    #byPostcode;
+    #byPostcodeLocality;
+    #byLocality;
+    /**
+     * This query matches the locality key by its suffix, for a `zh` query that gives the 鄉鎮市區 without its 縣市.
+     *
+     * The (street, number) index narrows the rows first, so the `LIKE` scans only rows that share the pair.
+     */
+    #byLocalityTail;
+    #byBbox;
+    /**
+     * @param dbPath Extract path.
+     * @param opts.streetLocale The street-normalization locale the extract was built with.
+     * A mismatch makes every key miss.
+     * @param opts.localityKeys Whether the extract's `locality_norm` holds full place names.
+     * With `"abbreviated"`, a row's locality can select a row but never rejects one.
+     * The US situs extract uses NAD city fields.
+     * Some counties abbreviate them (`addi` for Addison).
+     * Other counties replace them with the parent town.
+     *
+     * @defaultValue `"us"`
+     * @defaultValue `"abbreviated"` for `"us"` and `"full"` for every other locale.
+     */
+    constructor(dbPath, opts = {}) {
+        this.#db = new DatabaseClient(dbPath, { readOnly: true });
+        this.#locale = opts.streetLocale ?? "us";
+        this.#localityKeys = opts.localityKeys ?? (this.#locale === "us" ? "abbreviated" : "full");
+        // An extract without an `address_point` table, such as an interrupted build, makes every lookup miss.
+        if (hasTable(this.#db, "address_point")) {
+            this.#byPostcode = prepareGet(this.#db, `SELECT ${SELECT_COLS} FROM address_point
+				 WHERE postcode = ? AND street_norm = ? AND number = ? LIMIT 1`);
+            this.#byPostcodeLocality = prepareGet(this.#db, `SELECT ${SELECT_COLS} FROM address_point
+				 WHERE postcode = ? AND locality_norm = ? AND street_norm = ? AND number = ? LIMIT 1`);
+            this.#byLocality = prepareGet(this.#db, `SELECT ${SELECT_COLS} FROM address_point
+				 WHERE locality_norm = ? AND street_norm = ? AND number = ? LIMIT 1`);
+            this.#byBbox = prepareGet(this.#db, `SELECT ${SELECT_COLS} FROM address_point
+				 WHERE street_norm = ? AND number = ? AND lat BETWEEN ? AND ? AND lon BETWEEN ? AND ? LIMIT 1`);
+            this.#byLocalityTail = prepareGet(this.#db, `SELECT ${SELECT_COLS} FROM address_point
+				 WHERE street_norm = ? AND number = ? AND locality_norm LIKE ? LIMIT 1`);
+        }
+    }
+    find(query) {
+        if (!this.#byPostcode || !this.#byLocality || !this.#byBbox)
+            return null;
+        const number = normalizeHouseNumberForKey(query.number, this.#locale);
+        if (!number)
+            return null;
+        // A `zh` extract keys locality as 縣市 + 鄉鎮市區.
+        // The parser tags 縣市 as `region` and 鄉鎮市區 as `subregion`.
+        // The Taiwanese register has no postcode, so this pair becomes the locality key.
+        // A query with only the 鄉鎮市區 matches the stored key by its suffix.
+        const scoped = this.#locale === "zh" && !query.locality && query.subregion
+            ? query.region
+                ? { ...query, locality: `${query.region}${query.subregion}` }
+                : { ...query, localityTail: normalizeLocalityForKeyLocale(query.subregion, "zh") }
+            : query;
+        // `streetKeyVariants` yields the literal key first.
+        // Each variant runs the full number fallback sequence.
+        // The first variant with a match wins.
+        let row = null;
+        for (const streetNorm of streetKeyVariants(query.street, streetLocaleForSurface(query.street, this.#locale))) {
+            row = this.#findForKey(streetNorm, number, scoped);
+            if (row)
+                break;
+        }
+        if (!row)
+            return null;
+        return {
+            lat: row.lat,
+            lon: row.lon,
+            source: row.source,
+            release: row.release,
+            localityNorm: row.locality_norm || null,
+            postcode: row.postcode || null,
+        };
+    }
+    /**
+     * Tries one normalized street key with the exact number, then fallback number forms.
+     * Each fallback runs only after the previous forms missed.
+     */
+    #findForKey(streetNorm, number, query) {
+        let row = this.#probe(streetNorm, number, query);
+        // The registers store one number per point, so a range such as "385-387" falls back to its low end.
+        if (!row) {
+            const low = /^(\d+[a-z]?)-\d+[a-z]?$/.exec(number)?.[1];
+            if (low) {
+                row = this.#probe(streetNorm, low, query);
+            }
+        }
+        // BAN stores a letter suffix as "3 a", while G-NAF and most OA sources store "3a".
+        // For a number of digits plus one letter, the lookup retries the other spacing
+        // and then the bare number.
+        if (!row) {
+            const joined = /^(\d+)\s+([a-z])$/.exec(number);
+            const spaced = /^(\d+)([a-z])$/.exec(number);
+            if (joined) {
+                row = this.#probe(streetNorm, `${joined[1]}${joined[2]}`, query) ?? this.#probe(streetNorm, joined[1], query);
+            }
+            else if (spaced) {
+                row = this.#probe(streetNorm, `${spaced[1]} ${spaced[2]}`, query) ?? this.#probe(streetNorm, spaced[1], query);
+            }
+        }
+        // The Taiwanese register stores `14之12` and `30附40` as numbers `14` and `30`.
+        // It stores the rest in `unit`.
+        // A query number that still includes the sub-number falls back to the base number.
+        // That result is approximate.
+        if (!row && this.#locale === "zh") {
+            const base = /^(\d+)(?:[之附]\d+)+$/u.exec(number)?.[1];
+            if (base) {
+                row = this.#probe(streetNorm, base, query);
+            }
+        }
+        return row;
+    }
+    /**
+     * Probes one (street, number) key by postcode, then locality, then locality suffix, then bounding box.
+     * Each scope runs only when the previous ones missed.
+     */
+    #probe(streetNorm, number, query) {
+        let row = null;
+        if (query.postcode) {
+            const postcode = query.postcode.trim();
+            const localityKey = query.locality ? this.#localityKey(query.locality) : null;
+            // One postcode can cover several places with the same street and number,
+            // so a row whose locality agrees with the query is tried first.
+            // The postcode-only row answers only if `#scopeContradicts` accepts it.
+            const agreeing = localityKey ? this.#byPostcodeLocality(postcode, localityKey, streetNorm, number) : null;
+            const candidate = agreeing ?? this.#byPostcode(postcode, streetNorm, number);
+            row = candidate && !this.#scopeContradicts(candidate, query) ? candidate : null;
+        }
+        if (!row && query.locality) {
+            row = this.#byLocality(this.#localityKey(query.locality), streetNorm, number);
+        }
+        if (!row && query.localityTail && this.#byLocalityTail) {
+            // A Han key contains no `%` or `_`, so the pattern matches a literal suffix.
+            row = this.#byLocalityTail(streetNorm, number, `%${query.localityTail}`);
+        }
+        // The bounding box serves extracts whose points have no postcode or locality, such as OSM.
+        if (!row && query.bbox) {
+            const b = query.bbox;
+            const candidate = this.#byBbox(streetNorm, number, b.minLat, b.maxLat, b.minLon, b.maxLon);
+            // A row with its own scope that the scoped probes missed is a different address in the same box.
+            row = candidate && !this.#scopeContradicts(candidate, query) ? candidate : null;
+        }
+        return row;
+    }
+    /**
+     * Folds the query's locality the way the extract's builder folded `locality_norm`.
+     *
+     * FR extracts key arrondissements at the base city, so "Paris 13e Arrondissement"
+     * and "Paris" produce the same key.
+     */
+    #localityKey(locality) {
+        if (this.#locale === "fr")
+            return stripArrondissement(normalizeLocalityForKey(locality));
+        return normalizeLocalityForKeyLocale(locality, this.#locale);
+    }
+    /**
+     * Returns whether the row's own postcode or locality differs from the query's.
+     *
+     * A row field that is empty never contradicts.
+     * The locality is compared only when the extract's `localityKeys` is `"full"`,
+     * because abbreviated keys would reject correct rows.
+     */
+    #scopeContradicts(row, query) {
+        if (query.postcode && row.postcode && row.postcode.trim() !== query.postcode.trim())
+            return true;
+        if (this.#localityKeys === "full" && query.locality && row.locality_norm) {
+            return row.locality_norm !== this.#localityKey(query.locality);
+        }
+        return false;
+    }
+    [Symbol.dispose]() {
+        this.#db[Symbol.dispose]();
+    }
+}
+//# sourceMappingURL=point.js.map

package/out/address/point.js.map

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

package/out/{address/index.js → address.d.ts}

@@ -3,7 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  */
-export * from "#address/point/index";
+export * from "#address/point";
 export * from "#address/point/interpolation";
 export * from "#address/point/schema";
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=address.d.ts.map

package/out/address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../lib/address.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,8BAA8B,CAAA;AAC5C,cAAc,uBAAuB,CAAA"}

package/out/{address/index.d.ts → address.js}

@@ -3,7 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  */
-export * from "#address/point/index";
+export * from "#address/point";
 export * from "#address/point/interpolation";
 export * from "#address/point/schema";
-//# sourceMappingURL=index.d.ts.map
+//# sourceMappingURL=address.js.map

package/out/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","sourceRoot":"","sources":["../lib/address.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,8BAA8B,CAAA;AAC5C,cAAc,uBAAuB,CAAA"}

package/out/ancestry/backfill.d.ts

@@ -3,85 +3,32 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Repair the truncated ancestry that {@link populateAncestors} (the parent_id closure in
- *   unified-schema.ts) leaves wherever the closure dead-ends before reaching the top.
- *
- *   Root cause (#440 / #832): a place that straddles multiple parents — New York City spans five
- *   counties (its boroughs), London 30+ — carries `wof:parent_id = -4`, so the parent_id closure
- *   dead-ends and the place gets NO region/county/country ancestry. The resolver's region-descendant
- *   filter then can't reach it: given "New York, NY", NYC (with no NY-state ancestor) is excluded and
- *   a correctly-parented namesake ("New York Mills", pop 3,190) wins over NYC's 8.8M. The same defect
- *   orphans London, Singapore, and ~2,850 other localities — the most demo-visible queries.
- *
- *   **The dead end is inherited by children (#1445).** Repairing the `-4` place itself does not repair
- *   anything BELOW it: the closure walks Brooklyn → New York and stops, because New York's own
- *   `parent_id` is `-4`. Brooklyn-the-borough (pop 2.5M) therefore carried exactly two ancestor rows —
- *   itself and New York — with no county, region or country, and the only US locality-tier place named
- *   "Brooklyn" that survived a New-York-State descendant filter was Pillar Point, a Jefferson County
- *   hamlet 411 km away carrying "Brooklyn" as an alternate name. All five NYC boroughs, every London
- *   borough and Hyderabad's zones were in the same state.
- *
- *   So the candidate test is NOT "has only a self ancestor" — that misses every child of a repaired
- *   place, which by construction has two. It is **"has no `country`-tier ancestor"**. Country is the
- *   universal terminal for every non-{@link TOP_PLACETYPES} placetype, so its absence is exactly the
- *   signal that the chain dead-ended somewhere, at whatever depth. On a wide-coverage build this
- *   selects ~24k places against 2.55M rows.
- *
- *   A place whose `wof:hierarchy` genuinely stops short is NOT a candidate and needs no repair: the
- *   source is the authority on what a place should have. American Samoa's localities, for instance,
- *   have `{country_id, locality_id}` and no region in WOF itself — the artifact matching that is
- *   correct, not truncated.
- *
- *   The authoritative hierarchy IS in the source geojson: `wof:hierarchy` is an array of branches,
- *   each a `<placetype>_id` → id map (region_id, county_id, country_id, …), fully populated even when
- *   parent_id is -4. This reads it for every candidate and inserts the missing ancestor rows (one per
- *   distinct ancestor across branches).
- *
- *   MUST run AFTER populateAncestors and BEFORE the build freezes (VACUUM INTO), so the rows land in
- *   the shipped artifact — `scripts/build-unified-wof.ts` Phase 3 calls it inline. The standalone
- *   `scripts/backfill-ancestors-from-hierarchy.ts` is a thin CLI over the same function for ad-hoc
- *   repair of an already-built DB. Idempotent by the per-pair existence check, not by the candidate
- *   test: each (id, ancestor_id) is inserted at most once, so a second run over the same DB adds
- *   nothing.
+ *   Repair the truncated ancestry left by the `parent_id` closure. Must run after `populateAncestors` and before the build freezes.
  */
 import type { DatabaseClient } from "@mailwoman/sqlite/client";
-import { type PathBuilderLike } from "path-ts";
+import { PathBuilder, type PathBuilderLike } from "path-ts";
 import type { WOFDatabase } from "#schema";
 export interface AncestryBackfillResult {
-    /**
-     * Places that gained at least one ancestor row.
-     */
     placesFixed: number;
-    /**
-     * Total ancestor rows inserted.
-     */
     rowsAdded: number;
     /**
-     * Candidates whose source geojson could not be found (non-WOF backfilled places, or repos not present locally) —
-     * skipped, not an error.
+     * Candidates whose source geojson was not found (non-WOF backfilled places or absent repos),
+     * skipped rather than treated as an error.
      */
     noGeojson: number;
 }
 /**
- * Discover the `data` directories under a WOF repos root that hold attached geojson, e.g.
- * `<root>/whosonfirst-data/whosonfirst-data-admin-us/data`. Resolves an id to its geojson via these roots. Accepts both
- * the nested lab layout (a `whosonfirst-data` group dir holding the admin repos) and a flat layout (admin repos
- * directly under the root); searches at most two directory levels deep.
+ * Discover the `data` directories under a WOF repos root that hold attached geojson,
+ * accepting both the nested lab layout and a flat layout at most two directory levels deep.
  */
-export declare function discoverAdminDataRoots(reposRoot: PathBuilderLike): Promise<string[]>;
+export declare function discoverAdminDataRoots(reposRoot: PathBuilderLike): Promise<PathBuilder[]>;
 /**
- * Insert missing ancestor rows for every place whose ancestry chain dead-ended before reaching a country, by reading
- * `wof:hierarchy` from its source geojson under `geojsonRoots` (see {@link discoverAdminDataRoots}). Runs inside a
- * single transaction; caller owns connection lifecycle (open, WAL checkpoint, close).
+ * Insert missing ancestor rows for places whose ancestry chain ended before reaching a country.
  *
- * `opts.maxID` bounds the candidate scan to ids BELOW it — pass the synthetic-id base (`OVERTURE_ID_BASE`, 8e12) so the
- * backfill considers only real WOF places. Overture/GeoNames rows carry synthetic ids and have NO `wof:hierarchy`
- * geojson, so probing them is pure waste: on a wide-coverage DB the country-less set is millions of Overture/GeoNames
- * leaf localities, and the per-candidate geojson probe across every repo root turns a seconds-long WOF-only pass into a
- * ~40-minute one (their ancestry comes from the parent_id closure, not this backfill). Correctness-preserving — the
- * skipped rows would have `noGeojson`-skipped anyway. Omit `maxID` (default) for the legacy WOF-only DBs.
+ * The function reads `wof:hierarchy` and runs in one transaction under the caller's connection.
+ * `opts.maxID` bounds the scan to avoid probing synthetic-id Overture and GeoNames rows.
  */
-export declare function backfillAncestorsFromHierarchy(db: DatabaseClient<WOFDatabase>, geojsonRoots: readonly string[], opts?: {
+export declare function backfillAncestorsFromHierarchy(db: DatabaseClient<WOFDatabase>, geojsonRoots: readonly PathBuilderLike[], opts?: {
     maxID?: number;
 }): Promise<AncestryBackfillResult>;
 //# sourceMappingURL=backfill.d.ts.map

package/out/ancestry/backfill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backfill.d.ts","sourceRoot":"","sources":["../../lib/ancestry/backfill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAC9D,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAGjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAO1C,MAAM,WAAW,sBAAsB;IACtC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAA;CACjB;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,SAAS,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA8B1F;AAYD;;;;;;;;;;;GAWG;AACH,wBAAsB,8BAA8B,CACnD,EAAE,EAAE,cAAc,CAAC,WAAW,CAAC,EAC/B,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC3B,OAAO,CAAC,sBAAsB,CAAC,CAkHjC"}
+{"version":3,"file":"backfill.d.ts","sourceRoot":"","sources":["../../lib/ancestry/backfill.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAC9D,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAG3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAI1C,MAAM,WAAW,sBAAsB;IACtC,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAA;CACjB;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,SAAS,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CA8B/F;AAUD;;;;;GAKG;AACH,wBAAsB,8BAA8B,CACnD,EAAE,EAAE,cAAc,CAAC,WAAW,CAAC,EAC/B,YAAY,EAAE,SAAS,eAAe,EAAE,EACxC,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC3B,OAAO,CAAC,sBAAsB,CAAC,CA0GjC"}

package/out/ancestry/backfill.js

@@ -3,59 +3,15 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Repair the truncated ancestry that {@link populateAncestors} (the parent_id closure in
- *   unified-schema.ts) leaves wherever the closure dead-ends before reaching the top.
- *
- *   Root cause (#440 / #832): a place that straddles multiple parents — New York City spans five
- *   counties (its boroughs), London 30+ — carries `wof:parent_id = -4`, so the parent_id closure
- *   dead-ends and the place gets NO region/county/country ancestry. The resolver's region-descendant
- *   filter then can't reach it: given "New York, NY", NYC (with no NY-state ancestor) is excluded and
- *   a correctly-parented namesake ("New York Mills", pop 3,190) wins over NYC's 8.8M. The same defect
- *   orphans London, Singapore, and ~2,850 other localities — the most demo-visible queries.
- *
- *   **The dead end is inherited by children (#1445).** Repairing the `-4` place itself does not repair
- *   anything BELOW it: the closure walks Brooklyn → New York and stops, because New York's own
- *   `parent_id` is `-4`. Brooklyn-the-borough (pop 2.5M) therefore carried exactly two ancestor rows —
- *   itself and New York — with no county, region or country, and the only US locality-tier place named
- *   "Brooklyn" that survived a New-York-State descendant filter was Pillar Point, a Jefferson County
- *   hamlet 411 km away carrying "Brooklyn" as an alternate name. All five NYC boroughs, every London
- *   borough and Hyderabad's zones were in the same state.
- *
- *   So the candidate test is NOT "has only a self ancestor" — that misses every child of a repaired
- *   place, which by construction has two. It is **"has no `country`-tier ancestor"**. Country is the
- *   universal terminal for every non-{@link TOP_PLACETYPES} placetype, so its absence is exactly the
- *   signal that the chain dead-ended somewhere, at whatever depth. On a wide-coverage build this
- *   selects ~24k places against 2.55M rows.
- *
- *   A place whose `wof:hierarchy` genuinely stops short is NOT a candidate and needs no repair: the
- *   source is the authority on what a place should have. American Samoa's localities, for instance,
- *   have `{country_id, locality_id}` and no region in WOF itself — the artifact matching that is
- *   correct, not truncated.
- *
- *   The authoritative hierarchy IS in the source geojson: `wof:hierarchy` is an array of branches,
- *   each a `<placetype>_id` → id map (region_id, county_id, country_id, …), fully populated even when
- *   parent_id is -4. This reads it for every candidate and inserts the missing ancestor rows (one per
- *   distinct ancestor across branches).
- *
- *   MUST run AFTER populateAncestors and BEFORE the build freezes (VACUUM INTO), so the rows land in
- *   the shipped artifact — `scripts/build-unified-wof.ts` Phase 3 calls it inline. The standalone
- *   `scripts/backfill-ancestors-from-hierarchy.ts` is a thin CLI over the same function for ad-hoc
- *   repair of an already-built DB. Idempotent by the per-pair existence check, not by the candidate
- *   test: each (id, ancestor_id) is inserted at most once, so a second run over the same DB adds
- *   nothing.
+ *   Repair the truncated ancestry left by the `parent_id` closure. Must run after `populateAncestors` and before the build freezes.
  */
 import { readWOFFeature } from "@mailwoman/core/resources/whosonfirst";
-import { join, resolvePath } from "path-ts";
+import { PathBuilder } from "path-ts";
 import { Globerator } from "spliterator/node/fs";
-/**
- * Genuinely top-level placetypes — they never have (or need) an ancestor, so skip them.
- */
 const TOP_PLACETYPES = new Set(["country", "continent", "empire", "ocean", "marinearea", "planet"]);
 /**
- * Discover the `data` directories under a WOF repos root that hold attached geojson, e.g.
- * `<root>/whosonfirst-data/whosonfirst-data-admin-us/data`. Resolves an id to its geojson via these roots. Accepts both
- * the nested lab layout (a `whosonfirst-data` group dir holding the admin repos) and a flat layout (admin repos
- * directly under the root); searches at most two directory levels deep.
+ * Discover the `data` directories under a WOF repos root that hold attached geojson,
+ * accepting both the nested lab layout and a flat layout at most two directory levels deep.
  */
 export async function discoverAdminDataRoots(reposRoot) {
     const roots = [];
@@ -72,7 +28,7 @@ export async function discoverAdminDataRoots(reposRoot) {
             return;
         }
         for (const name of names) {
-            const child = join(dir, name);
+            const child = dir(name);
             if (name === "data") {
                 roots.push(child);
             }
@@ -81,36 +37,25 @@ export async function discoverAdminDataRoots(reposRoot) {
             }
         }
     };
-    await visit(resolvePath(reposRoot), 0);
+    await visit(PathBuilder.from(reposRoot), 0);
     return roots;
 }
-// `<placetype>_id` key → ancestor placetype. WOF hierarchy keys are e.g. region_id, county_id. Self
-// is filtered downstream by the `aid === id` check, so we do NOT special-case locality here: for a
-// locality candidate `locality_id` IS self (dropped by aid===id), but for a neighbourhood candidate
-// `locality_id` is its PARENT locality — a real ancestor we must keep.
+// The `aid === id` check filters out a place's own `locality_id`.
+// For a neighborhood, that id identifies a real ancestor.
 function placetypeFromKey(key) {
     if (!key.endsWith("_id"))
         return null;
     return key.slice(0, -3);
 }
 /**
- * Insert missing ancestor rows for every place whose ancestry chain dead-ended before reaching a country, by reading
- * `wof:hierarchy` from its source geojson under `geojsonRoots` (see {@link discoverAdminDataRoots}). Runs inside a
- * single transaction; caller owns connection lifecycle (open, WAL checkpoint, close).
+ * Insert missing ancestor rows for places whose ancestry chain ended before reaching a country.
  *
- * `opts.maxID` bounds the candidate scan to ids BELOW it — pass the synthetic-id base (`OVERTURE_ID_BASE`, 8e12) so the
- * backfill considers only real WOF places. Overture/GeoNames rows carry synthetic ids and have NO `wof:hierarchy`
- * geojson, so probing them is pure waste: on a wide-coverage DB the country-less set is millions of Overture/GeoNames
- * leaf localities, and the per-candidate geojson probe across every repo root turns a seconds-long WOF-only pass into a
- * ~40-minute one (their ancestry comes from the parent_id closure, not this backfill). Correctness-preserving — the
- * skipped rows would have `noGeojson`-skipped anyway. Omit `maxID` (default) for the legacy WOF-only DBs.
+ * The function reads `wof:hierarchy` and runs in one transaction under the caller's connection.
+ * `opts.maxID` bounds the scan to avoid probing synthetic-id Overture and GeoNames rows.
  */
 export async function backfillAncestorsFromHierarchy(db, geojsonRoots, opts = {}) {
     const maxID = opts.maxID ?? Number.MAX_SAFE_INTEGER;
-    // "No country-tier ancestor" is the dead-end signal at any depth — see the module docstring. The
-    // earlier "<= 1 ancestor row" test only caught the dead end's origin, never the children that
-    // inherit it (a child of a repaired -4 place has two rows: itself and that parent) (#1445).
-    // The id bound is stated first so SQLite prunes by the PK index before the NOT EXISTS runs at all.
+    // The id bound is stated first so SQLite prunes by the PK index before the not-exists runs.
     const candidateBase = db
         .selectFrom("spr")
         .where("id", "<", maxID)
@@ -120,12 +65,8 @@ export async function backfillAncestorsFromHierarchy(db, geojsonRoots, opts = {}
         .whereRef("a.id", "=", "spr.id")
         .where("a.ancestor_placetype", "=", "country"))));
     const candidates = await candidateBase.select(["id", "placetype"]).execute();
-    // Every candidate's existing ancestors in ONE query rather than an indexed read each. The widened
-    // candidate test made that per-candidate read the dominant cost of the pass, and the set is bounded:
-    // a candidate reaching this point has a handful of rows at most. The candidate set rides in as the
-    // SAME predicate re-issued as a subquery, never a materialized `IN (?, ?, …)` list — node:sqlite
-    // caps a statement at 32,766 bound variables and the wide-coverage build has 67,521 candidates
-    // (measured 2026-08-04).
+    // Keep the candidate set as a subquery instead of materializing an `IN` list.
+    // node:sqlite limits bound variables to 32,766.
     const alreadyPresent = new Map();
     for (const row of await db
         .selectFrom("ancestors")
@@ -155,7 +96,6 @@ export async function backfillAncestorsFromHierarchy(db, geojsonRoots, opts = {}
             }
             continue;
         }
-        // Collect distinct (ancestor_id, placetype) across all hierarchy branches, excluding self.
         const seen = new Map();
         for (const branch of hierarchy) {
             for (const [key, val] of Object.entries(branch)) {

package/out/ancestry/backfill.js.map

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

package/out/ancestry.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @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 and centroids, ordered nearest-first with the deepest
+ *   placetype first and the country last.
+ *
+ *   The reverse geocoder and `WOFSQLitePlaceLookup.ancestors()` share this walk. Placetype
+ *   specificity lives here in `PLACETYPE_DEPTH`, a single TypeScript map that extends below
+ *   `localadmin` so locality, borough, neighborhood and microhood rank correctly. Forward
+ *   resolution rarely sees those as ancestor placetypes, while reverse geocoding always does.
+ */
+import type { DatabaseClient } from "@mailwoman/sqlite/client";
+/**
+ * WOF placetype → containment depth, coarsest = 1.
+ *
+ * Higher = finer. Placetypes we never resolve (continent, empire, …) map to 0 and sort last.
+ *
+ * This differs from the FST's `PLACETYPE_ORDER` (fst-serialize.ts), which is a serialization order.
+ * This one is containment depth.
+ */
+export declare const PLACETYPE_DEPTH: Readonly<Record<string, number>>;
+/**
+ * Containment depth for a placetype, 0 when unknown (sorts coarsest).
+ */
+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>(db: DatabaseClient<DB>, id: number, schemaName?: string): AncestorPlaceRow[];
+export * from "#ancestry/backfill";
+//# sourceMappingURL=ancestry.d.ts.map

package/out/ancestry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ancestry.d.ts","sourceRoot":"","sources":["../lib/ancestry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAE9D;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAY5D,CAAA;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;GAEG;AACH,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;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,SAAS,GAAG,gBAAgB,EAAE,CAc/G;AAED,cAAc,oBAAoB,CAAA"}

package/out/ancestry.js

@@ -0,0 +1,59 @@
+/**
+ * @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 and centroids, ordered nearest-first with the deepest
+ *   placetype first and the country last.
+ *
+ *   The reverse geocoder and `WOFSQLitePlaceLookup.ancestors()` share this walk. Placetype
+ *   specificity lives here in `PLACETYPE_DEPTH`, a single TypeScript map that extends below
+ *   `localadmin` so locality, borough, neighborhood and microhood rank correctly. Forward
+ *   resolution rarely sees those as ancestor placetypes, while reverse geocoding always does.
+ */
+import { allRows } from "@mailwoman/core/utils";
+/**
+ * WOF placetype → containment depth, coarsest = 1.
+ *
+ * Higher = finer. Placetypes we never resolve (continent, empire, …) map to 0 and sort last.
+ *
+ * This differs from the FST's `PLACETYPE_ORDER` (fst-serialize.ts), which 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 when unknown (sorts coarsest).
+ */
+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 = allRows(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`), id);
+    rows.sort((a, b) => placetypeDepth(b.placetype) - placetypeDepth(a.placetype));
+    return rows;
+}
+export * from "#ancestry/backfill";
+//# sourceMappingURL=ancestry.js.map

package/out/ancestry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ancestry.js","sourceRoot":"","sources":["../lib/ancestry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAG/C;;;;;;;GAOG;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;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC/C,OAAO,eAAe,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;AACvC,CAAC;AAcD;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAK,EAAsB,EAAE,EAAU,EAAE,UAAU,GAAG,MAAM;IAC1F,MAAM,IAAI,GAAG,OAAO,CACnB,EAAE,CAAC,OAAO,CACT;;UAEO,UAAU,qBAAqB,UAAU;4CACP,CACzC,EACD,EAAE,CACF,CAAA;IAED,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;IAE9E,OAAO,IAAI,CAAA;AACZ,CAAC;AAED,cAAc,oBAAoB,CAAA"}