@mailwoman/corpus 8.6.0 → 9.1.0

package/src/shard-recipes/po-box-cedex.ts

@@ -20,9 +20,9 @@
  *   locality-hash holdout (hash%10===0).
  *
  *   Prerequisites (read once, before the generation loop — these do NOT consume `random`): the cached
- *   OA zips in /tmp/oa-cache, the GeoNames Canada dump at /tmp/geonames-cache/CA.zip, and the
- *   GeoNames POSTAL-CODE dumps for AU/NZ (/tmp/geonames-cache/{AU,NZ}-postal.zip). See the legacy
- *   script header for the exact curl commands.
+ *   OA zips in `$MAILWOMAN_DATA_ROOT/oa-cache`, the GeoNames Canada dump at
+ *   `$MAILWOMAN_DATA_ROOT/geonames/CA.zip`, and the GeoNames POSTAL-CODE dumps for AU/NZ
+ *   (`$MAILWOMAN_DATA_ROOT/geonames-postal/{AU,NZ}.zip`).
  *
  *   Byte-fidelity: the legacy script seeded its own mulberry32 from `--seed`
  *   (`mulberry32(opts.seed)`); this recipe re-creates the SAME generator
@@ -30,22 +30,32 @@
  *   reproduces the legacy run byte-for-byte.
  */
 
-import { spawnSync } from "node:child_process"
+import { existsSync } from "node:fs"
 
 import { isAuDeliveryService, isAuPostcode, isAuStateAbbreviation } from "@mailwoman/codex/au"
 import { FSA_LETTER_TO_PROVINCE, normalizeCaPostalCode } from "@mailwoman/codex/ca"
 import { isCedex } from "@mailwoman/codex/fr"
-import { isNzDeliveryService, isNzPostcode } from "@mailwoman/codex/nz"
+import { isNZDeliveryService, isNZPostcode } from "@mailwoman/codex/nz"
 import { isPOBox } from "@mailwoman/codex/us"
-
-import { alignRow } from "../align.ts"
+import { readZipEntry } from "@mailwoman/core/fs/zip"
+import { dataRootPath } from "@mailwoman/core/utils"
 import {
 	maybeNoisifyBoxNumber,
 	PO_BOX_LOCALE_TEMPLATES,
 	synthesizeMilitaryPoBoxRow,
 	type LocaleTemplate,
-} from "../synthesize-po-box.ts"
-import { makeMulberry32, shardSourceID, type CanonicalShardRow, type ShardRecipe } from "./scaffold.ts"
+} from "@mailwoman/corpus/synthesizers/po-box"
+import { alignRow } from "@mailwoman/corpus/utils"
+import { TextSpliterator, TSVSpliterator } from "spliterator"
+
+import {
+	makeMulberry32,
+	readCSVRecords,
+	readZippedCSVRecords,
+	shardSourceID,
+	type CanonicalShardRow,
+	type ShardRecipe,
+} from "./scaffold.ts"
 
 // ── Base-skeleton sources ────────────────────────────────────────────────────────────────────────
 // Same OA cache as the unit/affix shards. US train = every NON-Vermont state; US eval = Vermont (the
@@ -58,20 +68,29 @@ import { makeMulberry32, shardSourceID, type CanonicalShardRow, type ShardRecipe
    extracted as named constants above. */
 
 const US_TRAIN_SOURCES = [
-	{ 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 US_EVAL_SOURCE = { zip: "/tmp/oa-cache/us__vt__statewide.zip", csv: "us/vt/statewide.csv", region: "VT" }
-const FR_SOURCE = { zip: "/tmp/oa-cache/fr__countrywide.zip", csv: "fr/countrywide.csv" }
-const GEONAMES_CA = "/tmp/geonames-cache/CA.zip"
-const GEONAMES_POSTAL_AU = { zip: "/tmp/geonames-cache/AU-postal.zip", txt: "AU.txt" }
-const GEONAMES_POSTAL_NZ = { zip: "/tmp/geonames-cache/NZ-postal.zip", txt: "NZ.txt" }
+const US_EVAL_SOURCE = {
+	zip: dataRootPath("oa-cache", "us__vt__statewide.zip"),
+	csv: "us/vt/statewide.csv",
+	region: "VT",
+}
+
+const FR_SOURCE = { zip: dataRootPath("oa-cache", "fr__countrywide.zip"), csv: "fr/countrywide.csv" }
+// GeoNames has two per-country exports with different schemas, and this recipe reads both. The MAIN
+// dump (feature class + population columns) lives under `geonames/`; the POSTAL-CODE dump lives
+// under `geonames-postal/`, where the directory carries the "postal" distinction the filename used
+// to.
+const GEONAMES_CA = dataRootPath("geonames", "CA.zip")
+const GEONAMES_POSTAL_AU = { zip: dataRootPath("geonames-postal", "AU.zip"), txt: "AU.txt" }
+const GEONAMES_POSTAL_NZ = { zip: dataRootPath("geonames-postal", "NZ.zip"), txt: "NZ.txt" }
 
 /**
  * ── Surface vocabulary (codex + corpus templates — see the header) ──────────────────────────────.
@@ -172,20 +191,20 @@ interface USTuple {
 	postcode: string
 }
 
-interface FrTuple {
+interface FRTuple {
 	house_number: string
 	street: string
 	locality: string
 	postcode: string
 }
 
-interface AuTuple {
+interface AUTuple {
 	locality: string
 	region: string
 	postcode: string
 }
 
-interface NzTuple {
+interface NZTuple {
 	locality: string
 	postcode: string
 }
@@ -214,44 +233,6 @@ function localityHash(name: string): number {
 
 const isHoldoutLocality = (name: string): boolean => localityHash(name) % 10 === 0
 
-/**
- * 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
-}
-
 const MAX_LOCALITY_LENGTH = 40
 
 const cleanLocality = (loc: string) =>
@@ -260,93 +241,75 @@ const cleanLocality = (loc: string) =>
 /**
  * Stream real US tuples (number/street/city/postcode) out of a cached OA zip.
  */
-function readUsTuples(source: { zip: string; csv: string; region: string }): 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) => header.indexOf(name)
-
-	const iNum = idx("number"),
-		iStreet = idx("street"),
-		iCity = idx("city"),
-		iPost = idx("postcode")
-
-	const get = (cells: string[], i: number) => (i >= 0 && i < cells.length ? (cells[i] ?? "").trim() : "")
+async function readUsTuples(source: { zip: string; csv: string; region: string }): 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 locality = get(cells, iCity)
+	for await (const row of readZippedCSVRecords(source.zip, source.csv)) {
+		const locality = row.city ?? ""
 
 		if (!cleanLocality(locality)) continue
 		const key = locality.toLowerCase()
 
-		const street = get(cells, iStreet),
-			house_number = get(cells, iNum)
+		const street = row.street ?? "",
+			house_number = row.number ?? ""
 
 		// One tuple per (locality, street) pair keeps the pool varied without ballooning memory.
 		const pairKey = `${key}|${street}`.toLowerCase()
 
 		if (seen.has(pairKey)) continue
 		seen.add(pairKey)
-		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 ?? "" })
 	}
 
 	return tuples
 }
 
 /**
- * Stride-sampled FR tuples (number/street/city/postcode). The countrywide CSV is 2.5 GB and insee-ordered; `awk NR%K`
- * strides the whole country instead of reading one département. Quoted commas survive because awk only FILTERS lines —
- * parsing stays in splitCSV.
+ * The FR stride: keep line 3, then every 211th. Both numbers are the awk pre-filter's, kept exactly — they select which
+ * rows land in the shard, so changing either re-rolls the sample.
  */
-function readFrTuples(limit: number): FrTuple[] {
-	const r = spawnSync(
-		"bash",
-		["-c", `unzip -p "${FR_SOURCE.zip}" "${FR_SOURCE.csv}" | awk 'NR==1 || NR%211==3' | head -n ${limit + 1}`],
-		{ maxBuffer: 1024 * 1024 * 1024, encoding: "buffer" }
-	)
+const FR_STRIDE = 211
+const FR_STRIDE_OFFSET = 3
 
-	if (r.status !== 0 && !r.stdout.length) {
-		console.error(`  WARN: unzip failed for ${FR_SOURCE.zip}`)
+/**
+ * GeoNames population floor for a Canadian locality to enter the pool.
+ */
+const CA_LOCALITY_MIN_POPULATION = 1000
+
+/**
+ * Stride-sampled FR tuples (number/street/city/postcode). The countrywide CSV is 2.5 GB and insee-ordered; `awk NR%K`
+ * strides the whole country instead of reading one département.
+ *
+ * The stride counts PHYSICAL lines, so a record carrying a newline inside a quoted field is two lines to the stride and
+ * can be cut in half by it. That is a sampling artefact of striding before the parse, not of the parse: whichever lines
+ * survive are re-assembled into records by the CSV reader, and a halved record fails the field checks below. Hence
+ * `skipEmpty: false` and no quote handling on the line split — a blank line still advances the count, exactly as it did
+ * when this was `awk NR`, and the rows the stride selects are the rows every existing FR shard was built from.
+ */
+async function readFrTuples(limit: number): Promise<FRTuple[]> {
+	if (!existsSync(FR_SOURCE.zip)) {
+		console.error(`  WARN: ${FR_SOURCE.zip} is not cached — skipping ${FR_SOURCE.csv}`)
 
 		return []
 	}
 
-	const lines = r.stdout.toString("utf8").split(/\r?\n/)
+	const encoder = new TextEncoder()
 
-	if (lines.length < 2) return []
-	const header = splitCSV(lines[0]!).map((h) => h.trim().toLowerCase())
-	const idx = (n: string) => header.indexOf(n)
+	const strided = TextSpliterator.fromAsync(readZipEntry(FR_SOURCE.zip, FR_SOURCE.csv), { skipEmpty: false })
+		// `index` is 0-based where awk's NR is 1-based, hence the +1: keep the header, then every 211th line at offset 3.
+		.filter((_line, index) => index === 0 || (index + 1) % FR_STRIDE === FR_STRIDE_OFFSET)
+		.take(limit + 1)
+		.map((line) => encoder.encode(line + "\n"))
 
-	const iNum = idx("number"),
-		iStreet = idx("street"),
-		iCity = idx("city"),
-		iPost = idx("postcode")
-
-	const get = (cells: string[], i: number) => (i >= 0 && i < cells.length ? (cells[i] ?? "").trim() : "")
-	const tuples: FrTuple[] = []
+	const tuples: FRTuple[] = []
 	const seen = new Set<string>()
 
-	for (let li = 1; li < lines.length; li++) {
-		if (!lines[li]) continue
-		const cells = splitCSV(lines[li]!)
-
-		const locality = get(cells, iCity),
-			postcode = get(cells, iPost),
-			street = get(cells, iStreet),
-			house_number = get(cells, iNum)
+	for await (const row of readCSVRecords(strided)) {
+		const locality = row.city ?? "",
+			postcode = row.postcode ?? "",
+			street = row.street ?? "",
+			house_number = row.number ?? ""
 
 		if (!cleanLocality(locality) || !/^\d{5}$/.test(postcode) || !street || !house_number) continue
 		const key = `${locality}|${street}`.toLowerCase()
@@ -363,23 +326,29 @@ function readFrTuples(limit: number): FrTuple[] {
  * Canadian locality pools from the GeoNames dump (CC-BY 4.0): feature class P, admin1 10 (Québec) / 08 (Ontario),
  * population > 1000. GeoNames is the provenance-tracked source — no hand list.
  */
-function readCaLocalities(admin1: string): string[] {
-	const r = spawnSync(
-		"bash",
-		[
-			"-c",
-			`unzip -p "${GEONAMES_CA}" CA.txt | awk -F'\\t' '$7=="P" && $9=="CA" && $11=="${admin1}" && $15>1000 {print $2}'`,
-		],
-		{ maxBuffer: 1024 * 1024 * 256, encoding: "utf8" }
-	)
-
-	if (r.status !== 0) {
-		console.error(`  WARN: GeoNames read failed (admin1=${admin1}) — is ${GEONAMES_CA} present?`)
+async function readCaLocalities(admin1: string): Promise<string[]> {
+	if (!existsSync(GEONAMES_CA)) {
+		console.error(`  WARN: ${GEONAMES_CA} is not cached — skipping CA localities (admin1=${admin1})`)
 
 		return []
 	}
 
-	return [...new Set(r.stdout.split("\n").filter(cleanLocality))]
+	const localities = new Set<string>()
+
+	// GeoNames main dump columns, 0-based: 1 name, 6 feature class, 8 country, 10 admin1, 14 population.
+	for await (const columns of TSVSpliterator.fromAsync(readZipEntry(GEONAMES_CA, "CA.txt"), { header: false })) {
+		if (columns[6] !== "P" || columns[8] !== "CA" || columns[10] !== admin1) continue
+
+		if (Number(columns[14]) <= CA_LOCALITY_MIN_POPULATION) continue
+
+		const name = columns[1] ?? ""
+
+		if (cleanLocality(name)) {
+			localities.add(name)
+		}
+	}
+
+	return [...localities]
 }
 
 /**
@@ -389,25 +358,22 @@ function readCaLocalities(admin1: string): string[] {
  * validated against the codex 4-digit shape — a dump row that fails the contract is skipped, not emitted as a junk
  * label.
  */
-function readPostalTuples(
+async function readPostalTuples(
 	source: { zip: string; txt: string },
 	opts: { withState: boolean }
-): Array<AuTuple | NzTuple> {
-	const r = spawnSync("unzip", ["-p", source.zip, source.txt], { maxBuffer: 1024 * 1024 * 64, encoding: "utf8" })
-
-	if (r.status !== 0) {
-		console.error(`  WARN: unzip failed for ${source.zip} (status ${r.status})`)
+): Promise<Array<AUTuple | NZTuple>> {
+	if (!existsSync(source.zip)) {
+		console.error(`  WARN: ${source.zip} is not cached — skipping ${source.txt}`)
 
 		return []
 	}
 
-	const tuples: Array<AuTuple | NzTuple> = []
+	const tuples: Array<AUTuple | NZTuple> = []
 	const seen = new Set<string>()
-	const validPostcode = opts.withState ? isAuPostcode : isNzPostcode
+	const validPostcode = opts.withState ? isAuPostcode : isNZPostcode
 
-	for (const line of r.stdout.split("\n")) {
-		if (!line) continue
-		const cols = line.split("\t")
+	// A GeoNames dump carries no header row, so every line is data.
+	for await (const cols of TSVSpliterator.fromAsync(readZipEntry(source.zip, source.txt), { header: false })) {
 		const postcode = (cols[1] ?? "").trim()
 		const locality = (cols[2] ?? "").trim()
 		const region = (cols[4] ?? "").trim()
@@ -514,7 +480,7 @@ function makeCedex(random: () => number): string {
 /**
  * Compose an AU or NZ delivery-service phrase from the codex-sourced leaders. Same contract as makePoBoxPhrase: a
  * phrase built from a codex-known designator and a clean id must round-trip the codex matcher (isAuDeliveryService /
- * isNzDeliveryService) — a failure is a generation bug, loud. Noisy ids (commas / embedded spaces) are corpus-designed
+ * isNZDeliveryService) — a failure is a generation bug, loud. Noisy ids (commas / embedded spaces) are corpus-designed
  * adversarial forms, exempt.
  */
 function makeAuNzPoBoxPhrase(
@@ -532,14 +498,14 @@ function makeAuNzPoBoxPhrase(
 	let num = maybeNoisifyBoxNumber(pickBoxNumber(random), random)
 
 	// NZ CMB identifiers are alpha-led per the ADV358 example ("CMB B99").
-	if (leader === "CMB" && validate === isNzDeliveryService) {
+	if (leader === "CMB" && validate === isNZDeliveryService) {
 		num = `B${num}`
 	}
 
 	const phrase = `${caseDial(random, leader)} ${num}`
 	// The "clean id" shape differs per system: ADV358 identifiers carry no separators at all, the AU
 	// AMAS id (like the US one) tolerates dashes. Noisy ids outside the clean shape are exempt.
-	const cleanID = validate === isNzDeliveryService ? /^[\dA-Za-z]+$/ : /^[\dA-Za-z][\dA-Za-z-]*$/
+	const cleanID = validate === isNZDeliveryService ? /^[\dA-Za-z]+$/ : /^[\dA-Za-z][\dA-Za-z-]*$/
 
 	if (cleanID.test(num) && !validate(phrase)) {
 		throw new Error(`generated a phrase the codex matcher rejects: "${phrase}"`)
@@ -614,7 +580,7 @@ function renderPmbUs(random: () => number, t: USTuple): Rendered {
 	return { fmt: "pmb-bare", raw: `${road} ${phrase}`, components: { house_number: hn, street, po_box: phrase } }
 }
 
-function renderBpFr(random: () => number, t: FrTuple): Rendered {
+function renderBpFr(random: () => number, t: FRTuple): Rendered {
 	const phrase = makePoBoxPhrase(random, FR_LEADERS)
 	const { locality, postcode: pc } = t
 	const upper = random() < 0.5
@@ -651,7 +617,7 @@ function renderBpFr(random: () => number, t: FrTuple): Rendered {
 	}
 }
 
-function renderCedexFr(random: () => number, t: FrTuple): Rendered {
+function renderCedexFr(random: () => number, t: FRTuple): Rendered {
 	const cedex = makeCedex(random)
 	const { house_number: hn, street, locality, postcode: pc } = t
 	const loc = random() < 0.6 ? locality.toUpperCase() : locality
@@ -703,7 +669,7 @@ function renderCaEn(random: () => number, loc: string): Rendered {
 	return { fmt: "ca-en-bare", raw: phrase, components: { po_box: phrase } }
 }
 
-function renderAuPoBox(random: () => number, t: AuTuple): Rendered {
+function renderAUPoBox(random: () => number, t: AUTuple): Rendered {
 	const phrase = makeAuNzPoBoxPhrase(random, AU_LEADERS_CURRENT, AU_LEADERS_LEGACY, isAuDeliveryService)
 	const { locality, region: reg, postcode: pc } = t
 	const r = random()
@@ -737,8 +703,8 @@ function renderAuPoBox(random: () => number, t: AuTuple): Rendered {
 	return { fmt: "au-venue", raw: `${v}, ${phrase}, ${loc} ${reg} ${pc}`, components: { venue: v, ...base } }
 }
 
-function renderNzPoBox(random: () => number, t: NzTuple): Rendered {
-	const phrase = makeAuNzPoBoxPhrase(random, NZ_LEADERS_COMMON, NZ_LEADERS_RARE, isNzDeliveryService)
+function renderNZPoBox(random: () => number, t: NZTuple): Rendered {
+	const phrase = makeAuNzPoBoxPhrase(random, NZ_LEADERS_COMMON, NZ_LEADERS_RARE, isNZDeliveryService)
 	const { locality, postcode: pc } = t
 	// NZ addresses are written mixed-case ("PO Box 4099, Timaru 7942") — no region line (ADV358).
 	const base = { po_box: phrase, locality, postcode: pc }
@@ -795,7 +761,7 @@ export const poBoxCedexRecipe: ShardRecipe = {
 		const usPool: USTuple[] = []
 
 		for (const s of opts.golden ? [US_EVAL_SOURCE] : US_TRAIN_SOURCES) {
-			const t = readUsTuples(s)
+			const t = await readUsTuples(s)
 
 			console.error(`  ${s.csv}: ${t.length} tuples`)
 
@@ -805,21 +771,21 @@ export const poBoxCedexRecipe: ShardRecipe = {
 		}
 
 		// FR + CA pools: stable locality-hash holdout (golden gets hash%10==0, train the rest).
-		const frAll = readFrTuples(80_000)
+		const frAll = await readFrTuples(80_000)
 		const frPool = frAll.filter((t) => isHoldoutLocality(t.locality) === opts.golden)
 
 		console.error(`  ${FR_SOURCE.csv}: ${frAll.length} tuples (${frPool.length} after holdout split)`)
 
-		const qcAll = readCaLocalities("10")
-		const onAll = readCaLocalities("08")
+		const qcAll = await readCaLocalities("10")
+		const onAll = await readCaLocalities("08")
 		const qcPool = qcAll.filter((l) => isHoldoutLocality(l) === opts.golden)
 		const onPool = onAll.filter((l) => isHoldoutLocality(l) === opts.golden)
 
 		console.error(`  GeoNames CA: QC ${qcAll.length}→${qcPool.length}, ON ${onAll.length}→${onPool.length}`)
 
 		// AU/NZ pools: same stable locality-hash holdout as FR/CA.
-		const auAll = readPostalTuples(GEONAMES_POSTAL_AU, { withState: true }) as AuTuple[]
-		const nzAll = readPostalTuples(GEONAMES_POSTAL_NZ, { withState: false }) as NzTuple[]
+		const auAll = (await readPostalTuples(GEONAMES_POSTAL_AU, { withState: true })) as AUTuple[]
+		const nzAll = (await readPostalTuples(GEONAMES_POSTAL_NZ, { withState: false })) as NZTuple[]
 		const auPool = auAll.filter((t) => isHoldoutLocality(t.locality) === opts.golden)
 		const nzPool = nzAll.filter((t) => isHoldoutLocality(t.locality) === opts.golden)
 
@@ -827,7 +793,7 @@ export const poBoxCedexRecipe: ShardRecipe = {
 
 		if (!usPool.length || !frPool.length || !qcPool.length || !onPool.length || !auPool.length || !nzPool.length) {
 			throw new Error(
-				"A base pool is empty — check /tmp/oa-cache and /tmp/geonames-cache (CA.zip, AU-postal.zip, NZ-postal.zip)."
+				`A base pool is empty — check ${dataRootPath("oa-cache")}, ${GEONAMES_CA}, ${GEONAMES_POSTAL_AU.zip}, and ${GEONAMES_POSTAL_NZ.zip}.`
 			)
 		}
 
@@ -877,11 +843,11 @@ export const poBoxCedexRecipe: ShardRecipe = {
 				country = "CA"
 				locale = "fr-CA"
 			} else if (cls === "po-box-au") {
-				rendered = renderAuPoBox(random, pick(random, auPool))
+				rendered = renderAUPoBox(random, pick(random, auPool))
 				country = "AU"
 				locale = "en-AU"
 			} else if (cls === "po-box-nz") {
-				rendered = renderNzPoBox(random, pick(random, nzPool))
+				rendered = renderNZPoBox(random, pick(random, nzPool))
 				country = "NZ"
 				locale = "en-NZ"
 			} else if (cls === "po-box-us-military") {

package/src/shard-recipes/po-box.ts

@@ -9,7 +9,12 @@
  *   scripts/build-po-box-shard.mjs.
  */
 
-import { synthesizeMilitaryPoBoxRow, synthesizePoBoxRow, type PoBoxBaseTuple } from "../synthesize-po-box.ts"
+import {
+	synthesizeMilitaryPoBoxRow,
+	synthesizePoBoxRow,
+	type PoBoxBaseTuple,
+} from "@mailwoman/corpus/synthesizers/po-box"
+
 import { alignAndWrite, makeLcg, readTuples, shardSourceID, type ShardRecipe } from "./scaffold.ts"
 
 const LICENSE = "Synthetic — derived from CC-BY / public-domain input tuples"