@mailwoman/corpus 10.0.0 → 10.1.0

package/lib/adapters/index.ts

@@ -1,160 +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 { geonamesAdapter } from "#adapters/geonames/adapter"
-import { geonamesPostalAdapter } from "#adapters/geonames/postal/adapter"
-import { openaddressesAdapter } from "#adapters/openaddresses/adapter"
-import { osmAdapter } from "#adapters/osm/adapter"
-import { overtureAdapter } from "#adapters/overture/adapter"
-import { defaultAdapterRegistry } from "#adapters/utils"
-import { wofAdminAdapter } from "#adapters/wof/admin/json/adapter"
-import { wofPostalcodeAdapter } from "#adapters/wof/postalcode-json/adapter"
-import { gnafAdapter } from "#au/adapters/gnaf/adapter"
-import { banAdapter } from "#fr/adapters/ban/adapter"
-import type { CorpusAdapter } from "#types"
-import { fccBdcAdapter } from "#us/adapters/fcc-bdc/adapter"
-import { stateHiSchoolsAdapter } from "#us/adapters/state/hi-schools/adapter"
-import { stateIaContractorsAdapter } from "#us/adapters/state/ia-contractors/adapter"
-import { stateNyNotariesAdapter } from "#us/adapters/state/ny-notaries/adapter"
-import { stateTxNotariesAdapter } from "#us/adapters/state/tx-notaries/adapter"
-import { tigerAdapter } from "#us/adapters/tiger/adapter"
-import { usgovHrsaFqhcAdapter } from "#us/adapters/usgov/hrsa-fqhc/adapter"
-import { usgovImlsPlsAdapter } from "#us/adapters/usgov/imls-pls/adapter"
-import { USGovIRSBMFAdapter } from "#us/adapters/usgov/irs-bmf/adapter"
-import { usgovNADAdapter } from "#us/adapters/usgov/nad/adapter"
-import { usgovNPPESAdapter } from "#us/adapters/usgov/nppes/adapter"
-
-/**
- * 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,
-	osmAdapter,
-	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 "#fr/adapters/ban/adapter"
-export { FCC_BDC_ADAPTER_ID, FCC_BDC_DEFAULT_LICENSE, fccBdcAdapter } from "#us/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 "#us/adapters/state/hi-schools/adapter"
-
-export {
-	STATE_IA_CONTRACTORS_ADAPTER_ID,
-	STATE_IA_CONTRACTORS_DEFAULT_LICENSE,
-	stateIaContractorsAdapter,
-} from "#us/adapters/state/ia-contractors/adapter"
-
-export {
-	STATE_NY_NOTARIES_ADAPTER_ID,
-	STATE_NY_NOTARIES_DEFAULT_LICENSE,
-	stateNyNotariesAdapter,
-} from "#us/adapters/state/ny-notaries/adapter"
-
-export {
-	STATE_TX_NOTARIES_ADAPTER_ID,
-	STATE_TX_NOTARIES_DEFAULT_LICENSE,
-	stateTxNotariesAdapter,
-} from "#us/adapters/state/tx-notaries/adapter"
-
-export { TIGER_ADAPTER_ID, TIGER_DEFAULT_LICENSE, tigerAdapter } from "#us/adapters/tiger/adapter"
-
-export {
-	USGOV_HRSA_FQHC_ADAPTER_ID,
-	USGOV_HRSA_FQHC_DEFAULT_LICENSE,
-	usgovHrsaFqhcAdapter,
-} from "#us/adapters/usgov/hrsa-fqhc/adapter"
-
-export {
-	USGOV_IMLS_PLS_ADAPTER_ID,
-	USGOV_IMLS_PLS_DEFAULT_LICENSE,
-	usgovImlsPlsAdapter,
-} from "#us/adapters/usgov/imls-pls/adapter"
-
-export {
-	USGOV_IRS_BMF_ADAPTER_ID,
-	USGOV_IRS_BMF_DEFAULT_LICENSE,
-	USGovIRSBMFAdapter,
-} from "#us/adapters/usgov/irs-bmf/adapter"
-
-export { USGOV_NAD_ADAPTER_ID, USGOV_NAD_DEFAULT_LICENSE, usgovNADAdapter } from "#us/adapters/usgov/nad/adapter"
-
-export {
-	USGOV_NPPES_ADAPTER_ID,
-	USGOV_NPPES_DEFAULT_LICENSE,
-	usgovNPPESAdapter,
-} from "#us/adapters/usgov/nppes/adapter"
-
-export {
-	USGOV_SAMHSA_ADAPTER_ID,
-	USGOV_SAMHSA_DEFAULT_LICENSE,
-	usgovSamhsaTreatmentLocatorAdapter,
-} from "#us/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/synth-po-box/adapter.ts

@@ -1,204 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   `synth-po-box`: PO box / PMB / Apartado / BP synthesizer adapter.
- *
- *   Consumes a JSONL stream of (locality, region, postcode, country) tuples — typically extracted
- *   from existing corpus output (TIGER/NAD/BAN/WOF) — and emits synthetic PO box training rows. See
- *   `@mailwoman/corpus/synthesizers/po-box` for the per-locale templates and number-noise logic.
- *
- *   Why an adapter and not an augmenter:
- *
- *   - Per USPS Pub 28 / DMM 508, a PO box delivery line is mutually exclusive with a street line.
- *       Synthesizing PO boxes by mutating a street row would teach the model an invalid pattern.
- *       The clean shape is: read just (locality, region, postcode, country) and produce a fresh
- *       PO-box-shaped row.
- *   - Per-DeepSeek (3-turn consult, 2026-05-28): PMB rows that COMBINE a street line with a PMB number
- *       ARE valid (CMRA addresses). Those are produced when `pmbRatio > 0` AND the input tuple
- *       carries a `street` field.
- */
-
-import { tryParsingJSON } from "@mailwoman/core/json"
-import { makeLcg } from "@mailwoman/core/random"
-import { TextSpliterator } from "spliterator"
-
-import { stableSourceID } from "#adapters/utils"
-import {
-	countryToLocale,
-	REGION_OPTIONAL_LOCALES,
-	synthesizeMilitaryPoBoxRow,
-	synthesizePoBoxRow,
-	type PoBoxBaseTuple,
-} from "#synthesizers/po-box"
-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 SYNTH_PO_BOX_ADAPTER_ID = "synth-po-box"
-/**
- * License for the synthetic PO-box rows. The output is generated, but it inherits the terms of the real tuples it is
- * derived from, so the attribution travels with it.
- */
-export const SYNTH_PO_BOX_LICENSE = "Synthetic — derived from CC-BY / public-domain input tuples"
-
-export interface PoBoxInputRow extends PoBoxBaseTuple {
-	street?: string
-	houseNumber?: string
-}
-
-export interface SynthPoBoxAdapterOptions {
-	/**
-	 * How many PO box variants to emit per input tuple. Each variant picks a different leader (and possibly a different
-	 * number / noise level). Default 1.
-	 */
-	variantsPerInput?: number
-	/**
-	 * Probability (0..1) of emitting a PMB-with-street variant when both the input has a street and the locale supports
-	 * PMB. Default 0.15.
-	 */
-	pmbRatio?: number
-	/**
-	 * Deterministic seed for reproducible synthesis. Default Date.now().
-	 */
-	seed?: number
-	/**
-	 * Probability (0..1), evaluated per input tuple, of ALSO emitting one US military/diplomatic PO-box row
-	 * (`PSC/CMR/Unit <id> Box <box>, APO/FPO/DPO AA/AE/AP <zip>`, #517). These rows are self-contained — they draw no
-	 * field from the input tuple, so military volume scales with the input stream size. Default 0 (off) — the adapter's
-	 * contract is "one row per input"; the corpus build recipe opts in to seed the rare-but-real military class without
-	 * changing the default.
-	 */
-	militaryRatio?: number
-}
-
-export function createSynthPoBoxAdapter(opts: SynthPoBoxAdapterOptions = {}): CorpusAdapter {
-	const variantsPerInput = opts.variantsPerInput ?? 1
-	const pmbRatio = opts.pmbRatio ?? 0.15
-	const militaryRatio = opts.militaryRatio ?? 0
-
-	return {
-		id: SYNTH_PO_BOX_ADAPTER_ID,
-		defaultLicense: SYNTH_PO_BOX_LICENSE,
-		description:
-			"Synthetic PO box / PMB / Apartado / Boîte Postale rows. Consumes JSONL of (locality, region, postcode, country) tuples and emits locale-appropriate PO box variants.",
-
-		async *rows(options: AdapterOptions): AsyncIterable<CanonicalRow> {
-			const random = makeLcg(opts.seed ?? Date.now())
-
-			// TextSpliterator streams string lines; the per-line tryParsingJSON below keeps this reader
-			// tolerant of malformed rows (skipped++), so TextSpliterator + a non-throwing parse — not
-			// JSONSpliterator, which would throw on the first bad line.
-			const lines = TextSpliterator.fromAsync(options.inputPath)
-
-			let emitted = 0
-			let skipped = 0
-			let militarySeq = 0
-
-			for await (const line of lines) {
-				if (options.signal?.aborted) break
-
-				if (options.limit !== undefined && emitted >= options.limit) break
-
-				const trimmed = line.trim()
-
-				if (!trimmed) continue
-
-				const input = tryParsingJSON<PoBoxInputRow>(trimmed)
-
-				if (input === null) {
-					skipped++
-
-					continue
-				}
-
-				// Region is required EXCEPT for region-less locales (NZ: `Private Bag 12, Auckland 1010`
-				// has no region token, #517). synthesizePoBoxRow handles region absence; the guard just
-				// must not discard those tuples as "missing region".
-				const regionOptional = input.country ? REGION_OPTIONAL_LOCALES.has(countryToLocale(input.country)) : false
-
-				if (!input.locality || !input.postcode || !input.country || (!input.region && !regionOptional)) {
-					skipped++
-
-					continue
-				}
-
-				if (options.country && options.country !== input.country) continue
-
-				for (let v = 0; v < variantsPerInput; v++) {
-					const synth = synthesizePoBoxRow(input, { random, pmbRatio })
-
-					if (!synth) continue
-
-					// Include `v` in dependent_locality slot to vary the digest across variants;
-					// stableSourceID only accepts ComponentTag keys.
-					const sourceID = stableSourceID(SYNTH_PO_BOX_ADAPTER_ID, {
-						locality: `${input.locality}#${v}`,
-						region: input.region,
-						postcode: input.postcode,
-						country: input.country,
-					})
-
-					yield {
-						raw: synth.raw,
-						components: synth.components,
-						country: input.country,
-						locale: synth.locale,
-						source: SYNTH_PO_BOX_ADAPTER_ID,
-						source_id: sourceID,
-						corpus_version: "",
-						license: SYNTH_PO_BOX_LICENSE,
-					}
-
-					emitted++
-
-					if (options.limit !== undefined && emitted >= options.limit) break
-				}
-
-				// US military/diplomatic PO-box rows (#517): self-contained — draw nothing from the input
-				// tuple — emitted per input line with probability `militaryRatio` (off by default, so the
-				// default random stream and output are byte-identical). Military volume scales with the
-				// stream rather than the US-tuple count. US-only: suppressed under a non-US country filter
-				// and counted against `limit` like any other row.
-				const militaryAllowed = !options.country || options.country === "US"
-
-				if (
-					militaryRatio > 0 &&
-					militaryAllowed &&
-					(options.limit === undefined || emitted < options.limit) &&
-					random() < militaryRatio
-				) {
-					const mil = synthesizeMilitaryPoBoxRow({ random })
-
-					const sourceID = stableSourceID(SYNTH_PO_BOX_ADAPTER_ID, {
-						po_box: `${mil.components.po_box}#mil${militarySeq++}`,
-						locality: mil.components.locality!,
-						region: mil.components.region!,
-						postcode: mil.components.postcode!,
-					})
-
-					yield {
-						raw: mil.raw,
-						components: mil.components,
-						country: "US",
-						locale: mil.locale,
-						source: SYNTH_PO_BOX_ADAPTER_ID,
-						source_id: sourceID,
-						corpus_version: "",
-						license: SYNTH_PO_BOX_LICENSE,
-					}
-
-					emitted++
-				}
-			}
-		},
-	}
-}
-
-/**
- * The configured adapter instance registered with the corpus builder.
- */
-export const synthPoBoxAdapter = createSynthPoBoxAdapter()

package/lib/adapters/utils/index.ts

@@ -1,307 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   Adapter framework helpers — the pieces every corpus adapter and the runner share.
- *
- *   This file does **not** define `CorpusAdapter` (that lives in `./types.ts`, which is the single
- *   canonical schema module). It exposes:
- *
- *   - `AdapterRegistry`: a tiny lookup table the CLI + build pipeline use to find adapters by id.
- *   - `InMemoryAdapterRegistry`: the default implementation.
- *   - `stableSourceID(adapterID, components)`: deterministic content-addressed id for adapters whose
- *       source data has no native primary key (CSV, GeoJSON).
- *   - `HOUSE_NUMBER_PREFIX` + `splitStreetLine(line)`: the one house-number/street split every
- *       US CSV adapter uses.
- *   - `composeRaw(parts)`: the envelope-style raw line every US CSV adapter renders.
- *   - `canonicalDedupKey(row)`: normalized signature used to drop near-identical rows during a run.
- *       Adapter-internal dedup; cross-adapter dedup is the runner's job.
- *   - `streamingSha256()`: thin wrapper around `node:crypto` so the runner can hash JSONL output as it
- *       streams (avoids re-reading the slice for the manifest checksum).
- *   - `loadLibpostalDictionary(language, filename)`: the curated libpostal dictionary reader the
- *       street-decompose modules share — the one read this module performs; everything else here is
- *       pure, and other side-effecting code goes in `./runner.ts`.
- */
-
-import type { ComponentTag } from "@mailwoman/codex/component"
-import { readLocalTextFile } from "@mailwoman/core/fs/readers"
-import { sha256Hex, createHash, type Hash } from "@mailwoman/core/hash"
-import { isPresent } from "@mailwoman/core/objects"
-import { resourceDictionaryPath } from "@mailwoman/core/paths"
-import { TextSpliterator } from "spliterator"
-
-import type { CanonicalRow, CorpusAdapter } from "#types"
-
-/**
- * Lookup table for corpus adapters.
- *
- * The CLI's `npx mailwoman corpus run <adapter-id>` resolves `<adapter-id>` against this registry; the same registry is
- * iterated by the `corpus build` pipeline. Adapters do not self-register at module load — they're added explicitly so
- * the dependency graph stays traceable.
- */
-export interface AdapterRegistry {
-	/**
-	 * Add an adapter. Throws if `adapter.id` is already registered.
-	 */
-	register(adapter: CorpusAdapter): void
-
-	/**
-	 * Return the adapter for `id`, or `undefined`.
-	 */
-	get(id: string): CorpusAdapter | undefined
-
-	/**
-	 * All registered adapters, in insertion order.
-	 */
-	list(): readonly CorpusAdapter[]
-
-	/**
-	 * Convenience: ids only, in insertion order.
-	 */
-	ids(): readonly string[]
-}
-
-/**
- * Default in-memory registry. The runner constructs one per invocation; the CLI re-uses a shared singleton
- * (`defaultAdapterRegistry`) populated by `./adapters/index.ts` as adapters come online.
- */
-export class InMemoryAdapterRegistry implements AdapterRegistry {
-	#byID = new Map<string, CorpusAdapter>()
-
-	register(adapter: CorpusAdapter): void {
-		if (this.#byID.has(adapter.id)) {
-			throw new Error(`AdapterRegistry: id ${JSON.stringify(adapter.id)} already registered`)
-		}
-
-		this.#byID.set(adapter.id, adapter)
-	}
-
-	get(id: string): CorpusAdapter | undefined {
-		return this.#byID.get(id)
-	}
-
-	list(): readonly CorpusAdapter[] {
-		return Array.from(this.#byID.values())
-	}
-
-	ids(): readonly string[] {
-		return Array.from(this.#byID.keys())
-	}
-}
-
-/**
- * Process-wide default registry. Populated by `./adapters/index.ts` as adapters are built; imported by the CLI. Tests
- * should construct their own `InMemoryAdapterRegistry` to avoid cross-test pollution.
- */
-export const defaultAdapterRegistry = new InMemoryAdapterRegistry()
-
-/**
- * Deterministic content-addressed source id.
- *
- * For adapters whose upstream source has no native primary key (CSV rows, GeoJSON features), the runner expects a
- * stable id so dedup, holdout manifests, and resumability work across reruns. This helper produces one by hashing the
- * adapter id and a canonical serialization of the components dict (keys sorted, values verbatim).
- *
- * Output format: `<adapterID>-<first-12-hex-chars-of-sha256>`. 48 bits of entropy is enough for ~17M rows per adapter
- * before the expected collision count exceeds 1 (birthday paradox); adapters with more rows should extend the prefix
- * length.
- */
-export function stableSourceID(adapterID: string, components: Partial<Record<ComponentTag, string>>): string {
-	return stableSourceIDFromParts(adapterID, components)
-}
-
-/**
- * {@link stableSourceID} over arbitrary disambiguator keys — a variant index, a slot number, anything that is not a
- * `ComponentTag`. Every key handed in is sorted and hashed either way; only the key vocabulary differs, and the narrow
- * signature above is what stops an adapter hashing a misspelled component name.
- */
-export function stableSourceIDFromParts(
-	adapterID: string,
-	parts: Readonly<Record<string, string | undefined>>
-): string {
-	const sortedKeys = Object.keys(parts).toSorted()
-	const payload = sortedKeys.map((k) => `${k}=${parts[k] ?? ""}`).join("\u001F")
-	// One `update` over the joined string, not three chained ones — identical byte stream either way,
-	// but the separator has to stay inline or every id in every slice changes.
-	const digest = sha256Hex(`${adapterID}\u001E${payload}`)
-
-	return `${adapterID}-${digest.slice(0, 12)}`
-}
-
-/**
- * Leading house number on a US-style street line: digits, an optional hyphenated range (Queens `40-12`), an optional
- * single alpha suffix (`101A`), then whitespace, then the rest.
- *
- * This decides where the house number ends and the street begins for every US CSV adapter, so an edge case fixed here
- * is fixed for all of them.
- *
- * The remainder must stay `(\S.*)` and must NOT become `(.+)`: `\s+` and `.` both match a tab, so `\s+(.+)$` lets the
- * engine split a run of tabs between the two groups every possible way before failing — quadratic backtracking on
- * attacker-shaped input. Requiring a non-space start removes the overlap. Group 2 is trimmed by the caller either way,
- * so the two forms are indistinguishable on real input; only the failure cost differs.
- */
-export const HOUSE_NUMBER_PREFIX = /^(\d+(?:-\d+)?[A-Za-z]?)\s+(\S.*)$/
-
-/**
- * A street line split into its house number and the remainder.
- */
-export interface SplitStreetLine {
-	house_number?: string
-	street: string
-}
-
-/**
- * Split a US-style street line on {@link HOUSE_NUMBER_PREFIX}.
- *
- * The US CSV sources follow USPS Publication 28 conventions with hand-entry drift. The leading digit run is the house
- * number (`"123 Main St"`, `"6450 W Indian School Rd"`), and the regex tolerates one trailing letter (`"123A Main St"`)
- * plus an optional hyphenated half (`"40-12 Bell Blvd"`, common in NYC and suburban garden-apartment numbering; Hawaii
- * uses it island-wide — `"47-470 Hui Aeko Place"`).
- *
- * Returns `null` for blank input. Anything that does not match the prefix shape (`"PO Box 1234"`, `"RR 2 Box 67"`, `"HC
- * 1"`) becomes a single `street` value rather than being mangled — the model sees the original surface form and
- * downstream classifiers pick it up. Callers that need those forms recognized as something other than a street (see
- * `usgov-irs-bmf`) test for them BEFORE calling this.
- */
-export function splitStreetLine(line: string): SplitStreetLine | null {
-	const trimmed = line.trim()
-
-	if (!trimmed) return null
-
-	const match = HOUSE_NUMBER_PREFIX.exec(trimmed)
-
-	if (match) return { house_number: match[1], street: match[2]!.trim() }
-
-	return { street: trimmed }
-}
-
-/**
- * Parts of the envelope-style raw line {@link composeRaw} renders. Every field is dropped when empty, so a caller only
- * supplies what its source carries.
- */
-export interface ComposeRawParts {
-	venue?: string
-	houseNumber?: string
-	street?: string
-	/**
-	 * A street line already joined by the caller (e.g. a PO-box phrase) — used INSTEAD of `houseNumber`/`street`/`unit`
-	 * when present.
-	 */
-	streetLine?: string
-	unit?: string
-	locality: string
-	region?: string
-	postcode: string
-}
-
-/**
- * Compose the envelope-style raw address line the US CSV adapters share:
- *
- * `"<venue>, <house> <street> <unit>, <city>, <state> <postcode>"`
- *
- * The venue leads (US conventional addressee-then-address ordering) so a downstream model sees the
- * venue-prefix-then-address shape users actually type into geocoders. Empty segments drop out rather than leaving a
- * dangling separator.
- */
-export function composeRaw(parts: ComposeRawParts): string {
-	const streetLine =
-		parts.streetLine ?? [parts.houseNumber, parts.street, parts.unit].filter(isPresent).join(" ").trim()
-
-	const tail = [parts.locality.trim(), [parts.region, parts.postcode].filter(isPresent).join(" ").trim()]
-		.filter(isPresent)
-		.join(", ")
-
-	return [parts.venue, streetLine || undefined, tail].filter(isPresent).join(", ")
-}
-
-/**
- * Load one curated libpostal dictionary (`core/data/libpostal/dictionaries/<language>/<filename>`) as a lower-cased
- * form set. libpostal format: `canonical|abbr|abbr|...` — every form is indexed.
- *
- * `resourceDictionaryPath` already resolves both layouts — `core/data/...` from source and from the packaged `out/`
- * tree. The candidate list this replaced named it TWICE and then guessed a third path off `process.cwd()`, and
- * swallowed every error while probing, so a corrupt dictionary reported as a missing one.
- *
- * The largest libpostal dictionary is 8.4 KB, and each caller runs this once per process at module load.
- */
-export async function loadLibpostalDictionary(language: string, filename: string): Promise<Set<string>> {
-	const text = await readLocalTextFile(resourceDictionaryPath("libpostal", language, filename))
-	const set = new Set<string>()
-
-	for (const line of TextSpliterator.from(text)) {
-		const trimmed = line.trim()
-
-		if (!trimmed || trimmed.startsWith("#")) continue
-
-		for (const form of trimmed.split("|")) {
-			const f = form.trim().toLowerCase()
-
-			if (f) {
-				set.add(f)
-			}
-		}
-	}
-
-	return set
-}
-
-/**
- * Canonical dedup key for a row.
- *
- * Two rows that share this key are treated as duplicates and only the first wins. The key is built from `country`, the
- * sorted `components` dict, and a normalized `raw` (lower-cased, whitespace collapsed). License and provenance fields
- * are intentionally excluded so the same address from multiple adapters is recognized as a duplicate.
- *
- * Synthetic rows are never deduplicated against natural rows: `synth.method` is folded into the key when present,
- * ensuring each augmentation variant survives.
- */
-export function canonicalDedupKey(row: CanonicalRow): string {
-	const sortedKeys = Object.keys(row.components).toSorted() as ComponentTag[]
-	const compPart = sortedKeys.map((k) => `${k}=${row.components[k] ?? ""}`).join("\u001F")
-	const rawNorm = row.raw.toLowerCase().replaceAll(/\s+/g, " ").trim()
-	const synthPart = row.synth ? `\u001E${row.synth.method}` : ""
-
-	return `${row.country}\u001E${rawNorm}\u001E${compPart}${synthPart}`
-}
-
-/**
- * Streaming SHA-256 hasher.
- *
- * The runner feeds every JSONL line into one of these so the per-slice checksum can be recorded in `MANIFEST.json`
- * without a second pass over the slice. Implementation is a one-line wrapper, but giving it a name keeps the runner's
- * hash-tracking intent obvious.
- */
-export interface StreamingHasher {
-	update(chunk: string | Uint8Array): void
-	digest(): string
-}
-
-/**
- * Default `StreamingHasher` (SHA-256, hex).
- */
-/**
- * @see {@link StreamingHasher} — this is the incremental counterpart to `sha256Hex`, not a copy of
- *   it. `@mailwoman/core/utils` exposes one-shot digests (`sha256Hex`) and whole-file digests
- *   (`sha256File`); the runner needs neither, because it hashes JSONL lines as they stream past.
- */
-export function streamingSha256(): StreamingHasher {
-	const h: Hash = createHash("sha256")
-	let finalized = false
-	let digestHex = ""
-
-	return {
-		update(chunk) {
-			if (finalized) throw new Error("streamingSha256: update() called after digest()")
-			h.update(typeof chunk === "string" ? chunk : chunk)
-		},
-		digest() {
-			if (!finalized) {
-				digestHex = h.digest("hex")
-				finalized = true
-			}
-
-			return digestHex
-		},
-	}
-}