@mailwoman/corpus 9.0.0 → 9.2.0

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

@@ -30,24 +30,33 @@
  *   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 { isPOBox } from "@mailwoman/codex/us"
+import { readZipEntry } from "@mailwoman/core/fs/zip"
 import { dataRootPath } from "@mailwoman/core/utils"
-import { TextSpliterator } from "spliterator"
+import { TextSpliterator, TSVSpliterator } from "spliterator"
 
-import { alignRow } from "../align.ts"
 import {
 	maybeNoisifyBoxNumber,
 	PO_BOX_LOCALE_TEMPLATES,
 	synthesizeMilitaryPoBoxRow,
 	type LocaleTemplate,
-} from "../synthesize-po-box.ts"
-import { makeMulberry32, readCSVRecords, shardSourceID, type CanonicalShardRow, type ShardRecipe } from "./scaffold.ts"
+} from "#synthesizers/po-box"
+import { alignRow } from "#utils"
+
+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
@@ -233,19 +242,11 @@ 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 []
-	}
-
+async function readUsTuples(source: { zip: string; csv: string; region: string }): Promise<USTuple[]> {
 	const tuples: USTuple[] = []
 	const seen = new Set<string>()
 
-	for (const row of readCSVRecords(r.stdout)) {
+	for await (const row of readZippedCSVRecords(source.zip, source.csv)) {
 		const locality = row.city ?? ""
 
 		if (!cleanLocality(locality)) continue
@@ -265,31 +266,47 @@ function readUsTuples(source: { zip: string; csv: string; region: string }): UST
 	return tuples
 }
 
+/**
+ * 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.
+ */
+const FR_STRIDE = 211
+const FR_STRIDE_OFFSET = 3
+
+/**
+ * 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 awk and can be
- * cut in half by the stride. That is a sampling artefact of the awk pre-filter, not of the parse: whichever lines
- * survive are re-assembled into records by {@link readCSVRecords}, and a halved record fails the field checks below.
+ * 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.
  */
-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" }
-	)
-
-	if (r.status !== 0 && !r.stdout.length) {
-		console.error(`  WARN: unzip failed for ${FR_SOURCE.zip}`)
+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 encoder = new TextEncoder()
+
+	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 tuples: FRTuple[] = []
 	const seen = new Set<string>()
 
-	for (const row of readCSVRecords(r.stdout)) {
+	for await (const row of readCSVRecords(strided)) {
 		const locality = row.city ?? "",
 			postcode = row.postcode ?? "",
 			street = row.street ?? "",
@@ -310,23 +327,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([...TextSpliterator.from(r.stdout)].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]
 }
 
 /**
@@ -336,14 +359,12 @@ 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 []
 	}
@@ -352,11 +373,8 @@ function readPostalTuples(
 	const seen = new Set<string>()
 	const validPostcode = opts.withState ? isAuPostcode : isNZPostcode
 
-	for (const line of TextSpliterator.from(r.stdout)) {
-		if (!line) continue
-
-		// oxlint-disable-next-line mailwoman/prefer-spliterator -- One row already streamed off the line above.
-		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()
@@ -744,7 +762,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`)
 
@@ -754,21 +772,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)
 

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

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

package/src/shard-recipes/reviewed-postcode-tail.ts

@@ -0,0 +1,189 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   A bounded, reviewed source for Venezuela's `locality postcode, region` convention (#1821).
+ *   Bulk sources yielded zero Venezuelan tuples, so this recipe reads four reviewed facts and applies
+ *   only transformations that do not create another postcode-to-place join.
+ */
+
+import { readFileSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+
+import { parseJSONStrict } from "@mailwoman/core/objects"
+
+import { alignAndWrite, type ShardRecipe, shardSourceID } from "./scaffold.ts"
+
+/**
+ * A separate sampler bucket so a receipt measures these reviewed after-locality rows and no other postcode placement.
+ */
+export const REVIEWED_POSTCODE_TAIL_SOURCE = "synth-reviewed-postcode-tail"
+
+/**
+ * The four postcode-to-place facts reviewed for #1821 and committed in the package data file.
+ */
+const REVIEWED_TUPLE_COUNT = 4
+
+interface ReviewedTupleProvenance {
+	publisher: string
+	url: string
+	retrievedAt: string
+	reviewStatus: "reviewed"
+	sourceLicenseNote: string
+}
+
+export interface ReviewedPostcodeTuple {
+	id: string
+	locality: string
+	postcode: string
+	region: string
+	country: "Venezuela"
+	cc: "VE"
+	locale: "es-VE"
+	postcodePlacement: "after_locality"
+	provenance: ReviewedTupleProvenance
+}
+
+interface ReviewedPostcodeTupleFile {
+	version: string
+	reviewedAt: string
+	tuples: ReviewedPostcodeTuple[]
+}
+
+type VariantID =
+	| "canonical-country"
+	| "canonical-no-country"
+	| "comma-free"
+	| "uppercase"
+	| "left-context"
+	| "accent-folded"
+
+interface Variant {
+	id: VariantID
+	raw: string
+	components: Record<string, string>
+}
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/
+
+export function defaultReviewedPostcodeTuplePath(): string {
+	return fileURLToPath(import.meta.resolve("@mailwoman/corpus/data/reviewed-ve-postcode-tuples.json"))
+}
+
+export function readReviewedPostcodeTuples(path = defaultReviewedPostcodeTuplePath()): ReviewedPostcodeTuple[] {
+	const document = parseJSONStrict<ReviewedPostcodeTupleFile>(readFileSync(path, "utf8"))
+
+	if (!document.version || !ISO_DATE.test(document.reviewedAt) || document.tuples.length !== REVIEWED_TUPLE_COUNT) {
+		throw new Error("reviewed postcode tuple file must declare a version, review date, and exactly four tuples")
+	}
+
+	const ids = new Set<string>()
+	const facts = new Set<string>()
+
+	for (const tuple of document.tuples) {
+		const provenance = tuple.provenance
+		const fact = `${tuple.locality}\u0000${tuple.postcode}\u0000${tuple.region}`
+
+		if (
+			!tuple.id ||
+			!tuple.locality ||
+			!tuple.postcode ||
+			!tuple.region ||
+			tuple.country !== "Venezuela" ||
+			tuple.cc !== "VE" ||
+			tuple.locale !== "es-VE" ||
+			tuple.postcodePlacement !== "after_locality" ||
+			!provenance?.publisher ||
+			!URL.canParse(provenance.url) ||
+			!ISO_DATE.test(provenance.retrievedAt) ||
+			provenance.reviewStatus !== "reviewed" ||
+			!provenance.sourceLicenseNote
+		) {
+			throw new Error(`invalid reviewed postcode tuple: ${tuple.id || "<missing id>"}`)
+		}
+
+		if (ids.has(tuple.id) || facts.has(fact)) throw new Error(`duplicate reviewed postcode tuple: ${tuple.id}`)
+		ids.add(tuple.id)
+		facts.add(fact)
+	}
+
+	return document.tuples
+}
+
+const foldAccents = (value: string): string => value.normalize("NFD").replaceAll(/\p{M}/gu, "").normalize("NFC")
+
+export function reviewedPostcodeTailVariants(tuple: ReviewedPostcodeTuple): Variant[] {
+	const tail = `${tuple.locality} ${tuple.postcode}, ${tuple.region}`
+	const withCountry = `${tail}, ${tuple.country}`
+	const base = { locality: tuple.locality, postcode: tuple.postcode, region: tuple.region, country: tuple.country }
+	const upper = Object.fromEntries(Object.entries(base).map(([key, value]) => [key, value.toUpperCase()]))
+
+	const variants: Variant[] = [
+		{ id: "canonical-country", raw: withCountry, components: base },
+		{
+			id: "canonical-no-country",
+			raw: tail,
+			components: { locality: tuple.locality, postcode: tuple.postcode, region: tuple.region },
+		},
+		{ id: "comma-free", raw: `${tuple.locality} ${tuple.postcode} ${tuple.region} ${tuple.country}`, components: base },
+		{ id: "uppercase", raw: withCountry.toUpperCase(), components: upper },
+		{
+			id: "left-context",
+			raw: `Comercio Ejemplo, Calle Principal, ${withCountry}`,
+			components: { venue: "Comercio Ejemplo", street: "Calle Principal", ...base },
+		},
+	]
+
+	const foldedLocality = foldAccents(tuple.locality)
+	const foldedRegion = foldAccents(tuple.region)
+
+	if (foldedLocality !== tuple.locality || foldedRegion !== tuple.region) {
+		variants.push({
+			id: "accent-folded",
+			raw: `${foldedLocality} ${tuple.postcode}, ${foldedRegion}, ${tuple.country}`,
+			components: { locality: foldedLocality, postcode: tuple.postcode, region: foldedRegion, country: tuple.country },
+		})
+	}
+
+	return variants
+}
+
+/**
+ * Emit bounded surface variants of the committed reviewed facts without constructing another geographic join.
+ */
+export const reviewedPostcodeTailRecipe: ShardRecipe = {
+	name: "reviewed-postcode-tail",
+	description: "Reviewed Venezuela locality-postcode-region tails with bounded surface variants",
+	mode: "generate",
+	async run(opts, write) {
+		const tuples = readReviewedPostcodeTuples(opts.input)
+		let emitted = 0
+		let skipped = 0
+
+		for (const tuple of tuples) {
+			for (const variant of reviewedPostcodeTailVariants(tuple)) {
+				const sourceID = shardSourceID(REVIEWED_POSTCODE_TAIL_SOURCE, { tuple: tuple.id, variant: variant.id })
+
+				const canonical = {
+					raw: variant.raw,
+					components: variant.components,
+					country: tuple.cc,
+					locale: tuple.locale,
+					source: REVIEWED_POSTCODE_TAIL_SOURCE,
+					source_id: sourceID,
+					corpus_version: "0.11.0",
+					license: `Synthetic rendering of reviewed postal facts — ${tuple.provenance.publisher}; source terms recorded in reviewed-ve-postcode-tuples.json`,
+				}
+
+				if (alignAndWrite(write, canonical, "reviewed-postcode-tail", tuple.id)) {
+					emitted++
+				} else {
+					skipped++
+				}
+			}
+		}
+
+		return { read: tuples.length, emitted, skipped }
+	},
+}

package/src/shard-recipes/scaffold.ts

@@ -9,29 +9,64 @@
  *   only its synthesis + filter; the `mailwoman corpus shard <recipe>` command supplies the I/O.
  */
 
+import { existsSync } from "node:fs"
+
+import { readZipEntry } from "@mailwoman/core/fs/zip"
 import { tryParsingJSON } from "@mailwoman/core/objects"
-import { CSVSpliterator } from "spliterator"
+import type { PathBuilderLike } from "path-ts"
+import type { AsyncChunkIterator, AsyncDataResource } from "spliterator"
+import { AsyncSequence, CSVSpliterator } from "spliterator"
 
-import { stableSourceID } from "../adapter.ts"
-import { alignRow } from "../align.ts"
+import { stableSourceIDFromParts } from "#adapters/utils"
+import { alignRow } from "#utils"
 
 /**
- * {@link stableSourceID}, but accepting arbitrary disambiguator keys (e.g. a variant index `v`) that aren't
- * `ComponentTag`s. `stableSourceID` sorts + hashes EVERY key it's given, so passing extra keys is how the legacy
- * builders kept per-variant ids unique — the strict typing is just too narrow for that. Centralizes the one cast.
+ * {@link stableSourceIDFromParts} under the name the recipes use: arbitrary disambiguator keys (e.g. a variant index
+ * `v`) that aren't `ComponentTag`s, which is how the legacy builders kept per-variant ids unique.
  */
 export function shardSourceID(adapterID: string, parts: Record<string, string | undefined>): string {
-	return stableSourceID(adapterID, parts as unknown as Parameters<typeof stableSourceID>[1])
+	return stableSourceIDFromParts(adapterID, parts)
 }
 
+/**
+ * Where a country's convention writes the postcode inside the `«locality», «region»[, «country»]` admin tail.
+ *
+ * Load-bearing rather than cosmetic: the same digits change TAG with position. Measured on the shipped model,
+ * `Heladería Frappé Manía, Avenida Country Club, Barcelona 6001, Anzoátegui, Venezuela` tags `6001` as `house_number`
+ * and loses the locality into the street, while the identical row written `… 6001 Barcelona, Anzoátegui, Venezuela`
+ * tags it `postcode` and recovers `locality: Barcelona`. So a shard emitting one placement teaches one family of
+ * countries.
+ *
+ * Each is attested by a gauntlet board row, which is the bar for adding another:
+ *
+ * - `leading` — `«postcode» «locality», «region»`. `Rua da Praia, 15, 8600-315 Lagos, Algarve, Portugal`
+ *   (`pt_structured`). The default, and what every tuple written before this field existed means.
+ * - `after_locality` — `«locality» «postcode», «region»`. `…, Barcelona 6001, Anzoátegui, Venezuela`
+ *   (`ve_city_postcode_trailing_state`).
+ * - `after_region` — `«locality», «region» «postcode»`. `12 MG Road, Indiranagar, Bengaluru, Karnataka 560038, India`
+ *   (`in_structured`).
+ */
+export type PostcodePlacement = "leading" | "after_locality" | "after_region"
+
 /**
  * A (locality, region, postcode, country) source tuple — the input to tuples-mode recipes.
  */
 export interface ShardTuple {
 	locality?: string
+	/**
+	 * The segment before the locality, when the source has one. A shard whose every row BEGINS with the locality teaches
+	 * that the first named segment is the locality, which flips the model's default — measured on the v4.8.0 candidate,
+	 * where `Ye Three Lords, 27 Minories, London EC3N 1DE` came back `locality: "Ye Three Lords"`.
+	 */
+	dependentLocality?: string
 	region?: string
 	postcode?: string
 	country?: string
+	/**
+	 * Defaults to `leading` when absent, which is what every tuple file written before this field existed means — so an
+	 * old tuples file produces byte-identical rows.
+	 */
+	postcodePlacement?: PostcodePlacement
 	[k: string]: unknown
 }
 
@@ -55,17 +90,26 @@ export { makeLcg, mulberry32 as makeMulberry32, makeLcg as makeRandom } from "@m
 export type CSVRecord = Record<string, string | undefined>
 
 /**
- * Read an in-memory CSV (an `unzip -p` buffer, say) as header-keyed records.
- *
  * Quote handling spans the ROW split, not only the column split: a newline inside a quoted field belongs to a single
  * record, so the record boundaries can only be found by a scanner that already knows where the quotes are. Find the
  * lines first and unquote afterwards and such a record splits in two — the first half short by however many columns
  * followed the newline, which is how a `street` value comes to be read as `city`.
  *
+ * `header: false` keeps the first record in the stream, so this module owns the lower-casing rather than
+ * `normalizeKeys` — see {@link toHeader}.
+ */
+const CSV_INIT = { header: false, enableQuoteHandling: true } as const
+
+/**
  * Header names are lower-cased on the way in. `normalizeKeys` will not do it: it leaves an ALL CAPS header alone, and
  * OpenAddresses ships `LON,LAT,NUMBER,STREET` while other extracts ship the same names lower-case. A recipe names its
  * columns in lower case either way.
- *
+ */
+function toHeader(cells: readonly string[]): string[] {
+	return cells.map((name) => name.trim().toLowerCase())
+}
+
+/**
  * Line breaks inside a value become single spaces. A quote-aware parse is the first thing here able to return a value
  * CONTAINING one — `us/ia/statewide.csv` has 12, all unit designators like `"#2\n#2"` — and every consumer synthesizes
  * one-line address text from these cells with no guard, because until that parse landed no value could carry one.
@@ -75,27 +119,58 @@ export type CSVRecord = Record<string, string | undefined>
  * Only `\r` and `\n`, deliberately — NOT `\s`. Runs of spaces and tabs pass through exactly as the source wrote them
  * (OA's IA extract writes `NORTH`, three spaces, `MAIN STREET`), because those could always appear and every shard
  * built to date contains them. Widening this to `\s+` silently rewrites values on rows with no line break at all.
- * `scaffold.test.ts` pins both halves.
+ * `scaffold.test.ts` pins both halves, against both readers.
+ */
+function toRecord(header: readonly string[], cells: readonly string[]): CSVRecord {
+	const record: CSVRecord = {}
+
+	for (let i = 0; i < header.length; i++) {
+		record[header[i]!] = (cells[i] ?? "").replaceAll(/[\r\n]+/g, " ").trim()
+	}
+
+	return record
+}
+
+/**
+ * Read a CSV as header-keyed records.
+ *
+ * Returns the spliterator's own {@linkcode AsyncSequence}, so a caller composes `take`/`drop`/`filter` onto it — those
+ * ops fuse into one pull loop, and a `take` that is satisfied closes the source's file handle on the way out. Wrapping
+ * this in an `async function*` costs an async frame per row and takes those ops away; don't.
+ *
+ * A source at or below the spliterator's 128 KiB bulk threshold is read whole and parsed by the synchronous engine, so
+ * this is also the right reader for small sources — there is no buffered variant to reach for.
  */
-export function* readCSVRecords(source: Uint8Array): Generator<CSVRecord> {
+export function readCSVRecords(source: AsyncDataResource | AsyncChunkIterator): AsyncSequence<CSVRecord> {
 	let header: string[] | null = null
 
-	// `header: false` keeps the first record in the stream so this reader owns the lower-casing.
-	for (const cells of CSVSpliterator.from(source, { header: false, enableQuoteHandling: true })) {
-		if (!header) {
-			header = cells.map((name) => name.trim().toLowerCase())
+	return CSVSpliterator.fromAsync<string[]>(source, CSV_INIT)
+		.filter((cells) => {
+			if (header) return true
 
-			continue
-		}
+			header = toHeader(cells)
 
-		const record: CSVRecord = {}
+			return false
+		})
+		.map((cells) => toRecord(header!, cells))
+}
 
-		for (let i = 0; i < header.length; i++) {
-			record[header[i]!] = (cells[i] ?? "").replaceAll(/[\r\n]+/g, " ").trim()
-		}
+/**
+ * {@link readCSVRecords} over one member of a zip archive — what every recipe reading a cached OA source wants.
+ *
+ * A source a checkout has not cached yields nothing, after saying so. A lab holds the archives for the countries it has
+ * built, so a recipe naming ten sources routinely finds three, and the `unzip -p` subprocesses these replaced behaved
+ * the same way by accident — a non-zero exit warned and returned no rows. A recipe that ends up with NO tuples at all
+ * still throws; that is the case where the cache, not the recipe, is the problem.
+ */
+export function readZippedCSVRecords(archivePath: PathBuilderLike, entryName: string): AsyncSequence<CSVRecord> {
+	if (!existsSync(String(archivePath))) {
+		console.error(`  WARN: ${archivePath} is not cached — skipping ${entryName}`)
 
-		yield record
+		return AsyncSequence.from<CSVRecord>([])
 	}
+
+	return readCSVRecords(readZipEntry(archivePath, entryName))
 }
 
 /**
@@ -222,7 +297,7 @@ export interface ShardRecipeOpts {
 	 * `sub-venue`: the `poi.db` spatial layer, read for the en-US and fr-FR venue + confound pools (the two of poi.db's
 	 * four countries this shard has legs for). Default `$MAILWOMAN_DATA_ROOT/poi/poi.db`.
 	 */
-	poiDb?: string
+	poiDB?: string
 	/**
 	 * `sub-venue`: GB/US/FR address-context tuples JSONL. Default the house-venue v3 tuples
 	 * (`$MAILWOMAN_DATA_ROOT/corpus/intermediate/house-venue-tuples-v3.jsonl`); DE and ES read OpenAddresses directly.