@mailwoman/corpus 9.1.0 → 9.2.0

package/src/adapters/synth-po-box/adapter.ts

@@ -22,16 +22,17 @@
 
 import { tryParsingJSON } from "@mailwoman/core/objects"
 import { makeLcg } from "@mailwoman/core/utils"
-import { stableSourceID } from "@mailwoman/corpus/adapters/utils"
+import { TextSpliterator } from "spliterator"
+
+import { stableSourceID } from "#adapters/utils"
 import {
 	countryToLocale,
 	REGION_OPTIONAL_LOCALES,
 	synthesizeMilitaryPoBoxRow,
 	synthesizePoBoxRow,
 	type PoBoxBaseTuple,
-} from "@mailwoman/corpus/synthesizers/po-box"
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "@mailwoman/corpus/types"
-import { TextSpliterator } from "spliterator"
+} 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

package/src/adapters/tiger/adapter.ts

@@ -36,10 +36,11 @@
 
 import { DatabaseSync } from "node:sqlite"
 
-import { lookupFipsState } from "@mailwoman/corpus/codex/us-fips-state"
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "@mailwoman/corpus/types"
 import { formatAddress, reconcileComponents } from "@mailwoman/formatter"
 
+import { lookupFipsState } from "#codex/us-fips-state"
+import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "#types"
+
 import { decomposeStreet } from "./street-decompose.ts"
 
 /**

package/src/adapters/usgov-hrsa-fqhc/adapter.ts

@@ -29,12 +29,14 @@
  *   terms.
  */
 
-import { splitStreetLine, stableSourceID } from "@mailwoman/corpus/adapters/utils"
-import { lookupStateAbbreviation } from "@mailwoman/corpus/codex/us-fips-state"
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "@mailwoman/corpus/types"
+import { isPresent } from "@mailwoman/core/objects"
 import { reconcileComponents } from "@mailwoman/formatter"
 import { CSVSpliterator } from "spliterator"
 
+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.
@@ -89,10 +91,10 @@ function composeRaw(
 	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(", ")
+	const streetPart = [house, street].filter(isPresent).join(" ").trim()
+	const cityPart = [city.trim(), [state, postcode].filter(isPresent).join(" ").trim()].filter(isPresent).join(", ")
 
-	return [venue.trim(), streetPart, cityPart].filter(Boolean).join(", ")
+	return [venue.trim(), streetPart, cityPart].filter(isPresent).join(", ")
 }
 
 export function createUsgovHrsaFqhcAdapter(): CorpusAdapter {

package/src/adapters/usgov-imls-pls/adapter.ts

@@ -18,12 +18,14 @@
  *   License: stamped `"Public Domain"` per IMLS federal government distribution terms.
  */
 
-import { splitStreetLine, stableSourceID } from "@mailwoman/corpus/adapters/utils"
-import { lookupStateAbbreviation } from "@mailwoman/corpus/codex/us-fips-state"
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "@mailwoman/corpus/types"
+import { isPresent } from "@mailwoman/core/objects"
 import { reconcileComponents } from "@mailwoman/formatter"
 import { CSVSpliterator } from "spliterator"
 
+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.
@@ -74,7 +76,6 @@ export function createUsgovImlsPlsAdapter(): CorpusAdapter {
 				const city = (record.CITY ?? "").trim()
 				const zip = (record.ZIP ?? "").trim()
 				const stateAbbr = (record.STABR ?? "").trim()
-				const county = (record.CNTY ?? "").trim()
 
 				if (!libName || !city || !zip) continue
 
@@ -99,10 +100,14 @@ export function createUsgovImlsPlsAdapter(): CorpusAdapter {
 					// a postal-surface component here.
 				}
 
-				const streetPart = [split.house_number, split.street].filter(Boolean).join(" ").trim()
+				const streetPart = [split.house_number, split.street].filter(isPresent).join(" ").trim()
 
-				const raw = [libName, streetPart, [city, [stateAbbr, zip].filter(Boolean).join(" ")].filter(Boolean).join(", ")]
-					.filter(Boolean)
+				const raw = [
+					libName,
+					streetPart,
+					[city, [stateAbbr, zip].filter(isPresent).join(" ")].filter(isPresent).join(", "),
+				]
+					.filter(isPresent)
 					.join(", ")
 
 				const aligned = reconcileComponents(components, raw)

package/src/adapters/usgov-irs-bmf/adapter.ts

@@ -19,11 +19,13 @@
  *   federal).
  */
 
-import { splitStreetLine, stableSourceID } from "@mailwoman/corpus/adapters/utils"
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "@mailwoman/corpus/types"
+import { isPresent } from "@mailwoman/core/objects"
 import { reconcileComponents } from "@mailwoman/formatter"
 import { CSVSpliterator } from "spliterator"
 
+import { splitStreetLine, 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.
@@ -71,9 +73,9 @@ function composeRaw(
 	state: string,
 	postcode: string
 ): string {
-	const cityPart = [city.trim(), [state, postcode].filter(Boolean).join(" ").trim()].filter(Boolean).join(", ")
+	const cityPart = [city.trim(), [state, postcode].filter(isPresent).join(" ").trim()].filter(isPresent).join(", ")
 
-	return [venue, streetPart, cityPart].filter(Boolean).join(", ")
+	return [venue, streetPart, cityPart].filter(isPresent).join(", ")
 }
 
 export function createUsgovIrsBmfAdapter(): CorpusAdapter {
@@ -116,7 +118,7 @@ export function createUsgovIrsBmfAdapter(): CorpusAdapter {
 				if (!split) continue
 
 				const streetPart =
-					"po_box" in split ? split.po_box : [split.house_number, split.street].filter(Boolean).join(" ")
+					"po_box" in split ? split.po_box : [split.house_number, split.street].filter(isPresent).join(" ")
 
 				const components: CanonicalRow["components"] = {
 					...(venue ? { venue } : {}),

package/src/adapters/usgov-nad/adapter.ts

@@ -33,11 +33,12 @@
 import { readdir } from "node:fs/promises"
 import { join } from "node:path"
 
-import { tryParsingJSON } from "@mailwoman/core/objects"
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "@mailwoman/corpus/types"
+import { isPresent, tryParsingJSON } from "@mailwoman/core/objects"
 import { reconcileComponents } from "@mailwoman/formatter"
 import { TextSpliterator } from "spliterator"
 
+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.
@@ -175,7 +176,7 @@ function composeHouseNumber(r: NADRecord): string | undefined {
 	const pre = (r.AddNum_Pre ?? "").toString().trim()
 	const suf = (r.AddNum_Suf ?? "").toString().trim()
 
-	return [pre, num, suf].filter(Boolean).join(" ").trim() || undefined
+	return [pre, num, suf].filter(isPresent).join(" ").trim() || undefined
 }
 
 interface DecomposedNADStreet {
@@ -194,9 +195,9 @@ function decomposeNADStreet(r: NADRecord): DecomposedNADStreet | undefined {
 		const preSep = (r.St_PreSep ?? "").toString().trim()
 		const posTyp = (r.St_PosTyp ?? "").toString().trim()
 		const posDir = (r.St_PosDir ?? "").toString().trim()
-		const prefix = [preDir, preTyp, preSep].filter(Boolean).join(" ") || undefined
-		const suffix = [posTyp, posDir].filter(Boolean).join(" ") || undefined
-		const full = [prefix, name, suffix].filter(Boolean).join(" ")
+		const prefix = [preDir, preTyp, preSep].filter(isPresent).join(" ") || undefined
+		const suffix = [posTyp, posDir].filter(isPresent).join(" ") || undefined
+		const full = [prefix, name, suffix].filter(isPresent).join(" ")
 
 		return { prefix, street: name, suffix, full }
 	}
@@ -230,10 +231,10 @@ function composeRaw(parts: {
 	region: string
 	postcode: string
 }): string {
-	const streetLine = [parts.houseNumber, parts.street, parts.unit].filter(Boolean).join(" ").trim()
+	const streetLine = [parts.houseNumber, parts.street, parts.unit].filter(isPresent).join(" ").trim()
 	const tail = `${parts.locality}, ${parts.region} ${parts.postcode}`
 
-	return [parts.venue, streetLine || undefined, tail].filter(Boolean).join(", ")
+	return [parts.venue, streetLine || undefined, tail].filter(isPresent).join(", ")
 }
 
 export function createUsgovNADAdapter(): CorpusAdapter {

package/src/adapters/usgov-nppes/adapter.ts

@@ -21,12 +21,14 @@
  *   License: stamped `"Public Domain"` per CMS's federal government distribution terms.
  */
 
-import { splitStreetLine, stableSourceID } from "@mailwoman/corpus/adapters/utils"
-import { lookupStateAbbreviation } from "@mailwoman/corpus/codex/us-fips-state"
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "@mailwoman/corpus/types"
+import { isPresent } from "@mailwoman/core/objects"
 import { reconcileComponents } from "@mailwoman/formatter"
 import { CSVSpliterator } from "spliterator"
 
+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.
@@ -48,7 +50,7 @@ interface NPPESRow {
 	"Provider Second Line Business Practice Location Address": string
 	"Provider Business Practice Location Address City Name": string
 	"Provider Business Practice Location Address State Name": string
-	"Provider Business Practice Location Address Postal Code": string
+	"Provider Business Practice Location Address Postcode": string
 }
 
 function composeRaw(
@@ -59,10 +61,11 @@ function composeRaw(
 	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(", ")
+	const streetPart = [house, street].filter(isPresent).join(" ").trim()
+
+	const cityPart = [city.trim(), [state, postcode].filter(isPresent).join(" ").trim()].filter(isPresent).join(", ")
 
-	return [venue, streetPart, cityPart].filter(Boolean).join(", ")
+	return [venue, streetPart, cityPart].filter(isPresent).join(", ")
 }
 
 export function createUsgovNPPESAdapter(): CorpusAdapter {
@@ -91,7 +94,6 @@ export function createUsgovNPPESAdapter(): CorpusAdapter {
 				if (opts.limit !== undefined && emitted >= opts.limit) break
 
 				const npi = (record.NPI ?? "").trim()
-				const entityType = (record["Entity Type Code"] ?? "").trim()
 				const orgName = (record["Provider Organization Name (Legal Business Name)"] ?? "").trim()
 				const lastName = (record["Provider Last Name (Legal Name)"] ?? "").trim()
 				const firstName = (record["Provider First Name"] ?? "").trim()
@@ -100,7 +102,7 @@ export function createUsgovNPPESAdapter(): CorpusAdapter {
 				const address2 = (record["Provider Second Line Business Practice Location Address"] ?? "").trim()
 				const city = (record["Provider Business Practice Location Address City Name"] ?? "").trim()
 				const stateRaw = (record["Provider Business Practice Location Address State Name"] ?? "").trim()
-				const postcode = (record["Provider Business Practice Location Address Postal Code"] ?? "").trim()
+				const postcode = (record["Provider Business Practice Location Address Postcode"] ?? "").trim()
 
 				if (!city || !postcode) continue
 
@@ -108,12 +110,12 @@ export function createUsgovNPPESAdapter(): CorpusAdapter {
 
 				if (!state) continue
 
-				const fullStreet = [address1, address2].filter(Boolean).join(" ")
+				const fullStreet = [address1, address2].filter(isPresent).join(" ")
 				const split = splitStreetLine(fullStreet)
 
 				if (!split) continue
 
-				const venue = orgName || [firstName, lastName].filter(Boolean).join(" ") || undefined
+				const venue = orgName || [firstName, lastName].filter(isPresent).join(" ") || undefined
 
 				const components: CanonicalRow["components"] = {
 					...(venue ? { venue } : {}),

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

@@ -28,12 +28,14 @@
  *   distribution terms.
  */
 
-import { splitStreetLine, stableSourceID } from "@mailwoman/corpus/adapters/utils"
-import { lookupStateAbbreviation } from "@mailwoman/corpus/codex/us-fips-state"
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "@mailwoman/corpus/types"
+import { isPresent } from "@mailwoman/core/objects"
 import { reconcileComponents } from "@mailwoman/formatter"
 import { CSVSpliterator } from "spliterator"
 
+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.
@@ -114,10 +116,10 @@ function composeRaw(
 	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(", ")
+	const streetPart = [house, street].filter(isPresent).join(" ").trim()
+	const cityPart = [city.trim(), [state, postcode].filter(isPresent).join(" ").trim()].filter(isPresent).join(", ")
 
-	return [venue.trim(), streetPart, cityPart].filter(Boolean).join(", ")
+	return [venue.trim(), streetPart, cityPart].filter(isPresent).join(", ")
 }
 
 export function createUsgovSamhsaTreatmentLocatorAdapter(): CorpusAdapter {

package/src/adapters/utils/index.ts

@@ -26,7 +26,8 @@ import { createHash, type Hash } from "node:crypto"
 
 import type { ComponentTag } from "@mailwoman/core/types"
 import { sha256Hex } from "@mailwoman/core/utils"
-import type { CanonicalRow, CorpusAdapter } from "@mailwoman/corpus/types"
+
+import type { CanonicalRow, CorpusAdapter } from "#types"
 
 /**
  * Lookup table for corpus adapters.
@@ -103,8 +104,20 @@ export const defaultAdapterRegistry = new InMemoryAdapterRegistry()
  * length.
  */
 export function stableSourceID(adapterID: string, components: Partial<Record<ComponentTag, string>>): string {
-	const sortedKeys = Object.keys(components).toSorted() as ComponentTag[]
-	const payload = sortedKeys.map((k) => `${k}=${components[k] ?? ""}`).join("\u001F")
+	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 shard changes.
 	const digest = sha256Hex(`${adapterID}\u001E${payload}`)

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

@@ -31,7 +31,10 @@
 
 import { DatabaseSync } from "node:sqlite"
 
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "@mailwoman/corpus/types"
+import { isPresent } from "@mailwoman/core/objects"
+import { allRows, getRow } from "@mailwoman/core/utils"
+
+import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "#types"
 
 /**
  * Ancestry hops walked upward from a WOF record before giving up — deeper than any real JP admin chain.
@@ -52,12 +55,6 @@ interface PlaceRow {
 	country: string
 }
 
-interface NameRow {
-	id: number
-	name: string
-	language: string
-}
-
 /**
  * Walk parent chain up to 6 levels, over a place table already resident in memory.
  *
@@ -125,7 +122,7 @@ export function synthesizeJpAddress(
 		components.dependent_locality = neighbourhoodName
 	}
 
-	const raw = [regionName, localityName, neighbourhoodName].filter(Boolean).join("")
+	const raw = [regionName, localityName, neighbourhoodName].filter(isPresent).join("")
 
 	return { raw, components }
 }
@@ -161,16 +158,16 @@ export function createWOFAdminJpAdapter(): CorpusAdapter {
 				// seed; there are tens of thousands of neighbourhood seeds.
 				const byID = new Map<number, PlaceRow>()
 
-				for (const row of db
-					.prepare(`SELECT id, name, placetype, parent_id, country FROM spr WHERE country='JP'`)
-					.all() as unknown as PlaceRow[]) {
+				for (const row of allRows<PlaceRow>(
+					db.prepare(`SELECT id, name, placetype, parent_id, country FROM spr WHERE country='JP'`)
+				)) {
 					byID.set(row.id, row)
 				}
 
 				const outsideStmt = db.prepare(`SELECT id, name, placetype, parent_id, country FROM spr WHERE id = ?`)
 
 				const resolveOutside = (id: number): PlaceRow | undefined => {
-					const row = outsideStmt.get(id) as unknown as PlaceRow | undefined
+					const row = getRow<PlaceRow>(outsideStmt, id)
 
 					if (row) {
 						byID.set(id, row)

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

@@ -41,9 +41,11 @@
 
 import type { WhosOnFirstPlacetype } from "@mailwoman/core/resources/whosonfirst"
 import type { ComponentTag } from "@mailwoman/core/types"
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "@mailwoman/corpus/types"
-import { buildAncestryIndex, normalizeNameKey, walkFeatures, type WOFRecord } from "@mailwoman/corpus/utils"
-import { formatAddress, reconcileComponents } from "@mailwoman/formatter"
+
+import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "#types"
+import { buildAncestryIndex, normalizeNameKey, walkFeatures, type WOFRecord } from "#utils"
+
+import { emitWOFJSONRows, type WOFVariantSpec } from "../wof-json-rows.ts"
 
 /**
  * Display name for the country, keyed by ISO 3166-1 alpha-2.
@@ -95,18 +97,6 @@ function placetypeToTag(placetype: WhosOnFirstPlacetype | string): ComponentTag
 	}
 }
 
-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`.
  *
@@ -117,7 +107,7 @@ interface VariantSpec {
  * 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[] {
+export function variantsFor(row: WOFRecord, ancestry: WOFRecord[], selfName: string): WOFVariantSpec[] {
 	const selfTag = placetypeToTag(row.placetype)
 
 	if (!selfTag) return []
@@ -126,7 +116,7 @@ export function variantsFor(row: WOFRecord, ancestry: WOFRecord[], selfName: str
 	const country = ancestry.find((a) => placetypeToTag(a.placetype) === "country")
 	const countryDisplay = COUNTRY_DISPLAY_NAME[row.country] ?? country?.name ?? row.country
 
-	const variants: VariantSpec[] = []
+	const variants: WOFVariantSpec[] = []
 
 	switch (selfTag) {
 		case "locality":
@@ -247,43 +237,15 @@ export function createWOFAdminAdapter(): CorpusAdapter {
 			const ancestry = buildAncestryIndex(byID)
 
 			// Pass 2: emit rows in sorted-id order for deterministic JSONL.
-			const ids = [...byID.keys()].toSorted((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) 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++
-					}
-				}
-			}
+			yield* emitWOFJSONRows({
+				records: byID,
+				ancestry,
+				adapterOptions: opts,
+				adapterID: WOF_ADMIN_ADAPTER_ID,
+				localeByCountry: LOCALE_BY_COUNTRY,
+				nameSlotsFor,
+				variantsFor,
+			})
 		},
 	}
 }

package/src/adapters/wof-json-rows.ts

@@ -0,0 +1,79 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Deterministic canonical-row emission shared by WOF GeoJSON adapters.
+ */
+
+import type { ComponentTag } from "@mailwoman/core/types"
+import { formatAddress, reconcileComponents } from "@mailwoman/formatter"
+
+import type { AdapterOptions, CanonicalRow } from "#types"
+import type { WOFRecord } from "#utils"
+
+export interface WOFVariantSpec {
+	suffix: string
+	components: Partial<Record<ComponentTag, string>>
+}
+
+interface EmitWOFJSONRowsOptions {
+	records: ReadonlyMap<number, WOFRecord>
+	ancestry: ReadonlyMap<number, WOFRecord[]>
+	adapterOptions: AdapterOptions
+	adapterID: string
+	localeByCountry: Readonly<Record<string, string>>
+	shouldEmit?: (record: WOFRecord) => boolean
+	nameSlotsFor: (record: WOFRecord) => Array<{ key: string; value: string }>
+	variantsFor: (record: WOFRecord, ancestry: WOFRecord[], selfName: string) => WOFVariantSpec[]
+}
+
+/**
+ * Emit aligned rows in WOF-id order, enforcing the adapter limit across all name and hierarchy variants.
+ */
+export function* emitWOFJSONRows(options: EmitWOFJSONRowsOptions): Generator<CanonicalRow> {
+	const {
+		records,
+		ancestry,
+		adapterOptions,
+		adapterID,
+		localeByCountry,
+		shouldEmit = () => true,
+		nameSlotsFor,
+		variantsFor,
+	} = options
+
+	let emitted = 0
+
+	for (const id of [...records.keys()].toSorted((a, b) => a - b)) {
+		if (adapterOptions.signal?.aborted) return
+		const record = records.get(id)!
+
+		if (!shouldEmit(record)) continue
+
+		for (const slot of nameSlotsFor(record)) {
+			for (const variant of variantsFor(record, ancestry.get(id) ?? [], slot.value)) {
+				if (adapterOptions.limit !== undefined && emitted >= adapterOptions.limit) return
+
+				const raw = formatAddress(variant.components, record.country, { separator: ", " })
+
+				if (!raw) continue
+				const components = reconcileComponents(variant.components, raw)
+
+				if (!Object.keys(components).length) continue
+
+				yield {
+					raw,
+					components,
+					country: record.country,
+					locale: localeByCountry[record.country],
+					source: adapterID,
+					source_id: `${adapterID}-${record.id}-${slot.key}-${variant.suffix}`,
+					corpus_version: "",
+					license: "CC0-1.0",
+				}
+
+				emitted++
+			}
+		}
+	}
+}