@mailwoman/resolver-wof-sqlite 9.4.0 → 10.1.0

package/lib/reverse.ts

@@ -3,29 +3,23 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Reverse geocoding (#484): `(lat, lon)` → the containing admin hierarchy. Assembly over existing
- *   implementation, per the 2026-06-11 scoping notes:
+ *   Reverse geocoding: map a `(lat, lon)` point to the containing admin hierarchy.
  *
- *   1. **Candidate fetch** — the admin DB's `place_bbox` R*Tree (built by `fts.ts`) for places whose
- *        bbox contains the point, smallest-area-first (so the FIRST polygon confirmation is the
- *        deepest).
- *   2. **PIP confirmation** — ray-cast (geo.ts, the canonical TS port of
- *        `scripts/eval/pip-containment.py`) against the polygon sidecar DB (`wof-polygons.db`,
- *        `polygons(id, geom)` with GeoJSON text — built by `scripts/build-wof-polygons.mjs` for the
- *        demo map). A candidate whose polygon EXISTS but rejects the point is a bbox false positive
- *        and is dropped entirely; a candidate with no polygon row stays eligible for the
- *        approximate fallback.
- *   3. **Approximate descent** — WOF carries point geometry for most localities (#292: ~99% of JP
- *        municipalities; ~half of US localities have degenerate bboxes too), so the polygon walk
- *        usually bottoms out at county level. We then descend tier-by-tier (county → localadmin →
- *        locality → …) through the winner's DESCENDANTS (the `ancestors` table, reversed), taking
- *        the PIP-confirmed child when a polygon exists and the nearest-centroid child otherwise —
- *        the latter flagged `containment: "approximate"`, the demo's honesty convention.
- *   4. **Hierarchy assembly** — the deepest place's ancestor chain via the SAME walk forward resolution
- *        uses (`ancestry.ts`, #404), so consumers get a symmetric tree.
+ *   1. Fetch the admin DB's `place_bbox` R*Tree candidates whose bbox contains the point,
+ *      smallest-area-first, so the first polygon confirmation is the deepest.
+ *   2. Confirm each candidate by ray-cast (geo.ts, the canonical TS port of
+ *      `scripts/eval/pip-containment.py`) against the polygon sidecar DB (`wof-polygons.db`,
+ *      `polygons(id, geom)` with GeoJSON text, built by `scripts/build-wof-polygons.mjs`). A
+ *      candidate whose polygon exists but rejects the point is a bbox false positive and is
+ *      dropped. A candidate with no polygon row stays eligible for the approximate fallback.
+ *   3. Descend tier-by-tier through the winner's descendants (the `ancestors` table, reversed),
+ *      taking the PIP-confirmed child when a polygon exists and the nearest-centroid child
+ *      otherwise. A centroid-fallback step is flagged `containment: "approximate"`.
+ *   4. Assemble the deepest place's ancestor chain through the same walk forward resolution uses,
+ *      so consumers get a symmetric tree.
  *
- *   Reverse quality is country-dependent (polygon coverage: see the #292 JP finding); `containment`
- *   says so per result rather than pretending.
+ *   Reverse quality is country-dependent, because polygon coverage is. `containment` records this per
+ *   result.
  */
 
 import { tryParsingJSON } from "@mailwoman/core/json"
@@ -33,9 +27,10 @@ import { allRows } from "@mailwoman/core/utils"
 import { bboxAround, geometryContains, haversineKm, type ParsedGeometry } from "@mailwoman/spatial"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 import { tableExists } from "@mailwoman/sqlite/introspection"
+import type { PathBuilderLike } from "path-ts"
 
-import { ancestorLineage, placetypeDepth } from "#ancestry/index"
-import { PLACE_BBOX_TABLE } from "#fts/index"
+import { ancestorLineage, placetypeDepth } from "#ancestry"
+import { PLACE_BBOX_TABLE } from "#fts"
 import type { WOFDatabase } from "#schema"
 import type { PlaceCandidate, WOFPlacetype } from "#types"
 /**
@@ -51,62 +46,85 @@ const MAX_ABS_LONGITUDE = 180
 /**
  * How the deepest returned place was confirmed:
  *
- * - `"polygon"` — the point ray-cast INSIDE the place's real (DP-simplified) admin boundary.
- * - `"approximate"` — the place has no polygon on record; it won by nearest-centroid among the candidates whose bbox (or
- *   parent) contains the point. The same honesty convention as the demo's approximate circles — country-dependent data
- *   reality, surfaced instead of hidden.
+ * - `"polygon"`: the point ray-cast inside the place's real (DP-simplified) admin boundary.
+ * - `"approximate"`: the place has no polygon on record.
+ *   It returns the nearest-centroid candidate among places whose bbox or parent contains the point.
+ *   The demo's approximate circles use the same convention.
+ *   Both results expose country-dependent data coverage.
  */
 export type ContainmentKind = "polygon" | "approximate"
 
 export interface ReverseGeocodeResult {
 	/**
-	 * The containment chain, DEEPEST-FIRST (`[0]` is the winning place, then its ancestors up to country) — the same tree
-	 * shape forward resolution attaches via `includeAncestors`. Empty when no candidate's bbox contains the point (open
-	 * ocean, or outside the gazetteer's coverage).
+	 * The containment chain, deepest-first.
+	 *
+	 * `[0]` is the winning place, then its ancestors up to country.
+	 * This is the same tree shape forward resolution attaches via `includeAncestors`.
+	 *
+	 * Empty when no candidate's bbox contains the point (open ocean, or outside the gazetteer's coverage).
 	 */
 	hierarchy: PlaceCandidate[]
 	/**
-	 * Containment kind of the DEEPEST place in `hierarchy` (see {@link ContainmentKind}).
+	 * Containment kind of the deepest place in `hierarchy` (see {@link ContainmentKind}).
 	 */
 	containment: ContainmentKind
 }
 
 export interface WOFReverseGeocoderOpts {
 	/**
-	 * Path to the admin gazetteer DB (e.g. `admin-global-priority.db`) — must carry `spr`, `ancestors`, and the
-	 * package-built `place_bbox` R*Tree (`mailwoman gazetteer build fts`). Mutually exclusive with `adminDatabase`.
+	 * Path to the admin gazetteer DB (e.g. `admin-global-priority.db`).
+	 *
+	 * It must include `spr`, `ancestors`, and the package-built `place_bbox`
+	 * R*Tree (`mailwoman gazetteer build fts`).
+	 *
+	 * Mutually exclusive with `adminDatabase`.
 	 */
-	adminDBPath?: string
+	adminDBPath?: PathBuilderLike
 	/**
-	 * Pre-opened admin DB — primarily for tests against an inline fixture.
+	 * Pre-opened admin DB, primarily for tests against an inline fixture.
 	 */
 	adminDatabase?: DatabaseClient<WOFDatabase>
 	/**
-	 * Path to the polygon sidecar DB (`wof-polygons.db`, table `polygons(id, geom)`). OPTIONAL — without it every result
-	 * is `containment: "approximate"` (centroid-only mode). Mutually exclusive with `polygonDatabase`.
+	 * Path to the polygon sidecar DB (`wof-polygons.db`, table `polygons(id, geom)`).
+	 *
+	 * Optional.
+	 * Without it every result is `containment: "approximate"` (centroid-only mode).
+	 *
+	 * Mutually exclusive with `polygonDatabase`.
 	 */
-	polygonDBPath?: string
+	polygonDBPath?: PathBuilderLike
 	/**
-	 * Pre-opened polygon DB — primarily for tests.
+	 * Pre-opened polygon DB, primarily for tests.
 	 */
 	polygonDatabase?: DatabaseClient<WOFDatabase>
 }
 
 export interface ReverseGeocodeOpts {
 	/**
-	 * Restrict the hierarchy to these placetypes (both the bbox candidates and the descent tiers). Default: every admin
-	 * placetype the gazetteer carries. E.g. `["region", "county", "locality"]` to skip the neighbourhood grain.
+	 * Restrict the hierarchy to these placetypes (both the bbox candidates and the descent tiers).
+	 *
+	 * Default: every admin placetype in the gazetteer.
+	 * E.g.
+	 *
+	 * `["region", "county", "locality"]` to skip the neighborhood grain.
 	 */
 	placetypes?: WOFPlacetype[]
 	/**
-	 * Cap on the bbox candidate fetch. Default 128 — comfortably covers a dense metro (the most bbox-overlapping point
-	 * we've measured is a few dozen neighbourhoods + the admin chain).
+	 * Cap on the bbox candidate fetch.
+	 *
+	 * The default is 128.
+	 * Current measurements show that this covers a dense metro.
+	 *
+	 * The most bbox-overlapping point we have measured is a few dozen neighborhoods plus the admin chain.
 	 */
 	maxCandidates?: number
 	/**
-	 * Approximate (nearest-centroid) steps further than this from the query point are not taken — keeps a sparse
-	 * gazetteer from "refining" to a far-away sibling. Polygon-confirmed steps ignore it (containment is exact regardless
-	 * of centroid distance). Default 25 km.
+	 * The lookup skips approximate (nearest-centroid) steps farther than this from the query point.
+	 *
+	 * This keeps a sparse gazetteer from "refining" to a far-away sibling.
+	 *
+	 * Polygon-confirmed steps ignore it (containment is exact regardless of centroid distance).
+	 * Default 25 km.
 	 */
 	maxApproximateKm?: number
 }
@@ -115,8 +133,10 @@ const DEFAULT_MAX_CANDIDATES = 128
 const DEFAULT_MAX_APPROXIMATE_KM = 25
 
 /**
- * The tier ladder for the approximate descent, coarsest-first. Each tier is attempted among the CURRENT winner's
- * descendants; a tier with no rows is skipped (e.g. counties without localadmins jump straight to locality).
+ * The tier ladder for the approximate descent, coarsest-first.
+ *
+ * Each tier is attempted among the current winner's descendants.
+ * A tier with no rows is skipped (e.g. counties without localadmins jump straight to locality).
  */
 const DESCENT_TIERS: readonly WOFPlacetype[] = [
 	"county",
@@ -165,10 +185,12 @@ export class WOFReverseGeocoder implements Disposable {
 	readonly #polygons: DatabaseClient<WOFDatabase> | null
 	readonly #ownsPolygons: boolean
 	/**
-	 * Parsed-geometry cache. Reverse queries cluster geographically (an eval run hits the same ~15 county polygons 1400
-	 * times), so caching the JSON.parse pays for itself immediately. Bounded — cleared wholesale at the cap rather than
-	 * LRU-tracked; the polygons are DP-simplified and small, the cap exists only to keep a long-lived server process
-	 * honest.
+	 * Parsed-geometry cache.
+	 *
+	 * Reverse queries cluster geographically, so caching the JSON.parse avoids repeated work.
+	 * The cache is bounded and clears wholesale at the cap.
+	 *
+	 * The polygons are DP-simplified and small, so the cap only bounds a long-lived server process.
 	 */
 	readonly #geometryCache = new Map<number, ParsedGeometry | null>()
 	static readonly #GEOMETRY_CACHE_CAP = 4096
@@ -195,8 +217,9 @@ export class WOFReverseGeocoder implements Disposable {
 
 		this.#ownsPolygons = !opts.polygonDatabase && Boolean(opts.polygonDBPath)
 
-		// Fail loudly up front — the R*Tree is a build artifact, not part of the upstream WOF
-		// distribution, and a missing index would otherwise surface as an opaque SQL error per query.
+		// Fail loudly up front.
+		// The R*Tree is a build artifact and is not part of the upstream WOF distribution,
+		// so a missing index would otherwise surface as an opaque SQL error per query.
 		if (!tableExists(this.#admin, PLACE_BBOX_TABLE)) {
 			throw new Error(
 				`WOFReverseGeocoder: the admin DB has no \`${PLACE_BBOX_TABLE}\` R*Tree. Build it with ` +
@@ -213,18 +236,25 @@ export class WOFReverseGeocoder implements Disposable {
 	}
 
 	/**
-	 * Resolve a WGS-84 point to its containing admin hierarchy. Async for symmetry with `PlaceLookup.findPlace` (the work
-	 * is sync `node:sqlite` underneath — same convention). Thin wrapper over {@link reverseGeocodeSync}.
+	 * Resolve a WGS-84 point to its containing admin hierarchy.
+	 *
+	 * Async for symmetry with `PlaceLookup.findPlace`
+	 * (the work is sync `node:sqlite` underneath, the same convention).
+	 * Thin wrapper over {@link reverseGeocodeSync}.
 	 */
 	async reverseGeocode(lat: number, lon: number, opts: ReverseGeocodeOpts = {}): Promise<ReverseGeocodeResult> {
 		return this.reverseGeocodeSync(lat, lon, opts)
 	}
 
 	/**
-	 * Synchronous core of {@link reverseGeocode} — every step underneath is already sync `node:sqlite`, so this is the
-	 * REAL implementation; the async method above exists only for call-site symmetry with `PlaceLookup.findPlace`.
-	 * Exposed directly for callers that can't await mid-call (e.g. `mailwoman/poi-executor.ts`'s `createPOIExecutor`,
-	 * whose `POIIntentOutcome` return type is synchronous by contract — see `poi-intent.ts`'s `deps.execute`).
+	 * Synchronous core of {@link reverseGeocode}.
+	 *
+	 * Every step underneath is already sync `node:sqlite`, so this is the real implementation.
+	 * The async method above exists only for call-site symmetry with `PlaceLookup.findPlace`.
+	 *
+	 * Exposed directly for callers that can't await mid-call
+	 * (e.g. `mailwoman/poi-executor.ts`'s `createPOIExecutor`, whose `POIIntentOutcome`
+	 * return type is synchronous by interface. See `poi-intent.ts`'s `deps.execute`).
 	 */
 	reverseGeocodeSync(lat: number, lon: number, opts: ReverseGeocodeOpts = {}): ReverseGeocodeResult {
 		if (
@@ -239,8 +269,9 @@ export class WOFReverseGeocoder implements Disposable {
 		const maxApproximateKm = opts.maxApproximateKm ?? DEFAULT_MAX_APPROXIMATE_KM
 		const candidates = this.#bboxCandidates(lat, lon, opts)
 
-		// PIP walk, smallest-bbox-first: the first polygon that contains the point is the deepest
-		// polygon-confirmable place. Polygon-rejected candidates are bbox false positives — dropped.
+		// PIP walk, smallest-bbox-first.
+		// The first polygon that contains the point is the deepest polygon-confirmable place.
+		// Drop candidates whose bounding boxes match but whose polygons reject the point.
 		let winner: CandidateRow | null = null
 		let winnerConfirmed = false
 		const pointOnly: CandidateRow[] = []
@@ -261,7 +292,7 @@ export class WOFReverseGeocoder implements Disposable {
 		}
 
 		if (!winner) {
-			// No polygon confirmed anywhere — nearest centroid among the polygon-less bbox candidates.
+			// No polygon confirmed anywhere, so take the nearest centroid among the polygon-less bbox candidates.
 			let bestKm = Infinity
 
 			for (const c of pointOnly) {
@@ -302,7 +333,7 @@ export class WOFReverseGeocoder implements Disposable {
 					break
 				}
 
-				if (contains === false) continue // known not-here — polygon rejected
+				if (contains === false) continue // known not-here, polygon rejected
 				const km = haversineKm(lat, lon, k.lat, k.lon)
 
 				if (km <= maxApproximateKm && km < bestKm) {
@@ -318,12 +349,13 @@ export class WOFReverseGeocoder implements Disposable {
 				currentConfirmed = nextConfirmed
 				currentDistanceKm = nextKm
 			}
-			// An empty tier is NOT terminal — counties without localadmins jump straight to locality.
+			// An empty tier is not terminal.
+			// Counties without localadmins jump straight to locality.
 		}
 
-		// Hierarchy assembly via the shared ancestor walk. If the descent crossed an ancestry gap
-		// (the deepest place's recorded lineage misses the PIP root), merge the root's own chain so
-		// region/country are always present when a polygon confirmed them.
+		// Hierarchy assembly via the shared ancestor walk.
+		// If the descent crossed an ancestry gap (the deepest place's recorded lineage misses the PIP root),
+		// merge the root's own chain so region/country are always present when a polygon confirmed them.
 		const byID = new Map<number, PlaceCandidate>([[current.id, toPlaceCandidate(current, currentDistanceKm)]])
 
 		for (const a of ancestorLineage(this.#admin, current.id)) {
@@ -395,9 +427,12 @@ export class WOFReverseGeocoder implements Disposable {
 	}
 
 	/**
-	 * Descendants of `parentID` at one placetype tier, pre-filtered to a centroid window around the query point (a
-	 * generous 4× the approximate cap — polygon-holding children may legitimately have far centroids, e.g. a sprawling
-	 * consolidated city; the precise cap is applied per-candidate in the caller, and only to centroid-fallback steps).
+	 * Descendants of `parentID` at one placetype tier, pre-filtered to a centroid window
+	 * around the query point (a generous 4× the approximate cap, since polygon-holding
+	 * children may legitimately have far centroids, e.g. a sprawling consolidated city).
+	 *
+	 * The caller applies the precise cap per candidate.
+	 * It limits centroid-fallback steps only.
 	 */
 	#descendants(
 		parentID: number,
@@ -439,7 +474,8 @@ export class WOFReverseGeocoder implements Disposable {
 		}
 
 		const row = this.#polygons.prepare(`SELECT geom FROM polygons WHERE id = ?`).get(id) as { geom: string } | undefined
-		// Malformed row parses to null — treat as no-polygon rather than failing the query.
+		// Malformed row parses to null.
+		// Treat it as no-polygon so the query does not fail.
 		const geometry = row ? tryParsingJSON<ParsedGeometry>(row.geom) : null
 
 		this.#geometryCache.set(id, geometry)

package/lib/schema.ts

@@ -3,22 +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
  */
 
 /**
- * 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 {
@@ -29,16 +30,19 @@ export interface PlaceSearchTable {
 }
 
 /**
- * `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
@@ -63,15 +67,21 @@ export interface SprTable {
 }
 
 /**
- * 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 concatenates all names per id.
  *
- * No `kind` column in real WOF — the FTS build just concatenates ALL names per id.
+ * `official` marks a preferred-form name in an official language of the place's country.
+ * This column appears only in unified builds.
  *
- * `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.
+ * 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
@@ -90,8 +100,11 @@ export interface NamesTable {
 }
 
 /**
- * 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
@@ -103,8 +116,10 @@ export interface GeojsonTable {
 }
 
 /**
- * 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
@@ -114,9 +129,14 @@ export interface AncestorsTable {
 }
 
 /**
- * `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
@@ -124,8 +144,10 @@ export interface PlacePopulationTable {
 }
 
 /**
- * `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
@@ -133,8 +155,11 @@ export interface PlaceAbbrTable {
 }
 
 /**
- * `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
@@ -144,9 +169,12 @@ export interface ConcordancesTable {
 }
 
 /**
- * `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
@@ -158,14 +186,18 @@ export interface CoincidentRolesTable {
 }
 
 /**
- * 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 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.
  */
 /**
- * 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 provenance row every built extract includes: source fingerprints stored with
+ * the database rather than in a document that can drift from it.
+ *
+ * Written by the postcode builders in `mailwoman/gazetteer-pipeline`.
  */
 export interface ExtractMetaTable {
 	key: string