@mailwoman/corpus 9.0.0 → 9.2.0

package/src/adapters/state-ny-notaries/adapter.ts

@@ -14,12 +14,13 @@
  *   License: stamped `"Public Domain"` per New York state government open-data terms.
  */
 
+import { isPresent } from "@mailwoman/core/objects"
+import { reconcileComponents } from "@mailwoman/formatter"
 import { CSVSpliterator } from "spliterator"
 
-import { splitStreetLine, 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"
+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
@@ -32,30 +33,6 @@ export const STATE_NY_NOTARIES_ADAPTER_ID = "state-ny-notaries"
  */
 export const STATE_NY_NOTARIES_DEFAULT_LICENSE = "Public Domain"
 
-interface NyNotaryRow {
-	"Commission Holder Name": string
-	"Commission Number (UID)": string
-	"Business Name (if available)": string
-	"Business Address 1 (if available)": string
-	"Business Address 2 (if available)": string
-	" Business City (if available)": string
-	"Business State (if available)": string
-	"Business Zip (if available)": string
-	"Commissioned County": string
-}
-
-const RAW_NY_COLUMNS = [
-	"Commission Holder Name",
-	"Commission Number (UID)",
-	"Business Name (if available)",
-	"Business Address 1 (if available)",
-	"Business Address 2 (if available)",
-	" Business City (if available)",
-	"Business State (if available)",
-	"Business Zip (if available)",
-	"Commissioned County",
-] as const
-
 export function createStateNyNotariesAdapter(): CorpusAdapter {
 	return {
 		id: STATE_NY_NOTARIES_ADAPTER_ID,
@@ -104,7 +81,7 @@ export function createStateNyNotariesAdapter(): CorpusAdapter {
 
 				if (!state) continue
 
-				const fullAddress = [address1, address2].filter(Boolean).join(" ")
+				const fullAddress = [address1, address2].filter(isPresent).join(" ")
 				const split = splitStreetLine(fullAddress)
 
 				if (!split) continue
@@ -121,10 +98,14 @@ export function createStateNyNotariesAdapter(): CorpusAdapter {
 					...(county ? { subregion: county } : {}),
 				}
 
-				const streetPart = [split.house_number, split.street].filter(Boolean).join(" ").trim()
+				const streetPart = [split.house_number, split.street].filter(isPresent).join(" ").trim()
 
-				const raw = [venue, streetPart, [city, [stateAbbr, zip].filter(Boolean).join(" ")].filter(Boolean).join(", ")]
-					.filter(Boolean)
+				const raw = [
+					venue,
+					streetPart,
+					[city, [stateAbbr, zip].filter(isPresent).join(" ")].filter(isPresent).join(", "),
+				]
+					.filter(isPresent)
 					.join(", ")
 
 				const aligned = reconcileComponents(components, raw)

package/src/adapters/state-tx-notaries/adapter.ts

@@ -15,12 +15,13 @@
  *   License: stamped `"Public Domain"` per Texas state government open-data terms.
  */
 
+import { isPresent } from "@mailwoman/core/objects"
+import { reconcileComponents } from "@mailwoman/formatter"
 import { CSVSpliterator } from "spliterator"
 
-import { splitStreetLine, 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"
+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
@@ -104,7 +105,7 @@ export function createStateTxNotariesAdapter(): CorpusAdapter {
 
 				if (!split) continue
 
-				const venue = [firstName, lastName].filter(Boolean).join(" ") || undefined
+				const venue = [firstName, lastName].filter(isPresent).join(" ") || undefined
 
 				const components: CanonicalRow["components"] = {
 					...(venue ? { venue } : {}),
@@ -115,10 +116,14 @@ export function createStateTxNotariesAdapter(): CorpusAdapter {
 					...(zip ? { postcode: zip } : {}),
 				}
 
-				const streetPart = [split.house_number, split.street].filter(Boolean).join(" ").trim()
+				const streetPart = [split.house_number, split.street].filter(isPresent).join(" ").trim()
 
-				const raw = [venue, streetPart, [city, [stateAbbr, zip].filter(Boolean).join(" ")].filter(Boolean).join(", ")]
-					.filter(Boolean)
+				const raw = [
+					venue,
+					streetPart,
+					[city, [stateAbbr, zip].filter(isPresent).join(" ")].filter(isPresent).join(", "),
+				]
+					.filter(isPresent)
 					.join(", ")
 
 				const aligned = reconcileComponents(components, raw)

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

@@ -7,7 +7,7 @@
  *
  *   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
- *   `../../synthesize-po-box.ts` for the per-locale templates and number-noise logic.
+ *   `@mailwoman/corpus/synthesizers/po-box` for the per-locale templates and number-noise logic.
  *
  *   Why an adapter and not an augmenter:
  *
@@ -24,15 +24,15 @@ import { tryParsingJSON } from "@mailwoman/core/objects"
 import { makeLcg } from "@mailwoman/core/utils"
 import { TextSpliterator } from "spliterator"
 
-import { stableSourceID } from "../../adapter.ts"
+import { stableSourceID } from "#adapters/utils"
 import {
 	countryToLocale,
 	REGION_OPTIONAL_LOCALES,
 	synthesizeMilitaryPoBoxRow,
 	synthesizePoBoxRow,
 	type PoBoxBaseTuple,
-} from "../../synthesize-po-box.ts"
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "../../types.ts"
+} 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,9 +36,11 @@
 
 import { DatabaseSync } from "node:sqlite"
 
-import { lookupFipsState } from "../../codex/us-fips-state.ts"
-import { formatAddress, reconcileComponents } from "../../format.ts"
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "../../types.ts"
+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,13 @@
  *   terms.
  */
 
+import { isPresent } from "@mailwoman/core/objects"
+import { reconcileComponents } from "@mailwoman/formatter"
 import { CSVSpliterator } from "spliterator"
 
-import { splitStreetLine, 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"
+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
@@ -90,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,13 @@
  *   License: stamped `"Public Domain"` per IMLS federal government distribution terms.
  */
 
+import { isPresent } from "@mailwoman/core/objects"
+import { reconcileComponents } from "@mailwoman/formatter"
 import { CSVSpliterator } from "spliterator"
 
-import { splitStreetLine, 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"
+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
@@ -75,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
 
@@ -100,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,12 @@
  *   federal).
  */
 
+import { isPresent } from "@mailwoman/core/objects"
+import { reconcileComponents } from "@mailwoman/formatter"
 import { CSVSpliterator } from "spliterator"
 
-import { splitStreetLine, stableSourceID } from "../../adapter.ts"
-import { reconcileComponents } from "../../format.ts"
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "../../types.ts"
+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
@@ -72,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 {
@@ -117,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,11 @@
 import { readdir } from "node:fs/promises"
 import { join } from "node:path"
 
-import { tryParsingJSON } from "@mailwoman/core/objects"
+import { isPresent, tryParsingJSON } from "@mailwoman/core/objects"
+import { reconcileComponents } from "@mailwoman/formatter"
 import { TextSpliterator } from "spliterator"
 
-import { reconcileComponents } from "../../format.ts"
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "../../types.ts"
+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
@@ -176,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 {
@@ -195,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 }
 	}
@@ -231,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,13 @@
  *   License: stamped `"Public Domain"` per CMS's federal government distribution terms.
  */
 
+import { isPresent } from "@mailwoman/core/objects"
+import { reconcileComponents } from "@mailwoman/formatter"
 import { CSVSpliterator } from "spliterator"
 
-import { splitStreetLine, 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"
+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
@@ -49,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(
@@ -60,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()
 
-	return [venue, streetPart, cityPart].filter(Boolean).join(", ")
+	const cityPart = [city.trim(), [state, postcode].filter(isPresent).join(" ").trim()].filter(isPresent).join(", ")
+
+	return [venue, streetPart, cityPart].filter(isPresent).join(", ")
 }
 
 export function createUsgovNPPESAdapter(): CorpusAdapter {
@@ -92,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()
@@ -101,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
 
@@ -109,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,13 @@
  *   distribution terms.
  */
 
+import { isPresent } from "@mailwoman/core/objects"
+import { reconcileComponents } from "@mailwoman/formatter"
 import { CSVSpliterator } from "spliterator"
 
-import { splitStreetLine, 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"
+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
@@ -115,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/{adapter.ts → adapters/utils/index.ts}

@@ -27,7 +27,7 @@ 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 "./types.ts"
+import type { CanonicalRow, CorpusAdapter } from "#types"
 
 /**
  * Lookup table for corpus adapters.
@@ -104,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 "../../types.ts"
+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

@@ -42,9 +42,10 @@
 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"
+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.
@@ -96,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`.
  *
@@ -118,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 []
@@ -127,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":
@@ -248,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,
+			})
 		},
 	}
 }