@mailwoman/ban 5.7.0

package/README.md

@@ -0,0 +1,54 @@
+# @mailwoman/ban
+
+Base Adresse Nationale (France) rooftop ingestion. This package reads the open BAN CSV dumps
+(`adresses-<dept>.csv`, adresse.data.gouv.fr) and builds the **national FR address-point shard** on the
+same situs schema the US rooftop tier already uses — so the existing `AddressPointSqliteLookup` reads it
+with zero changes, and the resolver gains rooftop precision across France from the authoritative
+government register (26M addresses) instead of the sparse community fallback (OSM-FR, ~1.1M points).
+
+It is the French counterpart of the 50-state US situs layer (#1012). It closes the measured FR rooftop
+gap: commune resolution was already ~99% @25 km, but @1 km sat at ~37% and was _flat_ from clean to messy
+input — the flatness is the tell of a coverage ceiling, not a parse problem. BAN is the coverage.
+
+## The licensing boundary
+
+Unlike the ODbL OpenStreetMap tier, BAN is published under the **Licence Ouverte / Open Licence 2.0
+(Etalab)** — attribution only, **no share-alike**. So the built shard ships under the same terms as the
+permissive Mailwoman core (Who's On First, Overture, OpenAddresses, GeoNames); there is no lawyer sign-off
+gate. The one standing obligation is attribution:
+
+- **This package is code, and code only.** It contains no BAN bytes.
+- **Attribution rides on any result resolved through a BAN point.** The `source` on every BAN point is
+  `ban:fr`, and the resolver should surface
+  _"© les contributeurs de la Base Adresse Nationale (adresse.data.gouv.fr)"_.
+
+## Building the shard
+
+BAN's per-département dumps land under `$MAILWOMAN_DATA_ROOT/…/ban/` (or the corpus source dir). The build
+streams them — no external CLI, no DuckDB — so it is dependency-light and OOM-safe on the 26M-row national
+set.
+
+```bash
+# 1. Download the per-département dumps (or the national adresses-france.csv.gz):
+#    https://adresse.data.gouv.fr/data/ban/adresses/latest/csv/adresses-<dept>.csv.gz
+#    → $MAILWOMAN_DATA_ROOT/ban/sources/   (or reuse an existing corpus/sources/ban)
+
+# 2. Build the national shard (writes $MAILWOMAN_DATA_ROOT/ban/address-points-fr.db, sealed 0444):
+node ban/out/scripts/build-address-point-shard.js \
+  --csv-dir $MAILWOMAN_DATA_ROOT/corpus/sources/ban --release 2026-05-18
+
+# Validate on a few départements first (transient; skips the provenance rewrite):
+node ban/out/scripts/build-address-point-shard.js --depts 48,2A,05 --out /tmp/ban-sample.db
+```
+
+The build records provenance (source URL, license, release, row count, md5) in `ban/ATTRIBUTION.json` at
+creation, seals the artifact read-only, and swaps it into place atomically — it is a new, purely-additive
+file and never touches the OSM shard beside it.
+
+## The resolution tier
+
+`BANShardProvider.for(country)` is wired into `GeocodeDeps.nationalShards`, consulted **ahead of** the OSM
+`osmShards` tier (a national authoritative register outranks the community fallback) and only for a non-US
+parse. BAN rows carry their own postcode + commune, so the lookup keys on the scoped
+(`postcode` → `locality`) probes; no bbox fall-through is needed. Interpolation for house numbers BAN
+doesn't carry is not built yet — the exact-point tier is the whole win here (BAN's density is the point).

package/out/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/ban` — Base Adresse Nationale (France) rooftop address-point ingestion. The FR
+ *   counterpart of the 50-state US situs layer (#1012): the national government address register (26M
+ *   addresses) that closes the rooftop gap OSM-FR (~1.1M points) can't. PERMISSIVE CODE ONLY — this
+ *   workspace contains no BAN data bytes. It reads the open `adresses-<dept>.csv` dumps
+ *   (adresse.data.gouv.fr, Licence Ouverte/Etalab) and writes a national FR shard on the SHARED situs
+ *   schema (`@mailwoman/resolver-wof-sqlite/address-point-schema`), so the existing
+ *   `AddressPointSqliteLookup` reads it with zero changes. See `./sdk` for the ingestion surface and
+ *   `./scripts/build-address-point-shard` for the build CLI.
+ */
+export * from "./sdk/index.js";
+//# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,cAAc,gBAAgB,CAAA"}

package/out/index.js

@@ -0,0 +1,16 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/ban` — Base Adresse Nationale (France) rooftop address-point ingestion. The FR
+ *   counterpart of the 50-state US situs layer (#1012): the national government address register (26M
+ *   addresses) that closes the rooftop gap OSM-FR (~1.1M points) can't. PERMISSIVE CODE ONLY — this
+ *   workspace contains no BAN data bytes. It reads the open `adresses-<dept>.csv` dumps
+ *   (adresse.data.gouv.fr, Licence Ouverte/Etalab) and writes a national FR shard on the SHARED situs
+ *   schema (`@mailwoman/resolver-wof-sqlite/address-point-schema`), so the existing
+ *   `AddressPointSqliteLookup` reads it with zero changes. See `./sdk` for the ingestion surface and
+ *   `./scripts/build-address-point-shard` for the build CLI.
+ */
+export * from "./sdk/index.js";
+//# sourceMappingURL=index.js.map

package/out/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,cAAc,gBAAgB,CAAA"}

package/out/scripts/build-address-point-shard.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Build the national FR ROOFTOP address-point shard from the BAN `adresses-<dept>.csv` dumps
+ *   (adresse.data.gouv.fr), on the SHARED situs schema (`@mailwoman/resolver-wof-sqlite/address-point-schema`)
+ *   so the existing `AddressPointSqliteLookup` reads it with zero changes (#1012). BAN is a structured
+ *   government register — every row carries `numero`/`nom_voie`/`code_postal`/`nom_commune`/`lon`/`lat`,
+ *   so there is no OSM-style association gap: we write the exact source coordinate for every valid row.
+ *
+ *   The `rep` (repetition: bis/ter/…) is folded into the house-number key (`"8 bis"`), so a parsed
+ *   `"8 bis Rue X"` matches; plain-number rows are keyed on the bare number, unchanged. Keying uses THE
+ *   shared FR normalizer (`normalizeStreetForKeyLocale(street, "fr")`) — the identical function the
+ *   lookup tier applies at query time, so build-side and probe-side can't drift.
+ *
+ *   Build discipline (house rules): stream → positional prepared INSERT (batched) → indexes → ANALYZE →
+ *   atomic swap into place → SEAL 0444 → record md5 + provenance in `ban/ATTRIBUTION.json`. The output
+ *   is a NEW, purely-additive artifact (`ban/address-points-fr.db`); it never touches the OSM shard.
+ *
+ *   BAN is published under the Licence Ouverte / Etalab 2.0 (attribution, NO share-alike), so the built
+ *   shard ships under the same terms as the permissive core — no ODbL lawyer gate. `source = "ban:fr"`.
+ *
+ *   Usage:
+ *     node ban/out/scripts/build-address-point-shard.js \
+ *       --csv-dir $MAILWOMAN_DATA_ROOT/corpus/sources/ban --release 2026-05-18
+ *     # validate on a few départements first:
+ *     node ban/out/scripts/build-address-point-shard.js --depts 48,2A,05 --out /tmp/ban-sample.db
+ */
+export {};
+//# sourceMappingURL=build-address-point-shard.d.ts.map

package/out/scripts/build-address-point-shard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-address-point-shard.d.ts","sourceRoot":"","sources":["../../scripts/build-address-point-shard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG"}

package/out/scripts/build-address-point-shard.js

@@ -0,0 +1,201 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Build the national FR ROOFTOP address-point shard from the BAN `adresses-<dept>.csv` dumps
+ *   (adresse.data.gouv.fr), on the SHARED situs schema (`@mailwoman/resolver-wof-sqlite/address-point-schema`)
+ *   so the existing `AddressPointSqliteLookup` reads it with zero changes (#1012). BAN is a structured
+ *   government register — every row carries `numero`/`nom_voie`/`code_postal`/`nom_commune`/`lon`/`lat`,
+ *   so there is no OSM-style association gap: we write the exact source coordinate for every valid row.
+ *
+ *   The `rep` (repetition: bis/ter/…) is folded into the house-number key (`"8 bis"`), so a parsed
+ *   `"8 bis Rue X"` matches; plain-number rows are keyed on the bare number, unchanged. Keying uses THE
+ *   shared FR normalizer (`normalizeStreetForKeyLocale(street, "fr")`) — the identical function the
+ *   lookup tier applies at query time, so build-side and probe-side can't drift.
+ *
+ *   Build discipline (house rules): stream → positional prepared INSERT (batched) → indexes → ANALYZE →
+ *   atomic swap into place → SEAL 0444 → record md5 + provenance in `ban/ATTRIBUTION.json`. The output
+ *   is a NEW, purely-additive artifact (`ban/address-points-fr.db`); it never touches the OSM shard.
+ *
+ *   BAN is published under the Licence Ouverte / Etalab 2.0 (attribution, NO share-alike), so the built
+ *   shard ships under the same terms as the permissive core — no ODbL lawyer gate. `source = "ban:fr"`.
+ *
+ *   Usage:
+ *     node ban/out/scripts/build-address-point-shard.js \
+ *       --csv-dir $MAILWOMAN_DATA_ROOT/corpus/sources/ban --release 2026-05-18
+ *     # validate on a few départements first:
+ *     node ban/out/scripts/build-address-point-shard.js --depts 48,2A,05 --out /tmp/ban-sample.db
+ */
+import { createHash } from "node:crypto";
+import { createReadStream, existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { dirname } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { parseArgs } from "node:util";
+import { DatabaseClient } from "@mailwoman/core/kysley/client";
+import { dataRootPath, sealDatabase } from "@mailwoman/core/utils";
+import { ADDRESS_POINT_COLUMNS, createAddressPointIndexes, createAddressPointTable, } from "@mailwoman/resolver-wof-sqlite/address-point-schema";
+import { canonicalizeRouteKey, normalizeLocalityForKey, normalizeStreetForKeyLocale, } from "@mailwoman/resolver-wof-sqlite/street-normalize";
+import { extractBANAddrPoints } from "../sdk/extract.js";
+import { BAN_ATTRIBUTION, BAN_CSV_BASE, BAN_LICENSE } from "../sdk/fetch.js";
+import { streetLocaleForBANCountry } from "../sdk/street-locale.js";
+function parse() {
+    const { values } = parseArgs({
+        options: {
+            country: { type: "string" },
+            "csv-dir": { type: "string" },
+            release: { type: "string" },
+            out: { type: "string" },
+            depts: { type: "string" },
+        },
+    });
+    const country = (values.country ?? "fr").toLowerCase();
+    // Throws for an unsupported country — fail loud, never key with the wrong normalizer.
+    streetLocaleForBANCountry(country);
+    const csvDir = values["csv-dir"] ?? dataRootPath("corpus", "sources", "ban");
+    if (!existsSync(csvDir))
+        throw new Error(`BAN CSV dir not found: ${csvDir}`);
+    const release = values.release ?? "2026-05-18";
+    const output = values.out ?? dataRootPath("ban", `address-points-${country}.db`);
+    const depts = values.depts
+        ? values.depts
+            .split(",")
+            .map((d) => d.trim())
+            .filter(Boolean)
+        : null;
+    return { country, csvDir, release, output, depts };
+}
+/**
+ * Enumerate the per-département BAN dumps in `csvDir`, keyed by département code. Excludes the `merged` / `france`
+ * aggregates (they duplicate the per-département rows), and prefers an uncompressed `.csv` over a `.csv.gz` when both
+ * exist (the same dept, faster read). When `depts` is set, restricts to that list (for a fast validation build).
+ */
+function departementFiles(csvDir, depts) {
+    const byDept = new Map();
+    const wanted = depts ? new Set(depts.map((d) => d.toLowerCase())) : null;
+    for (const name of readdirSync(csvDir).sort()) {
+        const m = /^adresses-(.+?)\.csv(\.gz)?$/.exec(name);
+        if (!m)
+            continue;
+        const dept = m[1];
+        // The aggregate dumps double-count the per-département rows — skip them.
+        if (dept === "merged" || dept === "france")
+            continue;
+        if (wanted && !wanted.has(dept.toLowerCase()))
+            continue;
+        const path = `${csvDir}/${name}`;
+        const existing = byDept.get(dept);
+        // Prefer the uncompressed .csv over a .csv.gz for the same dept.
+        if (!existing || (existing.endsWith(".gz") && !name.endsWith(".gz"))) {
+            byDept.set(dept, path);
+        }
+    }
+    return byDept;
+}
+/** Streaming md5 of a file (never buffer a multi-GB artifact). */
+async function fileMD5(path) {
+    const hash = createHash("md5");
+    for await (const chunk of createReadStream(path)) {
+        hash.update(chunk);
+    }
+    return hash.digest("hex");
+}
+async function main() {
+    const args = parse();
+    const locale = streetLocaleForBANCountry(args.country);
+    const source = `ban:${args.country}`;
+    const files = departementFiles(args.csvDir, args.depts);
+    if (files.size === 0)
+        throw new Error(`no BAN département dumps found in ${args.csvDir}`);
+    const tmp = `${args.output}.building-${process.pid}.db`;
+    mkdirSync(dirname(args.output), { recursive: true });
+    for (const sfx of ["", "-wal", "-shm"]) {
+        rmSync(tmp + sfx, { force: true });
+    }
+    const out = new DatabaseSync(tmp);
+    out.exec("PRAGMA page_size=8192; PRAGMA journal_mode=OFF; PRAGMA synchronous=OFF; PRAGMA cache_size=-2000000;");
+    const kdb = new DatabaseClient({ database: out });
+    await createAddressPointTable(kdb);
+    const insert = out.prepare(`INSERT INTO address_point VALUES (${ADDRESS_POINT_COLUMNS.map(() => "?").join(", ")})`);
+    let total = 0;
+    let written = 0;
+    let noStreet = 0;
+    const BATCH = 50_000;
+    const deptList = [...files.keys()].sort();
+    console.error(`[ban] building ${args.country} rooftop shard from ${files.size} départements in ${args.csvDir}`);
+    out.exec("BEGIN");
+    for (const dept of deptList) {
+        const path = files.get(dept);
+        for await (const rec of extractBANAddrPoints(path)) {
+            total++;
+            const streetNorm = normalizeStreetForKeyLocale(rec.street, locale);
+            const numTrim = rec.numero.trim().toLowerCase();
+            if (!streetNorm || !numTrim) {
+                noStreet++;
+                continue;
+            }
+            // Fold `rep` into the house-number key: "8" + "bis" → "8 bis" (matches a parsed "8 bis Rue X").
+            const number = rec.rep ? `${numTrim} ${rec.rep}` : numTrim;
+            // Positional, in ADDRESS_POINT_COLUMNS order: street_norm, street_key, number, unit, postcode,
+            // locality_norm, street_raw, lat, lon, source, release.
+            insert.run(streetNorm, canonicalizeRouteKey(streetNorm), number, null, rec.postcode, rec.city ? normalizeLocalityForKey(rec.city) : null, rec.street, rec.lat, rec.lon, source, args.release);
+            written++;
+            if (written % BATCH === 0) {
+                out.exec("COMMIT");
+                out.exec("BEGIN");
+                if (written % 2_000_000 === 0) {
+                    console.error(`[ban]   ${written.toLocaleString()} written…`);
+                }
+            }
+        }
+        console.error(`[ban]   dept ${dept}: ${written.toLocaleString()} cumulative`);
+    }
+    out.exec("COMMIT");
+    console.error(`[ban] indexing…`);
+    await createAddressPointIndexes(kdb);
+    out.exec("ANALYZE");
+    await kdb.destroy();
+    // Atomic swap into place (move any prior aside first), then SEAL 0444.
+    if (existsSync(args.output)) {
+        renameSync(args.output, `${args.output}.prev`);
+    }
+    for (const sfx of ["-wal", "-shm"]) {
+        rmSync(args.output + sfx, { force: true });
+    }
+    renameSync(tmp, args.output);
+    if (existsSync(`${args.output}.prev`)) {
+        rmSync(`${args.output}.prev`, { force: true });
+    }
+    sealDatabase(args.output);
+    const md5 = await fileMD5(args.output);
+    const bytes = statSync(args.output).size;
+    // Provenance manifest — additive, written at creation (house discipline). Only for a FULL national build
+    // (the fast --depts validation builds are transient and don't rewrite the record).
+    if (!args.depts) {
+        const attributionPath = dataRootPath("ban", "ATTRIBUTION.json");
+        writeFileSync(attributionPath, JSON.stringify({
+            artifact: `address-points-${args.country}.db`,
+            source,
+            sourceURL: BAN_CSV_BASE,
+            license: BAN_LICENSE,
+            attribution: BAN_ATTRIBUTION,
+            release: args.release,
+            departements: deptList.length,
+            totalPoints: written,
+            bytes,
+            md5,
+            builtAt: new Date().toISOString(),
+        }, null, 2) + "\n");
+        console.error(`[ban] wrote ${attributionPath}`);
+    }
+    console.error(`[ban] DONE ${args.output}\n` +
+        `      départements                     : ${deptList.length}\n` +
+        `      total source rows                : ${total.toLocaleString()}\n` +
+        `      written points                   : ${written.toLocaleString()}\n` +
+        `      skipped (no street/number)       : ${noStreet.toLocaleString()}\n` +
+        `      bytes                            : ${bytes.toLocaleString()}\n` +
+        `      md5                              : ${md5}\n` +
+        `      source                           : ${source}  release=${args.release}  license=${BAN_LICENSE}`);
+}
+await main();
+//# sourceMappingURL=build-address-point-shard.js.map

package/out/scripts/build-address-point-shard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-address-point-shard.js","sourceRoot":"","sources":["../../scripts/build-address-point-shard.ts"],"names":[],"mappings":"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"}

package/out/sdk/ban.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The two contracts the BAN ingest must hold: (1) the extract locates its columns BY NAME off the
+ *   header (never by fixed position) and drops coordinate-less / streetless rows; (2) the provider is
+ *   FR-only and keys with the FR street locale — never a silent fold with the wrong rules. Build/probe
+ *   street-key consistency is covered by `@mailwoman/osm`'s `street-locale.test.ts` (same normalizer).
+ */
+export {};
+//# sourceMappingURL=ban.test.d.ts.map

package/out/sdk/ban.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ban.test.d.ts","sourceRoot":"","sources":["../../sdk/ban.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/out/sdk/ban.test.js

@@ -0,0 +1,50 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The two contracts the BAN ingest must hold: (1) the extract locates its columns BY NAME off the
+ *   header (never by fixed position) and drops coordinate-less / streetless rows; (2) the provider is
+ *   FR-only and keys with the FR street locale — never a silent fold with the wrong rules. Build/probe
+ *   street-key consistency is covered by `@mailwoman/osm`'s `street-locale.test.ts` (same normalizer).
+ */
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { expect, test } from "vitest";
+import { extractBANAddrPoints } from "./extract.js";
+import { streetLocaleForBANCountry, supportedBANCountries } from "./street-locale.js";
+const HEADER = "id;id_fantoir;numero;rep;nom_voie;code_postal;code_insee;nom_commune;code_insee_ancienne_commune;nom_ancienne_commune;x;y;lon;lat;type_position;alias;nom_ld;libelle_acheminement;nom_afnor;source_position;source_nom_voie;certification_commune;cad_parcelles";
+function fixtureCSV(rows) {
+    const dir = mkdtempSync(join(tmpdir(), "ban-test-"));
+    const path = join(dir, "adresses-48.csv");
+    writeFileSync(path, [HEADER, ...rows].join("\n") + "\n");
+    return path;
+}
+test("extract: yields the full tuple, folds rep to lower-case, skips coordinate-less rows", async () => {
+    const path = fixtureCSV([
+        "48004_x_1;;6;;Route de Pomaret;48800;48004;Altier;;;766812;6375458;3.840026;44.474983;entrée;;;;;;;1;",
+        "48005_x_2;;8;BIS;route de Laval;48310;48005;Albaret-le-Comtal;;;0;0;3.127407;44.877158;entrée;;;;;;;1;",
+        "48006_x_3;;9;;Rue Sans Coord;48000;48006;Mende;;;;;;;entrée;;;;;;;1;", // empty lon/lat → skipped
+    ]);
+    const recs = [];
+    for await (const r of extractBANAddrPoints(path)) {
+        recs.push(r);
+    }
+    expect(recs).toHaveLength(2);
+    expect(recs[0]).toMatchObject({
+        numero: "6",
+        rep: null,
+        street: "Route de Pomaret",
+        postcode: "48800",
+        city: "Altier",
+    });
+    expect(recs[0].lat).toBeCloseTo(44.474983);
+    expect(recs[1]).toMatchObject({ numero: "8", rep: "bis" }); // uppercase BIS folded
+});
+test("provider: FR-only, keys with the FR street locale, throws otherwise", () => {
+    expect(supportedBANCountries()).toEqual(["fr"]);
+    expect(streetLocaleForBANCountry("FR")).toBe("fr");
+    expect(() => streetLocaleForBANCountry("de")).toThrow(/No BAN street-normalization locale/);
+});
+//# sourceMappingURL=ban.test.js.map

package/out/sdk/ban.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ban.test.js","sourceRoot":"","sources":["../../sdk/ban.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAErC,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAErF,MAAM,MAAM,GACX,iQAAiQ,CAAA;AAElQ,SAAS,UAAU,CAAC,IAAc;IACjC,MAAM,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,WAAW,CAAC,CAAC,CAAA;IACpD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAA;IACzC,aAAa,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAA;IAExD,OAAO,IAAI,CAAA;AACZ,CAAC;AAED,IAAI,CAAC,qFAAqF,EAAE,KAAK,IAAI,EAAE;IACtG,MAAM,IAAI,GAAG,UAAU,CAAC;QACvB,uGAAuG;QACvG,wGAAwG;QACxG,sEAAsE,EAAE,0BAA0B;KAClG,CAAC,CAAA;IAEF,MAAM,IAAI,GAAG,EAAE,CAAA;IAEf,IAAI,KAAK,EAAE,MAAM,CAAC,IAAI,oBAAoB,CAAC,IAAI,CAAC,EAAE,CAAC;QAClD,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACb,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAA;IAC5B,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC;QAC7B,MAAM,EAAE,GAAG;QACX,GAAG,EAAE,IAAI;QACT,MAAM,EAAE,kBAAkB;QAC1B,QAAQ,EAAE,OAAO;QACjB,IAAI,EAAE,QAAQ;KACd,CAAC,CAAA;IACF,MAAM,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC,SAAS,CAAC,CAAA;IAC3C,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAA,CAAC,uBAAuB;AACnF,CAAC,CAAC,CAAA;AAEF,IAAI,CAAC,qEAAqE,EAAE,GAAG,EAAE;IAChF,MAAM,CAAC,qBAAqB,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;IAC/C,MAAM,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAClD,MAAM,CAAC,GAAG,EAAE,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,oCAAoC,CAAC,CAAA;AAC5F,CAAC,CAAC,CAAA"}

package/out/sdk/extract.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Stream rooftop address records out of a BAN `adresses-<dept>.csv` dump (adresse.data.gouv.fr). The
+ *   dump is a `;`-delimited, header-first CSV in which EVERY row already carries the full tuple —
+ *   `numero`, `rep`, `nom_voie`, `code_postal`, `nom_commune`, `lon`/`lat` — so there is no OSM-style
+ *   "association gap" (a point with no street): BAN is a structured government register, not a
+ *   community tag soup. We stream line-by-line (the national set is 26M rows / ~5 GB uncompressed);
+ *   `.csv.gz` inputs are transparently gunzipped.
+ *
+ *   The columns are located BY NAME off the header row (never by fixed position) so a future BAN
+ *   schema addition can't silently shift the tuple. Values contain no embedded `;` (the dumps are
+ *   uniform-arity — verified 23 fields across every département), so a plain split is both correct and
+ *   fast; a literal `"` inside a field (rare) is kept verbatim, never treated as a CSV quote wrapper.
+ */
+/** One BAN address point. Every field but `rep`/`postcode`/`city` is guaranteed present by the source. */
+export interface BANAddrRecord {
+    /** `numero` — the house number (numeric in BAN; the `rep` suffix is carried separately). */
+    numero: string;
+    /** `rep` — the repetition indicator (`bis`, `ter`, `quater`, `a`, `b`, …), or null when absent. */
+    rep: string | null;
+    /** `nom_voie` — the street/voie name, already in full form ("Route de …", "Rue du …"). */
+    street: string;
+    /** `code_postal` — the 5-digit postcode (nullable: a handful of lieu-dit rows omit it). */
+    postcode: string | null;
+    /** `nom_commune` — the commune (locality) name. */
+    city: string | null;
+    lon: number;
+    lat: number;
+}
+/**
+ * Stream every address point from one BAN département dump, geometry taken straight from the source `lon`/`lat`
+ * (WGS84). Rows with a non-finite coordinate or an empty `nom_voie`/`numero` are skipped (yield-side filtering is the
+ * caller's job for anything finer). The `rep` suffix is normalised to lower-case or null.
+ */
+export declare function extractBANAddrPoints(csvPath: string): AsyncGenerator<BANAddrRecord>;
+//# sourceMappingURL=extract.d.ts.map

package/out/sdk/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../sdk/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH,0GAA0G;AAC1G,MAAM,WAAW,aAAa;IAC7B,4FAA4F;IAC5F,MAAM,EAAE,MAAM,CAAA;IACd,mGAAmG;IACnG,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,0FAA0F;IAC1F,MAAM,EAAE,MAAM,CAAA;IACd,2FAA2F;IAC3F,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,mDAAmD;IACnD,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;CACX;AA6BD;;;;GAIG;AACH,wBAAuB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,aAAa,CAAC,CAyC1F"}

package/out/sdk/extract.js

@@ -0,0 +1,84 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Stream rooftop address records out of a BAN `adresses-<dept>.csv` dump (adresse.data.gouv.fr). The
+ *   dump is a `;`-delimited, header-first CSV in which EVERY row already carries the full tuple —
+ *   `numero`, `rep`, `nom_voie`, `code_postal`, `nom_commune`, `lon`/`lat` — so there is no OSM-style
+ *   "association gap" (a point with no street): BAN is a structured government register, not a
+ *   community tag soup. We stream line-by-line (the national set is 26M rows / ~5 GB uncompressed);
+ *   `.csv.gz` inputs are transparently gunzipped.
+ *
+ *   The columns are located BY NAME off the header row (never by fixed position) so a future BAN
+ *   schema addition can't silently shift the tuple. Values contain no embedded `;` (the dumps are
+ *   uniform-arity — verified 23 fields across every département), so a plain split is both correct and
+ *   fast; a literal `"` inside a field (rare) is kept verbatim, never treated as a CSV quote wrapper.
+ */
+import { createReadStream } from "node:fs";
+import { createGunzip } from "node:zlib";
+import { TextSpliterator } from "spliterator";
+/** The BAN CSV columns this ingest reads — resolved to indices off the header row. */
+const REQUIRED_COLUMNS = ["numero", "rep", "nom_voie", "code_postal", "nom_commune", "lon", "lat"];
+/** Map the header line to the indices of the columns we read; throws if the dump is missing a required column. */
+function headerIndices(header) {
+    const cols = header.split(";").map((c) => c.trim());
+    const idx = {};
+    for (const name of REQUIRED_COLUMNS) {
+        const at = cols.indexOf(name);
+        if (at < 0)
+            throw new Error(`BAN CSV header is missing required column "${name}" (got: ${cols.join(", ")})`);
+        idx[name] = at;
+    }
+    return idx;
+}
+/** A readable stream over `csvPath`, transparently gunzipping a `.csv.gz` input. */
+function openCSV(csvPath) {
+    const raw = createReadStream(csvPath);
+    return csvPath.endsWith(".gz") ? raw.pipe(createGunzip()) : raw;
+}
+/**
+ * Stream every address point from one BAN département dump, geometry taken straight from the source `lon`/`lat`
+ * (WGS84). Rows with a non-finite coordinate or an empty `nom_voie`/`numero` are skipped (yield-side filtering is the
+ * caller's job for anything finer). The `rep` suffix is normalised to lower-case or null.
+ */
+export async function* extractBANAddrPoints(csvPath) {
+    let idx = null;
+    for await (const line of TextSpliterator.fromAsync(openCSV(csvPath))) {
+        const row = typeof line === "string" ? line : String(line);
+        if (!row)
+            continue;
+        if (!idx) {
+            idx = headerIndices(row);
+            continue;
+        }
+        const cols = row.split(";");
+        const numero = cols[idx.numero]?.trim();
+        const street = cols[idx.nom_voie]?.trim();
+        if (!numero || !street)
+            continue;
+        // Guard the empty-string trap: `Number("")` is 0 (finite), which would write a bogus (0,0) point —
+        // so require a non-empty coord string BEFORE parsing, then the finite check catches garbage.
+        const lonStr = cols[idx.lon]?.trim();
+        const latStr = cols[idx.lat]?.trim();
+        if (!lonStr || !latStr)
+            continue;
+        const lon = Number(lonStr);
+        const lat = Number(latStr);
+        if (!Number.isFinite(lon) || !Number.isFinite(lat))
+            continue;
+        const rep = cols[idx.rep]?.trim();
+        const postcode = cols[idx.code_postal]?.trim();
+        const city = cols[idx.nom_commune]?.trim();
+        yield {
+            numero,
+            rep: rep ? rep.toLowerCase() : null,
+            street,
+            postcode: postcode || null,
+            city: city || null,
+            lon,
+            lat,
+        };
+    }
+}
+//# sourceMappingURL=extract.js.map

package/out/sdk/extract.js.map

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

package/out/sdk/fetch.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   BAN dump URLs + provenance constants. The Base Adresse Nationale publishes per-département and
+ *   national CSV exports at adresse.data.gouv.fr under the Licence Ouverte / Etalab 2.0. We pull the
+ *   per-département dumps (`adresses-<dept>.csv.gz`) — the ecosystem's default shard unit — and assemble
+ *   the national FR shard from them. These constants keep the build reproducible + the provenance
+ *   record honest (the source URL, the license, the required attribution string).
+ */
+/** The BAN "latest" CSV export root. */
+export declare const BAN_CSV_BASE = "https://adresse.data.gouv.fr/data/ban/adresses/latest/csv";
+/** Licence Ouverte / Etalab 2.0 — attribution, NO share-alike (unlike ODbL). */
+export declare const BAN_LICENSE = "Licence Ouverte / Open Licence 2.0 (Etalab)";
+/** The attribution string a result resolved through a BAN point must surface. */
+export declare const BAN_ATTRIBUTION = "\u00A9 les contributeurs de la Base Adresse Nationale (adresse.data.gouv.fr)";
+/**
+ * The download URL of one département's BAN dump. `dept` is the INSEE département code — `01`…`95`, the Corsica codes
+ * `2A`/`2B`, or an overseas code (`971`…`976`). Pass the code exactly as BAN names the file.
+ */
+export declare function banDepartementURL(dept: string): string;
+/** The download URL of the whole-country BAN dump (`adresses-france.csv.gz`). */
+export declare function banNationalURL(): string;
+//# sourceMappingURL=fetch.d.ts.map

package/out/sdk/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../sdk/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,wCAAwC;AACxC,eAAO,MAAM,YAAY,8DAA8D,CAAA;AAEvF,gFAAgF;AAChF,eAAO,MAAM,WAAW,gDAAgD,CAAA;AAExE,iFAAiF;AACjF,eAAO,MAAM,eAAe,iFAA4E,CAAA;AAExG;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,iFAAiF;AACjF,wBAAgB,cAAc,IAAI,MAAM,CAEvC"}

package/out/sdk/fetch.js

@@ -0,0 +1,29 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   BAN dump URLs + provenance constants. The Base Adresse Nationale publishes per-département and
+ *   national CSV exports at adresse.data.gouv.fr under the Licence Ouverte / Etalab 2.0. We pull the
+ *   per-département dumps (`adresses-<dept>.csv.gz`) — the ecosystem's default shard unit — and assemble
+ *   the national FR shard from them. These constants keep the build reproducible + the provenance
+ *   record honest (the source URL, the license, the required attribution string).
+ */
+/** The BAN "latest" CSV export root. */
+export const BAN_CSV_BASE = "https://adresse.data.gouv.fr/data/ban/adresses/latest/csv";
+/** Licence Ouverte / Etalab 2.0 — attribution, NO share-alike (unlike ODbL). */
+export const BAN_LICENSE = "Licence Ouverte / Open Licence 2.0 (Etalab)";
+/** The attribution string a result resolved through a BAN point must surface. */
+export const BAN_ATTRIBUTION = "© les contributeurs de la Base Adresse Nationale (adresse.data.gouv.fr)";
+/**
+ * The download URL of one département's BAN dump. `dept` is the INSEE département code — `01`…`95`, the Corsica codes
+ * `2A`/`2B`, or an overseas code (`971`…`976`). Pass the code exactly as BAN names the file.
+ */
+export function banDepartementURL(dept) {
+    return `${BAN_CSV_BASE}/adresses-${dept}.csv.gz`;
+}
+/** The download URL of the whole-country BAN dump (`adresses-france.csv.gz`). */
+export function banNationalURL() {
+    return `${BAN_CSV_BASE}/adresses-france.csv.gz`;
+}
+//# sourceMappingURL=fetch.js.map

package/out/sdk/fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.js","sourceRoot":"","sources":["../../sdk/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,wCAAwC;AACxC,MAAM,CAAC,MAAM,YAAY,GAAG,2DAA2D,CAAA;AAEvF,gFAAgF;AAChF,MAAM,CAAC,MAAM,WAAW,GAAG,6CAA6C,CAAA;AAExE,iFAAiF;AACjF,MAAM,CAAC,MAAM,eAAe,GAAG,yEAAyE,CAAA;AAExG;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC7C,OAAO,GAAG,YAAY,aAAa,IAAI,SAAS,CAAA;AACjD,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,cAAc;IAC7B,OAAO,GAAG,YAAY,yBAAyB,CAAA;AAChD,CAAC"}

package/out/sdk/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/ban` SDK — the Base Adresse Nationale ingestion surface. PERMISSIVE CODE ONLY: this
+ *   workspace contains no BAN data bytes. It reads the open `adresses-<dept>.csv` dumps
+ *   (adresse.data.gouv.fr) and writes a national FR rooftop address-point shard on the SHARED situs
+ *   schema (`@mailwoman/resolver-wof-sqlite/address-point-schema`). BAN is published under the Licence
+ *   Ouverte / Etalab (attribution, NO share-alike), so — unlike the ODbL OSM tier — the built shard
+ *   ships under the same terms as the permissive core; only the per-row attribution obligation rides
+ *   on it. See `ban/README.md` for the licensing boundary.
+ */
+export * from "./fetch.js";
+export * from "./extract.js";
+export * from "./street-locale.js";
+export * from "./shard-provider.js";
+//# sourceMappingURL=index.d.ts.map

package/out/sdk/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../sdk/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA"}

package/out/sdk/index.js

@@ -0,0 +1,18 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/ban` SDK — the Base Adresse Nationale ingestion surface. PERMISSIVE CODE ONLY: this
+ *   workspace contains no BAN data bytes. It reads the open `adresses-<dept>.csv` dumps
+ *   (adresse.data.gouv.fr) and writes a national FR rooftop address-point shard on the SHARED situs
+ *   schema (`@mailwoman/resolver-wof-sqlite/address-point-schema`). BAN is published under the Licence
+ *   Ouverte / Etalab (attribution, NO share-alike), so — unlike the ODbL OSM tier — the built shard
+ *   ships under the same terms as the permissive core; only the per-row attribution obligation rides
+ *   on it. See `ban/README.md` for the licensing boundary.
+ */
+export * from "./fetch.js";
+export * from "./extract.js";
+export * from "./street-locale.js";
+export * from "./shard-provider.js";
+//# sourceMappingURL=index.js.map

package/out/sdk/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../sdk/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA"}

package/out/sdk/shard-provider.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The BAN rooftop shard provider — the injection point the geocode cascade consults for the national
+ *   open-register precision tier (#1012), AHEAD of the community OSM tier. Given a data root, it opens
+ *   `ban/address-points-<cc>.db` with the country's street-normalization locale (so probe-side keying
+ *   matches the shard the builder wrote) and caches the open handle per country. Wire its bound `for`
+ *   into `GeocodeDeps.nationalShards`.
+ *
+ *   BAN is a French national register, so the registry is deliberately FR-only today; the shape
+ *   generalises to any other national open register (the coverage story, one country at a time).
+ */
+import { AddressPointSqliteLookup } from "@mailwoman/resolver-wof-sqlite";
+/** What the cascade needs from a BAN shard — structurally a subset of mailwoman's `StateShards`. */
+export interface BANShards {
+    addressPoints?: AddressPointSqliteLookup;
+}
+/**
+ * Opens + caches per-country BAN rooftop lookups. A non-US geocode consults `for(country)`; the first hit for a country
+ * opens its shard (with the matching street locale) once, subsequent calls reuse it.
+ */
+export declare class BANShardProvider {
+    #private;
+    constructor(dataRoot: string);
+    /** Resolve the BAN shards for an ISO-3166 alpha-2 country, or `{}` when none is shipped/registered. */
+    readonly for: (country: string) => BANShards;
+    close(): void;
+}
+//# sourceMappingURL=shard-provider.d.ts.map

package/out/sdk/shard-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shard-provider.d.ts","sourceRoot":"","sources":["../../sdk/shard-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAA;AAIzE,oGAAoG;AACpG,MAAM,WAAW,SAAS;IACzB,aAAa,CAAC,EAAE,wBAAwB,CAAA;CACxC;AAED;;;GAGG;AACH,qBAAa,gBAAgB;;gBAIhB,QAAQ,EAAE,MAAM;IAQ5B,uGAAuG;IACvG,QAAQ,CAAC,GAAG,GAAI,SAAS,MAAM,KAAG,SAAS,CAmB1C;IAED,KAAK,IAAI,IAAI;CAMb"}

package/out/sdk/shard-provider.js

@@ -0,0 +1,55 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The BAN rooftop shard provider — the injection point the geocode cascade consults for the national
+ *   open-register precision tier (#1012), AHEAD of the community OSM tier. Given a data root, it opens
+ *   `ban/address-points-<cc>.db` with the country's street-normalization locale (so probe-side keying
+ *   matches the shard the builder wrote) and caches the open handle per country. Wire its bound `for`
+ *   into `GeocodeDeps.nationalShards`.
+ *
+ *   BAN is a French national register, so the registry is deliberately FR-only today; the shape
+ *   generalises to any other national open register (the coverage story, one country at a time).
+ */
+import { existsSync } from "node:fs";
+import { AddressPointSqliteLookup } from "@mailwoman/resolver-wof-sqlite";
+import { streetLocaleForBANCountry, supportedBANCountries } from "./street-locale.js";
+/**
+ * Opens + caches per-country BAN rooftop lookups. A non-US geocode consults `for(country)`; the first hit for a country
+ * opens its shard (with the matching street locale) once, subsequent calls reuse it.
+ */
+export class BANShardProvider {
+    #dataRoot;
+    #cache = new Map();
+    constructor(dataRoot) {
+        this.#dataRoot = dataRoot;
+    }
+    #shardPath(countryCode) {
+        return `${this.#dataRoot}/ban/address-points-${countryCode}.db`;
+    }
+    /** Resolve the BAN shards for an ISO-3166 alpha-2 country, or `{}` when none is shipped/registered. */
+    for = (country) => {
+        const cc = country.toLowerCase();
+        const cached = this.#cache.get(cc);
+        if (cached)
+            return cached;
+        let entry = {};
+        // Only countries with a registered street locale AND an on-disk shard — never key with the wrong rules.
+        if (supportedBANCountries().includes(cc)) {
+            const path = this.#shardPath(cc);
+            if (existsSync(path)) {
+                entry = { addressPoints: new AddressPointSqliteLookup(path, { streetLocale: streetLocaleForBANCountry(cc) }) };
+            }
+        }
+        this.#cache.set(cc, entry);
+        return entry;
+    };
+    close() {
+        for (const entry of this.#cache.values()) {
+            entry.addressPoints?.close();
+        }
+        this.#cache.clear();
+    }
+}
+//# sourceMappingURL=shard-provider.js.map

package/out/sdk/shard-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shard-provider.js","sourceRoot":"","sources":["../../sdk/shard-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEpC,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAA;AAEzE,OAAO,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAOrF;;;GAGG;AACH,MAAM,OAAO,gBAAgB;IACnB,SAAS,CAAQ;IACjB,MAAM,GAAG,IAAI,GAAG,EAAqB,CAAA;IAE9C,YAAY,QAAgB;QAC3B,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAA;IAC1B,CAAC;IAED,UAAU,CAAC,WAAmB;QAC7B,OAAO,GAAG,IAAI,CAAC,SAAS,uBAAuB,WAAW,KAAK,CAAA;IAChE,CAAC;IAED,uGAAuG;IAC9F,GAAG,GAAG,CAAC,OAAe,EAAa,EAAE;QAC7C,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAA;QAChC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;QAElC,IAAI,MAAM;YAAE,OAAO,MAAM,CAAA;QAEzB,IAAI,KAAK,GAAc,EAAE,CAAA;QAEzB,wGAAwG;QACxG,IAAI,qBAAqB,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAA;YAEhC,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBACtB,KAAK,GAAG,EAAE,aAAa,EAAE,IAAI,wBAAwB,CAAC,IAAI,EAAE,EAAE,YAAY,EAAE,yBAAyB,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAA;YAC/G,CAAC;QACF,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAA;QAE1B,OAAO,KAAK,CAAA;IACb,CAAC,CAAA;IAED,KAAK;QACJ,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YAC1C,KAAK,CAAC,aAAa,EAAE,KAAK,EAAE,CAAA;QAC7B,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;IACpB,CAAC;CACD"}

package/out/sdk/street-locale.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Country → street-normalization-locale routing for the BAN rooftop build. The NORMALIZER itself
+ *   lives in `@mailwoman/resolver-wof-sqlite/street-normalize` (the one-function discipline — the
+ *   reader on the resolver side and the builder here must call the identical function). This module
+ *   only maps an ISO-3166 country code to the locale that selects the right per-locale rules, and
+ *   re-exports the normalizer so the BAN SDK is a self-contained surface. Kept SEPARATE from the
+ *   heavy `shard-provider.ts` (which pulls the SQLite lookup) so the pure locale contract is testable
+ *   without opening a database — mirrors `@mailwoman/osm`'s `street-locale.ts`.
+ */
+import { normalizeStreetForKeyLocale, type StreetLocale } from "@mailwoman/resolver-wof-sqlite/street-normalize";
+export { normalizeStreetForKeyLocale, type StreetLocale };
+/**
+ * Resolve the street-normalization locale for a BAN country. Throws for an unsupported country rather than silently
+ * folding with the wrong rules — a shard built with the wrong normalizer keys every street incorrectly and looks fine
+ * until a probe misses. Add the country to {@link BAN_COUNTRY_TO_STREET_LOCALE} (and a branch in
+ * `normalizeStreetForKeyLocale`) before building its shard.
+ */
+export declare function streetLocaleForBANCountry(countryCode: string): StreetLocale;
+/** The countries with a registered BAN street locale (for CLI validation / provider gating). */
+export declare function supportedBANCountries(): string[];
+//# sourceMappingURL=street-locale.d.ts.map

package/out/sdk/street-locale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"street-locale.d.ts","sourceRoot":"","sources":["../../sdk/street-locale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,2BAA2B,EAAE,KAAK,YAAY,EAAE,MAAM,iDAAiD,CAAA;AAEhH,OAAO,EAAE,2BAA2B,EAAE,KAAK,YAAY,EAAE,CAAA;AASzD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY,CAW3E;AAED,gGAAgG;AAChG,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD"}

package/out/sdk/street-locale.js

@@ -0,0 +1,40 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Country → street-normalization-locale routing for the BAN rooftop build. The NORMALIZER itself
+ *   lives in `@mailwoman/resolver-wof-sqlite/street-normalize` (the one-function discipline — the
+ *   reader on the resolver side and the builder here must call the identical function). This module
+ *   only maps an ISO-3166 country code to the locale that selects the right per-locale rules, and
+ *   re-exports the normalizer so the BAN SDK is a self-contained surface. Kept SEPARATE from the
+ *   heavy `shard-provider.ts` (which pulls the SQLite lookup) so the pure locale contract is testable
+ *   without opening a database — mirrors `@mailwoman/osm`'s `street-locale.ts`.
+ */
+import { normalizeStreetForKeyLocale } from "@mailwoman/resolver-wof-sqlite/street-normalize";
+export { normalizeStreetForKeyLocale };
+/**
+ * ISO-3166 alpha-2 (lowercase) → the street-normalization locale a BAN shard was built with. FR-only: BAN is the French
+ * national register. Adding a country here means shipping that country's national register on the shared schema AND
+ * having a matching branch in `normalizeStreetForKeyLocale` — never a silent fold with the wrong rules.
+ */
+const BAN_COUNTRY_TO_STREET_LOCALE = new Map([["fr", "fr"]]);
+/**
+ * Resolve the street-normalization locale for a BAN country. Throws for an unsupported country rather than silently
+ * folding with the wrong rules — a shard built with the wrong normalizer keys every street incorrectly and looks fine
+ * until a probe misses. Add the country to {@link BAN_COUNTRY_TO_STREET_LOCALE} (and a branch in
+ * `normalizeStreetForKeyLocale`) before building its shard.
+ */
+export function streetLocaleForBANCountry(countryCode) {
+    const locale = BAN_COUNTRY_TO_STREET_LOCALE.get(countryCode.toLowerCase());
+    if (!locale) {
+        throw new Error(`No BAN street-normalization locale registered for country "${countryCode}". ` +
+            `Add it to BAN_COUNTRY_TO_STREET_LOCALE and add the matching branch in normalizeStreetForKeyLocale before building its shard.`);
+    }
+    return locale;
+}
+/** The countries with a registered BAN street locale (for CLI validation / provider gating). */
+export function supportedBANCountries() {
+    return [...BAN_COUNTRY_TO_STREET_LOCALE.keys()];
+}
+//# sourceMappingURL=street-locale.js.map

package/out/sdk/street-locale.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"street-locale.js","sourceRoot":"","sources":["../../sdk/street-locale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,2BAA2B,EAAqB,MAAM,iDAAiD,CAAA;AAEhH,OAAO,EAAE,2BAA2B,EAAqB,CAAA;AAEzD;;;;GAIG;AACH,MAAM,4BAA4B,GAAG,IAAI,GAAG,CAAuB,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;AAElF;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,WAAmB;IAC5D,MAAM,MAAM,GAAG,4BAA4B,CAAC,GAAG,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,CAAA;IAE1E,IAAI,CAAC,MAAM,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACd,8DAA8D,WAAW,KAAK;YAC7E,8HAA8H,CAC/H,CAAA;IACF,CAAC;IAED,OAAO,MAAM,CAAA;AACd,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,qBAAqB;IACpC,OAAO,CAAC,GAAG,4BAA4B,CAAC,IAAI,EAAE,CAAC,CAAA;AAChD,CAAC"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@mailwoman/ban",
+  "version": "5.7.0",
+  "description": "Base Adresse Nationale (France) rooftop address-point ingestion — builds the national FR precision shard on the situs address-point schema.",
+  "keywords": [
+    "address-point",
+    "ban",
+    "france",
+    "geocoding",
+    "geospatial"
+  ],
+  "homepage": "https://github.com/sister-software/mailwoman",
+  "bugs": {
+    "url": "https://github.com/sister-software/mailwoman/issues"
+  },
+  "license": "AGPL-3.0-only OR LicenseRef-Commercial",
+  "contributors": [
+    {
+      "name": "Teffen Ellis",
+      "email": "teffen@sister.software"
+    }
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sister-software/mailwoman.git",
+    "directory": "ban"
+  },
+  "files": [
+    "out/**/*.js",
+    "out/**/*.js.map",
+    "out/**/*.d.ts",
+    "out/**/*.d.ts.map",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    "./scripts/*": "./out/scripts/*.js",
+    "./sdk": "./out/sdk/index.js",
+    ".": "./out/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@mailwoman/core": "5.7.0",
+    "@mailwoman/resolver-wof-sqlite": "5.7.0",
+    "kysely": "^0.29.2",
+    "spliterator": "^3.2.0"
+  },
+  "engines": {
+    "node": ">=24.18.0"
+  }
+}