@mailwoman/corpus 10.0.0 → 10.2.0

package/lib/synthesizers/house-venue.ts

@@ -3,34 +3,19 @@
  * @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"
+import { sample } from "@mailwoman/core/random"
+
+import { layoutAdminTail } from "#synthesizers/tail"
+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 +25,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 +48,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 +59,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 +83,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 +115,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 +137,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 +150,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 +170,13 @@ 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 admin tail,
+ * rendered through the country's codex layout.
+ * A country with no layout yields `null`.
+ *
+ * GB rows sometimes use British venue names and ranged house numbers.
+ */
 export function synthesizeHouseVenueRow(
 	base: HouseVenueBaseTuple,
 	opts: HouseVenueSynthesisOpts = {}
@@ -219,78 +185,50 @@ 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)
+	// country-branch: the British venue pool and the ranged house number are GB English data.
+	// A per-country venue pool from the Overture names file would replace the branch.
+	const gbPools = base.country === "GB"
+
+	const venue = gbPools && 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)) {
+	if (gbPools && 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,
+	const countrySurfaces = COUNTRY_SURFACES[base.country]
+	const countrySurface = countrySurfaces && random() < COUNTRY_APPEND_RATE ? sample(countrySurfaces, random) : undefined
+
+	// The layout decides the tail's order and which parts it prints: FR prints no region,
+	// VE keeps the region after the postcode, GB puts the postcode after the locality.
+	const tail = layoutAdminTail(base.country, {
 		locality: base.locality,
-		...(frOrder || gbOrder ? {} : { region: base.region }),
+		region: base.region,
 		postcode: base.postcode,
-	}
+		country: countrySurface,
+	})
 
-	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}`
+	if (!tail) return null
 
-	// 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}`
+	const components: CanonicalRow["components"] = {
+		house_number: houseNumber,
+		street,
+		venue,
+		...tail.components,
 	}
 
 	let raw: string
 
 	switch (template) {
 		case "venue-after-street":
-			raw = `${houseNumber} ${street}, ${venue}, ${tail}`
+			raw = `${houseNumber} ${street}, ${venue}, ${tail.raw}`
 			break
 		case "venue-before-street":
-			raw = `${venue}, ${houseNumber} ${street}, ${tail}`
+			raw = `${venue}, ${houseNumber} ${street}, ${tail.raw}`
 			break
 	}
 
@@ -298,11 +236,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

package/lib/synthesizers/no-street.ts

@@ -3,50 +3,26 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   No-street address synthesizer — the counter-distribution that v0.6.1's synth-street slice is
- *   missing. Generates BIO-labelable rows where there is NO street, NO house_number, NO
- *   street_prefix, NO street_suffix, NO intersection — only some subset of {venue, locality,
- *   region, postcode, country}.
- *
- *   Rationale: the [2026-05-28 night-2
- *   postmortem](../../docs/articles/evals/night-shifts/2026-05-28-night-2-postmortem.md) and the [layer-1
- *   eval](../../docs/articles/evals/experiments/2026-05-28-layer-1-morphology-fst.md) showed that synth-street
- *   pushed the model into a high-confidence "decompose mode" that leaked into `dependent_locality`.
- *   Per DeepSeek's turn-2 recipe, the model needs explicit counter-examples: addresses where the
- *   model should NOT emit street labels. This synthesizer is that source.
- *
- *   Six row templates, each producing a {raw, components} pair with no street-side tags:
- *
- *   1. **Plain venue + locality + region + postcode** `"Bob's Pizza, Boston, MA 02101"`
- *   2. **Adversarial venue (containing street-typing words)** `"Wall Street Industries, NY 10005"`,
- *        `"5th Avenue Theater, Seattle, WA"`, `"Highway 61 Diner, Memphis TN"`. These are the rows
- *        that v0.6.1's decompose-mode would mis-tag as street_prefix/suffix; explicit negative
- *        training kills that signal.
- *   3. **Locality + region + postcode (minimal)** — `"Boston, MA 02101"`
- *   4. **Locality + region** — `"Boston, MA"`
- *   5. **Postcode-only** — `"02101"`
- *   6. **Country-only** — `"United States"`, `"France"` (rare in real data, but the model has seen these
- *        and should not hallucinate streets on them).
- *
- *   Output is a `CanonicalRow` with no street-side components. Alignment will produce BIO labels
- *   where every token is one of {`B-venue`, `I-venue`, `B-locality`, `I-locality`, `B-region`,
- *   `B-postcode`, `B-country`, `I-country`, `O`} — explicitly never any street tag. That IS the
- *   counter-example signal the model is missing.
- *
- *   This complements (does not replace) the existing US-base-tuple source used by
- *   `po-box.ts`; the same `NoStreetBaseTuple` shape is consumed.
+ *   Generate addresses without street components as counterexamples for street-heavy training data.
+ *   Templates cover venues, localities, postcodes or countries. Some venue names contain
+ *   street-like words. Output components never include street-side tags.
  */
 
-import { countryToLocale, pick } from "#synthesizers/utils"
+import { formatAddressRow } from "@mailwoman/codex/address/format"
+import type { ComponentDict } from "@mailwoman/codex/address/render"
+import { countryCodeForTable } from "@mailwoman/codex/country"
+import { sample } from "@mailwoman/core/random"
+
+import { countryToLocale } from "#synthesizers/utils"
 import type { CanonicalRow } from "#types"
 
-//#region Types
+// #region 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
+    cutoffs rather than thresholds: `const r = random()` followed by a cascade of `r < 0.4` branches defines the
+   output distribution. The cascade shows each weight from top to bottom. A separate constant for each cutoff
    would hide the distribution behind a wall of identifiers. Genuine thresholds in these files are
-   extracted as named constants above. */
+    extracted as constants above. */
 
 export interface NoStreetBaseTuple {
 	locality: string
@@ -78,13 +54,12 @@ export interface SynthesizedNoStreetRow {
 	template: NoStreetTemplate
 }
 
-//#endregion
+// #endregion
 
-//#region Venue name pools
+// #region Venue name pools
 
 /**
- * Plain venue names — businesses without street-typing words in the name. Used as the easy-mode positive class for
- * venue detection.
+ * Venue names without street-like words.
  */
 const PLAIN_VENUES: ReadonlyArray<string> = [
 	"Bob's Pizza",
@@ -110,15 +85,10 @@ const PLAIN_VENUES: ReadonlyArray<string> = [
 ]
 
 /**
- * Adversarial venue names — businesses whose names contain street-typing tokens (Avenue, Street, Highway, Lane, Drive,
- * Court, Plaza, Park, ...) but are themselves venues, not streets. The model must learn that these are venues despite
- * the street-typing tokens.
+ * Venue names containing street-like words.
  *
- * **No leading digit+ordinal venues** (e.g. "5th Avenue Theatre", "7th Street Bistro"). The v0.6.2 2026-05-29 step-20K
- * eval showed that synthesized rows starting with `<digits><ordinal>` confused the model about house_number recognition
- * — tokens like "5th" (which should be `B-house_number` in real addresses) were being labeled `B-venue` because
- * adversarial venues placed them in venue position. v0.6.3 omits these patterns; the `synth-house-venue` slice
- * separately teaches that house_number and venue coexist.
+ * Avoid leading digit-plus-ordinal forms because they can confuse house-number labels.
+ * `invented-house-venue` covers house-number and venue co-occurrence.
  */
 const ADVERSARIAL_VENUES: ReadonlyArray<string> = [
 	"Wall Street Industries",
@@ -151,9 +121,10 @@ const ADVERSARIAL_VENUES: ReadonlyArray<string> = [
 	"Garden Lane Florist",
 ]
 
-// Compile-time guard: every venue must NOT start with the digit+ordinal pattern that
-// confuses house_number recognition. If a future contributor adds a "5th Avenue Theatre"-
-// style entry, this assertion will fire at module load time.
+// Compile-time guard: every venue must not start with the digit+ordinal pattern
+// that confuses house_number recognition.
+// If a future contributor adds a "5th Avenue Theatre"- style entry,
+// this assertion will fire at module load time.
 for (const v of ADVERSARIAL_VENUES) {
 	if (/^\d+(st|nd|rd|th)\b/i.test(v)) {
 		throw new Error(
@@ -172,14 +143,12 @@ const COUNTRY_NAMES = new Map<string, ReadonlyArray<string>>([
 	["AU", ["Australia"]],
 ])
 
-//#endregion
+// #endregion
 
-//#region Synthesis
+// #region Synthesis
 
 /**
- * Generate one no-street counter-example row for a base (locality, region, postcode, country) tuple. Picks a template
- * by weighted random; the venue templates are the critical counter-distribution against synth-street's decompose-mode
- * pressure.
+ * Generate one no-street row from a base tuple with locality, region, postcode or country.
  */
 export function synthesizeNoStreetRow(
 	base: NoStreetBaseTuple,
@@ -190,69 +159,52 @@ export function synthesizeNoStreetRow(
 
 	const template: NoStreetTemplate = opts.forceTemplate ?? pickTemplate(random)
 
+	// Address layouts are keyed by ISO alpha-2 codes.
+	const iso2 = countryCodeForTable(base.country)
+
+	if (!iso2) return null
+
+	/**
+	 * Render components with the country's address layout and return only fields present in the output.
+	 */
+	const render = (
+		extra: ComponentDict,
+		carry: { locality?: boolean; region?: boolean; postcode?: boolean }
+	): SynthesizedNoStreetRow | null => {
+		const dict: ComponentDict = { ...extra }
+
+		if (carry.locality && base.locality) {
+			dict.locality = base.locality
+		}
+
+		if (carry.region && base.region?.trim()) {
+			dict.region = base.region
+		}
+
+		if (carry.postcode && base.postcode) {
+			dict.postcode = base.postcode
+		}
+
+		const rendered = formatAddressRow(dict, iso2, { singleLine: true })
+
+		if (!rendered) return null
+
+		return { raw: rendered.raw, components: rendered.components, locale, template }
+	}
+
 	switch (template) {
 		case "venue-plain": {
-			const venue = pick(PLAIN_VENUES, random)
-			const raw = `${venue}, ${base.locality}, ${base.region} ${base.postcode}`
-
-			return {
-				raw,
-				components: {
-					venue,
-					locality: base.locality,
-					region: base.region,
-					postcode: base.postcode,
-				},
-				locale,
-				template,
-			}
+			return render({ venue: sample(PLAIN_VENUES, random) }, { locality: true, region: true, postcode: true })
 		}
 		case "venue-adversarial": {
-			// The venue-adversarial template name is descriptive — when selected, this branch
-			// always draws from the adversarial pool. The `adversarialVenueRatio` opt is what
-			// the OUTER template picker uses to bias toward this template versus the plain one;
-			// once we're inside this branch the choice is already made.
-			const venue = pick(ADVERSARIAL_VENUES, random)
-			const raw = `${venue}, ${base.locality}, ${base.region} ${base.postcode}`
-
-			return {
-				raw,
-				components: {
-					venue,
-					locality: base.locality,
-					region: base.region,
-					postcode: base.postcode,
-				},
-				locale,
-				template,
-			}
+			// The template picker already selected the adversarial venue form.
+			return render({ venue: sample(ADVERSARIAL_VENUES, random) }, { locality: true, region: true, postcode: true })
 		}
 		case "locality-region-postcode": {
-			const raw = `${base.locality}, ${base.region} ${base.postcode}`
-
-			return {
-				raw,
-				components: {
-					locality: base.locality,
-					region: base.region,
-					postcode: base.postcode,
-				},
-				locale,
-				template,
-			}
+			return render({}, { locality: true, region: true, postcode: true })
 		}
 		case "locality-region": {
-			const raw = `${base.locality}, ${base.region}`
-
-			return {
-				raw,
-				components: {
-					locality: base.locality,
-					region: base.region,
-				},
-				locale,
-				template,
-			}
+			return render({}, { locality: true, region: true })
 		}
 		case "postcode-only": {
 			return {
@@ -264,7 +216,7 @@ export function synthesizeNoStreetRow(
 		}
 		case "country-only": {
 			const names = COUNTRY_NAMES.get(base.country) ?? [base.country]
-			const country = pick(names, random)
+			const country = sample(names, random)
 
 			return {
 				raw: country,
@@ -277,15 +229,14 @@ export function synthesizeNoStreetRow(
 }
 
 /**
- * Template weights chosen so that the venue-* templates dominate (they're the counter-example shape that matters), with
- * the minimal templates as long-tail noise.
+ * Select a template, favoring venue examples over minimal address forms.
  */
 function pickTemplate(random: () => number): NoStreetTemplate {
 	const r = random()
 
 	if (r < 0.35) return "venue-adversarial"
 
-	// 35% — the critical slice
+	// 35% — the critical pattern
 	if (r < 0.6) return "venue-plain"
 
 	// 25%
@@ -302,8 +253,9 @@ function pickTemplate(random: () => number): NoStreetTemplate {
 }
 
 /**
- * Convenience: assert at type-level that a synthesized row carries no street-side components. Used by tests +
- * downstream consumers who want to verify the contract at runtime.
+ * Convenience: assert at type-level that a synthesized row has no street-side components.
+ *
+ * Used by tests + downstream consumers who want to check the interface behavior at runtime.
  */
 export const STREET_SIDE_TAGS = [
 	"street",
@@ -324,4 +276,4 @@ export function hasAnyStreetSideTag(components: CanonicalRow["components"]): boo
 	return false
 }
 
-//#endregion
+// #endregion