@mailwoman/corpus 10.0.0 → 10.2.0

package/lib/us/adapters/tiger/street-decompose.ts

@@ -3,20 +3,13 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Decompose a US street name into Stage 3 components: street_prefix, street, street_suffix.
- *
- *   Sources directionals and street types from the curated libpostal/en dictionaries
- *   (`core/data/libpostal/dictionaries/en/{directionals,street_types}.txt`). These are the same
- *   dictionaries the runtime classifiers (StreetPrefixClassifier, StreetSuffixClassifier) use, so
- *   corpus labels and runtime classifications agree on the vocabulary.
- *
- *   Examples: "N Main St" → { prefix: "N", street: "Main", suffix: "St" } "Pennsylvania Avenue NW" →
- *   { prefix: null, street: "Pennsylvania", suffix: "Avenue NW" } "Salmon St" → { prefix: null,
- *   street: "Salmon", suffix: "St" } "SE Hawthorne Blvd" → { prefix: "SE", street: "Hawthorne",
- *   suffix: "Blvd" }
+ * Decompose a US street name into Stage 3 components (street_prefix, street, street_suffix) from the
+ * curated libpostal/en directionals and street_types dictionaries — the same ones the runtime
+ * StreetPrefixClassifier and StreetSuffixClassifier use, so corpus labels and runtime classifications
+ * agree on the vocabulary.
  */
 
-import { loadLibpostalDictionary } from "#adapters/utils"
+import { loadLibpostalDictionary } from "#adapters/libpostal-dictionary"
 
 const [DIRECTIONALS, STREET_TYPES] = await Promise.all([
 	loadLibpostalDictionary("en", "directionals.txt"),
@@ -32,8 +25,8 @@ export interface DecomposedStreet {
 /**
  * Decompose a US street name into prefix/name/suffix components.
  *
- * Conservative — only emits prefix/suffix when there's a clear directional or street-type keyword. Returns the original
- * as `street` if nothing matches.
+ * Conservative, emitting a prefix or suffix only for a clear directional or street-type keyword.
+ * It returns the original as `street` when no pattern matches.
  */
 export function decomposeStreet(fullname: string): DecomposedStreet {
 	const trimmed = fullname.trim()
@@ -51,13 +44,11 @@ export function decomposeStreet(fullname: string): DecomposedStreet {
 	let startIdx = 0
 	let endIdx = tokens.length
 
-	// Leading directional prefix
 	if (DIRECTIONALS.has(norm(tokens[0]!)) && tokens.length >= 2) {
 		prefix = tokens[0]!
 		startIdx = 1
 	}
 
-	// Trailing post-directional combined with street type (e.g. "Pennsylvania Ave NW")
 	const last = norm(tokens[endIdx - 1]!)
 	const secondLast = endIdx >= 2 ? norm(tokens[endIdx - 2]!) : ""
 
@@ -68,7 +59,6 @@ export function decomposeStreet(fullname: string): DecomposedStreet {
 		suffix = tokens[endIdx - 1]!
 		endIdx -= 1
 	} else if (DIRECTIONALS.has(last) && endIdx - startIdx >= 2) {
-		// Post-directional without type
 		suffix = tokens[endIdx - 1]!
 		endIdx -= 1
 	}

package/lib/us/adapters/usgov/hrsa-fqhc/adapter.ts

@@ -5,23 +5,22 @@
  *
  *   `usgov-hrsa-fqhc`: HRSA "Health Center Service Delivery Site Locations" CSV consumer.
  *
- *   Federally Qualified Health Centers (FQHCs) are HRSA-funded community health programs that
- *   self-report site addresses to the HRSA Data Warehouse. The published CSV (`data.hrsa.gov`)
- *   carries the site name, the postal-formatted street address, and the locality/region/postcode
- *   quad. The source earns its place on adversarial-value-per-row (#22): every facility name is a
- *   human-typed venue string and the addresses pass through enough hands to accumulate the
- *   abbreviation drift + suite designator chaos that pure gazetteer data does not.
+ *   Federally Qualified Health Centers (FQHCs) are HRSA-funded community health programs.
+ *   They self-report site addresses to the HRSA Data Warehouse. The published CSV (`data.hrsa.gov`)
+ *   includes the site name, postal-formatted street address, locality, region and postcode.
+ *   Each facility name is a human-typed venue string. Multiple people have edited each address.
+ *   That editing introduces abbreviation drift and suite designators absent from gazetteer data.
  *
  *   The adapter consumes a CSV file the operator pre-downloads. The HRSA data is published as a
  *   single national CSV (~10K rows), small enough that the operator can re-fetch on every corpus
  *   rebuild without an intermediate SQLite step. Column names below match the HRSA Data Warehouse's
  *   "Health Center Service Delivery Site" public dataset. Operators substituting the
- *   closely-related "Site Address" or "Health Center" public extracts may need to remap columns;
- *   the README documents the expected set.
+ *   closely-related "Site Address" or "Health Center" public extracts may need to remap columns.
+ *   the readme documents the expected set.
  *
  *   Output: one row per CSV record, with `venue` component carrying the site name and the address
  *   quad on `(house_number, street, locality, region, postcode)`. Component order is critical:
- *   `venue` is inserted FIRST so alignment claims its surface span before `locality` searches for
+ *   `venue` is inserted first so alignment claims its surface span before `locality` searches for
  *   its own (the kryptonite case "Buffalo Health Clinic, …, Buffalo, NY" relies on `venue`
  *   consuming the first "Buffalo" so locality lands on the second).
  *
@@ -29,28 +28,33 @@
  *   terms.
  */
 
-import { formatAddressRow } from "@mailwoman/codex/address-format"
+import { formatAddressRow } from "@mailwoman/codex/address/format"
 import { CSVSpliterator } from "spliterator"
 
-import { splitStreetLine, stableSourceID } from "#adapters/utils"
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "#types"
+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.
+ * 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_HRSA_FQHC_ADAPTER_ID = "usgov-hrsa-fqhc"
 /**
- * License carried by this source (Public Domain), attached to each row so downstream consumers inherit the terms rather
- * than having to look them up.
+ * 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_HRSA_FQHC_DEFAULT_LICENSE = "Public Domain"
 
 /**
- * Subset of HRSA "Health Center Service Delivery Site Locations" CSV columns consulted by the adapter. Column names
- * match the canonical HRSA Data Warehouse export header. Operators substituting a closely-related extract should rename
- * columns to match; the README has the mapping cheatsheet.
+ * Subset of HRSA "Health Center Service Delivery Site Locations" CSV columns consulted by the adapter.
+ *
+ * Column names match the canonical HRSA Data Warehouse export header.
+ * Operators substituting a closely-related extract should rename columns to match.
+ * The readme has the mapping cheatsheet.
  */
 interface HRSASiteRow {
 	"Site Name": string
@@ -59,25 +63,36 @@ interface HRSASiteRow {
 	"Site State Abbreviation": string
 	"Site Postal Code": string
 	/**
-	 * Optional. Falls back to `stableSourceID` derived from components when missing.
+	 * Optional.
+	 *
+	 * Falls back to `stableSourceID` derived from components when missing.
 	 */
 	"Site ID"?: string
 }
 
 /**
- * Split a "123 Main St Suite 4" surface form into `(house_number, street)`. The regex tolerates one trailing letter on
- * the number (`"123A Main St"`) and a hyphenated form (`"40-12 Bell Blvd"`); anything else falls back to street-only.
+ * Split a "123 Main St Suite 4" surface form into `(house_number, street)`.
+ *
+ * The regex tolerates one trailing letter on the number (`"123A Main St"`)
+ * and a hyphenated form (`"40-12 Bell Blvd"`); anything else falls back to street-only.
+ *
+ * Suite / Apt / Unit designators stay on `street`.
+ * Mailwoman's `unit` component exists.
+ *
+ * The address formatter has no clean slot for it.
+ * HRSA addresses also keep the suite in the street column.
  *
- * Suite / Apt / Unit designators stay on `street` — Mailwoman's `unit` component exists but the address-formatter does
- * not have a clean slot for it, and HRSA addresses do not separate the suite into its own column. Leaving the surface
- * form intact in `street` preserves the adversarial training signal (the model learns that a trailing "Suite 4" is part
- * of the road line in this distribution).
+ * The intact surface form in `street` keeps the adversarial training signal
+ * (the model learns that a trailing "Suite 4" is part of the road line in this distribution).
  */
 
 export function createUSGovHRSAFQHCAdapter(): CorpusAdapter {
 	return {
 		id: USGOV_HRSA_FQHC_ADAPTER_ID,
 		defaultLicense: USGOV_HRSA_FQHC_DEFAULT_LICENSE,
+		addressRole: AddressRole.Facility,
+		register: SourceRegister.HRSAHealthCenters,
+		surface: SurfaceOrigin.Rendered,
 		description:
 			"HRSA Federally Qualified Health Center site locations (public-domain). Adversarial source: venue + address co-occurrence, hand-entered.",
 
@@ -97,20 +112,20 @@ export function createUSGovHRSAFQHCAdapter(): CorpusAdapter {
 
 				if (opts.limit !== undefined && emitted >= opts.limit) break
 
-				const venue = (record["Site Name"] ?? "").trim()
+				const venue = record["Site Name"] ?? ""
 				const split = splitStreetLine(record["Site Address"] ?? "")
-				const city = (record["Site City"] ?? "").trim()
-				const stateAbbr = (record["Site State Abbreviation"] ?? "").trim()
-				const postcode = (record["Site Postal Code"] ?? "").trim()
+				const city = record["Site City"] ?? ""
+				const stateAbbr = record["Site State Abbreviation"] ?? ""
+				const postcode = record["Site Postal Code"] ?? ""
 
 				if (!venue || !split || !city || !postcode) continue
 				const state = lookupStateAbbreviation(stateAbbr)
 
 				if (!state) continue
 
-				// Insertion order matters here. `venue` first so alignment claims its span
-				// (which may contain a token like "Buffalo") before `locality` runs its
-				// search — the kryptonite case `Buffalo Health Clinic, Buffalo NY`
+				// Insertion order matters here.
+				// `venue` first so alignment claims its span (which may contain a token like "Buffalo")
+				// before `locality` runs its search — the kryptonite case `Buffalo Health Clinic, Buffalo NY`
 				// otherwise mis-labels the venue's "Buffalo" as locality.
 				const components: CanonicalRow["components"] = {
 					venue,
@@ -127,7 +142,7 @@ export function createUSGovHRSAFQHCAdapter(): CorpusAdapter {
 
 				const { raw, components: aligned } = rendered
 
-				const siteID = (record["Site ID"] ?? "").trim()
+				const siteID = record["Site ID"] ?? ""
 
 				const sourceID = siteID
 					? `${USGOV_HRSA_FQHC_ADAPTER_ID}-${siteID}`

package/lib/us/adapters/usgov/imls-pls/adapter.ts

@@ -6,8 +6,8 @@
  *   `usgov-imls-pls`: IMLS Public Libraries Survey outlet CSV consumer.
  *
  *   The Institute of Museum and Library Services publishes an annual Public Libraries Survey with one
- *   row per library outlet (~17K rows). Each row carries the library name, street address, city,
- *   ZIP, county, and geocoordinates.
+ *   row per library outlet (~17K rows). Each row includes the library name, street address, city,
+ *   ZIP, county and geocoordinates.
  *
  *   The adapter consumes the outlet CSV the operator pre-downloads via `fetch-imls-pls.ts`. Column
  *   names match the IMLS PLS outlet file header.
@@ -18,21 +18,24 @@
  *   License: stamped `"Public Domain"` per IMLS federal government distribution terms.
  */
 
-import { formatAddressRow } from "@mailwoman/codex/address-format"
+import { formatAddressRow } from "@mailwoman/codex/address/format"
 import { CSVSpliterator } from "spliterator"
 
-import { splitStreetLine, stableSourceID } from "#adapters/utils"
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "#types"
+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.
+ * 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_IMLS_PLS_ADAPTER_ID = "usgov-imls-pls"
 /**
- * License carried by this source (Public Domain), attached to each row so downstream consumers inherit the terms rather
- * than having to look them up.
+ * 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_IMLS_PLS_DEFAULT_LICENSE = "Public Domain"
 
@@ -50,6 +53,9 @@ export function createUSGovIMLSPLSAdapter(): CorpusAdapter {
 	return {
 		id: USGOV_IMLS_PLS_ADAPTER_ID,
 		defaultLicense: USGOV_IMLS_PLS_DEFAULT_LICENSE,
+		addressRole: AddressRole.Facility,
+		register: SourceRegister.IMLSPublicLibraries,
+		surface: SurfaceOrigin.Rendered,
 		description: "IMLS Public Libraries Survey — ~17K library outlets with venue+address (public-domain).",
 
 		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
@@ -68,11 +74,11 @@ export function createUSGovIMLSPLSAdapter(): CorpusAdapter {
 
 				if (opts.limit !== undefined && emitted >= opts.limit) break
 
-				const libName = (record.LIBNAME ?? "").trim()
-				const address = (record.ADDRESS ?? "").trim()
-				const city = (record.CITY ?? "").trim()
-				const zip = (record.ZIP ?? "").trim()
-				const stateAbbr = (record.STABR ?? "").trim()
+				const libName = record.LIBNAME ?? ""
+				const address = record.ADDRESS ?? ""
+				const city = record.CITY ?? ""
+				const zip = record.ZIP ?? ""
+				const stateAbbr = record.STABR ?? ""
 
 				if (!libName || !city || !zip) continue
 
@@ -91,10 +97,10 @@ export function createUSGovIMLSPLSAdapter(): CorpusAdapter {
 					locality: city,
 					region: state.abbreviation,
 					postcode: zip,
-					// #552: no subregion — US postal addresses don't surface the county, so emitting
-					// subregion creates a phantom component with no raw-span to align to, quarantining
-					// ~21% of rows. The county is still available in the source CSV; it just isn't
-					// a postal-surface component here.
+					// No subregion: US postal addresses don't surface the county, so emitting subregion
+					// creates a phantom component with no raw-span to align to, quarantining ~21% of rows.
+					// The county is still available in the source CSV.
+					// It is not a postal-surface component here.
 				}
 
 				const rendered = formatAddressRow(components, "US", { singleLine: true })
@@ -105,7 +111,7 @@ export function createUSGovIMLSPLSAdapter(): CorpusAdapter {
 
 				if (Object.keys(aligned).length <= 2) continue
 
-				const fscsKey = (record.FSCSKEY ?? "").trim()
+				const fscsKey = record.FSCSKEY ?? ""
 
 				const sourceID = fscsKey
 					? `${USGOV_IMLS_PLS_ADAPTER_ID}-${fscsKey}`

package/lib/us/adapters/usgov/irs-bmf/adapter.ts

@@ -8,36 +8,41 @@
  *   The EO BMF is the IRS's authoritative registry of US tax-exempt organizations (charities,
  *   churches, foundations, ...), published as per-region CSVs at
  *   `https://www.irs.gov/charities-non-profits/exempt-organizations-business-master-file-extract-eo-bmf`
- *   (`eo1.csv`..`eo4.csv`, `eo_pr.csv`, `eo_xx.csv`). Each row carries an organization NAME plus
- *   its mailing address. It complements `usgov-nppes` with a DIFFERENT venue population
+ *   (`eo1.csv`..`eo4.csv`, `eo_pr.csv`, `eo_xx.csv`). Each row includes an organization name plus
+ *   its mailing address. It complements `usgov-nppes` with a different venue population
  *   (non-profits vs healthcare providers) and, notably, a high share of PO-box addresses — useful
  *   `po_box`-tag signal (a tag with historically low recall).
  *
- *   Output: one row per record with a usable city + postcode. NAME → `venue`; the street line becomes
- *   `po_box` when it's a PO-box, else `house_number` + `street`; CITY/STATE/ZIP fill the locality
- *   line. STATE is already a USPS abbreviation in the source. License: `"Public Domain"` (US
+ *   Output: one row per record with a usable city + postcode. name → `venue`; the street line becomes
+ *   `po_box` when it's a PO-box, else `house_number` + `street`; city/state/ZIP fill the locality
+ *   line. state is already a USPS abbreviation in the source. License: `"Public Domain"` (US
  *   federal).
  */
 
-import { formatAddressRow } from "@mailwoman/codex/address-format"
+import { formatAddressRow } from "@mailwoman/codex/address/format"
 import { CSVSpliterator } from "spliterator"
 
-import { splitStreetLine, stableSourceID } from "#adapters/utils"
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "#types"
+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"
 
 /**
- * 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.
+ * 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_IRS_BMF_ADAPTER_ID = "usgov-irs-bmf"
 /**
- * License carried by this source (Public Domain), attached to each row so downstream consumers inherit the terms rather
- * than having to look them up.
+ * 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_IRS_BMF_DEFAULT_LICENSE = "Public Domain"
 
 /**
- * PO box in its many written forms: "PO BOX 12", "P.O. BOX 12", "P O BOX 12", "POB 12", "BOX 12".
+ * PO box in its many written forms: "PO BOX 12", "P.O.
+ *
+ * BOX 12", "P O BOX 12", "POB 12", "BOX 12".
  */
 const PO_BOX = /^\s*(?:P\.?\s?O\.?\s*BOX|POB|BOX)\s+\w/i
 
@@ -53,9 +58,10 @@ interface IRSBMFRow {
 /**
  * Classify the street line into a `po_box` or a `{house_number?, street}` split.
  *
- * BMF mixes street addresses and PO boxes in one `STREET` column, so the PO-box shapes have to be claimed BEFORE the
- * shared house-number split runs — otherwise `splitStreetLine` would hand back `"PO Box 1234"` as a plain street, which
- * is correct for every other US adapter and wrong here.
+ * BMF mixes street addresses and PO boxes in one `street` column, so the PO-box shapes
+ * have to be claimed before the shared house-number split runs.
+ * Otherwise `splitStreetLine` would hand back `"PO Box 1234"` as a plain street.
+ * which is correct for every other US adapter and wrong here.
  */
 function splitStreetLineOrPOBox(street: string): { po_box: string } | { house_number?: string; street: string } | null {
 	const trimmed = street.trim()
@@ -69,6 +75,9 @@ export function createUSGovIRSBMFAdapter(): CorpusAdapter {
 	return {
 		id: USGOV_IRS_BMF_ADAPTER_ID,
 		defaultLicense: USGOV_IRS_BMF_DEFAULT_LICENSE,
+		addressRole: AddressRole.Mailing,
+		register: SourceRegister.IRSBusinessMasterFile,
+		surface: SurfaceOrigin.Rendered,
 		description:
 			"IRS Exempt Organizations Business Master File — US non-profit venue+address (public-domain), with strong PO-box coverage.",
 
@@ -88,15 +97,15 @@ export function createUSGovIRSBMFAdapter(): CorpusAdapter {
 
 				if (opts.limit !== undefined && emitted >= opts.limit) break
 
-				const ein = (record.EIN ?? "").trim()
-				const venue = (record.NAME ?? "").trim() || undefined
-				const street = (record.STREET ?? "").trim()
-				const city = (record.CITY ?? "").trim()
-				const state = (record.STATE ?? "").trim()
-				const zipRaw = (record.ZIP ?? "").trim()
+				const ein = record.EIN ?? ""
+				const venue = (record.NAME ?? "") || undefined
+				const street = record.STREET ?? ""
+				const city = record.CITY ?? ""
+				const state = record.STATE ?? ""
+				const zipRaw = record.ZIP ?? ""
 
 				if (!city || !zipRaw) continue
-				const postcode = zipRaw.split("-")[0]!.trim() // 5-digit; drop the optional +4
+				const postcode = zipRaw.split("-")[0]!.trim() // 5-digit. drop the optional +4
 
 				const split = splitStreetLineOrPOBox(street)