@mailwoman/corpus 9.4.0 → 10.1.0

package/lib/adapters/gnaf/adapter.ts

@@ -1,149 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   G-NAF (Australia) corpus adapter — the parser-teaching half of #208.
- *
- *   The model mis-parses Australian addresses in their native postcode-first / house-number-last
- *   order: it tags a leading 4-digit postcode as a house number (its US/EU prior) and swaps street
- *   ↔ locality with it. `scripts/eval/au-order-probe.ts` proved this is a word-ORDER coverage gap,
- *   not capability — the same addresses parse perfectly in canonical order (65% → 87% @25km if the
- *   parse were order-robust). EU survives the same eval because its postcodes are
- *   format-distinctive (a hyphenated `26-300` reads as a postcode anywhere); a bare AU `3053` only
- *   disambiguates by position.
- *
- *   So this adapter renders each assembled G-NAF tuple (from {@link ./assemble}) in one of three real
- *   AU layouts — real-AU canonical (number-first, postcode-trailing), postcode-first,
- *   locality-first — ROTATED by row index (`i % 3`), so the locality + postcode each land in every
- *   position across the slice. This is the exact mechanism that fixed #148's v1.9.0 order-overfit
- *   for the 16 EU locales (`scripts/rerender-overture-multiorder.mjs`, v1.9.1 → shipped v4.13.0);
- *   AU was simply never in that train (`country_weights` had no AU, and `data_loader.py` excludes
- *   unlisted countries). Rotating one order per row (rather than emitting all three) keeps this a
- *   clean single-variable extension of the proven recipe + matches its source-mass structure. The
- *   corpus aligner BIO-labels each (every component surface form occurs verbatim in `raw`, so
- *   alignment lands).
- *
- *   Input: the assembled component JSONL (one `{house_number,street,locality,region,postcode}` per
- *   line). Open G-NAF licence — attribute "Geoscape Australia".
- */
-
-import { tryParsingJSON } from "@mailwoman/core/json"
-import { reconcileComponents } from "@mailwoman/formatter"
-import { TextSpliterator } from "spliterator"
-
-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 GNAF_ADAPTER_ID = "gnaf"
-/**
- * Open G-NAF is freely redistributable with attribution to Geoscape Australia (CC-BY-style).
- */
-export const GNAF_DEFAULT_LICENSE = "CC-BY-4.0"
-
-interface GNAFTuple {
-	house_number: string
-	street: string
-	locality: string
-	region?: string
-	postcode: string
-}
-
-/**
- * The address layouts an AU address actually arrives in. The model already handles postcode-TRAILING (canonical); the
- * two postcode-LEADING forms are the ones it fails, so they carry the change. We keep the canonical form too so the
- * retrain doesn't forget it.
- */
-function renderOrders(c: GNAFTuple): string[] {
-	const region = c.region ? ` ${c.region}` : ""
-
-	return [
-		// real-AU canonical: number-first, street, suburb [state] postcode — "50 Barry Street, Carlton NSW 2000"
-		`${c.house_number} ${c.street}, ${c.locality}${region} ${c.postcode}`,
-		// postcode-first (the dominant failure): "2000 Carlton, Barry Street 50"
-		`${c.postcode} ${c.locality}, ${c.street} ${c.house_number}`,
-		// locality-first: "Carlton, 2000, Barry Street 50"
-		`${c.locality}, ${c.postcode}, ${c.street} ${c.house_number}`,
-	]
-}
-
-/**
- * Build the G-NAF adapter. `inputPath` is the assembled component JSONL (see {@link ./assemble}); it is country-pinned
- * to AU regardless of `opts.country` (G-NAF is Australia-only).
- */
-export function createGNAFAdapter(): CorpusAdapter {
-	return {
-		id: GNAF_ADAPTER_ID,
-		defaultLicense: GNAF_DEFAULT_LICENSE,
-		description:
-			"G-NAF (Australia): assembled address tuples rendered in multiple word orders (canonical / postcode-first / locality-first) — teaches the model AU's postcode-first layout.",
-
-		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
-			let emitted = 0
-			let idx = 0
-
-			// Input is the assembled component JSONL (one tuple per line). TextSpliterator auto-disposes on
-			// loop completion and on an early `break` (abort / limit), so the old explicit handle teardown is
-			// gone; the parse tolerates a trailing CR on CRLF sources and the `!line.trim()` guard skips blanks.
-			// The render order rotates (i % 3), matching v1.9.1's rerender.
-			for await (const line of TextSpliterator.fromAsync(opts.inputPath)) {
-				if (opts.signal?.aborted) break
-
-				if (opts.limit !== undefined && emitted >= opts.limit) break
-
-				if (!line.trim()) continue
-
-				const t = tryParsingJSON<GNAFTuple>(line)
-
-				if (t === null) continue
-
-				if (!t.house_number || !t.street || !t.locality || !t.postcode) continue
-
-				const orders = renderOrders(t)
-				const order = idx % orders.length
-
-				idx++
-				const raw = orders[order]!
-
-				const components: CanonicalRow["components"] = {
-					house_number: t.house_number,
-					street: t.street,
-					locality: t.locality,
-					postcode: t.postcode,
-				}
-
-				// region (state) rides only the canonical render (order 0); the postcode-leading layouts
-				// omit it (matching the eval's serialization) so it never breaks verbatim alignment.
-				if (order === 0 && t.region) {
-					components.region = t.region
-				}
-
-				const aligned = reconcileComponents(components, raw)
-
-				if (!Object.keys(aligned).length) continue
-
-				yield {
-					raw,
-					components: aligned,
-					country: "AU",
-					locale: "en-AU",
-					source: GNAF_ADAPTER_ID,
-					source_id: `${stableSourceID(GNAF_ADAPTER_ID, aligned)}-o${order}`,
-					corpus_version: "",
-					license: GNAF_DEFAULT_LICENSE,
-				}
-
-				emitted++
-			}
-		},
-	}
-}
-
-/**
- * The configured adapter instance registered with the corpus builder.
- */
-export const gnafAdapter = createGNAFAdapter()

package/lib/adapters/gnaf/assemble.ts

@@ -1,225 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   Assemble a sampled, component-labeled Australian address set from G-NAF (the Geocoded National
- *   Address File — Geoscape Australia, Open G-NAF licence; any derived artifact must attribute
- *   "Geoscape Australia"). G-NAF is a relational PSV distribution (~16.9M addresses);
- *   reconstructing a street address joins three tables — ADDRESS_DETAIL (number, postcode, the
- *   PIDs) → STREET_LOCALITY (street name + type) → LOCALITY (suburb). State is the per-file prefix
- *   (ACT/NSW/…).
- *
- *   Streaming + in-memory join via the house {@link PSVSpliterator} (pipe-separated; `mode: "object"`
- *   keys each row by its header) — NOT raw `read_csv` SQL, which a flat-file join doesn't need and
- *   which the #183–190 cleanup retired. The two lookup tables (STREET_LOCALITY ~765k rows, LOCALITY
- *   ~16k) fit as Maps; ADDRESS_DETAIL is streamed once and reservoir-sampled, so memory stays
- *   bounded (the OOM lesson from the Overture ingest).
- *
- *   No coordinates: the output feeds the PARSER ({@link ../gnaf/adapter}, #208) — teaching the model
- *   AU's postcode-first / house-number-last word order, the gap `scripts/eval/au-order-probe.ts`
- *   pinned (65%→87% if the parse were order-robust). The parser needs the address string +
- *   component labels, not lat/lon.
- *
- *   Output: component tuples as JSONL, consumed by the `gnaf` corpus adapter (which renders them in
- *   multiple orders + the corpus aligner BIO-labels them). An optional held-out eval set is
- *   excluded by (street, locality, postcode) so the training slice never overlaps the benchmark.
- */
-
-import { readDirectory } from "@mailwoman/core/fs/readers"
-import { openWriteStream } from "@mailwoman/core/fs/streams"
-import { tryParsingJSON } from "@mailwoman/core/json"
-import { join } from "path-ts"
-import { PSVSpliterator, TextSpliterator } from "spliterator"
-
-export interface GNAFAssembleOptions {
-	/**
-	 * G-NAF `Standard` directory (holds the per-state `*_psv.psv` tables).
-	 */
-	standardDir: string
-	/**
-	 * Target sample size (uniform reservoir → population-proportional across states).
-	 */
-	sampleSize: number
-	/**
-	 * Output JSONL path.
-	 */
-	out: string
-	/**
-	 * Optional held-out eval JSONL (rows with a `components` field) — its (street,locality,postcode) are excluded.
-	 */
-	holdoutPath?: string
-	/**
-	 * Progress sink (the CLI passes a setter).
-	 */
-	onProgress?: (message: string) => void
-}
-
-export interface GNAFAssembleResult {
-	written: number
-	seen: number
-	heldOut: number
-	byState: Record<string, number>
-}
-
-/**
- * UPPERCASE → Title Case, preserving intra-word apostrophes/hyphens (O'Brien, Coff's Harbour).
- */
-export function titlecase(s: string): string {
-	return s
-		.toLowerCase()
-		.replaceAll(/(^|[\s'\-/])([a-z])/g, (_m, p: string, c: string) => p + c.toUpperCase())
-		.trim()
-}
-
-/**
- * Holdout/dedup key: a street within a locality+postcode (house-number-agnostic — conservative).
- */
-export function gnafHoldoutKey(street: string, locality: string, postcode: string): string {
-	return `${street}|${locality}|${postcode}`.toLowerCase()
-}
-
-type Row = Record<string, string | number | undefined>
-
-async function* psvObjects(path: string): AsyncIterable<Row> {
-	yield* PSVSpliterator.fromAsync(path, { mode: "object", header: true }) as AsyncIterable<Row>
-}
-
-/**
- * Load a small lookup table fully into a Map keyed by `keyCol`.
- */
-async function loadMap<V>(paths: string[], keyCol: string, pick: (r: Row) => V): Promise<Map<string, V>> {
-	const m = new Map<string, V>()
-
-	for (const p of paths) {
-		for await (const r of psvObjects(p)) {
-			const k = r[keyCol]
-
-			if (k != null && k !== "") {
-				m.set(String(k), pick(r))
-			}
-		}
-	}
-
-	return m
-}
-
-/**
- * Build the held-out key set from an eval JSONL whose rows carry a `components` object.
- */
-async function loadHoldout(path: string): Promise<Set<string>> {
-	const keys = new Set<string>()
-
-	for await (const line of TextSpliterator.fromAsync(path)) {
-		if (!line.trim()) continue
-
-		const c = tryParsingJSON<{ components?: Record<string, string> }>(line)?.components
-
-		if (c?.street && c?.locality && c?.postcode) {
-			keys.add(gnafHoldoutKey(c.street, c.locality, c.postcode))
-		}
-	}
-
-	return keys
-}
-
-export async function assembleGNAF(opts: GNAFAssembleOptions): Promise<GNAFAssembleResult> {
-	const progress = opts.onProgress ?? (() => {})
-	const files = await readDirectory(opts.standardDir)
-
-	const pick = (re: RegExp, exclude?: RegExp) =>
-		files.filter((f) => re.test(f) && !(exclude && exclude.test(f))).map((f) => join(opts.standardDir, f))
-
-	// `*_LOCALITY_psv.psv` also globs `*_STREET_LOCALITY_psv.psv` — exclude the latter explicitly.
-	const streetPaths = pick(/_STREET_LOCALITY_psv\.psv$/)
-	const localityPaths = pick(/_LOCALITY_psv\.psv$/, /_STREET_LOCALITY_psv\.psv$/)
-	const addressPaths = pick(/_ADDRESS_DETAIL_psv\.psv$/)
-
-	const holdout = opts.holdoutPath ? await loadHoldout(opts.holdoutPath) : new Set<string>()
-
-	if (opts.holdoutPath) {
-		progress(`held-out eval keys: ${holdout.size}`)
-	}
-
-	progress(`loading STREET_LOCALITY (${streetPaths.length} files) + LOCALITY (${localityPaths.length})…`)
-
-	const streetMap = await loadMap(streetPaths, "STREET_LOCALITY_PID", (r) => ({
-		name: String(r.STREET_NAME ?? ""),
-		type: String(r.STREET_TYPE_CODE ?? ""),
-		suffix: String(r.STREET_SUFFIX_CODE ?? ""),
-	}))
-
-	const localityMap = await loadMap(localityPaths, "LOCALITY_PID", (r) => String(r.LOCALITY_NAME ?? ""))
-	progress(`streets=${streetMap.size.toLocaleString()} localities=${localityMap.size.toLocaleString()}`)
-
-	const reservoir: Array<{ house_number: string; street: string; locality: string; region: string; postcode: string }> =
-		[]
-
-	let seen = 0
-	let heldOut = 0
-
-	for (const p of addressPaths) {
-		const state = (p.match(/\/([A-Z]+)_ADDRESS_DETAIL/) ?? [])[1] ?? ""
-
-		for await (const r of psvObjects(p)) {
-			const numberFirst = String(r.NUMBER_FIRST ?? "")
-
-			if (!numberFirst || r.DATE_RETIRED || !r.POSTCODE) continue
-			const st = streetMap.get(String(r.STREET_LOCALITY_PID ?? ""))
-			const suburbRaw = localityMap.get(String(r.LOCALITY_PID ?? ""))
-
-			if (!st?.name || !suburbRaw) continue
-			const street = `${titlecase(st.name)} ${titlecase(st.type)}${st.suffix ? " " + titlecase(st.suffix) : ""}`.trim()
-			const locality = titlecase(suburbRaw)
-			const postcode = String(r.POSTCODE)
-
-			if (holdout.has(gnafHoldoutKey(street, locality, postcode))) {
-				heldOut++
-
-				continue
-			}
-
-			let house = numberFirst + (r.NUMBER_FIRST_SUFFIX ? String(r.NUMBER_FIRST_SUFFIX) : "")
-
-			if (r.NUMBER_LAST) {
-				house = `${house}-${String(r.NUMBER_LAST)}`
-			}
-
-			if (r.FLAT_NUMBER) {
-				house = `${String(r.FLAT_NUMBER)}/${house}`
-			}
-
-			const tuple = { house_number: house, street, locality, region: state, postcode }
-
-			seen++
-
-			if (reservoir.length < opts.sampleSize) {
-				reservoir.push(tuple)
-			} else {
-				const j = Math.floor(Math.random() * seen)
-
-				if (j < opts.sampleSize) {
-					reservoir[j] = tuple
-				}
-			}
-		}
-
-		progress(`${state}: ${seen.toLocaleString()} valid joinable seen`)
-	}
-
-	const out = openWriteStream(opts.out)
-	const byState: Record<string, number> = {}
-
-	for (const t of reservoir) {
-		out.write(JSON.stringify(t) + "\n")
-		byState[t.region] = (byState[t.region] ?? 0) + 1
-	}
-
-	await new Promise<void>((res) => {
-		out.end(res)
-	})
-
-	progress(`wrote ${reservoir.length.toLocaleString()} tuples → ${opts.out}`)
-
-	return { written: reservoir.length, seen, heldOut, byState }
-}

package/lib/adapters/index.ts

@@ -1,153 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   Adapter registry bootstrap.
- *
- *   Importing this module registers every built-in adapter with `defaultAdapterRegistry`. The CLI
- *   (`commands/corpus/list.tsx`, `commands/corpus/run.tsx`) imports it once at startup.
- *
- *   Adapters under construction live in their own subdirectories (`./wof-admin-json/`, `./ban/`, ...)
- *   and are added to the `BUILTIN_ADAPTERS` list here as they come online. Tests that need a
- *   pristine registry should construct their own `InMemoryAdapterRegistry` instead of mutating the
- *   default.
- *
- *   The WOF adapters export their canonical ids — `wof-admin` and `wof-postalcode` — so existing
- *   `mailwoman corpus build` callsites do not need to change despite the Phase 1.5.1 SQLite →
- *   JSON-bundle pivot (`./wof-admin-json/` and `./wof-postalcode-json/` directories hold the
- *   implementations; the registered ids are unchanged).
- */
-
-import { banAdapter } from "#adapters/ban/adapter"
-import { fccBdcAdapter } from "#adapters/fcc-bdc/adapter"
-import { geonamesPostalAdapter } from "#adapters/geonames-postal/adapter"
-import { geonamesAdapter } from "#adapters/geonames/adapter"
-import { gnafAdapter } from "#adapters/gnaf/adapter"
-import { openaddressesAdapter } from "#adapters/openaddresses/adapter"
-import { overtureAdapter } from "#adapters/overture/adapter"
-import { stateHiSchoolsAdapter } from "#adapters/state-hi-schools/adapter"
-import { stateIaContractorsAdapter } from "#adapters/state-ia-contractors/adapter"
-import { stateNyNotariesAdapter } from "#adapters/state-ny-notaries/adapter"
-import { stateTxNotariesAdapter } from "#adapters/state-tx-notaries/adapter"
-import { tigerAdapter } from "#adapters/tiger/adapter"
-import { usgovHrsaFqhcAdapter } from "#adapters/usgov-hrsa-fqhc/adapter"
-import { usgovImlsPlsAdapter } from "#adapters/usgov-imls-pls/adapter"
-import { USGovIRSBMFAdapter } from "#adapters/usgov-irs-bmf/adapter"
-import { usgovNADAdapter } from "#adapters/usgov-nad/adapter"
-import { usgovNPPESAdapter } from "#adapters/usgov-nppes/adapter"
-import { defaultAdapterRegistry } from "#adapters/utils"
-import { wofAdminAdapter } from "#adapters/wof-admin-json/adapter"
-import { wofPostalcodeAdapter } from "#adapters/wof-postalcode-json/adapter"
-import type { CorpusAdapter } from "#types"
-
-/**
- * Built-in adapters. Order is significant: `corpus build` iterates this list to drive every adapter in turn.
- * Coarse-first (admin → postcode), then street-level (BAN FR, TIGER US, OpenAddresses global), then adversarial-source
- * (FCC BDC US, HRSA FQHC US).
- *
- * The `usgov-samhsa-treatment-locator` adapter is intentionally absent from this list — the SAMHSA Open Data Foundry
- * bulk CSV the adapter was written against is no longer publicly distributed (see issue #33, 2026-05-17 investigation).
- * The factory + named export remain available so the adapter can be hand-registered if an operator obtains a compatible
- * CSV (FOIA, partner channel, upstream restoration). Re-add it here once a stable public source returns.
- */
-export const BUILTIN_ADAPTERS: readonly CorpusAdapter[] = [
-	wofAdminAdapter,
-	wofPostalcodeAdapter,
-	geonamesAdapter,
-	geonamesPostalAdapter,
-	banAdapter,
-	tigerAdapter,
-	openaddressesAdapter,
-	overtureAdapter,
-	gnafAdapter,
-	fccBdcAdapter,
-	usgovHrsaFqhcAdapter,
-	usgovNPPESAdapter,
-	usgovNADAdapter,
-	usgovImlsPlsAdapter,
-	USGovIRSBMFAdapter,
-	stateIaContractorsAdapter,
-	stateTxNotariesAdapter,
-	stateNyNotariesAdapter,
-	stateHiSchoolsAdapter,
-]
-
-for (const adapter of BUILTIN_ADAPTERS) {
-	if (!defaultAdapterRegistry.get(adapter.id)) {
-		defaultAdapterRegistry.register(adapter)
-	}
-}
-
-export { BAN_ADAPTER_ID, banAdapter } from "#adapters/ban/adapter"
-export { FCC_BDC_ADAPTER_ID, FCC_BDC_DEFAULT_LICENSE, fccBdcAdapter } from "#adapters/fcc-bdc/adapter"
-
-export {
-	GEONAMES_POSTAL_ADAPTER_ID,
-	GEONAMES_POSTAL_DEFAULT_LICENSE,
-	geonamesPostalAdapter,
-} from "#adapters/geonames-postal/adapter"
-
-export { GEONAMES_ADAPTER_ID, GEONAMES_DEFAULT_LICENSE, geonamesAdapter } from "#adapters/geonames/adapter"
-
-export {
-	OPENADDRESSES_ADAPTER_ID,
-	OPENADDRESSES_DEFAULT_LICENSE,
-	openaddressesAdapter,
-} from "#adapters/openaddresses/adapter"
-
-export {
-	STATE_HI_SCHOOLS_ADAPTER_ID,
-	STATE_HI_SCHOOLS_DEFAULT_LICENSE,
-	stateHiSchoolsAdapter,
-} from "#adapters/state-hi-schools/adapter"
-
-export {
-	STATE_IA_CONTRACTORS_ADAPTER_ID,
-	STATE_IA_CONTRACTORS_DEFAULT_LICENSE,
-	stateIaContractorsAdapter,
-} from "#adapters/state-ia-contractors/adapter"
-
-export {
-	STATE_NY_NOTARIES_ADAPTER_ID,
-	STATE_NY_NOTARIES_DEFAULT_LICENSE,
-	stateNyNotariesAdapter,
-} from "#adapters/state-ny-notaries/adapter"
-
-export {
-	STATE_TX_NOTARIES_ADAPTER_ID,
-	STATE_TX_NOTARIES_DEFAULT_LICENSE,
-	stateTxNotariesAdapter,
-} from "#adapters/state-tx-notaries/adapter"
-
-export { TIGER_ADAPTER_ID, TIGER_DEFAULT_LICENSE, tigerAdapter } from "#adapters/tiger/adapter"
-
-export {
-	USGOV_HRSA_FQHC_ADAPTER_ID,
-	USGOV_HRSA_FQHC_DEFAULT_LICENSE,
-	usgovHrsaFqhcAdapter,
-} from "#adapters/usgov-hrsa-fqhc/adapter"
-
-export {
-	USGOV_IMLS_PLS_ADAPTER_ID,
-	USGOV_IMLS_PLS_DEFAULT_LICENSE,
-	usgovImlsPlsAdapter,
-} from "#adapters/usgov-imls-pls/adapter"
-
-export {
-	USGOV_IRS_BMF_ADAPTER_ID,
-	USGOV_IRS_BMF_DEFAULT_LICENSE,
-	USGovIRSBMFAdapter,
-} from "#adapters/usgov-irs-bmf/adapter"
-
-export { USGOV_NAD_ADAPTER_ID, USGOV_NAD_DEFAULT_LICENSE, usgovNADAdapter } from "#adapters/usgov-nad/adapter"
-export { USGOV_NPPES_ADAPTER_ID, USGOV_NPPES_DEFAULT_LICENSE, usgovNPPESAdapter } from "#adapters/usgov-nppes/adapter"
-
-export {
-	USGOV_SAMHSA_ADAPTER_ID,
-	USGOV_SAMHSA_DEFAULT_LICENSE,
-	usgovSamhsaTreatmentLocatorAdapter,
-} from "#adapters/usgov-samhsa-treatment-locator/adapter"
-
-export { WOF_ADMIN_ADAPTER_ID, wofAdminAdapter } from "#adapters/wof-admin-json/adapter"
-export { WOF_POSTALCODE_ADAPTER_ID, wofPostalcodeAdapter } from "#adapters/wof-postalcode-json/adapter"

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

@@ -1,170 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   `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,
- *   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.
- *   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
- *   surfaced as `subregion`.
- *
- *   Output: one row per school with `venue` (school name), `(house_number?, street, locality,
- *   region=HI, postcode)`, and a stable `source_id` derived from the school `code`.
- *
- *   License: stamped `"Public Domain"` per Hawaii state government open-data terms.
- */
-
-import { isPresent } from "@mailwoman/core/objects"
-import { reconcileComponents } from "@mailwoman/formatter"
-import { CSVSpliterator, XLSXSpliterator } from "spliterator"
-
-import { type HiSchoolRow, schoolCellText, STATE_HI_SCHOOL_SHEETS } from "#adapters/state-hi-schools/workbook"
-import { splitStreetLine, stableSourceID } 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 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.
- */
-export const STATE_HI_SCHOOLS_DEFAULT_LICENSE = "Public Domain"
-
-const HI_STATE_ABBR = "HI"
-
-function normalizeZip(raw: HiSchoolRow["zip"]): string {
-	const trimmed = schoolCellText(raw)
-
-	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).
-	if (/^\d{4}$/.test(trimmed)) return `0${trimmed}`
-
-	return trimmed
-}
-
-async function* readSchoolRows(inputPath: string): AsyncGenerator<HiSchoolRow> {
-	if (inputPath.toLowerCase().endsWith(".xlsx")) {
-		for (const sheet of STATE_HI_SCHOOL_SHEETS) {
-			yield* XLSXSpliterator.fromAsync<HiSchoolRow>(inputPath, {
-				sheet,
-				mode: "object",
-				normalizeKeys: false,
-			})
-		}
-
-		return
-	}
-
-	yield* CSVSpliterator.fromAsync<HiSchoolRow>(inputPath, {
-		mode: "object",
-		normalizeKeys: false,
-		enableQuoteHandling: true,
-	})
-}
-
-export function createStateHiSchoolsAdapter(): CorpusAdapter {
-	return {
-		id: STATE_HI_SCHOOLS_ADAPTER_ID,
-		defaultLicense: STATE_HI_SCHOOLS_DEFAULT_LICENSE,
-		description: "Hawaii DOE School Directory — ~300 K-12 public + charter schools with venue+address (public-domain).",
-
-		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
-			if (opts.country && opts.country !== "US") {
-				throw new Error(`state-hi-schools adapter: only US supported, got country=${opts.country}`)
-			}
-
-			const state = lookupStateAbbreviation(HI_STATE_ABBR)
-
-			if (!state) {
-				throw new Error(`state-hi-schools adapter: HI not found in state codex (corpus bug)`)
-			}
-
-			let emitted = 0
-
-			for await (const record of readSchoolRows(opts.inputPath)) {
-				if (opts.signal?.aborted) break
-
-				if (opts.limit !== undefined && emitted >= opts.limit) break
-
-				const name = schoolCellText(record.name)
-				const address = schoolCellText(record.address)
-				const city = schoolCellText(record.city)
-				const zip = normalizeZip(record.zip)
-
-				if (!name || !address || !city || !zip) continue
-
-				const split = splitStreetLine(address)
-
-				if (!split) continue
-
-				const components: CanonicalRow["components"] = {
-					venue: name,
-					...(split.house_number ? { house_number: split.house_number } : {}),
-					street: split.street,
-					locality: city,
-					region: state.abbreviation,
-					postcode: zip,
-				}
-
-				const streetPart = [split.house_number, split.street].filter(isPresent).join(" ").trim()
-
-				const raw = [
-					name,
-					streetPart,
-					[city, [HI_STATE_ABBR, zip].filter(isPresent).join(" ")].filter(isPresent).join(", "),
-				]
-					.filter(isPresent)
-					.join(", ")
-
-				const aligned = reconcileComponents(components, raw)
-
-				if (Object.keys(aligned).length <= 2) continue
-
-				const code = schoolCellText(record.code)
-
-				const sourceID = code
-					? `${STATE_HI_SCHOOLS_ADAPTER_ID}-${code}`
-					: stableSourceID(STATE_HI_SCHOOLS_ADAPTER_ID, aligned)
-
-				yield {
-					raw,
-					components: aligned,
-					country: "US",
-					locale: "en-US",
-					source: STATE_HI_SCHOOLS_ADAPTER_ID,
-					source_id: sourceID,
-					corpus_version: "",
-					license: STATE_HI_SCHOOLS_DEFAULT_LICENSE,
-				}
-
-				emitted++
-			}
-		},
-	}
-}
-
-/**
- * The configured adapter instance registered with the corpus builder.
- */
-export const stateHiSchoolsAdapter = createStateHiSchoolsAdapter()