@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/lib/street/segment-schema.ts

@@ -3,43 +3,49 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Typed schema for the TIGER STREET-SEGMENT interpolation extracts (`street-segments-<cc>-<st>.db`,
- *   built by `scripts/build-interpolation-extract.ts` from TIGER EDGES) — the #483 Method-3 fallback
- *   the resolver drops to when the address-point tier (Method 2) can't bracket. Single source of
- *   truth for the columns the BUILDER writes and the READER ({@link StreetInterpolator}) probes, so
- *   a column rename in one is a compile error in the other.
- *
- *   The builder reads geometry from shapefiles via DuckDB's spatial extension (raw `ST_Read` — see
- *   AGENTS.md "Database / inline SQL") and writes here through `node:sqlite`. The hot positional
- *   INSERT (a county's worth of edges) stays raw; its column list is derived from
- *   {@link STREET_SEGMENT_COLUMNS} so it can't drift from the DDL.
+ *   Typed schema for the tiger street-segment interpolation extracts (`street-segments-<cc>-<st>.db`,
+ *   built by `scripts/build-interpolation-extract.ts` from tiger edges). This is the Method-3
+ *   fallback the resolver drops to when the address-point tier (Method 2) cannot bracket. It is the
+ *   definition of the columns the builder writes and the reader ({@link StreetInterpolator}) probes,
+ *   so a column rename in one is a compile error in the other.
+ *
+ *   The builder reads geometry from shapefiles via DuckDB's spatial extension (raw `ST_Read`, see
+ *   agents.md "Database / inline SQL") and writes here through `node:sqlite`. The hot positional
+ *   insert (a county's worth of edges) stays raw. Its column list derives from
+ *   {@link STREET_SEGMENT_COLUMNS} so it cannot drift from the DDL.
  */
 
-import type { Kysely } from "kysely"
+import { type Kysely, sql } from "kysely"
 
 import type { RouteKey } from "#street/normalize"
 
 /**
- * One TIGER street-segment edge: a `(from_hn, to_hn)` house-number range on one `side` of a named street, with the
- * geometry the interpolator walks. `min_hn`/`max_hn` are the sorted bounds (the probe filters on them); `parity` is
- * `odd`/`even`/`mixed`.
+ * One tiger street-segment edge: a `(from_hn, to_hn)` house-number range on one `side`
+ * of a street with a name, with the geometry the interpolator walks.
+ *
+ * `min_hn`/`max_hn` are the sorted bounds used by the probe.
+ * `parity` is `odd`, `even`, or `mixed`.
  */
 export interface StreetSegmentTable {
 	/**
-	 * `canonicalizeRouteKey(normalizeStreetForKey(street))` — the build/query-consistent probe key. The column NAME says
-	 * `street_norm`, but the value carries the route fold on top of the street fold, which is why the brand is
-	 * {@link RouteKey}: builder and probe both apply both folds, and a plain street key bound here misses every
-	 * numbered-route row.
+	 * `canonicalizeRouteKey(normalizeStreetForKey(street))`, the build/query-consistent probe key.
+	 *
+	 * The column name is `street_norm`, but the value includes the route fold on top of the street fold.
+	 * The value therefore uses the {@link RouteKey} brand.
+	 *
+	 * The builder and probe apply both folds.
+	 * A plain street key bound here misses every numbered-route row.
 	 */
 	street_norm: RouteKey
 	/**
-	 * `L` or `R` — the TIGER side the address range sits on.
+	 * `L` or `R`, the tiger side the address range sits on.
 	 */
 	side: string
 	from_hn: number
 	to_hn: number
 	/**
-	 * Sorted lower bound of `(from_hn, to_hn)` — the probe filters `min_hn <= n <= max_hn`.
+	 * Sorted lower bound of `(from_hn, to_hn)`.
+	 * The probe filters `min_hn <= n <= max_hn`.
 	 */
 	min_hn: number
 	/**
@@ -47,7 +53,7 @@ export interface StreetSegmentTable {
 	 */
 	max_hn: number
 	/**
-	 * `odd` | `even` | `mixed` — the house-number parity along the range.
+	 * `odd`, `even` or `mixed`, the house-number parity along the range.
 	 */
 	parity: string
 	postcode: string | null
@@ -56,11 +62,12 @@ export interface StreetSegmentTable {
 	 */
 	county_fips: string
 	/**
-	 * The street as it appeared in TIGER (kept for display / debugging).
+	 * The street as it appeared in tiger (kept for display / debugging).
 	 */
 	street_raw: string
 	/**
-	 * GeoJSON LineString text (no SpatiaLite — read back with `JSON.parse`).
+	 * GeoJSON LineString text without SpatiaLite.
+	 * Read back with `JSON.parse`.
 	 */
 	geometry: string
 	/**
@@ -68,21 +75,27 @@ export interface StreetSegmentTable {
 	 */
 	source: string
 	/**
-	 * The pinned TIGER release the edge was ingested from.
+	 * The pinned tiger release the edge was ingested from.
 	 */
 	release: string
 }
 
 /**
- * The extract's single-row calibration metadata (#374 doctrine, 2026-07-26): the conformal radius multiplier is a
- * property of the CALIBRATION SET the artifact was built against — so it ships IN the artifact (the pair-index δ
- * precedent, `neural/pair-index-resolver.ts`), not in caller code. Written once by the builder; read at open time by
- * {@link StreetInterpolator}. Extracts built before this table exists simply lack it — the reader degrades to
- * `undefined` and callers fall back to the in-code per-region table (never patch shipped DBs — rebuild).
+ * The extract's single-row calibration metadata: the conformal radius multiplier
+ * is a property of the calibration set the artifact was built against,
+ * so it ships in the artifact rather than in caller code.
+ *
+ * See the pair-index precedent in `neural/pair-index-resolver.ts`.
+ *
+ * The builder writes this table once. {@link StreetInterpolator} reads it when opening the database.
+ *
+ * Extracts built before this table exists lack it.
+ * The reader degrades to `undefined`, and callers fall back to the in-code per-region table.
+ * Shipped DBs are rebuilt rather than patched.
  */
 export interface InterpCalibrationRow {
 	/**
-	 * Conformal multiplier for the raw half-segment `uncertainty_m` radius (#374/#584) — ×Q̂ for a ~90% bound.
+	 * Conformal multiplier for the raw half-segment `uncertainty_m` radius, ×Q̂ for a ~90% bound.
 	 */
 	radius_multiplier: number
 	/**
@@ -90,7 +103,8 @@ export interface InterpCalibrationRow {
 	 */
 	method: string
 	/**
-	 * The calibration-table key the multiplier was selected by (a USPS region code, or `default` for unmeasured).
+	 * The calibration-table key the multiplier was selected by
+	 * (a USPS region code, or `default` for unmeasured).
 	 */
 	region: string
 }
@@ -104,8 +118,10 @@ export interface StreetSegmentDatabase {
 }
 
 /**
- * The `street_segment` columns in INSERT order. The builder's positional prepared statement derives its placeholder
- * list from this, so the positional order can't drift from the DDL / the reader.
+ * The `street_segment` columns in insert order.
+ *
+ * The builder's positional prepared statement derives its placeholder list from this,
+ * so the positional order can't drift from the DDL / the reader.
  */
 export const STREET_SEGMENT_COLUMNS = [
 	"street_norm",
@@ -124,11 +140,20 @@ export const STREET_SEGMENT_COLUMNS = [
 ] as const
 
 /**
- * Create the `street_segment` table — called before the streaming bulk load.
+ * The staging table the builder bulk-loads in source order before {@link clusterStreetSegments}
+ * copies its rows into `street_segment` in probe-key order.
+ */
+export const STREET_SEGMENT_STAGE_TABLE = "street_segment_stage"
+
+/**
+ * Create the `street_segment` table, or the staging table with the same columns.
  */
-export async function createStreetSegmentTable(db: Kysely<StreetSegmentDatabase>): Promise<void> {
+export async function createStreetSegmentTable(
+	db: Kysely<StreetSegmentDatabase>,
+	table: "street_segment" | typeof STREET_SEGMENT_STAGE_TABLE = "street_segment"
+): Promise<void> {
 	await db.schema
-		.createTable("street_segment")
+		.createTable(table)
 		.addColumn("street_norm", "text", (c) => c.notNull())
 		.addColumn("side", "text", (c) => c.notNull())
 		.addColumn("from_hn", "integer", (c) => c.notNull())
@@ -146,10 +171,13 @@ export async function createStreetSegmentTable(db: Kysely<StreetSegmentDatabase>
 }
 
 /**
- * Create + populate the single-row `interp_calibration` metadata table (see {@link InterpCalibrationRow}) — called once
- * by the extract builder, after the value is selected from the calibration source of record. Build-time only (async
- * Kysely is fine here); the READ side is the raw sync probe in {@link StreetInterpolator}'s constructor, per the
- * sync-by-interface doctrine.
+ * Create and populate the single-row `interp_calibration` metadata table (see {@link InterpCalibrationRow}).
+ *
+ * Called once by the extract builder, after the value is selected from the calibration source of record.
+ *
+ * Build-time only, so async Kysely is fine here.
+ * The read side is the raw sync probe in {@link StreetInterpolator}'s constructor,
+ * per the sync-by-interface doctrine.
  */
 export async function writeInterpCalibration(
 	db: Kysely<StreetSegmentDatabase>,
@@ -166,14 +194,59 @@ export async function writeInterpCalibration(
 }
 
 /**
- * Create the two probe indexes the reader relies on (postcode-scope, street-scope).
+ * The physical row order of `street_segment`: street first, then postcode and range.
+ *
+ * The browser reads the extract over HTTP range requests.
+ * Both probe forms fetch their matching rows from the table.
+ *
+ * In this order the postcode-scoped probe reads one contiguous run of rows.
+ * The street-only probe reads within one street's contiguous block.
+ *
+ * The staging rowid is the last key, so rows with equal keys keep their source order.
+ * The readers break span ties by that order.
+ */
+const STREET_SEGMENT_CLUSTER_ORDER = "street_norm, postcode, min_hn, max_hn, rowid"
+
+/**
+ * Copy the staged rows into `street_segment` in key order and drop the stage.
+ *
+ * The order is {@link STREET_SEGMENT_CLUSTER_ORDER}.
+ *
+ * `street_segment` stays a rowid table, because `postcode` is nullable.
+ * A `WITHOUT ROWID` primary key forbids a null column.
+ * A load in key order gives the same page locality.
+ *
+ * Run {@link createStreetSegmentIndexes} and `VACUUM` afterwards.
+ */
+export async function clusterStreetSegments(db: Kysely<StreetSegmentDatabase>): Promise<void> {
+	const columns = STREET_SEGMENT_COLUMNS.join(", ")
+
+	await sql
+		.raw(
+			`INSERT INTO street_segment (${columns}) SELECT ${columns} FROM ${STREET_SEGMENT_STAGE_TABLE} ORDER BY ${STREET_SEGMENT_CLUSTER_ORDER}`
+		)
+		.execute(db)
+
+	await db.schema.dropTable(STREET_SEGMENT_STAGE_TABLE).execute()
+}
+
+/**
+ * Create the two probe indexes the readers use (postcode-scope, street-scope).
+ *
+ * Each index holds `max_hn`.
+ * SQLite therefore rejects a range ending below the house number from the index entry.
+ * The rejected row's table page is never fetched.
  */
 export async function createStreetSegmentIndexes(db: Kysely<StreetSegmentDatabase>): Promise<void> {
 	await db.schema
 		.createIndex("idx_seg_postcode")
 		.on("street_segment")
-		.columns(["postcode", "street_norm", "min_hn"])
+		.columns(["postcode", "street_norm", "min_hn", "max_hn"])
 		.execute()
 
-	await db.schema.createIndex("idx_seg_street").on("street_segment").columns(["street_norm", "min_hn"]).execute()
+	await db.schema
+		.createIndex("idx_seg_street")
+		.on("street_segment")
+		.columns(["street_norm", "min_hn", "max_hn"])
+		.execute()
 }

package/lib/{street/index.ts → street.ts}

@@ -4,7 +4,7 @@
  * @author Teffen Ellis, et al.
  */
 
-export * from "#street/centroid/index"
+export * from "#street/centroid"
 export * from "#street/centroid/schema"
 export * from "#street/morphology/fst/builder"
 export * from "#street/morphology/fst/loader"

package/lib/types.ts

@@ -2,19 +2,12 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   Public surface for the WOF SQLite resolver — types only, no runtime.
- *
- *   These mirror the conceptual model described in `docs/plan/phases/PHASE_4_2_wof_sqlite.md`. Phase
- *   4.3 will extend `PlaceCandidate` with the resolver-decorated fields that flow into
- *   `AddressNode.source` / `sourceID` (e.g. an explicit `wofURI: "wof-admin:101751113"` form).
  */
 
+import type { LatLon, LatLonBounds } from "@mailwoman/spatial"
+
 /**
- * The placetype taxonomy used by Who's On First. Ordered roughly from coarsest (country) to finest (address). See
- * https://github.com/whosonfirst/whosonfirst-placetypes for the authoritative definitions of each.
- *
- * Phase 4.2 only emits the ones we actually look up; the union is open enough to extend later.
+ * Lists the Who's On First placetypes this resolver looks up, ordered roughly from coarsest to finest.
  */
 export type WOFPlacetype =
 	| "country"
@@ -33,222 +26,188 @@ export type WOFPlacetype =
 	| "address"
 
 /**
- * One candidate match for a place lookup.
- *
- * `score` is the post-boost ranking number — higher is better, but the scale is implementation- defined. Callers should
- * treat it as ordinal, not absolute.
- *
- * `id` is the WOF place id. It's named generically (not `wof_id`) so the shape stays structurally compatible with
- * `@mailwoman/resolver`'s `ResolvedPlace` — `WOFSQLitePlaceLookup` satisfies the generic `ResolverBackend` contract
- * without an adapter shim.
- *
- * `distanceKm` is populated only when the query carried `near` (and the place has a centroid). Useful for downstream
- * UIs that want to show "X km from you" alongside the result.
+ * Describes one ranked match for a place lookup, with `id` as the WOF id
+ * so the shape satisfies `ResolvedPlace`.
  */
 export interface PlaceCandidate {
 	id: number
 	name: string
 	placetype: WOFPlacetype
+
 	/**
-	 * ISO 3166-1 alpha-2 country code.
+	 * The ISO 3166-1 alpha-2 country code.
 	 */
 	country: string
 	lat: number
 	lon: number
-	parent_id?: number
-	score: number
-	distanceKm?: number
+
 	/**
-	 * True when this candidate's name OR an alias EXACTLY equals the query (the exact-match tier from
-	 * {@link RankingWeights.exactMatchTiering}). Surfaced so a downstream country re-rank (#369's postcode anchor in
-	 * `resolveTree`) can pin the country without crossing the tier — see the `exactMatch` field on `@mailwoman/core`'s
-	 * `ResolvedPlace`.
+	 * The place's depth-1 ancestor id from the ancestors sidecar, absent when the
+	 * artifact has no sidecar even for a place with a parent.
 	 */
-	exactMatch?: boolean
+	parent_id: number | null
+	score: number
+	distanceKm: number | null
+
 	/**
-	 * Combined prominence (population term + best proximity-bias term, same additive units) — populated by the FTS
-	 * lookup; the exact-tier sort orders by THIS instead of raw population when the query carried proximity hints
-	 * (`near`/`bias`).
+	 * Whether the candidate's name or an alias exactly equals the query, used by a
+	 * later re-rank to stay within the exact-match tier.
 	 */
-	prominence?: number
+	exactMatch: boolean | null
+
 	/**
-	 * Population from WOF's `wof:population` property. Only present when the candidate has it on record — WOF carries
-	 * population for ~15% of localities (mostly larger ones). Absent does NOT mean zero, just unknown.
+	 * The population term plus the best proximity-bias term.
+	 *
+	 * The exact tier sorts by this value instead of population when the query has `near` or `bias`.
 	 */
-	population?: number
+	prominence: number | null
+
 	/**
-	 * REFERENTIAL likelihood in [0, 1] — `referentialFromPopulation(population)`, the named form of the prominence key
-	 * this resolver has always ranked namesakes by (ROAD_TO_V9 §2, ratified 2026-08-06).
-	 *
-	 * It is a strictly-increasing function of {@link PlaceCandidate.population} below `REFERENTIAL_SATURATION_POPULATION`
-	 * and constant above it, so ordering by it — via `compareReferential`, which restores the megacity order with a
-	 * population tiebreak — is the SAME ORDER as ordering by population. That equivalence is the point: naming the
-	 * ranking key costs nothing at the ranking.
-	 *
-	 * Absent when the candidate has no population on record, exactly as {@link PlaceCandidate.population} is.
+	 * The WOF `wof:population` value, absent when the population is unknown.
 	 */
-	referential?: number
+	population: number | null
+
 	/**
-	 * STRICT encyclopedia-evidence importance in [0, 1], fan-out-guarded per #1497 — CARRIED, NEVER RANKED ON.
-	 *
-	 * RESERVED SLOT awaiting a strict-channel source: present only when a extract's `place_importance` table carries the
-	 * split columns, and no shipped extract does — the FTS lookup's clauses emit NULL for everything today. `undefined`
-	 * means either "no encyclopedia entry for this place" or "this gazetteer predates the split"; both are absence, and
-	 * neither is 0. The BLENDED prior the ranking reads is {@link PlaceCandidate.importance}.
-	 *
-	 * Saint-Denis is why this is not a ranking key: the Seine-Saint-Denis suburb (pop 96,128) scores 0.1173 while the
-	 * Aude hamlet (pop 418) scores 0.5683. Consumers that want to display salience read this; the ranking never does.
+	 * The referential likelihood in [0, 1], derived from {@link PlaceCandidate.population}
+	 * and absent whenever it is.
 	 */
-	encyclopedic?: number
+	referential: number | null
+
 	/**
-	 * BLENDED global toponym prior in [0, 1] (#28) — `candidate.importance` surfaced verbatim: the score source's legacy
-	 * blended importance (encyclopedia-derived where the concordance matched, a population-derived proxy elsewhere).
-	 * Emitted only by the candidate-table backend, and only when the artifact measured this place — absent is UNMEASURED,
-	 * never zero. Consumed by `rankByImportance` (`resolver/toponym-prior.ts`) for the bare-toponym class. See
-	 * `candidate-schema.ts` → `CandidateTable.importance` for why the blend, not the strict channel, is what ships.
+	 * The encyclopedia-evidence importance in [0, 1], used for display only and present only
+	 * when the extract's `place_importance` table has the split columns.
 	 */
-	importance?: number
+	encyclopedic: number | null
+
 	/**
-	 * Bounding box from WOF's `spr.{min,max}_{latitude,longitude}` columns. Coarse outline for the place — a city's bbox
-	 * is the city's full extent, a postcode's is roughly the postcode polygon's envelope. Optional because not all
-	 * callers ask for it; implementations are free to omit when the underlying schema lacks the columns.
+	 * The blended toponym prior in [0, 1] that `rankByImportance` reads for bare toponyms,
+	 * set only by the candidate-table backend.
 	 */
-	bbox?: GeoBbox
+	importance: number | null
+
 	/**
-	 * Set by the coordinate-first path when the chosen locality and the sibling postcode's containing locality are
-	 * geographically far apart — the postcode and the parsed city name disagree (a transposed / wrong-for-the-city
-	 * postcode). The candidate is still returned (the name wins for the locality), but the flag lets callers lower
-	 * confidence / surface the conflict rather than silently mislocate. A retrieval/BM25 geocoder can't raise this — it's
-	 * the falsehood-detection differentiator.
+	 * The bounding box from the WOF `spr` extent columns, omitted when the schema lacks them.
 	 */
-	mismatch?: boolean
+	bbox: LatLonBounds | null
+
 	/**
-	 * Admin-containment stamp (#1717 stage 2) — TRI-STATE, mirroring `ResolvedPlace.containedByQualifier` in
-	 * `@mailwoman/core`: `true` = the ancestors sidecar vouches this candidate sits under the query's
-	 * {@link FindPlaceQuery.regionQualifier}; `false` = evaluated and not vouched for; absent = never evaluated (no
-	 * qualifier on the query, or an artifact without the sidecar). Absence is required — the resolver walk reads it as
-	 * `unavailable`, never as "not contained".
+	 * Set by the postcode path when the chosen locality is far from the postcode's own
+	 * locality. the candidate is still returned so callers can lower their confidence.
 	 */
-	containedByQualifier?: boolean
+	mismatch: boolean | null
+
 	/**
-	 * The #1882 exemption's firing mark (#1893), mirroring `ResolvedPlace.variantAliasExempted` in `@mailwoman/core`:
-	 * present only when this candidate's row would have taken the cross-country alias penalty and the exemption prevented
-	 * it. Emitted by the candidate-table backend alone — the WASM FTS lookup never runs the ranker, and its candidates
-	 * omit the field (not evaluated, never "did not fire").
+	 * Whether the ancestors sidecar places this candidate under the query's
+	 * {@link FindPlaceQuery.regionQualifier}, with `false` meaning the check ran
+	 * and an absent value meaning it did not.
 	 */
-	variantAliasExempted?: true
-}
+	containedByQualifier: boolean | null
 
-/**
- * A WGS-84 lat/lon point. Used as a proximity hint for `FindPlaceQuery.near`.
- */
-export interface GeoPoint {
-	lat: number
-	lon: number
-}
+	/**
+	 * Set when the candidate lies outside the query's parent scope, so callers can demote it.
+	 */
+	regionScopeMiss: boolean | null
 
-/**
- * A WGS-84 bounding box. Used as a hard filter via `FindPlaceQuery.bbox`.
- */
-export interface GeoBbox {
-	minLat: number
-	maxLat: number
-	minLon: number
-	maxLon: number
+	/**
+	 * Set when the variant exemption spared the candidate from the cross-country
+	 * alias penalty, by the candidate-table backend only.
+	 */
+	variantAliasExempted: true | null
 }
 
 /**
- * Query against the resolver.
- *
- * `text` is the only required field; everything else narrows the search. When `country` and `parentID` are both set,
- * `parentID` wins (it's more specific).
- *
- * `near` and `bbox` are independent. `near` is a soft signal — candidates close to the point get a ranking boost but
- * distant candidates aren't dropped. `bbox` is a hard filter — only candidates whose bbox intersects the query bbox are
- * returned (uses the package-built R*Tree index when present; if the index is missing the option is silently ignored to
- * preserve backwards compatibility).
+ * Describes a place lookup.
  *
- * `near` may carry `maxDistanceKm` to escalate from a boost to a hard filter — candidates further than that distance
- * from the point are dropped at the SQL level via an R*Tree pre-filter.
+ * Every field except `text` narrows or ranks the search.
+ * An extract without the R*Tree index ignores `bbox` and `near.maxDistanceKm` without an error.
  */
 export interface FindPlaceQuery {
 	text: string
 	placetype?: WOFPlacetype | WOFPlacetype[]
+
 	/**
-	 * ISO 3166-1 alpha-2 — narrows to one country.
+	 * Restricts matches to one ISO 3166-1 alpha-2 country.
 	 */
 	country?: string
+
 	/**
-	 * ISO 3166-1 alpha-2 — narrows the TYPO-FUZZY tier only (#1585). Exact and qualifier-strip probes stay worldwide (a
-	 * locale hint is a prior, never a hard filter on exact matches), but a typo CORRECTION into a different country's
-	 * namespace is nearly always a scrape, so the corrected-key probes honor this scope and a scoped-empty ABSTAINS
-	 * rather than falling through to a world-fuzzy candidate. Ignored when `country` is set (already narrower).
+	 * Restricts the typo-fuzzy tier to one ISO 3166-1 alpha-2 country, returning no
+	 * result on a miss rather than falling back worldwide.
+	 * Ignored when `country` is set.
 	 */
 	fuzzyCountry?: string
+
 	/**
-	 * Restrict name matching to PRIMARY-keyed rows (#1632) — set by probes whose surface is a RE-READING (a token taken
-	 * out of a longer classified span), which never named an alias. See the ResolverBackend contract in
-	 * `@mailwoman/core/resolver`.
+	 * Whether to match only primary names, set by probes that re-read a token from
+	 * a longer span because that token was never an alias.
 	 */
 	primaryOnly?: boolean
+
 	/**
-	 * Alias-row NAME ROLES the probe refuses to answer through (#1730) — the bare-toponym side races pass `abbr`/`gloss`.
-	 * Role-NULL alias rows (the exonym tier) stay open; backends/artifacts without a role column ignore it.
+	 * Alias name roles, such as `abbr` or `gloss`, that the probe excludes.
+	 *
+	 * Rows with no role and artifacts without a role column are unaffected.
 	 */
 	excludeNameRoles?: readonly string[]
+
 	/**
-	 * WOF place id — narrows to descendants of this place.
+	 * Restricts matches to descendants of this WOF place id.
 	 */
 	parentID?: number
+
 	/**
-	 * Sibling postcode. When set on a `locality` query AND a `postcode_locality` table is present, triggers the
-	 * coordinate-first soft-score path: postcode→candidate localities are injected and scored `0.6·S_pc + 0.3·S_name +
-	 * 0.1·S_pop` against the FTS name-match set, recovering small localities the name-match alone misses. Ignored when no
-	 * postcode_locality extract is present.
+	 * The sibling postcode for a `locality` query.
+	 *
+	 * A `postcode_locality` table adds that postcode's localities and scores them on a
+	 * weighted blend so small localities a name match misses are found.
 	 */
 	postcode?: string
+
 	/**
-	 * Postcode-containment coherence (#31, Mechanism 2) — when true on a locality query that also carries `postcode`,
-	 * candidate rows within `POSTCODE_CONTAINMENT_THRESHOLD_KM` of the postcode's own centroid sort by distance first,
-	 * the rest appended in their original order. Set by the resolver from `ResolveOpts.postcodeContainmentCoherence`;
-	 * absent → the population-first order is untouched (byte-identical).
+	 * Whether a locality query with `postcode` moves candidates near the postcode's centroid
+	 * to the front, sorted by distance, with the rest keeping their order.
 	 */
 	postcodeContainmentCoherence?: boolean
+
 	/**
-	 * The tree's parsed REGION qualifier (#1717 stage 2) — set by the resolver on locality lookups when
-	 * `ResolveOpts.adminContainmentRerank` is on. See the `ResolverBackend` contract in `@mailwoman/core/resolver`: a
-	 * capable backend stamps `containedByQualifier`, ranks contained candidates first, and may ADD contained same-key
-	 * candidates a country scope hid — additive only, never a filter. Ignored on an artifact without the ancestors
-	 * sidecar (candidates then carry no stamp).
+	 * The parsed region qualifier for a locality lookup.
+	 *
+	 * A backend with the ancestors sidecar marks contained candidates.
+	 * It ranks them first.
+	 *
+	 * It may add candidates hidden by a country scope.
+	 * It never removes candidates.
 	 */
 	regionQualifier?: string
+
 	/**
-	 * Proximity hint — candidates close to this point get a ranking boost.
+	 * A proximity hint that boosts nearby candidates and filters by radius only when `maxDistanceKm` is set.
 	 */
-	near?: GeoPoint & { maxDistanceKm?: number }
+	near?: LatLon & { maxDistanceKm?: number }
+
 	/**
-	 * Ordered proximity-bias points (viewport center, user location, …), each optionally weighted (default 1.0, first
-	 * entry strongest by convention). SOFT — a re-rank signal, never a filter: with bias present, exact-tier candidates
-	 * order by combined prominence (population + the best decayed-distance term over these points) instead of population
-	 * alone, which is how an ambiguous bare postcode ("48026": Fraser MI vs Russi IT) follows the map view / the user.
-	 * Absent (and no `near`) → ranking is byte-identical to today. `near` is treated as a weight-1.0 bias point for
-	 * back-compat.
+	 * Ordered proximity-bias points with an optional weight defaulting to 1.
+	 *
+	 * The bias re-ranks exact-tier candidates by combined prominence.
+	 * It keeps every candidate.
+	 * It counts `near` as weight 1.
 	 */
-	bias?: Array<GeoPoint & { weight?: number }>
+	bias?: Array<LatLon & { weight?: number }>
+
 	/**
-	 * Bounding-box filter — only candidates whose bbox intersects this box are returned.
+	 * Returns only candidates whose bounding box intersects this box.
 	 */
-	bbox?: GeoBbox
+	bbox?: LatLonBounds
+
 	/**
-	 * Default 10.
+	 * The maximum number of candidates to return, defaulting to 10.
 	 */
 	limit?: number
 }
 
 /**
- * The pull-based lookup surface. Implementations resolve a `FindPlaceQuery` to a ranked list of `PlaceCandidate`s. The
- * interface is async even though `node:sqlite` is sync — leaves room for `Worker`-backed implementations later without
- * a public API break.
+ * Resolves a {@link FindPlaceQuery} to ranked {@link PlaceCandidate}s, asynchronously
+ * so a worker-backed implementation can share the interface.
  */
 export interface PlaceLookup extends Disposable {
 	findPlace(query: FindPlaceQuery): Promise<PlaceCandidate[]>