@mailwoman/resolver-wof-sqlite 9.1.0 → 9.3.0

package/out/address/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+export * from "#address/point";
+export * from "#address/point-interpolation";
+export * from "#address/point-schema";
+//# sourceMappingURL=index.d.ts.map

package/out/address/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/address/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,8BAA8B,CAAA;AAC5C,cAAc,uBAAuB,CAAA"}

package/out/address/index.js

@@ -0,0 +1,9 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+export * from "#address/point";
+export * from "#address/point-interpolation";
+export * from "#address/point-schema";
+//# sourceMappingURL=index.js.map

package/out/address/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../lib/address/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,8BAA8B,CAAA;AAC5C,cAAc,uBAAuB,CAAA"}

package/out/{address-point-interpolation.d.ts → address/point-interpolation.d.ts}

@@ -6,13 +6,13 @@
  *   Address-point interpolation — "Method 2" of the resolution ladder (#483, Phase 1 of
  *   `docs/articles/plan/2026-06-11-resolution-ladder.md`): when the exact address-point tier (#476)
  *   misses a house number, bracket the number with REAL neighbor points on the same street from the
- *   same #476 shard and interpolate linearly in house-number space between them. Real occupancy
- *   replaces TIGER's uniform-spacing assumption — the dominant error term of the TIGER pilot's gate
+ *   same #476 extract and interpolate linearly in house-number space between them. Real occupancy
+ *   replaces TIGER's uniform-spacing assumption — the dominant error term of the TIGER pilot's check
  *   miss; TIGER range interpolation (`StreetInterpolator`) demotes to the fallback for streets too
  *   sparse to bracket.
  *
  *   Matching key is `street_key` — THE shared normalizer plus the route fold
- *   (`canonicalizeRouteKey`), identical at build time (`scripts/build-address-point-shard.ts`) and
+ *   (`canonicalizeRouteKey`), identical at build time (`scripts/build-address-point-extract.ts`) and
  *   query time, by construction. Scope is postcode-first like the segment tier; a query without a
  *   postcode goes straight to the fallback (which carries its own statewide-ambiguity abstention).
  *
@@ -20,7 +20,7 @@
  *
  *   - Neighbor candidates NEVER include the queried number itself (any unit/duplicate row of it) — in
  *       production the exact tier would already have answered an on-file number, and in the eval
- *       this is what makes grading against the same shard non-circular by construction.
+ *       this is what makes grading against the same extract non-circular by construction.
  *   - Both-sided bracket (`bracket: "both"`): linear interpolation between the nearest known number
  *       below and above; `uncertaintyM` = half the distance between them.
  *   - Single-sided (`bracket: "single"`): linear extrapolation along the two nearest known numbers on
@@ -32,17 +32,18 @@
  *
  *   Standalone like the segment tier — core wiring rides the Phase 2 ordered `spatialTiers` list.
  */
-import { DatabaseSync } from "node:sqlite";
 import type { InterpolationLookup } from "@mailwoman/resolver";
-import type { InterpolatedHit, InterpolationQuery, StreetInterpolator } from "./interpolation.ts";
-export declare class AddressPointInterpolator implements InterpolationLookup {
+import { DatabaseClient } from "@mailwoman/sqlite/client";
+import type { AddressPointDatabase } from "#address/point-schema";
+import type { InterpolatedHit, InterpolationQuery, StreetInterpolator } from "#interpolation";
+export declare class AddressPointInterpolator<DB extends AddressPointDatabase = AddressPointDatabase> implements InterpolationLookup {
     #private;
     constructor(opts: {
         dbPath?: string;
-        database?: DatabaseSync;
+        database?: DatabaseClient<DB>;
         fallback?: StreetInterpolator;
     });
     find(query: InterpolationQuery): InterpolatedHit | null;
-    close(): void;
+    [Symbol.dispose](): void;
 }
-//# sourceMappingURL=address-point-interpolation.d.ts.map
+//# sourceMappingURL=point-interpolation.d.ts.map

package/out/address/point-interpolation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"point-interpolation.d.ts","sourceRoot":"","sources":["../../lib/address/point-interpolation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAE9D,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAEzD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AA6B7F,qBAAa,wBAAwB,CACpC,EAAE,SAAS,oBAAoB,GAAG,oBAAoB,CACrD,YAAW,mBAAmB;;gBAUnB,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,cAAc,CAAC,EAAE,CAAC,CAAC;QAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAA;KAAE;IA2BnG,IAAI,CAAC,KAAK,EAAE,kBAAkB,GAAG,eAAe,GAAG,IAAI;IAyBvD,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGxB"}

package/out/{address-point-interpolation.js → address/point-interpolation.js}

@@ -6,13 +6,13 @@
  *   Address-point interpolation — "Method 2" of the resolution ladder (#483, Phase 1 of
  *   `docs/articles/plan/2026-06-11-resolution-ladder.md`): when the exact address-point tier (#476)
  *   misses a house number, bracket the number with REAL neighbor points on the same street from the
- *   same #476 shard and interpolate linearly in house-number space between them. Real occupancy
- *   replaces TIGER's uniform-spacing assumption — the dominant error term of the TIGER pilot's gate
+ *   same #476 extract and interpolate linearly in house-number space between them. Real occupancy
+ *   replaces TIGER's uniform-spacing assumption — the dominant error term of the TIGER pilot's check
  *   miss; TIGER range interpolation (`StreetInterpolator`) demotes to the fallback for streets too
  *   sparse to bracket.
  *
  *   Matching key is `street_key` — THE shared normalizer plus the route fold
- *   (`canonicalizeRouteKey`), identical at build time (`scripts/build-address-point-shard.ts`) and
+ *   (`canonicalizeRouteKey`), identical at build time (`scripts/build-address-point-extract.ts`) and
  *   query time, by construction. Scope is postcode-first like the segment tier; a query without a
  *   postcode goes straight to the fallback (which carries its own statewide-ambiguity abstention).
  *
@@ -20,7 +20,7 @@
  *
  *   - Neighbor candidates NEVER include the queried number itself (any unit/duplicate row of it) — in
  *       production the exact tier would already have answered an on-file number, and in the eval
- *       this is what makes grading against the same shard non-circular by construction.
+ *       this is what makes grading against the same extract non-circular by construction.
  *   - Both-sided bracket (`bracket: "both"`): linear interpolation between the nearest known number
  *       below and above; `uncertaintyM` = half the distance between them.
  *   - Single-sided (`bracket: "single"`): linear extrapolation along the two nearest known numbers on
@@ -32,10 +32,10 @@
  *
  *   Standalone like the segment tier — core wiring rides the Phase 2 ordered `spatialTiers` list.
  */
-import { DatabaseSync } from "node:sqlite";
-import { haversineKm } from "./geo.js";
-import { hasTable } from "./sqlite-utils.js";
-import { canonicalizeRouteKey, normalizeStreetForKey } from "./street-normalize.js";
+import { haversineKm } from "@mailwoman/spatial";
+import { DatabaseClient } from "@mailwoman/sqlite/client";
+import { hasTable, prepareAll } from "#sqlite-utils";
+import { canonicalizeRouteKey, streetKeyVariants } from "#street/normalize";
 /**
  * Extrapolation cap for a single-sided bracket: at most one pair-span beyond the nearest known point (`t = 2`). Past
  * it, the two-point line carries no evidence about the query number.
@@ -43,28 +43,30 @@ import { canonicalizeRouteKey, normalizeStreetForKey } from "./street-normalize.
 const MAX_EXTRAPOLATION_T = 2;
 export class AddressPointInterpolator {
     #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();
     #fallback;
     #byPostcode;
     constructor(opts) {
         if (opts.database) {
             this.#db = opts.database;
-            this.#ownsDB = false;
         }
         else if (opts.dbPath) {
-            this.#db = new DatabaseSync(opts.dbPath, { readOnly: true });
-            this.#ownsDB = true;
+            this.#db = this.#resources.use(new DatabaseClient(opts.dbPath, { readOnly: true }));
         }
         else {
             throw new Error("AddressPointInterpolator: one of dbPath or database is required");
         }
         this.#fallback = opts.fallback;
-        // Degrade gracefully on an empty/tableless shard (#568): with no `address_point` table this tier
+        // Degrade gracefully on an empty/tableless extract (#568): with no `address_point` table this tier
         // is skipped, deferring to the segment fallback rather than crashing at construction.
         if (hasTable(this.#db, "address_point")) {
             // Strictly-numeric neighbor numbers on the route-folded street key within the ZIP. The
             // queried number itself is excluded HERE (see module doc: non-circular by construction).
-            this.#byPostcode = this.#db.prepare(`SELECT CAST(number AS INTEGER) AS n, lat, lon, source, release
+            this.#byPostcode = prepareAll(this.#db, `SELECT CAST(number AS INTEGER) AS n, lat, lon, source, release
 				 FROM address_point
 				 WHERE postcode = ? AND street_key = ?
 					AND number GLOB '[0-9]*' AND number NOT GLOB '*[^0-9]*'
@@ -72,22 +74,26 @@ export class AddressPointInterpolator {
         }
     }
     find(query) {
-        const streetKey = canonicalizeRouteKey(normalizeStreetForKey(query.street));
         const numberRaw = query.number.trim();
-        if (!streetKey || !/^\d+$/.test(numberRaw))
+        if (!/^\d+$/.test(numberRaw))
             return null;
         const n = Number(numberRaw);
-        // No own table (empty shard) or no postcode → defer to the segment fallback rather than query.
+        // No own table (empty extract) or no postcode → defer to the segment fallback rather than query.
         if (!this.#byPostcode || !query.postcode)
             return this.#fallback?.find(query) ?? null;
-        const rows = this.#byPostcode.all(query.postcode.trim(), streetKey, n);
+        // Key-variant ladder (see `streetKeyVariants`) — same probe order as the exact-point reader.
+        let rows = [];
+        for (const variant of streetKeyVariants(query.street)) {
+            const streetKey = canonicalizeRouteKey(variant);
+            rows = this.#byPostcode(query.postcode.trim(), streetKey, n);
+            if (rows.length)
+                break;
+        }
         const hit = rows.length >= 2 ? interpolateFromNeighbors(rows, n) : null;
         return hit ?? this.#fallback?.find(query) ?? null;
     }
-    close() {
-        if (this.#ownsDB) {
-            this.#db.close();
-        }
+    [Symbol.dispose]() {
+        this.#resources[Symbol.dispose]();
     }
 }
 /**
@@ -167,4 +173,4 @@ function interpolateFromNeighbors(rows, n) {
         release: near.release,
     };
 }
-//# sourceMappingURL=address-point-interpolation.js.map
+//# sourceMappingURL=point-interpolation.js.map

package/out/address/point-interpolation.js.map

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

package/out/{address-point-schema.d.ts → address/point-schema.d.ts}

@@ -3,8 +3,8 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Typed schema for the SITUS / rooftop ADDRESS-POINT shards (`address-points-<cc>-<slug>.db`, built
- *   by `scripts/build-address-point-shard.ts` — the #476/#567 national rooftop tier behind the
+ *   Typed schema for the SITUS / rooftop ADDRESS-POINT extracts (`address-points-<cc>-<slug>.db`, built
+ *   by `scripts/build-address-point-extract.ts` — the #476/#567 national rooftop tier behind the
  *   demo's "type any US address, get the building"). Single source of truth for the columns shared
  *   by the BUILDER and the READER ({@link AddressPointSqliteLookup}), so a column rename in one is a
  *   compile error in the other.
@@ -16,6 +16,7 @@
  *   schema guards the contract; positional inserts keep the speed.)
  */
 import type { Kysely } from "kysely";
+import type { NameKey, RouteKey, StreetKey } from "#street/normalize";
 /**
  * One rooftop address point. `(street_norm, number)` within a `postcode` (preferred) or `locality_norm` scope is the
  * lookup; `street_key` is the #483 route-fold key for interpolation. Coordinates are non-null (the builder drops
@@ -25,11 +26,12 @@ export interface AddressPointTable {
     /**
      * Shared {@link normalizeStreetForKey} of the street — the build/query-consistent probe key.
      */
-    street_norm: string;
+    street_norm: StreetKey;
     /**
-     * `canonicalizeRouteKey(street_norm)` — the route-fold key (#483 Method 2).
+     * `canonicalizeRouteKey(street_norm)` — the route-fold key (#483 Method 2). Its own brand, so it cannot be
+     * interchanged with the plain `street_norm` above.
      */
-    street_key: string;
+    street_key: RouteKey;
     /**
      * House number, normalized lower-case (kept TEXT — "123-A", "12 1/2" must survive).
      */
@@ -39,7 +41,7 @@ export interface AddressPointTable {
     /**
      * Shared {@link normalizeLocalityForKey} of the locality — the fallback scope.
      */
-    locality_norm: string | null;
+    locality_norm: NameKey | null;
     /**
      * The street as it appeared in the source (kept for display / debugging).
      */
@@ -54,6 +56,16 @@ export interface AddressPointTable {
      * The pinned data release the point was ingested from.
      */
     release: string;
+    /**
+     * The source register's stable administrative key for the point's commune or municipality — BAN's `code_insee`. A
+     * display name (`locality_norm`) is not a key; the coverage basis is computed per THIS.
+     */
+    admin_code: string | null;
+    /**
+     * The register's own certification flag for the point (BAN `certification_commune`: 1 certified by the commune, 0
+     * not), or null for a source that states none. A basis is never inferred from a share of these.
+     */
+    certified: number | null;
 }
 /**
  * The address-point database schema for `new DatabaseClient<AddressPointDatabase>(...)`.
@@ -61,17 +73,25 @@ export interface AddressPointTable {
 export interface AddressPointDatabase {
     address_point: AddressPointTable;
 }
+/**
+ * The slice of a Kysely handle the `address_point` DDL touches — the parameter type its builders take.
+ *
+ * Kysely is invariant in its schema parameter (the incompatibility is in `transaction()`), so a extract that EXTENDS
+ * `AddressPointTable` — OSM adds `h3_cell` — cannot pass its own handle to a `Kysely<AddressPointDatabase>` parameter.
+ * Naming only `schema` lets it, and the DDL below needs nothing else.
+ */
+export type AddressPointSchemaHandle = Pick<Kysely<AddressPointDatabase>, "schema">;
 /**
  * The `address_point` columns in INSERT order. The builder's positional prepared statement derives its placeholder list
  * from this, so the positional order can't drift from the DDL / the reader.
  */
-export declare const ADDRESS_POINT_COLUMNS: readonly ["street_norm", "street_key", "number", "unit", "postcode", "locality_norm", "street_raw", "lat", "lon", "source", "release"];
+export declare const ADDRESS_POINT_COLUMNS: readonly ["street_norm", "street_key", "number", "unit", "postcode", "locality_norm", "street_raw", "lat", "lon", "source", "release", "admin_code", "certified"];
 /**
  * Create the `address_point` table — called before the streaming bulk load.
  */
-export declare function createAddressPointTable(db: Kysely<AddressPointDatabase>): Promise<void>;
+export declare function createAddressPointTable(db: AddressPointSchemaHandle): Promise<void>;
 /**
  * Create the three probe indexes the reader relies on (postcode-scope, locality-scope, route-key).
  */
-export declare function createAddressPointIndexes(db: Kysely<AddressPointDatabase>): Promise<void>;
-//# sourceMappingURL=address-point-schema.d.ts.map
+export declare function createAddressPointIndexes(db: AddressPointSchemaHandle): Promise<void>;
+//# sourceMappingURL=point-schema.d.ts.map

package/out/address/point-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"point-schema.d.ts","sourceRoot":"","sources":["../../lib/address/point-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEpC,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAErE;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IACjC;;OAEG;IACH,WAAW,EAAE,SAAS,CAAA;IACtB;;;OAGG;IACH,UAAU,EAAE,QAAQ,CAAA;IACpB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB;;OAEG;IACH,aAAa,EAAE,OAAO,GAAG,IAAI,CAAA;IAC7B;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB;;;OAGG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,aAAa,EAAE,iBAAiB,CAAA;CAChC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,wBAAwB,GAAG,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,EAAE,QAAQ,CAAC,CAAA;AAEnF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,mKAcxB,CAAA;AAEV;;GAEG;AACH,wBAAsB,uBAAuB,CAAC,EAAE,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBzF;AAED;;GAEG;AACH,wBAAsB,yBAAyB,CAAC,EAAE,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmB3F"}

package/out/{address-point-schema.js → address/point-schema.js}

@@ -3,8 +3,8 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Typed schema for the SITUS / rooftop ADDRESS-POINT shards (`address-points-<cc>-<slug>.db`, built
- *   by `scripts/build-address-point-shard.ts` — the #476/#567 national rooftop tier behind the
+ *   Typed schema for the SITUS / rooftop ADDRESS-POINT extracts (`address-points-<cc>-<slug>.db`, built
+ *   by `scripts/build-address-point-extract.ts` — the #476/#567 national rooftop tier behind the
  *   demo's "type any US address, get the building"). Single source of truth for the columns shared
  *   by the BUILDER and the READER ({@link AddressPointSqliteLookup}), so a column rename in one is a
  *   compile error in the other.
@@ -31,6 +31,8 @@ export const ADDRESS_POINT_COLUMNS = [
     "lon",
     "source",
     "release",
+    "admin_code",
+    "certified",
 ];
 /**
  * Create the `address_point` table — called before the streaming bulk load.
@@ -50,6 +52,8 @@ export async function createAddressPointTable(db) {
         .addColumn("lon", "real", (c) => c.notNull())
         .addColumn("source", "text", (c) => c.notNull())
         .addColumn("release", "text", (c) => c.notNull())
+        .addColumn("admin_code", "text")
+        .addColumn("certified", "integer")
         .execute();
 }
 /**
@@ -73,4 +77,4 @@ export async function createAddressPointIndexes(db) {
     // bbox so it simply carries one extra (cheap) index on a future rebuild.
     await db.schema.createIndex("idx_ap_street").on("address_point").columns(["street_norm", "number"]).execute();
 }
-//# sourceMappingURL=address-point-schema.js.map
+//# sourceMappingURL=point-schema.js.map

package/out/address/point-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"point-schema.js","sourceRoot":"","sources":["../../lib/address/point-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAyEH;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACpC,aAAa;IACb,YAAY;IACZ,QAAQ;IACR,MAAM;IACN,UAAU;IACV,eAAe;IACf,YAAY;IACZ,KAAK;IACL,KAAK;IACL,QAAQ;IACR,SAAS;IACT,YAAY;IACZ,WAAW;CACF,CAAA;AAEV;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,EAA4B;IACzE,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,eAAe,CAAC;SAC5B,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QACrD,wFAAwF;SACvF,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACnD,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/C,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC;SACzB,SAAS,CAAC,UAAU,EAAE,MAAM,CAAC;SAC7B,SAAS,CAAC,eAAe,EAAE,MAAM,CAAC;SAClC,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACnD,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC5C,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC5C,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/C,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAChD,SAAS,CAAC,YAAY,EAAE,MAAM,CAAC;SAC/B,SAAS,CAAC,WAAW,EAAE,SAAS,CAAC;SACjC,OAAO,EAAE,CAAA;AACZ,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,EAA4B;IAC3E,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,iBAAiB,CAAC;SAC9B,EAAE,CAAC,eAAe,CAAC;SACnB,OAAO,CAAC,CAAC,UAAU,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC;SAC9C,OAAO,EAAE,CAAA;IAEX,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,iBAAiB,CAAC;SAC9B,EAAE,CAAC,eAAe,CAAC;SACnB,OAAO,CAAC,CAAC,eAAe,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC;SACnD,OAAO,EAAE,CAAA;IAEX,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC,EAAE,CAAC,eAAe,CAAC,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC,OAAO,EAAE,CAAA;IACjH,oGAAoG;IACpG,uGAAuG;IACvG,wGAAwG;IACxG,yEAAyE;IACzE,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,eAAe,CAAC,CAAC,OAAO,CAAC,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE,CAAA;AAC9G,CAAC"}

package/out/{address-point.d.ts → address/point.d.ts}

@@ -4,9 +4,9 @@
  * @author Teffen Ellis, et al.
  *
  *   SQLite implementation of core's `AddressPointLookup` (#476): exact `(street, number)` within a
- *   postcode (preferred), locality, or — for shards whose points carry no scope tag (OSM, #247) —
+ *   postcode (preferred), locality, or — for extracts whose points carry no scope tag (OSM, #247) —
  *   the resolved locality's BBOX. Query-side normalization is THE shared normalizer
- *   (`street-normalize.ts`), selected per the shard's `streetLocale` so build-side and probe-side
+ *   (`street-normalize.ts`), selected per the extract's `streetLocale` so build-side and probe-side
  *   stay identical by construction (US delegates to the USPS pipeline; FR/DE/NL use the locale rules).
  *
  *   Matching is exact-after-normalization only — no fuzzy street matching in this tier (measure how
@@ -15,16 +15,24 @@
  *   scopes missed). Multiple hits return the first by rowid — unit siblings share the building coord.
  */
 import type { AddressPointHit, AddressPointLookup } from "@mailwoman/resolver";
-import { type StreetLocale } from "./street-normalize.ts";
-export declare class AddressPointSqliteLookup implements AddressPointLookup {
+import type { AddressPointDatabase } from "#address/point-schema";
+import { type StreetLocale } from "#street/normalize";
+export declare class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressPointDatabase> implements AddressPointLookup, Disposable {
     #private;
     /**
-     * @param dbPath Shard path.
-     * @param opts.streetLocale The street-normalization locale this shard was BUILT with — must match, or every key
+     * @param dbPath Extract path.
+     * @param opts.streetLocale The street-normalization locale this extract was BUILT with — must match, or every key
      *   misses. Defaults to `"us"` (the situs tier), so existing callers are unchanged.
+     * @param opts.localityKeys Whether the extract's `locality_norm` is a FULL place name a query can be held to. The BAN
+     *   and OSM extracts write the commune or `addr:city` in full; the US situs extract writes the NAD city field, which
+     *   several counties abbreviate (`addi` for Addison on 5,174 Texas rows, 327,264 Texas rows at four characters or
+     *   fewer) or give as the parent town (`easton` for North Easton). A key like that can steer WHICH row answers but
+     *   cannot refuse one, so it never contradicts. Defaults from the street locale: `"us"` is abbreviated, the rest
+     *   full.
      */
     constructor(dbPath: string, opts?: {
         streetLocale?: StreetLocale;
+        localityKeys?: "full" | "abbreviated";
     });
     find(query: {
         street: string;
@@ -38,6 +46,6 @@ export declare class AddressPointSqliteLookup implements AddressPointLookup {
             maxLon: number;
         };
     }): AddressPointHit | null;
-    close(): void;
+    [Symbol.dispose](): void;
 }
-//# sourceMappingURL=address-point.d.ts.map
+//# sourceMappingURL=point.d.ts.map

package/out/address/point.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"point.d.ts","sourceRoot":"","sources":["../../lib/address/point.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAG9E,OAAO,KAAK,EAAE,oBAAoB,EAAqB,MAAM,uBAAuB,CAAA;AAEpF,OAAO,EAON,KAAK,YAAY,EACjB,MAAM,mBAAmB,CAAA;AAc1B,qBAAa,wBAAwB,CAAC,EAAE,SAAS,oBAAoB,GAAG,oBAAoB,CAC3F,YAAW,kBAAkB,EAAE,UAAU;;IAiBzC;;;;;;;;;;OAUG;gBACS,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,YAAY,CAAC,EAAE,YAAY,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,GAAG,aAAa,CAAA;KAAO;IAkC7G,IAAI,CAAC,KAAK,EAAE;QACX,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,MAAM,CAAA;QACd,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,IAAI,CAAC,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAA;KACzE,GAAG,eAAe,GAAG,IAAI;IAmK1B,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGxB"}

package/out/address/point.js

@@ -0,0 +1,191 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   SQLite implementation of core's `AddressPointLookup` (#476): exact `(street, number)` within a
+ *   postcode (preferred), locality, or — for extracts whose points carry no scope tag (OSM, #247) —
+ *   the resolved locality's BBOX. Query-side normalization is THE shared normalizer
+ *   (`street-normalize.ts`), selected per the extract's `streetLocale` so build-side and probe-side
+ *   stay identical by construction (US delegates to the USPS pipeline; FR/DE/NL use the locale rules).
+ *
+ *   Matching is exact-after-normalization only — no fuzzy street matching in this tier (measure how
+ *   far exact gets first; fuzz is a later, separate decision). Scope order is most-selective first:
+ *   postcode, then locality, then the bbox fall-through (only when a bbox is supplied AND the prior
+ *   scopes missed). Multiple hits return the first by rowid — unit siblings share the building coord.
+ */
+import { DatabaseClient } from "@mailwoman/sqlite/client";
+import { hasTable, prepareGet } from "#sqlite-utils";
+import { normalizeLocalityForKey, streetKeyVariants, streetLocaleForSurface, stripArrondissement, } from "#street/normalize";
+/**
+ * The 4 columns the reader SELECTs, in the schema's order — referenced by the prepared SELECTs so the projected
+ * `AddressPointRow` stays in lockstep with the shared schema.
+ */
+const SELECT_COLS = "lat, lon, source, release, locality_norm, postcode";
+export class AddressPointSqliteLookup {
+    #db;
+    #locale;
+    #localityKeys;
+    #byPostcode;
+    #byPostcodeLocality;
+    #byLocality;
+    #byBbox;
+    /**
+     * @param dbPath Extract path.
+     * @param opts.streetLocale The street-normalization locale this extract was BUILT with — must match, or every key
+     *   misses. Defaults to `"us"` (the situs tier), so existing callers are unchanged.
+     * @param opts.localityKeys Whether the extract's `locality_norm` is a FULL place name a query can be held to. The BAN
+     *   and OSM extracts write the commune or `addr:city` in full; the US situs extract writes the NAD city field, which
+     *   several counties abbreviate (`addi` for Addison on 5,174 Texas rows, 327,264 Texas rows at four characters or
+     *   fewer) or give as the parent town (`easton` for North Easton). A key like that can steer WHICH row answers but
+     *   cannot refuse one, so it never contradicts. Defaults from the street locale: `"us"` is abbreviated, the rest
+     *   full.
+     */
+    constructor(dbPath, opts = {}) {
+        this.#db = new DatabaseClient(dbPath, { readOnly: true });
+        this.#locale = opts.streetLocale ?? "us";
+        this.#localityKeys = opts.localityKeys ?? (this.#locale === "us" ? "abbreviated" : "full");
+        // Degrade gracefully on an empty/tableless extract (interrupted build, stray 0-byte file): with no
+        // `address_point` table this lookup is a no-op miss, not a crash that loses the whole state (#568).
+        if (hasTable(this.#db, "address_point")) {
+            this.#byPostcode = prepareGet(this.#db, `SELECT ${SELECT_COLS} FROM address_point
+				 WHERE postcode = ? AND street_norm = ? AND number = ? LIMIT 1`);
+            this.#byPostcodeLocality = prepareGet(this.#db, `SELECT ${SELECT_COLS} FROM address_point
+				 WHERE postcode = ? AND locality_norm = ? AND street_norm = ? AND number = ? LIMIT 1`);
+            this.#byLocality = prepareGet(this.#db, `SELECT ${SELECT_COLS} FROM address_point
+				 WHERE locality_norm = ? AND street_norm = ? AND number = ? LIMIT 1`);
+            this.#byBbox = prepareGet(this.#db, `SELECT ${SELECT_COLS} FROM address_point
+				 WHERE street_norm = ? AND number = ? AND lat BETWEEN ? AND ? AND lon BETWEEN ? AND ? LIMIT 1`);
+        }
+    }
+    find(query) {
+        if (!this.#byPostcode || !this.#byLocality || !this.#byBbox)
+            return null;
+        const number = query.number.trim().toLowerCase();
+        if (!number)
+            return null;
+        // Key-variant ladder (see `streetKeyVariants`): the literal key first, then the doubled-type
+        // collapse and the saint↔st register swap — each variant runs the FULL number ladder below, and
+        // the first variant to answer wins, so an attested literal key is never second-guessed.
+        let row;
+        for (const streetNorm of streetKeyVariants(query.street, streetLocaleForSurface(query.street, this.#locale))) {
+            row = this.#findForKey(streetNorm, number, query);
+            if (row)
+                break;
+        }
+        if (!row)
+            return null;
+        return {
+            lat: row.lat,
+            lon: row.lon,
+            source: row.source,
+            release: row.release,
+            ...(row.locality_norm ? { localityNorm: row.locality_norm } : {}),
+            ...(row.postcode ? { postcode: row.postcode } : {}),
+        };
+    }
+    /**
+     * The full number ladder for ONE normalized street key: exact, then the range low-end, then letter-suffix spacing
+     * with the base-number fall — see each rung's note in place.
+     */
+    #findForKey(streetNorm, number, query) {
+        let row = this.#probe(streetNorm, number, query);
+        // Range-surface fallback: every register this reader serves stores ONE number per point
+        // (G-NAF `NUMBER_FIRST`, BAN, OA, OSM `addr:housenumber`), but the attested surface is often
+        // a range — "385-387 Esplanade" keys `385`. Null-only: an exact range key that matched above
+        // (some OSM points DO carry "385-387" verbatim) is never second-guessed.
+        if (!row) {
+            const low = /^(\d+[a-z]?)-\d+[a-z]?$/.exec(number)?.[1];
+            if (low) {
+                row = this.#probe(streetNorm, low, query);
+            }
+        }
+        // Letter-suffix spacing fallback: the registers disagree on the joint — BAN stores "3 a"
+        // (space-separated), G-NAF and most OA sources store "3a" — and the parsed surface can arrive
+        // either way. On a miss, retry the OTHER spacing; on a double miss, the BASE number (the
+        // register attests no 3A but does attest 3 — the adjacent-parcel approximation, priced the
+        // same as the range fallback's low end). Null-only throughout, and only for the
+        // digits+single-letter shape (never touches "12 1/2" or unit-bearing forms).
+        if (!row) {
+            const joined = /^(\d+)\s+([a-z])$/.exec(number);
+            const spaced = /^(\d+)([a-z])$/.exec(number);
+            if (joined) {
+                row = this.#probe(streetNorm, `${joined[1]}${joined[2]}`, query) ?? this.#probe(streetNorm, joined[1], query);
+            }
+            else if (spaced) {
+                row = this.#probe(streetNorm, `${spaced[1]} ${spaced[2]}`, query) ?? this.#probe(streetNorm, spaced[1], query);
+            }
+        }
+        return row;
+    }
+    /**
+     * The scope ladder for one (street, number) key: postcode, then locality, then the bbox fall-through — each rung only
+     * when the prior missed.
+     */
+    #probe(streetNorm, number, query) {
+        let row;
+        if (query.postcode) {
+            const postcode = query.postcode.trim();
+            const localityKey = query.locality ? this.#localityKey(query.locality) : undefined;
+            // A postcode can span several places — DE 04509 covers Schönwölkau and Werlitzsch, both with a Teichstraße 3 —
+            // so when the query names a locality the row whose own locality agrees is asked for FIRST. Only when no such
+            // row exists does the postcode-only row answer, and then only if its locality does not name a different place
+            // (see `#scopeContradicts` for what "different" tolerates): a query naming a third village under the postcode
+            // falls through to the locality rung rather than answering the wrong rooftop.
+            const agreeing = localityKey ? this.#byPostcodeLocality(postcode, localityKey, streetNorm, number) : undefined;
+            const candidate = agreeing ?? this.#byPostcode(postcode, streetNorm, number);
+            row = candidate && !this.#scopeContradicts(candidate, query) ? candidate : undefined;
+        }
+        if (!row && query.locality) {
+            // FR extracts key arrondissement communes at the base city (both-sides fold, see the BAN
+            // builder + stripArrondissement) — fold the probe too so "Paris 13e Arrondissement" and
+            // "Paris" both hit. No-op for "us" extracts and every non-arrondissement commune.
+            row = this.#byLocality(this.#localityKey(query.locality), streetNorm, number);
+        }
+        // Bbox fall-through (#247): the point carries no postcode/locality of its own, but its coordinate falls
+        // inside the resolved locality's box. Only reached when the scoped probes missed AND a bbox was supplied.
+        if (!row && query.bbox) {
+            const b = query.bbox;
+            const candidate = this.#byBbox(streetNorm, number, b.minLat, b.maxLat, b.minLon, b.maxLon);
+            // A register row that carries its own scope and was NOT found by the scoped rungs is a different address that
+            // happens to share the street and number inside the box: `10 rue de la République, 75008 Paris` reached
+            // Servon's `10 rue de la République` (postcode 77170) 26 km away this way, at rooftop tier and 1 m uncertainty.
+            // The rung exists for points with no scope of their own; a point whose scope disagrees with the query is a miss.
+            row = candidate && !this.#scopeContradicts(candidate, query) ? candidate : undefined;
+        }
+        return row;
+    }
+    /**
+     * The query's locality folded the way the extract's builder folded its `locality_norm`. FR extracts key
+     * arrondissement communes at the base city (both-sides fold, see the BAN builder + stripArrondissement), so "Paris
+     * 13e Arrondissement" and "Paris" both hit; a no-op for every other locale.
+     */
+    #localityKey(locality) {
+        return this.#locale === "fr"
+            ? stripArrondissement(normalizeLocalityForKey(locality))
+            : normalizeLocalityForKey(locality);
+    }
+    /**
+     * Whether a row's OWN postcode or locality names a different place than the query did. Absent scope on the row is not
+     * a contradiction — it is the case the bbox rung was built for — and a rung that matched ON a field cannot contradict
+     * it, so at the postcode rung only the locality can disagree and at the bbox rung either can.
+     *
+     * The locality is consulted only on an extract whose keys are full names (the constructor's `localityKeys`). Under
+     * exact comparison against the US extract's abbreviated keys, the postcode rung refused `4900 Airport Pkwy, Addison
+     * TX 75001`'s own rooftop row (`addi`) and `678 Depot St, North Easton, MA 02356`'s (`easton`), and both `pass` board
+     * rows fell to interpolation 144–198 m away — invisible to a 1 km grade (#2155). `servon` against `paris` and
+     * `werlitzsch` against `krensitz`, on the BAN and OSM extracts, are different places and still refuse.
+     */
+    #scopeContradicts(row, query) {
+        if (query.postcode && row.postcode && row.postcode.trim() !== query.postcode.trim())
+            return true;
+        if (this.#localityKeys === "full" && query.locality && row.locality_norm) {
+            return row.locality_norm !== this.#localityKey(query.locality);
+        }
+        return false;
+    }
+    [Symbol.dispose]() {
+        this.#db[Symbol.dispose]();
+    }
+}
+//# sourceMappingURL=point.js.map

package/out/address/point.js.map

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