mailwoman 7.5.0 → 7.6.0

package/api-engine.ts

@@ -88,7 +88,10 @@ function buildPreflightMessage(): string {
 		`    curl -fSL https://public.sister.software/mailwoman/gazetteer/2026-07-07a/candidate.db \\`,
 		`      -o ${conventionCandidate}`,
 		"",
-		"  Then re-run `serve` (the file is auto-detected at that path), or point at your own:",
+		"  Then point `$MAILWOMAN_CANDIDATE_DB` at that file and re-run `serve`:",
+		`    export MAILWOMAN_CANDIDATE_DB=${conventionCandidate}`,
+		"",
+		"  Or point at your own gazetteer:",
 		"    $MAILWOMAN_WOF_DB=<path1,path2,...>    (admin WOF SQLite shard(s) — the FTS backend)",
 		"    $MAILWOMAN_CANDIDATE_DB=<path>         (candidate-table gazetteer — population-first, demo-parity)",
 		"",

package/commands/corpus/shard/index.tsx

@@ -43,9 +43,20 @@ const OptionsSchema = zod.object({
 	edgesDir: zod.string().optional().describe("intersection: TIGER EDGES dir"),
 	country: zod.string().optional().describe("locale: target country"),
 	intlFraction: zod.string().optional().describe("german/locale: international-order fraction"),
+	countryFraction: zod
+		.string()
+		.optional()
+		.describe("locale: fraction of rows that append an explicit country surface form. Default 0"),
+	districtAsLocality: zod
+		.boolean()
+		.optional()
+		.describe(
+			"locale: override the per-part districtAsLocality mapping (--no-district-as-locality to force off). Unset leaves each part's own value untouched"
+		),
 	bareProb: zod.string().optional().describe("street-bare: P(bare street)"),
 	hnProb: zod.string().optional().describe("street-bare: P(house number)"),
 	communes: zod.string().optional().describe("fr-admin-split: communes source"),
+	banDir: zod.string().optional().describe("fr-lieudit: BAN adresses-<dept>.csv directory"),
 	excludeSurfaces: zod
 		.string()
 		.optional()
@@ -97,9 +108,12 @@ const CorpusShard: CommandComponent<typeof OptionsSchema, typeof ArgumentsSchema
 			edgesDir: options.edgesDir,
 			country: options.country,
 			intlFraction: num(options.intlFraction),
+			countryFraction: num(options.countryFraction),
+			districtAsLocality: options.districtAsLocality,
 			bareProb: num(options.bareProb),
 			hnProb: num(options.hnProb),
 			communes: options.communes,
+			banDir: options.banDir,
 			excludeSurfaces: options.excludeSurfaces,
 			multilocaleCount: num(options.multilocaleCount),
 		}

package/commands/eval/invariance.tsx

@@ -0,0 +1,64 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman eval invariance` — the INVARIANCE MINI-SUITE: a standing, seconds-cheap
+ *   metamorphic-invariance check (comma-drop / abbreviation-swap / case-fold / lowercase /
+ *   whitespace-jitter / trailing-punct / idempotence) over `eval-harness/invariance/suite.jsonl`, meant
+ *   to run in EVERY probe grade so distribution-shift collateral surfaces at 2k-probe cost instead of
+ *   ship-prep cost. Compares decoded PARSE COMPONENTS only (no resolver) — cheap by construction. Exit
+ *   nonzero on any LOST pair, or when the DEGRADED count exceeds `--max-degraded`. `--baseline` switches
+ *   to regression mode: a violation the baseline ALSO exhibits on the same pair is reported but doesn't
+ *   fail the gate — the shape probe grading uses to diff a candidate against v385.
+ */
+
+import { Text } from "ink"
+import zod from "zod"
+
+import { type CommandComponent, useCommandTask } from "../../cli-kit/index.ts"
+import { runInvarianceCommand } from "../../eval-harness/invariance/command.ts"
+
+export const description =
+	"Metamorphic invariance mini-suite (comma-drop/abbrev/case/idempotence) — standing probe guard"
+
+const OptionsSchema = zod.object({
+	suite: zod.string().optional().describe("Alternate suite.jsonl path (default: the shipped fixture)"),
+	model: zod.string().optional().describe("Candidate ONNX (requires --tokenizer + --model-card)"),
+	tokenizer: zod.string().optional().describe("Candidate tokenizer path"),
+	modelCard: zod.string().optional().describe("Candidate model-card path"),
+	weightsCache: zod
+		.string()
+		.optional()
+		.describe(
+			"Package-shaped candidate weights dir (<root>/node_modules/@mailwoman/neural-weights-<locale>) — #718-safe, alternative to --model"
+		),
+	locale: zod.string().optional().describe("Locale tag for weights-package resolution (default en-US)"),
+	maxDegraded: zod.number().optional().describe("Fail if the NEW-violation DEGRADED count exceeds this (default 0)"),
+	baseline: zod
+		.string()
+		.optional()
+		.describe("Baseline ONNX for regression mode (requires --baseline-tokenizer + --baseline-model-card)"),
+	baselineTokenizer: zod.string().optional().describe("Baseline tokenizer path"),
+	baselineModelCard: zod.string().optional().describe("Baseline model-card path"),
+	baselineWeightsCache: zod
+		.string()
+		.optional()
+		.describe("Package-shaped baseline weights dir — alternative to --baseline + the two flags above"),
+})
+
+export { OptionsSchema as options }
+
+const EvalInvariance: CommandComponent<typeof OptionsSchema> = ({ options }) => {
+	const state = useCommandTask(
+		() => runInvarianceCommand(options),
+		(exitCode) => exitCode
+	)
+
+	if (state.status === "error") return <Text color="red">✗ {state.message}</Text>
+
+	// The runner narrates its own report + verdict lines — rendering anything here would duplicate it.
+	return null
+}
+
+export default EvalInvariance

package/commands/gazetteer/pair-index.tsx

@@ -0,0 +1,237 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman gazetteer pair-index` — build the PIX1 placetype-pair index (placetype-pair-prior
+ *   arc, Task 3) from the HM Land Registry PPD tuples CSV (`corpus/src/tools/fetch/ppd.ts`'s
+ *   `gb-tuples.csv`; columns `NUMBER,STREET,CITY,DISTRICT,REGION,POSTCODE`). Streams the CSV
+ *   (CSVSpliterator, the `corpus/src/shard-recipes/locale.ts` `readTuples` idiom), folds
+ *   child=CITY/parent=DISTRICT through `normalizeFSTToken` and tags every pair `dependent_locality`
+ *   (`PairIndexBuilder`, `gazetteer-pipeline/pair-index.ts` — the extracted, unit-tested fold/dedupe/
+ *   skip logic), then writes `pair-index-<country>.bin` via `serializePairIndex`.
+ *
+ *   `--delta` is REQUIRED with no default: it's the soft-prior bias magnitude a probe hit will
+ *   contribute at decode time, and the calibration task (not this one) owns the real value — a
+ *   silent default here would let an uncalibrated number ship unnoticed.
+ *
+ *   Self-verifying (the sealed-artifact spirit — see AGENTS.md's database section, which this
+ *   mirrors for a flat binary): after writing, the command re-reads the bytes through a fresh
+ *   `PairIndexResolver` and probes a few known (child, parent) pairs, printing `PROBE OK`/`PROBE
+ *   MISS` lines rather than trusting the write silently succeeded.
+ *
+ *   Also prints the raw (pre-fold) CITY word-length distribution (p50/p90/p99/max + a per-length
+ *   count table) — this sizes the word-span window the decode-side prior (Task 4) walks.
+ */
+
+import { createReadStream, existsSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { dataRootPath, md5File } from "@mailwoman/core/utils"
+// @mailwoman/neural's fst-prior and pair-index-resolver subpaths are self-contained (fst-prior only
+// type-imports from a sibling module; pair-index-resolver only imports core/types) — safe value
+// imports at module level, no heavy ONNX runtime pulled in (mirrors postcode-binary.tsx's comment).
+import { normalizeFSTToken } from "@mailwoman/neural/fst-prior"
+import { PairIndexResolver, serializePairIndex, type PairIndexHeader } from "@mailwoman/neural/pair-index-resolver"
+import { Box, Text } from "ink"
+import { CSVSpliterator } from "spliterator"
+import zod from "zod"
+
+import { type CommandComponent, useCommandTask } from "../../cli-kit/index.ts"
+import { PairIndexBuilder, applyPairIndexHoldout } from "../../gazetteer-pipeline/pair-index.ts"
+
+/**
+ * The GB source's adjudicated production distinct-pair count — the cross-check this build must reproduce. Re-anchored
+ * (final-review fix) from the rung-3 census's raw 19,431 lines (`scratchpad/gb-probe-grade/census-gb-pairs.jsonl`) down
+ * to 19,209. This is not a bug fix — a real Task-3 cross-check rebuild fired the gate at exactly this delta and it was
+ * adjudicated as the production fold correctly MERGING punctuation-variant duplicates the raw census counted separately
+ * (e.g. "St Helens" vs "St. Helens" fold to the SAME `(child, parent)` key). The collision receipt: 221 merge groups —
+ * 220 groups where 2 raw census lines collapse to 1 production entry (220 × 1 collapsed line = 220) plus 1 group where
+ * 3 raw lines collapse to 1 entry (1 × 2 collapsed lines = 2) — 220 + 2 = 222 raw lines absorbed; 19,431 − 222 =
+ * 19,209. See `.superpowers/sdd/progress.md`'s Task 3 entry for the adjudication record. A mismatch AGAINST 19,209 on a
+ * real rebuild means this build's fold diverged from the adjudicated baseline, not that 19,209 is wrong; investigate
+ * before trusting the artifact.
+ */
+const EXPECTED_GB_PAIR_COUNT = 19_209
+
+/**
+ * The raw rung-3 census's pre-fold line count (`scratchpad/gb-probe-grade/census-gb-pairs.jsonl`) — retained as a named
+ * constant for provenance/debugging (e.g. diffing a future source refresh against this cycle's raw count), NOT the
+ * cross-check target. See {@link EXPECTED_GB_PAIR_COUNT}'s doc comment for why the production target is lower.
+ */
+const RUNG3_PRE_FOLD_CENSUS_LINE_COUNT = 19_431
+
+/** Known (child, parent) pairs from the rung-3 GB census, probed after write as a self-check. */
+const GB_PROBE_PAIRS: ReadonlyArray<readonly [city: string, district: string]> = [
+	["Fishburn", "Stockton-on-Tees"],
+	["Shoreditch", "London"],
+	["Sedgefield", "Stockton-on-Tees"],
+]
+
+const OptionsSchema = zod.object({
+	out: zod.string().default("docs/static/mailwoman").describe("Output dir for pair-index-<country>.bin"),
+	country: zod.string().default("gb").describe("ISO country code this shard is built for"),
+	source: zod.string().optional().describe("Source PPD tuples CSV. Default <data-root>/ppd/2026-07-22/gb-tuples.csv"),
+	delta: zod
+		.number()
+		.describe(
+			"REQUIRED, no default — the soft-prior bias magnitude a probe hit contributes at decode time. " +
+				"The calibration task supplies the real value; this command refuses to default it silently."
+		),
+	holdoutFraction: zod
+		.number()
+		.min(0)
+		.max(1)
+		.default(0)
+		.describe(
+			"DEV-ONLY falsifier flag (placetype-pair-prior arc, Task 6) — withhold this fraction of deduplicated pairs " +
+				"from the build (seeded, deterministic; see --holdout-seed), for measuring decode-layer degradation " +
+				"against pairs the index was never trained/built on. Default 0 = a normal, complete build. NEVER pass a " +
+				"nonzero value for a shipped artifact build."
+		),
+	holdoutSeed: zod
+		.number()
+		.default(42)
+		.describe("Seed for --holdout-fraction's deterministic withholding. Ignored when --holdout-fraction is 0."),
+})
+
+export { OptionsSchema as options }
+
+const GazetteerPairIndex: CommandComponent<typeof OptionsSchema> = ({ options }) => {
+	const state = useCommandTask(async () => {
+		const country = options.country.toLowerCase()
+		const sourcePath = options.source ?? dataRootPath("ppd", "2026-07-22", "gb-tuples.csv")
+
+		if (!existsSync(sourcePath)) {
+			throw new Error(`pair-index: source CSV not found: ${sourcePath}`)
+		}
+
+		const builder = new PairIndexBuilder()
+		let header: string[] | null = null
+		let cityIx = -1
+		let districtIx = -1
+
+		// Same CSVSpliterator idiom as `corpus/src/shard-recipes/locale.ts`'s `readTuples`: array mode, no header
+		// row consumed by the parser (`header: false`), so we build the column index off the first yielded row
+		// ourselves and skip forward from there.
+		for await (const cells of CSVSpliterator.fromAsync<string[]>(createReadStream(sourcePath), {
+			mode: "array",
+			header: false,
+			enableQuoteHandling: true,
+		})) {
+			if (header === null) {
+				header = cells.map((h) => h.trim().toUpperCase())
+				cityIx = header.indexOf("CITY")
+				districtIx = header.indexOf("DISTRICT")
+
+				if (cityIx < 0 || districtIx < 0) {
+					throw new Error(`pair-index: source header is missing CITY/DISTRICT: ${header.join(",")}`)
+				}
+
+				continue
+			}
+
+			builder.addRow(cells[cityIx] ?? "", cells[districtIx] ?? "")
+		}
+
+		const built = builder.finish()
+		const { rowsKept, rowsSkipped, distribution } = built
+
+		// Task 6 falsifier-board dev flag: withhold a deterministic fraction of pairs from the build so a
+		// downstream eval can measure decode-layer degradation on pairs the index never saw. A no-op
+		// (`entries === built.entries` by value) when --holdout-fraction is the 0 default.
+		const { kept: entries, heldOut } = applyPairIndexHoldout(
+			built.entries,
+			options.holdoutFraction,
+			options.holdoutSeed
+		)
+		const sourceMD5 = await md5File(sourcePath)
+
+		const pairIndexHeader: PairIndexHeader = {
+			country,
+			delta: options.delta,
+			schemaVersion: 1,
+			foldVersion: 1,
+			sourceMD5s: [sourceMD5],
+			buildDate: new Date().toISOString(),
+		}
+
+		const bytes = serializePairIndex(pairIndexHeader, entries)
+		const outPath = join(options.out, `pair-index-${country}.bin`)
+
+		writeFileSync(outPath, bytes)
+
+		// Self-verifying readback: construct a fresh resolver over the bytes we just wrote (not the in-memory
+		// `entries`) and probe known pairs, rather than trusting the write silently succeeded.
+		const resolver = new PairIndexResolver(bytes)
+		const probeLines = GB_PROBE_PAIRS.map(([city, district]) => {
+			const child = normalizeFSTToken(city)
+			const parent = normalizeFSTToken(district)
+			const tag = resolver.probe(child, parent)
+
+			return tag
+				? `PROBE OK: fold("${city}")/fold("${district}") → "${child}"/"${parent}" → ${tag}`
+				: `PROBE MISS: fold("${city}")/fold("${district}") → "${child}"/"${parent}" → (no entry)`
+		})
+
+		const distLines = [
+			`CITY word-length distribution (raw, pre-fold; n=${distribution.totalRows.toLocaleString()}): ` +
+				`p50=${distribution.p50} p90=${distribution.p90} p99=${distribution.p99} max=${distribution.max}`,
+			...distribution.counts.map(
+				(b) => `  ${b.words} word${b.words === 1 ? "" : "s"}: ${b.rows.toLocaleString()} rows`
+			),
+		]
+
+		// The rung-3 cross-check assumes a COMPLETE build — a nonzero --holdout-fraction deliberately produces a
+		// smaller `entries.length` by design, so the strict count-match gate is meaningless (and would misreport
+		// "BLOCKED") under holdout. Gate against `built.entries.length` (pre-holdout) instead in that case.
+		const preHoldoutCount = built.entries.length
+		// Pre-fold context suffix — the raw rung-3 census line count, for provenance/debugging (e.g. diffing a
+		// future source refresh against this cycle's raw count). Not the cross-check target; see
+		// `EXPECTED_GB_PAIR_COUNT`'s doc comment for the 221-group collision receipt that separates the two numbers.
+		const preFoldSuffix = ` (pre-fold rung-3 census: ${RUNG3_PRE_FOLD_CENSUS_LINE_COUNT.toLocaleString()} lines)`
+		const gateLine =
+			country === "gb"
+				? options.holdoutFraction > 0
+					? `(cross-check skipped under --holdout-fraction; ${preHoldoutCount.toLocaleString()} distinct pairs before holdout, expects ${EXPECTED_GB_PAIR_COUNT.toLocaleString()})${preFoldSuffix}`
+					: preHoldoutCount === EXPECTED_GB_PAIR_COUNT
+						? `CROSS-CHECK PASS: ${preHoldoutCount.toLocaleString()} distinct pairs (production baseline expects ${EXPECTED_GB_PAIR_COUNT.toLocaleString()})${preFoldSuffix}`
+						: `CROSS-CHECK BLOCKED: ${preHoldoutCount.toLocaleString()} distinct pairs != the production baseline's ${EXPECTED_GB_PAIR_COUNT.toLocaleString()} — investigate fold divergence before trusting this artifact${preFoldSuffix}`
+				: `(cross-check only registered for gb; ${preHoldoutCount.toLocaleString()} distinct pairs)`
+
+		const holdoutLine =
+			options.holdoutFraction > 0
+				? `HOLDOUT: withheld ${heldOut.length.toLocaleString()}/${preHoldoutCount.toLocaleString()} pairs ` +
+					`(fraction=${options.holdoutFraction}, seed=${options.holdoutSeed}) — ${entries.length.toLocaleString()} pairs written`
+				: undefined
+
+		return [
+			`pair-index-${country}.bin → ${outPath} (${bytes.length.toLocaleString()} bytes)`,
+			`rows kept ${rowsKept.toLocaleString()} / skipped ${rowsSkipped.toLocaleString()} (empty CITY)`,
+			`distinct pairs: ${entries.length.toLocaleString()}`,
+			...(holdoutLine ? [holdoutLine] : []),
+			gateLine,
+			...distLines,
+			...probeLines,
+		]
+	})
+
+	if (state.status === "error") return <Text color="red">✗ {state.message}</Text>
+
+	if (state.status === "done") {
+		return (
+			<Box flexDirection="column">
+				{state.result.map((line, i) => (
+					<Text key={i} color={i === 0 ? "green" : undefined}>
+						{i === 0 ? "✓ " : "  "}
+						{line}
+					</Text>
+				))}
+			</Box>
+		)
+	}
+
+	return null
+}
+
+export default GazetteerPairIndex

package/commands/release/hf.tsx

@@ -36,6 +36,12 @@ const OptionsSchema = zod.object({
 	modelSize: zod.string().optional().describe("Override the displayed model size (default: derived from --model)"),
 	steps: zod.number().optional().describe("Training steps recorded in releases.json (default 100000)"),
 	postcodes: zod.string().optional().describe("Comma-separated postcode soft-feed binaries (postcode-us.bin,…)"),
+	pairIndexes: zod
+		.string()
+		.optional()
+		.describe(
+			"Comma-separated placetype-pair-index soft-feed binaries (pair-index-gb.bin,…; placetype-pair-prior arc, Task 8)"
+		),
 	gazetteerLexicon: zod
 		.string()
 		.optional()

package/eval-harness/gauntlet/cases/regression.ts

@@ -662,6 +662,6 @@ export const REGRESSION_CASES: SeedCase[] = [
 		expectLon: 2.3467,
 		expectToleranceM: 50_000,
 		addedAt: "2026-07-15",
-		note: "KNOWN FAIL (measured 2026-07-15): the street span swallows the trailing locality — street parses as 'Rue du Chat-qui-Pêche, Paris' and the tree then resolves to NOTHING. The only miss in the operator's 10-row tricky list (9/10 pass), so the esoteric morphology is NOT the problem — the boundary is. This is the #727 span-head's class; expect it to flip when Phase 2+ lands.",
+		note: "Passes on the staged v3.11.x candidates (task-8 record) — flip to pass WHEN a lineage successor promotes; shipped v385 still fails (verified 2026-07-23). The street/locality boundary that swallowed 'Paris' on 2026-07-15 has since flipped in experimental lineages (#727 span-head). Was the only miss in the operator's 10-row tricky list (9/10 passed at the time); tracked as span-head's class. See final-review fix-wave report / #1189 adjudication for context.",
 	},
 ]

package/eval-harness/invariance/command.ts

@@ -0,0 +1,59 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   CLI-facing orchestration for `mailwoman eval invariance` — wires suite + transforms + runner
+ *   together from argv-shaped options. Thin on purpose: the module the `invariance.tsx` command wraps
+ *   narrates everything and owns only the exit code, matching `eval gate` / `eval error-analysis`.
+ */
+
+import { type ModelSelectOptions, loadSuite, buildParseFn, runInvarianceSuite } from "./runner.ts"
+
+export interface InvarianceCommandOptions extends ModelSelectOptions {
+	/** Alternate suite fixture path. Default the shipped `suite.jsonl`. */
+	suite?: string
+	/** Fail the gate if the NEW-violation DEGRADED count exceeds this. Default 0. */
+	maxDegraded?: number
+	/**
+	 * `--baseline` regression mode (probe-grading shape, e.g. v385): a baseline candidate ONNX graded on the SAME suite.
+	 * Requires `baselineTokenizer` + `baselineModelCard`, or pass `baselineWeightsCache` instead for a package-shaped
+	 * dir.
+	 */
+	baseline?: string
+	baselineTokenizer?: string
+	baselineModelCard?: string
+	/** Package-shaped baseline weights dir — alternative to `baseline` + the two flags above. */
+	baselineWeightsCache?: string
+}
+
+/** Run the invariance mini-suite from CLI-shaped options. Returns the process exit code (0 = PASS). */
+export async function runInvarianceCommand(options: InvarianceCommandOptions): Promise<number> {
+	const rows = loadSuite(options.suite)
+	console.error(`[invariance] loaded ${rows.length} rows from ${options.suite ?? "the shipped suite.jsonl"}`)
+
+	console.error(`[invariance] loading candidate model…`)
+	const parse = await buildParseFn(options)
+
+	let baselineParse: Awaited<ReturnType<typeof buildParseFn>> | undefined
+
+	if (options.baselineWeightsCache || options.baseline) {
+		console.error(`[invariance] loading baseline model (regression mode)…`)
+		baselineParse = await buildParseFn({
+			weightsCache: options.baselineWeightsCache,
+			model: options.baselineWeightsCache ? undefined : options.baseline,
+			tokenizer: options.baselineTokenizer,
+			modelCard: options.baselineModelCard,
+			locale: options.locale,
+		})
+	}
+
+	const result = await runInvarianceSuite({
+		rows,
+		parse,
+		...(baselineParse ? { baselineParse } : {}),
+		maxDegraded: options.maxDegraded,
+	})
+
+	return result.exitCode
+}

package/eval-harness/invariance/compare.ts

@@ -0,0 +1,106 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Component-level comparison for the invariance mini-suite — pure, no model, no I/O. Compares two
+ *   decoded component maps (order-insensitive: a plain key→value record has no order) and classifies the
+ *   pair INVARIANT / DEGRADED / LOST.
+ *
+ *   `house_number` / `street` / `postcode` are treated as CRITICAL: they're the load-bearing tags a
+ *   downstream geocoder needs to resolve a rooftop (the same three the #251/#1101 DIR-test failures broke
+ *   on). A value change on a critical tag that's present in the original — including one token bleeding
+ *   from a neighboring tag, e.g. a stripped comma pulling a directional suffix into the locality — is LOST
+ *   even when the transformed parse is non-empty, because the address is no longer resolvable to the same
+ *   place. A drift confined to non-critical tags (locality, region, dependent_locality, unit, …) is
+ *   DEGRADED: recoverable, worth flagging, not ship-blocking on its own.
+ *
+ *   A critical tag that's ABSENT in the original parse but PRESENT in the transformed one — a hallucination
+ *   — is ALSO LOST, not DEGRADED and not ignored. (Adjudicated: review fix wave, 2026-07-23.) A missing
+ *   critical tag degrades gracefully to a coarser admin-tier fallback; a hallucinated one can resolve to a
+ *   SPECIFIC WRONG rooftop with high apparent confidence — worse than falling back, because nothing
+ *   downstream knows to distrust it.
+ */
+
+export const CRITICAL_TAGS = ["house_number", "street", "postcode"] as const
+
+export type Verdict = "INVARIANT" | "DEGRADED" | "LOST"
+
+/**
+ * Ordinal severity — INVARIANT < DEGRADED < LOST. Used by the runner's `--baseline` regression gate to decide whether a
+ * candidate's verdict on a (row, transform) pair is "at least as bad as" the baseline's, not merely "also
+ * non-INVARIANT" (see runner.ts's `preExisting` computation).
+ */
+export const VERDICT_SEVERITY: Record<Verdict, number> = { INVARIANT: 0, DEGRADED: 1, LOST: 2 }
+
+export interface CompareResult {
+	verdict: Verdict
+	/** Human-readable per-tag diff lines, empty for INVARIANT. */
+	diff: string[]
+}
+
+/** Normalize a component value for comparison: trim, lowercase, collapse internal whitespace. Non-string/empty → "". */
+function normVal(v: unknown): string {
+	if (typeof v !== "string") return ""
+
+	return v.trim().toLowerCase().replace(/\s+/g, " ")
+}
+
+/**
+ * Compare a baseline (`original`) component map against a perturbed (`transformed`) one. Order-insensitive by
+ * construction — both are plain key→value records.
+ */
+export function compareComponents(
+	original: Record<string, string>,
+	transformed: Record<string, string>
+): CompareResult {
+	const originalKeys = Object.keys(original).filter((k) => normVal(original[k]))
+	const transformedKeys = Object.keys(transformed).filter((k) => normVal(transformed[k]))
+
+	// LOST — the transformed parse is empty (or all-blank) while the original had components at all.
+	// "unresolvable-shaped": a fully collapsed decode, the parse-level analog of a resolver falling back
+	// to an admin-only tier with no coordinate.
+	if (transformedKeys.length === 0 && originalKeys.length > 0) {
+		return { verdict: "LOST", diff: ["transformed parse is empty"] }
+	}
+
+	const diff: string[] = []
+	let criticalBroken = false
+
+	for (const tag of CRITICAL_TAGS) {
+		const o = normVal(original[tag])
+		const t = normVal(transformed[tag])
+
+		if (!o) {
+			// Not present in the original. A hallucinated value on the TRANSFORMED side is still LOST — see
+			// the header doc comment (a wrong-but-confident rooftop is worse than a graceful fallback).
+			if (t) {
+				criticalBroken = true
+				diff.push(`${tag}: ∅ → "${transformed[tag]}" (hallucinated)`)
+			}
+
+			continue
+		}
+
+		if (o !== t) {
+			criticalBroken = true
+			diff.push(`${tag}: "${original[tag]}" → "${transformed[tag] ?? "∅"}"`)
+		}
+	}
+
+	if (criticalBroken) return { verdict: "LOST", diff }
+
+	// Non-critical drift: any key added/dropped, or any shared key's value changed.
+	const allKeys = new Set([...originalKeys, ...transformedKeys, ...Object.keys(transformed), ...Object.keys(original)])
+
+	for (const tag of allKeys) {
+		const o = normVal(original[tag])
+		const t = normVal(transformed[tag])
+
+		if (o !== t) {
+			diff.push(`${tag}: "${original[tag] ?? "∅"}" → "${transformed[tag] ?? "∅"}"`)
+		}
+	}
+
+	return diff.length > 0 ? { verdict: "DEGRADED", diff } : { verdict: "INVARIANT", diff: [] }
+}