@mailwoman/corpus 10.0.0 → 10.2.0

package/lib/us/fips-state.ts

@@ -8,7 +8,7 @@
  *   Covers all 50 states + DC + the five primary territories (PR, GU, VI, MP, AS).
  *
  *   The data is public-domain US Census reference (FIPS PUB 5-2, withdrawn but still the canonical
- *   numeric ID used by every TIGER product). It is reproduced here so the TIGER adapter can resolve
+ *   numeric ID used by every tiger product). It is reproduced here so the tiger adapter can resolve
  *   `statefp` columns (e.g. `"50"`) into a `region` component (e.g. `"VT"`) without an extra DB
  *   join.
  */
@@ -22,8 +22,10 @@ export interface USStateInfo {
 }
 
 /**
- * FIPS state-or-territory code → `{ abbreviation, name }`. Includes all 50 states, DC, and the five primary territories
- * (PR, GU, VI, MP, AS). Codes are two-digit zero-padded strings to match TIGER column `statefp`.
+ * FIPS state-or-territory code → `{ abbreviation, name }`.
+ *
+ * Includes all 50 states, DC and the five primary territories (PR, GU, VI, MP, AS).
+ * Codes are two-digit zero-padded strings to match tiger column `statefp`.
  */
 export const US_FIPS_STATE: Readonly<Record<string, USStateInfo>> = Object.freeze({
 	"01": { abbreviation: "AL", name: "Alabama" },
@@ -86,27 +88,34 @@ export const US_FIPS_STATE: Readonly<Record<string, USStateInfo>> = Object.freez
 })
 
 /**
- * Lookup helper. Returns null when the FIPS code isn't recognized.
+ * Lookup helper.
+ *
+ * @returns Null when the FIPS code isn't recognized.
  */
-export function lookupFipsState(statefp: string | null | undefined): USStateInfo | null {
+export function lookupFipsState(statefp: string | null): USStateInfo | null {
 	if (!statefp) return null
 
 	return US_FIPS_STATE[statefp] ?? null
 }
 
 /**
- * Inverted view: two-letter postal abbreviation → `USStateInfo`. Built once at module load. Used by adapters whose
- * source data ships the abbreviation rather than the FIPS code (FCC BDC, most federal CSVs).
+ * Inverted view: two-letter postal abbreviation → `USStateInfo`.
+ *
+ * Built once at module load.
+ * Used by adapters whose source data ships the abbreviation rather than the
+ * FIPS code (FCC BDC, most federal CSVs).
  */
 export const US_STATE_BY_ABBREVIATION: Readonly<Record<string, USStateInfo>> = Object.freeze(
 	Object.fromEntries(Object.values(US_FIPS_STATE).map((info) => [info.abbreviation, info]))
 )
 
 /**
- * Lookup helper for adapters carrying 2-char USPS abbreviations (`"CA"`, `"VT"`). Case-folded; null for any value
- * outside the 50 states + DC + the five primary territories.
+ * Lookup helper for adapters carrying 2-char USPS abbreviations (`"CA"`, `"VT"`).
+ *
+ * Case-folded.
+ * Null for any value outside the 50 states + DC + the five primary territories.
  */
-export function lookupStateAbbreviation(abbreviation: string | null | undefined): USStateInfo | null {
+export function lookupStateAbbreviation(abbreviation: string | null): USStateInfo | null {
 	if (!abbreviation) return null
 
 	return US_STATE_BY_ABBREVIATION[abbreviation.toUpperCase()] ?? null

package/lib/{synthesizers → us/synthesizers}/intersection.ts

@@ -6,22 +6,23 @@
  *   Intersection synthesizer — v0.7 coverage fix (night-3, DeepSeek-decided).
  *
  *   The 2026-05-29 harness diagnostic found the neural model emits `intersection_a`/`intersection_b`
- *   with ~0.0001 probability on canonical intersections ("Broadway & W 42nd St") — it never learned
- *   the tags, because the corpus has NO intersection training signal (no generator, and real-data
- *   adapters don't emit intersection-formatted rows). Intersections are 65 of the 376 harness
+ *   with ~0.0001 probability on canonical intersections ("Broadway & W 42nd St"). It never learned
+ *   the tags because the corpus has no intersection training signal. The corpus has no generator.
+ *   Real-data adapters don't emit intersection-formatted rows. Intersections are 65 of the 376 harness
  *   assertions (17%), all 0% neural. This generator produces the missing signal as a small targeted
- *   supplement slice (synthesis-as-supplement discipline: weight < 0.25, one-and-done).
+ *   supplement source (synthesis-as-supplement discipline: weight < 0.25, one-and-done).
  *
  *   Output is a `CanonicalRow` ({raw, components}); the corpus aligner turns it into BIO labels
  *   (B-/I-intersection_a, O on the connector, B-/I-intersection_b). Surface forms of both streets
- *   MUST occur verbatim in `raw` so alignment lands.
+ *   must occur verbatim in `raw` so alignment lands.
  *
  *   US-idiomatic only (the harness intersection cases are US: "X & Y, City, ST ZIP").
  */
 
 import type { DirectionalAbbreviation } from "@mailwoman/codex/us"
+import { sample } from "@mailwoman/core/random"
 
-import { pick } from "#synthesizers/utils"
+import { layoutAdminTail } from "#synthesizers/tail"
 import type { CanonicalRow } from "#types"
 
 /**
@@ -34,10 +35,10 @@ import type { CanonicalRow } from "#types"
 const MAX_DISTINCT_STREET_TRIES = 8
 
 /* oxlint-disable sister-software/no-unnamed-threshold -- the bare decimals below are weighted-sampler
-   cutoffs, not thresholds: `const r = random()` followed by a cascade of `r < 0.4` branches IS the
-   output distribution, and reading the cascade top-to-bottom is how you see it. Naming each cutoff
-   would hide the distribution behind a wall of identifiers. Genuine thresholds in these files are
-   extracted as named constants above. */
+   cutoffs rather than thresholds: `const r = random()` followed by a cascade of `r < 0.4` branches is the
+   output distribution. The cascade shows each weight from top to bottom. A separate constant for each cutoff
+   would hide the distribution behind identifiers. The genuine thresholds in these files are
+    extracted as constants above. */
 
 const STREET_CORES = [
 	"Main",
@@ -65,7 +66,7 @@ const STREET_CORES = [
 ] as const
 
 /**
- * Bare proper-noun streets that idiomatically take NO suffix.
+ * Bare proper-noun streets that idiomatically take no suffix.
  */
 const BARE_NAMES = ["Broadway", "Wall", "Bourbon", "Esplanade", "Riverside", "Lakeshore"] as const
 
@@ -87,13 +88,17 @@ const ORDINALS = [
 
 const SUFFIXES = ["St", "Ave", "Blvd", "Rd", "Dr", "Ln", "Way", "Pl", "Ct", "Pkwy", "Ter", "Cir"] as const
 
-// Vocabulary compile-checked against the codex; the ORDER stays this literal's. `Object.values(DirectionalAbbreviation)`
-// runs N,E,S,W,… — deriving the array from it would re-map every pick() draw and change shipped slice bytes.
+// Vocabulary compile-checked against the codex.
+// The order stays this literal's.
+// `Object.values(DirectionalAbbreviation)` runs N,E,S,W,… — deriving the array from it
+// would re-map every sample() draw and change shipped recipe-output bytes.
 const DIRECTIONALS = ["N", "S", "E", "W", "NE", "NW", "SE", "SW"] as const satisfies readonly DirectionalAbbreviation[]
 
 /**
- * Connectors between the two streets. Whitespace-padded forms keep tokens clean for alignment. `@` added in v0.7.2 —
- * the harness uses it ("Main St @ Second Ave") and v0.7.1 had never seen it.
+ * Connectors between the two streets.
+ *
+ * Whitespace-padded forms keep tokens clean for alignment.
+ * `@` added in v0.7.2 — the harness uses it ("Main St @ Second Ave") and v0.7.1 had never seen it.
  */
 const CONNECTORS = [" & ", " and ", " at ", " / ", " @ "] as const
 
@@ -122,23 +127,25 @@ export interface IntersectionSynthesisOpts {
  */
 function buildStreetName(random: () => number): string {
 	// ~20% bare proper-noun street (no suffix), else directional? + core/ordinal + suffix.
-	if (random() < 0.2) return pick(BARE_NAMES, random)
+	if (random() < 0.2) return sample(BARE_NAMES, random)
 
 	const parts: string[] = []
 
 	if (random() < 0.35) {
-		parts.push(pick(DIRECTIONALS, random))
+		parts.push(sample(DIRECTIONALS, random))
 	}
 
-	parts.push(random() < 0.45 ? pick(ORDINALS, random) : pick(STREET_CORES, random))
-	parts.push(pick(SUFFIXES, random))
+	parts.push(random() < 0.45 ? sample(ORDINALS, random) : sample(STREET_CORES, random))
+	parts.push(sample(SUFFIXES, random))
 
 	return parts.join(" ")
 }
 
 /**
- * Synthesize one US intersection row. Returns null on the rare degenerate case where the two streets collide (so
- * alignment never has two identical surface forms to disambiguate).
+ * Synthesize one US intersection row.
+ *
+ * @returns Null on the rare degenerate case where the two streets collide
+ * (so alignment never has two identical surface forms to disambiguate).
  */
 export function synthesizeIntersectionRow(
 	base: IntersectionBaseTuple,
@@ -146,6 +153,9 @@ export function synthesizeIntersectionRow(
 ): SynthesizedIntersectionRow | null {
 	const random = opts.random ?? Math.random
 
+	// The junction connectors and the street vocabulary are US English,
+	// which is why this synthesizer sits under `us/`.
+	// The admin tail renders through the country's layout.
 	if (base.country !== "US") return null
 
 	const a = buildStreetName(random)
@@ -159,15 +169,16 @@ export function synthesizeIntersectionRow(
 
 	if (b === a || a.includes(b) || b.includes(a)) return null
 
-	const connector = pick(CONNECTORS, random)
+	const connector = sample(CONNECTORS, random)
 	// "corner of" prefix variant (~20%) — still labels the two streets identically.
 	const cornerPrefix = random() < 0.2 ? "corner of " : ""
 
 	const components: CanonicalRow["components"] = { intersection_a: a, intersection_b: b }
 
-	// v0.7.2: ~60% BARE (no locality tail). v0.7.1 always appended ", City, ST", so the model learned
-	// to read post-intersection text as a locality and fumbled the harness's bare "X & Y" cases
-	// (mislabeling the second street as a locality). Match the eval distribution.
+	// v0.7.2: ~60% bare (no locality tail). v0.7.1 always appended ", City, ST",
+	// so the model learned to read post-intersection text as a locality and fumbled the
+	// harness's bare "X & Y" cases (mislabeling the second street as a locality).
+	// Match the eval distribution.
 	const bare = random() < 0.6
 	let raw: string
 
@@ -176,24 +187,23 @@ export function synthesizeIntersectionRow(
 	} else {
 		const includePostcode = base.postcode != null && random() < 0.7
 
-		const tail = includePostcode
-			? `, ${base.locality}, ${base.region} ${base.postcode}`
-			: `, ${base.locality}, ${base.region}`
+		const tail = layoutAdminTail(base.country, {
+			locality: base.locality,
+			region: base.region,
+			postcode: includePostcode ? base.postcode : undefined,
+		})
 
-		raw = `${cornerPrefix}${a}${connector}${b}${tail}`
-		components.locality = base.locality
-		components.region = base.region
+		if (!tail) return null
 
-		if (includePostcode) {
-			components.postcode = base.postcode
-		}
+		raw = `${cornerPrefix}${a}${connector}${b}, ${tail.raw}`
+		Object.assign(components, tail.components)
 	}
 
 	return { raw, components, locale: "en-US" }
 }
 
 /**
- * A small built-in US city/region/zip pool for standalone slice generation + tests.
+ * A small built-in US city/region/zip pool for standalone recipe-output generation + tests.
  */
 export const DEFAULT_US_BASES: ReadonlyArray<IntersectionBaseTuple> = [
 	{ locality: "New York", region: "NY", postcode: "10036", country: "US" },

package/lib/{synthesizers → us/synthesizers}/street.ts

@@ -7,32 +7,34 @@
  *   `street_prefix`, `street`, and `street_suffix` are emitted as separate BIO spans (instead of
  *   monolithic `street`). Mirrors the PO box synthesizer pattern.
  *
- *   Why this exists: TIGER/NAD/BAN adapter changes (committed earlier tonight) emit decomposed
- *   components from raw source data, but the v0.4.0 parquet slices on Modal were built BEFORE those
- *   changes. Rebuilding the full corpus requires downloading raw TIGER/NAD/BAN data and re-running
+ *   Why this exists: tiger/NAD/BAN adapter changes (committed earlier tonight) emit decomposed
+ *   components from raw source data, but the v0.4.0 parquet files on Modal were built before those
+ *   changes. A full-corpus rebuild requires downloading raw tiger/NAD/BAN data and re-running
  *   adapters end-to-end — out of scope for a single night shift. This synthesizer takes (locality,
  *   region, postcode) tuples and produces freshly-decomposed Stage 3 training rows, same shape as
  *   the PO box pipeline.
  *
- *   Note: uses the SAME decomposition logic as TIGER's `decomposeStreet()` so the synthetic
- *   distribution matches what the model would see if/when TIGER slices are rebuilt with the new
+ *   Note: uses the same decomposition logic as tiger's `decomposeStreet()` so the synthetic
+ *   distribution matches what the model would see if/when the tiger parquet files are rebuilt with the new
  *   adapter.
  */
 
 import { isPresent } from "@mailwoman/core/objects"
+import { sample } from "@mailwoman/core/random"
 
-import { pick, tieredNumber } from "#synthesizers/utils"
+import { layoutAdminTail } from "#synthesizers/tail"
+import { tieredNumber } from "#synthesizers/utils"
 import type { CanonicalRow } from "#types"
 import { decomposeStreet } from "#us/adapters/tiger/street-decompose"
 
-// Hand-curated US street name pool. Real frequency-weighted street names — sampled
-// from US Census TIGER 2024 top-1000 by occurrence count. Keep ~50 entries so the
-// synthesis distribution doesn't overfit to a tiny vocabulary.
+// Hand-curated US street name pool.
+// Real frequency-weighted street names — sampled from US Census tiger 2024 top-1000 by occurrence count.
+// Keep ~50 entries so the synthesis distribution doesn't overfit to a tiny vocabulary.
 /* oxlint-disable sister-software/no-unnamed-threshold -- the bare decimals below are weighted-sampler
-   cutoffs, not thresholds: `const r = random()` followed by a cascade of `r < 0.4` branches IS the
-   output distribution, and reading the cascade top-to-bottom is how you see it. Naming each cutoff
+   cutoffs rather than thresholds: `const r = random()` followed by a cascade of `r < 0.4` branches is the
+   output distribution. The cascade shows each weight from top to bottom. A separate constant for each cutoff
    would hide the distribution behind a wall of identifiers. Genuine thresholds in these files are
-   extracted as named constants above. */
+    extracted as constants above. */
 
 const STREET_NAMES = [
 	"Main",
@@ -175,23 +177,28 @@ export interface SynthesizedStreetRow {
 export interface StreetSynthesisOpts {
 	random?: () => number
 	/**
-	 * Probability of emitting house_number alongside the street. Default 0.85.
+	 * Probability of emitting house_number alongside the street.
+	 *
+	 * @defaultValue `0.85`
 	 */
 	includeHouseNumberProb?: number
 	/**
-	 * Probability of emitting the street BARE — no `, City, ST ZIP` tail and no region/locality/ postcode components
-	 * (just `street_prefix`/`street`/`street_suffix` + optional `house_number`). Default 0 (preserves the original
-	 * full-address behavior exactly, including the RNG sequence). Set >0 to teach the model that a bare `10th Ave` /
-	 * `Main St` is a STREET, not a locality — the functional-test failure cluster (bare streets mislabeled `locality`),
+	 * Probability of emitting the street bare — no `, City, ST ZIP` tail and no region/locality/
+	 * postcode components (just `street_prefix`/`street`/`street_suffix` + optional `house_number`).
+	 *
+	 * Set >0 to teach the model that a bare `10th Ave` / `Main St` is a street rather than a
+	 * locality — the functional-test failure cluster (bare streets mislabeled `locality`),
 	 * the bare-format analogue of the v0.7.x intersection-bare fix.
+	 *
+	 * @defaultValue `0` (leaves the original full-address output exactly as it was, including the RNG sequence)
 	 */
 	bareProb?: number
 }
 
 function randomHouseNumber(random: () => number): string {
-	// US house number distribution: skewed low. 1-99 (30%), 100-999 (40%),
-	// 1000-9999 (25%), 10000+ (5%). The last band's 89_999 span is this file's own
-	// (the PO-box generators use 90_000) and is baked into every shipped street slice.
+	// US house number distribution: skewed low. 1-99 (30%), 100-999 (40%), 1000-9999 (25%), 10000+ (5%).
+	// The last band's 89_999 span is this file's own (the PO-box generators use 90_000)
+	// and is baked into every shipped street recipe output.
 	return tieredNumber(random, [
 		{ cutoff: 0.3, base: 1, span: 99 },
 		{ cutoff: 0.7, base: 100, span: 900 },
@@ -201,8 +208,10 @@ function randomHouseNumber(random: () => number): string {
 }
 
 /**
- * Synthesize a US street address with decomposed Stage 3 components. The street is built from PREFIX + NAME + SUFFIX,
- * then passed through the same `decomposeStreet()` utility the TIGER adapter uses — guarantees the synthetic
+ * Synthesize a US street address with decomposed Stage 3 components.
+ *
+ * The street is built from prefix + name + suffix, then passed through the same
+ * `decomposeStreet()` utility the tiger adapter uses — guarantees the synthetic
  * distribution matches the canonical decomposition logic.
  */
 export function synthesizeStreetRow(
@@ -212,36 +221,40 @@ export function synthesizeStreetRow(
 	const random = opts.random ?? Math.random
 	const includeHN = opts.includeHouseNumberProb ?? 0.85
 
+	// The street vocabulary (`STREET_NAMES`, `STREET_SUFFIXES`, the directionals) is
+	// US English, which is why this synthesizer sits under `us/`.
+	// The admin tail renders through the country's layout.
 	if (base.country !== "US") return null
 
-	const prefix = pick(DIRECTIONAL_PREFIXES, random)
-	const name = pick(STREET_NAMES, random)
-	const suffix = pick(STREET_SUFFIXES, random)
-	const trailing = pick(TRAILING_DIRECTIONALS, random)
+	const prefix = sample(DIRECTIONAL_PREFIXES, random)
+	const name = sample(STREET_NAMES, random)
+	const suffix = sample(STREET_SUFFIXES, random)
+	const trailing = sample(TRAILING_DIRECTIONALS, random)
 
-	// Build the "full" street string the adapter would receive from TIGER FULLNAME.
+	// Build the "full" street string the adapter would receive from tiger fullname.
 	const parts = [prefix, name, suffix, trailing].filter(isPresent)
 	const fullStreet = parts.join(" ")
 
-	// Pass through the same decomposeStreet TIGER uses — match the training distribution.
+	// Pass through the same decomposeStreet tiger uses — match the training distribution.
 	const decomposed = decomposeStreet(fullStreet)
 
-	// NOTE: country is intentionally omitted. We don't emit "USA" or "US" in the raw
-	// string, and the aligner's fuzzy match (edit distance 2) will spuriously match
-	// "US" against any 2-char token (e.g. a house number "45" is exactly 2 substitutions
-	// from "US"). The PO box synthesizer skips country for the same reason.
-	// Bare mode is guarded by `> 0` so the default (bareProb=0) consumes no RNG and reproduces the
-	// original full-address output byte-for-byte.
+	// note: country is intentionally omitted.
+	// The raw string omits "USA" and "US".
+	// The aligner's fuzzy match (edit distance 2) will spuriously match "US" against any
+	// 2-char token (e.g. A house number "45" is exactly 2 substitutions from "US").
+	// The PO box synthesizer skips country for the same reason.
+	// Bare mode is guarded by `> 0` so the default (bareProb=0) consumes no RNG
+	// and reproduces the original full-address output byte-for-byte.
 	const bareProb = opts.bareProb ?? 0
 	const bare = bareProb > 0 && random() < bareProb
 
-	const components: CanonicalRow["components"] = bare
-		? {}
-		: {
-				region: base.region,
-				locality: base.locality,
-				postcode: base.postcode,
-			}
+	const tail = bare
+		? null
+		: layoutAdminTail(base.country, { locality: base.locality, region: base.region, postcode: base.postcode })
+
+	if (!bare && !tail) return null
+
+	const components: CanonicalRow["components"] = tail ? { ...tail.components } : {}
 
 	if (decomposed.prefix) {
 		components.street_prefix = decomposed.prefix
@@ -260,9 +273,9 @@ export function synthesizeStreetRow(
 	if (random() < includeHN) {
 		const hn = randomHouseNumber(random)
 		components.house_number = hn
-		raw = bare ? `${hn} ${fullStreet}` : `${hn} ${fullStreet}, ${base.locality}, ${base.region} ${base.postcode}`
+		raw = tail ? `${hn} ${fullStreet}, ${tail.raw}` : `${hn} ${fullStreet}`
 	} else {
-		raw = bare ? fullStreet : `${fullStreet}, ${base.locality}, ${base.region} ${base.postcode}`
+		raw = tail ? `${fullStreet}, ${tail.raw}` : fullStreet
 	}
 
 	return { raw, components, locale: "en-US" }

package/lib/us/tools/fetch/hrsa.ts

@@ -6,8 +6,8 @@
  *   Re-fetch the HRSA Health Center Service Delivery Sites CSV. Source for the `usgov-hrsa-fqhc`
  *   adapter. US Public Domain.
  *
- *   Uses Node's built-in fetch (gzip/brotli) and streaming sha256 instead of curl + sha256sum, and
- *   writes the same sibling `MANIFEST.json` (origin URL + fetch timestamp + byte count + sha256) so
+ *   Uses Node's built-in fetch (gzip/brotli) and streaming sha256 instead of curl + sha256sum. It
+ *   writes the same sibling `manifest.json` (origin URL + fetch timestamp + byte count + sha256) so
  *   downstream adapters can verify provenance.
  *
  *   Invoke via `mailwoman corpus fetch hrsa --out-root <path>`.
@@ -15,10 +15,9 @@
 
 import { makeDirectories } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
-import { join } from "path-ts"
 
-import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetch/download/index"
-import { downloadToFile, writeManifest } from "#tools/fetch/download/index"
+import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetch/download"
+import { downloadToFile, writeManifest } from "#tools/fetch/download"
 
 const SLUG = "usgov-hrsa-fqhc"
 const FILENAME = "Health_Center_Service_Delivery_and_LookAlike_Sites.csv"
@@ -27,9 +26,9 @@ const SOURCE_URL = `https://data.hrsa.gov/DataDownload/DD_Files/${FILENAME}`
 export type FetchHRSAOptions = BaseFetchOptions
 
 export async function fetchHRSA(options: FetchHRSAOptions, report?: (line: string) => void): Promise<FetchSummary> {
-	const destDir = join(options.outRoot, SLUG)
+	const destDir = options.outRoot(SLUG)
 	await makeDirectories(destDir)
-	const dest = join(destDir, FILENAME)
+	const dest = destDir(FILENAME)
 
 	report?.(`=== ${SLUG} / ${FILENAME}`)
 
@@ -51,7 +50,7 @@ export async function fetchHRSA(options: FetchHRSAOptions, report?: (line: strin
 		bytes,
 	}
 
-	await writeManifest(join(destDir, "MANIFEST.json"), manifest)
+	await writeManifest(destDir("MANIFEST.json"), manifest)
 
 	report?.(`  ✓ ${(bytes / 1024 / 1024).toFixed(1)} MB  sha256=${sha}`)
 

package/lib/us/tools/fetch/imls-pls.ts

@@ -3,43 +3,28 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Re-fetch the IMLS Public Libraries Survey (PLS) outlet-level data. Each US public library branch
- *   (outlet) is one row, ~17K rows with address fields. Source for the `usgov-imls-pls` adapter. US
- *   Public Domain (federal statistical survey).
- *
- *   The FY 2023 release is the most current as of 2026-05. IMLS ships a single ZIP containing CSV,
- *   SAS, and SPSS variants. We extract the outlet-level CSV (pls_fy*_outlet*.csv or similar) and
- *   discard the rest. The administrative-entity (system-level) CSV is intentionally skipped — it has
- *   no per-branch address detail.
- *
- *   Uses Node's built-in fetch (gzip/brotli) and streaming sha256 instead of curl + sha256sum. The
- *   ZIP is unpacked with the `unzip` binary via `node:child_process` (no clean Node equivalent for
- *   member listing + selective extraction).
- *
- *   Invoke via `mailwoman corpus fetch imls-pls --out-root <path>`. Idempotent: if dest CSV exists
- *   and sha matches MANIFEST, skips download.
+ * Re-fetch the IMLS Public Libraries Survey outlet-level data — one row per US public library branch —
+ * for the `usgov-imls-pls` adapter. The source is US Public Domain (a federal statistical survey).
+ * Extracts the outlet-level CSV from IMLS's single ZIP and discards the rest. The system-level CSV is
+ * skipped for having no per-branch address detail.
  */
 
 /* 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. */
+   procedure rather than sections of declarations. A region there folds no element a reader wants folded. */
 
 import { BYTES_PER_KIB, ByteFormatter } from "@mailwoman/core/fs/formatters"
-import { statPath, pathExists } from "@mailwoman/core/fs/readers"
+import { statPath, pathExists } from "@mailwoman/core/fs/readers/stat"
 import { makeDirectories, removePathIfPresent } from "@mailwoman/core/fs/writers"
 import { extractZipEntry, listZipEntries } from "@mailwoman/core/fs/zip"
 import { sha256File } from "@mailwoman/core/hash"
-import { basename, join } from "path-ts"
+import { basename } from "path-ts"
 
-import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetch/download/index"
-import { downloadToFile, readManifest, writeManifest } from "#tools/fetch/download/index"
-
-/**
- * Bytes per KiB — the divisor for human-readable sizes, and the floor below which a "download" is an error page rather
- * than data.
- */
+import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetch/download"
+import { downloadToFile, readManifest, writeManifest } from "#tools/fetch/download"
 
 /**
- * The PLS FY 2023 bulk CSV ZIP (most recent as of 2026-05). If IMLS publishes a newer year, update this URL.
+ * The PLS FY 2023 bulk CSV ZIP.
+ * Update this URL if IMLS publishes a newer year.
  */
 const ZIP_URL = "https://www.imls.gov/sites/default/files/2025-08/pls_fy2023_csv.zip"
 const SLUG = "usgov-imls-pls"
@@ -50,11 +35,11 @@ export async function fetchIMLSPLS(
 	options: FetchIMLSPLSOptions,
 	report?: (line: string) => void
 ): Promise<FetchSummary> {
-	const destDir = join(options.outRoot, SLUG)
+	const destDir = options.outRoot(SLUG)
 	await makeDirectories(destDir)
 
-	const zipDest = join(destDir, basename(ZIP_URL))
-	const manifestPath = join(destDir, "MANIFEST.json")
+	const zipDest = destDir(basename(ZIP_URL))
+	const manifestPath = destDir("MANIFEST.json")
 
 	report?.(`=== ${SLUG}`)
 
@@ -63,7 +48,7 @@ export async function fetchIMLSPLS(
 	const recorded = await readManifest<Partial<SourceManifest>>(manifestPath)
 
 	if (recorded?.sha256 && recorded.filename) {
-		const recordedPath = join(destDir, recorded.filename)
+		const recordedPath = destDir(recorded.filename)
 
 		if ((await pathExists(recordedPath)) && (await sha256File(recordedPath)) === recorded.sha256) {
 			report?.("  ✓ Already current (sha256 matches MANIFEST) — skipping download.")
@@ -92,15 +77,12 @@ export async function fetchIMLSPLS(
 		return { fetched: 0, skipped: 0, failed: 1, failedCodes: [SLUG] }
 	}
 
-	// Discover the outlet-level CSV inside the ZIP.
-	// Outlet files match: pls_fy*outlet*.csv (case-insensitive)
-	// Administrative-entity files match: pls_fy*ae*.csv — we skip those.
+	// Outlet files match `pls_fy*outlet*.csv`; administrative-entity files are skipped.
 	report?.("  Inspecting ZIP contents ...")
 	const entries = (await listZipEntries(zipDest)).map((entry) => entry.name)
 
 	let csvName = entries.find((name) => /pls_fy.*outlet.*\.csv/i.test(name))
 
-	// Fallback: if IMLS renames the file, grab any CSV that is NOT the ae file.
 	if (!csvName) {
 		csvName = entries.find((name) => /\.csv$/i.test(name) && !/system|state|_ae\b|_se\b/i.test(name))
 	}
@@ -119,7 +101,7 @@ export async function fetchIMLSPLS(
 
 	report?.(`  Extracting outlet CSV: ${csvName}`)
 
-	const csvDest = join(destDir, basename(csvName))
+	const csvDest = destDir(basename(csvName))
 
 	await extractZipEntry(zipDest, csvName, csvDest)
 	const csvSize = (await statPath(csvDest)).size
@@ -130,7 +112,7 @@ export async function fetchIMLSPLS(
 	await removePathIfPresent(zipDest)
 	report?.("  Removed ZIP (CSV kept)")
 
-	// MARK: Write MANIFEST
+	// MARK: Write manifest
 
 	const manifest: SourceManifest = {
 		source_url: ZIP_URL,