@mailwoman/corpus 9.4.0 → 10.1.0

package/lib/synthesizers/boundary-stress.ts

@@ -3,75 +3,38 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Boundary-instability synthesizer (#375 — the highest-impact parser change). The failure taxonomy
- *
- *   The within-token-punctuation decomposition (#702) found one failure FAMILY surfacing under many
- *   names: the model mis-places token boundaries between adjacent components when the boundary is
- *   ambiguous or unmarked. This generator emits diverse BIO-labeled rows that put the gold boundary
- *   exactly where the model wobbles, so a retrain learns the boundary from context, not the
- *   lexeme.
- *
- *   The four token-aligned stress shapes, all in BASE LOCALES (US/FR/DE) so the slice never
- *   introduces tokens the base corpus lacks (the #511 base-consistency lint flagged an earlier
- *   AU-bearing draft: AU 4-digit postcodes collide with US house numbers, and AU localities are
- *   absent from the US/FR/DE base — a real contradiction). Each component is a whitespace-separated
- *   token run, so `alignRow` labels it cleanly:
- *
- *   1. `street-eats-affix` — multi-word street + suffix (`Country Club Rd` → street + street_suffix),
- *        the #1 wobble: the model keeps the suffix in the street.
- *   2. `comma-less-city-state` — no comma between street / locality / region (`100 Main St Springfield
- *        IL 62701`), the #694 family: concatenated input loses the segmentation cue. US-only (US
- *        zips are base-consistent; the boundary is locale-agnostic).
- *   3. `fr-prefix` — FR street-type prefix split from the name (`Rue Jean-Baptiste Lebas` →
- *        street_prefix
- *
- *        - Street), postcode-first order.
- *   4. `house-number-after-street` — FR/DE number-follows-street (`Neuve-des-Capucines 5` → street +
- *        house_number), the model absorbs the number into the street.
- *
- *   Two BALANCING shapes (added 2026-06-18 after the v1.6.0 probes). The first pass at weight 1.0
- *   lifted the boundaries but over-fit a NARROW distribution — every row was a clean, full,
- *   structured address — so the model regressed on out-of-distribution real rows (held-out US
- *   locality 66.3→58.2%). These two widen the distribution the slice teaches over, per the
- *   diagnosis (scripts/eval/locality-regression-probe): 5. `bare-locality` — locality with NO
- *   street (`Public Library, Lisbon ND`, `75003 Paris`), the ship-blocker: 84% of the v1.6.0
- *   locality regression was DROPPED locality on bare "City, STATE" rows, because every other shape
- *   placed a street before the city. Bare / comma-less / postcode'd / venue-prefixed forms, US +
- *   FR. 6. `house-number-before-street` — the confounding mirror of #4 (same FR vocab, number
- *   BEFORE the street). A balanced before:after mix breaks the positional shortcut behind the #4
- *   order-bias.
- *
- *   EXCLUDED: the region+postcode glue (`NY14201` — sub-token, no punctuation to split) and the
- *   AU/NZ/UK slash unit-convention (`4/2A` → unit+house_number). The slash labels cleanly (the
- *   tokenizer splits `/`) and is the worst within-token class — but it inherently requires non-base
- *   AU/NZ/UK locales, which contradict the US/FR/DE base (the lint catch). It belongs in a
- *   separately-scoped AU/NZ/UK boundary-coverage slice that ALSO adds AU base coverage, not in this
- *   base-locale slice. `synthesizers/boundary-stress.test.ts` proves the alignments.
+ *   Generates US and French address rows that stress the boundaries between adjacent components.
  */
 
+/* oxlint-disable mailwoman/prefer-home -- the admin tails below are written as US templates because every tuple this
+   synthesizer draws from is `US_TUPLES`, a hardcoded US list. The comma-less arm deliberately malforms that order.
+ A layout cannot express it. The arm stresses the segmentation cue created by commas. */
+
 import type { DirectionalAbbreviation } from "@mailwoman/codex/us"
+import { sample } from "@mailwoman/core/random"
 
-import { pick } from "#synthesizers/utils"
 import type { CanonicalRow } from "#types"
 
 /* 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. */
+   cutoffs rather than thresholds: `const r = random()` followed by a cascade of `r < 0.4` branches is the
+   output distribution. The cascade shows each weight from top to bottom. A separate constant for each cutoff
+   would hide the distribution behind identifiers. The genuine thresholds in these files are
+    extracted as constants above. */
 
+/**
+ * The row templates that {@link synthesizeBoundaryStressRow} can produce.
+ */
 export type BoundaryStressTemplate =
 	| "street-eats-affix"
 	| "comma-less-city-state"
 	| "fr-prefix"
 	| "house-number-after-street"
-	// Added 2026-06-18 after the v1.6.0 probes (the slice's NARROW distribution over-fit "full structured
-	// address" and regressed OOD). These two re-balance the contexts the model actually sees:
-	| "bare-locality" // the ship-blocker fix: locality with NO street (the 84%-dropped "City, STATE" rows)
+	| "bare-locality"
 	| "house-number-before-street"
 
-// the confounding mirror of house-number-after-street (number position)
-
+/**
+ * A locality, region, postcode and country used as an address tail.
+ */
 export interface BoundaryStressBaseTuple {
 	locality: string
 	region: string
@@ -79,14 +42,20 @@ export interface BoundaryStressBaseTuple {
 	country: string
 }
 
+/**
+ * Options for {@link synthesizeBoundaryStressRow}.
+ */
 export interface BoundaryStressSynthesisOpts {
 	random?: () => number
 	/**
-	 * Force a specific shape (tests + balanced slice composition).
+	 * A template to use instead of a sampled one.
 	 */
 	forceTemplate?: BoundaryStressTemplate
 }
 
+/**
+ * One synthesized row with its template.
+ */
 export interface SynthesizedBoundaryStressRow {
 	raw: string
 	components: CanonicalRow["components"]
@@ -94,12 +63,6 @@ export interface SynthesizedBoundaryStressRow {
 	template: BoundaryStressTemplate
 }
 
-/**
- * Multi-word street names — the suffix boundary only bites when "Club" could be read as part of the name. Single-word
- * names alone teach nothing about the suffix edge. Multi-word names are what make the suffix boundary BITE (the model
- * must not read the trailing suffix word as part of the name). Kept diverse so the slice teaches the boundary, not the
- * lexeme.
- */
 const MULTIWORD_STREETS = [
 	"Country Club",
 	"Martin Luther King",
@@ -223,14 +186,9 @@ const SUFFIXES = [
 	"Walk",
 ] as const
 
-// Vocabulary compile-checked against the codex; the ORDER stays this literal's. `Object.values(DirectionalAbbreviation)`
-// runs N,E,S,W,… — deriving the array from it would re-map every pick() draw and change shipped slice bytes.
+// Keep the order fixed because seeded sampling depends on it.
 const DIRECTIONALS = ["N", "S", "E", "W", "NE", "NW", "SE", "SW"] as const satisfies readonly DirectionalAbbreviation[]
 
-/**
- * FR street-type prefixes + hyphenated honorific street names (the hyphen is incidental; the boundary stress is the
- * prefix↔name split + the number-after-street order).
- */
 const FR_PREFIXES = [
 	"Rue",
 	"Avenue",
@@ -276,16 +234,10 @@ const FR_NAMES = [
 ] as const
 
 /**
- * Org/venue prefixes for the bare-locality shape — the v1.6.0 locality drop hit org-PREFIXED real rows hardest ("LISBON
- * PUBLIC LIBRARY, …, Lisbon ND"; "Alburg Health Center"). Teaching the locality WITH a leading venue keeps the model
- * emitting it on facility-style addresses (NPPES/HRSA shapes). `venue` is a base ComponentTag. #511-LINTED 2026-06-18
- * (scripts/lint-venue-vocab — scan of nppes/hrsa/tiger/nad/wof-admin): every token here is venue-DOMINANT in the base,
- * so the slice agrees with it. The first draft was naive — 9 terms were dropped because their tokens are dominantly
- * street/locality and would CONTRADICT the base the way Madison-as-street did (#511): "Fire" 93% street, "Veterans" 94%
- * street, "City" 68% locality, "Hall" 63% street, "Memorial"/"Hospital" 62-63% street, "Recreation" 79% street, "Town"
- * 48% locality, "Library" 51% street, "County" 68% street, "Arts"/"Courthouse"/"Municipal" dependent_locality. Kept
- * tokens: Clinic 98%, Practice 98%, Dental 100%, Health 99%, Medical 88%, Community 92%, Department 90%, Group 87%,
- * Center 65%, School 70%, Public 89%, Elementary/Family 97% (all venue).
+ * Venue prefixes for bare-locality rows.
+ *
+ * The list uses only words that the base corpus labels as venue.
+ * It avoids words that it mostly labels as street or locality.
  */
 const VENUES = [
 	"Community Center",
@@ -304,12 +256,7 @@ const VENUES = [
 	"Public School",
 ] as const
 
-/**
- * Localities DERIVED from the base corpus (#511): every name here is verified locality-DOMINANT in the training data
- * (B-locality ≫ I-street), so the slice agrees with the base instead of fighting it. The night's targeted scan caught
- * the prior vocab (Madison, Portland, Springfield IL…) at 92–100% STREET in the base ("Madison Ave"), the "5th Avenue
- * Theatre" #511 trap. See 2026-06-17-locality-vocab-fix.
- */
+// The base corpus labels each of these localities as locality.
 const US_TUPLES: ReadonlyArray<BoundaryStressBaseTuple> = [
 	{ locality: "Albuquerque", region: "NM", postcode: "87102", country: "US" },
 	{ locality: "Indianapolis", region: "IN", postcode: "46203", country: "US" },
@@ -341,13 +288,7 @@ const US_TUPLES: ReadonlyArray<BoundaryStressBaseTuple> = [
 	{ locality: "Springfield", region: "MA", postcode: "01108", country: "US" },
 ]
 
-/**
- * FR localities DERIVED from the FR (ban) slices specifically — where these famous cities are 95–99% locality-DOMINANT
- * (Paris 515605/24789, Marseille 247014/1752, Lyon 106239/3114). NB: the all-slice scan falsely flagged them
- * street-dominant by undersampling the FR block (parts 180–209) and mixing in US street-contexts; the FR-block scan is
- * the honest distribution. Dept-diverse (28 depts), region empty (French addresses carry no region token; the
- * generator's region-optional path handles it).
- */
+// French rows have no region component.
 const FR_TUPLES: ReadonlyArray<BoundaryStressBaseTuple> = [
 	{ locality: "Paris", region: "", postcode: "75003", country: "FR" },
 	{ locality: "Marseille", region: "", postcode: "13016", country: "FR" },
@@ -369,9 +310,6 @@ const FR_TUPLES: ReadonlyArray<BoundaryStressBaseTuple> = [
 	{ locality: "Rambouillet", region: "", postcode: "78120", country: "FR" },
 ]
 
-// NB: no DE_TUPLES — German cities are street-dominated too ("Berliner Straße"), and the base yielded
-// zero locality-dominant DE towns in the scan, so house-number-after-street is FR-only here. DE's
-// native-order number-after-street is covered by the dedicated synth-german slice.
 const houseNumber = (random: () => number): string => String(1 + Math.floor(random() * 4999))
 const localeFor: Record<string, string> = { US: "en-US", FR: "fr-FR", DE: "de-DE" }
 
@@ -385,31 +323,23 @@ const ALL_TEMPLATES: readonly BoundaryStressTemplate[] = [
 ]
 
 /**
- * Synthesize one boundary-stress row. `base` is optional — when omitted, a locale-appropriate tuple is drawn from the
- * internal pools (so the generator is self-contained; a build script can pass real tuples for scale + diversity). Every
- * component value is a verbatim substring of `raw`, so `alignRow` locates + BIO-labels it.
+ * Synthesizes one row from a sampled or forced template.
+ *
+ * When `base` is absent, the function samples a built-in US or French tuple that suits the template.
  */
 export function synthesizeBoundaryStressRow(
 	base: BoundaryStressBaseTuple | undefined,
 	opts: BoundaryStressSynthesisOpts = {}
 ): SynthesizedBoundaryStressRow {
 	const random = opts.random ?? Math.random
-	const template = opts.forceTemplate ?? pick(ALL_TEMPLATES, random)
+	const template = opts.forceTemplate ?? sample(ALL_TEMPLATES, random)
 
 	if (template === "bare-locality") {
-		// The v1.6.0 ship-blocker fix: locality was DROPPED on bare/short "City, STATE" rows (84% of the
-		// regression) because every prior shape placed a street before the city, so the model learned "the
-		// city follows a street" and stopped emitting locality without one. Teach the locality with NO street,
-		// across the forms real data carries it — bare, comma-LESS, postcode'd, and venue/org-prefixed.
-		const b = base ?? (random() < 0.3 ? pick(FR_TUPLES, random) : pick(US_TUPLES, random))
-		const venue = random() < 0.45 ? pick(VENUES, random) : ""
-		// ~12% carry a trailing country token — the v1.7.1 country patch (DeepSeek 2026-06-18). The pure
-		// "City, STATE" bare rows carry NO country token, which cost ~4pp on us.country_homograph in v1.7.0;
-		// teaching "…, USA"/"…, France" recovers it as a single-variable additive without diluting locality.
+		const b = base ?? (random() < 0.3 ? sample(FR_TUPLES, random) : sample(US_TUPLES, random))
+		const venue = random() < 0.45 ? sample(VENUES, random) : ""
 		const withCountry = random() < 0.12
 
 		if (b.country === "FR") {
-			// FR carries no region token; "{postcode} {locality}" is the bare FR form.
 			const core = `${b.postcode} ${b.locality}${withCountry ? ", France" : ""}`
 
 			return {
@@ -426,9 +356,8 @@ export function synthesizeBoundaryStressRow(
 		}
 
 		const withZip = random() < 0.5
-		const comma = random() < 0.6 ? "," : "" // include the comma-LESS "City STATE" form too
-		// "United States" (United 98% / States 98% country in the base), NOT "USA" — the #511 lint found
-		// "USA" is locality-DOMINANT (75%, only 6% country) in the base; labeling it country would contradict.
+		const comma = random() < 0.6 ? "," : ""
+		// The base corpus labels this spelling as country.
 		const countryName = "United States"
 		const core = `${b.locality}${comma} ${b.region}${withZip ? ` ${b.postcode}` : ""}${withCountry ? `, ${countryName}` : ""}`
 
@@ -451,17 +380,12 @@ export function synthesizeBoundaryStressRow(
 		template === "house-number-after-street" ||
 		template === "house-number-before-street"
 	) {
-		// FR-only (no base-consistent DE locality vocab; see the DE_TUPLES note above).
-		const b = base ?? pick(FR_TUPLES, random)
-		const name = pick(FR_NAMES, random)
+		const b = base ?? sample(FR_TUPLES, random)
+		const name = sample(FR_NAMES, random)
 		const hn = houseNumber(random)
 
 		if (template === "house-number-before-street") {
-			// The confounding MIRROR of house-number-after-street: the SAME FR street vocab with the number
-			// BEFORE the name. A balanced before:after mix (the build/recipe sets the ratio, ~7:3 to keep US
-			// house_number 99.8% safe) teaches the model a street-adjacent number is a house_number by FORM,
-			// not position — the probe found v1.6.0 confidently absorbs the TRAILING number into street (I-street
-			// P=0.96), the order-bias.
+			// This form balances the number-after-street form with the same vocabulary.
 			const raw = `${hn} ${name}, ${b.postcode} ${b.locality}`
 
 			return {
@@ -473,8 +397,7 @@ export function synthesizeBoundaryStressRow(
 		}
 
 		if (template === "fr-prefix") {
-			const prefix = pick(FR_PREFIXES, random)
-			// "{hn} {prefix} {name}, {postcode} {locality}" — postcode-first, prefix split from the name.
+			const prefix = sample(FR_PREFIXES, random)
 			const raw = `${hn} ${prefix} ${name}, ${b.postcode} ${b.locality}`
 
 			return {
@@ -491,7 +414,6 @@ export function synthesizeBoundaryStressRow(
 			}
 		}
 
-		// house-number-after-street: "{name} {hn}, {postcode} {locality}" — number FOLLOWS the street.
 		const raw = `${name} ${hn}, ${b.postcode} ${b.locality}`
 
 		return {
@@ -502,13 +424,11 @@ export function synthesizeBoundaryStressRow(
 		}
 	}
 
-	// en-US street shapes (street-eats-affix + comma-less). US-only — US zips are base-consistent and
-	// the boundary these teach is locale-agnostic; no need to introduce a non-base locale.
-	const b = base ?? pick(US_TUPLES, random)
+	const b = base ?? sample(US_TUPLES, random)
 	const hn = houseNumber(random)
-	const dir = random() < 0.4 ? pick(DIRECTIONALS, random) : ""
-	const name = random() < 0.7 ? pick(MULTIWORD_STREETS, random) : pick(SINGLE_STREETS, random)
-	const suffix = pick(SUFFIXES, random)
+	const dir = random() < 0.4 ? sample(DIRECTIONALS, random) : ""
+	const name = random() < 0.7 ? sample(MULTIWORD_STREETS, random) : sample(SINGLE_STREETS, random)
+	const suffix = sample(SUFFIXES, random)
 	const streetCore = `${dir ? `${dir} ` : ""}${name} ${suffix}`
 
 	const components: CanonicalRow["components"] = {
@@ -523,10 +443,8 @@ export function synthesizeBoundaryStressRow(
 
 	const raw =
 		template === "comma-less-city-state"
-			? // no commas anywhere — the segmentation cue is gone
-				`${hn} ${streetCore} ${b.locality} ${b.region} ${b.postcode}`
-			: // standard delimited, multi-word street stresses the suffix boundary
-				`${hn} ${streetCore}, ${b.locality}, ${b.region} ${b.postcode}`
+			? `${hn} ${streetCore} ${b.locality} ${b.region} ${b.postcode}`
+			: `${hn} ${streetCore}, ${b.locality}, ${b.region} ${b.postcode}`
 
 	return { raw, components, locale: localeFor[b.country] ?? "en-US", template }
 }

package/lib/synthesizers/house-venue.ts

@@ -3,34 +3,20 @@
  * @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.
+ *   Generates addresses in which a house number, a street and a venue appear together.
  */
 
-import { countryToLocale, pick } from "#synthesizers/utils"
+/* oxlint-disable mailwoman/prefer-home -- the four admin tails below are hand-written per country on purpose. */
+
+import { sample } from "@mailwoman/core/random"
+
+import { countryToLocale } from "#synthesizers/utils"
 import type { CanonicalRow } from "#types"
 
+/**
+ * The address context for one row.
+ * The synthesizer fills a missing street or house number.
+ */
 export interface HouseVenueBaseTuple {
 	locality: string
 	region: string
@@ -40,17 +26,22 @@ export interface HouseVenueBaseTuple {
 	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"
+/**
+ * Whether the venue follows the street, as in `123 Main St, Sunrise Bakery, …`, or precedes it.
+ */
+export type HouseVenueTemplate = "venue-after-street" | "venue-before-street"
 
+/**
+ * Options for {@link synthesizeHouseVenueRow}.
+ */
 export interface HouseVenueSynthesisOpts {
 	random?: () => number
 	forceTemplate?: HouseVenueTemplate
 }
 
+/**
+ * One synthesized row with its template.
+ */
 export interface SynthesizedHouseVenueRow {
 	raw: string
 	components: CanonicalRow["components"]
@@ -58,12 +49,9 @@ export interface SynthesizedHouseVenueRow {
 	template: HouseVenueTemplate
 }
 
-//#region Venue pool
+// #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`.
- */
+// Venue names in this pool avoid street-like words.
 const PLAIN_VENUES: ReadonlyArray<string> = [
 	"Bob's Pizza",
 	"Acme Corporation",
@@ -72,9 +60,7 @@ const PLAIN_VENUES: ReadonlyArray<string> = [
 	"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.
+	// French addresses include both English and French venue names, so the pool includes both.
 	"Café de la Poste",
 	"Boulangerie Saint-Michel",
 	"Le Petit Bistrot",
@@ -98,12 +84,7 @@ const PLAIN_VENUES: ReadonlyArray<string> = [
 	"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.
- */
+// This pool must exclude the venue names in the held-out gauntlet fixtures.
 const GB_VENUES: ReadonlyArray<string> = [
 	"Ye Olde Cheshire Cheese",
 	"Ye Old Mitre",
@@ -135,13 +116,10 @@ const GB_VENUES: ReadonlyArray<string> = [
 	"Golden Dragon 金龍饭店",
 ]
 
-//#endregion
+// #endregion
 
-//#region Fallback street pool
+// #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",
@@ -160,13 +138,12 @@ const FALLBACK_STREETS: ReadonlyArray<string> = [
 	"Forest Blvd",
 ]
 
-//#endregion
+// #endregion
 
-//#region House-number generator
+// #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.
+	// Each digit count from one to four is equally likely.
 	const digits = Math.floor(random() * 4) + 1
 	const max = Math.pow(10, digits)
 	const n = Math.floor(random() * max) + 1
@@ -174,34 +151,17 @@ function randomHouseNumber(random: () => number): string {
 	return String(n)
 }
 
-//#endregion
+// #endregion
 
-//#region Synthesis
+// #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.
- */
+// Repeated entries weight the sample toward the more common form.
 const COUNTRY_SURFACES: Readonly<Record<string, ReadonlyArray<string>>> = {
 	US: ["United States", "USA"],
 	GB: ["United Kingdom", "United Kingdom", "United Kingdom", "UK"],
@@ -211,6 +171,12 @@ const COUNTRY_SURFACES: Readonly<Record<string, ReadonlyArray<string>>> = {
 	DE: ["Germany", "Deutschland"],
 }
 
+/**
+ * Synthesizes one row with a house number, a street, a venue and the tuple's locality and postcode.
+ *
+ * GB rows sometimes use British venue names and ranged house numbers.
+ * FR and GB rows omit the region.
+ */
 export function synthesizeHouseVenueRow(
 	base: HouseVenueBaseTuple,
 	opts: HouseVenueSynthesisOpts = {}
@@ -219,37 +185,14 @@ export function synthesizeHouseVenueRow(
 	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)
+	const venue = gbOrder && random() < GB_VENUE_POOL_RATE ? sample(GB_VENUES, random) : sample(PLAIN_VENUES, random)
+	const street = base.street ?? sample(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
@@ -274,11 +217,10 @@ export function synthesizeHouseVenueRow(
 				? `${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)
+		const countrySurface = sample(countrySurfaces, random)
 		components.country = countrySurface
 		tail = `${tail}, ${countrySurface}`
 	}
@@ -298,11 +240,11 @@ export function synthesizeHouseVenueRow(
 }
 
 /**
- * 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.
+ * Reports whether the components include both `house_number` and `venue`,
+ * which every row from this synthesizer does.
  */
 export function hasHouseNumberAndVenue(components: CanonicalRow["components"]): boolean {
 	return components.house_number !== undefined && components.venue !== undefined
 }
 
-//#endregion
+// #endregion