@mailwoman/corpus 7.2.0 → 7.3.0

package/src/adapters/usgov-samhsa-treatment-locator/adapter.ts

@@ -0,0 +1,211 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `usgov-samhsa-treatment-locator`: SAMHSA Behavioral Health Treatment Services Locator CSV
+ *   consumer.
+ *
+ *   SAMHSA's Treatment Locator (`findtreatment.gov`) is the federal directory of substance-use and
+ *   mental-health treatment facilities. The published CSV carries the facility name, an optional
+ *   secondary name (typically the organizational parent), and the postal address quad split into
+ *   primary + secondary street lines. Phase 1.6 §1.2 (#22) selects this source for the same reason
+ *   it selects HRSA: facility names are hand-typed venue strings and the addresses pass through
+ *   enough human + system hands to accumulate the suite-designator + sub-tenant chaos ("Suite C,
+ *   behind main building") that pure gazetteer data does not.
+ *
+ *   SAMHSA's two-line address shape is the key adapter-specific concern. `street1` typically carries
+ *   the canonical postal address (`"123 Main St"`); `street2` carries the suite / unit / "second
+ *   floor" surface form. The adapter joins them with `", "` into a single `street` component (Phase
+ *   1 keeps `unit` as a deferred slot since the OpenCage template doesn't have a clean rendering
+ *   for it). Operators wanting a different join policy can subclass the factory.
+ *
+ *   Column names below match the canonical SAMHSA Behavioral Health Treatment Services Locator CSV
+ *   export header. Operators substituting a closely-related extract should rename columns to match;
+ *   the README has the mapping cheatsheet.
+ *
+ *   License: stamped `"Public Domain"` per the SAMHSA Open Data Foundry's federal-government
+ *   distribution terms.
+ */
+
+import { createReadStream } from "node:fs"
+
+import { parse as csvParse } from "csv-parse"
+
+import { stableSourceID } from "../../adapter.ts"
+import { lookupStateAbbreviation } from "../../codex/us-fips-state.ts"
+import { reconcileComponents } from "../../format.ts"
+import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "../../types.ts"
+
+export const USGOV_SAMHSA_ADAPTER_ID = "usgov-samhsa-treatment-locator"
+export const USGOV_SAMHSA_DEFAULT_LICENSE = "Public Domain"
+
+/**
+ * Subset of SAMHSA Treatment Locator CSV columns consulted by the adapter. Column names match the canonical SAMHSA Open
+ * Data Foundry export header. `name1` is the venue; `name2` is optional and folded into the venue when present.
+ */
+interface SamhsaSiteRow {
+	name1: string
+	name2?: string
+	street1: string
+	street2?: string
+	city: string
+	state: string
+	zip: string
+	/** Optional. Falls back to `stableSourceID` derived from components when missing. */
+	frid?: string
+}
+
+const HOUSE_NUMBER_PREFIX = /^(\d+(?:-\d+)?[A-Za-z]?)\s+(.+)$/
+
+function splitAddress(address: string): { house_number?: string; street: string } | null {
+	const trimmed = address.trim()
+
+	if (!trimmed) return null
+	const m = HOUSE_NUMBER_PREFIX.exec(trimmed)
+
+	if (m) return { house_number: m[1], street: m[2]!.trim() }
+
+	return { street: trimmed }
+}
+
+/**
+ * Join the SAMHSA two-line street: primary street + optional secondary line (suite / unit / floor / "behind main
+ * building") on `", "`. The combined value is the `street` component surface form. Phase 1 does not break this out into
+ * the `unit` component — see the file-level comment.
+ */
+function joinTwoLineStreet(street1: string, street2: string | undefined): string {
+	const s1 = street1.trim()
+	const s2 = (street2 ?? "").trim()
+
+	if (!s1 && !s2) return ""
+
+	if (!s2) return s1
+
+	if (!s1) return s2
+
+	return `${s1}, ${s2}`
+}
+
+/**
+ * Combine `name1` + optional `name2` into a single venue surface form. SAMHSA conventions:
+ *
+ * - `name1` is the program / clinic name ("Mountain Plains Counseling Services").
+ * - `name2` is the parent organization ("Catholic Charities of Wyoming"), if any.
+ *
+ * Both render together as `"<name1> - <name2>"` when both are present — geocoder users typically type either form, so
+ * the model benefits from the joined surface.
+ */
+function composeVenue(name1: string, name2: string | undefined): string {
+	const n1 = name1.trim()
+	const n2 = (name2 ?? "").trim()
+
+	if (!n1 && !n2) return ""
+
+	if (!n2) return n1
+
+	if (!n1) return n2
+
+	return `${n1} - ${n2}`
+}
+
+/** Same envelope-style format as HRSA: venue prefix, street body, city/state/zip suffix. */
+function composeRaw(
+	venue: string,
+	house: string | undefined,
+	street: string,
+	city: string,
+	state: string,
+	postcode: string
+): string {
+	const streetPart = [house, street].filter(Boolean).join(" ").trim()
+	const cityPart = [city.trim(), [state, postcode].filter(Boolean).join(" ").trim()].filter(Boolean).join(", ")
+
+	return [venue.trim(), streetPart, cityPart].filter(Boolean).join(", ")
+}
+
+export function createUsgovSamhsaTreatmentLocatorAdapter(): CorpusAdapter {
+	return {
+		id: USGOV_SAMHSA_ADAPTER_ID,
+		defaultLicense: USGOV_SAMHSA_DEFAULT_LICENSE,
+		description:
+			"SAMHSA Behavioral Health Treatment Services Locator (public-domain). Adversarial source: venue + two-line address co-occurrence, hand-entered.",
+
+		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
+			if (opts.country && opts.country !== "US") {
+				throw new Error(`usgov-samhsa adapter: only US supported, got country=${opts.country}`)
+			}
+
+			const stream = createReadStream(opts.inputPath, { encoding: "utf8" })
+			const parser = stream.pipe(
+				csvParse({
+					columns: true,
+					skip_empty_lines: true,
+					relax_quotes: true,
+					relax_column_count: true,
+				})
+			)
+
+			let emitted = 0
+
+			try {
+				for await (const record of parser as AsyncIterable<SamhsaSiteRow>) {
+					if (opts.signal?.aborted) break
+
+					if (opts.limit !== undefined && emitted >= opts.limit) break
+
+					const venue = composeVenue(record.name1 ?? "", record.name2)
+					const street = joinTwoLineStreet(record.street1 ?? "", record.street2)
+					const split = splitAddress(street)
+					const city = (record.city ?? "").trim()
+					const stateAbbr = (record.state ?? "").trim()
+					const postcode = (record.zip ?? "").trim()
+
+					if (!venue || !split || !city || !postcode) continue
+					const state = lookupStateAbbreviation(stateAbbr)
+
+					if (!state) continue
+
+					// venue first — same kryptonite-defending insertion order as HRSA.
+					const components: CanonicalRow["components"] = {
+						venue,
+						...(split.house_number ? { house_number: split.house_number } : {}),
+						street: split.street,
+						locality: city,
+						region: state.abbreviation,
+						postcode,
+					}
+
+					const raw = composeRaw(venue, split.house_number, split.street, city, state.abbreviation, postcode)
+
+					if (!raw) continue
+
+					const aligned = reconcileComponents(components, raw)
+
+					if (Object.keys(aligned).length === 0) continue
+
+					const frID = (record.frid ?? "").trim()
+					const sourceID = frID
+						? `${USGOV_SAMHSA_ADAPTER_ID}-${frID}`
+						: stableSourceID(USGOV_SAMHSA_ADAPTER_ID, aligned)
+
+					yield {
+						raw,
+						components: aligned,
+						country: "US",
+						locale: "en-US",
+						source: USGOV_SAMHSA_ADAPTER_ID,
+						source_id: sourceID,
+						corpus_version: "",
+						license: USGOV_SAMHSA_DEFAULT_LICENSE,
+					}
+					emitted++
+				}
+			} finally {
+				stream.destroy()
+			}
+		},
+	}
+}
+
+export const usgovSamhsaTreatmentLocatorAdapter = createUsgovSamhsaTreatmentLocatorAdapter()

package/src/adapters/wof-admin-jp/adapter.ts

@@ -0,0 +1,176 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `wof-admin-jp`: Japanese admin-hierarchy adapter.
+ *
+ *   PROTOTYPE — not yet wired into the Stage 3 training corpus. Demonstrates the JP address shape and
+ *   synthesizes BIO-labeled training rows from the global WOF SQLite.
+ *
+ *   JP addresses differ from US/EU in three ways:
+ *
+ *   1. **Reversed ordering** — region → county → locality → block → house_number "東京都世田谷区南町1-2-3" not
+ *        "1-2-3 Minamicho, Setagaya, Tokyo"
+ *   2. **No street names** — most JP addresses use a block/sub-block grid system. The "neighbourhood"
+ *        placetype (丁目) is the closest analog to a street but is actually a grid cell.
+ *   3. **Postcode-first convention** — addresses are often prefixed with `〒NNN-NNNN`.
+ *
+ *   Schema mapping to ComponentTags (subset of Stage 3 + JP-specific Phase 6 tags):
+ *
+ *   | JP concept | WOF placetype | ComponentTag (Phase 6) |
+ *   |-----------------|--------------------|-----------------------| | 都道府県 (prefecture) | region |
+ *   region (or prefecture) | | 市区町村 (city/ward) | county/locality | locality (or municipality) | |
+ *   丁目 (chome) | neighbourhood | block (Phase 6 tag) | | 番地 (banchi) | (synth) | sub_block | | 号
+ *   (gō) | (synth) | house_number | | 〒 (postcode prefix) | — | postcode |
+ *
+ *   This adapter currently emits only the admin chain (region → locality → block). House numbers and
+ *   sub-blocks require a different data source (JP postcode database or real-world address dumps
+ *   from MLIT/JapanPost).
+ */
+
+import { DatabaseSync } from "node:sqlite"
+
+import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "../../types.ts"
+
+export const WOF_ADMIN_JP_ADAPTER_ID = "wof-admin-jp"
+
+interface PlaceRow {
+	id: number
+	name: string
+	placetype: string
+	parent_id: number
+	country: string
+}
+
+interface NameRow {
+	id: number
+	name: string
+	language: string
+}
+
+/** Walk parent chain up to 6 levels. */
+function chainOf(db: DatabaseSync, startID: number, _jpnNames: Map<number, string>): PlaceRow[] {
+	const stmt = db.prepare(`SELECT id, name, placetype, parent_id, country FROM spr WHERE id = ?`)
+	const out: PlaceRow[] = []
+	let id = startID
+
+	for (let i = 0; i < 6 && id > 0; i++) {
+		const row = stmt.get(id) as PlaceRow | undefined
+
+		if (!row) break
+		out.push(row)
+		id = row.parent_id
+	}
+
+	return out
+}
+
+/** Pick the best display name for a place: prefer Japanese variant, fall back to English. */
+function pickName(row: PlaceRow, jpnNames: Map<number, string>): string {
+	return jpnNames.get(row.id) ?? row.name
+}
+
+/**
+ * Synthesize a JP address from a hierarchy chain.
+ *
+ * Format: `〒<postcode>? <region><locality><neighbourhood>?`
+ *
+ * No house numbers yet — needs MLIT data.
+ */
+export function synthesizeJpAddress(
+	chain: PlaceRow[],
+	jpnNames: Map<number, string>
+): {
+	raw: string
+	components: CanonicalRow["components"]
+} | null {
+	const region = chain.find((r) => r.placetype === "region")
+	const locality = chain.find((r) => r.placetype === "locality" || r.placetype === "county")
+
+	if (!region || !locality) return null
+
+	const neighbourhood = chain.find((r) => r.placetype === "neighbourhood")
+
+	const regionName = pickName(region, jpnNames)
+	const localityName = pickName(locality, jpnNames)
+	const neighbourhoodName = neighbourhood ? pickName(neighbourhood, jpnNames) : null
+
+	const components: CanonicalRow["components"] = {
+		region: regionName,
+		locality: localityName,
+		country: "JP",
+	}
+
+	if (neighbourhoodName) {
+		components.dependent_locality = neighbourhoodName
+	}
+
+	const raw = [regionName, localityName, neighbourhoodName].filter(Boolean).join("")
+
+	return { raw, components }
+}
+
+/**
+ * Build the JP adapter. Reads from the unified global WOF SQLite, walks admin chains starting from neighbourhoods, and
+ * yields canonical rows.
+ */
+export function createWOFAdminJpAdapter(): CorpusAdapter {
+	return {
+		id: WOF_ADMIN_JP_ADAPTER_ID,
+		defaultLicense: "CC-BY-4.0",
+		description: "Japanese admin hierarchy from WOF (synthesized addresses without house numbers).",
+
+		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
+			if (opts.country && opts.country !== "JP") {
+				throw new Error(`wof-admin-jp adapter: only JP supported, got country=${opts.country}`)
+			}
+
+			const db = new DatabaseSync(opts.inputPath, { readOnly: true })
+
+			try {
+				const jpnNamesStmt = db.prepare(`SELECT id, name FROM names WHERE language = 'jpn'`)
+				const jpnNames = new Map<number, string>()
+
+				for (const row of jpnNamesStmt.all() as { id: number; name: string }[]) {
+					if (!jpnNames.has(row.id)) {
+						jpnNames.set(row.id, row.name)
+					}
+				}
+
+				const seeds = db.prepare(`SELECT id FROM spr WHERE country='JP' AND placetype='neighbourhood'`).all() as {
+					id: number
+				}[]
+
+				let emitted = 0
+
+				for (const seed of seeds) {
+					if (opts.signal?.aborted) break
+
+					if (opts.limit !== undefined && emitted >= opts.limit) break
+
+					const chain = chainOf(db, seed.id, jpnNames)
+					const synth = synthesizeJpAddress(chain, jpnNames)
+
+					if (!synth) continue
+
+					yield {
+						raw: synth.raw,
+						components: synth.components,
+						country: "JP",
+						locale: "ja-JP",
+						source: WOF_ADMIN_JP_ADAPTER_ID,
+						source_id: `${WOF_ADMIN_JP_ADAPTER_ID}-${seed.id}`,
+						corpus_version: "",
+						license: "CC-BY-4.0",
+					}
+					emitted++
+				}
+			} finally {
+				db.close()
+			}
+		},
+	}
+}
+
+export const wofAdminJpAdapter = createWOFAdminJpAdapter()

package/src/adapters/wof-admin-json/adapter.ts

@@ -0,0 +1,280 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `wof-admin`: Who's On First admin GeoJSON-bundle adapter.
+ *
+ *   **Phase 1.5.1 pivot.** The original Phase 1.5 SQLite adapter (formerly at
+ *   `packages/corpus/src/adapters/wof-admin/`, removed in this same change) was replaced by this
+ *   one because the SQLite distribution path was unworkable for the real corpus build:
+ *
+ *   1. `dist.whosonfirst.org/sqlite/` is dead (NXDOMAIN); the Geocode-Earth mirror is the only one.
+ *   2. The Geocode-Earth-hosted postalcode DB tags every row `mz:is_current = -1` ("unknown but treated
+ *        as active"); the SQLite adapter's `is_current = 1` predicate emitted zero rows.
+ *   3. The `names` table in the SQLite distribution is empty — localized `name:*` variants live in a
+ *        separate distribution. The St. Petersburg / Mt. Vernon / Ft. Lauderdale alternation cases
+ *        (the original Phase 1.5.1 motivator) cannot be solved on the SQLite path even with a
+ *        patched `is_current` predicate.
+ *
+ *   Input: a directory containing one or more cloned `whosonfirst-data-admin-<cc>` GitHub repos. Each
+ *   repo has `data/XXX/YYY/ZZZ/<wof-id>.geojson` files; `**\/*.geojson` walks the tree recursively.
+ *   Alternate-geometry siblings (`-alt-*`) are skipped — they're separate exports of the same
+ *   record, not new records.
+ *
+ *   Per record, the adapter emits one row per `(name-variant, hierarchy-variant)` pair:
+ *
+ *   - **Name variants**: the canonical `wof:name` (slot key `default`) plus every `name:*` localized
+ *       variant present on the feature (`name:eng_x_preferred`, `name:eng_x_colloquial`,
+ *       `name:rus_x_preferred`, ...). This is the Phase 1.5.1 fix for the St. Petersburg case:
+ *       `"Saint Petersburg"` (canonical) and `"St. Petersburg"` (eng_x_colloquial) both become
+ *       training rows for the same WOF id.
+ *   - **Hierarchy variants** (unchanged from the SQLite adapter): locality → 3 variants, region → 2,
+ *       country → 1, county → 1.
+ *
+ *   `source_id` is `wof-admin-<wof_id>-<name-slot>-<hierarchy-variant>`. The previous SQLite adapter
+ *   used `wof-admin-<wof_id>-<hierarchy-variant>` (no name slot); the new format adds a name-slot
+ *   segment so the colloquial / preferred / per-locale variants survive dedup independently.
+ *
+ *   License: CC0. The adapter stamps every row with `CC0-1.0`.
+ */
+
+import type { WhosOnFirstPlacetype } from "@mailwoman/core/resources/whosonfirst"
+import type { ComponentTag } from "@mailwoman/core/types"
+
+import { formatAddress, reconcileComponents } from "../../format.ts"
+import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "../../types.ts"
+import { buildAncestryIndex, normalizeNameKey, walkFeatures, type WOFRecord } from "../../wof-json.ts"
+
+/**
+ * Display name for the country, keyed by ISO 3166-1 alpha-2.
+ *
+ * Must be the **OpenCage-canonical** surface form: the `address-formatter` library expands some country names en route
+ * to its output (e.g. `"United States"` → `"United States of America"`). If `components.country` and the formatted
+ * `raw` disagree, alignment will fail downstream. Keying off the canonical form keeps the two in lockstep.
+ *
+ * Phase 1 US + FR only; extend as new locales come online. Missing countries fall back to the country row's `wof:name`,
+ * accepting the alignment risk for non-canonicalized names.
+ */
+const COUNTRY_DISPLAY_NAME: Record<string, string> = {
+	US: "United States of America",
+	FR: "France",
+}
+
+/** BCP-47 locale defaulting for the corpus row's `locale` field. Defaulted by country. */
+const LOCALE_BY_COUNTRY: Record<string, string> = {
+	US: "en-US",
+	FR: "fr-FR",
+}
+
+/** Map a WOF placetype to a Mailwoman `ComponentTag`, or `undefined` to skip. */
+function placetypeToTag(placetype: WhosOnFirstPlacetype | string): ComponentTag | undefined {
+	switch (placetype) {
+		case "country":
+		case "nation":
+			return "country"
+		case "macroregion":
+		case "region":
+			return "region"
+		case "macrocounty":
+		case "county":
+		case "localadmin":
+			return "subregion"
+		case "locality":
+			return "locality"
+		case "borough":
+		case "macrohood":
+		case "neighbourhood":
+		case "microhood":
+			return "dependent_locality"
+		default:
+			return undefined
+	}
+}
+
+interface VariantSpec {
+	/** Hierarchy-variant id appended to `source_id`. */
+	suffix: string
+
+	/** Component tag → display string the adapter will hand to the runner. */
+	components: Partial<Record<ComponentTag, string>>
+}
+
+/**
+ * Compute the hierarchy variants for a record given its ancestry chain and the chosen `selfName`.
+ *
+ * `selfName` is the surface form to use for the record's own component (locality / region / country / subregion).
+ * Callers pass the canonical `wof:name` for the `"default"` slot and a `name:*` localized value for variant slots;
+ * ancestor names always come from the ancestor's canonical `wof:name`.
+ *
+ * Country variants substitute `COUNTRY_DISPLAY_NAME` for the default slot so the OpenCage template produces the
+ * canonicalized form (`"United States of America"`), matching the legacy SQLite adapter's behavior.
+ */
+export function variantsFor(row: WOFRecord, ancestry: WOFRecord[], selfName: string): VariantSpec[] {
+	const selfTag = placetypeToTag(row.placetype)
+
+	if (!selfTag) return []
+
+	const region = ancestry.find((a) => placetypeToTag(a.placetype) === "region")
+	const country = ancestry.find((a) => placetypeToTag(a.placetype) === "country")
+	const countryDisplay = COUNTRY_DISPLAY_NAME[row.country] ?? country?.name ?? row.country
+
+	const variants: VariantSpec[] = []
+
+	switch (selfTag) {
+		case "locality":
+		case "dependent_locality": {
+			variants.push({ suffix: "self", components: { [selfTag]: selfName } })
+
+			if (region) {
+				variants.push({
+					suffix: "with-region",
+					components: { [selfTag]: selfName, region: region.name },
+				})
+			}
+
+			if (region && country) {
+				variants.push({
+					suffix: "with-region-country",
+					components: { [selfTag]: selfName, region: region.name, country: countryDisplay },
+				})
+			} else if (!region && country) {
+				variants.push({
+					suffix: "with-country",
+					components: { [selfTag]: selfName, country: countryDisplay },
+				})
+			}
+
+			return variants
+		}
+
+		case "region": {
+			variants.push({ suffix: "self", components: { region: selfName } })
+
+			if (country) {
+				variants.push({
+					suffix: "with-country",
+					components: { region: selfName, country: countryDisplay },
+				})
+			}
+
+			return variants
+		}
+
+		case "country": {
+			variants.push({ suffix: "self", components: { country: selfName } })
+
+			return variants
+		}
+
+		case "subregion": {
+			variants.push({ suffix: "self", components: { subregion: selfName } })
+
+			return variants
+		}
+
+		default:
+			return []
+	}
+}
+
+/**
+ * Build the per-record name-slot list. The canonical `"default"` slot uses the OpenCage-canonical country form when the
+ * record is itself a country (matches SQLite-adapter behavior); every other placetype's default slot uses `wof:name`
+ * verbatim.
+ *
+ * Subsequent slots come from `name:*` variants, deduplicated against the default name so we don't emit a redundant
+ * `"default"`-equivalent row under a localized key.
+ */
+export function nameSlotsFor(rec: WOFRecord): Array<{ key: string; value: string }> {
+	const selfTag = placetypeToTag(rec.placetype)
+	const canonicalSelfName = selfTag === "country" ? (COUNTRY_DISPLAY_NAME[rec.country] ?? rec.name) : rec.name
+
+	const seen = new Set<string>([canonicalSelfName])
+	const slots: Array<{ key: string; value: string }> = [{ key: "default", value: canonicalSelfName }]
+
+	for (const [rawKey, value] of rec.nameVariants) {
+		if (seen.has(value)) continue
+		seen.add(value)
+		slots.push({ key: normalizeNameKey(rawKey), value })
+	}
+
+	return slots
+}
+
+export const WOF_ADMIN_ADAPTER_ID = "wof-admin"
+
+/**
+ * Construct the wof-admin JSON-bundle adapter. The adapter is stateless across runs; calling this twice with the same
+ * input directory produces byte-identical `canonical.jsonl` (records are emitted in sorted `wof:id` order to be
+ * insensitive to filesystem walk ordering).
+ */
+export function createWOFAdminAdapter(): CorpusAdapter {
+	return {
+		id: WOF_ADMIN_ADAPTER_ID,
+		defaultLicense: "CC0-1.0",
+		description:
+			"Who's On First admin GeoJSON bundles (countries, regions, counties, localities) — multi-name variants per record.",
+
+		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
+			// Pass 1: scan every GeoJSON file once, build the in-memory record index.
+			// We keep only records whose placetype maps to a ComponentTag — irrelevant placetypes
+			// (campus, county-region hybrids on which Mailwoman has no opinion) are dropped here so
+			// they don't inflate the ancestry index. Country-filtered runs prune to the matching
+			// country code too; the ancestors of a same-country record live in the same admin repo.
+			const byID = new Map<number, WOFRecord>()
+
+			for await (const rec of walkFeatures(opts.inputPath, { signal: opts.signal })) {
+				if (opts.signal?.aborted) return
+
+				if (opts.country && rec.country !== opts.country) continue
+
+				if (!placetypeToTag(rec.placetype)) continue
+				byID.set(rec.id, rec)
+			}
+
+			const ancestry = buildAncestryIndex(byID)
+
+			// Pass 2: emit rows in sorted-id order for deterministic JSONL.
+			const ids = [...byID.keys()].sort((a, b) => a - b)
+			let emitted = 0
+
+			for (const id of ids) {
+				if (opts.signal?.aborted) return
+				const rec = byID.get(id)!
+				const chain = ancestry.get(id) ?? []
+				const slots = nameSlotsFor(rec)
+
+				for (const slot of slots) {
+					const variants = variantsFor(rec, chain, slot.value)
+
+					for (const variant of variants) {
+						if (opts.limit !== undefined && emitted >= opts.limit) return
+
+						const raw = formatAddress(variant.components, rec.country, { separator: ", " })
+
+						if (!raw) continue
+						const aligned = reconcileComponents(variant.components, raw)
+
+						if (Object.keys(aligned).length === 0) continue
+
+						yield {
+							raw,
+							components: aligned,
+							country: rec.country,
+							locale: LOCALE_BY_COUNTRY[rec.country],
+							source: WOF_ADMIN_ADAPTER_ID,
+							source_id: `${WOF_ADMIN_ADAPTER_ID}-${rec.id}-${slot.key}-${variant.suffix}`,
+							corpus_version: "",
+							license: "CC0-1.0",
+						}
+						emitted++
+					}
+				}
+			}
+		},
+	}
+}
+
+/** Single shared instance, suitable for `defaultAdapterRegistry`. */
+export const wofAdminAdapter = createWOFAdminAdapter()