@mailwoman/corpus 9.1.0 → 9.3.0

package/README.md

@@ -3,7 +3,7 @@
 **BIO-labeled training-corpus pipeline** for the Mailwoman address parser.
 
 Generates sequence-labeling training data from reference sources
-(OpenAddresses, libpostal dictionaries, synthetic shards) and assembles them into
+(OpenAddresses, libpostal dictionaries, synthetic training-data subsets) and assembles them into
 the TSV format consumed by the Modal training pipeline. This package produces
 the data that trains `@mailwoman/neural-weights-*`.
 
@@ -11,7 +11,7 @@ the data that trains `@mailwoman/neural-weights-*`.
 // The corpus pipeline is primarily build-time CLI tooling.
 // Key entry points:
 import { expandGolden } from "@mailwoman/corpus" // Expand reference addresses
-import { synthesizeShard } from "@mailwoman/corpus" // Generate synthetic training shards
+import { synthesizeSlice } from "@mailwoman/corpus" // Generate synthetic training rows
 import { alignRow } from "@mailwoman/corpus" // Align raw address → BIO tokens
 import { validateCorpus } from "@mailwoman/corpus" // Validate corpus integrity
 ```
@@ -20,28 +20,28 @@ import { validateCorpus } from "@mailwoman/corpus" // Validate corpus integrity
 
 The corpus pipeline assembles training data from multiple sources:
 
-| Source               | Description                                                              |
-| -------------------- | ------------------------------------------------------------------------ |
-| **OpenAddresses**    | Real government address point data (US, FR, DE, …)                       |
-| **NAD**              | National Address Database (US-specific)                                  |
-| **libpostal**        | Multilingual street/place name dictionaries                              |
-| **Synthetic shards** | Generated address variations (boundary stress, order variants, all-caps) |
-| **Overture Maps**    | Address theme ingestion (alpha)                                          |
+| Source             | Description                                                              |
+| ------------------ | ------------------------------------------------------------------------ |
+| **OpenAddresses**  | Real government address point data (US, FR, DE, …)                       |
+| **NAD**            | National Address Database (US-specific)                                  |
+| **libpostal**      | Multilingual street/place name dictionaries                              |
+| **Synthetic rows** | Generated address variations (boundary stress, order variants, all-caps) |
+| **Overture Maps**  | Address theme ingestion (alpha)                                          |
 
 Output format: TSV rows with `raw<TAB>BIO_labels` consumed by the Python
 training pipeline (`corpus-python/`).
 
 ## Key modules
 
-| Module                  | Purpose                                                            |
-| ----------------------- | ------------------------------------------------------------------ |
-| **`expand-golden.ts`**  | Expand reference addresses into training rows with alignment       |
-| **`align.ts`**          | Tokenize raw address → BIO label sequence                          |
-| **`validate.ts`**       | Validate corpus integrity, label coverage, shard balance           |
-| **`synthesizers/*.ts`** | Synthetic shard generators (boundary stress, order variants, etc.) |
-| **`ingest/`**           | Overture Maps + NAD ingestion                                      |
-| **`shard-registry.ts`** | Shard metadata and composition                                     |
-| **`stats.ts`**          | Per-shard and per-tag statistics                                   |
+| Module                  | Purpose                                                          |
+| ----------------------- | ---------------------------------------------------------------- |
+| **`expand-golden.ts`**  | Expand reference addresses into training rows with alignment     |
+| **`align.ts`**          | Tokenize raw address → BIO label sequence                        |
+| **`validate.ts`**       | Validate corpus integrity, label coverage, subset balance        |
+| **`synthesizers/*.ts`** | Synthetic row generators (boundary stress, order variants, etc.) |
+| **`ingest/`**           | Overture Maps + NAD ingestion                                    |
+| **`slice-registry.ts`** | Subset metadata and composition                                  |
+| **`stats.ts`**          | Per-subset and per-tag statistics                                |
 
 ## Build-time tooling
 
@@ -51,8 +51,8 @@ The corpus is assembled via scripts in `scripts/`:
 # Validate the corpus
 node scripts/validate-corpus.mjs
 
-# Rebuild shards
-node scripts/build-boundary-stress-shard.mjs
+# Rebuild slices
+node scripts/build-boundary-stress-slice.mjs
 
 # Corpus statistics
 node scripts/corpus-stats.mjs
@@ -63,15 +63,15 @@ node scripts/corpus-stats.mjs
 - **BIO (Begin/Inside/Outside) labeling** over SentencePiece tokens.
 - **Character-offset aligned** — labels track the raw string, not the
   normalized form, so the model learns real input distributions.
-- **Source-homogeneous shards** — each shard comes from one source, ordered by
-  type, so eval splits are honest (no bleed between train and held-out).
+- **Source-homogeneous subsets** — each training-data subset comes from one source, ordered by
+  type, so eval splits are clean (no bleed between train and held-out).
 
 ## Related
 
 - [`@mailwoman/neural`](../neural) — the runtime that loads and runs the trained model
 - [`@mailwoman/neural-weights-en-us`](../neural-weights-en-us) — the trained model itself
-- [Corpus Construction concepts](https://mailwoman.sister.software/articles/concepts/corpus-construction/)
-- [Training Pipeline concepts](https://mailwoman.sister.software/articles/concepts/training-pipeline/)
+- [Corpus Construction concepts](https://mailwoman.ai/articles/concepts/corpus-construction/)
+- [Training Pipeline concepts](https://mailwoman.ai/articles/concepts/training-pipeline/)
 - [CONTRIBUTING_MODEL_WORK](https://github.com/sister-software/mailwoman/blob/main/docs/engineering/CONTRIBUTING_MODEL_WORK.mdx)
 
 ## License

package/data/PROVENANCE.md

@@ -1,8 +1,21 @@
 # `corpus/data/` provenance
 
+## `reviewed-ve-postcode-tuples.json` — reviewed Venezuelan postcode placement (#1821)
+
+Four geographic facts support the Venezuelan `locality postcode, region` convention. The Barcelona
+tuple comes from the Anzoátegui state government's contact address. The Caracas, Sanare, and Santa
+Elena de Guairén tuples come from the Universal Postal Union's Venezuela addressing guide. The file
+records the publisher, full source address, retrieval date, review status, and source-license note for
+each tuple.
+
+Only factual fields are stored. No source prose is copied, and the corpus rows do not claim that either
+source published the facts under CC0 or another open-data license. The recipe creates bounded synthetic
+case, punctuation, accent, country-tail, and left-context forms while keeping each reviewed
+postcode-to-place join unchanged.
+
 ## `sub-venue-lexicon.json` — the sub-venue designator lexicon (#35, waves 1–2)
 
-The vocabulary a corpus shard (and eventually the span proposer) reads to recognize `Terminal 5`,
+The vocabulary a corpus slice (and eventually the span proposer) reads to recognize `Terminal 5`,
 `North Terminal`, `Concourse B`, `第1ターミナル` as venue-interior structure. Generated, **not
 hand-edited**. See `docs/engineering/sub-venue-corpus-task.mdx` for why this exists — the short
 version is that the `unit` tag was never taught the modifier+designator shape, so closing the class by
@@ -55,13 +68,13 @@ The extract JSONLs and the `.osm.pbf` files are build inputs under
 | OpenStreetMap   | Geofabrik `japan-latest.osm.pbf`                   | ODbL                | 183,999 |
 | Overture Places | `poi.db` spatial layer, vintage `2026-05-20.0`     | CDLA-Permissive-2.0 | 9,219   |
 
-**The ODbL question, unchanged from wave 1 and still open for the shard.** The committed artifact
+**The ODbL question, unchanged from wave 1 and still open for the slice.** The committed artifact
 contains no OSM geometry and no OSM row. What survives the OSM leg is surface COUNTS — that the token
 `ターミナル` appears in 1,215 Japanese feature names — plus the `identifierShapes` distribution, whose
 `examples` are gate reference strings (`B32`, `1A`, `16-18`). Facts and short factual strings are not
 a substantial extraction from a database, so this table is not treated as a Derived Database. That
-reading matches `osm/README.md`'s posture that the ODbL obligation rides on the built shard rather
-than on code. **A corpus shard built from OSM rows IS a derived work, and that question is still not
+reading matches `osm/README.md`'s posture that the ODbL obligation rides on the built slice rather
+than on code. **A corpus slice built from OSM rows IS a derived work, and that question is still not
 settled** — it gates step 4, not this table.
 
 ### What the sources are FOR, and what each cannot do
@@ -176,9 +189,9 @@ list.
 
 **A rejection of a SHIPPED designator is advisory.** `neural/venue-structure.ts` carries a flat
 English vocabulary with no locale gate, and `wing`, `terminal` and `concourse` are in it. This table
-cannot un-ship them: the `wing` / en-US rejection tells a shard author which locale to leave out of a
+cannot un-ship them: the `wing` / en-US rejection tells a slice author which locale to leave out of a
 generated line, and it does nothing to stop the span proposer firing on "Red Wing". Giving the shipped
-vocabulary a per-locale gate is step 4's problem, and it is the single largest thing the shard will
+vocabulary a per-locale gate is step 4's problem, and it is the single largest thing the slice will
 want that does not exist yet.
 
 The mechanism does hold for anything the lexicon adds. `pier` is promoted for en-GB and rejected for
@@ -190,7 +203,7 @@ en-US, and because it is not in the shipped list, the rejection has teeth: the r
 `Gate A12` is a rendering, not a string anyone wrote down: all 658 Great Britain `aeroway=gate`
 features but 13 are unnamed and carry only a `ref`. The table therefore carries a distribution rather
 than a phrase list — and the distribution turns out to differ by country far more than the shared
-vocabulary suggests, so a shard generating `Gate <ref>` for a French address has to sample France's:
+vocabulary suggests, so a slice generating `Gate <ref>` for a French address has to sample France's:
 
 | region | gate refs | most common shape      |           second | third           |
 | ------ | --------: | ---------------------- | ---------------: | --------------- |

package/data/reviewed-ve-postcode-tuples.json

@@ -0,0 +1,74 @@
+{
+	"version": "1.0.0",
+	"reviewedAt": "2026-08-24",
+	"tuples": [
+		{
+			"id": "ve-barcelona-6001-anzoategui",
+			"locality": "Barcelona",
+			"postcode": "6001",
+			"region": "Anzoátegui",
+			"country": "Venezuela",
+			"cc": "VE",
+			"locale": "es-VE",
+			"postcodePlacement": "after_locality",
+			"provenance": {
+				"publisher": "Gobierno del Estado Anzoátegui",
+				"url": "https://anzoategui.gob.ve/contacto/",
+				"retrievedAt": "2026-08-24",
+				"reviewStatus": "reviewed",
+				"sourceLicenseNote": "Factual address fields only; the source page does not state a reusable data license."
+			}
+		},
+		{
+			"id": "ve-caracas-1010-distrito-capital",
+			"locality": "Caracas",
+			"postcode": "1010",
+			"region": "Distrito Capital",
+			"country": "Venezuela",
+			"cc": "VE",
+			"locale": "es-VE",
+			"postcodePlacement": "after_locality",
+			"provenance": {
+				"publisher": "Universal Postal Union",
+				"url": "https://www.upu.int/UPU/media/upu/PostalEntitiesFiles/addressingUnit/venEn.pdf",
+				"retrievedAt": "2026-08-24",
+				"reviewStatus": "reviewed",
+				"sourceLicenseNote": "Factual postal fields only; no source prose is reproduced."
+			}
+		},
+		{
+			"id": "ve-sanare-3028-lara",
+			"locality": "Sanare",
+			"postcode": "3028",
+			"region": "Lara",
+			"country": "Venezuela",
+			"cc": "VE",
+			"locale": "es-VE",
+			"postcodePlacement": "after_locality",
+			"provenance": {
+				"publisher": "Universal Postal Union",
+				"url": "https://www.upu.int/UPU/media/upu/PostalEntitiesFiles/addressingUnit/venEn.pdf",
+				"retrievedAt": "2026-08-24",
+				"reviewStatus": "reviewed",
+				"sourceLicenseNote": "Factual postal fields only; no source prose is reproduced."
+			}
+		},
+		{
+			"id": "ve-santa-elena-8011-bolivar",
+			"locality": "Santa Elena de Guairén",
+			"postcode": "8011",
+			"region": "Bolívar",
+			"country": "Venezuela",
+			"cc": "VE",
+			"locale": "es-VE",
+			"postcodePlacement": "after_locality",
+			"provenance": {
+				"publisher": "Universal Postal Union",
+				"url": "https://www.upu.int/UPU/media/upu/PostalEntitiesFiles/addressingUnit/venEn.pdf",
+				"retrievedAt": "2026-08-24",
+				"reviewStatus": "reviewed",
+				"sourceLicenseNote": "Factual postal fields only; no source prose is reproduced."
+			}
+		}
+	]
+}

package/lib/adapters/ban/adapter.ts

@@ -0,0 +1,190 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `ban`: Base Adresse Nationale CSV adapter (FR street-level).
+ *
+ *   Input: a CSV dump from `adresse.data.gouv.fr` (semicolon-separated, ~25M rows nationally). The
+ *   adapter only reads the small set of columns needed for the corpus:
+ *
+ *   - `numero` → `house_number`
+ *   - `rep` → repetition index ("bis", "ter") appended to house_number
+ *   - `nom_voie` → `street` (full road name; includes the prefix "Rue", "Avenue", etc.)
+ *   - `code_postal` → `postcode`
+ *   - `nom_commune` → `locality`
+ *
+ *   `region` and `country` are not in BAN. The adapter stamps `country: "FR"` on every row; region is
+ *   left for the wof-postalcode + wof-admin cross-reference at corpus build time (a future pass;
+ *   for Phase 1 the row's region is simply absent).
+ *
+ *   License: the official BAN (adresse.data.gouv.fr) is DUAL-licensed — Licence Ouverte 2.0 (Etalab,
+ *   attribution-only) OR ODbL (share-alike). We ELECT Licence Ouverte 2.0 (issue #26 Tier B:
+ *   allowed for training with attribution; the ODbL option's share-alike obligation would defeat
+ *   the proprietary-weights goal). Stamped onto every row as `Licence Ouverte 2.0` — NOT the older
+ *   conservative `ODbL-1.0` label, which wrongly read as Tier-C-denied in the corpus license audit.
+ *   The model card MUST carry the BAN attribution (Tier B obligation).
+ *
+ *   The adapter is streaming-aware: `CSVSpliterator.fromAsync` reads the `;`-delimited dump row by
+ *   row, so a 25M-row file never sits in memory. Honors `opts.limit` for fixture / smoke runs,
+ *   `opts.signal` for cancellation, and `opts.country` for a self-consistency check (errors if
+ *   country !== FR).
+ */
+
+import { isPresent } from "@mailwoman/core/objects"
+import { reconcileComponents } from "@mailwoman/formatter"
+import { CSVSpliterator } from "spliterator"
+
+import { decomposeFrStreet } from "#adapters/ban/street-decompose"
+import { stableSourceID } from "#adapters/utils"
+import type { AdapterOptions, CanonicalRow, CorpusAdapter } 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.
+ */
+export const BAN_ADAPTER_ID = "ban"
+
+/**
+ * Subset of BAN CSV columns the adapter consults. Everything else is ignored; declaring the shape explicitly catches
+ * column-name drift early if BAN evolves its schema.
+ */
+interface BanRow {
+	id: string
+	numero: string
+	rep: string
+	nom_voie: string
+	code_postal: string
+	nom_commune: string
+}
+
+/**
+ * Compose `house_number` from `numero` + `rep`. BAN uses `rep` for repetition indices ("bis", "ter", "quater") that
+ * follow the house number. Result: `"10 bis"`, `"45"`, etc.
+ */
+function composeHouseNumber(numero: string, rep: string): string {
+	const n = numero.trim()
+	const r = rep.trim()
+
+	if (!n) return ""
+
+	return r ? `${n} ${r}` : n
+}
+
+/**
+ * Compose the raw FR-style address line. Two common BAN-derived shapes:
+ *
+ * "10 bis Avenue des Champs-Élysées, 75008 Paris" "45 Cours Lafayette, 69003 Lyon"
+ *
+ * FR convention puts postcode on the same line as the locality, comma-separated from the street. The adapter renders
+ * that directly rather than relying on OpenCage's template — BAN already gives us the canonical FR strings; the
+ * template would round-trip identically.
+ */
+function composeRaw(house: string, street: string, postcode: string, locality: string): string {
+	const parts: string[] = []
+	const streetPart = [house, street].filter(isPresent).join(" ").trim()
+
+	if (streetPart) {
+		parts.push(streetPart)
+	}
+
+	const cityPart = [postcode, locality].filter(isPresent).join(" ").trim()
+
+	if (cityPart) {
+		parts.push(cityPart)
+	}
+
+	return parts.join(", ").replaceAll(/\s+/g, " ").trim()
+}
+
+export function createBanAdapter(): CorpusAdapter {
+	return {
+		id: BAN_ADAPTER_ID,
+		defaultLicense: "Licence Ouverte 2.0",
+		description: "Base Adresse Nationale (FR): house-number-level street addresses (~25M rows).",
+
+		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
+			if (opts.country && opts.country !== "FR") {
+				throw new Error(`ban adapter: only FR supported, got country=${opts.country}`)
+			}
+
+			const rows = CSVSpliterator.fromAsync(opts.inputPath, {
+				mode: "object",
+				normalizeKeys: false,
+				columnDelimiter: ";",
+				enableQuoteHandling: true,
+			})
+
+			let emitted = 0
+
+			for await (const record of rows as AsyncIterable<BanRow>) {
+				if (opts.signal?.aborted) break
+
+				if (opts.limit !== undefined && emitted >= opts.limit) break
+
+				const house = composeHouseNumber(record.numero ?? "", record.rep ?? "")
+				const street = (record.nom_voie ?? "").trim()
+				const postcode = (record.code_postal ?? "").trim()
+				const locality = (record.nom_commune ?? "").trim()
+
+				if (!street || !locality) continue
+
+				if (!house && !postcode) continue
+
+				const decomposed = decomposeFrStreet(street)
+
+				const components: CanonicalRow["components"] = {}
+
+				if (house) {
+					components.house_number = house
+				}
+
+				if (decomposed.prefix) {
+					components.street_prefix = decomposed.prefix
+				}
+
+				if (decomposed.street) {
+					components.street = decomposed.street
+				}
+
+				if (postcode) {
+					components.postcode = postcode
+				}
+
+				if (locality) {
+					components.locality = locality
+				}
+
+				const raw = composeRaw(house, street, postcode, locality)
+
+				if (!raw) continue
+
+				const aligned = reconcileComponents(components, raw)
+
+				if (!Object.keys(aligned).length) continue
+
+				const sourceID = record.id?.trim()
+					? `${BAN_ADAPTER_ID}-${record.id.trim()}`
+					: stableSourceID(BAN_ADAPTER_ID, aligned)
+
+				yield {
+					raw,
+					components: aligned,
+					country: "FR",
+					locale: "fr-FR",
+					source: BAN_ADAPTER_ID,
+					source_id: sourceID,
+					corpus_version: "",
+					license: "Licence Ouverte 2.0",
+				}
+
+				emitted++
+			}
+		},
+	}
+}
+
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const banAdapter = createBanAdapter()

package/lib/adapters/ban/street-decompose.ts

@@ -0,0 +1,66 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Decompose a French street name into Stage 3 components. French convention puts the street type as
+ *   a leading word: "Rue de Rivoli", "Avenue des Champs-Élysées", "Bd Voltaire".
+ *
+ *   The street type becomes street_prefix in our schema. The remaining tokens form the street name.
+ *
+ *   Examples: "Rue de Rivoli" → { prefix: "Rue", street: "de Rivoli" } "Avenue des Champs-Élysées" →
+ *   { prefix: "Avenue", street: "des Champs-Élysées" } "Boulevard Voltaire" → { prefix:
+ *   "Boulevard", street: "Voltaire" }
+ *
+ *   Sources street types from `core/data/libpostal/dictionaries/fr/street_types.txt`.
+ */
+
+import { loadLibpostalDictionary } from "#adapters/utils"
+
+/**
+ * Tokens a BAN street needs before a type/article/name decomposition is attempted.
+ */
+const MIN_TOKENS_FOR_DECOMPOSE = 3
+
+const STREET_TYPES_FR = await loadLibpostalDictionary("fr", "street_types.txt")
+
+export interface DecomposedFrStreet {
+	prefix: string | null
+	street: string
+}
+
+/**
+ * Decompose a French street name into prefix (leading type word) and street name.
+ *
+ * If the first 1-2 tokens match a known street type (allowing for multi-word like "ancien chemin"), they become the
+ * prefix. Returns `{ prefix: null, street: original }` if no match.
+ */
+export function decomposeFrStreet(fullname: string): DecomposedFrStreet {
+	const trimmed = fullname.trim()
+
+	if (!trimmed) return { prefix: null, street: "" }
+
+	const tokens = trimmed.split(/\s+/)
+
+	if (tokens.length < 2) return { prefix: null, street: trimmed }
+
+	const norm = (s: string) => s.toLowerCase().replace(/[.,;]$/, "")
+
+	// Try 2-word prefix first (e.g. "ancien chemin")
+	if (tokens.length >= MIN_TOKENS_FOR_DECOMPOSE) {
+		const twoWord = norm(tokens[0]!) + " " + norm(tokens[1]!)
+
+		if (STREET_TYPES_FR.has(twoWord)) {
+			return { prefix: tokens.slice(0, 2).join(" "), street: tokens.slice(2).join(" ") }
+		}
+	}
+
+	// Then try 1-word prefix
+	const first = norm(tokens[0]!)
+
+	if (STREET_TYPES_FR.has(first)) {
+		return { prefix: tokens[0]!, street: tokens.slice(1).join(" ") }
+	}
+
+	return { prefix: null, street: trimmed }
+}

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

@@ -0,0 +1,174 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `fcc-bdc`: FCC Broadband Data Collection (BDC) — Fabric-derived location consumer.
+ *
+ *   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.
+ *
+ *   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.
+ *
+ *   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.
+ *
+ *   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.
+ *
+ *   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.
+ */
+
+import type { BDCDatabase } from "@mailwoman/bdc/schema"
+import { formatAddress, reconcileComponents } from "@mailwoman/formatter"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+
+import { splitStreetLine } from "#adapters/utils"
+import { lookupStateAbbreviation } from "#codex/us-fips-state"
+import type { AdapterOptions, CanonicalRow, CorpusAdapter } 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.
+ */
+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.
+ */
+export const FCC_BDC_DEFAULT_LICENSE = "Public Domain"
+
+/**
+ * SQLite row shape — one row per BSL `location_id`. Columns mirror NTIARecord.
+ */
+interface BdcLocationRow {
+	location_id: number
+	address_primary: string
+	city: string
+	state: string
+	zip: string
+	zip_suffix: string | null
+}
+
+/**
+ * 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:
+ *
+ * - 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.
+ */
+export function buildPostcode(zip: string, suffix: string | null): string {
+	const z = zip.trim()
+
+	if (!z) return ""
+	const s = suffix?.trim() ?? ""
+
+	if (!s) return z
+
+	if (s.includes("-")) return s
+
+	return `${z}-${s}`
+}
+
+/**
+ * Build a BDC adapter. Pure factory so multiple instances can be created in tests.
+ */
+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.",
+
+		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
+			if (opts.country && opts.country !== "US") {
+				throw new Error(`fcc-bdc adapter: only US supported, got country=${opts.country}`)
+			}
+
+			const db = new DatabaseClient<BDCDatabase>(opts.inputPath, { readOnly: true })
+			let emitted = 0
+
+			try {
+				const stmt = db.prepare(
+					`SELECT location_id, address_primary, city, state, zip, zip_suffix
+					 FROM bdc_locations
+					 ORDER BY location_id`
+				)
+
+				for (const row of stmt.iterate() as IterableIterator<BdcLocationRow>) {
+					if (opts.signal?.aborted) return
+
+					if (opts.limit !== undefined && emitted >= opts.limit) return
+
+					const split = splitStreetLine(row.address_primary ?? "")
+
+					if (!split) continue
+					const state = lookupStateAbbreviation(row.state)
+
+					if (!state) continue
+					const locality = row.city?.trim()
+
+					if (!locality) continue
+					const postcode = buildPostcode(row.zip ?? "", row.zip_suffix ?? null)
+
+					if (!postcode) continue
+
+					const components: CanonicalRow["components"] = {
+						...(split.house_number ? { house_number: split.house_number } : {}),
+						street: split.street,
+						locality,
+						region: state.abbreviation,
+						postcode,
+					}
+
+					const raw = formatAddress(components, "US", { separator: ", " })
+
+					if (!raw) continue
+					const aligned = reconcileComponents(components, raw)
+
+					if (!Object.keys(aligned).length) continue
+
+					yield {
+						raw,
+						components: aligned,
+						country: "US",
+						locale: "en-US",
+						source: FCC_BDC_ADAPTER_ID,
+						source_id: `${FCC_BDC_ADAPTER_ID}-${row.location_id}`,
+						corpus_version: "",
+						license: FCC_BDC_DEFAULT_LICENSE,
+					}
+
+					emitted++
+				}
+			} finally {
+				await db.destroy()
+			}
+		},
+	}
+}
+
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const fccBdcAdapter = createFccBdcAdapter()