@mailwoman/corpus 10.0.0 → 10.2.0

package/lib/recipes/street/affix.ts

@@ -2,36 +2,12 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   `street-affix` slice recipe — the US street-affix coverage slice (the v0-parity `street_prefix` /
- *   `street_suffix` gap — both ~0% F1 in the #15 assessment, collapsed into `street`). Raises
- *   PREVALENCE of affix-split streets with format diversity so the model learns to split "N Main
- *   St" → street_prefix="N" + street="Main" + street_suffix="St", and (negative space) sharpens
- *   `street` itself. Ported from scripts/build-street-affix-slice.mjs.
- *
- *   Reads REAL US OpenAddresses tuples and SPLITS the OA `street` field via the codex:
- *   `matchLeadingDirectional` (USPS Pub-28 C1) for the prefix, `matchTrailingSuffix` (Pub-28 C2
- *   street suffixes) for the suffix. OA streets nearly all carry a suffix; only ~10-20% carry a
- *   directional, so we INJECT a directional prefix onto a fraction of prefix-less streets to give
- *   `street_prefix` real signal. Each row varies surface form per affix — abbreviated ("N", "St")
- *   vs expanded ("North", "Street") — and varies the layout (full address / bare / street-only /
- *   venue-prefixed).
- *
- *   LEAKAGE-SAFE EVAL (`--golden`): held-out eval uses the VERMONT source only (the corpus
- *   defaultHoldout), a different seed, and emits {raw, components} for per-locale-f1. Train uses
- *   every NON-Vermont US source.
- *
- *   Multi-locale BALANCE (`--multilocale-count`, opts.multilocaleCount > 0): appends NO-affix
- *   native-order rows (FR/DE/IT/NL) AFTER the US affix rows, riding the same source weight, purely
- *   to keep the postcode-ORDER distribution multi-locale so a US-heavy affix slice doesn't dilute
- *   FR/DE postcode (the v0.9.8 blemish).
  */
 
 import type { ComponentTag } from "@mailwoman/codex/component"
 import {
 	DirectionalAbbreviation,
 	lookupDirectional,
-	matchCase,
 	matchLeadingDirectional,
 	matchTrailingSuffix,
 	renderDirectional,
@@ -39,17 +15,19 @@ import {
 	NAME_PRONE_US_SUFFIXES,
 } from "@mailwoman/codex/us"
 import { dataRootPath } from "@mailwoman/core/data-root"
+import { stringifyJSON } from "@mailwoman/core/json"
+import { sample } from "@mailwoman/core/random"
+import { normalizeWhitespace } from "@mailwoman/core/strings/format"
 import { mulberry32 as makeMulberry32 } from "@mailwoman/core/utils"
 import type { PathBuilderLike } from "path-ts"
+import { matchCase } from "spliterator"
 
-import { stableSourceID } from "#adapters/utils"
-import { readCSVRecords, readOATuples, sliceSourceID, type CorpusRecipe } from "#recipes/scaffold"
-import { pick } from "#synthesizers/utils"
+import { stableSourceID } from "#adapters/source-id"
+import { readCSVRecords, readOATuples, recipeSourceID, type CorpusRecipe } from "#recipes/scaffold"
+import { defaultRecipeSource } from "#recipes/sources"
 import type { CanonicalRow } from "#types"
 import { alignRow } from "#utils"
 
-// Same OA cache as the unit slice. Train = every NON-Vermont state; eval = Vermont (the holdout).
-
 interface USSource {
 	zip: PathBuilderLike
 	csv: string
@@ -72,10 +50,6 @@ const EVAL_SOURCE: USSource = {
 	region: "VT",
 }
 
-// Multi-locale BALANCE sources (--multilocale-count > 0). These rows carry NO affix split — they exist
-// only to keep the postcode-ORDER distribution multi-locale. Native-order rendering mirrors
-// build-country-slice-balanced.mjs: FR = number-street, postcode-city; DE/IT/NL = street-number,
-// postcode-city. `order` drives the body.
 interface BalanceSource {
 	zip: PathBuilderLike
 	csv: string
@@ -119,18 +93,10 @@ const MULTILOCALE_EVAL_SOURCES: readonly BalanceSource[] = [
 	{ zip: dataRootPath("oa-cache", "de__berlin.zip"), csv: "de/berlin.csv", iso2: "DE", region: "", order: "eu" },
 ]
 
-/**
- * ["N","E","S","W","NE","NW","SE","SW"].
- */
 const DIRECTIONAL_ABBRS = Object.values(DirectionalAbbreviation)
-/**
- * Fraction of prefix-less streets that get a synthetic directional.
- */
+
 const INJECT_PREFIX_PROB = 0.3
 
-/**
- * A real US skeleton tuple read from a cached OA zip.
- */
 interface USTuple {
 	house_number: string
 	street: string
@@ -140,9 +106,6 @@ interface USTuple {
 	base_source_id: string
 }
 
-/**
- * A non-US BALANCE tuple (carries a postcode + native order).
- */
 interface BalanceTuple {
 	house_number: string
 	street: string
@@ -153,14 +116,8 @@ interface BalanceTuple {
 	order: string
 }
 
-/**
- * Prefix carried through render — the (canonical, abbreviation) pair `renderDirectional` consumes.
- */
 type Prefix = Pick<NonNullable<ReturnType<typeof matchLeadingDirectional>>, "canonical" | "abbreviation">
 
-/**
- * Stream real US tuples (number/street/city/postcode) out of a cached OA zip.
- */
 async function readTuples(source: USSource): Promise<USTuple[]> {
 	return readOATuples(source, {
 		extra: (fields, _row, key) => ({
@@ -181,10 +138,6 @@ const title = (s: string): string =>
 const isSuffixOrDirectional = (word: string): boolean =>
 	matchTrailingSuffix(word) !== null || matchLeadingDirectional(word) !== null
 
-/**
- * Split an OA street into { prefix?, name, suffix } using the codex. Requires a trailing suffix and a non-empty name
- * that isn't itself an affix token. Returns null when the street has no usable suffix.
- */
 function parseStreet(
 	street: string,
 	opts: { allowNameProneTail?: boolean } = {}
@@ -193,7 +146,7 @@ function parseStreet(
 
 	if (words.length < 2) return null
 	let prefix: Prefix | null = null
-	// Leading directional — only if it leaves ≥2 words behind (room for a name + suffix).
+
 	const lead = matchLeadingDirectional(street)
 
 	if (lead && words.length > 2) {
@@ -201,7 +154,6 @@ function parseStreet(
 		words = words.slice(1)
 	}
 
-	// Trailing USPS suffix — only if it leaves ≥1 word for the name.
 	const trail = matchTrailingSuffix(words.join(" "))
 
 	if (!trail || words.length < 2) return null
@@ -219,16 +171,21 @@ function parseStreet(
 	return { prefix, name, suffix }
 }
 
+/**
+ * The two street shapes that the suffix-boundary recipe balances.
+ *
+ * In a `terminal-only` street, a name-prone suffix word precedes the real suffix and belongs to the name.
+ * In a `terminal-contrast` street, the name-prone word is itself the final suffix.
+ */
 export type SuffixBoundaryClass = "terminal-only" | "terminal-contrast"
 
-// A terminal-only surface needs a name word before the penultimate suffix (`Blue Hill Rd`): three words at least.
 const TERMINAL_ONLY_MIN_WORDS = 3
 
 /**
- * Classify a real street surface for #1569. `terminal-only` has an ambiguous suffix-eligible name word immediately
- * before a different terminal type (`Blue Hill Rd`); `terminal-contrast` ends at the ambiguous word itself (`Sutton
- * Hollow`). The contrast check intentionally wins when both final words are name-prone: only the LAST token is the
- * suffix under the canonical rule.
+ * Classifies a street as `terminal-only` or `terminal-contrast`, or returns `null` when it is neither.
+ *
+ * A street whose final word is name-prone is `terminal-contrast` even when the word
+ * before it is also name-prone, because only the final token is the suffix.
  */
 export function classifySuffixBoundaryStreet(street: string): SuffixBoundaryClass | null {
 	const words = street.trim().split(/\s+/)
@@ -247,9 +204,6 @@ export function classifySuffixBoundaryStreet(street: string): SuffixBoundaryClas
 	return penultimate && NAME_PRONE_US_SUFFIXES.has(penultimate.canonical) ? "terminal-only" : null
 }
 
-/**
- * Render the affix-split street in random surface forms (abbrev vs expanded per affix), Title-cased.
- */
 function renderStreet(
 	random: () => number,
 	parsed: { prefix: Prefix | null; name: string; suffix: string }
@@ -258,32 +212,28 @@ function renderStreet(
 	const parts: string[] = []
 	const components: Partial<Record<ComponentTag, string>> = { street: name }
 
-	// Prefix: natural (from parse) or injected onto a prefix-less street to boost street_prefix signal.
 	let prefix = parsed.prefix
 
 	if (!prefix && random() < INJECT_PREFIX_PROB) {
-		const m = lookupDirectional(pick(DIRECTIONAL_ABBRS, random))!
+		const m = lookupDirectional(sample(DIRECTIONAL_ABBRS, random))!
 		prefix = { canonical: m.directional, abbreviation: m.abbreviation }
 	}
 
 	if (prefix) {
-		const rendered = renderDirectional(prefix, random() < 0.5 ? "abbr" : "full", "Aa") // "Aa" → Title-case
+		const rendered = renderDirectional(prefix, random() < 0.5 ? "abbr" : "full", "Aa")
 		components.street_prefix = rendered
 		parts.push(rendered)
 	}
 
 	parts.push(name)
 
-	// Suffix: abbreviated ("St") vs expanded ("Street"), Title-cased to match the name.
 	const full = title(parsed.suffix)
 
-	// canonical is uppercase word → "Street"
 	const abbr = matchCase(
 		US_STREET_SUFFIX_PREFERRED_ABBR[parsed.suffix as keyof typeof US_STREET_SUFFIX_PREFERRED_ABBR],
 		"Aa"
 	)
 
-	// "AVE" → "Ave"
 	const renderedSuffix = random() < 0.5 ? abbr : full
 	components.street_suffix = renderedSuffix
 	parts.push(renderedSuffix)
@@ -291,19 +241,8 @@ function renderStreet(
 	return { street: parts.join(" "), components }
 }
 
-/**
- * Synthetic recipient/venue prefixes — the arena's "JOHN DOE, ACME INC, …" pattern.
- */
 const VENUES = ["John Doe", "Jane Smith", "Acme Inc", "Wayne Enterprises", "Maria Garcia", "Riverside Clinic"]
 
-/**
- * Real-venue pool for the suffix-boundary v2 venue shell (corpus 0.19.0). The 2026-08-10 recipe review found the
- * v0.18.x slice's venue-led rows detectable as templates (six fixed venue strings), and the frozen B1 board's failures
- * concentrate in exactly that shell (rich rows 5/43 vs bare 53/65 at v4.3.3 step-40k). HRSA's health-center site file
- * supplies thousands of REAL US facility names ('Alburg Health Center'-register), US-government public domain, already
- * a corpus source (`usgov-hrsa-fqhc`). Kept verbatim (including the ~11% all-caps names — real register diversity);
- * comma-carrying names are dropped because the venue layout uses commas as its field delimiter.
- */
 const VENUE_POOL_CSV = dataRootPath(
 	"corpus",
 	"sources",
@@ -311,7 +250,6 @@ const VENUE_POOL_CSV = dataRootPath(
 	"Health_Center_Service_Delivery_and_LookAlike_Sites.csv"
 )
 
-// Facility-name length window: shorter reads as an initialism, longer as a sentence.
 const VENUE_NAME_MIN_LENGTH = 3
 const VENUE_NAME_MAX_LENGTH = 60
 
@@ -320,9 +258,7 @@ async function readVenuePool(csvPath: PathBuilderLike): Promise<string[]> {
 	const pool: string[] = []
 
 	for await (const record of readCSVRecords(csvPath)) {
-		// One key, where the source's `Site Name` and `SITE NAME` both used to need naming: the reader snake-cases and
-		// lower-cases a header, so either spelling arrives here as `site_name`.
-		const name = (record.site_name ?? "").trim().replaceAll(/\s+/gu, " ")
+		const name = normalizeWhitespace(record.site_name ?? "")
 
 		if (
 			name.length < VENUE_NAME_MIN_LENGTH ||
@@ -344,19 +280,16 @@ async function readVenuePool(csvPath: PathBuilderLike): Promise<string[]> {
 
 const tail = (loc: string, reg: string, pc: string): string => (pc ? `${loc}, ${reg} ${pc}` : `${loc}, ${reg}`)
 
-/**
- * Layout-shell options for {@link renderRow}. `cutoffs` are the cumulative random() boundaries for [full, bare,
- * street-only] — the remainder is the venue shell. Defaults reproduce the original street-affix distribution
- * (40/25/20/15) with the six template venues.
- */
 interface RenderRowOpts {
 	venues?: readonly string[]
 	cutoffs?: readonly [number, number, number]
 }
 
 /**
- * Embed the rendered street in a RANDOM layout so the model recognizes affixes wherever the street sits: full address,
- * bare house+street, street-only (pure affix parse), or venue-prefixed.
+ * Places a rendered street in a full, bare, street-only, or venue-prefixed address.
+ *
+ * The `cutoffs` option sets the cumulative probabilities of the first three formats.
+ * The remainder produces venue-prefixed rows.
  */
 export function renderRow(
 	random: () => number,
@@ -387,7 +320,7 @@ export function renderRow(
 	if (r < bareCutoff) return { fmt: "bare", raw: road, components: withRoad }
 
 	if (r < streetOnlyCutoff) return { fmt: "street-only", raw: street, components: { ...streetComponents } }
-	const v = pick(venues, random)
+	const v = sample(venues, random)
 
 	return {
 		fmt: "venue",
@@ -396,11 +329,6 @@ export function renderRow(
 	}
 }
 
-/**
- * Capped reader for the multi-locale BALANCE sources. The FR/IT/NL countrywide extracts are GB-scale, so this reads
- * only as far as `limit` distinct tuples — the `break` closes the reader and releases the archive. Only keeps tuples
- * that carry a POSTCODE.
- */
 async function readBalanceTuples(source: BalanceSource, limit: number): Promise<BalanceTuple[]> {
 	return readOATuples(source, {
 		limit,
@@ -414,27 +342,20 @@ async function readBalanceTuples(source: BalanceSource, limit: number): Promise<
 	})
 }
 
-/**
- * Render a non-US BALANCE row in native order — NO affix split, NO country token. `street` is the OA value verbatim.
- * The sole job is to put a postcode in its native position so the slice doesn't pull the model US-ward.
- */
 function renderBalanceRow(t: BalanceTuple): { raw: string; components: Partial<Record<ComponentTag, string>> } {
 	const { house_number: hn, street, locality: loc, postcode: pc, order } = t
-	// region is intentionally omitted — it isn't rendered in `raw`, so labeling it would fail alignment.
+
 	const components: Partial<Record<ComponentTag, string>> = { house_number: hn, street, locality: loc, postcode: pc }
 
-	const raw =
-		order === "fr"
-			? `${hn} ${street}, ${pc} ${loc}` // French: number-street, postcode-city
-			: `${street} ${hn}, ${pc} ${loc}`
+	const raw = order === "fr" ? `${hn} ${street}, ${pc} ${loc}` : `${street} ${hn}, ${pc} ${loc}`
 
-	// DE/IT/NL: street-number, postcode-city
 	return { raw, components }
 }
 
 /**
- * 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.
+ * Generates US rows that split OpenAddresses streets into `street_prefix`, `street` and `street_suffix`.
+ *
+ * The `--multilocale-count` option appends FR, DE, IT and NL rows in native order without affix labels.
  */
 export const streetAffixRecipe: CorpusRecipe = {
 	name: "street-affix",
@@ -447,10 +368,9 @@ export const streetAffixRecipe: CorpusRecipe = {
 		},
 	],
 	async run(opts, write) {
-		// Legacy build-street-affix-slice.mjs seeded `mulberry32(opts.seed)`.
 		const random = makeMulberry32(opts.seed)
 		const count = opts.count ?? 50_000
-		const source = opts.sourceName ?? "synth-affix"
+		const source = opts.sourceName ?? defaultRecipeSource("synth-affix")
 		const multilocaleCount = opts.multilocaleCount ?? 0
 		const sources = opts.golden ? [EVAL_SOURCE] : TRAIN_SOURCES
 
@@ -491,7 +411,6 @@ export const streetAffixRecipe: CorpusRecipe = {
 			const { street, components: streetComponents } = renderStreet(random, parsed)
 			const { fmt, raw, components } = renderRow(random, base, street, streetComponents)
 
-			// Every affix surface form must survive verbatim in raw, else alignment can't label it.
 			const surfaces = [streetComponents.street_prefix, streetComponents.street, streetComponents.street_suffix].filter(
 				(s): s is string => Boolean(s)
 			)
@@ -514,7 +433,7 @@ export const streetAffixRecipe: CorpusRecipe = {
 			}
 
 			if (opts.golden) {
-				write(JSON.stringify({ raw, components, country: "US" }) + "\n")
+				write(stringifyJSON({ raw, components, country: "US" }))
 
 				emitted++
 
@@ -540,21 +459,18 @@ export const streetAffixRecipe: CorpusRecipe = {
 				continue
 			}
 
-			write(JSON.stringify({ ...aligned.row, synth_method: "affix", synth_base_id: null }) + "\n")
+			write(stringifyJSON({ ...aligned.row, synth_method: "affix", synth_base_id: null }))
 
 			emitted++
 		}
 
-		// ── Multi-locale balance rows (--multilocale-count) ─────────────────────────────────────────────
-		// Appended AFTER the US affix rows so the US affix signal is unchanged (same `--count`), and the
-		// non-US rows ride the SAME source weight. Native-order postcodes, no affix labels.
 		let balanceEmitted = 0
 		let balanceSkipped = 0
 		const balanceISO: Record<string, number> = {}
 
 		if (multilocaleCount > 0) {
 			const mlSources = opts.golden ? MULTILOCALE_EVAL_SOURCES : MULTILOCALE_SOURCES
-			const perSource = Math.ceil((multilocaleCount * 3) / mlSources.length) // over-read; balance locales
+			const perSource = Math.ceil((multilocaleCount * 3) / mlSources.length)
 			const mlPool: BalanceTuple[] = []
 
 			for (const s of mlSources) {
@@ -570,12 +486,11 @@ export const streetAffixRecipe: CorpusRecipe = {
 			const M = mlPool.length
 			let mlGuard = 0
 
-			// oxlint-disable-next-line eslint/no-unmodified-loop-condition -- `M > 0` is an invariant guard against an empty pool, not a progress condition
+			// oxlint-disable-next-line eslint/no-unmodified-loop-condition -- `M > 0` is an invariant guard against an empty pool rather than a progress condition
 			while (M > 0 && balanceEmitted < multilocaleCount && mlGuard++ < multilocaleCount * 10) {
 				const t = mlPool[Math.floor(random() * M)]!
 				const { raw, components } = renderBalanceRow(t)
 
-				// Every component surface must survive in raw, else alignment can't label it.
 				if (![components.street, components.locality, components.postcode].every((s) => !!s && raw.includes(s))) {
 					balanceSkipped++
 
@@ -586,7 +501,7 @@ export const streetAffixRecipe: CorpusRecipe = {
 				const locale = `${t.iso2.toLowerCase()}-${t.iso2}`
 
 				if (opts.golden) {
-					write(JSON.stringify({ raw, components, country: t.iso2 }) + "\n")
+					write(stringifyJSON({ raw, components, country: t.iso2 }))
 
 					balanceEmitted++
 
@@ -601,7 +516,7 @@ export const streetAffixRecipe: CorpusRecipe = {
 					source,
 					source_id: stableSourceID(source, components),
 					corpus_version: "0.4.0",
-					license: "OpenAddresses non-US skeletons (native-order postcode balance for the affix slice)",
+					license: "OpenAddresses non-US skeletons (native-order postcode balance for the affix recipe)",
 				}
 
 				const aligned = alignRow(canonical)
@@ -612,7 +527,7 @@ export const streetAffixRecipe: CorpusRecipe = {
 					continue
 				}
 
-				write(JSON.stringify({ ...aligned.row, synth_method: "affix-balance", synth_base_id: null }) + "\n")
+				write(stringifyJSON({ ...aligned.row, synth_method: "affix-balance", synth_base_id: null }))
 
 				balanceEmitted++
 			}
@@ -620,10 +535,10 @@ export const streetAffixRecipe: CorpusRecipe = {
 
 		console.error(
 			`Done: emitted ${emitted} affix rows, skipped ${skipped}, no-affix ${noAffix} (pool ${pool.length}).\n` +
-				`  formats: ${JSON.stringify(formatCounts)}\n` +
-				`  affix mix: ${JSON.stringify(affixCounts)}` +
+				`  formats: ${stringifyJSON(formatCounts)}\n` +
+				`  affix mix: ${stringifyJSON(affixCounts)}` +
 				(multilocaleCount > 0
-					? `\n  balance: emitted ${balanceEmitted}, skipped ${balanceSkipped}, iso ${JSON.stringify(balanceISO)}`
+					? `\n  balance: emitted ${balanceEmitted}, skipped ${balanceSkipped}, iso ${stringifyJSON(balanceISO)}`
 					: "")
 		)
 
@@ -631,24 +546,15 @@ export const streetAffixRecipe: CorpusRecipe = {
 	},
 }
 
-// The venue shell needs a real register: fewer names than this and the rows read as templates again.
 const VENUE_POOL_MIN_SIZE = 500
-// While both classes are open: 80% terminal-only, 20% terminal-contrast.
+
 const TERMINAL_ONLY_SHARE = 0.8
 
 /**
- * #1569 root-fix slice. Both classes come from real non-Vermont OA streets and use the affix recipe's existing layout
- * diversity. v4.3.1 makes terminal-only 80% of the mix: the first 40/60 run moved a 100-row TRAIN sample only 4→11
- * while contrast was already 95/100 before training (93/100 after). Post-run audit found that the global affix relabel
- * pass corrupts many already-decomposed target rows into double suffixes; do not retrain this recipe until relabel is
- * idempotent over a decomposed street family. The 20% contrast leg remains explicit, additive to the already-strong
- * base distribution, and B2 still checks it unchanged.
+ * Generates US rows that teach where a street name ends and its suffix begins.
  *
- * V2 (corpus 0.19.0, 2026-08-10 recipe review): the v4.3.3 board split (rich venue-led rows 5/43 vs bare 53/65) showed
- * the model separating template rows from real ones, and the venue shell was the giveaway — six fixed venue strings. v2
- * draws the venue shell from thousands of REAL HRSA facility names and raises its share (venue 30%, full 35%, bare 20%,
- * street-only 15%). Dose policy moved to the recipe's config side: weight ≤4 effective passes per run (Muennighoff
- * 2023's repetition knee) and the source is excluded from the augmentation pool — see the v4.4.0 config.
+ * The recipe targets 80% `terminal-only` and 20% `terminal-contrast` streets.
+ * It draws training rows from non-Vermont OpenAddresses streets and reserves Vermont for the golden set.
  */
 export const suffixBoundaryRecipe: CorpusRecipe = {
 	name: "suffix-boundary",
@@ -657,10 +563,9 @@ export const suffixBoundaryRecipe: CorpusRecipe = {
 	async run(opts, write) {
 		const random = makeMulberry32(opts.seed)
 		const count = opts.count ?? 30_000
-		const source = opts.sourceName ?? "synth-suffix-boundary"
+		const source = opts.sourceName ?? defaultRecipeSource("synth-suffix-boundary")
 		const sources = opts.golden ? [EVAL_SOURCE] : TRAIN_SOURCES
 
-		// v2 venue shell: real facility names, loud when the source file is missing or thin.
 		const venuePool = await readVenuePool(VENUE_POOL_CSV)
 
 		if (venuePool.length < VENUE_POOL_MIN_SIZE) {
@@ -722,7 +627,7 @@ export const suffixBoundaryRecipe: CorpusRecipe = {
 				country: "US",
 				locale: "en-US",
 				source,
-				source_id: sliceSourceID(source, { ...components, class: rowClass, n: String(emitted) }),
+				source_id: recipeSourceID(source, { ...components, class: rowClass, n: String(emitted) }),
 				corpus_version: "0.19.0",
 				license:
 					"OpenAddresses US (non-VT) skeletons; terminal suffix labels via USPS Pub-28 codex; venue shell from HRSA site names (US public domain)",
@@ -736,7 +641,7 @@ export const suffixBoundaryRecipe: CorpusRecipe = {
 				return false
 			}
 
-			write(JSON.stringify({ ...aligned.row, synth_method: method, synth_base_id: base.base_source_id }) + "\n")
+			write(stringifyJSON({ ...aligned.row, synth_method: method, synth_base_id: base.base_source_id }))
 
 			classCounts[rowClass]++
 			formatCounts[fmt] = (formatCounts[fmt] ?? 0) + 1
@@ -761,7 +666,7 @@ export const suffixBoundaryRecipe: CorpusRecipe = {
 						: "terminal-only"
 
 			const classPool = pool[rowClass]
-			const base = pick(classPool, random)
+			const base = sample(classPool, random)
 			const parsed = parseStreet(base.street, { allowNameProneTail: rowClass === "terminal-only" })
 
 			if (!parsed) {
@@ -772,11 +677,6 @@ export const suffixBoundaryRecipe: CorpusRecipe = {
 
 			if (!emitOne(rowClass, base, parsed, `suffix-boundary:${rowClass}`)) continue
 
-			// Stem-pair hard negative (v2, 2026-08-10 recipe review): after a terminal-only row
-			// ('Menlo Park' + 'Road'), also emit the SAME stem without its true suffix as a
-			// contrast row ('Menlo' + 'Park' under the canonical last-token rule). Sharing the stem
-			// forces the model to key on the licensing evidence — the trailing true suffix — rather
-			// than on name identity. Dose-neutral: these fill the existing 20% contrast target.
 			if (
 				rowClass === "terminal-only" &&
 				classCounts["terminal-contrast"] < classTargets["terminal-contrast"] &&
@@ -795,11 +695,11 @@ export const suffixBoundaryRecipe: CorpusRecipe = {
 		}
 
 		console.error(
-			`Done: emitted ${emitted}, skipped ${skipped}; source pools ${JSON.stringify({
+			`Done: emitted ${emitted}, skipped ${skipped}; source pools ${stringifyJSON({
 				terminalOnly: pool["terminal-only"].length,
 				terminalContrast: pool["terminal-contrast"].length,
-			})}; classes ${JSON.stringify(classCounts)}; stem pairs ${stemPairs}; ` +
-				`venue pool ${venuePool.length}; formats ${JSON.stringify(formatCounts)}`
+			})}; classes ${stringifyJSON(classCounts)}; stem pairs ${stemPairs}; ` +
+				`venue pool ${venuePool.length}; formats ${stringifyJSON(formatCounts)}`
 		)
 
 		return { emitted, skipped }

package/lib/recipes/street/bare.ts

@@ -3,30 +3,35 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `street-bare` slice recipe — BARE-street rows (the v0.8.0 harness change, 2026-06-05). The
+ *   `street-bare` recipe — bare-street rows (the v0.8.0 harness change, 2026-06-05). The
  *   `functional.test.ts` cluster (bare street names — "10th Ave", "Main St", "1 Main Pl") was
- *   mislabeled `locality` because {@link synthesizeStreetRow} only ever emitted streets WITH a ",
- *   City, ST ZIP" tail. This recipe emits streets BARE (`--bare-prob`, default 0.6) — no tail, only
+ *   mislabeled `locality` because {@link synthesizeStreetRow} only ever emitted streets with a ",
+ *   City, ST ZIP" tail. This recipe emits streets bare (`--bare-prob`, default 0.6) — no tail, only
  *   `street_prefix`/`street`/`street_suffix` (+ optional `house_number` at `--hn-prob`, default
  *   0.85) — over the built-in {@link DEFAULT_US_BASES} pool (round-robin). Generate-mode, US-only,
- *   in-distribution (no German-collapse risk). Ported from scripts/build-street-bare-slice.mjs.
+ *   in-distribution (no German-collapse risk). Ported from the root build script it replaced.
  *
  *   Byte-fidelity: the legacy script seeded its own mulberry32 from `--seed`
- *   (`mulberry32(opts.seed)`); this recipe re-creates the SAME generator
+ *   (`mulberry32(opts.seed)`); this recipe re-creates the same generator
  *   (`makeMulberry32(opts.seed)`) and preserves the synthesis call order exactly, so `--seed N`
  *   reproduces the legacy run byte-for-byte.
  */
 
+import { stringifyJSON } from "@mailwoman/core/json"
 import { mulberry32 as makeMulberry32 } from "@mailwoman/core/utils"
 
-import { sliceSourceID, type CanonicalSliceRow, type CorpusRecipe } from "#recipes/scaffold"
-import { DEFAULT_US_BASES } from "#synthesizers/intersection"
-import { synthesizeStreetRow, type StreetBaseTuple } from "#synthesizers/street"
+import { recipeSourceID, requireRegister, type CanonicalRecipeRow, type CorpusRecipe } from "#recipes/scaffold"
+import { defaultRecipeSource } from "#recipes/sources"
+import { SurfaceOrigin } from "#types"
+import { DEFAULT_US_BASES } from "#us/synthesizers/intersection"
+import { synthesizeStreetRow, type StreetBaseTuple } from "#us/synthesizers/street"
 import { alignRow } from "#utils"
 
 /**
- * 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 streetBareRecipe: CorpusRecipe = {
 	name: "street-bare",
@@ -41,7 +46,7 @@ export const streetBareRecipe: CorpusRecipe = {
 		const count = opts.count ?? 3000
 		const bareProb = opts.bareProb ?? 0.6
 		const hnProb = opts.hnProb ?? 0.85
-		const source = opts.sourceName ?? "synth-street-bare"
+		const source = opts.sourceName ?? defaultRecipeSource("synth-street-bare")
 
 		let emitted = 0
 		let skipped = 0
@@ -64,13 +69,13 @@ export const streetBareRecipe: CorpusRecipe = {
 
 			const isBare = synth.components.region === undefined
 
-			const canonical: CanonicalSliceRow = {
+			const canonical: CanonicalRecipeRow = {
 				raw: synth.raw,
 				components: synth.components,
 				country: base.country,
 				locale: synth.locale,
 				source,
-				source_id: sliceSourceID(source, {
+				source_id: recipeSourceID(source, {
 					street: synth.components.street,
 					street_suffix: synth.components.street_suffix,
 					house_number: synth.components.house_number,
@@ -81,9 +86,9 @@ export const streetBareRecipe: CorpusRecipe = {
 				license: "Synthetic — US street templates, public-domain street/city pools",
 			}
 
-			// Strict labeled-only check (matches the legacy builder): alignRow always returns a `row`
-			// (labeled OR quarantined), so the scaffold's `alignAndWrite` would write quarantined rows
-			// too — call alignRow directly and skip anything not "labeled".
+			// Strict labeled-only check (matches the legacy builder): alignRow always returns
+			// a `row` (labeled or quarantined), so the scaffold's `alignAndWrite` would write
+			// quarantined rows too — call alignRow directly and skip anything not "labeled".
 			const aligned = alignRow(canonical as Parameters<typeof alignRow>[0])
 
 			if (aligned.kind !== "labeled" || !aligned.row) {
@@ -92,7 +97,15 @@ export const streetBareRecipe: CorpusRecipe = {
 				continue
 			}
 
-			write(JSON.stringify({ ...aligned.row, synth_method: "street-bare", synth_base_id: null }) + "\n")
+			write(
+				stringifyJSON({
+					...aligned.row,
+					recipe: "street-bare",
+					base_source_id: null,
+					register: requireRegister(opts, "street-bare"),
+					surface: SurfaceOrigin.Composed,
+				})
+			)
 
 			emitted++
 		}