@mailwoman/resolver-wof-sqlite 9.4.0 → 10.1.0

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

@@ -0,0 +1,45 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Address-point interpolation, the second method of the resolution ladder. When the exact
+ *   address-point tier misses a house number, bracket the number with real neighbor points on the
+ *   same street and interpolate linearly in house-number space between them. Real occupancy
+ *   replaces the tiger range tier's uniform-spacing assumption. Tiger range interpolation
+ *   (`StreetInterpolator`) is the fallback for streets too sparse to bracket.
+ *
+ *   The matching key is `street_key`, the shared normalizer plus the route fold
+ *   (`canonicalizeRouteKey`), identical at build time (`mailwoman situs address-points`) and query
+ *   time by construction. Scope is postcode-first like the segment tier. A query without a postcode
+ *   goes straight to the fallback. The fallback has its own statewide-ambiguity abstention.
+ *
+ *   Neighbor candidates never include the queried number itself, so production never overrides an
+ *   on-file number and grading against the same extract is non-circular.
+ *
+ *   - Both-sided bracket (`bracket: "both"`): linear interpolation between the nearest known number
+ *       below and above. `uncertaintyM` is half the distance between them.
+ *   - Single-sided (`bracket: "single"`): linear extrapolation along the two nearest known numbers
+ *       on that side, capped at one pair-span beyond the nearest point (`t ≤ 2`, past which the line
+ *       provides no evidence and the query falls through). `uncertaintyM` is the pair distance plus
+ *       the extrapolated overshoot, larger than the both-sided radius.
+ *   - No bracket, meaning no neighbors, a single known number, or past the extrapolation cap: fall
+ *       through to the tiger fallback when configured, else null.
+ *
+ *   Standalone like the segment tier, wired through the ordered `spatialTiers` list.
+ */
+import type { InterpolationLookup } from "@mailwoman/core/resolver";
+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?: DatabaseClient<DB>;
+        fallback?: StreetInterpolator;
+    });
+    find(query: InterpolationQuery): InterpolatedHit | null;
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=interpolation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"interpolation.d.ts","sourceRoot":"","sources":["../../../lib/address/point/interpolation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAEnE,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;AA8B7F,qBAAa,wBAAwB,CACpC,EAAE,SAAS,oBAAoB,GAAG,oBAAoB,CACrD,YAAW,mBAAmB;;IAY/B,YAAY,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,cAAc,CAAC,EAAE,CAAC,CAAC;QAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAA;KAAE,EA2BlG;IAED,IAAI,CAAC,KAAK,EAAE,kBAAkB,GAAG,eAAe,GAAG,IAAI,CAsBtD;IAED,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAEvB;CACD"}

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

@@ -3,85 +3,84 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   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 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.
+ *   Address-point interpolation, the second method of the resolution ladder. When the exact
+ *   address-point tier misses a house number, bracket the number with real neighbor points on the
+ *   same street and interpolate linearly in house-number space between them. Real occupancy
+ *   replaces the tiger range tier's uniform-spacing assumption. Tiger range interpolation
+ *   (`StreetInterpolator`) is 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-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).
+ *   The matching key is `street_key`, the shared normalizer plus the route fold
+ *   (`canonicalizeRouteKey`), identical at build time (`mailwoman situs address-points`) and query
+ *   time by construction. Scope is postcode-first like the segment tier. A query without a postcode
+ *   goes straight to the fallback. The fallback has its own statewide-ambiguity abstention.
  *
- *   Bracketing contract:
+ *   Neighbor candidates never include the queried number itself, so production never overrides an
+ *   on-file number and grading against the same extract is non-circular.
  *
- *   - 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 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
- *       that side, capped at one pair-span beyond the nearest point (`t ≤ 2` — beyond that the line
- *       carries no evidence and the query falls through); `uncertaintyM` = the pair distance plus
- *       the extrapolated overshoot, explicitly larger than the both-sided radius.
- *   - No bracket (no neighbors, a single known number, or past the extrapolation cap): fall through to
- *       the TIGER fallback when configured, else null.
+ *       below and above. `uncertaintyM` is half the distance between them.
+ *   - Single-sided (`bracket: "single"`): linear extrapolation along the two nearest known numbers
+ *       on that side, capped at one pair-span beyond the nearest point (`t ≤ 2`, past which the line
+ *       provides no evidence and the query falls through). `uncertaintyM` is the pair distance plus
+ *       the extrapolated overshoot, larger than the both-sided radius.
+ *   - No bracket, meaning no neighbors, a single known number, or past the extrapolation cap: fall
+ *       through to the tiger fallback when configured, else null.
  *
- *   Standalone like the segment tier — core wiring rides the Phase 2 ordered `spatialTiers` list.
+ *   Standalone like the segment tier, wired through the ordered `spatialTiers` list.
  */
 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.
+ * 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 provides no evidence about the query number.
  */
 const MAX_EXTRAPOLATION_T = 2;
 export class AddressPointInterpolator {
     #db;
     /**
-     * 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 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 checks.
      */
-    #resources = new DisposableStack();
+    #resources;
     #fallback;
     #byPostcode;
     constructor(opts) {
+        using resources = new DisposableStack();
         if (opts.database) {
             this.#db = opts.database;
         }
         else if (opts.dbPath) {
-            this.#db = this.#resources.use(new DatabaseClient(opts.dbPath, { readOnly: true }));
+            this.#db = 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 extract (#568): with no `address_point` table this tier
-        // is skipped, deferring to the segment fallback rather than crashing at construction.
+        // Degrade gracefully on an extract without an `address_point` table.
+        // The tier is skipped and defers 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 = 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]*'
 					AND CAST(number AS INTEGER) != ?`);
         }
+        this.#resources = resources.move();
     }
     find(query) {
         const numberRaw = query.number.trim();
         if (!/^\d+$/.test(numberRaw))
             return null;
         const n = Number(numberRaw);
-        // 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;
-        // Key-variant ladder (see `streetKeyVariants`) — same probe order as the exact-point reader.
+        // Key-variant ladder (see `streetKeyVariants`), the same probe order as the exact-point reader.
         let rows = [];
         for (const variant of streetKeyVariants(query.street)) {
             const streetKey = canonicalizeRouteKey(variant);
@@ -122,7 +121,8 @@ function anchorsByNumber(rows) {
 }
 function interpolateFromNeighbors(rows, n) {
     const anchors = anchorsByNumber(rows);
-    // Nearest known number below and above the query (the rows never contain n itself).
+    // Nearest known number below and above the query.
+    // The rows never contain n itself.
     let below;
     let above;
     for (const anchor of anchors) {
@@ -149,7 +149,7 @@ function interpolateFromNeighbors(rows, n) {
         };
     }
     // Single-sided: extrapolate along the two nearest known numbers on the populated side.
-    // `near` is the anchor closest to n, `far` the next one out; t > 1 by construction.
+    // `t > 1` by construction because n lies outside the span.
     const side = below ? anchors.slice(-2) : anchors.slice(0, 2);
     if (side.length < 2)
         return null;
@@ -173,4 +173,4 @@ function interpolateFromNeighbors(rows, n) {
         release: near.release,
     };
 }
-//# sourceMappingURL=point-interpolation.js.map
+//# sourceMappingURL=interpolation.js.map

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

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

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

@@ -0,0 +1,74 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+import type { Kysely } from "kysely";
+import type { NameKey, RouteKey, StreetKey } from "#street/normalize";
+/**
+ * One rooftop address point; `(street_norm, number)` within a `postcode`
+ * or `locality_norm` scope is the lookup.
+ */
+export interface AddressPointTable {
+    /**
+     * Shared {@link normalizeStreetForKey} of the street — the build/query-consistent probe key.
+     */
+    street_norm: StreetKey;
+    /**
+     * `canonicalizeRouteKey(street_norm)` — the route-fold key, branded
+     * so it cannot be interchanged with `street_norm`.
+     */
+    street_key: RouteKey;
+    /**
+     * House number, normalized lower-case (kept text — "123-A", "12 1/2" must survive).
+     */
+    number: string;
+    unit: string | null;
+    postcode: string | null;
+    /**
+     * Shared {@link normalizeLocalityForKey} of the locality — the fallback scope.
+     */
+    locality_norm: NameKey | null;
+    street_raw: string;
+    lat: number;
+    lon: number;
+    /**
+     * Provenance: the dataset this point came from (e.g. `overture:us`, `openaddresses`).
+     */
+    source: string;
+    release: string;
+    /**
+     * The source register's stable administrative key for the point's commune or municipality —
+     * BAN's `code_insee`; the coverage basis is computed per this key.
+     */
+    admin_code: string | null;
+    /**
+     * The register's own certification flag for the point
+     * (BAN `certification_commune`: 1 certified, 0 not), never inferred from a share.
+     */
+    certified: number | null;
+}
+/**
+ * The address-point database schema for `new DatabaseClient<AddressPointDatabase>(...)`.
+ */
+export interface AddressPointDatabase {
+    address_point: AddressPointTable;
+}
+/**
+ * The subset of a Kysely handle the DDL touches, narrowed to `schema`
+ * because Kysely is invariant in its schema parameter.
+ */
+export type AddressPointSchemaHandle = Pick<Kysely<AddressPointDatabase>, "schema">;
+/**
+ * The `address_point` columns in insert order, from which the builder derives its positional placeholders.
+ */
+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: AddressPointSchemaHandle): Promise<void>;
+/**
+ * Create the three probe indexes the reader relies on (postcode-scope, locality-scope, route-key).
+ */
+export declare function createAddressPointIndexes(db: AddressPointSchemaHandle): Promise<void>;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../lib/address/point/schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEpC,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAErE;;;GAGG;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;IAE7B,UAAU,EAAE,MAAM,CAAA;IAClB,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd,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;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,EAAE,QAAQ,CAAC,CAAA;AAEnF;;GAEG;AACH,eAAO,MAAM,qBAAqB,YACjC,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,MAAM,EACN,UAAU,EACV,eAAe,EACf,YAAY,EACZ,KAAK,EACL,KAAK,EACL,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,WAAW,CACF,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,CAiB3F"}

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

@@ -2,22 +2,9 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   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.
- *
- *   The builder's hot INSERT (tens of millions of rows per state) stays a POSITIONAL prepared
- *   statement for throughput — but its column list is derived from {@link ADDRESS_POINT_COLUMNS}
- *   here, and its table comes from {@link createAddressPointTable}, so the positional order can't
- *   silently drift from what the reader expects. (Same convention as the candidate build: typed
- *   schema guards the contract; positional inserts keep the speed.)
  */
 /**
- * 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.
+ * The `address_point` columns in insert order, from which the builder derives its positional placeholders.
  */
 export const ADDRESS_POINT_COLUMNS = [
     "street_norm",
@@ -41,7 +28,6 @@ export async function createAddressPointTable(db) {
     await db.schema
         .createTable("address_point")
         .addColumn("street_norm", "text", (c) => c.notNull())
-        // `street_key` = canonicalizeRouteKey(street_norm): the route-fold key (#483 Method 2).
         .addColumn("street_key", "text", (c) => c.notNull())
         .addColumn("number", "text", (c) => c.notNull())
         .addColumn("unit", "text")
@@ -71,10 +57,8 @@ export async function createAddressPointIndexes(db) {
         .columns(["locality_norm", "street_norm", "number"])
         .execute();
     await db.schema.createIndex("idx_ap_streetkey").on("address_point").columns(["postcode", "street_key"]).execute();
-    // Street-first index for the BBOX scope (#247): OSM points often carry no postcode/locality, so the
-    // reader scopes a `(street_norm, number)` probe by the resolved locality's bbox (lat/lon BETWEEN). The
-    // postcode/locality indexes lead with their scope column and can't serve this; US situs never probes by
-    // bbox so it simply carries one extra (cheap) index on a future rebuild.
+    // Street-first index for the bbox scope: OSM points often have no postcode or locality,
+    // so the reader scopes a `(street_norm, number)` probe by the resolved locality's bbox.
     await db.schema.createIndex("idx_ap_street").on("address_point").columns(["street_norm", "number"]).execute();
 }
-//# sourceMappingURL=point-schema.js.map
+//# sourceMappingURL=schema.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../lib/address/point/schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAiEH;;GAEG;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;SAEpD,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,wFAAwF;IACxF,wFAAwF;IACxF,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

@@ -2,35 +2,38 @@
  * @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.
+ * @file SQLite implementation of core's `AddressPointLookup`.
  */
 import type { AddressPointHit, AddressPointLookup } from "@mailwoman/core/resolver";
-import type { AddressPointDatabase } from "#address/point-schema";
+import type { PathBuilderLike } from "path-ts";
+import type { AddressPointDatabase } from "#address/point/schema";
 import { type StreetLocale } from "#street/normalize";
+/**
+ * Finds an address point by exact normalized `(street, number)` within a postcode,
+ * a locality, or a bounding box.
+ *
+ * Query normalization uses the extract's `streetLocale`, which must match the
+ * locale the extract was built with.
+ * Street matching is exact after normalization.
+ *
+ * Scopes are tried from most to least selective: postcode, locality, locality suffix, then bounding box.
+ * When several rows match, any one of them can answer, because unit siblings share the building coordinate.
+ */
 export declare class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressPointDatabase> implements AddressPointLookup, Disposable {
     #private;
     /**
      * @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.
+     * @param opts.streetLocale The street-normalization locale the extract was built with.
+     * A mismatch makes every key miss.
+     * It defaults to `"us"`.
+     * @param opts.localityKeys Whether the extract's `locality_norm` holds full place names.
+     * With `"abbreviated"`, a row's locality can select a row but never rejects one.
+     * The US situs extract uses NAD city fields.
+     * Some counties abbreviate them (`addi` for Addison).
+     * Other counties replace them with the parent town.
+     * It defaults to `"abbreviated"` for `"us"` and `"full"` for every other locale.
      */
-    constructor(dbPath: string, opts?: {
+    constructor(dbPath: PathBuilderLike, opts?: {
         streetLocale?: StreetLocale;
         localityKeys?: "full" | "abbreviated";
     });

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

@@ -1 +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,0BAA0B,CAAA;AAGnF,OAAO,KAAK,EAAE,oBAAoB,EAAqB,MAAM,uBAAuB,CAAA;AAEpF,OAAO,EASN,KAAK,YAAY,EACjB,MAAM,mBAAmB,CAAA;AAc1B,qBAAa,wBAAwB,CAAC,EAAE,SAAS,oBAAoB,GAAG,oBAAoB,CAC3F,YAAW,kBAAkB,EAAE,UAAU;;IAwBzC;;;;;;;;;;OAUG;gBACS,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,YAAY,CAAC,EAAE,YAAY,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,GAAG,aAAa,CAAA;KAAO;IAwC7G,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,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,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;IAkM1B,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGxB"}
+{"version":3,"file":"point.d.ts","sourceRoot":"","sources":["../../lib/address/point.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAEnF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C,OAAO,KAAK,EAAE,oBAAoB,EAAqB,MAAM,uBAAuB,CAAA;AAEpF,OAAO,EASN,KAAK,YAAY,EACjB,MAAM,mBAAmB,CAAA;AAc1B;;;;;;;;;;GAUG;AACH,qBAAa,wBAAwB,CAAC,EAAE,SAAS,oBAAoB,GAAG,oBAAoB,CAC3F,YAAW,kBAAkB,EAAE,UAAU;;IAyBzC;;;;;;;;;;;OAWG;IACH,YACC,MAAM,EAAE,eAAe,EACvB,IAAI,GAAE;QAAE,YAAY,CAAC,EAAE,YAAY,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,GAAG,aAAa,CAAA;KAAO,EAsCjF;IAED,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,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,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,CAsCzB;IAyID,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAEvB;CACD"}