@mailwoman/resolver-wof-sqlite 9.4.0 → 10.1.0

package/lib/convention.ts

@@ -0,0 +1,144 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Defines resolution conventions as per-polygon profiles merged along a place's ancestor chain.
+ *
+ *   The strategy implementations live in `lookup.ts` and are registered by name.
+ */
+
+import type { FindPlaceQuery, PlaceCandidate } from "#types"
+
+/**
+ * Soft-scoring weights for the `postcode_area_resolution` strategy: `pc·S_pc + name·S_name + pop·S_pop`.
+ */
+export interface ScoringWeights {
+	pc: number
+	name: number
+	pop: number
+}
+
+/**
+ * A resolution profile attached to a Who's On First admin polygon.
+ */
+export interface Convention {
+	/**
+	 * The strategies that the dispatcher runs in order, by registered name.
+	 * The first strategy that returns a non-null result wins.
+	 */
+	candidateStrategies?: string[]
+	/**
+	 * Weights for the `postcode_area_resolution` soft score.
+	 *
+	 * A layer may set some weights and inherit the rest from the layers below it.
+	 */
+	scoringWeights?: Partial<ScoringWeights>
+}
+
+/**
+ * A convention with every field set, as `resolveConvention` returns it to strategies.
+ */
+export interface ResolvedConvention {
+	candidateStrategies: string[]
+	scoringWeights: ScoringWeights
+}
+
+/**
+ * The base layer that every ancestor chain starts from.
+ *
+ * It tries `postcode_area_resolution` and then falls back to fuzzy name matching.
+ * Every place without a convention override uses these values, so a change here
+ * changes resolution in every such country.
+ */
+export const WORLD_DEFAULT: ResolvedConvention = {
+	candidateStrategies: ["postcode_area_resolution", "fallback_fuzzy_name_match"],
+	scoringWeights: { pc: 0.6, name: 0.3, pop: 0.1 },
+}
+
+/**
+ * The names of the strategies that the backend registers.
+ *
+ * The dispatch registry and the build-time validator share this list, so the build
+ * rejects a convention that lists an unknown strategy.
+ */
+export const BUILTIN_STRATEGY_NAMES = ["postcode_area_resolution", "fallback_fuzzy_name_match"] as const
+
+/**
+ * The table name for the convention asset, shared by the build script,
+ * the runtime source and extract detection.
+ */
+export const ADDRESS_CONVENTION_TABLE = "address_convention"
+
+/**
+ * A resolution strategy selected by name.
+ *
+ * @returns `null` to abstain, so the dispatcher tries the next strategy,
+ * or an array, possibly empty, to claim the result.
+ */
+export type Strategy = (query: FindPlaceQuery, convention: ResolvedConvention) => Promise<PlaceCandidate[] | null>
+
+/**
+ * Looks up a convention by WOF polygon id.
+ * `get` returns `undefined` when the polygon has no override.
+ */
+export interface ConventionSource {
+	get(wofID: number): Convention | undefined
+}
+
+/**
+ * An in-memory convention source built from a `{ wofID: Convention }` map.
+ */
+export class SeedConventionSource implements ConventionSource {
+	readonly #rows: Map<number, Convention>
+
+	constructor(rows: Record<number, Convention> = {}) {
+		this.#rows = new Map(Object.entries(rows).map(([k, v]) => [Number(k), v]))
+	}
+
+	get(wofID: number): Convention | undefined {
+		return this.#rows.get(wofID)
+	}
+}
+
+/**
+ * Merges convention layers, with later, more specific layers winning per field.
+ *
+ * A layer's `candidateStrategies` replaces the whole list.
+ * `scoringWeights` merges key by key, so a layer can change one weight without restating the others.
+ */
+export function mergeConventions(base: Convention, ...overrides: Array<Convention | undefined>): Convention {
+	const out: Convention = {
+		candidateStrategies: base.candidateStrategies ? [...base.candidateStrategies] : undefined,
+		scoringWeights: base.scoringWeights ? { ...base.scoringWeights } : undefined,
+	}
+
+	for (const o of overrides) {
+		if (!o) continue
+
+		if (o.candidateStrategies !== undefined) {
+			out.candidateStrategies = [...o.candidateStrategies]
+		}
+
+		if (o.scoringWeights !== undefined) {
+			out.scoringWeights = { ...(out.scoringWeights ?? WORLD_DEFAULT.scoringWeights), ...o.scoringWeights }
+		}
+	}
+
+	return out
+}
+
+/**
+ * Resolves the effective convention for a place from its ancestor ids,
+ * ordered from most general to most specific.
+ *
+ * The merge starts from `WORLD_DEFAULT`, so every field is defined.
+ */
+export function resolveConvention(source: ConventionSource, ancestorIDs: readonly number[]): ResolvedConvention {
+	const layers = ancestorIDs.map((id) => source.get(id))
+	const merged = mergeConventions(WORLD_DEFAULT, ...layers)
+
+	return {
+		candidateStrategies: merged.candidateStrategies ?? WORLD_DEFAULT.candidateStrategies,
+		scoringWeights: { ...WORLD_DEFAULT.scoringWeights, ...merged.scoringWeights },
+	}
+}

package/lib/coverage-manifest-schema.ts

@@ -2,25 +2,11 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
+ * @file Schema and read/write helpers for the candidate gazetteer's coverage manifest.
  *
- *   Typed schema + read/write helpers for the candidate gazetteer's COVERAGE MANIFEST — the two
- *   country-keyed tables through which the artifact declares facts about ITSELF, so those facts are
- *   updated at gazetteer REBUILD, not by a hand-edited code PR after someone remembers:
- *
- *   - `country_coverage`: the hard-country-filter coverage record (#743/#194) — per-country
- *     promotion-eval verdicts + the measured hard-resolve rates that used to live in a code comment on
- *     `HARD_PLACE_COUNTRY_SAFELIST`. Presence = measured; `hard_filter_safe = 0` = measured and
- *     FAILED the check (FI 69.5%, PL 77.8%) — distinguishable from a country never measured at all
- *     (the meaning-of-zero rule, `docs/engineering/reference/layer-contract.mdx`).
- *   - `country_bbox`: the coarse guard-B plausibility boxes that used to live in
- *     `resolver/plausibility.ts`'s `COUNTRY_BBOX`. An absent row fails open (never trips the guard),
- *     exactly like an absent key in the constant.
- *
- *   Emission happens at build time (`mailwoman/gazetteer-pipeline/coverage-manifest.ts` owns the
- *   measured record and calls {@link writeGazetteerCoverageManifest} before the DB is sealed — never
- *   patch a shipped DB, rebuild). The read happens at open time ({@link WOFCandidateTableLookup}
- *   calls {@link readGazetteerCoverageManifest} in its constructor); an artifact that predates the
- *   manifest returns `undefined` and every consumer falls back to the code constants byte-identically.
+ *   The manifest holds two country-keyed tables. `country_coverage` records each measured country's hard-filter
+ *   verdict. A missing row means the country was never measured. `hard_filter_safe = 0` means measurement found the
+ *   filter unsafe. `country_bbox` holds coarse plausibility boxes. A missing bbox row never trips the guard.
  */
 
 import {
@@ -36,41 +22,45 @@ import { sql, type Kysely } from "kysely"
 import { hasTable } from "#sqlite-utils"
 
 /**
- * One country's hard-filter coverage measurement — the storage form of {@link CountryCoverageFact}.
+ * The stored form of {@link CountryCoverageFact}, one row per country.
  */
 export interface CountryCoverageTable {
 	/**
-	 * ISO 3166-1 alpha-2, uppercase (PK).
+	 * The upper-case ISO 3166-1 alpha-2 code.
+	 * This field is the primary key.
 	 */
 	country: string
 	/**
-	 * 0/1 — the promotion-eval verdict (a verdict column, NOT re-derived from the rate; see the fact type's docstring).
+	 * The promotion-eval verdict as 0 or 1.
+	 *
+	 * It is stored directly because the rate by itself does not decide it.
 	 */
 	hard_filter_safe: number
 	/**
-	 * Measured hard-resolve rate 0..1 on the panel named in `source`; NULL when the receipt recorded none.
+	 * The hard-resolve rate from 0 to 1 on the panel given in `source`, or NULL when none was recorded.
 	 */
 	hard_resolve_rate: number | null
 	/**
-	 * Panel size behind `hard_resolve_rate`; NULL when unrecorded.
+	 * The panel size behind `hard_resolve_rate`, or NULL when none was recorded.
 	 */
 	sample_size: number | null
 	/**
-	 * ISO-8601 date of the measurement / promote eval.
+	 * The ISO 8601 date of the measurement.
 	 */
 	measured_at: string
 	/**
-	 * The receipt: which panel/check produced this row.
+	 * The panel or check that produced this row.
 	 */
 	source: string
 }
 
 /**
- * One country's coarse guard-B bounding box — the storage form of {@link CountryBBoxFact}.
+ * The stored form of {@link CountryBBoxFact}, one coarse bounding box per country.
  */
 export interface CountryBBoxTable {
 	/**
-	 * ISO 3166-1 alpha-2, uppercase (PK).
+	 * The upper-case ISO 3166-1 alpha-2 code.
+	 * This field is the primary key.
 	 */
 	country: string
 	lat_min: number
@@ -78,7 +68,7 @@ export interface CountryBBoxTable {
 	lon_min: number
 	lon_max: number
 	/**
-	 * Provenance of the box (harness + date).
+	 * The provenance of the box.
 	 */
 	source: string
 }
@@ -92,16 +82,17 @@ export interface GazetteerCoverageDatabase {
 }
 
 /**
- * Table names the lookup probes (existence-restricted, so a candidate.db built before the manifest is byte-stable).
+ * The name of the per-country coverage table.
+ * Readers check that it exists before querying it.
  */
 export const COUNTRY_COVERAGE_TABLE = "country_coverage"
 /**
- * Table of per-country bounding boxes, used to reject a placement that fell outside its own country.
+ * The name of the per-country bounding-box table, used to reject a placement outside its own country.
  */
 export const COUNTRY_BBOX_TABLE = "country_bbox"
 
 /**
- * Create `country_coverage` — a handful of small PK-probed rows, the WITHOUT ROWID sweet spot.
+ * Creates the `country_coverage` table as a `WITHOUT ROWID` table keyed by country.
  */
 export async function createCountryCoverageTable(db: Kysely<GazetteerCoverageDatabase>): Promise<void> {
 	await db.schema
@@ -113,13 +104,13 @@ export async function createCountryCoverageTable(db: Kysely<GazetteerCoverageDat
 		.addColumn("sample_size", "integer")
 		.addColumn("measured_at", "text", (c) => c.notNull())
 		.addColumn("source", "text", (c) => c.notNull())
-		// `WITHOUT ROWID` has no first-class builder; the raw modifier is the idiomatic fallback.
+		// Kysely has no builder method for `without rowid`.
 		.modifyEnd(sql`without rowid`)
 		.execute()
 }
 
 /**
- * Create `country_bbox` — same shape discipline as {@link createCountryCoverageTable}.
+ * Creates the `country_bbox` table as a `WITHOUT ROWID` table keyed by country.
  */
 export async function createCountryBBoxTable(db: Kysely<GazetteerCoverageDatabase>): Promise<void> {
 	await db.schema
@@ -136,8 +127,10 @@ export async function createCountryBBoxTable(db: Kysely<GazetteerCoverageDatabas
 }
 
 /**
- * Write the coverage manifest into a candidate DB UNDER CONSTRUCTION (pre-seal — a shipped DB is never patched, rebuild
- * instead). Creates both tables and inserts the facts; call exactly once, from the gazetteer build.
+ * Creates both manifest tables in a candidate database under construction and inserts the facts.
+ *
+ * The gazetteer build calls it once.
+ * A shipped database is rebuilt instead of patched.
  */
 export async function writeGazetteerCoverageManifest(
 	db: Kysely<GazetteerCoverageDatabase>,
@@ -180,10 +173,12 @@ export async function writeGazetteerCoverageManifest(
 }
 
 /**
- * Read the coverage manifest from an OPEN candidate DB, or `undefined` when the artifact predates it (neither table
- * present) — the signal for consumers to fall back to the code constants byte-identically. Synchronous raw reads on
- * purpose: this runs inside {@link WOFCandidateTableLookup}'s synchronous constructor (the sync-reader carve-out in
- * `AGENTS.md`), and the tables are a few dozen rows read once per open.
+ * Reads the coverage manifest from an open candidate database.
+ *
+ * It returns `undefined` when neither table exists.
+ * Consumers then fall back to the code constants.
+ *
+ * The reads are synchronous because the candidate lookup calls this from its constructor.
  */
 export function readGazetteerCoverageManifest<DB>(db: DatabaseClient<DB>): GazetteerArtifactCoverage | undefined {
 	const hasCoverage = hasTable(db, COUNTRY_COVERAGE_TABLE)

package/lib/currency-backfill.ts

@@ -3,59 +3,29 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Pass 1c of the candidate build (#1737): resurrect deprecated-with-no-successor WOF localities that a second
- *   source independently attests. Extracted from `build-candidate.ts` as a cohesive unit — the checks, their measured
- *   constants, and the GeoNames dump reader live together here; the build calls {@link resurrectCurrencyHoles} once,
- *   between the primaries pass and the alias pass.
+ *   Restores deprecated WOF localities only when an independent source attests them.
  */
 
 import { pathExists } from "@mailwoman/core/fs/readers"
 import { isStrictlyFiner } from "@mailwoman/core/resources/whosonfirst"
 import { haversineKm } from "@mailwoman/spatial"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
-import { resolvePath } from "path-ts"
+import { type PathBuilderLike, 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"
 
-/**
- * Corroboration radius for the currency backfill (#1737), km — both for the live-near blocker and the GeoNames
- * attestation. Measured basis (2026-08-19 prototype, GB locality slice): at 10 km, 20 of 108 dead names resurrect —
- * Rochester (Kent), Aldershot, Staines, Telford, Ebbw Vale among them — while the `Birmingham/Wolverhampton/…`
- * conurbation blobs stay dead (no attestation) and Swansea/Wrexham stay out because a live same-name row already serves
- * them within the radius.
- */
 const CURRENCY_BACKFILL_RADIUS_KM = 10
 
-/**
- * Minimum attestor population for a resurrection. The same prototype measured 44 of 108 dead GB names attested but
- * under this floor — hamlet-scale ghosts whose absence from the index nobody has reported. A floor keeps the pass
- * answering the measured defect (real settlements) rather than re-importing the tail WOF chose to prune.
- */
 const CURRENCY_BACKFILL_POP_FLOOR = 1000
 
 /**
- * Pass 1c (#1737): resurrect deprecated-with-no-successor localities that a second source independently attests.
- *
- * WOF deprecations WITH a successor need nothing — the successor indexes. A deprecation with `is_superseded = 0` on a
- * populated place is the shape of an upstream mistake (Rochester Kent, Aldershot, Telford; 120 GB localities alone),
- * and it is indistinguishable from a correct pruning at this layer without outside evidence. So every resurrection
- * requires all three conditions, positive evidence only:
- *
- * 1. NO live same-name spr row of any placetype within {@link CURRENCY_BACKFILL_RADIUS_KM} of the dead record — a live row
- *    means the place is alive (possibly under another placetype) and there is no hole. A DISTANT same-name row is a
- *    namesake and does not block.
- * 2. A GeoNames feature-class-P attestation of the same folded name within the radius.
- * 3. The attestor at or above {@link CURRENCY_BACKFILL_POP_FLOOR}.
- *
- * The staged row keeps the WOF identity — id, name, centroid, bbox, region ancestry — because the dead record's own
- * data is not what is wrong with it. GeoNames contributes exactly two things: the attestation, and the population that
- * lets the row stand in prominence races (the dead record's own population is absent). Each name is judged once per
- * country; the resurrected place joins `attrs`, so the alias pass explodes its alt names like any primary's.
+ * Restore a deprecated locality only when no nearby live namesake exists and GeoNames
+ * attests the same folded name above {@link CURRENCY_BACKFILL_POP_FLOOR}.
  */
 export interface CurrencyBackfillOutcomes {
 	judged: number
@@ -66,8 +36,8 @@ export interface CurrencyBackfillOutcomes {
 }
 
 /**
- * One country's read of the check — every dead name judged, by outcome and by the dead row's placetype — so a census
- * can say what a wider dead-row query admits before a build carries it.
+ * One country's read of the check — every dead name judged, by outcome and by the dead
+ * row's placetype — so a census can say what a wider query admits.
  */
 export interface CurrencyBackfillCountryReport extends CurrencyBackfillOutcomes {
 	country: string
@@ -75,8 +45,7 @@ export interface CurrencyBackfillCountryReport extends CurrencyBackfillOutcomes
 	dumpPresent: boolean
 	byDeadPlacetype: Record<string, CurrencyBackfillOutcomes>
 	/**
-	 * The first resurrected names, `placetype:name`, so a census reads what a wider query admits — capped, because the
-	 * report is a receipt and not the table.
+	 * The first resurrected names, `placetype:name`, capped because the report is a receipt and not the table.
 	 */
 	sample: string[]
 }
@@ -84,8 +53,7 @@ export interface CurrencyBackfillCountryReport extends CurrencyBackfillOutcomes
 const REPORT_SAMPLE_SIZE = 25
 
 /**
- * The placetypes a dead row may carry to be judged at all. `locality` is the shipped default; `localadmin` is the
- * second cause #1746 named (one GB row of seventeen) and is admitted through this option once its census is read.
+ * The placetypes a dead row may have to be judged at all; `locality` is the shipped default.
  */
 export const DEFAULT_DEAD_PLACETYPES: readonly string[] = ["locality"]
 
@@ -96,10 +64,10 @@ function emptyOutcomes(): CurrencyBackfillOutcomes {
 export async function resurrectCurrencyHoles(ctx: {
 	src: DatabaseClient<WOFDatabase>
 	/**
-	 * The candidate build's transaction. Required unless `dryRun` — a dry run judges every row and stages nothing.
+	 * The candidate build's transaction, required unless `dryRun`.
 	 */
 	tx?: DatabaseClient<CandidateDatabase>
-	geonamesDir: string
+	geonamesDir: PathBuilderLike
 	countries: readonly string[]
 	attrs: Map<number, PlaceAttrs>
 	ccID: (code: string | null) => number
@@ -108,12 +76,10 @@ export async function resurrectCurrencyHoles(ctx: {
 	importance: ReturnType<typeof loadImportanceIndex> | undefined
 	stageRow: StageRow
 	progress: (phase: string, message: string) => void
-	/**
-	 * Which dead placetypes are judged. Default {@link DEFAULT_DEAD_PLACETYPES}.
-	 */
+
 	deadPlacetypes?: readonly string[]
 	/**
-	 * Judge and count, stage nothing — the census mode. No transaction is opened.
+	 * Judge and count while staging no row and opening no transaction.
 	 */
 	dryRun?: boolean
 	/**
@@ -163,9 +129,9 @@ export async function resurrectCurrencyHoles(ctx: {
 			continue
 		}
 
-		// Dead rows FIRST: a country with no deprecated-no-successor localities needs no attestors at all, and
-		// loading a national dump to judge zero rows is pure heap pressure on a build already near its ceiling
-		// (the first live run OOM'd in a later pass with JP/KR dumps loaded for 0 dead names each).
+		// Read dead rows first.
+		// A country with no dead names then avoids loading its national dump.
+		// That avoids heap pressure on a build near its limit.
 		const dead = deadStmt.all(cc, ...deadPlacetypes)
 
 		if (!dead.length) {
@@ -175,8 +141,8 @@ export async function resurrectCurrencyHoles(ctx: {
 			continue
 		}
 
-		// Only the dead names' own folded keys can ever be probed, so only those keys are worth holding —
-		// the rest of the national dump streams through without residency.
+		// Only the dead names' own folded keys can ever be probed, so the rest of the
+		// national dump streams through without residency.
 		const deadKeys = new Set<string>()
 
 		for (const d of dead) {
@@ -187,8 +153,7 @@ export async function resurrectCurrencyHoles(ctx: {
 			}
 		}
 
-		// Folded name → P-class attestors. GeoNames columns by index: 1 name, 2 ascii, 4 lat, 5 lon,
-		// 6 feature_class, 14 population.
+		// GeoNames columns by index: 1 name, 2 ascii, 4 lat, 5 lon, 6 feature_class, 14 population.
 		const attestors = new Map<string, { lat: number; lon: number; pop: number }[]>()
 
 		for await (const f of TSVSpliterator.fromAsync(dumpPath, { header: false })) {
@@ -232,31 +197,21 @@ export async function resurrectCurrencyHoles(ctx: {
 
 			if (!pkey || seen.has(pkey)) continue
 			seen.add(pkey)
-			// Read from the row: the query admits whatever `deadPlacetypes` names, and the rank comparison below must
-			// judge each candidate against ITS dead rung, never a hardcoded one.
+			// The query admits whatever `deadPlacetypes` names, so the rank comparison
+			// judges each candidate against its own dead rung.
 			const deadPlacetype = String(d.placetype ?? "locality")
 
 			count(deadPlacetype, "judged")
 			const dLat = Number(d.latitude)
 			const dLon = Number(d.longitude)
 
-			// A live row blocks only when it is AT LEAST AS COARSE as the dead one. The original check compared name and
-			// distance alone, on the premise that a nearby same-name row means "the place is alive under another
-			// placetype" — true for a place recorded twice, false for a placetype DEMOTION, which is the shape that
-			// actually occurs: WOF retired `Gillingham` the locality (pop 101,187) and kept `Gillingham` the
-			// neighbourhood 3.2 km away, and the check read the surviving CHILD as covering its own dead parent.
-			// Sixteen of seventeen GB refusals had exactly that shape (#1746).
-			//
-			// An UNRANKED placetype blocks, which is the conservative direction: this check's failure mode is inventing
-			// a place, so a row we cannot rank is treated as covering rather than waved through.
+			// A live row blocks unless it is strictly finer than the dead one.
+			// An unranked placetype also blocks because the failure mode is inventing a place.
 			const liveNear = liveStmt.all(cc, name).some((row) => {
 				if (haversineKm(dLat, dLon, Number(row.latitude), Number(row.longitude)) > CURRENCY_BACKFILL_RADIUS_KM) {
 					return false
 				}
 
-				// Blocks UNLESS the live row is strictly finer. The equal rung must still block — a live `locality`
-				// covers a dead `locality` — and an unranked placetype blocks too, since this check's failure mode
-				// is inventing a place.
 				return isStrictlyFiner(String(row.placetype ?? ""), deadPlacetype) !== true
 			})
 

package/lib/env.ts

@@ -3,7 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- * Environment variables naming the WOF SQLite artifacts this resolver opens, and the development weights the overlay
+ * Environment variables name the WOF SQLite artifacts this resolver opens and the development weights the overlay
  *   linker materializes. CLI flags (`--resolve-db`, …) override these at the call site.
  */
 

package/lib/exact-match.ts

@@ -3,20 +3,25 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The exact-match tier's name probes — the two case-folded equality lookups that decide whether a
+ *   The exact-match tier's name probes, the two case-folded equality lookups that decide whether a
  *   candidate holds the query text as its own name, an alias, or an official name.
  */
 
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { aliasBagExactMatch, foldQueryText } from "#fts/index"
+import { aliasBagExactMatch, foldQueryText } from "#fts"
 
 /**
- * Among `ids`, return the subset whose name OR any alias equals `text` case-insensitively — the exact-match tier for
- * ranking. One indexed query over `<schema>.names`. When the extract has no `names` table (a slim DB built with
- * `dropNames`, or a postcode-only extract), fall back to the self-contained `place_search` FTS content: its `alt_names`
- * column is the same alias set joined on the boundary-preserving `ALIAS_SEPARATOR` (#523), so `aliasBagExactMatch`
- * recovers the exact alias tier ("New York City" → New York) that the dropped `names` table used to provide.
+ * Among `ids`, return the subset whose name or any alias equals `text` case-insensitively,
+ * the exact-match tier for ranking.
+ *
+ * One indexed query over `<schema>.names`.
+ * When the extract has no `names` table (a slim database built with `dropNames`, or a postcode-only extract),
+ * fall back to the self-contained `place_search` FTS content.
+ *
+ * Its `alt_names` column is the same alias set joined on the boundary-preserving
+ * `ALIAS_SEPARATOR`, so `aliasBagExactMatch` recovers the exact alias tier
+ * ("New York City" → New York) that the dropped `names` table used to provide.
  */
 export function exactMatchIDs<DB>(
 	db: DatabaseClient<DB>,
@@ -41,7 +46,8 @@ export function exactMatchIDs<DB>(
 
 		return out
 	} catch {
-		// No `names` table on this extract — fall through to the place_search alias bag.
+		// No `names` table on this extract.
+		// Fall through to the place_search alias bag.
 	}
 
 	try {
@@ -57,12 +63,12 @@ export function exactMatchIDs<DB>(
 			}
 		}
 
-		// Alias pass via the shared bag parser (#523). Separated bags (built since #523) get a true
-		// per-alias equality check, unrestricted — matching the `names`-table branch above, where an
-		// alias match counts as exact regardless of other candidates. Legacy bags (no separator)
-		// fall back to padded containment, conditioned on "no canonical exact in the pool" because their
-		// lost boundaries would otherwise false-promote interior fragments ("York" inside the alias
-		// "New York City") or cross-alias fragments ("York New" across "…York" + "New City…").
+		// Alias pass via the shared bag parser.
+		// Separated bags get a true per-alias equality check, unrestricted, matching the `names`-table
+		// branch above where an alias match counts as exact regardless of other candidates.
+		// Legacy bags without a separator fall back to padded containment, conditioned on "no
+		// canonical exact in the pool" because their lost boundaries would otherwise false-promote
+		// interior fragments ("York" inside the alias "New York City") or cross-alias fragments.
 		const anyCanonicalExact = out.size > 0
 
 		for (const r of rows) {
@@ -71,17 +77,22 @@ export function exactMatchIDs<DB>(
 			}
 		}
 	} catch {
-		// Extract without place_search either → no exact-match tier. Falls back to weighted-sum order.
+		// Extract without place_search either, so there is no exact-match tier.
+		// The caller falls back to weighted-sum order.
 	}
 
 	return out
 }
 
 /**
- * Among `ids` (already known exact matches), the subset holding `text` as an OFFICIAL name (`names.official = 1`, the
- * #940 ingest bit). Same COLLATE NOCASE semantics as {@link WOFSQLitePlaceLookup.#exactMatchIDs} so the two probes
- * agree on what "equals the query" means. Fails soft on gazetteers built before #940 (no `official` column) — the
- * sub-tier then behaves exactly as if `officialNameExact` were off.
+ * Among `ids` (already known exact matches), the subset holding `text` as an
+ * official name (`names.official = 1`, the ingest bit).
+ *
+ * Same collate nocase semantics as {@link WOFSQLitePlaceLookup.#exactMatchIDs},
+ * so the two probes agree on what "equals the query" means.
+ * Fails soft on gazetteers built before the `official` column existed.
+ *
+ * The sub-tier then behaves exactly as if `officialNameExact` were off.
  */
 export function officialNameIDs<DB>(
 	db: DatabaseClient<DB>,
@@ -106,7 +117,7 @@ export function officialNameIDs<DB>(
 			out.add(r.id)
 		}
 	} catch {
-		// Pre-#940 gazetteer (no `official` column) or a names-less slim extract — feature inert.
+		// A gazetteer without the `official` column, or a names-less slim extract, leaves the feature inert.
 	}
 
 	return out