@mailwoman/corpus 9.2.0 → 9.4.0

package/lib/build.ts

@@ -0,0 +1,378 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   End-to-end corpus build (Phase 1 task #10 in the plan).
+ *
+ *   `buildCorpus(opts)` orchestrates every stage of the pipeline:
+ *
+ *   1. **Adapter runs** — drives every adapter in turn (via `runAdapter`), writing
+ *        `<intermediate>/<adapter.id>/canonical.jsonl` slices.
+ *   2. **Synthesis** — optional. For each canonical row, every applicable augmentation in the row's
+ *        country-default policy emits an augmented row alongside the original.
+ *   3. **Alignment** — every row (original + augmented) is aligned via `alignRow`. Successes go to
+ *        `labeled.jsonl`; quarantines are appended to `quarantine.jsonl` with reasons.
+ *   4. **Splits** — `splitRows` partitions labeled `source_id`s into train/val/test by locality holdout.
+ *        Manifest written to `splits/SPLIT_MANIFEST.json` + per-split `train.txt` / `val.txt` /
+ *        `test.txt`.
+ *   5. **Parquet slices** — `writeSlices` streams labeled rows into 1M-row `.parquet` slices per split
+ *        under `corpus-v<version>/{train,val,test}/part-NNNN.parquet` (SNAPPY-compressed, 50k-row
+ *        row groups), with per-slice checksums + per-stage manifest in
+ *        `corpus-v<version>/MANIFEST.json`.
+ *   6. **Top-level manifest** — `<outputDir>/MANIFEST.json` ties every per-stage manifest together with
+ *        a top-level corpus_version, built_at, and aggregate counts.
+ *
+ *   Output layout:
+ *
+ *   ```
+ *   <outputDir>/
+ *   MANIFEST.json
+ *   intermediate/
+ *     <adapter.id>/canonical.jsonl   # one per adapter
+ *     labeled.jsonl                  # post-alignment, pre-slice
+ *     quarantine.jsonl               # rows that failed alignment
+ *   splits/
+ *     SPLIT_MANIFEST.json
+ *     train.txt / val.txt / test.txt
+ *   corpus-v<version>/
+ *     MANIFEST.json
+ *     train/part-NNNN.parquet
+ *     val/part-NNNN.parquet
+ *     test/part-NNNN.parquet
+ * ```
+ *
+ *   The intermediate files live alongside the final slices for reproducibility + debugging. Operators
+ *   can `rm -rf intermediate/` after the build if disk is tight; the final `corpus-v<version>/` is
+ *   self-contained.
+ */
+
+import { pathExists, readLocalJSONFile } from "@mailwoman/core/fs/readers"
+import { openWriteStream, type WriteStream } from "@mailwoman/core/fs/streams"
+import { writeLocalJSONFile, makeDirectories } from "@mailwoman/core/fs/writers"
+import { join } from "path-ts"
+import { JSONSpliterator } from "spliterator"
+
+import { defaultAdapterRegistry } from "#adapters/utils"
+import { $public } from "#env"
+import { once, runAdapter, type AdapterRunManifest } from "#runner"
+import { defaultAugmentationsForCountry, synthesizeRow } from "#synthesizers/utils"
+import type { AdapterOptions, CanonicalRow, CorpusAdapter, LabeledRow } from "#types"
+import { alignRow } from "#utils/align"
+import { licenseExcluded } from "#utils/license"
+import { writeSlices, type SliceManifest } from "#utils/parquet"
+import {
+	defaultHoldouts,
+	splitForRow,
+	writeSplitManifestsFromLabeledFiles,
+	type SplitManifest,
+	type SplitName,
+} from "#utils/split"
+
+/**
+ * Stage tags surfaced to `onProgress`.
+ */
+export type BuildStage = "adapter-run" | "align" | "split" | "slice" | "manifest"
+
+/**
+ * Per-invocation options for `buildCorpus`.
+ */
+export interface BuildCorpusOptions {
+	/**
+	 * Root output directory. All build artifacts land beneath it.
+	 */
+	outputDir: string
+
+	/**
+	 * Corpus version (e.g. `"0.1.0"`). Stamped onto every row + into the output dir name.
+	 */
+	corpusVersion: string
+
+	/**
+	 * Adapters to drive, in order. Defaults to `defaultAdapterRegistry.list()`. Pass an explicit list to filter (e.g.
+	 * `[wofAdminAdapter]` for a smoke run).
+	 */
+	adapters?: readonly CorpusAdapter[]
+
+	/**
+	 * Per-adapter `AdapterOptions` — looked up by adapter id. Adapters whose id is missing from this map are skipped (and
+	 * noted in the manifest).
+	 */
+	adapterInputs: Record<string, AdapterOptions>
+
+	/**
+	 * Enable synthesis pass. Default `true`. Set `false` for fixture-driven smoke tests.
+	 */
+	synthesize?: boolean
+
+	/**
+	 * Forwarded to `writeSlices`. Default 1_000_000.
+	 */
+	rowsPerSlice?: number
+
+	/**
+	 * Progress hook. Errors thrown abort the build.
+	 */
+	onProgress?: (stage: BuildStage, message: string) => void
+
+	/**
+	 * License kinds to PURPOSELY exclude from this build (#26). Compiled patterns (see `compileLicenseExcludes` /
+	 * `SHARE_ALIKE_PATTERN` in `license.ts`); a row whose `license` matches any is dropped at ingest. Default (omitted)
+	 * includes EVERYTHING — exclusion is a deliberate act, not a silent default. A proprietary-weights build passes the
+	 * share-alike set (`--exclude-share-alike`).
+	 */
+	excludeLicenses?: readonly RegExp[]
+}
+
+/**
+ * Top-level manifest tying every stage together.
+ */
+export interface BuildCorpusManifest {
+	corpus_version: string
+	built_at: string
+	adapters: AdapterRunManifest[]
+	skipped_adapters: string[]
+	splits: { counts: SplitManifest["counts"]; holdouts: SplitManifest["holdouts"] }
+	slices: { counts: SliceManifest["counts"]; total_rows: number }
+	quarantine_count: number
+	total_aligned_rows: number
+	/**
+	 * Resolved license set across all INCLUDED rows (license string → row count), + the count dropped by
+	 * `excludeLicenses` (#26). The model card derives its data-attribution table from `licenses`.
+	 */
+	licenses: Record<string, number>
+	excluded_by_license: number
+}
+
+/**
+ * Drive the full corpus build to completion.
+ *
+ * Memory profile: the function maintains an in-memory `Map<source_id, SplitName>` to bridge the align → slice hand-off.
+ * For Phase 1 fixture-scale runs (≤ 10⁴ rows) this is trivial. For real 5M+ runs, the map fits comfortably in a few
+ * hundred MB; the canonical.jsonl and labeled.jsonl payloads stream and never sit in memory.
+ */
+export async function buildCorpus(opts: BuildCorpusOptions): Promise<BuildCorpusManifest> {
+	const adapters = opts.adapters ?? defaultAdapterRegistry.list()
+	const synthesize = opts.synthesize ?? true
+	const rowsPerSlice = opts.rowsPerSlice ?? 1_000_000
+	const built_at = new Date().toISOString()
+
+	await makeDirectories(opts.outputDir)
+	const intermediateDir = join(opts.outputDir, "intermediate")
+	await makeDirectories(intermediateDir)
+
+	// 1. Adapter runs.
+	const adapterRuns: AdapterRunManifest[] = []
+	const skipped: string[] = []
+
+	for (const adapter of adapters) {
+		const adapterOptions = opts.adapterInputs[adapter.id]
+
+		if (!adapterOptions) {
+			skipped.push(adapter.id)
+			opts.onProgress?.("adapter-run", `skipped ${adapter.id} (no input configured)`)
+
+			continue
+		}
+
+		// Opt-in resume (MAILWOMAN_RESUME=1): if a complete per-adapter canonical.jsonl + MANIFEST.json
+		// already exist, reuse them instead of re-emitting. The MANIFEST is written only after the
+		// canonical is fully flushed, so its presence guarantees completeness; row order is identical,
+		// so downstream holdout-split determinism is preserved. Recovers an align-phase crash without
+		// redoing the (expensive) emit phase. Default (unset) re-emits, preserving correctness. (2026-06-12.)
+		const adapterDir = join(intermediateDir, adapter.id)
+		const cachedManifest = join(adapterDir, "MANIFEST.json")
+
+		if (
+			$public.MAILWOMAN_RESUME === "1" &&
+			(await pathExists(cachedManifest)) &&
+			(await pathExists(join(adapterDir, "canonical.jsonl")))
+		) {
+			const cached = await readLocalJSONFile<AdapterRunManifest>(cachedManifest)
+			opts.onProgress?.("adapter-run", `resumed ${adapter.id} (reused ${cached.yielded} canonical rows)`)
+			adapterRuns.push(cached)
+
+			continue
+		}
+
+		opts.onProgress?.("adapter-run", `running ${adapter.id}`)
+
+		const m = await runAdapter({
+			adapter,
+			adapterOptions,
+			outputDir: intermediateDir,
+			corpusVersion: opts.corpusVersion,
+		})
+
+		adapterRuns.push(m)
+	}
+
+	// 2 + 3. Synthesis + alignment: stream every canonical.jsonl, optionally augment, align,
+	// and route each labeled row directly to its split-specific JSONL (`labeled-{train,val,test}.
+	// jsonl`). Memory cost is O(1) — the prior in-memory `splitInputs` array + `splitByIDMap`
+	// + `SplitManifest.{train,val,test}` arrays are gone; per-row split is decided inline via
+	// `splitForRow` (a pure function of source_id + region + holdout policy).
+	const labeledPaths: Record<SplitName, string> = {
+		train: join(intermediateDir, "labeled-train.jsonl"),
+		val: join(intermediateDir, "labeled-val.jsonl"),
+		test: join(intermediateDir, "labeled-test.jsonl"),
+	}
+
+	const labeledStreams: Record<SplitName, WriteStream> = {
+		train: openWriteStream(labeledPaths.train, { encoding: "utf8" }),
+		val: openWriteStream(labeledPaths.val, { encoding: "utf8" }),
+		test: openWriteStream(labeledPaths.test, { encoding: "utf8" }),
+	}
+
+	const quarantinePath = join(intermediateDir, "quarantine.jsonl")
+	const quarantineStream = openWriteStream(quarantinePath, { encoding: "utf8" })
+
+	let aligned = 0
+	let quarantined = 0
+	const counts: Record<SplitName, number> = { train: 0, val: 0, test: 0 }
+	const holdouts = defaultHoldouts()
+	// License accounting + the deliberate exclusion filter (#26). `licenseCounts` is the resolved
+	// license set (→ manifest + model-card attribution); `excludeLicenses` (empty by default → include
+	// everything) is the operator's PURPOSEFUL exclusion, never a silent drop.
+	const excludeLicenses = opts.excludeLicenses ?? []
+	const licenseCounts = new Map<string, number>()
+	let excludedByLicense = 0
+
+	const writeQuarantine = (row: CanonicalRow, reason: string): void => {
+		quarantineStream.write(`${JSON.stringify({ row, reason })}\n`)
+	}
+
+	for (const adapterRun of adapterRuns) {
+		opts.onProgress?.("align", `aligning ${adapterRun.adapter_id}`)
+
+		for await (const row of streamJSONL<CanonicalRow>(adapterRun.jsonl_path)) {
+			licenseCounts.set(row.license, (licenseCounts.get(row.license) ?? 0) + 1)
+
+			// Deliberate license exclusion (#26): drop a row ONLY when the operator named its license
+			// kind via `excludeLicenses`. Default (no patterns) keeps everything — exclusion is a
+			// purposeful act, not a silent default. Counted BEFORE the drop so the manifest's license
+			// set reflects what the corpus actually CONTAINED, and `excluded_by_license` what was removed.
+			if (licenseExcluded(row.license, excludeLicenses)) {
+				excludedByLicense++
+
+				continue
+			}
+
+			const fanned: CanonicalRow[] = [row]
+
+			if (synthesize) {
+				for (const aug of synthesizeRow(row, defaultAugmentationsForCountry(row.country))) {
+					fanned.push(aug)
+				}
+			}
+
+			for (const r of fanned) {
+				let result: ReturnType<typeof alignRow>
+
+				try {
+					result = alignRow(r)
+				} catch (error) {
+					// Last-resort robustness (2026-06-12): no single row may crash a multi-hour build.
+					// alignRow's targeted paths normalize/quarantine known issues with specific reasons;
+					// this catches any UNKNOWN throw (e.g. assertSpanInvariants on an unforeseen span
+					// shape) → quarantine + continue. A spike in `align-threw` reasons is a finding.
+					writeQuarantine(r, `align-threw:${(error as Error).message.slice(0, 160)}`)
+
+					quarantined++
+
+					continue
+				}
+
+				if (result.kind === "labeled") {
+					const split = splitForRow(result.row, holdouts)
+					labeledStreams[split].write(`${JSON.stringify(result.row)}\n`)
+
+					counts[split]++
+
+					aligned++
+				} else {
+					writeQuarantine(r, result.row.reason)
+
+					quarantined++
+				}
+			}
+		}
+	}
+
+	for (const s of Object.values(labeledStreams)) {
+		s.end()
+	}
+
+	quarantineStream.end()
+	await Promise.all([...Object.values(labeledStreams).map((s) => once(s, "close")), once(quarantineStream, "close")])
+
+	// 4. Splits — manifest derived by streaming the per-split labeled files; no in-memory
+	// source-id arrays. `sort(1)` from coreutils produces the deterministic per-split .txt
+	// manifests with disk spill for splits that exceed in-memory thresholds.
+	opts.onProgress?.("split", `splitting ${aligned} aligned rows`)
+	const splitsDir = join(opts.outputDir, "splits")
+
+	const splitCounts = await writeSplitManifestsFromLabeledFiles({
+		labeledPaths,
+		outputDir: splitsDir,
+		corpusVersion: opts.corpusVersion,
+		counts,
+		holdouts,
+	})
+
+	// 5. Parquet slices — per-split labeled JSONL streams in, sliced `.parquet` out. The prior
+	// `splitFor(source_id)` callback (and the `Map<source_id, SplitName>` behind it) is gone.
+	opts.onProgress?.("slice", "writing parquet slices")
+
+	const sliceManifest = await writeSlices(
+		{
+			train: streamJSONL<LabeledRow>(labeledPaths.train),
+			val: streamJSONL<LabeledRow>(labeledPaths.val),
+			test: streamJSONL<LabeledRow>(labeledPaths.test),
+		},
+		{
+			outputDir: opts.outputDir,
+			corpusVersion: opts.corpusVersion,
+			rowsPerSlice,
+		}
+	)
+
+	// License-set visibility (#26): loudly report the resolved license set so a build is an obvious
+	// deliberate act — especially a proprietary-weights build (did you pass --exclude-share-alike?).
+	const licenseSummary = [...licenseCounts.entries()].toSorted((a, b) => b[1] - a[1])
+
+	opts.onProgress?.(
+		"manifest",
+		`license set: ${licenseSummary.map(([l, c]) => `${l}=${c}`).join(", ")}` +
+			(excludedByLicense > 0
+				? ` | EXCLUDED ${excludedByLicense} rows by --exclude-licenses`
+				: " | NO license exclusion applied (all rows kept)")
+	)
+
+	// 6. Top-level manifest.
+	opts.onProgress?.("manifest", "writing top-level MANIFEST.json")
+
+	const manifest: BuildCorpusManifest = {
+		corpus_version: opts.corpusVersion,
+		built_at,
+		adapters: adapterRuns,
+		skipped_adapters: skipped,
+		splits: { counts: splitCounts, holdouts },
+		slices: { counts: sliceManifest.counts, total_rows: sliceManifest.total_rows },
+		quarantine_count: quarantined,
+		total_aligned_rows: aligned,
+		licenses: Object.fromEntries(licenseSummary),
+		excluded_by_license: excludedByLicense,
+	}
+
+	await writeLocalJSONFile(manifest, opts.outputDir, "MANIFEST.json")
+
+	return manifest
+}
+
+async function* streamJSONL<T>(path: string): AsyncIterable<T> {
+	// JSONSpliterator yields already-parsed rows (skipEmpty is on by default, so blank
+	// lines are dropped at the row level) and throws SyntaxError on a malformed row —
+	// same fail-loud behavior as the prior readline + bare `JSON.parse`.
+	yield* JSONSpliterator.fromAsync<T>(path)
+}

package/lib/env.ts

@@ -0,0 +1,50 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * Environment variables the corpus build and its acquisition tooling read.
+ */
+
+import { $private as corePrivate, $public as corePublic, liveEnv } from "@mailwoman/core/env"
+import { z } from "zod"
+
+/**
+ * Corpus build settings.
+ */
+export const PublicCorpusEnvSchema = z.object({
+	MAILWOMAN_RESUME: z.string().optional().meta({
+		title: "Build resume",
+		description: "Resume-state override used by corpus build tooling.",
+	}),
+})
+
+/**
+ * Credentials the corpus acquisition and golden-expansion tooling send. Never log their values.
+ */
+export const PrivateCorpusEnvSchema = z.object({
+	// OpenAddresses batch-download API token (`corpus/lib/tools/fetch/openaddresses.ts`).
+	OA_BATCH_TOKEN: z.string().optional().meta({
+		title: "OpenAddresses batch token",
+		description: "API token used by the OpenAddresses batch-download corpus fetcher.",
+	}),
+	// LLM API keys for the corpus golden-expansion tooling.
+	DEEPSEEK_API_KEY: z.string().optional().meta({
+		title: "DeepSeek API key",
+		description: "API key used by corpus golden-expansion tooling when calling DeepSeek.",
+	}),
+	ANTHROPIC_API_KEY: z.string().optional().meta({
+		title: "Anthropic API key",
+		description: "API key used by corpus golden-expansion tooling when calling Anthropic.",
+	}),
+})
+
+/**
+ * Live corpus settings over core's, sharing core's getters and cached values.
+ */
+export const $public = liveEnv(PublicCorpusEnvSchema, corePublic)
+
+/**
+ * Live corpus credentials over core's. Never log their values.
+ */
+export const $private = liveEnv(PrivateCorpusEnvSchema, corePrivate)

package/lib/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+export * from "#adapters/utils/index"
+export * from "#adapters/gnaf/assemble"
+export * from "#adapters/index"
+export * from "#build"
+export * from "#runner"
+export * from "#recipes/index"
+export * from "#types"

package/lib/recipes/anchor-absorption.ts

@@ -0,0 +1,101 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `anchor-absorption` slice recipe (#220/#723, Probe A1) — self-generates `--count` rows from
+ *   {@link synthesizeAnchorAbsorptionRow}'s 6-slice mix (CASE-H / CASE-P-us-rural / CASE-P-de /
+ *   anchor-fp / locale-ambig / standard), aligns each to BIO, and emits a labeled JSONL. The
+ *   LEADING 5-digit on CASE-H/anchor-fp/locale-ambig is sampled from the REAL US ZIPs in the
+ *   postcode-anchor lookup, so the shaped-painted anchor fires on it exactly as inference does —
+ *   teaching the model to OVERRIDE a present anchor from context. Ported from
+ *   scripts/build-anchor-absorption-slice.mjs.
+ */
+
+import { dataRootPath } from "@mailwoman/core/data-root"
+import { readLocalJSONFile } from "@mailwoman/core/fs/readers"
+import { makeLcg } from "@mailwoman/core/utils"
+import type { PathBuilderLike } from "path-ts"
+
+import { sliceSourceID, type CorpusRecipe } from "#recipes/scaffold"
+import { synthesizeAnchorAbsorptionRow } from "#synthesizers/anchor-absorption"
+import { alignRow } from "#utils"
+/**
+ * The leading-5-digit source: the real US ZIPs in the postcode anchor's pilot lookup. Resolved through the data-root
+ * helper (the lab default is `$MAILWOMAN_DATA_ROOT`), never re-hardcoded.
+ */
+const ANCHOR_LOOKUP = dataRootPath("anchor", "pilot-anchor-lookup.json")
+
+/**
+ * The real US ZIPs in the anchor lookup (entries whose value is a `[{ US: … }]` candidate list).
+ */
+async function loadRealUsZips(path: PathBuilderLike): Promise<string[]> {
+	const d = await readLocalJSONFile<Record<string, unknown>>(path)
+	const zips: string[] = []
+
+	for (const [pc, v] of Object.entries(d)) {
+		if (Array.isArray(v) && v[0] && typeof v[0] === "object" && "US" in (v[0] as object) && /^\d{5}$/.test(pc)) {
+			zips.push(pc)
+		}
+	}
+
+	return zips
+}
+
+/**
+ * Slice recipe registered with the corpus builder — see the file header for the parse behaviour it exists to exercise,
+ * and `description` below for the surface form it generates.
+ */
+export const anchorAbsorptionRecipe: CorpusRecipe = {
+	name: "anchor-absorption",
+	description: "Anchor-absorption counter-augmentation (#220/#723): 6-slice mix → synthesizeAnchorAbsorptionRow",
+	mode: "generate",
+	async run(opts, write) {
+		// Emit PRNG: the legacy build-anchor-absorption-slice.mjs seeded an LCG (lcg(opts.seed)).
+		const random = makeLcg(opts.seed)
+		const source = opts.sourceName ?? "synth-anchor-absorption"
+		const count = opts.count ?? 50_000
+		const realZips = await loadRealUsZips(ANCHOR_LOOKUP)
+
+		console.error(`Loaded ${realZips.length} real US ZIPs from the anchor lookup (the leading-5-digit source).`)
+
+		let written = 0
+		let quarantined = 0
+		const byTemplate: Record<string, number> = {}
+
+		for (let i = 0; i < count; i++) {
+			const synth = synthesizeAnchorAbsorptionRow({ random, realZips })
+			const country = synth.locale.split("-")[1]
+
+			// "en-US" -> "US", "de-DE" -> "DE"
+			const canonical = {
+				raw: synth.raw,
+				components: synth.components,
+				country,
+				locale: synth.locale,
+				source,
+				source_id: sliceSourceID(source, { v: String(i) }),
+			}
+
+			const aligned = alignRow(canonical as Parameters<typeof alignRow>[0])
+
+			if (aligned.kind !== "labeled") {
+				quarantined++
+
+				continue
+			}
+
+			write(
+				JSON.stringify({ ...aligned.row, synth_method: "anchor-absorption", synth_template: synth.template }) + "\n"
+			)
+
+			written++
+			byTemplate[synth.template] = (byTemplate[synth.template] ?? 0) + 1
+		}
+
+		console.error(`\nwrote ${written} rows (${quarantined} quarantined)`)
+		console.error("  by slice:", JSON.stringify(byTemplate))
+
+		return { emitted: written, skipped: quarantined }
+	},
+}

package/lib/recipes/bare-country.ts

@@ -0,0 +1,95 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `bare-country` — the country name as the WHOLE query. Addresses almost never consist of one bare
+ *   country name, so the class is out of the model's training distribution and the tag is a coin
+ *   flip: measured on the 2026-08-13 panel, France/Germany/United States/New Zealand parsed
+ *   `country` while Japan/China/Nigeria/Australia/Deutschland parsed `locality`. The retrieval-side
+ *   bare-country race (#1651) covers the answer either way; this slice closes the PARSE half so the
+ *   tag itself is right.
+ *
+ *   Source is the codex country table — every ISO canonical English name plus the curated surface
+ *   forms (endonyms and long-form names). The 2–3 letter CODES are deliberately excluded: a bare
+ *   `JP` or `GER` is an abbreviation register with its own ambiguity surface (`IN`, `DE`, `TO` are
+ *   English words), and teaching it here would be an unmeasured claim. Case augmentation is the
+ *   loader's job, as everywhere.
+ */
+
+import { COUNTRY_SURFACE_FORMS, CountryNames, matchCountry } from "@mailwoman/codex/country"
+import { mulberry32 as makeMulberry32 } from "@mailwoman/core/utils"
+
+import { alignAndWrite, type CorpusRecipe, sliceSourceID } from "#recipes/scaffold"
+/**
+ * Surfaces shorter than this are the code register (`JP`, `GER`), not a name — excluded (see the module doc).
+ */
+const MIN_NAME_LENGTH = 4
+
+/**
+ * Every (surface, iso2) pair the slice emits: the ISO canonical names plus each country's curated surface forms,
+ * deduplicated on the surface string (a form shared across countries — none known — would keep its first bearer).
+ */
+function* bareCountrySurfaces(): Generator<{ surface: string; iso2: string }> {
+	const seen = new Set<string>()
+
+	for (const [iso2, forms] of Object.entries(COUNTRY_SURFACE_FORMS)) {
+		for (const surface of forms) {
+			if (surface.length < MIN_NAME_LENGTH || seen.has(surface)) continue
+			seen.add(surface)
+			yield { surface, iso2 }
+		}
+	}
+
+	for (const name of CountryNames) {
+		if (name.length < MIN_NAME_LENGTH || seen.has(name)) continue
+		const matched = matchCountry(name)
+
+		if (!matched) continue
+		seen.add(name)
+		yield { surface: name, iso2: matched.iso2 }
+	}
+}
+
+/**
+ * Slice recipe registered with the corpus builder — see the file header for the parse behaviour it exists to exercise,
+ * and `description` below for the surface form it generates.
+ */
+export const bareCountryRecipe: CorpusRecipe = {
+	name: "bare-country",
+	description: "The country name as the whole query (#1651 parse half): ISO names + curated endonyms, no codes",
+	mode: "generate",
+	async run(opts, write) {
+		// Seeded for parity with the other recipes; the surfaces themselves drive the content.
+		makeMulberry32(opts.seed)
+		let read = 0
+		let emitted = 0
+		let skipped = 0
+
+		for (const { surface, iso2 } of bareCountrySurfaces()) {
+			read++
+
+			const components: Record<string, string> = { country: surface }
+			const source_id = sliceSourceID("synth-bare-country", { country: surface, cc: iso2, v: String(read) })
+
+			const canonical = {
+				raw: surface,
+				components,
+				country: iso2,
+				locale: "und",
+				source: "synth-bare-country",
+				source_id,
+				corpus_version: "0.11.0",
+				license: "Synthetic — bare-country; surfaces from the codex country table (ISO 3166 + curated forms)",
+			}
+
+			if (alignAndWrite(write, canonical, "bare-country")) {
+				emitted++
+			} else {
+				skipped++
+			}
+		}
+
+		return { read, emitted, skipped }
+	},
+}