@mailwoman/corpus 9.4.0 → 10.1.0

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" },

package/lib/synthesizers/no-street.ts

@@ -3,50 +3,25 @@
  * @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 { type ComponentDict, formatAddressRow } from "@mailwoman/codex/address/format"
+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 +53,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 +84,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 +120,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 +142,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 +158,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 +215,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 +228,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 +252,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 +275,4 @@ export function hasAnyStreetSideTag(components: CanonicalRow["components"]): boo
 	return false
 }
 
-//#endregion
+// #endregion