@mailwoman/resolver-wof-sqlite 2.1.0

package/out/candidate-schema.js

@@ -0,0 +1,109 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for the byte-range CANDIDATE gazetteer (`candidate.db`) — the single source of truth
+ *   for the columns shared by the BUILDER ({@link buildCandidateTable}) and the READERS (the Node
+ *   {@link WofCandidateTableLookup} + the browser `httpvfs-resolver.ts`). Before this module each
+ *   side hand-wrote the column list; a rename in one place broke the other at runtime. Now the
+ *   contract is a Kysely `Database` interface (`new DatabaseClient<CandidateDatabase>(...)` for
+ *   typed inserts) plus the table DDL as strings — so a column change is a compile error on every
+ *   consumer.
+ *
+ *   `cand_stage` is the transient staging table the builder bulk-loads; `candidate` is the clustered
+ *   `WITHOUT ROWID` B-tree it's materialized into (same columns). The reader queries `candidate`.
+ */
+import { sql } from "kysely";
+/**
+ * The `candidate`/`cand_stage` columns in clustered-key order. The materialization `INSERT INTO
+ * candidate SELECT … FROM cand_stage` derives its column list from this, so the two tables can't
+ * drift. Keep in sync with {@link CandidateTable}.
+ */
+export const CANDIDATE_COLUMNS = [
+    "name_key",
+    "country_id",
+    "region_id",
+    "placetype_id",
+    "neg_rank",
+    "spr_id",
+    "name",
+    "latitude",
+    "longitude",
+    "min_lat",
+    "min_lon",
+    "max_lat",
+    "max_lon",
+    "population",
+    "is_primary",
+];
+/**
+ * Create the code dictionaries + the transient staging table — called before the build's load
+ * passes. `cand_stage` mirrors {@link CandidateTable} but every column is nullable (the loader fills
+ * them positionally). Pass a {@link DatabaseClient} (or any `Kysely`) over the candidate DB.
+ */
+export async function createCandidateStagingTables(db) {
+    await db.schema
+        .createTable("country_codes")
+        .addColumn("id", "integer", (c) => c.primaryKey())
+        .addColumn("code", "text", (c) => c.unique())
+        .execute();
+    await db.schema
+        .createTable("placetype_codes")
+        .addColumn("id", "integer", (c) => c.primaryKey())
+        .addColumn("placetype", "text", (c) => c.unique())
+        .execute();
+    await db.schema
+        .createTable("cand_stage")
+        .addColumn("name_key", "text")
+        .addColumn("country_id", "integer")
+        .addColumn("region_id", "integer")
+        .addColumn("placetype_id", "integer")
+        .addColumn("neg_rank", "real")
+        .addColumn("spr_id", "integer")
+        .addColumn("name", "text")
+        .addColumn("latitude", "real")
+        .addColumn("longitude", "real")
+        .addColumn("min_lat", "real")
+        .addColumn("min_lon", "real")
+        .addColumn("max_lat", "real")
+        .addColumn("max_lon", "real")
+        .addColumn("population", "integer")
+        .addColumn("is_primary", "integer")
+        .execute();
+}
+/**
+ * Create the clustered `WITHOUT ROWID` lookup table — called after staging, before the VACUUM. The
+ * first six columns form the clustered primary key (population-ranked via `neg_rank`).
+ */
+export async function createCandidateTable(db) {
+    await db.schema
+        .createTable("candidate")
+        .addColumn("name_key", "text", (c) => c.notNull())
+        .addColumn("country_id", "integer", (c) => c.notNull())
+        .addColumn("region_id", "integer", (c) => c.notNull())
+        .addColumn("placetype_id", "integer", (c) => c.notNull())
+        .addColumn("neg_rank", "real", (c) => c.notNull())
+        .addColumn("spr_id", "integer", (c) => c.notNull())
+        .addColumn("name", "text")
+        .addColumn("latitude", "real")
+        .addColumn("longitude", "real")
+        .addColumn("min_lat", "real")
+        .addColumn("min_lon", "real")
+        .addColumn("max_lat", "real")
+        .addColumn("max_lon", "real")
+        .addColumn("population", "integer")
+        .addColumn("is_primary", "integer")
+        .addPrimaryKeyConstraint("candidate_pk", [
+        "name_key",
+        "country_id",
+        "region_id",
+        "placetype_id",
+        "neg_rank",
+        "spr_id",
+    ])
+        // `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/candidate-schema.js.map

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

package/out/coincident-roles.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `buildCoincidentRoles` — derives the **coincident-roles relation** (#403, epic #402) into the
+ *   unified gazetteer.
+ *
+ *   Many places occupy MULTIPLE admin tiers under one name: German city-states (Berlin/Hamburg/Bremen
+ *   = city == state), Italian provinces named after their capital (Milano, Varese…), Spanish
+ *   provinces-after-capitals, UK unitary authorities, JP prefectures, NL province-capitals
+ *   (Utrecht/Groningen), Shanghai. When an address surfaces only the admin role (the parser drops
+ *   the locality span), the resolver has no locality to place. The hierarchy-completion step (#405)
+ *   repairs that by consulting THIS relation; the table replaces #387's hardcoded 15 km constant
+ *   with the gazetteer's own structure, so the runtime is an O(1) membership lookup with no
+ *   distance math.
+ *
+ *   V1 is REGION-tier only (admin.placetype = `region`): the ~124 places matching the census across 9
+ *   countries (IT/ES/GB/JP/KR/FR/DE/NL/CN). County-tier same-name coincidences are deliberately
+ *   excluded — they're dominated by French cantons and JP counties (admin subdivisions named after
+ *   a seat town, not dual-role cities) that don't hit the parser-drops-locality failure; genuine
+ *   consolidated city-counties (US SF/Denver) are a separate follow-up needing a relative-size
+ *   filter.
+ *
+ *   A pair `(admin, locality)` is recorded when all hold: same `name` (case-insensitive), the
+ *   locality is a `descendant` of the admin (via the `ancestors` table), and their centroids are
+ *   within a RELATIVE tolerance — `toleranceFraction × admin-bbox-diagonal`, floored at
+ *   `minToleranceKm`. The relative term lets a large Italian province admit a city ~tens of km from
+ *   its centroid while a tiny city-state stays tight; the floor catches city-states whose bbox is
+ *   small (Bremen's centroids sit 9.3 km apart). The tolerance lives ONLY here at build time — it
+ *   never enters the resolver hot path.
+ *
+ *   `relationship_type` is recorded for debuggability / deferred per-type behavior; v1 completion is
+ *   uniform (see #405). It's a coarse classification, not critical.
+ *
+ *   Mirrors the derived-table builder pattern in `fts.ts` (`buildPlaceSearchFts`). Run incrementally
+ *   against an existing `admin-global-priority.db` via `build-coincident-roles-cli.ts`; should also
+ *   be wired as a post-step of the main `scripts/build-unified-wof.ts`.
+ */
+import type { DatabaseSync } from "node:sqlite";
+export declare const COINCIDENT_ROLES_TABLE = "coincident_roles";
+/** A place that plays multiple admin roles — one row of the relation, keyed by `admin_id`. */
+export interface CoincidentRole {
+    localityId: number;
+    relationshipType: "city-state" | "capital-seat" | "consolidated-county";
+    adminPlacetype: string;
+    distanceKm: number;
+    population: number;
+}
+export interface BuildCoincidentRolesOpts {
+    /** Drop + rebuild the table if it already exists. Default true (the build is cheap + idempotent). */
+    drop?: boolean;
+    /**
+     * Relative tolerance: a pair is kept when centroid distance ≤ `toleranceFraction ×
+     * bbox-diagonal`. Default 0.15.
+     */
+    toleranceFraction?: number;
+    /** Floor (km) under the relative tolerance, so small-bbox city-states still qualify. Default 12. */
+    minToleranceKm?: number;
+    /**
+     * Centroid distance (km) below which a region-tier pair is classed `city-state` (metadata only).
+     * Default 2.
+     */
+    cityStateMaxKm?: number;
+    onProgress?: (phase: string, detail?: string) => void;
+}
+export interface BuildCoincidentRolesResult {
+    created: boolean;
+    rowCount: number;
+    byCountry: Record<string, number>;
+    durationMs: number;
+}
+/**
+ * Derive the coincident-roles relation into `db`. Additive — only creates/replaces the
+ * `coincident_roles` table; never touches `spr`/`names`/`ancestors`. Idempotent.
+ */
+export declare function buildCoincidentRoles(db: DatabaseSync, opts?: BuildCoincidentRolesOpts): BuildCoincidentRolesResult;
+/** True iff the relation table exists. Used by the resolver to decide whether completion can run. */
+export declare function coincidentRolesExists(db: DatabaseSync): boolean;
+/**
+ * Load the relation into an in-memory map keyed by `admin_id` for O(1) runtime lookup (#405). Each
+ * admin may map to MULTIPLE same-name descendants; the consumer disambiguates (min distance →
+ * population → abstain). Returns an empty map when the table is absent.
+ */
+export declare function loadCoincidentRoles(db: DatabaseSync): Map<number, CoincidentRole[]>;
+//# sourceMappingURL=coincident-roles.d.ts.map

package/out/coincident-roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coincident-roles.d.ts","sourceRoot":"","sources":["../coincident-roles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C,eAAO,MAAM,sBAAsB,qBAAqB,CAAA;AAExD,8FAA8F;AAC9F,MAAM,WAAW,cAAc;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,gBAAgB,EAAE,YAAY,GAAG,cAAc,GAAG,qBAAqB,CAAA;IACvE,cAAc,EAAE,MAAM,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,wBAAwB;IACxC,qGAAqG;IACrG,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,oGAAoG;IACpG,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CACrD;AAED,MAAM,WAAW,0BAA0B;IAC1C,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,UAAU,EAAE,MAAM,CAAA;CAClB;AAsBD;;;GAGG;AACH,wBAAgB,oBAAoB,CACnC,EAAE,EAAE,YAAY,EAChB,IAAI,GAAE,wBAA6B,GACjC,0BAA0B,CAmF5B;AAED,qGAAqG;AACrG,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,YAAY,GAAG,OAAO,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,YAAY,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC,CA6BnF"}

package/out/coincident-roles.js

@@ -0,0 +1,160 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `buildCoincidentRoles` — derives the **coincident-roles relation** (#403, epic #402) into the
+ *   unified gazetteer.
+ *
+ *   Many places occupy MULTIPLE admin tiers under one name: German city-states (Berlin/Hamburg/Bremen
+ *   = city == state), Italian provinces named after their capital (Milano, Varese…), Spanish
+ *   provinces-after-capitals, UK unitary authorities, JP prefectures, NL province-capitals
+ *   (Utrecht/Groningen), Shanghai. When an address surfaces only the admin role (the parser drops
+ *   the locality span), the resolver has no locality to place. The hierarchy-completion step (#405)
+ *   repairs that by consulting THIS relation; the table replaces #387's hardcoded 15 km constant
+ *   with the gazetteer's own structure, so the runtime is an O(1) membership lookup with no
+ *   distance math.
+ *
+ *   V1 is REGION-tier only (admin.placetype = `region`): the ~124 places matching the census across 9
+ *   countries (IT/ES/GB/JP/KR/FR/DE/NL/CN). County-tier same-name coincidences are deliberately
+ *   excluded — they're dominated by French cantons and JP counties (admin subdivisions named after
+ *   a seat town, not dual-role cities) that don't hit the parser-drops-locality failure; genuine
+ *   consolidated city-counties (US SF/Denver) are a separate follow-up needing a relative-size
+ *   filter.
+ *
+ *   A pair `(admin, locality)` is recorded when all hold: same `name` (case-insensitive), the
+ *   locality is a `descendant` of the admin (via the `ancestors` table), and their centroids are
+ *   within a RELATIVE tolerance — `toleranceFraction × admin-bbox-diagonal`, floored at
+ *   `minToleranceKm`. The relative term lets a large Italian province admit a city ~tens of km from
+ *   its centroid while a tiny city-state stays tight; the floor catches city-states whose bbox is
+ *   small (Bremen's centroids sit 9.3 km apart). The tolerance lives ONLY here at build time — it
+ *   never enters the resolver hot path.
+ *
+ *   `relationship_type` is recorded for debuggability / deferred per-type behavior; v1 completion is
+ *   uniform (see #405). It's a coarse classification, not critical.
+ *
+ *   Mirrors the derived-table builder pattern in `fts.ts` (`buildPlaceSearchFts`). Run incrementally
+ *   against an existing `admin-global-priority.db` via `build-coincident-roles-cli.ts`; should also
+ *   be wired as a post-step of the main `scripts/build-unified-wof.ts`.
+ */
+import { haversineKm } from "@mailwoman/spatial";
+export const COINCIDENT_ROLES_TABLE = "coincident_roles";
+function tableExists(db, name) {
+    return !!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name = ?").get(name);
+}
+/**
+ * Derive the coincident-roles relation into `db`. Additive — only creates/replaces the
+ * `coincident_roles` table; never touches `spr`/`names`/`ancestors`. Idempotent.
+ */
+export function buildCoincidentRoles(db, opts = {}) {
+    const start = Date.now();
+    const drop = opts.drop ?? true;
+    const toleranceFraction = opts.toleranceFraction ?? 0.15;
+    const minToleranceKm = opts.minToleranceKm ?? 12;
+    const cityStateMaxKm = opts.cityStateMaxKm ?? 2;
+    const onProgress = opts.onProgress ?? (() => { });
+    if (tableExists(db, COINCIDENT_ROLES_TABLE) && drop) {
+        onProgress("dropping", COINCIDENT_ROLES_TABLE);
+        db.exec(`DROP TABLE ${COINCIDENT_ROLES_TABLE}`);
+    }
+    onProgress("creating", COINCIDENT_ROLES_TABLE);
+    // Raw DDL by design: this is a sync builder consumed by a sync CLI (build-coincident-roles-cli) and
+    // 6 sync unit tests, so routing one table through async Kysely would cascade async through all of
+    // them for no real gain. See AGENTS.md "Database / inline SQL". (The SELECT + INSERT loop below are
+    // likewise the raw hot path.)
+    db.exec(`
+		CREATE TABLE IF NOT EXISTS ${COINCIDENT_ROLES_TABLE} (
+			admin_id INTEGER NOT NULL,
+			locality_id INTEGER NOT NULL,
+			relationship_type TEXT NOT NULL,
+			admin_placetype TEXT NOT NULL,
+			distance_km REAL NOT NULL,
+			locality_population INTEGER NOT NULL DEFAULT 0,
+			PRIMARY KEY (admin_id, locality_id)
+		)
+	`);
+    onProgress("scanning");
+    // Admin (region/county tier) ⋈ same-name DESCENDANT locality. `place_population` is optional (LEFT
+    // JOIN → 0 when absent). The relative-tolerance filter + relationship classification happen in JS so
+    // the SQL stays a plain join. `spr` exposes the bbox columns we need for the diagonal.
+    const candidates = db
+        .prepare(`SELECT r.id AS admin_id, r.placetype AS admin_placetype, r.country AS country, l.id AS locality_id,
+				r.latitude AS rlat, r.longitude AS rlon, l.latitude AS llat, l.longitude AS llon,
+				r.min_latitude, r.min_longitude, r.max_latitude, r.max_longitude,
+				COALESCE(p.population, 0) AS pop
+			FROM spr r
+			JOIN spr l ON lower(l.name) = lower(r.name) AND l.placetype = 'locality'
+				AND l.is_current != 0 AND l.is_deprecated = 0
+			JOIN ${"ancestors"} a ON a.id = l.id AND a.ancestor_id = r.id
+			LEFT JOIN place_population p ON p.id = l.id
+			WHERE r.placetype = 'region'
+				AND r.is_current != 0 AND r.is_deprecated = 0`)
+        .all();
+    onProgress("filtering", `${candidates.length} candidates`);
+    const insert = db.prepare(`INSERT OR REPLACE INTO ${COINCIDENT_ROLES_TABLE}
+			(admin_id, locality_id, relationship_type, admin_placetype, distance_km, locality_population)
+			VALUES (?, ?, ?, ?, ?, ?)`);
+    const byCountry = {};
+    let rowCount = 0;
+    db.exec("BEGIN");
+    try {
+        for (const c of candidates) {
+            const dist = haversineKm(c.rlat, c.rlon, c.llat, c.llon);
+            const diag = haversineKm(c.min_latitude, c.min_longitude, c.max_latitude, c.max_longitude);
+            const tolerance = Math.max(toleranceFraction * diag, minToleranceKm);
+            if (dist > tolerance)
+                continue;
+            // v1 is region-tier only: a place is a `city-state` when its centroid coincides with the
+            // region's (Berlin/Hamburg), else `capital-seat` (a region named after its principal city, e.g.
+            // Milano province → Milano comune). `consolidated-county` is reserved for a future county-tier
+            // pass (US SF/Denver) — excluded from v1 because county-tier same-name coincidences are
+            // dominated by French cantons / JP counties that don't hit the parser-drops-locality failure.
+            const relationshipType = dist <= cityStateMaxKm ? "city-state" : "capital-seat";
+            insert.run(c.admin_id, c.locality_id, relationshipType, c.admin_placetype, dist, c.pop);
+            rowCount++;
+            byCountry[c.country] = (byCountry[c.country] ?? 0) + 1;
+        }
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        db.exec("ROLLBACK");
+        throw err;
+    }
+    db.exec(`CREATE INDEX IF NOT EXISTS coincident_roles_by_admin ON ${COINCIDENT_ROLES_TABLE} (admin_id)`);
+    onProgress("done", `${rowCount} coincident-role rows`);
+    return { created: true, rowCount, byCountry, durationMs: Date.now() - start };
+}
+/** True iff the relation table exists. Used by the resolver to decide whether completion can run. */
+export function coincidentRolesExists(db) {
+    return tableExists(db, COINCIDENT_ROLES_TABLE);
+}
+/**
+ * Load the relation into an in-memory map keyed by `admin_id` for O(1) runtime lookup (#405). Each
+ * admin may map to MULTIPLE same-name descendants; the consumer disambiguates (min distance →
+ * population → abstain). Returns an empty map when the table is absent.
+ */
+export function loadCoincidentRoles(db) {
+    const map = new Map();
+    if (!coincidentRolesExists(db))
+        return map;
+    const rows = db
+        .prepare(`SELECT admin_id, locality_id, relationship_type, admin_placetype, distance_km, locality_population
+			FROM ${COINCIDENT_ROLES_TABLE}`)
+        .all();
+    for (const r of rows) {
+        const entry = {
+            localityId: r.locality_id,
+            relationshipType: r.relationship_type,
+            adminPlacetype: r.admin_placetype,
+            distanceKm: r.distance_km,
+            population: r.locality_population,
+        };
+        const list = map.get(r.admin_id);
+        if (list)
+            list.push(entry);
+        else
+            map.set(r.admin_id, [entry]);
+    }
+    return map;
+}
+//# sourceMappingURL=coincident-roles.js.map

package/out/coincident-roles.js.map

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

package/out/convention.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The **Geographic Rule Engine** convention model (Direction E, #289 — see
+ *   `docs/articles/plan/2026-06-05-geographic-rule-engine.md` and epic #288).
+ *
+ *   A `Convention` is a declarative resolution profile attached to a Who's-On-First admin polygon.
+ *   The engine deep-merges the conventions along a resolved place's ancestor chain — country →
+ *   region → … → locality, most-specific winning — and the backend dispatches the named strategies
+ *   in `candidateStrategies`, first to return candidates wins.
+ *
+ *   This module is the backend-agnostic core: the convention TYPES, the deep-merge, and the seed
+ *   source. The strategy IMPLEMENTATIONS are SQL-bound and live in `lookup.ts`, registered by
+ *   name.
+ *
+ *   For the existing EU locales (DE/FR/GB/NL) the seed source is empty, so every query resolves to
+ *   `WORLD_DEFAULT` and the dispatch is byte-identical to the pre-engine coordinate-first path. JP
+ *   / KR / TW add rows here (and #290 swaps the seed map for a build-from-source sqlite-backed
+ *   source).
+ */
+import type { FindPlaceQuery, PlaceCandidate } from "./types.js";
+/**
+ * Soft-scoring weights for the `postcode_area_resolution` strategy: `pc·S_pc + name·S_name +
+ * pop·S_pop`.
+ */
+export interface ScoringWeights {
+    pc: number;
+    name: number;
+    pop: number;
+}
+/**
+ * A geographically-scoped resolution profile. Namespaced sections grow per phase; #289 ships the
+ * dispatch + scoring slice (`candidateStrategies` + `scoringWeights`). Later phases add
+ * `fieldMapping` (locale semantics for `locator[]`), `tokenNormalization`, etc.
+ */
+export interface Convention {
+    /** Ordered strategy names the dispatcher runs; the first to return a non-null result wins. */
+    candidateStrategies?: string[];
+    /**
+     * Weights for `postcode_area_resolution`'s soft-score. Partial — a layer may nudge one weight and
+     * inherit the rest from the layers below it (`resolveConvention` fills any gaps from
+     * WORLD_DEFAULT).
+     */
+    scoringWeights?: Partial<ScoringWeights>;
+}
+/**
+ * A fully-resolved convention: every field present, weights complete. What `resolveConvention`
+ * returns and what strategies consume.
+ */
+export interface ResolvedConvention {
+    candidateStrategies: string[];
+    scoringWeights: ScoringWeights;
+}
+/**
+ * The base layer every ancestor chain starts from. Reproduces the pre-engine coordinate-first
+ * behavior exactly: try `postcode_area_resolution`, else fall back to fuzzy name match; soft-score
+ * weights 0.6 / 0.3 / 0.1. Changing these changes EU behavior — don't, without a byte-stability
+ * run.
+ */
+export declare const WORLD_DEFAULT: ResolvedConvention;
+/**
+ * The strategy names the backend registers. The single source of truth shared by the dispatch
+ * registry and the build-time validator, so an authored convention that names a non-existent
+ * strategy is caught at build (loud) rather than silently skipped at runtime.
+ */
+export declare const BUILTIN_STRATEGY_NAMES: readonly ["postcode_area_resolution", "fallback_fuzzy_name_match"];
+/**
+ * Table name for the convention asset (#290). Carried here so the build script, the runtime source,
+ * and the shard auto-detect all agree.
+ */
+export declare const ADDRESS_CONVENTION_TABLE = "address_convention";
+/**
+ * A named resolution primitive. Returns `null` to abstain (gate unmet / no data) → the dispatcher
+ * tries the next strategy; returns an array (possibly empty) to claim the result.
+ */
+export type Strategy = (query: FindPlaceQuery, convention: ResolvedConvention) => Promise<PlaceCandidate[] | null>;
+/**
+ * Look up a convention record by WOF polygon id. Returns `undefined` when the polygon has no
+ * override.
+ */
+export interface ConventionSource {
+    get(wofId: number): Convention | undefined;
+}
+/**
+ * In-memory convention source seeded from a `{ wofId: Convention }` map. Empty for the EU locales
+ * (they ride `WORLD_DEFAULT`); JP / KR / TW add rows. #290 replaces this with a sqlite-backed
+ * source built from source, same distributable-asset discipline as `postcode-locality-intl.db`.
+ */
+export declare class SeedConventionSource implements ConventionSource {
+    #private;
+    constructor(rows?: Record<number, Convention>);
+    get(wofId: number): Convention | undefined;
+}
+/**
+ * Deep-merge convention layers, later (more-specific) layers winning per field.
+ * `candidateStrategies` is replaced wholesale — a convention names its full ordered list, it does
+ * not append. `scoringWeights` is merged key-by-key so a locality can nudge one weight without
+ * restating the others.
+ */
+export declare function mergeConventions(base: Convention, ...overrides: Array<Convention | undefined>): Convention;
+/**
+ * Resolve the effective convention for a place given its ancestor chain, ordered MOST-GENERAL →
+ * MOST-SPECIFIC (country, region, …, locality). Starts from `WORLD_DEFAULT` so every field is
+ * defined regardless of which (if any) ancestors carry an override.
+ */
+export declare function resolveConvention(source: ConventionSource, ancestorIds: readonly number[]): ResolvedConvention;
+//# sourceMappingURL=convention.d.ts.map

package/out/convention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convention.d.ts","sourceRoot":"","sources":["../convention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhE;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;CACX;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IAC1B,8FAA8F;IAC9F,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC9B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAA;CACxC;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,mBAAmB,EAAE,MAAM,EAAE,CAAA;IAC7B,cAAc,EAAE,cAAc,CAAA;CAC9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,kBAG3B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,oEAAqE,CAAA;AAExG;;;GAGG;AACH,eAAO,MAAM,wBAAwB,uBAAuB,CAAA;AAE5D;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,kBAAkB,KAAK,OAAO,CAAC,cAAc,EAAE,GAAG,IAAI,CAAC,CAAA;AAElH;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAChC,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAA;CAC1C;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,YAAW,gBAAgB;;gBAGhD,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAM;IAIjD,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;CAG1C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,SAAS,EAAE,KAAK,CAAC,UAAU,GAAG,SAAS,CAAC,GAAG,UAAU,CAa1G;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,kBAAkB,CAQ9G"}

package/out/convention.js

@@ -0,0 +1,94 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The **Geographic Rule Engine** convention model (Direction E, #289 — see
+ *   `docs/articles/plan/2026-06-05-geographic-rule-engine.md` and epic #288).
+ *
+ *   A `Convention` is a declarative resolution profile attached to a Who's-On-First admin polygon.
+ *   The engine deep-merges the conventions along a resolved place's ancestor chain — country →
+ *   region → … → locality, most-specific winning — and the backend dispatches the named strategies
+ *   in `candidateStrategies`, first to return candidates wins.
+ *
+ *   This module is the backend-agnostic core: the convention TYPES, the deep-merge, and the seed
+ *   source. The strategy IMPLEMENTATIONS are SQL-bound and live in `lookup.ts`, registered by
+ *   name.
+ *
+ *   For the existing EU locales (DE/FR/GB/NL) the seed source is empty, so every query resolves to
+ *   `WORLD_DEFAULT` and the dispatch is byte-identical to the pre-engine coordinate-first path. JP
+ *   / KR / TW add rows here (and #290 swaps the seed map for a build-from-source sqlite-backed
+ *   source).
+ */
+/**
+ * The base layer every ancestor chain starts from. Reproduces the pre-engine coordinate-first
+ * behavior exactly: try `postcode_area_resolution`, else fall back to fuzzy name match; soft-score
+ * weights 0.6 / 0.3 / 0.1. Changing these changes EU behavior — don't, without a byte-stability
+ * run.
+ */
+export const WORLD_DEFAULT = {
+    candidateStrategies: ["postcode_area_resolution", "fallback_fuzzy_name_match"],
+    scoringWeights: { pc: 0.6, name: 0.3, pop: 0.1 },
+};
+/**
+ * The strategy names the backend registers. The single source of truth shared by the dispatch
+ * registry and the build-time validator, so an authored convention that names a non-existent
+ * strategy is caught at build (loud) rather than silently skipped at runtime.
+ */
+export const BUILTIN_STRATEGY_NAMES = ["postcode_area_resolution", "fallback_fuzzy_name_match"];
+/**
+ * Table name for the convention asset (#290). Carried here so the build script, the runtime source,
+ * and the shard auto-detect all agree.
+ */
+export const ADDRESS_CONVENTION_TABLE = "address_convention";
+/**
+ * In-memory convention source seeded from a `{ wofId: Convention }` map. Empty for the EU locales
+ * (they ride `WORLD_DEFAULT`); JP / KR / TW add rows. #290 replaces this with a sqlite-backed
+ * source built from source, same distributable-asset discipline as `postcode-locality-intl.db`.
+ */
+export class SeedConventionSource {
+    #rows;
+    constructor(rows = {}) {
+        this.#rows = new Map(Object.entries(rows).map(([k, v]) => [Number(k), v]));
+    }
+    get(wofId) {
+        return this.#rows.get(wofId);
+    }
+}
+/**
+ * Deep-merge convention layers, later (more-specific) layers winning per field.
+ * `candidateStrategies` is replaced wholesale — a convention names its full ordered list, it does
+ * not append. `scoringWeights` is merged key-by-key so a locality can nudge one weight without
+ * restating the others.
+ */
+export function mergeConventions(base, ...overrides) {
+    const out = {
+        candidateStrategies: base.candidateStrategies ? [...base.candidateStrategies] : undefined,
+        scoringWeights: base.scoringWeights ? { ...base.scoringWeights } : undefined,
+    };
+    for (const o of overrides) {
+        if (!o)
+            continue;
+        if (o.candidateStrategies !== undefined)
+            out.candidateStrategies = [...o.candidateStrategies];
+        if (o.scoringWeights !== undefined) {
+            out.scoringWeights = { ...(out.scoringWeights ?? WORLD_DEFAULT.scoringWeights), ...o.scoringWeights };
+        }
+    }
+    return out;
+}
+/**
+ * Resolve the effective convention for a place given its ancestor chain, ordered MOST-GENERAL →
+ * MOST-SPECIFIC (country, region, …, locality). Starts from `WORLD_DEFAULT` so every field is
+ * defined regardless of which (if any) ancestors carry an override.
+ */
+export function resolveConvention(source, ancestorIds) {
+    const layers = ancestorIds.map((id) => source.get(id));
+    const merged = mergeConventions(WORLD_DEFAULT, ...layers);
+    return {
+        candidateStrategies: merged.candidateStrategies ?? WORLD_DEFAULT.candidateStrategies,
+        // Fill any weight gaps from the base so strategies always see a complete set.
+        scoringWeights: { ...WORLD_DEFAULT.scoringWeights, ...merged.scoringWeights },
+    };
+}
+//# sourceMappingURL=convention.js.map

package/out/convention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convention.js","sourceRoot":"","sources":["../convention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAuCH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAuB;IAChD,mBAAmB,EAAE,CAAC,0BAA0B,EAAE,2BAA2B,CAAC;IAC9E,cAAc,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE;CAChD,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,0BAA0B,EAAE,2BAA2B,CAAU,CAAA;AAExG;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,oBAAoB,CAAA;AAgB5D;;;;GAIG;AACH,MAAM,OAAO,oBAAoB;IACvB,KAAK,CAAyB;IAEvC,YAAY,OAAmC,EAAE;QAChD,IAAI,CAAC,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;IAC3E,CAAC;IAED,GAAG,CAAC,KAAa;QAChB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;IAC7B,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAgB,EAAE,GAAG,SAAwC;IAC7F,MAAM,GAAG,GAAe;QACvB,mBAAmB,EAAE,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,SAAS;QACzF,cAAc,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,SAAS;KAC5E,CAAA;IACD,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC3B,IAAI,CAAC,CAAC;YAAE,SAAQ;QAChB,IAAI,CAAC,CAAC,mBAAmB,KAAK,SAAS;YAAE,GAAG,CAAC,mBAAmB,GAAG,CAAC,GAAG,CAAC,CAAC,mBAAmB,CAAC,CAAA;QAC7F,IAAI,CAAC,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;YACpC,GAAG,CAAC,cAAc,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,cAAc,IAAI,aAAa,CAAC,cAAc,CAAC,EAAE,GAAG,CAAC,CAAC,cAAc,EAAE,CAAA;QACtG,CAAC;IACF,CAAC;IACD,OAAO,GAAG,CAAA;AACX,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAwB,EAAE,WAA8B;IACzF,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;IACtD,MAAM,MAAM,GAAG,gBAAgB,CAAC,aAAa,EAAE,GAAG,MAAM,CAAC,CAAA;IACzD,OAAO;QACN,mBAAmB,EAAE,MAAM,CAAC,mBAAmB,IAAI,aAAa,CAAC,mBAAmB;QACpF,8EAA8E;QAC9E,cAAc,EAAE,EAAE,GAAG,aAAa,CAAC,cAAc,EAAE,GAAG,MAAM,CAAC,cAAc,EAAE;KAC7E,CAAA;AACF,CAAC"}

package/out/fst-autocomplete.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   FST-based autocomplete. Prefix walk + BFS expansion to collect ranked place suggestions. O(depth
+ *   × branching) — the FST IS the autocomplete index.
+ *
+ *   Two query shapes are handled (the FST is a trie over normalized WORD tokens):
+ *
+ *   - COMPLETE tokens ("new york") — `walk` lands on a state; collect its accepting entries + BFS a
+ *       couple tokens past it for nearby completions. This is the CLI's "complete a place word"
+ *       path.
+ *   - A PARTIAL last token ("new yor", "chic") — `walk` fails (there is no "yor" edge, only "york"). So
+ *       walk the complete prefix, then complete the partial token by prefix-filtering the
+ *       continuation edges (`token.startsWith(partial)`). This is what a char-level typeahead
+ *       needs; without it "new yor" returns nothing useful. (#587)
+ */
+import { FstMatcher } from "./fst-matcher.js";
+export interface AutocompleteResult {
+    query: string;
+    normalizedTokens: string[];
+    depth: number;
+    suggestions: AutocompleteSuggestion[];
+}
+export interface AutocompleteSuggestion {
+    name: string;
+    placetype: string;
+    importance: number;
+    wofID: number;
+    parentChain: number[];
+    matchDepth: number;
+    completionTokens: string[];
+}
+export interface AutocompleteOpts {
+    maxSuggestions?: number;
+    maxExpansionDepth?: number;
+    /**
+     * Collapse same-name suggestions to the single highest-importance one. Off by default (the CLI
+     * surfaces distinct same-name places — New York the city vs the county); a typeahead wants it ON
+     * so the dropdown isn't four "New London"s. (#587)
+     */
+    dedupeByName?: boolean;
+}
+/**
+ * Autocomplete from the current prefix. Returns suggestions ranked importance-descending.
+ */
+export declare function autocomplete(fst: FstMatcher, query: string, opts?: AutocompleteOpts): AutocompleteResult;
+//# sourceMappingURL=fst-autocomplete.d.ts.map

package/out/fst-autocomplete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fst-autocomplete.d.ts","sourceRoot":"","sources":["../fst-autocomplete.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,UAAU,EAAmB,MAAM,kBAAkB,CAAA;AAG9D,MAAM,WAAW,kBAAkB;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,sBAAsB,EAAE,CAAA;CACrC;AAED,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,gBAAgB,EAAE,MAAM,EAAE,CAAA;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAChC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACtB;AAoBD;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,GAAG,kBAAkB,CA2D5G"}