@mailwoman/resolver-wof-sqlite 9.2.0 → 9.4.0

package/{sqlite-utils.ts → lib/sqlite-utils.ts}

@@ -6,13 +6,12 @@
  *   Small shared helpers for the SQLite-backed lookups.
  */
 
-import type { DatabaseSync, SQLInputValue } from "node:sqlite"
-
 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
-// seam; re-exported here because this module is where this package's readers already look for it.
-export { allRows, getRow } from "@mailwoman/core/utils"
+// 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
@@ -23,8 +22,8 @@ export type PreparedGet<Parameters extends SQLInputValue[], Row> = (...parameter
 /**
  * Prepare a single-row query while preserving its exact parameter tuple at every call site.
  */
-export function prepareGet<Parameters extends SQLInputValue[], Row>(
-	db: DatabaseSync,
+export function prepareGet<Parameters extends SQLInputValue[], Row, DB>(
+	db: DatabaseClient<DB>,
 	sql: string
 ): PreparedGet<Parameters, Row> {
 	const statement = db.prepare(sql)
@@ -40,8 +39,8 @@ export type PreparedAll<Parameters extends SQLInputValue[], Row> = (...parameter
 /**
  * Prepare a multi-row query while preserving its exact parameter tuple at every call site.
  */
-export function prepareAll<Parameters extends SQLInputValue[], Row>(
-	db: DatabaseSync,
+export function prepareAll<Parameters extends SQLInputValue[], Row, DB>(
+	db: DatabaseClient<DB>,
 	sql: string
 ): PreparedAll<Parameters, Row> {
 	const statement = db.prepare(sql)
@@ -51,15 +50,13 @@ export function prepareAll<Parameters extends SQLInputValue[], Row>(
 
 /**
  * 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.
+ * 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.
  */
-export function hasTable(db: DatabaseSync, name: string): boolean {
+export function hasTable<DB>(db: DatabaseClient<DB>, 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
+		return tableExists(db, name)
 	} catch {
 		return false
 	}
@@ -76,11 +73,9 @@ export function hasTable(db: DatabaseSync, name: string): boolean {
  * Note the interpolation: PRAGMA does not take bound parameters, so `table` is spliced. Every caller passes a
  * module-level constant; never pass user input.
  */
-export function hasColumn(db: DatabaseSync, table: string, column: string): boolean {
+export function hasColumn<DB>(db: DatabaseClient<DB>, table: string, column: string): boolean {
 	try {
-		const rows = allRows<{ name: string }>(db.prepare(`PRAGMA table_info(${table})`))
-
-		return rows.some((r) => String(r.name) === column)
+		return columnExists(db, table, column)
 	} catch {
 		return false
 	}

package/{street-centroid-schema.ts → lib/street/centroid-schema.ts}

@@ -3,10 +3,10 @@
  * @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
+ *   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
@@ -22,7 +22,7 @@
 
 import type { Kysely } from "kysely"
 
-import type { NameKey, StreetKey } from "./street-normalize.ts"
+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

package/{street-centroid.ts → lib/street/centroid.ts}

@@ -8,7 +8,7 @@
  *   number) plus a postcode/commune scope, it returns the street's CENTROID + an honest extent-derived
  *   uncertainty from the derived `street-centroids-<cc>.db` roll-up.
  *
- *   Query-side normalization is THE shared normalizer (`street-normalize.ts`), selected per the shard's
+ *   Query-side normalization is THE shared normalizer (`street-normalize.ts`), selected per the extract's
  *   `streetLocale`, so build-side and probe-side keys agree by construction. The commune scope folds
  *   through `normalizeLocalityForKey` + `stripArrondissement` (BAN names Paris/Lyon/Marseille per
  *   arrondissement; a query names the base commune).
@@ -19,11 +19,12 @@
  *   exact-after-normalization only (no fuzzy street matching in this tier).
  */
 
-import { DatabaseSync } from "node:sqlite"
+import type { StreetCentroidHit, StreetCentroidLookup } from "@mailwoman/core/resolver"
+import { haversineKm } from "@mailwoman/spatial"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import type { StreetCentroidHit, StreetCentroidLookup } from "@mailwoman/resolver"
-
-import { hasTable, prepareGet, type PreparedGet } from "./sqlite-utils.ts"
+import { hasTable, prepareGet, type PreparedGet } from "#sqlite-utils"
+import type { StreetCentroidDatabase } from "#street/centroid-schema"
 import {
 	normalizeLocalityForKey,
 	normalizeStreetForKeyLocale,
@@ -32,7 +33,7 @@ import {
 	streetLocaleForSurface,
 	type StreetLocale,
 	stripArrondissement,
-} from "./street-normalize.ts"
+} from "#street/normalize"
 
 /**
  * The weighted-centroid + extent + provenance an aggregate probe projects. `lat` is null when nothing matched.
@@ -61,33 +62,25 @@ const AGG_SELECT =
  * Half the bbox diagonal, in METERS — an honest coarse radius for a street centroid.
  */
 function extentRadiusM(minLat: number, maxLat: number, minLon: number, maxLon: number): number {
-	const R = 6_371_000
-	const toRad = (d: number): number => (d * Math.PI) / 180
-	const dLat = toRad(maxLat - minLat)
-	const dLon = toRad(maxLon - minLon)
-	const midLat = toRad((minLat + maxLat) / 2)
-	const a = Math.sin(dLat / 2) ** 2 + Math.cos(midLat) ** 2 * Math.sin(dLon / 2) ** 2
-	const diag = 2 * R * Math.asin(Math.min(1, Math.sqrt(a)))
-
-	return Math.round(diag / 2)
+	return Math.round(haversineKm(minLat, minLon, maxLat, maxLon) * 500)
 }
 
 export class StreetCentroidSqliteLookup implements StreetCentroidLookup {
-	readonly #db: DatabaseSync
+	readonly #db: DatabaseClient<StreetCentroidDatabase>
 	readonly #locale: StreetLocale
 	readonly #byPostcode: PreparedGet<[postcode: string, street: StreetKey], AggRow> | undefined
 	readonly #byLocality: PreparedGet<[locality: NameKey, street: StreetKey], AggRow> | undefined
 
 	/**
-	 * @param dbPath Shard path.
-	 * @param opts.streetLocale The street-normalization locale this shard was BUILT with — must match, or every key
+	 * @param dbPath Extract path.
+	 * @param opts.streetLocale The street-normalization locale this extract was BUILT with — must match, or every key
 	 *   misses. Defaults to `"fr"` (BAN is the French national register; the tier is FR-only today).
 	 */
 	constructor(dbPath: string, opts: { streetLocale?: StreetLocale } = {}) {
-		this.#db = new DatabaseSync(dbPath, { readOnly: true })
+		this.#db = new DatabaseClient<StreetCentroidDatabase>(dbPath, { readOnly: true })
 		this.#locale = opts.streetLocale ?? "fr"
 
-		// Degrade gracefully on an empty/tableless shard (interrupted build, stray 0-byte file): with no
+		// Degrade gracefully on an empty/tableless extract (interrupted build, stray 0-byte file): with no
 		// `street_centroid` table this lookup is a no-op miss, not a crash (mirrors the address-point reader).
 		if (hasTable(this.#db, "street_centroid")) {
 			this.#byPostcode = prepareGet(
@@ -130,7 +123,7 @@ export class StreetCentroidSqliteLookup implements StreetCentroidLookup {
 		}
 	}
 
-	close(): void {
-		this.#db.close()
+	[Symbol.dispose](): void {
+		this.#db[Symbol.dispose]()
 	}
 }

package/lib/street/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+export * from "#street/centroid"
+export * from "#street/centroid-schema"
+export * from "#street/morphology-fst-builder"
+export * from "#street/morphology-fst-loader"
+export * from "#street/name-lookup"
+export * from "#street/normalize"
+export * from "#street/segment-schema"

package/{street-morphology-fst-builder.ts → lib/street/morphology-fst-builder.ts}

@@ -23,14 +23,13 @@
  *   `fst-street-morphology.bin`.
  */
 
-import { readdirSync, readFileSync, statSync } from "node:fs"
-import { join } from "node:path"
-
+import { isDirectory, readDirectory, readLocalTextFile, statPath } from "@mailwoman/core/fs/readers"
+import { join } from "path-ts"
 import { TextSpliterator } from "spliterator"
 
-import type { FSTNode } from "./fst-matcher.ts"
-import { FSTMatcher, normalizeTokens } from "./fst-matcher.ts"
-import type { FSTProvenance, PlaceEntry } from "./fst-types.ts"
+import type { FSTNode } from "#fst/matcher"
+import { FSTMatcher, normalizeTokens } from "#fst/matcher"
+import type { FSTProvenance, PlaceEntry } from "#fst/types"
 
 /**
  * Reserved synthetic wofID base for street-morphology entries. 32-bit unsigned, well above any realistic WOF
@@ -96,7 +95,9 @@ function parseLine(line: string): { canonical: string; variants: string[] } | nu
 	return { canonical: parts[0]!, variants: parts }
 }
 
-export function buildStreetMorphologyFST(opts: BuildStreetMorphologyFSTOpts): BuildStreetMorphologyFSTResult {
+export async function buildStreetMorphologyFST(
+	opts: BuildStreetMorphologyFSTOpts
+): Promise<BuildStreetMorphologyFSTResult> {
 	const progress = opts.onProgress ?? (() => {})
 	const minVariantLength = opts.minVariantLength ?? 3
 
@@ -107,19 +108,28 @@ export function buildStreetMorphologyFST(opts: BuildStreetMorphologyFSTOpts): Bu
 	if (opts.locales && opts.locales.length) {
 		locales = opts.locales
 	} else {
-		locales = readdirSync(opts.dictionariesDir).filter((entry) => {
+		const entries = await readDirectory(opts.dictionariesDir)
+		const localeProbes: Array<[string, boolean]> = []
+
+		for (const entry of entries) {
 			const localePath = join(opts.dictionariesDir, entry)
 
-			if (!statSync(localePath).isDirectory()) return false
+			if (!(await isDirectory(localePath))) {
+				localeProbes.push([entry, false])
+
+				continue
+			}
 
 			try {
-				statSync(join(localePath, STREET_TYPES_FILENAME))
+				await statPath(join(localePath, STREET_TYPES_FILENAME))
 
-				return true
+				localeProbes.push([entry, true])
 			} catch {
-				return false
+				localeProbes.push([entry, false])
 			}
-		})
+		}
+
+		locales = localeProbes.filter(([, hasFile]) => hasFile).map(([entry]) => entry)
 	}
 
 	progress("discover", `Found ${locales.length} locales with ${STREET_TYPES_FILENAME}`)
@@ -130,7 +140,7 @@ export function buildStreetMorphologyFST(opts: BuildStreetMorphologyFSTOpts): Bu
 
 	for (const locale of locales) {
 		const filePath = join(opts.dictionariesDir, locale, STREET_TYPES_FILENAME)
-		const content = readFileSync(filePath, "utf8")
+		const content = await readLocalTextFile(filePath)
 
 		for (const line of TextSpliterator.from(content)) {
 			const parsed = parseLine(line)

package/{street-morphology-fst-loader.ts → lib/street/morphology-fst-loader.ts}

@@ -3,7 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Unified runtime loader for the street-morphology FST — the #1315 street-context gate's signal
+ *   Unified runtime loader for the street-morphology FST — the #1315 street-context check's signal
  *   source, previously rebuilt from the libpostal dictionaries per process at three duplicate call
  *   sites (runtime pipeline / parity eval / neural harness). The sealed artifact
  *   (`fst-street-morphology.bin`, built by `mailwoman gazetteer build street-morphology`) replaces
@@ -21,14 +21,14 @@
  *   `fst-deserialize-web.ts` (see the docs demo loader).
  */
 
-import { existsSync, readFileSync } from "node:fs"
+import { dataRootPath } from "@mailwoman/core/data-root"
+import { pathExists, readLocalBuffer } from "@mailwoman/core/fs/readers"
+import { resourceDictionaryPath } from "@mailwoman/core/paths"
 
-import { dataRootPath, resourceDictionaryPath } from "@mailwoman/core/utils"
-
-import type { FSTMatcher } from "./fst-matcher.ts"
-import { deserializeFST, readFSTProvenance } from "./fst-serialize.ts"
-import type { FSTProvenance } from "./fst-types.ts"
-import { buildStreetMorphologyFST } from "./street-morphology-fst-builder.ts"
+import type { FSTMatcher } from "#fst/matcher"
+import { deserializeFST, readFSTProvenance } from "#fst/serialize"
+import type { FSTProvenance } from "#fst/types"
+import { buildStreetMorphologyFST } from "#street/morphology-fst-builder"
 
 /**
  * The sealed artifact's canonical filename — identical in the data-root staging dir and as a weights-package sibling.
@@ -77,13 +77,15 @@ export interface LoadedStreetMorphologyFST {
 /**
  * Load the street-morphology matcher: sealed artifact first, per-process dictionary build as the degrade path.
  */
-export function loadStreetMorphologyFST(opts: LoadStreetMorphologyFSTOpts = {}): LoadedStreetMorphologyFST {
+export async function loadStreetMorphologyFST(
+	opts: LoadStreetMorphologyFSTOpts = {}
+): Promise<LoadedStreetMorphologyFST> {
 	const warn = opts.onWarn ?? (() => {})
 	const artifactPath = opts.artifactPath ?? defaultStreetMorphologyArtifactPath()
 
-	if (existsSync(artifactPath)) {
+	if (await pathExists(artifactPath)) {
 		try {
-			const buf = readFileSync(artifactPath)
+			const buf = await readLocalBuffer(artifactPath)
 			const matcher = deserializeFST(buf)
 			const provenance = readFSTProvenance(buf)
 
@@ -95,7 +97,7 @@ export function loadStreetMorphologyFST(opts: LoadStreetMorphologyFSTOpts = {}):
 		}
 	}
 
-	const built = buildStreetMorphologyFST({
+	const built = await buildStreetMorphologyFST({
 		dictionariesDir: opts.dictionariesDir ?? resourceDictionaryPath("libpostal"),
 	})
 

package/{street-name-lookup.ts → lib/street/name-lookup.ts}

@@ -8,7 +8,7 @@
  *   Reads a street-name index (the FR instance = BAN `street-centroids-fr.db`, a `street_centroid`
  *   table of `street_norm × locality_base × postcode` rows) and answers "does this street surface
  *   exist as a name" for the k-best rerank. Sync-by-interface, `readOnly`, prepared statements,
- *   graceful-degrade on a tableless shard — the same reader discipline as `AddressPointSqliteLookup`.
+ *   graceful-degrade on a tableless extract — the same reader discipline as `AddressPointSqliteLookup`.
  *
  *   THE FOLD CONTRACT: the surface is folded with {@link foldStreetSurface} (the shared function),
  *   and the DB's `street_norm` column MUST have been built with that SAME fold or every hyphenated /
@@ -19,24 +19,11 @@
  *   the production rebuild is a tracked BAN-sdk follow-up.
  */
 
-import { DatabaseSync } from "node:sqlite"
-
 import { foldStreetSurface, type StreetEvidenceScope, type StreetLocalityEvidence } from "@mailwoman/resolver"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-function hasTable(db: DatabaseSync, table: string): boolean {
-	const row = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ? LIMIT 1").get(table)
-
-	return row !== undefined
-}
-
-function hasColumn(db: DatabaseSync, table: string, column: string): boolean {
-	// `table` is a caller-controlled identifier (default `street_centroid`), not user input — safe to interpolate.
-	for (const row of db.prepare(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>) {
-		if (row.name === column) return true
-	}
-
-	return false
-}
+import type { WOFDatabase } from "#schema"
+import { hasColumn, hasTable } from "#sqlite-utils"
 
 export interface SQLiteStreetNameLookupOpts {
 	/**
@@ -53,22 +40,22 @@ export interface SQLiteStreetNameLookupOpts {
  * A {@link StreetLocalityEvidence} backed by a street-name SQLite index. Positive evidence only: any doubt (missing
  * table, read miss) returns `false`, so the rerank fails open to the model's ranking.
  */
-export class SQLiteStreetNameLookup implements StreetLocalityEvidence {
+export class SQLiteStreetNameLookup implements StreetLocalityEvidence, Disposable {
 	readonly countries: ReadonlySet<string>
-	readonly #db: DatabaseSync
-	readonly #byName: ReturnType<DatabaseSync["prepare"]> | undefined
-	readonly #byNameLocality: ReturnType<DatabaseSync["prepare"]> | undefined
-	readonly #byNamePostcode: ReturnType<DatabaseSync["prepare"]> | undefined
+	readonly #db: DatabaseClient<WOFDatabase>
+	readonly #byName: ReturnType<DatabaseClient["prepare"]> | undefined
+	readonly #byNameLocality: ReturnType<DatabaseClient["prepare"]> | undefined
+	readonly #byNamePostcode: ReturnType<DatabaseClient["prepare"]> | undefined
 
 	constructor(dbPath: string, opts: SQLiteStreetNameLookupOpts = {}) {
 		this.countries = new Set([...(opts.countries ?? ["FR"])].map((c) => c.toUpperCase()))
-		this.#db = new DatabaseSync(dbPath, { readOnly: true })
+		this.#db = new DatabaseClient<WOFDatabase>(dbPath, { readOnly: true })
 		const table = opts.table ?? "street_centroid"
 
-		// Degrade gracefully on an empty/tableless shard — a no-op miss, never a crash (#568 discipline).
+		// Degrade gracefully on an empty/tableless extract — a no-op miss, never a crash (#568 discipline).
 		if (hasTable(this.#db, table)) {
 			// Prefer the #727 phase-4c `name_key` column (foldStreetSurface, indexed by `idx_sc_name` for a direct seek);
-			// fall back to `street_norm` on a pre-rebuild shard (a skip-scan, but correct). The fold used to build
+			// fall back to `street_norm` on a pre-rebuild extract (a skip-scan, but correct). The fold used to build
 			// `name_key` MUST match `foldStreetSurface` here (the fold-parity contract).
 			const keyCol = hasColumn(this.#db, table, "name_key") ? "name_key" : "street_norm"
 			this.#byName = this.#db.prepare(`SELECT 1 FROM ${table} WHERE ${keyCol} = ? LIMIT 1`)
@@ -104,10 +91,7 @@ export class SQLiteStreetNameLookup implements StreetLocalityEvidence {
 		return this.#byName.get(norm) !== undefined
 	}
 
-	/**
-	 * Close the underlying handle.
-	 */
-	close(): void {
-		this.#db.close()
+	[Symbol.dispose](): void {
+		this.#db[Symbol.dispose]()
 	}
 }

package/{street-normalize.ts → lib/street/normalize.ts}

@@ -3,8 +3,8 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   THE street normalizer for the address-point tier (#476). One function, used by BOTH the shard
- *   builder (`scripts/build-address-point-shard.ts`) and the lookup tier (`address-point.ts`) —
+ *   THE street normalizer for the address-point tier (#476). One function, used by BOTH the extract
+ *   builder (`scripts/build-address-point-extract.ts`) and the lookup tier (`address-point.ts`) —
  *   never two implementations (the PLACETYPE_ORDER lesson: parallel copies silently corrupt).
  *
  *   Normalization contract (deliberately aggressive — both sides apply the same function, so
@@ -27,13 +27,13 @@ import type { Tagged } from "type-fest"
 
 /**
  * A place name folded by {@link normalizeLocalityForKey} — the value stored in, and required to probe, every
- * `name_key`-style column: the candidate gazetteer, the postal-city side-index, the street-centroid shard, an ancestor
- * chain's `parent_name_key`, and the address-point locality scope.
+ * `name_key`-style column: the candidate gazetteer, the postal-city side-index, the street-centroid extract, an
+ * ancestor chain's `parent_name_key`, and the address-point locality scope.
  *
  * The brand is here because the fold is applied at BUILD time and is therefore mandatory at QUERY time, while a
  * near-miss approximation of it (`toLowerCase()`, `trim()`) is still a `string`: it binds to the parameter, returns
  * fewer rows, and the shortfall reads as a coverage gap in the data rather than a defect in the probe. Requiring the
- * brand at the seam turns that silent under-match into a compile error. Mint one only by calling the fold.
+ * brand at the boundary turns that silent under-match into a compile error. Mint one only by calling the fold.
  */
 export type NameKey = Tagged<string, "NameKey">
 
@@ -64,8 +64,8 @@ const MIN_TOKENS_FOR_TAIL_MERGE = 3
 /**
  * Spelled ordinal street names → their digit-ordinal form ("tenth" → "10th"), applied ONLY when a street-type suffix
  * follows (#723 admin-tail) — so the ordinal cross-streets common in grid cities ("Tenth Street", "Fifth Avenue") match
- * the shards' digit keys, WITHOUT rewriting ordinal-WORD names where the next token is not a suffix ("First National
- * Bank Rd" stays "first national …"). Digit-source shards are unaffected (a digit token isn't in this map), so the
+ * the extracts' digit keys, WITHOUT rewriting ordinal-WORD names where the next token is not a suffix ("First National
+ * Bank Rd" stays "first national …"). Digit-source extracts are unaffected (a digit token isn't in this map), so the
  * existing keys need no rebuild; a future rebuild folds any spelled-source key the same way (the one-function
  * discipline).
  */
@@ -123,7 +123,7 @@ export function normalizeStreetForKey(street: string): StreetKey {
 	if (!tokens.length) return "" as StreetKey
 
 	// Spelled-ordinal street names → digit form when a street suffix follows ("Tenth Street" →
-	// "10th street", #723). Gated on the next token being a suffix so ordinal-WORD names are untouched.
+	// "10th street", #723). Conditioned on the next token being a suffix so ordinal-WORD names are untouched.
 	for (let i = 0; i < tokens.length - 1; i++) {
 		const digit = SPELLED_ORDINAL_TO_DIGIT.get(tokens[i]!)
 
@@ -193,7 +193,42 @@ export function normalizeStreetForKey(street: string): StreetKey {
  * article, so no salient-token / multi-key index is built yet (deferred until probing shows the normalizer can't absorb
  * the false-negatives).
  */
-export type StreetLocale = "us" | "en" | "fr" | "de" | "nl" | "pl" | "vn" | "id"
+export type StreetLocale = "us" | "en" | "fr" | "de" | "nl" | "pl" | "vn" | "id" | "zh"
+
+/**
+ * The Han fold shared by every `zh` key: NFKC so a full-width digit or letter keys as its ASCII form (the Taiwanese
+ * civil-affairs registers write `１２２`, a person types `122`), 臺 → 台 (the register writes 臺北市, the common hand writes
+ * 台北市), and no whitespace at all, because a Han surface carries none and a stray space would split one key into two.
+ * Kanji numerals stay as written: the register spells a road section `一段`, and so does a query.
+ */
+function foldHan(input: string): string {
+	return input.normalize("NFKC").replaceAll("臺", "台").replaceAll(/\s+/g, "").toLowerCase()
+}
+
+/**
+ * Country → street-locale registry surface for the acquisition SDKs (BAN, OSM). Each SDK keeps its own map — membership
+ * is a per-register decision — and this factory owns the lookup discipline: throw for an unsupported country rather
+ * than silently folding with the wrong rules, because a extract built with the wrong normalizer keys every street
+ * incorrectly and looks fine until a probe misses. `label` is the SDK's own registration instructions, appended to the
+ * error verbatim.
+ */
+export function createStreetLocaleRegistry(
+	registry: ReadonlyMap<string, StreetLocale>,
+	label: string
+): { localeFor: (countryCode: string) => StreetLocale; supported: () => string[] } {
+	return {
+		localeFor: (countryCode) => {
+			const locale = registry.get(countryCode.toLowerCase())
+
+			if (!locale) {
+				throw new Error(`No street-normalization locale registered for country "${countryCode}". ${label}`)
+			}
+
+			return locale
+		},
+		supported: () => [...registry.keys()],
+	}
+}
 
 /**
  * French street-type abbreviations → canonical full form, applied per token after {@link fold}. French address types
@@ -223,7 +258,7 @@ const FR_STREET_ABBREV = new Map<string, string>([
 ])
 
 /**
- * Polish leading street-type tokens, STRIPPED rather than expanded. Measured on the 5.56M-row PL OSM shard
+ * Polish leading street-type tokens, STRIPPED rather than expanded. Measured on the 5.56M-row PL OSM extract
  * (2026-08-19): OSM Poland tags `addr:street` BARE — `ulica%` covers 22 rows and `ul.%` eight, so an EXPANSION rule
  * makes a typed query ("ul. Świętokrzyska" → "ulica swietokrzyska") miss the 3,846 bare "swietokrzyska" rows. Stripping
  * the leading type on BOTH sides keys typed and bare surfaces identically. The full words are stripped too: the
@@ -255,7 +290,7 @@ const ID_STREET_ABBREV = new Map<string, string>([
  *   {@link PL_LEADING_TYPE} for the measured reason expansion was wrong for this source.
  * - **vn** — fold + đ→d AND ð→d (both non-decomposing, and OSM mixes the two codepoints inside single values — see the
  *   branch comment). Deliberately NO type-abbreviation map yet: the common abbreviation is the single letter "Đ." for
- *   Đường, and expanding a bare folded "d" token would rewrite initials — measure the miss rate on the built shard
+ *   Đường, and expanding a bare folded "d" token would rewrite initials — measure the miss rate on the built extract
  *   before adding anything.
  * - **id** — fold + expand leading type abbreviations (jl/jln→jalan, gg→gang); Indonesian street surfaces are otherwise
  *   ASCII-clean.
@@ -263,12 +298,16 @@ const ID_STREET_ABBREV = new Map<string, string>([
 export function normalizeStreetForKeyLocale(street: string, locale: StreetLocale): StreetKey {
 	if (locale === "us" || locale === "en") return normalizeStreetForKey(street)
 
+	// A Han street name has no tokens, no type abbreviation and no diacritics; the Latin pipeline below would only
+	// split it on whitespace it never carries. `zh` keys are the Han fold and nothing else.
+	if (locale === "zh") return foldHan(street) as StreetKey
+
 	// Hyphen → space so a compound name keys the same whether the source or the query writes the
 	// hyphen ("Champs-Élysées", "St-Honoré") or a space — both sides fold identically, so this is pure
 	// robustness. It also splits a hyphenated abbreviation ("St-Honoré" → "st honore") into tokens the
 	// per-locale type/Saint map can see. Letter maps for non-decomposing letters (ß, ł, đ) live in the
 	// per-locale branches, NEVER here: widening the shared pipeline would silently change keys under
-	// every already-built shard of the other locales.
+	// every already-built extract of the other locales.
 	const tokens = fold(street)
 		.replaceAll("ß", "ss")
 		.replaceAll("-", " ")
@@ -317,7 +356,7 @@ export function normalizeStreetForKeyLocale(street: string, locale: StreetLocale
 			break
 		case "vn":
 			// đ (U+0111, d-with-stroke) AND ð (U+00F0, eth): OSM Vietnamese data mixes the two visually
-			// identical codepoints inside single values — the 2026-08-19 shard measured `Đường Trần Hưng
+			// identical codepoints inside single values — the 2026-08-19 extract measured `Đường Trần Hưng
 			// Đạo` carrying d-with-stroke at the front and ETH in `Đạo`, splitting the country's most
 			// common street into two keys with the MAJORITY variant (630 vs 421 rows) unreachable by a
 			// correctly-typed query. No abbreviation map — see the locale table.
@@ -337,6 +376,33 @@ export function normalizeLocalityForKey(locality: string): NameKey {
 	return fold(locality) as NameKey
 }
 
+/**
+ * The locality key under a street locale: the Han fold for `zh`, {@link normalizeLocalityForKey} for every other.
+ * Separate from the shared fold on purpose — the candidate gazetteer's `name_key` column is the shared fold, and a Han
+ * rule inside it would re-key every 臺 name under an extract built without the rule.
+ */
+export function normalizeLocalityForKeyLocale(locality: string, locale: StreetLocale): NameKey {
+	return locale === "zh" ? (foldHan(locality) as NameKey) : normalizeLocalityForKey(locality)
+}
+
+/**
+ * The house-number key under a street locale. Every Latin register stores a lower-cased, trimmed number and the reader
+ * probes the same; `zh` additionally folds width and drops the trailing 號 the Taiwanese registers write on the number
+ * itself (`１２２號`), which a parse also carries on the `house_number` span (`122號`). Both sides key `122`.
+ */
+export function normalizeHouseNumberForKey(number: string, locale: StreetLocale): string {
+	// The sub-number is written two ways — `30之19號` and `30號之19` — and an attached number a third (`30附40號`,
+	// `55之23附1號`); the register stores the base `30` with the rest in `unit`. Every form keys with the 號 dropped and
+	// the base number first, which the reader's sub-number rung then falls from.
+	if (locale === "zh") {
+		return foldHan(number)
+			.replace(/^(\d+)號([之附]\d+)$/u, "$1$2")
+			.replace(/號$/u, "")
+	}
+
+	return number.trim().toLowerCase()
+}
+
 /**
  * Leading French street-type token. French types LEAD the name ("avenue du Parc", "boul Saint-Laurent") while English
  * types TRAIL ("Fifth Avenue", "Grosvenor Place"), so a leading type-token is the discriminating signal — "1 Avenue NE"
@@ -347,7 +413,7 @@ const FRENCH_LEAD_TYPE =
 	/^(?:rue|ruelle|av|ave|avenue|boul|bd|boulevard|ch|che|chemin|all[ée]e|imp|impasse|mont[ée]e|c[ôo]te|pl|place|prom|promenade|rang|rte|route|autoroute|carr[eé]|croissant|terrasse|sentier)(?=[\s.-]|$)/i
 
 /**
- * Surface-driven street-locale ROUTER for bilingual shards — the Québec finishing move on the CA rooftop shard.
+ * Surface-driven street-locale ROUTER for bilingual extracts — the Québec finishing move on the CA rooftop extract.
  *
  * A country registers ONE street locale, but Canada's street surfaces are two languages: under the `en` rules a French
  * surface passes through mostly unchanged (both sides fold identically, so those rows stay reachable), and what breaks
@@ -355,11 +421,11 @@ const FRENCH_LEAD_TYPE =
  * misses a full-word row and vice versa. Routing on the SURFACE (not the province) also carries bilingual NB and the
  * French street names outside Québec for free.
  *
- * ONE function, called by the shard BUILDER and the query PROBE alike — the #861 discipline: routing is part of the
+ * ONE function, called by the extract BUILDER and the query PROBE alike — the #861 discipline: routing is part of the
  * fold contract, and two transcriptions of this predicate would diverge exactly where it matters. Only an `en` base
- * re-routes: a `fr`/`de`/`nl` shard already speaks its own rules, and the US pipeline stays untouched.
+ * re-routes: a `fr`/`de`/`nl` extract already speaks its own rules, and the US pipeline stays untouched.
  *
- * Measured basis (CA shard, 2026-08-19): 183,963 distinct surfaces, 43,762 French-lead; 29,682 fold differently under
+ * Measured basis (CA extract, 2026-08-19): 183,963 distinct surfaces, 43,762 French-lead; 29,682 fold differently under
  * fr-vs-en (888,265 rows), and the non-French half of those are English surfaces this router keeps on `en` unchanged.
  */
 export function streetLocaleForSurface(street: string, base: StreetLocale): StreetLocale {
@@ -453,9 +519,9 @@ export function stripLocalityQualifier(locality: string): string {
  * (the state abbreviation form) fold to `state route N…`. Only digit-leading route numbers fold — `State Street` and
  * friends never match.
  *
- * Used by BOTH the segment-shard builder (`scripts/build-interpolation-shard.ts`) and the interpolation lookup — same
- * one-function discipline as {@link normalizeStreetForKey}. The address-point tier (#476) does NOT apply it yet:
- * adopting it there requires a shard rebuild (noted on #483).
+ * Used by BOTH the segment-extract builder (`scripts/build-interpolation-extract.ts`) and the interpolation lookup —
+ * same one-function discipline as {@link normalizeStreetForKey}. The address-point tier (#476) does NOT apply it yet:
+ * adopting it there requires a extract rebuild (noted on #483).
  *
  * A same-numbered US and state route stay DISTINCT keys (`us route 5` vs `state route 5`); only the BARE `route N` form
  * is ambiguous (designator unknown) and it stays unfolded — a bare-route query therefore misses rather than guessing a