@mailwoman/corpus 8.6.0 → 9.1.0

package/src/shard-recipes/street-affix.ts

@@ -27,8 +27,6 @@
  *   FR/DE postcode (the v0.9.8 blemish).
  */
 
-import { spawnSync } from "node:child_process"
-
 import {
 	DirectionalAbbreviation,
 	lookupDirectional,
@@ -39,11 +37,13 @@ import {
 	US_STREET_SUFFIX_PREFERRED_ABBR,
 } from "@mailwoman/codex/us"
 import type { ComponentTag } from "@mailwoman/core/types"
+import { dataRootPath } from "@mailwoman/core/utils"
+import { stableSourceID } from "@mailwoman/corpus/adapters/utils"
+import type { CanonicalRow } from "@mailwoman/corpus/types"
+import { alignRow } from "@mailwoman/corpus/utils"
 
-import { stableSourceID } from "../adapter.ts"
-import { alignRow } from "../align.ts"
-import type { CanonicalRow } from "../types.ts"
-import { makeMulberry32, type ShardRecipe } from "./scaffold.ts"
+import { NAME_PRONE_US_SUFFIXES } from "../name-prone-us-suffixes.ts"
+import { makeMulberry32, readCSVRecords, readZippedCSVRecords, shardSourceID, type ShardRecipe } from "./scaffold.ts"
 
 // Same OA cache as the unit shard. Train = every NON-Vermont state; eval = Vermont (the holdout).
 /* oxlint-disable sister-software/no-unnamed-threshold -- the bare decimals below are weighted-sampler
@@ -59,16 +59,20 @@ interface USSource {
 }
 
 const TRAIN_SOURCES: readonly USSource[] = [
-	{ zip: "/tmp/oa-cache/us__ca__berkeley.zip", csv: "us/ca/berkeley.csv", region: "CA" },
-	{ zip: "/tmp/oa-cache/us__ca__marin.zip", csv: "us/ca/marin.csv", region: "CA" },
-	{ zip: "/tmp/oa-cache/us__dc__statewide.zip", csv: "us/dc/statewide.csv", region: "DC" },
-	{ zip: "/tmp/oa-cache/us__ia__statewide.zip", csv: "us/ia/statewide.csv", region: "IA" },
-	{ zip: "/tmp/oa-cache/us__il__cook.zip", csv: "us/il/cook.csv", region: "IL" },
-	{ zip: "/tmp/oa-cache/us__mt__statewide.zip", csv: "us/mt/statewide.csv", region: "MT" },
-	{ zip: "/tmp/oa-cache/us__sd__statewide.zip", csv: "us/sd/statewide.csv", region: "SD" },
+	{ zip: dataRootPath("oa-cache", "us__ca__berkeley.zip"), csv: "us/ca/berkeley.csv", region: "CA" },
+	{ zip: dataRootPath("oa-cache", "us__ca__marin.zip"), csv: "us/ca/marin.csv", region: "CA" },
+	{ zip: dataRootPath("oa-cache", "us__dc__statewide.zip"), csv: "us/dc/statewide.csv", region: "DC" },
+	{ zip: dataRootPath("oa-cache", "us__ia__statewide.zip"), csv: "us/ia/statewide.csv", region: "IA" },
+	{ zip: dataRootPath("oa-cache", "us__il__cook.zip"), csv: "us/il/cook.csv", region: "IL" },
+	{ zip: dataRootPath("oa-cache", "us__mt__statewide.zip"), csv: "us/mt/statewide.csv", region: "MT" },
+	{ zip: dataRootPath("oa-cache", "us__sd__statewide.zip"), csv: "us/sd/statewide.csv", region: "SD" },
 ]
 
-const EVAL_SOURCE: USSource = { zip: "/tmp/oa-cache/us__vt__statewide.zip", csv: "us/vt/statewide.csv", region: "VT" }
+const EVAL_SOURCE: USSource = {
+	zip: dataRootPath("oa-cache", "us__vt__statewide.zip"),
+	csv: "us/vt/statewide.csv",
+	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
@@ -83,14 +87,38 @@ interface BalanceSource {
 }
 
 const MULTILOCALE_SOURCES: readonly BalanceSource[] = [
-	{ zip: "/tmp/oa-cache/de__sn__statewide.zip", csv: "de/sn/statewide.csv", iso2: "DE", region: "", order: "eu" },
-	{ zip: "/tmp/oa-cache/fr__countrywide.zip", csv: "fr/countrywide.csv", iso2: "FR", region: "", order: "fr" },
-	{ zip: "/tmp/oa-cache/it__countrywide.zip", csv: "it/countrywide.csv", iso2: "IT", region: "", order: "eu" },
-	{ zip: "/tmp/oa-cache/nl__countrywide.zip", csv: "nl/countrywide.csv", iso2: "NL", region: "", order: "eu" },
+	{
+		zip: dataRootPath("oa-cache", "de__sn__statewide.zip"),
+		csv: "de/sn/statewide.csv",
+		iso2: "DE",
+		region: "",
+		order: "eu",
+	},
+	{
+		zip: dataRootPath("oa-cache", "fr__countrywide.zip"),
+		csv: "fr/countrywide.csv",
+		iso2: "FR",
+		region: "",
+		order: "fr",
+	},
+	{
+		zip: dataRootPath("oa-cache", "it__countrywide.zip"),
+		csv: "it/countrywide.csv",
+		iso2: "IT",
+		region: "",
+		order: "eu",
+	},
+	{
+		zip: dataRootPath("oa-cache", "nl__countrywide.zip"),
+		csv: "nl/countrywide.csv",
+		iso2: "NL",
+		region: "",
+		order: "eu",
+	},
 ]
 
 const MULTILOCALE_EVAL_SOURCES: readonly BalanceSource[] = [
-	{ zip: "/tmp/oa-cache/de__berlin.zip", csv: "de/berlin.csv", iso2: "DE", region: "", order: "eu" },
+	{ zip: dataRootPath("oa-cache", "de__berlin.zip"), csv: "de/berlin.csv", iso2: "DE", region: "", order: "eu" },
 ]
 
 /**
@@ -111,6 +139,7 @@ interface USTuple {
 	locality: string
 	region: string
 	postcode: string
+	base_source_id: string
 }
 
 /**
@@ -131,84 +160,32 @@ interface BalanceTuple {
  */
 type Prefix = Pick<NonNullable<ReturnType<typeof matchLeadingDirectional>>, "canonical" | "abbreviation">
 
-/**
- * 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 US tuples (number/street/city/postcode) out of a cached OA zip.
  */
-function readTuples(source: USSource): USTuple[] {
-	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"),
-		iPost = idx("postcode")
-
-	const get = (cells: string[], i: number): string => (i >= 0 && i < cells.length ? (cells[i] ?? "").trim() : "")
+async function readTuples(source: USSource): Promise<USTuple[]> {
 	const tuples: USTuple[] = []
 	const seen = new Set<string>()
 
-	for (let li = 1; li < lines.length; 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)
+	for await (const row of readZippedCSVRecords(source.zip, source.csv)) {
+		const street = row.street ?? ""
+		const locality = row.city ?? ""
+		const house_number = row.number ?? ""
 
 		if (!street || !locality || !house_number) continue
 		const key = `${house_number}|${street}|${locality}`.toLowerCase()
 
 		if (seen.has(key)) continue
 		seen.add(key)
-		tuples.push({ house_number, street, locality, region: source.region, postcode: get(cells, iPost) })
+
+		tuples.push({
+			house_number,
+			street,
+			locality,
+			region: source.region,
+			postcode: row.postcode ?? "",
+			base_source_id: `openaddresses:${source.csv}:${key}`,
+		})
 	}
 
 	return tuples
@@ -228,7 +205,10 @@ const isSuffixOrDirectional = (word: string): boolean =>
  * 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): { prefix: Prefix | null; name: string; suffix: string } | null {
+function parseStreet(
+	street: string,
+	opts: { allowNameProneTail?: boolean } = {}
+): { prefix: Prefix | null; name: string; suffix: string } | null {
 	let words = street.trim().split(/\s+/)
 
 	if (words.length < 2) return null
@@ -248,11 +228,42 @@ function parseStreet(street: string): { prefix: Prefix | null; name: string; suf
 	const suffix = trail.canonical
 	const name = words.slice(0, -1).join(" ")
 
-	if (!name || isSuffixOrDirectional(name)) return null
+	if (!name) return null
+
+	if (isSuffixOrDirectional(name)) {
+		const nameTail = matchTrailingSuffix(name)
+
+		if (!opts.allowNameProneTail || !nameTail || !NAME_PRONE_US_SUFFIXES.has(nameTail.canonical)) return null
+	}
 
 	return { prefix, name, suffix }
 }
 
+export type SuffixBoundaryClass = "terminal-only" | "terminal-contrast"
+
+/**
+ * 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.
+ */
+export function classifySuffixBoundaryStreet(street: string): SuffixBoundaryClass | null {
+	const words = street.trim().split(/\s+/)
+
+	if (words.length < 2) return null
+	const terminal = matchTrailingSuffix(words.at(-1)!)
+
+	if (!terminal) return null
+
+	if (NAME_PRONE_US_SUFFIXES.has(terminal.canonical)) return "terminal-contrast"
+
+	if (words.length < 3) return null
+
+	const penultimate = matchTrailingSuffix(words.at(-2)!)
+
+	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.
  */
@@ -302,18 +313,65 @@ function renderStreet(
  */
 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 shard'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",
+	"usgov-hrsa-fqhc",
+	"Health_Center_Service_Delivery_and_LookAlike_Sites.csv"
+)
+
+async function readVenuePool(csvPath: string): Promise<string[]> {
+	const seen = new Set<string>()
+	const pool: string[] = []
+
+	for await (const record of readCSVRecords(csvPath)) {
+		const name = (record["site name"] ?? record["Site Name"] ?? "").trim().replaceAll(/\s+/gu, " ")
+
+		if (name.length < 3 || name.length > 60 || name.includes(",") || !/\p{L}/u.test(name)) continue
+		const key = name.toLowerCase()
+
+		if (seen.has(key)) continue
+		seen.add(key)
+		pool.push(name)
+	}
+
+	return pool
+}
+
 const tail = (loc: string, reg: string, pc: string): string => (pc ? `${loc}, ${reg} ${pc}` : `${loc}, ${reg}`)
 
+/**
+ * Layout-shell options for {@link renderRow}. `cuts` are the cumulative random() cutoffs 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[]
+	cuts?: 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.
  */
-function renderRow(
+export function renderRow(
 	random: () => number,
 	base: USTuple,
 	street: string,
-	streetComponents: Partial<Record<ComponentTag, string>>
+	streetComponents: Partial<Record<ComponentTag, string>>,
+	opts: RenderRowOpts = {}
 ): { fmt: string; raw: string; components: Partial<Record<ComponentTag, string>> } {
+	const venues = opts.venues ?? VENUES
+	const [fullCut, bareCut, streetOnlyCut] = opts.cuts ?? [0.4, 0.65, 0.85]
+
 	const hn = base.house_number,
 		loc = base.locality,
 		reg = base.region,
@@ -323,17 +381,17 @@ function renderRow(
 	const withRoad: Partial<Record<ComponentTag, string>> = { house_number: hn, ...streetComponents }
 	const r = random()
 
-	if (r < 0.4)
+	if (r < fullCut)
 		return {
 			fmt: "full",
 			raw: `${road}, ${tail(loc, reg, pc)}`,
 			components: { ...withRoad, locality: loc, region: reg, ...(pc ? { postcode: pc } : {}) },
 		}
 
-	if (r < 0.65) return { fmt: "bare", raw: road, components: withRoad }
+	if (r < bareCut) return { fmt: "bare", raw: road, components: withRoad }
 
-	if (r < 0.85) return { fmt: "street-only", raw: street, components: { ...streetComponents } }
-	const v = VENUES[Math.floor(random() * VENUES.length)]!
+	if (r < streetOnlyCut) return { fmt: "street-only", raw: street, components: { ...streetComponents } }
+	const v = venues[Math.floor(random() * venues.length)]!
 
 	return {
 		fmt: "venue",
@@ -343,48 +401,21 @@ function renderRow(
 }
 
 /**
- * Capped reader for the multi-locale BALANCE sources. The FR/IT/NL countrywide extracts are GB-scale; reading the whole
- * CSV blows V8's string limit, so cap the bytes with `head` (mirrors build-country-shard-balanced.mjs). Only keeps
- * tuples that carry a POSTCODE.
+ * 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.
  */
-function readBalanceTuples(source: BalanceSource, limit: number): BalanceTuple[] {
-	const maxLines = Math.max(limit * 8, 20_000) + 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 = (n: string): number => header.indexOf(n)
-
-	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() : "")
+async function readBalanceTuples(source: BalanceSource, limit: number): Promise<BalanceTuple[]> {
 	const tuples: BalanceTuple[] = []
 	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]!)
+	for await (const row of readZippedCSVRecords(source.zip, source.csv)) {
+		if (tuples.length >= limit) break
 
-		const street = get(cells, iStreet),
-			locality = get(cells, iCity),
-			house_number = get(cells, iNum),
-			postcode = get(cells, iPost)
+		const street = row.street ?? "",
+			locality = row.city ?? "",
+			house_number = row.number ?? "",
+			postcode = row.postcode ?? ""
 
 		if (!street || !locality || !house_number || !postcode) continue // postcode is required for balance
 		const key = `${house_number}|${street}|${locality}`.toLowerCase()
@@ -396,7 +427,7 @@ function readBalanceTuples(source: BalanceSource, limit: number): BalanceTuple[]
 			house_number,
 			street,
 			locality,
-			region: get(cells, iRegion) || source.region,
+			region: row.region || source.region,
 			postcode,
 			iso2: source.iso2,
 			order: source.order,
@@ -449,7 +480,7 @@ export const streetAffixRecipe: ShardRecipe = {
 		const pool: USTuple[] = []
 
 		for (const s of sources) {
-			const t = readTuples(s)
+			const t = await readTuples(s)
 
 			console.error(`  ${s.csv}: ${t.length} unique tuples`)
 
@@ -459,7 +490,7 @@ export const streetAffixRecipe: ShardRecipe = {
 		}
 
 		if (!pool.length) {
-			throw new Error("No US tuples found — are the cached OA zips present in /tmp/oa-cache?")
+			throw new Error(`No US tuples found — are the cached OA zips present in ${dataRootPath("oa-cache")}?`)
 		}
 
 		let emitted = 0
@@ -550,7 +581,7 @@ export const streetAffixRecipe: ShardRecipe = {
 			const mlPool: BalanceTuple[] = []
 
 			for (const s of mlSources) {
-				const t = readBalanceTuples(s, perSource)
+				const t = await readBalanceTuples(s, perSource)
 
 				console.error(`  balance ${s.csv} (${s.iso2}): ${t.length} tuples`)
 
@@ -622,3 +653,173 @@ export const streetAffixRecipe: ShardRecipe = {
 		return { emitted: emitted + balanceEmitted, skipped: skipped + balanceSkipped }
 	},
 }
+
+/**
+ * #1569 root-fix shard. 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 gates it unchanged.
+ *
+ * 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.
+ */
+export const suffixBoundaryRecipe: ShardRecipe = {
+	name: "suffix-boundary",
+	description: "US #1569 suffix boundary: OA terminal-only positives + over-sampled terminal contrasts",
+	mode: "generate",
+	async run(opts, write) {
+		const random = makeMulberry32(opts.seed)
+		const count = opts.count ?? 30_000
+		const source = opts.sourceName ?? "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 < 500) {
+			throw new Error(
+				`suffix-boundary v2 venue pool too thin: ${venuePool.length} names from ${VENUE_POOL_CSV} — ` +
+					"is the usgov-hrsa-fqhc source present?"
+			)
+		}
+
+		const shell: RenderRowOpts = { venues: venuePool, cuts: [0.35, 0.55, 0.7] }
+
+		const pool: Record<SuffixBoundaryClass, USTuple[]> = {
+			"terminal-only": [],
+			"terminal-contrast": [],
+		}
+
+		for (const s of sources) {
+			for (const tuple of await readTuples(s)) {
+				const rowClass = classifySuffixBoundaryStreet(tuple.street)
+
+				if (rowClass) {
+					pool[rowClass].push(tuple)
+				}
+			}
+		}
+
+		if (!pool["terminal-only"].length || !pool["terminal-contrast"].length) {
+			throw new Error(
+				`Suffix-boundary source class missing: terminal-only=${pool["terminal-only"].length}, ` +
+					`terminal-contrast=${pool["terminal-contrast"].length}`
+			)
+		}
+
+		let emitted = 0
+		let skipped = 0
+		const classCounts: Record<SuffixBoundaryClass, number> = { "terminal-only": 0, "terminal-contrast": 0 }
+		const terminalOnlyTarget = Math.round(count * 0.8)
+
+		const classTargets: Record<SuffixBoundaryClass, number> = {
+			"terminal-only": terminalOnlyTarget,
+			"terminal-contrast": count - terminalOnlyTarget,
+		}
+
+		const formatCounts: Record<string, number> = {}
+		let stemPairs = 0
+
+		const emitOne = (
+			rowClass: SuffixBoundaryClass,
+			base: USTuple,
+			parsed: NonNullable<ReturnType<typeof parseStreet>>,
+			method: string
+		): boolean => {
+			const { street, components: streetComponents } = renderStreet(random, parsed)
+			const { fmt, raw, components } = renderRow(random, base, street, streetComponents, shell)
+
+			const canonical: CanonicalRow = {
+				raw,
+				components,
+				country: "US",
+				locale: "en-US",
+				source,
+				source_id: shardSourceID(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)",
+			}
+
+			const aligned = alignRow(canonical)
+
+			if (aligned.kind !== "labeled" || !aligned.row) {
+				skipped++
+
+				return false
+			}
+
+			write(JSON.stringify({ ...aligned.row, synth_method: method, synth_base_id: base.base_source_id }) + "\n")
+
+			classCounts[rowClass]++
+			formatCounts[fmt] = (formatCounts[fmt] ?? 0) + 1
+
+			emitted++
+
+			return true
+		}
+
+		// oxlint-disable-next-line eslint/no-unmodified-loop-condition -- emitted/skipped advance inside emitOne (a closure); the rule cannot see through the call
+		while (emitted < count && emitted + skipped < count * 10) {
+			const terminalOnlyOpen = classCounts["terminal-only"] < classTargets["terminal-only"]
+			const terminalContrastOpen = classCounts["terminal-contrast"] < classTargets["terminal-contrast"]
+
+			const rowClass: SuffixBoundaryClass =
+				terminalOnlyOpen && terminalContrastOpen
+					? random() < 0.8
+						? "terminal-only"
+						: "terminal-contrast"
+					: terminalContrastOpen
+						? "terminal-contrast"
+						: "terminal-only"
+
+			const classPool = pool[rowClass]
+			const base = classPool[Math.floor(random() * classPool.length)]!
+			const parsed = parseStreet(base.street, { allowNameProneTail: rowClass === "terminal-only" })
+
+			if (!parsed) {
+				skipped++
+
+				continue
+			}
+
+			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"] &&
+				emitted < count &&
+				random() < 0.5
+			) {
+				const stemParsed = parseStreet(parsed.name)
+
+				if (
+					stemParsed &&
+					emitOne("terminal-contrast", base, stemParsed, "suffix-boundary:terminal-contrast:stem-pair")
+				) {
+					stemPairs++
+				}
+			}
+		}
+
+		console.error(
+			`Done: emitted ${emitted}, skipped ${skipped}; source pools ${JSON.stringify({
+				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)}`
+		)
+
+		return { emitted, skipped }
+	},
+}

package/src/shard-recipes/street-bare.ts

@@ -17,9 +17,10 @@
  *   reproduces the legacy run byte-for-byte.
  */
 
-import { alignRow } from "../align.ts"
-import { DEFAULT_US_BASES } from "../synthesize-intersection.ts"
-import { synthesizeStreetRow, type StreetBaseTuple } from "../synthesize-street.ts"
+import { DEFAULT_US_BASES } from "@mailwoman/corpus/synthesizers/intersection"
+import { synthesizeStreetRow, type StreetBaseTuple } from "@mailwoman/corpus/synthesizers/street"
+import { alignRow } from "@mailwoman/corpus/utils"
+
 import { makeMulberry32, shardSourceID, type CanonicalShardRow, type ShardRecipe } from "./scaffold.ts"
 
 /**

package/src/shard-recipes/street.ts

@@ -7,8 +7,9 @@
  *   {@link synthesizeStreetRow} → aligned LabeledRow. Ported from scripts/build-street-shard.mjs.
  */
 
-import { stableSourceID } from "../adapter.ts"
-import { synthesizeStreetRow, type StreetBaseTuple } from "../synthesize-street.ts"
+import { stableSourceID } from "@mailwoman/corpus/adapters/utils"
+import { synthesizeStreetRow, type StreetBaseTuple } from "@mailwoman/corpus/synthesizers/street"
+
 import { alignAndWrite, makeLcg, readTuples, type ShardRecipe } from "./scaffold.ts"
 
 /**