@mailwoman/corpus 7.2.0 → 7.2.1

package/src/synthesize-german.ts

@@ -0,0 +1,227 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   German address synthesizer — multi-locale coverage (night-shift 2026-06-02, DE-1).
+ *
+ *   The neural model is out-of-distribution on German: it truncates `Straußstraße`→`Strau` (exits at
+ *   the ß-piece boundary), absorbs the house number into the street (`Hauptstraße 5` → one span),
+ *   and mis-tags the native-order house number as a postcode (`Prenzlauer Allee 36, 10405 Berlin` →
+ *   postcode `36`). The cause is ORDER: the model was trained US+FR (house-number-FIRST,
+ *   postcode-AFTER-city), and never saw the German convention (house-number-AFTER-street,
+ *   postcode-BEFORE-city). DE-0 confirmed the tokenizer round-trips German orthography cleanly, so
+ *   this is a coverage gap, not a tokenizer ceiling.
+ *
+ *   This generator produces the missing signal as a small targeted supplement shard
+ *   (synthesis-as-supplement discipline: weight < 0.25, one-and-done). It does NOT synthesize
+ *   German street names (German morphology is hard to fake) — it takes REAL German component tuples
+ *   (from OpenAddresses Berlin/Saxony) and renders them in idiomatic German order via the OpenCage
+ *   `DE` template (`formatAddress(..., "DE")` → `"Straußstraße 27, 12623 Berlin"`). The corpus
+ *   aligner turns the row into BIO labels; every emitted component surface form occurs verbatim in
+ *   `raw` so alignment lands.
+ */
+
+import { formatAddress } from "./format.ts"
+import type { CanonicalRow } from "./types.ts"
+
+/** A real address tuple (e.g. one OpenAddresses row): street + locality required, rest optional. */
+export interface LocaleBaseTuple {
+	house_number?: string
+	street: string
+	locality: string
+	/**
+	 * A sub-locality that sits BELOW the locality (a suburb / district). NZ is the case that needs it: the OA DISTRICT
+	 * column holds the city (`Auckland`) and CITY holds the suburb (`Birkenhead`), so the real envelope carries both (`31
+	 * Rawene Road, Birkenhead, Auckland`). Rendered between street and locality in both orders when present.
+	 */
+	dependent_locality?: string
+	region?: string
+	postcode?: string
+}
+/** @deprecated Alias — use LocaleBaseTuple. */
+export type GermanBaseTuple = LocaleBaseTuple
+
+export interface SynthesizedLocaleRow {
+	raw: string
+	components: CanonicalRow["components"]
+	locale: string
+}
+/** @deprecated Alias — use SynthesizedLocaleRow. */
+export type SynthesizedGermanRow = SynthesizedLocaleRow
+
+export interface LocaleSynthesisOpts {
+	random?: () => number
+	/**
+	 * Rendering order for the SAME components. `"native"` (default) uses the country's own template (DE →
+	 * house-AFTER-street, postcode-BEFORE-city). `"international"` renders house-FIRST, postcode-AFTER-city — the US/GB
+	 * layout that international feeds, US-centric systems, and our own OpenAddresses de-sample impose on non-US
+	 * addresses. Training both teaches the model that a German address can arrive either way, so the eval's US-order
+	 * rendering stops reading as a collapse. See `docs/articles/evals/resolver-geo/2026-06-06-anchor-pilot.md` (the
+	 * order-artifact correction).
+	 */
+	order?: "native" | "international"
+	/**
+	 * Postcode surface shape. `"conventional"` (default) canonicalizes to the country's rendered form (NL: OA's glued
+	 * `1011AB` → the spaced `1011 AB`); `"as-source"` keeps the source's own surface — the form OA (and the OA-derived
+	 * evals) feed, which for NL is 100% glued. Only NL differs today; every other country passes through identically
+	 * either way. Mixing both teaches the two-letter-suffix `1012 LM` shape AND the glued feed shape (#241 — the model
+	 * currently glues the suffix onto the city).
+	 */
+	postcodeShape?: "conventional" | "as-source"
+	/**
+	 * How the NATIVE-order render joins street and house number. The OpenCage ES template comma-joins (`Calle Mayor, 12`
+	 * — the official Spanish convention); OA-derived feeds and our ES eval space-join (`CALLE MAYOR 12`, the observed
+	 * form on all 3,000 eval rows). `"template"` (default) keeps the template's own join; `"space"` collapses `<street>,
+	 * <house_number>` → `<street> <house_number>` after rendering. Countries whose template already space-joins
+	 * (DE/IT/NL) render identically under both. Mixing both stops an ES shard from teaching the comma as THE street→house
+	 * boundary signal (#241 format-diversity audit). International order ignores this (the US template is already
+	 * house-first space-joined).
+	 */
+	nativeHouseJoin?: "template" | "space"
+}
+/** @deprecated Alias — use LocaleSynthesisOpts. */
+export type GermanSynthesisOpts = LocaleSynthesisOpts
+
+/** ISO-3166 alpha-2 → BCP-47 tag for the emitted rows (primary language per country). */
+const LOCALE_TAG: Record<string, string> = {
+	DE: "de-DE",
+	ES: "es-ES",
+	IT: "it-IT",
+	NL: "nl-NL",
+	GB: "en-GB",
+	FR: "fr-FR",
+	US: "en-US",
+	NZ: "en-NZ",
+}
+
+/**
+ * Canonicalize a postcode to the form the country's template renders, so the stored component aligns verbatim against
+ * `raw`. NL is the case that needs it: OA stores `1011AB` but the OpenCage NL template emits the conventional spaced
+ * `1011 AB` (4 digits + space + 2 letters), which otherwise fails verbatim alignment and drops the row. Other countries
+ * pass through unchanged.
+ */
+function normalizePostcode(postcode: string, country: string): string {
+	if (country === "NL") {
+		const m = /^(\d{4})\s*([A-Za-z]{2})$/.exec(postcode)
+
+		if (m) return `${m[1]} ${m[2]!.toUpperCase()}`
+	}
+
+	return postcode
+}
+
+/** True when `value` appears verbatim AND as a standalone token (so BIO alignment lands cleanly). */
+function tokenPresent(raw: string, value: string): boolean {
+	if (!raw.includes(value)) return false
+	// Reject substring-of-a-larger-number collisions (e.g. house "2" inside postcode "12623").
+	const i = raw.indexOf(value)
+	const before = raw[i - 1]
+	const after = raw[i + value.length]
+	const isDigit = (c: string | undefined) => c !== undefined && c >= "0" && c <= "9"
+
+	if (/^\d+$/.test(value) && (isDigit(before) || isDigit(after))) return false
+
+	return true
+}
+
+/**
+ * Render one real tuple into an idiomatic, locale-ordered `{raw, components}` row via the OpenCage `country` template
+ * (DE → house-after-street + postcode-before-city; ES/IT the same; GB house-first; NL carries the `1012 LM` postcode),
+ * with light variation (drop house number / postcode some of the time). Returns `null` when the tuple is too thin or a
+ * component wouldn't align cleanly.
+ *
+ * Region handling is order-dependent: NATIVE order omits it (the native template absorbs the admin region into the
+ * postcode/city line, so it rarely renders verbatim and would break BIO alignment), while INTERNATIONAL order includes
+ * it in the tail ("City, Region Postcode" — the US/feed layout the eval uses; v0.9.3 / #327).
+ *
+ * Pass `opts.order: "international"` to render the same components house-first / postcode-after-city instead (see
+ * {@link LocaleSynthesisOpts.order}) — the layout international feeds impose on foreign addresses, and the one a
+ * native-order-trained model treats as a "collapse."
+ */
+export function synthesizeLocaleRow(
+	base: LocaleBaseTuple,
+	country: string,
+	opts: LocaleSynthesisOpts = {}
+): SynthesizedLocaleRow | null {
+	const random = opts.random ?? Math.random
+	const order = opts.order ?? "native"
+
+	if (!base.street || !base.locality) return null
+
+	const components: CanonicalRow["components"] = { street: base.street, locality: base.locality }
+
+	// Sub-locality (suburb / district) sits between street and locality and renders in BOTH orders — it's part
+	// of the address body, not the admin-region tail that native order drops. NZ needs it (suburb + city both on
+	// the envelope). The tokenPresent gate below drops the row if the template didn't surface it verbatim.
+	if (base.dependent_locality) {
+		components.dependent_locality = base.dependent_locality
+	}
+
+	// ~80% keep the house number (the rest are street-only forms, also idiomatic).
+	if (base.house_number && random() < 0.8) {
+		components.house_number = base.house_number
+	}
+
+	// ~85% keep the postcode (canonicalized to the country's rendered form — NL spaces it). The
+	// `postcodeShape: "as-source"` rewrite happens AFTER the render: the OpenCage NL template
+	// normalizes the postcode itself, so a glued input can't survive rendering directly.
+	if (base.postcode && random() < 0.85) {
+		components.postcode = normalizePostcode(base.postcode, country)
+	}
+
+	// International order carries the REGION in the tail ("City, Region Postcode") — the layout real
+	// US/feed renderings (and our OA eval) use. v0.9.2 rendered international order WITHOUT the region,
+	// so the model never learned to segment the tail and mangled it at eval (region absorbed into the
+	// locality / locality dropped); v0.9.3 closes that gap (#327). Native order still drops the region
+	// (the native template absorbs it into the city line, which would break verbatim alignment).
+	if (order === "international" && base.region) {
+		components.region = base.region
+	}
+
+	// Native order uses the address's own country template; international order uses the US template —
+	// house-first, postcode-after-city, with a region slot for the tail. Neither branch consumes a
+	// `random()` draw for the template, so the RNG sequence existing callers/tests depend on is stable.
+	const renderCountry = order === "international" ? "US" : country
+	let raw = formatAddress(components, renderCountry, { separator: ", " })
+
+	if (!raw) return null
+
+	// Native-order space-join (see {@link LocaleSynthesisOpts.nativeHouseJoin}): collapse the template's
+	// `<street>, <hn>` comma to a space — the OA/feed layout. A no-op for templates that already
+	// space-join (the substring isn't present), and skipped when the house number was dropped above.
+	if (order === "native" && opts.nativeHouseJoin === "space" && components.house_number) {
+		raw = raw.replace(
+			`${components.street}, ${components.house_number}`,
+			`${components.street} ${components.house_number}`
+		)
+	}
+
+	// `postcodeShape: "as-source"` (see {@link LocaleSynthesisOpts.postcodeShape}): rewrite BOTH raw and
+	// the component back to the source's own surface (NL glued `1011AB`). Post-render because the
+	// OpenCage NL template normalizes the postcode to the spaced form no matter what it's given.
+	if (opts.postcodeShape === "as-source" && components.postcode && base.postcode) {
+		const sourceForm = base.postcode.trim()
+
+		if (sourceForm && sourceForm !== components.postcode && raw.includes(components.postcode)) {
+			raw = raw.replace(components.postcode, sourceForm)
+			components.postcode = sourceForm
+		}
+	}
+
+	// Every component must align — drop the row if the template didn't surface one verbatim, or a
+	// numeric component collides with a neighbouring digit run.
+	for (const value of Object.values(components)) {
+		if (!value || !tokenPresent(raw, value)) return null
+	}
+
+	return { raw, components, locale: LOCALE_TAG[country] ?? country.toLowerCase() }
+}
+
+/** German wrapper over {@link synthesizeLocaleRow}. Kept for the build-german-shard caller + tests. */
+export function synthesizeGermanRow(
+	base: LocaleBaseTuple,
+	opts: LocaleSynthesisOpts = {}
+): SynthesizedLocaleRow | null {
+	return synthesizeLocaleRow(base, "DE", opts)
+}

package/src/synthesize-house-venue.ts

@@ -0,0 +1,192 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   House-number + venue + street co-occurrence synthesizer. The v0.6.3 corrective shard.
+ *
+ *   The v0.6.2 step-20K diagnostic showed that adding synth-no-street counter-distribution regressed
+ *   house_number recall by ~4-5pp. DeepSeek's turn-8 root-cause:
+ *
+ *   1. Direct: `5th Avenue Theatre`-style adversarial venues teach the model that tokens like "5th"
+ *        belong to venues, not house_numbers. (Fixed in `synthesize-no-street.ts` by removing
+ *        digit+ordinal venue patterns.)
+ *   2. Distributional dilution: synth-no-street adds 122K rows where house_number is absent. The model's
+ *        training distribution shifts toward "house_number is rare," and it under-emits the tag at
+ *        inference.
+ *
+ *   This synthesizer fixes #2 directly. Each emitted row has ALL of: house_number, street, venue,
+ *   locality, region, postcode — a counter-example to "house_number is rare." Used as a companion
+ *   shard to synth-no-street; the v0.6.3 config weights synth-no-street at 0.5 and
+ *   synth-house-venue at 1.0 to recover the lost house_number signal.
+ *
+ *   Real-world shape: business cards, mailing labels, store directories — `"123 Main St, Sunrise
+ *   Bakery, Springfield, IL 62701"` is a perfectly ordinary address form.
+ *
+ *   Venue pool: PLAIN_VENUES from `synthesize-no-street.ts` (re-exported here). Adversarial venues
+ *   are deliberately NOT used here — the point is to teach co-occurrence, not to re-introduce
+ *   decompose-mode pressure.
+ */
+
+import type { CanonicalRow } from "./types.ts"
+
+export interface HouseVenueBaseTuple {
+	locality: string
+	region: string
+	postcode: string
+	country: string
+	street?: string
+	houseNumber?: string
+}
+
+export type HouseVenueTemplate =
+	| "venue-after-street" // "123 Main St, Sunrise Bakery, Springfield, IL 02101"
+	| "venue-before-street" // "Sunrise Bakery, 123 Main St, Springfield, IL 02101"
+
+export interface HouseVenueSynthesisOpts {
+	random?: () => number
+	forceTemplate?: HouseVenueTemplate
+}
+
+export interface SynthesizedHouseVenueRow {
+	raw: string
+	components: CanonicalRow["components"]
+	locale: string
+	template: HouseVenueTemplate
+}
+
+// ---------------------------------------------------------------------------------------------
+// Venue pool — PLAIN, no street-typing tokens. The point of this shard is to teach
+// house_number + venue coexistence, NOT to re-introduce decompose-mode pressure.
+// Adversarial venue names live in `synthesize-no-street.ts`.
+// ---------------------------------------------------------------------------------------------
+
+const PLAIN_VENUES: ReadonlyArray<string> = [
+	"Bob's Pizza",
+	"Acme Corporation",
+	"Joe's Diner",
+	"Sunrise Bakery",
+	"Maple Leaf Cafe",
+	"Riverside Garden Center",
+	"Tech Solutions Inc",
+	"Pacific Industries",
+	"Atlantic Holdings",
+	"Stellar Consulting",
+	"Greenfield Partners",
+	"Mountain View Studio",
+	"The Daily Grind",
+	"Sunset Bistro",
+	"Harvest Moon Florist",
+	"Iron Forge Brewing",
+	"Crescent City Bookstore",
+	"Lighthouse Insurance Group",
+	"Pinecrest Veterinary",
+	"Westwood Realty",
+]
+
+// ---------------------------------------------------------------------------------------------
+// Fallback street pool for tuples that didn't carry a `street` field. Plain street names
+// without typing-token ambiguity.
+// ---------------------------------------------------------------------------------------------
+
+const FALLBACK_STREETS: ReadonlyArray<string> = [
+	"Main St",
+	"Oak Ave",
+	"Pine Rd",
+	"Elm Dr",
+	"Cedar Ln",
+	"Maple Blvd",
+	"Birch Ct",
+	"Walnut Pl",
+	"Cherry Way",
+	"Spruce St",
+	"Park Ave",
+	"Lake Dr",
+	"Hill Rd",
+	"River Ln",
+	"Forest Blvd",
+]
+
+// ---------------------------------------------------------------------------------------------
+// House-number generator
+// ---------------------------------------------------------------------------------------------
+
+function randomHouseNumber(random: () => number): string {
+	// Generate a plain numeric house number 1-9999. No fractions/ranges — those land in
+	// `data/eval/falsehoods/numbers.jsonl` as known edge cases, not training material.
+	const digits = Math.floor(random() * 4) + 1
+	const max = Math.pow(10, digits)
+	const n = Math.floor(random() * max) + 1
+
+	return String(n)
+}
+
+function pick<T>(arr: ReadonlyArray<T>, random: () => number): T {
+	return arr[Math.floor(random() * arr.length)]!
+}
+
+function countryToLocale(country: string): string {
+	switch (country) {
+		case "US":
+			return "en-US"
+		case "CA":
+			return "en-CA"
+		case "GB":
+			return "en-GB"
+		case "AU":
+			return "en-AU"
+		case "FR":
+			return "fr-FR"
+		case "DE":
+			return "de-DE"
+		default:
+			return "en-US"
+	}
+}
+
+// ---------------------------------------------------------------------------------------------
+// Synthesis
+// ---------------------------------------------------------------------------------------------
+
+export function synthesizeHouseVenueRow(
+	base: HouseVenueBaseTuple,
+	opts: HouseVenueSynthesisOpts = {}
+): SynthesizedHouseVenueRow | null {
+	const random = opts.random ?? Math.random
+	const locale = countryToLocale(base.country)
+	const template = opts.forceTemplate ?? (random() < 0.5 ? "venue-after-street" : "venue-before-street")
+
+	const venue = pick(PLAIN_VENUES, random)
+	const street = base.street ?? pick(FALLBACK_STREETS, random)
+	const houseNumber = base.houseNumber ?? randomHouseNumber(random)
+
+	const components: CanonicalRow["components"] = {
+		house_number: houseNumber,
+		street,
+		venue,
+		locality: base.locality,
+		region: base.region,
+		postcode: base.postcode,
+	}
+
+	let raw: string
+
+	switch (template) {
+		case "venue-after-street":
+			raw = `${houseNumber} ${street}, ${venue}, ${base.locality}, ${base.region} ${base.postcode}`
+			break
+		case "venue-before-street":
+			raw = `${venue}, ${houseNumber} ${street}, ${base.locality}, ${base.region} ${base.postcode}`
+			break
+	}
+
+	return { raw, components, locale, template }
+}
+
+/**
+ * Contract: every synthesized row carries BOTH house_number AND venue (the co-occurrence signal that synth-no-street's
+ * distributional shift cost the model). Used by tests + downstream consumers.
+ */
+export function hasHouseNumberAndVenue(components: CanonicalRow["components"]): boolean {
+	return components.house_number !== undefined && components.venue !== undefined
+}

package/src/synthesize-intersection.ts

@@ -0,0 +1,205 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Intersection synthesizer — v0.7 coverage fix (night-3, DeepSeek-decided).
+ *
+ *   The 2026-05-29 harness diagnostic found the neural model emits `intersection_a`/`intersection_b`
+ *   with ~0.0001 probability on canonical intersections ("Broadway & W 42nd St") — it never learned
+ *   the tags, because the corpus has NO intersection training signal (no generator, and real-data
+ *   adapters don't emit intersection-formatted rows). Intersections are 65 of the 376 harness
+ *   assertions (17%), all 0% neural. This generator produces the missing signal as a small targeted
+ *   supplement shard (synthesis-as-supplement discipline: weight < 0.25, one-and-done).
+ *
+ *   Output is a `CanonicalRow` ({raw, components}); the corpus aligner turns it into BIO labels
+ *   (B-/I-intersection_a, O on the connector, B-/I-intersection_b). Surface forms of both streets
+ *   MUST occur verbatim in `raw` so alignment lands.
+ *
+ *   US-idiomatic only (the harness intersection cases are US: "X & Y, City, ST ZIP").
+ */
+
+import type { CanonicalRow } from "./types.ts"
+
+/** Street name cores (no suffix) — proper-noun streets that often appear bare. */
+const STREET_CORES = [
+	"Main",
+	"Oak",
+	"Elm",
+	"Maple",
+	"Pine",
+	"Cedar",
+	"Park",
+	"Lake",
+	"Hill",
+	"Washington",
+	"Lincoln",
+	"Jefferson",
+	"Madison",
+	"Franklin",
+	"Market",
+	"Broad",
+	"Church",
+	"Mill",
+	"Highland",
+	"Sunset",
+	"Union",
+	"Spring",
+] as const
+
+/** Bare proper-noun streets that idiomatically take NO suffix. */
+const BARE_NAMES = ["Broadway", "Wall", "Bourbon", "Esplanade", "Riverside", "Lakeshore"] as const
+
+const ORDINALS = [
+	"1st",
+	"2nd",
+	"3rd",
+	"4th",
+	"5th",
+	"6th",
+	"7th",
+	"8th",
+	"9th",
+	"10th",
+	"42nd",
+	"23rd",
+	"34th",
+] as const
+
+const SUFFIXES = ["St", "Ave", "Blvd", "Rd", "Dr", "Ln", "Way", "Pl", "Ct", "Pkwy", "Ter", "Cir"] as const
+
+const DIRECTIONALS = ["N", "S", "E", "W", "NE", "NW", "SE", "SW"] as const
+
+/**
+ * Connectors between the two streets. Whitespace-padded forms keep tokens clean for alignment. `@` added in v0.7.2 —
+ * the harness uses it ("Main St @ Second Ave") and v0.7.1 had never seen it.
+ */
+const CONNECTORS = [" & ", " and ", " at ", " / ", " @ "] as const
+
+export interface IntersectionBaseTuple {
+	locality: string
+	region: string
+	/** ZIP — optional; ~30% of synthetic intersections omit it (idiomatic). */
+	postcode?: string
+	country: string
+}
+
+export interface SynthesizedIntersectionRow {
+	raw: string
+	components: CanonicalRow["components"]
+	locale: string
+}
+
+export interface IntersectionSynthesisOpts {
+	random?: () => number
+}
+
+function pick<T>(arr: ReadonlyArray<T>, random: () => number): T {
+	return arr[Math.floor(random() * arr.length)]!
+}
+
+/** Build a single street surface form, e.g. "W 42nd St", "Broadway", "Main St", "N Oak Ave". */
+function buildStreetName(random: () => number): string {
+	// ~20% bare proper-noun street (no suffix), else directional? + core/ordinal + suffix.
+	if (random() < 0.2) return pick(BARE_NAMES, random)
+
+	const parts: string[] = []
+
+	if (random() < 0.35) {
+		parts.push(pick(DIRECTIONALS, random))
+	}
+	parts.push(random() < 0.45 ? pick(ORDINALS, random) : pick(STREET_CORES, random))
+	parts.push(pick(SUFFIXES, random))
+
+	return parts.join(" ")
+}
+
+/**
+ * Synthesize one US intersection row. Returns null on the rare degenerate case where the two streets collide (so
+ * alignment never has two identical surface forms to disambiguate).
+ */
+export function synthesizeIntersectionRow(
+	base: IntersectionBaseTuple,
+	opts: IntersectionSynthesisOpts = {}
+): SynthesizedIntersectionRow | null {
+	const random = opts.random ?? Math.random
+
+	if (base.country !== "US") return null
+
+	const a = buildStreetName(random)
+	let b = buildStreetName(random)
+	// Ensure distinct surface forms (and not a substring of each other — alignment needs unambiguous spans).
+	let tries = 0
+
+	while ((b === a || a.includes(b) || b.includes(a)) && tries++ < 8) {
+		b = buildStreetName(random)
+	}
+
+	if (b === a || a.includes(b) || b.includes(a)) return null
+
+	const connector = pick(CONNECTORS, random)
+	// "corner of" prefix variant (~20%) — still labels the two streets identically.
+	const cornerPrefix = random() < 0.2 ? "corner of " : ""
+
+	const components: CanonicalRow["components"] = { intersection_a: a, intersection_b: b }
+
+	// v0.7.2: ~60% BARE (no locality tail). v0.7.1 always appended ", City, ST", so the model learned
+	// to read post-intersection text as a locality and fumbled the harness's bare "X & Y" cases
+	// (mislabeling the second street as a locality). Match the eval distribution.
+	const bare = random() < 0.6
+	let raw: string
+
+	if (bare) {
+		raw = `${cornerPrefix}${a}${connector}${b}`
+	} else {
+		const includePostcode = base.postcode != null && random() < 0.7
+		const tail = includePostcode
+			? `, ${base.locality}, ${base.region} ${base.postcode}`
+			: `, ${base.locality}, ${base.region}`
+		raw = `${cornerPrefix}${a}${connector}${b}${tail}`
+		components.locality = base.locality
+		components.region = base.region
+
+		if (includePostcode) {
+			components.postcode = base.postcode
+		}
+	}
+
+	return { raw, components, locale: "en-US" }
+}
+
+/** A small built-in US city/region/zip pool for standalone shard generation + tests. */
+export const DEFAULT_US_BASES: ReadonlyArray<IntersectionBaseTuple> = [
+	{ locality: "New York", region: "NY", postcode: "10036", country: "US" },
+	{ locality: "Chicago", region: "IL", postcode: "60613", country: "US" },
+	{ locality: "Los Angeles", region: "CA", postcode: "90012", country: "US" },
+	{ locality: "Seattle", region: "WA", postcode: "98109", country: "US" },
+	{ locality: "Austin", region: "TX", postcode: "78701", country: "US" },
+	{ locality: "Portland", region: "OR", postcode: "97205", country: "US" },
+	{ locality: "Denver", region: "CO", postcode: "80202", country: "US" },
+	{ locality: "Boston", region: "MA", postcode: "02116", country: "US" },
+	{ locality: "Miami", region: "FL", postcode: "33130", country: "US" },
+	{ locality: "Atlanta", region: "GA", postcode: "30303", country: "US" },
+]
+
+/** Generate `count` intersection rows over the provided bases (round-robin). */
+export function generateIntersectionRows(
+	count: number,
+	bases: ReadonlyArray<IntersectionBaseTuple> = DEFAULT_US_BASES,
+	opts: IntersectionSynthesisOpts = {}
+): SynthesizedIntersectionRow[] {
+	const random = opts.random ?? Math.random
+	const out: SynthesizedIntersectionRow[] = []
+	let guard = 0
+
+	while (out.length < count && guard++ < count * 4) {
+		const base = bases[out.length % bases.length]!
+		const row = synthesizeIntersectionRow(base, { random })
+
+		if (row) {
+			out.push(row)
+		}
+	}
+
+	return out
+}