@mailwoman/corpus 10.0.0 → 10.1.0

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

@@ -3,62 +3,36 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `usgov-nad`: US DOT National Address Database — ~97M structured address-point records.
- *
- *   The single largest US address source available — federal aggregation of state + local 911-grade
- *   address points (every addressable location). Compared to TIGER ADDRFEAT (~20M segment-level, no
- *   city/locality) and NPPES (~7M provider-centric venues), NAD covers the entire residential +
- *   commercial address space with full structured components.
- *
- *   The adapter consumes NDJSON slices produced by `fetch-nad.ts`'s featureserver mode (operator
- *   pre-downloads via `mailwoman corpus fetch nad`). Each slice is per-OID-range
- *   `oids_<start>-<end>.ndjson` with a sibling `.manifest.json`. Adapter iterates every `.ndjson`
- *   in the input directory, skipping the `quarantined-bash-bug/` subdir (legacy of the bash-
- *   fetcher's silent-page-failure bug).
- *
- *   Field mapping (NAD v9 → CanonicalRow components):
- *
- *   - House_number: `AddNo_Full` (pre-composed); falls back to AddNum_Pre + Add_Number + AddNum_Suf
- *   - Street: `StNam_Full` (pre-composed); falls back to St_PreDir + St_PreTyp + St_Name + St_PosTyp
- *
- *       - St_PosDir + St_PosMod composition
- *   - Locality: `Post_City` > `Inc_Muni` > `Census_Plc` > `Uninc_Comm` (first non-empty)
- *   - Region: `State` (2-char USPS code, including territories: PR, GU, VI, AS, MP)
- *   - Postcode: `Zip_Code` + `Plus_4` (joined as `XXXXX-NNNN` when both present)
- *   - Venue: `LandmkName` (typically a park, school, hospital, named facility — when present)
- *
- *   License: stamped `"Public Domain"` per 17 U.S.C. § 105 (US federal works).
+ *   Reads the US DOT National Address Database from a directory of NDJSON files written by the NAD fetcher.
  */
 
-import { formatAddressRow } from "@mailwoman/codex/address-format"
+import { formatAddressRow } from "@mailwoman/codex/address/format"
+import { US_STATE_ABBREVIATIONS } from "@mailwoman/codex/us/state"
 import { tryParsingJSON } from "@mailwoman/core/json"
 import { isPresent } from "@mailwoman/core/objects"
-import { join } from "path-ts"
+import { resolvePathBuilder } from "path-ts"
 import { TextSpliterator } from "spliterator"
 import { Globerator } from "spliterator/node/fs"
 
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "#types"
+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.
+ * The adapter id stamped on every emitted row.
  */
 export const USGOV_NAD_ADAPTER_ID = "usgov-nad"
 /**
- * License carried by this source (Public Domain), attached to each row so downstream consumers inherit the terms rather
- * than having to look them up.
+ * The license label on every emitted row, because US federal works are public domain under 17 U.S.C. § 105.
  */
 export const USGOV_NAD_DEFAULT_LICENSE = "Public Domain"
 
 interface NADRecord {
 	OBJECTID?: number
 	UUID?: string | null
-	// House number
 	AddNum_Pre?: string | null
 	Add_Number?: number | string | null
 	AddNum_Suf?: string | null
 	AddNo_Full?: string | null
-	// Street parts
 	St_PreMod?: string | null
 	St_PreDir?: string | null
 	St_PreTyp?: string | null
@@ -68,7 +42,6 @@ interface NADRecord {
 	St_PosDir?: string | null
 	St_PosMod?: string | null
 	StNam_Full?: string | null
-	// Sub-address (carried as part of street for now; Phase 1 has no unit/floor labels)
 	Building?: string | null
 	Floor?: string | null
 	Unit?: string | null
@@ -76,9 +49,7 @@ interface NADRecord {
 	Seat?: string | null
 	Addtl_Loc?: string | null
 	SubAddress?: string | null
-	// Landmark / venue
 	LandmkName?: string | null
-	// Locality alternates (we prefer Post_City for what a human would type)
 	County?: string | null
 	Inc_Muni?: string | null
 	Post_City?: string | null
@@ -90,71 +61,20 @@ interface NADRecord {
 	Urbnztn_PR?: string | null
 	PlaceOther?: string | null
 	PlaceNmTyp?: string | null
-	// State + ZIP
 	State?: string | null
 	Zip_Code?: string | null
 	Plus_4?: string | null
 }
 
-const US_STATES_SET = new Set([
-	"AL",
-	"AK",
-	"AZ",
-	"AR",
-	"CA",
-	"CO",
-	"CT",
-	"DE",
-	"DC",
-	"FL",
-	"GA",
-	"HI",
-	"ID",
-	"IL",
-	"IN",
-	"IA",
-	"KS",
-	"KY",
-	"LA",
-	"ME",
-	"MD",
-	"MA",
-	"MI",
-	"MN",
-	"MS",
-	"MO",
-	"MT",
-	"NE",
-	"NV",
-	"NH",
-	"NJ",
-	"NM",
-	"NY",
-	"NC",
-	"ND",
-	"OH",
-	"OK",
-	"OR",
-	"PA",
-	"RI",
-	"SC",
-	"SD",
-	"TN",
-	"TX",
-	"UT",
-	"VT",
-	"VA",
-	"WA",
-	"WV",
-	"WI",
-	"WY",
-	// Territories that ship in NAD
-	"PR",
-	"GU",
-	"VI",
-	"AS",
-	"MP",
-])
+/**
+ * The USPS abbreviations a NAD row's `State` must match, taken from codex rather than restated.
+ *
+ * `US_STATE_ABBREVIATIONS` holds the 50 states, the District of Columbia and the five primary territories.
+ * That is the set NAD publishes under, so this adapter keeps no list of its own.
+ *
+ * The two had identical membership when they were reconciled, at 56 entries each.
+ */
+const US_STATES_SET: ReadonlySet<string> = new Set(US_STATE_ABBREVIATIONS)
 
 function nonEmpty(...values: Array<string | null | undefined>): string | undefined {
 	for (const v of values) {
@@ -166,7 +86,15 @@ function nonEmpty(...values: Array<string | null | undefined>): string | undefin
 	return undefined
 }
 
-function composeHouseNumber(r: NADRecord): string | undefined {
+/**
+ * The house number a NAD record states, read from its own four columns.
+ *
+ * NAD publishes `AddNo_Full` already assembled and the parts beside it, so this prefers the
+ * assembled column and falls back to joining `AddNum_Pre`, `Add_Number` and `AddNum_Suf`.
+ * The shared `composeHouseNumber` in `#adapters/street-line` joins exactly two columns with
+ * one separator, so it fits a publisher that splits the number in two rather than in four.
+ */
+function nadHouseNumber(r: NADRecord): string | undefined {
 	const full = (r.AddNo_Full ?? "").toString().trim()
 
 	if (full) return full
@@ -186,6 +114,8 @@ interface DecomposedNADStreet {
 	full: string
 }
 
+// Structured street fields take precedence.
+// If they are empty, `StNam_Full` supplies the whole street.
 function decomposeNADStreet(r: NADRecord): DecomposedNADStreet | undefined {
 	const name = (r.St_Name ?? "").toString().trim()
 
@@ -209,6 +139,7 @@ function decomposeNADStreet(r: NADRecord): DecomposedNADStreet | undefined {
 	return undefined
 }
 
+// The postal city comes first because it is the name that people write on mail.
 function composeLocality(r: NADRecord): string | undefined {
 	return nonEmpty(r.Post_City, r.Inc_Muni, r.Census_Plc, r.Uninc_Comm)
 }
@@ -222,10 +153,19 @@ function composePostcode(r: NADRecord): string | undefined {
 	return plus4 ? `${zip}-${plus4}` : zip
 }
 
+/**
+ * Creates the NAD adapter.
+ *
+ * The adapter skips records without a US state code, locality, or ZIP code.
+ * It also skips rows whose rendering keeps two or fewer components.
+ */
 export function createUsgovNADAdapter(): CorpusAdapter {
 	return {
 		id: USGOV_NAD_ADAPTER_ID,
 		defaultLicense: USGOV_NAD_DEFAULT_LICENSE,
+		addressRole: AddressRole.Premise,
+		register: SourceRegister.NationalAddressDatabase,
+		surface: SurfaceOrigin.Rendered,
 		description:
 			"US DOT National Address Database — ~97M structured US address points (911-grade). Single largest US source.",
 
@@ -234,19 +174,18 @@ export function createUsgovNADAdapter(): CorpusAdapter {
 				throw new Error(`usgov-nad adapter: only US supported, got country=${opts.country}`)
 			}
 
-			// inputPath is a directory of NDJSON slices (per fetch-nad.ts featureserver output).
-			// Single-file inputs (e.g. a bulk-extracted CSV) are not currently supported — the
-			// featureserver slice pattern is the primary distribution.
-			const slices = await Globerator.files("ndjson", { cwd: opts.inputPath, absolute: false }).toSorted()
+			// The input must be a directory of NDJSON files.
+			const files = await Globerator.files("ndjson", {
+				cwd: opts.inputPath,
+				absolute: false,
+				recursive: false,
+			}).toSorted()
 
 			let emitted = 0
-			outer: for (const slice of slices) {
+			outer: for (const file of files) {
 				if (opts.signal?.aborted) break
-				// TextSpliterator streams string lines; the per-line tryParsingJSON below keeps the reader
-				// tolerant of malformed rows (skip silently), so TextSpliterator + a non-throwing parse —
-				// not JSONSpliterator, which would throw. The path string lets the lib own + dispose each
-				// slice's file handle, including on the `break outer` early exit.
-				const lines = TextSpliterator.fromAsync(join(opts.inputPath, slice))
+				// The spliterator closes the file when the loop exits early.
+				const lines = TextSpliterator.fromAsync(resolvePathBuilder(opts.inputPath, file))
 
 				for await (const line of lines) {
 					if (opts.signal?.aborted) break outer
@@ -257,7 +196,7 @@ export function createUsgovNADAdapter(): CorpusAdapter {
 
 					const record = tryParsingJSON<NADRecord>(line)
 
-					if (record === null) continue // malformed line — skip silently
+					if (record === null) continue
 
 					const state = (record.State ?? "").toString().trim().toUpperCase()
 
@@ -272,7 +211,7 @@ export function createUsgovNADAdapter(): CorpusAdapter {
 					if (!postcode) continue
 
 					const decomposed = decomposeNADStreet(record)
-					const houseNumber = composeHouseNumber(record)
+					const houseNumber = nadHouseNumber(record)
 					const venue = nonEmpty(record.LandmkName)
 					const unit = nonEmpty(record.Unit, record.Building, record.Floor, record.Room)
 
@@ -298,7 +237,7 @@ export function createUsgovNADAdapter(): CorpusAdapter {
 
 					const sourceID = record.UUID
 						? `${USGOV_NAD_ADAPTER_ID}-${record.UUID}`
-						: `${USGOV_NAD_ADAPTER_ID}-${record.OBJECTID ?? `${slice}:${emitted}`}`
+						: `${USGOV_NAD_ADAPTER_ID}-${record.OBJECTID ?? `${file}:${emitted}`}`
 
 					yield {
 						raw,
@@ -319,6 +258,6 @@ export function createUsgovNADAdapter(): CorpusAdapter {
 }
 
 /**
- * The configured adapter instance registered with the corpus builder.
+ * The NAD adapter instance that the corpus builder registers.
  */
 export const usgovNADAdapter = createUsgovNADAdapter()

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

@@ -3,41 +3,28 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `usgov-nppes`: CMS National Plan and Provider Enumeration System (NPI registry) CSV consumer.
- *
- *   NPPES is the authoritative US healthcare provider registry, published monthly by CMS. Each row
- *   carries a provider's business practice location address together with their legal business name
- *   or individual name. At ~7M rows it is the single largest venue+address signal source
- *   available.
- *
- *   The adapter consumes the monthly full-replacement CSV (operator pre-downloads via
- *   `fetch-nppes.ts`). Column names match the canonical NPPES "Full Replacement Monthly NPI File"
- *   header published at `https://download.cms.gov/nppes/NPI_Files.html`.
- *
- *   Output: one row per CSV record where the practice location address is populated. Organization
- *   rows carry `venue` from the legal business name; individual rows compose `attention` from
- *   last+first name. Address quad goes on `(house_number, street, locality, region, postcode)`.
- *
- *   License: stamped `"Public Domain"` per CMS's federal government distribution terms.
+ *   Reads provider practice-location addresses from the monthly CMS NPPES full-replacement CSV.
  */
 
-import { formatAddressRow } from "@mailwoman/codex/address-format"
+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 { 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.
+ * The adapter id stamped on every emitted row.
  */
 export const USGOV_NPPES_ADAPTER_ID = "usgov-nppes"
 /**
- * License carried by this source (Public Domain), attached to each row so downstream consumers inherit the terms rather
- * than having to look them up.
+ * 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"
 
@@ -51,13 +38,56 @@ interface NPPESRow {
 	"Provider Second Line Business Practice Location Address": string
 	"Provider Business Practice Location Address City Name": string
 	"Provider Business Practice Location Address State Name": string
-	"Provider Business Practice Location Address Postcode": 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.",
 
@@ -71,22 +101,29 @@ export function createUsgovNPPESAdapter(): CorpusAdapter {
 			})
 
 			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 ?? "").trim()
-				const orgName = (record["Provider Organization Name (Legal Business Name)"] ?? "").trim()
-				const lastName = (record["Provider Last Name (Legal Name)"] ?? "").trim()
-				const firstName = (record["Provider First Name"] ?? "").trim()
-
-				const address1 = (record["Provider First Line Business Practice Location Address"] ?? "").trim()
-				const address2 = (record["Provider Second Line Business Practice Location Address"] ?? "").trim()
-				const city = (record["Provider Business Practice Location Address City Name"] ?? "").trim()
-				const stateRaw = (record["Provider Business Practice Location Address State Name"] ?? "").trim()
-				const postcode = (record["Provider Business Practice Location Address Postcode"] ?? "").trim()
+				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
 
@@ -138,6 +175,6 @@ export function createUsgovNPPESAdapter(): CorpusAdapter {
 }
 
 /**
- * The configured adapter instance registered with the corpus builder.
+ * The NPPES adapter instance that the corpus builder registers.
  */
 export const usgovNPPESAdapter = createUsgovNPPESAdapter()

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

@@ -3,52 +3,57 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `usgov-samhsa-treatment-locator`: SAMHSA Behavioral Health Treatment Services Locator CSV
+ *   `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 carries the facility name, an optional
+ *   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 (#22) selects this source for the same reason
+ *   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 carries
- *   the canonical postal address (`"123 Main St"`); `street2` carries the suite / unit / "second
+ *   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.
+ *   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
+ *   License: stamped `"Public Domain"` per the samhsa Open Data Foundry's 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_SAMHSA_ADAPTER_ID = "usgov-samhsa-treatment-locator"
 /**
- * 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_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.
+ * 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
@@ -59,15 +64,19 @@ interface SamhsaSiteRow {
 	state: string
 	zip: string
 	/**
-	 * Optional. Falls back to `stableSourceID` derived from components when missing.
+	 * 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.
+ * 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()
@@ -83,13 +92,14 @@ function joinTwoLineStreet(street1: string, street2: string | undefined): string
 }
 
 /**
- * Combine `name1` + optional `name2` into a single venue surface form. SAMHSA conventions:
+ * 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.
+ * 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()
@@ -108,6 +118,9 @@ 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.",
 
@@ -130,9 +143,9 @@ export function createUsgovSamhsaTreatmentLocatorAdapter(): CorpusAdapter {
 				const venue = composeVenue(record.name1 ?? "", record.name2)
 				const street = joinTwoLineStreet(record.street1 ?? "", record.street2)
 				const split = splitStreetLine(street)
-				const city = (record.city ?? "").trim()
-				const stateAbbr = (record.state ?? "").trim()
-				const postcode = (record.zip ?? "").trim()
+				const city = record.city ?? ""
+				const stateAbbr = record.state ?? ""
+				const postcode = record.zip ?? ""
 
 				if (!venue || !split || !city || !postcode) continue
 				const state = lookupStateAbbreviation(stateAbbr)
@@ -155,7 +168,7 @@ export function createUsgovSamhsaTreatmentLocatorAdapter(): CorpusAdapter {
 
 				const { raw, components: aligned } = rendered
 
-				const frID = (record.frid ?? "").trim()
+				const frID = record.frid ?? ""
 
 				const sourceID = frID ? `${USGOV_SAMHSA_ADAPTER_ID}-${frID}` : stableSourceID(USGOV_SAMHSA_ADAPTER_ID, aligned)
 

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,7 +88,9 @@ 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 {
 	if (!statefp) return null
@@ -95,16 +99,21 @@ export function lookupFipsState(statefp: string | null | undefined): USStateInfo
 }
 
 /**
- * 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 {
 	if (!abbreviation) return null