@mailwoman/corpus 8.6.0 → 9.0.0

package/src/shard-recipes/unit.ts

@@ -4,7 +4,7 @@
  * @author Teffen Ellis, et al.
  *
  *   `unit` shard recipe — US secondary-unit coverage (#451, the v0-parity `unit` gap). Onto REAL US
- *   OpenAddresses skeletons (cached zips under `/tmp/oa-cache`) it INJECTS a USPS Pub-28 Appendix
+ *   OpenAddresses skeletons (cached zips under `$MAILWOMAN_DATA_ROOT/oa-cache`) it INJECTS a USPS Pub-28 Appendix
  *   C2 secondary-unit designator (the `@mailwoman/codex/us` table), varying the surface form
  *   (canonical "Apartment" vs approved "Apt") AND the unit's POSITION (after-street / unit-first /
  *   bare / venue-prefixed) per row, so the model learns to RECOGNIZE the designator wherever it
@@ -25,11 +25,12 @@ import { spawnSync } from "node:child_process"
 
 import { US_UNIT_DESIGNATOR_PREFERRED_ABBR, type USUnitDesignator } from "@mailwoman/codex/us"
 import type { ComponentTag } from "@mailwoman/core/types"
+import { dataRootPath } from "@mailwoman/core/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 { makeMulberry32, readCSVRecords, type ShardRecipe } from "./scaffold.ts"
 
 /**
  * A cached OpenAddresses extract: the zip, the CSV member, and the implied (file-level) region.
@@ -58,16 +59,20 @@ interface UnitSource {
  * state cached; eval is Vermont only (the corpus holdout).
  */
 const TRAIN_SOURCES: readonly UnitSource[] = [
-	{ 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: UnitSource = { zip: "/tmp/oa-cache/us__vt__statewide.zip", csv: "us/vt/statewide.csv", region: "VT" }
+const EVAL_SOURCE: UnitSource = {
+	zip: dataRootPath("oa-cache", "us__vt__statewide.zip"),
+	csv: "us/vt/statewide.csv",
+	region: "VT",
+}
 
 /**
  * USPS Pub-28 C2 designators that take a secondary identifier ("Apt 4B"). Weighted toward the common ones the v0-parity
@@ -114,44 +119,6 @@ interface UnitTuple {
 	oaUnit: string
 }
 
-/**
- * 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 + the bare OA unit id) out of a cached OA zip.
  */
@@ -164,28 +131,13 @@ function readTuples(source: UnitSource): UnitTuple[] {
 		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"),
-		iUnit = idx("unit"),
-		iCity = idx("city"),
-		iPost = idx("postcode")
-
-	const get = (cells: string[], i: number): string => (i >= 0 && i < cells.length ? (cells[i] ?? "").trim() : "")
 	const tuples: UnitTuple[] = []
 	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 (const row of readCSVRecords(r.stdout)) {
+		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()
@@ -198,8 +150,8 @@ function readTuples(source: UnitSource): UnitTuple[] {
 			street,
 			locality,
 			region: source.region,
-			postcode: get(cells, iPost),
-			oaUnit: get(cells, iUnit),
+			postcode: row.postcode ?? "",
+			oaUnit: row.unit ?? "",
 		})
 	}
 
@@ -321,7 +273,7 @@ export const unitRecipe: 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

package/src/split.ts

@@ -152,6 +152,13 @@ export function splitRows(rows: Iterable<SplitInputRow>, opts: SplitOptions = {}
 /**
  * Lightweight deterministic 0..(n-1) bucket from a string id.
  */
+/**
+ * Deterministic bucket for a stable id.
+ *
+ * Stays on raw `createHash` rather than `sha256Hex` from `@mailwoman/core/utils`: it needs the digest BYTES, and the
+ * shared helper returns hex. Re-parsing hex back into bytes to reach the same four octets would cost more than the one
+ * line it saves.
+ */
 export function hashBucket(id: string, n: number): number {
 	const digest = createHash("sha256").update(id).digest()
 	// Read 4 bytes as uint32 to avoid bigint overhead.

package/src/synthesize.ts

@@ -34,6 +34,7 @@ import {
 	matchTrailingSuffix,
 } from "@mailwoman/codex/us"
 import type { BIOLabel, ComponentTag } from "@mailwoman/core/types"
+import { mulberry32 } from "@mailwoman/core/utils"
 
 import { alignRow, assertSpanInvariants, type ComponentSpan } from "./align.ts"
 import { whitespaceTokenizer, type Tokenizer } from "./tokenize.ts"
@@ -213,21 +214,6 @@ function hashString(s: string): number {
 	return h >>> 0
 }
 
-/**
- * Mulberry32 — a tiny seeded PRNG. Same seed → same stream → reproducible typos.
- */
-function mulberry32(seed: number): () => number {
-	let a = seed >>> 0
-
-	return () => {
-		a = (a + 0x6d_2b_79_f5) | 0
-		let t = Math.imul(a ^ (a >>> 15), 1 | a)
-		t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
-
-		return ((t ^ (t >>> 14)) >>> 0) / 4_294_967_296
-	}
-}
-
 /**
  * Inject ONE realistic typo — an adjacent-QWERTY-key substitution OR an adjacent-character transposition — into a
  * single alpha name component (street/locality/region…), teaching the model to recover from real-world misspellings

package/src/tools/align-shard.ts

@@ -27,7 +27,7 @@ import { createWriteStream } from "node:fs"
  * --corpus-version 0.5.0
  */
 import { alignRow } from "@mailwoman/corpus"
-import { TextSpliterator } from "spliterator"
+import { JSONSpliterator } from "spliterator"
 
 export interface AlignShardOptions {
 	input: string
@@ -36,16 +36,13 @@ export interface AlignShardOptions {
 }
 
 export async function alignCanonicalShard(args: AlignShardOptions): Promise<void> {
-	// Read phase only — the write path stays on createWriteStream. TextSpliterator + JSON.parse keeps the
-	// original tolerance: the `!line.trim()` guard skips blank lines and a trailing CR is valid JSON whitespace.
+	// Read phase only — the write path stays on createWriteStream.
 	const outStream = createWriteStream(args.output, { encoding: "utf8" })
 	let labeled = 0
 	let quarantined = 0
 	const quarantineReasons: Record<string, number> = {}
 
-	for await (const line of TextSpliterator.fromAsync(args.input)) {
-		if (!line.trim()) continue
-		const canonical = JSON.parse(line) as Parameters<typeof alignRow>[0]
+	for await (const canonical of JSONSpliterator.fromAsync<Parameters<typeof alignRow>[0]>(args.input)) {
 		// Stamp the target corpus version so the emitted row's provenance matches the run it joins.
 		canonical.corpus_version = args.corpusVersion
 		const result = alignRow(canonical)

package/src/tools/audit.ts

@@ -18,6 +18,9 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs"
 import { basename, join } from "node:path"
 
+import { parseJSONStrict } from "@mailwoman/core/objects"
+import { TextSpliterator } from "spliterator"
+
 /**
  * Share of a shard one source may hold before the mix is flagged as dominated by it.
  */
@@ -66,13 +69,11 @@ interface ParsedConfig {
  */
 function parseConfig(configPath: string): ParsedConfig | null {
 	if (!existsSync(configPath)) return null
-	const text = readFileSync(configPath, "utf8")
-	const lines = text.split("\n")
 	const weights: Record<string, number> = {}
 	let inBlock = false
 	let blockIndent = -1
 
-	for (const raw of lines) {
+	for (const raw of TextSpliterator.from(readFileSync(configPath))) {
 		const sourceWeightsMatch = raw.match(/^([\t ]*)source_weights:\s*$/)
 
 		if (sourceWeightsMatch) {
@@ -217,9 +218,9 @@ function manifestScan(corpusDir: string, knownPrefixes: readonly string[]): Shar
 
 	if (!existsSync(manifestPath)) return null
 
-	const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as {
+	const manifest = parseJSONStrict<{
 		shards?: Array<{ split: string; source?: string | null; first_source_id?: string | null }>
-	}
+	}>(readFileSync(manifestPath, "utf8"))
 
 	if (!Array.isArray(manifest.shards)) return null
 	const bySplit: Record<string, Record<string, number>> = {}

package/src/tools/corpus-stats.ts

@@ -32,14 +32,15 @@
  *
  *   For a quick local-corpus baseline (limited but useful for linter testing): node
  *   scripts/build-corpus-stats.ts\
- *   --shards /mnt/playpen/mailwoman-data/corpus/versioned/v0.4.0/corpus-v0.4.0/train/\
+ *   --shards $MAILWOMAN_DATA_ROOT/corpus/versioned/v0.4.0/corpus-v0.4.0/train/\
  *   --output /tmp/corpus-stats-local.json
  */
 
-import { execSync } from "node:child_process"
 import { readdirSync, statSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
 
+import { ParquetReader } from "../parquet-wrapper/index.ts"
+
 const SEP = ""
 const MIN_BIGRAM_COUNT = 2
 
@@ -65,36 +66,28 @@ function discoverShards(shardsArg: string): string[] {
 }
 
 /**
- * Use a Python subprocess to read parquet (pyarrow is heavier than parquet-wasm but already on the path here, and we
- * have nothing in the JS ecosystem that reads parquet cleanly at this scale). Emits one JSON object per line: `{tokens:
- * [...], labels: [...]}`.
+ * Stream a shard's `tokens`/`labels` columns.
+ *
+ * `limit` stops the iteration rather than filtering afterwards, so a capped run reads only the row groups it needs.
  */
-function streamShardRows(shardPath: string, limit?: number): Array<{ tokens: string[]; labels: string[] }> {
-	// Pipe the python script via stdin instead of `-c` to preserve newlines verbatim
-	// (JSON-encoding the script for -c collapses real newlines into literal `\n`).
-	const py = `
-import pyarrow.parquet as pq
-import json, sys
-t = pq.read_table(${JSON.stringify(shardPath)}, columns=['tokens', 'labels'])
-tokens_col = t['tokens'].to_pylist()
-labels_col = t['labels'].to_pylist()
-n = min(len(tokens_col), ${limit ?? "len(tokens_col)"})
-for i in range(n):
-    sys.stdout.write(json.dumps({"tokens": tokens_col[i], "labels": labels_col[i]}) + "\\n")
-`
-
-	const buf = execSync(`python3`, { input: py, maxBuffer: 1024 * 1024 * 1024 })
-	const rows: Array<{ tokens: string[]; labels: string[] }> = []
-
-	for (const line of buf.toString("utf8").split("\n")) {
-		if (!line) continue
-		rows.push(JSON.parse(line))
-	}
+async function* streamShardRows(
+	shardPath: string,
+	limit?: number
+): AsyncIterable<{ tokens: string[]; labels: string[] }> {
+	await using reader = await ParquetReader.openFile<{ tokens: string[]; labels: string[] }>(shardPath)
+
+	let emitted = 0
 
-	return rows
+	for await (const row of reader.project("tokens", "labels")) {
+		if (limit !== undefined && emitted >= limit) break
+
+		yield row
+
+		emitted++
+	}
 }
 
-export function buildCorpusStats(args: CorpusStatsOptions): void {
+export async function buildCorpusStats(args: CorpusStatsOptions): Promise<void> {
 	const shardPaths = discoverShards(args.shardsArg)
 
 	console.error(`Discovered ${shardPaths.length} parquet shard(s)`)
@@ -106,11 +99,10 @@ export function buildCorpusStats(args: CorpusStatsOptions): void {
 	for (const path of shardPaths) {
 		console.error(`Reading ${path}...`)
 
-		const rows = streamShardRows(path, args.limitPerShard)
-		totalRows += rows.length
+		const before = totalRows
 
-		for (const row of rows) {
-			const { tokens, labels } = row
+		for await (const { tokens, labels } of streamShardRows(path, args.limitPerShard)) {
+			totalRows++
 
 			if (tokens.length !== labels.length) continue
 
@@ -143,7 +135,7 @@ export function buildCorpusStats(args: CorpusStatsOptions): void {
 		}
 
 		console.error(
-			`  ${rows.length} rows; running totals: ${tokenStats.size} unique tokens, ${bigramStats.size} unique bigrams`
+			`  ${totalRows - before} rows; running totals: ${tokenStats.size} unique tokens, ${bigramStats.size} unique bigrams`
 		)
 	}
 

package/src/tools/fetch/download.ts

@@ -12,6 +12,8 @@ import { existsSync } from "node:fs"
 import { readFile, writeFile } from "node:fs/promises"
 import { setTimeout as sleep } from "node:timers/promises"
 
+import { tryParsingJSON } from "@mailwoman/core/objects"
+
 /**
  * Rate limited — retryable, the server is asking us to back off.
  */
@@ -127,11 +129,11 @@ export async function downloadToFile(options: DownloadOptions): Promise<{ bytes:
 export async function readManifest<T>(path: string): Promise<T | null> {
 	if (!existsSync(path)) return null
 
-	try {
-		return JSON.parse(await readFile(path, "utf8")) as T
-	} catch {
-		return null
-	}
+	// A read failure (e.g. the file vanished after the existsSync probe) maps to null like corrupt
+	// JSON does; tryParsingJSON returns null for the non-string sentinel.
+	const text = await readFile(path, "utf8").catch(() => null)
+
+	return tryParsingJSON<T>(text)
 }
 
 /**

package/src/tools/fetch/imls-pls.ts

@@ -30,6 +30,7 @@ import { basename, join } from "node:path"
 import { promisify } from "node:util"
 
 import { sha256File } from "@mailwoman/core/utils"
+import { TextSpliterator } from "spliterator"
 
 import type { BaseFetchOptions, FetchSummary } from "./download.ts"
 import { downloadToFile, readManifest, writeManifest } from "./download.ts"
@@ -64,8 +65,7 @@ interface SourceManifest {
 async function listZipEntries(zipPath: string): Promise<string[]> {
 	const listing = await execFileAsync("unzip", ["-l", zipPath])
 
-	return listing.stdout
-		.split("\n")
+	return [...TextSpliterator.from(listing.stdout)]
 		.map((line) => line.trim().split(/\s+/).pop() ?? "")
 		.filter((name) => name.length > 0)
 }

package/src/tools/fetch/index.ts

@@ -40,6 +40,13 @@
  *       Tier A (US PD).
  *   - `openaddresses` — OpenAddresses country collections (default: Canada / `ca`). Tier B/C mixed
  *       — per-row filter.
+ *   - `ourairports` — OurAirports global airport CSVs (~83K airports + the country/region/runway
+ *       joins). Tier A (public domain). The VENUE half of the sub-venue arc (#35); it carries no
+ *       interior structure, which comes from `@mailwoman/osm/sdk`'s `extractOSMSubVenues`.
+ *   - `wikidata-subvenue` — the multilingual sub-venue DESIGNATOR vocabulary, pulled as the labels
+ *       and aliases of eight Wikidata concepts (terminal, gate, concourse, campus, …) plus the
+ *       airport-terminal instance labels as attested usage. Tier A (CC0). The only module in this
+ *       family built on `APIClient` — see its docstring for why.
  *   - `state-sources` — NY/TX/DE/OR notaries, IA contractors, WA health providers, HI lobbyists.
  *       Tier A (state PD-equivalent).
  *   - `state-hi-schools` — Hawaii DOE school directory (XLSX → CSV via openpyxl). Tier A (state
@@ -65,7 +72,7 @@
  *
  *   # Download Canada (~2 GiB compressed, ~7 GiB uncompressed)
  *   mailwoman corpus fetch openaddresses --country ca \
- *     --out-root /mnt/playpen/mailwoman-data/corpus/sources
+ *     --out-root $MAILWOMAN_DATA_ROOT/corpus/sources
  *
  *   # Or any other OA country code
  *   mailwoman corpus fetch openaddresses --country fr
@@ -91,9 +98,11 @@ import { fetchIMLSPLS } from "./imls-pls.ts"
 import { fetchNAD } from "./nad.ts"
 import { fetchNPPES } from "./nppes.ts"
 import { fetchOpenAddresses } from "./openaddresses.ts"
+import { fetchOurAirports } from "./ourairports.ts"
 import { fetchStateHISchools } from "./state-hi-schools.ts"
 import { fetchStateSources } from "./state-sources.ts"
 import { fetchTigerFull } from "./tiger-full.ts"
+import { fetchWikidataSubVenue } from "./wikidata-subvenue.ts"
 
 export * from "./ban.ts"
 export * from "./hrsa.ts"
@@ -101,9 +110,11 @@ export * from "./imls-pls.ts"
 export * from "./nad.ts"
 export * from "./nppes.ts"
 export * from "./openaddresses.ts"
+export * from "./ourairports.ts"
 export * from "./state-hi-schools.ts"
 export * from "./state-sources.ts"
 export * from "./tiger-full.ts"
+export * from "./wikidata-subvenue.ts"
 
 /**
  * The fetch-source registry: id → module entry point. Each entry point takes its own options interface.
@@ -115,9 +126,11 @@ export const FETCH_SOURCES = {
 	"imls-pls": fetchIMLSPLS,
 	nppes: fetchNPPES,
 	openaddresses: fetchOpenAddresses,
+	ourairports: fetchOurAirports,
 	"state-sources": fetchStateSources,
 	"state-hi-schools": fetchStateHISchools,
 	"tiger-full": fetchTigerFull,
+	"wikidata-subvenue": fetchWikidataSubVenue,
 } as const
 
 export type FetchSourceID = keyof typeof FETCH_SOURCES

package/src/tools/fetch/nad.ts

@@ -26,7 +26,7 @@
  *   ## Usage
  *
  *   ```sh
- *   mailwoman corpus fetch nad --out-root /mnt/playpen/mailwoman-data/corpus/sources
+ *   mailwoman corpus fetch nad --out-root $MAILWOMAN_DATA_ROOT/corpus/sources
  *
  *   # Resume from an OID
  *   mailwoman corpus fetch nad --start-oid 34400001

package/src/tools/fetch/nppes.ts

@@ -31,6 +31,7 @@ import { join } from "node:path"
 import { promisify } from "node:util"
 
 import { sha256File } from "@mailwoman/core/utils"
+import { TextSpliterator } from "spliterator"
 
 import type { BaseFetchOptions, FetchSummary } from "./download.ts"
 import { downloadToFile, readManifest, writeManifest } from "./download.ts"
@@ -79,7 +80,7 @@ async function discoverLatestZip(): Promise<string | undefined> {
 async function findNpidataCSV(zipPath: string): Promise<string | undefined> {
 	const listing = await execFileAsync("unzip", ["-l", zipPath])
 
-	for (const line of listing.stdout.split("\n")) {
+	for (const line of TextSpliterator.from(listing.stdout)) {
 		const match = /npidata_pfile\S+\.csv/i.exec(line)
 
 		if (match?.[0]) return match[0]

package/src/tools/fetch/openaddresses.ts

@@ -44,7 +44,7 @@
  *   ```sh
  *   # With token (preferred). Default country: ca. Supports any OA country code (us-west, fr, …)
  *   OA_BATCH_TOKEN=<token> mailwoman corpus fetch openaddresses --country ca \
- *     --out-root /mnt/playpen/mailwoman-data/corpus/sources
+ *     --out-root $MAILWOMAN_DATA_ROOT/corpus/sources
  *
  *   # Without token (will detect + print instructions, then report the failure):
  *   mailwoman corpus fetch openaddresses --country ca

package/src/tools/fetch/ourairports.ts

@@ -0,0 +1,166 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Fetch the OurAirports CSV dumps — the VENUE side of the sub-venue corpus arc (#35).
+ *
+ *   Source : https://davidmegginson.github.io/ourairports-data/ (the project's own GitHub Pages
+ *            mirror of the nightly export; `ourairports.com/data/` redirects here).
+ *   License: PUBLIC DOMAIN. OurAirports places its data in the public domain and asks only for a
+ *            courtesy credit — no attribution obligation rides on a derived shard, which makes this
+ *            the one transport source in the arc with no licensing question at all. Tier A.
+ *
+ *   ## What it is good for, and what it is not
+ *
+ *   `airports.csv` is every airport on earth with ICAO/IATA codes, coordinates, `municipality`, and
+ *   `iso_country` — 12.7 MB, ~83,000 rows as of 2026-08-04. That is the CONTAINING VENUE for a
+ *   `<sub-venue>, <venue>, <street>, <locality>, <postcode>` corpus line, and it is better at that job
+ *   than OSM: every row is named, the name is canonical, and `municipality` gives the locality without
+ *   a spatial join.
+ *
+ *   It carries NO interior structure. There is no terminal, concourse, gate or pier table — the
+ *   corpus task says as much ("Good for the venue side of each pair, weaker on interior structure")
+ *   and a row-level read confirms it. Pair it with the OSM `aeroway` extractor
+ *   (`@mailwoman/osm/sdk`'s `extractOSMSubVenues`), which is where the sub-venue half comes from.
+ *
+ *   ## Why `downloadToFile` and not `APIClient`
+ *
+ *   `AGENTS.md` routes HTTP through `APIClient`, and that rule is about API REQUESTS — small bodies,
+ *   repeated calls, rate-limited hosts. This is four static file transfers against a GitHub Pages CDN
+ *   with no rate limit and nothing to pace, run once per refresh. It uses the same `downloadToFile`
+ *   every other module in this `fetch/` family uses, which is where the retry and timeout live.
+ *   The Wikidata sibling (`wikidata-subvenue.ts`) IS an API client and is built on `APIClient`
+ *   accordingly; the split between the two is the one `AGENTS.md` draws.
+ *
+ *   Invoke via `mailwoman corpus fetch ourairports --out-root <path>`.
+ */
+
+import { mkdirSync } from "node:fs"
+import { join } from "node:path"
+
+import { sha256File } from "@mailwoman/core/utils"
+
+import type { BaseFetchOptions, FetchSummary } from "./download.ts"
+import { downloadToFile, writeManifest } from "./download.ts"
+
+const SLUG = "ourairports"
+
+/**
+ * The GitHub Pages mirror the project itself publishes. `ourairports.com/data/*.csv` 302s here, so pointing at the
+ * mirror directly saves a redirect and is the URL the project's own README gives.
+ */
+const BASE_URL = "https://davidmegginson.github.io/ourairports-data"
+
+/**
+ * The files worth having, and why each one.
+ *
+ * `airports.csv` is the payload. The other three are small joins that turn its codes into text: `countries.csv` and
+ * `regions.csv` expand `iso_country`/`iso_region` into names (a corpus line needs "Germany", not "DE"), and
+ * `runways.csv` is the only file carrying per-airport sub-structure of any kind — runway designators, which are NOT
+ * sub-venue designators (nobody addresses mail to a runway) but are worth having on disk as the negative class if the
+ * shard ever needs one.
+ */
+const FILES = ["airports.csv", "countries.csv", "regions.csv", "runways.csv"] as const
+
+export type FetchOurAirportsOptions = BaseFetchOptions
+
+interface OurAirportsFileEntry {
+	filename: string
+	source_url: string
+	sha256: string
+	bytes: number
+	/**
+	 * The upstream `Last-Modified`, when the CDN gave one. This is the DATA's vintage; `downloaded_at` is only when we
+	 * asked. `corpus/AGENTS.md` has the standing warning that a file's mtime is not its data's vintage — recording the
+	 * upstream header is how a later refresh decision gets made on the right number.
+	 */
+	last_modified: string | null
+}
+
+interface OurAirportsManifest {
+	source: string
+	base_url: string
+	license: string
+	downloaded_at: string
+	files: OurAirportsFileEntry[]
+}
+
+/**
+ * Read the upstream `Last-Modified` with a HEAD. Returns `null` on any failure — provenance metadata is nice to have
+ * and must never fail a download that otherwise succeeded.
+ */
+async function readLastModified(url: string): Promise<string | null> {
+	try {
+		const res = await fetch(url, { method: "HEAD", signal: AbortSignal.timeout(30_000) })
+
+		return res.ok ? res.headers.get("last-modified") : null
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Download the OurAirports CSVs into `<outRoot>/ourairports/`, with a sibling `MANIFEST.json` carrying each file's
+ * origin URL, sha256, byte count and upstream `Last-Modified`.
+ */
+export async function fetchOurAirports(
+	options: FetchOurAirportsOptions,
+	report?: (line: string) => void
+): Promise<FetchSummary> {
+	const destDir = join(options.outRoot, SLUG)
+	mkdirSync(destDir, { recursive: true })
+
+	const entries: OurAirportsFileEntry[] = []
+	const failedCodes: string[] = []
+	let fetched = 0
+	let failed = 0
+
+	for (const filename of FILES) {
+		const url = `${BASE_URL}/${filename}`
+		const dest = join(destDir, filename)
+
+		report?.(`=== ${SLUG} / ${filename}`)
+
+		try {
+			const [{ bytes }, lastModified] = await Promise.all([
+				downloadToFile({
+					url,
+					dest,
+					timeoutMs: 600_000,
+					retries: 2,
+					headers: { "Accept-Encoding": "gzip, br" },
+					report,
+				}),
+				readLastModified(url),
+			])
+
+			entries.push({
+				filename,
+				source_url: url,
+				sha256: await sha256File(dest),
+				bytes,
+				last_modified: lastModified,
+			})
+
+			fetched++
+		} catch (error) {
+			report?.(`✗ ${filename}: ${error instanceof Error ? error.message : String(error)}`)
+			failedCodes.push(filename)
+
+			failed++
+		}
+	}
+
+	const manifest: OurAirportsManifest = {
+		source: "OurAirports",
+		base_url: BASE_URL,
+		license: "public domain (courtesy credit requested)",
+		downloaded_at: new Date().toISOString(),
+		files: entries,
+	}
+
+	await writeManifest(join(destDir, "MANIFEST.json"), manifest)
+
+	return { fetched, skipped: 0, failed, failedCodes }
+}