@mailwoman/resolver-wof-sqlite 9.4.0 → 10.1.0

package/out/polygon-schema.js

@@ -4,10 +4,10 @@
  * @author Teffen Ellis, et al.
  *
  *   Typed schema for the polygon sidecar (`wof-polygons.db`) — the one table `WOFReverseGeocoder` probes for a
- *   place's geometry. The interface is the read/write contract and {@link createPolygonsTable} creates the table, so a
+ *   place's geometry. The interface is the read/write interface and {@link createPolygonsTable} creates the table, so a
  *   column added to one is a compile error against the other.
  *
- *   The sidecar is OPTIONAL to the reverse geocoder: without it every result falls back to a centroid, so the reader
+ *   The sidecar is optional to the reverse geocoder: without it every result falls back to a centroid, so the reader
  *   checks for the table's presence rather than assuming it.
  */
 /**

package/out/polygon-schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"polygon-schema.js","sourceRoot":"","sources":["../lib/polygon-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA0BH;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,EAAuB;IAChE,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,UAAU,CAAC;SACvB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;SAC3D,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;SACvD,OAAO,EAAE,CAAA;AACZ,CAAC"}
+{"version":3,"file":"polygon-schema.js","sourceRoot":"","sources":["../lib/polygon-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA8BH;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,EAAuB;IAChE,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,UAAU,CAAC;SACvB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;SAC3D,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;SACvD,OAAO,EAAE,CAAA;AACZ,CAAC"}

package/out/postal/{city-alias-lookup.d.ts → city/alias/lookup.d.ts}

@@ -3,30 +3,25 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Node reader over the POSTAL-CITY ALIAS table (`postal-city-alias-<cc>.db`) — the observed
+ *   Node reader over the postal-city alias table (`postal-city-alias-<cc>.db`) — the observed
  *   `postal_city → geo_locality` aliases per postcode (`build-postal-city-alias.ts`). Consumed by
  *   {@link WOFSQLitePlaceLookup}'s coordinate-first locality scorer: a user-typed postal city
  *   ("Antioch", postcode 37013) becomes a name-match alias for the geographic locality the postcode
- *   actually sits in ("Nashville"), so the right place tiers to the top instead of a same-named
- *   town in another state. Opt-in — the lookup is only constructed when a path is supplied, and
+ *   actually sits in ("Nashville"), so the right place tiers to the top instead of a place with the same name
+ *   town in another state. Opt-in — the lookup is only constructed when a path is supplied.
  *   absent it the resolver is byte-identical.
  *
- *   The reader returns RAW divergent rows for a postcode; normalization + name-matching against the
+ *   The reader returns RAW divergent rows for a postcode. normalization + name-matching against the
  *   candidate localities is the scorer's job (it owns the case/diacritic fold the soft name score
  *   uses), keeping one normalizer in one place.
  */
-import { DatabaseClient } from "@mailwoman/sqlite/client";
-import type { PostalCityAliasDatabase } from "#postal/city-alias-schema";
-export interface WOFPostalCityAliasLookupOpts {
-    /**
-     * Path to a `postal-city-alias-<cc>.db` built by `build-postal-city-alias.ts`. Opened read-only.
-     */
-    databasePath?: string;
-    /**
-     * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
-     */
-    database?: DatabaseClient<PostalCityAliasDatabase>;
-}
+import { SQLiteLookup, type SQLiteLookupOptions } from "@mailwoman/sqlite/lookup";
+import type { PostalCityAliasDatabase } from "#postal/city/alias/schema";
+/**
+ * Where a {@link WOFPostalCityAliasLookup} reads from: a `postal-city-alias-<cc>.db` built by
+ * `build-postal-city-alias.ts`, opened read-only, or a connection the caller already holds.
+ */
+export type WOFPostalCityAliasLookupOpts = SQLiteLookupOptions<PostalCityAliasDatabase>;
 /**
  * One divergent alias edge: the postal-system name and the geographic locality it maps to.
  */
@@ -45,18 +40,20 @@ export interface PostalCityAlias {
     n: number;
 }
 /**
- * Reader over `postal_city_alias`. The only query is a postcode-scoped probe for DIVERGENT rows (where the postal name
- * differs from the geographic name — the rows that carry alias signal), issued via the typed Kysely query builder
- * against {@link PostalCityAliasDatabase}.
+ * Reader over `postal_city_alias`.
+ *
+ * The only query is a postcode-scoped probe for divergent rows
+ * (where the postal name differs from the geographic name — the rows that provide alias signal),
+ * issued via the typed Kysely query builder against {@link PostalCityAliasDatabase}.
  */
-export declare class WOFPostalCityAliasLookup implements Disposable {
-    #private;
+export declare class WOFPostalCityAliasLookup extends SQLiteLookup<PostalCityAliasDatabase> {
     constructor(opts: WOFPostalCityAliasLookupOpts);
     /**
-     * Divergent postal-city aliases for a postcode (empty when the postcode isn't in the table). The scorer groups these
-     * by normalized `geoLocality` and appends the `postalCity` surfaces to the matching candidate locality's alias set.
+     * Divergent postal-city aliases for a postcode (empty when the postcode isn't in the table).
+     *
+     * The scorer groups these by normalized `geoLocality` and appends the `postalCity`
+     * surfaces to the matching candidate locality's alias set.
      */
     getDivergentAliases(postcode: string): Promise<PostalCityAlias[]>;
-    [Symbol.dispose](): void;
 }
-//# sourceMappingURL=city-alias-lookup.d.ts.map
+//# sourceMappingURL=lookup.d.ts.map

package/out/postal/city/alias/lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../../../../lib/postal/city/alias/lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAEjF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAA;AAExE;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG,mBAAmB,CAAC,uBAAuB,CAAC,CAAA;AAEvF;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,CAAC,EAAE,MAAM,CAAA;CACT;AAED;;;;;;GAMG;AACH,qBAAa,wBAAyB,SAAQ,YAAY,CAAC,uBAAuB,CAAC;IAClF,YAAY,IAAI,EAAE,4BAA4B,EAE7C;IAED;;;;;OAKG;IACG,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAatE;CACD"}

package/out/postal/city/alias/lookup.js

@@ -0,0 +1,49 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Node reader over the postal-city alias table (`postal-city-alias-<cc>.db`) — the observed
+ *   `postal_city → geo_locality` aliases per postcode (`build-postal-city-alias.ts`). Consumed by
+ *   {@link WOFSQLitePlaceLookup}'s coordinate-first locality scorer: a user-typed postal city
+ *   ("Antioch", postcode 37013) becomes a name-match alias for the geographic locality the postcode
+ *   actually sits in ("Nashville"), so the right place tiers to the top instead of a place with the same name
+ *   town in another state. Opt-in — the lookup is only constructed when a path is supplied.
+ *   absent it the resolver is byte-identical.
+ *
+ *   The reader returns RAW divergent rows for a postcode. normalization + name-matching against the
+ *   candidate localities is the scorer's job (it owns the case/diacritic fold the soft name score
+ *   uses), keeping one normalizer in one place.
+ */
+import { SQLiteLookup } from "@mailwoman/sqlite/lookup";
+/**
+ * Reader over `postal_city_alias`.
+ *
+ * The only query is a postcode-scoped probe for divergent rows
+ * (where the postal name differs from the geographic name — the rows that provide alias signal),
+ * issued via the typed Kysely query builder against {@link PostalCityAliasDatabase}.
+ */
+export class WOFPostalCityAliasLookup extends SQLiteLookup {
+    constructor(opts) {
+        super(opts);
+    }
+    /**
+     * Divergent postal-city aliases for a postcode (empty when the postcode isn't in the table).
+     *
+     * The scorer groups these by normalized `geoLocality` and appends the `postalCity`
+     * surfaces to the matching candidate locality's alias set.
+     */
+    async getDivergentAliases(postcode) {
+        const pc = postcode.trim();
+        if (!pc)
+            return [];
+        const rows = await this.database
+            .selectFrom("postal_city_alias")
+            .select(["postal_city", "geo_locality", "n"])
+            .where("postcode", "=", pc)
+            .where("divergent", "=", 1)
+            .execute();
+        return rows.map((r) => ({ postalCity: String(r.postal_city), geoLocality: String(r.geo_locality), n: Number(r.n) }));
+    }
+}
+//# sourceMappingURL=lookup.js.map

package/out/postal/city/alias/lookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.js","sourceRoot":"","sources":["../../../../lib/postal/city/alias/lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAA4B,MAAM,0BAA0B,CAAA;AA4BjF;;;;;;GAMG;AACH,MAAM,OAAO,wBAAyB,SAAQ,YAAqC;IAClF,YAAY,IAAkC;QAC7C,KAAK,CAAC,IAAI,CAAC,CAAA;IACZ,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,mBAAmB,CAAC,QAAgB;QACzC,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAA;QAE1B,IAAI,CAAC,EAAE;YAAE,OAAO,EAAE,CAAA;QAElB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ;aAC9B,UAAU,CAAC,mBAAmB,CAAC;aAC/B,MAAM,CAAC,CAAC,aAAa,EAAE,cAAc,EAAE,GAAG,CAAC,CAAC;aAC5C,KAAK,CAAC,UAAU,EAAE,GAAG,EAAE,EAAE,CAAC;aAC1B,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,CAAC;aAC1B,OAAO,EAAE,CAAA;QAEX,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACrH,CAAC;CACD"}

package/out/postal/{city-alias-schema.d.ts → city/alias/schema.d.ts}

@@ -3,22 +3,24 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Typed schema for the POSTAL-CITY ALIAS table (`postal-city-alias-<cc>.db`, built by
+ *   Typed schema for the postal-city alias table (`postal-city-alias-<cc>.db`, built by
  *   `scripts/build-postal-city-alias.ts`) — the single source of truth for the columns shared by
- *   the BUILDER and the READER ({@link WOFPostalCityAliasLookup}). Like {@link CandidateTable}, the
- *   contract is a Kysely `Database` interface plus the table DDL as a string, so a column rename in
+ *   the builder and the reader ({@link WOFPostalCityAliasLookup}). Like {@link CandidateTable}, the
+ *   interface is a Kysely `Database` interface plus the table DDL as a string, so a column rename in
  *   the builder is a compile error in the reader.
  *
- *   Provenance discipline (provenance-first): this is a SIBLING table to the PIP-derived
+ *   Provenance discipline (provenance-first): this is a sibling table to the PIP-derived
  *   `postcode_locality` data, never mixed into it — one table, one provenance class. Each row is an
- *   OBSERVED `(postcode, postal_city, geo_locality)` aggregate from Overture's `postal_city` field
+ *   observed `(postcode, postal_city, geo_locality)` aggregate from Overture's `postal_city` field
  *   with a usage count `n`; `divergent = 1` exactly when `postal_city != geo_locality` (the alias
  *   signal — the only rows the resolver consumes).
  */
 import type { Kysely } from "kysely";
 /**
- * One observed postal-city aggregate. The natural key is `(postcode, postal_city, geo_locality)`; the builder enforces
- * a `MIN_COUNT` floor on `n`, so every row is a non-trivial usage.
+ * One observed postal-city aggregate.
+ *
+ * The natural key is `(postcode, postal_city, geo_locality)`; the builder enforces a
+ * `MIN_COUNT` floor on `n`, so every row is a non-trivial usage.
  */
 export interface PostalCityAliasTable {
     /**
@@ -57,12 +59,14 @@ export interface PostalCityAliasDatabase {
     postal_city_alias: PostalCityAliasTable;
 }
 /**
- * The `postal_city_alias` column order — the builder's INSERT derives its column list from this.
+ * The `postal_city_alias` column order — the builder's insert derives its column list from this.
  */
 export declare const POSTAL_CITY_ALIAS_COLUMNS: readonly ["postcode", "postal_city", "geo_locality", "n", "divergent", "source", "release"];
 /**
- * Create the `postal_city_alias` table + its two probe indexes. Kept here (not only in the builder) so tests can stand
- * up a fixture DB with the exact production shape. Pass a {@link DatabaseClient} (or any `Kysely`) over the alias DB.
+ * Create the `postal_city_alias` table + its two probe indexes.
+ *
+ * Kept here (not only in the builder) so tests can stand up a fixture DB with the exact production shape.
+ * Pass a {@link DatabaseClient} (or any `Kysely`) over the alias DB.
  */
 export declare function createPostalCityAliasTable(db: Kysely<PostalCityAliasDatabase>): Promise<void>;
-//# sourceMappingURL=city-alias-schema.d.ts.map
+//# sourceMappingURL=schema.d.ts.map

package/out/postal/city/alias/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../lib/postal/city/alias/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEpC;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACpC;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB;;OAEG;IACH,CAAC,EAAE,MAAM,CAAA;IACT;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,iBAAiB,EAAE,oBAAoB,CAAA;CACvC;AAED;;GAEG;AACH,eAAO,MAAM,yBAAyB,YACrC,UAAU,EACV,aAAa,EACb,cAAc,EACd,GAAG,EACH,WAAW,EACX,QAAQ,EACR,SAAS,CACA,CAAA;AAEV;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAAC,EAAE,EAAE,MAAM,CAAC,uBAAuB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAcnG"}

package/out/postal/{city-alias-schema.js → city/alias/schema.js}

@@ -3,20 +3,20 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Typed schema for the POSTAL-CITY ALIAS table (`postal-city-alias-<cc>.db`, built by
+ *   Typed schema for the postal-city alias table (`postal-city-alias-<cc>.db`, built by
  *   `scripts/build-postal-city-alias.ts`) — the single source of truth for the columns shared by
- *   the BUILDER and the READER ({@link WOFPostalCityAliasLookup}). Like {@link CandidateTable}, the
- *   contract is a Kysely `Database` interface plus the table DDL as a string, so a column rename in
+ *   the builder and the reader ({@link WOFPostalCityAliasLookup}). Like {@link CandidateTable}, the
+ *   interface is a Kysely `Database` interface plus the table DDL as a string, so a column rename in
  *   the builder is a compile error in the reader.
  *
- *   Provenance discipline (provenance-first): this is a SIBLING table to the PIP-derived
+ *   Provenance discipline (provenance-first): this is a sibling table to the PIP-derived
  *   `postcode_locality` data, never mixed into it — one table, one provenance class. Each row is an
- *   OBSERVED `(postcode, postal_city, geo_locality)` aggregate from Overture's `postal_city` field
+ *   observed `(postcode, postal_city, geo_locality)` aggregate from Overture's `postal_city` field
  *   with a usage count `n`; `divergent = 1` exactly when `postal_city != geo_locality` (the alias
  *   signal — the only rows the resolver consumes).
  */
 /**
- * The `postal_city_alias` column order — the builder's INSERT derives its column list from this.
+ * The `postal_city_alias` column order — the builder's insert derives its column list from this.
  */
 export const POSTAL_CITY_ALIAS_COLUMNS = [
     "postcode",
@@ -28,8 +28,10 @@ export const POSTAL_CITY_ALIAS_COLUMNS = [
     "release",
 ];
 /**
- * Create the `postal_city_alias` table + its two probe indexes. Kept here (not only in the builder) so tests can stand
- * up a fixture DB with the exact production shape. Pass a {@link DatabaseClient} (or any `Kysely`) over the alias DB.
+ * Create the `postal_city_alias` table + its two probe indexes.
+ *
+ * Kept here (not only in the builder) so tests can stand up a fixture DB with the exact production shape.
+ * Pass a {@link DatabaseClient} (or any `Kysely`) over the alias DB.
  */
 export async function createPostalCityAliasTable(db) {
     await db.schema
@@ -45,4 +47,4 @@ export async function createPostalCityAliasTable(db) {
     await db.schema.createIndex("idx_pca_postcode").on("postal_city_alias").column("postcode").execute();
     await db.schema.createIndex("idx_pca_pair").on("postal_city_alias").columns(["postal_city", "geo_locality"]).execute();
 }
-//# sourceMappingURL=city-alias-schema.js.map
+//# sourceMappingURL=schema.js.map

package/out/postal/city/alias/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../../lib/postal/city/alias/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAgDH;;GAEG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACxC,UAAU;IACV,aAAa;IACb,cAAc;IACd,GAAG;IACH,WAAW;IACX,QAAQ;IACR,SAAS;CACA,CAAA;AAEV;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,EAAmC;IACnF,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,mBAAmB,CAAC;SAChC,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACjD,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACpD,SAAS,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACrD,SAAS,CAAC,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC7C,SAAS,CAAC,WAAW,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACrD,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,OAAO,EAAE,CAAA;IAEX,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC,EAAE,CAAC,mBAAmB,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE,CAAA;IACpG,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,mBAAmB,CAAC,CAAC,OAAO,CAAC,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC,CAAC,OAAO,EAAE,CAAA;AACvH,CAAC"}

package/out/postal/city/candidate-schema.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for the postal-city candidate side-index, a small `(name_key, postcode)` →
+ *   geo-locality table alongside the byte-range `candidate` table.
+ *   The candidate-backend resolver (the demo and CLI default) can then match the FTS coordinate-first scorer.
+ *   It resolves a user-typed postal city ("Antioch", 37013) to the geographic locality the postcode
+ *   resolve a user-typed postal city ("Antioch", 37013) to the geographic locality the postcode
+ *   sits in ("Nashville").
+ *
+ *   The `candidate` B-tree is keyed `(name_key, country_id, region_id, placetype_id, …)` and ranked
+ *   population-first, so it has no postcode dimension. A cloned alias row cannot satisfy both
+ *   purposes, because a sentinel rank is bare-name-safe and then loses to any in-region homonym.
+ *   The exact `(name_key, postcode)` probe bypasses population and region ranking entirely.
+ *   It runs only when the query includes a postcode, leaving the common no-postcode path untouched.
+ */
+import { type Kysely } from "kysely";
+import type { NameKey } from "#street/normalize";
+/**
+ * One postal-city → geo-locality edge, keyed exactly by `(name_key, postcode)`.
+ *
+ * The probe returns the geographic locality directly.
+ * The denormalized name/coord avoid a join back to `candidate`.
+ */
+export interface PostalCityCandidateTable {
+    /**
+     * {@link normalizeLocalityForKey} of the postal-city name, the build/query-consistent probe key.
+     */
+    name_key: NameKey;
+    /**
+     * The postcode the alias is scoped to (the second half of the exact key).
+     */
+    postcode: string;
+    /**
+     * WOF id of the geographic locality the postcode sits in (the resolve target).
+     */
+    spr_id: number;
+    /**
+     * The geographic locality's display name.
+     */
+    name: string;
+    latitude: number;
+    longitude: number;
+}
+/**
+ * The postal-city-candidate database schema for `new DatabaseClient<PostalCityCandidateDatabase>(...)`.
+ */
+export interface PostalCityCandidateDatabase {
+    postal_city_candidate: PostalCityCandidateTable;
+}
+/**
+ * The table name the lookup probes (existence-restricted, so an old candidate.db without it is byte-stable).
+ */
+export declare const POSTAL_CITY_CANDIDATE_TABLE = "postal_city_candidate";
+/**
+ * Column order for the builder's positional insert.
+ */
+export declare const POSTAL_CITY_CANDIDATE_COLUMNS: readonly ["name_key", "postcode", "spr_id", "name", "latitude", "longitude"];
+/**
+ * Create the side-index, a clustered `without rowid` B-tree on `(name_key, postcode)`
+ * so the resolve is a single exact probe.
+ *
+ * Idempotent (`if not exists`).
+ * Pass a {@link DatabaseClient} (or any `Kysely`) over the candidate DB.
+ *
+ * The Kysely schema-builder is the house idiom for table creation.
+ * See `agents.md` on inline SQL and Kysely.
+ */
+export declare function createPostalCityCandidateTable(db: Kysely<PostalCityCandidateDatabase>): Promise<void>;
+//# sourceMappingURL=candidate-schema.d.ts.map

package/out/postal/city/candidate-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate-schema.d.ts","sourceRoot":"","sources":["../../../lib/postal/city/candidate-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAO,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACxC;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAA;IACjB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC3C,qBAAqB,EAAE,wBAAwB,CAAA;CAC/C;AAED;;GAEG;AACH,eAAO,MAAM,2BAA2B,0BAA0B,CAAA;AAElE;;GAEG;AACH,eAAO,MAAM,6BAA6B,YACzC,UAAU,EACV,UAAU,EACV,QAAQ,EACR,MAAM,EACN,UAAU,EACV,WAAW,CACF,CAAA;AAEV;;;;;;;;;GASG;AACH,wBAAsB,8BAA8B,CAAC,EAAE,EAAE,MAAM,CAAC,2BAA2B,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAc3G"}

package/out/postal/city/candidate-schema.js

@@ -0,0 +1,60 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for the postal-city candidate side-index, a small `(name_key, postcode)` →
+ *   geo-locality table alongside the byte-range `candidate` table.
+ *   The candidate-backend resolver (the demo and CLI default) can then match the FTS coordinate-first scorer.
+ *   It resolves a user-typed postal city ("Antioch", 37013) to the geographic locality the postcode
+ *   resolve a user-typed postal city ("Antioch", 37013) to the geographic locality the postcode
+ *   sits in ("Nashville").
+ *
+ *   The `candidate` B-tree is keyed `(name_key, country_id, region_id, placetype_id, …)` and ranked
+ *   population-first, so it has no postcode dimension. A cloned alias row cannot satisfy both
+ *   purposes, because a sentinel rank is bare-name-safe and then loses to any in-region homonym.
+ *   The exact `(name_key, postcode)` probe bypasses population and region ranking entirely.
+ *   It runs only when the query includes a postcode, leaving the common no-postcode path untouched.
+ */
+import { sql } from "kysely";
+/**
+ * The table name the lookup probes (existence-restricted, so an old candidate.db without it is byte-stable).
+ */
+export const POSTAL_CITY_CANDIDATE_TABLE = "postal_city_candidate";
+/**
+ * Column order for the builder's positional insert.
+ */
+export const POSTAL_CITY_CANDIDATE_COLUMNS = [
+    "name_key",
+    "postcode",
+    "spr_id",
+    "name",
+    "latitude",
+    "longitude",
+];
+/**
+ * Create the side-index, a clustered `without rowid` B-tree on `(name_key, postcode)`
+ * so the resolve is a single exact probe.
+ *
+ * Idempotent (`if not exists`).
+ * Pass a {@link DatabaseClient} (or any `Kysely`) over the candidate DB.
+ *
+ * The Kysely schema-builder is the house idiom for table creation.
+ * See `agents.md` on inline SQL and Kysely.
+ */
+export async function createPostalCityCandidateTable(db) {
+    await db.schema
+        .createTable(POSTAL_CITY_CANDIDATE_TABLE)
+        .ifNotExists()
+        .addColumn("name_key", "text", (c) => c.notNull())
+        .addColumn("postcode", "text", (c) => c.notNull())
+        .addColumn("spr_id", "integer", (c) => c.notNull())
+        .addColumn("name", "text", (c) => c.notNull())
+        .addColumn("latitude", "real", (c) => c.notNull())
+        .addColumn("longitude", "real", (c) => c.notNull())
+        .addPrimaryKeyConstraint("postal_city_candidate_pk", ["name_key", "postcode"])
+        // `without rowid` has no first-class builder. The raw modifier is the idiomatic fallback.
+        .modifyEnd(sql `without rowid`)
+        .execute();
+}
+//# sourceMappingURL=candidate-schema.js.map

package/out/postal/city/candidate-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate-schema.js","sourceRoot":"","sources":["../../../lib/postal/city/candidate-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,GAAG,EAAe,MAAM,QAAQ,CAAA;AAsCzC;;GAEG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,uBAAuB,CAAA;AAElE;;GAEG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC5C,UAAU;IACV,UAAU;IACV,QAAQ;IACR,MAAM;IACN,UAAU;IACV,WAAW;CACF,CAAA;AAEV;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAAC,EAAuC;IAC3F,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,2BAA2B,CAAC;SACxC,WAAW,EAAE;SACb,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACjD,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACjD,SAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAClD,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC7C,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACjD,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAClD,uBAAuB,CAAC,0BAA0B,EAAE,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;QAC9E,0FAA0F;SACzF,SAAS,CAAC,GAAG,CAAA,eAAe,CAAC;SAC7B,OAAO,EAAE,CAAA;AACZ,CAAC"}

package/out/postal.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+export * from "#postal/city/alias/lookup";
+export * from "#postal/city/alias/schema";
+export * from "#postal/city/candidate-schema";
+//# sourceMappingURL=postal.d.ts.map

package/out/postal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postal.d.ts","sourceRoot":"","sources":["../lib/postal.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,2BAA2B,CAAA;AACzC,cAAc,2BAA2B,CAAA;AACzC,cAAc,+BAA+B,CAAA"}

package/out/postal.js

@@ -0,0 +1,9 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+export * from "#postal/city/alias/lookup";
+export * from "#postal/city/alias/schema";
+export * from "#postal/city/candidate-schema";
+//# sourceMappingURL=postal.js.map

package/out/postal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postal.js","sourceRoot":"","sources":["../lib/postal.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,2BAA2B,CAAA;AACzC,cAAc,2BAA2B,CAAA;AACzC,cAAc,+BAA+B,CAAA"}

package/out/postcode-point-lookup.d.ts

@@ -2,38 +2,28 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   SQLite-backed postcode lookup for the postcode anchor (#240). A thin exact-match resolver over
- *   one or more `postalcode-*.db` extracts (the `spr` schema built by `build-unified-wof --placetypes
- *   postalcode`, then centroid-backfilled by `scripts/backfill-postcode-centroids.ts`).
- *
- *   This is the production implementation of the `PostcodeResolver` interface consumed by
- *   `@mailwoman/neural`'s `extractPostcodeAnchors`. It is deliberately dumb: an indexed exact-match
- *   on the postcode string across every extract, unioned. No FTS, no ranking, no proximity — the
- *   anchor only needs "does this string exist as a postcode, in which countries, near where". A
- *   future WASM build swaps this for an FST-backed resolver behind the same `lookup()` interface.
- *
- *   Why multiple extracts instead of the multi-extract `WOFSQLitePlaceLookup`: that resolver routes a
- *   query to ONE extract by placetype, but every postcode extract shares `placetype='postalcode'`, so a
- *   single query could only ever hit one country's extract. The anchor needs the union across
- *   countries to build its country posterior, so it queries each extract directly.
  */
+import type { PathBuilderLike } from "path-ts";
 /**
- * A gazetteer hit. `lat`/`lon` of 0 means the postcode is known but has no centroid (no admin parent).
+ * One postcode row from the WOF gazetteer, where a `lat`/`lon` of 0 means the
+ * postcode is known but has no centroid.
  */
 export interface PostcodePlace {
     country: string;
     lat: number;
     lon: number;
 }
+/**
+ * Looks up current WOF `postalcode` places by exact name across one or more read-only gazetteer databases.
+ */
 export declare class WOFPostcodeLookup {
     #private;
     /**
-     * Open each extract read-only and prepare its exact-match statement.
+     * Opens each database read-only and prepares its exact-match statement.
      */
-    constructor(dbPaths: readonly string[]);
+    constructor(dbPaths: readonly PathBuilderLike[]);
     /**
-     * Exact-match the postcode across every extract and union the rows.
+     * Returns the union of exact-name matches for `postcode` across every database, without deduplication.
      */
     lookup(postcode: string): PostcodePlace[];
     [Symbol.dispose](): void;

package/out/postcode-point-lookup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"postcode-point-lookup.d.ts","sourceRoot":"","sources":["../lib/postcode-point-lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;CACX;AAKD,qBAAa,iBAAiB;;IAI7B;;OAEG;gBACS,OAAO,EAAE,SAAS,MAAM,EAAE;IAKtC;;OAEG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,EAAE;IAYzC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAKxB"}
+{"version":3,"file":"postcode-point-lookup.d.ts","sourceRoot":"","sources":["../lib/postcode-point-lookup.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAI9C;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;CACX;AAKD;;GAEG;AACH,qBAAa,iBAAiB;;IAI7B;;OAEG;IACH,YAAY,OAAO,EAAE,SAAS,eAAe,EAAE,EAG9C;IAED;;OAEG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,EAAE,CAUxC;IAED,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAIvB;CACD"}

package/out/postcode-point-lookup.js

@@ -2,36 +2,24 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   SQLite-backed postcode lookup for the postcode anchor (#240). A thin exact-match resolver over
- *   one or more `postalcode-*.db` extracts (the `spr` schema built by `build-unified-wof --placetypes
- *   postalcode`, then centroid-backfilled by `scripts/backfill-postcode-centroids.ts`).
- *
- *   This is the production implementation of the `PostcodeResolver` interface consumed by
- *   `@mailwoman/neural`'s `extractPostcodeAnchors`. It is deliberately dumb: an indexed exact-match
- *   on the postcode string across every extract, unioned. No FTS, no ranking, no proximity — the
- *   anchor only needs "does this string exist as a postcode, in which countries, near where". A
- *   future WASM build swaps this for an FST-backed resolver behind the same `lookup()` interface.
- *
- *   Why multiple extracts instead of the multi-extract `WOFSQLitePlaceLookup`: that resolver routes a
- *   query to ONE extract by placetype, but every postcode extract shares `placetype='postalcode'`, so a
- *   single query could only ever hit one country's extract. The anchor needs the union across
- *   countries to build its country posterior, so it queries each extract directly.
  */
 import { DatabaseClient } from "@mailwoman/sqlite/client";
 const LOOKUP_SQL = "SELECT country, latitude AS lat, longitude AS lon FROM spr WHERE name = ? AND placetype = 'postalcode' AND is_current != 0";
+/**
+ * Looks up current WOF `postalcode` places by exact name across one or more read-only gazetteer databases.
+ */
 export class WOFPostcodeLookup {
     #dbs;
     #stmts;
     /**
-     * Open each extract read-only and prepare its exact-match statement.
+     * Opens each database read-only and prepares its exact-match statement.
      */
     constructor(dbPaths) {
         this.#dbs = dbPaths.map((p) => new DatabaseClient(p, { readOnly: true }));
         this.#stmts = this.#dbs.map((db) => db.prepare(LOOKUP_SQL));
     }
     /**
-     * Exact-match the postcode across every extract and union the rows.
+     * Returns the union of exact-name matches for `postcode` across every database, without deduplication.
      */
     lookup(postcode) {
         const out = [];

package/out/postcode-point-lookup.js.map

@@ -1 +1 @@
-{"version":3,"file":"postcode-point-lookup.js","sourceRoot":"","sources":["../lib/postcode-point-lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAazD,MAAM,UAAU,GACf,4HAA4H,CAAA;AAE7H,MAAM,OAAO,iBAAiB;IACpB,IAAI,CAA+B;IACnC,MAAM,CAAyC;IAExD;;OAEG;IACH,YAAY,OAA0B;QACrC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,cAAc,CAAc,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;QACtF,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAA;IAC5D,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,QAAgB;QACtB,MAAM,GAAG,GAAoB,EAAE,CAAA;QAE/B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACtC,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;YACvF,CAAC;QACF,CAAC;QAED,OAAO,GAAG,CAAA;IACX,CAAC;IAED,CAAC,MAAM,CAAC,OAAO,CAAC;QACf,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC5B,EAAE,CAAC,OAAO,EAAE,CAAA;QACb,CAAC;IACF,CAAC;CACD"}
+{"version":3,"file":"postcode-point-lookup.js","sourceRoot":"","sources":["../lib/postcode-point-lookup.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAezD,MAAM,UAAU,GACf,4HAA4H,CAAA;AAE7H;;GAEG;AACH,MAAM,OAAO,iBAAiB;IACpB,IAAI,CAA+B;IACnC,MAAM,CAAyC;IAExD;;OAEG;IACH,YAAY,OAAmC;QAC9C,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,cAAc,CAAc,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;QACtF,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAA;IAC5D,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,QAAgB;QACtB,MAAM,GAAG,GAAoB,EAAE,CAAA;QAE/B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACtC,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;YACvF,CAAC;QACF,CAAC;QAED,OAAO,GAAG,CAAA;IACX,CAAC;IAED,CAAC,MAAM,CAAC,OAAO,CAAC;QACf,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC5B,EAAE,CAAC,OAAO,EAAE,CAAA;QACb,CAAC;IACF,CAAC;CACD"}