mailwoman 8.0.0 → 8.1.0

package/api-engine.ts

@@ -332,12 +332,16 @@ export async function createServeEngine(): Promise<ServeEngine> {
 				...incomingOpts,
 				defaultCountry: incomingOpts.defaultCountry ?? deps.defaultCountry,
 				...(addressPoints ? { addressPoints } : {}),
+				// #374 calibration ladder: explicit incoming factor (instrument override, survives the spread) →
+				// the artifact's own header value (`interpolation.radiusCalibration`, read at shard open — the
+				// resolver consumes it directly, nothing passed here) → the in-code per-region table for shards
+				// predating the `interp_calibration` metadata table.
 				...(interpolation
 					? {
 							interpolation,
-							interpolationRadiusCalibration:
-								incomingOpts.interpolationRadiusCalibration ??
-								interpCalibrationForRegion(INTERP_RADIUS_CALIBRATION, slug),
+							...(incomingOpts.interpolationRadiusCalibration == null && interpolation.radiusCalibration == null
+								? { interpolationRadiusCalibration: interpCalibrationForRegion(INTERP_RADIUS_CALIBRATION, slug) }
+								: {}),
 						}
 					: {}),
 			}

package/commands/gazetteer/build/fst.tsx

@@ -0,0 +1,60 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman gazetteer build fst` — per-locale decode-bias FST gazetteers (`fst-<locale>.bin`,
+ *   #1318) with build-time degenerate-surface curation. Artifacts land in a staging dir BESIDE the
+ *   shipped `fst-per-locale/` (never overwriting); the swap is operator-gated after the battery. See
+ *   `mailwoman/gazetteer-pipeline/fst.ts` for the curation policy.
+ */
+
+import { Text } from "ink"
+import zod from "zod"
+
+import { type CommandComponent, useCommandTask } from "../../../cli-kit/index.ts"
+
+const OptionsSchema = zod.object({
+	locales: zod.string().optional().describe("Comma-separated locales (default: all shipped FST locales)"),
+	db: zod.string().optional().describe("WOF admin DB (default: $MAILWOMAN_DATA_ROOT/wof/admin-global-priority.db)"),
+	output: zod.string().optional().describe("Output dir (default: $MAILWOMAN_DATA_ROOT/wof/fst-per-locale-curated)"),
+	uncurated: zod.boolean().default(false).describe("A/B control build: same DB, no curation"),
+})
+
+export { OptionsSchema as options }
+
+const GazetteerBuildFST: CommandComponent<typeof OptionsSchema> = ({ options }) => {
+	const state = useCommandTask(async () => {
+		const { buildLocaleFSTs } = await import("../../../gazetteer-pipeline/fst.ts")
+		const built = buildLocaleFSTs({
+			locales: options.locales?.split(",").map((s) => s.trim()),
+			dbPath: options.db,
+			outputDir: options.output,
+			uncurated: options.uncurated,
+			onProgress: (line) => console.error(line),
+		})
+
+		return built.map(
+			(b) =>
+				`fst-${b.locale} → ${b.path} (${(b.bytes / 1e6).toFixed(1)} MB, ${b.nameInsertions} insertions, ${b.excludedInsertions} excluded)`
+		)
+	})
+
+	if (state.status === "error") return <Text color="red">✗ {state.message}</Text>
+
+	if (state.status === "done") {
+		return (
+			<>
+				{state.result.map((line, i) => (
+					<Text key={i} color="green">
+						✓ {line}
+					</Text>
+				))}
+			</>
+		)
+	}
+
+	return null
+}
+
+export default GazetteerBuildFST

package/commands/gazetteer/build/street-morphology.tsx

@@ -0,0 +1,54 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman gazetteer build street-morphology` — the sealed street-morphology FST artifact
+ *   (`fst-street-morphology.bin`), the #1315 street-context gate's signal source serialized once at
+ *   build time instead of rebuilt from the libpostal dictionaries per process (and never in the
+ *   browser). Lands at `$MAILWOMAN_DATA_ROOT/wof/` by default — beside, never inside, the
+ *   per-locale FST dir. See `mailwoman/gazetteer-pipeline/street-morphology.ts` for the rationale.
+ */
+
+import { Text } from "ink"
+import zod from "zod"
+
+import { type CommandComponent, useCommandTask } from "../../../cli-kit/index.ts"
+
+const OptionsSchema = zod.object({
+	dictionaries: zod
+		.string()
+		.optional()
+		.describe("libpostal dictionaries root (default: core's bundled data/libpostal/dictionaries)"),
+	locales: zod
+		.string()
+		.optional()
+		.describe("Comma-separated locale subfolders (default: every locale with a street_types.txt)"),
+	output: zod.string().optional().describe("Output path (default: $MAILWOMAN_DATA_ROOT/wof/fst-street-morphology.bin)"),
+})
+
+export { OptionsSchema as options }
+
+const GazetteerBuildStreetMorphology: CommandComponent<typeof OptionsSchema> = ({ options }) => {
+	const state = useCommandTask(async () => {
+		const { buildStreetMorphologyArtifact } = await import("../../../gazetteer-pipeline/street-morphology.ts")
+		const built = buildStreetMorphologyArtifact({
+			dictionariesDir: options.dictionaries,
+			locales: options.locales?.split(",").map((s) => s.trim()),
+			output: options.output,
+			onProgress: (line) => console.error(line),
+		})
+
+		return `${built.path} (${(built.bytes / 1e3).toFixed(0)} kB, ${built.canonicalCount} canonicals, ${built.variantCount} variants, ${built.localeCount} locales)`
+	})
+
+	if (state.status === "error") return <Text color="red">✗ {state.message}</Text>
+
+	if (state.status === "done") {
+		return <Text color="green">✓ {state.result}</Text>
+	}
+
+	return null
+}
+
+export default GazetteerBuildStreetMorphology

package/commands/geocode.tsx

@@ -120,9 +120,10 @@ const OptionsSchema = zod.object({
 		.optional()
 		.describe(
 			"Conformal calibration multiplier for the interpolation tier's reported uncertainty_m (#374). " +
-				"The raw half-segment radius covers only ~72% of true errors. Default (unset): the per-region " +
-				"table (#584) selects by parsed region — 1.44 (DC) … 3.12 (AZ), 1.95 for unmeasured states — " +
-				"for a ~90% bound. Pass an explicit number to force a single multiplier everywhere (1 = raw)."
+				"The raw half-segment radius covers only ~72% of true errors. Default (unset): the shard's own " +
+				"baked value (its interp_calibration metadata table) when it carries one, else the in-code " +
+				"per-region table (#584) selected by parsed region — 1.44 (DC) … 3.12 (AZ), 1.95 for unmeasured " +
+				"states — for a ~90% bound. Pass an explicit number to force a single multiplier everywhere (1 = raw)."
 		),
 	placeCountry: zod
 		.boolean()

package/commands/situs/interpolation-shard.tsx

@@ -35,6 +35,15 @@ import { Box, Text } from "ink"
 import zod from "zod"
 
 import { type CommandComponent, commandError, useCommandTask } from "../../cli-kit/index.ts"
+import { INTERP_RADIUS_CALIBRATION } from "../../interp-calibration.ts"
+
+/**
+ * Provenance tag for the baked `interp_calibration` row — the split-conformal multi-region recalibration this build
+ * selects its multiplier from (`docs/articles/evals/calibration/2026-06-14-interp-multiregion-recalibration.md`). Bump
+ * when the calibration source of record (`interp-calibration.ts` / `data/calibration/interp-radius-conformal.json`) is
+ * re-measured.
+ */
+const CALIBRATION_METHOD = "split-conformal:2026-06-14"
 
 /** State abbreviation → state FIPS prefix, for picking county files out of --edges-dir. */
 const STATE_FIPS: Record<string, string> = {
@@ -183,7 +192,8 @@ const SitusInterpolationShard: CommandComponent<typeof OptionsSchema> = ({ optio
 				"@duckdb/node-api is not installed — `situs interpolation-shard` is a maintainer-only data command"
 			)
 		}
-		const { STREET_SEGMENT_COLUMNS, createStreetSegmentTable, createStreetSegmentIndexes } = segmentSchema
+		const { STREET_SEGMENT_COLUMNS, createStreetSegmentTable, createStreetSegmentIndexes, writeInterpCalibration } =
+			segmentSchema
 		const { canonicalizeRouteKey, normalizeStreetForKey } = streetNormalize
 
 		const shapefiles = globSync(`${options.edgesDir}/tl_*_${STATE_FIPS[STATE]}???_edges.shp`).sort()
@@ -209,6 +219,17 @@ const SitusInterpolationShard: CommandComponent<typeof OptionsSchema> = ({ optio
 		// producer can't drift. DuckDB below is the raw spatial reader; the hot INSERT stays on `db`.
 		const kdb = new DatabaseClient<StreetSegmentDatabase>({ database: db })
 		await createStreetSegmentTable(kdb)
+		// #374 doctrine: the conformal radius multiplier is a property of the calibration set, so it ships IN
+		// the artifact — bake the state's factor (or the conservative default for unmeasured states) into the
+		// shard's `interp_calibration` metadata table. `StreetInterpolator` reads it at open time; callers
+		// stop carrying the number.
+		const measuredMultiplier = INTERP_RADIUS_CALIBRATION.byRegion[STATE]
+		const calibration = {
+			radius_multiplier: measuredMultiplier ?? INTERP_RADIUS_CALIBRATION.default,
+			method: CALIBRATION_METHOD,
+			region: measuredMultiplier === undefined ? "default" : STATE,
+		}
+		await writeInterpCalibration(kdb, calibration)
 		const insert = db.prepare(
 			`INSERT INTO street_segment (${STREET_SEGMENT_COLUMNS.join(", ")})
 					 VALUES (${STREET_SEGMENT_COLUMNS.map(() => "?").join(", ")})`
@@ -300,6 +321,7 @@ const SitusInterpolationShard: CommandComponent<typeof OptionsSchema> = ({ optio
 			`distinct streets: ${stats.streets} · postcodes: ${stats.postcodes}`,
 			`parity: odd ${parityCounts.odd} · even ${parityCounts.even} · mixed ${parityCounts.mixed}`,
 			`skipped non-numeric ranges: ${skippedNonNumeric}`,
+			`baked radius calibration: ×${calibration.radius_multiplier} (${calibration.region}, ${calibration.method})`,
 		]
 	})
 

package/eval-harness/parity-corpus.ts

@@ -98,11 +98,14 @@ export async function runParityEval(options: ParityEvalOptions = {}): Promise<Pa
 	let fstStreetMorphology: import("@mailwoman/resolver-wof-sqlite/fst-matcher").FSTMatcher | undefined
 
 	if (options.streetMorphology) {
-		const { buildStreetMorphologyFST } = await import("@mailwoman/resolver-wof-sqlite/street-morphology-fst-builder")
-		const built = buildStreetMorphologyFST({ dictionariesDir: "core/data/libpostal/dictionaries" })
-		fstStreetMorphology = built.matcher
+		// Sealed-artifact-first (static-index candidate 1): the loader's shared ladder — data-root
+		// `fst-street-morphology.bin`, degrading to the per-process dictionary build this site used to
+		// inline (with a cwd-relative dictionaries path, no less).
+		const { loadStreetMorphologyFST } = await import("@mailwoman/resolver-wof-sqlite/street-morphology-fst-loader")
+		const loaded = loadStreetMorphologyFST({ onWarn: (message) => console.warn(message) })
+		fstStreetMorphology = loaded.matcher
 		console.log(
-			`street-morphology bias ON: ${built.locales.length} locales, ${built.variantCount} variants (${built.canonicalCount} canonical)`
+			`street-morphology bias ON (${loaded.source === "artifact" ? `sealed artifact ${loaded.path}` : "per-process dictionary build"}${loaded.provenance ? `: ${loaded.provenance.placeCount} canonical affixes, ${loaded.provenance.nameInsertions} variant insertions` : ""})`
 		)
 	}
 

package/gazetteer-pipeline/coverage-manifest.ts

@@ -0,0 +1,163 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The MEASURED COVERAGE RECORD for the candidate gazetteer + its build-time emission (survey
+ *   candidate #2, 2026-07-26) — the durable home for two sets of facts that used to be hand-grown
+ *   code constants updated by PR-after-someone-remembers:
+ *
+ *   - The hard-country-filter coverage measurements (#743/#194) behind
+ *     `HARD_PLACE_COUNTRY_SAFELIST` (`core/pipeline/runtime-pipeline.ts`) — previously a code
+ *     comment ("US 100, FR 100 … FI 69.5 (out)"), i.e. measurement as trivia.
+ *   - The guard-B plausibility boxes behind `COUNTRY_BBOX` (`resolver/plausibility.ts`).
+ *
+ *   Doctrine (operator-ratified 2026-07-26): facts ABOUT an artifact live in the artifact's
+ *   manifest, read at load — so they update at gazetteer REBUILD, not at a code PR. This module is
+ *   the drawer: it owns the reviewed measurement record ({@link MEASURED_COUNTRY_COVERAGE},
+ *   {@link MEASURED_COUNTRY_BBOXES} — grow THESE at promotes, like `defaults.ts` owns the build
+ *   recipe) and the emission step `buildCandidate` runs before sealing. The schema + canonical
+ *   read/write functions live in `@mailwoman/resolver-wof-sqlite/coverage-manifest-schema` (the
+ *   fold/build convention: canonical package functions, composed here).
+ *
+ *   The SHIPPED candidate gazetteer is never patched ("never patch databases — rebuild"): an
+ *   artifact predating the manifest reads `undefined` at open and every consumer falls back to the
+ *   code constants byte-identically. The meaning-of-zero rule is honored structurally: FI/PL are
+ *   PRESENT rows with `hardFilterSafe: false` (measured, failed the gate) — distinguishable from a
+ *   country that was simply never measured (absent row).
+ */
+
+import { DatabaseSync } from "node:sqlite"
+
+import { DatabaseClient } from "@mailwoman/core/kysley/client"
+import type { CountryBBoxFact, CountryCoverageFact } from "@mailwoman/core/resolver"
+// resolver-wof-sqlite is an optional peer of mailwoman (the geocode.tsx convention) — runtime
+// imports are DYNAMIC inside the functions; type-only imports are erased and safe at module level.
+import type { GazetteerCoverageDatabase } from "@mailwoman/resolver-wof-sqlite"
+
+/** Shared source string for the #743 promote measurements. */
+const OA_PANEL_SOURCE = "#743 OA held-out hard-resolve panel (DeepSeek-advised gate, 2026-06-22)"
+
+/** Shared source string for the #928 promote OSM panels. */
+const OSM_PANEL_SOURCE = "#928 promote OSM panel, night 34 (2026-07-06)"
+
+/**
+ * The reviewed per-country hard-filter coverage record — every promote-gate verdict + measurement that grew (or
+ * deliberately kept a country off) the hard-country safelist. This is the structured form of the receipts that lived in
+ * the `HARD_PLACE_COUNTRY_SAFELIST` code comment; the derived safelist (`hardFilterSafe === true`) is asserted
+ * byte-identical to that constant in `coverage-manifest.test.ts`, so the two cannot drift silently.
+ *
+ * Grow THIS at promotes (with the panel receipt in `source`); the fact reaches production at the next gazetteer rebuild
+ * — the constant in core is only the fallback for artifacts predating the manifest.
+ */
+export const MEASURED_COUNTRY_COVERAGE: readonly CountryCoverageFact[] = [
+	{ country: "US", hardFilterSafe: true, hardResolveRate: 1.0, measuredAt: "2026-06-22", source: OA_PANEL_SOURCE },
+	{ country: "FR", hardFilterSafe: true, hardResolveRate: 1.0, measuredAt: "2026-06-22", source: OA_PANEL_SOURCE },
+	{ country: "DE", hardFilterSafe: true, hardResolveRate: 1.0, measuredAt: "2026-06-22", source: OA_PANEL_SOURCE },
+	{ country: "ES", hardFilterSafe: true, hardResolveRate: 0.998, measuredAt: "2026-06-22", source: OA_PANEL_SOURCE },
+	{ country: "NL", hardFilterSafe: true, hardResolveRate: 0.973, measuredAt: "2026-06-22", source: OA_PANEL_SOURCE },
+	{ country: "IT", hardFilterSafe: true, hardResolveRate: 0.968, measuredAt: "2026-06-22", source: OA_PANEL_SOURCE },
+	// Measured and FAILED the gate — present rows on purpose (meaning-of-zero: a failed measurement is a
+	// first-class negative result, distinguishable from "never measured"). They stay on the soft prior
+	// until their gazetteer coverage is filled (#193).
+	{ country: "FI", hardFilterSafe: false, hardResolveRate: 0.695, measuredAt: "2026-06-22", source: OA_PANEL_SOURCE },
+	{ country: "PL", hardFilterSafe: false, hardResolveRate: 0.778, measuredAt: "2026-06-22", source: OA_PANEL_SOURCE },
+	// #928 promote (2026-07-06): the postcodeCountryPrior FORMAT signal routes GB/CA confidently (the
+	// language placer conflated both with US), and the OSM-panel gates passed with the hard filter ON.
+	// Rates here are the panels' RESOLVE rates (1 − unresolved/n): GB 293/300 (271 ok, 7 unresolved),
+	// CA 269/300 (200 ok, 31 unresolved) — CA cleared on the format-prior rationale despite the sub-95%
+	// panel number, which is exactly why `hardFilterSafe` is a stored VERDICT, not a rate threshold.
+	{
+		country: "GB",
+		hardFilterSafe: true,
+		hardResolveRate: 0.977,
+		sampleSize: 300,
+		measuredAt: "2026-07-06",
+		source: OSM_PANEL_SOURCE,
+	},
+	{
+		country: "CA",
+		hardFilterSafe: true,
+		hardResolveRate: 0.897,
+		sampleSize: 300,
+		measuredAt: "2026-07-06",
+		source: OSM_PANEL_SOURCE,
+	},
+	// AU added with the #244 AU placer class: 150k-row G-NAF training → AU test-acc 100%, and the hard
+	// filter is recall-SAFE on the AU panel (unresolved 4→2 while abroad 43→20). No single-rate number
+	// in the receipt → no `hardResolveRate` (never invent a magnitude).
+	{
+		country: "AU",
+		hardFilterSafe: true,
+		measuredAt: "2026-07-06",
+		source: "#244 AU placer-class promote (2026-07-06): hard filter recall-safe (unresolved 4→2, abroad 43→20)",
+	},
+]
+
+/** Shared source string for the guard-B boxes. */
+const BBOX_SOURCE = "2026-07-15 coordinate-parity receipt harness (scratchpad/coord-parity.mjs) — deliberately coarse"
+
+const bbox = (country: string, latMin: number, latMax: number, lonMin: number, lonMax: number): CountryBBoxFact => ({
+	country,
+	latMin,
+	latMax,
+	lonMin,
+	lonMax,
+	source: BBOX_SOURCE,
+})
+
+/**
+ * The reviewed guard-B bounding-box record — the structured form of `COUNTRY_BBOX` (`resolver/plausibility.ts`),
+ * asserted byte-identical to that constant in `coverage-manifest.test.ts`. Same growth discipline as
+ * {@link MEASURED_COUNTRY_COVERAGE}: add boxes HERE; the constant is only the pre-manifest fallback.
+ */
+export const MEASURED_COUNTRY_BBOXES: readonly CountryBBoxFact[] = [
+	bbox("US", 18, 72, -180, -66),
+	bbox("AU", -44, -10, 112, 154),
+	bbox("BR", -34, 6, -74, -34),
+	bbox("CZ", 48, 51.5, 12, 19),
+	bbox("DE", 47, 55.5, 5.5, 15.5),
+	bbox("ES", 35, 44, -10, 5),
+	bbox("FR", 41, 51.5, -5.5, 9.8),
+	bbox("GB", 49, 61, -8.7, 2),
+	bbox("HR", 42, 46.6, 13, 19.5),
+	bbox("IN", 6, 36, 68, 98),
+	bbox("NL", 50.7, 53.7, 3.3, 7.3),
+	bbox("NO", 57, 71.5, 4, 31),
+	bbox("PL", 49, 55, 14, 24.2),
+	bbox("PT", 36.5, 42.2, -9.6, -6.1),
+	bbox("RO", 43.5, 48.3, 20, 30),
+	bbox("SE", 55, 69.1, 10.9, 24.2),
+	bbox("SK", 47.7, 49.7, 16.8, 22.6),
+	bbox("SI", 45.4, 46.9, 13.3, 16.6),
+]
+
+export interface EmitCoverageManifestOptions {
+	/** The candidate DB under construction — MUST be pre-seal (a shipped DB is never patched, rebuild instead). */
+	dbPath: string
+	/** Coverage rows to bake (default {@link MEASURED_COUNTRY_COVERAGE}). */
+	coverage?: readonly CountryCoverageFact[]
+	/** Guard-B bbox rows to bake (default {@link MEASURED_COUNTRY_BBOXES}). */
+	bboxes?: readonly CountryBBoxFact[]
+}
+
+/**
+ * Bake the coverage manifest into a candidate DB under construction. Called by `buildCandidate` between the candidate
+ * build and the seal; standalone use is fine for tests/fixtures (never against a sealed artifact).
+ */
+export async function emitCoverageManifest(opts: EmitCoverageManifestOptions): Promise<void> {
+	const { writeGazetteerCoverageManifest } = await import("@mailwoman/resolver-wof-sqlite")
+
+	const db = new DatabaseSync(opts.dbPath)
+	const kdb = new DatabaseClient<GazetteerCoverageDatabase>({ database: db })
+
+	try {
+		await writeGazetteerCoverageManifest(kdb, {
+			coverage: opts.coverage ?? MEASURED_COUNTRY_COVERAGE,
+			bboxes: opts.bboxes ?? MEASURED_COUNTRY_BBOXES,
+		})
+	} finally {
+		// `kdb` wraps the same handle; destroy() owns the close.
+		await kdb.destroy()
+	}
+}

package/gazetteer-pipeline/fst.ts

@@ -0,0 +1,213 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Per-locale FST gazetteer build (`mailwoman gazetteer build fst`) — the decode-bias FST shipped as
+ *   `fst-<locale>.bin` in the weights packages (#1318), rebuilt WITH degenerate-surface curation.
+ *
+ *   THE CURATION (the "serialize runtime decisions into static indexes" doctrine): a name whose whole
+ *   normalized surface is a bare function word ("la" — the case-folded Los Angeles alias colliding
+ *   with the French article), a bare street-type word ("boulevard", "lane" — real US places that are
+ *   street vocabulary everywhere else), or a composition of nothing but function words ("de la") is
+ *   NEVER inserted as a bias key. This is the ASR-contextual-biasing "prune the bias list" discipline
+ *   and Carmen's index-time token hygiene: the hazard is removed from the artifact rather than
+ *   guarded at decode time, so it cannot misfire on lowercase, comma-free, any-locale input. The FST
+ *   is a bias list, not the gazetteer of record — the resolver's candidate tables are untouched, so
+ *   excluded places stay findable; they just stop nudging the decoder on degenerate keys.
+ *
+ *   Exclusion sources are the SHIPPED libpostal dictionaries (`core/data/libpostal/dictionaries/`):
+ *   per-language `stopwords.txt` (whole-surface + compositional clauses) and `street_types.txt`
+ *   (whole-surface clause only — "Avenue Road" is a real name; "de la" is not). The language set is
+ *   the served Latin-script tiers, uniform across locales (a FR query hits the en-us FST on the
+ *   default path, so per-locale language scoping would under-curate).
+ *
+ *   Provenance (policy string + excluded-insertion count) is recorded in the artifact trailer.
+ *   Artifacts are written to --output (default: a `fst-per-locale-curated/` sibling of the shipped
+ *   `fst-per-locale/` dir) — staged BESIDE, never overwriting; the swap into the shipped path is
+ *   operator-gated after the battery.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { join, resolve } from "node:path"
+
+import { dataRootPath, repoRootPathBuilder } from "@mailwoman/core/utils"
+import { buildFSTFromWOF } from "@mailwoman/resolver-wof-sqlite/fst-builder"
+import { normalizeTokens } from "@mailwoman/resolver-wof-sqlite/fst-matcher"
+import { serializeFST } from "@mailwoman/resolver-wof-sqlite/fst-serialize"
+
+/** The served Latin-script language tiers (see SCOPE.mdx) — uniform curation set for every locale FST. */
+export const CURATION_LANGUAGES = [
+	"en",
+	"fr",
+	"de",
+	"nl",
+	"es",
+	"it",
+	"pt",
+	"da",
+	"nb",
+	"sv",
+	"fi",
+	"pl",
+	"cs",
+	"sk",
+	"sl",
+	"hr",
+	"hu",
+] as const
+
+export const EXCLUSION_POLICY_ID =
+	"degenerate-surface-exclusion v1.1 (libpostal stopwords+street_types, 17 langs, + supplemental)"
+
+/**
+ * Function-word surfaces the libpostal dictionaries MISS. Each entry carries its justification — this list is curated,
+ * not a dumping ground; a candidate belongs here only when it is a common function word in a served language whose
+ * libpostal stopword file lacks the bare form.
+ */
+export const SUPPLEMENTAL_DEGENERATE_SURFACES: ReadonlySet<string> = new Set([
+	// Dutch/Danish preposition ("op de hoek", "op til") — absent from libpostal nl/da stopwords.txt as
+	// a bare word. Shipped-index victim: the Overland Park "OP" initialism alias (wof 85945755).
+	"op",
+])
+
+/** The shipped per-locale FST set (provenance-recovered country scoping; en-nz deliberately has none). */
+export const FST_LOCALES: ReadonlyMap<string, string[]> = new Map([
+	["en-us", ["US"]],
+	["fr-fr", ["FR"]],
+	["en-gb", ["GB"]],
+	["de-de", ["DE"]],
+])
+
+/** One dictionary line = canonical|variant|variant… — every pipe-separated form is a surface. */
+function surfacesOfLine(line: string): string[] {
+	return line
+		.split("|")
+		.map((s) => s.trim())
+		.filter(Boolean)
+}
+
+/**
+ * Load the degenerate-surface exclusion sets from the shipped libpostal dictionaries. Returns normalized-join keys
+ * (`normalizeTokens(surface).join(" ")`) so they compare exactly against the builder's insertion keys.
+ */
+export function loadDegenerateSurfaces(languages: readonly string[] = CURATION_LANGUAGES): {
+	surfaces: Set<string>
+	stopwordTokens: Set<string>
+} {
+	const dictionariesDir = String(repoRootPathBuilder("core", "data", "libpostal", "dictionaries"))
+	const surfaces = new Set<string>()
+	const stopwordTokens = new Set<string>()
+
+	for (const lang of languages) {
+		for (const [file, isStopwords] of [
+			["stopwords.txt", true],
+			["street_types.txt", false],
+		] as const) {
+			const path = join(dictionariesDir, lang, file)
+
+			if (!existsSync(path)) continue
+
+			for (const line of readFileSync(path, "utf8").split("\n")) {
+				for (const surface of surfacesOfLine(line)) {
+					const tokens = normalizeTokens(surface)
+
+					if (tokens.length === 0) continue
+					surfaces.add(tokens.join(" "))
+
+					// Compositional clause sources from stopwords ONLY — single-token entries, so
+					// multi-word stopword phrases ("à côté de") never leak their content words in.
+					if (isStopwords && tokens.length === 1) {
+						stopwordTokens.add(tokens[0]!)
+					}
+				}
+			}
+		}
+	}
+
+	for (const s of SUPPLEMENTAL_DEGENERATE_SURFACES) {
+		const tokens = normalizeTokens(s)
+
+		if (tokens.length === 0) continue
+		surfaces.add(tokens.join(" "))
+
+		if (tokens.length === 1) {
+			stopwordTokens.add(tokens[0]!)
+		}
+	}
+
+	return { surfaces, stopwordTokens }
+}
+
+export interface BuildLocaleFSTsOpts {
+	/** Locales to build (default: every FST_LOCALES key). */
+	locales?: string[]
+	/** WOF admin DB (default: `$MAILWOMAN_DATA_ROOT/wof/admin-global-priority.db`). */
+	dbPath?: string
+	/** Output dir (default: `$MAILWOMAN_DATA_ROOT/wof/fst-per-locale-curated`). Never the shipped dir. */
+	outputDir?: string
+	/** Skip the curation (an A/B control build with the SAME current DB). */
+	uncurated?: boolean
+	onProgress?: (line: string) => void
+}
+
+export interface BuiltLocaleFST {
+	locale: string
+	path: string
+	bytes: number
+	nameInsertions: number
+	excludedInsertions: number
+}
+
+export function buildLocaleFSTs(opts: BuildLocaleFSTsOpts = {}): BuiltLocaleFST[] {
+	const locales = opts.locales ?? [...FST_LOCALES.keys()]
+	const dbPath = opts.dbPath ?? String(dataRootPath("wof", "admin-global-priority.db"))
+	const outputDir = resolve(opts.outputDir ?? String(dataRootPath("wof", "fst-per-locale-curated")))
+	const progress = opts.onProgress ?? (() => {})
+
+	const exclusion = opts.uncurated ? undefined : loadDegenerateSurfaces()
+
+	if (exclusion) {
+		progress(
+			`curation: ${exclusion.surfaces.size} whole surfaces + ${exclusion.stopwordTokens.size} stopword tokens (${EXCLUSION_POLICY_ID})`
+		)
+	}
+	mkdirSync(outputDir, { recursive: true })
+
+	const built: BuiltLocaleFST[] = []
+
+	for (const locale of locales) {
+		const countries = FST_LOCALES.get(locale)
+
+		if (!countries) throw new Error(`unknown FST locale ${locale} — add it to FST_LOCALES with its country scope`)
+
+		progress(`building fst-${locale} (countries=[${countries}]) from ${dbPath}`)
+		const { matcher, provenance } = buildFSTFromWOF({
+			dbPath,
+			countries,
+			...(exclusion
+				? {
+						excludeSurfaces: exclusion.surfaces,
+						excludeAllTokensOf: exclusion.stopwordTokens,
+						exclusionPolicy: EXCLUSION_POLICY_ID,
+					}
+				: {}),
+			onProgress: (phase, detail) => progress(`  [${phase}] ${detail ?? ""}`),
+		})
+		const outPath = join(outputDir, `fst-${locale}${opts.uncurated ? ".uncurated" : ""}.bin`)
+		const bytes = serializeFST(matcher, provenance)
+		writeFileSync(outPath, bytes)
+		built.push({
+			locale,
+			path: outPath,
+			bytes: bytes.length,
+			nameInsertions: provenance.nameInsertions,
+			excludedInsertions: provenance.excludedInsertions ?? 0,
+		})
+		progress(
+			`  wrote ${outPath} (${(bytes.length / 1e6).toFixed(1)} MB, ${provenance.nameInsertions} insertions, ${provenance.excludedInsertions ?? 0} excluded)`
+		)
+	}
+
+	return built
+}

package/gazetteer-pipeline/index.ts

@@ -40,6 +40,7 @@ import type { GeonamesIngestProgress } from "@mailwoman/resolver-wof-sqlite"
 import type { BuildCandidateResult } from "@mailwoman/resolver-wof-sqlite/build-candidate"
 
 import { mailwomanDataRoot } from "../resolver-backend.ts"
+import { emitCoverageManifest } from "./coverage-manifest.ts"
 
 /**
  * The bilingual / alt-name EU set the GeoNames fold lifts (FI hard-resolve 69.5 → 85.8 %). GeoNames `<CC>.txt` dumps
@@ -190,7 +191,8 @@ export interface BuildOptions {
 
 /**
  * Build the byte-range candidate gazetteer from an admin DB + postcode shards. The FTS5-trigram fuzzy index is baked in
- * by `buildCandidateTable`. Pure pass-through to the canonical builder.
+ * by `buildCandidateTable`; the coverage manifest (survey candidate #2 — the artifact's own hard-filter coverage record
+ * + guard-B bboxes, see `coverage-manifest.ts`) is baked in before the seal.
  */
 export async function buildCandidate(opts: BuildOptions): Promise<BuildCandidateResult> {
 	const { buildCandidateTable } = await import("@mailwoman/resolver-wof-sqlite/build-candidate")
@@ -201,6 +203,11 @@ export async function buildCandidate(opts: BuildOptions): Promise<BuildCandidate
 		postcodes: [...(opts.postcodeShards ?? resolvePostcodeShards())],
 		onProgress: opts.onProgress,
 	})
+	// Coverage manifest (survey candidate #2): facts about the artifact live IN the artifact — bake the
+	// measured hard-filter coverage record + guard-B bboxes so consumers read them at open instead of
+	// falling back to the code constants. MUST run pre-seal (a shipped DB is never patched — rebuild).
+	opts.onProgress?.("coverage-manifest", "baking country coverage + bbox manifest")
+	await emitCoverageManifest({ dbPath: opts.out })
 	// The sealed-artifact invariant: a built DB is a read-only asset from the moment it exists.
 	sealDatabase(opts.out)
 
@@ -314,6 +321,7 @@ export function defaultGazetteerVersion(now: Date, suffix = "a"): string {
 
 	return `${y}-${m}-${d}${suffix}`
 }
+export * from "./coverage-manifest.ts"
 export * from "./defaults.ts"
 export * from "./fts.ts"
 export * from "./verify.ts"