@mailwoman/corpus 9.3.0 → 10.0.0

package/lib/recipes/fr-bare-street.ts

@@ -1,170 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   `fr-bare-street` slice recipe (#251) — the postcode-anchoring-imbalance change. 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 slices).
- *
- *   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 slice.
- */
-
-import { FR_VOIE_TYPES } from "@mailwoman/codex/fr"
-
-import { decomposeFrStreet } from "#adapters/ban/street-decompose"
-import { alignAndWrite, makeMulberry32, readTuples, type CorpusRecipe, sliceSourceID } from "#recipes/scaffold"
-
-/**
- * Canonical voie type (lowercase, accent-kept) → its most common written abbreviation, from the codex table's first
- * entry. Types with no attested abbreviation stay canonical in the abbreviated form.
- */
-const FR_VOIE_ABBREV: Record<string, string> = Object.fromEntries(
-	Object.entries(FR_VOIE_TYPES).flatMap(([canonical, abbrevs]) => (abbrevs[0] ? [[canonical, abbrevs[0]]] : []))
-)
-
-/**
- * The order-cycle slot for the BARE-STREET-ONLY form (`«voie» «name»`, no number, no locality) — the absence
- * counterweight to the locality-terminated comma-free forms (see the cycle comment).
- */
-const BARE_STREET_ONLY_FORM = 3
-
-/**
- * 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.
- */
-export const frBareStreetRecipe: CorpusRecipe = {
-	name: "fr-bare-street",
-	description:
-		"FR bare street+city, NO postcode (#251): comma / comma-free / abbreviated-voie surfaces over one label set",
-	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)
-
-			// A no-prefix nom_voie ("La Ville Mois") is not the prefix-led class the numbered forms
-			// exercise — but as a BARE surface it is exactly the non-voie-led counterweight the v4.5.1
-			// probe showed missing ('Savile Row'-shaped spans still fell to the trailing-locality
-			// prior; the voie-led bare form protected only voie-led spans). Alternate rows emit the
-			// whole span as a bare street; the rest skip as before.
-			if (!prefix || !street) {
-				if (read % 2 === 0 && fullStreet.split(" ").length >= 2) {
-					const bare = {
-						raw: fullStreet,
-						components: { street: fullStreet } as Record<string, string>,
-						country: "FR",
-						locale: "fr-FR",
-						source: "synth-fr-bare-street",
-						source_id: sliceSourceID("synth-fr-bare-street", {
-							street: fullStreet,
-							f: "bare-nonvoie",
-							v: String(read),
-						}),
-						corpus_version: "0.9.4",
-						license:
-							"Synthetic — fr-bare-street; (street, number, city) from BAN (Base Adresse Nationale, Licence Ouverte)",
-					}
-
-					if (alignAndWrite(write, bare, "fr-bare-street")) {
-						emitted++
-					} else {
-						skipped++
-					}
-
-					continue
-				}
-
-				skipped++
-
-				continue
-			}
-
-			// Four surfaces over the same tuple, cycled deterministically. The comma form was the
-			// original change; the COMMA-FREE form is the colloquial register users actually type
-			// ('12 rue de Rome Paris' — the street↔locality boundary with NO delimiter, the fr-fr
-			// panel's named loss); the ABBREVIATED form is the typeahead register the geocoder-tester
-			// FR slice attests at scale; and the BARE-STREET-ONLY form is the absence counterweight —
-			// without it, every delimiter-free surface in the mix ENDS in a locality, the model learns
-			// "trailing span = locality" as categorical, and bare street names across locales flip to
-			// locality wholesale (the v4.5.0 no-promote's measured erosion: 'Calle de Alcalá',
-			// 'Madison Square West', and COMER's fork all fell to that prior). Tags are identical
-			// where present; each component VALUE is the span as written (BIO alignment binds value
-			// to surface); the bare form carries NO number and NO locality because the surface has
-			// neither.
-			const form = read % 4
-			const prefixSurface = form >= 2 ? (FR_VOIE_ABBREV[prefix.toLowerCase()] ?? prefix) : prefix
-
-			const components: Record<string, string> =
-				form === BARE_STREET_ONLY_FORM
-					? { street_prefix: prefix, street }
-					: { house_number: number, street_prefix: prefixSurface, street, locality }
-
-			// When the tuple carries a WOF-attested neighbourhood, the comma slot renders the
-			// THREE-slot middle surface — the dependent-locality counterweight (the v4.5.1 erosion's
-			// untouched half: the two-slot comma-free endings squeezed the middle tag out).
-			const hood = String(t.neighbourhood ?? "").trim()
-
-			if (form === 0 && hood) {
-				components.dependent_locality = hood
-			}
-
-			const raw =
-				form === 0
-					? hood
-						? `${number} ${prefix} ${street}, ${hood}, ${locality}`
-						: `${number} ${prefix} ${street}, ${locality}`
-					: form === BARE_STREET_ONLY_FORM
-						? `${prefix} ${street}`
-						: `${number} ${prefixSurface} ${street} ${locality}`
-
-			const source_id = sliceSourceID("synth-fr-bare-street", { ...components, f: String(form), 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/lib/recipes/fr-fragment.ts

@@ -1,333 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   `fr-fragment` slice recipe (#727 T2) — the HOUSE-NUMBER-LICENCE change.
- *
- *   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 slice
- *   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 slice.
- *
- *   MIX. The slice is ~145K rows off a 120K-tuple draw; the intended corpus mix is **5–10%**, set at
- *   assembly time by slice weight rather than by row count. Keep the cap: a slice 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 slice 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
- *   change is slice 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 slice.
- */
-
-import { TextSpliterator } from "spliterator"
-
-import { decomposeFrStreet } from "#adapters/ban/street-decompose"
-import { alignAndWrite, makeMulberry32, readTuples, type CorpusRecipe, sliceSourceID } from "#recipes/scaffold"
-import { pick } from "#synthesizers/utils"
-
-/**
- * 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"]
-
-// Recipe-fidelity: this accent-STRIPPING fold is the surface key every committed fr-fragment slice and the fragment
-// board's reserved list were built with — not the diacritic-KEEPING `foldNOSurface` the Norwegian slices share.
-const norm = (value: string): string =>
-	value
-		.normalize("NFD")
-		.replaceAll(/[̀-ͯ]/g, "")
-		.toLowerCase()
-		.replaceAll(/\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 sliced 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
-
-// A quarter of house numbers carry an alphanumeric suffix (`8 bis`, `12B`).
-const ALNUM_HOUSE_NUMBER_SHARE = 0.25
-
-/**
- * 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.
- */
-export const frFragmentRecipe: CorpusRecipe = {
-	name: "fr-fragment",
-	description:
-		"FR street fragments with NO house number (#727 T2): the house-number-licence change — 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 slice trains on its own eval set. " +
-					"Source-disjoint by street SURFACE is the split discipline; there is no safe default."
-			)
-		}
-
-		const excluded = new Set<string>()
-
-		for await (const line of TextSpliterator.fromAsync(excludePath)) {
-			const trimmed = line.trim()
-
-			if (trimmed && !trimmed.startsWith("#")) {
-				excluded.add(trimmed)
-			}
-		}
-
-		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 = pick(HOUSE_NUMBERS, random)
-				const alnum = random() < ALNUM_HOUSE_NUMBER_SHARE
-				const suffix = pick(ALNUM_SUFFIXES, random)
-
-				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 = sliceSourceID("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++
-			}
-		}
-
-		// MARK: counter-distribution — bare localities
-		// 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].toSorted()
-		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(pick(pool, random))
-			const sourceID = sliceSourceID("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 }
-	},
-}