@mailwoman/resolver-wof-sqlite 9.1.0 → 9.2.0

package/candidate-lookup.ts

@@ -14,7 +14,7 @@
  *   {@link normalizeLocalityForKey} (build- and query-consistent), each row is denormalized (display
  *   `name`, centroid, bbox), and population rank is precomputed into `neg_rank` — so the result is
  *   POPULATION-FIRST and COUNTRY-AGNOSTIC (when no `country` filter is given), exactly like the
- *   demo. That's the deliberate divergence from {@link WOFSqlitePlaceLookup}'s FTS/bm25 ranking: a
+ *   demo. That's the deliberate divergence from {@link WOFSQLitePlaceLookup}'s FTS/bm25 ranking: a
  *   bare "Moscow" resolves to the 10.4 M-pop Russian city, not whichever same-name US township bm25
  *   floats to the top.
  *
@@ -25,19 +25,37 @@
 
 import { DatabaseSync } from "node:sqlite"
 
-import { expandPlacetypeFilter, type GazetteerArtifactCoverage } from "@mailwoman/resolver"
-
+import { jaroWinkler, levenshteinSimilarity } from "@mailwoman/match/comparators"
+import {
+	expandPlacetypeFilter,
+	partitionByContainment,
+	type Ancestor,
+	type GazetteerArtifactCoverage,
+} from "@mailwoman/resolver"
+import { haversineKm } from "@mailwoman/spatial"
+
+import {
+	CANDIDATE_ANCESTOR_TABLE,
+	CANDIDATE_INTERVAL_TABLE,
+	intervalContains,
+	type CandidateAncestorTable,
+	type IntervalLabel,
+} from "./candidate-ancestors-schema.ts"
 import { CANDIDATE_FTS_TABLE } from "./candidate-fts.ts"
 import type { CandidateTable, CountryCodeTable, PlacetypeCodeTable } from "./candidate-schema.ts"
 import { readGazetteerCoverageManifest } from "./coverage-manifest-schema.ts"
-import { haversineKm } from "./geo.ts"
-import { trigramJaccard } from "./lookup.ts"
 import { referentialFromPopulation } from "./place-importance-schema.ts"
 import { POSTAL_CITY_CANDIDATE_TABLE, type PostalCityCandidateTable } from "./postal-city-candidate-schema.ts"
-import { hasColumn, hasTable } from "./sqlite-utils.ts"
-import { normalizeLocalityForKey, stripLocalityQualifier } from "./street-normalize.ts"
+import { rankByPrimaryPreference, type RankedRow, RERANK_FETCH } from "./primary-preference.ts"
+import { applyProximityRerank } from "./proximity-rerank.ts"
+import { REGION_CLASS_PLACETYPES, regionQualifierProbeKeys } from "./region-keys.ts"
+import { allRows, hasColumn, hasTable } from "./sqlite-utils.ts"
+import { type NameKey, normalizeLocalityForKey, stripLocalityQualifier } from "./street-normalize.ts"
 import type { FindPlaceQuery, PlaceCandidate, PlaceLookup, WOFPlacetype } from "./types.ts"
 
+export { rankByPrimaryPreference } from "./primary-preference.ts"
+export type { RankedRow } from "./primary-preference.ts"
+
 export interface WOFCandidateTableLookupOpts {
 	/**
 	 * Path to a `candidate.db` built by `build-candidate.ts`. Opened read-only.
@@ -47,6 +65,12 @@ export interface WOFCandidateTableLookupOpts {
 	 * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
 	 */
 	database?: DatabaseSync
+	/**
+	 * #1882 opt-in: exempt `name_role = 'variant'` aliases — the holder's own primary name in another orthography,
+	 * stamped by the build's own-name detector — from the cross-country primary-preference penalty. No-ops on an artifact
+	 * without the role column. Default OFF (D-rule).
+	 */
+	variantAliasExemption?: boolean
 }
 
 /**
@@ -77,126 +101,37 @@ type CandidateRow = Pick<
 	Partial<Pick<CandidateTable, "importance">>
 
 /**
- * FTS5-trigram over-fetch before the trigram-Jaccard re-rank, and the minimum similarity to count as a fuzzy hit (below
- * it the trigram overlap is noise, e.g. unrelated same-trigram names). Tunable.
+ * FTS5-trigram over-fetch before the WORD-LEVEL re-rank. The trigram index stays the candidate GENERATOR (it is what
+ * the artifact carries); the scoring moved off trigram-Jaccard on 2026-08-12 (#1614), which the aucklnad receipts
+ * falsified as a typo measure: it scored the true transposition correction 'auckland' at 0.333 — below its own 0.34 bar
+ * — while 'auckley' scored 0.375 and the 'gore bay' scrape 0.455, because shared generic suffixes count as trigram
+ * evidence and transpositions count against it.
  */
 const FUZZY_FETCH = 40
-const FUZZY_MIN = 0.34
 
 /**
- * Postcode-containment re-rank gate radius (km) — the SAME value the resolver's country pass measures at
- * (`POSTCODE_COUNTRY_COHERENCE_GATE_KM`, resolver/postcode-country-coherence.ts): a locality within this distance of
- * the postcode's own centroid counts as "containing" it. One number, two passes — a divergence here would make the two
- * mechanisms disagree about what is proximal.
+ * Minimum WORD-LEVEL similarity (max of Jaro-Winkler and normalized edit similarity — the `match/comparators`
+ * primitives, deliberately WITHOUT `nameSimilarity`'s token-subset floor, which is a person-name rule that would hand
+ * 'stanmore bay' to a place named 'Bay') for a fuzzy correction to count. Measured on the #1614 receipts:
+ * 'aucklnad'→'auckland' 0.975 (in), →'auckley' 0.868 (in, but outranked), 'stanmore bay'→'gore bay' ~0.70 (out),
+ * 'sacremento'→'sacramento' ~0.97 (in).
  */
-const POSTCODE_CONTAINMENT_GATE_KM = 25
+const WORD_FUZZY_MIN = 0.85
 
 /**
- * Bounded PRIMARY-NAME preference across a CROSS-COUNTRY name collision (the `is_primary` ranking signal).
- *
- * The raw candidate order is population-first (`neg_rank ASC`) and treats an ALIAS row (a place's alt-name / exonym,
- * `is_primary=0`) and a PRIMARY-name row (`is_primary=1`) on equal footing. So a foreign place whose transliterated
- * exonym coincidentally normalizes to a query — Changchun CN stores the Turkish exonym "Çançun" (`name_key="cancun"`),
- * 4.19 M pop — outranks the PRIMARY-name place the query actually means (Cancún MX, 0.89 M pop). This penalty makes a
- * same-key alias have to clear a population MARGIN over a foreign primary before it wins.
- *
- * It is deliberately NOT a dominant sort key (no `ORDER BY is_primary DESC`, which would make every primary outrank
- * every alias and break the alt-names users depend on — "NYC"→New York, "LA"→Los Angeles, "Frisco"→San Francisco). Two
- * bounds keep it a soft prior:
- *
- * 1. **Cross-country only.** The penalty applies to an alias ONLY when the top-population primary sharing the key is in a
- *    DIFFERENT country. A SAME-country nickname contest (San Francisco's alias "Frisco" vs the primary Frisco, TX —
- *    both US) is left on pure population, so the legitimate alias still wins.
- * 2. **Population-bounded.** The penalty is {@link PRIMARY_PREFERENCE_LOG10} in log10-population units — an alias must be
- *    at least 10x more populous than the foreign primary to still win. So a genuinely dominant alias keeps winning
- *    ("Los Angeles" over La, Ghana — gap 1.6; "Las Vegas" over Vegas, Cuba — gap 2.4) while a near-tie coincidental
- *    collision defers to the primary (Cancún over Changchun — gap 0.7).
- */
-const PRIMARY_PREFERENCE_LOG10 = 1
-
-/**
- * Over-fetch cap for {@link rankByPrimaryPreference}: the candidate rows for one `name_key` (all same-name places
- * worldwide) are re-ranked in-process, so the probe fetches this many (population-ordered) before the re-rank rather
- * than the caller's small `limit`, ensuring the intended primary isn't cut below the fold by a cluster of more-populous
- * foreign aliases. Bounded and small — a single contiguous B-tree scan.
+ * The word-level correction similarity — see {@link WORD_FUZZY_MIN}.
  */
-const RERANK_FETCH = 64
-
-/**
- * A candidate row annotated with the {@link rankByPrimaryPreference} effective rank + the exact-tier demotion flag.
- */
-export type RankedRow<R> = R & {
-	/**
-	 * `neg_rank` plus the bounded cross-country alias penalty — the value the row is ORDERED by, and the base the emitted
-	 * `prominence` is derived from (so the resolver walk's `prominence ?? score` sort, `resolve.ts`, agrees with this
-	 * order; the raw `score`/`neg_rank` is left intact for the walk's `minWinningScore` gate).
-	 */
-	effectiveNegRank: number
-	/**
-	 * True when this row is a cross-country alias that LOST the bounded population contest to the same-key primary — a
-	 * coincidental foreign exonym (Changchun's "Çançun" for "Cancun"). Such a row is dropped out of the exact-match tier
-	 * (`exactMatch=false`) so the resolver walk's country pin — the model's `anchorPosterior`, which "never crosses the
-	 * exact/partial boundary" (`resolve.ts`) — can't ride a spurious posterior (CN 0.86 for "Cancun") back over the
-	 * primary. Only the LOSING foreign alias is demoted; a dominant alias (Los Angeles over La, Ghana) keeps its exact
-	 * tier, and a same-country nickname (San Francisco's "Frisco") is never touched.
-	 */
-	demoted: boolean
-	/**
-	 * True when this row came from the TYPO-CORRECTOR tier — the FTS5-trigram fallback that fires only after the exact
-	 * and qualifier-strip probes both missed. Such a row answers a query the gazetteer does not contain, so it is a fuzzy
-	 * match by construction and must not claim `exactMatch` (#17). Recall is unaffected: the row is still returned, still
-	 * ranked, still resolvable — it just stops asserting a match quality it does not have, which is what the FTS backend
-	 * has always done and what every `exactMatch`-filtering consumer assumed.
-	 */
-	fuzzy?: boolean
+function wordFuzzySimilarity(a: string, b: string): number {
+	return Math.max(jaroWinkler(a, b), levenshteinSimilarity(a, b))
 }
 
 /**
- * Bounded cross-country primary-name preference (see {@link PRIMARY_PREFERENCE_LOG10}). Pure + total-ordered so
- * `candidate-lookup.test.ts` can exercise it on synthetic rows. `rows` arrive population-ordered (`neg_rank ASC`); an
- * alias (`is_primary=0`) is pushed back by `delta` in log10-population units ONLY when the top-population primary
- * sharing the key is in a different country, and is `demoted` out of the exact tier when that penalty leaves it BEHIND
- * the primary. Returns the top `limit` after the re-rank, each annotated.
+ * Postcode-containment re-rank gate radius (km) — the SAME value the resolver's country pass measures at
+ * (`POSTCODE_COUNTRY_COHERENCE_GATE_KM`, resolver/postcode-country-coherence.ts): a locality within this distance of
+ * the postcode's own centroid counts as "containing" it. One number, two passes — a divergence here would make the two
+ * mechanisms disagree about what is proximal.
  */
-export function rankByPrimaryPreference<R extends Pick<CandidateRow, "neg_rank" | "is_primary" | "country_id">>(
-	rows: readonly R[],
-	limit: number,
-	delta = PRIMARY_PREFERENCE_LOG10
-): Array<RankedRow<R>> {
-	// The primary the alias actually competes with for the top slot: highest population (min neg_rank). Undefined
-	// when the set has no primary → nothing to prefer, penalty is 0, order stays population-first (today's behavior).
-	let topPrimary: R | undefined
-
-	for (const r of rows) {
-		if (r.is_primary === 1 && (topPrimary === undefined || r.neg_rank < topPrimary.neg_rank)) {
-			topPrimary = r
-		}
-	}
-
-	const topCountry = topPrimary?.country_id
-
-	// A cross-country alias (different country than the top primary) is penalized; it is DEMOTED when even after — i.e.
-	// the penalty leaves its effective rank behind the primary's raw rank (it lost the bounded population contest).
-	const isCrossCountryAlias = (r: R): boolean =>
-		topCountry !== undefined && r.is_primary !== 1 && r.country_id !== topCountry
-
-	const annotate = (r: R): RankedRow<R> => {
-		const penalized = isCrossCountryAlias(r)
-		const effectiveNegRank = r.neg_rank + (penalized ? delta : 0)
-
-		return { ...r, effectiveNegRank, demoted: penalized && effectiveNegRank > topPrimary!.neg_rank }
-	}
-
-	return (
-		rows
-			.map((r, i) => ({ row: annotate(r), i }))
-			// Effective rank ASC; ties keep population order, then original index (stable).
-			// oxlint-disable-next-line unicorn/no-array-sort -- sorts a freshly-built array; toSorted would double-allocate on a hot path
-			.sort((a, b) => a.row.effectiveNegRank - b.row.effectiveNegRank || a.row.neg_rank - b.row.neg_rank || a.i - b.i)
-			.slice(0, limit)
-			.map((x) => x.row)
-	)
-}
+const POSTCODE_CONTAINMENT_GATE_KM = 25
 
 /**
  * Unpadded character-trigrams of `s`, OR'd into an FTS5 trigram MATCH query (each quoted so FTS treats it as a literal
@@ -218,7 +153,7 @@ function ftsTrigramQuery(s: string): string {
 }
 
 /**
- * Node {@link PlaceLookup} over `candidate.db`. Drop-in for {@link WOFSqlitePlaceLookup} in `createWOFResolver(backend)`
+ * Node {@link PlaceLookup} over `candidate.db`. Drop-in for {@link WOFSQLitePlaceLookup} in `createWOFResolver(backend)`
  * — same `findPlace` contract, population-first ranking.
  */
 export class WOFCandidateTableLookup implements PlaceLookup {
@@ -259,6 +194,48 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 	 * into `no such column` on the first keystroke rather than into "no fame signal", which is what it is.
 	 */
 	readonly #importanceSelect: string
+	/**
+	 * Whether the artifact carries the #1730 `name_role` column — absent on pre-role builds, where the `excludeNameRoles`
+	 * filter degrades to a no-op rather than erroring on a missing column.
+	 */
+	readonly #hasNameRole: boolean
+	readonly #variantAliasExemption: boolean
+	/**
+	 * `", name_role"` when the artifact carries the column — the probe SELECT rides it so the #1882 exemption can read
+	 * the stamp off the row; empty on a pre-role build.
+	 */
+	readonly #roleSelect: string
+	/**
+	 * Prepared chain probe over the `candidate_ancestor` sidecar — `undefined` when the artifact predates it.
+	 */
+	readonly #ancestorsProbe: ReturnType<DatabaseSync["prepare"]> | undefined
+	readonly #ancestorsCache = new Map<number, Ancestor[]>()
+	/**
+	 * Prepared interval-label probe over `candidate_interval` — `undefined` when the artifact predates the sidecar, which
+	 * is what makes the admin-containment re-rank (#1717 stage 2) capability-gated: without it,
+	 * `FindPlaceQuery.regionQualifier` is ignored, no candidate carries a `containedByQualifier` stamp, and the resolver
+	 * walk reports the lever `unavailable` instead of silently dead.
+	 */
+	readonly #intervalProbe: ReturnType<DatabaseSync["prepare"]> | undefined
+	readonly #intervalCache = new Map<number, IntervalLabel | null>()
+	/**
+	 * Prepared qualifier probe: the region-band rows (plus `country` — the region SLOT can hold a mislabeled country
+	 * name, "Moscow, Russia" parses region="Russia") for one folded qualifier key. `undefined` when the artifact lacks
+	 * the sidecar or the placetype dictionary lacks the band entirely.
+	 */
+	readonly #qualifierProbe: ReturnType<DatabaseSync["prepare"]> | undefined
+	/**
+	 * The ancestor lineage of a resolved place — nearest-first (locality-tier → county → region → … → country), the same
+	 * order the FTS backend's `ancestorLineage` serves, read from the `candidate_ancestor` sidecar in one clustered
+	 * probe. Backs `ResolveOpts.includeAncestors` (#404) on this backend, which is what puts region-class ancestry in
+	 * front of the admin-coherence check (#1717).
+	 *
+	 * A PROPERTY, not a method, and assigned only when the artifact carries the sidecar: capability probes (`typeof
+	 * backend.ancestors === "function"` — the resolver's gap report) then read the ARTIFACT truthfully. A candidate.db
+	 * built before the sidecar reports the capability absent instead of presenting a method that answers `[]` for every
+	 * place, which would be an absence dressed as a negative answer.
+	 */
+	readonly ancestors: ((id: number | string) => Ancestor[]) | undefined
 
 	constructor(opts: WOFCandidateTableLookupOpts) {
 		if (opts.database) {
@@ -273,15 +250,13 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 
 		// The code tables are tiny (country/placetype dictionaries) — load them once at construction so
 		// `findPlace` is a single B-tree probe with no dictionary round-trip.
-		for (const r of this.#db.prepare("SELECT id, code FROM country_codes").all() as unknown as CountryCodeTable[]) {
+		for (const r of allRows<CountryCodeTable>(this.#db.prepare("SELECT id, code FROM country_codes"))) {
 			const code = String(r.code).toUpperCase()
 			this.#countryToID.set(code, Number(r.id))
 			this.#idToCountry.set(Number(r.id), code)
 		}
 
-		for (const r of this.#db
-			.prepare("SELECT id, placetype FROM placetype_codes")
-			.all() as unknown as PlacetypeCodeTable[]) {
+		for (const r of allRows<PlacetypeCodeTable>(this.#db.prepare("SELECT id, placetype FROM placetype_codes"))) {
 			this.#placetypeToID.set(String(r.placetype), Number(r.id))
 			this.#idToPlacetype.set(Number(r.id), String(r.placetype))
 		}
@@ -306,6 +281,38 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 
 		// #28 fame column: probed ONCE here (it runs a PRAGMA, and `findPlace` is per-keystroke hot).
 		this.#importanceSelect = hasColumn(this.#db, "candidate", "importance") ? ", importance" : ""
+		this.#hasNameRole = hasColumn(this.#db, "candidate", "name_role")
+		this.#variantAliasExemption = opts.variantAliasExemption === true
+		this.#roleSelect = this.#hasNameRole ? ", name_role" : ""
+
+		// Ancestors sidecar (#1717): existence-gated like the probes above, and the CAPABILITY gates with
+		// it — see the `ancestors` property doc for why an older artifact must read as "no ancestors()"
+		// rather than as a method that answers [] everywhere.
+		if (hasTable(this.#db, CANDIDATE_ANCESTOR_TABLE)) {
+			this.#ancestorsProbe = this.#db.prepare(
+				`SELECT parent_spr_id, parent_placetype_id, parent_name FROM ${CANDIDATE_ANCESTOR_TABLE}` +
+					" WHERE spr_id = ? ORDER BY depth ASC"
+			)
+
+			this.ancestors = (id) => this.#ancestorLineage(id)
+		}
+
+		// Admin-containment re-rank (#1717 stage 2): gated on the interval half of the sidecar (built in
+		// the same pass as the closure rows; probed separately so a hand-degraded artifact degrades
+		// truthfully) AND on the placetype dictionary carrying the qualifier band at all.
+		if (this.#ancestorsProbe && hasTable(this.#db, CANDIDATE_INTERVAL_TABLE)) {
+			this.#intervalProbe = this.#db.prepare(`SELECT pre, post FROM ${CANDIDATE_INTERVAL_TABLE} WHERE spr_id = ?`)
+
+			const bandIDs = [...REGION_CLASS_PLACETYPES, "country"]
+				.map((placetype) => this.#placetypeToID.get(placetype))
+				.filter((id): id is number => id !== undefined)
+
+			if (bandIDs.length) {
+				this.#qualifierProbe = this.#db.prepare(
+					`SELECT DISTINCT spr_id FROM candidate WHERE name_key = ? AND placetype_id IN (${bandIDs.join(",")}) LIMIT 8`
+				)
+			}
+		}
 
 		// Coverage manifest (survey candidate #2): the artifact's own coverage facts, existence-gated like
 		// the probes above — a candidate.db built before the manifest reads `undefined` and consumers keep
@@ -313,6 +320,225 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		this.artifactCoverage = readGazetteerCoverageManifest(this.#db)
 	}
 
+	/**
+	 * The memoized chain read behind {@link ancestors}. Sync raw `.prepare()` on purpose — the backend contract's
+	 * `ancestors()` is synchronous (the sync-by-interface resolver-reader rule), and the sidecar row already carries the
+	 * parent's name and placetype, so this is one clustered probe with no join.
+	 */
+	#ancestorLineage(id: number | string): Ancestor[] {
+		const pid = typeof id === "number" ? id : Number(id)
+
+		if (!Number.isFinite(pid) || !this.#ancestorsProbe) return []
+
+		const cached = this.#ancestorsCache.get(pid)
+
+		if (cached) return cached
+
+		const rows = allRows<Pick<CandidateAncestorTable, "parent_spr_id" | "parent_placetype_id" | "parent_name">>(
+			this.#ancestorsProbe,
+			pid
+		)
+
+		const lineage: Ancestor[] = rows.map((r) => ({
+			id: Number(r.parent_spr_id),
+			placetype: this.#idToPlacetype.get(Number(r.parent_placetype_id)) ?? "",
+			name: String(r.parent_name ?? ""),
+		}))
+
+		this.#ancestorsCache.set(pid, lineage)
+
+		return lineage
+	}
+
+	/**
+	 * The interval label for one place, memoized. `null` is a real answer — the place has no recorded ancestry in the
+	 * source (absence semantics: UNVERIFIABLE, never a containment verdict) — and is cached as such.
+	 */
+	#intervalLabel(sprID: number): IntervalLabel | null {
+		if (!this.#intervalProbe) return null
+
+		const cached = this.#intervalCache.get(sprID)
+
+		if (cached !== undefined) return cached
+
+		const row = this.#intervalProbe.get(sprID) as { pre: number; post: number } | undefined
+		const label = row ? { pre: Number(row.pre), post: Number(row.post) } : null
+
+		this.#intervalCache.set(sprID, label)
+
+		return label
+	}
+
+	/**
+	 * The qualifier's own rows in the candidate table: every region-band (+ country) place whose `name_key` matches one
+	 * of the qualifier's {@link regionQualifierProbeKeys} expansions. Alias keys participate — `Thüringen` finds the row
+	 * stored as `Thuringia` through the artifact's own alias keying, which is precisely the variant-form bridge the
+	 * admin-coherence verdicts' fold-equality bound cannot offer (its stated v1 bound). Empty = the qualifier names
+	 * nothing the artifact knows; the caller then stamps `false` everywhere and reorders nothing.
+	 */
+	#qualifierRegionIDs(qualifier: string, country: string | undefined): Set<number> {
+		const ids = new Set<number>()
+
+		if (!this.#qualifierProbe) return ids
+
+		for (const key of regionQualifierProbeKeys(qualifier, country)) {
+			if (!key) continue
+
+			for (const row of allRows<{ spr_id: number }>(this.#qualifierProbe, key)) {
+				ids.add(Number(row.spr_id))
+			}
+		}
+
+		return ids
+	}
+
+	/**
+	 * Is `sprID` contained by ANY of the qualifier's rows? Interval first — {@link intervalContains}, O(1), reflexive —
+	 * then the closure rows where intervals abstain: the interval forest encodes only the CANONICAL parent per place, so
+	 * a `false` there means "not contained along the canonical hierarchy", and the chain probe (one clustered read of
+	 * ≤{@link MAX_ANCESTOR_DEPTH} rows) is the complete record that settles it.
+	 */
+	#containedByQualifier(sprID: number, qualifierIDs: ReadonlySet<number>, qualifierLabels: IntervalLabel[]): boolean {
+		if (qualifierIDs.has(sprID)) return true
+
+		const label = this.#intervalLabel(sprID)
+
+		if (label && qualifierLabels.some((outer) => intervalContains(outer, label))) return true
+
+		return this.#ancestorLineage(sprID).some((ancestor) => qualifierIDs.has(Number(ancestor.id)))
+	}
+
+	/**
+	 * The #1717 stage-2 re-rank over one lookup's final row set. Three steps, each additive:
+	 *
+	 * 1. Resolve the qualifier to its region-band rows ({@link #qualifierRegionIDs}) and stamp every existing row's
+	 *    `containedByQualifier` — the stamp is the trace surface, written even when nothing reorders.
+	 * 2. INJECT contained same-key candidates the country scope hid: the deciding-site measurement (2026-08-18, the #1729
+	 *    lesson re-confirmed) showed `Weimar, Thüringen` under the en-US locale probes `country_id = US`, so the DE row
+	 *    is not IN the list and no reorder of the list can reach it. The injection probe runs the same exact fold (and,
+	 *    on a contained-miss, the qualifier-strip variant restricted to primary keys — the #1626 alias-scrape guard)
+	 *    under the SHAPE conds only, appends contained rows not already present, and never removes anything — recall can
+	 *    only widen. The typo-fuzzy tier is deliberately not probed: a qualifier cannot vouch for a name the gazetteer
+	 *    does not carry.
+	 * 3. Partition contained-first — the SHARED {@link partitionByContainment} (tier-safe, stable; the resolver walk runs
+	 *    the same function after its fame re-rank, one function at both deciding sites per the #861 rule) — then
+	 *    re-window to `limit`.
+	 *
+	 * A qualifier that matches nothing stamps `false` everywhere and reorders nothing — byte-identical answers, and the
+	 * walk's verdict reads `no_contained_candidate` rather than `unavailable` (the question WAS asked).
+	 */
+	#applyAdminContainment(
+		rows: Array<RankedRow<CandidateRow>>,
+		qualifier: string,
+		country: string | undefined,
+		opts: {
+			nameKey: NameKey
+			strippedKey: NameKey
+			shapeFilters: string[]
+			shapeParams: Array<string | number>
+			limit: number
+		}
+	): Array<RankedRow<CandidateRow>> {
+		const qualifierIDs = this.#qualifierRegionIDs(qualifier, country)
+
+		if (!qualifierIDs.size) {
+			for (const row of rows) {
+				row.containedByQualifier = false
+			}
+
+			return rows
+		}
+
+		const qualifierLabels = [...qualifierIDs]
+			.map((id) => this.#intervalLabel(id))
+			.filter((label): label is IntervalLabel => label !== null)
+
+		const contained = (sprID: number): boolean => this.#containedByQualifier(sprID, qualifierIDs, qualifierLabels)
+
+		for (const row of rows) {
+			row.containedByQualifier = contained(Number(row.spr_id))
+		}
+
+		const present = new Set(rows.map((row) => Number(row.spr_id)))
+		const injected: Array<RankedRow<CandidateRow>> = []
+
+		const injectSQL = (primaryOnly: boolean): string =>
+			"SELECT spr_id, name, country_id, placetype_id, latitude, longitude, min_lat, min_lon, max_lat, max_lon, neg_rank, is_primary, population" +
+			`${this.#importanceSelect} FROM candidate WHERE ${["name_key = ?", ...opts.shapeFilters, ...(primaryOnly ? ["is_primary = 1"] : [])].join(" AND ")} ` +
+			"ORDER BY neg_rank ASC LIMIT ?"
+
+		const injectFrom = (key: string, primaryOnly: boolean): void => {
+			const fetched = allRows<CandidateRow>(
+				this.#db.prepare(injectSQL(primaryOnly)),
+				key,
+				...opts.shapeParams,
+				RERANK_FETCH
+			)
+
+			for (const row of fetched) {
+				const sprID = Number(row.spr_id)
+
+				if (present.has(sprID) || !contained(sprID)) continue
+				present.add(sprID)
+
+				injected.push({ ...row, effectiveNegRank: row.neg_rank, demoted: false, containedByQualifier: true })
+			}
+		}
+
+		injectFrom(opts.nameKey, false)
+
+		// #1731: the dependent-locality band. A locality query's filter group (locality/borough/localadmin)
+		// cannot reach a neighbourhood-tier namesake, so a CONTAINED one is structurally invisible no matter
+		// how the list reorders — the Astoria class: Queens' Astoria is a WOF neighbourhood, and the walk
+		// answered the Oregon locality under `qualifier="NY"` because nothing in the pool sat under NY. The
+		// widening is injection-only and triple-gated: the band is explicit (neighbourhood/macrohood/microhood
+		// — never region or country tiers), admission still requires the sidecar's containment proof, and only
+		// primary-keyed rows enter (an alias-keyed neighbourhood is the #1626 scrape class). Recall can only
+		// widen, and only toward rows the qualifier vouches for. `opts.shapeFilters`' bbox clause is
+		// deliberately not carried: containment is the stronger constraint, and the two co-occurring is not a
+		// measured shape.
+		const bandIDs = ["neighbourhood", "macrohood", "microhood"]
+			.map((placetype) => this.#placetypeToID.get(placetype))
+			.filter((id): id is number => id !== undefined)
+
+		if (bandIDs.length) {
+			const bandSQL =
+				"SELECT spr_id, name, country_id, placetype_id, latitude, longitude, min_lat, min_lon, max_lat, max_lon, neg_rank, is_primary, population" +
+				`${this.#importanceSelect} FROM candidate WHERE name_key = ? AND placetype_id IN (${bandIDs.map(() => "?").join(",")}) AND is_primary = 1 ` +
+				"ORDER BY neg_rank ASC LIMIT ?"
+
+			const fetched = allRows<CandidateRow>(this.#db.prepare(bandSQL), opts.nameKey, ...bandIDs, RERANK_FETCH)
+
+			for (const row of fetched) {
+				const sprID = Number(row.spr_id)
+
+				if (present.has(sprID) || !contained(sprID)) continue
+				present.add(sprID)
+
+				injected.push({ ...row, effectiveNegRank: row.neg_rank, demoted: false, containedByQualifier: true })
+			}
+		}
+
+		// The strip variant mirrors the cascade's discipline: tried only when the exact fold vouched for
+		// nothing, and primary-keyed only (a stripped surface never named an alias — #1626).
+		if (
+			!injected.length &&
+			!rows.some((row) => row.containedByQualifier) &&
+			opts.strippedKey &&
+			opts.strippedKey !== opts.nameKey
+		) {
+			injectFrom(opts.strippedKey, true)
+		}
+
+		if (!injected.length && !rows.some((row) => row.containedByQualifier)) return rows
+
+		return partitionByContainment(
+			[...rows, ...injected],
+			(row) => row.containedByQualifier === true,
+			(row) => !row.demoted && !row.fuzzy
+		).slice(0, opts.limit)
+	}
+
 	/**
 	 * Does this query want a locality-tier place? Postal-city aliases (#741) are all localities.
 	 */
@@ -402,9 +628,15 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 
 		const limit = Math.max(1, query.limit ?? 10)
 
-		// Filter conds shared by the exact-key + strip-fallback probes (everything but name_key).
+		// Filter conds shared by the exact-key + strip-fallback probes (everything but name_key). The
+		// SHAPE subset (placetype/bbox/primary — everything but the country scope) is kept separately
+		// because the admin-containment injection probe (#1717 stage 2) runs under the shape conds
+		// WITHOUT the country: bypassing a locale-inferred country scope for a qualifier-vouched
+		// candidate is the lever's whole point, and it is the one filter injection may cross.
 		const filters: string[] = []
 		const filterParams: Array<string | number> = []
+		const shapeFilters: string[] = []
+		const shapeParams: Array<string | number> = []
 
 		if (query.country) {
 			const cid = this.#countryToID.get(query.country.toUpperCase())
@@ -424,16 +656,37 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 				.filter((v): v is number => v !== undefined)
 
 			if (!ids.length) return []
-			filters.push(`placetype_id IN (${ids.map(() => "?").join(",")})`)
-			filterParams.push(...ids)
+			shapeFilters.push(`placetype_id IN (${ids.map(() => "?").join(",")})`)
+			shapeParams.push(...ids)
 		}
 
 		if (query.bbox) {
 			const b = query.bbox
-			filters.push("latitude BETWEEN ? AND ? AND longitude BETWEEN ? AND ?")
-			filterParams.push(b.minLat, b.maxLat, b.minLon, b.maxLon)
+			shapeFilters.push("latitude BETWEEN ? AND ? AND longitude BETWEEN ? AND ?")
+			shapeParams.push(b.minLat, b.maxLat, b.minLon, b.maxLon)
+		}
+
+		// The re-reading guard (#1632, the #1626 rationale generalized to the caller): a probe whose surface
+		// is a token cut out of a longer classified span never NAMED an alias, so alias-keyed rows must not
+		// answer it — 'Savile Row''s token 'Row' resolved Rhu, Scotland (585 km) through the village's
+		// historical-name alias key. Whole-input bare probes never set this, keeping the exonym recall the
+		// #1546 note protects (Москва's alias rows answer 'Moscow').
+		if (query.primaryOnly) {
+			shapeFilters.push("is_primary = 1")
+		}
+
+		// The role guard (#1730): a probe may refuse abbreviation/gloss alias rows while keeping the
+		// role-NULL exonym tier open — the distinction `primaryOnly` cannot express. Degrades to a no-op
+		// on an artifact without the column.
+		if (query.excludeNameRoles?.length && this.#hasNameRole) {
+			shapeFilters.push(`(name_role IS NULL OR name_role NOT IN (${query.excludeNameRoles.map(() => "?").join(",")}))`)
+			shapeParams.push(...query.excludeNameRoles)
 		}
 
+		// The main-probe conds are country-then-shape, exactly the order they have always been.
+		filters.push(...shapeFilters)
+		filterParams.push(...shapeParams)
+
 		// Region scope: when the cascade resolves a region and passes it down as `parentID` (the walk sets
 		// `query.parentID = parentResolved.id`), the candidate build stamps each place's region-tier ancestor
 		// id into `region_id` (build-candidate.ts `regionOf`), and that id equals the resolved region's WOF id
@@ -444,7 +697,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		// ancestor), or a wrong parent degrades to today's behavior — never worse, recall-safe by construction.
 		const regionParentID = query.parentID || undefined
 
-		const probe = (nk: string, regionID: number | undefined): Array<RankedRow<CandidateRow>> => {
+		const probe = (nk: string, regionID: number | undefined, countryID?: number): Array<RankedRow<CandidateRow>> => {
 			const conds = ["name_key = ?", ...filters]
 			const params: Array<string | number> = [nk, ...filterParams]
 
@@ -453,6 +706,12 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 				params.push(regionID)
 			}
 
+			// #1585: the fuzzy tier's country scope — only the corrected-key probes pass this.
+			if (typeof countryID === "number") {
+				conds.push("country_id = ?")
+				params.push(countryID)
+			}
+
 			// Fetch population-ordered (the clustered-key order — a cheap ordered scan), over-fetching to
 			// RERANK_FETCH so the bounded cross-country primary-preference re-rank (below) can promote the
 			// intended primary even when a cluster of more-populous foreign aliases sits ahead of it. `is_primary`
@@ -467,11 +726,11 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			// it to every lookup, including the qualified addresses the D-rule guard exists to protect.
 			const sql =
 				"SELECT spr_id, name, country_id, placetype_id, latitude, longitude, min_lat, min_lon, max_lat, max_lon, neg_rank, is_primary, population" +
-				`${this.#importanceSelect} FROM candidate WHERE ${conds.join(" AND ")} ORDER BY neg_rank ASC LIMIT ?`
+				`${this.#importanceSelect}${this.#roleSelect} FROM candidate WHERE ${conds.join(" AND ")} ORDER BY neg_rank ASC LIMIT ?`
 
-			const fetched = this.#db.prepare(sql).all(...params, Math.max(limit, RERANK_FETCH)) as unknown as CandidateRow[]
+			const fetched = allRows<CandidateRow>(this.#db.prepare(sql), ...params, Math.max(limit, RERANK_FETCH))
 
-			return rankByPrimaryPreference(fetched, limit)
+			return rankByPrimaryPreference(fetched, limit, undefined, this.#idToPlacetype, this.#variantAliasExemption)
 		}
 
 		// The exact → qualifier-strip → typo-fuzzy probe cascade, run at a fixed region scope. Region scoping
@@ -487,7 +746,14 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 				const strippedKey = normalizeLocalityForKey(stripLocalityQualifier(text))
 
 				if (strippedKey && strippedKey !== nameKey) {
-					rows = probe(strippedKey, regionID)
+					// #1626: a stripped probe may answer only through a NON-PRIMARY alias key, which is a
+					// scrape, not a qualifier match — 'Savile Row' stripped to 'row' resolved Rhu, Scotland
+					// (585 km) through the village's historical-name alias. The legitimate qualifier class
+					// matches the place's own primary key ('Lenk im Simmental' → the Lenk row keyed 'lenk',
+					// is_primary=1), so refusing alias-keyed rows keeps every intended case and kills the
+					// scrape. The alias tier remains fully available to EXACT queries — only the stripped
+					// RETRY loses it, because the query's own surface never named the alias.
+					rows = probe(strippedKey, regionID).filter((r) => r.is_primary === 1)
 				}
 			}
 
@@ -507,9 +773,18 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			// DIFFERENT postcode. The 2026-08-05 Code-Point swap exposed the trap at scale: Northern Ireland's
 			// `BT3 9QQ` (absent — no permissive NI source) trigram-matched Sheffield's `S3 9QQ` (Jaccard 0.4
 			// on {39q, 9qq}) and resolved 200+ km wrong with full confidence. An unknown postcode must abstain.
+			// #1585: a locale HINT scopes the typo tier to its country. Only when no hard `country`
+			// filter is active (that is already narrower); a scope naming a country the table doesn't
+			// carry is a SCOPED-EMPTY — the fuzzy tier abstains rather than falling through worldwide.
+			const fuzzyCountryID =
+				!query.country && query.fuzzyCountry ? this.#countryToID.get(query.fuzzyCountry.toUpperCase()) : undefined
+
+			const fuzzyScopedOut = !query.country && !!query.fuzzyCountry && typeof fuzzyCountryID !== "number"
+
 			if (
 				!rows.length &&
 				!wantsPostcode &&
+				!fuzzyScopedOut &&
 				this.#ftsProbe &&
 				this.#nameKeyExistsProbe &&
 				!this.#nameKeyExistsProbe.get(nameKey)
@@ -517,11 +792,11 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 				const match = ftsTrigramQuery(nameKey)
 
 				if (match) {
-					const hits = this.#ftsProbe.all(match, FUZZY_FETCH) as unknown as Array<{ name_key: string }>
+					const hits = allRows<{ name_key: string }>(this.#ftsProbe, match, FUZZY_FETCH)
 
 					const ranked = hits
-						.map((h) => ({ nk: String(h.name_key), s: trigramJaccard(nameKey, String(h.name_key)) }))
-						.filter((h) => h.s >= FUZZY_MIN)
+						.map((h) => ({ nk: String(h.name_key), s: wordFuzzySimilarity(nameKey, String(h.name_key)) }))
+						.filter((h) => h.s >= WORD_FUZZY_MIN)
 						// oxlint-disable-next-line unicorn/no-array-sort -- sorts a freshly-built array; toSorted would double-allocate on a hot path
 						.sort((a, b) => b.s - a.s)
 
@@ -532,7 +807,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 						seen.add(h.nk)
 						// #17: stamp the tier. These rows answer a name the gazetteer does not carry, so they are
 						// fuzzy matches and `exactMatch` below must say so — see `RankedRow.fuzzy`.
-						rows.push(...probe(h.nk, regionID).map((r) => ({ ...r, fuzzy: true })))
+						rows.push(...probe(h.nk, regionID, fuzzyCountryID).map((r) => ({ ...r, fuzzy: true })))
 
 						if (rows.length >= limit) break
 					}
@@ -545,12 +820,17 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		}
 
 		let rows = cascade(regionParentID)
+		// #1731: whether the rows the caller receives came from the UNSCOPED fallback below — the backend's
+		// interior gate the resolver-side trace (#1721) cannot otherwise see. Stamped onto every returned
+		// place, because the re-admission path is exactly where a wrong-instance namesake enters.
+		let regionScopeMiss = false
 
 		// Region-scope fallback: if scoping to the parent region found nothing across the whole cascade, retry
 		// unscoped so a place with no in-region row (missing ancestry, or a country/non-region parent) still
 		// resolves exactly as it does today. Only when a region scope was actually applied.
 		if (!rows.length && regionParentID !== undefined) {
 			rows = cascade(undefined)
+			regionScopeMiss = rows.length > 0
 		}
 
 		// Postcode-containment coherence (#31, Mechanism 2): re-rank the rows by proximity to the postcode's
@@ -591,6 +871,21 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			}
 		}
 
+		// Admin-containment re-rank (#1717 stage 2): LAST, on the final row set — the qualifier is the
+		// address's outermost explicit statement, so its partition outranks the postcode-proximity order
+		// above (contained rows keep that order among themselves). Capability-gated on the sidecar
+		// (`#qualifierProbe`); when the artifact predates it, `regionQualifier` is ignored, no stamp is
+		// written, and the resolver walk reports the lever `unavailable`.
+		if (query.regionQualifier?.trim() && this.#qualifierProbe && this.#wantsLocality(query.placetype)) {
+			rows = this.#applyAdminContainment(rows, query.regionQualifier.trim(), query.country, {
+				nameKey,
+				strippedKey: normalizeLocalityForKey(stripLocalityQualifier(text)),
+				shapeFilters,
+				shapeParams,
+				limit,
+			})
+		}
+
 		const candidates = rows.map((row): PlaceCandidate => {
 			const hasBbox = row.min_lat != null && row.max_lat != null && row.min_lon != null && row.max_lon != null
 
@@ -619,6 +914,13 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 				// EXCEPT a row the typo-corrector produced (`fuzzy`), which by definition answers a name the
 				// gazetteer does not carry (see `RankedRow.fuzzy`).
 				exactMatch: !row.demoted && !row.fuzzy,
+				// #1731: emitted ONLY when a region scope was applied, missed, and the unscoped fallback
+				// produced this row — the re-admission path. Absence means the question never arose.
+				...(regionScopeMiss ? { regionScopeMiss: true } : {}),
+				// #1717 stage 2 — the containment stamp, tri-state: emitted ONLY when the question was
+				// asked (a `regionQualifier` query over a sidecar-bearing artifact); its absence is what
+				// the resolver walk reports as `unavailable` (meaning-of-zero).
+				...(row.containedByQualifier === undefined ? {} : { containedByQualifier: row.containedByQualifier }),
 				// The two-score split's carry (ROAD_TO_V9 §2). `referential` names the prominence this
 				// backend has always ordered by — `neg_rank` IS `-log10(population + 1)`, so the score and
 				// the sort key are two readings of the same number.
@@ -654,59 +956,10 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			}
 		})
 
-		// Proximity re-rank (#938): with bias hints (the demo's map viewport / user location), re-sort the
-		// exact-match candidates by the SAME prominence the FTS server uses (lookup.ts) — population and
-		// nearness in one additive scale — so an in-view namesake wins a tie without a hard filter. Byte-
-		// identical to the plain population order when no bias is passed. `score` here is -neg_rank =
-		// log10(population + 1), so popTerm is the server formula read straight off it. Constants MIRROR
-		// lookup.ts's DEFAULT_WEIGHTS (biasBoost 4, populationBoost 4, populationScaleLog10 6,
-		// proximityScaleKm 100) — the #861 server↔demo parity contract; keep them in lockstep.
+		// Proximity re-rank (#938) — the shared implementation, so the browser byte-range twin runs the same
+		// code rather than the same constants. See proximity-rerank.ts for why that distinction mattered.
 		if (query.bias && query.bias.length) {
-			const BIAS_BOOST = 4
-			const POP_BOOST = 4
-			const POP_SCALE_LOG10 = 6
-			// SHARPER than lookup.ts's 100 km on purpose: this backend's `score` is log-population ALONE
-			// (no bm25 document term), so the population signal is weaker relative to the bias and the
-			// gentle 100 km decay let a 230 km-distant alias-exact township ("Paris Township", OH) edge
-			// out a global city ("Paris", FR) from a nearby view. A ~30 km scale keeps the boost to
-			// candidates the user is actually LOOKING at — an in-view namesake still wins (Dublin, OH from
-			// an Ohio view), a distant one no longer does (Paris stays FR from a Michigan view).
-			const PROX_SCALE_KM = 30
-
-			const combinedProminence = (c: PlaceCandidate): number => {
-				// Population base is the PENALIZED `prominence` (set above = -effectiveNegRank), not raw `score`, so
-				// the cross-country primary preference carries into the bias-weighted order too — a coincidental
-				// foreign alias doesn't ride population back over a primary just because a viewport hint is present.
-				const popBase = c.prominence ?? c.score
-				const popTerm = POP_BOOST * Math.min(1, Math.max(0, popBase) / POP_SCALE_LOG10)
-				let proxTerm = 0
-
-				if (!(c.lat === 0 && c.lon === 0)) {
-					for (const b of query.bias!) {
-						const d = haversineKm(b.lat, b.lon, c.lat, c.lon)
-						const term = (BIAS_BOOST * (b.weight ?? 1)) / (1 + d / PROX_SCALE_KM)
-
-						if (term > proxTerm) {
-							proxTerm = term
-						}
-					}
-				}
-
-				return popTerm + proxTerm
-			}
-
-			// Persist the combined value into `prominence` so the resolver walk's `prominence ?? score` sort (and any
-			// other node consumer) honors the bias order — then sort. Stable within equal prominence (preserves the
-			// population order the B-tree already gave).
-			candidates
-				.map((c, i) => {
-					c.prominence = combinedProminence(c)
-
-					return { c, i, p: c.prominence }
-				})
-				// oxlint-disable-next-line unicorn/no-array-sort -- sorts a freshly-built array; toSorted would double-allocate on a hot path
-				.sort((a, b) => b.p - a.p || a.i - b.i)
-				.forEach((x, j) => (candidates[j] = x.c))
+			applyProximityRerank(candidates, query.bias)
 		}
 
 		return candidates