@mailwoman/corpus 9.4.0 → 10.1.0

package/lib/adapters/overture/adapter.ts

@@ -3,51 +3,51 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `overture`: Overture Maps Addresses adapter (epic #470 — the conditional corpus adapter, realized
- *   2026-06-20). Overture's global Addresses theme is the single-schema, well-normalized address
- *   dataset that fixes OpenAddresses' per-country patchiness (OA dropped Spain; OA-DE omits the
- *   Bundesland) — it even re-hosts the OA Spain data the standalone OA bucket no longer serves.
- *
- *   This adapter consumes a per-country LINE-DELIMITED JSON dump of the corpus-relevant fields (`{
- *   street, number, unit, postcode, locality }`), produced by `scripts/ingest-overture-addresses.ts
- *   --corpus-jsonl` (which does the DuckDB / S3 heavy lifting and flattens `address_levels` → the
- *   municipality locality). The split keeps `@mailwoman/corpus` — a RUNTIME dep of the `mailwoman`
- *   CLI — free of the heavy native `@duckdb/node-api`; the adapter just streams JSONL line-by-line,
- *   exactly like `openaddresses`.
- *
- *   The `street` surface carries the locale's street keyword verbatim (`"CALLE JULAN"`, `"VIA
- *   ROMA"`). We map it to `street` whole and let the downstream affix-relabel split `street_prefix`
- *   — the same path every other source rides. This slice exists because the model was
- *   en-us/fr-trained and never saw non-en/fr street formats (the 2026-06-19 EU parse-blocker
- *   measured loc-correct ES 21% / IT 59% / NL 64% vs FR/US ~98%).
- *
- *   `--country` is REQUIRED (the JSONL is per-country and the rows omit a country field), matching
- *   `openaddresses`. License is Overture's CDLA-Permissive-2.0 (attribution; not share-alike).
- *
- *   | Field | ComponentTag | | --------- | ---------------------------------------------- | |
- *   `street` | `street` (keyword incl.; affix-relabel splits prefix) | | `number` | `house_number`
- *   (skipped when "S-N"/"S/N" = sin número) | | `unit` | `unit` (if non-empty) | | `postcode`|
- *   `postcode` | | `locality`| `locality` (Overture address_levels municipality, or postal_city) |
+ * `overture`: Overture Maps Addresses adapter. The `street` value keeps the locale's street keyword
+ * verbatim. The downstream affix-relabel step splits `street_prefix` from that value.
  */
 
+import { formatAddressRow } from "@mailwoman/codex/address/format"
+import { COUNTRY_SURFACE_FORMS } from "@mailwoman/codex/country"
 import { tryParsingJSON } from "@mailwoman/core/json"
-import { formatAddress, reconcileComponents } from "@mailwoman/formatter"
+import { sample } from "@mailwoman/core/random"
+import { mulberry32 as makeMulberry32 } from "@mailwoman/core/utils"
 import { TextSpliterator } from "spliterator"
 
-import { stableSourceID } from "#adapters/utils"
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "#types"
+import { stableSourceID } from "#adapters/source-id"
+import { SourceRegister } from "#registers"
+import { AddressRole, type AdapterOptions, type CanonicalRow, type CorpusAdapter, SurfaceOrigin } 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.
+ * Registry id stamped into every row this adapter emits, so a corpus record traces back to its dataset.
  */
 export const OVERTURE_ADAPTER_ID = "overture"
 /**
- * License carried by this source (CDLA-Permissive-2.0), attached to each row so downstream consumers inherit the terms
- * rather than having to look them up.
+ * License assigned by this source (`cdla-Permissive-2.0`, attribution-only
+ * rather than share-alike), attached to every row.
  */
 export const OVERTURE_DEFAULT_LICENSE = "CDLA-Permissive-2.0"
 
+const DEFAULT_COUNTRY_SEED = 20_260_922
+
+/**
+ * One attested written form of a country's name.
+ *
+ * Raises rather than returning empty when the codex has no entry, so a requested
+ * fraction cannot silently produce no country rows.
+ */
+function countrySurfaceForm(country: string, random: () => number): string {
+	const forms = COUNTRY_SURFACE_FORMS[country as keyof typeof COUNTRY_SURFACE_FORMS]
+
+	if (!forms?.length) {
+		throw new Error(
+			`No COUNTRY_SURFACE_FORMS entry for ${country} — add it to codex/country/country.ts before using --country-fraction`
+		)
+	}
+
+	return sample(forms, random)
+}
+
 /**
  * The flattened per-row shape emitted by `ingest-overture-addresses.ts --corpus-jsonl`.
  */
@@ -59,6 +59,21 @@ interface OvertureCorpusRow {
 	locality?: string
 }
 
+/**
+ * Whether an Overture `unit` value is a secondary-unit designator
+ * (a digit or a single bare word) rather than a name.
+ *
+ * Overture-SG puts an estate name in this field on 91,818 of 142,210 rows and the literal
+ * `NIL` on 47,407 more, so a name taught as `unit` would teach a trailing proper name.
+ */
+export function unitFieldIsDesignator(value: string): boolean {
+	const trimmed = value.trim()
+
+	if (!trimmed || trimmed.toUpperCase() === "NIL") return false
+
+	return /\d/u.test(trimmed) || !/\s/u.test(trimmed)
+}
+
 function parseLine(line: string): OvertureCorpusRow | null {
 	const t = line.trim()
 
@@ -73,6 +88,11 @@ export function createOvertureAdapter(): CorpusAdapter {
 	return {
 		id: OVERTURE_ADAPTER_ID,
 		defaultLicense: OVERTURE_DEFAULT_LICENSE,
+		addressRole: AddressRole.Premise,
+		// Overture rows include their own `sources[].dataset` and `sources[].license`,
+		// so this declares the aggregator rather than asserting a national grant.
+		register: SourceRegister.Overture,
+		surface: SurfaceOrigin.Rendered,
 		description: "Overture Maps Addresses (global): per-country JSONL of street/number/postcode/locality.",
 
 		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
@@ -83,10 +103,10 @@ export function createOvertureAdapter(): CorpusAdapter {
 			}
 
 			const country = opts.country
+			const countryFraction = opts.countryFraction ?? 0
+			const random = makeMulberry32(opts.seed ?? DEFAULT_COUNTRY_SEED)
 
-			// TextSpliterator streams string lines (parseLine keeps tolerating blank/`#`/malformed
-			// lines by returning null); the path string lets the lib own + dispose the file handle,
-			// including on an early `break`.
+			// The path string lets `TextSpliterator` own and dispose the file handle, including on an early `break`.
 			const lines = TextSpliterator.fromAsync(opts.inputPath)
 
 			let emitted = 0
@@ -106,7 +126,7 @@ export function createOvertureAdapter(): CorpusAdapter {
 				const postcode = r.postcode?.trim() ?? ""
 				const locality = r.locality?.trim() ?? ""
 
-				// Only useful with a street + (postcode OR locality); point-only rows quarantine anyway.
+				// Only useful with a street + (postcode or locality); point-only rows quarantine anyway.
 				if (!street) continue
 
 				if (!postcode && !locality) continue
@@ -120,7 +140,7 @@ export function createOvertureAdapter(): CorpusAdapter {
 
 				components.street = street
 
-				if (unit) {
+				if (unitFieldIsDesignator(unit)) {
 					components.unit = unit
 				}
 
@@ -132,13 +152,17 @@ export function createOvertureAdapter(): CorpusAdapter {
 					components.locality = locality
 				}
 
-				const raw = formatAddress(components, country, { separator: ", " })
+				// Overture rows are country-implicit, so the surface form goes into `components`
+				// and each country's layout decides where the country lands in the rendered string.
+				if (countryFraction > 0 && random() < countryFraction) {
+					components.country = countrySurfaceForm(country, random)
+				}
 
-				if (!raw) continue
+				const rendered = formatAddressRow(components, country, { singleLine: true })
 
-				const aligned = reconcileComponents(components, raw)
+				if (!rendered) continue
 
-				if (!Object.keys(aligned).length) continue
+				const { raw, components: aligned } = rendered
 
 				yield {
 					raw,

package/lib/adapters/po-box/adapter.ts

@@ -0,0 +1,202 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * PO box / PMB / Apartado / BP synthesizer adapter. It emits {@linkcode PO_BOX_ADAPTER_ID}.
+ *
+ * A PO box delivery line is mutually exclusive with a street line (USPS Pub 28 / DMM 508), so rows
+ * are generated fresh from a tuple rather than by mutating a street row.
+ */
+
+import { tryParsingJSON } from "@mailwoman/core/json"
+import { makeLcg } from "@mailwoman/core/random"
+import { TextSpliterator } from "spliterator"
+
+import { stableSourceID } from "#adapters/source-id"
+import { defaultRecipeSource } from "#recipes/sources"
+import {
+	poBoxTemplateLocale,
+	REGION_OPTIONAL_LOCALES,
+	synthesizeMilitaryPoBoxRow,
+	synthesizePoBoxRow,
+	type PoBoxBaseTuple,
+} from "#synthesizers/po-box"
+import { AddressRole, type AdapterOptions, type CanonicalRow, type CorpusAdapter, SurfaceOrigin } from "#types"
+
+/**
+ * Registry id stamped into every row this adapter emits, so a corpus record traces back to its dataset.
+ *
+ * The value comes from `RECIPE_SOURCES` because `recipes/po/box/index.ts` writes rows under the same id.
+ * Two producers of one id have to spell it the same way, or a rewrite of a corpus through that table
+ * moves the recipe's rows and leaves this adapter's behind under a name the table no longer answers for.
+ */
+export const PO_BOX_ADAPTER_ID = defaultRecipeSource("synth-po-box")
+/**
+ * License for synthetic PO-box rows.
+ *
+ * They inherit the terms of the real tuples used to derive them.
+ *
+ * The value is stored in each row's `license` column and read by `licenseNamedIn`,
+ * so it stays byte-for-byte.
+ */
+export const PO_BOX_LICENSE = "Synthetic — derived from CC-BY / public-domain input tuples"
+
+export interface PoBoxInputRow extends PoBoxBaseTuple {
+	street?: string
+	houseNumber?: string
+}
+
+export interface PoBoxAdapterOptions {
+	/**
+	 * How many PO box variants to emit per input tuple, each picking a different leader
+	 * (and possibly a different number or noise level); default 1.
+	 */
+	variantsPerInput?: number
+	/**
+	 * Probability (0..1) of emitting a PMB-with-street variant when the input has
+	 * a street and the locale supports PMB.
+	 * The default is 0.15.
+	 */
+	pmbRatio?: number
+	/**
+	 * Deterministic seed for reproducible synthesis.
+	 * The default is `Date.now()`.
+	 */
+	seed?: number
+	/**
+	 * Probability (0..1) per input tuple of additionally emitting one self-contained US
+	 * military/diplomatic PO-box row, so military volume scales with the input stream.
+	 * The default is 0.
+	 */
+	militaryRatio?: number
+}
+
+export function createPoBoxAdapter(opts: PoBoxAdapterOptions = {}): CorpusAdapter {
+	const variantsPerInput = opts.variantsPerInput ?? 1
+	const pmbRatio = opts.pmbRatio ?? 0.15
+	const militaryRatio = opts.militaryRatio ?? 0
+
+	return {
+		id: PO_BOX_ADAPTER_ID,
+		defaultLicense: PO_BOX_LICENSE,
+		addressRole: AddressRole.Mailing,
+		// No register asserts these boxes exist.
+		// The rows teach the shape of a post-office box line.
+		register: null,
+		surface: SurfaceOrigin.Invented,
+		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())
+
+			// A non-throwing parse (the `skipped++` below) tolerates malformed rows,
+			// unlike `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), where the guard must not discard the tuple as missing region.
+				const regionOptional = input.country ? REGION_OPTIONAL_LOCALES.has(poBoxTemplateLocale(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 the locality slot to vary the digest across variants;
+					// `stableSourceID` only accepts `ComponentTag` keys.
+					const sourceID = stableSourceID(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: PO_BOX_ADAPTER_ID,
+						source_id: sourceID,
+						corpus_version: "",
+						license: PO_BOX_LICENSE,
+					}
+
+					emitted++
+
+					if (options.limit !== undefined && emitted >= options.limit) break
+				}
+
+				// US military/diplomatic rows are self-contained and off by default,
+				// so the default random stream and output stay byte-identical.
+				// They are US-only and count against `limit`.
+				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(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: PO_BOX_ADAPTER_ID,
+						source_id: sourceID,
+						corpus_version: "",
+						license: PO_BOX_LICENSE,
+					}
+
+					emitted++
+				}
+			}
+		},
+	}
+}
+
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const poBoxAdapter = createPoBoxAdapter()

package/lib/adapters/registry.ts

@@ -0,0 +1,79 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The lookup table that resolves an adapter id to its implementation.
+ *
+ * `mailwoman corpus run <adapter-id>` and the `corpus build` pipeline both resolve `<adapter-id>`
+ * through this registry. Adapters do not self-register at module load; `adapters.ts` adds each one
+ * explicitly, so the dependency graph stays traceable.
+ */
+
+import { stringifyJSON } from "@mailwoman/core/json"
+
+import type { CorpusAdapter } from "#types"
+
+/**
+ * Lookup table for corpus adapters.
+ */
+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 {@linkcode defaultAdapterRegistry}, which `adapters.ts` populates.
+ */
+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 ${stringifyJSON(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.ts`.
+ *
+ * A test constructs its own {@linkcode InMemoryAdapterRegistry} rather than mutating this one.
+ */
+export const defaultAdapterRegistry = new InMemoryAdapterRegistry()

package/lib/adapters/sha256-stream.ts

@@ -0,0 +1,49 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The incremental digest the runner records in `manifest.json`.
+ */
+
+import { createHash, type Hash } from "@mailwoman/core/hash"
+
+/**
+ * A digest built from chunks rather than from one value.
+ *
+ * `@mailwoman/core/hash` covers one-shot digests with `sha256Hex` and whole-file digests with `sha256File`.
+ * The runner needs neither, because it hashes each jsonl line as it streams past
+ * and would otherwise read the file a second time for the manifest checksum.
+ */
+export interface StreamingHasher {
+	update(chunk: string | Uint8Array): void
+	digest(): string
+}
+
+/**
+ * A SHA-256 {@linkcode StreamingHasher} returning a hex digest.
+ *
+ * `digest()` is idempotent and `update()` after it throws, so a caller cannot
+ * extend a digest it has already recorded.
+ */
+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(chunk)
+		},
+		digest() {
+			if (!finalized) {
+				digestHex = h.digest("hex")
+				finalized = true
+			}
+
+			return digestHex
+		},
+	}
+}

package/lib/adapters/source-id.ts

@@ -0,0 +1,49 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The deterministic row id for a source that publishes no primary key of its own.
+ *
+ * A CSV row or GeoJSON feature often carries no stable identifier. The runner still needs one, so
+ * deduplication and holdout manifests agree across reruns and a run can resume. These functions
+ * derive it by hashing the adapter id together with a canonical serialization of the row's values.
+ *
+ * The separator bytes are part of the hashed stream, so changing them changes every id in every
+ * built corpus.
+ */
+
+import type { ComponentTag } from "@mailwoman/codex/component"
+import { sha256Hex } from "@mailwoman/core/hash"
+
+/**
+ * The deterministic content-addressed source id for a row, keyed by its components.
+ *
+ * The output is `<adapterID>-<first 12 hex characters of sha256>`.
+ * Twelve hex characters carry 48 bits, which holds about 17 million rows per adapter
+ * before the expected collision count passes 1.
+ * An adapter above that extends the prefix.
+ */
+export function stableSourceID(adapterID: string, components: Partial<Record<ComponentTag, string>>): string {
+	return stableSourceIDFromParts(adapterID, components)
+}
+
+/**
+ * {@linkcode stableSourceID} over arbitrary disambiguator keys, such as a variant index
+ * or a slot number that is not a `ComponentTag`.
+ *
+ * Both functions sort and hash every key handed in, so only the key vocabulary differs.
+ * The narrower signature above stops an adapter from 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 rather than three chained ones — identical byte stream
+	// either way, but the separator has to stay inline or every id in every built corpus changes.
+	const digest = sha256Hex(`${adapterID}\u001E${payload}`)
+
+	return `${adapterID}-${digest.slice(0, 12)}`
+}

package/lib/adapters/street-line.ts

@@ -0,0 +1,135 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Reading a house number and a street out of the columns a publisher supplies.
+ *
+ * Publishers divide the same address two ways. Some write one street line that holds the number and
+ * the street together, which {@linkcode splitStreetLine} separates for a number-first country and
+ * {@linkcode splitTrailingStreetLine} for a number-last one. Others write the number across
+ * two columns, which {@linkcode composeHouseNumber} joins. Every adapter facing either shape uses
+ * these, so an edge case fixed here is fixed for all of them.
+ *
+ * Which of the two split functions a country takes is `STREET_ORDERS` in
+ * `packages/mailwoman/tools/dev-tools/codex/street-orders.ts`, whose values reach the generated
+ * layouts `@mailwoman/codex/address/layouts` serves.
+ */
+
+/**
+ * A leading house number on a US-style street line contains digits and an optional hyphenated range
+ * (Queens `40-12`), an optional single alpha suffix (`101A`), then whitespace, then the rest.
+ *
+ * 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.
+ * The required 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.
+ * An input that does not match the prefix shape, including `"PO Box 1234"`,
+ * `"RR 2 Box 67"` and `"HC 1"`, becomes a single `street` value rather than being mangled,
+ * so the model sees the original surface form and downstream classifiers pick it up.
+ * A caller that needs those forms recognized as something other than a street
+ * (see `usgov-irs-bmf`) tests 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 }
+}
+
+/**
+ * A trailing house number on a number-last street line contains digits,
+ * an optional single alpha suffix written against them (`39A`), and an optional slash-
+ * or hyphen-joined subdivision (`2/TER`, `16/18`, `12-B`).
+ *
+ * The street and the number are separated by whitespace, a comma, or both,
+ * because a publisher in a number-last country may write either: Italy's ANAC release
+ * carries `VIA INDIPENDENZA, 41` and `VIA MAZZINI 7` in the same column.
+ * The separator is required, so `VIA1` stays one street name.
+ *
+ * Group 1 starts at `\S` and the lazy `.*?` is bounded by that required separator,
+ * so a run of whitespace between the two groups has one split rather than every possible split.
+ * That is the same backtracking argument {@linkcode HOUSE_NUMBER_PREFIX} records, read from the other end.
+ */
+export const HOUSE_NUMBER_SUFFIX = /^(\S.*?)[\s,]+(\d+[A-Za-z]?(?:\s*[/-]\s*[0-9A-Za-z]{1,4})?)$/u
+
+/**
+ * Split a number-last street line on {@link HOUSE_NUMBER_SUFFIX}.
+ *
+ * A number-last country writes the number after the street name, which is what
+ * `STREET_ORDERS` records for Italy, Germany, Finland and 150 other jurisdictions.
+ * Whitespace inside the line is collapsed, and the separators inside a subdivided
+ * number are closed up, so `VIA PERUGIA 2 / A` yields `2/A`.
+ *
+ * @returns `null` for blank input.
+ * A line that ends in anything but a number becomes a single `street` value
+ * rather than being mangled, as `PIAZZA CASTELLO` and `VIALE ROMA SNC` do.
+ * A caller that treats an unplaced number inside such a line as a defect tests
+ * the returned `street` for a digit.
+ * This function leaves that decision to the caller, because a street name can legitimately hold a digit.
+ */
+export function splitTrailingStreetLine(line: string): SplitStreetLine | null {
+	const trimmed = line.replaceAll(/\s+/gu, " ").trim()
+
+	if (!trimmed) return null
+
+	const match = HOUSE_NUMBER_SUFFIX.exec(trimmed)
+
+	if (!match) return { street: trimmed }
+
+	return { house_number: match[2]!.replaceAll(/\s*([/-])\s*/gu, "$1"), street: match[1]!.trim() }
+}
+
+/**
+ * Joins a house number to the suffix a publisher stores in its own column.
+ *
+ * Several registers split a house number across two columns: BAN writes `10`
+ * and `bis`, Kartverket writes `12` and `B`.
+ * The separator differs per publisher, so the caller states it, and the two values are
+ * trimmed here because a publisher's padding is not part of the number.
+ *
+ * @param number The numeric part, from the publisher's number column.
+ * @param suffix The letter or word that follows it, from the publisher's suffix column.
+ * @param separator What to place between them.
+ * Kartverket joins `12` and `B` as `12B`; BAN joins `10` and `bis` as `10 bis`.
+ * @returns The joined number, or an empty string when the numeric part is absent.
+ * A caller treats the empty string as a row with no house number rather than assigning it.
+ */
+export function composeHouseNumber(number: string, suffix: string, separator = ""): string {
+	const trimmedNumber = number.trim()
+
+	if (!trimmedNumber) return ""
+
+	const trimmedSuffix = suffix.trim()
+
+	return trimmedSuffix ? `${trimmedNumber}${separator}${trimmedSuffix}` : trimmedNumber
+}