@mailwoman/corpus 9.1.0 → 9.3.0

package/lib/synthesizers/german.ts

@@ -0,0 +1,260 @@
+/**
+ * @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 slice
+ *   (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 "@mailwoman/formatter"
+
+import type { CanonicalRow } from "#types"
+
+/**
+ * A real address tuple (e.g. one OpenAddresses row): street + locality required, rest optional.
+ */
+/* oxlint-disable sister-software/no-unnamed-threshold -- the bare decimals below are weighted-sampler
+   cutoffs, not thresholds: `const r = random()` followed by a cascade of `r < 0.4` branches IS the
+   output distribution, and reading the cascade top-to-bottom is how you see it. Naming each cutoff
+   would hide the distribution behind a wall of identifiers. Genuine thresholds in these files are
+   extracted as named constants above. */
+
+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 slice 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"
+	/**
+	 * The string between rendered address lines. `", "` (default) is the template's own join. `" "` renders the
+	 * comma-free single-line register — dictation, a copy out of a one-field form — `Neusser Str. 12 Nippes 50733 Köln`
+	 * for the same components. Stage 2 segments the comma form into three and the comma-free form into ONE, and a single
+	 * segment starves the placetype-pair prior, which is how the comma-free form loses `Nippes` (#1946). Only the native
+	 * order reads it; the international layout keeps its own separator.
+	 */
+	separator?: ", " | " "
+}
+
+/**
+ * @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 check 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
+	const separator = order === "native" ? (opts.separator ?? ", ") : ", "
+	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" && separator === ", " && 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-slice caller + tests.
+ */
+export function synthesizeGermanRow(
+	base: LocaleBaseTuple,
+	opts: LocaleSynthesisOpts = {}
+): SynthesizedLocaleRow | null {
+	return synthesizeLocaleRow(base, "DE", opts)
+}

package/lib/synthesizers/house-venue.ts

@@ -0,0 +1,308 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   House-number + venue + street co-occurrence synthesizer. The v0.6.3 corrective slice.
+ *
+ *   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 `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
+ *   slice 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 `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 { countryToLocale, pick } from "#synthesizers/utils"
+import type { CanonicalRow } from "#types"
+
+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
+}
+
+//#region Venue pool
+
+/**
+ * PLAIN venue names, carrying no street-typing tokens. This slice teaches house_number + venue coexistence, NOT
+ * decompose-mode pressure — adversarial venue names live in `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",
+	// FR-flavored venue names (the run-2 contingency): the failing gauntlet fixtures carry
+	// international/English names at FR addresses, but native forms must appear too — the register
+	// mixes both in real Paris data.
+	"Café de la Poste",
+	"Boulangerie Saint-Michel",
+	"Le Petit Bistrot",
+	"Brasserie du Marché",
+	"Chez Marcel",
+	"La Belle Époque",
+	"Restaurant du Port",
+	"Pharmacie Centrale",
+	"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",
+]
+
+/**
+ * GB-flavored venue names (#1366): institutional forms (Club/Centre/House/Arms/Station), the "Ye" archaic register, and
+ * brand–dash–place compounds — INCLUDING directional-led names, because the target class is venues that open with
+ * compass words ("New North Health Centre", "Southfields Station") and the base model reads those as locality/street
+ * evidence. The six #1366 gauntlet fixtures' own venue names are deliberately ABSENT — the fixtures stay held-out.
+ */
+const GB_VENUES: ReadonlyArray<string> = [
+	"Ye Olde Cheshire Cheese",
+	"Ye Old Mitre",
+	"The Red Lion",
+	"The Crown & Anchor",
+	"The King's Arms",
+	"The White Hart",
+	"The Royal Oak",
+	"North End Road Market",
+	"Northfields Community Centre",
+	"South Bank Tavern",
+	"Southgate Dental Practice",
+	"West End Barbers",
+	"East Street Pharmacy",
+	"New Cross Learning Centre",
+	"Old Street Works",
+	"Upper Crust - Waterloo",
+	"Pret a Manger - Leadenhall",
+	"Greggs - Camden High Street",
+	"The Ivy - Chelsea Garden",
+	"Marks & Spencer Simply Food",
+	"Chapel Market Fishmongers",
+	"Victoria Coach Station",
+	"Highbury Fields Tennis Club",
+	"The Carpenters Arms",
+	"St Bride's Institute",
+	"Albion House",
+	"Imperial Dry Cleaners",
+	"Golden Dragon 金龍饭店",
+]
+
+//#endregion
+
+//#region Fallback street pool
+
+/**
+ * Stand-in streets for tuples that carried no `street` field. Plain names, no 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",
+]
+
+//#endregion
+
+//#region 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)
+}
+
+//#endregion
+
+//#region Synthesis
+
+/**
+ * Fraction of GB rows drawing from {@link GB_VENUES} instead of the shared pool. 0.7 mirrors the register mix in real
+ * GB listings data (institutional names dominate, international/generic names still appear) — pre-registered in the
+ * #1366 memo.
+ */
+const GB_VENUE_POOL_RATE = 0.7
+
+/**
+ * Fraction of GB rows whose house number widens into a range ("287-293"). Real GB venue addresses frequently span
+ * buildings; 0.15 keeps ranges a minority register — pre-registered in the #1366 memo.
+ */
+const GB_RANGE_NUMBER_RATE = 0.15
+
+/**
+ * Fraction of rows (EVERY template order) rendered with a trailing country surface, tagged `country`. The 2026-08-01
+ * operator probe set proved the mechanism: the FR control row ("…, 75004 Paris, France") fails on a model trained only
+ * on country-less venue rows while its country-less twin passes — a trailing country makes the whole template OOD
+ * (Addendum 3 of the #1366 pre-registration). 0.3 keeps the country-less register dominant.
+ */
+const COUNTRY_APPEND_RATE = 0.3
+
+/**
+ * Trailing country surfaces by tuple country — the register mixes formal and short forms where both are common.
+ */
+const COUNTRY_SURFACES: Readonly<Record<string, ReadonlyArray<string>>> = {
+	US: ["United States", "USA"],
+	GB: ["United Kingdom", "United Kingdom", "United Kingdom", "UK"],
+	FR: ["France"],
+	CA: ["Canada"],
+	AU: ["Australia"],
+	DE: ["Germany", "Deutschland"],
+}
+
+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")
+
+	// FR renders postcode-before-locality with NO region ("MR & MRS CRAB, 20 Rue de la Huchette,
+	// 75005 Paris" — the v4.0.0 gauntlet's venue-led failure family, the run-2 contingency's exact
+	// target shape). GB (#1366) renders locality-then-postcode with NO region and NO comma between
+	// them ("Ye Three Lords, 27 Minories, London EC3N 1DE" — the third tail the slice must teach).
+	// VE (#1821) renders locality-then-postcode and KEEPS the region after it. Every other country
+	// keeps the original US-order tail, which is itself the `after_region` surface — `Springfield, IL
+	// 02101` and `Bengaluru, Karnataka 560038` are the same shape.
+	const frOrder = base.country === "FR"
+	const gbOrder = base.country === "GB"
+	// VE writes the code on the LOCALITY segment with the region still after it — `…, Barcelona 6001, Anzoátegui,
+	// Venezuela`, the four `ve_city_postcode_trailing_state` board rows. That is neither GB's form (which drops the
+	// region) nor the default (which puts the region before the code), so it needs its own branch.
+	//
+	// It belongs HERE rather than in a standalone admin slice, and that is measured: three trailing-region slices
+	// carrying only admin segments all graded DO-NOT-SHIP, and the way they failed was by damaging the classes they did
+	// not contain — v4.8.0 turned `Ye Three Lords, 27 Minories, London EC3N 1DE` into `locality: "Ye Three Lords"`,
+	// losing the venue and the street. Every row this synthesizer emits carries a venue, a street AND a house number,
+	// so the surface is taught with the alternatives present rather than against them.
+	const veOrder = base.country === "VE"
+
+	// GB rows draw from the GB pool 70% of the time (institutional/archaic/brand-dash-place forms,
+	// incl. directional-led names — the #1366 target class) and the shared pool otherwise; real GB
+	// registers mix both. Other locales keep the shared pool (which already carries the FR flavor).
+	const venue = gbOrder && random() < GB_VENUE_POOL_RATE ? pick(GB_VENUES, random) : pick(PLAIN_VENUES, random)
+	const street = base.street ?? pick(FALLBACK_STREETS, random)
+	let houseNumber = base.houseNumber ?? randomHouseNumber(random)
+
+	// GB range numbers ("287-293 New N Rd"): real GB venue addresses frequently span buildings.
+	// 15% of GB rows widen the number into a range (same parity, small span — the register's real
+	// shape). Pre-registered in the #1366 memo; the base pool's no-ranges stance stays for other
+	// locales.
+	if (gbOrder && random() < GB_RANGE_NUMBER_RATE && /^\d+$/.test(houseNumber)) {
+		const start = Number.parseInt(houseNumber, 10)
+		const span = (1 + Math.floor(random() * 4)) * 2
+
+		houseNumber = `${start}-${start + span}`
+	}
+
+	const components: CanonicalRow["components"] = {
+		house_number: houseNumber,
+		street,
+		venue,
+		locality: base.locality,
+		...(frOrder || gbOrder ? {} : { region: base.region }),
+		postcode: base.postcode,
+	}
+
+	let tail = frOrder
+		? `${base.postcode} ${base.locality}`
+		: gbOrder
+			? `${base.locality} ${base.postcode}`
+			: veOrder
+				? `${base.locality} ${base.postcode}, ${base.region}`
+				: `${base.locality}, ${base.region} ${base.postcode}`
+
+	// Trailing country surface (Addendum 3): appended AFTER the tail in every order, tagged.
+	const countrySurfaces = COUNTRY_SURFACES[base.country]
+
+	if (countrySurfaces && random() < COUNTRY_APPEND_RATE) {
+		const countrySurface = pick(countrySurfaces, random)
+		components.country = countrySurface
+		tail = `${tail}, ${countrySurface}`
+	}
+
+	let raw: string
+
+	switch (template) {
+		case "venue-after-street":
+			raw = `${houseNumber} ${street}, ${venue}, ${tail}`
+			break
+		case "venue-before-street":
+			raw = `${venue}, ${houseNumber} ${street}, ${tail}`
+			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
+}
+
+//#endregion