@mailwoman/corpus 9.4.0 → 10.1.0

package/lib/recipes/intersection.ts

@@ -3,53 +3,54 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `intersection` slice recipe — the REAL-pair intersection training slice (#487). The model scored
- *   0.0 on intersection_a/b because the training mix had ZERO intersection-labeled rows. This is
- *   the missing data. Ported from scripts/build-intersection-slice.mjs.
+ *   `intersection` recipe, the real-pair intersection training source.
  *
- *   STREET PAIRS ARE REAL: the same TIGER 2023 EDGES extraction as the eval builder
- *   (scripts/eval/build-intersection-real.ts) — a node where two road edges (MTFCC S1*) with
+ *   Street pairs are real. The extraction matches the eval builder
+ *   (`scripts/eval/build-intersection-real.ts`). A node where two road edges (mtfcc S1*) with
  *   distinct FULLNAMEs meet is a real crossing. Real pairs avoid teaching fake street-street
  *   co-occurrences.
  *
- *   LEAKAGE POLICY (mirrors the affix slice's VT discipline):
+ *   Leakage policy (mirrors the affix recipe's VT discipline):
  *
- *   - TRAIN counties: Cook IL (grid city) + Morris NJ (suburb).
- *   - GOLDEN (`--golden`) county: Washington VT (rural) ONLY — the corpus defaultHoldout state.
- *   - Every crossing in data/eval/external/intersection-real.jsonl is excluded from BOTH modes, by node
- *       id AND by order-insensitive name pair (the eval shares all three counties).
+ *   - train counties: Cook IL (grid city) + Morris NJ (suburb).
+ *   - golden (`--golden`) county: Washington VT (rural) only, the corpus defaultHoldout state.
+ *   - Every crossing in data/eval/external/intersection-real.jsonl is excluded from both modes, by node
+ *       id and by order-insensitive name pair (the eval shares all three counties).
  *
- *   RENDERING: junction-format variety — padded/TIGHT `&` and `/`, `and`, `at`, `@`, leading-phrase
- *   `corner of` / `intersection of` — crossed with tails (bare / `, ST` / `, ST ZIP` / `, City, ST
- *   [ZIP]`) and case variants. ZIPs are the crossing's own TIGER edge ZIPL (real); the locality
- *   tail comes from the OA Cook-county ZIP→city majority map.
+ *   Junction-format variety includes padded and tight `&` and `/`, `and`, `at`, `@`, and the
+ *   leading phrases `corner of` and `intersection of`, crossed with tails (bare / `, ST` / `, ST ZIP` /
+ *   `, City, ST [ZIP]`) and case variants. ZIPs are the crossing's own tiger edge zipl (real). The
+ *   locality tail comes from the OA Cook-county ZIP→city majority map.
  *
- *   AUDIT: every emitted row is label-checked on the RAW SURFACE via the #519 char-offset span
- *   triple. Any violation FAILS the build (throws). A JSON audit report lands next to the output.
+ *   Audit: every emitted row is label-checked on the RAW surface via the char-offset span triple. Any
+ *   violation fails the build (throws). A JSON audit report lands next to the output.
  *
- *   External inputs (`--edges-dir`, opts.edgesDir; both already on disk — do not re-download):
+ *   External inputs (`--edges-dir` and opts.edgesDir, both already on disk. Do not re-download):
  *
- *   - <edges-dir>/tl_2023_{17031,34027,50023}_edges.shp (unzipped TIGER 2023 EDGES; default
+ *   - <edges-dir>/tl_2023_{17031,34027,50023}_edges.shp (unzipped tiger 2023 edges. default
  *       `$MAILWOMAN_DATA_ROOT/census/tiger2023-edges`, where `mailwoman situs interpolation` puts them)
  *   - `$MAILWOMAN_DATA_ROOT/oa-cache/us__il__cook.zip` (ZIP→city tails)
  */
 
 import type { DuckDBConnection } from "@duckdb/node-api"
+import type { ComponentTag } from "@mailwoman/codex/component"
 import { dataRootPath } from "@mailwoman/core/data-root"
 import { pathExists } from "@mailwoman/core/fs/readers"
 import { writeLocalJSONFile } from "@mailwoman/core/fs/writers"
+import { stringifyJSON } from "@mailwoman/core/json"
 import { repoRootPath } from "@mailwoman/core/paths"
-import type { ComponentTag } from "@mailwoman/core/types"
+import { sample } from "@mailwoman/core/random"
 import { mulberry32 as makeMulberry32 } from "@mailwoman/core/utils"
 import type { PathBuilderLike } from "path-ts"
 import { JSONSpliterator } from "spliterator"
 
-import { stableSourceID } from "#adapters/utils"
+import { stableSourceID } from "#adapters/source-id"
+import { openDuckDB } from "#parquet/duckdb"
 import { readZippedCSVRecords, type CorpusRecipe } from "#recipes/scaffold"
-import { pick, weightedPick } from "#synthesizers/utils"
+import { defaultRecipeSource } from "#recipes/sources"
+import { weightedPick } from "#synthesizers/utils"
 import type { CanonicalRow, LabeledRow } from "#types"
 import { alignRow } from "#utils"
-import { connectDuckDB } from "#utils/parquet"
 
 interface County {
 	fips: string
@@ -66,15 +67,18 @@ const GOLDEN_COUNTIES: readonly County[] = [{ fips: "50023", state: "VT", regime
 
 const EVAL_GOLD_PATH = repoRootPath("data", "eval", "external", "intersection-real.jsonl")
 /**
- * Where `mailwoman situs interpolation` unpacks the per-county TIGER EDGES shapefiles — a Census download, so it sits
- * beside the other Census vintages under `census/`. `--edges-dir` overrides it.
+ * Where `mailwoman situs interpolation` unpacks the per-county tiger edges shapefiles.
+ *
+ * A Census download, so it sits beside the other Census vintages under `census/`.
+ *
+ * `--edges-dir` overrides it.
  */
 const DEFAULT_EDGES_DIR = dataRootPath("census", "tiger2023-edges")
 
 const OA_COOK = { zip: dataRootPath("oa-cache", "us__il__cook.zip"), csv: "us/il/cook.csv" }
 
 /**
- * One real crossing extracted from a county's TIGER EDGES shapefile.
+ * One real crossing extracted from a county's tiger edges shapefile.
  */
 interface Crossing {
 	a: string
@@ -86,8 +90,10 @@ interface Crossing {
 }
 
 /**
- * Junction forms. Weights favor the common connectors; the tight (unpadded) variants and leading phrases get enough
- * mass to register (each ≥5%) — they're the audited gaps the old synth missed.
+ * Junction forms.
+ *
+ * Weights favor the common connectors.
+ * The tight (unpadded) variants and leading phrases each account for at least 5% of the mass.
  */
 interface Form {
 	id: string
@@ -108,9 +114,15 @@ const FORMS: readonly Form[] = [
 ]
 
 /**
- * Tail forms. ~55% bare (the v0.7.2 lesson: an always-present tail taught the model to read post-intersection text as a
- * locality and fumble bare "X & Y"). City tails require a ZIP→city hit (Cook only); ZIP tails require the edge to carry
- * a ZIPL. Misses downgrade to the region tail.
+ * Tail forms.
+ * About 55% bare.
+ *
+ * An always-present tail teaches the model to read post-intersection text as a locality,
+ * so the bare form keeps a majority.
+ * City tails require a ZIP→city hit (Cook only).
+ *
+ * ZIP tails require the edge to include a zipl.
+ * Misses downgrade to the region tail.
  */
 interface Tail {
 	id: string
@@ -138,14 +150,16 @@ const CASES: readonly Casing[] = [
 ]
 
 /**
- * Words a connector may contribute as O tokens. The audit rejects any O token outside this set — an unlabeled
- * street/locality token would surface here.
+ * Words a connector may contribute as O tokens.
+ *
+ * The audit rejects any O token outside this set.
+ * An unlabeled street/locality token would surface here.
  */
 const CONNECTOR_O_TOKENS = new Set(["and", "at", "of", "corner", "intersection"])
 
 /**
- * Street names that would make the connector ambiguous or break verbatim alignment: embedded connector punctuation, or
- * a standalone "and"/"at" word.
+ * Street names that would make the connector ambiguous or break verbatim alignment:
+ * embedded connector punctuation, or a standalone "and"/"at" word.
  */
 const BAD_NAME = /[,&@/]|\b(and|at)\b/i
 
@@ -160,7 +174,8 @@ const CONNECTOR_PUNCT_RE = /^[\s,&@/]*$/
 const pairKey = (a: string, b: string): string => [a.toLowerCase(), b.toLowerCase()].toSorted().join("\u001F")
 
 /**
- * One row of the intersection eval gold — the shape this recipe reads to exclude eval crossings.
+ * One row of the intersection eval gold.
+ * The shape this recipe reads to exclude eval crossings.
  */
 interface EvalGoldRow {
 	node: number | string
@@ -189,9 +204,11 @@ async function readEvalExclusions(): Promise<{ nodes: Set<number>; pairs: Set<st
 }
 
 /**
- * Extract real crossings from one county's TIGER EDGES shapefile. Same query shape as the eval builder (2 incident
- * distinct S1* FULLNAMEs at a node, both names >=6 chars), plus the edge ZIPL so tails can carry the crossing's own
- * ZIP. Hash-ordered for seed-stable determinism.
+ * Extract real crossings from one county's tiger edges shapefile.
+ *
+ * Same query shape as the eval builder (2 incident distinct S1* FULLNAMEs at a node, both names >=6 chars),
+ * plus the edge zipl so tails can include the crossing's own ZIP.
+ * Hash-ordered for seed-stable determinism.
  */
 async function extractCrossings(
 	db: DuckDBConnection,
@@ -245,7 +262,6 @@ async function extractCrossings(
 async function buildZipCityMap(): Promise<Map<string, string>> {
 	const counts = new Map<string, Map<string, number>>()
 
-	// zip → Map(city → n)
 	for await (const row of readZippedCSVRecords(OA_COOK.zip, OA_COOK.csv)) {
 		const city = row.city ?? ""
 		const zip = row.postcode ?? ""
@@ -279,8 +295,10 @@ async function buildZipCityMap(): Promise<Map<string, string>> {
 }
 
 /**
- * Render one crossing → { raw, components, formID, tailID, caseID }. Components are inserted in claim order (streets
- * first) so alignment can't grab a region/postcode lookalike inside a street.
+ * Render one crossing → { raw, components, formID, tailID, caseID }.
+ *
+ * Components are inserted in claim order (streets first) so alignment can't grab
+ * a region/postcode lookalike inside a street.
  */
 function renderRow(
 	random: () => number,
@@ -326,15 +344,18 @@ function renderRow(
 	const casing = weightedPick(CASES, random, (c) => c.w)
 	raw = casing.apply(raw)
 
-	// Components keep their original case; alignRow matches case-insensitively and labels the
-	// tokens of the (cased) raw — the parquet row carries tokens+labels only.
+	// Components keep their original case. alignRow matches case-insensitively
+	// and labels the tokens of the (cased) raw.
+	// The parquet row contains tokens+labels only.
 	return { raw, components, formID: form.id, tailID: tail.id, caseID: casing.id }
 }
 
 /**
- * Label-correctness audit for one aligned row, on the RAW SURFACE via the #519 span triple. Returns a list of
- * violations (empty = clean). Re-derives the span checks independent of `alignRow`'s own assertion, so a builder bug
- * can't vouch for itself.
+ * Label-correctness audit for one aligned row, on the RAW surface via the char-offset span triple.
+ *
+ * @returns A list of violations (empty = clean).
+ * Re-derives the span checks independent of `alignRow`'s own assertion,
+ * so a builder bug can't vouch for itself.
  */
 function auditRow(row: LabeledRow, components: Partial<Record<ComponentTag, string>>): string[] {
 	const errors: string[] = []
@@ -374,7 +395,6 @@ function auditRow(row: LabeledRow, components: Partial<Record<ComponentTag, stri
 		errors.push(`span count ${span_tags.length} != components ${compCount}`)
 	}
 
-	// Raw-surface reconstruction: each component's single span slices raw to the component verbatim.
 	for (const [tag, value] of Object.entries(components)) {
 		if (value == null) continue
 		const indices = span_tags.map((t, i) => (t === tag ? i : -1)).filter((i) => i >= 0)
@@ -429,8 +449,10 @@ function auditRow(row: LabeledRow, components: Partial<Record<ComponentTag, stri
 }
 
 /**
- * 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.
+ *
+ * See the file header for the parse behavior it exercises.
+ * See `description` below for the generated surface form.
  */
 export const intersectionRecipe: CorpusRecipe = {
 	name: "intersection",
@@ -443,17 +465,17 @@ export const intersectionRecipe: CorpusRecipe = {
 		},
 	],
 	async run(opts, write) {
-		// Legacy build-intersection-slice.mjs seeded `mulberry32(opts.seed)`.
 		const random = makeMulberry32(opts.seed)
 		const count = opts.count ?? 40_000
-		const source = opts.sourceName ?? "synth-intersection"
+		const source = opts.sourceName ?? defaultRecipeSource("synth-intersection")
 		const edgesDir = opts.edgesDir ?? DEFAULT_EDGES_DIR
 		const counties = opts.golden ? GOLDEN_COUNTIES : TRAIN_COUNTIES
 		const exclusions = await readEvalExclusions()
 
 		console.error(`  eval exclusions: ${exclusions.nodes.size} nodes, ${exclusions.pairs.size} pairs`)
 
-		const db = await connectDuckDB()
+		using db = await openDuckDB()
+
 		await db.run("INSTALL spatial; LOAD spatial;")
 
 		// Pool real crossings: eval-excluded, connector-safe names, one crossing per distinct pair.
@@ -518,7 +540,7 @@ export const intersectionRecipe: CorpusRecipe = {
 		const samples: Array<{ form: string; raw: string; tokens: readonly string[]; labels: readonly string[] }> = []
 
 		while (emitted < count && guard++ < count * 10) {
-			const crossing = pick(pool, random)
+			const crossing = sample(pool, random)
 			const { raw, components, formID, tailID, caseID } = renderRow(random, crossing, zipCity)
 
 			if (seenRaw.has(raw)) {
@@ -529,7 +551,7 @@ export const intersectionRecipe: CorpusRecipe = {
 
 			if (opts.golden) {
 				seenRaw.add(raw)
-				write(JSON.stringify({ raw, components, country: "US", form: formID }) + "\n")
+				write(stringifyJSON({ raw, components, country: "US", form: formID }))
 				formCounts[formID] = (formCounts[formID] ?? 0) + 1
 				tailCounts[tailID] = (tailCounts[tailID] ?? 0) + 1
 				caseCounts[caseID] = (caseCounts[caseID] ?? 0) + 1
@@ -552,8 +574,8 @@ export const intersectionRecipe: CorpusRecipe = {
 				license: "TIGER/Line 2023 EDGES (US Census, public domain) real street pairs; OA Cook IL zip-to-city tails",
 			}
 
-			// Verbatim-only alignment: raw is built from the component values, so a fuzzy fallback could
-			// only ever mislabel (e.g. claim a lookalike window for a near-duplicate street).
+			// Verbatim-only alignment: raw is built from the component values, so a fuzzy fallback
+			// could only ever mislabel (e.g. Claim a lookalike window for a near-duplicate street).
 			const aligned = alignRow(canonical, { maxEditDistance: 0 })
 
 			if (aligned.kind !== "labeled" || !aligned.row) {
@@ -571,7 +593,7 @@ export const intersectionRecipe: CorpusRecipe = {
 			}
 
 			seenRaw.add(raw)
-			write(JSON.stringify({ ...aligned.row, synth_method: "intersection", synth_base_id: null }) + "\n")
+			write(stringifyJSON({ ...aligned.row, synth_method: "intersection", synth_base_id: null }))
 			formCounts[formID] = (formCounts[formID] ?? 0) + 1
 			tailCounts[tailID] = (tailCounts[tailID] ?? 0) + 1
 			caseCounts[caseID] = (caseCounts[caseID] ?? 0) + 1
@@ -604,14 +626,14 @@ export const intersectionRecipe: CorpusRecipe = {
 
 		console.error(
 			`Done: emitted ${emitted} rows (skipped ${skipped}) from ${usedCrossings.size}/${pool.length} real crossings. → ${opts.output}\n` +
-				`  forms: ${JSON.stringify(formCounts)}\n` +
-				`  tails: ${JSON.stringify(tailCounts)}\n` +
-				`  cases: ${JSON.stringify(caseCounts)}\n` +
+				`  forms: ${stringifyJSON(formCounts)}\n` +
+				`  tails: ${stringifyJSON(tailCounts)}\n` +
+				`  cases: ${stringifyJSON(caseCounts)}\n` +
 				`  audit: ${auditErrors.length} violation(s)`
 		)
 
 		if (auditErrors.length) {
-			throw new Error(`AUDIT FAILED — first violation: ${JSON.stringify(auditErrors[0])}`)
+			throw new Error(`AUDIT FAILED — first violation: ${stringifyJSON(auditErrors[0])}`)
 		}
 
 		return { emitted, skipped }

package/lib/recipes/po/box/cedex/au-nz.ts

@@ -0,0 +1,82 @@
+/**
+ * @copyright Sister Software
+ */
+
+import { isAuDeliveryService } from "@mailwoman/codex/au"
+import { isNZDeliveryService } from "@mailwoman/codex/nz"
+import { sample } from "@mailwoman/core/random"
+
+import { makeAuNZPoBoxPhrase } from "#recipes/po/box/cedex/phrases"
+import type { AUTuple, NZTuple, Rendered } from "#recipes/po/box/cedex/types"
+import {
+	AU_LEADERS_CURRENT,
+	AU_LEADERS_LEGACY,
+	NZ_LEADERS_COMMON,
+	NZ_LEADERS_RARE,
+	VENUES_EN,
+} from "#recipes/po/box/cedex/vocabulary"
+
+const AU_UPPER_LOCALITY_CUTOFF = 0.6,
+	AU_STANDARD_CUTOFF = 0.45,
+	AU_LABEL_CUTOFF = 0.6,
+	AU_NO_POSTCODE_CUTOFF = 0.75,
+	AU_BARE_CUTOFF = 0.88
+
+const NZ_STANDARD_CUTOFF = 0.55,
+	NZ_NO_POSTCODE_CUTOFF = 0.7,
+	NZ_BARE_CUTOFF = 0.85
+
+export function renderAUPoBox(random: () => number, tuple: AUTuple): Rendered {
+	const phrase = makeAuNZPoBoxPhrase(random, AU_LEADERS_CURRENT, AU_LEADERS_LEGACY, isAuDeliveryService)
+	const { locality, region, postcode } = tuple
+	const draw = random()
+	const location = draw < AU_UPPER_LOCALITY_CUTOFF ? locality.toUpperCase() : locality
+	const base = { po_box: phrase, locality: location, region, postcode }
+
+	if (draw < AU_STANDARD_CUTOFF)
+		return { fmt: "au-standard", raw: `${phrase}, ${location} ${region} ${postcode}`, components: base }
+
+	if (draw < AU_LABEL_CUTOFF) {
+		const upper = phrase.toUpperCase()
+
+		return {
+			fmt: "au-label-nocomma",
+			raw: `${upper} ${locality.toUpperCase()} ${region} ${postcode}`,
+			components: { po_box: upper, locality: locality.toUpperCase(), region, postcode },
+		}
+	}
+
+	if (draw < AU_NO_POSTCODE_CUTOFF)
+		return {
+			fmt: "au-no-postcode",
+			raw: `${phrase}, ${location} ${region}`,
+			components: { po_box: phrase, locality: location, region },
+		}
+
+	if (draw < AU_BARE_CUTOFF) return { fmt: "au-bare", raw: phrase, components: { po_box: phrase } }
+	const venue = sample(VENUES_EN, random)
+
+	return {
+		fmt: "au-venue",
+		raw: `${venue}, ${phrase}, ${location} ${region} ${postcode}`,
+		components: { venue, ...base },
+	}
+}
+
+export function renderNZPoBox(random: () => number, tuple: NZTuple): Rendered {
+	const phrase = makeAuNZPoBoxPhrase(random, NZ_LEADERS_COMMON, NZ_LEADERS_RARE, isNZDeliveryService)
+	const { locality, postcode } = tuple
+	const base = { po_box: phrase, locality, postcode }
+	const draw = random()
+
+	if (draw < NZ_STANDARD_CUTOFF)
+		return { fmt: "nz-standard", raw: `${phrase}, ${locality} ${postcode}`, components: base }
+
+	if (draw < NZ_NO_POSTCODE_CUTOFF)
+		return { fmt: "nz-no-postcode", raw: `${phrase}, ${locality}`, components: { po_box: phrase, locality } }
+
+	if (draw < NZ_BARE_CUTOFF) return { fmt: "nz-bare", raw: phrase, components: { po_box: phrase } }
+	const venue = sample(VENUES_EN, random)
+
+	return { fmt: "nz-venue", raw: `${venue}, ${phrase}, ${locality} ${postcode}`, components: { venue, ...base } }
+}

package/lib/recipes/po/box/cedex/ca.ts

@@ -0,0 +1,59 @@
+/**
+ * @copyright Sister Software
+ */
+
+import { sample } from "@mailwoman/core/random"
+
+import { makeCaPostcode, makePoBoxPhrase } from "#recipes/po/box/cedex/phrases"
+import type { Rendered } from "#recipes/po/box/cedex/types"
+import {
+	CA_EN_LEADERS,
+	CA_FR_LEADERS,
+	ON_FSA_LETTERS,
+	QC_FSA_LETTERS,
+	VENUES_FR,
+} from "#recipes/po/box/cedex/vocabulary"
+
+const CA_FR_GOLDEN_ORDER_CUTOFF = 0.4,
+	CA_FR_NATIVE_CUTOFF = 0.7,
+	CA_FR_BARE_CUTOFF = 0.85
+
+const CA_EN_STANDARD_CUTOFF = 0.5,
+	CA_EN_GOLDEN_ORDER_CUTOFF = 0.8
+
+export function renderCaFr(random: () => number, locality: string): Rendered {
+	const phrase = makePoBoxPhrase(random, CA_FR_LEADERS)
+	const postcode = makeCaPostcode(random, QC_FSA_LETTERS)
+	const components = { po_box: phrase, postcode, locality, region: "QC" }
+	const draw = random()
+
+	if (draw < CA_FR_GOLDEN_ORDER_CUTOFF)
+		return { fmt: "ca-fr-golden-order", raw: `${phrase}, ${postcode} ${locality}, QC`, components }
+
+	if (draw < CA_FR_NATIVE_CUTOFF)
+		return { fmt: "ca-fr-native", raw: `${phrase}, ${locality} QC ${postcode}`, components }
+
+	if (draw < CA_FR_BARE_CUTOFF) return { fmt: "ca-fr-bare", raw: phrase, components: { po_box: phrase } }
+	const venue = sample(VENUES_FR, random)
+
+	return {
+		fmt: "ca-fr-venue",
+		raw: `${venue}, ${phrase}, ${locality} QC ${postcode}`,
+		components: { venue, ...components },
+	}
+}
+
+export function renderCaEn(random: () => number, locality: string): Rendered {
+	const phrase = makePoBoxPhrase(random, CA_EN_LEADERS)
+	const postcode = makeCaPostcode(random, ON_FSA_LETTERS)
+	const components = { po_box: phrase, locality, region: "ON", postcode }
+	const draw = random()
+
+	if (draw < CA_EN_STANDARD_CUTOFF)
+		return { fmt: "ca-en-standard", raw: `${phrase}, ${locality}, ON ${postcode}`, components }
+
+	if (draw < CA_EN_GOLDEN_ORDER_CUTOFF)
+		return { fmt: "ca-en-golden-order", raw: `${phrase}, ${postcode} ${locality}, ON`, components }
+
+	return { fmt: "ca-en-bare", raw: phrase, components: { po_box: phrase } }
+}

package/lib/recipes/po/box/cedex/fr.ts

@@ -0,0 +1,77 @@
+/**
+ * @copyright Sister Software
+ */
+
+import { sample } from "@mailwoman/core/random"
+
+import { makeCedex, makePoBoxPhrase } from "#recipes/po/box/cedex/phrases"
+import type { FRTuple, Rendered } from "#recipes/po/box/cedex/types"
+import { FR_LEADERS, VENUES_FR } from "#recipes/po/box/cedex/vocabulary"
+
+const BP_TAIL_CUTOFF = 0.45,
+	BP_BARE_CUTOFF = 0.6,
+	BP_CEDEX_CUTOFF = 0.8
+
+const CEDEX_UPPER_LOCALITY_SHARE = 0.6,
+	CEDEX_LINE_CUTOFF = 0.4,
+	CEDEX_FULL_CUTOFF = 0.75,
+	CEDEX_GOLDEN_ORDER_CUTOFF = 0.85
+
+export function renderBpFr(random: () => number, tuple: FRTuple): Rendered {
+	const phrase = makePoBoxPhrase(random, FR_LEADERS)
+	const { locality, postcode } = tuple
+	const location = random() < 0.5 ? locality.toUpperCase() : locality
+	const draw = random()
+
+	if (draw < BP_TAIL_CUTOFF)
+		return {
+			fmt: "bp-tail",
+			raw: `${phrase}, ${postcode} ${location}`,
+			components: { po_box: phrase, postcode, locality: location },
+		}
+
+	if (draw < BP_BARE_CUTOFF) return { fmt: "bp-bare", raw: phrase, components: { po_box: phrase } }
+
+	if (draw < BP_CEDEX_CUTOFF) {
+		const cedex = makeCedex(random)
+		const upperLocality = locality.toUpperCase()
+
+		return {
+			fmt: "bp-cedex",
+			raw: `${phrase}, ${postcode} ${upperLocality} ${cedex}`,
+			components: { po_box: phrase, postcode, locality: upperLocality, cedex },
+		}
+	}
+
+	const venue = sample(VENUES_FR, random)
+
+	return {
+		fmt: "bp-venue",
+		raw: `${venue}, ${phrase}, ${postcode} ${location}`,
+		components: { venue, po_box: phrase, postcode, locality: location },
+	}
+}
+
+export function renderCedexFr(random: () => number, tuple: FRTuple): Rendered {
+	const cedex = makeCedex(random)
+	const { house_number, street, locality, postcode } = tuple
+	const location = random() < CEDEX_UPPER_LOCALITY_SHARE ? locality.toUpperCase() : locality
+	const line = { postcode, locality: location, cedex }
+	const draw = random()
+
+	if (draw < CEDEX_LINE_CUTOFF) return { fmt: "cedex-line", raw: `${postcode} ${location} ${cedex}`, components: line }
+
+	if (draw < CEDEX_FULL_CUTOFF)
+		return {
+			fmt: "cedex-full",
+			raw: `${house_number} ${street}, ${postcode} ${location} ${cedex}`,
+			components: { house_number, street, ...line },
+		}
+
+	if (draw < CEDEX_GOLDEN_ORDER_CUTOFF)
+		return { fmt: "cedex-golden-order", raw: `${postcode} ${cedex} ${location}`, components: line }
+
+	const venue = sample(VENUES_FR, random)
+
+	return { fmt: "cedex-venue", raw: `${venue}, ${postcode} ${location} ${cedex}`, components: { venue, ...line } }
+}

package/lib/recipes/po/box/cedex/phrases.ts

@@ -0,0 +1,109 @@
+/**
+ * @copyright Sister Software
+ */
+
+import { normalizeCaPostalCode } from "@mailwoman/codex/ca"
+import { isCedex } from "@mailwoman/codex/fr"
+import { isNZDeliveryService } from "@mailwoman/codex/nz"
+import { isUSPoBoxDesignator, matchPOBox } from "@mailwoman/codex/us"
+import { sample } from "@mailwoman/core/random"
+
+import { CA_INTERIOR_LETTERS } from "#recipes/po/box/cedex/vocabulary"
+import { maybeNoisifyBoxNumber } from "#synthesizers/po-box"
+import { tieredNumber } from "#synthesizers/utils"
+
+const BOX_TWO_DIGIT_CUTOFF = 0.3
+const BOX_THREE_DIGIT_CUTOFF = 0.7
+const BOX_FOUR_DIGIT_CUTOFF = 0.95
+const TEMPLATE_CASE_CUTOFF = 0.7
+const UPPER_CASE_CUTOFF = 0.92
+const RARE_LEADER_SHARE = 0.1
+const CEDEX_UPPER_CUTOFF = 0.6
+const CEDEX_TITLE_CUTOFF = 0.9
+const CEDEX_UNNUMBERED_SHARE = 0.2
+
+const pickBoxNumber = (random: () => number): string =>
+	tieredNumber(random, [
+		{ cutoff: BOX_TWO_DIGIT_CUTOFF, base: 1, span: 99 },
+		{ cutoff: BOX_THREE_DIGIT_CUTOFF, base: 100, span: 900 },
+		{ cutoff: BOX_FOUR_DIGIT_CUTOFF, base: 1000, span: 9000 },
+		{ base: 10_000, span: 90_000 },
+	])
+
+const caseDial = (random: () => number, value: string): string => {
+	const draw = random()
+
+	return draw < TEMPLATE_CASE_CUTOFF ? value : draw < UPPER_CASE_CUTOFF ? value.toUpperCase() : value.toLowerCase()
+}
+
+export function makePoBoxPhrase(
+	random: () => number,
+	leaders: ReadonlyArray<string>,
+	rareLeaders?: ReadonlyArray<string>
+): string {
+	let leader = sample(leaders, random)
+
+	if (rareLeaders && random() < RARE_LEADER_SHARE) {
+		leader = sample(rareLeaders, random)
+	}
+
+	const number = maybeNoisifyBoxNumber(pickBoxNumber(random), random)
+	const phrase = leader === "#" ? `#${number}` : `${caseDial(random, leader)} ${number}`
+
+	if (isUSPoBoxDesignator(leader) && /^[\dA-Za-z][\dA-Za-z-]*$/.test(number) && !matchPOBox(phrase))
+		throw new Error(`generated a po_box phrase the codex matcher rejects: "${phrase}"`)
+
+	return phrase
+}
+
+export function makeCedex(random: () => number): string {
+	const draw = random()
+	const word = draw < CEDEX_UPPER_CUTOFF ? "CEDEX" : draw < CEDEX_TITLE_CUTOFF ? "Cedex" : "cedex"
+	let phrase = word
+
+	if (random() >= CEDEX_UNNUMBERED_SHARE) {
+		const number = 1 + Math.floor(random() * 20)
+		phrase = `${word} ${random() < 0.5 ? String(number).padStart(2, "0") : String(number)}`
+	}
+
+	if (!isCedex(phrase)) throw new Error(`makeCedex emitted a phrase the codex matcher rejects: "${phrase}"`)
+
+	return phrase
+}
+
+export function makeAuNZPoBoxPhrase(
+	random: () => number,
+	leaders: ReadonlyArray<string>,
+	rareLeaders: ReadonlyArray<string>,
+	validate: (input: unknown) => boolean
+): string {
+	let leader = sample(leaders, random)
+
+	if (random() < RARE_LEADER_SHARE) {
+		leader = sample(rareLeaders, random)
+	}
+
+	let number = maybeNoisifyBoxNumber(pickBoxNumber(random), random)
+
+	if (leader === "CMB" && validate === isNZDeliveryService) {
+		number = `B${number}`
+	}
+
+	const phrase = `${caseDial(random, leader)} ${number}`
+	const cleanID = validate === isNZDeliveryService ? /^[\dA-Za-z]+$/ : /^[\dA-Za-z][\dA-Za-z-]*$/
+
+	if (cleanID.test(number) && !validate(phrase))
+		throw new Error(`generated a phrase the codex matcher rejects: "${phrase}"`)
+
+	return phrase
+}
+
+export function makeCaPostcode(random: () => number, fsaLetters: string[]): string {
+	const letter = () => CA_INTERIOR_LETTERS[Math.floor(random() * CA_INTERIOR_LETTERS.length)]!
+	const digit = () => String(Math.floor(random() * 10))
+	const postcode = `${sample(fsaLetters, random)}${digit()}${letter()} ${digit()}${letter()}${digit()}`
+
+	if (!normalizeCaPostalCode(postcode)) throw new Error(`generated an invalid CA postcode: ${postcode}`)
+
+	return postcode
+}