@mailwoman/corpus 10.0.0 → 10.2.0

package/lib/us/adapters/fcc-bdc/adapter.ts

@@ -3,58 +3,43 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `fcc-bdc`: FCC Broadband Data Collection (BDC) — Fabric-derived location consumer.
+ *   `fcc-bdc`: FCC Broadband Data Collection (BDC) adapter.
  *
- *   The first member of Phase 1.6's "adversarial sources" class. BDC ships the public-domain US
- *   broadband-serviceable-location (BSL) fabric: ~120M addresses keyed by stable `location_id`,
- *   carrying `address_primary` + `city` + `state` + `zip` + `zip_suffix`. Compared to the clean
- *   gazetteer rows from WOF / TIGER / BAN, BDC carries the chaos of address data that has passed
- *   through several layers of human entry + automated geocoding + revision: abbreviation drift,
- *   inconsistent unit designators, "RR" / "HC" / "PSC" rural-route shapes, embedded apartment /
- *   suite numbers that did not survive the address parser cleanly. This is the highest-signal,
- *   hardest-to-normalize address corpus in the federal public-domain catalog.
+ *   Reads BDC Fabric addresses from a prebuilt SQLite database.
+ * 	 Note that Fabric IDs are managed by CostQuest and may be subject to licensing or usage restrictions.
  *
- *   Following the `tiger` / `wof-admin` pattern, this adapter consumes a SQLite database the operator
- *   pre-builds via the isp-nexus BDC ETL (`/srv/isp-nexus/sync/fcc/bdc/`) or any equivalent
- *   host-side pipeline. The mailwoman side does not download or parse the raw CSV/ZIP distribution
- *   directly — that keeps the adapter narrow and the BDC ingest pluggable.
+ *   Each row is keyed by `location_id` and includes:
+ *   `address_primary`, `city`, `state`, `zip`, and `zip_suffix`.
  *
- *   The SQLite schema is documented in README.md and modeled after `NTIARecord`
- *   (`isp-nexus/fcc/bdc/data-collection.ts`): one row per `location_id`. The adapter splits
- *   `address_primary` into `house_number` (leading numeric prefix, if any) + `street` (everything
- *   after), and combines `zip` + `zip_suffix` into the canonical USPS `postcode` slot.
+ *   This adapter does not download raw BDC files.
  *
- *   One CanonicalRow per fabric record. Unlike `tiger` (multiple postcode variants per segment) or
- *   `wof-admin` (multiple hierarchy variants per place), BDC records already represent fully
- *   specified addresses; no fan-out is warranted. Adversarial composition (Phase 1.6 §2.1) is the
- *   mechanism for deriving multiple training rows per BDC record.
+ *   It converts each source row into one CanonicalRow by:
+ *   - splitting `address_primary` into `house_number` + `street`
+ *   - combining `zip` + `zip_suffix` into `postcode`
  *
- *   License: stamped `"Public Domain"` per the BDC fabric's US federal-government distribution terms.
- *   The CostQuest Fabric source data has its own license; consumers who substitute that path should
- *   re-stamp accordingly.
+ *   Rows are stamped with the source license: `"Public Domain"`.
  */
 
 import type { BDCDatabase } from "@mailwoman/bdc/schema"
-import { formatAddressRow } from "@mailwoman/codex/address-format"
+import { formatAddressRow } from "@mailwoman/codex/address/format"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { splitStreetLine } from "#adapters/utils"
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "#types"
+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.
+ * Stable registry id for this adapter.
  */
 export const FCC_BDC_ADAPTER_ID = "fcc-bdc"
 /**
- * License carried by this source (Public Domain), attached to each row so downstream consumers inherit the terms rather
- * than having to look them up.
+ * Default license stamped on emitted rows.
  */
 export const FCC_BDC_DEFAULT_LICENSE = "Public Domain"
 
 /**
- * SQLite row shape — one row per BSL `location_id`. Columns mirror NTIARecord.
+ * SQLite row shape (one row per `location_id`).
  */
 interface BdcLocationRow {
 	location_id: number
@@ -66,16 +51,14 @@ interface BdcLocationRow {
 }
 
 /**
- * Combine `zip` + optional `zip_suffix` into the canonical USPS postcode surface form.
- *
- * NTIARecord doc is ambiguous about whether `zip_suffix` is the 4-digit extension alone or the full ZIP+4 string. This
- * handles both:
+ * Build USPS postcode from `zip` and optional `zip_suffix`.
+ * Handles both a 4-digit suffix and a full ZIP+4 value.
  *
  * - Bare 4-digit extension (`zip="94103"`, `zip_suffix="1234"`) → `"94103-1234"`
  * - Already-joined form (`zip_suffix="94103-1234"`) → returned as-is
  * - No suffix → bare `zip`
  *
- * Empty / whitespace-only suffix is treated as missing.
+ * Empty/whitespace suffix is treated as missing.
  */
 export function buildPostcode(zip: string, suffix: string | null): string {
 	const z = zip.trim()
@@ -91,14 +74,16 @@ export function buildPostcode(zip: string, suffix: string | null): string {
 }
 
 /**
- * Build a BDC adapter. Pure factory so multiple instances can be created in tests.
+ * Build the BDC corpus adapter.
  */
 export function createFccBdcAdapter(): CorpusAdapter {
 	return {
 		id: FCC_BDC_ADAPTER_ID,
 		defaultLicense: FCC_BDC_DEFAULT_LICENSE,
-		description:
-			"FCC Broadband Data Collection — Fabric-derived BSL addresses (public-domain); SQLite DB the operator builds via the isp-nexus BDC ETL.",
+		addressRole: AddressRole.Premise,
+		register: SourceRegister.FCCBroadbandData,
+		surface: SurfaceOrigin.Rendered,
+		description: "FCC Broadband Data Collection — Fabric-derived BSL addresses (public-domain).",
 
 		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
 			if (opts.country && opts.country !== "US") {
@@ -168,6 +153,6 @@ export function createFccBdcAdapter(): CorpusAdapter {
 }
 
 /**
- * The configured adapter instance registered with the corpus builder.
+ * Default configured adapter instance.
  */
 export const fccBdcAdapter = createFccBdcAdapter()

package/lib/us/adapters/state/hi-schools/adapter.ts

@@ -5,21 +5,21 @@
  *
  *   `state-hi-schools`: Hawaii DOE public + charter school workbook consumer.
  *
- *   The Hawaii State Department of Education publishes a directory of all HIDOE schools and public
- *   charter schools (PCS) as an XLSX workbook (`SchoolList.xlsx`) with two sheets: `HIDOE` (~258
- *   rows) and `PCS` (~38 rows). Total ~296 rows statewide. Each row carries a school name,
+ *   The Hawaii State Department of Education publishes a directory of all hidoe schools and public
+ *   charter schools (PCS) as an xlsx workbook (`SchoolList.xlsx`) with two sheets: `hidoe` (~258
+ *   rows) and `PCS` (~38 rows). Total ~296 rows statewide. Each row includes a school name,
  *   single-line street address, city, ZIP, a numeric `code`, and HI-specific administrative columns
  *   (complex, complex_area, district, island, charter).
  *
- *   The adapter consumes the original XLSX retained by the fetcher and reads both worksheets directly.
+ *   The adapter consumes the original xlsx retained by the fetcher and reads both worksheets directly.
  *   Legacy flat CSV artifacts remain accepted so existing source caches do not need conversion.
  *
  *   Address parsing notes: Hawaii's residential numbering is hyphenated on Oahu (`47-470 Hui Aeko
  *   Place`), Kauai (`2-4035 Kaumualii Hwy`), and elsewhere. The shared HOUSE_NUMBER_PREFIX regex
  *   covers this via its optional `(?:-\d+)?` group.
  *
- *   The `island` and `district` columns are HIDOE administrative labels (Honolulu, Central, Leeward,
- *   Windward, Hilo, Hawaii, Maui, Kauai) — they are NOT US counties and intentionally are not
+ *   The `island` and `district` columns are hidoe administrative labels (Honolulu, Central, Leeward,
+ *   Windward, Hilo, Hawaii, Maui, Kauai) — they are not US counties and intentionally are not
  *   surfaced as `subregion`.
  *
  *   Output: one row per school with `venue` (school name), `(house_number?, street, locality,
@@ -28,22 +28,26 @@
  *   License: stamped `"Public Domain"` per Hawaii state government open-data terms.
  */
 
-import { formatAddressRow } from "@mailwoman/codex/address-format"
+import { formatAddressRow } from "@mailwoman/codex/address/format"
+import type { PathBuilderLike } from "path-ts"
 import { CSVSpliterator, XLSXSpliterator } 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 { type HiSchoolRow, schoolCellText, STATE_HI_SCHOOL_SHEETS } from "#us/adapters/state/hi-schools/workbook"
 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 STATE_HI_SCHOOLS_ADAPTER_ID = "state-hi-schools"
 /**
- * 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 STATE_HI_SCHOOLS_DEFAULT_LICENSE = "Public Domain"
 
@@ -54,15 +58,19 @@ function normalizeZip(raw: HiSchoolRow["zip"]): string {
 
 	if (!trimmed) return ""
 
-	// XLSX → CSV conversion may emit numeric ZIPs without leading zeros. HI ZIPs all begin
-	// with 96, so a 4-digit value indicates a leading-zero stripped during numeric coercion
-	// (defensive — has not been observed in the published file as of 2026-05).
+	// xlsx → CSV conversion may emit numeric ZIPs without leading zeros.
+	// HI ZIPs all begin with 96, so a 4-digit value indicates a leading-zero stripped during
+	// numeric coercion (defensive — has not been observed in the published file as of 2026-05).
 	if (/^\d{4}$/.test(trimmed)) return `0${trimmed}`
 
 	return trimmed
 }
 
-async function* readSchoolRows(inputPath: string): AsyncGenerator<HiSchoolRow> {
+async function* readSchoolRows(source: PathBuilderLike): AsyncGenerator<HiSchoolRow> {
+	// XLSXSpliterator opens a string, URL, or byte source.
+	// A PathBuilder is none of those.
+	const inputPath = source.toString()
+
 	if (inputPath.toLowerCase().endsWith(".xlsx")) {
 		for (const sheet of STATE_HI_SCHOOL_SHEETS) {
 			yield* XLSXSpliterator.fromAsync<HiSchoolRow>(inputPath, {
@@ -83,6 +91,9 @@ export function createStateHiSchoolsAdapter(): CorpusAdapter {
 	return {
 		id: STATE_HI_SCHOOLS_ADAPTER_ID,
 		defaultLicense: STATE_HI_SCHOOLS_DEFAULT_LICENSE,
+		addressRole: AddressRole.Facility,
+		register: SourceRegister.HawaiiSchools,
+		surface: SurfaceOrigin.Rendered,
 		description: "Hawaii DOE School Directory — ~300 K-12 public + charter schools with venue+address (public-domain).",
 
 		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {

package/lib/us/adapters/state/hi-schools/workbook.ts

@@ -12,12 +12,17 @@ import type { XLSXCellValue } from "spliterator"
 export const STATE_HI_SCHOOL_SHEETS = ["HIDOE", "PCS"] as const
 
 /**
- * Columns required to construct a corpus row. Fetch validation uses the same contract as the adapter.
+ * Columns required to construct a corpus row.
+ *
+ * Fetch validation uses the same interface as the adapter.
  */
 export const STATE_HI_SCHOOL_REQUIRED_COLUMNS = ["code", "name", "address", "city", "zip"] as const
 
 /**
- * Workbook row fields consumed by the adapter. XLSX cells are typed; the legacy CSV path supplies strings.
+ * Workbook row fields consumed by the adapter.
+ *
+ * Xlsx cells are typed.
+ * The legacy CSV path supplies strings.
  */
 export interface HiSchoolRow {
 	code: XLSXCellValue | undefined
@@ -30,6 +35,6 @@ export interface HiSchoolRow {
 /**
  * Convert a typed workbook cell or legacy CSV field to the trimmed text used by the corpus row.
  */
-export function schoolCellText(value: XLSXCellValue | undefined): string {
+export function schoolCellText(value: XLSXCellValue | null | undefined): string {
 	return value === null || value === undefined ? "" : String(value).trim()
 }

package/lib/us/adapters/state/ia-contractors/adapter.ts

@@ -6,32 +6,41 @@
  *   `state-ia-contractors`: Iowa Active Construction Contractor Registrations CSV consumer.
  *
  *   Iowa Workforce Development publishes a public registry of active construction contractors. Each
- *   row carries a business name, street address, city/state/zip, and contact info.
+ *   row includes a business name, street address, city/state/zip and contact info.
  *
  *   The adapter consumes the CSV the operator pre-downloads via `fetch-state-sources.ts`.
  *
  *   Output: one row per contractor with `venue` (business name) and address quad `(house_number,
  *   street, locality, region, postcode)`.
  *
+ *   The id spells the publisher's own word for the trade. Iowa titles the dataset `IA Active
+ *   Construction Contractor Registrations`, and the root instructions preserve an external name. The
+ *   id is also stored as data: it is the `source` string on every row of a built corpus and the key a
+ *   training config's `source_weights` map addresses, so renaming it strands every corpus built
+ *   before the rename.
+ *
  *   License: stamped `"Public Domain"` per Iowa state government open-data terms.
  */
 
-import { formatAddressRow } from "@mailwoman/codex/address-format"
+import { formatAddressRow } from "@mailwoman/codex/address/format"
 import { isPresent } from "@mailwoman/core/objects"
 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 STATE_IA_CONTRACTORS_ADAPTER_ID = "state-ia-contractors"
 /**
- * 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 STATE_IA_CONTRACTORS_DEFAULT_LICENSE = "Public Domain"
 
@@ -51,6 +60,9 @@ export function createStateIaContractorsAdapter(): CorpusAdapter {
 	return {
 		id: STATE_IA_CONTRACTORS_ADAPTER_ID,
 		defaultLicense: STATE_IA_CONTRACTORS_DEFAULT_LICENSE,
+		addressRole: AddressRole.RegisteredOffice,
+		register: SourceRegister.IowaContractors,
+		surface: SurfaceOrigin.Rendered,
 		description:
 			"Iowa Active Construction Contractor Registrations — business name + full street address (public-domain).",
 
@@ -70,12 +82,12 @@ export function createStateIaContractorsAdapter(): CorpusAdapter {
 
 				if (opts.limit !== undefined && emitted >= opts.limit) break
 
-				const businessName = (record["Business Name"] ?? "").trim()
-				const address1 = (record["Address 1"] ?? "").trim()
-				const address2 = (record["Address 2"] ?? "").trim()
-				const city = (record.City ?? "").trim()
-				const stateAbbr = (record.State ?? "").trim()
-				const zip = (record["Zip Code"] ?? "").trim()
+				const businessName = record["Business Name"] ?? ""
+				const address1 = record["Address 1"] ?? ""
+				const address2 = record["Address 2"] ?? ""
+				const city = record.City ?? ""
+				const stateAbbr = record.State ?? ""
+				const zip = record["Zip Code"] ?? ""
 
 				if (!city || !zip) continue
 
@@ -107,7 +119,7 @@ export function createStateIaContractorsAdapter(): CorpusAdapter {
 
 				if (Object.keys(aligned).length <= 2) continue
 
-				const regNum = (record["Registration #"] ?? "").trim()
+				const regNum = record["Registration #"] ?? ""
 
 				const sourceID = regNum
 					? `${STATE_IA_CONTRACTORS_ADAPTER_ID}-${regNum}`

package/lib/us/adapters/state/ny-notaries/adapter.ts

@@ -6,7 +6,7 @@
  *   `state-ny-notaries`: New York Commissioned Notaries CSV consumer.
  *
  *   The New York Department of State publishes a registry of commissioned notaries public. Each row
- *   optionally carries a business name and business address (~1-5% fill rate).
+ *   optionally includes a business name and business address (~1-5% fill rate).
  *
  *   The adapter consumes the CSV the operator pre-downloads via `fetch-state-sources.ts`. Column
  *   names match the data.ny.gov export header (note: some columns have leading spaces).
@@ -14,22 +14,25 @@
  *   License: stamped `"Public Domain"` per New York state government open-data terms.
  */
 
-import { formatAddressRow } from "@mailwoman/codex/address-format"
+import { formatAddressRow } from "@mailwoman/codex/address/format"
 import { isPresent } from "@mailwoman/core/objects"
 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 STATE_NY_NOTARIES_ADAPTER_ID = "state-ny-notaries"
 /**
- * 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 STATE_NY_NOTARIES_DEFAULT_LICENSE = "Public Domain"
 
@@ -37,6 +40,9 @@ export function createStateNyNotariesAdapter(): CorpusAdapter {
 	return {
 		id: STATE_NY_NOTARIES_ADAPTER_ID,
 		defaultLicense: STATE_NY_NOTARIES_DEFAULT_LICENSE,
+		addressRole: AddressRole.Practice,
+		register: SourceRegister.NewYorkNotaries,
+		surface: SurfaceOrigin.Rendered,
 		description: "New York Commissioned Notaries — name + optional business address (public-domain).",
 
 		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
@@ -50,26 +56,19 @@ export function createStateNyNotariesAdapter(): CorpusAdapter {
 
 			let emitted = 0
 
-			for await (const rawRecord of rows as AsyncIterable<Record<string, string>>) {
+			for await (const record of rows as AsyncIterable<Record<string, string>>) {
 				if (opts.signal?.aborted) break
 
 				if (opts.limit !== undefined && emitted >= opts.limit) break
 
-				// NY CSV has columns with leading spaces, so we normalize by trimming keys.
-				const record: Record<string, string> = {}
-
-				for (const key of Object.keys(rawRecord)) {
-					record[key.trim()] = rawRecord[key] ?? ""
-				}
-
-				const holderName = (record["Commission Holder Name"] ?? "").trim()
-				const businessName = (record["Business Name (if available)"] ?? "").trim()
-				const address1 = (record["Business Address 1 (if available)"] ?? "").trim()
-				const address2 = (record["Business Address 2 (if available)"] ?? "").trim()
-				const city = (record["Business City (if available)"] ?? "").trim()
-				const stateAbbr = (record["Business State (if available)"] ?? "").trim()
-				const zip = (record["Business Zip (if available)"] ?? "").trim()
-				const county = (record["Commissioned County"] ?? "").trim()
+				const holderName = record["Commission Holder Name"] ?? ""
+				const businessName = record["Business Name (if available)"] ?? ""
+				const address1 = record["Business Address 1 (if available)"] ?? ""
+				const address2 = record["Business Address 2 (if available)"] ?? ""
+				const city = record["Business City (if available)"] ?? ""
+				const stateAbbr = record["Business State (if available)"] ?? ""
+				const zip = record["Business Zip (if available)"] ?? ""
+				const county = record["Commissioned County"] ?? ""
 
 				if (!city || !stateAbbr || !zip) continue
 
@@ -104,7 +103,7 @@ export function createStateNyNotariesAdapter(): CorpusAdapter {
 
 				if (Object.keys(aligned).length <= 2) continue
 
-				const commNum = (record["Commission Number (UID)"] ?? "").trim()
+				const commNum = record["Commission Number (UID)"] ?? ""
 
 				const sourceID = commNum
 					? `${STATE_NY_NOTARIES_ADAPTER_ID}-${commNum}`

package/lib/us/adapters/state/tx-notaries/adapter.ts

@@ -6,36 +6,39 @@
  *   `state-tx-notaries`: Texas Notary Public Commissions CSV consumer.
  *
  *   The Texas Secretary of State publishes a registry of commissioned notaries public. Each row
- *   optionally carries a mailing address in free-form text (often multi-line with embedded
+ *   optionally includes a mailing address in free-form text (often multi-line with embedded
  *   city/state/zip). Address fill rate is ~5-10%.
  *
- *   The adapter parses the embedded `Address` field for city/state/zip using a trailing `"CITY, ST
+ *   The adapter parses the embedded `Address` field for city/state/zip using a trailing `"city, ST
  *   ZIP"` pattern.
  *
  *   License: stamped `"Public Domain"` per Texas state government open-data terms.
  */
 
-import { formatAddressRow } from "@mailwoman/codex/address-format"
+import { formatAddressRow } from "@mailwoman/codex/address/format"
 import { formatPersonName } from "@mailwoman/record/name"
 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 STATE_TX_NOTARIES_ADAPTER_ID = "state-tx-notaries"
 /**
- * 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 STATE_TX_NOTARIES_DEFAULT_LICENSE = "Public Domain"
 
 /**
- * Match trailing "CITY, ST ZIP" or "CITY, ST" at the end of an address line.
+ * Match trailing "city, ST ZIP" or "city, ST" at the end of an address line.
  */
 const CITY_STATE_ZIP_SUFFIX = /[,]?\s*([^,]+),\s*([A-Z]{2})\s*(\d{5}(?:-\d{4})?)?\s*$/i
 
@@ -50,6 +53,9 @@ export function createStateTxNotariesAdapter(): CorpusAdapter {
 	return {
 		id: STATE_TX_NOTARIES_ADAPTER_ID,
 		defaultLicense: STATE_TX_NOTARIES_DEFAULT_LICENSE,
+		addressRole: AddressRole.Mailing,
+		register: SourceRegister.TexasNotaries,
+		surface: SurfaceOrigin.Rendered,
 		description:
 			"Texas Notary Public Commissions — name + mailing address with embedded city/state/zip (public-domain).",
 
@@ -69,16 +75,16 @@ export function createStateTxNotariesAdapter(): CorpusAdapter {
 
 				if (opts.limit !== undefined && emitted >= opts.limit) break
 
-				const rawAddress = (record.Address ?? "").trim()
+				const rawAddress = record.Address ?? ""
 
 				if (!rawAddress) continue
 
-				const firstName = (record["First Name"] ?? "").trim()
-				const lastName = (record["Last Name"] ?? "").trim()
-				const notaryID = (record["Notary ID"] ?? "").trim()
+				const firstName = record["First Name"] ?? ""
+				const lastName = record["Last Name"] ?? ""
+				const notaryID = record["Notary ID"] ?? ""
 
 				// Parse embedded city/state/zip from the trailing portion of the address.
-				// Addresses look like: "1215 MCMILLAN DR\nCEDAR HILL, TX 75104"
+				// Addresses look like: "1215 mcmillan DR\nCEDAR hill, TX 75104"
 				const addrSingleLine = rawAddress.replaceAll("\n", ", ")
 				const cszMatch = CITY_STATE_ZIP_SUFFIX.exec(addrSingleLine)
 

package/lib/us/adapters/tiger/adapter.ts

@@ -3,59 +3,35 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `tiger`: US Census TIGER/Line consumer adapter.
+ * `tiger`: Adapter for US Census TIGER/Line data.
  *
- *   TIGER/Line is the canonical US street + locality dataset published by the Census Bureau as a
- *   **public-domain** product (no ODbL share-alike concerns for US-only corpora). Coverage extends
- *   to every named street segment + every incorporated place + CDP across the 50 states + DC + the
- *   five primary territories — substantially better US street-name coverage than OSM, especially in
- *   rural areas.
+ * This reads a prebuilt SQLite database (from TIGER shapefiles) and emits:
+ * - Street rows from `tiger_streets`
+ * - Locality rows from `tiger_places`
  *
- *   Following the `wof-admin` / `wof-postalcode` pattern, this adapter consumes a SQLite database the
- *   operator pre-builds from the raw TIGER shapefiles (see the README for the schema and a
- *   suggested `ogr2ogr` pipeline). The mailwoman side does not parse Shapefile binary directly —
- *   keeping the adapter narrow lets the operator pick their own ingestion tool (ogr2ogr / shp2pgsql
- *   / a custom Python script / etc.) without forcing a heavy native dep into `@mailwoman/corpus`.
- *
- *   Two row classes are emitted:
- *
- *   - **Street-level** (`tiger_streets`): one row per segment, optionally with up to two postcode
- *       variants if `zipl` / `zipr` differ. Components: `{ street, region, postcode? }`. Streets
- *       without a recognized state FIPS are dropped — there's no useful row without `region`.
- *   - **Locality-level** (`tiger_places`): up to three variants per place: locality-only,
- *       locality-with-region, locality-with-region-country (mirrors `wof-admin`'s fan-out for
- *       consistency).
- *   - `packages/corpus/lib/us/fips-state.ts` — the FIPS → `{abbreviation, name}` lookup table
- *       (originally `tiger/state.ts`, AGPL-3.0 → AGPL-3.0). The full isp-nexus TIGER module ships a
- *       TypeORM-backed service layer; mailwoman only needs the lookup data so we don't carry the
- *       service layer over.
- *
- *   License: stamped `"Public Domain"` per Census Bureau guidance on TIGER/Line. No per-row override
- *   needed — every row in TIGER is the same license.
+ * TIGER is public domain, so every emitted row is stamped `"Public Domain"`.
  */
 
-import { formatAddressRow } from "@mailwoman/codex/address-format"
+import { formatAddressRow } from "@mailwoman/codex/address/format"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
-import type { TIGERDatabase } from "@mailwoman/tiger/sdk/schema"
+import type { TIGERDatabase } from "@mailwoman/tiger/schema"
 
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "#types"
+import { SourceRegister } from "#registers"
+import { AddressRole, type AdapterOptions, type CanonicalRow, type CorpusAdapter, SurfaceOrigin } from "#types"
 import { decomposeStreet } from "#us/adapters/tiger/street-decompose"
 import { lookupFipsState } 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.
  */
 export const TIGER_ADAPTER_ID = "tiger"
 /**
- * License carried by this source (Public Domain), attached to each row so downstream consumers inherit the terms rather
- * than having to look them up.
+ * Default license for rows from this source.
  */
 export const TIGER_DEFAULT_LICENSE = "Public Domain"
 
 /**
- * The country surface form used in `formatAddress` for US. Matches the canonical OpenCage US template output so
- * reconciliation doesn't strip it when the row carries `country` explicitly.
+ * Country display name used by `formatAddress`.
  */
 const US_COUNTRY_DISPLAY = "United States of America"
 
@@ -75,11 +51,7 @@ interface TigerPlaceRow {
 }
 
 /**
- * Yield one or more `CanonicalRow`s per street segment. Postcode variants:
- *
- * - No ZIP set → one row, street + region.
- * - `zipl === zipr` → one row, street + region + postcode.
- * - `zipl !== zipr` → two rows (one per side's ZIP).
+ * Build one or more street variants from a TIGER street segment.
  */
 function* streetVariants(row: TigerStreetRow): Iterable<{
 	components: CanonicalRow["components"]
@@ -135,7 +107,7 @@ function* streetVariants(row: TigerStreetRow): Iterable<{
 }
 
 /**
- * Three locality-level variants, mirroring `wof-admin`'s fan-out.
+ * Build locality variants for a TIGER place.
  */
 function* placeVariants(row: TigerPlaceRow): Iterable<{
 	components: CanonicalRow["components"]
@@ -165,12 +137,15 @@ function* placeVariants(row: TigerPlaceRow): Iterable<{
 }
 
 /**
- * Build a TIGER adapter. Pure factory so multiple instances can be created in tests.
+ * Build a TIGER adapter.
  */
 export function createTigerAdapter(): CorpusAdapter {
 	return {
 		id: TIGER_ADAPTER_ID,
 		defaultLicense: TIGER_DEFAULT_LICENSE,
+		addressRole: AddressRole.Premise,
+		register: SourceRegister.CensusTIGER,
+		surface: SurfaceOrigin.Rendered,
 		description:
 			"US Census TIGER/Line streets + places consumer (public-domain); SQLite DB built via `mailwoman tiger fetch`.",
 
@@ -245,6 +220,6 @@ export function createTigerAdapter(): CorpusAdapter {
 }
 
 /**
- * The configured adapter instance registered with the corpus builder.
+ * Configured adapter instance.
  */
 export const tigerAdapter = createTigerAdapter()