@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/lib/search-fetch.ts

@@ -3,43 +3,52 @@
  * @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 type { DatabaseClient, SQLInputValue } from "@mailwoman/sqlite/client"
 
-import { PLACE_BBOX_TABLE, PLACE_POPULATION_TABLE } from "#fts/index"
+import { PLACE_BBOX_TABLE, PLACE_POPULATION_TABLE } from "#fts"
 import type { RankingWeights } from "#ranking-weights"
 import type { FindPlaceQuery, WOFPlacetype } from "#types"
 /**
- * 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
 
@@ -49,27 +58,31 @@ export interface RawSearchRow {
 	placetype: string
 	country: string | null
 	parent_id: number | null
-	rank: number // BM25 (lower = better in SQLite); we negate to get higher-is-better
+	rank: number // BM25 (lower = better in SQLite). We negate to get higher-is-better
 	lat: number | null
 	lon: number | null
 	min_latitude: number | null
 	max_latitude: number | null
 	min_longitude: number | null
 	max_longitude: number | null
-	population: number | null // from the place_population aux table; null when missing
+	population: number | null // from the place_population aux table. null when missing
 	/**
-	 * 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 function fetchSearchRows<DB>(options: {
 	db: DatabaseClient<DB>
@@ -96,23 +109,26 @@ export function fetchSearchRows<DB>(options: {
 		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: string[] = ["place_search MATCH ?", "spr.is_current != 0", "spr.is_deprecated = 0"]
 	const params: SQLInputValue[] = [ftsQuery]
 
@@ -131,23 +147,27 @@ export function fetchSearchRows<DB>(options: {
 		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
@@ -158,31 +178,32 @@ export function fetchSearchRows<DB>(options: {
 		? `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,
@@ -213,12 +234,13 @@ export function fetchSearchRows<DB>(options: {
 
 	const rawRows = allRows<RawSearchRow>(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/lib/sqlite/convention-source.ts

@@ -2,46 +2,40 @@
  * @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 { tryParsingJSON } from "@mailwoman/core/json"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { ADDRESS_CONVENTION_TABLE, type Convention, type ConventionSource } from "#convention/index"
+import { ADDRESS_CONVENTION_TABLE, 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 class SqliteConventionSource<DB> implements ConventionSource {
 	readonly #db: DatabaseClient<DB>
 	readonly #schema: string
-	/**
-	 * Memoize per-id lookups (including misses, as `null`) so a hot ancestor chain is queried once.
-	 */
+
 	readonly #cache = new Map<number, Convention | null>()
 
 	/**
-	 * @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) {
 		this.#db = db
 		this.#schema = schema
 	}
 
-	get(wofID: number): Convention | undefined {
+	get(wofID: number): Convention | null {
 		const cached = this.#cache.get(wofID)
 
-		if (cached !== undefined) return cached ?? undefined
+		if (cached !== undefined) return cached
 		let value: Convention | null = null
 
 		try {
@@ -53,13 +47,11 @@ export class SqliteConventionSource<DB> implements ConventionSource {
 				value = tryParsingJSON<Convention>(row.convention)
 			}
 		} catch {
-			// A missing table → treat as no override (the chain falls back to WORLD_DEFAULT); malformed
-			// JSON already nulls out above. The build script validates structure, so this is purely defensive.
 			value = null
 		}
 
 		this.#cache.set(wofID, value)
 
-		return value ?? undefined
+		return value
 	}
 }

package/lib/sqlite/utils.ts

@@ -2,25 +2,22 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   Small shared helpers for the SQLite-backed lookups.
+ * @file Shared helpers for the SQLite-backed lookups.
  */
 
 import { allRows, getRow } from "@mailwoman/core/utils"
 import type { DatabaseClient, SQLInputValue } from "@mailwoman/sqlite/client"
 import { hasColumn as columnExists, tableExists } from "@mailwoman/sqlite/introspection"
 
-// The row-shape assertion itself lives in `core` so the readers that cannot depend on this package reach the same
-// helper; re-exported here because this module is where this package's readers already look for it.
-
 /**
- * A prepared single-row query whose parameter tuple remains visible to TypeScript. `StatementSync` accepts only the
- * broad `SQLInputValue[]`, which otherwise erases tagged key types before they reach SQLite.
+ * A prepared single-row query whose parameter tuple stays visible to TypeScript.
+ *
+ * `StatementSync` accepts any `SQLInputValue[]`, which would erase tagged key types at the call site.
  */
-export type PreparedGet<Parameters extends SQLInputValue[], Row> = (...parameters: Parameters) => Row | undefined
+export type PreparedGet<Parameters extends SQLInputValue[], Row> = (...parameters: Parameters) => Row | null
 
 /**
- * Prepare a single-row query while preserving its exact parameter tuple at every call site.
+ * Prepares a single-row query with a typed parameter tuple.
  */
 export function prepareGet<Parameters extends SQLInputValue[], Row, DB>(
 	db: DatabaseClient<DB>,
@@ -32,12 +29,12 @@ export function prepareGet<Parameters extends SQLInputValue[], Row, DB>(
 }
 
 /**
- * Multi-row counterpart to {@link PreparedGet}.
+ * The multi-row counterpart to {@link PreparedGet}.
  */
 export type PreparedAll<Parameters extends SQLInputValue[], Row> = (...parameters: Parameters) => Row[]
 
 /**
- * Prepare a multi-row query while preserving its exact parameter tuple at every call site.
+ * Prepares a multi-row query with a typed parameter tuple.
  */
 export function prepareAll<Parameters extends SQLInputValue[], Row, DB>(
 	db: DatabaseClient<DB>,
@@ -49,10 +46,11 @@ export function prepareAll<Parameters extends SQLInputValue[], Row, DB>(
 }
 
 /**
- * True when `name` is a table in the open database. The street-level lookups use this to degrade gracefully on an
- * empty/tableless extract — an interrupted `build-*-extract.ts`, or a stray 0-byte file (e.g. `sqlite3 <missing>.db
- * "…"` CREATES one) — rather than throwing `no such table` at construction and taking down a whole state's geocode
- * (#568). A missing table makes the lookup a no-op miss.
+ * Returns true when `name` is a table in the open database.
+ * Returns false when the check itself fails.
+ *
+ * The street-level lookups call it so that an empty extract, such as an interrupted build
+ * or a zero-byte file, makes every lookup miss instead of throwing `no such table`.
  */
 export function hasTable<DB>(db: DatabaseClient<DB>, name: string): boolean {
 	try {
@@ -63,15 +61,14 @@ export function hasTable<DB>(db: DatabaseClient<DB>, name: string): boolean {
 }
 
 /**
- * True when `table` exists in the open database AND carries `column`.
+ * Returns true when `table` exists in the open database and has `column`.
  *
- * The column-level sibling of {@link hasTable}, and it exists for the same reason one layer down: an artifact built
- * before a column was added is still a VALID artifact, and a reader that unconditionally names the new column in its
- * `SELECT` turns "this gazetteer is a build behind" into `no such column` at the first keystroke. Probe once at
- * construction and shape the query — `table_info` is a PRAGMA, so it must not sit on a per-query path.
+ * An artifact built before a column was added is still valid, so readers call this once
+ * at construction and leave the column out of their queries when it is missing.
+ * Avoid calling it per query, because it runs a pragma.
  *
- * Note the interpolation: PRAGMA does not take bound parameters, so `table` is spliced. Every caller passes a
- * module-level constant; never pass user input.
+ * The pragma does not accept bound parameters, so `table` is interpolated into the SQL.
+ * Pass only constants.
  */
 export function hasColumn<DB>(db: DatabaseClient<DB>, table: string, column: string): boolean {
 	try {

package/lib/street/centroid/schema.ts

@@ -3,21 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Typed schema for the DERIVED STREET-CENTROID extract (`street-centroids-<cc>.db`, built by
- *   `ban/scripts/build-street-centroid-extract.ts` — the #1042 street-level tier behind "street-only
- *   FR queries deserve a street-level answer"). The extract is a `GROUP BY street` roll-up of the
- *   sealed rooftop address-point extract: one row per (street, postcode, commune) carrying the street's
- *   CENTROID + bounding-box EXTENT + member-point count. No new data source — a derived artifact.
- *
- *   Single source of truth for the columns shared by the BUILDER (a positional prepared INSERT for
- *   throughput) and the READER ({@link StreetCentroidSqliteLookup}), so a column rename in one is a
- *   compile error in the other — the same discipline as `address-point-schema.ts`.
- *
- *   Probe scopes (most-selective first): by `postcode`, else by `locality_base` (the
- *   arrondissement-stripped commune — see `stripArrondissement`; BAN names Paris/Lyon/Marseille rows
- *   per arrondissement, but a query names the base commune). The reader WEIGHTED-aggregates across the
- *   matched rows (by `point_count`) so a locality-scope probe returns the street's grand centroid over
- *   every postcode/arrondissement it spans.
+ *   Schema for the street-centroid extract. It groups address-point rows by street.
  */
 
 import type { Kysely } from "kysely"
@@ -25,30 +11,36 @@ import type { Kysely } from "kysely"
 import type { NameKey, StreetKey } from "#street/normalize"
 
 /**
- * One street roll-up. `(street_norm, postcode, locality_base)` is unique. `lat`/`lon` are the UNWEIGHTED mean of the
- * group's member address points (each source row = one point), so a cross-group weighted mean (`SUM(lat*point_count) /
- * SUM(point_count)`) reconstructs the grand centroid. `min_/max_lat/lon` are the group's extent (the reader turns the
- * bbox diagonal into an honest `uncertainty_m`).
+ * One row per street, postcode and commune.
+ *
+ * The tuple `(street_norm, postcode, locality_base)` is unique.
+ * The reader combines rows by `SUM(lat * point_count) / SUM(point_count)` to get a
+ * street's centroid across every postcode and arrondissement it spans.
+ *
+ * It converts the bounding-box diagonal from the `min_*` and `max_*` columns into `uncertainty_m`.
  */
 export interface StreetCentroidTable {
 	/**
-	 * Shared `normalizeStreetForKeyLocale` of the street — the build/query-consistent probe key.
+	 * The street key from `normalizeStreetForKeyLocale`, which both the builder and the reader use.
 	 */
 	street_norm: StreetKey
 	/**
-	 * The 5-digit postcode of this group, or null when the source row carried none.
+	 * The postcode of this group, or null when the source row has none.
 	 */
 	postcode: string | null
 	/**
-	 * Arrondissement-stripped commune (`stripArrondissement(normalizeLocalityForKey(commune))`) — the fallback scope.
+	 * The commune key with any arrondissement removed.
+	 *
+	 * BAN stores Paris, Lyon and Marseille per arrondissement, but a query usually gives the base commune.
+	 * The reader uses this column when the query has no postcode.
 	 */
 	locality_base: NameKey
 	/**
-	 * Weighted-mean centroid latitude of the street's member points.
+	 * The mean latitude of the group's member address points.
 	 */
 	lat: number
 	/**
-	 * Weighted-mean centroid longitude of the street's member points.
+	 * The mean longitude of the group's member address points.
 	 */
 	lon: number
 	min_lat: number
@@ -56,31 +48,32 @@ export interface StreetCentroidTable {
 	min_lon: number
 	max_lon: number
 	/**
-	 * Member address-point count — the weight for a cross-group centroid aggregate.
+	 * The number of member address points.
+	 * This value weights the cross-row centroid.
 	 */
 	point_count: number
 	/**
-	 * A representative street name as it appeared in the source (display / debugging).
+	 * One street name as it appeared in the source, kept for display and debugging.
 	 */
 	street_raw: string
 	/**
-	 * Provenance: the register this street was derived from (e.g. `ban:fr`).
+	 * The source register, such as `ban:fr`.
 	 */
 	source: string
 	/**
-	 * The pinned data release the underlying points came from.
+	 * The data release that the member points came from.
 	 */
 	release: string
 	/**
-	 * #727 phase-4c: `foldStreetSurface(street_raw)` — the contract-fold street-NAME existence key for
-	 * {@link StreetLocalityEvidence}. Distinct from `street_norm` (the `street-normalize` geocoding key): the
-	 * name-evidence rerank folds the model's street surface with the SAME `foldStreetSurface` used to build this column
-	 * (the fold-parity contract), so it must not drift from `street_norm`'s richer normalizer. Indexed (`idx_sc_name`)
-	 * for a direct seek.
+	 * The value of `foldStreetSurface(street_raw)`, used by {@link StreetLocalityEvidence}
+	 * to check that a street name exists.
+	 *
+	 * The name-evidence rerank folds the model's street text with the same function, so this
+	 * column must use `foldStreetSurface` and must not follow the `street_norm` normalizer.
+	 * The type is a plain string because `foldStreetSurface` differs from the
+	 * {@link NameKey} fold that other `name_key` columns use.
 	 *
-	 * Deliberately UNBRANDED despite the `name_key` column name: `foldStreetSurface` is a different fold from the
-	 * {@link NameKey} one every other `name_key` column carries, and giving it that brand would invite exactly the
-	 * cross-fold probe the brands exist to stop.
+	 * A `NameKey` type would allow a probe with the wrong fold.
 	 */
 	name_key: string
 }
@@ -93,8 +86,9 @@ export interface StreetCentroidDatabase {
 }
 
 /**
- * The `street_centroid` 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_centroid` columns in insert order.
+ *
+ * The builder derives the placeholders of its positional insert from this list.
  */
 export const STREET_CENTROID_COLUMNS = [
 	"street_norm",
@@ -114,7 +108,7 @@ export const STREET_CENTROID_COLUMNS = [
 ] as const
 
 /**
- * Create the `street_centroid` table — called before the streaming bulk load.
+ * Creates the `street_centroid` table before the bulk load.
  */
 export async function createStreetCentroidTable(db: Kysely<StreetCentroidDatabase>): Promise<void> {
 	await db.schema
@@ -137,9 +131,10 @@ export async function createStreetCentroidTable(db: Kysely<StreetCentroidDatabas
 }
 
 /**
- * Create the probe indexes: the two geocoding-scope indexes (postcode, locality-base) the resolver reader relies on,
- * plus `idx_sc_name` — the #727 phase-4c name-existence key for a direct `name_key = ?` seek (the unscoped fragment
- * lookup; without it that query skip-scans `idx_sc_postcode` at ~5 ms/probe).
+ * Creates the postcode and locality indexes that the reader probes, plus `idx_sc_name`.
+ *
+ * The `idx_sc_name` index serves the unscoped `name_key = ?` lookup.
+ * Without it, SQLite would skip-scan `idx_sc_postcode`.
  */
 export async function createStreetCentroidIndexes(db: Kysely<StreetCentroidDatabase>): Promise<void> {
 	await db.schema.createIndex("idx_sc_postcode").on("street_centroid").columns(["postcode", "street_norm"]).execute()