@mailwoman/corpus 7.2.0 → 7.2.1

package/src/shard-recipes/fr-order.ts

@@ -0,0 +1,283 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `fr-order` shard recipe — French reversed-order coverage (#560). Reads REAL OpenAddresses FR
+ *   tuples (`fr/countrywide.csv` from the cached zip), then for each row picks — by
+ *   `--reversed-fraction` (default 0.5) — whether to render in CANONICAL French order
+ *   (number-street, postcode-city) or one of four REVERSED / postcode-first variants the
+ *   v4.4.0→v0.5.0 regression exposed (the model misses house_number in every reversed one):
+ *
+ *   - A: "47110 Sainte-Livrade-sur-Lot, 69 Allée du Bugatel" (postcode city, HN street)
+ *   - B: "Sainte-Livrade-sur-Lot, 47110, 619 Impasse de la Rose" (city, postcode, HN street)
+ *   - C: "Sainte-Livrade-sur-Lot 59 bis Rue des Ecuries 47110" (city HN street postcode — NO commas)
+ *   - D: "47110, 6 rue de la république, Sainte-Livrade-sur-Lot" (postcode, HN street, city)
+ *
+ *   Sub-modes ride alongside order: `bis`/`ter`/`quater` ordinal suffixes in house_number, and
+ *   ALL-CAPS locality. `--golden` emits a held-out reversed-order eval slice with a different
+ *   seed.
+ *
+ *   The inline synthesis (the OA-CSV reader, the ordinal/all-caps tables, the canonical + reversed
+ *   renderers) is ported faithfully from scripts/build-fr-order-shard.mjs. This is a
+ *   `generate`-mode recipe that still reads REAL tuples off disk — `--count` bounds the OUTPUT, not
+ *   the input. The passed `random` (the framework LCG) is consumed in the exact call order the
+ *   legacy script used.
+ *
+ *   NOT ported (diagnostic-only, no effect on emitted bytes): the post-run `runSpanCheck` self-check
+ *   (it reads the finished file back with a separate PRNG and prints to stderr; the recipe's output
+ *   stream is still open during `run`), and the dead `renderReversed` helper (the legacy `main`
+ *   inlined the variant logic and never called it).
+ */
+
+import { spawnSync } from "node:child_process"
+
+import type { ComponentTag } from "@mailwoman/core/types"
+
+import { stableSourceID } from "../adapter.ts"
+import { alignRow } from "../align.ts"
+import type { CanonicalRow } from "../types.ts"
+import { makeMulberry32, type ShardRecipe } from "./scaffold.ts"
+
+const SOURCE = { zip: "/tmp/oa-cache/fr__countrywide.zip", csv: "fr/countrywide.csv" }
+
+// Ordinal suffixes used in French house numbers (BAN corpus), to cover the "8 bis" sub-mode.
+const ORDINAL_SUFFIXES: readonly string[] = ["bis", "ter", "quater"]
+// Probability that a row gets an ordinal suffix injected (matches the golden's ~10-15% rate).
+const ORDINAL_PROB = 0.12
+// Probability that a locality renders ALL-CAPS (another sub-mode: "SAINTE-LIVRADE-SUR-LOT").
+const ALLCAPS_PROB = 0.1
+
+/** A real FR tuple read out of the cached OA zip. */
+interface FrTuple {
+	house_number: string
+	street: string
+	locality: string
+	postcode: string
+}
+
+/** Minimal RFC-4180-ish splitter (handles quoted fields with doubled-quote escaping). */
+function splitCSV(line: string): string[] {
+	const out: string[] = []
+	let cur = ""
+	let inQ = false
+
+	for (let i = 0; i < line.length; i++) {
+		const c = line[i]
+
+		if (inQ) {
+			if (c === '"') {
+				if (line[i + 1] === '"') {
+					cur += '"'
+					i++
+				} else {
+					inQ = false
+				}
+			} else {
+				cur += c
+			}
+		} else if (c === '"') {
+			inQ = true
+		} else if (c === ",") {
+			out.push(cur)
+			cur = ""
+		} else {
+			cur += c
+		}
+	}
+	out.push(cur)
+
+	return out
+}
+
+/**
+ * Stream FR tuples out of the cached OA zip. The countrywide extract is GB-scale; cap with `head` to stay under V8's
+ * string limit. Only keeps rows with a house_number (the shard's core signal) and a postcode (required for
+ * reversed-order rendering to be meaningful).
+ */
+function readTuples(limit: number): FrTuple[] {
+	const maxLines = Math.max(limit * 8, 40000) + 1
+	const r = spawnSync("bash", ["-c", `unzip -p "${SOURCE.zip}" "${SOURCE.csv}" | head -n ${maxLines}`], {
+		maxBuffer: 1024 * 1024 * 1024,
+		encoding: "buffer",
+	})
+
+	if (r.status !== 0) {
+		console.error(`  WARN: unzip failed for ${SOURCE.zip} (status ${r.status})`)
+
+		return []
+	}
+	const lines = r.stdout.toString("utf8").split(/\r?\n/)
+
+	if (lines.length < 2) return []
+	const header = splitCSV(lines[0]!).map((h) => h.trim().toLowerCase())
+	const idx = (name: string): number => header.indexOf(name)
+	const iNum = idx("number"),
+		iStreet = idx("street"),
+		iCity = idx("city"),
+		iPost = idx("postcode")
+	const get = (cells: string[], i: number): string => (i >= 0 && i < cells.length ? (cells[i] ?? "").trim() : "")
+	const tuples: FrTuple[] = []
+	const seen = new Set<string>()
+
+	for (let li = 1; li < lines.length && tuples.length < limit; li++) {
+		if (!lines[li]) continue
+		const cells = splitCSV(lines[li]!)
+		const street = get(cells, iStreet)
+		const locality = get(cells, iCity)
+		const house_number = get(cells, iNum)
+		const postcode = get(cells, iPost)
+
+		// Require all four fields: HN is the signal; postcode drives reversed-order variants.
+		if (!street || !locality || !house_number || !postcode) continue
+		const key = `${house_number}|${street}|${locality}|${postcode}`.toLowerCase()
+
+		if (seen.has(key)) continue
+		seen.add(key)
+		tuples.push({ house_number, street, locality, postcode })
+	}
+
+	return tuples
+}
+
+/**
+ * Optionally augment a house_number with a French ordinal suffix ("59 bis", "4 ter"). Appended with a space so it forms
+ * one multi-token house_number string that alignRow can still locate verbatim.
+ */
+function maybeAddOrdinal(random: () => number, house_number: string): string {
+	if (random() >= ORDINAL_PROB) return house_number
+	const suffix = ORDINAL_SUFFIXES[Math.floor(random() * ORDINAL_SUFFIXES.length)]!
+
+	// Vary suffix case: "bis" (lower) vs "BIS" (upper) — a real-world split in the golden.
+	return `${house_number} ${random() < 0.5 ? suffix : suffix.toUpperCase()}`
+}
+
+/** Render a tuple in CANONICAL French order: "9 Rue de la Promenade, 01200 Villes". */
+function renderCanonical(
+	hn: string,
+	street: string,
+	postcode: string,
+	locality: string
+): { raw: string; components: Partial<Record<ComponentTag, string>> } {
+	const raw = `${hn} ${street}, ${postcode} ${locality}`
+
+	return { raw, components: { house_number: hn, street, postcode, locality } }
+}
+
+export const frOrderRecipe: ShardRecipe = {
+	name: "fr-order",
+	description: "French reversed-order rows (#560): real OA FR tuples rendered canonical + 4 postcode-first variants",
+	mode: "generate",
+	options: [
+		{ flag: "--reversed-fraction <p>", description: "Fraction rendered reversed-order. Default 0.5" },
+		{ flag: "--golden", description: "Emit the held-out reversed-order eval slice" },
+	],
+	async run(opts, write) {
+		if (opts.count == null) throw new Error("fr-order recipe requires --count <N>")
+		const count = opts.count
+		// Legacy build-fr-order-shard.mjs seeded mulberry32 with the raw seed: `const random = mulberry32(opts.seed)`.
+		// (The omitted diagnostic runSpanCheck used a separate mulberry32(opts.seed + 1) — not part of generation.)
+		const random = makeMulberry32(opts.seed)
+		const source = opts.sourceName ?? "synth-fr-order"
+		const reversedFraction = opts.reversedFraction ?? 0.5
+
+		// Over-read from the CSV so the dedup + filter pass can fill `count` rows.
+		const poolLimit = Math.max(count * 8, 40000)
+		const pool = readTuples(poolLimit)
+		console.error(`  ${SOURCE.csv}: ${pool.length} unique tuples (capped read)`)
+
+		if (pool.length === 0) {
+			throw new Error("No FR tuples found — is /tmp/oa-cache/fr__countrywide.zip present?")
+		}
+
+		let emitted = 0
+		let skipped = 0
+		let guard = 0
+		const N = pool.length
+
+		while (emitted < count && guard++ < count * 10) {
+			const base = pool[Math.floor(random() * N)]!
+			const { street, postcode } = base
+			const locality = random() < ALLCAPS_PROB ? base.locality.toUpperCase() : base.locality
+			const house_number = maybeAddOrdinal(random, base.house_number)
+
+			// Pick canonical vs reversed by --reversed-fraction.
+			const isReversed = random() < reversedFraction
+
+			let rendered: { raw: string; components: Partial<Record<ComponentTag, string>> }
+
+			if (isReversed) {
+				const variantRoll = random()
+				let raw: string
+
+				if (variantRoll < 0.25) {
+					// Variant A: postcode+city as a unit, then HN+street
+					raw = `${postcode} ${locality}, ${house_number} ${street}`
+				} else if (variantRoll < 0.5) {
+					// Variant B: city, then postcode, then HN+street (comma-separated, postcode isolated)
+					raw = `${locality}, ${postcode}, ${house_number} ${street}`
+				} else if (variantRoll < 0.75) {
+					// Variant C: no commas — locality HN street postcode (the "run-together" format)
+					raw = `${locality} ${house_number} ${street} ${postcode}`
+				} else {
+					// Variant D: postcode, HN+street, city (reversed top-to-bottom)
+					raw = `${postcode}, ${house_number} ${street}, ${locality}`
+				}
+				rendered = { raw, components: { house_number, street, postcode, locality } }
+			} else {
+				rendered = renderCanonical(house_number, street, postcode, locality)
+			}
+
+			const { raw, components } = rendered
+
+			// Safety check: every component must appear verbatim in raw (alignment precondition).
+			const componentValues = Object.values(components).filter(Boolean) as string[]
+
+			if (!componentValues.every((v) => raw.includes(v))) {
+				skipped++
+				continue
+			}
+
+			// --golden: emit per-locale-f1 eval rows ({raw, components, country:"FR"}).
+			if (opts.golden) {
+				write(JSON.stringify({ raw, components, country: "FR" }) + "\n")
+				emitted++
+				continue
+			}
+
+			const sourceID = stableSourceID(source, {
+				street: components.street,
+				house_number: components.house_number,
+				locality: components.locality,
+				postcode: components.postcode,
+			})
+			const canonical: CanonicalRow = {
+				raw,
+				components,
+				country: "FR",
+				locale: "fr-FR",
+				source,
+				source_id: sourceID,
+				corpus_version: "0.5.0",
+				license: "OpenAddresses FR countrywide tuples, rendered canonical + reversed-order — see ingest SOURCE",
+			}
+			const aligned = alignRow(canonical)
+
+			if (aligned.kind !== "labeled" || !aligned.row) {
+				skipped++
+				continue
+			}
+			write(
+				JSON.stringify({
+					...aligned.row,
+					synth_method: "fr-order",
+					synth_order: isReversed ? "reversed" : "canonical",
+					synth_base_id: null,
+				}) + "\n"
+			)
+			emitted++
+		}
+
+		return { emitted, skipped }
+	},
+}

package/src/shard-recipes/german.ts

@@ -0,0 +1,206 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `german` shard recipe — German coverage rows from REAL OpenAddresses tuples (Berlin + Saxony,
+ *   cached zips). Each sampled tuple is rendered via {@link synthesizeGermanRow} in BOTH orders —
+ *   `--intl-fraction` (default 0.4) in international order (house-first / postcode-after-city), the
+ *   rest in idiomatic German order — then aligned to BIO. Generate-mode: it builds a tuple pool
+ *   from the cached zips, then draws `--count` rows from it with the passed `random` (so the emit
+ *   stream matches the legacy reservoir-sample loop). Ported from scripts/build-german-shard.mjs.
+ *
+ *   ORDER ROBUSTNESS (2026-06-06): mixing the two renderings stops a native-only shard from teaching
+ *   German order so well it reads the US/feed-order eval as a "collapse". See
+ *   docs/articles/evals/resolver-geo/2026-06-06-anchor-pilot.md (the order-artifact correction).
+ */
+
+import { spawnSync } from "node:child_process"
+
+import { stableSourceID } from "../adapter.ts"
+import { alignRow } from "../align.ts"
+import { synthesizeGermanRow, type LocaleBaseTuple } from "../synthesize-german.ts"
+import { makeMulberry32, type ShardRecipe } from "./scaffold.ts"
+
+/**
+ * A German OA source (cached zip) + the Bundesland the file covers (OA's REGION column is empty for DE).
+ */
+interface GermanSource {
+	zip: string
+	csv: string
+	region: string
+}
+
+// `region` is the Bundesland the source covers. OA's REGION column is empty for DE, but the region is
+// implied by the per-state file — the international order needs it for the "City, Region Postcode" tail
+// (v0.9.3 / #327). berlin.csv → Berlin (a city-state, region==locality); sn/statewide → Sachsen.
+const SOURCES: GermanSource[] = [
+	{ zip: "/tmp/oa-cache/de__berlin.zip", csv: "de/berlin.csv", region: "Berlin" },
+	{ zip: "/tmp/oa-cache/de__sn__statewide.zip", csv: "de/sn/statewide.csv", region: "Sachsen" },
+]
+
+/** Minimal RFC-4180-ish splitter (handles quoted fields). */
+function splitCSV(line: string): string[] {
+	const out: string[] = []
+	let cur = ""
+	let inQ = false
+
+	for (let i = 0; i < line.length; i++) {
+		const c = line[i]!
+
+		if (inQ) {
+			if (c === '"') {
+				if (line[i + 1] === '"') {
+					cur += '"'
+					i++
+				} else {
+					inQ = false
+				}
+			} else {
+				cur += c
+			}
+		} else if (c === '"') {
+			inQ = true
+		} else if (c === ",") {
+			out.push(cur)
+			cur = ""
+		} else {
+			cur += c
+		}
+	}
+	out.push(cur)
+
+	return out
+}
+
+/** Stream real German tuples out of a cached OA zip (buffered `unzip -p`). */
+function readGermanTuples(source: GermanSource): LocaleBaseTuple[] {
+	const r = spawnSync("unzip", ["-p", source.zip, source.csv], { maxBuffer: 1024 * 1024 * 1024, encoding: "buffer" })
+
+	if (r.status !== 0) {
+		console.error(`  WARN: unzip failed for ${source.zip} (status ${r.status})`)
+
+		return []
+	}
+	const lines = r.stdout.toString("utf8").split(/\r?\n/)
+
+	if (lines.length < 2) return []
+	const header = splitCSV(lines[0]!).map((h) => h.trim().toLowerCase())
+	const idx = (name: string): number => header.indexOf(name)
+	const iNum = idx("number"),
+		iStreet = idx("street"),
+		iCity = idx("city"),
+		iRegion = idx("region"),
+		iPost = idx("postcode")
+	const get = (cells: string[], i: number): string => (i >= 0 && i < cells.length ? (cells[i] ?? "").trim() : "")
+	const tuples: LocaleBaseTuple[] = []
+	const seen = new Set<string>()
+
+	for (let li = 1; li < lines.length; li++) {
+		const lineStr = lines[li]
+
+		if (!lineStr) continue
+		const cells = splitCSV(lineStr)
+		const street = get(cells, iStreet)
+		const locality = get(cells, iCity)
+
+		if (!street || !locality) continue
+		const house_number = get(cells, iNum)
+		const postcode = get(cells, iPost)
+		// OA's REGION column is empty for DE — fall back to the source's Bundesland (set per file).
+		const region = get(cells, iRegion) || source.region || ""
+		const key = `${house_number}|${street}|${locality}|${postcode}`.toLowerCase()
+
+		if (seen.has(key)) continue
+		seen.add(key)
+		tuples.push({ house_number, street, locality, region, postcode })
+	}
+
+	return tuples
+}
+
+export const germanRecipe: ShardRecipe = {
+	name: "german",
+	description: "German coverage rows from real OA tuples (Berlin/Saxony), both orders → synthesizeGermanRow",
+	mode: "generate",
+	options: [{ flag: "--intl-fraction <f>", description: "Fraction rendered international order. Default 0.4" }],
+	async run(opts, write) {
+		// Emit PRNG: the legacy build-german-shard.mjs seeded mulberry32(opts.seed).
+		const random = makeMulberry32(opts.seed)
+		const source = opts.sourceName ?? "synth-german"
+		const intlFraction = opts.intlFraction ?? 0.4
+
+		if (!(intlFraction >= 0 && intlFraction <= 1)) {
+			throw new Error(`--intl-fraction must be in [0, 1], got ${intlFraction}`)
+		}
+		const count = opts.count ?? 4000
+
+		// Pool real tuples from every German source, then sample `count` rows from it.
+		const pool: LocaleBaseTuple[] = []
+
+		for (const s of SOURCES) {
+			const t = readGermanTuples(s)
+			console.error(`  ${s.csv}: ${t.length} unique tuples`)
+
+			for (const x of t) {
+				pool.push(x)
+			} // NOT pool.push(...t) — spreading ~840K args overflows the stack
+		}
+
+		if (pool.length === 0) {
+			throw new Error("No German tuples found — are the cached zips present in /tmp/oa-cache?")
+		}
+
+		let emitted = 0
+		let skipped = 0
+		let guard = 0
+		const N = pool.length
+
+		while (emitted < count && guard++ < count * 6) {
+			const base = pool[Math.floor(random() * N)]!
+			// Per-row order: `--intl-fraction` of rows render house-first / postcode-after-city (the US/feed
+			// layout), the rest in idiomatic German order. Same components either way.
+			const order = random() < intlFraction ? "international" : "native"
+			const synth = synthesizeGermanRow(base, { random, order })
+
+			if (!synth) {
+				skipped++
+				continue
+			}
+
+			// --golden: emit per-locale-f1 eval rows ({raw, components}) instead of aligned BIO. `order`
+			// rides along so the eval can stratify native vs international.
+			if (opts.golden) {
+				write(JSON.stringify({ raw: synth.raw, components: synth.components, country: "DE", order }) + "\n")
+				emitted++
+				continue
+			}
+			const sourceID = stableSourceID(source, {
+				street: synth.components.street,
+				house_number: synth.components.house_number,
+				locality: synth.components.locality,
+				postcode: synth.components.postcode,
+			})
+			const canonical = {
+				raw: synth.raw,
+				components: synth.components,
+				country: "DE",
+				locale: synth.locale,
+				source,
+				source_id: sourceID,
+				corpus_version: "0.4.0",
+				license: `OpenAddresses DE (Berlin/Saxony) tuples, rendered ${order}-order — see ingest SOURCES`,
+			}
+			const aligned = alignRow(canonical as Parameters<typeof alignRow>[0])
+
+			if (aligned.kind !== "labeled" || !aligned.row) {
+				skipped++
+				continue
+			}
+			write(JSON.stringify({ ...aligned.row, synth_method: "german", synth_order: order, synth_base_id: null }) + "\n")
+			emitted++
+		}
+
+		return { emitted, skipped }
+	},
+}

package/src/shard-recipes/house-venue.ts

@@ -0,0 +1,78 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `house-venue` shard recipe — synthetic house_number+venue+street co-occurrence rows: tuples →
+ *   {@link synthesizeHouseVenueRow} → aligned LabeledRow. The v0.6.3 corrective companion to the
+ *   no-street shard: every row carries BOTH house_number AND venue, restoring the house_number
+ *   signal that no-street's distributional shift cost the model. Ported from
+ *   scripts/build-house-venue-shard.mjs.
+ */
+
+import { synthesizeHouseVenueRow, type HouseVenueBaseTuple } from "../synthesize-house-venue.ts"
+import { alignAndWrite, makeLcg, readTuples, shardSourceID, type ShardRecipe } from "./scaffold.ts"
+
+const LICENSE = "Synthetic — derived from CC-BY / public-domain input tuples"
+
+export const houseVenueRecipe: ShardRecipe = {
+	name: "house-venue",
+	description: "House_number+venue co-occurrence rows: tuples → synthesizeHouseVenueRow → aligned LabeledRow",
+	mode: "tuples",
+	async run(opts, write) {
+		if (!opts.input) throw new Error("house-venue recipe requires --input <tuples.jsonl>")
+		// Legacy build-house-venue-shard.mjs seeded the LCG via makeRandom(opts.seed) (s = seed).
+		const random = makeLcg(opts.seed)
+		const source = opts.sourceName ?? "synth-house-venue"
+		let read = 0
+		let emitted = 0
+		let skipped = 0
+
+		for await (const tuple of readTuples(opts.input)) {
+			read++
+
+			if (!tuple.locality || !tuple.region || !tuple.postcode || !tuple.country) {
+				skipped++
+				continue
+			}
+
+			for (let v = 0; v < opts.variants; v++) {
+				const synth = synthesizeHouseVenueRow(tuple as HouseVenueBaseTuple, { random })
+
+				if (!synth) {
+					skipped++
+					continue
+				}
+				const ok = alignAndWrite(
+					write,
+					{
+						raw: synth.raw,
+						components: synth.components,
+						country: tuple.country,
+						locale: synth.locale,
+						source,
+						source_id: shardSourceID(source, {
+							locality: tuple.locality,
+							region: tuple.region,
+							postcode: tuple.postcode,
+							country: tuple.country,
+							template: synth.template,
+							v: String(v),
+						}),
+						corpus_version: "0.4.0",
+						license: LICENSE,
+					},
+					synth.template
+				)
+
+				if (ok) {
+					emitted++
+				} else {
+					skipped++
+				}
+			}
+		}
+
+		return { read, emitted, skipped }
+	},
+}

package/src/shard-recipes/index.ts

@@ -0,0 +1,76 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The synthetic-corpus SHARD RECIPE registry. Each recipe ({@link ShardRecipe}) is what one legacy
+ *   `build-*-shard.mjs` script used to be; the `mailwoman corpus shard <recipe>` command dispatches
+ *   to them. A new shard is a new entry here, not a new script.
+ */
+
+import { anchorAbsorptionRecipe } from "./anchor-absorption.ts"
+import { boundaryStressRecipe } from "./boundary-stress.ts"
+import { countryBalancedRecipe } from "./country-balanced.ts"
+import { czPcFirstPrepositionRecipe } from "./cz-pcfirst-preposition.ts"
+import { frAdminSplitRecipe } from "./fr-admin-split.ts"
+import { frBareStreetRecipe } from "./fr-bare-street.ts"
+import { frFragmentRecipe } from "./fr-fragment.ts"
+import { frOrderRecipe } from "./fr-order.ts"
+import { germanRecipe } from "./german.ts"
+import { houseVenueRecipe } from "./house-venue.ts"
+import { intersectionRecipe } from "./intersection.ts"
+import { localeRecipe } from "./locale.ts"
+import { nlPostcodeRecipe } from "./nl-postcode.ts"
+import { noFragmentRecipe } from "./no-fragment.ts"
+import { noStreetLedRecipe } from "./no-street-led.ts"
+import { noStreetRecipe } from "./no-street.ts"
+import { poBoxCedexRecipe } from "./po-box-cedex.ts"
+import { poBoxRecipe } from "./po-box.ts"
+import type { ShardRecipe } from "./scaffold.ts"
+import { siBareVillageRecipe } from "./si-bare-village.ts"
+import { streetAffixRecipe } from "./street-affix.ts"
+import { streetBareRecipe } from "./street-bare.ts"
+import { streetRecipe } from "./street.ts"
+import { unitRecipe } from "./unit.ts"
+
+export * from "./scaffold.ts"
+
+/** Every registered recipe, in display order. */
+const RECIPES: readonly ShardRecipe[] = [
+	streetRecipe,
+	streetBareRecipe,
+	streetAffixRecipe,
+	noStreetRecipe,
+	houseVenueRecipe,
+	poBoxRecipe,
+	poBoxCedexRecipe,
+	unitRecipe,
+	intersectionRecipe,
+	germanRecipe,
+	localeRecipe,
+	frOrderRecipe,
+	frAdminSplitRecipe,
+	frBareStreetRecipe,
+	frFragmentRecipe,
+	czPcFirstPrepositionRecipe,
+	nlPostcodeRecipe,
+	noStreetLedRecipe,
+	noFragmentRecipe,
+	siBareVillageRecipe,
+	countryBalancedRecipe,
+	boundaryStressRecipe,
+	anchorAbsorptionRecipe,
+]
+
+/** Recipe name → recipe. */
+export const SHARD_RECIPES: ReadonlyMap<string, ShardRecipe> = new Map(RECIPES.map((r) => [r.name, r]))
+
+/** Look up a recipe by its `<recipe>` name. */
+export function getShardRecipe(name: string): ShardRecipe | undefined {
+	return SHARD_RECIPES.get(name)
+}
+
+/** All recipes (for `--list` / help). */
+export function listShardRecipes(): readonly ShardRecipe[] {
+	return RECIPES
+}