@mailwoman/corpus 7.5.0 → 7.7.0

package/out/src/shard-recipes/fr-lieudit.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `fr-lieudit` shard recipe — FR lieu-dit (hamlet/place) `dependent_locality` coverage
+ *   (`.superpowers/sdd/deploc-world-survey.md`, FR section, 2026-07-22). Streams every BAN
+ *   `adresses-<dept>.csv` dump under `--ban-dir` through `@mailwoman/ban/sdk`'s
+ *   `extractBANAddrPoints`, which now surfaces a cleaned `lieuDit` per record (junk/dup filtering
+ *   lives in `ban/sdk/extract.ts`'s `cleanLieuDit`, not duplicated here). Only rows carrying a clean
+ *   lieu-dit survive into the pool; the existing `ban`/`synth-fr` sources and their emitted rows are
+ *   untouched — this recipe reads the SAME raw CSVs but emits under its own source name.
+ *
+ *   Mapping: lieu-dit → `dependent_locality`, commune → `locality`. Rendered to match the formatter's
+ *   FR `place`-slot convention (`fix(formatter): render dependent_locality for neither-slot templates`,
+ *   b1edc1b7, verified via a `formatAddress` smoke call): house+street on line 1, the lieu-dit ALONE on
+ *   line 2, postcode+commune on line 3 — French postal convention (La Poste's line 5).
+ *
+ *   ~1.69M clean rows survive the filter nationally (26M total BAN rows, 1.81M raw `nom_ld` fills, ~6.6%
+ *   junk/dup). The pool is read in full (small string tuples only — no coordinates needed) and
+ *   Fisher-Yates shuffled with the seeded PRNG before slicing to `--count`, rather than sampled WITH
+ *   replacement — at a `--count` a sizeable fraction of the pool, with-replacement draws would produce a
+ *   large duplicate rate (birthday-paradox math: ~190k expected collisions at count=800k over a 1.69M
+ *   pool).
+ */
+import { type ShardRecipe } from "./scaffold.ts";
+export declare const frLieuditRecipe: ShardRecipe;
+//# sourceMappingURL=fr-lieudit.d.ts.map

package/out/src/shard-recipes/fr-lieudit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fr-lieudit.d.ts","sourceRoot":"","sources":["../../../src/shard-recipes/fr-lieudit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAcH,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAA;AA4HhE,eAAO,MAAM,eAAe,EAAE,WA+G7B,CAAA"}

package/out/src/shard-recipes/fr-lieudit.js

@@ -0,0 +1,212 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `fr-lieudit` shard recipe — FR lieu-dit (hamlet/place) `dependent_locality` coverage
+ *   (`.superpowers/sdd/deploc-world-survey.md`, FR section, 2026-07-22). Streams every BAN
+ *   `adresses-<dept>.csv` dump under `--ban-dir` through `@mailwoman/ban/sdk`'s
+ *   `extractBANAddrPoints`, which now surfaces a cleaned `lieuDit` per record (junk/dup filtering
+ *   lives in `ban/sdk/extract.ts`'s `cleanLieuDit`, not duplicated here). Only rows carrying a clean
+ *   lieu-dit survive into the pool; the existing `ban`/`synth-fr` sources and their emitted rows are
+ *   untouched — this recipe reads the SAME raw CSVs but emits under its own source name.
+ *
+ *   Mapping: lieu-dit → `dependent_locality`, commune → `locality`. Rendered to match the formatter's
+ *   FR `place`-slot convention (`fix(formatter): render dependent_locality for neither-slot templates`,
+ *   b1edc1b7, verified via a `formatAddress` smoke call): house+street on line 1, the lieu-dit ALONE on
+ *   line 2, postcode+commune on line 3 — French postal convention (La Poste's line 5).
+ *
+ *   ~1.69M clean rows survive the filter nationally (26M total BAN rows, 1.81M raw `nom_ld` fills, ~6.6%
+ *   junk/dup). The pool is read in full (small string tuples only — no coordinates needed) and
+ *   Fisher-Yates shuffled with the seeded PRNG before slicing to `--count`, rather than sampled WITH
+ *   replacement — at a `--count` a sizeable fraction of the pool, with-replacement draws would produce a
+ *   large duplicate rate (birthday-paradox math: ~190k expected collisions at count=800k over a 1.69M
+ *   pool).
+ */
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { extractBANAddrPoints } from "@mailwoman/ban/sdk";
+import { COUNTRY_SURFACE_FORMS } from "@mailwoman/codex/country";
+import { dataRootPath } from "@mailwoman/core/utils";
+import { stableSourceID } from "../adapter.js";
+import { decomposeFrStreet } from "../adapters/ban/street-decompose.js";
+import { alignRow } from "../align.js";
+import { makeMulberry32 } from "./scaffold.js";
+const DEFAULT_LICENSE = "Licence Ouverte 2.0"; // matches the `ban` adapter's Tier-B election for BAN data
+/**
+ * Enumerate `adresses-<dept>.csv[.gz]` files in `banDir`, ONE path per département. Excludes the `merged`/`france`
+ * aggregates (they duplicate the per-département rows) and, when both a `.csv` and a `.csv.gz` exist for the same dept
+ * (observed on disk for 13/2A/48/69/75 — a stale re-fetch artifact), prefers the uncompressed `.csv` — mirrors
+ * `ban/scripts/build-address-point-shard.ts`'s `departementFiles`, which hit and fixed this exact double-count trap
+ * first.
+ */
+function departementFiles(banDir) {
+    const byDept = new Map();
+    for (const name of readdirSync(banDir).sort()) {
+        const m = /^adresses-(.+?)\.csv(\.gz)?$/.exec(name);
+        if (!m)
+            continue;
+        const dept = m[1];
+        if (dept === "merged" || dept === "france")
+            continue;
+        const existing = byDept.get(dept);
+        if (!existing || (existing.endsWith(".gz") && !name.endsWith(".gz"))) {
+            byDept.set(dept, join(banDir, name));
+        }
+    }
+    return [...byDept.keys()].sort().map((dept) => byDept.get(dept));
+}
+/** Stream every département file, keeping only rows with a clean `lieuDit` (junk/dup filtering lives in `ban/sdk`). */
+async function readLieuDitPool(banDir) {
+    const files = departementFiles(banDir);
+    if (files.length === 0) {
+        throw new Error(`No BAN adresses-<dept>.csv files found in ${banDir} — fetch BAN first (\`mailwoman corpus fetch ban\`).`);
+    }
+    const pool = [];
+    let scanned = 0;
+    for (const path of files) {
+        let deptCount = 0;
+        for await (const rec of extractBANAddrPoints(path)) {
+            scanned++;
+            if (!rec.lieuDit || !rec.city)
+                continue;
+            pool.push({
+                numero: rec.numero,
+                rep: rec.rep,
+                street: rec.street,
+                postcode: rec.postcode,
+                locality: rec.city,
+                dependentLocality: rec.lieuDit,
+            });
+            deptCount++;
+        }
+        console.error(`  ${path}: ${deptCount.toLocaleString()} clean lieu-dit rows`);
+    }
+    console.error(`  scanned ${scanned.toLocaleString()} BAN rows across ${files.length} départements → pool=${pool.length.toLocaleString()}`);
+    return pool;
+}
+/** `house_number` = `numero` + folded `rep` ("10 bis"), matching the `ban` adapter's own composition. */
+function composeHouseNumber(numero, rep) {
+    return rep ? `${numero} ${rep}` : numero;
+}
+/**
+ * Render the raw address string: house+street line, the lieu-dit ALONE on its own line, postcode+commune line — the
+ * exact shape `formatAddress` produces for FR's `place`-slot mapping (verified via a smoke call before this recipe was
+ * written; see the module docstring).
+ */
+function composeRaw(house, street, dependentLocality, postcode, locality) {
+    const lines = [];
+    const streetLine = `${house} ${street}`.trim();
+    if (streetLine) {
+        lines.push(streetLine);
+    }
+    lines.push(dependentLocality);
+    const cityLine = [postcode, locality].filter(Boolean).join(" ").trim();
+    if (cityLine) {
+        lines.push(cityLine);
+    }
+    return lines.join("\n");
+}
+/** Fisher-Yates shuffle, in place, with the recipe's seeded PRNG — reproducible sampling without replacement. */
+function shuffleInPlace(arr, random) {
+    for (let i = arr.length - 1; i > 0; i--) {
+        const j = Math.floor(random() * (i + 1));
+        [arr[i], arr[j]] = [arr[j], arr[i]];
+    }
+}
+export const frLieuditRecipe = {
+    name: "fr-lieudit",
+    description: "FR lieu-dit rows: BAN nom_ld → dependent_locality (commune → locality), lieu-dit on its own line",
+    mode: "generate",
+    options: [
+        {
+            flag: "--ban-dir <dir>",
+            description: "BAN adresses-<dept>.csv directory. Default $MAILWOMAN_DATA_ROOT/corpus/sources/ban",
+        },
+        {
+            flag: "--country-fraction <f>",
+            description: "Fraction of rows that append an explicit 'France' surface form + a `country` component. Default 0",
+        },
+    ],
+    async run(opts, write) {
+        const random = makeMulberry32(opts.seed);
+        const source = opts.sourceName ?? "synth-fr-lieudit";
+        const count = opts.count ?? 800_000;
+        const banDir = opts.banDir ?? dataRootPath("corpus", "sources", "ban");
+        const countryFraction = opts.countryFraction ?? 0;
+        if (!(countryFraction >= 0 && countryFraction <= 1)) {
+            throw new Error(`--country-fraction must be in [0, 1], got ${countryFraction}`);
+        }
+        const pool = await readLieuDitPool(banDir);
+        if (pool.length === 0) {
+            throw new Error(`No clean lieu-dit rows found under ${banDir} — see ban/sdk/extract.ts's cleanLieuDit filter.`);
+        }
+        shuffleInPlace(pool, random);
+        const selected = pool.slice(0, Math.min(count, pool.length));
+        let emitted = 0;
+        let skipped = 0;
+        let countryAppended = 0;
+        for (const t of selected) {
+            const house = composeHouseNumber(t.numero, t.rep);
+            const decomposed = decomposeFrStreet(t.street);
+            const components = {
+                house_number: house,
+                dependent_locality: t.dependentLocality,
+                locality: t.locality,
+            };
+            if (decomposed.prefix) {
+                components.street_prefix = decomposed.prefix;
+            }
+            if (decomposed.street) {
+                components.street = decomposed.street;
+            }
+            if (t.postcode) {
+                components.postcode = t.postcode;
+            }
+            let raw = composeRaw(house, t.street, t.dependentLocality, t.postcode, t.locality);
+            if (!raw) {
+                skipped++;
+                continue;
+            }
+            // Country-append (the fr-admin-split #728 pattern, generalized): ~`countryFraction` of the time
+            // append an explicit "France" surface form onto the trailing (postcode+commune) line + a
+            // `country` component — the model relearns to emit country WHEN present without over-firing it
+            // on the (still-majority) country-less rows. `countryFraction <= 0` (the default) never draws
+            // from `random`, so the byte-stream is unaffected when the flag is unset.
+            if (countryFraction > 0 && random() < countryFraction) {
+                const forms = COUNTRY_SURFACE_FORMS.FR;
+                const form = forms[Math.floor(random() * forms.length)];
+                raw = `${raw}, ${form}`;
+                components.country = form;
+                countryAppended++;
+            }
+            const sourceID = stableSourceID(source, {
+                street: t.street,
+                house_number: house,
+                dependent_locality: t.dependentLocality,
+                locality: t.locality,
+                postcode: t.postcode ?? undefined,
+            });
+            const canonical = {
+                raw,
+                components,
+                country: "FR",
+                locale: "fr-FR",
+                source,
+                source_id: sourceID,
+                corpus_version: "",
+                license: DEFAULT_LICENSE,
+            };
+            const aligned = alignRow(canonical);
+            if (aligned.kind !== "labeled" || !aligned.row) {
+                skipped++;
+                continue;
+            }
+            write(JSON.stringify({ ...aligned.row, synth_method: source, synth_base_id: null }) + "\n");
+            emitted++;
+        }
+        console.error(`  emitted=${emitted} skipped=${skipped} country-appended=${countryAppended} pool=${pool.length}`);
+        return { emitted, skipped };
+    },
+};
+//# sourceMappingURL=fr-lieudit.js.map

package/out/src/shard-recipes/fr-lieudit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fr-lieudit.js","sourceRoot":"","sources":["../../../src/shard-recipes/fr-lieudit.ts"],"names":[],"mappings":"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"}

package/out/src/shard-recipes/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shard-recipes/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAoBH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAOhD,cAAc,eAAe,CAAA;AA6B7B,4BAA4B;AAC5B,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAA4C,CAAA;AAEvG,+CAA+C;AAC/C,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEpE;AAED,yCAAyC;AACzC,wBAAgB,gBAAgB,IAAI,SAAS,WAAW,EAAE,CAEzD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shard-recipes/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAqBH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAOhD,cAAc,eAAe,CAAA;AA8B7B,4BAA4B;AAC5B,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAA4C,CAAA;AAEvG,+CAA+C;AAC/C,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEpE;AAED,yCAAyC;AACzC,wBAAgB,gBAAgB,IAAI,SAAS,WAAW,EAAE,CAEzD"}

package/out/src/shard-recipes/index.js

@@ -14,6 +14,7 @@ import { czPcFirstPrepositionRecipe } from "./cz-pcfirst-preposition.js";
 import { frAdminSplitRecipe } from "./fr-admin-split.js";
 import { frBareStreetRecipe } from "./fr-bare-street.js";
 import { frFragmentRecipe } from "./fr-fragment.js";
+import { frLieuditRecipe } from "./fr-lieudit.js";
 import { frOrderRecipe } from "./fr-order.js";
 import { germanRecipe } from "./german.js";
 import { houseVenueRecipe } from "./house-venue.js";
@@ -48,6 +49,7 @@ const RECIPES = [
     frAdminSplitRecipe,
     frBareStreetRecipe,
     frFragmentRecipe,
+    frLieuditRecipe,
     czPcFirstPrepositionRecipe,
     nlPostcodeRecipe,
     noStreetLedRecipe,

package/out/src/shard-recipes/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/shard-recipes/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAC7D,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAA;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAEzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAEtC,cAAc,eAAe,CAAA;AAE7B,iDAAiD;AACjD,MAAM,OAAO,GAA2B;IACvC,YAAY;IACZ,gBAAgB;IAChB,iBAAiB;IACjB,cAAc;IACd,gBAAgB;IAChB,WAAW;IACX,gBAAgB;IAChB,UAAU;IACV,kBAAkB;IAClB,YAAY;IACZ,YAAY;IACZ,aAAa;IACb,kBAAkB;IAClB,kBAAkB;IAClB,gBAAgB;IAChB,0BAA0B;IAC1B,gBAAgB;IAChB,iBAAiB;IACjB,gBAAgB;IAChB,mBAAmB;IACnB,qBAAqB;IACrB,oBAAoB;IACpB,sBAAsB;CACtB,CAAA;AAED,4BAA4B;AAC5B,MAAM,CAAC,MAAM,aAAa,GAAqC,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;AAEvG,+CAA+C;AAC/C,MAAM,UAAU,cAAc,CAAC,IAAY;IAC1C,OAAO,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAC/B,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,gBAAgB;IAC/B,OAAO,OAAO,CAAA;AACf,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/shard-recipes/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAC7D,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAA;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAEzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAEtC,cAAc,eAAe,CAAA;AAE7B,iDAAiD;AACjD,MAAM,OAAO,GAA2B;IACvC,YAAY;IACZ,gBAAgB;IAChB,iBAAiB;IACjB,cAAc;IACd,gBAAgB;IAChB,WAAW;IACX,gBAAgB;IAChB,UAAU;IACV,kBAAkB;IAClB,YAAY;IACZ,YAAY;IACZ,aAAa;IACb,kBAAkB;IAClB,kBAAkB;IAClB,gBAAgB;IAChB,eAAe;IACf,0BAA0B;IAC1B,gBAAgB;IAChB,iBAAiB;IACjB,gBAAgB;IAChB,mBAAmB;IACnB,qBAAqB;IACrB,oBAAoB;IACpB,sBAAsB;CACtB,CAAA;AAED,4BAA4B;AAC5B,MAAM,CAAC,MAAM,aAAa,GAAqC,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;AAEvG,+CAA+C;AAC/C,MAAM,UAAU,cAAc,CAAC,IAAY;IAC1C,OAAO,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAC/B,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,gBAAgB;IAC/B,OAAO,OAAO,CAAA;AACf,CAAC"}

package/out/src/shard-recipes/locale.d.ts

@@ -24,7 +24,7 @@
  *   source shape, the rest the spaced conventional one. These draws are consumed ONLY for their
  *   country, so DE/FR emit streams are unchanged for a given seed.
  */
-import { type LocaleBaseTuple } from "../synthesize-german.ts";
+import { type LocaleBaseTuple, type SynthesizedLocaleRow } from "../synthesize-german.ts";
 import { type ShardRecipe } from "./scaffold.ts";
 /**
  * One per-country OA source part: either a cached `zip` + `csv` member (streamed via `unzip -p`) or an extracted plain
@@ -43,6 +43,34 @@ export interface LocalePart {
      * rows). Without this, the default CITY→locality mapping wrongly trains the suburb as the locality.
      */
     districtAsLocality?: boolean;
+    /**
+     * ES pedanía part only — the header is the RAW (un-conformed) CNIG export schema (`numero`, `tipo_vial`,
+     * `nombre_via`, `poblacion`, `municipio`, `comunidad_autonoma`, `cod_postal`), NOT the standard OA
+     * NUMBER/STREET/CITY/DISTRICT/REGION/POSTCODE header every other part uses. Verified 2026-07-22 by exact- coordinate
+     * cross-check: the OA-conformed `extracted/es/countrywide.csv` collapses CITY to `municipio` and drops `poblacion`
+     * (Spain's below-municipio núcleo/pedanía name) entirely, so the pedanía signal survives ONLY in this raw export.
+     * `street` is reconstructed as `tipo_vial + " " + nombre_via` (verified byte-identical to the conformed STREET column
+     * for the same row). CITY-analog = `poblacion`, DISTRICT-analog = `municipio`.
+     */
+    cnigRaw?: boolean;
+}
+export interface LocaleCountrySource {
+    source: string;
+    parts: LocalePart[];
+    /**
+     * The `corpus_version` stamped on emitted rows. DE/FR keep the historical `0.4.0` (regenerating those shards must
+     * stay lineage-identical); ES/IT/NL are the #241 staging lineage (`v0.9.9-es-it-nl`).
+     */
+    corpusVersion: string;
+    /**
+     * An ALTERNATE part list, read instead of {@link parts} when the `--district-as-locality` override is explicitly
+     * `true` for this invocation (see `run()`). ES-only for now — the standard `parts` entry can't supply real
+     * dependent-locality signal (its OA-conformed CSV drops `poblacion`; see {@link LocalePart.cnigRaw}), so the pedanía
+     * build reads a wholly different raw source instead of flipping the standard CITY/DISTRICT columns. `undefined` for
+     * every other country — the override then just forces `districtAsLocality` on the normal `parts`, as GB/NZ already do
+     * per-part.
+     */
+    pedaniaParts?: LocalePart[];
 }
 /**
  * OA CITY-noise normalization (#241) — the documented cleaning step, derived from the 2026-07-02 FULL-STREAM audit of
@@ -78,5 +106,26 @@ export declare function cleanCityNoise(city: string): string | null;
  * Exported for {@link locale.test.ts} — the CSV read path (quote handling, CRLF, region fallback) has no other test.
  */
 export declare function readTuples(part: LocalePart, rng: () => number): Promise<LocaleBaseTuple[]>;
+/**
+ * Country-append fraction (the fr-admin-split #728 pattern, generalized to the locale recipe): mutates `synth` in
+ * place, `countryFraction` of the time appending an explicit country surface form ("United Kingdom") to `raw` + 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. `countryFraction <= 0` (the default) short-circuits the `random()` draw away
+ * entirely — no `synth` mutation and no RNG consumption — so every existing locale's emit stream stays byte-identical
+ * to before this option existed. Exported for {@link locale.test.ts}.
+ */
+export declare function applyCountryAppend(synth: SynthesizedLocaleRow, country: string, countryFraction: number, random: () => number): void;
+/**
+ * Merge the `--district-as-locality` CLI override onto one part. `undefined` (flag absent) returns `part` unchanged
+ * (same object — no allocation, no behavior change); `true`/`false` returns a shallow copy with `districtAsLocality`
+ * forced to that value for this invocation only. Exported for {@link locale.test.ts}.
+ */
+export declare function applyDistrictAsLocalityOverride(part: LocalePart, override: boolean | undefined): LocalePart;
+/**
+ * Pick which part list a `--country` run reads: {@link LocaleCountrySource.pedaniaParts} when the override is explicitly
+ * `true` AND the country registers one (ES only, so far), else the default `parts` — unchanged for every other
+ * country/override combination. Exported for {@link locale.test.ts}.
+ */
+export declare function resolveLocaleParts(countrySource: LocaleCountrySource, override: boolean | undefined): LocalePart[];
 export declare const localeRecipe: ShardRecipe;
 //# sourceMappingURL=locale.d.ts.map

package/out/src/shard-recipes/locale.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"locale.d.ts","sourceRoot":"","sources":["../../../src/shard-recipes/locale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAUH,OAAO,EAAE,KAAK,eAAe,EAAuB,MAAM,yBAAyB,CAAA;AACnF,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAA;AAEhE;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC5B;AAiFD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM1D;AAWD;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CA2GhG;AAED,eAAO,MAAM,YAAY,EAAE,WAwH1B,CAAA"}
+{"version":3,"file":"locale.d.ts","sourceRoot":"","sources":["../../../src/shard-recipes/locale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAWH,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,oBAAoB,EAAuB,MAAM,yBAAyB,CAAA;AAC9G,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAA;AAEhE;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,mBAAmB;IACnC,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,UAAU,EAAE,CAAA;IACnB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,UAAU,EAAE,CAAA;CAC3B;AA6FD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM1D;AAgBD;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAoJhG;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,oBAAoB,EAC3B,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,MAAM,MAAM,GAClB,IAAI,CAgBN;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,UAAU,CAE3G;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,mBAAmB,EAAE,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,UAAU,EAAE,CAElH;AAED,eAAO,MAAM,YAAY,EAAE,WAgJ1B,CAAA"}

package/out/src/shard-recipes/locale.js

@@ -26,6 +26,7 @@
  */
 import { spawn } from "node:child_process";
 import { createReadStream } from "node:fs";
+import { COUNTRY_SURFACE_FORMS } from "@mailwoman/codex/country";
 import { dataRootPath } from "@mailwoman/core/utils";
 import { CSVSpliterator } from "spliterator";
 import { stableSourceID } from "../adapter.js";
@@ -68,6 +69,18 @@ const COUNTRY_SOURCES = {
         source: "synth-es",
         corpusVersion: "0.9.9",
         parts: [{ path: dataRootPath("openaddresses", "extracted", "es", "countrywide.csv") }],
+        // Pedanía shard (`synth-es-pedania`, `--district-as-locality`). Reads the RAW (un-conformed) CNIG export
+        // cached at oa-cache/es__countrywide.zip — the `parts` CSV above lost `poblacion` in OA's own conform step
+        // (see {@link LocalePart.cnigRaw}). districtAsLocality is pinned true here (this part only exists to be
+        // read pedanía-style); the CLI override still applies harmlessly on top.
+        pedaniaParts: [
+            {
+                zip: dataRootPath("oa-cache", "es__countrywide.zip"),
+                csv: "es_addresses.csv",
+                cnigRaw: true,
+                districtAsLocality: true,
+            },
+        ],
     },
     NZ: {
         // LINZ-derived OA countrywide extract (2.12M rows). `districtAsLocality` inverts the CITY/DISTRICT
@@ -78,6 +91,16 @@ const COUNTRY_SOURCES = {
         // coord board; that split is a BUILD-TIME concern (scratchpad), so the committed recipe reads the full CSV.
         parts: [{ path: dataRootPath("openaddresses", "extracted", "nz", "countrywide.csv"), districtAsLocality: true }],
     },
+    GB: {
+        // HM Land Registry Price Paid Data tuples (25.67M rows; see Task 2's ppd ingest). PPD's DISTRICT is the
+        // postal town (locality) and CITY is the dependent locality — legitimately EMPTY on the majority of rows
+        // (most GB addresses have no dependent locality). `districtAsLocality` maps DISTRICT→locality and, when
+        // present, CITY→dependent_locality; the `readTuples` gate above only drops a row when BOTH are empty, so
+        // the majority empty-CITY rows survive.
+        source: "synth-gb",
+        corpusVersion: "0.9.9",
+        parts: [{ path: dataRootPath("ppd", "2026-07-22", "gb-tuples.csv"), districtAsLocality: true }],
+    },
 };
 /**
  * Per-part reservoir cap. Streaming + Algorithm-R reservoir sampling to this size keeps memory bounded regardless of
@@ -168,39 +191,79 @@ export async function readTuples(part, rng) {
             if (header === null) {
                 header = cells.map((h) => h.trim().toLowerCase());
                 const ix = (name) => header.indexOf(name);
-                cols = {
-                    num: ix("number"),
-                    street: ix("street"),
-                    city: ix("city"),
-                    district: ix("district"),
-                    region: ix("region"),
-                    post: ix("postcode"),
-                };
+                // `cnigRaw` (ES pedanía only): the RAW CNIG header has no NUMBER/STREET/CITY/DISTRICT/REGION/POSTCODE
+                // at all — `numero`/`nombre_via`/`poblacion`/`municipio`/`comunidad_autonoma`/`cod_postal` instead.
+                // See {@link LocalePart.cnigRaw}.
+                cols = part.cnigRaw
+                    ? {
+                        num: ix("numero"),
+                        street: ix("nombre_via"),
+                        tipoVial: ix("tipo_vial"),
+                        city: ix("poblacion"),
+                        district: ix("municipio"),
+                        region: ix("comunidad_autonoma"),
+                        post: ix("cod_postal"),
+                    }
+                    : {
+                        num: ix("number"),
+                        street: ix("street"),
+                        tipoVial: -1,
+                        city: ix("city"),
+                        district: ix("district"),
+                        region: ix("region"),
+                        post: ix("postcode"),
+                    };
                 continue;
             }
             if (cols === null)
                 continue;
-            const street = get(cells, cols.street);
+            // cnigRaw: STREET is split into a road-type column (`tipo_vial`, e.g. "CARRETERA") and the name
+            // (`nombre_via`) — rejoin them exactly as OA's own conform step does (verified byte-identical to the
+            // conformed STREET column for the same source row). Every other part's header already carries the
+            // pre-joined STREET column, so `cols.tipoVial === -1` and this is a no-op there.
+            const street = cols.tipoVial >= 0
+                ? [get(cells, cols.tipoVial), get(cells, cols.street)].filter(Boolean).join(" ")
+                : get(cells, cols.street);
             const rawCity = get(cells, cols.city);
-            if (!street || !rawCity)
+            if (!street)
                 continue;
-            // Default: CITY → locality. NZ (`districtAsLocality`) inverts it — the OA DISTRICT holds the city
+            // Default: CITY → locality. NZ/GB (`districtAsLocality`) inverts it — the OA DISTRICT holds the city
             // (`Auckland`) and CITY holds the suburb (`Birkenhead`), so DISTRICT → locality and CITY →
             // dependent_locality. When DISTRICT is empty (~18% of NZ rows), fall back to CITY → locality with no
-            // sub-locality. See {@link LocalePart.districtAsLocality}.
+            // sub-locality. GB PPD tuples flip which side is legitimately empty — on the MAJORITY of GB rows CITY
+            // (the dependent_locality) is empty and DISTRICT (the locality) is populated, so the gate below only
+            // drops a `districtAsLocality` row when BOTH are empty, not when CITY alone is (that used to silently
+            // drop most of the GB source — see the fixed `readTuples` gate below). See
+            // {@link LocalePart.districtAsLocality}.
             let locality;
             let dependent_locality;
             if (part.districtAsLocality) {
-                const cleanedDistrict = cleanCityNoise(get(cells, cols.district));
+                const rawDistrict = get(cells, cols.district);
+                if (!rawCity && !rawDistrict)
+                    continue;
+                const cleanedDistrict = cleanCityNoise(rawDistrict);
                 if (cleanedDistrict) {
                     locality = cleanedDistrict;
-                    dependent_locality = cleanCityNoise(rawCity) ?? undefined;
+                    const cleanedCity = cleanCityNoise(rawCity);
+                    // ES pedanía lesson (2026-07-22): the CNIG `poblacion` column is filled on ~93% of rows but
+                    // EQUALS `municipio` on the majority of those (the address point sits in the municipio's own
+                    // main town, not a below-municipio pedanía) — only ~32.6% of ES rows carry a genuinely
+                    // DISTINCT poblacion. GB/NZ never hit this (CITY/DISTRICT name the same place only by rare
+                    // coincidence), but the guard is general: a dependent_locality equal to its own locality is
+                    // never a real sub-locality, so drop it rather than emit a same-value pair (would fail the
+                    // dep_loc≠locality invariant every recipe otherwise upholds).
+                    dependent_locality =
+                        cleanedCity && cleanedCity.localeCompare(locality, undefined, { sensitivity: "base" }) !== 0
+                            ? cleanedCity
+                            : undefined;
                 }
                 else {
                     locality = cleanCityNoise(rawCity);
                 }
             }
             else {
+                if (!rawCity)
+                    continue;
                 locality = cleanCityNoise(rawCity);
             }
             if (!locality) {
@@ -235,13 +298,58 @@ export async function readTuples(part, rng) {
     console.error(`  ${part.path ?? part.csv}: ${reservoir.length} sampled of ${seen} rows (${dropped} city-noise drops)`);
     return reservoir;
 }
+/**
+ * Country-append fraction (the fr-admin-split #728 pattern, generalized to the locale recipe): mutates `synth` in
+ * place, `countryFraction` of the time appending an explicit country surface form ("United Kingdom") to `raw` + 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. `countryFraction <= 0` (the default) short-circuits the `random()` draw away
+ * entirely — no `synth` mutation and no RNG consumption — so every existing locale's emit stream stays byte-identical
+ * to before this option existed. Exported for {@link locale.test.ts}.
+ */
+export function applyCountryAppend(synth, country, countryFraction, random) {
+    if (countryFraction > 0 && random() < countryFraction) {
+        const forms = COUNTRY_SURFACE_FORMS[country];
+        if (!forms?.length) {
+            // The BR/NZ lesson: a missing table entry must never silently no-op a requested fraction —
+            // it must raise so the gap is caught at build time, not discovered later as a 0% gate failure.
+            throw new Error(`No COUNTRY_SURFACE_FORMS entry for ${country} — add it to codex/country/country.ts before using --country-fraction`);
+        }
+        const form = forms[Math.floor(random() * forms.length)];
+        synth.raw = `${synth.raw}, ${form}`;
+        synth.components = { ...synth.components, country: form };
+    }
+}
+/**
+ * Merge the `--district-as-locality` CLI override onto one part. `undefined` (flag absent) returns `part` unchanged
+ * (same object — no allocation, no behavior change); `true`/`false` returns a shallow copy with `districtAsLocality`
+ * forced to that value for this invocation only. Exported for {@link locale.test.ts}.
+ */
+export function applyDistrictAsLocalityOverride(part, override) {
+    return override === undefined ? part : { ...part, districtAsLocality: override };
+}
+/**
+ * Pick which part list a `--country` run reads: {@link LocaleCountrySource.pedaniaParts} when the override is explicitly
+ * `true` AND the country registers one (ES only, so far), else the default `parts` — unchanged for every other
+ * country/override combination. Exported for {@link locale.test.ts}.
+ */
+export function resolveLocaleParts(countrySource, override) {
+    return override === true && countrySource.pedaniaParts ? countrySource.pedaniaParts : countrySource.parts;
+}
 export const localeRecipe = {
     name: "locale",
-    description: "Per-locale coverage rows (DE/FR/NL/IT/ES) from real OA tuples, both orders → synthesizeLocaleRow",
+    description: "Per-locale coverage rows (DE/FR/NL/IT/ES/NZ/GB) from real OA tuples, both orders → synthesizeLocaleRow",
     mode: "generate",
     options: [
-        { flag: "--country <cc>", description: "Target country (DE|FR|NL|IT|ES|NZ). Default DE" },
+        { flag: "--country <cc>", description: "Target country (DE|FR|NL|IT|ES|NZ|GB). Default DE" },
         { flag: "--intl-fraction <f>", description: "Fraction rendered international order. Default 0.4" },
+        {
+            flag: "--country-fraction <f>",
+            description: "Fraction of rows that append an explicit country surface form (`, United Kingdom`) + a `country` component (fr-admin-split pattern). Default 0 — byte-identical to before when unset.",
+        },
+        {
+            flag: "--district-as-locality / --no-district-as-locality",
+            description: "Override the per-part districtAsLocality mapping for this run. Unset (default) leaves each COUNTRY_SOURCES part's own value untouched — every existing build stays byte-identical. ES additionally switches to the pedanía (poblacion→dependent_locality) source when passed as true — combine with --source-name synth-es-pedania.",
+        },
     ],
     async run(opts, write) {
         // Emit PRNG: the legacy build-locale-shard.mjs seeded mulberry32(opts.seed). The reservoir uses a
@@ -256,15 +364,27 @@ export const localeRecipe = {
         if (!(intlFraction >= 0 && intlFraction <= 1)) {
             throw new Error(`--intl-fraction must be in [0, 1], got ${intlFraction}`);
         }
+        // Default 0 → the `random() < countryFraction` draw below is short-circuited away entirely (never
+        // consumed), so every existing locale's emit stream is byte-identical to before this option existed.
+        const countryFraction = opts.countryFraction ?? 0;
+        if (!(countryFraction >= 0 && countryFraction <= 1)) {
+            throw new Error(`--country-fraction must be in [0, 1], got ${countryFraction}`);
+        }
         const source = opts.sourceName ?? countrySource.source;
         const count = opts.count ?? 4000;
-        const { parts } = countrySource;
+        // Tri-state: `undefined` (flag absent) touches nothing below — `parts` stays the default list and each
+        // part keeps its own `districtAsLocality`, so every existing locale build is byte-identical to before this
+        // option existed. `true` additionally selects `pedaniaParts` when the country registers one (ES); `false`
+        // forces the mapping off on every part read this run (a debugging escape hatch for GB/NZ).
+        const districtAsLocalityOverride = opts.districtAsLocality;
+        const parts = resolveLocaleParts(countrySource, districtAsLocalityOverride);
         const pool = [];
         for (let pi = 0; pi < parts.length; pi++) {
             // A reservoir PRNG per part, seeded but independent of the emit loop's `random`, so the sample is
             // reproducible without perturbing the synth/order draws.
             const reservoirRng = makeMulberry32((opts.seed ^ (0x9e3779b9 * (pi + 1))) >>> 0);
-            const t = await readTuples(parts[pi], reservoirRng);
+            const effectivePart = applyDistrictAsLocalityOverride(parts[pi], districtAsLocalityOverride);
+            const t = await readTuples(effectivePart, reservoirRng);
             for (const x of t) {
                 pool.push(x);
             } // NOT pool.push(...t) — spreading huge arrays overflows the stack
@@ -292,6 +412,7 @@ export const localeRecipe = {
                 skipped++;
                 continue;
             }
+            applyCountryAppend(synth, country, countryFraction, random);
             if (opts.golden) {
                 // Golden rows must round-trip through alignRow exactly like training rows (#241 done-when): a
                 // render that can't be BIO-labeled can't serve as a parser golden either. Consumes no RNG draw.