@mailwoman/corpus 7.2.0 → 7.3.0

package/src/shard-recipes/fr-admin-split.ts

@@ -0,0 +1,212 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `fr-admin-split` shard recipe — the FR admin-split coverage shard (night 2026-06-19,
+ *   surpass-v1.5.0). Teaches the model to SPLIT the département out of the locality on
+ *   bare/space/comma-delimited French place rows — the admin-deciding failure class the pre-GPU
+ *   self-validation proved moves the resolved coordinate (collision communes −61%; see
+ *   docs/articles/evals/experiments/2026-06-19-fr-admin-split-prevalidation.md). Ported from
+ *   scripts/build-fr-admin-split-shard.mjs.
+ *
+ *   Failure shapes (the model currently mis-handles all of these):
+ *
+ *   - `Thauron, Creuse` → région dropped to null (the comma+full-name miss)
+ *   - `Montredon, Lozère` → région = "ère" (the diacritic subword split, #727)
+ *   - (AU analog) `CANBERRA ACT` → the space-delimited admin fuse
+ *
+ *   The département is the essential admin unit for FR postal geography and maps to the `region`
+ *   component tag in our schema. We derive it DETERMINISTICALLY from the real postcode via codex
+ *   `departementForCodePostal` (first two digits = département) — salvage-first, no re-derived
+ *   table.
+ *
+ *   Data (`--communes`, opts.communes): REAL BAN (Base Adresse Nationale) commune+postcode+coord
+ *   tuples, one per line, TAB-separated `commune <TAB> postcode <TAB> lon <TAB> lat`. Build the
+ *   input TSV once from the BAN staging CSV (see the legacy script header). Anchor-ON by
+ *   construction: rows carry a REAL postcode token in `raw` + a `postcode` component, so the
+ *   training loader paints the anchor feature onto that span automatically. The trailing-postcode
+ *   anchor REINFORCES the FR split (FR postcode is trailing, unlike German PLZ-leading — the v0.9.2
+ *   scar is positional, not universal).
+ */
+
+import { departementForCodePostal } from "@mailwoman/codex/fr"
+import type { ComponentTag } from "@mailwoman/core/types"
+import { CSVSpliterator, Delimiters } from "spliterator"
+
+import { stableSourceID } from "../adapter.ts"
+import { alignRow } from "../align.ts"
+import type { CanonicalRow } from "../types.ts"
+import { makeMulberry32, type ShardRecipe } from "./scaffold.ts"
+
+const DEFAULT_COMMUNES = "/tmp/reg/fr-communes.tsv"
+const LICENSE = "BAN (Base Adresse Nationale) commune+postcode tuples, rendered admin-split — see ingest SOURCE"
+
+/** One distinct commune row from the TSV, with the département derived from its postcode. */
+interface CommuneRow {
+	commune: string
+	postcode: string
+	departement: string
+	lon: string | undefined
+	lat: string | undefined
+}
+
+/** One rendered admin-split variant. */
+interface AdminSplitVariant {
+	raw: string
+	components: Partial<Record<ComponentTag, string>>
+	order: string
+}
+
+/** Read the distinct commune TSV (commune, postcode, lon, lat); derive the département name. */
+async function readCommunes(path: string): Promise<CommuneRow[]> {
+	const rows: CommuneRow[] = []
+
+	// The TSV is headerless — every line is a commune tuple — so `header: false` keeps row 1 instead of
+	// spending it on column names. Source is repo-generated (LF); even under CRLF only the trailing `lat`
+	// column carries a CR, and it's consumed via `Number()` (whitespace-trimming), so it stays harmless.
+	for await (const [commune, postcode, lon, lat] of CSVSpliterator.fromAsync(path, {
+		columnDelimiter: Delimiters.Tab,
+		header: false,
+	})) {
+		if (!commune || !postcode) continue
+		const dep = departementForCodePostal(postcode)
+
+		if (!dep) continue // bad/unmappable postcode — skip (CEDEX, etc.)
+		// Substring invariant: a département whose name isn't a clean token (none are) or a commune
+		// containing the département name would confuse alignment — both are vanishingly rare here.
+		rows.push({ commune, postcode, departement: dep.name, lon, lat })
+	}
+
+	return rows
+}
+
+/**
+ * Render one admin-split variant. The CORE teaching signal: the département, even as a full word after a comma or a
+ * space, is `region` — never folded into `locality`. Variants 1-3 are the failure class; 4-5 are canonical-FR
+ * preservation so the model doesn't over-fire region on every trailing token (and the bare commune still resolves).
+ */
+function render(random: () => number, c: CommuneRow): AdminSplitVariant {
+	const r = random()
+	const loc = random() < 0.1 ? c.commune.toUpperCase() : c.commune
+	const dep = c.departement
+	const pc = c.postcode
+	let out: AdminSplitVariant
+
+	if (r < 0.25) {
+		// 1. bare comma, NO postcode — the Thauron/#727 shape (anchor off)
+		out = { raw: `${loc}, ${dep}`, components: { locality: loc, region: dep }, order: "bare-comma" }
+	} else if (r < 0.5) {
+		// 2. bare comma + postcode — anchor ON
+		out = {
+			raw: `${loc}, ${dep} ${pc}`,
+			components: { locality: loc, region: dep, postcode: pc },
+			order: "bare-comma-pc",
+		}
+	} else if (r < 0.7) {
+		// 3. space-delimited admin (the AU `CANBERRA ACT` fuse applied to FR) — anchor ON
+		out = { raw: `${loc} ${dep} ${pc}`, components: { locality: loc, region: dep, postcode: pc }, order: "space-pc" }
+	} else if (r < 0.85) {
+		// 4. canonical FR postcode-first (NO département) — preservation, anchor ON
+		out = { raw: `${pc} ${loc}`, components: { postcode: pc, locality: loc }, order: "canonical-pc-first" }
+	} else {
+		// 5. commune + postcode (NO département) — preservation, anchor ON
+		out = { raw: `${loc} ${pc}`, components: { locality: loc, postcode: pc }, order: "commune-pc" }
+	}
+
+	// fr.country preservation (the v1.8.0 #728 finding): the v1.8.0 shard's bare rows carried NO country
+	// token, so the model under-emitted country on FR (fr.country −3.5pp). ~20% of rows now append an
+	// explicit "France" + a `country` component — the model relearns to emit country WHEN the token is
+	// present without over-firing it on the (still-majority) country-less rows. Substring invariant holds.
+	if (random() < 0.2) {
+		out = {
+			raw: `${out.raw}, France`,
+			components: { ...out.components, country: "France" },
+			order: `${out.order}+fr`,
+		}
+	}
+
+	return out
+}
+
+export const frAdminSplitRecipe: ShardRecipe = {
+	name: "fr-admin-split",
+	description: "FR admin-split rows: BAN communes → split département into `region` (+ canonical-FR preservation)",
+	mode: "generate",
+	options: [
+		{ flag: "--communes <tsv>", description: "BAN commune+postcode+coord TSV. Default /tmp/reg/fr-communes.tsv" },
+	],
+	async run(opts, write) {
+		// Legacy build-fr-admin-split-shard.mjs seeded `mulberry32(opts.seed)`.
+		const random = makeMulberry32(opts.seed)
+		const count = opts.count ?? 60000
+		const source = opts.sourceName ?? "synth-fr-admin-split"
+		const communesPath = opts.communes ?? DEFAULT_COMMUNES
+
+		const pool = await readCommunes(communesPath)
+		console.error(`  ${communesPath}: ${pool.length} communes with derived département`)
+
+		if (pool.length === 0) {
+			throw new Error("No communes — build the TSV from BAN first (see the recipe header).")
+		}
+
+		let emitted = 0
+		let skipped = 0
+		let guard = 0
+		const orderCounts: Record<string, number> = {}
+		const N = pool.length
+
+		while (emitted < count && guard++ < count * 12) {
+			const base = pool[Math.floor(random() * N)]!
+			const { raw, components, order } = render(random, base)
+
+			// Alignment precondition: every component surface appears verbatim in raw.
+			const values = Object.values(components).filter((v): v is string => Boolean(v))
+
+			if (!values.every((v) => raw.includes(v))) {
+				skipped++
+				continue
+			}
+
+			if (opts.golden) {
+				// Held-out eval slice for the centroid gate — carries the truth coordinate.
+				write(JSON.stringify({ raw, components, country: "FR", lat: Number(base.lat), lon: Number(base.lon) }) + "\n")
+				emitted++
+				orderCounts[order] = (orderCounts[order] ?? 0) + 1
+				continue
+			}
+
+			const sourceID = stableSourceID(source, {
+				locality: components.locality,
+				region: components.region,
+				postcode: components.postcode,
+			})
+			const canonical: CanonicalRow = {
+				raw,
+				components,
+				country: "FR",
+				locale: "fr-FR",
+				source,
+				source_id: sourceID,
+				corpus_version: "0.5.0",
+				license: LICENSE,
+			}
+			const aligned = alignRow(canonical)
+
+			if (aligned.kind !== "labeled" || !aligned.row) {
+				skipped++
+				continue
+			}
+			write(
+				JSON.stringify({ ...aligned.row, synth_method: "fr-admin-split", synth_order: order, synth_base_id: null }) +
+					"\n"
+			)
+			emitted++
+			orderCounts[order] = (orderCounts[order] ?? 0) + 1
+		}
+
+		console.error(`  emitted=${emitted} skipped=${skipped} order-mix=${JSON.stringify(orderCounts)}`)
+
+		return { emitted, skipped }
+	},
+}

package/src/shard-recipes/fr-bare-street.ts

@@ -0,0 +1,85 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `fr-bare-street` shard recipe (#251) — the postcode-anchoring-imbalance lever. BAN (and every
+ *   other comprehensive FR source) is postcode-COMPLETE, so the model learned the French
+ *   street→locality boundary as "the token after the 5-digit postcode," never as "comma + city." Strip
+ *   the postcode and it leaks the street's proper-noun tokens into the following locality ("Rue René
+ *   Cassin, Paris" → street="Rue Ren", locality="Cassin"). This recipe mints the MISSING distribution:
+ *   the BARE comma form, NO postcode, real `(street, number, city)` tuples from BAN (Licence Ouverte —
+ *   permissive; the model stays clean of ODbL, unlike the opt-in OSM rooftop shards).
+ *
+ *   Each tuple → `<n> <Rue/Avenue/…> <proper-noun name>, <City>` with the FR prefix split
+ *   ({@link decomposeFrStreet}: "Rue" → street_prefix, the rest → street). Tuples whose street carries
+ *   no recognized FR type word are skipped — the failing class is precisely the prefix-led street.
+ *
+ *   ⚠ Convention loss-mask: this recipe TEACHES FR `street_prefix`. The conventions loss-mask forbids it
+ *   for FR and will `-inf` these gold labels (the v1.6.0 ~7M-loss blow-up). Disable that mask for any
+ *   run including this shard.
+ */
+
+import { decomposeFrStreet } from "../adapters/ban/street-decompose.ts"
+import { alignAndWrite, makeMulberry32, readTuples, type ShardRecipe, shardSourceID } from "./scaffold.ts"
+
+export const frBareStreetRecipe: ShardRecipe = {
+	name: "fr-bare-street",
+	description:
+		"FR bare comma-form street+city, NO postcode (#251): '<n> Rue <name>, <City>' — the postcode-anchoring lever",
+	mode: "tuples",
+	async run(opts, write) {
+		// Seeded for parity with the other recipes; unused beyond reproducibility (the tuples drive the content).
+		makeMulberry32(opts.seed)
+		let read = 0
+		let emitted = 0
+		let skipped = 0
+
+		for await (const t of readTuples(opts.input!)) {
+			read++
+			const fullStreet = String(t.street ?? "").trim()
+			const number = String(t.number ?? "").trim()
+			const locality = String(t.locality ?? "").trim()
+
+			if (!fullStreet || !number || !locality) {
+				skipped++
+				continue
+			}
+			const { prefix, street } = decomposeFrStreet(fullStreet)
+
+			// The failing class is the prefix-led FR street; a no-prefix nom_voie ("La Ville Mois") isn't it.
+			if (!prefix || !street) {
+				skipped++
+				continue
+			}
+			const components: Record<string, string> = {
+				house_number: number,
+				street_prefix: prefix,
+				street,
+				locality,
+			}
+			// BARE comma form, number-before (FR's dominant order), NO postcode — the whole point.
+			const raw = `${number} ${prefix} ${street}, ${locality}`
+			const source_id = shardSourceID("synth-fr-bare-street", { ...components, v: String(read) })
+			const canonical = {
+				raw,
+				components,
+				country: "FR",
+				locale: "fr-FR",
+				source: "synth-fr-bare-street",
+				source_id,
+				corpus_version: "0.9.4",
+				license:
+					"Synthetic — fr-bare-street; (street, number, city) from BAN (Base Adresse Nationale, Licence Ouverte)",
+			}
+
+			if (alignAndWrite(write, canonical, "fr-bare-street")) {
+				emitted++
+			} else {
+				skipped++
+			}
+		}
+
+		return { read, emitted, skipped }
+	},
+}

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

@@ -0,0 +1,304 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `fr-fragment` shard recipe (#727 T2) — the HOUSE-NUMBER-LICENCE lever.
+ *
+ *   The measured problem (T1c, `2026-07-16-t1c-fragment-board-verdict.md`): the shipped model scores
+ *   **0.925** on `<n> Rue X` and **0.215** on `Rue X`. Same streets, same model; the only difference
+ *   is a leading number. It has learned that a house number LICENSES a street reading at all — strip
+ *   it and a designator-led phrase parses as a locality, designator included:
+ *
+ *   ```
+ *   "Rue Montmartre"        -> locality="Rue Montmartre"
+ *   "Allee Poque"           -> locality="Allee Poque"
+ *   ```
+ *
+ *   `Rue` can only mean street in French. The model is not mislabelling an ambiguous toponym; it is
+ *   mislabelling `Rue`.
+ *
+ *   WHY THE EXISTING RECIPE DOESN'T COVER THIS. {@link frBareStreetRecipe} (#251) mints
+ *   `<n> Rue <name>, <City>` — the bare COMMA form, no postcode. It targets postcode-anchoring
+ *   imbalance, and every row it emits still carries a house number AND a locality. It cannot teach
+ *   the class above, because it never shows the model a street standing alone.
+ *
+ *   WHAT THIS MINTS. Five street forms — the first three carry NO house number and NO locality, which
+ *   is the whole point — plus the counter-distribution:
+ *
+ *   1. `bare-street`         "Rue Montmartre"
+ *   2. `street-particle`     "Rue de la Paix"
+ *   3. `date-name`           "Allee du 11 Novembre 1918"
+ *   4. `street-housenumber`  "12 Rue Montmartre"     — the anchor, so the licence isn't UNLEARNED
+ *   5. `alnum-housenumber`   "12 bis Rue Montmartre"
+ *   6. `bare-locality`       "Mery-sur-Oise"         — NEGATIVE: a bare toponym that IS a locality
+ *
+ *   The **admin/street homonym** class (`Rue de Rome`) is deliberately NOT a separate form. Homonym
+ *   streets are already in the register and fall into 1–3 naturally; there is nothing different to
+ *   teach about them, because the lesson is identical — the designator makes it a street. The
+ *   fragment board scores them separately (they need measuring, not minting), and the recipe would
+ *   need a second pass over the commune set to label them, buying a `synth_method` string and no
+ *   training signal.
+ *
+ *   FORM 7 IS NOT OPTIONAL. T1c's standing prediction: the board's `bare-locality` cell reads 0.980
+ *   for the WRONG REASON — the model calls everything without a house number a locality, and on bare
+ *   localities that is accidentally right. Teach bare streets alone and the model has every incentive
+ *   to flip that default rather than learn the distinction, trading a 0.215 for a 0.980. The shard
+ *   must show BOTH bare forms so the discriminating evidence is the designator, which is the only
+ *   thing that actually distinguishes them. This is the same counter-distribution principle
+ *   {@link noStreetRecipe} established after synth-street pushed the model into "decompose mode".
+ *
+ *   SPLIT. `--exclude-surfaces` takes the fragment board's reserved surface list
+ *   (`mailwoman/eval-harness/fixtures/ban-fragments-fr.surfaces.txt`). Every listed surface is
+ *   skipped — source-disjoint by normalized street SURFACE, never by record row. Row-disjoint leaks
+ *   the surface across the boundary and measures memorization of `Rue de Rivoli` while claiming
+ *   generalization to unseen streets. The recipe REFUSES to run without the list rather than
+ *   silently minting a contaminated shard.
+ *
+ *   MIX. The shard is ~145K rows off a 120K-tuple draw; the intended corpus mix is **5–10%**, set at
+ *   assembly time by shard weight rather than by row count. Keep the cap: a shard that fixes fragments
+ *   by degrading full addresses has moved the failure, not fixed it — which is what
+ *   `street-housenumber` / `alnum-housenumber` on the fragment board and the global parity floor are
+ *   there to catch. `date-name` is ~0.5% of the shard because BAN only holds ~1,418 date-name streets
+ *   after filtering and the tuple extractor already takes every one; if that class needs more, the
+ *   lever is shard weight, not invented data.
+ *
+ *   ⚠ Convention loss-mask: like {@link frBareStreetRecipe}, this recipe TEACHES FR `street_prefix`.
+ *   The conventions loss-mask forbids it for FR and will `-inf` these gold labels (the v1.6.0 ~7M-loss
+ *   blow-up). Disable that mask for any run including this shard.
+ */
+
+import { readFileSync } from "node:fs"
+
+import { decomposeFrStreet } from "../adapters/ban/street-decompose.ts"
+import { alignAndWrite, makeMulberry32, readTuples, type ShardRecipe, shardSourceID } from "./scaffold.ts"
+
+/** House numbers, weighted toward the small values that dominate real BAN rows. */
+const HOUSE_NUMBERS = [
+	1, 1, 2, 2, 3, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 15, 16, 18, 20, 21, 24, 27, 30, 33, 42, 57, 68, 84, 102, 115, 140,
+]
+/** FR alphanumeric house-number forms. `bis`/`ter` are separated; a bare letter is suffixed. */
+const ALNUM_SUFFIXES = ["bis", "ter", "A", "B"]
+
+const norm = (value: string): string =>
+	value
+		.normalize("NFD")
+		.replace(/[̀-ͯ]/g, "")
+		.toLowerCase()
+		.replace(/\s+/g, " ")
+		.trim()
+
+/**
+ * French commune convention: capitalize each element, leave the joining particles lowercase. `saint-jean-de-luz` →
+ * `Saint-Jean-de-Luz`, not `Saint-Jean-De-Luz`.
+ *
+ * Needed because BAN's sharded DBs keep only `locality_base` — normalized, lowercase, accent-stripped. Emitting that
+ * verbatim would teach the counter-distribution that a lowercase accent-stripped string is a locality, which is not a
+ * fact about French and would not match the fragment board (which reconstructs the same casing). The accents are gone
+ * from the source and cannot be recovered here; the casing can.
+ */
+const FR_LOWER = new Set([
+	"le",
+	"la",
+	"les",
+	"de",
+	"du",
+	"des",
+	"d",
+	"l",
+	"sur",
+	"sous",
+	"en",
+	"aux",
+	"au",
+	"et",
+	"lez",
+])
+
+export function frTitleCase(value: string): string {
+	const cap = (token: string, first: boolean): string =>
+		!first && FR_LOWER.has(token) ? token : token.charAt(0).toUpperCase() + token.slice(1)
+
+	return value
+		.split(" ")
+		.map((word, wordIndex) =>
+			word
+				.split("-")
+				.map((bit, bitIndex) => cap(bit, wordIndex === 0 && bitIndex === 0))
+				.join("-")
+		)
+		.join(" ")
+}
+
+/** Does the street name carry a particle? Decides the particle vs bare classification. */
+const PARTICLE = /\b(de la|de l'|du|des|de|d'|le|la|les)\b/i
+/** Does the street name carry date material (a year, or a day + French month)? */
+const DATEISH =
+	/\b(1[0-9]|20)\d{2}\b|\b\d{1,2}\s+(janvier|f[ée]vrier|mars|avril|mai|juin|juillet|ao[ûu]t|septembre|octobre|novembre|d[ée]cembre)\b/i
+
+export const frFragmentRecipe: ShardRecipe = {
+	name: "fr-fragment",
+	description:
+		"FR street fragments with NO house number (#727 T2): the house-number-licence lever — bare/particle/date-name/homonym + the bare-locality counter",
+	mode: "tuples",
+	options: [
+		{
+			flag: "--exclude-surfaces <path>",
+			description: "REQUIRED. The fragment board's reserved surface list; every listed street is skipped.",
+		},
+		{
+			flag: "--hn-prob <n>",
+			description: "Share of rows carrying a house number (default 0.35 — the anchor, not the point)",
+		},
+		{
+			flag: "--bare-prob <n>",
+			description: "Share of NO-house-number rows that are bare LOCALITIES (default 0.25 — the counter)",
+		},
+	],
+	async run(opts, write) {
+		const random = makeMulberry32(opts.seed)
+		const excludePath = opts.excludeSurfaces
+
+		if (!excludePath) {
+			throw new Error(
+				"fr-fragment: --exclude-surfaces is REQUIRED. Pass the fragment board's reserved list " +
+					"(mailwoman/eval-harness/fixtures/ban-fragments-fr.surfaces.txt) or this shard trains on its own eval set. " +
+					"Source-disjoint by street SURFACE is the split discipline; there is no safe default."
+			)
+		}
+
+		const excluded = new Set(
+			readFileSync(excludePath, "utf8")
+				.split("\n")
+				.map((line) => line.trim())
+				.filter((line) => line && !line.startsWith("#"))
+		)
+
+		if (!excluded.size) throw new Error(`fr-fragment: --exclude-surfaces "${excludePath}" listed no surfaces`)
+
+		const hnProb = opts.hnProb ?? 0.35
+		const bareLocalityProb = opts.bareProb ?? 0.25
+
+		// The locality pool is harvested from the tuples themselves — every BAN row carries its
+		// commune, so the counter-distribution needs no second source.
+		const localities = new Set<string>()
+
+		let read = 0
+		let emitted = 0
+		let skipped = 0
+		let contaminated = 0
+
+		for await (const tuple of readTuples(opts.input!)) {
+			read++
+			const fullStreet = String(tuple.street ?? "").trim()
+			const locality = String(tuple.locality ?? "").trim()
+
+			if (locality) {
+				localities.add(locality)
+			}
+
+			if (!fullStreet) {
+				skipped++
+				continue
+			}
+
+			// THE SPLIT. A surface on the fragment board never enters training.
+			if (excluded.has(norm(fullStreet))) {
+				contaminated++
+				continue
+			}
+
+			const { prefix, street } = decomposeFrStreet(fullStreet)
+
+			// The failing class is the designator-led street. A no-prefix nom_voie ("La Ville Mois")
+			// is a different problem and would muddy the signal.
+			if (!prefix || !street) {
+				skipped++
+				continue
+			}
+
+			const carriesNumber = random() < hnProb
+			const components: Record<string, string> = { street_prefix: prefix, street }
+			let raw = `${prefix} ${street}`
+			let klass = DATEISH.test(street) ? "date-name" : PARTICLE.test(street) ? "street-particle" : "bare-street"
+
+			if (carriesNumber) {
+				const number = HOUSE_NUMBERS[Math.floor(random() * HOUSE_NUMBERS.length)]!
+				const alnum = random() < 0.25
+				const suffix = ALNUM_SUFFIXES[Math.floor(random() * ALNUM_SUFFIXES.length)]!
+				const houseNumber = alnum
+					? suffix === "bis" || suffix === "ter"
+						? `${number} ${suffix}`
+						: `${number}${suffix}`
+					: String(number)
+				components.house_number = houseNumber
+				raw = `${houseNumber} ${prefix} ${street}`
+				klass = alnum ? "alnum-housenumber" : "street-housenumber"
+			}
+
+			const sourceID = shardSourceID("synth-fr-fragment", { ...components, v: String(read) })
+
+			if (
+				alignAndWrite(
+					write,
+					{
+						raw,
+						components,
+						country: "FR",
+						locale: "fr-FR",
+						source: "synth-fr-fragment",
+						source_id: sourceID,
+						corpus_version: "0.9.4",
+						license: "Synthetic — fr-fragment; (street, commune) from BAN (Base Adresse Nationale, Licence Ouverte)",
+					},
+					`fr-fragment:${klass}`
+				)
+			) {
+				emitted++
+			} else {
+				skipped++
+			}
+		}
+
+		// ---- the counter-distribution: bare localities, NO street anywhere in the row -------------
+		// Minted last so the locality pool is complete. Without these the model can satisfy every row
+		// above by flipping its default from "bare => locality" to "bare => street", which trades one
+		// broken prior for another and would show up as bare-locality collapsing on the board.
+		const pool = [...localities].sort()
+		const wanted = Math.round((emitted / Math.max(1, 1 - bareLocalityProb)) * bareLocalityProb)
+
+		for (let i = 0; i < wanted && pool.length; i++) {
+			// BAN gives `locality_base` normalized; restore the casing the fragment board also
+			// reconstructs, so train and eval show the model the same shape of French.
+			const name = frTitleCase(pool[Math.floor(random() * pool.length)]!)
+			const sourceID = shardSourceID("synth-fr-fragment", { locality: name, v: `neg-${i}` })
+
+			if (
+				alignAndWrite(
+					write,
+					{
+						raw: name,
+						components: { locality: name },
+						country: "FR",
+						locale: "fr-FR",
+						source: "synth-fr-fragment",
+						source_id: sourceID,
+						corpus_version: "0.9.4",
+						license: "Synthetic — fr-fragment counter-distribution; commune from BAN (Licence Ouverte)",
+					},
+					"fr-fragment:bare-locality"
+				)
+			) {
+				emitted++
+			} else {
+				skipped++
+			}
+		}
+
+		if (contaminated) {
+			console.error(`fr-fragment: skipped ${contaminated} rows whose street surface is reserved by the fragment board`)
+		}
+
+		return { read, emitted, skipped }
+	},
+}