@mailwoman/resolver-wof-sqlite 9.2.0 → 9.3.0

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/resolver"
+import { haversineKm } from "@mailwoman/spatial"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-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]!)
 
@@ -195,6 +195,31 @@ export function normalizeStreetForKey(street: string): StreetKey {
  */
 export type StreetLocale = "us" | "en" | "fr" | "de" | "nl" | "pl" | "vn" | "id"
 
+/**
+ * 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
  * LEAD the name ("Av. de…", "Bd …", "Pl. …") and "St"/"Ste" abbreviate Saint/Sainte inside names ("Rue St-Honoré" →
@@ -223,7 +248,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 +280,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.
@@ -268,7 +293,7 @@ export function normalizeStreetForKeyLocale(street: string, locale: StreetLocale
 	// 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 +342,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.
@@ -347,7 +372,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 +380,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 +478,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

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

@@ -3,8 +3,8 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Typed schema for the TIGER STREET-SEGMENT interpolation shards (`street-segments-<cc>-<st>.db`,
- *   built by `scripts/build-interpolation-shard.ts` from TIGER EDGES) — the #483 Method-3 fallback
+ *   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.
@@ -17,7 +17,7 @@
 
 import type { Kysely } from "kysely"
 
-import type { RouteKey } from "./street-normalize.ts"
+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
@@ -74,11 +74,11 @@ export interface StreetSegmentTable {
 }
 
 /**
- * The shard's single-row calibration metadata (#374 doctrine, 2026-07-26): the conformal radius multiplier is a
+ * 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}. Shards 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).
+ * {@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).
  */
 export interface InterpCalibrationRow {
 	/**
@@ -147,7 +147,7 @@ export async function createStreetSegmentTable(db: Kysely<StreetSegmentDatabase>
 
 /**
  * Create + populate the single-row `interp_calibration` metadata table (see {@link InterpCalibrationRow}) — called once
- * by the shard builder, after the value is selected from the calibration source of record. Build-time only (async
+ * 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.
  */

package/{types.ts → lib/types.ts}

@@ -91,8 +91,8 @@ export interface PlaceCandidate {
 	/**
 	 * 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 shard's `place_importance` table carries the
-	 * split columns, and no shipped shard does — the FTS lookup's clauses emit NULL for everything today. `undefined`
+	 * 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}.
 	 *
@@ -126,10 +126,17 @@ export interface PlaceCandidate {
 	 * 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 load-bearing — the resolver walk reads it
-	 * as `unavailable`, never as "not contained".
+	 * qualifier on the query, or an artifact without the sidecar). Absence is required — the resolver walk reads it as
+	 * `unavailable`, never as "not contained".
 	 */
 	containedByQualifier?: boolean
+	/**
+	 * 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").
+	 */
+	variantAliasExempted?: true
 }
 
 /**
@@ -179,8 +186,8 @@ export interface FindPlaceQuery {
 	 */
 	fuzzyCountry?: string
 	/**
-	 * Restrict name matching to PRIMARY-keyed rows (#1632) — set by probes whose surface is a RE-READING (a token cut out
-	 * of a longer classified span), which never named an alias. See the ResolverBackend contract in
+	 * 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`.
 	 */
 	primaryOnly?: boolean
@@ -197,14 +204,14 @@ export interface FindPlaceQuery {
 	 * 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 shard is present.
+	 * postcode_locality extract is present.
 	 */
 	postcode?: string
 	/**
 	 * Postcode-containment coherence (#31, Mechanism 2) — when true on a locality query that also carries `postcode`,
-	 * candidate rows within `POSTCODE_CONTAINMENT_GATE_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).
+	 * 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).
 	 */
 	postcodeContainmentCoherence?: boolean
 	/**
@@ -243,7 +250,6 @@ export interface FindPlaceQuery {
  * interface is async even though `node:sqlite` is sync — leaves room for `Worker`-backed implementations later without
  * a public API break.
  */
-export interface PlaceLookup {
+export interface PlaceLookup extends Disposable {
 	findPlace(query: FindPlaceQuery): Promise<PlaceCandidate[]>
-	close(): void
 }