@mailwoman/resolver-wof-sqlite 7.2.0 → 7.3.0

package/schema.ts

@@ -0,0 +1,176 @@
+/**
+ * @copyright Sister Software
+ * @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.
+ *
+ *   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.
+ *
+ *   Authoritative schema docs:
+ *
+ *   - 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).
+ *
+ * `content` is unindexed — it's 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 {
+	rowid: number
+	wof_id: number
+	name: string
+	alt_names: string | null
+}
+
+/**
+ * `spr` — the Who's On First "Standard Places Response": a denormalized lightweight summary of one row per place. The
+ * resolver's main lookup table.
+ *
+ * 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.
+ *
+ * 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).
+ */
+export interface SprTable {
+	id: number
+	parent_id: number | null
+	name: string | null
+	placetype: string | null
+	country: string | null
+	latitude: number
+	longitude: number
+	min_latitude: number
+	min_longitude: number
+	max_latitude: number
+	max_longitude: number
+	is_current: number
+	is_deprecated: number
+	is_ceased: number
+	is_superseded: number
+	is_superseding: number
+	superseded_by: string | null
+	supersedes: string | null
+	lastmodified: number
+}
+
+/**
+ * Alternate names per place, keyed by language tag subfields (BCP-47 components). Joins back to `spr.id` via `id` (NOT
+ * `place_id` — the real WOF schema uses the same column name as the spr primary key; this is a normal join across two
+ * tables with the same FK column name).
+ *
+ * No `kind` column in real WOF — the FTS build just concatenates ALL names per id.
+ *
+ * `official` (#936 ingest bit, our unified builds only; absent in real WOF dumps) marks a PREFERRED-form name in an
+ * official language of the place's country — the aliases eligible to join the name-exact tier under the option-3 rule.
+ * See `unified-schema.ts` for the full contract.
+ */
+export interface NamesTable {
+	id: number
+	placetype: string | null
+	country: string | null
+	language: string | null // ISO-639 alpha-3
+	extlang: string | null
+	script: string | null
+	region: string | null
+	variant: string | null
+	extension: string | null
+	privateuse: string | null
+	official: number | null
+	name: string
+	lastmodified: number
+}
+
+/**
+ * Per-place GeoJSON blob. Centroid lat/lon are already exposed via `spr.{latitude,longitude}` so the resolver doesn't
+ * need to parse this; we keep the table modeled in case Phase 4.3 wants the full geometry for bbox / polygon work.
+ */
+export interface GeojsonTable {
+	id: number
+	body: string
+	source: string | null
+	alt_label: string | null
+	is_alt: number
+	lastmodified: number
+}
+
+/**
+ * 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
+	ancestor_id: number
+	ancestor_placetype: string | null
+	lastmodified: number
+}
+
+/**
+ * `place_population` — `id → wof:population`, split off `spr` so a population-rank join is a single indexed probe.
+ * Written by the build/augment ingest + the GeoNames backfill; read by the candidate build's `neg_rank`. WOF carries
+ * population for ~15% of localities; absent = unknown, not zero.
+ */
+export interface PlacePopulationTable {
+	id: number
+	population: number
+}
+
+/**
+ * `place_abbr` — `id → abbreviation` (e.g. `IL → Illinois`), derived from `names` rows whose `language = 'abbr'`. Lets
+ * the resolver accept a 2-letter region abbreviation as an exact match.
+ */
+export interface PlaceAbbrTable {
+	id: number
+	abbr: string
+}
+
+/**
+ * `concordances` — external-id cross-references per place (`id → (other_source, other_id)`), e.g. a GeoNames or
+ * Overture GERS id. Metadata only; not part of the resolve path.
+ */
+export interface ConcordancesTable {
+	id: number
+	other_id: string
+	other_source: string
+	lastmodified: number
+}
+
+/**
+ * `coincident_roles` (#402) — the dual-role relation: a place that is BOTH an admin region AND a locality (Berlin the
+ * city-state). One row per (admin, locality) pair the resolver can complete a hierarchy with. Surfaced by
+ * {@link MailwomanLookupLike.coincidentRolesFor}.
+ */
+export interface CoincidentRolesTable {
+	admin_id: number
+	locality_id: number
+	relationship_type: string
+	admin_placetype: string
+	distance_km: number
+	locality_population: number
+}
+
+/**
+ * The full schema we hand to `Kysely<WOFDatabase>` / `new DatabaseClient<WOFDatabase>(...)`. Tables not listed here
+ * will fail type-checked queries — by design. The reader ({@link WOFSqlitePlaceLookup}) already consumes this; the
+ * build/augment WRITERS adopt it so a column rename is a compile error on both sides (the drift that bit the corpus
+ * TIGER adapter).
+ */
+export interface WOFDatabase {
+	place_search: PlaceSearchTable
+	spr: SprTable
+	names: NamesTable
+	geojson: GeojsonTable
+	ancestors: AncestorsTable
+	place_population: PlacePopulationTable
+	place_abbr: PlaceAbbrTable
+	concordances: ConcordancesTable
+	coincident_roles: CoincidentRolesTable
+}

package/sharding.ts

@@ -0,0 +1,235 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Multi-shard support for `WOFSqlitePlaceLookup` — opens multiple WOF SQLite distributions on one
+ *   connection via `ATTACH DATABASE`, and routes queries to the right shard based on placetype.
+ *
+ *   ## The FTS5 syntax rule that drove this design
+ *
+ *   The naive `SELECT … FROM pc.place_search WHERE pc.place_search MATCH ?` fails — SQLite parses the
+ *   schema-qualified table on the left of MATCH as "column place_search of table pc". Discovered in
+ *   the spike at PR review time; documented as `_SHARD_RULE.md` should it ever bite again.
+ *
+ *   The working form: schema-qualified in FROM, bare table name in MATCH:
+ *
+ *   ```sql
+ *   SELECT … FROM pc.place_search WHERE place_search MATCH ?
+ * ```
+ *
+ *   Identical table names across attached shards (which is what we have — every shard ships its own
+ *   `place_search` + `place_bbox`) are fine because the bare-name MATCH resolves against FROM
+ *   scope.
+ */
+
+import { basename } from "node:path"
+
+/**
+ * Derive a SQL-safe schema name from a WOF distribution filename. Used by `ATTACH DATABASE … AS <name>` so each shard
+ * gets a stable, predictable handle.
+ *
+ * Convention strips the `whosonfirst-data-` prefix and the `-latest.db` (or just `.db`) suffix, then replaces `-` with
+ * `_` for SQL identifier safety.
+ *
+ * Examples:
+ *
+ * - `whosonfirst-data-admin-us-latest.db` → `admin_us`
+ * - `whosonfirst-data-postalcode-us-latest.db` → `postalcode_us`
+ * - `whosonfirst-data-admin-latest.db` → `admin`
+ * - `my-custom.db` → `my_custom`
+ *
+ * Callers can override the derived name explicitly via `ShardConfig.schemaName` when the filename doesn't follow WOF
+ * convention.
+ */
+export function deriveSchemaName(path: string): string {
+	const stem = basename(path)
+		.replace(/^whosonfirst-data-/u, "")
+		.replace(/-latest\.db$/u, "")
+		.replace(/\.db$/u, "")
+		.replace(/[^a-zA-Z0-9_]/g, "_")
+
+	if (!stem) {
+		throw new Error(`deriveSchemaName: could not derive a SQL schema name from path ${JSON.stringify(path)}`)
+	}
+
+	return stem
+}
+
+/**
+ * Per-shard configuration. The simple form is just a path string — the schema name is derived from it. The object form
+ * lets callers override the derived schema name (useful when a filename doesn't follow WOF convention) or attach an
+ * extra hint about which placetypes route here.
+ */
+export interface ShardConfig {
+	path: string
+	/**
+	 * Override the auto-derived schema name. Useful when the filename doesn't match WOF convention or when you want a
+	 * memorable handle. Must be a valid SQLite identifier — `[a-zA-Z_][a-zA-Z0-9_]*`.
+	 */
+	schemaName?: string
+	/**
+	 * Optional explicit list of placetypes this shard serves. When set, queries against any listed placetype are routed
+	 * to this shard. When omitted, routing falls back to a name-match heuristic: a shard whose `schemaName` contains the
+	 * placetype as a substring (e.g. `postalcode_us` for `postalcode` queries) is preferred for that placetype.
+	 */
+	placetypes?: readonly string[]
+}
+
+/**
+ * Resolved post-derivation: paired path + chosen schema name + (possibly empty) placetypes hint. Used internally by
+ * `WOFSqlitePlaceLookup` so the routing logic operates on uniform structures.
+ */
+export interface ResolvedShard {
+	path: string
+	schemaName: string
+	placetypes: readonly string[]
+}
+
+/** SQLite identifier regex — `[A-Za-z_][A-Za-z0-9_]*`. */
+const SQLITE_IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/u
+
+/**
+ * Normalize the user-provided `databasePath` opt (which may be a single string, an array of strings, or an array of
+ * `ShardConfig` objects) into a uniform `ResolvedShard[]`.
+ *
+ * The first shard becomes `main` regardless of its derived schema name — that's the SQLite convention. Subsequent
+ * shards keep their derived (or override) schema name.
+ */
+export function resolveShards(input: string | ReadonlyArray<string | ShardConfig>): ResolvedShard[] {
+	const list = typeof input === "string" ? [input] : input
+
+	if (list.length === 0) throw new Error("resolveShards: at least one shard is required")
+
+	const seen = new Set<string>()
+	const out: ResolvedShard[] = []
+
+	for (let i = 0; i < list.length; i++) {
+		const entry = list[i]!
+		const cfg: ShardConfig = typeof entry === "string" ? { path: entry } : entry
+		const derived = cfg.schemaName ?? deriveSchemaName(cfg.path)
+
+		if (!SQLITE_IDENT_RE.test(derived)) {
+			throw new Error(
+				`resolveShards: schema name ${JSON.stringify(derived)} is not a valid SQLite identifier ` +
+					`(derived from path ${JSON.stringify(cfg.path)}). Pass an explicit ` +
+					`{ path, schemaName } to override.`
+			)
+		}
+		// The first shard is always main per SQLite semantics — its derived name is informational
+		// only. Subsequent shards must have unique non-main names.
+		const schemaName = i === 0 ? "main" : derived
+
+		if (i > 0 && (schemaName === "main" || seen.has(schemaName))) {
+			throw new Error(
+				`resolveShards: schema name ${JSON.stringify(schemaName)} collides ` +
+					`(either with "main" or another shard). Pass an explicit { path, schemaName }.`
+			)
+		}
+		seen.add(schemaName)
+		out.push({
+			path: cfg.path,
+			schemaName,
+			placetypes: cfg.placetypes ?? [],
+		})
+	}
+
+	return out
+}
+
+/**
+ * Pick the shard to route a query to given the requested placetype(s).
+ *
+ * Routing rules, in order:
+ *
+ * 1. If any shard has explicit `placetypes` that includes the requested placetype, use it.
+ * 2. Otherwise, if a non-main shard's `schemaName` matches the placetype (e.g. `postalcode_us` matches `postalcode`), use
+ *    it.
+ * 3. Otherwise, fall back to `main`.
+ *
+ * This deliberately doesn't UNION across shards — BM25 scores aren't comparable across separately- indexed corpora, and
+ * the typical mailwoman query has a single placetype anyway. If a caller needs cross-shard results they can issue two
+ * `findPlace` calls.
+ */
+/**
+ * All placetype-matching shards, in routing order (the country-aware pick chooses among these). Used by the bias path:
+ * a country-less postcode query with proximity hints fans out across every matching shard and merges, because
+ * single-shard routing would hide the cross-country ambiguity the hints exist to resolve ("48026" lives in
+ * postalcode-us AND postalcode-intl).
+ */
+export function pickShardsForPlacetype(shards: ResolvedShard[], placetype: string | undefined): ResolvedShard[] {
+	if (!placetype) return [shards[0]!]
+	const matches: ResolvedShard[] = []
+
+	for (const s of shards) {
+		if (s.placetypes.includes(placetype)) {
+			matches.push(s)
+		}
+	}
+
+	for (const s of shards) {
+		if (s.schemaName === "main" || matches.includes(s)) continue
+
+		if (
+			s.schemaName === placetype ||
+			s.schemaName.startsWith(`${placetype}_`) ||
+			s.schemaName.endsWith(`_${placetype}`)
+		) {
+			matches.push(s)
+		}
+	}
+
+	return matches.length > 0 ? matches : [shards[0]!]
+}
+
+export function pickShardForPlacetype(
+	shards: ResolvedShard[],
+	placetype: string | undefined,
+	opts?: {
+		/**
+		 * #920: the query's country constraint, when the caller has one. With MULTIPLE shards matching a placetype
+		 * (postalcode-us + postalcode-geonames-tail), first-match routing sent every postcode query to the first shard and
+		 * starved the rest — a FI postcode could never reach the tail shard. When `country` is given and a matching shard's
+		 * probed country set contains it, that shard wins; shards without the country are skipped; the placetype-match
+		 * order remains the tiebreak when no shard claims the country (or none was probed).
+		 */
+		country?: string
+		/** Per-schema probed country sets (see `WOFSqlitePlaceLookup`'s construction probe). */
+		countriesBySchema?: ReadonlyMap<string, ReadonlySet<string>>
+	}
+): ResolvedShard {
+	if (!placetype) return shards[0]!
+
+	const matches: ResolvedShard[] = []
+
+	for (const s of shards) {
+		if (s.placetypes.includes(placetype)) {
+			matches.push(s)
+		}
+	}
+
+	for (const s of shards) {
+		if (s.schemaName === "main" || matches.includes(s)) continue
+
+		// Substring match: `postalcode_us` matches `postalcode`. Conservative — requires the
+		// placetype to appear at a word boundary in the schema name to avoid false hits like
+		// `region` matching `arboregion`.
+		if (
+			s.schemaName === placetype ||
+			s.schemaName.startsWith(`${placetype}_`) ||
+			s.schemaName.endsWith(`_${placetype}`)
+		) {
+			matches.push(s)
+		}
+	}
+
+	if (matches.length === 0) return shards[0]!
+
+	if (opts?.country && opts.countriesBySchema) {
+		for (const s of matches) {
+			if (opts.countriesBySchema.get(s.schemaName)?.has(opts.country)) return s
+		}
+	}
+
+	return matches[0]!
+}

package/sqlite-convention-source.ts

@@ -0,0 +1,61 @@
+/**
+ * @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-load-bearing-trivia`).
+ *
+ *   The asset is the queryable, distributable artifact; the strategy IMPLEMENTATIONS stay in code. An
+ *   unknown strategy NAME is surfaced loudly at dispatch (see `lookup.ts`), not silently
+ *   swallowed.
+ */
+
+import type { DatabaseSync } from "node:sqlite"
+
+import { ADDRESS_CONVENTION_TABLE, type Convention, type ConventionSource } from "./convention.ts"
+
+export class SqliteConventionSource implements ConventionSource {
+	readonly #db: DatabaseSync
+	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 shard name —
+	 *   `WOFSqlitePlaceLookup` auto-detects which shard carries the table).
+	 */
+	constructor(db: DatabaseSync, schema: string) {
+		this.#db = db
+		this.#schema = schema
+	}
+
+	get(wofID: number): Convention | undefined {
+		const cached = this.#cache.get(wofID)
+
+		if (cached !== undefined) return cached ?? undefined
+		let value: Convention | null = null
+
+		try {
+			const row = this.#db
+				.prepare(`SELECT convention FROM ${this.#schema}.${ADDRESS_CONVENTION_TABLE} WHERE wof_id = ?`)
+				.get(wofID) as { convention: string } | undefined
+
+			if (row?.convention) {
+				value = JSON.parse(row.convention) as Convention
+			}
+		} catch {
+			// Malformed JSON or a missing table → treat as no override (the chain falls back to
+			// WORLD_DEFAULT). The build script validates structure, so this is purely defensive.
+			value = null
+		}
+		this.#cache.set(wofID, value)
+
+		return value ?? undefined
+	}
+}

package/sqlite-utils.ts

@@ -0,0 +1,25 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Small shared helpers for the SQLite-backed lookups.
+ */
+
+import type { DatabaseSync } from "node:sqlite"
+
+/**
+ * True when `name` is a table in the open database. The street-level lookups use this to degrade gracefully on an
+ * empty/tableless shard — an interrupted `build-*-shard.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.
+ */
+export function hasTable(db: DatabaseSync, name: string): boolean {
+	try {
+		const row = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ? LIMIT 1").get(name)
+
+		return row !== undefined
+	} catch {
+		return false
+	}
+}

package/street-centroid-schema.ts

@@ -0,0 +1,124 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for the DERIVED STREET-CENTROID shard (`street-centroids-<cc>.db`, built by
+ *   `ban/scripts/build-street-centroid-shard.ts` — the #1042 street-level tier behind "street-only
+ *   FR queries deserve a street-level answer"). The shard is a `GROUP BY street` roll-up of the
+ *   sealed rooftop address-point shard: 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.
+ */
+
+import type { Kysely } from "kysely"
+
+/**
+ * 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`).
+ */
+export interface StreetCentroidTable {
+	/** Shared `normalizeStreetForKeyLocale` of the street — the build/query-consistent probe key. */
+	street_norm: string
+	/** The 5-digit postcode of this group, or null when the source row carried none. */
+	postcode: string | null
+	/** Arrondissement-stripped commune (`stripArrondissement(normalizeLocalityForKey(commune))`) — the fallback scope. */
+	locality_base: string
+	/** Weighted-mean centroid latitude of the street's member points. */
+	lat: number
+	/** Weighted-mean centroid longitude of the street's member points. */
+	lon: number
+	min_lat: number
+	max_lat: number
+	min_lon: number
+	max_lon: number
+	/** Member address-point count — the weight for a cross-group centroid aggregate. */
+	point_count: number
+	/** A representative street name as it appeared in the source (display / debugging). */
+	street_raw: string
+	/** Provenance: the register this street was derived from (e.g. `ban:fr`). */
+	source: string
+	/** The pinned data release the underlying 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.
+	 */
+	name_key: string
+}
+
+/** The street-centroid database schema for `new DatabaseClient<StreetCentroidDatabase>(...)`. */
+export interface StreetCentroidDatabase {
+	street_centroid: StreetCentroidTable
+}
+
+/**
+ * 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.
+ */
+export const STREET_CENTROID_COLUMNS = [
+	"street_norm",
+	"postcode",
+	"locality_base",
+	"lat",
+	"lon",
+	"min_lat",
+	"max_lat",
+	"min_lon",
+	"max_lon",
+	"point_count",
+	"street_raw",
+	"source",
+	"release",
+	"name_key",
+] as const
+
+/** Create the `street_centroid` table — called before the streaming bulk load. */
+export async function createStreetCentroidTable(db: Kysely<StreetCentroidDatabase>): Promise<void> {
+	await db.schema
+		.createTable("street_centroid")
+		.addColumn("street_norm", "text", (c) => c.notNull())
+		.addColumn("postcode", "text")
+		.addColumn("locality_base", "text", (c) => c.notNull())
+		.addColumn("lat", "real", (c) => c.notNull())
+		.addColumn("lon", "real", (c) => c.notNull())
+		.addColumn("min_lat", "real", (c) => c.notNull())
+		.addColumn("max_lat", "real", (c) => c.notNull())
+		.addColumn("min_lon", "real", (c) => c.notNull())
+		.addColumn("max_lon", "real", (c) => c.notNull())
+		.addColumn("point_count", "integer", (c) => c.notNull())
+		.addColumn("street_raw", "text", (c) => c.notNull())
+		.addColumn("source", "text", (c) => c.notNull())
+		.addColumn("release", "text", (c) => c.notNull())
+		.addColumn("name_key", "text", (c) => c.notNull())
+		.execute()
+}
+
+/**
+ * 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).
+ */
+export async function createStreetCentroidIndexes(db: Kysely<StreetCentroidDatabase>): Promise<void> {
+	await db.schema.createIndex("idx_sc_postcode").on("street_centroid").columns(["postcode", "street_norm"]).execute()
+	await db.schema
+		.createIndex("idx_sc_locality")
+		.on("street_centroid")
+		.columns(["locality_base", "street_norm"])
+		.execute()
+	await db.schema.createIndex("idx_sc_name").on("street_centroid").columns(["name_key"]).execute()
+}