@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/out/sqlite/convention-source.js

@@ -2,31 +2,24 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   `SqliteConventionSource` — a `ConventionSource` backed by the build-from-source convention asset
- *   (#290, Direction E). Conventions live in a read-only, provenance-stamped `address_convention`
- *   table keyed by WOF polygon id; this source queries them ON DEMAND by id (one indexed lookup,
- *   memoized) rather than paging the whole table into memory as a code constant — the deliberate
- *   counter to the Pelias "giant dictionary in RAM, no provenance" pattern (see the operator design
- *   value in memory `feedback-no-irrelevant-trivia`).
- *
- *   The asset is the queryable, distributable artifact; the strategy IMPLEMENTATIONS stay in code. An
- *   unknown strategy NAME is surfaced loudly at dispatch (see `lookup.ts`), not silently
- *   swallowed.
  */
 import { tryParsingJSON } from "@mailwoman/core/json";
-import { ADDRESS_CONVENTION_TABLE } from "#convention/index";
+import { ADDRESS_CONVENTION_TABLE } from "#convention";
+/**
+ * Reads per-place address conventions from the convention table in an attached
+ * SQLite schema, caching each lookup, including misses.
+ *
+ * A missing table or unparseable row reads as no convention rather than throwing.
+ */
 export class SqliteConventionSource {
     #db;
     #schema;
-    /**
-     * Memoize per-id lookups (including misses, as `null`) so a hot ancestor chain is queried once.
-     */
     #cache = new Map();
     /**
-     * @param db An open handle to a DB that has the convention asset attached (or is it).
-     * @param schema The schema name the `address_convention` table lives under (`main` or an ATTACHed extract name —
-     *   `WOFSQLitePlaceLookup` auto-detects which extract carries the table).
+     * Creates a source over an open database that is, or has attached, the convention asset.
+     *
+     * @param db The open database handle.
+     * @param schema The schema that holds the convention table, either `main` or an attached extract's name.
      */
     constructor(db, schema) {
         this.#db = db;
@@ -35,7 +28,7 @@ export class SqliteConventionSource {
     get(wofID) {
         const cached = this.#cache.get(wofID);
         if (cached !== undefined)
-            return cached ?? undefined;
+            return cached;
         let value = null;
         try {
             const row = this.#db
@@ -46,12 +39,10 @@ export class SqliteConventionSource {
             }
         }
         catch {
-            // A missing table → treat as no override (the chain falls back to WORLD_DEFAULT); malformed
-            // JSON already nulls out above. The build script validates structure, so this is purely defensive.
             value = null;
         }
         this.#cache.set(wofID, value);
-        return value ?? undefined;
+        return value;
     }
 }
 //# sourceMappingURL=convention-source.js.map

package/out/sqlite/convention-source.js.map

@@ -1 +1 @@
-{"version":3,"file":"convention-source.js","sourceRoot":"","sources":["../../lib/sqlite/convention-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAGrD,OAAO,EAAE,wBAAwB,EAA0C,MAAM,mBAAmB,CAAA;AAEpG,MAAM,OAAO,sBAAsB;IACzB,GAAG,CAAoB;IACvB,OAAO,CAAQ;IACxB;;OAEG;IACM,MAAM,GAAG,IAAI,GAAG,EAA6B,CAAA;IAEtD;;;;OAIG;IACH,YAAY,EAAsB,EAAE,MAAc;QACjD,IAAI,CAAC,GAAG,GAAG,EAAE,CAAA;QACb,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;IACtB,CAAC;IAED,GAAG,CAAC,KAAa;QAChB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAErC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,IAAI,SAAS,CAAA;QACpD,IAAI,KAAK,GAAsB,IAAI,CAAA;QAEnC,IAAI,CAAC;YACJ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG;iBAClB,OAAO,CAAC,0BAA0B,IAAI,CAAC,OAAO,IAAI,wBAAwB,mBAAmB,CAAC;iBAC9F,GAAG,CAAC,KAAK,CAAuC,CAAA;YAElD,IAAI,GAAG,EAAE,UAAU,EAAE,CAAC;gBACrB,KAAK,GAAG,cAAc,CAAa,GAAG,CAAC,UAAU,CAAC,CAAA;YACnD,CAAC;QACF,CAAC;QAAC,MAAM,CAAC;YACR,4FAA4F;YAC5F,mGAAmG;YACnG,KAAK,GAAG,IAAI,CAAA;QACb,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;QAE7B,OAAO,KAAK,IAAI,SAAS,CAAA;IAC1B,CAAC;CACD"}
+{"version":3,"file":"convention-source.js","sourceRoot":"","sources":["../../lib/sqlite/convention-source.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAGrD,OAAO,EAAE,wBAAwB,EAA0C,MAAM,aAAa,CAAA;AAE9F;;;;;GAKG;AACH,MAAM,OAAO,sBAAsB;IACzB,GAAG,CAAoB;IACvB,OAAO,CAAQ;IAEf,MAAM,GAAG,IAAI,GAAG,EAA6B,CAAA;IAEtD;;;;;OAKG;IACH,YAAY,EAAsB,EAAE,MAAc;QACjD,IAAI,CAAC,GAAG,GAAG,EAAE,CAAA;QACb,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;IACtB,CAAC;IAED,GAAG,CAAC,KAAa;QAChB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAErC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAA;QACvC,IAAI,KAAK,GAAsB,IAAI,CAAA;QAEnC,IAAI,CAAC;YACJ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG;iBAClB,OAAO,CAAC,0BAA0B,IAAI,CAAC,OAAO,IAAI,wBAAwB,mBAAmB,CAAC;iBAC9F,GAAG,CAAC,KAAK,CAAuC,CAAA;YAElD,IAAI,GAAG,EAAE,UAAU,EAAE,CAAC;gBACrB,KAAK,GAAG,cAAc,CAAa,GAAG,CAAC,UAAU,CAAC,CAAA;YACnD,CAAC;QACF,CAAC;QAAC,MAAM,CAAC;YACR,KAAK,GAAG,IAAI,CAAA;QACb,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;QAE7B,OAAO,KAAK,CAAA;IACb,CAAC;CACD"}

package/out/sqlite/utils.d.ts

@@ -2,44 +2,44 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   Small shared helpers for the SQLite-backed lookups.
+ * @file Shared helpers for the SQLite-backed lookups.
  */
 import type { DatabaseClient, SQLInputValue } from "@mailwoman/sqlite/client";
 /**
- * A prepared single-row query whose parameter tuple remains visible to TypeScript. `StatementSync` accepts only the
- * broad `SQLInputValue[]`, which otherwise erases tagged key types before they reach SQLite.
+ * A prepared single-row query whose parameter tuple stays visible to TypeScript.
+ *
+ * `StatementSync` accepts any `SQLInputValue[]`, which would erase tagged key types at the call site.
  */
-export type PreparedGet<Parameters extends SQLInputValue[], Row> = (...parameters: Parameters) => Row | undefined;
+export type PreparedGet<Parameters extends SQLInputValue[], Row> = (...parameters: Parameters) => Row | null;
 /**
- * Prepare a single-row query while preserving its exact parameter tuple at every call site.
+ * Prepares a single-row query with a typed parameter tuple.
  */
 export declare function prepareGet<Parameters extends SQLInputValue[], Row, DB>(db: DatabaseClient<DB>, sql: string): PreparedGet<Parameters, Row>;
 /**
- * Multi-row counterpart to {@link PreparedGet}.
+ * The multi-row counterpart to {@link PreparedGet}.
  */
 export type PreparedAll<Parameters extends SQLInputValue[], Row> = (...parameters: Parameters) => Row[];
 /**
- * Prepare a multi-row query while preserving its exact parameter tuple at every call site.
+ * Prepares a multi-row query with a typed parameter tuple.
  */
 export declare function prepareAll<Parameters extends SQLInputValue[], Row, DB>(db: DatabaseClient<DB>, sql: string): PreparedAll<Parameters, Row>;
 /**
- * True when `name` is a table in the open database. The street-level lookups use this to degrade gracefully on an
- * empty/tableless extract — an interrupted `build-*-extract.ts`, or a stray 0-byte file (e.g. `sqlite3 <missing>.db
- * "…"` CREATES one) — rather than throwing `no such table` at construction and taking down a whole state's geocode
- * (#568). A missing table makes the lookup a no-op miss.
+ * Returns true when `name` is a table in the open database.
+ * Returns false when the check itself fails.
+ *
+ * The street-level lookups call it so that an empty extract, such as an interrupted build
+ * or a zero-byte file, makes every lookup miss instead of throwing `no such table`.
  */
 export declare function hasTable<DB>(db: DatabaseClient<DB>, name: string): boolean;
 /**
- * True when `table` exists in the open database AND carries `column`.
+ * Returns true when `table` exists in the open database and has `column`.
  *
- * The column-level sibling of {@link hasTable}, and it exists for the same reason one layer down: an artifact built
- * before a column was added is still a VALID artifact, and a reader that unconditionally names the new column in its
- * `SELECT` turns "this gazetteer is a build behind" into `no such column` at the first keystroke. Probe once at
- * construction and shape the query — `table_info` is a PRAGMA, so it must not sit on a per-query path.
+ * An artifact built before a column was added is still valid, so readers call this once
+ * at construction and leave the column out of their queries when it is missing.
+ * Avoid calling it per query, because it runs a pragma.
  *
- * Note the interpolation: PRAGMA does not take bound parameters, so `table` is spliced. Every caller passes a
- * module-level constant; never pass user input.
+ * The pragma does not accept bound parameters, so `table` is interpolated into the SQL.
+ * Pass only constants.
  */
 export declare function hasColumn<DB>(db: DatabaseClient<DB>, table: string, column: string): boolean;
 //# sourceMappingURL=utils.d.ts.map

package/out/sqlite/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../lib/sqlite/utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAM7E;;;GAGG;AACH,MAAM,MAAM,WAAW,CAAC,UAAU,SAAS,aAAa,EAAE,EAAE,GAAG,IAAI,CAAC,GAAG,UAAU,EAAE,UAAU,KAAK,GAAG,GAAG,SAAS,CAAA;AAEjH;;GAEG;AACH,wBAAgB,UAAU,CAAC,UAAU,SAAS,aAAa,EAAE,EAAE,GAAG,EAAE,EAAE,EACrE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,EACtB,GAAG,EAAE,MAAM,GACT,WAAW,CAAC,UAAU,EAAE,GAAG,CAAC,CAI9B;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,UAAU,SAAS,aAAa,EAAE,EAAE,GAAG,IAAI,CAAC,GAAG,UAAU,EAAE,UAAU,KAAK,GAAG,EAAE,CAAA;AAEvG;;GAEG;AACH,wBAAgB,UAAU,CAAC,UAAU,SAAS,aAAa,EAAE,EAAE,GAAG,EAAE,EAAE,EACrE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,EACtB,GAAG,EAAE,MAAM,GACT,WAAW,CAAC,UAAU,EAAE,GAAG,CAAC,CAI9B;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAM1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAM5F"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../lib/sqlite/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAG7E;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,UAAU,SAAS,aAAa,EAAE,EAAE,GAAG,IAAI,CAAC,GAAG,UAAU,EAAE,UAAU,KAAK,GAAG,GAAG,IAAI,CAAA;AAE5G;;GAEG;AACH,wBAAgB,UAAU,CAAC,UAAU,SAAS,aAAa,EAAE,EAAE,GAAG,EAAE,EAAE,EACrE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,EACtB,GAAG,EAAE,MAAM,GACT,WAAW,CAAC,UAAU,EAAE,GAAG,CAAC,CAI9B;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,UAAU,SAAS,aAAa,EAAE,EAAE,GAAG,IAAI,CAAC,GAAG,UAAU,EAAE,UAAU,KAAK,GAAG,EAAE,CAAA;AAEvG;;GAEG;AACH,wBAAgB,UAAU,CAAC,UAAU,SAAS,aAAa,EAAE,EAAE,GAAG,EAAE,EAAE,EACrE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,EACtB,GAAG,EAAE,MAAM,GACT,WAAW,CAAC,UAAU,EAAE,GAAG,CAAC,CAI9B;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAM1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAM5F"}

package/out/sqlite/utils.js

@@ -2,30 +2,30 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   Small shared helpers for the SQLite-backed lookups.
+ * @file Shared helpers for the SQLite-backed lookups.
  */
 import { allRows, getRow } from "@mailwoman/core/utils";
 import { hasColumn as columnExists, tableExists } from "@mailwoman/sqlite/introspection";
 /**
- * Prepare a single-row query while preserving its exact parameter tuple at every call site.
+ * Prepares a single-row query with a typed parameter tuple.
  */
 export function prepareGet(db, sql) {
     const statement = db.prepare(sql);
     return (...parameters) => getRow(statement, ...parameters);
 }
 /**
- * Prepare a multi-row query while preserving its exact parameter tuple at every call site.
+ * Prepares a multi-row query with a typed parameter tuple.
  */
 export function prepareAll(db, sql) {
     const statement = db.prepare(sql);
     return (...parameters) => allRows(statement, ...parameters);
 }
 /**
- * True when `name` is a table in the open database. The street-level lookups use this to degrade gracefully on an
- * empty/tableless extract — an interrupted `build-*-extract.ts`, or a stray 0-byte file (e.g. `sqlite3 <missing>.db
- * "…"` CREATES one) — rather than throwing `no such table` at construction and taking down a whole state's geocode
- * (#568). A missing table makes the lookup a no-op miss.
+ * Returns true when `name` is a table in the open database.
+ * Returns false when the check itself fails.
+ *
+ * The street-level lookups call it so that an empty extract, such as an interrupted build
+ * or a zero-byte file, makes every lookup miss instead of throwing `no such table`.
  */
 export function hasTable(db, name) {
     try {
@@ -36,15 +36,14 @@ export function hasTable(db, name) {
     }
 }
 /**
- * True when `table` exists in the open database AND carries `column`.
+ * Returns true when `table` exists in the open database and has `column`.
  *
- * The column-level sibling of {@link hasTable}, and it exists for the same reason one layer down: an artifact built
- * before a column was added is still a VALID artifact, and a reader that unconditionally names the new column in its
- * `SELECT` turns "this gazetteer is a build behind" into `no such column` at the first keystroke. Probe once at
- * construction and shape the query — `table_info` is a PRAGMA, so it must not sit on a per-query path.
+ * An artifact built before a column was added is still valid, so readers call this once
+ * at construction and leave the column out of their queries when it is missing.
+ * Avoid calling it per query, because it runs a pragma.
  *
- * Note the interpolation: PRAGMA does not take bound parameters, so `table` is spliced. Every caller passes a
- * module-level constant; never pass user input.
+ * The pragma does not accept bound parameters, so `table` is interpolated into the SQL.
+ * Pass only constants.
  */
 export function hasColumn(db, table, column) {
     try {

package/out/sqlite/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../lib/sqlite/utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AAEvD,OAAO,EAAE,SAAS,IAAI,YAAY,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAA;AAWxF;;GAEG;AACH,MAAM,UAAU,UAAU,CACzB,EAAsB,EACtB,GAAW;IAEX,MAAM,SAAS,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAEjC,OAAO,CAAC,GAAG,UAAU,EAAE,EAAE,CAAC,MAAM,CAAM,SAAS,EAAE,GAAG,UAAU,CAAC,CAAA;AAChE,CAAC;AAOD;;GAEG;AACH,MAAM,UAAU,UAAU,CACzB,EAAsB,EACtB,GAAW;IAEX,MAAM,SAAS,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAEjC,OAAO,CAAC,GAAG,UAAU,EAAE,EAAE,CAAC,OAAO,CAAM,SAAS,EAAE,GAAG,UAAU,CAAC,CAAA;AACjE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAK,EAAsB,EAAE,IAAY;IAChE,IAAI,CAAC;QACJ,OAAO,WAAW,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;IAC7B,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAA;IACb,CAAC;AACF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS,CAAK,EAAsB,EAAE,KAAa,EAAE,MAAc;IAClF,IAAI,CAAC;QACJ,OAAO,YAAY,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,CAAA;IACvC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAA;IACb,CAAC;AACF,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../lib/sqlite/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AAEvD,OAAO,EAAE,SAAS,IAAI,YAAY,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAA;AASxF;;GAEG;AACH,MAAM,UAAU,UAAU,CACzB,EAAsB,EACtB,GAAW;IAEX,MAAM,SAAS,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAEjC,OAAO,CAAC,GAAG,UAAU,EAAE,EAAE,CAAC,MAAM,CAAM,SAAS,EAAE,GAAG,UAAU,CAAC,CAAA;AAChE,CAAC;AAOD;;GAEG;AACH,MAAM,UAAU,UAAU,CACzB,EAAsB,EACtB,GAAW;IAEX,MAAM,SAAS,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAEjC,OAAO,CAAC,GAAG,UAAU,EAAE,EAAE,CAAC,OAAO,CAAM,SAAS,EAAE,GAAG,UAAU,CAAC,CAAA;AACjE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAK,EAAsB,EAAE,IAAY;IAChE,IAAI,CAAC;QACJ,OAAO,WAAW,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;IAC7B,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAA;IACb,CAAC;AACF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CAAK,EAAsB,EAAE,KAAa,EAAE,MAAc;IAClF,IAAI,CAAC;QACJ,OAAO,YAAY,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,CAAA;IACvC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAA;IACb,CAAC;AACF,CAAC"}

package/out/street/centroid/schema.d.ts

@@ -3,49 +3,41 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Typed schema for the DERIVED STREET-CENTROID extract (`street-centroids-<cc>.db`, built by
- *   `ban/scripts/build-street-centroid-extract.ts` — the #1042 street-level tier behind "street-only
- *   FR queries deserve a street-level answer"). The extract is a `GROUP BY street` roll-up of the
- *   sealed rooftop address-point extract: one row per (street, postcode, commune) carrying the street's
- *   CENTROID + bounding-box EXTENT + member-point count. No new data source — a derived artifact.
- *
- *   Single source of truth for the columns shared by the BUILDER (a positional prepared INSERT for
- *   throughput) and the READER ({@link StreetCentroidSqliteLookup}), so a column rename in one is a
- *   compile error in the other — the same discipline as `address-point-schema.ts`.
- *
- *   Probe scopes (most-selective first): by `postcode`, else by `locality_base` (the
- *   arrondissement-stripped commune — see `stripArrondissement`; BAN names Paris/Lyon/Marseille rows
- *   per arrondissement, but a query names the base commune). The reader WEIGHTED-aggregates across the
- *   matched rows (by `point_count`) so a locality-scope probe returns the street's grand centroid over
- *   every postcode/arrondissement it spans.
+ *   Schema for the street-centroid extract. It groups address-point rows by street.
  */
 import type { Kysely } from "kysely";
 import type { NameKey, StreetKey } from "#street/normalize";
 /**
- * One street roll-up. `(street_norm, postcode, locality_base)` is unique. `lat`/`lon` are the UNWEIGHTED mean of the
- * group's member address points (each source row = one point), so a cross-group weighted mean (`SUM(lat*point_count) /
- * SUM(point_count)`) reconstructs the grand centroid. `min_/max_lat/lon` are the group's extent (the reader turns the
- * bbox diagonal into an honest `uncertainty_m`).
+ * One row per street, postcode and commune.
+ *
+ * The tuple `(street_norm, postcode, locality_base)` is unique.
+ * The reader combines rows by `SUM(lat * point_count) / SUM(point_count)` to get a
+ * street's centroid across every postcode and arrondissement it spans.
+ *
+ * It converts the bounding-box diagonal from the `min_*` and `max_*` columns into `uncertainty_m`.
  */
 export interface StreetCentroidTable {
     /**
-     * Shared `normalizeStreetForKeyLocale` of the street — the build/query-consistent probe key.
+     * The street key from `normalizeStreetForKeyLocale`, which both the builder and the reader use.
      */
     street_norm: StreetKey;
     /**
-     * The 5-digit postcode of this group, or null when the source row carried none.
+     * The postcode of this group, or null when the source row has none.
      */
     postcode: string | null;
     /**
-     * Arrondissement-stripped commune (`stripArrondissement(normalizeLocalityForKey(commune))`) — the fallback scope.
+     * The commune key with any arrondissement removed.
+     *
+     * BAN stores Paris, Lyon and Marseille per arrondissement, but a query usually gives the base commune.
+     * The reader uses this column when the query has no postcode.
      */
     locality_base: NameKey;
     /**
-     * Weighted-mean centroid latitude of the street's member points.
+     * The mean latitude of the group's member address points.
      */
     lat: number;
     /**
-     * Weighted-mean centroid longitude of the street's member points.
+     * The mean longitude of the group's member address points.
      */
     lon: number;
     min_lat: number;
@@ -53,31 +45,32 @@ export interface StreetCentroidTable {
     min_lon: number;
     max_lon: number;
     /**
-     * Member address-point count — the weight for a cross-group centroid aggregate.
+     * The number of member address points.
+     * This value weights the cross-row centroid.
      */
     point_count: number;
     /**
-     * A representative street name as it appeared in the source (display / debugging).
+     * One street name as it appeared in the source, kept for display and debugging.
      */
     street_raw: string;
     /**
-     * Provenance: the register this street was derived from (e.g. `ban:fr`).
+     * The source register, such as `ban:fr`.
      */
     source: string;
     /**
-     * The pinned data release the underlying points came from.
+     * The data release that the member points came from.
      */
     release: string;
     /**
-     * #727 phase-4c: `foldStreetSurface(street_raw)` — the contract-fold street-NAME existence key for
-     * {@link StreetLocalityEvidence}. Distinct from `street_norm` (the `street-normalize` geocoding key): the
-     * name-evidence rerank folds the model's street surface with the SAME `foldStreetSurface` used to build this column
-     * (the fold-parity contract), so it must not drift from `street_norm`'s richer normalizer. Indexed (`idx_sc_name`)
-     * for a direct seek.
+     * The value of `foldStreetSurface(street_raw)`, used by {@link StreetLocalityEvidence}
+     * to check that a street name exists.
+     *
+     * The name-evidence rerank folds the model's street text with the same function, so this
+     * column must use `foldStreetSurface` and must not follow the `street_norm` normalizer.
+     * The type is a plain string because `foldStreetSurface` differs from the
+     * {@link NameKey} fold that other `name_key` columns use.
      *
-     * Deliberately UNBRANDED despite the `name_key` column name: `foldStreetSurface` is a different fold from the
-     * {@link NameKey} one every other `name_key` column carries, and giving it that brand would invite exactly the
-     * cross-fold probe the brands exist to stop.
+     * A `NameKey` type would allow a probe with the wrong fold.
      */
     name_key: string;
 }
@@ -88,18 +81,20 @@ export interface StreetCentroidDatabase {
     street_centroid: StreetCentroidTable;
 }
 /**
- * The `street_centroid` 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 `street_centroid` columns in insert order.
+ *
+ * The builder derives the placeholders of its positional insert from this list.
  */
 export declare const STREET_CENTROID_COLUMNS: readonly ["street_norm", "postcode", "locality_base", "lat", "lon", "min_lat", "max_lat", "min_lon", "max_lon", "point_count", "street_raw", "source", "release", "name_key"];
 /**
- * Create the `street_centroid` table — called before the streaming bulk load.
+ * Creates the `street_centroid` table before the bulk load.
  */
 export declare function createStreetCentroidTable(db: Kysely<StreetCentroidDatabase>): Promise<void>;
 /**
- * Create the probe indexes: the two geocoding-scope indexes (postcode, locality-base) the resolver reader relies on,
- * plus `idx_sc_name` — the #727 phase-4c name-existence key for a direct `name_key = ?` seek (the unscoped fragment
- * lookup; without it that query skip-scans `idx_sc_postcode` at ~5 ms/probe).
+ * Creates the postcode and locality indexes that the reader probes, plus `idx_sc_name`.
+ *
+ * The `idx_sc_name` index serves the unscoped `name_key = ?` lookup.
+ * Without it, SQLite would skip-scan `idx_sc_postcode`.
  */
 export declare function createStreetCentroidIndexes(db: Kysely<StreetCentroidDatabase>): Promise<void>;
 //# sourceMappingURL=schema.d.ts.map

package/out/street/centroid/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../lib/street/centroid/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEpC,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAE3D;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IACnC;;OAEG;IACH,WAAW,EAAE,SAAS,CAAA;IACtB;;OAEG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB;;OAEG;IACH,aAAa,EAAE,OAAO,CAAA;IACtB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;;;;;OAUG;IACH,QAAQ,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,eAAe,EAAE,mBAAmB,CAAA;CACpC;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB,YACnC,aAAa,EACb,UAAU,EACV,eAAe,EACf,KAAK,EACL,KAAK,EACL,SAAS,EACT,SAAS,EACT,SAAS,EACT,SAAS,EACT,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,UAAU,CACD,CAAA;AAEV;;GAEG;AACH,wBAAsB,yBAAyB,CAAC,EAAE,EAAE,MAAM,CAAC,sBAAsB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBjG;AAED;;;;GAIG;AACH,wBAAsB,2BAA2B,CAAC,EAAE,EAAE,MAAM,CAAC,sBAAsB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAUnG"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../lib/street/centroid/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEpC,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAE3D;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IACnC;;OAEG;IACH,WAAW,EAAE,SAAS,CAAA;IACtB;;OAEG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB;;;;;OAKG;IACH,aAAa,EAAE,OAAO,CAAA;IACtB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;;;;;OAUG;IACH,QAAQ,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,eAAe,EAAE,mBAAmB,CAAA;CACpC;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,YACnC,aAAa,EACb,UAAU,EACV,eAAe,EACf,KAAK,EACL,KAAK,EACL,SAAS,EACT,SAAS,EACT,SAAS,EACT,SAAS,EACT,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,UAAU,CACD,CAAA;AAEV;;GAEG;AACH,wBAAsB,yBAAyB,CAAC,EAAE,EAAE,MAAM,CAAC,sBAAsB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBjG;AAED;;;;;GAKG;AACH,wBAAsB,2BAA2B,CAAC,EAAE,EAAE,MAAM,CAAC,sBAAsB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAUnG"}

package/out/street/centroid/schema.js

@@ -3,25 +3,12 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Typed schema for the DERIVED STREET-CENTROID extract (`street-centroids-<cc>.db`, built by
- *   `ban/scripts/build-street-centroid-extract.ts` — the #1042 street-level tier behind "street-only
- *   FR queries deserve a street-level answer"). The extract is a `GROUP BY street` roll-up of the
- *   sealed rooftop address-point extract: one row per (street, postcode, commune) carrying the street's
- *   CENTROID + bounding-box EXTENT + member-point count. No new data source — a derived artifact.
- *
- *   Single source of truth for the columns shared by the BUILDER (a positional prepared INSERT for
- *   throughput) and the READER ({@link StreetCentroidSqliteLookup}), so a column rename in one is a
- *   compile error in the other — the same discipline as `address-point-schema.ts`.
- *
- *   Probe scopes (most-selective first): by `postcode`, else by `locality_base` (the
- *   arrondissement-stripped commune — see `stripArrondissement`; BAN names Paris/Lyon/Marseille rows
- *   per arrondissement, but a query names the base commune). The reader WEIGHTED-aggregates across the
- *   matched rows (by `point_count`) so a locality-scope probe returns the street's grand centroid over
- *   every postcode/arrondissement it spans.
+ *   Schema for the street-centroid extract. It groups address-point rows by street.
  */
 /**
- * The `street_centroid` 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 `street_centroid` columns in insert order.
+ *
+ * The builder derives the placeholders of its positional insert from this list.
  */
 export const STREET_CENTROID_COLUMNS = [
     "street_norm",
@@ -40,7 +27,7 @@ export const STREET_CENTROID_COLUMNS = [
     "name_key",
 ];
 /**
- * Create the `street_centroid` table — called before the streaming bulk load.
+ * Creates the `street_centroid` table before the bulk load.
  */
 export async function createStreetCentroidTable(db) {
     await db.schema
@@ -62,9 +49,10 @@ export async function createStreetCentroidTable(db) {
         .execute();
 }
 /**
- * Create the probe indexes: the two geocoding-scope indexes (postcode, locality-base) the resolver reader relies on,
- * plus `idx_sc_name` — the #727 phase-4c name-existence key for a direct `name_key = ?` seek (the unscoped fragment
- * lookup; without it that query skip-scans `idx_sc_postcode` at ~5 ms/probe).
+ * Creates the postcode and locality indexes that the reader probes, plus `idx_sc_name`.
+ *
+ * The `idx_sc_name` index serves the unscoped `name_key = ?` lookup.
+ * Without it, SQLite would skip-scan `idx_sc_postcode`.
  */
 export async function createStreetCentroidIndexes(db) {
     await db.schema.createIndex("idx_sc_postcode").on("street_centroid").columns(["postcode", "street_norm"]).execute();

package/out/street/centroid/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../lib/street/centroid/schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../lib/street/centroid/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAiFH;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACtC,aAAa;IACb,UAAU;IACV,eAAe;IACf,KAAK;IACL,KAAK;IACL,SAAS;IACT,SAAS;IACT,SAAS;IACT,SAAS;IACT,aAAa;IACb,YAAY;IACZ,QAAQ;IACR,SAAS;IACT,UAAU;CACD,CAAA;AAEV;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,EAAkC;IACjF,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,iBAAiB,CAAC;SAC9B,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACpD,SAAS,CAAC,UAAU,EAAE,MAAM,CAAC;SAC7B,SAAS,CAAC,eAAe,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACtD,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,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAChD,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAChD,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAChD,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAChD,SAAS,CAAC,aAAa,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACvD,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,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAChD,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACjD,OAAO,EAAE,CAAA;AACZ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,EAAkC;IACnF,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC,EAAE,CAAC,iBAAiB,CAAC,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC,CAAC,OAAO,EAAE,CAAA;IAEnH,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,iBAAiB,CAAC;SAC9B,EAAE,CAAC,iBAAiB,CAAC;SACrB,OAAO,CAAC,CAAC,eAAe,EAAE,aAAa,CAAC,CAAC;SACzC,OAAO,EAAE,CAAA;IAEX,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,iBAAiB,CAAC,CAAC,OAAO,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,EAAE,CAAA;AACjG,CAAC"}

package/out/street/centroid.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file SQLite implementation of core's `StreetCentroidLookup`.
+ */
+import type { StreetCentroidHit, StreetCentroidLookup } from "@mailwoman/core/resolver";
+import type { PathBuilderLike } from "path-ts";
+import { type StreetLocale } from "#street/normalize";
+/**
+ * Finds a street's centroid and extent-based uncertainty by street name,
+ * scoped by postcode and then by base commune.
+ */
+export declare class StreetCentroidSqliteLookup implements StreetCentroidLookup {
+    #private;
+    /**
+     * The extract defaults to the `fr` street-normalization locale.
+     * A mismatch with the extract's locale makes every key miss.
+     */
+    constructor(dbPath: PathBuilderLike, opts?: {
+        streetLocale?: StreetLocale;
+    });
+    find(query: {
+        street: string;
+        postcode?: string;
+        locality?: string;
+    }): StreetCentroidHit | null;
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=centroid.d.ts.map

package/out/street/centroid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"centroid.d.ts","sourceRoot":"","sources":["../../lib/street/centroid.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAA;AAGvF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAI9C,OAAO,EAMN,KAAK,YAAY,EAEjB,MAAM,mBAAmB,CAAA;AAkC1B;;;GAGG;AACH,qBAAa,0BAA2B,YAAW,oBAAoB;;IAMtE;;;OAGG;IACH,YAAY,MAAM,EAAE,eAAe,EAAE,IAAI,GAAE;QAAE,YAAY,CAAC,EAAE,YAAY,CAAA;KAAO,EAgB9E;IAED,IAAI,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,iBAAiB,GAAG,IAAI,CA0B9F;IAED,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAEvB;CACD"}

package/out/street/{centroid/index.js → centroid.js}

@@ -2,54 +2,43 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   SQLite implementation of core's `StreetCentroidLookup` (#1042): the street-level tier BELOW the
- *   exact address-point tier and ABOVE admin-centroid resolution. Given a street name (no house
- *   number) plus a postcode/commune scope, it returns the street's CENTROID + an honest extent-derived
- *   uncertainty from the derived `street-centroids-<cc>.db` roll-up.
- *
- *   Query-side normalization is THE shared normalizer (`street-normalize.ts`), selected per the extract's
- *   `streetLocale`, so build-side and probe-side keys agree by construction. The commune scope folds
- *   through `normalizeLocalityForKey` + `stripArrondissement` (BAN names Paris/Lyon/Marseille per
- *   arrondissement; a query names the base commune).
- *
- *   Scope order is most-selective first: `postcode`, then the base commune. Each scope WEIGHTED-
- *   aggregates (by `point_count`) across the matched rows in SQL, so a commune-scope probe returns the
- *   street's grand centroid over every postcode/arrondissement it spans — one row, one hit. Matching is
- *   exact-after-normalization only (no fuzzy street matching in this tier).
+ * @file SQLite implementation of core's `StreetCentroidLookup`.
  */
 import { haversineKm } from "@mailwoman/spatial";
 import { DatabaseClient } from "@mailwoman/sqlite/client";
 import { hasTable, prepareGet } from "#sqlite-utils";
 import { normalizeLocalityForKey, normalizeStreetForKeyLocale, streetLocaleForSurface, stripArrondissement, } from "#street/normalize";
 /**
- * Weighted-centroid aggregate over a WHERE-filtered set. `SUM(coord*n)/SUM(n)` reconstructs the grand centroid.
+ * The aggregate columns that weight each row's centroid by `point_count` to
+ * reconstruct the combined centroid.
  */
 const AGG_SELECT = "SUM(lat * point_count) / SUM(point_count) AS lat, " +
     "SUM(lon * point_count) / SUM(point_count) AS lon, " +
     "MIN(min_lat) AS min_lat, MAX(max_lat) AS max_lat, MIN(min_lon) AS min_lon, MAX(max_lon) AS max_lon, " +
     "MAX(source) AS source, MAX(release) AS release";
 /**
- * Half the bbox diagonal, in METERS — an honest coarse radius for a street centroid.
+ * Half the bounding-box diagonal in meters, used as a coarse uncertainty radius for a street centroid.
  */
 function extentRadiusM(minLat, maxLat, minLon, maxLon) {
     return Math.round(haversineKm(minLat, minLon, maxLat, maxLon) * 500);
 }
+/**
+ * Finds a street's centroid and extent-based uncertainty by street name,
+ * scoped by postcode and then by base commune.
+ */
 export class StreetCentroidSqliteLookup {
     #db;
     #locale;
     #byPostcode;
     #byLocality;
     /**
-     * @param dbPath Extract path.
-     * @param opts.streetLocale The street-normalization locale this extract was BUILT with — must match, or every key
-     *   misses. Defaults to `"fr"` (BAN is the French national register; the tier is FR-only today).
+     * The extract defaults to the `fr` street-normalization locale.
+     * A mismatch with the extract's locale makes every key miss.
      */
     constructor(dbPath, opts = {}) {
         this.#db = new DatabaseClient(dbPath, { readOnly: true });
         this.#locale = opts.streetLocale ?? "fr";
-        // Degrade gracefully on an empty/tableless extract (interrupted build, stray 0-byte file): with no
-        // `street_centroid` table this lookup is a no-op miss, not a crash (mirrors the address-point reader).
+        // An extract without a `street_centroid` table makes every lookup miss.
         if (hasTable(this.#db, "street_centroid")) {
             this.#byPostcode = prepareGet(this.#db, `SELECT ${AGG_SELECT} FROM street_centroid WHERE postcode = ? AND street_norm = ?`);
             this.#byLocality = prepareGet(this.#db, `SELECT ${AGG_SELECT} FROM street_centroid WHERE locality_base = ? AND street_norm = ?`);
@@ -61,7 +50,7 @@ export class StreetCentroidSqliteLookup {
         const streetNorm = normalizeStreetForKeyLocale(query.street, streetLocaleForSurface(query.street, this.#locale));
         if (!streetNorm)
             return null;
-        let row;
+        let row = null;
         if (query.postcode?.trim()) {
             row = this.#byPostcode(query.postcode.trim(), streetNorm);
         }
@@ -83,4 +72,4 @@ export class StreetCentroidSqliteLookup {
         this.#db[Symbol.dispose]();
     }
 }
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=centroid.js.map

package/out/street/centroid.js.map

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

package/out/street/morphology/fst/builder.d.ts

@@ -5,13 +5,14 @@
  *
  *   Build a street-morphology FST from libpostal's street_types dictionaries. The morphology FST maps
  *   street-typing affixes (Street/Avenue/rue/Calle/Straße/...) to a single synthetic placetype
- *   `"street_affix"` — distinct from the admin FST in source data, intent, and binary artifact.
+ *   `"street_affix"`. Its source data and purpose differ from the admin FST.
+ *   It also produces a separate binary artifact.
  *
  *   The morphology FST closes the inference-time vacuum identified by the v0.6.1 postmortem: street
  *   tokens have no admin-FST anchor, so synth-street training pushed the model toward over-emitting
  *   `dependent_locality` on subcomponents. With the morphology FST, the neural decoder gets
  *   positive evidence for street-typing affixes and the adjacent name tokens, plus negative
- *   evidence away from `dependent_locality` on the same neighbours.
+ *   evidence away from `dependent_locality` on the same neighbors.
  *
  *   Design rationale + the four-layer street-supplement architecture lives in
  *   `docs/articles/concepts/street-supplement-architecture.md`.
@@ -22,25 +23,34 @@
  *   Output: an `FSTMatcher` ready to serialize via `serializeFST` to e.g.
  *   `fst-street-morphology.bin`.
  */
+import { type PathBuilderLike } from "path-ts";
 import { FSTMatcher } from "#fst/matcher";
 import type { FSTProvenance } from "#fst/types";
 export interface BuildStreetMorphologyFSTOpts {
     /**
      * Path to the `core/data/libpostal/dictionaries` directory containing per-locale subfolders.
      */
-    dictionariesDir: string;
+    dictionariesDir: PathBuilderLike;
     /**
-     * Optional locale filter — only ingest these locale subfolders. Defaults to all that have a `street_types.txt`.
+     * Optional locale filter — only ingest these locale subfolders.
+     *
+     * @defaultValue all that have a `street_types.txt`.
      */
     locales?: string[];
     /**
-     * Minimum length (in characters, post-normalization) of variant surface forms to insert into the trie. Defaults to 3.
+     * Minimum length (in characters, post-normalization) of variant surface forms to insert into the trie.
+     *
+     * Rationale: libpostal's street_types dictionaries contain 1-2 character abbreviations
+     * (`a`, `b`, `av`, `bd`, `br`, ...) that collide with non-affix tokens at parse time,
+     * including US state abbreviations (`or`, `CA`, `ND`, `NY`).
+     * Single-letter unit designators and other short tokens also collide.
+     *
+     * Empirically these collisions push the morphology prior to mis-tag state
+     * abbreviations as `street_suffix`.
+     *
+     * A minimum length of 3 retains useful forms (`ave`, `blvd`, `rue`, `str`) while filtering out the noise.
      *
-     * Rationale: libpostal's street_types dictionaries contain 1-2 character abbreviations (`a`, `b`, `av`, `bd`, `br`,
-     * ...) that collide with non-affix tokens at parse time — notably US state abbreviations (`OR`, `CA`, `ND`, `NY`),
-     * single-letter unit designators, and arbitrary short tokens. Empirically these collisions push the morphology prior
-     * to mis-tag state abbreviations as `street_suffix`. A minimum length of 3 retains useful forms (`ave`, `blvd`,
-     * `rue`, `str`) while filtering out the noise.
+     * @defaultValue `3`
      */
     minVariantLength?: number;
     /**