@mailwoman/resolver-wof-sqlite 8.0.0 → 8.1.0

package/out/street-segment-schema.js

@@ -52,6 +52,21 @@ export async function createStreetSegmentTable(db) {
         .addColumn("release", "text", (c) => c.notNull())
         .execute();
 }
+/**
+ * Create + populate the single-row `interp_calibration` metadata table (see {@link InterpCalibrationRow}) — called once
+ * by the shard builder, after the value is selected from the calibration source of record. Build-time only (async
+ * Kysely is fine here); the READ side is the raw sync probe in {@link StreetInterpolator}'s constructor, per the
+ * sync-by-interface doctrine.
+ */
+export async function writeInterpCalibration(db, row) {
+    await db.schema
+        .createTable("interp_calibration")
+        .addColumn("radius_multiplier", "real", (c) => c.notNull())
+        .addColumn("method", "text", (c) => c.notNull())
+        .addColumn("region", "text", (c) => c.notNull())
+        .execute();
+    await db.insertInto("interp_calibration").values(row).execute();
+}
 /** Create the two probe indexes the reader relies on (postcode-scope, street-scope). */
 export async function createStreetSegmentIndexes(db) {
     await db.schema

package/out/street-segment-schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"street-segment-schema.js","sourceRoot":"","sources":["../street-segment-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAwCH;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACrC,aAAa;IACb,MAAM;IACN,SAAS;IACT,OAAO;IACP,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,UAAU;IACV,aAAa;IACb,YAAY;IACZ,UAAU;IACV,QAAQ;IACR,SAAS;CACA,CAAA;AAEV,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,EAAiC;IAC/E,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,gBAAgB,CAAC;SAC7B,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACpD,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC7C,SAAS,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACnD,SAAS,CAAC,OAAO,EAAE,SAAS,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,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAClD,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/C,SAAS,CAAC,UAAU,EAAE,MAAM,CAAC;SAC7B,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACpD,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACnD,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACjD,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;AACZ,CAAC;AAED,wFAAwF;AACxF,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,EAAiC;IACjF,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,kBAAkB,CAAC;SAC/B,EAAE,CAAC,gBAAgB,CAAC;SACpB,OAAO,CAAC,CAAC,UAAU,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC;SAC9C,OAAO,EAAE,CAAA;IACX,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAC,gBAAgB,CAAC,CAAC,OAAO,CAAC,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE,CAAA;AAChH,CAAC"}
+{"version":3,"file":"street-segment-schema.js","sourceRoot":"","sources":["../street-segment-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAyDH;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACrC,aAAa;IACb,MAAM;IACN,SAAS;IACT,OAAO;IACP,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,UAAU;IACV,aAAa;IACb,YAAY;IACZ,UAAU;IACV,QAAQ;IACR,SAAS;CACA,CAAA;AAEV,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,EAAiC;IAC/E,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,gBAAgB,CAAC;SAC7B,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACpD,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC7C,SAAS,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACnD,SAAS,CAAC,OAAO,EAAE,SAAS,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,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAClD,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/C,SAAS,CAAC,UAAU,EAAE,MAAM,CAAC;SAC7B,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACpD,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACnD,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACjD,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;AACZ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC3C,EAAiC,EACjC,GAAyB;IAEzB,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,oBAAoB,CAAC;SACjC,SAAS,CAAC,mBAAmB,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC1D,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/C,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/C,OAAO,EAAE,CAAA;IACX,MAAM,EAAE,CAAC,UAAU,CAAC,oBAAoB,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAA;AAChE,CAAC;AAED,wFAAwF;AACxF,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,EAAiC;IACjF,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,kBAAkB,CAAC;SAC/B,EAAE,CAAC,gBAAgB,CAAC;SACpB,OAAO,CAAC,CAAC,UAAU,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC;SAC9C,OAAO,EAAE,CAAA;IACX,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAC,gBAAgB,CAAC,CAAC,OAAO,CAAC,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE,CAAA;AAChH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailwoman/resolver-wof-sqlite",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "description": "Who's On First SQLite resolver — FTS5-backed PlaceLookup that resolves text queries to WOF place IDs + coordinates. Optional dependency for callers who want geocoding.",
   "license": "AGPL-3.0-only OR LicenseRef-Commercial",
   "repository": {
@@ -46,6 +46,10 @@
       "types": "./out/street-morphology-fst-builder.d.ts",
       "default": "./out/street-morphology-fst-builder.js"
     },
+    "./street-morphology-fst-loader": {
+      "types": "./out/street-morphology-fst-loader.d.ts",
+      "default": "./out/street-morphology-fst-loader.js"
+    },
     "./fst-matcher": {
       "types": "./out/fst-matcher.d.ts",
       "default": "./out/fst-matcher.js"
@@ -151,6 +155,10 @@
         "types": "./out/street-morphology-fst-builder.d.ts",
         "default": "./out/street-morphology-fst-builder.js"
       },
+      "./street-morphology-fst-loader": {
+        "types": "./out/street-morphology-fst-loader.d.ts",
+        "default": "./out/street-morphology-fst-loader.js"
+      },
       "./fst-matcher": {
         "types": "./out/fst-matcher.d.ts",
         "default": "./out/fst-matcher.js"
@@ -234,10 +242,10 @@
     }
   },
   "dependencies": {
-    "@mailwoman/codex": "8.0.0",
-    "@mailwoman/core": "8.0.0",
-    "@mailwoman/resolver": "8.0.0",
-    "@mailwoman/spatial": "8.0.0",
+    "@mailwoman/codex": "8.1.0",
+    "@mailwoman/core": "8.1.0",
+    "@mailwoman/resolver": "8.1.0",
+    "@mailwoman/spatial": "8.1.0",
     "h3-js": "^4.5.0",
     "kysely": "^0.29.4"
   }

package/street-morphology-fst-loader.ts

@@ -0,0 +1,87 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Unified runtime loader for the street-morphology FST — the #1315 street-context gate's signal
+ *   source, previously rebuilt from the libpostal dictionaries per process at three duplicate call
+ *   sites (runtime pipeline / parity eval / neural harness). The sealed artifact
+ *   (`fst-street-morphology.bin`, built by `mailwoman gazetteer build street-morphology`) replaces
+ *   those per-process builds; this loader is the ONE resolution ladder every node call site shares:
+ *
+ *   1. An explicit `artifactPath` (e.g. the weights-package sibling surfaced by
+ *      `NeuralAddressClassifier.streetMorphologyPath`). When given, it is the only artifact probed.
+ *   2. Otherwise the staged sealed artifact at `$MAILWOMAN_DATA_ROOT/wof/fst-street-morphology.bin`.
+ *   3. Build-from-dictionaries fallback: `buildStreetMorphologyFST` over core's bundled libpostal
+ *      `street_types.txt` files — the pre-artifact behavior, kept so a missing artifact degrades to
+ *      a per-process build rather than a crash.
+ *
+ *   A present-but-unreadable artifact reports through `onWarn` and falls through to the build rung.
+ *   Browsers can't take the fallback (no fs) — they deserialize the same artifact via
+ *   `fst-deserialize-web.ts` (see the docs demo loader).
+ */
+
+import { existsSync, readFileSync } from "node:fs"
+
+import { dataRootPath, resourceDictionaryPath } from "@mailwoman/core/utils"
+
+import type { FSTMatcher } from "./fst-matcher.ts"
+import { deserializeFST, readFSTProvenance } from "./fst-serialize.ts"
+import type { FSTProvenance } from "./fst-types.ts"
+import { buildStreetMorphologyFST } from "./street-morphology-fst-builder.ts"
+
+/** The sealed artifact's canonical filename — identical in the data-root staging dir and as a weights-package sibling. */
+export const STREET_MORPHOLOGY_ARTIFACT_FILENAME = "fst-street-morphology.bin"
+
+/** The staged artifact's default location: `$MAILWOMAN_DATA_ROOT/wof/fst-street-morphology.bin`. */
+export function defaultStreetMorphologyArtifactPath(): string {
+	return String(dataRootPath("wof", STREET_MORPHOLOGY_ARTIFACT_FILENAME))
+}
+
+export interface LoadStreetMorphologyFSTOpts {
+	/**
+	 * Explicit artifact path (e.g. a weights-package sibling). When given it is the ONLY artifact probed — missing or
+	 * unreadable degrades straight to the dictionary build, never a throw.
+	 */
+	artifactPath?: string
+	/** Dictionaries dir for the build fallback. Defaults to core's bundled libpostal dictionaries. */
+	dictionariesDir?: string
+	/** Unreadable-artifact diagnostics. Defaults to silent (the caller owns its warn channel). */
+	onWarn?: (message: string) => void
+}
+
+export interface LoadedStreetMorphologyFST {
+	matcher: FSTMatcher
+	/** Which rung produced the matcher: a sealed-artifact deserialize, or the per-process dictionary build. */
+	source: "artifact" | "built"
+	/** The artifact path when `source === "artifact"`. */
+	path?: string
+	/** Build provenance — read from the artifact trailer, or carried fresh off the fallback build. */
+	provenance?: FSTProvenance
+}
+
+/** Load the street-morphology matcher: sealed artifact first, per-process dictionary build as the degrade path. */
+export function loadStreetMorphologyFST(opts: LoadStreetMorphologyFSTOpts = {}): LoadedStreetMorphologyFST {
+	const warn = opts.onWarn ?? (() => {})
+	const artifactPath = opts.artifactPath ?? defaultStreetMorphologyArtifactPath()
+
+	if (existsSync(artifactPath)) {
+		try {
+			const buf = readFileSync(artifactPath)
+			const matcher = deserializeFST(buf)
+			const provenance = readFSTProvenance(buf)
+
+			return { matcher, source: "artifact", path: artifactPath, ...(provenance ? { provenance } : {}) }
+		} catch (err) {
+			warn(
+				`street-morphology artifact at ${artifactPath} unreadable (${(err as Error).message}) — falling back to the dictionary build`
+			)
+		}
+	}
+
+	const built = buildStreetMorphologyFST({
+		dictionariesDir: opts.dictionariesDir ?? resourceDictionaryPath("libpostal"),
+	})
+
+	return { matcher: built.matcher, source: "built", provenance: built.provenance }
+}

package/street-segment-schema.ts

@@ -48,9 +48,26 @@ export interface StreetSegmentTable {
 	release: string
 }
 
+/**
+ * The shard's single-row calibration metadata (#374 doctrine, 2026-07-26): the conformal radius multiplier is a
+ * property of the CALIBRATION SET the artifact was built against — so it ships IN the artifact (the pair-index δ
+ * precedent, `neural/pair-index-resolver.ts`), not in caller code. Written once by the builder; read at open time by
+ * {@link StreetInterpolator}. Shards built before this table exists simply lack it — the reader degrades to `undefined`
+ * and callers fall back to the in-code per-region table (never patch shipped DBs — rebuild).
+ */
+export interface InterpCalibrationRow {
+	/** Conformal multiplier for the raw half-segment `uncertainty_m` radius (#374/#584) — ×Q̂ for a ~90% bound. */
+	radius_multiplier: number
+	/** Provenance of the multiplier (e.g. `split-conformal:2026-06-14`). */
+	method: string
+	/** The calibration-table key the multiplier was selected by (a USPS region code, or `default` for unmeasured). */
+	region: string
+}
+
 /** The street-segment database schema for `new DatabaseClient<StreetSegmentDatabase>(...)`. */
 export interface StreetSegmentDatabase {
 	street_segment: StreetSegmentTable
+	interp_calibration: InterpCalibrationRow
 }
 
 /**
@@ -93,6 +110,25 @@ export async function createStreetSegmentTable(db: Kysely<StreetSegmentDatabase>
 		.execute()
 }
 
+/**
+ * Create + populate the single-row `interp_calibration` metadata table (see {@link InterpCalibrationRow}) — called once
+ * by the shard builder, after the value is selected from the calibration source of record. Build-time only (async
+ * Kysely is fine here); the READ side is the raw sync probe in {@link StreetInterpolator}'s constructor, per the
+ * sync-by-interface doctrine.
+ */
+export async function writeInterpCalibration(
+	db: Kysely<StreetSegmentDatabase>,
+	row: InterpCalibrationRow
+): Promise<void> {
+	await db.schema
+		.createTable("interp_calibration")
+		.addColumn("radius_multiplier", "real", (c) => c.notNull())
+		.addColumn("method", "text", (c) => c.notNull())
+		.addColumn("region", "text", (c) => c.notNull())
+		.execute()
+	await db.insertInto("interp_calibration").values(row).execute()
+}
+
 /** Create the two probe indexes the reader relies on (postcode-scope, street-scope). */
 export async function createStreetSegmentIndexes(db: Kysely<StreetSegmentDatabase>): Promise<void> {
 	await db.schema