@mailwoman/resolver-wof-sqlite 9.4.0 → 10.1.0

package/out/exact-match.js

@@ -3,16 +3,21 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The exact-match tier's name probes — the two case-folded equality lookups that decide whether a
+ *   The exact-match tier's name probes, the two case-folded equality lookups that decide whether a
  *   candidate holds the query text as its own name, an alias, or an official name.
  */
-import { aliasBagExactMatch, foldQueryText } from "#fts/index";
+import { aliasBagExactMatch, foldQueryText } from "#fts";
 /**
- * Among `ids`, return the subset whose name OR any alias equals `text` case-insensitively — the exact-match tier for
- * ranking. One indexed query over `<schema>.names`. When the extract has no `names` table (a slim DB built with
- * `dropNames`, or a postcode-only extract), fall back to the self-contained `place_search` FTS content: its `alt_names`
- * column is the same alias set joined on the boundary-preserving `ALIAS_SEPARATOR` (#523), so `aliasBagExactMatch`
- * recovers the exact alias tier ("New York City" → New York) that the dropped `names` table used to provide.
+ * Among `ids`, return the subset whose name or any alias equals `text` case-insensitively,
+ * the exact-match tier for ranking.
+ *
+ * One indexed query over `<schema>.names`.
+ * When the extract has no `names` table (a slim database built with `dropNames`, or a postcode-only extract),
+ * fall back to the self-contained `place_search` FTS content.
+ *
+ * Its `alt_names` column is the same alias set joined on the boundary-preserving
+ * `ALIAS_SEPARATOR`, so `aliasBagExactMatch` recovers the exact alias tier
+ * ("New York City" → New York) that the dropped `names` table used to provide.
  */
 export function exactMatchIDs(db, schemaName, ids, text) {
     const out = new Set();
@@ -30,7 +35,8 @@ export function exactMatchIDs(db, schemaName, ids, text) {
         return out;
     }
     catch {
-        // No `names` table on this extract — fall through to the place_search alias bag.
+        // No `names` table on this extract.
+        // Fall through to the place_search alias bag.
     }
     try {
         const rows = db
@@ -42,12 +48,12 @@ export function exactMatchIDs(db, schemaName, ids, text) {
                 out.add(r.id);
             }
         }
-        // Alias pass via the shared bag parser (#523). Separated bags (built since #523) get a true
-        // per-alias equality check, unrestricted — matching the `names`-table branch above, where an
-        // alias match counts as exact regardless of other candidates. Legacy bags (no separator)
-        // fall back to padded containment, conditioned on "no canonical exact in the pool" because their
-        // lost boundaries would otherwise false-promote interior fragments ("York" inside the alias
-        // "New York City") or cross-alias fragments ("York New" across "…York" + "New City…").
+        // Alias pass via the shared bag parser.
+        // Separated bags get a true per-alias equality check, unrestricted, matching the `names`-table
+        // branch above where an alias match counts as exact regardless of other candidates.
+        // Legacy bags without a separator fall back to padded containment, conditioned on "no
+        // canonical exact in the pool" because their lost boundaries would otherwise false-promote
+        // interior fragments ("York" inside the alias "New York City") or cross-alias fragments.
         const anyCanonicalExact = out.size > 0;
         for (const r of rows) {
             if (aliasBagExactMatch(r.alt_names, needle, anyCanonicalExact)) {
@@ -56,15 +62,20 @@ export function exactMatchIDs(db, schemaName, ids, text) {
         }
     }
     catch {
-        // Extract without place_search either → no exact-match tier. Falls back to weighted-sum order.
+        // Extract without place_search either, so there is no exact-match tier.
+        // The caller falls back to weighted-sum order.
     }
     return out;
 }
 /**
- * Among `ids` (already known exact matches), the subset holding `text` as an OFFICIAL name (`names.official = 1`, the
- * #940 ingest bit). Same COLLATE NOCASE semantics as {@link WOFSQLitePlaceLookup.#exactMatchIDs} so the two probes
- * agree on what "equals the query" means. Fails soft on gazetteers built before #940 (no `official` column) — the
- * sub-tier then behaves exactly as if `officialNameExact` were off.
+ * Among `ids` (already known exact matches), the subset holding `text` as an
+ * official name (`names.official = 1`, the ingest bit).
+ *
+ * Same collate nocase semantics as {@link WOFSQLitePlaceLookup.#exactMatchIDs},
+ * so the two probes agree on what "equals the query" means.
+ * Fails soft on gazetteers built before the `official` column existed.
+ *
+ * The sub-tier then behaves exactly as if `officialNameExact` were off.
  */
 export function officialNameIDs(db, schemaName, ids, text) {
     const out = new Set();
@@ -81,7 +92,7 @@ export function officialNameIDs(db, schemaName, ids, text) {
         }
     }
     catch {
-        // Pre-#940 gazetteer (no `official` column) or a names-less slim extract — feature inert.
+        // A gazetteer without the `official` column, or a names-less slim extract, leaves the feature inert.
     }
     return out;
 }

package/out/exact-match.js.map

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

package/out/extracts.d.ts

@@ -1,33 +1,29 @@
+import { type PathBuilderLike } from "path-ts";
 /**
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Multi-extract support for `WOFSQLitePlaceLookup` — opens multiple WOF SQLite distributions on one
- *   connection via `ATTACH DATABASE`, and routes queries to the right extract based on placetype.
+ *   Multi-extract support for `WOFSQLitePlaceLookup`. It opens multiple WOF SQLite distributions
+ *   on one connection with `attach database`. It routes queries by 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 `_EXTRACT_RULE.md` should it ever bite again.
- *
- *   The working form: schema-qualified in FROM, bare table name in MATCH:
+ *   SQLite parses a schema-qualified table on the left of `match` as "column place_search of table
+ *   pc", so the working form is schema-qualified in `from` and a bare table name in `match`:
  *
  *   ```sql
- *   SELECT … FROM pc.place_search WHERE place_search MATCH ?
+ *   select … from pc.place_search where place_search match ?
  * ```
  *
- *   Identical table names across attached extracts (which is what we have — every extract ships its own
- *   `place_search` + `place_bbox`) are fine because the bare-name MATCH resolves against FROM
- *   scope.
+ *   Identical table names across attached extracts are fine, because the bare-name `match` resolves
+ *   against `from` scope. Every extract ships its own `place_search` and `place_bbox`.
  */
 /**
- * Derive a SQL-safe schema name from a WOF distribution filename. Used by `ATTACH DATABASE … AS <name>` so each extract
- * gets a stable, predictable handle.
+ * Derive a SQL-safe schema name from a WOF distribution filename.
  *
- * Convention strips the `whosonfirst-data-` prefix and the `-latest.db` (or just `.db`) suffix, then replaces `-` with
- * `_` for SQL identifier safety.
+ * Used by `attach database … AS <name>` so each extract 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:
  *
@@ -36,32 +32,42 @@
  * - `whosonfirst-data-admin-latest.db` → `admin`
  * - `my-custom.db` → `my_custom`
  *
- * Callers can override the derived name explicitly via `ExtractConfig.schemaName` when the filename doesn't follow WOF
- * convention.
+ * Callers can override the derived name explicitly via `ExtractConfig.schemaName`
+ * when the filename doesn't follow WOF convention.
  */
-export declare function deriveSchemaName(path: string): string;
+export declare function deriveSchemaName(path: PathBuilderLike): string;
 /**
- * Per-extract 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.
+ * Per-extract 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 ExtractConfig {
-    path: string;
+    path: PathBuilderLike;
     /**
-     * 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_]*`.
+     * Override the auto-derived schema name.
+     *
+     * Useful when the filename does not match WOF convention or when you want a memorable handle.
+     * Must be a valid SQLite identifier matching `[a-zA-Z_][a-zA-Z0-9_]*`.
      */
     schemaName?: string;
     /**
-     * Optional explicit list of placetypes this extract serves. When set, queries against any listed placetype are routed
-     * to this extract. When omitted, routing falls back to a name-match heuristic: a extract whose `schemaName` contains
-     * the placetype as a substring (e.g. `postalcode_us` for `postalcode` queries) is preferred for that placetype.
+     * Optional explicit list of placetypes this extract serves.
+     *
+     * When set, queries against any listed placetype are routed to this extract.
+     * When omitted, routing falls back to a name-match heuristic: an extract 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.
+ * 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 ResolvedExtract {
     path: string;
@@ -69,41 +75,46 @@ export interface ResolvedExtract {
     placetypes: readonly string[];
 }
 /**
- * Normalize the user-provided `databasePath` opt (which may be a single string, an array of strings, or an array of
- * `ExtractConfig` objects) into a uniform `ResolvedExtract[]`.
+ * Normalize the user-provided `databasePath` opt (which may be a single string, an array
+ * of strings, or an array of `ExtractConfig` objects) into a uniform `ResolvedExtract[]`.
  *
- * The first extract becomes `main` regardless of its derived schema name — that's the SQLite convention. Subsequent
- * extracts keep their derived (or override) schema name.
+ * The first extract becomes `main` regardless of its derived schema name, following SQLite convention.
+ * Subsequent extracts keep their derived or overridden schema name.
  */
-export declare function resolveExtracts(input: string | ReadonlyArray<string | ExtractConfig>): ResolvedExtract[];
+export declare function resolveExtracts(input: PathBuilderLike | ReadonlyArray<PathBuilderLike | ExtractConfig>): ResolvedExtract[];
+/**
+ * All placetype-matching extracts, in routing order (the country-aware pick chooses among these).
+ *
+ * Used by the bias path: a country-less postcode query with proximity hints fans out across
+ * every matching extract and merges, because single-extract routing would hide the cross-country
+ * ambiguity the hints exist to resolve ("48026" lives in postalcode-us and postalcode-intl).
+ */
+export declare function pickExtractsForPlacetype(extracts: ResolvedExtract[], placetype: string | undefined): ResolvedExtract[];
 /**
  * Pick the extract to route a query to given the requested placetype(s).
  *
- * Routing rules, in order:
+ * The resolver applies these routing rules in order:
  *
  * 1. If any extract has explicit `placetypes` that includes the requested placetype, use it.
- * 2. Otherwise, if a non-main extract's `schemaName` matches the placetype (e.g. `postalcode_us` matches `postalcode`),
- *    use it.
+ * 2. Otherwise, if a non-main extract'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 extracts — BM25 scores aren't comparable across separately- indexed corpora,
- * and the typical mailwoman query has a single placetype anyway. If a caller needs cross-extract results they can issue
- * two `findPlace` calls.
- */
-/**
- * All placetype-matching extracts, in routing order (the country-aware pick chooses among these). Used by the bias
- * path: a country-less postcode query with proximity hints fans out across every matching extract and merges, because
- * single-extract routing would hide the cross-country ambiguity the hints exist to resolve ("48026" lives in
- * postalcode-us AND postalcode-intl).
+ * This deliberately does not union across extracts.
+ * BM25 scores are not comparable across separately indexed corpora.
+ * A typical mailwoman query has one placetype.
+ *
+ * Callers that need cross-extract results can issue two `findPlace` calls.
  */
-export declare function pickExtractsForPlacetype(extracts: ResolvedExtract[], placetype: string | undefined): ResolvedExtract[];
 export declare function pickExtractForPlacetype(extracts: ResolvedExtract[], placetype: string | undefined, opts?: {
     /**
-     * #920: the query's country constraint, when the caller has one. With MULTIPLE extracts matching a placetype
-     * (postalcode-us + postalcode-geonames-tail), first-match routing sent every postcode query to the first extract
-     * and starved the rest — a FI postcode could never reach the tail extract. When `country` is given and a matching
-     * extract's probed country set contains it, that extract wins; extracts without the country are skipped; the
-     * placetype-match order remains the tiebreak when no extract claims the country (or none was probed).
+     * The query's country constraint, when the caller has one.
+     *
+     * When `country` is given and a matching extract's probed country set contains it, that extract wins.
+     * Extracts without the country are skipped.
+     *
+     * The placetype-match order remains the tiebreak when no extract claims
+     * the country (or none was probed).
      */
     country?: string;
     /**

package/out/extracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extracts.d.ts","sourceRoot":"","sources":["../lib/extracts.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYrD;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAC7B;AAOD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,GAAG,aAAa,CAAC,GAAG,eAAe,EAAE,CA0CxG;AAED;;;;;;;;;;;;;GAaG;AACH;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACvC,QAAQ,EAAE,eAAe,EAAE,EAC3B,SAAS,EAAE,MAAM,GAAG,SAAS,GAC3B,eAAe,EAAE,CAuBnB;AAED,wBAAgB,uBAAuB,CACtC,QAAQ,EAAE,eAAe,EAAE,EAC3B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,IAAI,CAAC,EAAE;IACN;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,iBAAiB,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAA;CAC5D,GACC,eAAe,CAmCjB"}
+{"version":3,"file":"extracts.d.ts","sourceRoot":"","sources":["../lib/extracts.ts"],"names":[],"mappings":"AACA,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAErE;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAY9D;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,eAAe,CAAA;IACrB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAC7B;AAgBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC9B,KAAK,EAAE,eAAe,GAAG,aAAa,CAAC,eAAe,GAAG,aAAa,CAAC,GACrE,eAAe,EAAE,CA2CnB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACvC,QAAQ,EAAE,eAAe,EAAE,EAC3B,SAAS,EAAE,MAAM,GAAG,SAAS,GAC3B,eAAe,EAAE,CAuBnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACtC,QAAQ,EAAE,eAAe,EAAE,EAC3B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,IAAI,CAAC,EAAE;IACN;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,iBAAiB,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAA;CAC5D,GACC,eAAe,CAmCjB"}

package/out/extracts.js

@@ -1,34 +1,30 @@
-import { basename } from "path-ts";
+import { stringifyJSON } from "@mailwoman/core/json";
+import { basename, PathBuilder } from "path-ts";
 /**
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Multi-extract support for `WOFSQLitePlaceLookup` — opens multiple WOF SQLite distributions on one
- *   connection via `ATTACH DATABASE`, and routes queries to the right extract based on placetype.
+ *   Multi-extract support for `WOFSQLitePlaceLookup`. It opens multiple WOF SQLite distributions
+ *   on one connection with `attach database`. It routes queries by 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 `_EXTRACT_RULE.md` should it ever bite again.
- *
- *   The working form: schema-qualified in FROM, bare table name in MATCH:
+ *   SQLite parses a schema-qualified table on the left of `match` as "column place_search of table
+ *   pc", so the working form is schema-qualified in `from` and a bare table name in `match`:
  *
  *   ```sql
- *   SELECT … FROM pc.place_search WHERE place_search MATCH ?
+ *   select … from pc.place_search where place_search match ?
  * ```
  *
- *   Identical table names across attached extracts (which is what we have — every extract ships its own
- *   `place_search` + `place_bbox`) are fine because the bare-name MATCH resolves against FROM
- *   scope.
+ *   Identical table names across attached extracts are fine, because the bare-name `match` resolves
+ *   against `from` scope. Every extract ships its own `place_search` and `place_bbox`.
  */
 /**
- * Derive a SQL-safe schema name from a WOF distribution filename. Used by `ATTACH DATABASE … AS <name>` so each extract
- * gets a stable, predictable handle.
+ * Derive a SQL-safe schema name from a WOF distribution filename.
+ *
+ * Used by `attach database … AS <name>` so each extract 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.
+ * Convention strips the `whosonfirst-data-` prefix and the `-latest.db` (or just `.db`)
+ * suffix, then replaces `-` with `_` for SQL identifier safety.
  *
  * Examples:
  *
@@ -37,56 +33,65 @@ import { basename } from "path-ts";
  * - `whosonfirst-data-admin-latest.db` → `admin`
  * - `my-custom.db` → `my_custom`
  *
- * Callers can override the derived name explicitly via `ExtractConfig.schemaName` when the filename doesn't follow WOF
- * convention.
+ * Callers can override the derived name explicitly via `ExtractConfig.schemaName`
+ * when the filename doesn't follow WOF convention.
  */
 export function deriveSchemaName(path) {
-    const stem = basename(path)
+    const stem = basename(path.toString())
         .replace(/^whosonfirst-data-/u, "")
         .replace(/-latest\.db$/u, "")
         .replace(/\.db$/u, "")
         .replaceAll(/[^a-zA-Z0-9_]/g, "_");
     if (!stem) {
-        throw new Error(`deriveSchemaName: could not derive a SQL schema name from path ${JSON.stringify(path)}`);
+        throw new Error(`deriveSchemaName: could not derive a SQL schema name from path ${stringifyJSON(path)}`);
     }
     return stem;
 }
 /**
- * SQLite identifier regex — `[A-Za-z_][A-Za-z0-9_]*`.
+ * SQLite identifier regex matching `[A-Za-z_][A-Za-z0-9_]*`.
  */
 const SQLITE_IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/u;
 /**
- * Normalize the user-provided `databasePath` opt (which may be a single string, an array of strings, or an array of
- * `ExtractConfig` objects) into a uniform `ResolvedExtract[]`.
+ * Whether a `databasePath` entry is a path or an {@link ExtractConfig}.
+ *
+ * A builder is a `String` object, so `typeof` by itself reads it as an object.
+ */
+function isPathBuilderLike(value) {
+    return typeof value === "string" || value instanceof PathBuilder;
+}
+/**
+ * Normalize the user-provided `databasePath` opt (which may be a single string, an array
+ * of strings, or an array of `ExtractConfig` objects) into a uniform `ResolvedExtract[]`.
  *
- * The first extract becomes `main` regardless of its derived schema name — that's the SQLite convention. Subsequent
- * extracts keep their derived (or override) schema name.
+ * The first extract becomes `main` regardless of its derived schema name, following SQLite convention.
+ * Subsequent extracts keep their derived or overridden schema name.
  */
 export function resolveExtracts(input) {
-    const list = typeof input === "string" ? [input] : input;
+    const list = isPathBuilderLike(input) ? [input] : input;
     if (!list.length)
         throw new Error("resolveExtracts: at least one extract is required");
     const seen = new Set();
     const out = [];
     for (let i = 0; i < list.length; i++) {
         const entry = list[i];
-        const cfg = typeof entry === "string" ? { path: entry } : entry;
+        const cfg = isPathBuilderLike(entry) ? { path: entry } : entry;
         const derived = cfg.schemaName ?? deriveSchemaName(cfg.path);
         if (!SQLITE_IDENT_RE.test(derived)) {
-            throw new Error(`resolveExtracts: schema name ${JSON.stringify(derived)} is not a valid SQLite identifier ` +
-                `(derived from path ${JSON.stringify(cfg.path)}). Pass an explicit ` +
+            throw new Error(`resolveExtracts: schema name ${stringifyJSON(derived)} is not a valid SQLite identifier ` +
+                `(derived from path ${stringifyJSON(cfg.path)}). Pass an explicit ` +
                 `{ path, schemaName } to override.`);
         }
-        // The first extract is always main per SQLite semantics — its derived name is informational
-        // only. Subsequent extracts must have unique non-main names.
+        // SQLite always treats the first extract as main.
+        // Its derived name is informational only.
+        // Subsequent extracts must have unique non-main names.
         const schemaName = i === 0 ? "main" : derived;
         if (i > 0 && (schemaName === "main" || seen.has(schemaName))) {
-            throw new Error(`resolveExtracts: schema name ${JSON.stringify(schemaName)} collides ` +
+            throw new Error(`resolveExtracts: schema name ${stringifyJSON(schemaName)} collides ` +
                 `(either with "main" or another extract). Pass an explicit { path, schemaName }.`);
         }
         seen.add(schemaName);
         out.push({
-            path: cfg.path,
+            path: cfg.path.toString(),
             schemaName,
             placetypes: cfg.placetypes ?? [],
         });
@@ -94,24 +99,11 @@ export function resolveExtracts(input) {
     return out;
 }
 /**
- * Pick the extract to route a query to given the requested placetype(s).
- *
- * Routing rules, in order:
- *
- * 1. If any extract has explicit `placetypes` that includes the requested placetype, use it.
- * 2. Otherwise, if a non-main extract's `schemaName` matches the placetype (e.g. `postalcode_us` matches `postalcode`),
- *    use it.
- * 3. Otherwise, fall back to `main`.
+ * All placetype-matching extracts, in routing order (the country-aware pick chooses among these).
  *
- * This deliberately doesn't UNION across extracts — BM25 scores aren't comparable across separately- indexed corpora,
- * and the typical mailwoman query has a single placetype anyway. If a caller needs cross-extract results they can issue
- * two `findPlace` calls.
- */
-/**
- * All placetype-matching extracts, in routing order (the country-aware pick chooses among these). Used by the bias
- * path: a country-less postcode query with proximity hints fans out across every matching extract and merges, because
- * single-extract routing would hide the cross-country ambiguity the hints exist to resolve ("48026" lives in
- * postalcode-us AND postalcode-intl).
+ * Used by the bias path: a country-less postcode query with proximity hints fans out across
+ * every matching extract and merges, because single-extract routing would hide the cross-country
+ * ambiguity the hints exist to resolve ("48026" lives in postalcode-us and postalcode-intl).
  */
 export function pickExtractsForPlacetype(extracts, placetype) {
     if (!placetype)
@@ -133,6 +125,22 @@ export function pickExtractsForPlacetype(extracts, placetype) {
     }
     return matches.length ? matches : [extracts[0]];
 }
+/**
+ * Pick the extract to route a query to given the requested placetype(s).
+ *
+ * The resolver applies these routing rules in order:
+ *
+ * 1. If any extract has explicit `placetypes` that includes the requested placetype, use it.
+ * 2. Otherwise, if a non-main extract's `schemaName` matches the placetype
+ *    (e.g. `postalcode_us` matches `postalcode`), use it.
+ * 3. Otherwise, fall back to `main`.
+ *
+ * This deliberately does not union across extracts.
+ * BM25 scores are not comparable across separately indexed corpora.
+ * A typical mailwoman query has one placetype.
+ *
+ * Callers that need cross-extract results can issue two `findPlace` calls.
+ */
 export function pickExtractForPlacetype(extracts, placetype, opts) {
     if (!placetype)
         return extracts[0];
@@ -145,9 +153,9 @@ export function pickExtractForPlacetype(extracts, placetype, opts) {
     for (const s of extracts) {
         if (s.schemaName === "main" || matches.includes(s))
             continue;
-        // Substring match: `postalcode_us` matches `postalcode`. Conservative — requires the
-        // placetype to appear at a word boundary in the schema name to avoid false hits like
-        // `region` matching `arboregion`.
+        // A substring match lets `postalcode_us` match `postalcode`.
+        // Conservative, requiring the placetype at a word boundary in the schema name
+        // to avoid false hits like `region` matching `arboregion`.
         if (s.schemaName === placetype ||
             s.schemaName.startsWith(`${placetype}_`) ||
             s.schemaName.endsWith(`_${placetype}`)) {

package/out/extracts.js.map

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

package/out/fst/autocomplete.d.ts

@@ -3,18 +3,18 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   FST-based autocomplete — mailwoman vocabulary over `@mailwoman/ancestrie`'s generic algorithm
- *   (#1728 phase 2). The #587 behavior — prefix walk + BFS expansion, partial-last-token completion,
- *   per-branch capping, dedupe — lives in ancestrie's `autocomplete`; this module contributes only
- *   the storage adapter ({@link FSTMatcher} → `AncestrieReaderLike`) and the mapping back to
- *   mailwoman's suggestion shape (name, placetype, referential/encyclopedic, WOF ids).
+ *   FST-based autocomplete, mailwoman vocabulary over `@mailwoman/ancestrie`'s generic algorithm.
+ *   The prefix walk, BFS expansion, partial-last-token completion, per-branch capping and dedupe
+ *   live in ancestrie's `autocomplete`. This module contributes only the storage adapter
+ *   ({@link FSTMatcher} → `AncestrieReaderLike`) and the mapping back to mailwoman's suggestion
+ *   shape (name, placetype, referential and encyclopedic scores, WOF ids).
  *
- *   THE BYTES DO NOT MIGRATE. The shipped artifacts are `FST\0` v1–v5 (`fst-serialize.ts`), not
- *   ancestrie's `ANCT`: ancestrie entries are id-keyed with one record per id, while an FST place row
- *   is per-(surface, place) — `crossCountryBranches` is a property of the SURFACE, so the same wofID
- *   legitimately carries different values under different aliases and cannot be represented id-keyed.
- *   The matcher, both deserializers, and the serializer therefore stay here; what migrated is the
- *   ALGORITHM, which is the half that drifts (the #861 share-the-function rule).
+ *   The bytes do not migrate. The shipped artifacts are `FST\0` v1 to v5 (`fst-serialize.ts`), and
+ *   ancestrie's entries are id-keyed with one record per id. An FST place row is per-(surface,
+ *   place), because `crossCountryBranches` is a property of the surface, so the same wofID
+ *   legitimately has different values under different aliases, so it cannot use IDs as keys.
+ *   The matcher, both deserializers and serializer stay here. The algorithm is the
+ *   half that migrated.
  */
 import type { FSTMatcher } from "#fst/matcher";
 export interface AutocompleteResult {
@@ -27,14 +27,18 @@ export interface AutocompleteSuggestion {
     name: string;
     placetype: string;
     /**
-     * The REFERENTIAL likelihood the suggestion is ranked by (ROAD_TO_V9 §2). Autocomplete answers "which place does the
-     * user mean", so it ranks referentially like everything else; encyclopedic importance rides along on
-     * {@link AutocompleteSuggestion.encyclopedic} for display and never enters the order.
+     * The referential likelihood the suggestion is ranked by (ROAD_TO_V9 §2).
+     *
+     * Autocomplete answers "which place does the user mean", so it ranks referentially like everything else.
+     * Encyclopedic importance appears in {@link AutocompleteSuggestion.encyclopedic}
+     * for display and never enters the order.
      */
     referential: number;
     /**
-     * Encyclopedic (Wikipedia) importance, when the FST artifact carries one for this place. `undefined` = no article, or
-     * a pre-v5 binary — never 0.
+     * Encyclopedic (Wikipedia) importance, when the FST artifact stores one for this place.
+     *
+     * `undefined` means no article, or a pre-v5 binary.
+     * It is never 0.
      */
     encyclopedic?: number;
     wofID: number;
@@ -46,14 +50,18 @@ export interface AutocompleteOpts {
     maxSuggestions?: number;
     maxExpansionDepth?: number;
     /**
-     * Collapse same-name suggestions to the single highest-referential one. Off by default (the CLI surfaces distinct
-     * same-name places — New York the city vs the county); a typeahead wants it ON so the dropdown isn't four "New
-     * London"s. (#587)
+     * Collapse same-name suggestions to the single highest-referential one.
+     *
+     * Off by default, because the CLI surfaces distinct same-name places such as
+     * New York the city and New York the county.
+     * A typeahead wants it on so the dropdown does not show four "New London"s.
      */
     dedupeByName?: boolean;
 }
 /**
- * Autocomplete from the current prefix. Returns suggestions ranked referential-descending.
+ * Autocomplete from the current prefix.
+ *
+ * @returns Suggestions ranked referential-descending.
  */
 export declare function autocomplete(fst: FSTMatcher, query: string, opts?: AutocompleteOpts): AutocompleteResult;
 //# sourceMappingURL=autocomplete.d.ts.map

package/out/fst/autocomplete.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"autocomplete.d.ts","sourceRoot":"","sources":["../../lib/fst/autocomplete.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAWH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAI9C,MAAM,WAAW,kBAAkB;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,sBAAsB,EAAE,CAAA;CACrC;AAED,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,gBAAgB,EAAE,MAAM,EAAE,CAAA;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAChC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACtB;AAyED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,GAAG,kBAAkB,CA+B5G"}
+{"version":3,"file":"autocomplete.d.ts","sourceRoot":"","sources":["../../lib/fst/autocomplete.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAWH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAI9C,MAAM,WAAW,kBAAkB;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,sBAAsB,EAAE,CAAA;CACrC;AAED,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,gBAAgB,EAAE,MAAM,EAAE,CAAA;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAChC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACtB;AAkFD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,GAAG,kBAAkB,CA+B5G"}