@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/lib/poi/lookup.ts

@@ -3,59 +3,47 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Node reader for `poi.db` (spec §3.4) — the res-9 k-ring reader over the clustered `poi`
- *   `WITHOUT ROWID` B-tree `poi-schema.ts` builds. Three search modes share one
- *   artifact:
+ *   Node reader for `poi.db` (spec §3.4), the res-9 k-ring reader over the clustered `poi`
+ *   `without rowid` B-tree `poi-schema.ts` builds. Category, brand and name searches share one
+ *   artifact. Each path has a method that returns its details.
  *
- *   - **Category**: `latLngToCell(center, 9)` → `gridDisk` ring-by-ring expansion, probing each
- *     cell's clustered `(h3_cell, category_id, neg_rank, …)` range. Rings accumulate until `limit`
- *     rows are on hand after a completed ring, or `maxRings` is exhausted; the pool is sorted by
- *     haversine distance from `center` after every ring.
- *   - **Brand**: NOT a k-ring walk. Brand rows are globally sparse (~0.31% of poi.db; median nearest
- *     tagged instance ~110 km), so ring expansion could never reach them. Instead a single brand-wide
- *     indexed fetch on `brand_wikidata` (the partial `poi_brand_wikidata` index) pulls EVERY row for
- *     the QID — category unconstrained — then haversine-sorts from `center` and takes the nearest
- *     `limit`, bounded by a `BRAND_MAX_DISTANCE_KM` sanity radius.
- *   - **Name**: FTS5 `MATCH` against the `poi_search` virtual table, hydrated back to full rows by
- *     `name_key`. No center required; if one is given, hits are still distance-sorted.
- *
- *   `latLngToCell`/`gridDisk` come from `h3-js`; the 48-bit short-cell packing that turns a raw H3
- *   cell into the integer `poi.h3_cell` stores is `@mailwoman/spatial`'s `shortCellToInt` — that math
- *   is NEVER reimplemented here (see AGENTS.md on `@mailwoman/spatial` being the one true home for
- *   it).
+ *   `latLngToCell` and `gridDisk` come from `h3-js`. The 48-bit short-cell packing that turns a raw
+ *   H3 cell into the integer `poi.h3_cell` stores is `@mailwoman/spatial`'s `shortCellToInt`, and
+ *   that math is never reimplemented here.
  */
 
 import { allRows } from "@mailwoman/core/utils"
 import { haversineKm, shortCellToInt, type H3Cell } from "@mailwoman/spatial"
-import { DatabaseClient } from "@mailwoman/sqlite/client"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
+import { SQLiteLookup, type SQLiteLookupOptions } from "@mailwoman/sqlite/lookup"
 import { gridDisk, latLngToCell } from "h3-js"
 
 import type { POICategoryCodeTable, POIDatabase, POITable } from "#poi/schema"
 /**
- * Resolution the `poi` table's `h3_cell` column is keyed at — matches the builder (spec §3.4).
+ * Resolution the `poi` table's `h3_cell` column is keyed at, matching the builder (spec §3.4).
  */
 export const POI_H3_RESOLUTION = 9
 
 /**
- * Ring budget default: 16 res-9 k-rings ≈ ~5.4 km (corner) / ~4.3 km worst-bearing. Category path only — the brand path
- * ignores rings entirely.
+ * Ring budget default: 16 res-9 k-rings, about 5.4 km at the corner and 4.3 km worst-case.
+ *
+ * Category path only, since the brand path ignores rings entirely.
+ * Dense categories never reach this ceiling, because the loop breaks once a ring accumulates `limit` rows.
  *
- * Raised from 12 (≈4 km) after nm-04 ("hiking trail near Marseille") exposed a boundary miss for SPARSE categories: the
- * nearest `trail` instance sits at 3.90 km, but the res-9 disk of radius 11 (maxRings 12) reaches only ~3.16 km in its
- * worst bearing — the cell holding that trail isn't covered until ring 13 (maxRings 14). Dense categories are
- * unaffected: the loop breaks the ring it accumulates `limit` rows (cafe@Paris fills 20 by ring 2), so this ceiling
- * never enters their probe budget. Only sparse-but-present categories that never reach `limit` scan the fuller budget —
- * a cold, one-shot `mailwoman poi` path, not per-keystroke. 16 (not the bare threshold 14) leaves ~2 rings of margin so
- * the radius is stable against small db rebuilds, while staying ~4x tighter than the board's 25 km "roughly right
- * place" window (no wrong-city false positives). The browser reader passes its own smaller `maxRings` and is
- * untouched.
+ * Sparse-but-present categories that never reach `limit` scan the fuller budget.
+ * The extra rings keep the radius stable across small DB rebuilds.
+ * The browser reader passes its own smaller `maxRings`.
  */
 const DEFAULT_MAX_RINGS = 16
 
 /**
- * Brand sanity radius (km): the brand-wide fetch returns the global nearest at ANY distance, so this drops hits far
- * enough to be certainly the wrong continent — "Applebee's near Marseille" comes back empty rather than with a 5,700 km
- * hit. A product bound, not a reach cap (the index already makes the fetch cheap regardless of distance).
+ * Brand sanity radius (km).
+ *
+ * The brand-wide fetch returns the global nearest at any distance, so this drops
+ * hits far enough away to be certainly on another continent.
+ * "Applebee's near Marseille" comes back empty instead of with a 5,700 km hit.
+ *
+ * This is a product bound, since the index already makes the fetch cheap regardless of distance.
  */
 const BRAND_MAX_DISTANCE_KM = 500
 
@@ -66,16 +54,18 @@ const DEFAULT_LIMIT = 20
 
 export interface POISearchQuery {
 	/**
-	 * Poi-taxonomy category id (string side of the dictionary). Ignored when `brandWikidata` is also set — brand wins.
-	 */
-	categoryID?: string
-	/**
-	 * Fan-out category ids — the Overture `taxonomy.primary` leaves a single canonical category rolls up into (e.g.
-	 * `supermarket` → `grocery_store`, `organic_grocery_store`, …). When set, the k-ring walk probes EVERY resolvable
-	 * leaf per cell and unions the rows; unknown leaves are skipped. Supersedes `categoryID` (which is treated as a
-	 * one-element list `[categoryID]` when this is absent). Ignored when `brandWikidata` is set — brand wins.
+	 * Poi-taxonomy category ids (string side of the dictionary) to search.
+	 *
+	 * A single category is a one-element list.
+	 * A canonical Overture `taxonomy.primary` category passes every leaf it rolls up into,
+	 * as in `supermarket` → `grocery_store`, `organic_grocery_store`, ….
+	 *
+	 * The k-ring walk probes every resolvable leaf per cell and unions the rows.
+	 * Unknown leaves are skipped.
+	 *
+	 * Ignored when `brandWikidata` is set, since brand wins.
 	 */
-	categoryIDs?: string[]
+	categoryIDs?: readonly string[]
 	/**
 	 * Wikidata QID for brand-exact search.
 	 */
@@ -85,12 +75,17 @@ export interface POISearchQuery {
 	 */
 	name?: string
 	/**
-	 * Search center. Required for category/brand queries (k-ring expansion).
+	 * Search center.
+	 *
+	 * Required for category/brand queries (k-ring expansion).
 	 */
 	center?: { latitude: number; longitude: number }
 	/**
-	 * Ring budget: how many res-9 k-rings to expand before giving up (default 16 ≈ ~5.4 km). Counts ring 0, so k reaches
-	 * `maxRings - 1`.
+	 * Ring budget: how many res-9 k-rings to expand before giving up.
+	 *
+	 * Counts ring 0, so k reaches `maxRings - 1`.
+	 *
+	 * @defaultValue `16` ≈ ~5.4 km
 	 */
 	maxRings?: number
 	limit?: number
@@ -105,25 +100,25 @@ export interface POISearchHit {
 	country: string
 	confidence: number
 	/**
-	 * Overture GERS id — nullable METADATA ONLY, never a key (the #470 rule; see `POITable.gers_id`).
+	 * Overture gers id.
+	 *
+	 * Nullable metadata, never a key.
+	 * See `POITable.gers_id`.
 	 */
 	gersID: string | null
-	distanceM?: number
+	distanceM: number | null
 }
 
-export interface POILookupOpts<DB extends POIDatabase = POIDatabase> {
-	/**
-	 * Path to a `poi.db` built by the (future) POI builder. Opened read-only.
-	 */
-	databasePath?: string
-	/**
-	 * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
-	 */
-	database?: DatabaseClient<DB>
-}
+/**
+ * Where a {@link POILookup} reads from.
+ *
+ * The source is a `poi.db` built by the POI builder, opened read-only,
+ * or a connection the caller already holds.
+ */
+export type POILookupOpts<DB extends POIDatabase = POIDatabase> = SQLiteLookupOptions<DB>
 
 /**
- * The `poi` columns every search mode hydrates — a typed projection of the SHARED {@link POITable}.
+ * The `poi` columns every search mode hydrates, a typed projection of the shared {@link POITable}.
  */
 type POIRow = Pick<
 	POITable,
@@ -141,13 +136,7 @@ type POIRow = Pick<
 /**
  * Node reader over `poi.db`.
  */
-export class POILookup<DB extends POIDatabase = POIDatabase> implements Disposable {
-	#db: DatabaseClient<DB>
-	/**
-	 * Resources this instance opened. A connection handed in by a caller is NOT in here, so disposal cannot reach it —
-	 * ownership is membership rather than a flag a later branch has to check.
-	 */
-	readonly #resources = new DisposableStack()
+export class POILookup<DB extends POIDatabase = POIDatabase> extends SQLiteLookup<DB> {
 	readonly #categoryToID = new Map<string, number>()
 	readonly #idToCategory = new Map<number, string>()
 
@@ -156,39 +145,36 @@ export class POILookup<DB extends POIDatabase = POIDatabase> implements Disposab
 	 */
 	readonly #categoryCellProbe: ReturnType<DatabaseClient["prepare"]>
 	/**
-	 * `brand_wikidata` → ALL of a brand's rows globally (partial-index range-scan); distance-sorted in JS, not SQL.
+	 * `brand_wikidata` → all of a brand's rows globally (partial-index range-scan).
+	 * The sort happens in JS.
 	 */
 	readonly #brandProbe: ReturnType<DatabaseClient["prepare"]>
 	/**
-	 * FTS5 `MATCH` over `poi_search`, returning candidate `name_key`s to hydrate.
+	 * FTS5 `match` over `poi_search`, returning candidate `name_key`s to hydrate.
 	 */
 	readonly #nameFTSProbe: ReturnType<DatabaseClient["prepare"]>
 
 	constructor(opts: POILookupOpts<DB>) {
-		if (opts.database) {
-			this.#db = opts.database
-		} else if (opts.databasePath) {
-			this.#db = this.#resources.use(new DatabaseClient<DB>(opts.databasePath, { readOnly: true }))
-		} else {
-			throw new Error("POILookup needs `databasePath` or `database`")
-		}
+		super(opts)
 
-		// The category dictionary is tiny (poi-taxonomy's category count) — load it once at
-		// construction so `search` never round-trips to it.
-		for (const r of allRows<POICategoryCodeTable>(this.#db.prepare("SELECT id, category FROM poi_category_codes"))) {
+		// The category dictionary is tiny (poi-taxonomy's category count), so load it once
+		// at construction and keep `search` from round-tripping to it.
+		for (const r of allRows<POICategoryCodeTable>(
+			this.database.prepare("SELECT id, category FROM poi_category_codes")
+		)) {
 			this.#categoryToID.set(String(r.category), Number(r.id))
 			this.#idToCategory.set(Number(r.id), String(r.category))
 		}
 
 		const columns = "name, category_id, brand_wikidata, latitude, longitude, country, confidence, name_key, gers_id"
 
-		this.#categoryCellProbe = this.#db.prepare(
+		this.#categoryCellProbe = this.database.prepare(
 			`SELECT ${columns} FROM poi WHERE h3_cell = ? AND category_id = ? ORDER BY neg_rank ASC LIMIT ?`
 		)
 
-		this.#brandProbe = this.#db.prepare(`SELECT ${columns} FROM poi WHERE brand_wikidata = ?`)
+		this.#brandProbe = this.database.prepare(`SELECT ${columns} FROM poi WHERE brand_wikidata = ?`)
 
-		this.#nameFTSProbe = this.#db.prepare(
+		this.#nameFTSProbe = this.database.prepare(
 			"SELECT name_key FROM poi_search WHERE poi_search MATCH ? ORDER BY bm25(poi_search) LIMIT ?"
 		)
 	}
@@ -200,13 +186,11 @@ export class POILookup<DB extends POIDatabase = POIDatabase> implements Disposab
 			return this.#searchByName(query.name, limit, query.center)
 		}
 
-		if (query.categoryID || (query.categoryIDs && query.categoryIDs.length) || query.brandWikidata) {
+		if (query.categoryIDs?.length || query.brandWikidata) {
 			if (!query.center) {
 				throw new Error("POILookup.search: category/brand search requires a `center`")
 			}
 
-			// brandWikidata wins over categoryID(s) when both are set — see POISearchQuery.categoryID. The brand path is
-			// a brand-wide indexed fetch, NOT a k-ring walk (brand rows are too sparse for ring expansion to reach).
 			if (query.brandWikidata) {
 				return this.#searchBrand(query.brandWikidata, query.center, limit)
 			}
@@ -218,10 +202,14 @@ export class POILookup<DB extends POIDatabase = POIDatabase> implements Disposab
 	}
 
 	/**
-	 * Brand path: a single brand-wide indexed fetch — NO k-ring. Fetch EVERY row for the QID (the partial
-	 * `poi_brand_wikidata` index makes this a range-scan, not a 13.68M full scan), haversine-sort from `center`, drop
-	 * anything past the {@link BRAND_MAX_DISTANCE_KM} sanity radius, and take the nearest `limit`. Returns the true
-	 * nearest at any distance — the reach ceiling k-ring hits on sparse brand rows is gone.
+	 * Brand path: a single brand-wide indexed fetch and no k-ring.
+	 *
+	 * The partial `poi_brand_wikidata` index turns the QID fetch into a range-scan
+	 * instead of a 13.68M full scan.
+	 * Rows are sorted by haversine distance from `center`.
+	 *
+	 * The lookup drops rows past {@link BRAND_MAX_DISTANCE_KM}.
+	 * It returns the nearest `limit` rows.
 	 */
 	#searchBrand(brandWikidata: string, center: { latitude: number; longitude: number }, limit: number): POISearchHit[] {
 		const rows = allRows<POIRow>(this.#brandProbe, brandWikidata)
@@ -242,11 +230,9 @@ export class POILookup<DB extends POIDatabase = POIDatabase> implements Disposab
 		const maxRings = query.maxRings ?? DEFAULT_MAX_RINGS
 		const categoryIDs: number[] = []
 
-		// `categoryIDs` (the fan-out list) supersedes the single `categoryID`; either way, resolve each id through the
-		// dictionary and drop the ones the db doesn't carry (Overture-taxonomy drift, or an identity id with no rows).
-		const seedIDs = query.categoryIDs?.length ? query.categoryIDs : query.categoryID ? [query.categoryID] : []
-
-		for (const id of seedIDs) {
+		// Each id resolves through the dictionary.
+		// Unresolved ids are dropped to cover Overture taxonomy drift and identity ids with no rows.
+		for (const id of query.categoryIDs ?? []) {
 			const resolved = this.#categoryToID.get(id)
 
 			if (resolved !== undefined) {
@@ -254,7 +240,8 @@ export class POILookup<DB extends POIDatabase = POIDatabase> implements Disposab
 			}
 		}
 
-		// No resolvable leaf (every id unknown to the dictionary) can't have rows — a clean miss, not a throw.
+		// No resolvable leaf can have rows, since every id is unknown to the dictionary.
+		// This is a clean miss instead of a throw.
 		if (!categoryIDs.length) return []
 
 		const origin = latLngToCell(center.latitude, center.longitude, POI_H3_RESOLUTION) as H3Cell
@@ -263,8 +250,8 @@ export class POILookup<DB extends POIDatabase = POIDatabase> implements Disposab
 
 		// `ring` starts at 0 (the origin cell itself), so this loop's k reaches `maxRings - 1`.
 		for (let ring = 0; ring < maxRings; ring++) {
-			// gridDisk(origin, ring) returns the WHOLE disk out to `ring`; diffing against what's
-			// already been probed derives just this ring's new cells.
+			// gridDisk(origin, ring) returns the whole disk out to `ring`, so diffing against
+			// the already-probed set derives just this ring's new cells.
 			const diskCells = gridDisk(origin, ring) as string[]
 			const newCells = diskCells.filter((cell) => !seenCells.has(cell))
 
@@ -272,8 +259,6 @@ export class POILookup<DB extends POIDatabase = POIDatabase> implements Disposab
 				seenCells.add(cell)
 				const shortCell = shortCellToInt(cell as H3Cell)
 
-				// Fan-out: probe every resolved Overture leaf for this canonical category, unioning the rows. The
-				// post-ring distance sort + `slice(0, limit)` below dedupes the pool down to the nearest `limit`.
 				for (const categoryID of categoryIDs) {
 					rows.push(...allRows<POIRow>(this.#categoryCellProbe, shortCell, categoryID, limit))
 				}
@@ -288,11 +273,13 @@ export class POILookup<DB extends POIDatabase = POIDatabase> implements Disposab
 	}
 
 	/**
-	 * Name path: FTS5 MATCH → hydrate by name_key. No center required; distance-sorts if one is given anyway.
+	 * Name path: FTS5 match → hydrate by name_key.
+	 *
+	 * No center is required.
+	 * Hits are distance-sorted when one is given.
 	 *
-	 * Hydration is ONE batched `WHERE name_key IN (...)` query over the FTS hits' unique `name_key`s, not a per-hit probe
-	 * — with up to `limit` FTS hits, a per-hit probe was up to `limit` full table scans before `createPOINameKeyIndex`
-	 * (poi-schema.ts) + this batching.
+	 * Hydration is one batched `where name_key IN (...)` query over the unique `name_key`s
+	 * of the FTS hits, since a per-hit probe would be up to `limit` full table scans.
 	 */
 	#searchByName(name: string, limit: number, center?: { latitude: number; longitude: number }): POISearchHit[] {
 		const matchQuery = sanitizePOINameQuery(name)
@@ -339,21 +326,19 @@ export class POILookup<DB extends POIDatabase = POIDatabase> implements Disposab
 	}
 
 	/**
-	 * Batched hydration for the FTS name path: `WHERE name_key IN (?, ?, …)`, one query for the whole batch instead of
-	 * one probe per FTS hit. This is a cold path (name search only) with variable arity per call, so the statement is
-	 * prepared fresh each time rather than cached.
+	 * Batched hydration for the FTS name path: `where name_key IN (?, ?, …)`,
+	 * one query for the whole batch instead of one probe per FTS hit.
+	 *
+	 * This is a cold path (name search only) with variable arity per call,
+	 * so the statement is prepared fresh each time rather than cached.
 	 */
 	#hydrateByNameKeys(nameKeys: string[]): POIRow[] {
 		const columns = "name, category_id, brand_wikidata, latitude, longitude, country, confidence, name_key, gers_id"
 		const placeholders = nameKeys.map(() => "?").join(", ")
-		const stmt = this.#db.prepare(`SELECT ${columns} FROM poi WHERE name_key IN (${placeholders})`)
+		const stmt = this.database.prepare(`SELECT ${columns} FROM poi WHERE name_key IN (${placeholders})`)
 
 		return allRows<POIRow>(stmt, ...nameKeys)
 	}
-
-	[Symbol.dispose](): void {
-		this.#resources[Symbol.dispose]()
-	}
 }
 
 function sortByDistance(rows: POIRow[], center: { latitude: number; longitude: number }): POIRow[] {
@@ -378,27 +363,25 @@ function toHit(
 		country: row.country,
 		confidence: row.confidence,
 		gersID: row.gers_id,
-		...(center
-			? { distanceM: haversineKm(center.latitude, center.longitude, row.latitude, row.longitude) * 1000 }
-			: {}),
+		distanceM: center ? haversineKm(center.latitude, center.longitude, row.latitude, row.longitude) * 1000 : null,
 	}
 }
 
 /**
- * Sanitize free text into an FTS5-safe MATCH query: strip the characters FTS5 would otherwise read as syntax (`"`
- * phrase delimiters, `*` prefix wildcards, `:` column-filter separators), then phrase-quote each whitespace-separated
- * token (AND-joined).
+ * Sanitize free text into an FTS5-safe `match` query: strip the characters FTS5 would otherwise
+ * read as syntax (`"` phrase delimiters, `*` prefix wildcards, `:` column-filter separators),
+ * then phrase-quote each whitespace-separated token (and-joined).
  *
- * `resolver-wof-sqlite` already has this discipline — `lookup.ts`'s `sanitizeFTSQuery` — but that function is
- * module-private there (not re-exported from `fts.ts` or the package's `index.ts`), so this replicates the same
- * discipline locally rather than reaching across the module boundary for a private helper.
+ * `lookup.ts` already has this discipline in `sanitizeFTSQuery`, but that function is
+ * module-private there and is not re-exported from `fts.ts` or the package's `index.ts`.
+ * This replicates the discipline locally rather than reach across the module boundary for a private helper.
  */
 function sanitizePOINameQuery(text: string): string {
 	return text
 		.replaceAll(/["*:]/g, "")
 		.trim()
 		.split(/\s+/u)
-		.filter((token) => token.length > 0)
+		.filter((token) => token.length)
 		.map((token) => `"${token.replaceAll('"', '""')}"`)
 		.join(" ")
 }

package/lib/poi/schema.ts

@@ -3,23 +3,25 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Typed schema for poi.db — spatial layer #1 (spec §3.4). One clustered `WITHOUT ROWID` B-tree
- *   keyed `(h3_cell, category_id, neg_rank, rowid_key)` so "everything near this res-9 cell" is a
- *   contiguous key range (the byte-range/httpvfs access pattern, same discipline as the candidate
- *   gazetteer). Rows carry denormalized name/brand/coords; category ids are small ints via the
- *   `poi_category_codes` dictionary (poi-taxonomy category ids are the string side). The DB also
- *   embeds the layer-contract tables from `@mailwoman/core/layers` — the builder writes the
- *   manifest (tier `shipped`, spine `h3` res 9) and per-res-6-cell coverage.
+ *   Typed schema for poi.db, the first spatial layer (spec §3.4). One clustered `without rowid`
+ *   B-tree uses `(h3_cell, category_id, neg_rank, rowid_key)` as its key. All rows near a res-9 cell
+ *   occupy a contiguous key range. This matches byte-range and httpvfs access and follows the
+ *   candidate gazetteer's layout. Rows include denormalized name, brand and coordinates.
+ *   The `poi_category_codes` dictionary stores category ids as small integers. POI-taxonomy category
+ *   ids remain strings. The database embeds the layer-interface tables from `@mailwoman/core/layers`.
+ *   The builder writes a manifest with tier `shipped` and spine `h3` res 9. It also writes per-res-6-cell coverage.
  */
 
-import type { LayerContractDatabase } from "@mailwoman/core/layers"
+import type { layerschemadatabase } from "@mailwoman/core/layers"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { sql, type Kysely } from "kysely"
 
 import type { NameKey } from "#street/normalize"
 
 /**
- * One POI row. Clustered PK: h3_cell → category_id → neg_rank → rowid_key.
+ * One POI row.
+ *
+ * Clustered PK: h3_cell → category_id → neg_rank → rowid_key.
  */
 export interface POITable {
 	/**
@@ -40,10 +42,12 @@ export interface POITable {
 	rowid_key: number
 	name: string | null
 	/**
-	 * Probe key for exact name lookups, minted by {@link normalizeLocalityForKey} at build AND at query.
+	 * Probe key for exact name lookups, minted by {@link normalizeLocalityForKey} at build and at query.
+	 *
+	 * Branded because a `toLowerCase()` approximation of the fold is still a `string`.
+	 * That approximation binds to the parameter and returns fewer rows.
 	 *
-	 * Branded because a `toLowerCase()` approximation of the fold is still a `string`: it binds to the parameter, returns
-	 * fewer rows, and the shortfall reads as a coverage gap in the data rather than a defect in the probe.
+	 * The shortfall looks like a data coverage gap instead of a probe defect.
 	 */
 	name_key: NameKey | null
 	brand_wikidata: string | null
@@ -58,14 +62,18 @@ export interface POITable {
 	 */
 	confidence: number
 	/**
-	 * GERS id — nullable METADATA ONLY, never a key (the #470 rule).
+	 * Gers id.
+	 * Nullable metadata, never a key.
 	 */
 	gers_id: string | null
 }
 
 /**
- * Staging mirror — every column nullable except the coords (the loader fills positionally; the materialize SELECT
- * enforces completeness).
+ * The staging mirror.
+ * Every column is nullable except the coords.
+ *
+ * The loader fills this table positionally.
+ * The materialize select enforces completeness.
  */
 export interface POIStageTable {
 	h3_cell: number | null
@@ -90,14 +98,14 @@ export interface POICategoryCodeTable {
 	category: string
 }
 
-export interface POIDatabase extends LayerContractDatabase {
+export interface POIDatabase extends layerschemadatabase {
 	poi: POITable
 	poi_stage: POIStageTable
 	poi_category_codes: POICategoryCodeTable
 }
 
 /**
- * Clustered-key-order column list shared by builder + `INSERT INTO poi SELECT … FROM poi_stage`.
+ * Clustered-key-order column list shared by builder + `insert into poi select … from poi_stage`.
  */
 export const POI_COLUMNS = [
 	"h3_cell",
@@ -154,25 +162,31 @@ export async function createPOITable(db: Kysely<POIDatabase>): Promise<void> {
 		.addColumn("confidence", "real", (c) => c.notNull())
 		.addColumn("gers_id", "text")
 		.addPrimaryKeyConstraint("poi_pk", ["h3_cell", "category_id", "neg_rank", "rowid_key"])
-		// `WITHOUT ROWID` has no first-class builder; the raw modifier is the idiomatic fallback.
+		// `without rowid` has no first-class builder. The raw modifier is the idiomatic fallback.
 		.modifyEnd(sql`without rowid`)
 		.execute()
 }
 
 /**
- * Secondary index for the FTS-hydration path. Builders call this AFTER the bulk materialize (index-after-load).
+ * Secondary index for the FTS-hydration path.
+ *
+ * Builders call this after the bulk materialize (index-after-load).
  */
 export async function createPOINameKeyIndex(db: Kysely<POIDatabase>): Promise<void> {
 	await db.schema.createIndex("poi_name_key").on("poi").column("name_key").execute()
 }
 
 /**
- * Secondary index for the BRAND path — a brand-wide fetch by `brand_wikidata` (no `h3_cell` prefix). Brand rows are
- * globally sparse (~0.31% of poi.db, median nearest tagged instance ~110 km), so the k-ring walk can never reach them;
- * the reader instead fetches ALL of a brand's rows and distance-sorts. Without this index that is a full-table scan
- * (~600 ms); with it, a range-scan (<1 ms p50). PARTIAL (`WHERE brand_wikidata IS NOT NULL`) so the ~99.7% of rows that
- * carry no QID never enter the B-tree — the index holds only the ~43k branded rows. Builders call this AFTER the bulk
- * materialize (index-after-load), same phase as {@link createPOINameKeyIndex}.
+ * Secondary index for the brand path, a brand-wide fetch by `brand_wikidata` with no `h3_cell` prefix.
+ *
+ * Brand rows are globally sparse, so the k-ring walk can never reach them and the reader
+ * instead fetches all of a brand's rows and distance-sorts.
+ * Without this index that fetch is a full-table scan, while with it the fetch is a range-scan.
+ *
+ * The partial index (`where brand_wikidata is not NULL`) keeps the mostly unbranded rows out of the B-tree.
+ *
+ * Builders call this after the bulk materialize (index-after-load),
+ * same phase as {@link createPOINameKeyIndex}.
  */
 export async function createPOIBrandIndex(db: Kysely<POIDatabase>): Promise<void> {
 	await db.schema
@@ -189,7 +203,9 @@ export async function createPOIBrandIndex(db: Kysely<POIDatabase>): Promise<void
 export const POI_FTS_TABLE = "poi_search"
 
 /**
- * FTS5 stays raw SQL by project rule (Kysely can't express virtual tables). Content-keyed by name_key.
+ * FTS5 stays raw SQL by project rule (Kysely can't express virtual tables).
+ *
+ * Content-keyed by name_key.
  */
 export function createPOISearchFTS<DB>(db: DatabaseClient<DB>): void {
 	db.exec(

package/lib/polygon-schema.ts

@@ -4,10 +4,10 @@
  * @author Teffen Ellis, et al.
  *
  *   Typed schema for the polygon sidecar (`wof-polygons.db`) — the one table `WOFReverseGeocoder` probes for a
- *   place's geometry. The interface is the read/write contract and {@link createPolygonsTable} creates the table, so a
+ *   place's geometry. The interface is the read/write interface and {@link createPolygonsTable} creates the table, so a
  *   column added to one is a compile error against the other.
  *
- *   The sidecar is OPTIONAL to the reverse geocoder: without it every result falls back to a centroid, so the reader
+ *   The sidecar is optional to the reverse geocoder: without it every result falls back to a centroid, so the reader
  *   checks for the table's presence rather than assuming it.
  */
 
@@ -19,8 +19,10 @@ import type { Kysely } from "kysely"
 export interface PolygonsTable {
 	id: number
 	/**
-	 * The GeoJSON geometry, JSON-encoded. A row that fails to parse reads as no-polygon, never as an error — a malformed
-	 * geometry must not fail the whole reverse query.
+	 * The GeoJSON geometry, JSON-encoded.
+	 *
+	 * A row that fails to parse reads as no-polygon, never as an error.
+	 * A malformed geometry must not fail the whole reverse query.
 	 */
 	geom: string
 }
@@ -30,8 +32,10 @@ export interface PolygonDatabase {
 }
 
 /**
- * The slice of a Kysely handle the polygon DDL touches. Kysely is invariant in its schema parameter, so naming only
- * `schema` lets a builder holding a wider handle pass it without a cast.
+ * The subset of a Kysely handle the polygon DDL touches.
+ *
+ * Kysely is invariant in its schema parameter, so naming only `schema` lets a
+ * builder holding a wider handle pass it without a cast.
  */
 export type PolygonSchemaHandle = Pick<Kysely<PolygonDatabase>, "schema">