@mailwoman/corpus 9.2.0 → 9.4.0

package/lib/synthesizers/intersection.ts

@@ -0,0 +1,233 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   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
+ *   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).
+ *
+ *   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.
+ *
+ *   US-idiomatic only (the harness intersection cases are US: "X & Y, City, ST ZIP").
+ */
+
+import type { DirectionalAbbreviation } from "@mailwoman/codex/us"
+
+import { pick } from "#synthesizers/utils"
+import type { CanonicalRow } from "#types"
+
+/**
+ * Street name cores (no suffix) — proper-noun streets that often appear bare.
+ */
+
+/**
+ * Attempts to draw a second street distinct from the first before giving up on the pair.
+ */
+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. */
+
+const STREET_CORES = [
+	"Main",
+	"Oak",
+	"Elm",
+	"Maple",
+	"Pine",
+	"Cedar",
+	"Park",
+	"Lake",
+	"Hill",
+	"Washington",
+	"Lincoln",
+	"Jefferson",
+	"Madison",
+	"Franklin",
+	"Market",
+	"Broad",
+	"Church",
+	"Mill",
+	"Highland",
+	"Sunset",
+	"Union",
+	"Spring",
+] as const
+
+/**
+ * Bare proper-noun streets that idiomatically take NO suffix.
+ */
+const BARE_NAMES = ["Broadway", "Wall", "Bourbon", "Esplanade", "Riverside", "Lakeshore"] as const
+
+const ORDINALS = [
+	"1st",
+	"2nd",
+	"3rd",
+	"4th",
+	"5th",
+	"6th",
+	"7th",
+	"8th",
+	"9th",
+	"10th",
+	"42nd",
+	"23rd",
+	"34th",
+] as const
+
+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.
+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.
+ */
+const CONNECTORS = [" & ", " and ", " at ", " / ", " @ "] as const
+
+export interface IntersectionBaseTuple {
+	locality: string
+	region: string
+	/**
+	 * ZIP — optional; ~30% of synthetic intersections omit it (idiomatic).
+	 */
+	postcode?: string
+	country: string
+}
+
+export interface SynthesizedIntersectionRow {
+	raw: string
+	components: CanonicalRow["components"]
+	locale: string
+}
+
+export interface IntersectionSynthesisOpts {
+	random?: () => number
+}
+
+/**
+ * Build a single street surface form, e.g. "W 42nd St", "Broadway", "Main St", "N Oak Ave".
+ */
+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)
+
+	const parts: string[] = []
+
+	if (random() < 0.35) {
+		parts.push(pick(DIRECTIONALS, random))
+	}
+
+	parts.push(random() < 0.45 ? pick(ORDINALS, random) : pick(STREET_CORES, random))
+	parts.push(pick(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).
+ */
+export function synthesizeIntersectionRow(
+	base: IntersectionBaseTuple,
+	opts: IntersectionSynthesisOpts = {}
+): SynthesizedIntersectionRow | null {
+	const random = opts.random ?? Math.random
+
+	if (base.country !== "US") return null
+
+	const a = buildStreetName(random)
+	let b = buildStreetName(random)
+	// Ensure distinct surface forms (and not a substring of each other — alignment needs unambiguous spans).
+	let tries = 0
+
+	while ((b === a || a.includes(b) || b.includes(a)) && tries++ < MAX_DISTINCT_STREET_TRIES) {
+		b = buildStreetName(random)
+	}
+
+	if (b === a || a.includes(b) || b.includes(a)) return null
+
+	const connector = pick(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.
+	const bare = random() < 0.6
+	let raw: string
+
+	if (bare) {
+		raw = `${cornerPrefix}${a}${connector}${b}`
+	} else {
+		const includePostcode = base.postcode != null && random() < 0.7
+
+		const tail = includePostcode
+			? `, ${base.locality}, ${base.region} ${base.postcode}`
+			: `, ${base.locality}, ${base.region}`
+
+		raw = `${cornerPrefix}${a}${connector}${b}${tail}`
+		components.locality = base.locality
+		components.region = base.region
+
+		if (includePostcode) {
+			components.postcode = base.postcode
+		}
+	}
+
+	return { raw, components, locale: "en-US" }
+}
+
+/**
+ * A small built-in US city/region/zip pool for standalone slice generation + tests.
+ */
+export const DEFAULT_US_BASES: ReadonlyArray<IntersectionBaseTuple> = [
+	{ locality: "New York", region: "NY", postcode: "10036", country: "US" },
+	{ locality: "Chicago", region: "IL", postcode: "60613", country: "US" },
+	{ locality: "Los Angeles", region: "CA", postcode: "90012", country: "US" },
+	{ locality: "Seattle", region: "WA", postcode: "98109", country: "US" },
+	{ locality: "Austin", region: "TX", postcode: "78701", country: "US" },
+	{ locality: "Portland", region: "OR", postcode: "97205", country: "US" },
+	{ locality: "Denver", region: "CO", postcode: "80202", country: "US" },
+	{ locality: "Boston", region: "MA", postcode: "02116", country: "US" },
+	{ locality: "Miami", region: "FL", postcode: "33130", country: "US" },
+	{ locality: "Atlanta", region: "GA", postcode: "30303", country: "US" },
+]
+
+/**
+ * Generate `count` intersection rows over the provided bases (round-robin).
+ */
+export function generateIntersectionRows(
+	count: number,
+	bases: ReadonlyArray<IntersectionBaseTuple> = DEFAULT_US_BASES,
+	opts: IntersectionSynthesisOpts = {}
+): SynthesizedIntersectionRow[] {
+	const random = opts.random ?? Math.random
+	const out: SynthesizedIntersectionRow[] = []
+	let guard = 0
+
+	while (out.length < count && guard++ < count * 4) {
+		const base = bases[out.length % bases.length]!
+		const row = synthesizeIntersectionRow(base, { random })
+
+		if (row) {
+			out.push(row)
+		}
+	}
+
+	return out
+}

package/lib/synthesizers/no-street.ts

@@ -0,0 +1,327 @@
+/**
+ * @copyright Sister Software
+ * @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.
+ */
+
+import { countryToLocale, pick } from "#synthesizers/utils"
+import type { CanonicalRow } from "#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
+   would hide the distribution behind a wall of identifiers. Genuine thresholds in these files are
+   extracted as named constants above. */
+
+export interface NoStreetBaseTuple {
+	locality: string
+	region: string
+	postcode: string
+	country: string
+}
+
+export type NoStreetTemplate =
+	| "venue-plain"
+	| "venue-adversarial"
+	| "locality-region-postcode"
+	| "locality-region"
+	| "postcode-only"
+	| "country-only"
+
+export interface NoStreetSynthesisOpts {
+	random?: () => number
+	/**
+	 * Override the template selection entirely (used by tests for deterministic coverage).
+	 */
+	forceTemplate?: NoStreetTemplate
+}
+
+export interface SynthesizedNoStreetRow {
+	raw: string
+	components: CanonicalRow["components"]
+	locale: string
+	template: NoStreetTemplate
+}
+
+//#endregion
+
+//#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.
+ */
+const PLAIN_VENUES: ReadonlyArray<string> = [
+	"Bob's Pizza",
+	"Acme Corporation",
+	"Joe's Diner",
+	"Sunrise Bakery",
+	"Maple Leaf Cafe",
+	"Riverside Garden Center",
+	"Tech Solutions Inc",
+	"Pacific Industries",
+	"Atlantic Holdings",
+	"Stellar Consulting",
+	"Greenfield Partners",
+	"Mountain View Studio",
+	"The Daily Grind",
+	"Sunset Bistro",
+	"Harvest Moon Florist",
+	"Iron Forge Brewing",
+	"Crescent City Bookstore",
+	"Lighthouse Insurance Group",
+	"Pinecrest Veterinary",
+	"Westwood Realty",
+]
+
+/**
+ * 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.
+ *
+ * **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.
+ */
+const ADVERSARIAL_VENUES: ReadonlyArray<string> = [
+	"Wall Street Industries",
+	"Highway 61 Diner",
+	"Lane Bryant",
+	"Park Avenue Dental",
+	"Broadway Theatre Company",
+	"Madison Square Garden",
+	"Main Street Bakery",
+	"Sunset Boulevard Studios",
+	"Ocean Drive Cafe",
+	"Mountain Road Outfitters",
+	"Hollywood Boulevard Salon",
+	"East Bay Auto",
+	"West End Pharmacy",
+	"North Shore Insurance",
+	"South Park Children's Center",
+	"River Road Animal Hospital",
+	"Hill Street Blues Bar",
+	"Court House Square Realty",
+	"Plaza Hotel",
+	"Lincoln Park Zoo",
+	"Central Park Conservancy",
+	"Lakeshore Boulevard Apartments",
+	"Memorial Drive Medical Center",
+	"Wabash Avenue Press",
+	"State Street Bank",
+	"Market Street Grill",
+	"Beach Boulevard Diner",
+	"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.
+for (const v of ADVERSARIAL_VENUES) {
+	if (/^\d+(st|nd|rd|th)\b/i.test(v)) {
+		throw new Error(
+			`ADVERSARIAL_VENUES entry "${v}" starts with digit+ordinal; this pattern confuses ` +
+				`house_number recognition (see v0.6.3 eval doc). Use a non-numeric venue name.`
+		)
+	}
+}
+
+const COUNTRY_NAMES = new Map<string, ReadonlyArray<string>>([
+	["US", ["United States", "USA", "U.S.A.", "United States of America"]],
+	["FR", ["France"]],
+	["DE", ["Germany", "Deutschland"]],
+	["GB", ["United Kingdom", "UK", "Great Britain"]],
+	["CA", ["Canada"]],
+	["AU", ["Australia"]],
+])
+
+//#endregion
+
+//#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.
+ */
+export function synthesizeNoStreetRow(
+	base: NoStreetBaseTuple,
+	opts: NoStreetSynthesisOpts = {}
+): SynthesizedNoStreetRow | null {
+	const random = opts.random ?? Math.random
+	const locale = countryToLocale(base.country)
+
+	const template: NoStreetTemplate = opts.forceTemplate ?? pickTemplate(random)
+
+	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,
+			}
+		}
+		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,
+			}
+		}
+		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,
+			}
+		}
+		case "locality-region": {
+			const raw = `${base.locality}, ${base.region}`
+
+			return {
+				raw,
+				components: {
+					locality: base.locality,
+					region: base.region,
+				},
+				locale,
+				template,
+			}
+		}
+		case "postcode-only": {
+			return {
+				raw: base.postcode,
+				components: { postcode: base.postcode },
+				locale,
+				template,
+			}
+		}
+		case "country-only": {
+			const names = COUNTRY_NAMES.get(base.country) ?? [base.country]
+			const country = pick(names, random)
+
+			return {
+				raw: country,
+				components: { country },
+				locale,
+				template,
+			}
+		}
+	}
+}
+
+/**
+ * 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.
+ */
+function pickTemplate(random: () => number): NoStreetTemplate {
+	const r = random()
+
+	if (r < 0.35) return "venue-adversarial"
+
+	// 35% — the critical slice
+	if (r < 0.6) return "venue-plain"
+
+	// 25%
+	if (r < 0.8) return "locality-region-postcode"
+
+	// 20%
+	if (r < 0.92) return "locality-region"
+
+	// 12%
+	if (r < 0.98) return "postcode-only"
+
+	// 6%
+	return "country-only" // 2%
+}
+
+/**
+ * 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.
+ */
+export const STREET_SIDE_TAGS = [
+	"street",
+	"street_prefix",
+	"street_prefix_particle",
+	"street_suffix",
+	"house_number",
+	"intersection_a",
+	"intersection_b",
+	"unit",
+] as const
+
+export function hasAnyStreetSideTag(components: CanonicalRow["components"]): boolean {
+	for (const t of STREET_SIDE_TAGS) {
+		if (components[t]) return true
+	}
+
+	return false
+}
+
+//#endregion