@mailwoman/corpus 10.0.0 → 10.2.0

package/lib/synthesizers/utils.ts

@@ -3,56 +3,35 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Synthesis / augmentation per Phase 1 task #6.
- *
- *   An `Augmentation` is a pure function that takes a `CanonicalRow` and either returns a new
- *   `CanonicalRow` (with `raw` AND `components` transformed in lockstep so alignment still
- *   succeeds) or `null` when the augmentation doesn't apply to the row's shape.
- *
- *   Synthesis runs **before** alignment: augmentations transform raw + components together, and the
- *   runner reruns alignment on each augmented row to produce its labels. This keeps the synthesis
- *   surface small (no token/label arithmetic) at the cost of a re-run.
- *
- *   Every augmented row carries the `synth` marker:
- *
- *   - `method`: the augmentation's stable id (e.g. `"case-upper"`, `"accent-strip"`).
- *   - `base_source_id`: the source_id of the un-augmented (or upstream-augmented) row, so ancestry is
- *       traceable.
- *
- *   Phase 1 implements the locale-agnostic + most useful US/FR augmentations. Typo injection (#530)
- *   is now implemented ({@link typoInject}) — the "seed-aware API" the deferral asked for is
- *   resolved by seeding the PRNG from each row's `source_id`. It ships in {@link AUGMENTATIONS} but
- *   is kept OUT of the default set ({@link defaultAugmentationsForCountry}) until its on-model
- *   effect is measured; see the note there.
+ * Synthesis and augmentation utilities.
  */
 
 import type { BIOLabel, ComponentTag } from "@mailwoman/codex/component"
 import {
 	US_STREET_SUFFIX_PREFERRED_ABBR,
 	US_UNIT_DESIGNATOR_PREFERRED_ABBR,
-	matchCase,
 	matchLeadingDesignator,
 	matchTrailingSuffix,
 } from "@mailwoman/codex/us"
 import { isPresent } from "@mailwoman/core/objects"
-import { mulberry32 } from "@mailwoman/core/random"
+import { mulberry32, sample } from "@mailwoman/core/random"
 import { escapeRegExp } from "@mailwoman/core/strings/regexp"
 import { stripCombiningMarks } from "@mailwoman/normalize/fold"
+import { matchCase } from "spliterator"
 
 import type { CanonicalRow, LabeledRow, QuarantinedRow } from "#types"
 import { alignRow, assertSpanInvariants, type ComponentSpan } from "#utils/align"
 import { whitespaceTokenizer, type Tokenizer } from "#utils/tokenize"
 
 /**
- * An augmentation transforms a single row. Return `null` if the augmentation doesn't apply (e.g. accent-strip on a row
- * that has no accents; particle-strip on a US row).
+ * A row augmentation.
  */
 export type Augmentation = (row: CanonicalRow) => CanonicalRow | null
 
 type ComponentDict = Partial<Record<ComponentTag, string>>
 
 /**
- * Helper: build the augmented row with synth marker + chained source_id.
+ * Build an augmented row with its `RecipeMarker`.
  */
 function withAugmentation(
 	source: CanonicalRow,
@@ -60,23 +39,21 @@ function withAugmentation(
 	newRaw: string,
 	newComponents: ComponentDict
 ): CanonicalRow {
-	const baseID = source.synth?.base_source_id ?? source.source_id
+	const baseID = source.recipe?.base_source_id ?? source.source_id
 
 	return {
 		...source,
 		raw: newRaw,
 		components: newComponents,
 		source_id: `${source.source_id}+${method}`,
-		synth: { method, base_source_id: baseID },
+		recipe: { recipe: method, base_source_id: baseID },
 	}
 }
 
-// ===========================================================================
-// Locale-agnostic augmentations
-// ===========================================================================
+// Locale-agnostic augmentations.
 
 /**
- * Upper-case raw + every component value. Returns null if already all-upper.
+ * Upper-case raw and components.
  */
 export const caseUpper: Augmentation = (row) => {
 	if (row.raw === row.raw.toUpperCase()) return null
@@ -93,7 +70,7 @@ export const caseUpper: Augmentation = (row) => {
 }
 
 /**
- * Lower-case raw + every component value. Returns null if already all-lower.
+ * Lower-case raw and components.
  */
 export const caseLower: Augmentation = (row) => {
 	if (row.raw === row.raw.toLowerCase()) return null
@@ -110,7 +87,7 @@ export const caseLower: Augmentation = (row) => {
 }
 
 /**
- * Drop commas from `raw`. Components unchanged (they didn't carry commas).
+ * Drop commas from raw.
  */
 export const dropCommas: Augmentation = (row) => {
 	if (!row.raw.includes(",")) return null
@@ -120,10 +97,7 @@ export const dropCommas: Augmentation = (row) => {
 }
 
 /**
- * Replace single spaces with double spaces in `raw` AND in every component value. The component update is essential for
- * alignment: `alignRow` substring-searches each component's surface form inside `raw`, so doubling the spaces in `raw`
- * only would leave single-spaced components unfindable (this was the bug behind v0.1.1's first build attempt — 99.9% of
- * quarantined rows traced back to this augmentation). Doubling both keeps the substring contract intact.
+ * Double spaces in raw and components.
  */
 export const doubleSpace: Augmentation = (row) => {
 	if (!/ /.test(row.raw)) return null
@@ -140,8 +114,7 @@ export const doubleSpace: Augmentation = (row) => {
 }
 
 /**
- * Strip Unicode combining marks (accents, diacritics) from raw + components. "Hôtel" → "Hotel"; "Île-de-France" →
- * "Ile-de-France". Returns null if the row has no accents.
+ * Strip accents/diacritics from raw and components.
  */
 export const accentStrip: Augmentation = (row) => {
 	const stripped = stripCombiningMarks(row.raw)
@@ -158,13 +131,10 @@ export const accentStrip: Augmentation = (row) => {
 	return withAugmentation(row, "accent-strip", stripped, newComponents)
 }
 
-// The typo-injection helpers below keep generated rows reproducible.
-// The Phase-1 deferral asked for a "seed-aware API" so the corpus stays reproducible. Resolution:
-// seed the PRNG from the row's own `source_id` — deterministic per row, no global state, fits the
-// existing `(row) => CanonicalRow | null` signature unchanged.
+// Typo helpers are deterministic per row.
 
 /**
- * QWERTY adjacency for realistic single-key substitutions (lowercase; case is restored on apply).
+ * QWERTY adjacency for key-neighbor substitutions.
  */
 const QWERTY_ADJACENCY: Record<string, string> = {
 	a: "qwsz",
@@ -196,12 +166,12 @@ const QWERTY_ADJACENCY: Record<string, string> = {
 }
 
 /**
- * A component value eligible for a typo: a pure-letter name of ≥4 chars (excludes numbers/postcodes/units).
+ * Eligible typo target: letter-like name with length >= 4.
  */
 const ALPHA_NAME = /^[\p{L}][\p{L} '.-]{3,}$/u
 
 /**
- * Djb2 → uint32 seed. Deterministic; no `Math.random` (banned here and breaks corpus reproducibility).
+ * Deterministic djb2 hash to uint32.
  */
 function hashString(s: string): number {
 	let h = 5381
@@ -214,19 +184,12 @@ function hashString(s: string): number {
 }
 
 /**
- * Inject ONE realistic typo — an adjacent-QWERTY-key substitution OR an adjacent-character transposition — into a
- * single alpha name component (street/locality/region…), teaching the model to recover from real-world misspellings
- * ("Cupertino" → "Cupertimo"). The edit is applied to BOTH `raw` and the component so the substring contract `alignRow`
- * depends on holds. Number / postcode / unit components are never touched (they fail {@link ALPHA_NAME}). Deterministic
- * per row (seeded from `source_id`). Returns `null` when no eligible component exists or the edit is a no-op.
+ * Inject one deterministic typo into an eligible component.
  */
 export const typoInject: Augmentation = (row) => {
 	const rng = mulberry32(hashString(`${row.source_id}:typo`))
 
-	// Count occurrences so we only edit an UNAMBIGUOUS target — a value that appears exactly once in
-	// raw and isn't a substring of another component. (e.g. "Cupertino" the locality is a substring of
-	// "Cupertino Avenue" the street; editing it would `replace` the street's occurrence and break the
-	// span. The substring contract `alignRow` enforces is why we filter rather than guess the position.)
+	// Only edit an unambiguous component value.
 	const occurs = (needle: string): number => {
 		let n = 0
 
@@ -244,8 +207,8 @@ export const typoInject: Augmentation = (row) => {
 	)
 
 	if (!eligible.length) return null
-	const [tag, value] = pick(eligible, rng)
-	// Interior alpha positions only — keep the first char (most real typos are interior) + a right neighbour.
+	const [tag, value] = sample(eligible, rng)
+	// Interior letter positions only.
 	const positions: number[] = []
 
 	for (let i = 1; i < value.length - 1; i++)
@@ -254,14 +217,14 @@ export const typoInject: Augmentation = (row) => {
 		}
 
 	if (!positions.length) return null
-	const i = pick(positions, rng)
+	const i = sample(positions, rng)
 	const ch = value[i]!
 	let typed: string
 
 	if (rng() < 0.5) {
 		const next = value[i + 1]!
 
-		if (ch === next) return null // transposing equal chars is a no-op
+		if (ch === next) return null
 		typed = value.slice(0, i) + next + ch + value.slice(i + 2)
 	} else {
 		const lower = ch.toLowerCase()
@@ -275,16 +238,14 @@ export const typoInject: Augmentation = (row) => {
 	if (typed === value) return null
 	const newRaw = row.raw.replace(value, typed)
 
-	// first occurrence; `replace(string, …)` is literal, not regex
+	// `replace(string, …)` updates the first literal match.
 	return withAugmentation(row, "typo-inject", newRaw, { ...row.components, [tag]: typed })
 }
 
-// ===========================================================================
-// US-specific augmentations
-// ===========================================================================
+// US-specific augmentations.
 
 /**
- * US state full ↔ alpha-2 mapping. Two-way: `STATE_TO_ABBR["Oregon"] = "OR"`.
+ * US state full name -> alpha-2.
  */
 const STATE_NAME_TO_ABBR: Record<string, string> = {
 	Alabama: "AL",
@@ -345,9 +306,13 @@ const STATE_ABBR_TO_NAME: Record<string, string> = Object.fromEntries(
 )
 
 /**
- * US: substitute the full state name for its alpha-2 abbreviation.
+ * Expand state abbreviation to full name.
  */
 export const stateExpand: Augmentation = (row) => {
+	// country-branch: the state, directional, street-suffix, unit and ZIP+4
+	// augmentations below read US vocabulary tables.
+	// Per-country abbreviation tables in the codex would let
+	// `defaultAugmentationsForCountry` serve every country.
 	if (row.country !== "US") return null
 	const region = row.components.region
 
@@ -355,8 +320,7 @@ export const stateExpand: Augmentation = (row) => {
 	const full = STATE_ABBR_TO_NAME[region]
 
 	if (!full) return null
-	// Replace the bounded "OR" surface form with "Oregon" in raw. Use word boundaries so we
-	// don't match inside "Stop" or similar.
+	// Replace exact word matches only.
 	const re = new RegExp(`\\b${region}\\b`, "g")
 
 	if (!re.test(row.raw)) return null
@@ -367,9 +331,10 @@ export const stateExpand: Augmentation = (row) => {
 }
 
 /**
- * US: substitute the alpha-2 abbreviation for the full state name.
+ * Abbreviate full state name to alpha-2.
  */
 export const stateAbbreviate: Augmentation = (row) => {
+	// country-branch: see `stateExpand`.
 	if (row.country !== "US") return null
 	const region = row.components.region
 
@@ -402,9 +367,10 @@ const DIRECTIONAL_ABBR_TO_FULL: Record<string, string> = Object.fromEntries(
 )
 
 /**
- * US: expand directional abbreviations in `street`/`street_suffix` (NW → Northwest).
+ * Expand directional abbreviations.
  */
 export const directionalExpand: Augmentation = (row) => {
+	// country-branch: see `stateExpand`.
 	if (row.country !== "US") return null
 	const tagsToCheck: ComponentTag[] = ["street", "street_suffix", "street_prefix"]
 	let changed = false
@@ -430,9 +396,10 @@ export const directionalExpand: Augmentation = (row) => {
 }
 
 /**
- * US: abbreviate directional words (Northwest → NW).
+ * Abbreviate directional words.
  */
 export const directionalAbbreviate: Augmentation = (row) => {
+	// country-branch: see `stateExpand`.
 	if (row.country !== "US") return null
 	const tagsToCheck: ComponentTag[] = ["street", "street_suffix", "street_prefix"]
 	let changed = false
@@ -462,15 +429,10 @@ export const directionalAbbreviate: Augmentation = (row) => {
 }
 
 /**
- * US: swap the trailing street-suffix word in `components.street` to its preferred USPS abbreviation, preserving case.
- * `"5th Avenue"` → `"5th Ave"`; `"5TH AVENUE"` → `"5TH AVE"`; `"main street"` → `"main st"`. Returns null when no
- * trailing suffix is recognized, when the trailing word is already the preferred abbreviation, or when the swap would
- * leave `raw` un- touched (alignment requires both raw and components to move in lockstep).
- *
- * Targets the trailing word only to avoid mangling streets like "Avenue of the Americas" where the suffix-shaped word
- * is part of the proper name rather than a USPS suffix.
+ * Abbreviate trailing US street suffix.
  */
 export const streetSuffixAbbreviate: Augmentation = (row) => {
+	// country-branch: see `stateExpand`.
 	if (row.country !== "US") return null
 	const street = row.components.street
 
@@ -497,14 +459,10 @@ export const streetSuffixAbbreviate: Augmentation = (row) => {
 }
 
 /**
- * US: swap the trailing street-suffix word in `components.street` to its full canonical form, preserving case. `"5th
- * Ave"` → `"5th Avenue"`; `"5TH AVE"` → `"5TH AVENUE"`; `"main st"` → `"main street"`. Returns null when no trailing
- * suffix is recognized, when the trailing word is already the canonical full form, or when the swap would leave `raw`
- * untouched.
- *
- * Same trailing-word-only rule as `streetSuffixAbbreviate`.
+ * Expand trailing US street suffix.
  */
 export const streetSuffixExpand: Augmentation = (row) => {
+	// country-branch: see `stateExpand`.
 	if (row.country !== "US") return null
 	const street = row.components.street
 
@@ -530,15 +488,10 @@ export const streetSuffixExpand: Augmentation = (row) => {
 }
 
 /**
- * US: swap the LEADING secondary-unit designator in `components.unit` to its approved USPS abbreviation, preserving
- * case + the identifier. `"Apartment 4B"` → `"Apt 4B"`; `"SUITE 200"` → `"STE 200"`; `"floor 3"` → `"fl 3"`. Returns
- * null when the unit has no recognized leading designator (a bare `"4B"` / `"#210"`), the designator is already the
- * approved abbreviation, or the swap would leave `raw` untouched.
- *
- * Mirrors `streetSuffixAbbreviate`, but designators LEAD the unit (vs suffixes that trail the street). Sourced from the
- * USPS Pub-28 C2 codex — the data-generation counterpart to the runtime `UnitDesignatorClassifier`.
+ * Abbreviate leading US unit designator.
  */
 export const unitDesignatorAbbreviate: Augmentation = (row) => {
+	// country-branch: see `stateExpand`.
 	if (row.country !== "US") return null
 	const unit = row.components.unit
 
@@ -565,12 +518,10 @@ export const unitDesignatorAbbreviate: Augmentation = (row) => {
 }
 
 /**
- * US: swap the LEADING secondary-unit designator in `components.unit` to its full canonical form, preserving case + the
- * identifier. `"Apt 4B"` → `"Apartment 4B"`; `"STE 200"` → `"SUITE 200"`. Returns null when there's no recognized
- * leading designator, it's already the canonical word, or the swap would leave `raw` untouched. Same leading-word-only
- * rule as `unitDesignatorAbbreviate`.
+ * Expand leading US unit designator.
  */
 export const unitDesignatorExpand: Augmentation = (row) => {
+	// country-branch: see `stateExpand`.
 	if (row.country !== "US") return null
 	const unit = row.components.unit
 
@@ -596,9 +547,10 @@ export const unitDesignatorExpand: Augmentation = (row) => {
 }
 
 /**
- * US: ZIP+4 form `12345-6789` → `123456789` (dash dropped).
+ * Drop dash from ZIP+4.
  */
 export const zipPlus4DashDrop: Augmentation = (row) => {
+	// country-branch: see `stateExpand`.
 	if (row.country !== "US") return null
 	const postcode = row.components.postcode
 
@@ -611,21 +563,21 @@ export const zipPlus4DashDrop: Augmentation = (row) => {
 	return withAugmentation(row, "zip-plus4-dash-drop", newRaw, { ...row.components, postcode: noDash })
 }
 
-// ===========================================================================
-// FR-specific augmentations
-// ===========================================================================
+// French-specific augmentations.
 
 /**
- * FR: drop the article particle from a street ("Rue de la République" → "Rue République").
+ * Drop French street particle.
  */
 export const particleStrip: Augmentation = (row) => {
+	// country-branch: the particle list is French.
+	// A per-language particle table in the codex would replace this.
 	if (row.country !== "FR") return null
 	const particle = row.components.street_prefix_particle
 
 	if (!particle) return null
 	const newComponents: ComponentDict = { ...row.components }
 	delete newComponents.street_prefix_particle
-	// Drop the particle from raw, then collapse any double spaces.
+	// Remove particle and normalize spaces.
 	const re = new RegExp(`\\s+${escapeRegExp(particle)}\\s+`, "g")
 
 	if (!re.test(row.raw)) return null
@@ -634,12 +586,10 @@ export const particleStrip: Augmentation = (row) => {
 	return withAugmentation(row, "particle-strip", newRaw, newComponents)
 }
 
-// ===========================================================================
-// Registry + default policies
-// ===========================================================================
+// Stable augmentation registry.
 
 /**
- * Stable id → augmentation table.
+ * Stable id -> augmentation function.
  */
 export const AUGMENTATIONS: Record<string, Augmentation> = {
 	"case-upper": caseUpper,
@@ -661,17 +611,14 @@ export const AUGMENTATIONS: Record<string, Augmentation> = {
 }
 
 /**
- * Default augmentation set, by country. Phase 1: US + FR; others get the locale-agnostic set.
+ * Default augmentations by country.
  */
 export function defaultAugmentationsForCountry(country: string): readonly Augmentation[] {
-	// `typoInject` (#530) is deliberately NOT in the default set. It is implemented, tested, and
-	// registered in {@link AUGMENTATIONS} so callers can opt in (add it here or compose it directly),
-	// but it changes the synthesized corpus distribution and its effect on the trained model is not
-	// yet measured. Per the project's default-OFF discipline, promotion into the default build is an
-	// operator call once an A/B vs the current corpus exists — keeping the default byte-stable.
+	// `typoInject` is opt-in only.
 	const universal = [caseUpper, caseLower, dropCommas, doubleSpace]
 
 	switch (country) {
+		// country-branch: the US and FR augmentation lists exist because the two tier-1 locales have vocabulary tables. See `stateExpand`.
 		case "US":
 			return [
 				...universal,
@@ -685,6 +632,7 @@ export function defaultAugmentationsForCountry(country: string): readonly Augmen
 				unitDesignatorExpand,
 				zipPlus4DashDrop,
 			]
+		// country-branch: see the US case above.
 		case "FR":
 			return [...universal, accentStrip, particleStrip]
 		default:
@@ -693,8 +641,7 @@ export function defaultAugmentationsForCountry(country: string): readonly Augmen
 }
 
 /**
- * Run every augmentation against a row; collect the non-null outputs. The augmentations are pure, so callers can
- * compose them off this generator (e.g. nesting accent-strip ∘ state-abbreviate).
+ * Yield all non-null augmentation outputs.
  */
 export function* synthesizeRow(
 	row: CanonicalRow,
@@ -710,18 +657,7 @@ export function* synthesizeRow(
 }
 
 /**
- * One element of `arr`, drawn with the supplied unit-interval source.
- */
-export function pick<T>(arr: ReadonlyArray<T>, random: () => number): T {
-	return arr[Math.floor(random() * arr.length)]!
-}
-
-/**
- * One element of `items`, drawn with probability proportional to `weightOf(item)`.
- *
- * One `random()` draw per call. `inclusive` (the default) keeps an item whose cumulative weight lands exactly on the
- * draw (`r <= 0` after subtraction); pass `inclusive: false` for the strict `r < 0` boundary — the two callers this
- * consolidates disagreed on that float-exact edge, and each keeps its own reading so its draw stream is unchanged.
+ * Weighted random pick from items.
  */
 export function weightedPick<T>(
 	items: readonly T[],
@@ -743,8 +679,7 @@ export function weightedPick<T>(
 }
 
 /**
- * One band of a {@link tieredNumber} distribution: a tier draw below `cutoff` (the last band omits it) yields `base +
- * floor(random() * span)`.
+ * One band in a tiered number distribution.
  */
 export interface TieredNumberBand {
 	cutoff?: number
@@ -753,10 +688,7 @@ export interface TieredNumberBand {
 }
 
 /**
- * A number drawn from a tiered magnitude distribution — the house/box-number shape the synthesizers share.
- *
- * Exactly two `random()` draws per call, in the order every caller established: one tier draw, then one value draw
- * inside the chosen band.
+ * Draw a number from tiered bands.
  */
 export function tieredNumber(random: () => number, bands: readonly TieredNumberBand[]): string {
 	const r = random()
@@ -774,11 +706,7 @@ export function tieredNumber(random: () => number, bands: readonly TieredNumberB
 }
 
 /**
- * The primary locale a synthesizer renders for a country — ISO-3166-1 alpha-2, alpha-3, or the English display name,
- * case- and whitespace-tolerant. Unknown countries render as `en-US`.
- *
- * The PO-box synthesizer keeps its own template-scoped `countryToLocale` on top of this one: it maps any locale WITHOUT
- * a PO-box template back to `en-US` (so `DE` still renders the en-US box vocabulary there).
+ * Map country names/codes to default locale.
  */
 export function countryToLocale(country: string): string {
 	const c = country.trim().toUpperCase()
@@ -806,96 +734,37 @@ export function countryToLocale(country: string): string {
 	return "en-US"
 }
 
-// ===========================================================================
-// Compositional synthesis (Phase 1.6 §2.1)
-// ===========================================================================
-//
-// The single-row augmentations above transform one `CanonicalRow` into another with `raw` and
-// `components` moved in lockstep, leaving alignment to derive labels downstream. Composition is
-// fundamentally different: it takes a **venue string** and an **address row** from a different
-// source and renders them together as a single `raw`, producing adversarial training examples
-// where embedded place-shaped tokens collide with real address components.
-//
-// Naive post-hoc alignment of the composed string would mis-label the embedded tokens: a venue
-// like `"Buffalo Health Clinic"` shares the token `"Buffalo"` with an address locality
-// `"Buffalo, NY"`, and alignment's leftmost-substring search would claim the venue's `"Buffalo"`
-// as the locality (or vice versa, depending on order). Composition therefore **emits labels
-// directly** — venue tokens are unconditionally labeled `B-venue` / `I-venue`, and the address
-// half re-uses the labels produced by aligning the un-composed address row in isolation. No
-// re-search across the composed boundary.
-//
-// Why a separate primitive (not an `Augmentation`):
-//
-// - Augmentations are unary `(CanonicalRow) -> CanonicalRow | null` and run through
-//   `synthesizeRow`. Composition is binary `(string, CanonicalRow) -> LabeledRow` and emits
-//   `LabeledRow` directly (it cannot defer labels to alignment without the embedded-token bug).
-// - Augmentations preserve provenance to a single source; compositions cite the address source
-//   in `synth.base_source_id` and carry the venue surface form on the `venue` component.
-// - Throttling (the issue calls for ~5-15% of training set) is a build-time policy, not an
-//   adapter-level concern — the build pipeline applies it; the primitive stays pure.
-//
-// See `DECISIONS.md` for the rationale on why composition lives alongside augmentation but is
-// not part of the `AUGMENTATIONS` registry.
-
-/**
- * Options accepted by `composeAdversarialRow`.
+// Compositional synthesis combines a venue string and an address row.
+
+/**
+ * Options for `composeAdversarialRow`.
  */
 export interface ComposeAdversarialOptions {
 	/**
-	 * Stable pattern label written into the emitted row's `synth.method` field (as `compose:<pattern>`). Free-form but
-	 * should be one of a small set of canonical pattern names so downstream filtering / stratification can target
-	 * individual patterns.
-	 *
-	 * Recommended values (Phase 1.6 §2.1):
-	 *
-	 * - `"place-name-venue"` — venue token shared with locality (`Buffalo Health Clinic, Buffalo NY`).
-	 * - `"place-shaped-venue"` — venue contains a place-shaped substring (`New York, New York Steakhouse, Las Vegas NV`).
-	 * - `"particle-honorific"` — apostrophe + St./Saint ambiguity (`P'tit St. Denis Street Café`).
+	 * Pattern name written to the row's `recipe.recipe` as `compose:<pattern>`.
 	 */
 	pattern: string
 
 	/**
-	 * Separator inserted between the venue and the address `raw`. Default `", "`. Single space (`" "`) produces the
-	 * harder unpunctuated variant; newline (`"\n"`) the multi-line variant.
+	 * Separator between venue and address raw.
+	 *
+	 * @defaultValue `", "`
 	 */
 	separator?: string
 
 	/**
-	 * Tokenizer to apply to the venue prefix. Default `whitespaceTokenizer()`. The address half uses the same tokenizer
-	 * when re-aligned — pass a consistent one if customizing.
+	 * Tokenizer for venue and address alignment.
 	 */
 	tokenizer?: Tokenizer
 }
 
 /**
- * Either a successful labeled composition or a quarantined attempt.
+ * Successful composition or quarantine result.
  */
 export type ComposeResult = { kind: "labeled"; row: LabeledRow } | { kind: "quarantined"; row: QuarantinedRow }
 
 /**
- * Compose a venue string + an address row into a single adversarial `LabeledRow`.
- *
- * The emitted row's `raw` is `${venue}${separator}${address.raw}`. Tokens are produced by tokenizing the two halves
- * independently and concatenating; labels are venue tokens → `B-venue` / `I-venue` followed by the address's labels
- * (obtained by aligning the input address in isolation). This deterministic boundary is the entire point of the
- * primitive: the embedded place-shaped tokens in the venue stay labeled as `venue`, never as the address's locality /
- * region / etc., even when they share surface forms.
- *
- * The char-offset span triple (#519) is re-targeted to the composed surface by the same deterministic boundary: one
- * `venue` span over `[0, venue.length)` (no re-search), then the address's own spans shifted by `venue.length +
- * separator.length` — plain offset arithmetic, no token indirection. The separator chars sit outside every span
- * (deliberately unlabeled — now expressible). The composed triple is passed through `assertSpanInvariants` so a
- * composition bug can't ride into a corpus.
- *
- * The address's components are forwarded as-is (alignment ran on them and they survived); `venue` is added on top with
- * the trimmed venue string as its surface form.
- *
- * Returns `{ kind: "quarantined" }` when:
- *
- * - The venue is empty or whitespace-only.
- * - The venue is not NFC-normalized (char offsets over a non-NFC raw are ambiguous — the same discipline `alignRow`
- *   enforces on adapter rows, surfaced as quarantine here because the venue is caller-supplied data).
- * - The address row fails alignment in isolation (the underlying failure reason is propagated).
+ * Compose venue + address into a labeled adversarial row.
  */
 export function composeAdversarialRow(
 	venue: string,
@@ -911,8 +780,7 @@ export function composeAdversarialRow(
 		return { kind: "quarantined", row: { row: address, reason: "venue-empty" } }
 	}
 
-	// Char-offset spans over the composed raw are only meaningful under NFC (#519) — the address
-	// half is enforced by alignRow; the venue is caller-supplied and checked here.
+	// Venue must be NFC for stable char offsets.
 	if (venueTrimmed.normalize("NFC") !== venueTrimmed) {
 		return { kind: "quarantined", row: { row: address, reason: "venue-not-nfc" } }
 	}
@@ -920,9 +788,7 @@ export function composeAdversarialRow(
 	const addressAligned = alignRow(address, { tokenizer })
 
 	if (addressAligned.kind !== "labeled") {
-		// Surface the address's quarantine reason but tag it with the compose attempt for
-		// debugging. The original CanonicalRow stays on the QuarantinedRow so callers can
-		// inspect the address payload.
+		// Propagate address alignment failure with compose prefix.
 		return {
 			kind: "quarantined",
 			row: { row: address, reason: `compose-address-${addressAligned.row.reason}` },
@@ -947,16 +813,13 @@ export function composeAdversarialRow(
 		...address.components,
 	}
 
-	// Re-target the char-offset spans (#519) onto the composed surface: the venue span covers the
-	// whole trimmed venue (internal punctuation included — the token path cannot say that), and the
-	// address's spans shift right by the venue + separator length. alignRow emits the triple on
-	// every labeled row, so absence here is an alignment-contract bug, not data — fail loudly.
+	// Shift address spans by venue + separator and prepend one venue span.
 	const { span_starts: addrStarts, span_ends: addrEnds, span_tags: addrTags } = addressAligned.row
 
-	if (addrStarts === undefined || addrEnds === undefined || addrTags === undefined) {
+	if (!addrStarts || !addrEnds || !addrTags) {
 		throw new Error(
 			`composeAdversarialRow: alignRow returned a labeled row without the span triple ` +
-				`(source=${address.source}, source_id=${address.source_id}) — alignment contract violation`
+				`(source=${address.source}, source_id=${address.source_id}) — alignment interface violation`
 		)
 	}
 
@@ -967,7 +830,7 @@ export function composeAdversarialRow(
 		...addrTags.map((tag, i) => ({ tag, start: addrStarts[i]! + offset, end: addrEnds[i]! + offset })),
 	]
 
-	const baseSourceID = address.synth?.base_source_id ?? address.source_id
+	const baseSourceID = address.recipe?.base_source_id ?? address.source_id
 	const method = `compose:${options.pattern}`
 
 	const composed: LabeledRow = {
@@ -979,7 +842,7 @@ export function composeAdversarialRow(
 		source_id: `${address.source_id}+${method}`,
 		corpus_version: address.corpus_version,
 		license: address.license,
-		synth: { method, base_source_id: baseSourceID },
+		recipe: { recipe: method, base_source_id: baseSourceID },
 		tokens,
 		labels,
 		span_starts: spans.map((s) => s.start),