@mailwoman/corpus 10.0.0 → 10.1.0

package/lib/recipes/intersection.ts

@@ -3,33 +3,31 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `intersection` slice recipe — the REAL-pair intersection training slice (#487). The model scored
- *   0.0 on intersection_a/b because the training mix had ZERO intersection-labeled rows. This is
- *   the missing data. Ported from scripts/build-intersection-slice.mjs.
+ *   `intersection` recipe, the real-pair intersection training source.
  *
- *   STREET PAIRS ARE REAL: the same TIGER 2023 EDGES extraction as the eval builder
- *   (scripts/eval/build-intersection-real.ts) — a node where two road edges (MTFCC S1*) with
+ *   Street pairs are real. The extraction matches the eval builder
+ *   (`scripts/eval/build-intersection-real.ts`). A node where two road edges (mtfcc S1*) with
  *   distinct FULLNAMEs meet is a real crossing. Real pairs avoid teaching fake street-street
  *   co-occurrences.
  *
- *   LEAKAGE POLICY (mirrors the affix slice's VT discipline):
+ *   Leakage policy (mirrors the affix recipe's VT discipline):
  *
- *   - TRAIN counties: Cook IL (grid city) + Morris NJ (suburb).
- *   - GOLDEN (`--golden`) county: Washington VT (rural) ONLY — the corpus defaultHoldout state.
- *   - Every crossing in data/eval/external/intersection-real.jsonl is excluded from BOTH modes, by node
- *       id AND by order-insensitive name pair (the eval shares all three counties).
+ *   - train counties: Cook IL (grid city) + Morris NJ (suburb).
+ *   - golden (`--golden`) county: Washington VT (rural) only, the corpus defaultHoldout state.
+ *   - Every crossing in data/eval/external/intersection-real.jsonl is excluded from both modes, by node
+ *       id and by order-insensitive name pair (the eval shares all three counties).
  *
- *   RENDERING: junction-format variety — padded/TIGHT `&` and `/`, `and`, `at`, `@`, leading-phrase
- *   `corner of` / `intersection of` — crossed with tails (bare / `, ST` / `, ST ZIP` / `, City, ST
- *   [ZIP]`) and case variants. ZIPs are the crossing's own TIGER edge ZIPL (real); the locality
- *   tail comes from the OA Cook-county ZIP→city majority map.
+ *   Junction-format variety includes padded and tight `&` and `/`, `and`, `at`, `@`, and the
+ *   leading phrases `corner of` and `intersection of`, crossed with tails (bare / `, ST` / `, ST ZIP` /
+ *   `, City, ST [ZIP]`) and case variants. ZIPs are the crossing's own tiger edge zipl (real). The
+ *   locality tail comes from the OA Cook-county ZIP→city majority map.
  *
- *   AUDIT: every emitted row is label-checked on the RAW SURFACE via the #519 char-offset span
- *   triple. Any violation FAILS the build (throws). A JSON audit report lands next to the output.
+ *   Audit: every emitted row is label-checked on the RAW surface via the char-offset span triple. Any
+ *   violation fails the build (throws). A JSON audit report lands next to the output.
  *
- *   External inputs (`--edges-dir`, opts.edgesDir; both already on disk — do not re-download):
+ *   External inputs (`--edges-dir` and opts.edgesDir, both already on disk. Do not re-download):
  *
- *   - <edges-dir>/tl_2023_{17031,34027,50023}_edges.shp (unzipped TIGER 2023 EDGES; default
+ *   - <edges-dir>/tl_2023_{17031,34027,50023}_edges.shp (unzipped tiger 2023 edges. default
  *       `$MAILWOMAN_DATA_ROOT/census/tiger2023-edges`, where `mailwoman situs interpolation` puts them)
  *   - `$MAILWOMAN_DATA_ROOT/oa-cache/us__il__cook.zip` (ZIP→city tails)
  */
@@ -39,17 +37,20 @@ import type { ComponentTag } from "@mailwoman/codex/component"
 import { dataRootPath } from "@mailwoman/core/data-root"
 import { pathExists } from "@mailwoman/core/fs/readers"
 import { writeLocalJSONFile } from "@mailwoman/core/fs/writers"
+import { stringifyJSON } from "@mailwoman/core/json"
 import { repoRootPath } from "@mailwoman/core/paths"
+import { sample } from "@mailwoman/core/random"
 import { mulberry32 as makeMulberry32 } from "@mailwoman/core/utils"
 import type { PathBuilderLike } from "path-ts"
 import { JSONSpliterator } from "spliterator"
 
-import { stableSourceID } from "#adapters/utils"
+import { stableSourceID } from "#adapters/source-id"
+import { openDuckDB } from "#parquet/duckdb"
 import { readZippedCSVRecords, type CorpusRecipe } from "#recipes/scaffold"
-import { pick, weightedPick } from "#synthesizers/utils"
+import { defaultRecipeSource } from "#recipes/sources"
+import { weightedPick } from "#synthesizers/utils"
 import type { CanonicalRow, LabeledRow } from "#types"
 import { alignRow } from "#utils"
-import { connectDuckDB } from "#utils/parquet"
 
 interface County {
 	fips: string
@@ -66,15 +67,18 @@ const GOLDEN_COUNTIES: readonly County[] = [{ fips: "50023", state: "VT", regime
 
 const EVAL_GOLD_PATH = repoRootPath("data", "eval", "external", "intersection-real.jsonl")
 /**
- * Where `mailwoman situs interpolation` unpacks the per-county TIGER EDGES shapefiles — a Census download, so it sits
- * beside the other Census vintages under `census/`. `--edges-dir` overrides it.
+ * Where `mailwoman situs interpolation` unpacks the per-county tiger edges shapefiles.
+ *
+ * A Census download, so it sits beside the other Census vintages under `census/`.
+ *
+ * `--edges-dir` overrides it.
  */
 const DEFAULT_EDGES_DIR = dataRootPath("census", "tiger2023-edges")
 
 const OA_COOK = { zip: dataRootPath("oa-cache", "us__il__cook.zip"), csv: "us/il/cook.csv" }
 
 /**
- * One real crossing extracted from a county's TIGER EDGES shapefile.
+ * One real crossing extracted from a county's tiger edges shapefile.
  */
 interface Crossing {
 	a: string
@@ -86,8 +90,10 @@ interface Crossing {
 }
 
 /**
- * Junction forms. Weights favor the common connectors; the tight (unpadded) variants and leading phrases get enough
- * mass to register (each ≥5%) — they're the audited gaps the old synth missed.
+ * Junction forms.
+ *
+ * Weights favor the common connectors.
+ * The tight (unpadded) variants and leading phrases each account for at least 5% of the mass.
  */
 interface Form {
 	id: string
@@ -108,9 +114,15 @@ const FORMS: readonly Form[] = [
 ]
 
 /**
- * Tail forms. ~55% bare (the v0.7.2 lesson: an always-present tail taught the model to read post-intersection text as a
- * locality and fumble bare "X & Y"). City tails require a ZIP→city hit (Cook only); ZIP tails require the edge to carry
- * a ZIPL. Misses downgrade to the region tail.
+ * Tail forms.
+ * About 55% bare.
+ *
+ * An always-present tail teaches the model to read post-intersection text as a locality,
+ * so the bare form keeps a majority.
+ * City tails require a ZIP→city hit (Cook only).
+ *
+ * ZIP tails require the edge to include a zipl.
+ * Misses downgrade to the region tail.
  */
 interface Tail {
 	id: string
@@ -138,14 +150,16 @@ const CASES: readonly Casing[] = [
 ]
 
 /**
- * Words a connector may contribute as O tokens. The audit rejects any O token outside this set — an unlabeled
- * street/locality token would surface here.
+ * Words a connector may contribute as O tokens.
+ *
+ * The audit rejects any O token outside this set.
+ * An unlabeled street/locality token would surface here.
  */
 const CONNECTOR_O_TOKENS = new Set(["and", "at", "of", "corner", "intersection"])
 
 /**
- * Street names that would make the connector ambiguous or break verbatim alignment: embedded connector punctuation, or
- * a standalone "and"/"at" word.
+ * Street names that would make the connector ambiguous or break verbatim alignment:
+ * embedded connector punctuation, or a standalone "and"/"at" word.
  */
 const BAD_NAME = /[,&@/]|\b(and|at)\b/i
 
@@ -160,7 +174,8 @@ const CONNECTOR_PUNCT_RE = /^[\s,&@/]*$/
 const pairKey = (a: string, b: string): string => [a.toLowerCase(), b.toLowerCase()].toSorted().join("\u001F")
 
 /**
- * One row of the intersection eval gold — the shape this recipe reads to exclude eval crossings.
+ * One row of the intersection eval gold.
+ * The shape this recipe reads to exclude eval crossings.
  */
 interface EvalGoldRow {
 	node: number | string
@@ -189,9 +204,11 @@ async function readEvalExclusions(): Promise<{ nodes: Set<number>; pairs: Set<st
 }
 
 /**
- * Extract real crossings from one county's TIGER EDGES shapefile. Same query shape as the eval builder (2 incident
- * distinct S1* FULLNAMEs at a node, both names >=6 chars), plus the edge ZIPL so tails can carry the crossing's own
- * ZIP. Hash-ordered for seed-stable determinism.
+ * Extract real crossings from one county's tiger edges shapefile.
+ *
+ * Same query shape as the eval builder (2 incident distinct S1* FULLNAMEs at a node, both names >=6 chars),
+ * plus the edge zipl so tails can include the crossing's own ZIP.
+ * Hash-ordered for seed-stable determinism.
  */
 async function extractCrossings(
 	db: DuckDBConnection,
@@ -245,7 +262,6 @@ async function extractCrossings(
 async function buildZipCityMap(): Promise<Map<string, string>> {
 	const counts = new Map<string, Map<string, number>>()
 
-	// zip → Map(city → n)
 	for await (const row of readZippedCSVRecords(OA_COOK.zip, OA_COOK.csv)) {
 		const city = row.city ?? ""
 		const zip = row.postcode ?? ""
@@ -279,8 +295,10 @@ async function buildZipCityMap(): Promise<Map<string, string>> {
 }
 
 /**
- * Render one crossing → { raw, components, formID, tailID, caseID }. Components are inserted in claim order (streets
- * first) so alignment can't grab a region/postcode lookalike inside a street.
+ * Render one crossing → { raw, components, formID, tailID, caseID }.
+ *
+ * Components are inserted in claim order (streets first) so alignment can't grab
+ * a region/postcode lookalike inside a street.
  */
 function renderRow(
 	random: () => number,
@@ -326,15 +344,18 @@ function renderRow(
 	const casing = weightedPick(CASES, random, (c) => c.w)
 	raw = casing.apply(raw)
 
-	// Components keep their original case; alignRow matches case-insensitively and labels the
-	// tokens of the (cased) raw — the parquet row carries tokens+labels only.
+	// Components keep their original case. alignRow matches case-insensitively
+	// and labels the tokens of the (cased) raw.
+	// The parquet row contains tokens+labels only.
 	return { raw, components, formID: form.id, tailID: tail.id, caseID: casing.id }
 }
 
 /**
- * Label-correctness audit for one aligned row, on the RAW SURFACE via the #519 span triple. Returns a list of
- * violations (empty = clean). Re-derives the span checks independent of `alignRow`'s own assertion, so a builder bug
- * can't vouch for itself.
+ * Label-correctness audit for one aligned row, on the RAW surface via the char-offset span triple.
+ *
+ * @returns A list of violations (empty = clean).
+ * Re-derives the span checks independent of `alignRow`'s own assertion,
+ * so a builder bug can't vouch for itself.
  */
 function auditRow(row: LabeledRow, components: Partial<Record<ComponentTag, string>>): string[] {
 	const errors: string[] = []
@@ -374,7 +395,6 @@ function auditRow(row: LabeledRow, components: Partial<Record<ComponentTag, stri
 		errors.push(`span count ${span_tags.length} != components ${compCount}`)
 	}
 
-	// Raw-surface reconstruction: each component's single span slices raw to the component verbatim.
 	for (const [tag, value] of Object.entries(components)) {
 		if (value == null) continue
 		const indices = span_tags.map((t, i) => (t === tag ? i : -1)).filter((i) => i >= 0)
@@ -429,8 +449,10 @@ function auditRow(row: LabeledRow, components: Partial<Record<ComponentTag, stri
 }
 
 /**
- * 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.
+ * Recipe registered with the corpus builder.
+ *
+ * See the file header for the parse behavior it exercises.
+ * See `description` below for the generated surface form.
  */
 export const intersectionRecipe: CorpusRecipe = {
 	name: "intersection",
@@ -443,17 +465,17 @@ export const intersectionRecipe: CorpusRecipe = {
 		},
 	],
 	async run(opts, write) {
-		// Legacy build-intersection-slice.mjs seeded `mulberry32(opts.seed)`.
 		const random = makeMulberry32(opts.seed)
 		const count = opts.count ?? 40_000
-		const source = opts.sourceName ?? "synth-intersection"
+		const source = opts.sourceName ?? defaultRecipeSource("synth-intersection")
 		const edgesDir = opts.edgesDir ?? DEFAULT_EDGES_DIR
 		const counties = opts.golden ? GOLDEN_COUNTIES : TRAIN_COUNTIES
 		const exclusions = await readEvalExclusions()
 
 		console.error(`  eval exclusions: ${exclusions.nodes.size} nodes, ${exclusions.pairs.size} pairs`)
 
-		const db = await connectDuckDB()
+		using db = await openDuckDB()
+
 		await db.run("INSTALL spatial; LOAD spatial;")
 
 		// Pool real crossings: eval-excluded, connector-safe names, one crossing per distinct pair.
@@ -518,7 +540,7 @@ export const intersectionRecipe: CorpusRecipe = {
 		const samples: Array<{ form: string; raw: string; tokens: readonly string[]; labels: readonly string[] }> = []
 
 		while (emitted < count && guard++ < count * 10) {
-			const crossing = pick(pool, random)
+			const crossing = sample(pool, random)
 			const { raw, components, formID, tailID, caseID } = renderRow(random, crossing, zipCity)
 
 			if (seenRaw.has(raw)) {
@@ -529,7 +551,7 @@ export const intersectionRecipe: CorpusRecipe = {
 
 			if (opts.golden) {
 				seenRaw.add(raw)
-				write(JSON.stringify({ raw, components, country: "US", form: formID }) + "\n")
+				write(stringifyJSON({ raw, components, country: "US", form: formID }))
 				formCounts[formID] = (formCounts[formID] ?? 0) + 1
 				tailCounts[tailID] = (tailCounts[tailID] ?? 0) + 1
 				caseCounts[caseID] = (caseCounts[caseID] ?? 0) + 1
@@ -552,8 +574,8 @@ export const intersectionRecipe: CorpusRecipe = {
 				license: "TIGER/Line 2023 EDGES (US Census, public domain) real street pairs; OA Cook IL zip-to-city tails",
 			}
 
-			// Verbatim-only alignment: raw is built from the component values, so a fuzzy fallback could
-			// only ever mislabel (e.g. claim a lookalike window for a near-duplicate street).
+			// Verbatim-only alignment: raw is built from the component values, so a fuzzy fallback
+			// could only ever mislabel (e.g. Claim a lookalike window for a near-duplicate street).
 			const aligned = alignRow(canonical, { maxEditDistance: 0 })
 
 			if (aligned.kind !== "labeled" || !aligned.row) {
@@ -571,7 +593,7 @@ export const intersectionRecipe: CorpusRecipe = {
 			}
 
 			seenRaw.add(raw)
-			write(JSON.stringify({ ...aligned.row, synth_method: "intersection", synth_base_id: null }) + "\n")
+			write(stringifyJSON({ ...aligned.row, synth_method: "intersection", synth_base_id: null }))
 			formCounts[formID] = (formCounts[formID] ?? 0) + 1
 			tailCounts[tailID] = (tailCounts[tailID] ?? 0) + 1
 			caseCounts[caseID] = (caseCounts[caseID] ?? 0) + 1
@@ -604,14 +626,14 @@ export const intersectionRecipe: CorpusRecipe = {
 
 		console.error(
 			`Done: emitted ${emitted} rows (skipped ${skipped}) from ${usedCrossings.size}/${pool.length} real crossings. → ${opts.output}\n` +
-				`  forms: ${JSON.stringify(formCounts)}\n` +
-				`  tails: ${JSON.stringify(tailCounts)}\n` +
-				`  cases: ${JSON.stringify(caseCounts)}\n` +
+				`  forms: ${stringifyJSON(formCounts)}\n` +
+				`  tails: ${stringifyJSON(tailCounts)}\n` +
+				`  cases: ${stringifyJSON(caseCounts)}\n` +
 				`  audit: ${auditErrors.length} violation(s)`
 		)
 
 		if (auditErrors.length) {
-			throw new Error(`AUDIT FAILED — first violation: ${JSON.stringify(auditErrors[0])}`)
+			throw new Error(`AUDIT FAILED — first violation: ${stringifyJSON(auditErrors[0])}`)
 		}
 
 		return { emitted, skipped }

package/lib/recipes/po/box/cedex/au-nz.ts

@@ -4,6 +4,7 @@
 
 import { isAuDeliveryService } from "@mailwoman/codex/au"
 import { isNZDeliveryService } from "@mailwoman/codex/nz"
+import { sample } from "@mailwoman/core/random"
 
 import { makeAuNZPoBoxPhrase } from "#recipes/po/box/cedex/phrases"
 import type { AUTuple, NZTuple, Rendered } from "#recipes/po/box/cedex/types"
@@ -14,7 +15,6 @@ import {
 	NZ_LEADERS_RARE,
 	VENUES_EN,
 } from "#recipes/po/box/cedex/vocabulary"
-import { pick } from "#synthesizers/utils"
 
 const AU_UPPER_LOCALITY_CUTOFF = 0.6,
 	AU_STANDARD_CUTOFF = 0.45,
@@ -54,7 +54,7 @@ export function renderAUPoBox(random: () => number, tuple: AUTuple): Rendered {
 		}
 
 	if (draw < AU_BARE_CUTOFF) return { fmt: "au-bare", raw: phrase, components: { po_box: phrase } }
-	const venue = pick(VENUES_EN, random)
+	const venue = sample(VENUES_EN, random)
 
 	return {
 		fmt: "au-venue",
@@ -76,7 +76,7 @@ export function renderNZPoBox(random: () => number, tuple: NZTuple): Rendered {
 		return { fmt: "nz-no-postcode", raw: `${phrase}, ${locality}`, components: { po_box: phrase, locality } }
 
 	if (draw < NZ_BARE_CUTOFF) return { fmt: "nz-bare", raw: phrase, components: { po_box: phrase } }
-	const venue = pick(VENUES_EN, random)
+	const venue = sample(VENUES_EN, random)
 
 	return { fmt: "nz-venue", raw: `${venue}, ${phrase}, ${locality} ${postcode}`, components: { venue, ...base } }
 }

package/lib/recipes/po/box/cedex/ca.ts

@@ -2,6 +2,8 @@
  * @copyright Sister Software
  */
 
+import { sample } from "@mailwoman/core/random"
+
 import { makeCaPostcode, makePoBoxPhrase } from "#recipes/po/box/cedex/phrases"
 import type { Rendered } from "#recipes/po/box/cedex/types"
 import {
@@ -11,7 +13,6 @@ import {
 	QC_FSA_LETTERS,
 	VENUES_FR,
 } from "#recipes/po/box/cedex/vocabulary"
-import { pick } from "#synthesizers/utils"
 
 const CA_FR_GOLDEN_ORDER_CUTOFF = 0.4,
 	CA_FR_NATIVE_CUTOFF = 0.7,
@@ -33,7 +34,7 @@ export function renderCaFr(random: () => number, locality: string): Rendered {
 		return { fmt: "ca-fr-native", raw: `${phrase}, ${locality} QC ${postcode}`, components }
 
 	if (draw < CA_FR_BARE_CUTOFF) return { fmt: "ca-fr-bare", raw: phrase, components: { po_box: phrase } }
-	const venue = pick(VENUES_FR, random)
+	const venue = sample(VENUES_FR, random)
 
 	return {
 		fmt: "ca-fr-venue",

package/lib/recipes/po/box/cedex/fr.ts

@@ -2,10 +2,11 @@
  * @copyright Sister Software
  */
 
+import { sample } from "@mailwoman/core/random"
+
 import { makeCedex, makePoBoxPhrase } from "#recipes/po/box/cedex/phrases"
 import type { FRTuple, Rendered } from "#recipes/po/box/cedex/types"
 import { FR_LEADERS, VENUES_FR } from "#recipes/po/box/cedex/vocabulary"
-import { pick } from "#synthesizers/utils"
 
 const BP_TAIL_CUTOFF = 0.45,
 	BP_BARE_CUTOFF = 0.6,
@@ -42,7 +43,7 @@ export function renderBpFr(random: () => number, tuple: FRTuple): Rendered {
 		}
 	}
 
-	const venue = pick(VENUES_FR, random)
+	const venue = sample(VENUES_FR, random)
 
 	return {
 		fmt: "bp-venue",
@@ -70,7 +71,7 @@ export function renderCedexFr(random: () => number, tuple: FRTuple): Rendered {
 	if (draw < CEDEX_GOLDEN_ORDER_CUTOFF)
 		return { fmt: "cedex-golden-order", raw: `${postcode} ${cedex} ${location}`, components: line }
 
-	const venue = pick(VENUES_FR, random)
+	const venue = sample(VENUES_FR, random)
 
 	return { fmt: "cedex-venue", raw: `${venue}, ${postcode} ${location} ${cedex}`, components: { venue, ...line } }
 }

package/lib/recipes/po/box/cedex/phrases.ts

@@ -6,10 +6,11 @@ import { normalizeCaPostalCode } from "@mailwoman/codex/ca"
 import { isCedex } from "@mailwoman/codex/fr"
 import { isNZDeliveryService } from "@mailwoman/codex/nz"
 import { isUSPoBoxDesignator, matchPOBox } from "@mailwoman/codex/us"
+import { sample } from "@mailwoman/core/random"
 
 import { CA_INTERIOR_LETTERS } from "#recipes/po/box/cedex/vocabulary"
 import { maybeNoisifyBoxNumber } from "#synthesizers/po-box"
-import { pick, tieredNumber } from "#synthesizers/utils"
+import { tieredNumber } from "#synthesizers/utils"
 
 const BOX_TWO_DIGIT_CUTOFF = 0.3
 const BOX_THREE_DIGIT_CUTOFF = 0.7
@@ -40,10 +41,10 @@ export function makePoBoxPhrase(
 	leaders: ReadonlyArray<string>,
 	rareLeaders?: ReadonlyArray<string>
 ): string {
-	let leader = pick(leaders, random)
+	let leader = sample(leaders, random)
 
 	if (rareLeaders && random() < RARE_LEADER_SHARE) {
-		leader = pick(rareLeaders, random)
+		leader = sample(rareLeaders, random)
 	}
 
 	const number = maybeNoisifyBoxNumber(pickBoxNumber(random), random)
@@ -76,10 +77,10 @@ export function makeAuNZPoBoxPhrase(
 	rareLeaders: ReadonlyArray<string>,
 	validate: (input: unknown) => boolean
 ): string {
-	let leader = pick(leaders, random)
+	let leader = sample(leaders, random)
 
 	if (random() < RARE_LEADER_SHARE) {
-		leader = pick(rareLeaders, random)
+		leader = sample(rareLeaders, random)
 	}
 
 	let number = maybeNoisifyBoxNumber(pickBoxNumber(random), random)
@@ -100,7 +101,7 @@ export function makeAuNZPoBoxPhrase(
 export function makeCaPostcode(random: () => number, fsaLetters: string[]): string {
 	const letter = () => CA_INTERIOR_LETTERS[Math.floor(random() * CA_INTERIOR_LETTERS.length)]!
 	const digit = () => String(Math.floor(random() * 10))
-	const postcode = `${pick(fsaLetters, random)}${digit()}${letter()} ${digit()}${letter()}${digit()}`
+	const postcode = `${sample(fsaLetters, random)}${digit()}${letter()} ${digit()}${letter()}${digit()}`
 
 	if (!normalizeCaPostalCode(postcode)) throw new Error(`generated an invalid CA postcode: ${postcode}`)
 

package/lib/recipes/po/box/cedex/recipe.ts

@@ -3,6 +3,8 @@
  */
 
 import { dataRootPath } from "@mailwoman/core/data-root"
+import { stringifyJSON } from "@mailwoman/core/json"
+import { sample } from "@mailwoman/core/random"
 import { mulberry32 as makeMulberry32 } from "@mailwoman/core/utils"
 
 import { renderAUPoBox, renderNZPoBox } from "#recipes/po/box/cedex/au-nz"
@@ -24,9 +26,10 @@ import {
 import type { AUTuple, NZTuple, Rendered, USTuple } from "#recipes/po/box/cedex/types"
 import { renderPmbUs, renderPoBoxUs } from "#recipes/po/box/cedex/us"
 import { CLASS_MIX } from "#recipes/po/box/cedex/vocabulary"
-import { sliceSourceID, type CanonicalSliceRow, type CorpusRecipe } from "#recipes/scaffold"
+import { recipeSourceID, type CanonicalRecipeRow, type CorpusRecipe } from "#recipes/scaffold"
+import { defaultRecipeSource } from "#recipes/sources"
 import { synthesizeMilitaryPoBoxRow } from "#synthesizers/po-box"
-import { pick } from "#synthesizers/utils"
+import { SurfaceOrigin } from "#types"
 import { alignRow } from "#utils"
 
 const COMPONENT_ORDER = ["house_number", "street", "po_box", "venue", "locality", "postcode", "region", "cedex"]
@@ -47,7 +50,7 @@ const pickClass = (draw: number): string => {
 }
 
 /**
- * Generate PO-box and CEDEX rows from US, French, Canadian, Australian, and New Zealand source pools.
+ * Generate PO-box and cedex rows from source pools in the US, France, Canada, Australia and New Zealand.
  */
 export const poBoxCedexRecipe: CorpusRecipe = {
 	name: "po-box-cedex",
@@ -57,7 +60,7 @@ export const poBoxCedexRecipe: CorpusRecipe = {
 	async run(opts, write) {
 		const random = makeMulberry32(opts.seed)
 		const count = opts.count ?? 50_000
-		const source = opts.sourceName ?? "synth-po-box-cedex"
+		const source = opts.sourceName ?? defaultRecipeSource("synth-po-box-cedex")
 		const usPool: USTuple[] = []
 
 		for (const sourceEntry of opts.golden ? [US_EVAL_SOURCE] : US_TRAIN_SOURCES) {
@@ -107,34 +110,34 @@ export const poBoxCedexRecipe: CorpusRecipe = {
 			let locale: string
 
 			if (kind === "po-box-us") {
-				rendered = renderPoBoxUs(random, pick(usPool, random))
+				rendered = renderPoBoxUs(random, sample(usPool, random))
 				country = "US"
 				locale = "en-US"
 			} else if (kind === "pmb-us") {
-				const tuple = pick(usPool, random)
+				const tuple = sample(usPool, random)
 
 				if (!tuple.postcode || !tuple.street || !tuple.house_number) continue
 				rendered = renderPmbUs(random, tuple)
 				country = "US"
 				locale = "en-US"
 			} else if (kind === "bp-fr") {
-				rendered = renderBpFr(random, pick(frPool, random))
+				rendered = renderBpFr(random, sample(frPool, random))
 				country = "FR"
 				locale = "fr-FR"
 			} else if (kind === "cedex-fr") {
-				rendered = renderCedexFr(random, pick(frPool, random))
+				rendered = renderCedexFr(random, sample(frPool, random))
 				country = "FR"
 				locale = "fr-FR"
 			} else if (kind === "cp-ca-fr") {
-				rendered = renderCaFr(random, pick(qcPool, random))
+				rendered = renderCaFr(random, sample(qcPool, random))
 				country = "CA"
 				locale = "fr-CA"
 			} else if (kind === "po-box-au") {
-				rendered = renderAUPoBox(random, pick(auPool, random))
+				rendered = renderAUPoBox(random, sample(auPool, random))
 				country = "AU"
 				locale = "en-AU"
 			} else if (kind === "po-box-nz") {
-				rendered = renderNZPoBox(random, pick(nzPool, random))
+				rendered = renderNZPoBox(random, sample(nzPool, random))
 				country = "NZ"
 				locale = "en-NZ"
 			} else if (kind === "po-box-us-military") {
@@ -144,7 +147,7 @@ export const poBoxCedexRecipe: CorpusRecipe = {
 				country = "US"
 				locale = "en-US"
 			} else {
-				rendered = renderCaEn(random, pick(onPool, random))
+				rendered = renderCaEn(random, sample(onPool, random))
 				country = "CA"
 				locale = "en-CA"
 			}
@@ -158,20 +161,20 @@ export const poBoxCedexRecipe: CorpusRecipe = {
 			}
 
 			if (opts.golden) {
-				write(JSON.stringify({ raw, components: orderComponents(components), country }) + "\n")
+				write(stringifyJSON({ raw, components: orderComponents(components), country }))
 
 				emitted++
 
 				continue
 			}
 
-			const canonical: CanonicalSliceRow = {
+			const canonical: CanonicalRecipeRow = {
 				raw,
 				components: orderComponents(components),
 				country,
 				locale,
 				source,
-				source_id: sliceSourceID(source, components),
+				source_id: recipeSourceID(source, components),
 				corpus_version: "0.4.0",
 				license:
 					country === "CA"
@@ -193,7 +196,16 @@ export const poBoxCedexRecipe: CorpusRecipe = {
 				continue
 			}
 
-			write(JSON.stringify({ ...aligned.row, synth_method: kind, synth_base_id: null }) + "\n")
+			// The CEDEX number is drawn rather than read from La Poste's own file.
+			write(
+				stringifyJSON({
+					...aligned.row,
+					recipe: kind,
+					base_source_id: null,
+					register: null,
+					surface: SurfaceOrigin.Invented,
+				})
+			)
 
 			emitted++
 		}

package/lib/recipes/po/box/cedex/sources.ts

@@ -171,9 +171,9 @@ export async function readPostalTuples(
 	const validPostcode = opts.withState ? isAuPostcode : isNZPostcode
 
 	for await (const columns of TSVSpliterator.fromAsync(readZipEntry(source.zip, source.txt), { header: false })) {
-		const postcode = (columns[1] ?? "").trim(),
-			locality = (columns[2] ?? "").trim(),
-			region = (columns[4] ?? "").trim()
+		const postcode = columns[1] ?? "",
+			locality = columns[2] ?? "",
+			region = columns[4] ?? ""
 
 		if (!cleanLocality(locality) || !validPostcode(postcode) || (opts.withState && !isAuStateAbbreviation(region)))
 			continue

package/lib/recipes/po/box/cedex/us.ts

@@ -2,10 +2,15 @@
  * @copyright Sister Software
  */
 
+/* oxlint-disable mailwoman/prefer-home -- this module is the US arm of the cedex recipe, identified by its path. Its
+ sibling arms cover the other countries. A layout call would answer the same string for the only country that reaches
+   it. */
+
+import { sample } from "@mailwoman/core/random"
+
 import { makePoBoxPhrase } from "#recipes/po/box/cedex/phrases"
 import type { Rendered, USTuple } from "#recipes/po/box/cedex/types"
 import { US_LEADERS_COMMON, US_LEADERS_RARE, US_PMB_LEADERS, VENUES_EN } from "#recipes/po/box/cedex/vocabulary"
-import { pick } from "#synthesizers/utils"
 
 const US_FULL_CUTOFF = 0.4,
 	US_NO_POSTCODE_CUTOFF = 0.55,
@@ -30,7 +35,7 @@ export function renderPoBoxUs(random: () => number, tuple: USTuple): Rendered {
 	if (draw < US_BARE_CUTOFF) return { fmt: "bare", raw: phrase, components: { po_box: phrase } }
 
 	if (draw < US_VENUE_CUTOFF) {
-		const venue = pick(VENUES_EN, random)
+		const venue = sample(VENUES_EN, random)
 
 		return {
 			fmt: "venue",