@mailwoman/corpus 9.4.0 → 10.0.0

package/out/fr/recipes/order.js

@@ -0,0 +1,198 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `fr-order` slice 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-slice.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 { dataRootPath } from "@mailwoman/core/data-root";
+import { isPresent } from "@mailwoman/core/objects";
+import { mulberry32 as makeMulberry32 } from "@mailwoman/core/utils";
+import { stableSourceID } from "#adapters/utils";
+import { readOATuples } from "#recipes/scaffold";
+import { pick } from "#synthesizers/utils";
+import { alignRow } from "#utils";
+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 = ["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;
+/**
+ * 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
+ * slice's core signal) and a postcode (required for reversed-order rendering to be meaningful; it is also part of this
+ * recipe's dedup key).
+ */
+async function readTuples(limit) {
+    return readOATuples(SOURCE, {
+        limit,
+        requirePostcode: true,
+        dedupIncludesPostcode: true,
+        extra: (fields) => fields,
+    });
+}
+/**
+ * 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, house_number) {
+    if (random() >= ORDINAL_PROB)
+        return house_number;
+    const suffix = pick(ORDINAL_SUFFIXES, random);
+    // 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, street, postcode, locality) {
+    const raw = `${hn} ${street}, ${postcode} ${locality}`;
+    return { raw, components: { house_number: hn, street, postcode, locality } };
+}
+// Reversed layouts, a quarter each: A postcode+city then HN+street; B city, postcode, HN+street; C run-together;
+// D postcode, HN+street, city.
+const REVERSED_VARIANT_A_CUTOFF = 0.25;
+const REVERSED_VARIANT_B_CUTOFF = 0.5;
+const REVERSED_VARIANT_C_CUTOFF = 0.75;
+/**
+ * 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 frOrderRecipe = {
+    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-slice.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;
+            if (isReversed) {
+                const variantRoll = random();
+                let raw;
+                if (variantRoll < REVERSED_VARIANT_A_CUTOFF) {
+                    // Variant A: postcode+city as a unit, then HN+street
+                    raw = `${postcode} ${locality}, ${house_number} ${street}`;
+                }
+                else if (variantRoll < REVERSED_VARIANT_B_CUTOFF) {
+                    // Variant B: city, then postcode, then HN+street (comma-separated, postcode isolated)
+                    raw = `${locality}, ${postcode}, ${house_number} ${street}`;
+                }
+                else if (variantRoll < REVERSED_VARIANT_C_CUTOFF) {
+                    // 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 = {
+                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 };
+    },
+};
+//# sourceMappingURL=order.js.map

package/out/fr/recipes/order.js.map

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

package/out/fr/tools/fetch/ban.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Fetch the full French BAN (Base Adresse Nationale) — all metropolitan départements (01-95, 2A,
+ *   2B) plus 5 overseas DOM/TOM (971-976 excl. 975).
+ *
+ *   Source: https://adresse.data.gouv.fr/data/ban/adresses/latest/csv/
+ *   Licence: Licence Ouverte 2.0 (attribution required — Tier B).
+ *
+ *   Files already present with matching sha256 are skipped (re-runnable). Downloads `.csv.gz`,
+ *   decompresses to `.csv`, deletes the `.gz` artifact. One shared `MANIFEST.json` at
+ *   `<outRoot>/ban/MANIFEST.json` covers all codes.
+ *
+ *   Invoke via `mailwoman corpus fetch ban --out-root <path>`. Built-in `fetch` with gzip/brotli
+ *   decompression replaces curl; native `node:zlib` gunzip replaces the `gunzip` subprocess; no
+ *   Python.
+ */
+import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download/index";
+export interface BanManifestEntry {
+    dept_code: string;
+    filename: string;
+    source_url: string;
+    downloaded_at: string;
+    sha256: string;
+    bytes: number;
+}
+export type FetchBanOptions = BaseFetchOptions;
+export declare function fetchBan(options: FetchBanOptions, report?: (line: string) => void): Promise<FetchSummary>;
+//# sourceMappingURL=ban.d.ts.map

package/out/fr/tools/fetch/ban.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ban.d.ts","sourceRoot":"","sources":["../../../../lib/fr/tools/fetch/ban.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAUH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAsHjF,MAAM,WAAW,gBAAgB;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;CACb;AAED,MAAM,MAAM,eAAe,GAAG,gBAAgB,CAAA;AAE9C,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAmI/G"}

package/out/fr/tools/fetch/ban.js

@@ -0,0 +1,239 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Fetch the full French BAN (Base Adresse Nationale) — all metropolitan départements (01-95, 2A,
+ *   2B) plus 5 overseas DOM/TOM (971-976 excl. 975).
+ *
+ *   Source: https://adresse.data.gouv.fr/data/ban/adresses/latest/csv/
+ *   Licence: Licence Ouverte 2.0 (attribution required — Tier B).
+ *
+ *   Files already present with matching sha256 are skipped (re-runnable). Downloads `.csv.gz`,
+ *   decompresses to `.csv`, deletes the `.gz` artifact. One shared `MANIFEST.json` at
+ *   `<outRoot>/ban/MANIFEST.json` covers all codes.
+ *
+ *   Invoke via `mailwoman corpus fetch ban --out-root <path>`. Built-in `fetch` with gzip/brotli
+ *   decompression replaces curl; native `node:zlib` gunzip replaces the `gunzip` subprocess; no
+ *   Python.
+ */
+import { gunzip } from "@mailwoman/core/fs/compression";
+import { BYTES_PER_KIB, ByteFormatter } from "@mailwoman/core/fs/formatters";
+import { isFile, readLocalBuffer, tryStat } from "@mailwoman/core/fs/readers";
+import { makeDirectories, removePath, writeLocalFile } from "@mailwoman/core/fs/writers";
+import { sha256File } from "@mailwoman/core/hash";
+import { sleep } from "@mailwoman/core/utils/sleep";
+import { join } from "path-ts";
+import { downloadToFile, loadManifestEntries, writeManifest } from "#tools/fetch/download/index";
+/**
+ * Bytes per KiB — the divisor for human-readable sizes, and the floor below which a "download" is an error page rather
+ * than data.
+ */
+const BASE_URL = "https://adresse.data.gouv.fr/data/ban/adresses/latest/csv";
+/**
+ * All département codes — metropolitan 01-95 (with 2A/2B for Corsica instead of 20) plus overseas DOM/TOM. Codes do not
+ * change.
+ */
+const DEPT_CODES = [
+    "01",
+    "02",
+    "03",
+    "04",
+    "05",
+    "06",
+    "07",
+    "08",
+    "09",
+    "10",
+    "11",
+    "12",
+    "13",
+    "14",
+    "15",
+    "16",
+    "17",
+    "18",
+    "19",
+    "21",
+    "22",
+    "23",
+    "24",
+    "25",
+    "26",
+    "27",
+    "28",
+    "29",
+    "2A",
+    "2B",
+    "30",
+    "31",
+    "32",
+    "33",
+    "34",
+    "35",
+    "36",
+    "37",
+    "38",
+    "39",
+    "40",
+    "41",
+    "42",
+    "43",
+    "44",
+    "45",
+    "46",
+    "47",
+    "48",
+    "49",
+    "50",
+    "51",
+    "52",
+    "53",
+    "54",
+    "55",
+    "56",
+    "57",
+    "58",
+    "59",
+    "60",
+    "61",
+    "62",
+    "63",
+    "64",
+    "65",
+    "66",
+    "67",
+    "68",
+    "69",
+    "70",
+    "71",
+    "72",
+    "73",
+    "74",
+    "75",
+    "76",
+    "77",
+    "78",
+    "79",
+    "80",
+    "81",
+    "82",
+    "83",
+    "84",
+    "85",
+    "86",
+    "87",
+    "88",
+    "89",
+    "90",
+    "91",
+    "92",
+    "93",
+    "94",
+    "95",
+    "971",
+    "972",
+    "973",
+    "974",
+    "976",
+];
+export async function fetchBan(options, report) {
+    const banDir = join(options.outRoot, "ban");
+    const manifestPath = join(banDir, "MANIFEST.json");
+    await makeDirectories(banDir);
+    // Load existing entries (code -> entry): skip detection + preservation of untouched codes.
+    const entries = await loadManifestEntries(manifestPath, (entry) => entry.dept_code);
+    let fetched = 0;
+    let skipped = 0;
+    let failed = 0;
+    const failedCodes = [];
+    for (const code of DEPT_CODES) {
+        const filename = `adresses-${code}.csv`;
+        const gzFile = join(banDir, `${filename}.gz`);
+        const csvFile = join(banDir, filename);
+        const url = `${BASE_URL}/adresses-${code}.csv.gz`;
+        report?.(`=== dept ${code}`);
+        // If the CSV already exists, compare its sha256 against the manifest.
+        if (await isFile(csvFile)) {
+            const existingSha = await sha256File(csvFile);
+            const recordedSha = entries.get(code)?.sha256;
+            if (recordedSha && existingSha === recordedSha) {
+                report?.(`  → already present + sha matches — skipping`);
+                skipped++;
+                continue;
+            }
+            report?.(`  → present but sha mismatch or no manifest entry — re-fetching`);
+            await removePath(csvFile);
+        }
+        // Download the gzipped CSV.
+        try {
+            await downloadToFile({
+                url,
+                dest: gzFile,
+                timeoutMs: 600_000,
+                headers: { "Accept-Encoding": "gzip, br" },
+                report,
+            });
+        }
+        catch (error) {
+            report?.(`  ✗ download failed: ${url} (${error.message})`);
+            failed++;
+            failedCodes.push(code);
+            continue;
+        }
+        // Guard against truncated 404/error pages.
+        const gzSize = (await tryStat(gzFile))?.size ?? 0;
+        if (gzSize < BYTES_PER_KIB) {
+            report?.(`  ✗ response too small (${gzSize} bytes) — probable 404 / error page`);
+            await removePath(gzFile);
+            failed++;
+            failedCodes.push(code);
+            continue;
+        }
+        // Decompress in-place; delete the .gz.
+        try {
+            await writeLocalFile(await gunzip(await readLocalBuffer(gzFile)), csvFile);
+        }
+        catch (error) {
+            report?.(`  ✗ decompress failed: ${error.message}`);
+            await removePath(gzFile);
+            failed++;
+            failedCodes.push(code);
+            continue;
+        }
+        await removePath(gzFile);
+        if (!(await isFile(csvFile))) {
+            report?.(`  ✗ decompressed file not found at ${csvFile}`);
+            failed++;
+            failedCodes.push(code);
+            continue;
+        }
+        const bytes = (await tryStat(csvFile))?.size ?? 0;
+        const sha = await sha256File(csvFile);
+        entries.set(code, {
+            dept_code: code,
+            filename,
+            source_url: url,
+            downloaded_at: new Date().toISOString(),
+            sha256: sha,
+            bytes,
+        });
+        report?.(`  ✓ ${ByteFormatter.formatIEC(bytes)}  sha256=${sha}`);
+        fetched++;
+        // Be a polite citizen — short pause between requests.
+        await sleep(200);
+    }
+    // Write the consolidated MANIFEST.json (entries sorted by dept_code, codepoint order).
+    const sorted = [...entries.values()].toSorted((a, b) => a.dept_code < b.dept_code ? -1 : a.dept_code > b.dept_code ? 1 : 0);
+    await writeManifest(manifestPath, sorted);
+    report?.(`Wrote ${manifestPath} with ${sorted.length} entries.`);
+    report?.(`=== summary ===`);
+    report?.(`fetched:  ${fetched}`);
+    report?.(`skipped:  ${skipped} (already present + sha matched)`);
+    report?.(`failed:   ${failed}`);
+    if (failedCodes.length) {
+        report?.(`failed codes: ${failedCodes.join(" ")}`);
+    }
+    return { fetched, skipped, failed, failedCodes };
+}
+//# sourceMappingURL=ban.js.map

package/out/fr/tools/fetch/ban.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ban.js","sourceRoot":"","sources":["../../../../lib/fr/tools/fetch/ban.ts"],"names":[],"mappings":"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"}

package/out/index.d.ts

@@ -4,7 +4,7 @@
  * @author Teffen Ellis, et al.
  */
 export * from "#adapters/utils/index";
-export * from "#adapters/gnaf/assemble";
+export * from "#au/adapters/gnaf/assemble";
 export * from "#adapters/index";
 export * from "#build";
 export * from "#runner";

package/out/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,uBAAuB,CAAA;AACrC,cAAc,yBAAyB,CAAA;AACvC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,QAAQ,CAAA;AACtB,cAAc,SAAS,CAAA;AACvB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,QAAQ,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,uBAAuB,CAAA;AACrC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,iBAAiB,CAAA;AAC/B,cAAc,QAAQ,CAAA;AACtB,cAAc,SAAS,CAAA;AACvB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,QAAQ,CAAA"}

package/out/index.js

@@ -4,7 +4,7 @@
  * @author Teffen Ellis, et al.
  */
 export * from "#adapters/utils/index";
-export * from "#adapters/gnaf/assemble";
+export * from "#au/adapters/gnaf/assemble";
 export * from "#adapters/index";
 export * from "#build";
 export * from "#runner";

package/out/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,uBAAuB,CAAA;AACrC,cAAc,yBAAyB,CAAA;AACvC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,QAAQ,CAAA;AACtB,cAAc,SAAS,CAAA;AACvB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,QAAQ,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,uBAAuB,CAAA;AACrC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,iBAAiB,CAAA;AAC/B,cAAc,QAAQ,CAAA;AACtB,cAAc,SAAS,CAAA;AACvB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,QAAQ,CAAA"}

package/out/international/recipes/locale.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `locale` slice recipe — the multi-locale generalization of the `german` recipe. Reads REAL
+ *   OpenAddresses tuples for a `--country` (DE/FR/NL/IT/ES), renders each via
+ *   {@link synthesizeLocaleRow} in BOTH orders (`--intl-fraction`, default 0.4 international / the
+ *   rest country-native), aligns to BIO, and emits a labeled JSONL. Generate-mode: it STREAMS each
+ *   source CSV (a streamed zip member for cached zips, plain `createReadStream` for extracted CSVs) and
+ *   reservoir-samples to {@link RESERVOIR_CAP} (so FR/ES countrywide work in bounded memory), then
+ *   draws `--count` rows from the pool with the passed `random`. Ported from
+ *   scripts/build-locale-slice.mjs.
+ *
+ *   The reservoir uses its OWN seeded PRNG ({@link makeMulberry32}, per part), independent of the
+ *   emit `random`, so the input sample is reproducible WITHOUT perturbing the synth/order draws.
+ *
+ *   SURFACE DIVERSITY (#241): two per-country shape draws ride the emit loop, sized by the
+ *   2026-07-02 format-diversity audit against the `openaddresses-{es,nl,it}-sample.jsonl` observed
+ *   forms. ES: the OpenCage template comma-joins the house number (`CALLE MAYOR, 12`) but all 3,000
+ *   eval rows space-join (`CALLE MAYOR 12`) — {@link ES_SPACE_JOIN_FRACTION} of native rows collapse
+ *   the comma. NL: OA (and the eval, 3,000/3,000) glue the postcode (`1187LM`) while the national
+ *   convention spaces it (`1187 LM`) — {@link NL_GLUED_POSTCODE_FRACTION} of rows keep the glued
+ *   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 { PathBuilderLike } from "path-ts";
+import type { CorpusRecipe } from "#recipes/scaffold";
+import { type LocaleBaseTuple, type SynthesizedLocaleRow } from "#synthesizers/locale";
+/**
+ * One per-country OA source part: either a cached `zip` + `csv` member (streamed out of the archive) or an extracted
+ * plain `path` (streamed via `createReadStream`). Both carry the standard OA header
+ * (LON,LAT,NUMBER,STREET,UNIT,CITY,DISTRICT,REGION,POSTCODE,ID,HASH). An optional `region` fallback covers countries
+ * whose REGION column is empty (DE — the Bundesland is implied by the per-state file).
+ */
+export interface LocalePart {
+    zip?: PathBuilderLike;
+    csv?: string;
+    path?: PathBuilderLike;
+    region?: string;
+    /**
+     * NZ — the OA DISTRICT column holds the city (`Auckland`) and CITY holds the suburb (`Birkenhead`). When set, map
+     * DISTRICT→locality and CITY→dependent_locality (falling back to CITY→locality when DISTRICT is empty, ~18% of NZ
+     * 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 slices 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
+ * the ES (15.6M rows), IT (13.9M), and NL (9.1M) sources (not a hand-list). Returns the cleaned city, or `null` to drop
+ * the tuple.
+ *
+ * Cleaned classes:
+ *
+ * 1. DROP pseudo-localities — the ES cadastral aggregates (`Comunidad de 09076, 09150 y 09578`, `Ledanía de …`; 0.06% of
+ *    ES rows): any CITY containing a comma or a ≥4-digit run is a land-register aggregate, not a renderable city.
+ *    Structural, locale-safe — NL's genuine `2e Valthermond` (one digit) survives; IT/NL have zero hits.
+ * 2. STRIP a trailing parenthesized 1–3-letter admin code — the NL BAG province disambiguator (`Bergen (NH)`, `Rijswijk
+ *    (GLD)` → `Bergen`, `Rijswijk`; 0.13% of NL rows). The analogue of the German Kreis/region-suffix class (#241 names
+ *    `Rabenau Sachs` / `Weißwasser /O.L.`): an admin-region gloss glued onto the locality value that dirties locality
+ *    labels.
+ *
+ * Audit-verified NON-noise, deliberately NOT cleaned (a naive suffix rule would mangle real names):
+ *
+ * - ES/IT city-ends-with-province (`Alhama de Almería`, `GENZANO DI ROMA`; ~0.8% each): genuine toponyms whose linking
+ *   `de`/`di` makes them full names, unlike the German glued-abbreviation class.
+ * - ES bilingual slash names (`Laudio/Llodio`; 2.16%): official co-names — the eval expects them verbatim.
+ * - IT ALL-CAPS city casing (98.79% of the source, and the eval's observed form): casing is the #829 case-augmentation
+ *   change, not this slice's.
+ */
+export declare function cleanCityNoise(city: string): string | null;
+/**
+ * Stream real tuples out of an OA source part and reservoir-sample to {@link RESERVOIR_CAP}. Reads the CSV row-by-row —
+ * `readZipEntry | CSVSpliterator` for zip parts, `createReadStream | CSVSpliterator` for extracted parts (both bounded
+ * memory) — and keeps a uniform random sample (Algorithm R) seeded by `rng`, separate from the emit loop's PRNG. NO
+ * global dedup (a 25M-key Set would OOM; OA rows are near-unique). The city passes through {@link cleanCityNoise}; the
+ * region falls back to `part.region` when the row's REGION cell is empty (DE).
+ *
+ * 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[];
+/**
+ * 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 declare const localeRecipe: CorpusRecipe;
+//# sourceMappingURL=locale.d.ts.map