@mailwoman/resolver-wof-sqlite 9.3.0 → 10.0.0

package/lib/candidate/extract-fold.ts

@@ -8,17 +8,51 @@
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 import { tableExists } from "@mailwoman/sqlite/introspection"
 
-import type { CandidateDatabase } from "#candidate-schema"
+import { CANDIDATE_ANCESTOR_COLUMNS, CANDIDATE_ANCESTOR_TABLE } from "#candidate/ancestors/schema"
 import type { PlaceAttrs, StageRow } from "#candidate/place-attrs"
+import type { CandidateDatabase } from "#candidate/schema"
 import type { WOFDatabase } from "#schema"
 import { normalizeLocalityForKey } from "#street/normalize"
 
+/**
+ * The extract's own region-tier ancestry, when it carries any: extract id → the admin region's id. A locality extract
+ * derived from a national register (the Taiwanese 鄉鎮市區 from the civil-affairs address points) knows which 縣市 each row
+ * belongs to, and writes that as an `ancestors` row against the admin region's WOF id. Without it a folded row has no
+ * region scope, so a `parentID`-scoped probe misses it and the cascade widens to whatever namesake carries the key.
+ *
+ * Only a region the admin build staged (`attrs`) counts: an id the admin does not know cannot be denormalized into a
+ * closure row, and a scope nothing can match would be a silent zero rather than an absence.
+ */
+function extractRegionAncestry(pc: DatabaseClient<WOFDatabase>, attrs: Map<number, PlaceAttrs>): Map<number, number> {
+	const regionOf = new Map<number, number>()
+
+	if (!tableExists(pc, "ancestors")) {
+		return regionOf
+	}
+
+	for (const r of pc
+		.prepare(
+			"SELECT id, MIN(ancestor_id) AS ancestor_id FROM ancestors WHERE ancestor_placetype = 'region' GROUP BY id"
+		)
+		.iterate()) {
+		const rid = Number(r.ancestor_id)
+
+		if (attrs.has(rid)) {
+			regionOf.set(Number(r.id), rid)
+		}
+	}
+
+	return regionOf
+}
+
 /**
  * Fold ONE extract (`spr` rows at `extractPlacetype` carrying real coordinates) in, then pass 4b: the alias names
  * hanging off that same extract's `names` table.
  *
  * Self-contained by construction — it shares only the staging statement and the code dictionaries with the admin passes
- * above it, and nothing downstream reads anything it produces except the two counters it returns.
+ * above it, and nothing downstream reads anything it produces except the counters it returns. The one thing it writes
+ * beyond the staging table is a depth-1 closure row for a row whose extract names its region (see
+ * {@link extractRegionAncestry}), so the pick's stamped ancestors agree with the scope it was found under.
  */
 export function foldExtract(ctx: {
 	/**
@@ -30,8 +64,13 @@ export function foldExtract(ctx: {
 	ccID: (code: string | null) => number
 	ptID: (pt: string | null) => number
 	stageRow: StageRow
+	/**
+	 * The admin places pass 1 staged — what an extract's region ancestry is resolved against. Absent, no extract row
+	 * takes a region scope (the postcode extracts, which carry none).
+	 */
+	attrs?: Map<number, PlaceAttrs>
 	progress: (phase: string, message: string) => void
-}): { primaries: number; aliases: number } {
+}): { primaries: number; aliases: number; scoped: number; ancestorRows: number } {
 	const { out, extractPath, extractPlacetype, ccID, ptID, stageRow, progress } = ctx
 
 	progress(extractPlacetype === "postalcode" ? "postcodes" : "localities", `reading ${extractPath}`)
@@ -41,8 +80,24 @@ export function foldExtract(ctx: {
 	// Per-extract, not the admin `attrs` map: pass 1 only ever sees the admin DB, so the alias pass
 	// below has nothing to join against unless this primary loop records what it staged.
 	const pcAttrs = new Map<number, PlaceAttrs>()
+	const regionOf = ctx.attrs ? extractRegionAncestry(pc, ctx.attrs) : new Map<number, number>()
+
+	const insAncestor = out.prepare(
+		`INSERT OR IGNORE INTO ${CANDIDATE_ANCESTOR_TABLE} VALUES (${CANDIDATE_ANCESTOR_COLUMNS.map(() => "?").join(", ")})`
+	)
+
+	// The region's own closure rows, as the sidecar pass wrote them. A scoped row inherits the whole chain above its
+	// region — macroregion, country — not the region alone: the widened-scope refusal reads a pick's stamped ancestors
+	// against the parent the walk resolved, and a 縣市 that resolves to its macroregion record (`桃園市`, which WOF names
+	// only at that tier) would otherwise contradict a lineage that stops at the region.
+	const regionChain = out.prepare(
+		`SELECT depth, parent_spr_id, parent_placetype_id, parent_name, parent_name_key FROM ${CANDIDATE_ANCESTOR_TABLE} WHERE spr_id = ? ORDER BY depth`
+	)
+
 	let primaries = 0
 	let aliases = 0
+	let scoped = 0
+	let ancestorRows = 0
 
 	out.exec("BEGIN")
 
@@ -60,12 +115,15 @@ export function foldExtract(ctx: {
 
 		const lat = r.latitude as number
 		const lon = r.longitude as number
+		const id = Number(r.id)
+		const rid = regionOf.get(id) ?? 0
 
-		// region_id 0 (a postcode is unique by name+country — no same-name disambiguation); neg_rank 0
-		// (no population). bbox = the postcode's own min/max (falls back to the centroid point).
+		// region_id from the extract's own ancestry when it names one, else 0 (a postcode is unique by
+		// name+country — no same-name disambiguation); neg_rank 0 (no population). bbox = the row's own
+		// min/max (falls back to the centroid point).
 		const a: PlaceAttrs = {
 			cid: ccID(r.country as string | null),
-			rid: 0,
+			rid,
 			ptid: pcPtid,
 			name,
 			lat,
@@ -83,15 +141,38 @@ export function foldExtract(ctx: {
 			imp: null,
 		}
 
-		pcAttrs.set(Number(r.id), a)
-		stageRow(key, a, Number(r.id), 1)
+		pcAttrs.set(id, a)
+		stageRow(key, a, id, 1)
+
+		if (rid !== 0) {
+			const region = ctx.attrs!.get(rid)!
+
+			insAncestor.run(id, 1, rid, region.ptid, region.name, region.pkey)
+
+			scoped++
+
+			ancestorRows++
+
+			for (const link of regionChain.iterate(rid)) {
+				insAncestor.run(
+					id,
+					Number(link.depth) + 1,
+					Number(link.parent_spr_id),
+					Number(link.parent_placetype_id),
+					String(link.parent_name ?? ""),
+					String(link.parent_name_key ?? "")
+				)
+
+				ancestorRows++
+			}
+		}
 
 		primaries++
 	}
 
 	out.exec("COMMIT")
 
-	// --- pass 4b: postcode ALIAS names (#1495) ---
+	// Fold postcode aliases into the staged candidate names.
 	//
 	// The delivery-city names GeoNames supplies for a ZIP ("Brooklyn" for 11201) are written into
 	// the extract's `names` table by `postcode/centroid-fills.ts`'s `geonamesNameFill`. Everything
@@ -134,5 +215,5 @@ export function foldExtract(ctx: {
 		progress("postcode-aliases", `${extractPath} has no \`names\` table — no delivery-city aliases to fold`)
 	}
 
-	return { primaries, aliases }
+	return { primaries, aliases, scoped, ancestorRows }
 }

package/lib/{candidate-importance.ts → candidate/importance.ts}

@@ -44,7 +44,7 @@
 import { haversineKm } from "@mailwoman/spatial"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import type { CandidateDatabase } from "#candidate-schema"
+import type { CandidateDatabase } from "#candidate/schema"
 import { normalizeLocalityForKey } from "#street/normalize"
 
 /**

package/lib/{candidate-lookup.ts → candidate/lookup.ts}

@@ -4,10 +4,10 @@
  * @author Teffen Ellis, et al.
  *
  *   Node-side {@link PlaceLookup} over the byte-range CANDIDATE table (`build-candidate.ts`) — the
- *   SAME gazetteer the browser demo resolves against ({@link WOFCandidateTableLookup} in
- *   `docs/src/shared/httpvfs-resolver.ts`), but reading a LOCAL `candidate.db` via `node:sqlite`
- *   instead of sql.js-httpvfs. This is what makes the server/CLI resolver match the demo: one
- *   lookup surface, one artifact, one ranking.
+ *   SAME gazetteer the browser runtime resolves against ({@link WOFCandidateTableLookup} in
+ *   `packages/resolver-wof-wasm/lib/httpvfs/resolver.ts`), but reading a LOCAL `candidate.db` via
+ *   `node:sqlite` instead of sql.js-httpvfs. This is what makes the server/CLI resolver match the
+ *   browser: one lookup surface, one artifact, one ranking.
  *
  *   The query is a single contiguous probe on the `WITHOUT ROWID` B-tree keyed `(name_key,
  *   country_id, region_id, placetype_id, neg_rank, spr_id)`. `name_key` is the SHARED
@@ -23,13 +23,11 @@
  *   `bbox` field on {@link FindPlaceQuery}).
  */
 
+import { expandPlacetypeFilter } from "@mailwoman/codex/placetype-map"
+import { type Ancestor, type GazetteerArtifactCoverage, referentialFromPopulation } from "@mailwoman/core/resolver"
+import { allRows } from "@mailwoman/core/utils"
 import { jaroWinkler, levenshteinSimilarity } from "@mailwoman/match/comparators"
-import {
-	expandPlacetypeFilter,
-	partitionByContainment,
-	type Ancestor,
-	type GazetteerArtifactCoverage,
-} from "@mailwoman/resolver"
+import { partitionByContainment } from "@mailwoman/resolver"
 import { haversineKm } from "@mailwoman/spatial"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 import type { PathBuilderLike } from "path-ts"
@@ -40,16 +38,15 @@ import {
 	intervalContains,
 	type CandidateAncestorTable,
 	type IntervalLabel,
-} from "#candidate-ancestors-schema"
-import { CANDIDATE_FTS_TABLE } from "#candidate-fts"
-import type { CandidateDatabase, CandidateTable, CountryCodeTable, PlacetypeCodeTable } from "#candidate-schema"
+} from "#candidate/ancestors/schema"
+import { CANDIDATE_FTS_TABLE } from "#candidate/fts"
+import type { CandidateDatabase, CandidateTable, CountryCodeTable, PlacetypeCodeTable } from "#candidate/schema"
 import { readGazetteerCoverageManifest } from "#coverage-manifest-schema"
-import { referentialFromPopulation } from "#place-importance-schema"
-import { POSTAL_CITY_CANDIDATE_TABLE, type PostalCityCandidateTable } from "#postal/city-candidate-schema"
+import { POSTAL_CITY_CANDIDATE_TABLE, type PostalCityCandidateTable } from "#postal/city/candidate-schema"
 import { rankByPrimaryPreference, type RankedRow, RERANK_FETCH } from "#primary-preference"
 import { applyProximityRerank } from "#proximity-rerank"
 import { REGION_CLASS_PLACETYPES, regionQualifierProbeKeys } from "#region-keys"
-import { allRows, hasColumn, hasTable } from "#sqlite-utils"
+import { hasColumn, hasTable } from "#sqlite-utils"
 import { type NameKey, normalizeLocalityForKey, stripLocalityQualifier } from "#street/normalize"
 import type { FindPlaceQuery, PlaceCandidate, PlaceLookup, WOFPlacetype } from "#types"
 

package/lib/candidate/name-roles.ts

@@ -9,9 +9,9 @@ import { isOfficialLanguage } from "@mailwoman/codex/country"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { tableExists } from "@mailwoman/sqlite/introspection"
 
-import type { CandidateDatabase } from "#candidate-schema"
 import { isOwnNameVariant } from "#candidate/own-name"
 import type { PlaceAttrs } from "#candidate/place-attrs"
+import type { CandidateDatabase } from "#candidate/schema"
 import type { WOFDatabase } from "#schema"
 import { normalizeLocalityForKey } from "#street/normalize"
 
@@ -141,7 +141,7 @@ export function stampNameRoles(ctx: {
 			.run().changes
 	)
 
-	// --- variant detector (#1882): the alias surface is the holder's OWN primary name in another
+	// Detect aliases that are the holder's own primary name in another variant.
 	// orthography — romanization, spacing/diacritic variant, or abbreviation expansion. The verdict
 	// is per (alias key, primary key) pair, so it runs in JS over the still-unstamped alias rows;
 	// an uncovered script answers no-verdict and stamps nothing (own-name.ts owns the predicate and

package/lib/candidate/own-name.ts

@@ -127,6 +127,7 @@ export function romanizeNameKey(key: string): string | null {
  * Edit similarity between a holder's primary name key and one of its alias keys, both romanized and
  * abbreviation-expanded. `null` when either side's script is uncovered.
  */
+// repo-health-ignore export-name-affix -- romanizes and expands abbreviations first; `nameSimilarity` compares as given.
 export function ownNameSimilarity(primaryKey: string, aliasKey: string): number | null {
 	const primary = romanizeNameKey(primaryKey)
 	const alias = romanizeNameKey(aliasKey)

package/lib/{candidate-schema.ts → candidate/schema.ts}

@@ -5,7 +5,7 @@
  *
  *   Typed schema for the byte-range CANDIDATE gazetteer (`candidate.db`) — the single source of truth
  *   for the columns shared by the BUILDER ({@link buildCandidateTable}) and the READERS (the Node
- *   {@link WOFCandidateTableLookup} + the browser `httpvfs-resolver.ts`). Before this module each
+ *   {@link WOFCandidateTableLookup} + the browser `@mailwoman/resolver-wof-wasm/httpvfs/resolver`). Before this module each
  *   side hand-wrote the column list; a rename in one place broke the other at runtime. Now the
  *   contract is a Kysely `Database` interface (`new DatabaseClient<CandidateDatabase>(...)` for
  *   typed inserts) plus the table DDL as strings — so a column change is a compile error on every
@@ -17,7 +17,7 @@
 
 import { sql, type Kysely } from "kysely"
 
-import type { CandidateAncestorsDatabase } from "#candidate-ancestors-schema"
+import type { CandidateAncestorsDatabase } from "#candidate/ancestors/schema"
 import type { CapitalTable } from "#capital-schema"
 import type { NameKey } from "#street/normalize"
 

package/lib/{candidate-scoring.ts → candidate/scoring.ts}

@@ -7,12 +7,12 @@
  *   ordered — the weighted-sum score and the exact-match tiering that ranks over it.
  */
 
+import { compareReferential, referentialFromPopulation } from "@mailwoman/core/resolver"
 import { haversineKm } from "@mailwoman/spatial"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 
 import { exactMatchIDs, officialNameIDs } from "#exact-match"
 import { foldQueryText } from "#fts/index"
-import { compareReferential, referentialFromPopulation } from "#place-importance-schema"
 import { populationBoostTerm, type RankingWeights } from "#ranking-weights"
 import type { RawSearchRow } from "#search-fetch"
 import type { FindPlaceQuery, PlaceCandidate, WOFPlacetype } from "#types"

package/lib/coincident-roles.ts

@@ -38,14 +38,13 @@
  *   be wired as a post-step of the main `scripts/build-unified-wof.ts`.
  */
 
-import type { CoincidentLocality } from "@mailwoman/resolver"
+import type { CoincidentLocality } from "@mailwoman/core/resolver"
+import { allRows } from "@mailwoman/core/utils"
 import { haversineKm } from "@mailwoman/spatial"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { tableExists } from "@mailwoman/sqlite/introspection"
 
 import type { WOFDatabase } from "#schema"
-import { allRows } from "#sqlite-utils"
-
 /**
  * Table of places that hold more than one admin role — a locality that is also its county seat. Written by the
  * gazetteer build, read by the resolver when a coincident locality has to be chosen.

package/lib/coverage-manifest-schema.ts

@@ -29,10 +29,11 @@ import {
 	type CountryCoverageFact,
 	type GazetteerArtifactCoverage,
 } from "@mailwoman/core/resolver"
+import { allRows } from "@mailwoman/core/utils"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { sql, type Kysely } from "kysely"
 
-import { allRows, hasTable } from "#sqlite-utils"
+import { hasTable } from "#sqlite-utils"
 
 /**
  * One country's hard-filter coverage measurement — the storage form of {@link CountryCoverageFact}.

package/lib/currency-backfill.ts

@@ -16,9 +16,9 @@ import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { resolvePath } from "path-ts"
 import { TSVSpliterator } from "spliterator"
 
-import type { loadImportanceIndex } from "#candidate-importance"
-import type { CandidateDatabase } from "#candidate-schema"
+import type { loadImportanceIndex } from "#candidate/importance"
 import type { PlaceAttrs, StageRow } from "#candidate/place-attrs"
+import type { CandidateDatabase } from "#candidate/schema"
 import type { WOFDatabase } from "#schema"
 import { normalizeLocalityForKey } from "#street/normalize"
 

package/lib/fst/builder.ts

@@ -11,6 +11,7 @@
  *   PlaceEntry at terminals → return FSTMatcher.
  */
 
+import { allRows, getRow } from "@mailwoman/core/utils"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 import { resolvePath } from "path-ts"
 
@@ -20,7 +21,6 @@ import { FSTMatcher, normalizeTokens } from "#fst/matcher"
 import type { BuildFSTOpts, BuildFSTResult, FSTProvenance, PlaceEntry, PlacetypeID } from "#fst/types"
 import { loadImportanceSplit } from "#place-importance-schema"
 import type { WOFDatabase } from "#schema"
-import { allRows, getRow } from "#sqlite-utils"
 
 const DEFAULT_PLACETYPES: PlacetypeID[] = [
 	"country",

package/lib/fst/deserialize-web.ts

@@ -67,7 +67,7 @@ export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
 
 	let pos = HEADER_SIZE
 
-	// --- String table ---
+	// Decode the interned string table.
 	const strOffsets = new Uint32Array(stringCount + 1)
 
 	for (let i = 0; i <= stringCount; i++) {
@@ -86,7 +86,7 @@ export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
 
 	pos += stringBytes
 
-	// --- State table ---
+	// Decode the state table and its transitions.
 	const stateEntrySize = version >= VERSION_WIDE_STATE_COUNTERS ? WIDE_STATE_ENTRY_SIZE : NARROW_STATE_ENTRY_SIZE
 	// v5 grew the place entry by the encyclopedic float; v4-and-below files are read at the old stride.
 	const placeEntrySize = isSplit ? SPLIT_PLACE_ENTRY_SIZE : LEGACY_PLACE_ENTRY_SIZE

package/lib/fst/freshness.ts

@@ -146,7 +146,6 @@ export async function peekFSTStampFields(path: string): Promise<FSTStampFields |
  * Re-exported from `@mailwoman/core/hash`. This package's own test imports it from here, and the sidecar convention
  * below is what it is for.
  */
-export { md5File } from "@mailwoman/core/hash"
 
 /**
  * The source identity an FST build should stamp, or a check should compare against.

package/lib/fst/serialize.ts

@@ -77,7 +77,7 @@ for (let i = 0; i < PLACETYPE_ORDER.length; i++) {
 export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): Buffer {
 	const nodes = matcher.toNodes() as FSTNode[]
 
-	// --- String interning ---
+	// Intern state-edge strings before serializing their table.
 	const stringMap = new Map<string, number>()
 	const strings: string[] = []
 
@@ -106,7 +106,7 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 	const encodedStrings = strings.map((s) => Buffer.from(s, "utf8"))
 	const stringBytes = encodedStrings.reduce((sum, b) => sum + b.length, 0)
 
-	// --- Counts ---
+	// Count each serialized record class.
 	let totalEdges = 0
 	let totalPlaces = 0
 
@@ -115,7 +115,7 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 		totalPlaces += node.places.length
 	}
 
-	// --- Allocate ---
+	// Allocate the complete binary buffer.
 	const stringTableSize = (strings.length + 1) * 4 + stringBytes
 	const stateTableSize = nodes.length * WIDE_STATE_ENTRY_SIZE
 	const edgeTableSize = totalEdges * EDGE_ENTRY_SIZE
@@ -127,7 +127,7 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 	const buf = Buffer.alloc(totalSize)
 	let pos = 0
 
-	// --- Header ---
+	// Read the versioned binary header.
 	// flags bit0 (survey #4, 2026-07-27): place rows carry surface-ambiguity data in the former _pad
 	// byte (pp+6 = crossCountryBranches u8, pp+7 reserved). Presence-signaled here so VERSION stays
 	// put: pre-ambiguity artifacts read flags=0 → readers expose `undefined`, never a fake 0.
@@ -151,7 +151,7 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 	buf.writeUInt32LE(provenanceJson ? binarySize : 0, pos)
 	pos += 4
 
-	// --- String table ---
+	// Read the interned string table.
 	let strOffset = 0
 
 	for (const encoded of encodedStrings) {
@@ -170,7 +170,7 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 		pos += encoded.length
 	}
 
-	// --- State, edge, and place tables ---
+	// Read state, edge, and place tables.
 	const stateTableStart = pos
 	const edgeTableStart = stateTableStart + stateTableSize
 	const placeTableStart = edgeTableStart + edgeTableSize
@@ -234,7 +234,7 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 }
 
 export function deserializeFST(buf: Buffer): FSTMatcher {
-	// --- Header ---
+	// Verify the versioned binary header.
 	if (buf.length < HEADER_SIZE) throw new Error("FST buffer too small for header")
 
 	if (!buf.subarray(0, 4).equals(MAGIC)) throw new Error("FST magic mismatch")
@@ -257,7 +257,7 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 
 	let pos = HEADER_SIZE
 
-	// --- String table ---
+	// Verify string-table offsets and contents.
 	const strOffsets = new Uint32Array(stringCount + 1)
 
 	for (let i = 0; i <= stringCount; i++) {
@@ -276,7 +276,7 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 
 	pos += stringBytes
 
-	// --- State table ---
+	// Verify state-table offsets and transitions.
 	const stateEntrySize = version >= VERSION_WIDE_STATE_COUNTERS ? WIDE_STATE_ENTRY_SIZE : NARROW_STATE_ENTRY_SIZE
 	// v5 grew the place entry by the encyclopedic float; v4-and-below files are read at the old stride.
 	const placeEntrySize = version >= VERSION_TWO_SCORE_SPLIT ? SPLIT_PLACE_ENTRY_SIZE : LEGACY_PLACE_ENTRY_SIZE

package/lib/geonames/aliases.ts

@@ -26,19 +26,13 @@
 
 import { isOfficialLanguage } from "@mailwoman/codex/country"
 import { pathExists } from "@mailwoman/core/fs/readers"
+import { GEONAMES_ID_BASE, GEONAMES_POSTAL_ID_BASE } from "@mailwoman/core/resolver/synthetic-id-ranges"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { join, type PathBuilderLike } from "path-ts"
 import { TSVSpliterator } from "spliterator"
 
-import { GEONAMES_POSTAL_ID_BASE } from "#geonames/postal"
 import type { WOFDatabase } from "#schema"
 
-/**
- * Synthetic id base for GeoNames-sourced rows (#743/#193) — above Overture's 8e12 so the three sources (WOF real ids,
- * Overture, GeoNames) never collide in a combined DB.
- */
-export const GEONAMES_ID_BASE = 9_000_000_000_000
-
 /**
  * The four tables the alias fold writes into the range it owns. The purge and the ingest must agree on this list — a
  * table written but not purged is exactly the #1514 defect.

package/lib/geonames/postal.ts

@@ -35,6 +35,7 @@
  */
 
 import { pathExists } from "@mailwoman/core/fs/readers"
+import { GEONAMES_POSTAL_ID_BASE } from "@mailwoman/core/resolver/synthetic-id-ranges"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { join, type PathBuilderLike } from "path-ts"
 import { TSVSpliterator } from "spliterator"
@@ -47,13 +48,6 @@ import type { WOFDatabase } from "#schema"
  */
 const GEONAMES_POSTAL_COLUMNS = 11
 
-/**
- * Synthetic id base for GeoNames-POSTAL rows — its own namespace above the alias fold's {@link GEONAMES_ID_BASE} (9e12)
- * allocation so all four sources (WOF, Overture, GeoNames-alias, GeoNames-postal) coexist collision-free in a combined
- * DB.
- */
-export const GEONAMES_POSTAL_ID_BASE = 9_500_000_000_000
-
 /**
  * The #920 name law: reduce a postcode to the sanitized-query token shape — strip every non-letter/number — so the
  * stored name matches what `sanitizeFTSQuery` produces from the parsed postcode token. `"110 00"` → `"11000"`,

package/lib/index.ts

@@ -29,25 +29,25 @@ export {
 	createCandidateIntervalTable,
 	intervalContains,
 	MAX_ANCESTOR_DEPTH,
-} from "#candidate-ancestors-schema"
+} from "#candidate/ancestors/schema"
 
 export type {
 	CandidateAncestorsDatabase,
 	CandidateAncestorTable,
 	CandidateIntervalTable,
 	IntervalLabel,
-} from "#candidate-ancestors-schema"
+} from "#candidate/ancestors/schema"
 
-export { CANDIDATE_FTS_TABLE, createCandidateFTS } from "#candidate-fts"
+export { CANDIDATE_FTS_TABLE, createCandidateFTS } from "#candidate/fts"
 
 export {
 	ImportanceIndex,
 	IMPORTANCE_JOIN_RADIUS_KM,
 	type ImportanceIndexStats,
 	loadImportanceIndex,
-} from "#candidate-importance"
+} from "#candidate/importance"
 
-export { WOFCandidateTableLookup, type WOFCandidateTableLookupOpts } from "#candidate-lookup"
+export { WOFCandidateTableLookup, type WOFCandidateTableLookupOpts } from "#candidate/lookup"
 
 export {
 	COUNTRY_BBOX_TABLE,
@@ -61,33 +61,26 @@ export {
 export type { CountryBBoxTable, CountryCoverageTable, GazetteerCoverageDatabase } from "#coverage-manifest-schema"
 export { SQLiteStreetNameLookup, type SQLiteStreetNameLookupOpts } from "#street/name-lookup"
 
-export {
-	GEONAMES_ID_BASE,
-	type GeonamesIngestProgress,
-	ingestGeonamesAliases,
-	purgeGeonamesAliasRange,
-} from "#geonames/aliases"
-
-export { GEONAMES_POSTAL_ID_BASE } from "#geonames/postal"
+export { type GeonamesIngestProgress, ingestGeonamesAliases, purgeGeonamesAliasRange } from "#geonames/aliases"
 
-export { ADDRESS_POINT_COLUMNS, createAddressPointIndexes, createAddressPointTable } from "#address/point-schema"
-export type { AddressPointDatabase, AddressPointTable } from "#address/point-schema"
+export { ADDRESS_POINT_COLUMNS, createAddressPointIndexes, createAddressPointTable } from "#address/point/schema"
+export type { AddressPointDatabase, AddressPointTable } from "#address/point/schema"
 
 export {
 	WOFPostalCityAliasLookup,
 	type PostalCityAlias,
 	type WOFPostalCityAliasLookupOpts,
-} from "#postal/city-alias-lookup"
+} from "#postal/city/alias/lookup"
 
-export type { PostalCityAliasDatabase, PostalCityAliasTable } from "#postal/city-alias-schema"
+export type { PostalCityAliasDatabase, PostalCityAliasTable } from "#postal/city/alias/schema"
 
 export {
 	POSTAL_CITY_CANDIDATE_COLUMNS,
 	POSTAL_CITY_CANDIDATE_TABLE,
 	createPostalCityCandidateTable,
-} from "#postal/city-candidate-schema"
+} from "#postal/city/candidate-schema"
 
-export type { PostalCityCandidateDatabase, PostalCityCandidateTable } from "#postal/city-candidate-schema"
+export type { PostalCityCandidateDatabase, PostalCityCandidateTable } from "#postal/city/candidate-schema"
 
 export {
 	ADDRESS_CONVENTION_TABLE,
@@ -103,7 +96,7 @@ export {
 	type Strategy,
 } from "#convention/index"
 
-export { SqliteConventionSource } from "#sqlite-convention-source"
+export { SqliteConventionSource } from "#sqlite/convention-source"
 
 export { WOFPostcodeLookup, type PostcodePlace } from "#postcode-point-lookup"
 
@@ -127,17 +120,17 @@ export {
 	type WOFReverseGeocoderOpts,
 } from "#reverse"
 
-export { AddressPointInterpolator } from "#address/point-interpolation"
-export { AddressPointSqliteLookup } from "#address/point"
+export { AddressPointInterpolator } from "#address/point/interpolation"
+export { AddressPointSqliteLookup } from "#address/point/index"
 
 export {
 	STREET_CENTROID_COLUMNS,
 	createStreetCentroidIndexes,
 	createStreetCentroidTable,
-} from "#street/centroid-schema"
+} from "#street/centroid/schema"
 
-export type { StreetCentroidDatabase, StreetCentroidTable } from "#street/centroid-schema"
-export { StreetCentroidSqliteLookup } from "#street/centroid"
+export type { StreetCentroidDatabase, StreetCentroidTable } from "#street/centroid/schema"
+export { StreetCentroidSqliteLookup } from "#street/centroid/index"
 
 export {
 	StreetInterpolator,

package/lib/interpolation.ts

@@ -27,7 +27,7 @@
  */
 
 import { parseJSONStrict } from "@mailwoman/core/json"
-import type { InterpolationLookup } from "@mailwoman/resolver"
+import type { InterpolationLookup } from "@mailwoman/core/resolver"
 import { clampFraction, haversineKm, pointAlong } from "@mailwoman/spatial"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 

package/lib/lookup.ts

@@ -10,13 +10,15 @@
  *   See `docs/plan/phases/PHASE_4_2_wof_sqlite.md` for the design rationale.
  */
 
-import { expandPlacetypeFilter, type Ancestor, type CoincidentLocality } from "@mailwoman/resolver"
+import { expandPlacetypeFilter } from "@mailwoman/codex/placetype-map"
+import type { Ancestor, CoincidentLocality } from "@mailwoman/core/resolver"
+import { allRows } from "@mailwoman/core/utils"
 import { haversineKm } from "@mailwoman/spatial"
 import type { SQLInputValue } from "@mailwoman/sqlite/client"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 
 import { ancestorLineage } from "#ancestry/index"
-import { candidateFromSearchRow, rankCandidates } from "#candidate-scoring"
+import { candidateFromSearchRow, rankCandidates } from "#candidate/scoring"
 import { loadCoincidentLocalities } from "#coincident-roles"
 import {
 	ADDRESS_CONVENTION_TABLE,
@@ -46,12 +48,11 @@ import {
 import { normalizePlacetypes, sanitizeFTSQuery } from "#fts/query"
 import { cfNormalize, softNameScore } from "#name-score"
 import { encyclopedicClauses } from "#place-importance-schema"
-import type { WOFPostalCityAliasLookup } from "#postal/city-alias-lookup"
+import type { WOFPostalCityAliasLookup } from "#postal/city/alias/lookup"
 import { DEFAULT_WEIGHTS, populationScaleTerm, type RankingWeights } from "#ranking-weights"
 import type { WOFDatabase } from "#schema"
 import { fetchSearchRows, type RawSearchRow } from "#search-fetch"
-import { SqliteConventionSource } from "#sqlite-convention-source"
-import { allRows } from "#sqlite-utils"
+import { SqliteConventionSource } from "#sqlite/convention-source"
 import type { FindPlaceQuery, PlaceCandidate, PlaceLookup, WOFPlacetype } from "#types"
 
 export interface WOFSQLitePlaceLookupOpts {