@mailwoman/resolver-wof-sqlite 2.1.0

package/out/reverse.js

@@ -0,0 +1,290 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Reverse geocoding (#484): `(lat, lon)` → the containing admin hierarchy. Assembly over existing
+ *   machinery, per the 2026-06-11 scoping notes:
+ *
+ *   1. **Candidate fetch** — the admin DB's `place_bbox` R*Tree (built by `fts.ts`) for places whose
+ *        bbox contains the point, smallest-area-first (so the FIRST polygon confirmation is the
+ *        deepest).
+ *   2. **PIP confirmation** — ray-cast (geo.ts, the canonical TS port of
+ *        `scripts/eval/pip-containment.py`) against the polygon sidecar DB (`wof-polygons.db`,
+ *        `polygons(id, geom)` with GeoJSON text — built by `scripts/build-wof-polygons.mjs` for the
+ *        demo map). A candidate whose polygon EXISTS but rejects the point is a bbox false positive
+ *        and is dropped entirely; a candidate with no polygon row stays eligible for the
+ *        approximate fallback.
+ *   3. **Approximate descent** — WOF carries point geometry for most localities (#292: ~99% of JP
+ *        municipalities; ~half of US localities have degenerate bboxes too), so the polygon walk
+ *        usually bottoms out at county level. We then descend tier-by-tier (county → localadmin →
+ *        locality → …) through the winner's DESCENDANTS (the `ancestors` table, reversed), taking
+ *        the PIP-confirmed child when a polygon exists and the nearest-centroid child otherwise —
+ *        the latter flagged `containment: "approximate"`, the demo's honesty convention.
+ *   4. **Hierarchy assembly** — the deepest place's ancestor chain via the SAME walk forward resolution
+ *        uses (`ancestry.ts`, #404), so consumers get a symmetric tree.
+ *
+ *   Reverse quality is country-dependent (polygon coverage: see the #292 JP finding); `containment`
+ *   says so per result rather than pretending.
+ */
+import { DatabaseSync } from "node:sqlite";
+import { ancestorLineage, placetypeDepth } from "./ancestry.js";
+import { PLACE_BBOX_TABLE } from "./fts.js";
+import { geometryContains, haversineKm } from "./geo.js";
+const DEFAULT_MAX_CANDIDATES = 128;
+const DEFAULT_MAX_APPROXIMATE_KM = 25;
+/**
+ * The tier ladder for the approximate descent, coarsest-first. Each tier is attempted among the
+ * CURRENT winner's descendants; a tier with no rows is skipped (e.g. counties without localadmins
+ * jump straight to locality).
+ */
+const DESCENT_TIERS = [
+    "county",
+    "localadmin",
+    "locality",
+    "borough",
+    "neighbourhood",
+    "microhood",
+];
+function toPlaceCandidate(row, distanceKm) {
+    const c = {
+        id: row.id,
+        name: row.name,
+        placetype: row.placetype,
+        country: row.country ?? "",
+        lat: row.lat,
+        lon: row.lon,
+        parent_id: row.parent_id ?? undefined,
+        score: 0,
+    };
+    if (distanceKm !== undefined)
+        c.distanceKm = distanceKm;
+    return c;
+}
+export class WofReverseGeocoder {
+    #admin;
+    #ownsAdmin;
+    #polygons;
+    #ownsPolygons;
+    /**
+     * Parsed-geometry cache. Reverse queries cluster geographically (an eval run hits the same ~15
+     * county polygons 1400 times), so caching the JSON.parse pays for itself immediately. Bounded —
+     * cleared wholesale at the cap rather than LRU-tracked; the polygons are DP-simplified and small,
+     * the cap exists only to keep a long-lived server process honest.
+     */
+    #geometryCache = new Map();
+    static #GEOMETRY_CACHE_CAP = 4096;
+    constructor(opts) {
+        if (opts.adminDatabase && opts.adminDbPath) {
+            throw new Error("WofReverseGeocoder: pass either `adminDatabase` or `adminDbPath`, not both");
+        }
+        if (!opts.adminDatabase && !opts.adminDbPath) {
+            throw new Error("WofReverseGeocoder: one of `adminDatabase` or `adminDbPath` is required");
+        }
+        if (opts.polygonDatabase && opts.polygonDbPath) {
+            throw new Error("WofReverseGeocoder: pass either `polygonDatabase` or `polygonDbPath`, not both");
+        }
+        this.#admin = opts.adminDatabase ?? new DatabaseSync(opts.adminDbPath, { readOnly: true });
+        this.#ownsAdmin = !opts.adminDatabase;
+        this.#polygons =
+            opts.polygonDatabase ?? (opts.polygonDbPath ? new DatabaseSync(opts.polygonDbPath, { readOnly: true }) : null);
+        this.#ownsPolygons = !opts.polygonDatabase && Boolean(opts.polygonDbPath);
+        // Fail loudly up front — the R*Tree is a build artifact, not part of the upstream WOF
+        // distribution, and a missing index would otherwise surface as an opaque SQL error per query.
+        const hasBbox = this.#admin
+            .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+            .get(PLACE_BBOX_TABLE);
+        if (!hasBbox) {
+            throw new Error(`WofReverseGeocoder: the admin DB has no \`${PLACE_BBOX_TABLE}\` R*Tree. Build it with ` +
+                "`mailwoman-wof-build-fts <path-to-wof.db>` (see resolver-wof-sqlite/README.md).");
+        }
+        if (this.#polygons) {
+            const hasPolygons = this.#polygons
+                .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'polygons'`)
+                .get();
+            if (!hasPolygons) {
+                throw new Error("WofReverseGeocoder: the polygon DB has no `polygons` table. Expected a `wof-polygons.db` " +
+                    "built by scripts/build-wof-polygons.mjs.");
+            }
+        }
+    }
+    /**
+     * Resolve a WGS-84 point to its containing admin hierarchy. Async for symmetry with
+     * `PlaceLookup.findPlace` (the work is sync `node:sqlite` underneath — same convention).
+     */
+    async reverseGeocode(lat, lon, opts = {}) {
+        if (!Number.isFinite(lat) || !Number.isFinite(lon) || Math.abs(lat) > 90 || Math.abs(lon) > 180) {
+            throw new RangeError(`WofReverseGeocoder.reverseGeocode: (${lat}, ${lon}) is not a WGS-84 coordinate`);
+        }
+        const maxApproximateKm = opts.maxApproximateKm ?? DEFAULT_MAX_APPROXIMATE_KM;
+        const candidates = this.#bboxCandidates(lat, lon, opts);
+        // PIP walk, smallest-bbox-first: the first polygon that contains the point is the deepest
+        // polygon-confirmable place. Polygon-rejected candidates are bbox false positives — dropped.
+        let winner = null;
+        let winnerConfirmed = false;
+        const pointOnly = [];
+        for (const c of candidates) {
+            const contains = geometryContains(this.#geometry(c.id), lon, lat);
+            if (contains === true) {
+                winner = c;
+                winnerConfirmed = true;
+                break;
+            }
+            if (contains === null)
+                pointOnly.push(c);
+        }
+        if (!winner) {
+            // No polygon confirmed anywhere — nearest centroid among the polygon-less bbox candidates.
+            let bestKm = Infinity;
+            for (const c of pointOnly) {
+                const km = haversineKm(lat, lon, c.lat, c.lon);
+                if (km < bestKm) {
+                    bestKm = km;
+                    winner = c;
+                }
+            }
+            if (!winner)
+                return { hierarchy: [], containment: "approximate" };
+        }
+        // Approximate descent into finer tiers than the winner.
+        let current = winner;
+        let currentConfirmed = winnerConfirmed;
+        let currentDistanceKm = currentConfirmed ? undefined : haversineKm(lat, lon, current.lat, current.lon);
+        for (const tier of DESCENT_TIERS) {
+            if (placetypeDepth(tier) <= placetypeDepth(current.placetype))
+                continue;
+            if (opts.placetypes && !opts.placetypes.includes(tier))
+                continue;
+            const kids = this.#descendants(current.id, tier, lat, lon, maxApproximateKm);
+            let next = null;
+            let nextConfirmed = false;
+            let nextKm;
+            let bestKm = Infinity;
+            for (const k of kids) {
+                const contains = geometryContains(this.#geometry(k.id), lon, lat);
+                if (contains === true) {
+                    next = k;
+                    nextConfirmed = true;
+                    nextKm = undefined;
+                    break;
+                }
+                if (contains === false)
+                    continue; // known not-here — polygon rejected
+                const km = haversineKm(lat, lon, k.lat, k.lon);
+                if (km <= maxApproximateKm && km < bestKm) {
+                    bestKm = km;
+                    next = k;
+                    nextConfirmed = false;
+                    nextKm = km;
+                }
+            }
+            if (next) {
+                current = next;
+                currentConfirmed = nextConfirmed;
+                currentDistanceKm = nextKm;
+            }
+            // An empty tier is NOT terminal — counties without localadmins jump straight to locality.
+        }
+        // Hierarchy assembly via the shared ancestor walk. If the descent crossed an ancestry gap
+        // (the deepest place's recorded lineage misses the PIP root), merge the root's own chain so
+        // region/country are always present when a polygon confirmed them.
+        const byId = new Map();
+        byId.set(current.id, toPlaceCandidate(current, currentDistanceKm));
+        for (const a of ancestorLineage(this.#admin, current.id)) {
+            if (!byId.has(a.id)) {
+                byId.set(a.id, { ...a, placetype: a.placetype, country: a.country ?? "", score: 0 });
+            }
+        }
+        if (!byId.has(winner.id)) {
+            byId.set(winner.id, toPlaceCandidate(winner));
+            for (const a of ancestorLineage(this.#admin, winner.id)) {
+                if (!byId.has(a.id)) {
+                    byId.set(a.id, { ...a, placetype: a.placetype, country: a.country ?? "", score: 0 });
+                }
+            }
+        }
+        const hierarchy = [...byId.values()];
+        if (opts.placetypes) {
+            const allowed = new Set(opts.placetypes);
+            for (let i = hierarchy.length - 1; i >= 0; i--) {
+                if (!allowed.has(hierarchy[i].placetype))
+                    hierarchy.splice(i, 1);
+            }
+        }
+        hierarchy.sort((a, b) => placetypeDepth(b.placetype) - placetypeDepth(a.placetype));
+        return { hierarchy, containment: currentConfirmed ? "polygon" : "approximate" };
+    }
+    /** Bbox candidates containing the point, smallest-area-first, via the `place_bbox` R*Tree. */
+    #bboxCandidates(lat, lon, opts) {
+        const where = [
+            "bbox.min_lat <= ?",
+            "bbox.max_lat >= ?",
+            "bbox.min_lon <= ?",
+            "bbox.max_lon >= ?",
+            "spr.is_current != 0",
+            "spr.is_deprecated = 0",
+        ];
+        const params = [lat, lat, lon, lon];
+        if (opts.placetypes && opts.placetypes.length > 0) {
+            where.push(`spr.placetype IN (${opts.placetypes.map(() => "?").join(", ")})`);
+            params.push(...opts.placetypes);
+        }
+        params.push(opts.maxCandidates ?? DEFAULT_MAX_CANDIDATES);
+        return this.#admin
+            .prepare(`SELECT spr.id AS id, spr.name AS name, spr.placetype AS placetype, spr.country AS country,
+					spr.parent_id AS parent_id, spr.latitude AS lat, spr.longitude AS lon
+				FROM ${PLACE_BBOX_TABLE} bbox JOIN spr ON spr.id = bbox.id
+				WHERE ${where.join(" AND ")}
+				ORDER BY (bbox.max_lat - bbox.min_lat) * (bbox.max_lon - bbox.min_lon) ASC
+				LIMIT ?`)
+            .all(...params);
+    }
+    /**
+     * Descendants of `parentId` at one placetype tier, pre-filtered to a centroid window around the
+     * query point (a generous 4× the approximate cap — polygon-holding children may legitimately have
+     * far centroids, e.g. a sprawling consolidated city; the precise cap is applied per-candidate in
+     * the caller, and only to centroid-fallback steps).
+     */
+    #descendants(parentId, placetype, lat, lon, maxApproximateKm) {
+        const windowDeg = (maxApproximateKm * 4) / 111;
+        return this.#admin
+            .prepare(`SELECT s.id AS id, s.name AS name, s.placetype AS placetype, s.country AS country,
+					s.parent_id AS parent_id, s.latitude AS lat, s.longitude AS lon
+				FROM ancestors a JOIN spr s ON s.id = a.id
+				WHERE a.ancestor_id = ? AND s.placetype = ? AND s.is_current != 0 AND s.is_deprecated = 0
+					AND s.latitude BETWEEN ? AND ? AND s.longitude BETWEEN ? AND ?`)
+            .all(parentId, placetype, lat - windowDeg, lat + windowDeg, lon - windowDeg, lon + windowDeg);
+    }
+    /** Parsed GeoJSON geometry for a WOF id, or null when absent / unparseable / no polygon DB. */
+    #geometry(id) {
+        if (!this.#polygons)
+            return null;
+        const cached = this.#geometryCache.get(id);
+        if (cached !== undefined)
+            return cached;
+        if (this.#geometryCache.size >= WofReverseGeocoder.#GEOMETRY_CACHE_CAP)
+            this.#geometryCache.clear();
+        const row = this.#polygons.prepare(`SELECT geom FROM polygons WHERE id = ?`).get(id);
+        let geometry = null;
+        if (row) {
+            try {
+                geometry = JSON.parse(row.geom);
+            }
+            catch {
+                geometry = null; // malformed row — treat as no-polygon rather than failing the query
+            }
+        }
+        this.#geometryCache.set(id, geometry);
+        return geometry;
+    }
+    close() {
+        if (this.#ownsAdmin)
+            this.#admin.close();
+        if (this.#ownsPolygons)
+            this.#polygons?.close();
+    }
+    [Symbol.dispose]() {
+        this.close();
+    }
+}
+//# sourceMappingURL=reverse.js.map

package/out/reverse.js.map

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

package/out/schema.d.ts

@@ -0,0 +1,163 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Kysely table types for the subset of the Who's On First SQLite schema we touch in Phase 4.2.
+ *
+ *   The full upstream distribution at data.geocode.earth/wof/dist/sqlite/ ships ~7 tables; this file
+ *   models only the ones we read. Pretending to model the others would be misleading — we haven't
+ *   verified their shapes and they're not part of the resolver's contract.
+ *
+ *   Authoritative schema docs:
+ *
+ *   - Whosonfirst SQLite README: https://github.com/whosonfirst/go-whosonfirst-sqlite
+ *   - Per-table sources under https://github.com/whosonfirst/go-whosonfirst-sqlite-features
+ */
+/**
+ * The FTS5 virtual table built by this package on first open (NOT shipped by upstream WOF).
+ *
+ * `content` is unindexed — it's there so we can roundtrip the original name back to the caller
+ * without a second SELECT. The actual FTS rebuild happens in `fts.ts::buildPlaceSearchFts`.
+ */
+export interface PlaceSearchTable {
+    rowid: number;
+    wof_id: number;
+    name: string;
+    alt_names: string | null;
+}
+/**
+ * `spr` — the Who's On First "Standard Places Response": a denormalized lightweight summary of one
+ * row per place. The resolver's main lookup table.
+ *
+ * Lifecycle flags carry TWO conventions, both meaning "currently valid": `is_current = -1` (modern
+ * Who's On First) and `is_current = 1` (legacy Mapzen-era). Only `is_current = 0` means "not
+ * current". Filters in `lookup.ts` and `fts.ts` use `is_current != 0 AND is_deprecated = 0` — see
+ * #91 for the diagnostic that uncovered the mixed-convention reality.
+ *
+ * Lat/lon live directly on this row — no GeoJSON extraction needed for centroid resolution. `min_*`
+ * / `max_*` form a bounding box if callers want one (Phase 4.3 candidate).
+ */
+export interface SprTable {
+    id: number;
+    parent_id: number | null;
+    name: string | null;
+    placetype: string | null;
+    country: string | null;
+    latitude: number;
+    longitude: number;
+    min_latitude: number;
+    min_longitude: number;
+    max_latitude: number;
+    max_longitude: number;
+    is_current: number;
+    is_deprecated: number;
+    is_ceased: number;
+    is_superseded: number;
+    is_superseding: number;
+    superseded_by: string | null;
+    supersedes: string | null;
+    lastmodified: number;
+}
+/**
+ * Alternate names per place, keyed by language tag subfields (BCP-47 components). Joins back to
+ * `spr.id` via `id` (NOT `place_id` — the real WOF schema uses the same column name as the spr
+ * primary key; this is a normal join across two tables with the same FK column name).
+ *
+ * No `kind` column in real WOF — the FTS build just concatenates ALL names per id.
+ */
+export interface NamesTable {
+    id: number;
+    placetype: string | null;
+    country: string | null;
+    language: string | null;
+    extlang: string | null;
+    script: string | null;
+    region: string | null;
+    variant: string | null;
+    extension: string | null;
+    privateuse: string | null;
+    name: string;
+    lastmodified: number;
+}
+/**
+ * Per-place GeoJSON blob. Centroid lat/lon are already exposed via `spr.{latitude,longitude}` so
+ * the resolver doesn't need to parse this; we keep the table modeled in case Phase 4.3 wants the
+ * full geometry for bbox / polygon work.
+ */
+export interface GeojsonTable {
+    id: number;
+    body: string;
+    source: string | null;
+    alt_label: string | null;
+    is_alt: number;
+    lastmodified: number;
+}
+/**
+ * Adjacency table for ancestor relationships. One row per (place, ancestor) pair, including
+ * transitive ancestors. Used to implement `FindPlaceQuery.parentId` (descendant lookup).
+ */
+export interface AncestorsTable {
+    id: number;
+    ancestor_id: number;
+    ancestor_placetype: string | null;
+    lastmodified: number;
+}
+/**
+ * `place_population` — `id → wof:population`, split off `spr` so a population-rank join is a single
+ * indexed probe. Written by the build/augment ingest + the GeoNames backfill; read by the candidate
+ * build's `neg_rank`. WOF carries population for ~15% of localities; absent = unknown, not zero.
+ */
+export interface PlacePopulationTable {
+    id: number;
+    population: number;
+}
+/**
+ * `place_abbr` — `id → abbreviation` (e.g. `IL → Illinois`), derived from `names` rows whose
+ * `language = 'abbr'`. Lets the resolver accept a 2-letter region abbreviation as an exact match.
+ */
+export interface PlaceAbbrTable {
+    id: number;
+    abbr: string;
+}
+/**
+ * `concordances` — external-id cross-references per place (`id → (other_source, other_id)`), e.g. a
+ * GeoNames or Overture GERS id. Metadata only; not part of the resolve path.
+ */
+export interface ConcordancesTable {
+    id: number;
+    other_id: string;
+    other_source: string;
+    lastmodified: number;
+}
+/**
+ * `coincident_roles` (#402) — the dual-role relation: a place that is BOTH an admin region AND a
+ * locality (Berlin the city-state). One row per (admin, locality) pair the resolver can complete a
+ * hierarchy with. Surfaced by {@link MailwomanLookupLike.coincidentRolesFor}.
+ */
+export interface CoincidentRolesTable {
+    admin_id: number;
+    locality_id: number;
+    relationship_type: string;
+    admin_placetype: string;
+    distance_km: number;
+    locality_population: number;
+}
+/**
+ * The full schema we hand to `Kysely<WofDatabase>` / `new DatabaseClient<WofDatabase>(...)`. Tables
+ * not listed here will fail type-checked queries — by design. The reader
+ * ({@link WofSqlitePlaceLookup}) already consumes this; the build/augment WRITERS adopt it so a
+ * column rename is a compile error on both sides (the drift that bit the corpus TIGER adapter).
+ */
+export interface WofDatabase {
+    place_search: PlaceSearchTable;
+    spr: SprTable;
+    names: NamesTable;
+    geojson: GeojsonTable;
+    ancestors: AncestorsTable;
+    place_population: PlacePopulationTable;
+    place_abbr: PlaceAbbrTable;
+    concordances: ConcordancesTable;
+    coincident_roles: CoincidentRolesTable;
+}
+//# sourceMappingURL=schema.d.ts.map

package/out/schema.d.ts.map

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

package/out/schema.js

@@ -0,0 +1,18 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Kysely table types for the subset of the Who's On First SQLite schema we touch in Phase 4.2.
+ *
+ *   The full upstream distribution at data.geocode.earth/wof/dist/sqlite/ ships ~7 tables; this file
+ *   models only the ones we read. Pretending to model the others would be misleading — we haven't
+ *   verified their shapes and they're not part of the resolver's contract.
+ *
+ *   Authoritative schema docs:
+ *
+ *   - Whosonfirst SQLite README: https://github.com/whosonfirst/go-whosonfirst-sqlite
+ *   - Per-table sources under https://github.com/whosonfirst/go-whosonfirst-sqlite-features
+ */
+export {};
+//# sourceMappingURL=schema.js.map

package/out/schema.js.map

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

package/out/sharding.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Multi-shard support for `WofSqlitePlaceLookup` — opens multiple WOF SQLite distributions on one
+ *   connection via `ATTACH DATABASE`, and routes queries to the right shard based on placetype.
+ *
+ *   ## The FTS5 syntax rule that drove this design
+ *
+ *   The naive `SELECT … FROM pc.place_search WHERE pc.place_search MATCH ?` fails — SQLite parses the
+ *   schema-qualified table on the left of MATCH as "column place_search of table pc". Discovered in
+ *   the spike at PR review time; documented as `_SHARD_RULE.md` should it ever bite again.
+ *
+ *   The working form: schema-qualified in FROM, bare table name in MATCH:
+ *
+ *   ```sql
+ *   SELECT … FROM pc.place_search WHERE place_search MATCH ?
+ * ```
+ *
+ *   Identical table names across attached shards (which is what we have — every shard ships its own
+ *   `place_search` + `place_bbox`) are fine because the bare-name MATCH resolves against FROM
+ *   scope.
+ */
+/**
+ * Derive a SQL-safe schema name from a WOF distribution filename. Used by `ATTACH DATABASE … AS
+ * <name>` so each shard gets a stable, predictable handle.
+ *
+ * Convention strips the `whosonfirst-data-` prefix and the `-latest.db` (or just `.db`) suffix,
+ * then replaces `-` with `_` for SQL identifier safety.
+ *
+ * Examples:
+ *
+ * - `whosonfirst-data-admin-us-latest.db` → `admin_us`
+ * - `whosonfirst-data-postalcode-us-latest.db` → `postalcode_us`
+ * - `whosonfirst-data-admin-latest.db` → `admin`
+ * - `my-custom.db` → `my_custom`
+ *
+ * Callers can override the derived name explicitly via `ShardConfig.schemaName` when the filename
+ * doesn't follow WOF convention.
+ */
+export declare function deriveSchemaName(path: string): string;
+/**
+ * Per-shard configuration. The simple form is just a path string — the schema name is derived from
+ * it. The object form lets callers override the derived schema name (useful when a filename doesn't
+ * follow WOF convention) or attach an extra hint about which placetypes route here.
+ */
+export interface ShardConfig {
+    path: string;
+    /**
+     * Override the auto-derived schema name. Useful when the filename doesn't match WOF convention or
+     * when you want a memorable handle. Must be a valid SQLite identifier —
+     * `[a-zA-Z_][a-zA-Z0-9_]*`.
+     */
+    schemaName?: string;
+    /**
+     * Optional explicit list of placetypes this shard serves. When set, queries against any listed
+     * placetype are routed to this shard. When omitted, routing falls back to a name-match heuristic:
+     * a shard whose `schemaName` contains the placetype as a substring (e.g. `postalcode_us` for
+     * `postalcode` queries) is preferred for that placetype.
+     */
+    placetypes?: readonly string[];
+}
+/**
+ * Resolved post-derivation: paired path + chosen schema name + (possibly empty) placetypes hint.
+ * Used internally by `WofSqlitePlaceLookup` so the routing logic operates on uniform structures.
+ */
+export interface ResolvedShard {
+    path: string;
+    schemaName: string;
+    placetypes: readonly string[];
+}
+/**
+ * Normalize the user-provided `databasePath` opt (which may be a single string, an array of
+ * strings, or an array of `ShardConfig` objects) into a uniform `ResolvedShard[]`.
+ *
+ * The first shard becomes `main` regardless of its derived schema name — that's the SQLite
+ * convention. Subsequent shards keep their derived (or override) schema name.
+ */
+export declare function resolveShards(input: string | ReadonlyArray<string | ShardConfig>): ResolvedShard[];
+/**
+ * Pick the shard to route a query to given the requested placetype(s).
+ *
+ * Routing rules, in order:
+ *
+ * 1. If any shard has explicit `placetypes` that includes the requested placetype, use it.
+ * 2. Otherwise, if a non-main shard's `schemaName` matches the placetype (e.g. `postalcode_us` matches
+ *    `postalcode`), use it.
+ * 3. Otherwise, fall back to `main`.
+ *
+ * This deliberately doesn't UNION across shards — BM25 scores aren't comparable across separately-
+ * indexed corpora, and the typical mailwoman query has a single placetype anyway. If a caller needs
+ * cross-shard results they can issue two `findPlace` calls.
+ */
+export declare function pickShardForPlacetype(shards: ResolvedShard[], placetype: string | undefined): ResolvedShard;
+//# sourceMappingURL=sharding.d.ts.map

package/out/sharding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharding.d.ts","sourceRoot":"","sources":["../sharding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUrD;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAC7B;AAKD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,GAAG,WAAW,CAAC,GAAG,aAAa,EAAE,CAkClG;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAmB3G"}