@mailwoman/corpus 9.2.0 → 9.3.0

package/src/shard-recipes/fr-order.ts

@@ -1,258 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   `fr-order` shard recipe — French reversed-order coverage (#560). Reads REAL OpenAddresses FR
- *   tuples (`fr/countrywide.csv` from the cached zip), then for each row picks — by
- *   `--reversed-fraction` (default 0.5) — whether to render in CANONICAL French order
- *   (number-street, postcode-city) or one of four REVERSED / postcode-first variants the
- *   v4.4.0→v0.5.0 regression exposed (the model misses house_number in every reversed one):
- *
- *   - A: "47110 Sainte-Livrade-sur-Lot, 69 Allée du Bugatel" (postcode city, HN street)
- *   - B: "Sainte-Livrade-sur-Lot, 47110, 619 Impasse de la Rose" (city, postcode, HN street)
- *   - C: "Sainte-Livrade-sur-Lot 59 bis Rue des Ecuries 47110" (city HN street postcode — NO commas)
- *   - D: "47110, 6 rue de la république, Sainte-Livrade-sur-Lot" (postcode, HN street, city)
- *
- *   Sub-modes ride alongside order: `bis`/`ter`/`quater` ordinal suffixes in house_number, and
- *   ALL-CAPS locality. `--golden` emits a held-out reversed-order eval slice with a different
- *   seed.
- *
- *   The inline synthesis (the OA-CSV reader, the ordinal/all-caps tables, the canonical + reversed
- *   renderers) is ported faithfully from scripts/build-fr-order-shard.mjs. This is a
- *   `generate`-mode recipe that still reads REAL tuples off disk — `--count` bounds the OUTPUT, not
- *   the input. The passed `random` (the framework LCG) is consumed in the exact call order the
- *   legacy script used.
- *
- *   NOT ported (diagnostic-only, no effect on emitted bytes): the post-run `runSpanCheck` self-check
- *   (it reads the finished file back with a separate PRNG and prints to stderr; the recipe's output
- *   stream is still open during `run`), and the dead `renderReversed` helper (the legacy `main`
- *   inlined the variant logic and never called it).
- */
-
-import { isPresent } from "@mailwoman/core/objects"
-import type { ComponentTag } from "@mailwoman/core/types"
-import { dataRootPath } from "@mailwoman/core/utils"
-
-import { stableSourceID } from "#adapters/utils"
-import type { CanonicalRow } from "#types"
-import { alignRow } from "#utils"
-
-import { makeMulberry32, readZippedCSVRecords, type ShardRecipe } from "./scaffold.ts"
-
-/* oxlint-disable sister-software/no-unnamed-threshold -- the bare decimals below are weighted-sampler
-   cutoffs, not thresholds: `const r = random()` followed by a cascade of `r < 0.4` branches IS the
-   output distribution, and reading the cascade top-to-bottom is how you see it. Naming each cutoff
-   would hide the distribution behind a wall of identifiers. Genuine thresholds in these files are
-   extracted as named constants above. */
-
-const SOURCE = { zip: dataRootPath("oa-cache", "fr__countrywide.zip"), csv: "fr/countrywide.csv" }
-
-/**
- * Ordinal suffixes used in French house numbers (BAN corpus), to cover the "8 bis" sub-mode.
- */
-const ORDINAL_SUFFIXES: readonly string[] = ["bis", "ter", "quater"]
-/**
- * Probability that a row gets an ordinal suffix injected (matches the golden's ~10-15% rate).
- */
-const ORDINAL_PROB = 0.12
-/**
- * Probability that a locality renders ALL-CAPS (another sub-mode: "SAINTE-LIVRADE-SUR-LOT").
- */
-const ALLCAPS_PROB = 0.1
-
-/**
- * A real FR tuple read out of the cached OA zip.
- */
-interface FrTuple {
-	house_number: string
-	street: string
-	locality: string
-	postcode: string
-}
-
-/**
- * Stream FR tuples out of the cached OA zip. The countrywide extract is GB-scale, so this reads only as far as `limit`
- * distinct tuples — the `break` closes the reader and releases the archive. Only keeps rows with a house_number (the
- * shard's core signal) and a postcode (required for reversed-order rendering to be meaningful).
- */
-async function readTuples(limit: number): Promise<FrTuple[]> {
-	const tuples: FrTuple[] = []
-	const seen = new Set<string>()
-
-	for await (const row of readZippedCSVRecords(SOURCE.zip, SOURCE.csv)) {
-		if (tuples.length >= limit) break
-		const street = row.street ?? ""
-		const locality = row.city ?? ""
-		const house_number = row.number ?? ""
-		const postcode = row.postcode ?? ""
-
-		// Require all four fields: HN is the signal; postcode drives reversed-order variants.
-		if (!street || !locality || !house_number || !postcode) continue
-		const key = `${house_number}|${street}|${locality}|${postcode}`.toLowerCase()
-
-		if (seen.has(key)) continue
-		seen.add(key)
-		tuples.push({ house_number, street, locality, postcode })
-	}
-
-	return tuples
-}
-
-/**
- * Optionally augment a house_number with a French ordinal suffix ("59 bis", "4 ter"). Appended with a space so it forms
- * one multi-token house_number string that alignRow can still locate verbatim.
- */
-function maybeAddOrdinal(random: () => number, house_number: string): string {
-	if (random() >= ORDINAL_PROB) return house_number
-	const suffix = ORDINAL_SUFFIXES[Math.floor(random() * ORDINAL_SUFFIXES.length)]!
-
-	// Vary suffix case: "bis" (lower) vs "BIS" (upper) — a real-world split in the golden.
-	return `${house_number} ${random() < 0.5 ? suffix : suffix.toUpperCase()}`
-}
-
-/**
- * Render a tuple in CANONICAL French order: "9 Rue de la Promenade, 01200 Villes".
- */
-function renderCanonical(
-	hn: string,
-	street: string,
-	postcode: string,
-	locality: string
-): { raw: string; components: Partial<Record<ComponentTag, string>> } {
-	const raw = `${hn} ${street}, ${postcode} ${locality}`
-
-	return { raw, components: { house_number: hn, street, postcode, locality } }
-}
-
-/**
- * Shard 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.
- */
-export const frOrderRecipe: ShardRecipe = {
-	name: "fr-order",
-	description: "French reversed-order rows (#560): real OA FR tuples rendered canonical + 4 postcode-first variants",
-	mode: "generate",
-	options: [
-		{ flag: "--reversed-fraction <p>", description: "Fraction rendered reversed-order. Default 0.5" },
-		{ flag: "--golden", description: "Emit the held-out reversed-order eval slice" },
-	],
-	async run(opts, write) {
-		if (opts.count == null) throw new Error("fr-order recipe requires --count <N>")
-		const count = opts.count
-		// Legacy build-fr-order-shard.mjs seeded mulberry32 with the raw seed: `const random = mulberry32(opts.seed)`.
-		// (The omitted diagnostic runSpanCheck used a separate mulberry32(opts.seed + 1) — not part of generation.)
-		const random = makeMulberry32(opts.seed)
-		const source = opts.sourceName ?? "synth-fr-order"
-		const reversedFraction = opts.reversedFraction ?? 0.5
-
-		// Over-read from the CSV so the dedup + filter pass can fill `count` rows.
-		const poolLimit = Math.max(count * 8, 40_000)
-		const pool = await readTuples(poolLimit)
-
-		console.error(`  ${SOURCE.csv}: ${pool.length} unique tuples (capped read)`)
-
-		if (!pool.length) {
-			throw new Error(`No FR tuples found — is ${SOURCE.zip} present?`)
-		}
-
-		let emitted = 0
-		let skipped = 0
-		let guard = 0
-		const N = pool.length
-
-		while (emitted < count && guard++ < count * 10) {
-			const base = pool[Math.floor(random() * N)]!
-			const { street, postcode } = base
-			const locality = random() < ALLCAPS_PROB ? base.locality.toUpperCase() : base.locality
-			const house_number = maybeAddOrdinal(random, base.house_number)
-
-			// Pick canonical vs reversed by --reversed-fraction.
-			const isReversed = random() < reversedFraction
-
-			let rendered: { raw: string; components: Partial<Record<ComponentTag, string>> }
-
-			if (isReversed) {
-				const variantRoll = random()
-				let raw: string
-
-				if (variantRoll < 0.25) {
-					// Variant A: postcode+city as a unit, then HN+street
-					raw = `${postcode} ${locality}, ${house_number} ${street}`
-				} else if (variantRoll < 0.5) {
-					// Variant B: city, then postcode, then HN+street (comma-separated, postcode isolated)
-					raw = `${locality}, ${postcode}, ${house_number} ${street}`
-				} else if (variantRoll < 0.75) {
-					// Variant C: no commas — locality HN street postcode (the "run-together" format)
-					raw = `${locality} ${house_number} ${street} ${postcode}`
-				} else {
-					// Variant D: postcode, HN+street, city (reversed top-to-bottom)
-					raw = `${postcode}, ${house_number} ${street}, ${locality}`
-				}
-
-				rendered = { raw, components: { house_number, street, postcode, locality } }
-			} else {
-				rendered = renderCanonical(house_number, street, postcode, locality)
-			}
-
-			const { raw, components } = rendered
-
-			// Safety check: every component must appear verbatim in raw (alignment precondition).
-			const componentValues = Object.values(components).filter(isPresent)
-
-			if (!componentValues.every((v) => raw.includes(v))) {
-				skipped++
-
-				continue
-			}
-
-			// --golden: emit per-locale-f1 eval rows ({raw, components, country:"FR"}).
-			if (opts.golden) {
-				write(JSON.stringify({ raw, components, country: "FR" }) + "\n")
-
-				emitted++
-
-				continue
-			}
-
-			const sourceID = stableSourceID(source, {
-				street: components.street,
-				house_number: components.house_number,
-				locality: components.locality,
-				postcode: components.postcode,
-			})
-
-			const canonical: CanonicalRow = {
-				raw,
-				components,
-				country: "FR",
-				locale: "fr-FR",
-				source,
-				source_id: sourceID,
-				corpus_version: "0.5.0",
-				license: "OpenAddresses FR countrywide tuples, rendered canonical + reversed-order — see ingest SOURCE",
-			}
-
-			const aligned = alignRow(canonical)
-
-			if (aligned.kind !== "labeled" || !aligned.row) {
-				skipped++
-
-				continue
-			}
-
-			write(
-				JSON.stringify({
-					...aligned.row,
-					synth_method: "fr-order",
-					synth_order: isReversed ? "reversed" : "canonical",
-					synth_base_id: null,
-				}) + "\n"
-			)
-
-			emitted++
-		}
-
-		return { emitted, skipped }
-	},
-}

package/src/shard-recipes/german.ts

@@ -1,170 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   `german` shard recipe — German coverage rows from REAL OpenAddresses tuples (Berlin + Saxony,
- *   cached zips). Each sampled tuple is rendered via {@link synthesizeGermanRow} in BOTH orders —
- *   `--intl-fraction` (default 0.4) in international order (house-first / postcode-after-city), the
- *   rest in idiomatic German order — then aligned to BIO. Generate-mode: it builds a tuple pool
- *   from the cached zips, then draws `--count` rows from it with the passed `random` (so the emit
- *   stream matches the legacy reservoir-sample loop). Ported from scripts/build-german-shard.mjs.
- *
- *   ORDER ROBUSTNESS (2026-06-06): mixing the two renderings stops a native-only shard from teaching
- *   German order so well it reads the US/feed-order eval as a "collapse". See
- *   docs/articles/evals/resolver-geo/2026-06-06-anchor-pilot.md (the order-artifact correction).
- */
-
-import { dataRootPath } from "@mailwoman/core/utils"
-
-import { stableSourceID } from "#adapters/utils"
-import { synthesizeGermanRow, type LocaleBaseTuple } from "#synthesizers/german"
-import { alignRow } from "#utils"
-
-import { makeMulberry32, readZippedCSVRecords, type ShardRecipe } from "./scaffold.ts"
-
-/**
- * A German OA source (cached zip) + the Bundesland the file covers (OA's REGION column is empty for DE).
- */
-interface GermanSource {
-	zip: string
-	csv: string
-	region: string
-}
-
-/**
- * `region` is the Bundesland the source covers. OA's REGION column is empty for DE, but the region is implied by the
- * per-state file — the international order needs it for the "City, Region Postcode" tail (v0.9.3 / #327). berlin.csv →
- * Berlin (a city-state, region==locality); sn/statewide → Sachsen.
- */
-const SOURCES: GermanSource[] = [
-	{ zip: dataRootPath("oa-cache", "de__berlin.zip"), csv: "de/berlin.csv", region: "Berlin" },
-	{ zip: dataRootPath("oa-cache", "de__sn__statewide.zip"), csv: "de/sn/statewide.csv", region: "Sachsen" },
-]
-
-/**
- * Stream real German tuples out of a cached OA zip.
- */
-async function readGermanTuples(source: GermanSource): Promise<LocaleBaseTuple[]> {
-	const tuples: LocaleBaseTuple[] = []
-	const seen = new Set<string>()
-
-	for await (const row of readZippedCSVRecords(source.zip, source.csv)) {
-		const street = row.street ?? ""
-		const locality = row.city ?? ""
-
-		if (!street || !locality) continue
-		const house_number = row.number ?? ""
-		const postcode = row.postcode ?? ""
-		// OA's REGION column is empty for DE — fall back to the source's Bundesland (set per file).
-		const region = row.region || source.region || ""
-		const key = `${house_number}|${street}|${locality}|${postcode}`.toLowerCase()
-
-		if (seen.has(key)) continue
-		seen.add(key)
-		tuples.push({ house_number, street, locality, region, postcode })
-	}
-
-	return tuples
-}
-
-/**
- * Shard 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.
- */
-export const germanRecipe: ShardRecipe = {
-	name: "german",
-	description: "German coverage rows from real OA tuples (Berlin/Saxony), both orders → synthesizeGermanRow",
-	mode: "generate",
-	options: [{ flag: "--intl-fraction <f>", description: "Fraction rendered international order. Default 0.4" }],
-	async run(opts, write) {
-		// Emit PRNG: the legacy build-german-shard.mjs seeded mulberry32(opts.seed).
-		const random = makeMulberry32(opts.seed)
-		const source = opts.sourceName ?? "synth-german"
-		const intlFraction = opts.intlFraction ?? 0.4
-
-		if (!(intlFraction >= 0 && intlFraction <= 1)) {
-			throw new Error(`--intl-fraction must be in [0, 1], got ${intlFraction}`)
-		}
-
-		const count = opts.count ?? 4000
-
-		// Pool real tuples from every German source, then sample `count` rows from it.
-		const pool: LocaleBaseTuple[] = []
-
-		for (const s of SOURCES) {
-			const t = await readGermanTuples(s)
-
-			console.error(`  ${s.csv}: ${t.length} unique tuples`)
-
-			for (const x of t) {
-				pool.push(x)
-			} // NOT pool.push(...t) — spreading ~840K args overflows the stack
-		}
-
-		if (!pool.length) {
-			throw new Error(`No German tuples found — are the cached zips present in ${dataRootPath("oa-cache")}?`)
-		}
-
-		let emitted = 0
-		let skipped = 0
-		let guard = 0
-		const N = pool.length
-
-		while (emitted < count && guard++ < count * 6) {
-			const base = pool[Math.floor(random() * N)]!
-			// Per-row order: `--intl-fraction` of rows render house-first / postcode-after-city (the US/feed
-			// layout), the rest in idiomatic German order. Same components either way.
-			const order = random() < intlFraction ? "international" : "native"
-			const synth = synthesizeGermanRow(base, { random, order })
-
-			if (!synth) {
-				skipped++
-
-				continue
-			}
-
-			// --golden: emit per-locale-f1 eval rows ({raw, components}) instead of aligned BIO. `order`
-			// rides along so the eval can stratify native vs international.
-			if (opts.golden) {
-				write(JSON.stringify({ raw: synth.raw, components: synth.components, country: "DE", order }) + "\n")
-
-				emitted++
-
-				continue
-			}
-
-			const sourceID = stableSourceID(source, {
-				street: synth.components.street,
-				house_number: synth.components.house_number,
-				locality: synth.components.locality,
-				postcode: synth.components.postcode,
-			})
-
-			const canonical = {
-				raw: synth.raw,
-				components: synth.components,
-				country: "DE",
-				locale: synth.locale,
-				source,
-				source_id: sourceID,
-				corpus_version: "0.4.0",
-				license: `OpenAddresses DE (Berlin/Saxony) tuples, rendered ${order}-order — see ingest SOURCES`,
-			}
-
-			const aligned = alignRow(canonical as Parameters<typeof alignRow>[0])
-
-			if (aligned.kind !== "labeled" || !aligned.row) {
-				skipped++
-
-				continue
-			}
-
-			write(JSON.stringify({ ...aligned.row, synth_method: "german", synth_order: order, synth_base_id: null }) + "\n")
-
-			emitted++
-		}
-
-		return { emitted, skipped }
-	},
-}

package/src/shard-recipes/house-venue.ts

@@ -1,88 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   `house-venue` shard recipe — synthetic house_number+venue+street co-occurrence rows: tuples →
- *   {@link synthesizeHouseVenueRow} → aligned LabeledRow. The v0.6.3 corrective companion to the
- *   no-street shard: every row carries BOTH house_number AND venue, restoring the house_number
- *   signal that no-street's distributional shift cost the model. Ported from
- *   scripts/build-house-venue-shard.mjs.
- */
-
-import { synthesizeHouseVenueRow, type HouseVenueBaseTuple } from "#synthesizers/house-venue"
-
-import { alignAndWrite, makeLcg, readTuples, shardSourceID, type ShardRecipe } from "./scaffold.ts"
-
-const LICENSE = "Synthetic — derived from CC-BY / public-domain input tuples"
-
-/**
- * Shard 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.
- */
-export const houseVenueRecipe: ShardRecipe = {
-	name: "house-venue",
-	description: "House_number+venue co-occurrence rows: tuples → synthesizeHouseVenueRow → aligned LabeledRow",
-	mode: "tuples",
-	async run(opts, write) {
-		if (!opts.input) throw new Error("house-venue recipe requires --input <tuples.jsonl>")
-		// Legacy build-house-venue-shard.mjs seeded the LCG via makeRandom(opts.seed) (s = seed).
-		const random = makeLcg(opts.seed)
-		const source = opts.sourceName ?? "synth-house-venue"
-		let read = 0
-		let emitted = 0
-		let skipped = 0
-
-		for await (const tuple of readTuples(opts.input)) {
-			read++
-
-			// FR renders without a region (postcode-before-locality tail — the run-2 contingency), so
-			// an empty region is valid there and stays required everywhere else.
-			if (!tuple.locality || !tuple.postcode || !tuple.country || (!tuple.region && tuple.country !== "FR")) {
-				skipped++
-
-				continue
-			}
-
-			for (let v = 0; v < opts.variants; v++) {
-				const synth = synthesizeHouseVenueRow(tuple as HouseVenueBaseTuple, { random })
-
-				if (!synth) {
-					skipped++
-
-					continue
-				}
-
-				const ok = alignAndWrite(
-					write,
-					{
-						raw: synth.raw,
-						components: synth.components,
-						country: tuple.country,
-						locale: synth.locale,
-						source,
-						source_id: shardSourceID(source, {
-							locality: tuple.locality,
-							region: tuple.region,
-							postcode: tuple.postcode,
-							country: tuple.country,
-							template: synth.template,
-							v: String(v),
-						}),
-						corpus_version: "0.4.0",
-						license: LICENSE,
-					},
-					synth.template
-				)
-
-				if (ok) {
-					emitted++
-				} else {
-					skipped++
-				}
-			}
-		}
-
-		return { read, emitted, skipped }
-	},
-}

package/src/shard-recipes/index.ts

@@ -1,95 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   The synthetic-corpus SHARD RECIPE registry. Each recipe ({@link ShardRecipe}) is what one legacy
- *   `build-*-shard.mjs` script used to be; the `mailwoman corpus shard <recipe>` command dispatches
- *   to them. A new shard is a new entry here, not a new script.
- */
-
-import { anchorAbsorptionRecipe } from "./anchor-absorption.ts"
-import { bareCountryRecipe } from "./bare-country.ts"
-import { boundaryStressRecipe } from "./boundary-stress.ts"
-import { countryBalancedRecipe } from "./country-balanced.ts"
-import { czPcFirstPrepositionRecipe } from "./cz-pcfirst-preposition.ts"
-import { frAdminSplitRecipe } from "./fr-admin-split.ts"
-import { frBareStreetRecipe } from "./fr-bare-street.ts"
-import { frFragmentRecipe } from "./fr-fragment.ts"
-import { frLieuditRecipe } from "./fr-lieudit.ts"
-import { frOrderRecipe } from "./fr-order.ts"
-import { germanRecipe } from "./german.ts"
-import { houseVenueRecipe } from "./house-venue.ts"
-import { intersectionRecipe } from "./intersection.ts"
-import { localeRecipe } from "./locale.ts"
-import { nlPostcodeRecipe } from "./nl-postcode.ts"
-import { noFragmentRecipe } from "./no-fragment.ts"
-import { noStreetLedRecipe } from "./no-street-led.ts"
-import { noStreetRecipe } from "./no-street.ts"
-import { poBoxCedexRecipe } from "./po-box-cedex.ts"
-import { poBoxRecipe } from "./po-box.ts"
-import { reviewedPostcodeTailRecipe } from "./reviewed-postcode-tail.ts"
-import type { ShardRecipe } from "./scaffold.ts"
-import { siBareVillageRecipe } from "./si-bare-village.ts"
-import { streetAffixRecipe, suffixBoundaryRecipe } from "./street-affix.ts"
-import { streetBareRecipe } from "./street-bare.ts"
-import { streetRecipe } from "./street.ts"
-import { subVenueRecipe } from "./sub-venue.ts"
-import { trailingRegionRecipe } from "./trailing-region.ts"
-import { unitRecipe } from "./unit.ts"
-
-export * from "./scaffold.ts"
-
-/**
- * Every registered recipe, in display order.
- */
-const RECIPES: readonly ShardRecipe[] = [
-	bareCountryRecipe,
-	trailingRegionRecipe,
-	reviewedPostcodeTailRecipe,
-	streetRecipe,
-	streetBareRecipe,
-	streetAffixRecipe,
-	suffixBoundaryRecipe,
-	noStreetRecipe,
-	houseVenueRecipe,
-	poBoxRecipe,
-	poBoxCedexRecipe,
-	unitRecipe,
-	intersectionRecipe,
-	germanRecipe,
-	localeRecipe,
-	frOrderRecipe,
-	frAdminSplitRecipe,
-	frBareStreetRecipe,
-	frFragmentRecipe,
-	frLieuditRecipe,
-	czPcFirstPrepositionRecipe,
-	nlPostcodeRecipe,
-	noStreetLedRecipe,
-	noFragmentRecipe,
-	siBareVillageRecipe,
-	countryBalancedRecipe,
-	boundaryStressRecipe,
-	anchorAbsorptionRecipe,
-	subVenueRecipe,
-]
-
-/**
- * Recipe name → recipe.
- */
-export const SHARD_RECIPES: ReadonlyMap<string, ShardRecipe> = new Map(RECIPES.map((r) => [r.name, r]))
-
-/**
- * Look up a recipe by its `<recipe>` name.
- */
-export function getShardRecipe(name: string): ShardRecipe | undefined {
-	return SHARD_RECIPES.get(name)
-}
-
-/**
- * All recipes (for `--list` / help).
- */
-export function listShardRecipes(): readonly ShardRecipe[] {
-	return RECIPES
-}