mailwoman 8.4.0 → 8.6.0

package/commands/filer/linkage-eval.tsx

@@ -0,0 +1,57 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman filer linkage-eval` — the 3b Task 4 corporate-family recovery eval. Geocode-free,
+ *   database-free (builds its own scratch `filer.db` artifacts from an embedded synthetic corpus); emits
+ *   the markdown scorecard to stdout and, when `--out-md` is given, to that path too. `--date` overrides
+ *   the report's dated H1 so the committed scorecard can be regenerated without editing code.
+ */
+
+import { filerLinkageEval } from "@mailwoman/filer/tools"
+import { Text } from "ink"
+import zod from "zod"
+
+import { type CommandComponent, useCommandTask } from "../../cli-kit/index.ts"
+
+const OptionsSchema = zod.object({
+	outMd: zod.string().optional().describe("Also write the markdown report here"),
+	date: zod.string().optional().describe("Report date (YYYY-MM-DD) for the H1 — defaults to today"),
+})
+
+export { OptionsSchema as options }
+
+/**
+ * `null` renders as `N/A`, never as `0.000` — the withheld run makes no positive call, so its precision and F1 are
+ * undefined rather than zero (see `linkage-metrics.ts`).
+ */
+function formatScoreValue(value: number | null): string {
+	return value === null ? "N/A" : value.toFixed(3)
+}
+
+const FilerLinkageEval: CommandComponent<typeof OptionsSchema> = ({ options }) => {
+	const state = useCommandTask(() =>
+		filerLinkageEval({ outMd: options.outMd, date: options.date }, (line) => console.error(line))
+	)
+
+	if (state.status === "error") return <Text color="red">✗ {state.message}</Text>
+
+	if (state.status === "done") {
+		const { withheld, control } = state.result
+
+		// Both rows, always: the withheld number is the measurement and the control is what makes it falsifiable.
+		return (
+			<Text color="green">
+				linkage-eval · withheld: recall {formatScoreValue(withheld.score.recall)} ({withheld.score.truePositivePairs}/
+				{withheld.score.truthPositivePairs} pairs, F1 {formatScoreValue(withheld.score.f1)}) · control: F1{" "}
+				{formatScoreValue(control.score.f1)} ({control.score.truePositivePairs}/{control.score.truthPositivePairs}{" "}
+				pairs)
+			</Text>
+		)
+	}
+
+	return null
+}
+
+export default FilerLinkageEval

package/commands/gazetteer/build/bdc.tsx

@@ -40,6 +40,7 @@ import {
 	createBDCClient,
 	createTIGERBlockCentroidLookup,
 	downloadBDCFile,
+	formatBDCThrottleStats,
 	resolveLatestVintage,
 	retrieveAvailabilityFiles,
 	retrieveFilingDates,
@@ -140,6 +141,12 @@ const GazetteerBuildBDC: CommandComponent<typeof OptionsSchema> = ({ options })
 			csvPaths.push(await downloadBDCFile(client, file, cacheDir))
 		}
 
+		// The FCC caps this API at ten requests per minute — six seconds a call — so a national run is
+		// throttle-bound by construction and the interesting number is how much of the wall clock went to
+		// waiting rather than transferring. Printed once the network phase is over, on stderr with the rest
+		// of the progress stream, so a rate change can be assessed against a measurement.
+		console.error(`▸ ${formatBDCThrottleStats(client.throttleStats())}`)
+
 		const out = options.out ?? dataRootPath("bdc", "bdc.db")
 		const buildSHA = execFileSync("git", ["rev-parse", "--short", "HEAD"]).toString().trim()
 		const tigerDBPath = dataRootPath("tiger", "tiger.db")

package/commands/gazetteer/census.tsx

@@ -0,0 +1,190 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman gazetteer census` — build the PCN1 placetype census (hierarchy campaign R4c) from the
+ *   shipped WOF admin DB. Counts each locality-class parent's children through the projection table
+ *   (`gazetteer-pipeline/placetype-census.ts`), folds parent surfaces with the SAME `normalizeFSTToken`
+ *   the PIX1 pair index uses — so a consumer folds once and probes both artifacts — and writes
+ *   `placetype-census-<country>.bin`.
+ *
+ *   Fold collisions SUM. Two distinct raw parents that fold together ("St Helens" / "St. Helens") are
+ *   one census node whose counts are the union of both; the serializer refuses duplicate parents, so a
+ *   merge bug surfaces as a throw rather than a silently halved count.
+ *
+ *   `--delta` is deliberately OPTIONAL and unset by default, unlike the pair index's required one: R4c
+ *   ships the census as data + loader + offline probe with NO decode wiring. A calibrated delta is a
+ *   later rung's output; writing one now would put an unmeasured bias into a shipped artifact.
+ *
+ *   Self-verifying (the sealed-artifact spirit): after writing, the command re-reads its own bytes
+ *   through a fresh `PlacetypeCensusResolver` and probes known parents, printing PROBE OK/MISS with the
+ *   node's dependent-locality share and lift rather than trusting the write.
+ */
+
+import { existsSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+import type { ComponentTag } from "@mailwoman/core/types"
+import { dataRootPath, md5File } from "@mailwoman/core/utils"
+import { normalizeFSTToken } from "@mailwoman/neural/fst-prior"
+import {
+	PlacetypeCensusResolver,
+	serializePlacetypeCensus,
+	type PlacetypeCensusHeader,
+	type PlacetypeCensusNode,
+} from "@mailwoman/neural/placetype-census"
+import { Box, Text } from "ink"
+import zod from "zod"
+
+import { type CommandComponent, useCommandTask } from "../../cli-kit/index.ts"
+import { buildPlacetypeCensus, toBaseRates } from "../../gazetteer-pipeline/placetype-census.ts"
+
+/**
+ * Known parents probed after write, PER COUNTRY. Probing another country's names against a freshly built census prints
+ * reassuring-looking misses that verify nothing (the lesson the pair-index command's en-nz first build taught).
+ */
+const PROBE_PARENTS_BY_COUNTRY: Readonly<Record<string, readonly string[]>> = {
+	gb: ["London", "Manchester", "Birmingham"],
+	us: ["New York", "Chicago", "Springfield"],
+}
+
+const OptionsSchema = zod.object({
+	out: zod.string().default("docs/static/mailwoman").describe("Output dir for placetype-census-<country>.bin"),
+	country: zod.string().default("gb").describe("ISO country code this census is built for"),
+	source: zod.string().optional().describe("WOF admin DB. Default <data-root>/wof/admin-global-priority.db"),
+	delta: zod
+		.number()
+		.optional()
+		.describe(
+			"OPTIONAL soft-prior magnitude written into the header. Omit (the default) for an un-wired census — R4c " +
+				"ships data + loader + offline probe only; a calibration rung supplies the real value."
+		),
+})
+
+export { OptionsSchema as options }
+
+const GazetteerCensus: CommandComponent<typeof OptionsSchema> = ({ options }) => {
+	const state = useCommandTask(async () => {
+		const country = options.country.toLowerCase()
+		const sourcePath = options.source ?? String(dataRootPath("wof", "admin-global-priority.db"))
+
+		if (!existsSync(sourcePath)) {
+			throw new Error(`census: source WOF admin DB not found: ${sourcePath}`)
+		}
+
+		const built = buildPlacetypeCensus(sourcePath, country.toUpperCase())
+
+		if (built.unmappedPlacetypes.length) {
+			throw new Error(
+				`census: source carries placetypes absent from PLACETYPE_PROJECTION: ${built.unmappedPlacetypes.join(", ")} — ` +
+					`extend the projection table (and plan/reference/placetype-evidence.mdx) before building.`
+			)
+		}
+
+		// Fold, merging collisions by SUMMING counts — the serializer throws on duplicates, so a merge bug is loud.
+		const folded = new Map<string, PlacetypeCensusNode>()
+		let collisions = 0
+
+		for (const node of built.nodes) {
+			const parent = normalizeFSTToken(node.parent)
+
+			if (!parent) continue
+
+			const existing = folded.get(parent)
+
+			if (!existing) {
+				folded.set(parent, { parent, counts: { ...node.counts }, total: node.total })
+
+				continue
+			}
+
+			collisions++
+
+			for (const [tag, n] of Object.entries(node.counts) as Array<[ComponentTag, number]>) {
+				existing.counts[tag] = (existing.counts[tag] ?? 0) + n
+			}
+
+			existing.total += node.total
+		}
+
+		const nodes = [...folded.values()]
+		const baseRates = toBaseRates(built.countryTotals)
+		const sourceMD5 = await md5File(sourcePath)
+
+		const header: PlacetypeCensusHeader = {
+			country,
+			schemaVersion: 1,
+			foldVersion: 1,
+			sourceMD5s: [sourceMD5],
+			buildDate: new Date().toISOString(),
+			baseRates,
+			...(options.delta !== undefined ? { delta: options.delta } : {}),
+		}
+
+		const bytes = serializePlacetypeCensus(header, nodes)
+		const outPath = join(options.out, `placetype-census-${country}.bin`)
+
+		writeFileSync(outPath, bytes)
+
+		// Self-verifying readback over the bytes just written, not the in-memory nodes.
+		const resolver = new PlacetypeCensusResolver(bytes)
+		const probeParents = PROBE_PARENTS_BY_COUNTRY[country]
+
+		if (!probeParents) {
+			throw new Error(
+				`census: no self-check probe parents registered for country "${country}" — add an entry to ` +
+					`PROBE_PARENTS_BY_COUNTRY (probing another country's names verifies nothing).`
+			)
+		}
+
+		const probeLines = probeParents.map((raw) => {
+			const parent = normalizeFSTToken(raw)
+			const node = resolver.probe(parent)
+
+			if (!node) return `PROBE MISS: fold("${raw}") → "${parent}" → (no node)`
+
+			const depLoc = node.counts.dependent_locality ?? 0
+			const share = resolver.share(parent, "dependent_locality")
+			const lift = resolver.lift(parent, "dependent_locality")
+
+			return (
+				`PROBE OK: "${parent}" → ${node.total.toLocaleString()} children, ` +
+				`${depLoc.toLocaleString()} dependent_locality (share ${(share * 100).toFixed(1)}%, lift ${lift.toFixed(1)}×)`
+			)
+		})
+
+		const baseRateLines = (Object.entries(baseRates) as Array<[ComponentTag, number]>)
+			.toSorted((a, b) => b[1] - a[1])
+			.map(([tag, rate]) => `  ${tag}: ${(rate * 100).toFixed(2)}%`)
+
+		return [
+			`placetype-census-${country}.bin → ${outPath} (${bytes.length.toLocaleString()} bytes)`,
+			`header: ${options.delta !== undefined ? `delta=${options.delta}` : "(no delta — un-wired census)"}`,
+			`nodes: ${nodes.length.toLocaleString()} (${built.nodes.length.toLocaleString()} pre-fold, ${collisions.toLocaleString()} fold collisions merged)`,
+			`child links counted: ${built.links.toLocaleString()}`,
+			"country base rates:",
+			...baseRateLines,
+			...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 GazetteerCensus

package/commands/gazetteer/granularity.tsx

@@ -0,0 +1,104 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman gazetteer granularity` — the per-country gazetteer depth scorecard.
+ *
+ *   Answers "where does the admin gazetteer bottom out?" for every country it knows, which nobody
+ *   had measured: the shipped artifact stocks 9 of WOF's 34 placetypes and carries a
+ *   `dependent_locality` tier in 11 of 244 countries. Read-only, no network, no model — three
+ *   grouped queries over `spr`/`ancestors` and a markdown render.
+ *
+ *   The report is a COMMITTED artifact (the `fill-rates.md` precedent), so the source md5 and the
+ *   parent-coverage floor are pinned in its header. Re-running against a rebuilt gazetteer and
+ *   diffing the report is the intended workflow.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs"
+import { dirname } from "node:path"
+
+import { dataRootPath, md5File } from "@mailwoman/core/utils"
+import { Box, Text } from "ink"
+import zod from "zod"
+
+import { type CommandComponent, useCommandTask } from "../../cli-kit/index.ts"
+import { renderGranularityReport } from "../../gazetteer-pipeline/granularity-report.ts"
+import { DEFAULT_COVERAGE_FLOOR, bottomsOutAt, buildGranularityLadder } from "../../gazetteer-pipeline/granularity.ts"
+
+const OptionsSchema = zod.object({
+	out: zod
+		.string()
+		.default("docs/articles/evals/coverage/gazetteer-depth-scorecard.md")
+		.describe("Output path for the markdown scorecard"),
+	source: zod.string().optional().describe("WOF admin DB. Default $MAILWOMAN_DATA_ROOT/wof/admin-global-priority.db"),
+	floor: zod
+		.number()
+		.default(DEFAULT_COVERAGE_FLOOR)
+		.describe(
+			`Parent-coverage floor for crediting a sub-locality rung. Default ${DEFAULT_COVERAGE_FLOOR} — set low on ` +
+				"purpose, to catch thin-but-real tiers rather than certify them."
+		),
+})
+
+export { OptionsSchema as options }
+
+const GazetteerGranularity: CommandComponent<typeof OptionsSchema> = ({ options }) => {
+	const state = useCommandTask(async () => {
+		const sourcePath = options.source ?? String(dataRootPath("wof", "admin-global-priority.db"))
+		const rows = buildGranularityLadder(sourcePath)
+
+		if (!rows.length) {
+			throw new Error(`granularity: no countries measured from ${sourcePath} — is this an admin DB?`)
+		}
+
+		const markdown = renderGranularityReport(rows, {
+			// Display the portable form; never bake the resolved lab path into a committed artifact.
+			sourcePath: "$MAILWOMAN_DATA_ROOT/wof/admin-global-priority.db",
+			sourceMD5: await md5File(sourcePath),
+			buildDate: new Date().toISOString(),
+			floor: options.floor,
+		})
+
+		mkdirSync(dirname(options.out), { recursive: true })
+		writeFileSync(options.out, markdown)
+
+		const byBottom = new Map<string, number>()
+
+		for (const row of rows) {
+			const bottom = bottomsOutAt(row, options.floor) ?? "(none)"
+
+			byBottom.set(bottom, (byBottom.get(bottom) ?? 0) + 1)
+		}
+
+		const distribution = [...byBottom.entries()]
+			.toSorted((a, b) => b[1] - a[1])
+			.map(([rung, n]) => `  ${rung}: ${n.toLocaleString()} countries`)
+
+		return [
+			`gazetteer depth scorecard → ${options.out}`,
+			`countries measured: ${rows.length.toLocaleString()} (floor ${(options.floor * 100).toFixed(1)}%)`,
+			"bottoms out at:",
+			...distribution,
+		]
+	})
+
+	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 GazetteerGranularity

package/commands/gazetteer/pair-index.tsx

@@ -24,7 +24,7 @@
  *   count table) — this sizes the word-span window the decode-side prior (Task 4) walks.
  */
 
-import { createReadStream, existsSync, writeFileSync } from "node:fs"
+import { createReadStream, existsSync, readFileSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
 
 import { dataRootPath, md5File } from "@mailwoman/core/utils"
@@ -38,6 +38,8 @@ import { CSVSpliterator } from "spliterator"
 import zod from "zod"
 
 import { type CommandComponent, useCommandTask } from "../../cli-kit/index.ts"
+import { extractBoroughPairs } from "../../gazetteer-pipeline/borough-pairs.ts"
+import { extractLieuDitPairs } from "../../gazetteer-pipeline/lieudit-pairs.ts"
 import { PairIndexBuilder, applyPairIndexHoldout } from "../../gazetteer-pipeline/pair-index.ts"
 
 /**
@@ -61,6 +63,15 @@ const EXPECTED_GB_PAIR_COUNT = 19_209
  */
 const RUNG3_PRE_FOLD_CENSUS_LINE_COUNT = 19_431
 
+/**
+ * The US instance's cross-check (hierarchy campaign R5), measured 2026-08-01 against the shipped
+ * `admin-global-priority.db`. Unlike GB there is no postal register in the mix — every pair is WOF-sourced (borough +
+ * neighbourhood children under locality/localadmin/borough parents, see `PAIR_PLACETYPES_BY_COUNTRY`), so this number
+ * tracks the WOF snapshot alone. A snapshot refresh legitimately moves it; re-anchor the constant deliberately, after
+ * inspecting the diff, rather than relaxing the gate.
+ */
+const EXPECTED_US_PAIR_COUNT = 47_878
+
 /**
  * Known (child, parent) pairs probed after write as a self-check — PER COUNTRY, keyed by the `--country` code. Probing
  * another country's names against a freshly built index prints reassuring-looking `PROBE MISS` lines that verify
@@ -78,6 +89,53 @@ const PROBE_PAIRS_BY_COUNTRY: Readonly<Record<string, ReadonlyArray<readonly [ci
 		// The repeated-name convention's identity pair — the (x,x) evidence the segment rule keys on.
 		["Mangawhai", "Mangawhai"],
 	],
+	// R5 (hierarchy campaign): the US instance's probes. Unlike GB/NZ these are NOT postal-format
+	// dependent localities — USPS routes city/state/ZIP — they are the borough/neighbourhood class
+	// the schema's umbrella term covers, sourced from WOF rather than a postal register.
+	us: [
+		["Astoria", "Queens"],
+		["Park Slope", "Brooklyn"],
+		["Manhattan", "New York"],
+	],
+	// R10: the IN instance. Indian addresses carry an area/locality line above the city
+	// ("Indiranagar, Bengaluru"), which is the dependent-locality slot.
+	in: [
+		["Indiranagar", "Bangalore"],
+		["Mulund East", "Mumbai"],
+	],
+	// R11: the ES + IT instances. Spanish barrios and Italian quartieri under their municipio/comune.
+	es: [
+		["Aravaca", "Madrid"],
+		["Triana", "Sevilla"],
+	],
+	it: [
+		["Barona", "Milano"],
+		["Trastevere", "Roma"],
+	],
+	// R9: the DE instance. Ortsteile/Stadtteile under their Gemeinde — the line German addresses
+	// carry when they carry one at all (the Ortsteil sits above "PLZ Stadt", never inside it).
+	de: [
+		["Nippes", "Köln"],
+		["Schwabing", "München"],
+	],
+	// R6: the FR instance. These are LIEUX-DITS under their communes (BAN `nom_ld`), not quartiers —
+	// see gazetteer-pipeline/lieudit-pairs.ts for why the French source differs from the US one.
+	fr: [
+		["Pinsonnac", "Montpeyroux"],
+		["Line", "Salignac-Eyvigues"],
+	],
+}
+
+/**
+ * Split a comma-separated path list, tolerating whitespace and an absent value. Each secondary source stays its OWN
+ * file rather than being pre-merged into a blob, so every one keeps a distinct provenance md5 in the header — which is
+ * what lets a freshness guard notice that exactly one of them changed.
+ */
+function splitPathList(value: string | undefined): string[] {
+	return (value ?? "")
+		.split(",")
+		.map((path) => path.trim())
+		.filter(Boolean)
 }
 
 const OptionsSchema = zod.object({
@@ -110,6 +168,22 @@ const OptionsSchema = zod.object({
 				"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."
 		),
+	pairsJsonl: zod
+		.string()
+		.optional()
+		.describe(
+			"Secondary pairs JSONL ({child, parent} per line) merged through the same fold — hierarchy campaign R3 (ONSPD London wards etc.)"
+		),
+	boroughDb: zod
+		.string()
+		.optional()
+		.describe("WOF admin DB path — merge borough (child, parent) pairs for the country (hierarchy campaign R2)"),
+	banDir: zod
+		.string()
+		.optional()
+		.describe(
+			"BAN adresses-<dept>.csv directory — merge FR (lieu-dit, commune) pairs through ban/sdk's cleanLieuDit filter (hierarchy campaign R6)"
+		),
 	holdoutSeed: zod
 		.number()
 		.default(42)
@@ -121,12 +195,23 @@ 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")
+		// The PPD tuples CSV is a GB national register — there is no equivalent for the US instance (USPS routes
+		// city/state/ZIP, so no postal source carries dependent localities). A country whose pairs come entirely from
+		// the WOF/secondary sources below runs with NO CSV rather than being handed an empty one.
+		const sourcePath =
+			options.source ?? (country === "gb" ? String(dataRootPath("ppd", "2026-07-22", "gb-tuples.csv")) : undefined)
 
-		if (!existsSync(sourcePath)) {
+		if (sourcePath && !existsSync(sourcePath)) {
 			throw new Error(`pair-index: source CSV not found: ${sourcePath}`)
 		}
 
+		if (!sourcePath && !options.boroughDb && !options.pairsJsonl && !options.banDir) {
+			throw new Error(
+				`pair-index: country "${country}" has no PPD default — pass --source, --borough-db, --pairs-jsonl or --ban-dir, ` +
+					`or the build would write an empty index.`
+			)
+		}
+
 		const builder = new PairIndexBuilder()
 		let header: string[] | null = null
 		let cityIx = -1
@@ -135,24 +220,82 @@ const GazetteerPairIndex: CommandComponent<typeof OptionsSchema> = ({ options })
 		// 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(",")}`)
+		if (sourcePath) {
+			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
 				}
 
-				continue
+				builder.addRow(cells[cityIx] ?? "", cells[districtIx] ?? "")
 			}
+		}
+
+		// R2 (hierarchy campaign): borough pairs from the WOF admin DB, through the SAME fold/dedupe
+		// as the CSV rows (boroughs project onto dependent_locality — plan/reference/placetype-evidence).
+		let boroughsAdded = 0
+
+		if (options.boroughDb) {
+			const before = builder.distinctCount
+
+			for (const pair of extractBoroughPairs(options.boroughDb, country.toUpperCase())) {
+				builder.addRow(pair.child, pair.parent)
+			}
+
+			boroughsAdded = builder.distinctCount - before
 
-			builder.addRow(cells[cityIx] ?? "", cells[districtIx] ?? "")
+			console.error(`pair-index: +${boroughsAdded} distinct borough pairs (WOF admin DB)`)
+		}
+
+		// R6: FR lieu-dit pairs from the raw BAN dump. Streams ~26M rows, so it is the slowest source by far —
+		// deliberately opt-in per build rather than a default.
+		if (options.banDir) {
+			const before = builder.distinctCount
+			const { pairs, rowsWithLieuDit, filesRead } = await extractLieuDitPairs(options.banDir)
+
+			for (const pair of pairs) {
+				builder.addRow(pair.child, pair.parent)
+			}
+
+			boroughsAdded += builder.distinctCount - before
+
+			console.error(
+				`pair-index: +${builder.distinctCount - before} distinct lieu-dit pairs ` +
+					`(${filesRead} départements, ${rowsWithLieuDit.toLocaleString()} rows with a clean lieu-dit)`
+			)
+		}
+
+		// R3: generic secondary pairs (ONSPD-derived London ward pairs; future NI/IE sources) — the
+		// same fold/dedupe path, counted into the cross-check delta alongside the boroughs.
+		if (options.pairsJsonl) {
+			for (const path of splitPathList(options.pairsJsonl)) {
+				const before = builder.distinctCount
+
+				for (const line of readFileSync(path, "utf8").split("\n")) {
+					if (!line.trim()) continue
+
+					const pair = JSON.parse(line) as { child: string; parent: string }
+
+					builder.addRow(pair.child, pair.parent)
+				}
+
+				boroughsAdded += builder.distinctCount - before
+
+				console.error(
+					`pair-index: +${builder.distinctCount - before} distinct secondary pairs (${path.split("/").pop()})`
+				)
+			}
 		}
 
 		const built = builder.finish()
@@ -167,7 +310,13 @@ const GazetteerPairIndex: CommandComponent<typeof OptionsSchema> = ({ options })
 			options.holdoutSeed
 		)
 
-		const sourceMD5 = await md5File(sourcePath)
+		// Provenance covers every source that contributed rows, in the order they were folded in — a US build has no
+		// CSV at all, so an unconditional single-element array would have claimed a source the artifact never read.
+		const sourceMD5s = [
+			...(sourcePath ? [await md5File(sourcePath)] : []),
+			...(options.boroughDb ? [await md5File(options.boroughDb)] : []),
+			...(await Promise.all(splitPathList(options.pairsJsonl).map((path) => md5File(path)))),
+		]
 
 		// `transitionBeta` is spread conditionally so an omitted flag writes NO header key at all (a
 		// beta-less binary, byte-shape-identical to every pre-TRANSITION-BETA artifact) — not a null/0.
@@ -176,7 +325,7 @@ const GazetteerPairIndex: CommandComponent<typeof OptionsSchema> = ({ options })
 			delta: options.delta,
 			schemaVersion: 1,
 			foldVersion: 1,
-			sourceMD5s: [sourceMD5],
+			sourceMD5s,
 			buildDate: new Date().toISOString(),
 			...(options.transitionBeta !== undefined ? { transitionBeta: options.transitionBeta } : {}),
 		}
@@ -228,11 +377,17 @@ const GazetteerPairIndex: CommandComponent<typeof OptionsSchema> = ({ options })
 		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)`
+					? `(cross-check skipped under --holdout-fraction; ${preHoldoutCount.toLocaleString()} distinct pairs before holdout, expects ${(EXPECTED_GB_PAIR_COUNT + boroughsAdded).toLocaleString()})${preFoldSuffix}`
+					: preHoldoutCount === EXPECTED_GB_PAIR_COUNT + boroughsAdded
+						? `CROSS-CHECK PASS: ${preHoldoutCount.toLocaleString()} distinct pairs (baseline ${EXPECTED_GB_PAIR_COUNT.toLocaleString()} + ${boroughsAdded} borough)${preFoldSuffix}`
+						: `CROSS-CHECK BLOCKED: ${preHoldoutCount.toLocaleString()} distinct pairs != baseline ${EXPECTED_GB_PAIR_COUNT.toLocaleString()} + ${boroughsAdded} borough — investigate fold divergence before trusting this artifact${preFoldSuffix}`
+				: country === "us"
+					? options.holdoutFraction > 0
+						? `(cross-check skipped under --holdout-fraction; ${preHoldoutCount.toLocaleString()} distinct pairs before holdout, expects ${EXPECTED_US_PAIR_COUNT.toLocaleString()})`
+						: preHoldoutCount === EXPECTED_US_PAIR_COUNT
+							? `CROSS-CHECK PASS: ${preHoldoutCount.toLocaleString()} distinct pairs (all WOF-sourced; no postal register)`
+							: `CROSS-CHECK BLOCKED: ${preHoldoutCount.toLocaleString()} distinct pairs != ${EXPECTED_US_PAIR_COUNT.toLocaleString()} — a WOF snapshot refresh moves this number, so re-anchor the constant DELIBERATELY (with the diff inspected) rather than trusting the artifact`
+					: `(cross-check only registered for gb/us; ${preHoldoutCount.toLocaleString()} distinct pairs)`
 
 		const holdoutLine =
 			options.holdoutFraction > 0