@mailwoman/corpus 9.0.0 → 9.2.0

package/src/tools/fetch/nppes.ts

@@ -24,20 +24,17 @@
 /* oxlint-disable sister-software/prefer-region-over-marks -- these markers label steps inside one
    procedure, not sections of declarations. A region there folds nothing a reader wants folded. */
 
-import { execFile } from "node:child_process"
 import { existsSync, mkdirSync, statSync } from "node:fs"
 import { rm } from "node:fs/promises"
-import { join } from "node:path"
-import { promisify } from "node:util"
+import { basename, join } from "node:path"
 
+import { APIClient, pluckResponseData } from "@mailwoman/core/api"
+import { extractZipEntry, listZipEntries } from "@mailwoman/core/fs/zip"
 import { sha256File } from "@mailwoman/core/utils"
-import { TextSpliterator } from "spliterator"
 
 import type { BaseFetchOptions, FetchSummary } from "./download.ts"
 import { downloadToFile, readManifest, writeManifest } from "./download.ts"
 
-const execFileAsync = promisify(execFile)
-
 const INDEX_URL = "https://download.cms.gov/nppes/NPI_Files.html"
 const BASE_URL = "https://download.cms.gov/nppes"
 const SLUG = "usgov-nppes"
@@ -57,13 +54,14 @@ interface SourceManifest {
  * `NPPES_Data_Dissemination_<Month>_<Year>*.zip`; weekly files carry a `MMDDYY_MMDDYY` date range, which we exclude.
  */
 async function discoverLatestZip(): Promise<string | undefined> {
-	const res = await fetch(INDEX_URL, {
-		headers: { "Accept-Encoding": "gzip, br" },
-		signal: AbortSignal.timeout(60_000),
+	// `responseType: "text"` — the index is HTML, scraped by regex below.
+	const html = await new APIClient({
+		displayName: "nppes-index",
+		retry: true,
+		axios: { headers: { "Accept-Encoding": "gzip, br" } },
 	})
-
-	if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText} on ${INDEX_URL}`)
-	const html = await res.text()
+		.fetch<string>({ url: INDEX_URL, responseType: "text", timeout: 60_000 })
+		.then(pluckResponseData)
 
 	for (const match of html.matchAll(/NPPES_Data_Dissemination_[A-Za-z]+_\d{4}[^"]*\.zip/g)) {
 		const name = match[0]
@@ -75,18 +73,13 @@ async function discoverLatestZip(): Promise<string | undefined> {
 }
 
 /**
- * Extract the main registry CSV name (npidata_pfile_*.csv) from a ZIP's `unzip -l` listing.
+ * The main registry CSV (npidata_pfile_*.csv), which the archive also carries alongside a header file and a per-month
+ * change file.
  */
 async function findNpidataCSV(zipPath: string): Promise<string | undefined> {
-	const listing = await execFileAsync("unzip", ["-l", zipPath])
-
-	for (const line of TextSpliterator.from(listing.stdout)) {
-		const match = /npidata_pfile\S+\.csv/i.exec(line)
+	const entries = await listZipEntries(zipPath)
 
-		if (match?.[0]) return match[0]
-	}
-
-	return undefined
+	return entries.find((entry) => /npidata_pfile\S+\.csv/i.test(entry.name))?.name
 }
 
 export async function fetchNPPES(options: FetchNPPESOptions, report?: (line: string) => void): Promise<FetchSummary> {
@@ -149,9 +142,10 @@ export async function fetchNPPES(options: FetchNPPESOptions, report?: (line: str
 	}
 
 	report?.(`  Extracting: ${csvName}`)
-	await execFileAsync("unzip", ["-o", "-j", zipDest, csvName, "-d", destDir])
 
-	const csvDest = join(destDir, csvName)
+	const csvDest = join(destDir, basename(csvName))
+
+	await extractZipEntry(zipDest, csvName, csvDest)
 	const csvSize = statSync(csvDest).size
 	const csvSha = await sha256File(csvDest)
 	report?.(`  CSV size: ${(csvSize / 1024 / 1024).toFixed(1)} MB`)

package/src/tools/fetch/openaddresses.ts

@@ -62,7 +62,9 @@ import { pipeline } from "node:stream/promises"
 import { setTimeout as sleep } from "node:timers/promises"
 import { promisify } from "node:util"
 
+import { APIClient, isSuccessStatus } from "@mailwoman/core/api"
 import { $private } from "@mailwoman/core/env"
+import { ByteFormatter } from "@mailwoman/core/fs/utils"
 import { sha256File } from "@mailwoman/core/utils"
 
 import type { BaseFetchOptions, FetchSummary } from "./download.ts"
@@ -82,8 +84,6 @@ const HTTP_OK = 200
  */
 const MIN_PLAUSIBLE_SHARD_BYTES = 10_240
 
-const BYTES_PER_KIB = 1024
-
 const execFileAsync = promisify(execFile)
 
 const OA_BASE = "https://batch.openaddresses.io"
@@ -132,20 +132,6 @@ async function countLines(path: string): Promise<number> {
 	return count
 }
 
-function humanBytes(bytes: number): string {
-	const units = ["B", "KiB", "MiB", "GiB", "TiB"]
-	let value = bytes
-	let unit = 0
-
-	while (value >= BYTES_PER_KIB && unit < units.length - 1) {
-		value /= 1024
-
-		unit++
-	}
-
-	return `${value.toFixed(unit === 0 ? 0 : 1)}${units[unit]}`
-}
-
 interface StreamDownloadOpts {
 	headers?: Record<string, string>
 	timeoutMs: number
@@ -263,18 +249,28 @@ The Canada collection (ca) is ~2 GiB compressed / ~7 GiB uncompressed
 	if (collectionID === undefined) {
 		report?.(`Unknown country code '${country}'. Fetching collection list to find ID...`)
 
-		const res = await fetch(`${OA_BASE}/api/collections`, {
-			headers: { Authorization: `Bearer ${token}`, "Accept-Encoding": "gzip, br" },
-			signal: AbortSignal.timeout(30_000),
+		// The collections API only. The COLLECTION ARCHIVES stay on raw `fetch` — they stream multi-gigabyte
+		// bodies straight to disk, where response caching is nonsense and axios would buffer them in memory.
+		const res = await new APIClient({
+			displayName: "openaddresses-api",
+			retry: true,
+			axios: { headers: { Authorization: `Bearer ${token}`, "Accept-Encoding": "gzip, br" } },
 		})
+			// `validateStatus` keeps a non-2xx as a RESPONSE rather than a throw: the caller reports the status and
+			// returns `fail(country)`, a graceful path this must not turn into an exception.
+			.fetch<OaCollection[]>({
+				url: `${OA_BASE}/api/collections`,
+				timeout: 30_000,
+				validateStatus: () => true,
+			})
 
-		if (!res.ok) {
+		if (!isSuccessStatus(res.status)) {
 			report?.(`ERROR: GET /api/collections returned HTTP ${res.status}.`)
 
 			return fail(country)
 		}
 
-		const collections = (await res.json()) as OaCollection[]
+		const collections = res.data
 		const match = collections.find((item) => item.name === country)
 
 		if (match?.id === undefined) {
@@ -395,7 +391,7 @@ URL tried: ${OA_BASE}/api/collections/${collectionID}/download
 
 	await writeManifest(manifestPath, manifest)
 
-	report?.(`  ✓ ${humanBytes(size)}  rows=${rowCount}  sha256=${sha}`)
+	report?.(`  ✓ ${ByteFormatter.formatIEC(size)}  rows=${rowCount}  sha256=${sha}`)
 	report?.(`  MANIFEST written to ${manifestPath}`)
 	report?.(`=== done`)
 	report?.(`Feed to the adapter:`)

package/src/tools/fetch/ourairports.ts

@@ -39,6 +39,7 @@
 import { mkdirSync } from "node:fs"
 import { join } from "node:path"
 
+import { APIClient } from "@mailwoman/core/api"
 import { sha256File } from "@mailwoman/core/utils"
 
 import type { BaseFetchOptions, FetchSummary } from "./download.ts"
@@ -92,9 +93,13 @@ interface OurAirportsManifest {
  */
 async function readLastModified(url: string): Promise<string | null> {
 	try {
-		const res = await fetch(url, { method: "HEAD", signal: AbortSignal.timeout(30_000) })
+		const res = await new APIClient({ displayName: "ourairports", retry: true }).fetch({
+			url,
+			method: "head",
+			timeout: 30_000,
+		})
 
-		return res.ok ? res.headers.get("last-modified") : null
+		return (res.headers["last-modified"] as string | undefined) ?? null
 	} catch {
 		return null
 	}

package/src/tools/fetch/ppd.ts

@@ -104,7 +104,7 @@ export async function extractPPDTuples(
 /**
  * Stream `inputPath` (PPD CSV) → `outputPath` (OA-shaped tuples CSV), returning the row-count stats.
  */
-export async function runPPDExtract(inputPath: string, outputPath: string): Promise<PPDExtractStats> {
+async function runPPDExtract(inputPath: string, outputPath: string): Promise<PPDExtractStats> {
 	// No `encoding` — CSVSpliterator delimits raw bytes and decodes utf-8 itself (see readTuples in
 	// shard-recipes/locale.ts). `header: false` yields every row as data — PPD ships no header row.
 	const rows = CSVSpliterator.fromAsync<string[]>(createReadStream(inputPath), {

package/src/tools/fetch/state-hi-schools.ts

@@ -25,6 +25,7 @@ import { existsSync, mkdirSync, statSync } from "node:fs"
 import { unlink } from "node:fs/promises"
 import { join } from "node:path"
 
+import { BYTES_PER_KIB, ByteFormatter } from "@mailwoman/core/fs/utils"
 import { sha256File } from "@mailwoman/core/utils"
 
 import type { BaseFetchOptions, FetchSummary } from "./download.ts"
@@ -34,7 +35,6 @@ import { downloadToFile, readManifest, writeManifest } from "./download.ts"
  * Bytes per KiB — the divisor for human-readable sizes, and the floor below which a "download" is an error page rather
  * than data.
  */
-const BYTES_PER_KIB = 1024
 
 const SOURCE_URL = "https://www.hawaiipublicschools.org/DOE%20Forms/SchoolList.xlsx"
 const SLUG = "state-hi-schools"
@@ -96,26 +96,6 @@ interface Manifest {
 	notes: string
 }
 
-/**
- * Mimic `numfmt --to=iec` for a friendly byte-size log line.
- */
-function iec(bytes: number): string {
-	if (bytes < BYTES_PER_KIB) return String(bytes)
-	const units = ["K", "M", "G", "T", "P"]
-	let value = bytes / 1024
-	let i = 0
-
-	while (value >= BYTES_PER_KIB && i < units.length - 1) {
-		value /= 1024
-
-		i++
-	}
-
-	const rounded = value < 10 ? value.toFixed(1) : Math.round(value).toString()
-
-	return `${rounded}${units[i] ?? ""}`
-}
-
 /**
  * Run the openpyxl converter. Its stderr narration streams straight through to the process stderr (matching the old
  * `stdio: inherit` behavior) rather than routing through `report` — the python child owns those lines.
@@ -190,7 +170,7 @@ export async function fetchStateHISchools(
 	}
 
 	const xlsxSize = statSync(xlsxDest).size
-	report?.(`  Downloaded XLSX: ${iec(xlsxSize)}`)
+	report?.(`  Downloaded XLSX: ${ByteFormatter.formatIEC(xlsxSize)}`)
 
 	if (xlsxSize < BYTES_PER_KIB) {
 		report?.(`  ✗ Response too small (${xlsxSize} bytes) — probable error page`)
@@ -221,7 +201,7 @@ export async function fetchStateHISchools(
 
 	await writeManifest(manifestPath, manifest)
 
-	report?.(`  ✓ ${iec(csvSize)}  sha256=${csvSha}`)
+	report?.(`  ✓ ${ByteFormatter.formatIEC(csvSize)}  sha256=${csvSha}`)
 	report?.(`  MANIFEST written to ${manifestPath}`)
 
 	return { fetched: 1, skipped: 0, failed: 0, failedCodes: [] }

package/src/tools/fetch/state-sources.ts

@@ -20,6 +20,7 @@
 import { mkdirSync } from "node:fs"
 import { join } from "node:path"
 
+import { BYTES_PER_KIB } from "@mailwoman/core/fs/utils"
 import { sha256File } from "@mailwoman/core/utils"
 
 import type { BaseFetchOptions, FetchSummary } from "./download.ts"
@@ -29,7 +30,6 @@ import { downloadToFile, writeManifest } from "./download.ts"
  * Bytes per KiB — the divisor for human-readable sizes, and the floor below which a "download" is an error page rather
  * than data.
  */
-const BYTES_PER_KIB = 1024
 
 export type FetchStateSourcesOptions = BaseFetchOptions
 

package/src/tools/fetch/tiger-full.ts

@@ -28,6 +28,8 @@ import { Readable } from "node:stream"
 import { pipeline } from "node:stream/promises"
 import { setTimeout as sleep } from "node:timers/promises"
 
+import { APIClient, pluckResponseData } from "@mailwoman/core/api"
+import { BYTES_PER_KIB, ByteFormatter } from "@mailwoman/core/fs/utils"
 import { sha256File } from "@mailwoman/core/utils"
 
 import type { BaseFetchOptions, FetchSummary } from "./download.ts"
@@ -47,8 +49,6 @@ const HTTP_OK = 200
  */
 const HTTP_REDIRECT = 300
 
-const BYTES_PER_KIB = 1024
-
 const TIGER_BASE_URL = "https://www2.census.gov/geo/tiger/TIGER2024/ADDRFEAT"
 
 export interface FetchTigerFullOptions extends BaseFetchOptions {
@@ -77,20 +77,6 @@ interface CountyEntry {
 	bytes: number
 }
 
-function humanBytes(bytes: number): string {
-	const units = ["B", "KiB", "MiB", "GiB", "TiB"]
-	let value = bytes
-	let unit = 0
-
-	while (value >= BYTES_PER_KIB && unit < units.length - 1) {
-		value /= 1024
-
-		unit++
-	}
-
-	return `${value.toFixed(unit === 0 ? 0 : 1)}${units[unit]}`
-}
-
 /**
  * Stream an HTTP download to disk, returning the final HTTP status (0 on network error after retries).
  *
@@ -193,7 +179,7 @@ export async function fetchTigerFull(
 	options: FetchTigerFullOptions,
 	report?: (line: string) => void
 ): Promise<FetchSummary> {
-	const skipStateFips = (options.skipStateFips ?? "50").split(/\s+/).filter(Boolean)
+	const skipStateFips = (options.skipStateFips ?? "50").split(/\s+/).filter((value) => value.length > 0)
 	const rateSleepMs = Math.round((options.rateSleep ?? 0.2) * 1000)
 	const maxParallel = options.maxParallel ?? 4
 	const dryRun = options.dryRun ?? false
@@ -205,13 +191,17 @@ export async function fetchTigerFull(
 
 	report?.(`=== Fetching TIGER 2024 ADDRFEAT directory listing...`)
 
-	const listingRes = await fetch(`${TIGER_BASE_URL}/`, {
-		headers: { "Accept-Encoding": "gzip, br" },
-		signal: AbortSignal.timeout(60_000),
+	// `responseType: "text"` — an Apache directory index, scraped below. The per-county ARCHIVE downloads
+	// stay on raw `fetch` (they stream to disk; see `downloadOne`).
+	const listingRes = await new APIClient({
+		displayName: "tiger-listing",
+		retry: true,
+		axios: { headers: { "Accept-Encoding": "gzip, br" } },
 	})
+		.fetch<string>({ url: `${TIGER_BASE_URL}/`, responseType: "text", timeout: 60_000 })
+		.then(pluckResponseData)
 
-	if (!listingRes.ok) throw new Error(`Failed to fetch TIGER directory listing: HTTP ${listingRes.status}`)
-	const html = await listingRes.text()
+	const html = listingRes
 	const allZips = [...new Set(html.match(/tl_2024_[0-9]{5}_addrfeat\.zip/g))].toSorted()
 	const totalCounties = allZips.length
 	report?.(`  Found ${totalCounties} county ZIPs in the TIGER 2024 ADDRFEAT index.`)
@@ -314,7 +304,10 @@ export async function fetchTigerFull(
 		// Collect results from this state.
 		for (const result of results) {
 			if (result.ok) {
-				report?.(`  ok ${result.filename}  ${humanBytes(result.bytes)}  sha256=${result.sha256.slice(0, 12)}...`)
+				report?.(
+					`  ok ${result.filename}  ${ByteFormatter.formatIEC(result.bytes)}  sha256=${result.sha256.slice(0, 12)}...`
+				)
+
 				manifest.set(result.filename, { filename: result.filename, sha256: result.sha256, bytes: result.bytes })
 
 				totalFetched++
@@ -350,7 +343,7 @@ export async function fetchTigerFull(
 	report?.(`  Counties failed           : ${totalFailed}`)
 
 	if (totalBytesFetched > 0) {
-		report?.(`  Bytes fetched this run    : ${humanBytes(totalBytesFetched)} (${totalBytesFetched})`)
+		report?.(`  Bytes fetched this run    : ${ByteFormatter.formatIEC(totalBytesFetched)} (${totalBytesFetched})`)
 	}
 
 	if (totalFailed > 0) {

package/src/tools/golden-expand.ts

@@ -50,8 +50,9 @@ import { mkdir } from "node:fs/promises"
 import { dirname } from "node:path"
 
 import { ParquetReader } from "@dsnp/parquetjs"
+import { APIClient, pluckResponseData } from "@mailwoman/core/api"
 import { $private } from "@mailwoman/core/env"
-import { tryParsingJSON } from "@mailwoman/core/objects"
+import { isPresent, tryParsingJSON } from "@mailwoman/core/objects"
 import { dataRootPath } from "@mailwoman/core/utils"
 import { createNewlineWriter } from "spliterator"
 
@@ -195,7 +196,7 @@ async function loadSeeds(
 	const paths = corpusPath
 		.split(",")
 		.map((p) => p.trim())
-		.filter(Boolean)
+		.filter(isPresent)
 
 	report?.(`reading seeds from ${paths.length} shard(s) (target: ${count}, stratified)`)
 
@@ -345,24 +346,28 @@ function makeDeepseekProvider(model: string): LlmProvider {
 		name: "deepseek",
 		model,
 		async generateVariants(seed, n) {
-			const res = await fetch("https://api.deepseek.com/chat/completions", {
-				method: "POST",
-				headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
-				body: JSON.stringify({
-					model,
-					messages: [
-						{ role: "system", content: SYSTEM_PROMPT },
-						{ role: "user", content: buildUserPrompt(seed, n) },
-					],
-					response_format: { type: "json_object" },
-					max_tokens: 800,
-					temperature: 0.7,
-				}),
-				signal: AbortSignal.timeout(60_000),
+			const data = await new APIClient({
+				displayName: "deepseek",
+				retry: true,
+				axios: { headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" } },
 			})
+				.fetch<{ choices?: Array<{ message: { content: string } }> }>({
+					url: "https://api.deepseek.com/chat/completions",
+					method: "post",
+					timeout: 60_000,
+					data: {
+						model,
+						messages: [
+							{ role: "system", content: SYSTEM_PROMPT },
+							{ role: "user", content: buildUserPrompt(seed, n) },
+						],
+						response_format: { type: "json_object" },
+						max_tokens: 800,
+						temperature: 0.7,
+					},
+				})
+				.then(pluckResponseData)
 
-			if (!res.ok) throw new Error(`DeepSeek HTTP ${res.status}: ${await res.text()}`)
-			const data = (await res.json()) as { choices?: Array<{ message: { content: string } }> }
 			const content = data.choices?.[0]?.message.content ?? "{}"
 
 			return parseCandidates(content)
@@ -379,24 +384,30 @@ function makeAnthropicProvider(model: string): LlmProvider {
 		name: "anthropic",
 		model,
 		async generateVariants(seed, n) {
-			const res = await fetch("https://api.anthropic.com/v1/messages", {
-				method: "POST",
-				headers: {
-					"x-api-key": apiKey,
-					"anthropic-version": "2023-06-01",
-					"Content-Type": "application/json",
+			const data = await new APIClient({
+				displayName: "anthropic",
+				retry: true,
+				axios: {
+					headers: {
+						"x-api-key": apiKey,
+						"anthropic-version": "2023-06-01",
+						"Content-Type": "application/json",
+					},
 				},
-				body: JSON.stringify({
-					model,
-					max_tokens: 800,
-					system: SYSTEM_PROMPT,
-					messages: [{ role: "user", content: buildUserPrompt(seed, n) }],
-				}),
-				signal: AbortSignal.timeout(60_000),
 			})
+				.fetch<{ content?: Array<{ type: string; text: string }> }>({
+					url: "https://api.anthropic.com/v1/messages",
+					method: "post",
+					timeout: 60_000,
+					data: {
+						model,
+						max_tokens: 800,
+						system: SYSTEM_PROMPT,
+						messages: [{ role: "user", content: buildUserPrompt(seed, n) }],
+					},
+				})
+				.then(pluckResponseData)
 
-			if (!res.ok) throw new Error(`Anthropic HTTP ${res.status}: ${await res.text()}`)
-			const data = (await res.json()) as { content?: Array<{ type: string; text: string }> }
 			const text = data.content?.find((c) => c.type === "text")?.text ?? "[]"
 
 			return parseCandidates(text)

package/src/tools/golden-relabel-street.ts

@@ -60,10 +60,12 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from
 import { basename, join } from "node:path"
 
 import { isStreetDirectionalToken, matchTrailingSuffix, type USStreetSuffix } from "@mailwoman/codex/us"
-import { parseJSONStrict, tryParsingJSON } from "@mailwoman/core/objects"
+import { isPresent, parseJSONStrict, tryParsingJSON } from "@mailwoman/core/objects"
 import { sha256File } from "@mailwoman/core/utils"
 import { TextSpliterator } from "spliterator"
 
+import { NAME_PRONE_US_SUFFIXES } from "../name-prone-us-suffixes.ts"
+
 // ── Types ──────────────────────────────────────────────────────────────────
 
 /**
@@ -136,71 +138,6 @@ export interface GoldenRelabelResult {
  * pass 3 — the whole flagged class is 60 rows of 1,906), not from the whole 200-entry table: flagging every possible
  * name-head would mark a third of the corrections and stop being a review artifact.
  */
-const NAME_PRONE_SUFFIXES: ReadonlySet<USStreetSuffix> = new Set<USStreetSuffix>([
-	"BEACH",
-	"BROOK",
-	"BROOKS",
-	"CAMP",
-	"CENTER",
-	"CENTERS",
-	"CLUB",
-	"COMMON",
-	"COMMONS",
-	"CREEK",
-	"CROSSING",
-	"ESTATE",
-	"ESTATES",
-	"FIELD",
-	"FIELDS",
-	"FOREST",
-	"GARDEN",
-	"GARDENS",
-	"GLEN",
-	"GREEN",
-	"GREENS",
-	"GROVE",
-	"GROVES",
-	"HARBOR",
-	"HEIGHTS",
-	"HILL",
-	"HILLS",
-	"HOLLOW",
-	"ISLAND",
-	"ISLANDS",
-	"ISLE",
-	"JUNCTION",
-	"LAKE",
-	"LAKES",
-	"LANDING",
-	"MALL",
-	"MANOR",
-	"MEADOW",
-	"MEADOWS",
-	"MILL",
-	"MILLS",
-	"MISSION",
-	"ORCHARD",
-	"PARK",
-	"PASS",
-	"PLAZA",
-	"POINT",
-	"POINTS",
-	"RANCH",
-	"RIDGE",
-	"SHORE",
-	"SHORES",
-	"SPRING",
-	"SPRINGS",
-	"SQUARE",
-	"STATION",
-	"SUMMIT",
-	"VALLEY",
-	"VIEW",
-	"VIEWS",
-	"VILLAGE",
-	"VISTA",
-])
-
 // ── Byte-exact tail split ──────────────────────────────────────────────────
 
 interface TailSplit {
@@ -381,7 +318,7 @@ export function relabelGoldenStreetRow(
 		throw new Error(`golden-relabel: span reconstruction failed for ${JSON.stringify(street)}`)
 	}
 
-	if (canonical && NAME_PRONE_SUFFIXES.has(canonical)) {
+	if (canonical && NAME_PRONE_US_SUFFIXES.has(canonical)) {
 		flags.push({
 			kind: "name-prone-suffix",
 			detail: `${canonical} heads proper names as often as street types`,
@@ -679,7 +616,7 @@ export async function relabelGoldenDirectory(
 function renderDeckMarkdown(deck: GoldenRelabelDeckEntry[], parent: string, version: string): string {
 	const span = (components: Record<string, string>): string =>
 		[components.street_prefix, components.street, components.street_suffix]
-			.filter(Boolean)
+			.filter(isPresent)
 			.map((s) => JSON.stringify(s))
 			.join(" + ")
 

package/src/tools/index.ts

@@ -4,8 +4,7 @@
  * @author Teffen Ellis, et al.
  *
  *   Corpus operator tools — the `run()`-style modules behind `mailwoman corpus …` commands. No argv,
- *   no `process.exit`: commands own parsing, rendering, and exit codes (see the 2026-07-09
- *   scripts→Pastel spec).
+ *   no `process.exit`: commands own parsing, rendering, and exit codes.
  */
 
 export * from "./align-shard.ts"
@@ -23,6 +22,7 @@ export * from "./lint-shard.ts"
 export * from "./lint-shard-vocab.ts"
 export * from "./shard-kryptonite.ts"
 export * from "./overture-subvenue.ts"
+export * from "./postcode-triples.ts"
 export * from "./sub-venue-lexicon.ts"
 export * from "./sub-venue-promotions.ts"
 export * from "./shard-translit.ts"

package/src/tools/ingest-csv.ts

@@ -241,7 +241,6 @@ async function runIngest(opts: IngestOptions): Promise<void> {
 	const createTableSQL = `CREATE TABLE IF NOT EXISTS "${opts.tableName}" (\n  ${colDefs}\n);`
 
 	const tempCols = columns.map((c) => `"${c.name}"`).join(", ")
-	const insertSQL = `INSERT INTO "${opts.tableName}" (${tempCols})\nSELECT ${tempCols} FROM temp."${opts.tableName}_source";`
 
 	process.stderr.write(`\nSchema inferred from ${sampleRows.length} sample rows:\n`)
 	process.stderr.write(`${createTableSQL}\n\n`)
@@ -264,17 +263,6 @@ async function runIngest(opts: IngestOptions): Promise<void> {
 
 	// Use the .import approach via a temp table, then INSERT INTO ... SELECT to handle
 	// NULL normalization and type coercion.
-	const csvBasename = basename(opts.inputPath)
-
-	const importSQL = [
-		`CREATE TEMP TABLE "${opts.tableName}_source" (${colDefs});`,
-		`.mode csv`,
-		`.separator "${opts.separator}"`,
-		`.import "${csvBasename}" --skip ${opts.skipLines + (opts.hasHeader ? 1 : 0)} --schema temp ${opts.tableName}_source`,
-		insertSQL,
-		`DROP TABLE temp."${opts.tableName}_source";`,
-	]
-
 	// better-sqlite3 doesn't support .import natively, so we use a different approach:
 	// Read the CSV line-by-line and INSERT in a transaction.
 	process.stderr.write(`Importing rows...\n`)
@@ -373,7 +361,6 @@ async function runIngest(opts: IngestOptions): Promise<void> {
 	db.close()
 
 	// Write MANIFEST
-	const fileSize = (await import("node:fs/promises")).stat
 	const stat = await (await import("node:fs/promises")).stat(opts.outputPath)
 
 	const manifest = {