@mailwoman/corpus 9.3.0 → 10.0.0

package/lib/tools/fetch/geonames/postal.ts

@@ -0,0 +1,180 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Fetch the GeoNames per-country postal-code exports — the only source in this family that carries a
+ *   `(postcode, locality, region)` triple with the NAMES inline.
+ *
+ *   Source : https://download.geonames.org/export/zip/<CC>.zip
+ *   License: CC-BY-4.0, attribute "GeoNames". Tier B.
+ *
+ *   ## Why this source and not a join
+ *
+ *   A postcode slice is only useful to the corpus if a postcode reaches a locality and a region. Two routes exist and
+ *   only one of them works everywhere:
+ *
+ *   - **`parent_id`** — `postalcode-intl.db` carries a real parent that resolves in the admin gazetteer (measured: NL
+ *     97.5% of rows linked, FR 90.7%, DE 66.1%, ES 34.9%, IT 27.4%, and 93.8–100% of those resolve to a
+ *     `locality`/`localadmin`). It is also the ONLY slice that does: `postalcode-geonames-intl.db` and every
+ *     `postalcode-<cc>-overture.db` carry `parent_id = 0` on every row, so five countries have this route and the rest
+ *     have none.
+ *   - **Nearest locality centroid** — the obvious fallback, and it does not work. Scored against the `parent_id` truth
+ *     on 1,000–1,500 postcodes per country: NL 81.1%, DE 44.7%, ES 35.1%, FR 29.0%, IT 13.5%. A locality's centroid
+ *     sits at its middle, so a postcode near the edge is routinely closer to a neighbouring town's centroid than to its
+ *     own. Under 50% for four of the five, which is not a join.
+ *
+ *   The GeoNames export sidesteps both: columns 3 and 4 ARE the place and admin1 names, so there is nothing to join and
+ *   nothing to approximate. `@mailwoman/corpus`'s `geonames-postal` adapter consumes it directly.
+ *
+ *   ## Coverage is not universal, and the gap is the point
+ *
+ *   GeoNames publishes ~80 countries, NOT all of them. Venezuela returns 404 — so a VE postcode slice cannot be built
+ *   from this source at any effort, and that is an acquisition question rather than a build one. Ask for a country
+ *   before assuming it is there; an absent country fails as one entry, never as the whole run.
+ *
+ *   ## Row counts from this source overstate, for some countries by exactly 2×
+ *
+ *   Countries whose postcode format contains a hyphen are published TWICE — once `3750-000`, once `3750000`. Measured
+ *   on the slice built from this source: PT 395,544 rows over 197,772 distinct codes and PL 40,598 over 20,299, both
+ *   exactly 2.00×, while AU, CZ and AT (no hyphen in the format) are 1.00×. A consumer sizing a slice from the row
+ *   count doubles its estimate for those countries.
+ *
+ *   ## Why `downloadToFile` and not `APIClient`
+ *
+ *   Same split `AGENTS.md` draws and the `ourairports` sibling explains: these are static file transfers from a plain
+ *   file host, run once per refresh. The pacing, retry and caching `APIClient` exists for have nothing to act on here.
+ *
+ *   Invoke via `mailwoman corpus fetch geonames-postal --countries pt,au,nz`.
+ */
+
+import { makeDirectories } from "@mailwoman/core/fs/writers"
+import { sha256File } from "@mailwoman/core/hash"
+import { join } from "path-ts"
+
+import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download/index"
+import { downloadToFile, HTTPStatusError, writeManifest } from "#tools/fetch/download/index"
+
+/**
+ * The one status that means "the source does not publish this country" rather than "the transfer failed".
+ */
+const HTTP_NOT_FOUND = 404
+
+const SLUG = "geonames-postal"
+
+/**
+ * GeoNames' own export directory. One zip per ISO alpha-2 code, each holding `<CC>.txt` plus the shared `readme.txt`.
+ */
+const BASE_URL = "https://download.geonames.org/export/zip"
+
+/**
+ * Countries fetched when the caller names none.
+ *
+ * These are the ones the corpus wants and cannot get from `postalcode-intl.db`'s `parent_id` route — see the header for
+ * why that route covers exactly five countries. Venezuela is deliberately absent because GeoNames does not publish it.
+ */
+export const GEONAMES_POSTAL_DEFAULT_COUNTRIES = ["PT", "AU", "NZ", "IE", "BR", "ZA", "MX"] as const
+
+export interface FetchGeonamesPostalOptions extends BaseFetchOptions {
+	/**
+	 * ISO alpha-2 codes, in any casing. Defaults to {@linkcode GEONAMES_POSTAL_DEFAULT_COUNTRIES}.
+	 */
+	countries?: readonly string[]
+	/**
+	 * Export directory to read from. Defaults to GeoNames' own. Exists so the 404-is-a-coverage-finding behaviour can be
+	 * exercised against a local server rather than by asking GeoNames for a country it does not have.
+	 */
+	baseURL?: string
+}
+
+interface GeonamesPostalFileEntry {
+	country: string
+	filename: string
+	source_url: string
+	sha256: string
+	bytes: number
+}
+
+interface GeonamesPostalManifest {
+	source: string
+	base_url: string
+	license: string
+	attribution: string
+	downloaded_at: string
+	files: GeonamesPostalFileEntry[]
+	/**
+	 * Countries asked for and NOT published by GeoNames, recorded so a later reader does not spend the fetch again to
+	 * rediscover it. An absence here is a fact about the source, not about the run.
+	 */
+	unavailable: string[]
+}
+
+/**
+ * Download the requested GeoNames postal zips into `<outRoot>/geonames-postal/`, with a sibling `MANIFEST.json`
+ * carrying each file's origin URL, sha256 and byte count, plus the countries the source does not publish.
+ *
+ * A country the source does not carry is counted as failed and named in `failedCodes` — it does not stop the rest.
+ */
+export async function fetchGeonamesPostal(
+	options: FetchGeonamesPostalOptions,
+	report?: (line: string) => void
+): Promise<FetchSummary> {
+	const destDir = join(options.outRoot, SLUG)
+	await makeDirectories(destDir)
+
+	const countries = (options.countries ?? GEONAMES_POSTAL_DEFAULT_COUNTRIES).map((code) => code.trim().toUpperCase())
+	const baseURL = options.baseURL ?? BASE_URL
+	const retryDelayMs = options.retryDelayMs
+	const entries: GeonamesPostalFileEntry[] = []
+	const failedCodes: string[] = []
+	const unavailable: string[] = []
+	let fetched = 0
+	let failed = 0
+
+	for (const country of countries) {
+		const filename = `${country}.zip`
+		const url = `${baseURL}/${filename}`
+		const dest = join(destDir, filename)
+
+		report?.(`=== ${SLUG} / ${country}`)
+
+		try {
+			const { bytes } = await downloadToFile({ url, dest, timeoutMs: 300_000, retries: 2, retryDelayMs, report })
+
+			entries.push({ country, filename, source_url: url, sha256: await sha256File(dest), bytes })
+
+			fetched++
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error)
+
+			// A 404 here means GeoNames does not publish the country at all, which is a different finding from a failed
+			// transfer and the one a caller planning a slice needs to see. Branch on the TYPED status: matching message
+			// prose classified a 500 as "unpublished" whenever the URL happened to contain the substring 404 — an
+			// ephemeral test-server port did exactly that in CI.
+			if (error instanceof HTTPStatusError && error.status === HTTP_NOT_FOUND) {
+				report?.(`✗ ${country}: GeoNames does not publish a postal export for this country`)
+				unavailable.push(country)
+			} else {
+				report?.(`✗ ${country}: ${message}`)
+			}
+
+			failedCodes.push(country)
+
+			failed++
+		}
+	}
+
+	const manifest: GeonamesPostalManifest = {
+		source: "GeoNames postal codes",
+		base_url: baseURL,
+		license: "CC-BY-4.0",
+		attribution: "GeoNames",
+		downloaded_at: new Date().toISOString(),
+		files: entries,
+		unavailable,
+	}
+
+	await writeManifest(join(destDir, "MANIFEST.json"), manifest)
+
+	return { fetched, skipped: 0, failed, failedCodes }
+}

package/lib/tools/fetch/index.ts

@@ -57,6 +57,18 @@
  *   - `state-hi-schools` — Hawaii DOE school directory (original XLSX; HIDOE + PCS sheets). Tier A
  *       (state PD-equivalent).
  *   - `tiger-full` — US Census TIGER 2024 ADDRFEAT, all US counties. Tier A (US PD).
+ *   - `juso-kr` — the Korean road-name address register (주소DB, plus the English road-name DB) from
+ *       business.juso.go.kr, the LABEL source for Korean. Tier B ("이용허락범위 제한 없음", attribution).
+ *   - `localdata-kr` — Korea's local-government permit registry, one CSV per category, each row carrying
+ *       the lot-number AND road-name address of one premises plus a coordinate. The NOISY source for
+ *       Korean. Tier B (same label as `juso-kr`).
+ *   - `gcis-tw` — Taiwan's company and business registers from the economic ministry's open-data
+ *       platform, 148 files by region and industry. The NOISY source for Taiwanese. Tier B (Open
+ *       Government Data License v1.0 — the prescribed attribution is a condition of the grant).
+ *   - `acra-sg` — Singapore's ACRA corporate-entity register, 27 CSVs with the address FIELDED. The
+ *       NOISY source for Singapore. Tier B (Singapore Open Data Licence 1.0).
+ *   - `houjin-jp` — the National Tax Agency's corporate-number register, the nationwide Unicode CSV.
+ *       The NOISY source for Japanese. Tier A-equivalent (free use, no attribution condition stated).
  *
  *   License tiers per `docs/licensing-strategy.md` (or the playpen knowledge base mirror at
  *   `docs/docs/projects/mailwoman/licensing-strategy.md`). `openaddresses` is a **Tier-mixed**
@@ -97,39 +109,54 @@
  *   5. Add the source's adapter (or extend an existing one) under `corpus/src/adapters/`.
  */
 
-import { fetchBan } from "#tools/fetch/ban"
-import { fetchGeonamesDumps } from "#tools/fetch/geonames-dump"
-import { fetchGeonamesPostal } from "#tools/fetch/geonames-postal"
-import { fetchHRSA } from "#tools/fetch/hrsa"
-import { fetchIMLSPLS } from "#tools/fetch/imls-pls"
-import { fetchNAD } from "#tools/fetch/nad"
-import { fetchNPPES } from "#tools/fetch/nppes"
+import { fetchBan } from "#fr/tools/fetch/ban"
+import { fetchHoujinJP } from "#jp/tools/fetch/houjin"
+import { fetchJusoKR } from "#kr/tools/fetch/juso"
+import { fetchLocaldataKR } from "#kr/tools/fetch/localdata"
+import { fetchACRASG } from "#sg/tools/fetch/acra"
+import { fetchGeonamesDumps } from "#tools/fetch/geonames/dump"
+import { fetchGeonamesPostal } from "#tools/fetch/geonames/postal"
 import { fetchOpenAddresses } from "#tools/fetch/openaddresses"
 import { fetchOurAirports } from "#tools/fetch/ourairports"
-import { fetchStateHISchools } from "#tools/fetch/state-hi-schools"
-import { fetchStateSources } from "#tools/fetch/state-sources"
-import { fetchTigerFull } from "#tools/fetch/tiger-full"
 import { fetchWikidataSubVenue } from "#tools/fetch/wikidata-subvenue"
+import { fetchGCISTW } from "#tw/tools/fetch/gcis"
+import { fetchHRSA } from "#us/tools/fetch/hrsa"
+import { fetchIMLSPLS } from "#us/tools/fetch/imls-pls"
+import { fetchNAD } from "#us/tools/fetch/nad"
+import { fetchNPPES } from "#us/tools/fetch/nppes"
+import { fetchStateHISchools } from "#us/tools/fetch/state/hi-schools"
+import { fetchStateSources } from "#us/tools/fetch/state/sources"
+import { fetchTigerFull } from "#us/tools/fetch/tiger-full"
 
-export * from "#tools/fetch/ban"
-export * from "#tools/fetch/geonames-dump"
-export * from "#tools/fetch/geonames-postal"
-export * from "#tools/fetch/hrsa"
-export * from "#tools/fetch/imls-pls"
-export * from "#tools/fetch/nad"
-export * from "#tools/fetch/nppes"
+export * from "#sg/tools/fetch/acra"
+export * from "#fr/tools/fetch/ban"
+export * from "#tw/tools/fetch/gcis"
+export * from "#tools/fetch/geonames/dump"
+export * from "#tools/fetch/geonames/postal"
+export * from "#jp/tools/fetch/houjin"
+export * from "#us/tools/fetch/hrsa"
+export * from "#us/tools/fetch/imls-pls"
+export * from "#kr/tools/fetch/juso"
+export * from "#kr/tools/fetch/localdata"
+export * from "#us/tools/fetch/nad"
+export * from "#us/tools/fetch/nppes"
 export * from "#tools/fetch/openaddresses"
 export * from "#tools/fetch/ourairports"
-export * from "#tools/fetch/state-hi-schools"
-export * from "#tools/fetch/state-sources"
-export * from "#tools/fetch/tiger-full"
+export * from "#us/tools/fetch/state/hi-schools"
+export * from "#us/tools/fetch/state/sources"
+export * from "#us/tools/fetch/tiger-full"
 export * from "#tools/fetch/wikidata-subvenue"
 
 /**
  * The fetch-source registry: id → module entry point. Each entry point takes its own options interface.
  */
 export const FETCH_SOURCES = {
+	"acra-sg": fetchACRASG,
 	ban: fetchBan,
+	"gcis-tw": fetchGCISTW,
+	"houjin-jp": fetchHoujinJP,
+	"juso-kr": fetchJusoKR,
+	"localdata-kr": fetchLocaldataKR,
 	nad: fetchNAD,
 	"geonames-dump": fetchGeonamesDumps,
 	"geonames-postal": fetchGeonamesPostal,

package/lib/tools/fetch/openaddresses.ts

@@ -63,8 +63,8 @@ import { isoSeconds } from "@mailwoman/core/utils"
 import { join } from "path-ts"
 
 import { $private } from "#env"
-import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download"
-import { streamDownload, writeManifest } from "#tools/fetch/download"
+import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download/index"
+import { streamDownload, writeManifest } from "#tools/fetch/download/index"
 
 /**
  * Bytes per KiB — the divisor for human-readable sizes, and the floor below which a "download" is an error page rather

package/lib/tools/fetch/ourairports.ts

@@ -41,8 +41,8 @@ import { makeDirectories } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
 import { join } from "path-ts"
 
-import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download"
-import { downloadToFile, writeManifest } from "#tools/fetch/download"
+import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download/index"
+import { downloadToFile, writeManifest } from "#tools/fetch/download/index"
 
 const SLUG = "ourairports"
 

package/lib/tools/fetch/ppd.ts

@@ -90,11 +90,9 @@ export async function extractPPDTuples(
  */
 async function runPPDExtract(inputPath: string, outputPath: string): Promise<PPDExtractStats> {
 	// No `encoding` — CSVSpliterator delimits raw bytes and decodes utf-8 itself (see readTuples in
-	// recipes/locale.ts). `header: false` yields every row as data — PPD ships no header row.
+	// recipes/international/locale.ts). `header: false` yields every row as data — PPD ships no header row.
 	const rows = CSVSpliterator.fromAsync<string[]>(openReadStream(inputPath), {
-		mode: "array",
 		header: false,
-		enableQuoteHandling: true,
 	})
 
 	const out = openWriteStream(outputPath, { encoding: "utf8" })

package/lib/tools/fetch/wikidata-subvenue.ts

@@ -60,8 +60,8 @@ import { makeDirectories, writeLocalFile } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
 import { join } from "path-ts"
 
-import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download"
-import { writeManifest } from "#tools/fetch/download"
+import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download/index"
+import { writeManifest } from "#tools/fetch/download/index"
 
 const SLUG = "wikidata-subvenue"
 

package/lib/tools/golden/promote.ts

@@ -0,0 +1,340 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Promote LLM-synthesized golden-set candidates into a versioned golden dir, with
+ *   human-typed-likelihood filters + dedup. Companion to `golden-expand.ts`.
+ *
+ *   ## What it does
+ *
+ *   1. Reads a candidates JSONL from `data/eval/golden/candidates/`
+ *   2. Reads the previous-version golden dir for forward-copy + dedup base
+ *   3. Applies filters that drop candidates unlikely to be human-typed:
+ *
+ *        - Components-glued-without-commas (5+ components but <2 separators → freeform jumble)
+ *        - Postcode-at-start with many other components (US/UK conventions put postcode last; FR puts it
+ *                 before locality only)
+ *        - Suspicious-token signals (unmatched brackets, control chars, etc.)
+ *   4. Dedupes by normalized raw (case-insensitive, whitespace-collapsed)
+ *   5. Splits by country (US/FR/other) and writes `data/eval/golden/v<X.Y.Z>/{us,fr,other}.jsonl`
+ *   6. Forward-copies the prior version's adversarial.jsonl + README as-is
+ *   7. Writes MANIFEST.json with sha256 of each output file
+ *
+ *   ## Usage
+ *
+ *   ```sh
+ *   mailwoman corpus golden promote \
+ *   --input data/eval/golden/candidates/expand-20260518-162627.jsonl \
+ *   --bump-to v0.1.1 \
+ *   --prior v0.1.0
+ *   ```
+ */
+
+import { pathExists } from "@mailwoman/core/fs/readers"
+import { copyFileTo, makeDirectories, writeLocalJSONFile } from "@mailwoman/core/fs/writers"
+import { sha256File } from "@mailwoman/core/hash"
+import { foldCaseWhitespace } from "@mailwoman/normalize/fold"
+import { join } from "path-ts"
+import { createNewlineWriter, JSONSpliterator } from "spliterator"
+import { Globerator } from "spliterator/node/fs"
+
+import type { GoldenCandidateEntry as GoldenEntry } from "#utils/golden"
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+/**
+ * Components a candidate needs before it is rich enough to be worth a golden-set slot.
+ */
+const MIN_GOLDEN_COMPONENTS = 5
+
+/**
+ * Components an existing entry must still carry to survive promotion.
+ */
+const MIN_PROMOTABLE_COMPONENTS = 4
+
+/**
+ * Quote-delimited segments above which the raw line is malformed rather than merely quoted.
+ */
+const MAX_QUOTE_SEGMENTS = 3
+
+export interface PromoteStats {
+	candidatesIn: number
+	filteredOut: { glued: number; postcodeLeading: number; suspicious: number; duplicate: number; forwardDup: number }
+	kept: number
+	perCountry: Record<string, number>
+}
+
+export interface PromoteGoldenOptions {
+	/**
+	 * Candidates JSONL (required).
+	 */
+	input: string
+	/**
+	 * Target golden version dir (required, e.g. `v0.1.1`).
+	 */
+	bumpTo: string
+	/**
+	 * Previous version to forward-copy + dedup against. Default `v0.1.0`.
+	 */
+	prior?: string
+	/**
+	 * Golden dir root. Default `data/eval/golden`.
+	 */
+	goldenRoot?: string
+	/**
+	 * Skip the human-typed-likelihood filters (keep everything that passed expand-golden's validator).
+	 */
+	noFilters?: boolean
+	/**
+	 * Report what would be written but don't touch disk.
+	 */
+	dryRun?: boolean
+}
+
+// ── Filters ───────────────────────────────────────────────────────────────
+
+/**
+ * Heuristic: an address with 5+ components but fewer than 2 separators (commas/newlines/dashes) is most likely glued
+ * together rather than human-typed.
+ */
+function isComponentsGlued(entry: GoldenEntry): boolean {
+	const componentCount = Object.keys(entry.components).length
+
+	if (componentCount < MIN_GOLDEN_COMPONENTS) return false
+	const separators = (entry.raw.match(/[,\n;]/g) ?? []).length
+
+	return separators < 2
+}
+
+/**
+ * Heuristic: in US/UK conventions, postcode goes at the END of the address. If postcode appears in the first third of a
+ * multi-component raw AND there are 4+ components, the LLM probably over-aggressively reordered. FR is exempt (postcode
+ * often precedes locality there).
+ */
+function isPostcodeBadlyLeading(entry: GoldenEntry): boolean {
+	if (Object.keys(entry.components).length < MIN_PROMOTABLE_COMPONENTS) return false
+
+	if (entry.country === "FR" || entry.country === "France") return false
+	const postcode = entry.components.postcode
+
+	if (!postcode) return false
+	const postcodeIdx = entry.raw.indexOf(postcode)
+
+	if (postcodeIdx === -1) return false
+
+	return postcodeIdx < entry.raw.length / 3
+}
+
+/**
+ * Heuristic: catch-all for visually-bad outputs — unmatched brackets, control chars, suspicious punctuation that
+ * suggests the LLM emitted markup instead of an address.
+ */
+function isSuspicious(entry: GoldenEntry): boolean {
+	const raw = entry.raw
+
+	// eslint-disable-next-line no-control-regex
+	if (/[\u0000-\u001F\u007F]/.test(raw)) return true
+	const openBrackets = (raw.match(/[[({<]/g) ?? []).length
+	const closeBrackets = (raw.match(/[\])}>]/g) ?? []).length
+
+	if (openBrackets !== closeBrackets) return true
+
+	if (raw.split('"').length > MAX_QUOTE_SEGMENTS) return true
+
+	// too many quote marks
+	return false
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────
+
+export async function promoteGolden(
+	options: PromoteGoldenOptions,
+	report?: (line: string) => void
+): Promise<PromoteStats> {
+	const prior = options.prior ?? "v0.1.0"
+	const goldenRoot = options.goldenRoot ?? "data/eval/golden"
+	const applyFilters = !options.noFilters
+	const dryRun = options.dryRun ?? false
+
+	report?.(`reading candidates: ${options.input}`)
+
+	// The candidates file is the REQUIRED input, so its absence must not read as "zero candidates" —
+	// that promotes the prior version unchanged and reports success. `JSONSpliterator.fromAsync`
+	// reports a missing path as a bare `TypeError` naming its own internals, so name the path here.
+	if (!(await pathExists(options.input))) {
+		throw new Error(`Candidates file not found: ${options.input}`)
+	}
+
+	// Forward-copy base: existing entries from the prior golden version go forward verbatim,
+	// and we dedupe new candidates against them so v_new = v_old ∪ accepted_candidates.
+	const priorDir = join(goldenRoot, prior)
+	const priorEntries: { country: string; entries: GoldenEntry[] }[] = []
+	const seenNormalized = new Set<string>()
+
+	if (await pathExists(priorDir)) {
+		for await (const f of Globerator.files("jsonl", { cwd: priorDir, absolute: false })) {
+			const country = f.replace(".jsonl", "").toUpperCase()
+			const entries = await JSONSpliterator.fromAsync<GoldenEntry>(join(priorDir, f)).toArray()
+
+			priorEntries.push({ country, entries })
+
+			for (const e of entries) {
+				seenNormalized.add(foldCaseWhitespace(e.raw))
+			}
+
+			report?.(`  prior ${country}: ${entries.length} entries (forward-copy base)`)
+		}
+	} else {
+		report?.(`  ⚠ prior dir ${priorDir} not found — starting fresh`)
+	}
+
+	// Filter pass
+	const stats: PromoteStats = {
+		candidatesIn: 0,
+		filteredOut: { glued: 0, postcodeLeading: 0, suspicious: 0, duplicate: 0, forwardDup: 0 },
+		kept: 0,
+		perCountry: {},
+	}
+
+	const accepted: GoldenEntry[] = []
+	const seenInBatch = new Set<string>()
+
+	for await (const cand of JSONSpliterator.fromAsync<GoldenEntry>(options.input)) {
+		stats.candidatesIn++
+		const norm = foldCaseWhitespace(cand.raw)
+
+		// Dedup pass 1: against prior versioned golden
+		if (seenNormalized.has(norm)) {
+			stats.filteredOut.forwardDup++
+
+			continue
+		}
+
+		// Dedup pass 2: against this batch
+		if (seenInBatch.has(norm)) {
+			stats.filteredOut.duplicate++
+
+			continue
+		}
+
+		if (applyFilters) {
+			if (isComponentsGlued(cand)) {
+				stats.filteredOut.glued++
+
+				continue
+			}
+
+			if (isPostcodeBadlyLeading(cand)) {
+				stats.filteredOut.postcodeLeading++
+
+				continue
+			}
+
+			if (isSuspicious(cand)) {
+				stats.filteredOut.suspicious++
+
+				continue
+			}
+		}
+
+		accepted.push(cand)
+		seenInBatch.add(norm)
+
+		stats.kept++
+		const country = cand.country || "OTHER"
+		stats.perCountry[country] = (stats.perCountry[country] ?? 0) + 1
+	}
+
+	report?.(`  ${stats.candidatesIn} candidates loaded`)
+
+	// Bucket per country, including forward-copied entries
+	const buckets = new Map<string, GoldenEntry[]>()
+
+	for (const { country, entries } of priorEntries) {
+		// Existing files keyed by filename uppercase (us.jsonl → US, adversarial.jsonl → ADVERSARIAL)
+		buckets.set(country, [...entries])
+	}
+
+	for (const cand of accepted) {
+		const key = (cand.country || "OTHER").toUpperCase()
+
+		if (!buckets.has(key)) {
+			buckets.set(key, [])
+		}
+
+		buckets.get(key)!.push(cand)
+	}
+
+	// Output
+	const outDir = join(goldenRoot, options.bumpTo)
+	report?.(`=== plan ===`)
+	report?.(`output dir: ${outDir}${dryRun ? " (dry-run)" : ""}`)
+
+	for (const [key, entries] of buckets) {
+		report?.(`  ${key.toLowerCase()}.jsonl: ${entries.length} entries`)
+	}
+
+	report?.(`=== filter stats ===`)
+	report?.(`candidates in:        ${stats.candidatesIn}`)
+	report?.(`  filtered (glued):           ${stats.filteredOut.glued}`)
+	report?.(`  filtered (postcode-lead):   ${stats.filteredOut.postcodeLeading}`)
+	report?.(`  filtered (suspicious):      ${stats.filteredOut.suspicious}`)
+	report?.(`  filtered (dup-in-batch):    ${stats.filteredOut.duplicate}`)
+	report?.(`  filtered (dup-vs-prior):    ${stats.filteredOut.forwardDup}`)
+	report?.(`  kept:                       ${stats.kept}`)
+	report?.(`per-country (kept):`)
+
+	for (const [c, n] of Object.entries(stats.perCountry).toSorted((a, b) => b[1] - a[1])) {
+		report?.(`  ${c}: ${n}`)
+	}
+
+	if (dryRun) {
+		report?.(`(dry-run: no files written)`)
+
+		return stats
+	}
+
+	await makeDirectories(outDir)
+
+	const manifest: {
+		promoted_at: string
+		from: string
+		from_sha256: string
+		files: Record<string, { entries: number; sha256: string }>
+	} = {
+		promoted_at: new Date().toISOString(),
+		from: options.input,
+		from_sha256: await sha256File(options.input),
+		files: {},
+	}
+
+	for (const [key, entries] of buckets) {
+		const filename = `${key.toLowerCase()}.jsonl`
+		const path = join(outDir, filename)
+
+		{
+			await using out = createNewlineWriter(path)
+
+			for (const entry of entries) {
+				await out.write(JSON.stringify(entry))
+			}
+		}
+
+		manifest.files[filename] = { entries: entries.length, sha256: await sha256File(path) }
+	}
+
+	// Forward-copy non-.jsonl files (README.md, etc.) from prior
+	if (await pathExists(priorDir)) {
+		for await (const f of Globerator.from("*", { cwd: priorDir, absolute: false })) {
+			if (f.endsWith(".jsonl")) continue
+			await copyFileTo(join(priorDir, f), join(outDir, f))
+			report?.(`  forward-copied: ${f}`)
+		}
+	}
+
+	await writeLocalJSONFile(manifest, join(outDir, "MANIFEST.json"))
+	report?.(`✓ promoted to ${outDir}`)
+
+	return stats
+}