@mailwoman/corpus 10.0.0 → 10.2.0

package/lib/recipes/trailing-region.ts

@@ -3,76 +3,57 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `trailing-region` — the `«locality», «region», «country»` admin tail, the Portopetro class
- *   (board row `es-op3-southeast-portopetro`): `…, 07691 Portopetro, Illes Balears, Spain` parsed
- *   with the REGION mislabeled `locality` and the true locality dropped entirely. Spanish sources
- *   are postcode-complete and rarely write the region, so the trailing-region segment is
- *   under-attested and the model reads the last populous name as the locality.
+ *   `trailing-region` — the `«locality», «region»[, «country»]` admin tail, built from real
+ *   `(locality, region)` WOF ancestor pairs.
  *
- *   Tuples are real `(locality, region)` ancestor pairs from the WOF admin DB (the fr-hood-pairs
- *   extraction shape). Two surface forms per pair — with and without the trailing country — so the
- *   region is attested both as the middle and the final segment. A bare `«region»` form is
- *   deliberately absent: that surface is the bare-toponym class with its own rules, and teaching it
- *   here as `region` would fight the locality/region ambiguity the dominance race arbitrates.
+ *   A tuple's `postcodePlacement` selects where the postcode sits: `leading` (the default, so a
+ *   tuples file written before the field existed is unchanged), `after_locality`, or `after_region`.
  *
- *   The recipe is country-agnostic; the country tail surface comes from the tuple's `country`
- *   field ("Spain", "United Kingdom") so one recipe serves every extraction.
- *
- *   POSTCODE-PREFIXED FORMS (2026-08-20, #1748). The two bare forms above were the whole slice, and the
- *   board row this recipe was written for is NOT bare — it reads `…, 07691 Portopetro, Illes Balears,
- *   Spain`. Measured over both built slices: 88,904 rows, zero containing a postcode. So the model
- *   learned the bare tail correctly and had never once seen the shape it was failing on, which is why no
- *   decode change moved it.
- *
- *   The collapse is two-staged and neither trigger is a street, which is what makes this cheap to teach:
- *
- *       Portopetro, Illes Balears, Spain             locality ✓  region ✓
- *       07691 Portopetro, Illes Balears, Spain       locality ✓  region DISCARDED
- *       15, 07691 Portopetro, Illes Balears, Spain   locality DISPLACED by the region
- *
- *   A postcode alone drops the region (every locale measured); a house number then displaces the
- *   locality. So the added surfaces are postcode-prefixed and house-number-plus-postcode-prefixed, and
- *   the slice still needs no street names.
- *
- *   POSTCODE PLACEMENT. The three surfaces above are the LEADING form, and for a long time they were the
- *   only one, so this slice taught only the countries that write the postcode first. That is a real gap
- *   and not a stylistic one, because the same digits change TAG with position. Measured on the shipped
- *   model: `Barcelona 6001, Anzoátegui, Venezuela` tags `6001` as `house_number` and loses the locality
- *   into the street, while `6001 Barcelona, Anzoátegui, Venezuela` tags it `postcode` and recovers
- *   `locality: Barcelona`. `Sandton 2196` vs `2196 Sandton` behaves the same way, and no decode-time
- *   change moves it — `postcodeShapeCoherence: true` leaves all eight VE board rows byte-identical.
- *
- *   So the tuple's `postcodePlacement` selects the surface, and it keeps apart two trailing conventions
- *   that are NOT the same shape: VE writes `Barcelona 6001, Anzoátegui, Venezuela` (the code on the
- *   LOCALITY segment) and IN writes `…, Bengaluru, Karnataka 560038, India` (on the REGION segment).
- *   Each of the three placements matches a board row verbatim. A tuple with no placement means `leading`,
- *   so a tuples file written before the field existed produces the rows it always did.
+ *   A bare `«region»` form is deliberately absent: teaching it as `region` would fight the
+ *   locality/region ambiguity the dominance race arbitrates. A `dependentLocality`, when present,
+ *   becomes `«dep_locality», «locality»…`; without it every row begins with the locality and teaches
+ *   the model that the first segment is the locality.
+ */
+
+import { lookupCanadianProvince } from "@mailwoman/codex/ca"
+import { lookupUSState } from "@mailwoman/codex/us"
+import { mulberry32 as makeMulberry32 } from "@mailwoman/core/utils"
+
+import {
+	alignAndWrite,
+	type PostcodePlacement,
+	readTuples,
+	requireRegister,
+	type CorpusRecipe,
+	recipeSourceID,
+} from "#recipes/scaffold"
+import { defaultRecipeSource } from "#recipes/sources"
+import { SurfaceOrigin } from "#types"
+
+/**
+ * The region code an address line in this country writes, or `null` where the region name is written out.
  *
- *   LEFT CONTEXT (v25). A tuple may carry a `dependentLocality`, and when it does the surface becomes
- *   `«dep_locality», «locality»…`. This is not decoration: without it EVERY row in the slice begins with
- *   the locality, and at a 9.4% share that taught the model the first named segment is the locality.
- *   Measured on the v4.8.0 candidate — `Ye Three Lords, 27 Minories, London EC3N 1DE` came back
- *   `locality: "Ye Three Lords"` with venue and street both gone, `Le Colimaçon, 44 Rue Vieille du
- *   Temple, 75004 Paris` came back `locality: "Le Colimaçon"`, and 11 of 25 regressions were venue-led
- *   rows across seven countries. The house-number prefix does NOT supply this: a number before the
- *   locality does not teach that a NAME can precede one. `no-fragment.ts`'s header records the same
- *   trap from the other direction.
+ * A subdivision belongs here only when its code is a posted surface: Canadian province
+ * and US state codes are, a Bundesland or a région is not.
  *
- *   The (postcode, locality, region) triples are REAL — `postalcode-intl.db` parents joined to admin
- *   localities and their region ancestors — with one filter that had to be measured rather than assumed.
- *   A handful of localities act as catch-all parents: `Schwedt/Oder` claims 9,222 postcodes, `Korb`
- *   4,846, against a p50 of 1 and a p99 of 53. Eight such hubs held 47% of the join. Capping at the p99
- *   drops them and keeps 17,908 triples. The house number is synthetic because a house number asserts no
- *   fact about a place; the postcode is not, because it does.
+ * Several Canadian codes collide with ISO alpha-2 country codes (`NL`, `PE`),
+ * so a code left unattested here reads as the country.
  */
+function regionCodeSurface(cc: string, region: string): string | null {
+	const country = cc.toUpperCase()
 
-import { mulberry32 as makeMulberry32 } from "@mailwoman/core/utils"
+	// country-branch: the codex holds region codes for CA and US only.
+	// The WOF admin database's `place_abbr` holds codes for ten countries
+	// (IT, US, ES, MX, BR, CA, AU, AE, UA, AD), and an ISO 3166-2 table would cover every country.
+	// The tree holds neither as a lookup yet.
+	if (country === "CA") return lookupCanadianProvince(region)
 
-import { alignAndWrite, type PostcodePlacement, readTuples, type CorpusRecipe, sliceSourceID } from "#recipes/scaffold"
+	// country-branch: see the CA branch above.
+	return country === "US" ? lookupUSState(region) : null
+}
 
 /**
- * Slice recipe registered with the corpus builder — see the file header for the parse behaviour it exists to exercise,
- * and `description` below for the surface form it generates.
+ * Recipe registered with the corpus builder.
  */
 export const trailingRegionRecipe: CorpusRecipe = {
 	name: "trailing-region",
@@ -80,12 +61,17 @@ export const trailingRegionRecipe: CorpusRecipe = {
 	mode: "tuples",
 	async run(opts, write) {
 		makeMulberry32(opts.seed)
-		const structuredSource = opts.sourceName ?? "synth-trailing-region-structured"
-		const bareSource = opts.sourceName ? `${opts.sourceName}-bare` : "synth-trailing-region"
+		const structuredSource = opts.sourceName ?? defaultRecipeSource("synth-trailing-region-structured")
+		const bareSource = opts.sourceName ? `${opts.sourceName}-bare` : defaultRecipeSource("synth-trailing-region")
 		let read = 0
 		let emitted = 0
 		let skipped = 0
 
+		const TRAILING_REGION_PROVENANCE = {
+			register: requireRegister(opts, "trailing-region"),
+			surface: SurfaceOrigin.Composed,
+		}
+
 		for await (const t of readTuples(opts.input!)) {
 			read++
 			const locality = String(t.locality ?? "").trim()
@@ -93,8 +79,7 @@ export const trailingRegionRecipe: CorpusRecipe = {
 			const country = String(t.country ?? "").trim()
 			const dependentLocality = String(t.dependentLocality ?? "").trim()
 
-			// A pair whose region EQUALS its locality (Santa Cruz de Tenerife inside Santa Cruz de
-			// Tenerife) teaches nothing about the boundary this slice exists for.
+			// A pair whose region equals its locality provides no signal about the boundary this recipe teaches.
 			if (!locality || !region || locality === region) {
 				skipped++
 
@@ -104,19 +89,13 @@ export const trailingRegionRecipe: CorpusRecipe = {
 			const withCountry = read % 2 === 0 && country.length > 0
 			const postcode = String(t.postcode ?? "").trim()
 
-			// A tuple carrying a postcode emits the STRUCTURED tail — the shape the bare-only slice never
-			// contained. Every fourth such row also carries a house number, which is the second trigger:
-			// the postcode discards the region, the house number then displaces the locality.
+			// The house number is the second trigger: the postcode discards the region,
+			// the house number then displaces the locality.
 			const withHouseNumber = postcode.length > 0 && read % 4 === 1
 			const houseNumber = withHouseNumber ? String((read % 97) + 1) : ""
 
 			const components: Record<string, string> = { locality, region }
 
-			// LEFT CONTEXT. Without it every row begins with the locality, and the slice teaches that the first named
-			// segment IS the locality — measured on the v4.8.0 candidate: `Ye Three Lords, 27 Minories, London EC3N 1DE`
-			// came back `locality: "Ye Three Lords"` with the venue and street gone, and 11 of its 25 regressions were
-			// venue-led rows across seven countries. The house-number prefix does not supply it, because a NUMBER before
-			// the locality does not teach that a NAME can precede one.
 			if (dependentLocality && dependentLocality !== locality) {
 				components["dependent_locality"] = dependentLocality
 			}
@@ -134,31 +113,32 @@ export const trailingRegionRecipe: CorpusRecipe = {
 			}
 
 			const placement = (t.postcodePlacement as PostcodePlacement | undefined) ?? "leading"
-			// Both trailing placements put the code inside the ADMIN tail; they differ in which segment carries it.
 			const bareLocality = postcode && placement === "after_locality" ? `${locality} ${postcode}` : locality
 
-			const localitySegment =
-				components["dependent_locality"] === undefined ? bareLocality : `${dependentLocality}, ${bareLocality}`
+			const localitySegment = components["dependent_locality"] ? `${dependentLocality}, ${bareLocality}` : bareLocality
+
+			// The code alternates with the region name rather than replacing it:
+			// both forms are posted and the resolver matches on the name.
+			const regionCode = read % 3 === 2 ? regionCodeSurface(String(t.cc ?? ""), region) : null
+			const regionSurface = regionCode ?? region
+
+			if (regionCode) {
+				components["region"] = regionCode
+			}
 
-			const regionSegment = postcode && placement === "after_region" ? `${region} ${postcode}` : region
+			const regionSegment = postcode && placement === "after_region" ? `${regionSurface} ${postcode}` : regionSurface
 
 			const tail = withCountry
 				? `${localitySegment}, ${regionSegment}, ${country}`
 				: `${localitySegment}, ${regionSegment}`
 
-			// A leading postcode joins the head, ahead of the locality; the other two are already in the tail, so the
-			// head carries at most the house number.
 			const leadingPostcode = postcode && placement === "leading" ? `${postcode} ` : ""
 			const head = withHouseNumber ? `${houseNumber}, ${leadingPostcode}` : leadingPostcode
 			const raw = `${head}${tail}`
-			// A DISTINCT source for the structured rows. The sampler buckets by `source` and weights each bucket,
-			// so emitting these under `synth-trailing-region` would pool them with the 88,904 bare rows and make
-			// the new surface unweightable — the dose would silently be whatever the bare slice's weight bought.
-			// `--source-name` overrides both, and for the same reason one rung up: a rebuild of one country's
-			// surfaces (#1673's corrected Spanish names) pooled under the shipped label would be dosed at
-			// whatever the rows it was built to outweigh are already drawing.
+			// A distinct source for the structured rows: the sampler buckets by `source`,
+			// so pooling them with the bare rows would make their weight unsettable.
 			const sourceLabel = postcode ? structuredSource : bareSource
-			const source_id = sliceSourceID(sourceLabel, { ...components, v: String(read) })
+			const source_id = recipeSourceID(sourceLabel, { ...components, v: String(read) })
 
 			const canonical = {
 				raw,
@@ -171,7 +151,15 @@ export const trailingRegionRecipe: CorpusRecipe = {
 				license: "Synthetic — trailing-region; (locality, region) ancestor pairs from WOF (CC0/ODC-By per source)",
 			}
 
-			if (alignAndWrite(write, canonical, "trailing-region")) {
+			// Per row, because the id names this tuple's record.
+			// A tuples file written before `sourceID` existed contains no id.
+			// and `null` means the recipe had no id to forward.
+			if (
+				alignAndWrite(write, canonical, "trailing-region", {
+					...TRAILING_REGION_PROVENANCE,
+					baseSourceID: t.sourceID ?? null,
+				})
+			) {
 				emitted++
 			} else {
 				skipped++

package/lib/recipes/unit/sources.ts

@@ -0,0 +1,44 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Lists the cached OpenAddresses extracts read by the `unit` recipe.
+ *   It also identifies the held-out extract excluded from training.
+ *
+ */
+
+import { dataRootPath } from "@mailwoman/core/data-root"
+import type { PathBuilderLike } from "path-ts"
+
+/**
+ * A cached OpenAddresses extract.
+ *
+ * Its fields identify the ZIP, CSV member and implied file-level region.
+ */
+export interface UnitSource {
+	zip: PathBuilderLike
+	csv: string
+	region: string
+}
+
+/**
+ * Every non-Vermont state cached; `region` is implied by the file.
+ */
+export const TRAIN_SOURCES: readonly UnitSource[] = [
+	{ zip: dataRootPath("oa-cache", "us__ca__berkeley.zip"), csv: "us/ca/berkeley.csv", region: "CA" },
+	{ zip: dataRootPath("oa-cache", "us__ca__marin.zip"), csv: "us/ca/marin.csv", region: "CA" },
+	{ zip: dataRootPath("oa-cache", "us__dc__statewide.zip"), csv: "us/dc/statewide.csv", region: "DC" },
+	{ zip: dataRootPath("oa-cache", "us__ia__statewide.zip"), csv: "us/ia/statewide.csv", region: "IA" },
+	{ zip: dataRootPath("oa-cache", "us__il__cook.zip"), csv: "us/il/cook.csv", region: "IL" },
+	{ zip: dataRootPath("oa-cache", "us__mt__statewide.zip"), csv: "us/mt/statewide.csv", region: "MT" },
+	{ zip: dataRootPath("oa-cache", "us__sd__statewide.zip"), csv: "us/sd/statewide.csv", region: "SD" },
+]
+
+/**
+ * Vermont, the corpus holdout — `--golden` reads this and no other source.
+ */
+export const EVAL_SOURCE: UnitSource = {
+	zip: dataRootPath("oa-cache", "us__vt__statewide.zip"),
+	csv: "us/vt/statewide.csv",
+	region: "VT",
+}

package/lib/recipes/unit.ts

@@ -3,75 +3,35 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `unit` slice recipe — US secondary-unit coverage (#451, the v0-parity `unit` gap). Onto REAL US
- *   OpenAddresses skeletons (cached zips under `$MAILWOMAN_DATA_ROOT/oa-cache`) it INJECTS a USPS Pub-28 Appendix
- *   C2 secondary-unit designator (the `@mailwoman/codex/us` table), varying the surface form
- *   (canonical "Apartment" vs approved "Apt") AND the unit's POSITION (after-street / unit-first /
- *   bare / venue-prefixed) per row, so the model learns to RECOGNIZE the designator wherever it
- *   sits. The inline synthesis (the OA-CSV reader, the designator tables, `makeUnit`/`renderUnit`)
- *   is ported faithfully from scripts/build-unit-slice.mjs.
+ *   `unit` recipe: injects a USPS Pub-28 C2 secondary-unit designator into real US OpenAddresses
+ *   skeletons, varying the surface form and the unit's position per row.
  *
- *   `--golden`: a held-out eval over the VERMONT source only (the corpus `defaultHoldout`, never
- *   trained) with a different seed, emitting `{raw, components, country}` for per-locale-f1. Train
- *   uses every NON-Vermont US source. Designators are injected in both (OA carries none), so the
- *   eval measures designator recognition on held-out addresses.
- *
- *   NOTE: this is a `generate`-mode recipe but it still reads REAL tuples off disk (`unzip` of the
- *   cached OA zips) — `--count` bounds the OUTPUT, not the input. The passed `random` (the
- *   framework LCG) is consumed in the exact call order the legacy script used.
+ *   `--golden` emits the held-out Vermont eval (`{raw, components, country}`) with a different
+ *   seed. Train uses every non-Vermont US source. `--count` bounds the output and leaves the input unbounded.
  */
 
 import type { ComponentTag } from "@mailwoman/codex/component"
 import { US_UNIT_DESIGNATOR_PREFERRED_ABBR, type USUnitDesignator } from "@mailwoman/codex/us"
 import { dataRootPath } from "@mailwoman/core/data-root"
+import { stringifyJSON } from "@mailwoman/core/json"
+import { sample } from "@mailwoman/core/random"
 import { mulberry32 as makeMulberry32 } from "@mailwoman/core/utils"
-import type { PathBuilderLike } from "path-ts"
 
-import { stableSourceID } from "#adapters/utils"
-import { readOATuples, type CorpusRecipe } from "#recipes/scaffold"
-import { pick } from "#synthesizers/utils"
+import { stableSourceID } from "#adapters/source-id"
+import { readOATuples, requireRegister, type CorpusRecipe } from "#recipes/scaffold"
+import { defaultRecipeSource } from "#recipes/sources"
+import { EVAL_SOURCE, TRAIN_SOURCES, type UnitSource } from "#recipes/unit/sources"
+import { SurfaceOrigin } from "#types"
 import type { CanonicalRow } from "#types"
 import { alignRow } from "#utils"
-/**
- * A cached OpenAddresses extract: the zip, the CSV member, and the implied (file-level) region.
- */
 
 /**
- * Longest OpenAddresses unit id reused verbatim. Longer values are building codes or free text, so a synthetic id is
- * substituted instead.
+ * Longer OpenAddresses unit ids are building codes or free text, so a synthetic id is substituted instead.
  */
 const MAX_REAL_UNIT_ID_LENGTH = 6
 
-interface UnitSource {
-	zip: PathBuilderLike
-	csv: string
-	region: string
-}
-
-/**
- * OA REGION is empty for US per-state extracts — the region is implied by the file. Train sources are every NON-Vermont
- * state cached; eval is Vermont only (the corpus holdout).
- */
-const TRAIN_SOURCES: readonly UnitSource[] = [
-	{ zip: dataRootPath("oa-cache", "us__ca__berkeley.zip"), csv: "us/ca/berkeley.csv", region: "CA" },
-	{ zip: dataRootPath("oa-cache", "us__ca__marin.zip"), csv: "us/ca/marin.csv", region: "CA" },
-	{ zip: dataRootPath("oa-cache", "us__dc__statewide.zip"), csv: "us/dc/statewide.csv", region: "DC" },
-	{ zip: dataRootPath("oa-cache", "us__ia__statewide.zip"), csv: "us/ia/statewide.csv", region: "IA" },
-	{ zip: dataRootPath("oa-cache", "us__il__cook.zip"), csv: "us/il/cook.csv", region: "IL" },
-	{ zip: dataRootPath("oa-cache", "us__mt__statewide.zip"), csv: "us/mt/statewide.csv", region: "MT" },
-	{ zip: dataRootPath("oa-cache", "us__sd__statewide.zip"), csv: "us/sd/statewide.csv", region: "SD" },
-]
-
-const EVAL_SOURCE: UnitSource = {
-	zip: dataRootPath("oa-cache", "us__vt__statewide.zip"),
-	csv: "us/vt/statewide.csv",
-	region: "VT",
-}
-
 /**
- * USPS Pub-28 C2 designators that take a secondary identifier ("Apt 4B"). Weighted toward the common ones the v0-parity
- * arena failed on (Apt/Ste/Unit/Fl/Rm). Standalone designators (Basement, Lobby, Penthouse) are emitted occasionally
- * with no id.
+ * USPS Pub-28 C2 designators that take a secondary identifier ("Apt 4B").
  */
 const ID_DESIGNATORS: readonly USUnitDesignator[] = [
 	"APARTMENT",
@@ -95,16 +55,20 @@ const STANDALONE_DESIGNATORS: readonly USUnitDesignator[] = [
 	"LOWER",
 ]
 
+const ID_WEIGHT = 0.85
+
 /**
- * 85% id-bearing designators, 15% standalone.
+ * Share of id-containing rows written with the `#` sigil.
+ *
+ * The same sigil leads a private mailbox, so only context can decide the reading.
  */
-const ID_WEIGHT = 0.85
+const SIGIL_WEIGHT = 0.2
 const SYNTH_IDS: readonly string[] = ["4B", "200", "12", "3", "A", "101", "5", "2A", "310", "B", "7", "1500", "404"]
 
 /**
  * A real US tuple read out of a cached OA zip (number/street/city/postcode + the bare OA unit id).
  */
-interface UnitTuple {
+export interface UnitTuple {
 	house_number: string
 	street: string
 	locality: string
@@ -113,40 +77,34 @@ interface UnitTuple {
 	oaUnit: string
 }
 
-/**
- * Stream real US tuples (number/street/city/postcode + the bare OA unit id) out of a cached OA zip.
- */
 async function readTuples(source: UnitSource): Promise<UnitTuple[]> {
 	return readOATuples(source, {
 		extra: (fields, row) => ({ ...fields, region: source.region, oaUnit: row.unit ?? "" }),
 	})
 }
 
-/**
- * Title-case a canonical/abbrev designator ("APARTMENT" → "Apartment", "APT" → "Apt").
- */
 const title = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1).toLowerCase()
 
 /**
  * Build an injected unit string ("Apt 4B"), varying canonical vs approved-abbrev form per row.
  */
-function makeUnit(random: () => number, oaUnit: string): string {
+export function makeUnit(random: () => number, oaUnit: string): string {
 	const standalone = random() >= ID_WEIGHT
 	const pool = standalone ? STANDALONE_DESIGNATORS : ID_DESIGNATORS
-	const canonical = pick(pool, random)
-	// Vary the surface form 50/50 (this is the #454 expand/abbreviate variety, baked into the slice).
+	const canonical = sample(pool, random)
 	const designator = random() < 0.5 ? title(canonical) : title(US_UNIT_DESIGNATOR_PREFERRED_ABBR[canonical])
 
 	if (standalone) return designator
 
-	const id = oaUnit && oaUnit.length <= MAX_REAL_UNIT_ID_LENGTH ? oaUnit : pick(SYNTH_IDS, random)
+	const id = oaUnit && oaUnit.length <= MAX_REAL_UNIT_ID_LENGTH ? oaUnit : sample(SYNTH_IDS, random)
+
+	// Both spacings are emitted: attesting one leaves the other reachable only by
+	// generalization the model does not make here.
+	if (random() < SIGIL_WEIGHT) return random() < 0.5 ? `#${id}` : `# ${id}`
 
 	return `${designator} ${id}`
 }
 
-/**
- * Synthetic recipient/venue prefixes — the "JOHN DOE, ACME INC, ..." arena pattern.
- */
 const VENUES: readonly string[] = [
 	"John Doe",
 	"Jane Smith",
@@ -161,22 +119,43 @@ const VENUES: readonly string[] = [
 ]
 
 /**
- * Address tail: "City, ST 12345" (or no postcode).
+ * Share of tails that write a comma before the postcode.
+ *
+ * A bare number by itself in a later comma segment appears nowhere else in the mixture,
+ * so this is the only counter-evidence for that segment.
+ */
+const COMMA_POSTCODE_WEIGHT = 0.15
+
+const tail = (random: () => number, loc: string, reg: string, pc: string): string => {
+	if (!pc) return `${loc}, ${reg}`
+
+	return random() < COMMA_POSTCODE_WEIGHT ? `${loc}, ${reg}, ${pc}` : `${loc}, ${reg} ${pc}`
+}
+
+/**
+ * The identifier inside a rendered unit, or `null` when a standalone designator
+ * or a letter-only id has none.
  */
-const tail = (loc: string, reg: string, pc: string): string => (pc ? `${loc}, ${reg} ${pc}` : `${loc}, ${reg}`)
+function unitIdentifier(unit: string): string | null {
+	const last = unit.replace(/^#\s*/, "").split(/\s+/).at(-1)
 
-// Layouts: 34% full-after, 18% full-first, 16% bare-after, 16% bare-first, 16% venue.
-const FULL_AFTER_CUTOFF = 0.34
+	return last && /\d/.test(last) ? last : null
+}
+
+// `full-comma-bare` writes the identifier with no designator at all, the one unit surface carrying no
+// token that decides its reading, so it is the smallest share and confined to the comma layout.
+const FULL_AFTER_CUTOFF = 0.26
+const FULL_COMMA_CUTOFF = 0.31
+const FULL_COMMA_BARE_CUTOFF = 0.34
 const FULL_FIRST_CUTOFF = 0.52
 const BARE_AFTER_CUTOFF = 0.68
 const BARE_FIRST_CUTOFF = 0.84
 
 /**
- * Render a unit row in a RANDOM layout — units spread across positions, the city/state tail dropped on bare rows, a
- * recipient/venue prefixed on the venue format — so the model learns to RECOGNIZE the designator wherever it sits.
- * Returns {fmt, raw, components}.
+ * Render a unit row in a random layout, spreading units across positions
+ * and varying the surrounding surface.
  */
-function renderUnit(
+export function renderUnit(
 	random: () => number,
 	base: UnitTuple,
 	unit: string
@@ -201,10 +180,29 @@ function renderUnit(
 	const r = random()
 
 	if (r < FULL_AFTER_CUTOFF)
-		return { fmt: "full-after", raw: `${road} ${unit}, ${tail(loc, reg, pc)}`, components: full }
+		return { fmt: "full-after", raw: `${road} ${unit}, ${tail(random, loc, reg, pc)}`, components: full }
+
+	if (r < FULL_COMMA_CUTOFF)
+		return { fmt: "full-comma", raw: `${road}, ${unit}, ${tail(random, loc, reg, pc)}`, components: full }
+
+	if (r < FULL_COMMA_BARE_CUTOFF) {
+		const identifier = unitIdentifier(unit)
+
+		// A standalone designator has no identifier to write bare, so it keeps the
+		// designator form rather than disappearing from the layout.
+		if (identifier) {
+			return {
+				fmt: "full-comma-bare",
+				raw: `${road}, ${identifier}, ${tail(random, loc, reg, pc)}`,
+				components: { ...full, unit: identifier },
+			}
+		}
+
+		return { fmt: "full-comma", raw: `${road}, ${unit}, ${tail(random, loc, reg, pc)}`, components: full }
+	}
 
 	if (r < FULL_FIRST_CUTOFF)
-		return { fmt: "full-first", raw: `${unit}, ${road}, ${tail(loc, reg, pc)}`, components: full }
+		return { fmt: "full-first", raw: `${unit}, ${road}, ${tail(random, loc, reg, pc)}`, components: full }
 
 	if (r < BARE_AFTER_CUTOFF)
 		return { fmt: "bare-after", raw: `${road} ${unit}`, components: { house_number: hn, street, unit } }
@@ -212,26 +210,28 @@ function renderUnit(
 	if (r < BARE_FIRST_CUTOFF)
 		return { fmt: "bare-first", raw: `${unit} ${road}`, components: { house_number: hn, street, unit } }
 
-	const v = pick(VENUES, random)
+	const v = sample(VENUES, random)
 
-	return { fmt: "venue", raw: `${v}, ${road} ${unit}, ${tail(loc, reg, pc)}`, components: { venue: v, ...full } }
+	return {
+		fmt: "venue",
+		raw: `${v}, ${road} ${unit}, ${tail(random, loc, reg, pc)}`,
+		components: { venue: v, ...full },
+	}
 }
 
 /**
- * Slice recipe registered with the corpus builder — see the file header for the parse behaviour it exists to exercise,
- * and `description` below for the surface form it generates.
+ * Recipe registered with the corpus builder.
  */
 export const unitRecipe: CorpusRecipe = {
 	name: "unit",
 	description: "US secondary-unit rows (#451): real OA skeletons + injected USPS Pub-28 C2 unit designators",
 	mode: "generate",
-	options: [{ flag: "--golden", description: "Emit the held-out VT eval slice ({raw, components, country})" }],
+	options: [{ flag: "--golden", description: "Emit the held-out VT eval set ({raw, components, country})" }],
 	async run(opts, write) {
 		if (opts.count == null) throw new Error("unit recipe requires --count <N>")
 		const count = opts.count
-		// Legacy build-unit-slice.mjs seeded mulberry32 with the raw seed: `const random = mulberry32(opts.seed)`.
 		const random = makeMulberry32(opts.seed)
-		const source = opts.sourceName ?? "synth-unit"
+		const source = opts.sourceName ?? defaultRecipeSource("synth-unit")
 		const sources = opts.golden ? [EVAL_SOURCE] : TRAIN_SOURCES
 
 		const pool: UnitTuple[] = []
@@ -259,16 +259,20 @@ export const unitRecipe: CorpusRecipe = {
 			const base = pool[Math.floor(random() * N)]!
 			const unit = makeUnit(random, base.oaUnit)
 			const { raw, components } = renderUnit(random, base, unit)
+			// The rendered component rather than the designator form handed in:
+			// `full-comma-bare` writes the identifier by itself, so checking the pre-render
+			// string would refuse every row of that layout.
+			const rendered = components.unit
 
 			// The unit must survive verbatim in raw, else alignment can't label it.
-			if (!raw.includes(unit)) {
+			if (!rendered || !raw.includes(rendered)) {
 				skipped++
 
 				continue
 			}
 
 			if (opts.golden) {
-				write(JSON.stringify({ raw, components, country: "US" }) + "\n")
+				write(stringifyJSON({ raw, components, country: "US" }))
 
 				emitted++
 
@@ -294,7 +298,15 @@ export const unitRecipe: CorpusRecipe = {
 				continue
 			}
 
-			write(JSON.stringify({ ...aligned.row, synth_method: "unit", synth_base_id: null }) + "\n")
+			write(
+				stringifyJSON({
+					...aligned.row,
+					recipe: "unit",
+					base_source_id: null,
+					register: requireRegister(opts, "unit"),
+					surface: SurfaceOrigin.Composed,
+				})
+			)
 
 			emitted++
 		}