@mailwoman/corpus 9.4.0 → 10.1.0

package/lib/us/adapters/usgov/nppes/adapter.ts

@@ -0,0 +1,180 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Reads provider practice-location addresses from the monthly CMS NPPES full-replacement CSV.
+ */
+
+import { formatAddressRow } from "@mailwoman/codex/address/format"
+import { stringifyJSON } from "@mailwoman/core/json"
+import { isPresent } from "@mailwoman/core/objects"
+import { formatPersonName } from "@mailwoman/record/name"
+import type { PathBuilderLike } from "path-ts"
+import { CSVSpliterator } from "spliterator"
+
+import { stableSourceID } from "#adapters/source-id"
+import { splitStreetLine } from "#adapters/street-line"
+import { SourceRegister } from "#registers"
+import { AddressRole, type AdapterOptions, type CanonicalRow, type CorpusAdapter, SurfaceOrigin } from "#types"
+import { lookupStateAbbreviation } from "#us/fips-state"
+
+/**
+ * The adapter id stamped on every emitted row.
+ */
+export const USGOV_NPPES_ADAPTER_ID = "usgov-nppes"
+/**
+ * The license label on every emitted row, because CMS distributes NPPES as a federal public-domain work.
+ */
+export const USGOV_NPPES_DEFAULT_LICENSE = "Public Domain"
+
+interface NPPESRow {
+	NPI: string
+	"Entity Type Code": string
+	"Provider Organization Name (Legal Business Name)": string
+	"Provider Last Name (Legal Name)": string
+	"Provider First Name": string
+	"Provider First Line Business Practice Location Address": string
+	"Provider Second Line Business Practice Location Address": string
+	"Provider Business Practice Location Address City Name": string
+	"Provider Business Practice Location Address State Name": string
+	// This is the publisher's exact column name, so it must keep the words "Postal Code".
+	"Provider Business Practice Location Address Postal Code": string
+}
+
+/**
+ * The columns that every emitted row needs, in the publisher's spelling.
+ *
+ * A missing column reads as `undefined` on every record.
+ * The row filter would then drop every row without an error.
+ */
+const REQUIRED_COLUMNS = [
+	"Provider First Line Business Practice Location Address",
+	"Provider Business Practice Location Address City Name",
+	"Provider Business Practice Location Address State Name",
+	"Provider Business Practice Location Address Postal Code",
+] as const
+
+/**
+ * Throws when the first parsed record lacks a required practice-location column.
+ *
+ * The check reads the parsed record's keys, so it sees the column names exactly
+ * as the CSV reader produced them.
+ */
+function assertPracticeLocationColumns(record: NPPESRow, inputPath: PathBuilderLike): void {
+	const present = new Set(Object.keys(record))
+	const missing = REQUIRED_COLUMNS.filter((column) => !present.has(column))
+
+	if (!missing.length) return
+
+	throw new Error(
+		`usgov-nppes adapter: ${inputPath} carries none of ${missing.map((column) => stringifyJSON(column)).join(", ")}. ` +
+			`Every row would be dropped and the run would report zero rows read from a file it read in full. ` +
+			`Check the publisher's own spelling against this adapter's column names.`
+	)
+}
+
+/**
+ * Creates the NPPES adapter.
+ *
+ * Each row's `venue` is the organization's legal name or, for an individual provider,
+ * the formatted person name.
+ * The adapter skips records without a city, a postcode, a known state or a parseable street line.
+ */
+export function createUsgovNPPESAdapter(): CorpusAdapter {
+	return {
+		id: USGOV_NPPES_ADAPTER_ID,
+		defaultLicense: USGOV_NPPES_DEFAULT_LICENSE,
+		addressRole: AddressRole.Practice,
+		register: SourceRegister.NPPES,
+		surface: SurfaceOrigin.Rendered,
+		description:
+			"CMS National Plan and Provider Enumeration System — 7M provider practice locations (public-domain). Venue+address co-occurrence at scale.",
+
+		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
+			if (opts.country && opts.country !== "US") {
+				throw new Error(`usgov-nppes adapter: only US supported, got country=${opts.country}`)
+			}
+
+			const rows = CSVSpliterator.fromAsync(opts.inputPath, {
+				normalizeKeys: false,
+			})
+
+			let emitted = 0
+			let checkedHeader = false
+
+			for await (const record of rows as AsyncIterable<NPPESRow>) {
+				if (opts.signal?.aborted) break
+
+				if (opts.limit !== undefined && emitted >= opts.limit) break
+
+				const npi = record.NPI ?? ""
+				const orgName = record["Provider Organization Name (Legal Business Name)"] ?? ""
+				const lastName = record["Provider Last Name (Legal Name)"] ?? ""
+				const firstName = record["Provider First Name"] ?? ""
+
+				const address1 = record["Provider First Line Business Practice Location Address"] ?? ""
+				const address2 = record["Provider Second Line Business Practice Location Address"] ?? ""
+				const city = record["Provider Business Practice Location Address City Name"] ?? ""
+				const stateRaw = record["Provider Business Practice Location Address State Name"] ?? ""
+				const postcode = record["Provider Business Practice Location Address Postal Code"] ?? ""
+
+				// The first record's keys reveal a renamed column before the filters below drop every row.
+				if (!checkedHeader) {
+					checkedHeader = true
+					assertPracticeLocationColumns(record, opts.inputPath)
+				}
+
+				if (!city || !postcode) continue
+
+				const state = lookupStateAbbreviation(stateRaw)
+
+				if (!state) continue
+
+				const fullStreet = [address1, address2].filter(isPresent).join(" ")
+				const split = splitStreetLine(fullStreet)
+
+				if (!split) continue
+
+				const venue = orgName || formatPersonName({ given: firstName, family: lastName }, "short") || undefined
+
+				const components: CanonicalRow["components"] = {
+					...(venue ? { venue } : {}),
+					...(split.house_number ? { house_number: split.house_number } : {}),
+					street: split.street,
+					locality: city,
+					region: state.abbreviation,
+					postcode,
+				}
+
+				const rendered = formatAddressRow(components, "US", { singleLine: true })
+
+				if (!rendered) continue
+
+				const { raw, components: aligned } = rendered
+
+				if (Object.keys(aligned).length <= 2) continue
+
+				const sourceID = npi ? `${USGOV_NPPES_ADAPTER_ID}-${npi}` : stableSourceID(USGOV_NPPES_ADAPTER_ID, aligned)
+
+				yield {
+					raw,
+					components: aligned,
+					country: "US",
+					locale: "en-US",
+					source: USGOV_NPPES_ADAPTER_ID,
+					source_id: sourceID,
+					corpus_version: "",
+					license: USGOV_NPPES_DEFAULT_LICENSE,
+				}
+
+				emitted++
+			}
+		},
+	}
+}
+
+/**
+ * The NPPES adapter instance that the corpus builder registers.
+ */
+export const usgovNPPESAdapter = createUsgovNPPESAdapter()

package/lib/us/adapters/usgov/samhsa-treatment-locator/adapter.ts

@@ -0,0 +1,195 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `usgov-samhsa-treatment-locator`: samhsa Behavioral Health Treatment Services Locator CSV
+ *   consumer.
+ *
+ *   samhsa's Treatment Locator (`findtreatment.gov`) is the federal directory of substance-use and
+ *   mental-health treatment facilities. The published CSV includes the facility name, an optional
+ *   secondary name (typically the organizational parent), and the postal address quad split into
+ *   primary + secondary street lines. Phase 1.6 §1.2 selects this source for the same reason
+ *   it selects HRSA: facility names are hand-typed venue strings and the addresses pass through
+ *   enough human + system hands to accumulate the suite-designator + sub-tenant chaos ("Suite C,
+ *   behind main building") that pure gazetteer data does not.
+ *
+ *   samhsa's two-line address shape is the key adapter-specific concern. `street1` typically contains
+ *   the canonical postal address (`"123 Main St"`); `street2` contains the suite / unit / "second
+ *   floor" surface form. The adapter joins them with `", "` into a single `street` component (Phase
+ *   1 keeps `unit` as a deferred slot since the OpenCage template doesn't have a clean rendering
+ *   for it). Operators wanting a different join policy can subclass the factory.
+ *
+ *   Column names below match the canonical samhsa Behavioral Health Treatment Services Locator CSV
+ *   export header. Operators substituting a closely-related extract should rename columns to match.
+ *   the readme has the mapping cheatsheet.
+ *
+ *   License: stamped `"Public Domain"` per the samhsa Open Data Foundry's federal-government
+ *   distribution terms.
+ */
+
+import { formatAddressRow } from "@mailwoman/codex/address/format"
+import { CSVSpliterator } from "spliterator"
+
+import { stableSourceID } from "#adapters/source-id"
+import { splitStreetLine } from "#adapters/street-line"
+import { SourceRegister } from "#registers"
+import { AddressRole, type AdapterOptions, type CanonicalRow, type CorpusAdapter, SurfaceOrigin } from "#types"
+import { lookupStateAbbreviation } from "#us/fips-state"
+
+/**
+ * Registry id for this adapter.
+ *
+ * Stamped into every row it emits, so a corpus record can be traced back to the dataset it came from.
+ */
+export const USGOV_SAMHSA_ADAPTER_ID = "usgov-samhsa-treatment-locator"
+/**
+ * License assigned by this source (Public Domain), attached to each row so downstream
+ * consumers inherit the terms rather than having to look them up.
+ */
+export const USGOV_SAMHSA_DEFAULT_LICENSE = "Public Domain"
+
+/**
+ * Subset of samhsa Treatment Locator CSV columns consulted by the adapter.
+ *
+ * Column names match the canonical samhsa Open Data Foundry export header.
+ * `name1` is the venue; `name2` is optional and folded into the venue when present.
+ */
+interface SamhsaSiteRow {
+	name1: string
+	name2?: string
+	street1: string
+	street2?: string
+	city: string
+	state: string
+	zip: string
+	/**
+	 * Optional.
+	 *
+	 * Falls back to `stableSourceID` derived from components when missing.
+	 */
+	frid?: string
+}
+
+/**
+ * Join the samhsa two-line street: primary street + optional secondary line
+ * (suite / unit / floor / "behind main building") on `", "`.
+ *
+ * The combined value is the `street` component surface form.
+ * Phase 1 does not break this out into the `unit` component — see the file-level comment.
+ */
+function joinTwoLineStreet(street1: string, street2: string | undefined): string {
+	const s1 = street1.trim()
+	const s2 = (street2 ?? "").trim()
+
+	if (!s1 && !s2) return ""
+
+	if (!s2) return s1
+
+	if (!s1) return s2
+
+	return `${s1}, ${s2}`
+}
+
+/**
+ * Combine `name1` + optional `name2` into a single venue surface form.
+ * Samhsa conventions:
+ *
+ * - `name1` is the program / clinic name ("Mountain Plains Counseling Services").
+ * - `name2` is the parent organization ("Catholic Charities of Wyoming"), if any.
+ *
+ * Both render together as `"<name1> - <name2>"` when both are present — geocoder users
+ * typically type either form, so the model benefits from the joined surface.
+ */
+function composeVenue(name1: string, name2: string | undefined): string {
+	const n1 = name1.trim()
+	const n2 = (name2 ?? "").trim()
+
+	if (!n1 && !n2) return ""
+
+	if (!n2) return n1
+
+	if (!n1) return n2
+
+	return `${n1} - ${n2}`
+}
+
+export function createUsgovSamhsaTreatmentLocatorAdapter(): CorpusAdapter {
+	return {
+		id: USGOV_SAMHSA_ADAPTER_ID,
+		defaultLicense: USGOV_SAMHSA_DEFAULT_LICENSE,
+		addressRole: AddressRole.Facility,
+		register: SourceRegister.SAMHSATreatmentLocator,
+		surface: SurfaceOrigin.Rendered,
+		description:
+			"SAMHSA Behavioral Health Treatment Services Locator (public-domain). Adversarial source: venue + two-line address co-occurrence, hand-entered.",
+
+		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
+			if (opts.country && opts.country !== "US") {
+				throw new Error(`usgov-samhsa adapter: only US supported, got country=${opts.country}`)
+			}
+
+			const rows = CSVSpliterator.fromAsync(opts.inputPath, {
+				normalizeKeys: false,
+			})
+
+			let emitted = 0
+
+			for await (const record of rows as AsyncIterable<SamhsaSiteRow>) {
+				if (opts.signal?.aborted) break
+
+				if (opts.limit !== undefined && emitted >= opts.limit) break
+
+				const venue = composeVenue(record.name1 ?? "", record.name2)
+				const street = joinTwoLineStreet(record.street1 ?? "", record.street2)
+				const split = splitStreetLine(street)
+				const city = record.city ?? ""
+				const stateAbbr = record.state ?? ""
+				const postcode = record.zip ?? ""
+
+				if (!venue || !split || !city || !postcode) continue
+				const state = lookupStateAbbreviation(stateAbbr)
+
+				if (!state) continue
+
+				// venue first — same kryptonite-defending insertion order as HRSA.
+				const components: CanonicalRow["components"] = {
+					venue,
+					...(split.house_number ? { house_number: split.house_number } : {}),
+					street: split.street,
+					locality: city,
+					region: state.abbreviation,
+					postcode,
+				}
+
+				const rendered = formatAddressRow(components, "US", { singleLine: true })
+
+				if (!rendered) continue
+
+				const { raw, components: aligned } = rendered
+
+				const frID = record.frid ?? ""
+
+				const sourceID = frID ? `${USGOV_SAMHSA_ADAPTER_ID}-${frID}` : stableSourceID(USGOV_SAMHSA_ADAPTER_ID, aligned)
+
+				yield {
+					raw,
+					components: aligned,
+					country: "US",
+					locale: "en-US",
+					source: USGOV_SAMHSA_ADAPTER_ID,
+					source_id: sourceID,
+					corpus_version: "",
+					license: USGOV_SAMHSA_DEFAULT_LICENSE,
+				}
+
+				emitted++
+			}
+		},
+	}
+}
+
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const usgovSamhsaTreatmentLocatorAdapter = createUsgovSamhsaTreatmentLocatorAdapter()

package/lib/us/fips-state.ts

@@ -0,0 +1,122 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   US Census FIPS state codes → two-letter abbreviation + full display name.
+ *
+ *   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
+ *   `statefp` columns (e.g. `"50"`) into a `region` component (e.g. `"VT"`) without an extra DB
+ *   join.
+ */
+
+/**
+ * Per-state record: two-letter postal abbreviation + full canonical display name.
+ */
+export interface USStateInfo {
+	abbreviation: string
+	name: string
+}
+
+/**
+ * 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" },
+	"02": { abbreviation: "AK", name: "Alaska" },
+	"04": { abbreviation: "AZ", name: "Arizona" },
+	"05": { abbreviation: "AR", name: "Arkansas" },
+	"06": { abbreviation: "CA", name: "California" },
+	"08": { abbreviation: "CO", name: "Colorado" },
+	"09": { abbreviation: "CT", name: "Connecticut" },
+	"10": { abbreviation: "DE", name: "Delaware" },
+	"11": { abbreviation: "DC", name: "District of Columbia" },
+	"12": { abbreviation: "FL", name: "Florida" },
+	"13": { abbreviation: "GA", name: "Georgia" },
+	"15": { abbreviation: "HI", name: "Hawaii" },
+	"16": { abbreviation: "ID", name: "Idaho" },
+	"17": { abbreviation: "IL", name: "Illinois" },
+	"18": { abbreviation: "IN", name: "Indiana" },
+	"19": { abbreviation: "IA", name: "Iowa" },
+	"20": { abbreviation: "KS", name: "Kansas" },
+	"21": { abbreviation: "KY", name: "Kentucky" },
+	"22": { abbreviation: "LA", name: "Louisiana" },
+	"23": { abbreviation: "ME", name: "Maine" },
+	"24": { abbreviation: "MD", name: "Maryland" },
+	"25": { abbreviation: "MA", name: "Massachusetts" },
+	"26": { abbreviation: "MI", name: "Michigan" },
+	"27": { abbreviation: "MN", name: "Minnesota" },
+	"28": { abbreviation: "MS", name: "Mississippi" },
+	"29": { abbreviation: "MO", name: "Missouri" },
+	"30": { abbreviation: "MT", name: "Montana" },
+	"31": { abbreviation: "NE", name: "Nebraska" },
+	"32": { abbreviation: "NV", name: "Nevada" },
+	"33": { abbreviation: "NH", name: "New Hampshire" },
+	"34": { abbreviation: "NJ", name: "New Jersey" },
+	"35": { abbreviation: "NM", name: "New Mexico" },
+	"36": { abbreviation: "NY", name: "New York" },
+	"37": { abbreviation: "NC", name: "North Carolina" },
+	"38": { abbreviation: "ND", name: "North Dakota" },
+	"39": { abbreviation: "OH", name: "Ohio" },
+	"40": { abbreviation: "OK", name: "Oklahoma" },
+	"41": { abbreviation: "OR", name: "Oregon" },
+	"42": { abbreviation: "PA", name: "Pennsylvania" },
+	"44": { abbreviation: "RI", name: "Rhode Island" },
+	"45": { abbreviation: "SC", name: "South Carolina" },
+	"46": { abbreviation: "SD", name: "South Dakota" },
+	"47": { abbreviation: "TN", name: "Tennessee" },
+	"48": { abbreviation: "TX", name: "Texas" },
+	"49": { abbreviation: "UT", name: "Utah" },
+	"50": { abbreviation: "VT", name: "Vermont" },
+	"51": { abbreviation: "VA", name: "Virginia" },
+	"53": { abbreviation: "WA", name: "Washington" },
+	"54": { abbreviation: "WV", name: "West Virginia" },
+	"55": { abbreviation: "WI", name: "Wisconsin" },
+	"56": { abbreviation: "WY", name: "Wyoming" },
+	// Territories
+	"60": { abbreviation: "AS", name: "American Samoa" },
+	"66": { abbreviation: "GU", name: "Guam" },
+	"69": { abbreviation: "MP", name: "Northern Mariana Islands" },
+	"72": { abbreviation: "PR", name: "Puerto Rico" },
+	"78": { abbreviation: "VI", name: "Virgin Islands" },
+})
+
+/**
+ * Lookup helper.
+ *
+ * @returns Null when the FIPS code isn't recognized.
+ */
+export function lookupFipsState(statefp: string | null | undefined): 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).
+ */
+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.
+ */
+export function lookupStateAbbreviation(abbreviation: string | null | undefined): USStateInfo | null {
+	if (!abbreviation) return null
+
+	return US_STATE_BY_ABBREVIATION[abbreviation.toUpperCase()] ?? null
+}

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

@@ -0,0 +1,58 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   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. 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 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"
+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 = options.outRoot(SLUG)
+	await makeDirectories(destDir)
+	const dest = destDir(FILENAME)
+
+	report?.(`=== ${SLUG} / ${FILENAME}`)
+
+	const { bytes } = await downloadToFile({
+		url: SOURCE_URL,
+		dest,
+		timeoutMs: 600_000,
+		headers: { "Accept-Encoding": "gzip, br" },
+		report,
+	})
+
+	const sha = await sha256File(dest)
+
+	const manifest: SourceManifest = {
+		source_url: SOURCE_URL,
+		downloaded_at: new Date().toISOString(),
+		filename: FILENAME,
+		sha256: sha,
+		bytes,
+	}
+
+	await writeManifest(destDir("MANIFEST.json"), manifest)
+
+	report?.(`  ✓ ${(bytes / 1024 / 1024).toFixed(1)} MB  sha256=${sha}`)
+
+	return { fetched: 1, skipped: 0, failed: 0, failedCodes: [] }
+}

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

@@ -0,0 +1,131 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * 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 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 { makeDirectories, removePathIfPresent } from "@mailwoman/core/fs/writers"
+import { extractZipEntry, listZipEntries } from "@mailwoman/core/fs/zip"
+import { sha256File } from "@mailwoman/core/hash"
+import { basename } from "path-ts"
+
+import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetch/download"
+import { downloadToFile, readManifest, writeManifest } from "#tools/fetch/download"
+
+/**
+ * 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 type FetchIMLSPLSOptions = BaseFetchOptions
+
+export async function fetchIMLSPLS(
+	options: FetchIMLSPLSOptions,
+	report?: (line: string) => void
+): Promise<FetchSummary> {
+	const destDir = options.outRoot(SLUG)
+	await makeDirectories(destDir)
+
+	const zipDest = destDir(basename(ZIP_URL))
+	const manifestPath = destDir("MANIFEST.json")
+
+	report?.(`=== ${SLUG}`)
+
+	// MARK: Idempotency check
+
+	const recorded = await readManifest<Partial<SourceManifest>>(manifestPath)
+
+	if (recorded?.sha256 && 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: [] }
+		}
+	}
+
+	// MARK: Download ZIP
+
+	report?.(`  Downloading ${ZIP_URL} ...`)
+
+	const { bytes: zipSize } = await downloadToFile({
+		url: ZIP_URL,
+		dest: zipDest,
+		timeoutMs: 600_000,
+		headers: { "Accept-Encoding": "gzip, br" },
+		report,
+	})
+
+	report?.(`  Downloaded: ${ByteFormatter.formatIEC(zipSize)}`)
+
+	if (zipSize < BYTES_PER_KIB) {
+		report?.(`  ✗ Response too small (${zipSize} bytes) — probable error page`)
+
+		return { fetched: 0, skipped: 0, failed: 1, failedCodes: [SLUG] }
+	}
+
+	// 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))
+
+	if (!csvName) {
+		csvName = entries.find((name) => /\.csv$/i.test(name) && !/system|state|_ae\b|_se\b/i.test(name))
+	}
+
+	if (!csvName) {
+		report?.("  Available files in ZIP:")
+
+		for (const name of entries) {
+			report?.(`    ${name}`)
+		}
+
+		report?.("  ✗ Could not identify outlet CSV — inspect above listing and update this module")
+
+		return { fetched: 0, skipped: 0, failed: 1, failedCodes: [SLUG] }
+	}
+
+	report?.(`  Extracting outlet CSV: ${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
+
+	const manifest: SourceManifest = {
+		source_url: ZIP_URL,
+		downloaded_at: new Date().toISOString(),
+		filename: basename(csvName),
+		sha256: csvSha,
+		bytes: csvSize,
+	}
+
+	await writeManifest(manifestPath, manifest)
+
+	report?.(`  ✓ ${(csvSize / 1024 / 1024).toFixed(1)} MB  sha256=${csvSha}`)
+	report?.(`  MANIFEST written to ${manifestPath}`)
+
+	return { fetched: 1, skipped: 0, failed: 0, failedCodes: [] }
+}