@mailwoman/resolver-wof-sqlite 9.2.0 → 9.3.0

package/out/candidate-importance.js

@@ -27,7 +27,7 @@
  *   Warwick in America the fame of Warwick, Rhode Island, which is the fan-out defect
  *   `importance-fanout.ts` documents one layer up, re-introduced at the join. So the group is
  *   disambiguated GEOGRAPHICALLY: the nearest centroid wins, and only within
- *   {@link IMPORTANCE_JOIN_GATE_KM}. Two artifacts describing the same settlement put its centroid in
+ *   {@link IMPORTANCE_JOIN_RADIUS_KM}. Two artifacts describing the same settlement put its centroid in
  *   almost the same place; two same-named towns in one country do not.
  *
  *   ## What lands in the column
@@ -40,9 +40,9 @@
  *   A place with no match gets NULL. NULL is UNMEASURED, never zero — the consumer
  *   (`resolver/toponym-prior.ts`) leaves an unmeasured candidate exactly where population put it.
  */
-import { DatabaseSync } from "node:sqlite";
 import { haversineKm } from "@mailwoman/spatial";
-import { normalizeLocalityForKey } from "./street-normalize.js";
+import { DatabaseClient } from "@mailwoman/sqlite/client";
+import { normalizeLocalityForKey } from "#street/normalize";
 /**
  * How far apart two artifacts may put the same place's centroid and still be read as the same place.
  *
@@ -51,18 +51,18 @@ import { normalizeLocalityForKey } from "./street-normalize.js";
  * country, placetype)`). The nearest-centroid distance is **exactly 0.00 km for 577,080 of them (56.6%)** — the two
  * snapshots agree to the bit — and 656,755 (64.4%) are inside 500 m.
  *
- * What sets the gate is where that mode ENDS, and the per-kilometre density says so plainly. It falls from 1,076
- * places/km over 3–5 km to a trough of **441 places/km over 7–10 km**, then climbs back and flattens onto a plateau of
- * 760–780 places/km from 30 km out to 100 km and beyond. That plateau is the background rate of two DIFFERENT towns
- * wearing one name in one country, and it does not decay with distance because there is no reason it should. 10 km is
- * the floor between the two populations. Admitting it scores 679,163 places (66.6% of the matched set); pushing the
- * gate to 25 km buys 8,722 more, and by then better than half of each additional kilometre is the wrong town.
+ * What sets the radius is where that mode ENDS, and the per-kilometre density states. It falls from 1,076 places/km
+ * over 3–5 km to a trough of **441 places/km over 7–10 km**, then climbs back and flattens onto a plateau of 760–780
+ * places/km from 30 km out to 100 km and beyond. That plateau is the background rate of two DIFFERENT towns wearing one
+ * name in one country, and it does not decay with distance because there is no reason it should. 10 km is the floor
+ * between the two populations. Admitting it scores 679,163 places (66.6% of the matched set); pushing the radius to 25
+ * km buys 8,722 more, and by then better than half of each additional kilometre is the wrong town.
  *
  * The four-row bare-GB board is insensitive across this whole range — 5 km and 25 km were both measured and select
- * identical rows — so the value is chosen by what the join MEANS, not by what it scores. The gate is the definition of
- * "this is the same place"; widening it past the floor starts handing one town's fame to another.
+ * identical rows — so the value is chosen by what the join MEANS, not by what it scores. The radius is the definition
+ * of "this is the same place"; widening it past the floor starts handing one town's fame to another.
  */
-export const IMPORTANCE_JOIN_GATE_KM = 10;
+export const IMPORTANCE_JOIN_RADIUS_KM = 10;
 /**
  * `(name_key, country, placetype)` → the scored places under it. The separator is U+0000, which no WOF name carries and
  * no fold can produce, so the three fields can't smear into one another.
@@ -77,24 +77,24 @@ export class ImportanceIndex {
     #groups;
     stats;
     /**
-     * Places {@link find} matched inside the gate.
+     * Places {@link find} matched inside the radius.
      */
     matched = 0;
     /**
-     * Places {@link find} REFUSED — the key matched a scored group, but the nearest member of it was outside the gate, so
-     * it is a different place wearing the same name.
+     * Places {@link find} REFUSED — the key matched a scored group, but the nearest member of it was outside the radius,
+     * so it is a different place wearing the same name.
      *
      * This is the number worth watching across rebuilds. A jump means the score source and the admin source have drifted
-     * apart and the join is being asked to guess; it does not mean the gate is too tight.
+     * apart and the join is being asked to guess; it does not mean the radius is too tight.
      */
-    gated = 0;
+    refused = 0;
     constructor(groups, stats) {
         this.#groups = groups;
         this.stats = stats;
     }
     /**
      * The importance of the scored place nearest `(lat, lon)` sharing `name`'s folded key, `country` and `placetype`, or
-     * null when there is no such place within {@link IMPORTANCE_JOIN_GATE_KM}.
+     * null when there is no such place within {@link IMPORTANCE_JOIN_RADIUS_KM}.
      *
      * Null is UNMEASURED. Never substitute a zero, and never fall back to a population-derived value here — the source
      * column already carries that fallback where it has one, and inventing a second one would make an absence
@@ -116,8 +116,8 @@ export class ImportanceIndex {
                 best = place;
             }
         }
-        if (!best || bestKm > IMPORTANCE_JOIN_GATE_KM) {
-            this.gated++;
+        if (!best || bestKm > IMPORTANCE_JOIN_RADIUS_KM) {
+            this.refused++;
             return null;
         }
         this.matched++;
@@ -137,38 +137,33 @@ export class ImportanceIndex {
  * 25 s.
  */
 export function loadImportanceIndex(databasePath) {
-    const db = new DatabaseSync(databasePath, { readOnly: true });
-    try {
-        const groups = new Map();
-        let places = 0;
-        let unkeyable = 0;
-        for (const row of db
-            .prepare(`SELECT s.name AS name, s.country AS country, s.placetype AS placetype,
-					s.latitude AS latitude, s.longitude AS longitude, i.importance AS importance
-				 FROM place_importance i JOIN spr s ON s.id = i.id
-				 WHERE s.is_current != 0 AND s.is_deprecated = 0`)
-            .iterate()) {
-            const importance = Number(row.importance);
-            if (!Number.isFinite(importance))
-                continue;
-            const nameKey = normalizeLocalityForKey(String(row.name ?? ""));
-            if (!nameKey) {
-                unkeyable++;
-                continue;
-            }
-            const key = groupKey(nameKey, row.country, row.placetype);
-            let group = groups.get(key);
-            if (!group) {
-                group = [];
-                groups.set(key, group);
-            }
-            group.push({ lat: Number(row.latitude), lon: Number(row.longitude), importance });
-            places++;
+    using db = new DatabaseClient(databasePath, { readOnly: true });
+    const groups = new Map();
+    let places = 0;
+    let unkeyable = 0;
+    for (const row of db
+        .prepare(`SELECT s.name AS name, s.country AS country, s.placetype AS placetype,
+				s.latitude AS latitude, s.longitude AS longitude, i.importance AS importance
+			 FROM place_importance i JOIN spr s ON s.id = i.id
+			 WHERE s.is_current != 0 AND s.is_deprecated = 0`)
+        .iterate()) {
+        const importance = Number(row.importance);
+        if (!Number.isFinite(importance))
+            continue;
+        const nameKey = normalizeLocalityForKey(String(row.name ?? ""));
+        if (!nameKey) {
+            unkeyable++;
+            continue;
         }
-        return new ImportanceIndex(groups, { places, keys: groups.size, unkeyable });
-    }
-    finally {
-        db.close();
+        const key = groupKey(nameKey, row.country, row.placetype);
+        let group = groups.get(key);
+        if (!group) {
+            group = [];
+            groups.set(key, group);
+        }
+        group.push({ lat: Number(row.latitude), lon: Number(row.longitude), importance });
+        places++;
     }
+    return new ImportanceIndex(groups, { places, keys: groups.size, unkeyable });
 }
 //# sourceMappingURL=candidate-importance.js.map

package/out/candidate-importance.js.map

@@ -1 +1 @@
-{"version":3,"file":"candidate-importance.js","sourceRoot":"","sources":["../candidate-importance.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"candidate-importance.js","sourceRoot":"","sources":["../lib/candidate-importance.ts"],"names":[],"mappings":"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"}

package/out/candidate-lookup.d.ts

@@ -22,20 +22,22 @@
  *   stored bbox and the locality query is point-in-bbox-filtered on the candidate centroid (the
  *   `bbox` field on {@link FindPlaceQuery}).
  */
-import { DatabaseSync } from "node:sqlite";
 import { type Ancestor, type GazetteerArtifactCoverage } from "@mailwoman/resolver";
-import type { FindPlaceQuery, PlaceCandidate, PlaceLookup } from "./types.ts";
-export { rankByPrimaryPreference } from "./primary-preference.ts";
-export type { RankedRow } from "./primary-preference.ts";
+import { DatabaseClient } from "@mailwoman/sqlite/client";
+import type { PathBuilderLike } from "path-ts";
+import type { CandidateDatabase } from "#candidate-schema";
+import type { FindPlaceQuery, PlaceCandidate, PlaceLookup } from "#types";
+export { rankByPrimaryPreference } from "#primary-preference";
+export type { RankedRow } from "#primary-preference";
 export interface WOFCandidateTableLookupOpts {
     /**
      * Path to a `candidate.db` built by `build-candidate.ts`. Opened read-only.
      */
-    databasePath?: string;
+    databasePath?: PathBuilderLike;
     /**
      * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
      */
-    database?: DatabaseSync;
+    database?: DatabaseClient<CandidateDatabase>;
     /**
      * #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
@@ -47,12 +49,12 @@ export interface WOFCandidateTableLookupOpts {
  * Node {@link PlaceLookup} over `candidate.db`. Drop-in for {@link WOFSQLitePlaceLookup} in `createWOFResolver(backend)`
  * — same `findPlace` contract, population-first ranking.
  */
-export declare class WOFCandidateTableLookup implements PlaceLookup {
+export declare class WOFCandidateTableLookup implements PlaceLookup, Disposable {
     #private;
     /**
      * Facts this candidate DB declares about itself — the coverage manifest (`country_coverage` + `country_bbox`) the
      * gazetteer build emits, read once at open. `undefined` when the artifact predates the manifest, so every consumer
-     * (the hard-country coverage gate, guard-B plausibility) falls back to its code constants byte-identically.
+     * (the hard-country coverage check, guard-B plausibility) falls back to its code constants byte-identically.
      */
     readonly artifactCoverage: GazetteerArtifactCoverage | undefined;
     /**
@@ -69,6 +71,6 @@ export declare class WOFCandidateTableLookup implements PlaceLookup {
     readonly ancestors: ((id: number | string) => Ancestor[]) | undefined;
     constructor(opts: WOFCandidateTableLookupOpts);
     findPlace(query: FindPlaceQuery): Promise<PlaceCandidate[]>;
-    close(): void;
+    [Symbol.dispose](): void;
 }
 //# sourceMappingURL=candidate-lookup.d.ts.map

package/out/candidate-lookup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"candidate-lookup.d.ts","sourceRoot":"","sources":["../candidate-lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAG1C,OAAO,EAGN,KAAK,QAAQ,EACb,KAAK,yBAAyB,EAC9B,MAAM,qBAAqB,CAAA;AAoB5B,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAgB,MAAM,YAAY,CAAA;AAE3F,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAA;AACjE,YAAY,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAExD,MAAM,WAAW,2BAA2B;IAC3C;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;OAEG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAC/B;AAiFD;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,WAAW;;IAyB1D;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,yBAAyB,GAAG,SAAS,CAAA;IAsChE;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,KAAK,QAAQ,EAAE,CAAC,GAAG,SAAS,CAAA;gBAEzD,IAAI,EAAE,2BAA2B;IAwVvC,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAgYjE,KAAK,IAAI,IAAI;CAKb"}
+{"version":3,"file":"candidate-lookup.d.ts","sourceRoot":"","sources":["../lib/candidate-lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAGN,KAAK,QAAQ,EACb,KAAK,yBAAyB,EAC9B,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAU9C,OAAO,KAAK,EAAE,iBAAiB,EAAwD,MAAM,mBAAmB,CAAA;AAShH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAgB,MAAM,QAAQ,CAAA;AAEvF,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAA;AAC7D,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAEpD,MAAM,WAAW,2BAA2B;IAC3C;;OAEG;IACH,YAAY,CAAC,EAAE,eAAe,CAAA;IAC9B;;OAEG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAA;IAC5C;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAC/B;AAiFD;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,WAAW,EAAE,UAAU;;IA6BtE;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,yBAAyB,GAAG,SAAS,CAAA;IAsChE;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,KAAK,QAAQ,EAAE,CAAC,GAAG,SAAS,CAAA;gBAEzD,IAAI,EAAE,2BAA2B;IAsVvC,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAmYjE,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGxB"}

package/out/candidate-lookup.js

@@ -22,21 +22,21 @@
  *   stored bbox and the locality query is point-in-bbox-filtered on the candidate centroid (the
  *   `bbox` field on {@link FindPlaceQuery}).
  */
-import { DatabaseSync } from "node:sqlite";
 import { jaroWinkler, levenshteinSimilarity } from "@mailwoman/match/comparators";
 import { expandPlacetypeFilter, partitionByContainment, } from "@mailwoman/resolver";
 import { haversineKm } from "@mailwoman/spatial";
-import { CANDIDATE_ANCESTOR_TABLE, CANDIDATE_INTERVAL_TABLE, intervalContains, } from "./candidate-ancestors-schema.js";
-import { CANDIDATE_FTS_TABLE } from "./candidate-fts.js";
-import { readGazetteerCoverageManifest } from "./coverage-manifest-schema.js";
-import { referentialFromPopulation } from "./place-importance-schema.js";
-import { POSTAL_CITY_CANDIDATE_TABLE } from "./postal-city-candidate-schema.js";
-import { rankByPrimaryPreference, RERANK_FETCH } from "./primary-preference.js";
-import { applyProximityRerank } from "./proximity-rerank.js";
-import { REGION_CLASS_PLACETYPES, regionQualifierProbeKeys } from "./region-keys.js";
-import { allRows, hasColumn, hasTable } from "./sqlite-utils.js";
-import { normalizeLocalityForKey, stripLocalityQualifier } from "./street-normalize.js";
-export { rankByPrimaryPreference } from "./primary-preference.js";
+import { DatabaseClient } from "@mailwoman/sqlite/client";
+import { CANDIDATE_ANCESTOR_TABLE, CANDIDATE_INTERVAL_TABLE, intervalContains, } from "#candidate-ancestors-schema";
+import { CANDIDATE_FTS_TABLE } from "#candidate-fts";
+import { readGazetteerCoverageManifest } from "#coverage-manifest-schema";
+import { referentialFromPopulation } from "#place-importance-schema";
+import { POSTAL_CITY_CANDIDATE_TABLE } from "#postal/city-candidate-schema";
+import { rankByPrimaryPreference, 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 { normalizeLocalityForKey, stripLocalityQualifier } from "#street/normalize";
+export { rankByPrimaryPreference } from "#primary-preference";
 /**
  * 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
@@ -60,12 +60,12 @@ function wordFuzzySimilarity(a, b) {
     return Math.max(jaroWinkler(a, b), levenshteinSimilarity(a, b));
 }
 /**
- * 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.
+ * Postcode-containment re-rank check radius (km) — the SAME value the resolver's country pass measures at
+ * (`POSTCODE_COUNTRY_COHERENCE_THRESHOLD_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.
  */
-const POSTCODE_CONTAINMENT_GATE_KM = 25;
+const POSTCODE_CONTAINMENT_THRESHOLD_KM = 25;
 /**
  * Unpadded character-trigrams of `s`, OR'd into an FTS5 trigram MATCH query (each quoted so FTS treats it as a literal
  * term). Returns "" when `s` is shorter than a trigram or yields no clean grams — the caller then skips the fuzzy
@@ -87,7 +87,11 @@ function ftsTrigramQuery(s) {
  */
 export class WOFCandidateTableLookup {
     #db;
-    #ownsDB;
+    /**
+     * Resources this instance opened. A connection handed in by a caller is NOT in here, so disposal cannot reach it —
+     * ownership is membership rather than a flag a later branch has to check.
+     */
+    #resources = new DisposableStack();
     #countryToID = new Map();
     #idToCountry = new Map();
     #placetypeToID = new Map();
@@ -103,22 +107,22 @@ export class WOFCandidateTableLookup {
      */
     #ftsProbe;
     /**
-     * Prepared UNFILTERED existence probe (`name_key` present anywhere, ignoring country/placetype/bbox). Gates the fuzzy
-     * fallback: fuzzy is a TYPO corrector, so it engages only when the name doesn't exist in the gazetteer at all. A name
-     * that DOES exist but missed under the active filter is a filter miss (e.g. a placer misroute "Vienna, Austria"→IT),
-     * not a spelling miss — fuzzing it would scrape an unrelated same-country place and defeat the cascade's
-     * country-agnostic retry. Prepared only alongside `#ftsProbe`.
+     * Prepared UNFILTERED existence probe (`name_key` present anywhere, ignoring country/placetype/bbox). Checks the
+     * fuzzy fallback: fuzzy is a TYPO corrector, so it engages only when the name doesn't exist in the gazetteer at all.
+     * A name that DOES exist but missed under the active filter is a filter miss (e.g. a placer misroute "Vienna,
+     * Austria"→IT), not a spelling miss — fuzzing it would scrape an unrelated same-country place and defeat the
+     * cascade's country-agnostic retry. Prepared only alongside `#ftsProbe`.
      */
     #nameKeyExistsProbe;
     /**
      * Facts this candidate DB declares about itself — the coverage manifest (`country_coverage` + `country_bbox`) the
      * gazetteer build emits, read once at open. `undefined` when the artifact predates the manifest, so every consumer
-     * (the hard-country coverage gate, guard-B plausibility) falls back to its code constants byte-identically.
+     * (the hard-country coverage check, guard-B plausibility) falls back to its code constants byte-identically.
      */
     artifactCoverage;
     /**
      * `", importance"` when this artifact carries the #28 fame column, `""` when it does not — spliced into the probe's
-     * SELECT list. Existence-gated exactly like `#ftsProbe` and `#postalCityProbe` above, and for the same reason: a
+     * SELECT list. Existence-restricted exactly like `#ftsProbe` and `#postalCityProbe` above, and for the same reason: a
      * candidate.db built before the column is a valid artifact, and naming a column it lacks would turn a stale gazetteer
      * into `no such column` on the first keystroke rather than into "no fame signal", which is what it is.
      */
@@ -141,9 +145,9 @@ export class WOFCandidateTableLookup {
     #ancestorsCache = new Map();
     /**
      * 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,
+     * is what makes the admin-containment re-rank (#1717 stage 2) capability-restricted: without it,
      * `FindPlaceQuery.regionQualifier` is ignored, no candidate carries a `containedByQualifier` stamp, and the resolver
-     * walk reports the lever `unavailable` instead of silently dead.
+     * walk reports the change `unavailable` instead of silently dead.
      */
     #intervalProbe;
     #intervalCache = new Map();
@@ -168,11 +172,9 @@ export class WOFCandidateTableLookup {
     constructor(opts) {
         if (opts.database) {
             this.#db = opts.database;
-            this.#ownsDB = false;
         }
         else if (opts.databasePath) {
-            this.#db = new DatabaseSync(opts.databasePath, { readOnly: true });
-            this.#ownsDB = true;
+            this.#db = this.#resources.use(new DatabaseClient(opts.databasePath, { readOnly: true }));
         }
         else {
             throw new Error("WOFCandidateTableLookup needs `databasePath` or `database`");
@@ -204,7 +206,7 @@ export class WOFCandidateTableLookup {
         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
+        // Ancestors sidecar (#1717): existence-restricted like the probes above, and the CAPABILITY checks 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)) {
@@ -212,7 +214,7 @@ export class WOFCandidateTableLookup {
                 " 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
+        // Admin-containment re-rank (#1717 stage 2): conditioned 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)) {
@@ -224,7 +226,7 @@ export class WOFCandidateTableLookup {
                 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
+        // Coverage manifest (survey candidate #2): the artifact's own coverage facts, existence-restricted like
         // the probes above — a candidate.db built before the manifest reads `undefined` and consumers keep
         // their code-constant fallbacks byte-identically.
         this.artifactCoverage = readGazetteerCoverageManifest(this.#db);
@@ -289,7 +291,7 @@ export class WOFCandidateTableLookup {
      * 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.
+     * ≤{@link MAX_ANCESTOR_DEPTH} rows) is the complete record that determines the result.
      */
     #containedByQualifier(sprID, qualifierIDs, qualifierLabels) {
         if (qualifierIDs.has(sprID))
@@ -353,7 +355,7 @@ export class WOFCandidateTableLookup {
         // 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
+        // widening is injection-only and triple-conditioned: 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
@@ -439,7 +441,7 @@ export class WOFCandidateTableLookup {
             return [];
         // #741: postcode-keyed postal-city alias. An exact `(name_key, postcode)` hit resolves a
         // user-typed POSTAL city ("Antioch", 37013) to the geographic locality the postcode sits in
-        // ("Nashville"), bypassing the population/region ranking that can't see the postcode. Gated on
+        // ("Nashville"), bypassing the population/region ranking that can't see the postcode. Conditioned on
         // the side-index being present, a postcode in the query, and a locality-tier request — so the
         // common (no-postcode / non-locality) path is untouched. A hit short-circuits: the postcode is
         // an exact, high-confidence disambiguator, so we return the single geographic locality.
@@ -465,7 +467,7 @@ export class WOFCandidateTableLookup {
         // 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.
+        // candidate is the change's whole point and the one filter injection may cross.
         const filters = [];
         const filterParams = [];
         const shapeFilters = [];
@@ -495,7 +497,7 @@ export class WOFCandidateTableLookup {
             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
+        // is a token taken 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').
@@ -577,7 +579,7 @@ export class WOFCandidateTableLookup {
             // the same on either backend. The country/placetype/bbox/region filters still apply via `probe`.
             // Skipped when the index is absent (byte-stable for an older candidate.db).
             //
-            // Gate: only when the name doesn't exist in the gazetteer AT ALL (unfiltered). A name that exists
+            // Condition: only when the name doesn't exist in the gazetteer AT ALL (unfiltered). A name that exists
             // but missed under the active country/placetype/bbox filter is a FILTER miss, not a spelling miss
             // — fuzzing it scrapes an unrelated same-filter place ("Vienna, Austria" misrouted to IT would
             // pull a tiny Italian name_key near Siena) and masks the cascade's country-agnostic retry that
@@ -624,7 +626,7 @@ export class WOFCandidateTableLookup {
         };
         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
+        // interior check 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
@@ -639,8 +641,8 @@ export class WOFCandidateTableLookup {
         // holds 75001, not the one that holds a 75001-free namesake). The resolver sends this flag on locality
         // lookups when `ResolveOpts.postcodeContainmentCoherence` is on. Strictly beneath the #741 postal-city
         // short-circuit above — an exact (name, postcode) hit IS the answer and outranks any re-rank — and after
-        // the region-scope fallback, so it sees the final row set. Rows within the gate sort by distance first;
-        // the out-gate tail keeps its original population-first order. No in-gate row, or no postcode row in
+        // the region-scope fallback, so it sees the final row set. Rows within the radius sort by distance first;
+        // the out-of-radius tail keeps its original population-first order. No in-radius row, or no postcode row in
         // the candidate table → unchanged (byte-identical to the flag-off path).
         if (query.postcode &&
             query.postcodeContainmentCoherence === true &&
@@ -648,29 +650,29 @@ export class WOFCandidateTableLookup {
             rows.length > 1) {
             const anchor = this.#postcodeAnchor(query.postcode, query.country);
             if (anchor) {
-                const inGate = [];
-                const outGate = [];
+                const insideThreshold = [];
+                const outsideThreshold = [];
                 for (const row of rows) {
                     const distanceKm = haversineKm(anchor.lat, anchor.lon, Number(row.latitude), Number(row.longitude));
-                    if (distanceKm <= POSTCODE_CONTAINMENT_GATE_KM) {
-                        inGate.push({ row, distanceKm });
+                    if (distanceKm <= POSTCODE_CONTAINMENT_THRESHOLD_KM) {
+                        insideThreshold.push({ row, distanceKm });
                     }
                     else {
-                        outGate.push(row);
+                        outsideThreshold.push(row);
                     }
                 }
-                if (inGate.length) {
+                if (insideThreshold.length) {
                     // oxlint-disable-next-line unicorn/no-array-sort -- sorts a freshly-built array; toSorted would double-allocate on a hot path
-                    inGate.sort((a, b) => a.distanceKm - b.distanceKm);
-                    rows = [...inGate.map(({ row }) => row), ...outGate];
+                    insideThreshold.sort((a, b) => a.distanceKm - b.distanceKm);
+                    rows = [...insideThreshold.map(({ row }) => row), ...outsideThreshold];
                 }
             }
         }
         // 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
+        // above (contained rows keep that order among themselves). Capability-conditioned on the sidecar
         // (`#qualifierProbe`); when the artifact predates it, `regionQualifier` is ignored, no stamp is
-        // written, and the resolver walk reports the lever `unavailable`.
+        // written, and the resolver walk reports the change `unavailable`.
         if (query.regionQualifier?.trim() && this.#qualifierProbe && this.#wantsLocality(query.placetype)) {
             rows = this.#applyAdminContainment(rows, query.regionQualifier.trim(), query.country, {
                 nameKey,
@@ -686,13 +688,13 @@ export class WOFCandidateTableLookup {
                 id: Number(row.spr_id),
                 name: String(row.name ?? ""),
                 placetype: (this.#idToPlacetype.get(Number(row.placetype_id)) ?? ""),
-                // Surfaced so the cascade can country-gate a postcode by the resolved locality (an ambiguous
+                // Surfaced so the cascade can country-restrict a postcode by the resolved locality (an ambiguous
                 // international postcode like 10115 = Berlin DE AND New York US must not out-resolve the city).
                 country: this.#idToCountry.get(Number(row.country_id)) ?? "",
                 lat: Number(row.latitude),
                 lon: Number(row.longitude),
                 // `score` stays the RAW population rank (`-neg_rank`) — it feeds the resolver walk's absolute
-                // `minWinningScore` gate (`resolve.ts`), which must see real prominence, never a penalized value.
+                // `minWinningScore` floor (`resolve.ts`), which must see real prominence, never a penalized value.
                 score: -Number(row.neg_rank),
                 // `prominence` carries the bounded cross-country primary preference (the effective, penalty-adjusted
                 // rank). The walk ORDERS candidates by `prominence ?? score` (`resolve.ts`), so this is what makes the
@@ -714,6 +716,9 @@ export class WOFCandidateTableLookup {
                 // 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 }),
+                // #1893 — the exemption's firing mark, carried only when the ranker actually spared this row
+                // the cross-country penalty (see RankedRow.variantExempted).
+                ...(row.variantExempted ? { variantAliasExempted: true } : {}),
                 // 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.
@@ -755,10 +760,8 @@ export class WOFCandidateTableLookup {
         }
         return candidates;
     }
-    close() {
-        if (this.#ownsDB) {
-            this.#db.close();
-        }
+    [Symbol.dispose]() {
+        this.#resources[Symbol.dispose]();
     }
 }
 //# sourceMappingURL=candidate-lookup.js.map