@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/out/schema.d.ts

@@ -3,21 +3,23 @@
  * @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.
+ *   Kysely table types for the subset of the Who's On First SQLite schema this package touches.
  *
- *   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.
+ *   The full upstream distribution at data.geocode.earth/wof/dist/sqlite/ ships about seven tables.
+ *   This file models only the tables we read. The others are outside the resolver interface. Their shapes remain unverified.
  *
  *   Authoritative schema docs:
  *
- *   - Whosonfirst SQLite README: https://github.com/whosonfirst/go-whosonfirst-sqlite
+ *   - Whosonfirst SQLite readme: https://github.com/whosonfirst/go-whosonfirst-sqlite
  *   - Per-table sources under https://github.com/whosonfirst/go-whosonfirst-sqlite-features
  */
+import type { KeyValueMetaTable } from "@mailwoman/sqlite/database-schema";
 /**
- * The FTS5 virtual table built by this package on first open (NOT shipped by upstream WOF).
+ * The FTS5 virtual table this package builds on first open.
+ * It is local to this repository.
  *
- * `content` is unindexed — it's there so we can roundtrip the original name back to the caller without a second SELECT.
+ * `content` is unindexed and is 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 {
@@ -27,16 +29,19 @@ export interface PlaceSearchTable {
     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.
+ * `spr`, the Who's On First "Standard Places Response": a denormalized lightweight
+ * summary of one row per place.
  *
- * 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.
+ * The resolver's main lookup table.
  *
- * 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).
+ * Lifecycle flags use two conventions, both meaning "currently valid": `is_current = -1`
+ * for modern Who's On First and `is_current = 1` for the 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`.
+ *
+ * Lat/lon live directly on this row, so centroid resolution needs no GeoJSON extraction.
+ * `min_*` and `max_*` form a bounding box if callers want one.
  */
 export interface SprTable {
     id: number;
@@ -60,15 +65,21 @@ export interface SprTable {
     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).
+ * Alternate names per place, keyed by language tag subfields (BCP-47 components).
+ *
+ * Joins back to `spr.id` via `id`.
+ * The real WOF schema uses the same column name as the spr primary key, so 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.
+ * No `kind` column in real WOF.
+ * The FTS build concatenates all names per id.
  *
- * `official` (#936 ingest bit, our unified builds only; absent in real WOF dumps) marks a PREFERRED-form name in an
- * official language of the place's country — the aliases eligible to join the name-exact tier under the option-3 rule.
- * See `unified-schema.ts` for the full contract.
+ * `official` marks a preferred-form name in an official language of the place's country.
+ * This column appears only in unified builds.
+ *
+ * Real WOF dumps omit it.
+ * These are the aliases eligible to join the name-exact tier.
+ * See `unified-schema.ts` for the full interface.
  */
 export interface NamesTable {
     id: number;
@@ -86,8 +97,11 @@ export interface NamesTable {
     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.
+ * Per-place GeoJSON blob.
+ *
+ * Centroid lat/lon are already exposed via `spr.{latitude,longitude}`,
+ * so the resolver does not need to parse this.
+ * The table stays modeled so a caller that wants the full geometry for bbox or polygon work can read it.
  */
 export interface GeojsonTable {
     id: number;
@@ -98,8 +112,10 @@ export interface GeojsonTable {
     lastmodified: number;
 }
 /**
- * Adjacency table for ancestor relationships. One row per (place, ancestor) pair, including transitive ancestors. Used
- * to implement `FindPlaceQuery.parentID` (descendant lookup).
+ * 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;
@@ -108,25 +124,35 @@ export interface AncestorsTable {
     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.
+ * `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 records population for ~15% of localities.
+ * Absent = unknown rather than 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.
+ * `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.
+ * `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;
@@ -135,9 +161,12 @@ export interface ConcordancesTable {
     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}.
+ * `coincident_roles`.
+ *
+ * The dual-role relation, where a place 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;
@@ -148,21 +177,15 @@ export interface CoincidentRolesTable {
     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).
- */
-/**
- * The provenance row every built extract carries: source fingerprints travelling WITH the database rather than in a
- * document that can drift from it. Written by the postcode builders in `mailwoman/gazetteer-pipeline`.
+ * 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 and augment writers adopt it so a column rename is a compile error on both sides.
  */
-export interface ExtractMetaTable {
-    key: string;
-    value: string | null;
-}
 export interface WOFDatabase {
-    meta: ExtractMetaTable;
+    meta: KeyValueMetaTable;
     place_search: PlaceSearchTable;
     spr: SprTable;
     names: NamesTable;

package/out/schema.d.ts.map

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

package/out/schema.js

@@ -3,15 +3,14 @@
  * @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.
+ *   Kysely table types for the subset of the Who's On First SQLite schema this package touches.
  *
- *   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.
+ *   The full upstream distribution at data.geocode.earth/wof/dist/sqlite/ ships about seven tables.
+ *   This file models only the tables we read. The others are outside the resolver interface. Their shapes remain unverified.
  *
  *   Authoritative schema docs:
  *
- *   - Whosonfirst SQLite README: https://github.com/whosonfirst/go-whosonfirst-sqlite
+ *   - Whosonfirst SQLite readme: https://github.com/whosonfirst/go-whosonfirst-sqlite
  *   - Per-table sources under https://github.com/whosonfirst/go-whosonfirst-sqlite-features
  */
 export {};

package/out/schema.js.map

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

package/out/search-fetch.d.ts

@@ -3,13 +3,13 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The FTS5 candidate fetch behind the fuzzy name match: the schema-qualified `place_search`
- *   MATCH, its population-ordered companion fetch, and the raw row shape both of them return.
+ *   Fetches FTS5 candidates for fuzzy name matching. It runs the schema-qualified `place_search` match and its
+ *   population-ordered companion query. Both queries return the raw row shape defined here.
  *
  *   Bbox and near-with-radius narrow at the SQL level through SQLite's built-in `rtree`, whose index name and schema
- *   live in `fts.ts` beside the FTS5 build. That is why this package pulls neither SpatiaLite nor turf: the R*Tree does
- *   the narrowing, and the passes downstream of it operate on ≤ a few hundred candidates per query rather than the
- *   whole corpus, so an exact haversine over the survivors is cheap.
+ *   are defined in `fts.ts` beside the FTS5 build. This package uses SQLite's R*Tree instead of SpatiaLite or turf.
+ *   The R*Tree narrows the search to at most a few hundred candidates per query. Downstream passes work on that set
+ *   instead of the whole corpus, so exact haversine calculations remain cheap.
  */
 import type { DatabaseClient } from "@mailwoman/sqlite/client";
 import type { RankingWeights } from "#ranking-weights";
@@ -29,17 +29,21 @@ export interface RawSearchRow {
     max_longitude: number | null;
     population: number | null;
     /**
-     * From `place_importance.encyclopedic` when the extract's table carries the two-score split columns. NULL means the
-     * place has no Wikipedia article, or the extract predates the split — absence either way, and never 0 (ROAD_TO_V9
-     * §2).
+     * From `place_importance.encyclopedic` when the extract's table includes the two-score split columns.
+     *
+     * NULL means the place has no Wikipedia article, or the extract predates the split.
+     * Either case records an absence.
+     * The value remains null rather than 0 (ROAD_TO_V9 §2).
      */
     encyclopedic: number | null;
 }
 /**
- * Fetch the raw candidate rows for a name match on one extract: the BM25-ordered window over `place_search` (widened
- * for short queries), plus the population-ordered companion fetch that keeps the prominent holders of a name
- * pool-complete. `schemaName` is the routed extract's bare schema name — validated at construction, so it is
- * interpolated directly.
+ * Fetch the raw candidate rows for a name match on one extract: the BM25-ordered
+ * window over `place_search` (widened for short queries), plus the population-ordered
+ * companion fetch that keeps the prominent holders of a name pool-complete.
+ *
+ * `schemaName` is the routed extract's bare schema name, validated at construction,
+ * so it is interpolated directly.
  */
 export declare function fetchSearchRows<DB>(options: {
     db: DatabaseClient<DB>;

package/out/search-fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search-fetch.d.ts","sourceRoot":"","sources":["../lib/search-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,0BAA0B,CAAA;AAG7E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AAyB1D,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB;;;;OAIG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,OAAO,EAAE;IAC5C,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,cAAc,CAAA;IACrB,UAAU,EAAE,YAAY,EAAE,GAAG,IAAI,CAAA;IACjC,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC1C,kBAAkB,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAChD,mBAAmB,EAAE,WAAW,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC1E,OAAO,EAAE,cAAc,CAAA;CACvB,GAAG,YAAY,EAAE,CA2KjB"}
+{"version":3,"file":"search-fetch.d.ts","sourceRoot":"","sources":["../lib/search-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,0BAA0B,CAAA;AAG7E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AAkC1D,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB;;;;;;OAMG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,OAAO,EAAE;IAC5C,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,cAAc,CAAA;IACrB,UAAU,EAAE,YAAY,EAAE,GAAG,IAAI,CAAA;IACjC,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC1C,kBAAkB,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAChD,mBAAmB,EAAE,WAAW,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC1E,OAAO,EAAE,cAAc,CAAA;CACvB,GAAG,YAAY,EAAE,CAoLjB"}

package/out/search-fetch.js

@@ -3,61 +3,75 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The FTS5 candidate fetch behind the fuzzy name match: the schema-qualified `place_search`
- *   MATCH, its population-ordered companion fetch, and the raw row shape both of them return.
+ *   Fetches FTS5 candidates for fuzzy name matching. It runs the schema-qualified `place_search` match and its
+ *   population-ordered companion query. Both queries return the raw row shape defined here.
  *
  *   Bbox and near-with-radius narrow at the SQL level through SQLite's built-in `rtree`, whose index name and schema
- *   live in `fts.ts` beside the FTS5 build. That is why this package pulls neither SpatiaLite nor turf: the R*Tree does
- *   the narrowing, and the passes downstream of it operate on ≤ a few hundred candidates per query rather than the
- *   whole corpus, so an exact haversine over the survivors is cheap.
+ *   are defined in `fts.ts` beside the FTS5 build. This package uses SQLite's R*Tree instead of SpatiaLite or turf.
+ *   The R*Tree narrows the search to at most a few hundred candidates per query. Downstream passes work on that set
+ *   instead of the whole corpus, so exact haversine calculations remain cheap.
  */
 import { allRows } from "@mailwoman/core/utils";
 import { bboxAround } from "@mailwoman/spatial";
-import { PLACE_BBOX_TABLE, PLACE_POPULATION_TABLE } from "#fts/index";
+import { PLACE_BBOX_TABLE, PLACE_POPULATION_TABLE } from "#fts";
 /**
- * Query length at or below which the FTS window is widened. A two- or three-character query is almost always a region
- * abbreviation, where the exact match can otherwise fall outside the window behind higher-bm25 partial hits — "NY"
- * losing to "New York".
+ * Query length at or below which the FTS window is widened.
+ *
+ * A two- or three-character query is almost always a region abbreviation, where the exact match
+ * can otherwise fall outside the window behind higher-bm25 partial hits, as "NY" losing to "New York".
  */
 const SHORT_QUERY_MAX_LENGTH = 3;
 /**
- * Over-fetch floor for SHORT (≤3-char) queries — region abbreviations like "NY"/"VT". An exact-abbrev holder's BM25 is
- * poor (long multilingual alt-name document), so the normal `limit * 4` window can drop it before `exactMatchTiering`
- * promotes it. 200 comfortably covers every same-abbrev region across the 12-country gazetteer (a 2-letter token
- * matches a few dozen regions at most) while staying a cheap region-placetype fetch. See the `#fuzzyNameMatch`
- * over-fetch comment.
+ * Over-fetch floor for short (≤3-character) queries.
+ *
+ * These queries are usually region abbreviations such as "NY" or "VT".
+ *
+ * An exact-abbrev holder's BM25 is poor (long multilingual alt-name document),
+ * so the normal `limit * 4` window can drop it before `exactMatchTiering` promotes
+ * it. 200 comfortably covers every same-abbrev region across the 12-country gazetteer
+ * (a 2-letter token matches a few dozen regions at most) while staying a cheap region-placetype fetch.
+ * See the `#fuzzyNameMatch` over-fetch comment.
  */
 const SHORT_QUERY_OVERFETCH = 200;
 /**
- * How many rows the population-ordered companion fetch (#905) adds to the candidate pool. Small on purpose: its only
- * job is to guarantee the FAMOUS holders of a name enter the pool at all — for "Paris"-class floods the bm25 window is
- * saturated by thousands of tiny same-name rows and no boost inside the bm25-based ORDER BY can rescue a candidate
- * whose bm25 is length-poisoned by ~15 points (see the fetch-site comment).
+ * How many rows the population-ordered companion fetch adds to the candidate pool.
+ *
+ * Small on purpose.
+ * Its only job is to guarantee the famous holders of a name enter the pool at all.
+ *
+ * For "Paris"-class floods, thousands of small same-name rows fill the BM25 window.
+ * A boost inside the BM25-based ORDER BY cannot rescue a candidate whose score is
+ * length-poisoned by about 15 points (see the fetch-site comment).
  */
 const POPULATION_FETCH_LIMIT = 15;
 /**
- * Fetch the raw candidate rows for a name match on one extract: the BM25-ordered window over `place_search` (widened
- * for short queries), plus the population-ordered companion fetch that keeps the prominent holders of a name
- * pool-complete. `schemaName` is the routed extract's bare schema name — validated at construction, so it is
- * interpolated directly.
+ * Fetch the raw candidate rows for a name match on one extract: the BM25-ordered
+ * window over `place_search` (widened for short queries), plus the population-ordered
+ * companion fetch that keeps the prominent holders of a name pool-complete.
+ *
+ * `schemaName` is the routed extract's bare schema name, validated at construction,
+ * so it is interpolated directly.
  */
 export function fetchSearchRows(options) {
     const { db, schemaName: sch, query, placetypes, ftsQuery, limit, hasBboxIndex, hasPopulationIndex, encyclopedicClauses, weights, } = options;
-    // Over-fetch so post-scoring + exact-match tiering have room to re-rank. SHORT queries (a 2–3-char
-    // region abbreviation like "NY"/"VT") are the danger case the `exactMatchTiering` docstring flags:
-    // the exact-abbrev holder's BM25 is poor (its long multilingual alt-name document tanks the score),
-    // so under the normal `limit * 4` window it drops OUT of the candidate pool BEFORE tiering can
-    // promote it — "NY" then resolves to a token-matching foreign region (Highland, GB) instead of New
-    // York. Widen the window for short queries so the exact match is always present to be tiered.
-    // (Cross-country abbrev collisions — "VT" is BOTH Vermont and Viterbo — still need a country/
-    // postcode signal to disambiguate; this only rescues the window-drop class, not genuine ambiguity.
-    // With a `country` hint every abbrev resolves; bare + no-context lifts 7→10/15 US states.)
+    // Over-fetch so post-scoring and exact-match tiering have room to re-rank.
+    // Short queries (a 2-3-char region abbreviation like "NY" or "VT") are the danger
+    // case the `exactMatchTiering` docstring flags.
+    // The exact-abbrev holder's BM25 is poor, so under the normal `limit * 4` window it
+    // drops out of the candidate pool before tiering can promote it.
+    // A wider window for short queries keeps the exact match available for tiering.
+    // Cross-country abbrev collisions ("VT" is both Vermont and Viterbo) still need a country
+    // or postcode signal to disambiguate, so this only rescues the window-drop class.
     const ftsLimit = query.text.trim().length <= SHORT_QUERY_MAX_LENGTH ? Math.max(limit * 4, SHORT_QUERY_OVERFETCH) : limit * 4;
-    // Filter out historical / superseded / deprecated places by default — they live in the same
-    // spr table but should never win a contemporary lookup. `is_current = 0` is the only WOF
-    // value that means "not current"; both `-1` (modern) and `1` (legacy) mean current. See #91.
-    // Note: with schema-qualified FROM the bare `place_search` reference in MATCH resolves to
-    // the FROM table — required by FTS5 parser, see extracts.ts header comment.
+    // Filter out historical, superseded and deprecated places by default.
+    // They live in the same spr table but should never win a contemporary lookup.
+    // `is_current = 0` is the only WOF value that means "not current", while both
+    // `-1` (modern) and `1` (legacy) mean current.
+    //
+    // The schema-qualified `from` makes the bare `place_search` reference in
+    // `match` resolve to the from table.
+    // The FTS5 parser requires that resolution.
+    // See the extracts.ts header comment.
     const where = ["place_search MATCH ?", "spr.is_current != 0", "spr.is_deprecated = 0"];
     const params = [ftsQuery];
     if (placetypes && placetypes.length) {
@@ -72,21 +86,25 @@ export function fetchSearchRows(options) {
         where.push(`(spr.parent_id = ? OR spr.id IN (SELECT id FROM ${sch}.ancestors WHERE ancestor_id = ?))`);
         params.push(query.parentID, query.parentID);
     }
-    // Bbox + near-with-radius are SQL-level filters via the R*Tree. We only emit the JOIN when
-    // the active extract has the R*Tree; missing-but-requested is silently treated as no-bbox-
-    // filter so legacy DBs / extracts-without-bbox don't crash.
+    // Bbox and near-with-radius are SQL-level filters via the R*Tree.
+    // The join is emitted only when the active extract has the R*Tree.
+    // A requested filter on a legacy extract is silently treated as no bbox filter
+    // so the query does not crash.
     const extractHasBbox = hasBboxIndex.get(sch) === true;
     const useBboxJoin = (query.bbox || query.near?.maxDistanceKm !== undefined) && extractHasBbox;
     let joinClause = `JOIN ${sch}.spr ON spr.id = place_search.wof_id`;
     if (useBboxJoin) {
         joinClause += ` JOIN ${sch}.${PLACE_BBOX_TABLE} bbox ON bbox.id = spr.id`;
-        // AABB intersection — both bbox sides must overlap. R*Tree handles this in O(log n).
+        // aabb intersection.
+        // Both bounding-box sides must overlap.
+        // The R*Tree checks them in O(log n).
         const filterBox = query.bbox || bboxAround(query.near.lat, query.near.lon, query.near.maxDistanceKm);
         where.push("bbox.min_lat <= ? AND bbox.max_lat >= ?", "bbox.min_lon <= ? AND bbox.max_lon >= ?");
         params.push(filterBox.maxLat, filterBox.minLat, filterBox.maxLon, filterBox.minLon);
     }
-    // LEFT JOIN the population aux table when present. Missing-on-this-extract means the SELECT
-    // just doesn't include the population column; the post-scoring loop treats it as 0.
+    // Left join the population aux table when present.
+    // If this extract lacks the table, the select omits the population column.
+    // The post-scoring loop then uses 0.
     const extractHasPopulation = hasPopulationIndex.get(sch) === true;
     const populationSelect = extractHasPopulation
         ? `${PLACE_POPULATION_TABLE}.population AS population`
@@ -94,29 +112,30 @@ export function fetchSearchRows(options) {
     const populationJoin = extractHasPopulation
         ? `LEFT JOIN ${sch}.${PLACE_POPULATION_TABLE} ON ${PLACE_POPULATION_TABLE}.id = spr.id`
         : "";
-    // The encyclopedic score is CARRIED, never ranked on (ROAD_TO_V9 §2, ratified 2026-08-06) — it
-    // appears in the SELECT and in no ORDER BY, here or in the companion fetch below. Conditioned on the
-    // split column, so a pre-split extract emits a literal NULL and builds no join at all.
+    // The encyclopedic score is returned and never ranked on (ROAD_TO_V9 §2).
+    // It appears in the select and in no order BY, here or in the companion fetch below.
+    // It is conditioned on the split column, so a pre-split extract emits a literal NULL
+    // and builds no join at all.
     const { select: encyclopedicSelect, join: encyclopedicJoin } = encyclopedicClauses.get(sch);
-    // Push the population boost into the ORDER BY when the index is available, so famous places
-    // (whose long alt-name lists hurt BM25) actually make it into the over-fetch window. The TS
-    // post-scoring will still compute the same boost for the final score; this just ensures the
-    // candidate set is right.
+    // Push the population boost into the order BY when the index is available, so famous places
+    // (whose long alt-name lists hurt BM25) actually make it into the over-fetch window.
+    // The TS post-scoring will still compute the same boost for the final score.
+    // This just ensures the candidate set is right.
     //
     // Formula: rank_adjusted = bm25 - populationBoost * min(1.0, log10(1 + pop) / scaleLog10)
     // Lower rank_adjusted = better (matches SQLite's bm25 convention of "more negative = better").
     //
-    // #905 — do NOT reach for bm25 column weights here. Measured falsification (2026-07-02): FTS5's
-    // bm25 length normalization is polluted by the row's TOTAL document size, so identical 1-token
-    // `name` docs read −16.0 (empty alt_names) vs −0.43 (2.7 KB alt_names) EVEN with the alt_names
-    // column weighted to zero — no weighting isolates name relevance in this schema. The famous-
-    // holder guarantee lives in the population-ordered companion fetch below instead, and the
-    // exact tier breaks ties by population in the post-scoring sort.
+    // Do not reach for bm25 column weights here.
+    // FTS5's bm25 length normalization is polluted by the row's total document size,
+    // so identical 1-token `name` docs read −16.0 (empty alt_names) against −0.43
+    // (2.7 KB alt_names) even with the alt_names column weighted to zero.
+    // The population-ordered companion fetch below returns the most populous holder of the name.
+    // The post-scoring sort uses population to break ties in the exact tier.
     const orderByExpr = extractHasPopulation
         ? `(bm25(place_search) - ? * MIN(1.0, COALESCE(log10(1.0 + ${PLACE_POPULATION_TABLE}.population), 0) / ?))`
         : "bm25(place_search)";
-    // Schema-qualified FROM with bare-name MATCH — required syntax for FTS5 on attached schemas.
-    // See extracts.ts header for the failure mode that drove this design.
+    // Schema-qualified `from` with a bare-name `match` is required syntax for FTS5 on attached schemas.
+    // See the extracts.ts header for the failure mode that drove this design.
     const stmt = db.prepare(`
 		SELECT
 			spr.id AS id,
@@ -143,12 +162,13 @@ export function fetchSearchRows(options) {
     }
     params.push(ftsLimit);
     const rawRows = allRows(stmt, ...params);
-    // #905 companion fetch: the same MATCH, ordered by population alone. For name floods
-    // ("Paris" matches thousands of gap-fill villages) the bm25-based window above cannot admit
-    // the famous holder — its bm25 is length-poisoned by the row's alias bulk (measured ~15 pts,
-    // vs a +4.0 boost cap), so FR Paris never even reaches post-scoring. This fetch makes the
-    // prominent holders of a name pool-complete BY CONSTRUCTION; the exact-tier sort below
-    // decides whether they win. Skipped without a population index (nothing to order by).
+    // Companion fetch: the same `match`, ordered only by population.
+    // For name floods ("Paris" matches thousands of gap-fill villages) the bm25-based
+    // window above cannot admit the famous holder, because its bm25 is length-poisoned
+    // by the row's alias bulk (measured ~15 pts, against a +4.0 boost cap).
+    // This fetch includes prominent holders of a name in the candidate pool.
+    // The exact-tier sort below decides whether they win.
+    // It is skipped without a population index, since there is no column to order by.
     if (extractHasPopulation) {
         const popStmt = db.prepare(`
 			SELECT

package/out/search-fetch.js.map

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

package/out/sqlite/convention-source.d.ts

@@ -2,28 +2,24 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   `SqliteConventionSource` — a `ConventionSource` backed by the build-from-source convention asset
- *   (#290, Direction E). Conventions live in a read-only, provenance-stamped `address_convention`
- *   table keyed by WOF polygon id; this source queries them ON DEMAND by id (one indexed lookup,
- *   memoized) rather than paging the whole table into memory as a code constant — the deliberate
- *   counter to the Pelias "giant dictionary in RAM, no provenance" pattern (see the operator design
- *   value in memory `feedback-no-irrelevant-trivia`).
- *
- *   The asset is the queryable, distributable artifact; the strategy IMPLEMENTATIONS stay in code. An
- *   unknown strategy NAME is surfaced loudly at dispatch (see `lookup.ts`), not silently
- *   swallowed.
  */
 import type { DatabaseClient } from "@mailwoman/sqlite/client";
-import { type Convention, type ConventionSource } from "#convention/index";
+import { type Convention, type ConventionSource } from "#convention";
+/**
+ * Reads per-place address conventions from the convention table in an attached
+ * SQLite schema, caching each lookup, including misses.
+ *
+ * A missing table or unparseable row reads as no convention rather than throwing.
+ */
 export declare class SqliteConventionSource<DB> implements ConventionSource {
     #private;
     /**
-     * @param db An open handle to a DB that has the convention asset attached (or is it).
-     * @param schema The schema name the `address_convention` table lives under (`main` or an ATTACHed extract name —
-     *   `WOFSQLitePlaceLookup` auto-detects which extract carries the table).
+     * Creates a source over an open database that is, or has attached, the convention asset.
+     *
+     * @param db The open database handle.
+     * @param schema The schema that holds the convention table, either `main` or an attached extract's name.
      */
     constructor(db: DatabaseClient<DB>, schema: string);
-    get(wofID: number): Convention | undefined;
+    get(wofID: number): Convention | null;
 }
 //# sourceMappingURL=convention-source.d.ts.map

package/out/sqlite/convention-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"convention-source.d.ts","sourceRoot":"","sources":["../../lib/sqlite/convention-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAE9D,OAAO,EAA4B,KAAK,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAEpG,qBAAa,sBAAsB,CAAC,EAAE,CAAE,YAAW,gBAAgB;;IAQlE;;;;OAIG;IACH,YAAY,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAGjD;IAED,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAuBzC;CACD"}
+{"version":3,"file":"convention-source.d.ts","sourceRoot":"","sources":["../../lib/sqlite/convention-source.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAE9D,OAAO,EAA4B,KAAK,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAE9F;;;;;GAKG;AACH,qBAAa,sBAAsB,CAAC,EAAE,CAAE,YAAW,gBAAgB;;IAMlE;;;;;OAKG;IACH,YAAY,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAGjD;IAED,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAqBpC;CACD"}