@mailwoman/corpus 10.0.0 → 10.1.0

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

package/lib/synthesizers/intersection.ts

@@ -6,22 +6,26 @@
  *   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
+ *   with ~0.0001 probability on canonical intersections ("Broadway & W 42nd St"). It never learned
+ *   the tags because the corpus has no intersection training signal. The corpus has no generator.
+ *   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 slice (synthesis-as-supplement discipline: weight < 0.25, one-and-done).
+ *   supplement source (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.
+ *   must occur verbatim in `raw` so alignment lands.
  *
  *   US-idiomatic only (the harness intersection cases are US: "X & Y, City, ST ZIP").
  */
 
+/* oxlint-disable mailwoman/prefer-home -- the admin tails below are written as US templates because this synthesizer
+   refuses a non-US tuple outright (`if (base.country !== "US") return null`). A layout call would answer the same
+   string for the only country that reaches it. The function would read as though the file served more. */
+
 import type { DirectionalAbbreviation } from "@mailwoman/codex/us"
+import { sample } from "@mailwoman/core/random"
 
-import { pick } from "#synthesizers/utils"
 import type { CanonicalRow } from "#types"
 
 /**
@@ -34,10 +38,10 @@ import type { CanonicalRow } from "#types"
 const MAX_DISTINCT_STREET_TRIES = 8
 
 /* 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. */
 
 const STREET_CORES = [
 	"Main",
@@ -65,7 +69,7 @@ const STREET_CORES = [
 ] as const
 
 /**
- * Bare proper-noun streets that idiomatically take NO suffix.
+ * Bare proper-noun streets that idiomatically take no suffix.
  */
 const BARE_NAMES = ["Broadway", "Wall", "Bourbon", "Esplanade", "Riverside", "Lakeshore"] as const
 
@@ -87,13 +91,17 @@ const ORDINALS = [
 
 const SUFFIXES = ["St", "Ave", "Blvd", "Rd", "Dr", "Ln", "Way", "Pl", "Ct", "Pkwy", "Ter", "Cir"] 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.
+// 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 sample() draw and change shipped recipe-output bytes.
 const DIRECTIONALS = ["N", "S", "E", "W", "NE", "NW", "SE", "SW"] as const satisfies readonly DirectionalAbbreviation[]
 
 /**
- * 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.
+ * 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
 
@@ -122,23 +130,25 @@ export interface IntersectionSynthesisOpts {
  */
 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)
+	if (random() < 0.2) return sample(BARE_NAMES, random)
 
 	const parts: string[] = []
 
 	if (random() < 0.35) {
-		parts.push(pick(DIRECTIONALS, random))
+		parts.push(sample(DIRECTIONALS, random))
 	}
 
-	parts.push(random() < 0.45 ? pick(ORDINALS, random) : pick(STREET_CORES, random))
-	parts.push(pick(SUFFIXES, random))
+	parts.push(random() < 0.45 ? sample(ORDINALS, random) : sample(STREET_CORES, random))
+	parts.push(sample(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).
+ * 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,
@@ -159,15 +169,16 @@ export function synthesizeIntersectionRow(
 
 	if (b === a || a.includes(b) || b.includes(a)) return null
 
-	const connector = pick(CONNECTORS, random)
+	const connector = sample(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.
+	// 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
 
@@ -193,7 +204,7 @@ export function synthesizeIntersectionRow(
 }
 
 /**
- * A small built-in US city/region/zip pool for standalone slice generation + tests.
+ * A small built-in US city/region/zip pool for standalone recipe-output generation + tests.
  */
 export const DEFAULT_US_BASES: ReadonlyArray<IntersectionBaseTuple> = [
 	{ locality: "New York", region: "NY", postcode: "10036", country: "US" },