@mailwoman/corpus 10.0.0 → 10.1.0

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

package/lib/synthesizers/po-box.ts

@@ -3,46 +3,29 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   PO box / PMB / Apartado / Boîte Postale synthesizer.
- *
- *   Generates BIO-labeled corpus rows where the delivery line is a PO box (mutually exclusive with
- *   street + house_number per USPS Pub 28 / DMM 508). Locale-aware: emits idiomatic forms for
- *   en-US, en-CA, en-GB, en-AU, fr-FR, fr-CA, es-ES, es-MX, es-AR.
- *
- *   Per-DeepSeek design:
- *
- *   - PMB ("Private Mailbox" — at CMRAs like UPS Store) shares the `po_box` tag with USPS PO Box.
- *       Disambiguation is a downstream heuristic (presence of a street line).
- *   - Whole-phrase span ("PO Box 123") not number-only ("123"). Matches existing golden eval.
- *   - 10% of outputs receive number-format noise (commas, dashes, embedded spaces) to harden against
- *       real-world OCR/transcription input.
- *   - PO boxes drop street/house_number/unit/street_prefix/street_suffix from input components.
- *
- *   References:
- *
- *   - USPS Pub 28 §28C2.040 — Private Mailbox formatting
- *   - USPS DMM 508 §4.1.4 / §4.5.4 — PO Box and street-addressed PO Box
+ *   Generates localized PO-box and private-mailbox rows in which the designator and number form one `po_box` span.
  */
 
-import { countryToLocale as baseCountryToLocale, pick, tieredNumber } 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 as baseCountryToLocale, tieredNumber } from "#synthesizers/utils"
 import type { CanonicalRow } from "#types"
 
-/**
- * Digits a box number needs before a thousands comma is plausible (`1,234`).
- */
 const MIN_DIGITS_FOR_COMMA_GROUPING = 4
 
-/**
- * Digits a box number needs before a hyphen group is plausible (`12-34`).
- */
 const MIN_DIGITS_FOR_HYPHEN_GROUPING = 3
 
 /* 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 `r < 0.4` branches defines the
+   output distribution. The branches show each weight from top to bottom. A separate constant for each cutoff
+   would hide the distribution behind identifiers. Genuine thresholds in these files are
+   constants defined above. */
 
+/**
+ * The address tail for one PO-box row.
+ */
 export interface PoBoxBaseTuple {
 	locality: string
 	region: string
@@ -50,18 +33,23 @@ export interface PoBoxBaseTuple {
 	country: string
 }
 
+/**
+ * One locale's PO-box designators.
+ */
 export interface LocaleTemplate {
 	locale: string
 	leaders: ReadonlyArray<string>
-	// Use 'pmb' to render as "STREET, PMB N, CITY ..." instead of replacing the street line.
+	/**
+	 * Private-mailbox designators.
+	 * They render beside the street instead of replacing it.
+	 */
 	pmb?: ReadonlyArray<string>
 }
 
 /**
- * The per-locale PO-box designator vocabulary (DeepSeek-signed list, see the header). Exported so slice builders
- * (scripts/build-po-box-cedex-slice.mjs) can reuse THIS list as the single source of truth for non-US leaders instead
- * of re-deriving it — the US slice additionally has `@mailwoman/codex/us` `US_PO_BOX_DESIGNATORS`/`isPOBox` as its
- * matcher-side truth.
+ * The PO-box designator vocabulary for each supported locale.
+ *
+ * Other recipes, such as the CEDEX recipe, reuse this list.
  */
 export const PO_BOX_LOCALE_TEMPLATES: ReadonlyArray<LocaleTemplate> = [
 	{
@@ -111,35 +99,34 @@ export const PO_BOX_LOCALE_TEMPLATES: ReadonlyArray<LocaleTemplate> = [
 const LEADERS_BY_LOCALE = new Map<string, LocaleTemplate>(PO_BOX_LOCALE_TEMPLATES.map((t) => [t.locale, t]))
 
 /**
- * Inject number-format noise into a box number string. Returns the noisy variant or the original (10% probability of
- * noise per the design).
+ * Returns the box number unchanged 90% of the time.
+ *
+ * Otherwise, the function adds a thousands comma, an inner hyphen, or spaces between the digits.
  */
 export function maybeNoisifyBoxNumber(num: string, random: () => number): string {
 	if (random() > 0.1) return num
 
 	const variants: Array<(s: string) => string> = [
-		// Thousand-separator comma (real input: "Box 1,234")
 		(s) => (s.length >= MIN_DIGITS_FOR_COMMA_GROUPING ? `${s.slice(0, -3)},${s.slice(-3)}` : s),
-		// Embedded dash (real input: "PMB-200")
 		(s) => (s.length >= MIN_DIGITS_FOR_HYPHEN_GROUPING ? `${s.slice(0, -2)}-${s.slice(-2)}` : s),
-		// Embedded spaces (real input from OCR: "1 2 3 4")
 		(s) => s.split("").join(" "),
 	]
 
-	const f = pick(variants, random)
+	const f = sample(variants, random)
 
 	return f(num)
 }
 
 /**
- * Compose a PO box phrase like "PO Box 123" or "PMB 200".
- *
- * Returns both the phrase and the canonical leader+number so the BIO aligner can mark the entire span as `po_box`.
+ * Joins a designator and a number into one `po_box` phrase.
  */
 export function composePoBoxPhrase(leader: string, number: string): string {
 	return `${leader} ${number}`
 }
 
+/**
+ * One synthesized row with its template.
+ */
 export interface SynthesizedPoBoxRow {
 	raw: string
 	components: CanonicalRow["components"]
@@ -147,24 +134,29 @@ export interface SynthesizedPoBoxRow {
 	template: "po-box" | "pmb-with-street" | "military-po-box"
 }
 
+/**
+ * Options for the PO-box synthesizers.
+ */
 export interface PoBoxSynthesisOpts {
 	/**
-	 * Random function — pass deterministic seed for tests. Default Math.random.
+	 * The random source.
+	 * It defaults to `Math.random`.
 	 */
 	random?: () => number
 	/**
-	 * Number generator. Default uniform over 1..99999.
+	 * The box-number generator.
+	 *
+	 * By default, it chooses a number from 1 to 99,999 and weights short numbers more heavily.
 	 */
 	pickNumber?: (random: () => number) => string
 	/**
-	 * PMB probability when locale supports it (and a street is provided in the base tuple).
+	 * The probability of a private-mailbox row when the locale and tuple allow one.
+	 * The default is 0.
 	 */
 	pmbRatio?: number
 }
 
 function defaultPickNumber(random: () => number): string {
-	// 70% of real PO boxes are 1-5 digits; long ones exist (USPS allows up to ~6 digits).
-	// Bands: 1-99, 100-999, 1000-9999, 10000-99999 (span 90_000 — the street generator's 89_999 is its own).
 	return tieredNumber(random, [
 		{ cutoff: 0.3, base: 1, span: 99 },
 		{ cutoff: 0.7, base: 100, span: 900 },
@@ -174,8 +166,10 @@ function defaultPickNumber(random: () => number): string {
 }
 
 /**
- * Generate one PO box row for a base (locality, region, postcode, country) tuple. Picks a locale-appropriate leader and
- * number. Optionally generates a PMB variant when the base tuple includes a street.
+ * Generates a localized PO-box row, or a private-mailbox row when the tuple
+ * has a street and the locale allows it.
+ *
+ * The function returns `null` when the country lacks a template locale, an ISO code or a layout.
  */
 export function synthesizePoBoxRow(
 	base: PoBoxBaseTuple & { street?: string; houseNumber?: string },
@@ -185,67 +179,61 @@ export function synthesizePoBoxRow(
 	const pickNumber = opts.pickNumber ?? defaultPickNumber
 	const pmbRatio = opts.pmbRatio ?? 0
 
-	const locale = countryToLocale(base.country)
+	const locale = poBoxTemplateLocale(base.country)
 	const tpl = LEADERS_BY_LOCALE.get(locale)
 
 	if (!tpl) return null
 
 	const number = maybeNoisifyBoxNumber(pickNumber(random), random)
-	const leader = pick(tpl.leaders, random)
+	const leader = sample(tpl.leaders, random)
 	const poBoxPhrase = composePoBoxPhrase(leader, number)
 
-	// PMB variant: requires both a street and a PMB-supporting locale.
 	const wantPmb = base.street && tpl.pmb && random() < pmbRatio
 
+	const iso2 = countryCodeForTable(base.country)
+
+	if (!iso2) return null
+
+	// The country's layout decides the order and which components appear.
+	const adminTail: ComponentDict = { locality: base.locality, postcode: base.postcode }
+
+	if (base.region?.trim()) {
+		adminTail.region = base.region
+	}
+
 	if (wantPmb) {
-		const pmbLeader = pick(tpl.pmb!, random)
+		const pmbLeader = sample(tpl.pmb!, random)
 		const pmbPhrase = composePoBoxPhrase(pmbLeader, number)
-		const streetLine = base.houseNumber ? `${base.houseNumber} ${base.street}` : base.street!
-		const raw = `${streetLine}, ${pmbPhrase}, ${base.locality}, ${base.region} ${base.postcode}`
+		const dict: ComponentDict = { ...adminTail, street: base.street!, po_box: pmbPhrase }
+
+		if (base.houseNumber) {
+			dict.house_number = base.houseNumber
+		}
+
+		const rendered = formatAddressRow(dict, iso2, { singleLine: true })
+
+		if (!rendered) return null
 
 		return {
-			raw,
-			components: {
-				...(base.houseNumber ? { house_number: base.houseNumber } : {}),
-				street: base.street!,
-				po_box: pmbPhrase,
-				locality: base.locality,
-				region: base.region,
-				postcode: base.postcode,
-				country: base.country,
-			},
+			raw: rendered.raw,
+			components: { ...rendered.components, country: base.country },
 			locale,
 			template: "pmb-with-street",
 		}
 	}
 
-	// Standard PO box: replaces the street line entirely. Region-optional — NZ (and other region-less
-	// locales) read "Private Bag 12, Auckland 1010" with no region token between locality and postcode.
-	const hasRegion = Boolean(base.region && base.region.trim())
-	const tail = hasRegion ? `${base.locality}, ${base.region} ${base.postcode}` : `${base.locality} ${base.postcode}`
-	const raw = `${poBoxPhrase}, ${tail}`
+	const rendered = formatAddressRow({ ...adminTail, po_box: poBoxPhrase }, iso2, { singleLine: true })
+
+	if (!rendered) return null
 
 	return {
-		raw,
-		components: {
-			po_box: poBoxPhrase,
-			locality: base.locality,
-			...(hasRegion ? { region: base.region } : {}),
-			postcode: base.postcode,
-			country: base.country,
-		},
+		raw: rendered.raw,
+		components: { ...rendered.components, country: base.country },
 		locale,
 		template: "po-box",
 	}
 }
 
-/**
- * The US military/diplomatic PO-box class (#517). A distinct shape the leader-based locale templates can't express: a
- * unit line (`PSC <id> Box <box>`, `CMR <id> Box <box>`, `Unit <id> [Box <box>]`) tagged `po_box`, then the post-office
- * code (APO/FPO/DPO) as the locality and the armed-forces region (AA/AE/AP) as the region, with a theatre-specific ZIP.
- * Authoritative reference + citations: `@mailwoman/codex` `codex/us/military-address.ts`; the small constants are
- * inlined here so the generator is self-contained.
- */
 const MIL_UNITS: ReadonlyArray<{ code: string; boxRequired: boolean }> = [
 	{ code: "PSC", boxRequired: true },
 	{ code: "CMR", boxRequired: true },
@@ -254,9 +242,7 @@ const MIL_UNITS: ReadonlyArray<{ code: string; boxRequired: boolean }> = [
 
 const MIL_PO_CODES = ["APO", "FPO", "DPO"] as const
 
-/**
- * Region → plausible ZIP prefix (AE Europe 09xxx, AP Pacific 962-966xx, AA Americas 340xx).
- */
+// Each armed-forces region has its own ZIP range.
 const MIL_REGION_ZIP: ReadonlyArray<{ region: string; zip: (r: () => number) => string }> = [
 	{ region: "AE", zip: (r) => `09${String(Math.floor(r() * 1000)).padStart(3, "0")}` },
 	{ region: "AP", zip: (r) => `96${String(200 + Math.floor(r() * 100)).padStart(3, "0")}` },
@@ -264,15 +250,19 @@ const MIL_REGION_ZIP: ReadonlyArray<{ region: string; zip: (r: () => number) =>
 ]
 
 /**
- * Generate one US military/diplomatic PO-box row (#517). Self-contained — draws no base tuple.
+ * Generates a US military or diplomatic address without a base tuple.
+ *
+ * The unit line is the `po_box`.
+ * APO, FPO, or DPO is the locality.
+ * The armed-forces code is the region.
  */
 export function synthesizeMilitaryPoBoxRow(opts: PoBoxSynthesisOpts = {}): SynthesizedPoBoxRow {
 	const random = opts.random ?? Math.random
-	const unit = pick(MIL_UNITS, random)
+	const unit = sample(MIL_UNITS, random)
 	const unitID = String(1 + Math.floor(random() * 9999))
-	const { region, zip } = pick(MIL_REGION_ZIP, random)
+	const { region, zip } = sample(MIL_REGION_ZIP, random)
 	const zipStr = zip(random)
-	const po = pick(MIL_PO_CODES, random)
+	const po = sample(MIL_PO_CODES, random)
 	const hasBox = unit.boxRequired || random() < 0.5
 	const unitLine = hasBox ? `${unit.code} ${unitID} Box ${1 + Math.floor(random() * 9999)}` : `${unit.code} ${unitID}`
 	const raw = `${unitLine}, ${po} ${region} ${zipStr}`
@@ -294,30 +284,25 @@ export function synthesizeMilitaryPoBoxRow(opts: PoBoxSynthesisOpts = {}): Synth
 const PO_BOX_TEMPLATE_LOCALES: ReadonlySet<string> = new Set(PO_BOX_LOCALE_TEMPLATES.map((t) => t.locale))
 
 /**
- * Map a country code (ISO-3166-1 alpha-2 or alpha-3, or country display name) to the locale code we have a PO box
- * template for.
+ * Returns the locale whose PO-box vocabulary a country uses.
  *
- * TEMPLATE-SCOPED on top of the shared `#synthesizers/utils` map: a locale the shared map resolves but
- * {@link PO_BOX_LOCALE_TEMPLATES} does not carry falls back to `en-US`, so `DE` (shared: `de-DE`, no PO-box template)
- * keeps rendering the en-US box vocabulary here.
+ * Countries without their own template use `en-US` designators.
+ * Their address order still comes from the country's layout.
  */
-export function countryToLocale(country: string): string {
+export function poBoxTemplateLocale(country: string): string {
 	const locale = baseCountryToLocale(country)
 
 	return PO_BOX_TEMPLATE_LOCALES.has(locale) ? locale : "en-US"
 }
 
 /**
- * All locales we synthesize for. Exposed for tests and for source-weight tuning.
+ * Returns the locales that have PO-box templates.
  */
 export function supportedLocales(): ReadonlyArray<string> {
 	return PO_BOX_LOCALE_TEMPLATES.map((t) => t.locale)
 }
 
 /**
- * Locales whose standard PO-box delivery line carries NO region token — the address reads `<po_box>, <locality>
- * <postcode>` with nothing between locality and postcode (#517). NZ is the canonical case (`Private Bag 12, Auckland
- * 1010`). Consumers (e.g. the synth-po-box adapter) use this to avoid discarding region-less input tuples for these
- * locales as "missing region".
+ * Locales whose standard PO-box layout omits the region.
  */
 export const REGION_OPTIONAL_LOCALES: ReadonlySet<string> = new Set(["en-NZ"])