@mailwoman/resolver-wof-sqlite 9.0.0 → 9.2.0

package/out/uprn-schema.js

@@ -0,0 +1,78 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for `uprn.db` — the OS Open UPRN spatial layer: every GB Unique Property Reference
+ *   Number with its WGS84 point, so mailwoman results can carry UPRN as an interoperability key
+ *   beside our own `@mailwoman/address-id`. One rowid table keyed `uprn INTEGER PRIMARY KEY` (the
+ *   rowid alias — the optimal shape for an integer-PK point table; `WITHOUT ROWID` buys nothing
+ *   here), plus a secondary res-9 `h3_cell` index for the bounded nearest-point probe.
+ *
+ *   ## Coordinates are OS's own WGS84 columns
+ *
+ *   The source CSV publishes BOTH coordinate systems per row — OSGB36 eastings/northings AND WGS84
+ *   `LATITUDE`/`LONGITUDE`. This layer stores OS's own lat/lon verbatim and never reconverts from
+ *   eastings: `@mailwoman/spatial`'s `osgb36ToWGS84` is a 7-parameter Helmert with a measured p95 of
+ *   4.18 m, and re-deriving what the publisher already computed (with OSTN15, exactly) would replace
+ *   their answer with a strictly worse one.
+ *
+ *   ## Why `h3_cell` exists at all
+ *
+ *   The layer contract requires every domain row to be addressable by at least one spine key —
+ *   `writeLayerManifest` throws on a manifest that declares none — and UPRN is its own id space, not
+ *   H3/WOF/address-id/street. The res-9 short cell (`shortCellToInt`, the same packing as poi.db and
+ *   the OSM situs shards) is the spine that fits a point table, and its index doubles as the
+ *   `nearestUPRN` ring probe.
+ *
+ *   The DB also embeds the layer-contract tables from `@mailwoman/core/layers`; the builder
+ *   (`packages/mailwoman/gazetteer-pipeline/uprn-layer.ts`) writes the manifest and per-res-6-cell
+ *   coverage.
+ */
+import { shortCellToInt } from "@mailwoman/spatial";
+import { latLngToCell } from "h3-js";
+/**
+ * Resolution the `uprn` table's `h3_cell` column is keyed at — the shared layer-spine resolution (poi.db, the OSM situs
+ * shards).
+ */
+export const UPRN_H3_RESOLUTION = 9;
+/**
+ * Resolution of the layer's `layer_coverage` cells — coarse, per the contract (matches poi.db).
+ */
+export const UPRN_COVERAGE_H3_RESOLUTION = 6;
+/**
+ * The full res-9 cell for a UPRN point — the ONE derivation both the builder and every consumer share, so a fixture
+ * built by a test and a row built by the real ingest can never disagree on which cell a coordinate keys to.
+ */
+export function uprnFullCell(latitude, longitude) {
+    return latLngToCell(latitude, longitude, UPRN_H3_RESOLUTION);
+}
+/**
+ * The `h3_cell` column value for a UPRN point: {@link uprnFullCell} packed to the shared 48-bit short-cell integer.
+ */
+export function uprnH3Cell(latitude, longitude) {
+    return shortCellToInt(uprnFullCell(latitude, longitude));
+}
+export async function createUPRNTable(db) {
+    await db.schema
+        .createTable("uprn")
+        .addColumn("uprn", "integer", (c) => c.primaryKey())
+        .addColumn("lat", "real", (c) => c.notNull())
+        .addColumn("lon", "real", (c) => c.notNull())
+        .addColumn("h3_cell", "integer", (c) => c.notNull())
+        .execute();
+}
+export async function createUPRNMetaTable(db) {
+    await db.schema
+        .createTable("uprn_meta")
+        .addColumn("key", "text", (c) => c.primaryKey())
+        .addColumn("value", "text", (c) => c.notNull())
+        .execute();
+}
+/**
+ * Secondary index for the `nearestUPRN` ring probe. Builders call this AFTER the bulk load (index-after-load).
+ */
+export async function createUPRNIndexes(db) {
+    await db.schema.createIndex("uprn_h3_cell").on("uprn").column("h3_cell").execute();
+}
+//# sourceMappingURL=uprn-schema.js.map

package/out/uprn-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uprn-schema.js","sourceRoot":"","sources":["../uprn-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,EAAE,cAAc,EAAe,MAAM,oBAAoB,CAAA;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAA;AAGpC;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAA;AAEnC;;GAEG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAA;AAuC5C;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,SAAiB;IAC/D,OAAO,YAAY,CAAC,QAAQ,EAAE,SAAS,EAAE,kBAAkB,CAAW,CAAA;AACvE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,QAAgB,EAAE,SAAiB;IAC7D,OAAO,cAAc,CAAC,YAAY,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAA;AACzD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,EAAwB;IAC7D,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,MAAM,CAAC;SACnB,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;SACnD,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC5C,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC5C,SAAS,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACnD,OAAO,EAAE,CAAA;AACZ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,EAAwB;IACjE,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,WAAW,CAAC;SACxB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;SAC/C,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC9C,OAAO,EAAE,CAAA;AACZ,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,EAAwB;IAC/D,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAA;AACnF,CAAC"}

package/out/weights-overlay-linker.d.ts

@@ -0,0 +1,141 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * Shared development tooling for weights overlays: the symlink primitives every overlay linker uses, and the
+ * placetype-pair index build.
+ */
+/**
+ * Replicate `ln -sf SRC DEST` ATOMICALLY: symlink under a temp name, then rename over the destination. A plain
+ * unlink-then-symlink leaves a no-file window that concurrent vitest workers can hit mid-suite — bit CI on 2026-07-24.
+ * rename(2) replaces the destination atomically.
+ */
+export declare function linkForce(src: string, dest: string): void;
+/**
+ * Remove a leftover local file/symlink so the #1179 base-weights fallback engages.
+ */
+export declare function removeIfPresent(dest: string): void;
+/**
+ * Symlink one soft-feed sibling into an overlay, warning rather than failing when the source is absent.
+ *
+ * Every one of these artifacts is OPTIONAL by design — the runtime has a fallback for each, so a fresh worktree that
+ * has not built the gazetteer still geocodes. That is why the miss prints the consequence instead of throwing: the
+ * operator needs to know which channel just resolved OFF, not to have the link step abort.
+ */
+export declare function linkSoftFeedSibling(source: string, destination: string, consequenceIfMissing: string): boolean;
+/**
+ * What one pair-index overlay has to say about itself. Everything else is shared.
+ */
+export interface PairIndexOverlay {
+    /**
+     * Workspace directory name, e.g. `neural-weights-de-de`.
+     */
+    packageDir: string;
+    /**
+     * ISO country code passed to `gazetteer pair-index --country`, and the suffix of the built artifact (`de` →
+     * `pair-index-de.bin`). NOT the locale tag: `en-in` builds `pair-index-in.bin`.
+     */
+    country: string;
+    /**
+     * Calibrated magnitudes the locale's bars were measured at. Baked into the artifact's PIX1 header, which is how the
+     * freshness check below notices a change to either.
+     */
+    delta: number;
+    transitionBeta: number;
+}
+/**
+ * The header fields a dev-weights freshness guard reads.
+ */
+export interface PairIndexHeaderFields {
+    delta: number;
+    transitionBeta: number | undefined;
+    parentDelta: number | undefined;
+    schemaVersion: number;
+    /**
+     * One md5 per source the build read, in fold order. Empty on a header that recorded none.
+     */
+    sourceMD5s: string[];
+}
+/**
+ * Minimal PIX1 header reader — magic + header only, reimplemented so a data-only weights package gains no dependency on
+ * `@mailwoman/neural` (which pulls onnxruntime-node) to read a few fields. `neural/pair-index-resolver.ts`'s own header
+ * parse is the source of truth this must follow.
+ *
+ * Shared by the overlay build below AND by the four hand-written base linkers
+ * (`neural-weights-{en-us,en-gb,en-nz,fr-fr}/scripts/link-dev-weights.ts`), which each carried their own near-copy
+ * before 2026-08-04 — the ×5 clone the taste audit named, and the reason three of them were schema-blind while this one
+ * was not.
+ */
+export declare function peekPairIndexHeaderFields(path: string): PairIndexHeaderFields;
+/**
+ * Md5 of `path`, cached in a standard `md5sum`-format sidecar (`<hash> <filename>`) beside it so a multi-gigabyte
+ * source is hashed once per change rather than once per linker run. The sidecar is trusted only when at least as new as
+ * the source; a missing or stale sidecar recomputes and rewrites, so the cache self-heals.
+ *
+ * The shared home for the copies the base linkers (`en-us`, `en-gb`, `en-nz`) each carry — new callers import this one.
+ */
+export declare function md5FileWithSidecar(path: string): Promise<string>;
+/**
+ * The calibrated magnitudes a linker bakes into its artifact. `undefined` means the flag is NOT passed and the header
+ * carries no such key — a real state, distinct from zero (see `PairIndexHeader.parentDelta`), so the comparison below
+ * is `!==` against `undefined` rather than a truthiness test.
+ */
+export interface PairIndexCalibration {
+    delta: number;
+    transitionBeta?: number;
+    parentDelta?: number;
+}
+/**
+ * Why an existing `pair-index-*.bin` is stale against `expected`, or `undefined` when its header matches. Covers the
+ * FORMAT (schemaVersion) and every calibrated magnitude; source-md5 freshness stays with the caller, because each base
+ * linker passes a different set of sources and only it knows what they are.
+ *
+ * One place so a magnitude added to the header cannot be checked by some linkers and not others — which is exactly how
+ * three of the four base linkers ended up unable to notice a schema bump.
+ */
+export declare function pairIndexStaleReason(header: PairIndexHeaderFields, expected: PairIndexCalibration): string | undefined;
+/**
+ * The PIX1 schema this tree's reader requires. MUST equal `KNOWN_SCHEMA_VERSION` in `neural/pair-index-resolver.ts` —
+ * they are two ends of one fact, and this copy exists only because a data-only overlay must not gain a dependency on
+ * `@mailwoman/neural` (onnxruntime-node) to read one header field. Bump BOTH in the same commit; a schema bump that
+ * leaves this behind makes every dev checkout rebuild-loop or serve an artifact the runtime refuses.
+ *
+ * The freshness guard must compare it: a guard that checks only delta + source md5 reads a format-obsolete binary as
+ * "current" and leaves every dev checkout with artifacts the runtime refuses — the R5 freshness-guard lesson, format
+ * edition. Also compared by the four hand-written base linkers (`neural-weights-{en-us,en-gb,en-nz,fr-fr}`), which
+ * import this constant rather than re-typing the number.
+ */
+export declare const REQUIRED_PAIR_INDEX_SCHEMA = 3;
+/**
+ * Warn when the per-locale FST a linker just symlinked was built from a DIFFERENT admin database than the one on disk
+ * now.
+ *
+ * WHY IT WARNS RATHER THAN REBUILDS, unlike its pair-index sibling above. A pair index is seconds of work and the
+ * linker owns its whole recipe. A locale FST is a multi-minute build whose output goes to a STAGING dir on purpose —
+ * the swap into `fst-per-locale/` is operator-gated after the battery, because an FST changes decoder behaviour and the
+ * D-rule does not let that land unmeasured. So the guard's job is to make the drift impossible to miss, and to name the
+ * command that starts fixing it. It is also why a stale FST is never fatal: the artifact is a decode-time bias list,
+ * and a dev tree must still run.
+ *
+ * The source-side half of the comparison lives here rather than in `fst-freshness.ts` for the same reason
+ * `pairIndexStaleReason` splits: only the caller knows which database it built against. All three FST-linking base
+ * packages build against the same one, so they share this rather than each pinning it.
+ */
+export declare function warnIfFSTStale(fstPath: string, locale: string): void;
+/**
+ * Build `pair-index-<country>.bin` into the overlay, skipping the work when the artifact on disk was already built at
+ * these magnitudes FROM the admin database on disk.
+ *
+ * The skip requires both halves (#1734): the header magnitudes (`pairIndexStaleReason`) AND the header's `sourceMD5s`
+ * against the current admin DB's md5. Magnitudes alone read a source change as "current" whenever pair counts happen
+ * not to move the calibrated numbers — the R5 freshness-guard lesson, which resurfaced in the 2026-08-18 admin swap
+ * when all four overlay locales skipped while the md5-checking base linkers rebuilt. This build's ONE source is the
+ * admin DB it passes as `--borough-db`, so the comparison is exactly one md5; a linker with a different source list
+ * (fr's BAN directory) owns its own guard and must never be pointed at this one.
+ *
+ * Exits non-zero on a failed build. Missing INPUTS (an unbuilt CLI, an absent WOF database) warn and return instead: a
+ * fresh clone has neither, and `yarn test` invokes this to verify auto-resolve, so a hard failure there would be a
+ * failure to have run a build yet rather than a real fault.
+ */
+export declare function buildPairIndexOverlay({ packageDir, country, delta, transitionBeta, }: PairIndexOverlay): Promise<void>;
+//# sourceMappingURL=weights-overlay-linker.d.ts.map

package/out/weights-overlay-linker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"weights-overlay-linker.d.ts","sourceRoot":"","sources":["../weights-overlay-linker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAqBH;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CASzD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAUlD;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,GAAG,OAAO,CAY9G;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,cAAc,EAAE,MAAM,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,KAAK,EAAE,MAAM,CAAA;IACb,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,aAAa,EAAE,MAAM,CAAA;IACrB;;OAEG;IACH,UAAU,EAAE,MAAM,EAAE,CAAA;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,CA2B7E;AAOD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAsBtE;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,MAAM,CAAA;IACb,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,qBAAqB,EAC7B,QAAQ,EAAE,oBAAoB,GAC5B,MAAM,GAAG,SAAS,CAgBpB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,IAAI,CAAA;AAE3C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAUpE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,qBAAqB,CAAC,EAC3C,UAAU,EACV,OAAO,EACP,KAAK,EACL,cAAc,GACd,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuFlC"}

package/out/weights-overlay-linker.js

@@ -0,0 +1,259 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * Shared development tooling for weights overlays: the symlink primitives every overlay linker uses, and the
+ * placetype-pair index build.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, statSync, symlinkSync, unlinkSync, writeFileSync, } from "node:fs";
+import { resolve } from "node:path";
+import { parseJSONStrict } from "@mailwoman/core/objects";
+import { dataRootPath, md5File, weightsOverlayPath, workspacePath } from "@mailwoman/core/utils";
+import { fstFreshnessWarning } from "./fst-freshness.js";
+/**
+ * Replicate `ln -sf SRC DEST` ATOMICALLY: symlink under a temp name, then rename over the destination. A plain
+ * unlink-then-symlink leaves a no-file window that concurrent vitest workers can hit mid-suite — bit CI on 2026-07-24.
+ * rename(2) replaces the destination atomically.
+ */
+export function linkForce(src, dest) {
+    const tmp = `${dest}.tmp-link`;
+    if (existsSync(tmp)) {
+        unlinkSync(tmp);
+    }
+    symlinkSync(src, tmp);
+    renameSync(tmp, dest);
+}
+/**
+ * Remove a leftover local file/symlink so the #1179 base-weights fallback engages.
+ */
+export function removeIfPresent(dest) {
+    try {
+        lstatSync(dest);
+    }
+    catch {
+        return;
+    }
+    unlinkSync(dest);
+    console.log(`removed stale local ${dest} (base fallback to en-us engages)`);
+}
+/**
+ * Symlink one soft-feed sibling into an overlay, warning rather than failing when the source is absent.
+ *
+ * Every one of these artifacts is OPTIONAL by design — the runtime has a fallback for each, so a fresh worktree that
+ * has not built the gazetteer still geocodes. That is why the miss prints the consequence instead of throwing: the
+ * operator needs to know which channel just resolved OFF, not to have the link step abort.
+ */
+export function linkSoftFeedSibling(source, destination, consequenceIfMissing) {
+    if (!existsSync(source)) {
+        console.error(`WARNING: missing ${source} — ${consequenceIfMissing}`);
+        return false;
+    }
+    linkForce(source, destination);
+    console.log(`linked ${destination} \u2190 ${source}`);
+    return true;
+}
+/**
+ * Minimal PIX1 header reader — magic + header only, reimplemented so a data-only weights package gains no dependency on
+ * `@mailwoman/neural` (which pulls onnxruntime-node) to read a few fields. `neural/pair-index-resolver.ts`'s own header
+ * parse is the source of truth this must follow.
+ *
+ * Shared by the overlay build below AND by the four hand-written base linkers
+ * (`neural-weights-{en-us,en-gb,en-nz,fr-fr}/scripts/link-dev-weights.ts`), which each carried their own near-copy
+ * before 2026-08-04 — the ×5 clone the taste audit named, and the reason three of them were schema-blind while this one
+ * was not.
+ */
+export function peekPairIndexHeaderFields(path) {
+    const bytes = readFileSync(path);
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    // "PIX1" little-endian.
+    const MAGIC = 0x31_58_49_50;
+    if (view.getUint32(0, true) !== MAGIC) {
+        throw new Error(`pair index: bad magic reading ${path}`);
+    }
+    const headerLen = view.getUint32(4, true);
+    const header = parseJSONStrict(Buffer.from(bytes.subarray(8, 8 + headerLen)).toString("utf8"));
+    return {
+        delta: header.delta,
+        transitionBeta: header.transitionBeta,
+        parentDelta: header.parentDelta,
+        schemaVersion: header.schemaVersion,
+        sourceMD5s: header.sourceMD5s ?? [],
+    };
+}
+/**
+ * Hex characters in an md5 digest.
+ */
+const MD5_HEX_LENGTH = 32;
+/**
+ * Md5 of `path`, cached in a standard `md5sum`-format sidecar (`<hash> <filename>`) beside it so a multi-gigabyte
+ * source is hashed once per change rather than once per linker run. The sidecar is trusted only when at least as new as
+ * the source; a missing or stale sidecar recomputes and rewrites, so the cache self-heals.
+ *
+ * The shared home for the copies the base linkers (`en-us`, `en-gb`, `en-nz`) each carry — new callers import this one.
+ */
+export async function md5FileWithSidecar(path) {
+    const sidecarPath = `${path}.md5`;
+    const sourceStats = statSync(path);
+    if (existsSync(sidecarPath)) {
+        try {
+            if (statSync(sidecarPath).mtime >= sourceStats.mtime) {
+                const [hash] = readFileSync(sidecarPath, "utf8").trim().split(/\s+/);
+                if (hash && hash.length === MD5_HEX_LENGTH)
+                    return hash;
+            }
+        }
+        catch {
+            // Unreadable sidecar — recompute below.
+        }
+    }
+    const hash = await md5File(path);
+    const filename = path.split(/[/\\]/).pop() || path;
+    writeFileSync(sidecarPath, `${hash}  ${filename}\n`);
+    return hash;
+}
+/**
+ * Why an existing `pair-index-*.bin` is stale against `expected`, or `undefined` when its header matches. Covers the
+ * FORMAT (schemaVersion) and every calibrated magnitude; source-md5 freshness stays with the caller, because each base
+ * linker passes a different set of sources and only it knows what they are.
+ *
+ * One place so a magnitude added to the header cannot be checked by some linkers and not others — which is exactly how
+ * three of the four base linkers ended up unable to notice a schema bump.
+ */
+export function pairIndexStaleReason(header, expected) {
+    if (header.schemaVersion !== REQUIRED_PAIR_INDEX_SCHEMA) {
+        return `schemaVersion ${header.schemaVersion} → ${REQUIRED_PAIR_INDEX_SCHEMA}`;
+    }
+    if (header.delta !== expected.delta)
+        return `delta ${header.delta} → ${expected.delta}`;
+    if (header.transitionBeta !== expected.transitionBeta) {
+        return `transitionBeta ${header.transitionBeta ?? "(absent)"} → ${expected.transitionBeta ?? "(absent)"}`;
+    }
+    if (header.parentDelta !== expected.parentDelta) {
+        return `parentDelta ${header.parentDelta ?? "(absent)"} → ${expected.parentDelta ?? "(absent)"}`;
+    }
+    return undefined;
+}
+/**
+ * The PIX1 schema this tree's reader requires. MUST equal `KNOWN_SCHEMA_VERSION` in `neural/pair-index-resolver.ts` —
+ * they are two ends of one fact, and this copy exists only because a data-only overlay must not gain a dependency on
+ * `@mailwoman/neural` (onnxruntime-node) to read one header field. Bump BOTH in the same commit; a schema bump that
+ * leaves this behind makes every dev checkout rebuild-loop or serve an artifact the runtime refuses.
+ *
+ * The freshness guard must compare it: a guard that checks only delta + source md5 reads a format-obsolete binary as
+ * "current" and leaves every dev checkout with artifacts the runtime refuses — the R5 freshness-guard lesson, format
+ * edition. Also compared by the four hand-written base linkers (`neural-weights-{en-us,en-gb,en-nz,fr-fr}`), which
+ * import this constant rather than re-typing the number.
+ */
+export const REQUIRED_PAIR_INDEX_SCHEMA = 3;
+/**
+ * Warn when the per-locale FST a linker just symlinked was built from a DIFFERENT admin database than the one on disk
+ * now.
+ *
+ * WHY IT WARNS RATHER THAN REBUILDS, unlike its pair-index sibling above. A pair index is seconds of work and the
+ * linker owns its whole recipe. A locale FST is a multi-minute build whose output goes to a STAGING dir on purpose —
+ * the swap into `fst-per-locale/` is operator-gated after the battery, because an FST changes decoder behaviour and the
+ * D-rule does not let that land unmeasured. So the guard's job is to make the drift impossible to miss, and to name the
+ * command that starts fixing it. It is also why a stale FST is never fatal: the artifact is a decode-time bias list,
+ * and a dev tree must still run.
+ *
+ * The source-side half of the comparison lives here rather than in `fst-freshness.ts` for the same reason
+ * `pairIndexStaleReason` splits: only the caller knows which database it built against. All three FST-linking base
+ * packages build against the same one, so they share this rather than each pinning it.
+ */
+export function warnIfFSTStale(fstPath, locale) {
+    const warning = fstFreshnessWarning({
+        fstPath,
+        sourceDBPath: String(dataRootPath("wof", "admin-global-priority.db")),
+        rebuildCommand: `node packages/mailwoman/out/cli.js gazetteer build fst --locales ${locale}  (writes to a staging dir; swap is operator-gated)`,
+    });
+    if (warning) {
+        console.error(warning);
+    }
+}
+/**
+ * Build `pair-index-<country>.bin` into the overlay, skipping the work when the artifact on disk was already built at
+ * these magnitudes FROM the admin database on disk.
+ *
+ * The skip requires both halves (#1734): the header magnitudes (`pairIndexStaleReason`) AND the header's `sourceMD5s`
+ * against the current admin DB's md5. Magnitudes alone read a source change as "current" whenever pair counts happen
+ * not to move the calibrated numbers — the R5 freshness-guard lesson, which resurfaced in the 2026-08-18 admin swap
+ * when all four overlay locales skipped while the md5-checking base linkers rebuilt. This build's ONE source is the
+ * admin DB it passes as `--borough-db`, so the comparison is exactly one md5; a linker with a different source list
+ * (fr's BAN directory) owns its own guard and must never be pointed at this one.
+ *
+ * Exits non-zero on a failed build. Missing INPUTS (an unbuilt CLI, an absent WOF database) warn and return instead: a
+ * fresh clone has neither, and `yarn test` invokes this to verify auto-resolve, so a hard failure there would be a
+ * failure to have run a build yet rather than a real fault.
+ */
+export async function buildPairIndexOverlay({ packageDir, country, delta, transitionBeta, }) {
+    const CLI = String(workspacePath("mailwoman", "out", "cli.js"));
+    const ARTIFACT = `pair-index-${country}.bin`;
+    // Built into the data-root OVERLAY, not into the tracked package. The locale is recovered from the
+    // workspace name (`neural-weights-en-gb` → `en-gb`) so callers keep passing the one identifier they
+    // already had; the alternative was a second parameter every caller would have to keep in step with the
+    // first, which is the drift this whole rollout is removing.
+    const PKG_DIR = String(weightsOverlayPath(packageDir.replace(/^neural-weights-/, "")));
+    const DEST = resolve(PKG_DIR, ARTIFACT);
+    mkdirSync(PKG_DIR, { recursive: true });
+    /**
+     * Checked-in WOF-derived admin pairs — the same posture as the GB secondary sources.
+     */
+    const WOF_ADMIN_DB = String(dataRootPath("wof", "admin-global-priority.db"));
+    if (!existsSync(CLI)) {
+        console.error(`WARNING: ${CLI} not built — run \`yarn compile\` first, then re-run for ${ARTIFACT}.`);
+        return;
+    }
+    if (!existsSync(WOF_ADMIN_DB)) {
+        console.error(`WARNING: missing ${WOF_ADMIN_DB} — ${ARTIFACT} not built.`);
+        return;
+    }
+    if (existsSync(DEST)) {
+        try {
+            // No `parentDelta` in the expectation: the overlay locales (de/in/es/it) ship WITHOUT the whole-edge
+            // parent bias — unmeasured there, and the D-rule's answer to an unmeasured locale is a per-locale
+            // gate, not an inherited magnitude. `PairIndexOverlay` therefore has no `parentDelta` field to pass;
+            // adding one is a deliberate act that should arrive with a board.
+            const header = peekPairIndexHeaderFields(DEST);
+            const reason = pairIndexStaleReason(header, { delta, transitionBeta });
+            if (reason) {
+                console.log(`rebuilding ${ARTIFACT} — ${reason}`);
+            }
+            else {
+                // The source-md5 half (#1734). This build reads exactly one source, so one md5; an artifact that
+                // recorded none, or a different count, predates the stamp and is stale by that fact alone.
+                const adminMD5 = await md5FileWithSidecar(WOF_ADMIN_DB);
+                if (header.sourceMD5s.length === 1 && header.sourceMD5s[0] === adminMD5) {
+                    console.log(`skipped ${ARTIFACT} build — ${DEST} is current (magnitudes + source md5 match)`);
+                    return;
+                }
+                console.log(`rebuilding ${ARTIFACT} — header source md5s [${header.sourceMD5s.join(", ") || "(none recorded)"}] != ` +
+                    `current admin DB [${adminMD5}]`);
+            }
+        }
+        catch (error) {
+            console.log(`rebuilding ${ARTIFACT} — header unreadable (${error.message})`);
+        }
+    }
+    const result = spawnSync(process.execPath, [
+        CLI,
+        "gazetteer",
+        "pair-index",
+        "--out",
+        PKG_DIR,
+        "--country",
+        country,
+        "--delta",
+        String(delta),
+        "--transition-beta",
+        String(transitionBeta),
+        "--borough-db",
+        WOF_ADMIN_DB,
+    ], { stdio: "inherit" });
+    if (result.status !== 0 || !existsSync(DEST)) {
+        console.error(`FAILED: gazetteer pair-index --country ${country} (exit ${result.status})`);
+        process.exit(1);
+    }
+    console.log(`built ${ARTIFACT} ← ${WOF_ADMIN_DB}`);
+}
+//# sourceMappingURL=weights-overlay-linker.js.map

package/out/weights-overlay-linker.js.map

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