@mailwoman/corpus 10.0.0 → 10.2.0

package/out/{synthesizers → us/synthesizers}/street.js

@@ -7,28 +7,30 @@
  *   `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 { pick, tieredNumber } from "#synthesizers/utils";
+import { sample } from "@mailwoman/core/random";
+import { layoutAdminTail } from "#synthesizers/tail";
+import { tieredNumber } from "#synthesizers/utils";
 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",
     "Oak",
@@ -151,9 +153,9 @@ const TRAILING_DIRECTIONALS = [
     "SW",
 ];
 function randomHouseNumber(random) {
-    // 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 },
@@ -162,39 +164,44 @@ function randomHouseNumber(random) {
     ]);
 }
 /**
- * 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(base, opts = {}) {
     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);
-    // Build the "full" street string the adapter would receive from TIGER FULLNAME.
+    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.
     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 = 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 = tail ? { ...tail.components } : {};
     if (decomposed.prefix) {
         components.street_prefix = decomposed.prefix;
     }
@@ -208,10 +215,10 @@ export function synthesizeStreetRow(base, opts = {}) {
     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/out/us/synthesizers/street.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"street.js","sourceRoot":"","sources":["../../../lib/us/synthesizers/street.ts"],"names":[],"mappings":"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"}

package/out/us/tools/fetch/hrsa.d.ts

@@ -6,13 +6,13 @@
  *   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>`.
  */
-import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download/index";
+import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download";
 export type FetchHRSAOptions = BaseFetchOptions;
 export declare function fetchHRSA(options: FetchHRSAOptions, report?: (line: string) => void): Promise<FetchSummary>;
 //# sourceMappingURL=hrsa.d.ts.map

package/out/us/tools/fetch/hrsa.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hrsa.d.ts","sourceRoot":"","sources":["../../../../lib/us/tools/fetch/hrsa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAkB,MAAM,6BAA6B,CAAA;AAOjG,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,CAAA;AAE/C,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CA8BjH"}
+{"version":3,"file":"hrsa.d.ts","sourceRoot":"","sources":["../../../../lib/us/tools/fetch/hrsa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAkB,MAAM,uBAAuB,CAAA;AAO3F,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,CAAA;AAE/C,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CA8BjH"}

package/out/us/tools/fetch/hrsa.js

@@ -6,23 +6,22 @@
  *   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>`.
  */
 import { makeDirectories } from "@mailwoman/core/fs/writers";
 import { sha256File } from "@mailwoman/core/hash";
-import { join } from "path-ts";
-import { downloadToFile, writeManifest } from "#tools/fetch/download/index";
+import { downloadToFile, writeManifest } from "#tools/fetch/download";
 const SLUG = "usgov-hrsa-fqhc";
 const FILENAME = "Health_Center_Service_Delivery_and_LookAlike_Sites.csv";
 const SOURCE_URL = `https://data.hrsa.gov/DataDownload/DD_Files/${FILENAME}`;
 export async function fetchHRSA(options, report) {
-    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}`);
     const { bytes } = await downloadToFile({
         url: SOURCE_URL,
@@ -39,7 +38,7 @@ export async function fetchHRSA(options, report) {
         sha256: sha,
         bytes,
     };
-    await writeManifest(join(destDir, "MANIFEST.json"), manifest);
+    await writeManifest(destDir("MANIFEST.json"), manifest);
     report?.(`  ✓ ${(bytes / 1024 / 1024).toFixed(1)} MB  sha256=${sha}`);
     return { fetched: 1, skipped: 0, failed: 0, failedCodes: [] };
 }

package/out/us/tools/fetch/hrsa.js.map

@@ -1 +1 @@
-{"version":3,"file":"hrsa.js","sourceRoot":"","sources":["../../../../lib/us/tools/fetch/hrsa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AAG9B,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAE3E,MAAM,IAAI,GAAG,iBAAiB,CAAA;AAC9B,MAAM,QAAQ,GAAG,wDAAwD,CAAA;AACzE,MAAM,UAAU,GAAG,+CAA+C,QAAQ,EAAE,CAAA;AAI5E,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAyB,EAAE,MAA+B;IACzF,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;IAC3C,MAAM,eAAe,CAAC,OAAO,CAAC,CAAA;IAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;IAEpC,MAAM,EAAE,CAAC,OAAO,IAAI,MAAM,QAAQ,EAAE,CAAC,CAAA;IAErC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,cAAc,CAAC;QACtC,GAAG,EAAE,UAAU;QACf,IAAI;QACJ,SAAS,EAAE,OAAO;QAClB,OAAO,EAAE,EAAE,iBAAiB,EAAE,UAAU,EAAE;QAC1C,MAAM;KACN,CAAC,CAAA;IAEF,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,CAAA;IAElC,MAAM,QAAQ,GAAmB;QAChC,UAAU,EAAE,UAAU;QACtB,aAAa,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACvC,QAAQ,EAAE,QAAQ;QAClB,MAAM,EAAE,GAAG;QACX,KAAK;KACL,CAAA;IAED,MAAM,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE,QAAQ,CAAC,CAAA;IAE7D,MAAM,EAAE,CAAC,OAAO,CAAC,KAAK,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,GAAG,EAAE,CAAC,CAAA;IAErE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,CAAA;AAC9D,CAAC"}
+{"version":3,"file":"hrsa.js","sourceRoot":"","sources":["../../../../lib/us/tools/fetch/hrsa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAGjD,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAErE,MAAM,IAAI,GAAG,iBAAiB,CAAA;AAC9B,MAAM,QAAQ,GAAG,wDAAwD,CAAA;AACzE,MAAM,UAAU,GAAG,+CAA+C,QAAQ,EAAE,CAAA;AAI5E,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAyB,EAAE,MAA+B;IACzF,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,MAAM,eAAe,CAAC,OAAO,CAAC,CAAA;IAC9B,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAE9B,MAAM,EAAE,CAAC,OAAO,IAAI,MAAM,QAAQ,EAAE,CAAC,CAAA;IAErC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,cAAc,CAAC;QACtC,GAAG,EAAE,UAAU;QACf,IAAI;QACJ,SAAS,EAAE,OAAO;QAClB,OAAO,EAAE,EAAE,iBAAiB,EAAE,UAAU,EAAE;QAC1C,MAAM;KACN,CAAC,CAAA;IAEF,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,CAAA;IAElC,MAAM,QAAQ,GAAmB;QAChC,UAAU,EAAE,UAAU;QACtB,aAAa,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACvC,QAAQ,EAAE,QAAQ;QAClB,MAAM,EAAE,GAAG;QACX,KAAK;KACL,CAAA;IAED,MAAM,aAAa,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,CAAA;IAEvD,MAAM,EAAE,CAAC,OAAO,CAAC,KAAK,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,GAAG,EAAE,CAAC,CAAA;IAErE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,CAAA;AAC9D,CAAC"}

package/out/us/tools/fetch/imls-pls.d.ts

@@ -3,23 +3,12 @@
  * @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.
  */
-import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download/index";
+import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download";
 export type FetchIMLSPLSOptions = BaseFetchOptions;
 export declare function fetchIMLSPLS(options: FetchIMLSPLSOptions, report?: (line: string) => void): Promise<FetchSummary>;
 //# sourceMappingURL=imls-pls.d.ts.map

package/out/us/tools/fetch/imls-pls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"imls-pls.d.ts","sourceRoot":"","sources":["../../../../lib/us/tools/fetch/imls-pls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAYH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAkB,MAAM,6BAA6B,CAAA;AAcjG,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAAA;AAElD,wBAAsB,YAAY,CACjC,OAAO,EAAE,mBAAmB,EAC5B,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC7B,OAAO,CAAC,YAAY,CAAC,CAiGvB"}
+{"version":3,"file":"imls-pls.d.ts","sourceRoot":"","sources":["../../../../lib/us/tools/fetch/imls-pls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAYH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAkB,MAAM,uBAAuB,CAAA;AAU3F,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAAA;AAElD,wBAAsB,YAAY,CACjC,OAAO,EAAE,mBAAmB,EAC5B,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC7B,OAAO,CAAC,YAAY,CAAC,CA8FvB"}

package/out/us/tools/fetch/imls-pls.js

@@ -3,50 +3,36 @@
  * @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 { 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 { basename } from "path-ts";
+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";
 export async function fetchIMLSPLS(options, report) {
-    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}`);
     // MARK: Idempotency check
     const recorded = await readManifest(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.");
             return { fetched: 0, skipped: 1, failed: 0, failedCodes: [] };
@@ -66,13 +52,10 @@ export async function fetchIMLSPLS(options, report) {
         report?.(`  ✗ Response too small (${zipSize} bytes) — probable error page`);
         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));
     }
@@ -85,14 +68,14 @@ export async function fetchIMLSPLS(options, report) {
         return { fetched: 0, skipped: 0, failed: 1, failedCodes: [SLUG] };
     }
     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;
     const csvSha = await sha256File(csvDest);
     // MARK: Remove ZIP (small, but keep destDir clean)
     await removePathIfPresent(zipDest);
     report?.("  Removed ZIP (CSV kept)");
-    // MARK: Write MANIFEST
+    // MARK: Write manifest
     const manifest = {
         source_url: ZIP_URL,
         downloaded_at: new Date().toISOString(),

package/out/us/tools/fetch/imls-pls.js.map

@@ -1 +1 @@
-{"version":3,"file":"imls-pls.js","sourceRoot":"","sources":["../../../../lib/us/tools/fetch/imls-pls.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"imls-pls.js","sourceRoot":"","sources":["../../../../lib/us/tools/fetch/imls-pls.ts"],"names":[],"mappings":"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"}

package/out/us/tools/fetch/nad.d.ts

@@ -4,7 +4,7 @@
  * @author Teffen Ellis, et al.
  *
  *   Fetch the US DOT National Address Database (NAD) — ~97 million structured US address-point
- *   records aggregated from state and local authorities. Source for the `usgov-nad` adapter (#30).
+ *   records aggregated from state and local authorities. Source for the `usgov-nad` adapter.
  *   US Public Domain (17 U.S.C. § 105).
  *
  *   - Bounded per-chunk page concurrency (4× speedup at safe pressure)
@@ -20,8 +20,8 @@
  *   - **`bulk`** mode requires a pre-signed S3 URL (Akamai blocks scripted curl on the DOT page). Pass
  *       `--nad-url <presigned>` from a browser visit to
  *       [https://www.transportation.gov/gis/national-address-database](https://www.transportation.gov/gis/national-address-database).
- *   - **`featureserver`** mode (default) pages the live FeatureService via OBJECTID ranges, writing
- *       NDJSON chunks into `<outRoot>/usgov-nad/featureserver/`.
+ *   - **`featureserver`** mode (default) pages the live FeatureService via objectid ranges, writing
+ *       ndjson chunks into `<outRoot>/usgov-nad/featureserver/`.
  *
  *   ## Usage
  *
@@ -35,10 +35,12 @@
  *   mailwoman corpus fetch nad --concurrency 8 --page-size 10000
  *   ```
  */
-import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download/index";
+import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download";
 export interface FetchNADOptions extends BaseFetchOptions {
     /**
-     * Fetch strategy. Default `featureserver`.
+     * Fetch strategy.
+     *
+     * @defaultValue `featureserver`
      */
     mode?: "featureserver" | "bulk";
     /**
@@ -46,23 +48,33 @@ export interface FetchNADOptions extends BaseFetchOptions {
      */
     nadURL?: string;
     /**
-     * Records per output file. Default `100000`.
+     * Records per output file.
+     *
+     * @defaultValue `100000`
      */
     chunkSize?: number;
     /**
-     * Records per HTTP request. Default `5000`.
+     * Records per http request.
+     *
+     * @defaultValue `5000`
      */
     pageSize?: number;
     /**
-     * Parallel page fetches within a chunk. Default `4`.
+     * Parallel page fetches within a chunk.
+     *
+     * @defaultValue `4`
      */
     concurrency?: number;
     /**
-     * Start OBJECTID. Default `1`.
+     * Start objectid.
+     *
+     * @defaultValue `1`
      */
     startOID?: number;
     /**
-     * Stop before this OID. Default = total count.
+     * Stop before this OID.
+     *
+     * @defaultValue = total count.
      */
     endOID?: number;
 }

package/out/us/tools/fetch/nad.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nad.d.ts","sourceRoot":"","sources":["../../../../lib/us/tools/fetch/nad.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAQH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAQjF,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACxD;;OAEG;IACH,IAAI,CAAC,EAAE,eAAe,GAAG,MAAM,CAAA;IAC/B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAuPD,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAY/G"}
+{"version":3,"file":"nad.d.ts","sourceRoot":"","sources":["../../../../lib/us/tools/fetch/nad.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AASH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAQ3E,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACxD;;;;OAIG;IACH,IAAI,CAAC,EAAE,eAAe,GAAG,MAAM,CAAA;IAC/B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AA4PD,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAY/G"}

package/out/us/tools/fetch/nad.js

@@ -4,7 +4,7 @@
  * @author Teffen Ellis, et al.
  *
  *   Fetch the US DOT National Address Database (NAD) — ~97 million structured US address-point
- *   records aggregated from state and local authorities. Source for the `usgov-nad` adapter (#30).
+ *   records aggregated from state and local authorities. Source for the `usgov-nad` adapter.
  *   US Public Domain (17 U.S.C. § 105).
  *
  *   - Bounded per-chunk page concurrency (4× speedup at safe pressure)
@@ -20,8 +20,8 @@
  *   - **`bulk`** mode requires a pre-signed S3 URL (Akamai blocks scripted curl on the DOT page). Pass
  *       `--nad-url <presigned>` from a browser visit to
  *       [https://www.transportation.gov/gis/national-address-database](https://www.transportation.gov/gis/national-address-database).
- *   - **`featureserver`** mode (default) pages the live FeatureService via OBJECTID ranges, writing
- *       NDJSON chunks into `<outRoot>/usgov-nad/featureserver/`.
+ *   - **`featureserver`** mode (default) pages the live FeatureService via objectid ranges, writing
+ *       ndjson chunks into `<outRoot>/usgov-nad/featureserver/`.
  *
  *   ## Usage
  *
@@ -36,17 +36,19 @@
  *   ```
  */
 import { APIClient, pluckResponseData } from "@mailwoman/core/api";
-import { statPath, pathExists } from "@mailwoman/core/fs/readers";
+import { statPath, pathExists } from "@mailwoman/core/fs/readers/stat";
 import { makeDirectories, writeLocalTextFile } from "@mailwoman/core/fs/writers";
 import { sha256File } from "@mailwoman/core/hash";
-import { join } from "path-ts";
-import { downloadToFile, readManifest, writeManifest } from "#tools/fetch/download/index";
+import { stringifyJSON } from "@mailwoman/core/json";
+import { downloadToFile, readManifest, writeManifest } from "#tools/fetch/download";
 const SLUG = "usgov-nad";
 const FEATURE_SERVICE_URL = "https://services.arcgis.com/xOi1kZaI0eWDREZv/ArcGIS/rest/services/Address_Points_from_National_Address_Database_view/FeatureServer/0";
 /**
- * ArcGIS paged reads. Retry is ON: the loop walks OBJECTID ranges to completion, so one throttled page previously ended
- * a multi-hour national download. No rate budget — pages are requested one at a time and each assembles thousands of
- * records server-side.
+ * ArcGIS paged reads.
+ *
+ * Retry is on: the loop walks objectid ranges to completion, since one throttled
+ * page can otherwise end a multi-hour national download.
+ * No rate budget — pages are requested one at a time and each assembles thousands of records server-side.
  */
 const nadClient = new APIClient({
     displayName: "nad",
@@ -82,17 +84,20 @@ async function discoverTotalCount() {
     return data.count;
 }
 /**
- * Fetch a single chunk by paging through its OID range with bounded concurrency. Returns the count of records written
- * and the count of pages that errored. The caller decides whether to mark the chunk complete based on errors === 0.
+ * Fetch a single chunk by paging through its OID range with bounded concurrency.
+ *
+ * Returns the count of records written and the count of pages that errored.
+ * The caller decides whether to mark the chunk complete based on errors === 0.
  *
- * NOTE(phase1): this is a JSON API pager, not a file download — the shared `downloadToFile` doesn't apply here.
+ * Note(phase1): this is a JSON API pager rather than a file download —
+ * the shared `downloadToFile` doesn't apply here.
  */
 async function fetchChunk(chunkPath, chunkStart, chunkEnd, pageSize, concurrency, report) {
     const pageRanges = [];
     for (let cursor = chunkStart; cursor <= chunkEnd; cursor += pageSize) {
         pageRanges.push([cursor, Math.min(cursor + pageSize - 1, chunkEnd)]);
     }
-    // Run bounded-concurrency page fetches. Results indexed by page slot for in-order write.
+    // Results indexed by page slot for in-order write.
     const pageResults = pageRanges.map(() => ({
         rows: [],
         error: null,
@@ -114,7 +119,7 @@ async function fetchChunk(chunkPath, chunkStart, chunkEnd, pageSize, concurrency
         }
     });
     await Promise.all(workers);
-    // Single-writer phase — write all pages in OID order to keep NDJSON deterministic.
+    // Single-writer phase — write all pages in OID order to keep ndjson deterministic.
     const lines = [];
     let errors = 0;
     for (const { rows, error } of pageResults) {
@@ -123,10 +128,10 @@ async function fetchChunk(chunkPath, chunkStart, chunkEnd, pageSize, concurrency
             continue;
         }
         for (const row of rows) {
-            lines.push(JSON.stringify(row));
+            lines.push(stringifyJSON(row));
         }
     }
-    await writeLocalTextFile(!lines.length ? "" : lines.join("\n") + "\n", chunkPath);
+    await writeLocalTextFile(lines, chunkPath);
     return { recordCount: lines.length, errors };
 }
 async function featureserverMode(options, report) {
@@ -134,7 +139,7 @@ async function featureserverMode(options, report) {
     const pageSize = options.pageSize ?? 5000;
     const concurrency = options.concurrency ?? 4;
     const startOID = options.startOID ?? 1;
-    const chunkDir = join(options.outRoot, SLUG, "featureserver");
+    const chunkDir = options.outRoot(SLUG, "featureserver");
     await makeDirectories(chunkDir);
     report?.(`=== ${SLUG} / featureserver`);
     report?.(`  Discovering record count ...`);
@@ -151,10 +156,10 @@ async function featureserverMode(options, report) {
     for (let cursor = startOID; cursor <= endOID; cursor += chunkSize) {
         const chunkEnd = Math.min(cursor + chunkSize - 1, endOID);
         const chunkName = `oids_${cursor}-${chunkEnd}`;
-        const chunkPath = join(chunkDir, `${chunkName}.ndjson`);
-        const manifestPath = join(chunkDir, `${chunkName}.manifest.json`);
-        // Idempotency: skip a chunk only if it's marked complete (the bash version's bug was
-        // marking complete on partial-failure runs; we now only set complete after a clean fetch).
+        const chunkPath = chunkDir(`${chunkName}.ndjson`);
+        const manifestPath = chunkDir(`${chunkName}.manifest.json`);
+        // Idempotency: skip a chunk only when its manifest is marked complete.
+        // Complete is set only after a clean fetch.
         if (await pathExists(chunkPath)) {
             const recorded = await readManifest(manifestPath);
             if (recorded?.complete) {
@@ -194,7 +199,7 @@ async function featureserverMode(options, report) {
     report?.(`total records: ${totalRecords.toLocaleString()}`);
     report?.(`page errors:   ${totalErrors}`);
     report?.(`output:        ${chunkDir}`);
-    // `failed` counts page errors (the old exit-1 condition), `failedCodes` names the dirty chunks.
+    // `failed` counts page errors and `failedCodes` records the dirty chunks.
     return { fetched, skipped, failed: totalErrors, failedCodes };
 }
 async function bulkMode(options, report) {
@@ -203,15 +208,15 @@ async function bulkMode(options, report) {
             `visit https://www.transportation.gov/gis/national-address-database in a browser, ` +
             `accept the disclaimer, and re-run with the pre-signed S3 URL.`);
     }
-    const destDir = join(options.outRoot, SLUG);
+    const destDir = options.outRoot(SLUG);
     await makeDirectories(destDir);
     const filename = new URL(options.nadURL).pathname.split("/").pop() ?? "NAD.zip";
-    const destPath = join(destDir, filename);
+    const destPath = destDir(filename);
     report?.(`=== ${SLUG} / ${filename}`);
     report?.(`  URL: ${options.nadURL.slice(0, 100)}${options.nadURL.length > 100 ? "…" : ""}`);
     const { bytes } = await downloadToFile({ url: options.nadURL, dest: destPath, timeoutMs: 3 * 3600 * 1000, report });
     const sha = await sha256File(destPath);
-    await writeManifest(join(destDir, "MANIFEST.json"), {
+    await writeManifest(destDir("MANIFEST.json"), {
         source_url: options.nadURL,
         downloaded_at: new Date().toISOString(),
         filename,