@mailwoman/ban 5.7.0 → 5.9.0

package/out/scripts/build-street-centroid-shard.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Build the DERIVED street-centroid shard (`ban/street-centroids-<cc>.db`, #1042) from the SEALED
+ *   rooftop address-point shard (`ban/address-points-<cc>.db`, #1012). No new data source: it is a
+ *   `GROUP BY street` roll-up of the register we already ingested — one row per (street_norm, postcode,
+ *   commune) carrying the street's CENTROID + bounding-box EXTENT + member-point count. The output feeds
+ *   `StreetCentroidSqliteLookup`, the street-level tier for a street-only query (a thoroughfare with NO
+ *   house number) that no address-POINT tier can serve by definition.
+ *
+ *   The commune is the arrondissement-STRIPPED base commune (`stripArrondissement` — BAN names
+ *   Paris/Lyon/Marseille rows per arrondissement, but a query names the base commune); the aggregation
+ *   groups on the full `locality_norm` and emits the base, so a rare (street, postcode, base) collision
+ *   across two arrondissements is merged harmlessly by the reader's weighted aggregate.
+ *
+ *   The SEALED input is opened READ-ONLY and NEVER modified. Build discipline (house rules): aggregate
+ *   in SQLite → stream via `.iterate()` → positional prepared INSERT (batched) into a staging DB →
+ *   indexes → ANALYZE → atomic swap into place → SEAL 0444 → record md5 + the derivation provenance in
+ *   `ban/street-centroids-<cc>.ATTRIBUTION.json`. Purely additive; it never touches the rooftop shard.
+ *
+ *   Usage:
+ *     node ban/out/scripts/build-street-centroid-shard.js            # fr, default paths
+ *     node ban/out/scripts/build-street-centroid-shard.js --country fr --out /tmp/sc-fr.db
+ */
+export {};
+//# sourceMappingURL=build-street-centroid-shard.d.ts.map

package/out/scripts/build-street-centroid-shard.d.ts.map

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

package/out/scripts/build-street-centroid-shard.js

@@ -0,0 +1,170 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Build the DERIVED street-centroid shard (`ban/street-centroids-<cc>.db`, #1042) from the SEALED
+ *   rooftop address-point shard (`ban/address-points-<cc>.db`, #1012). No new data source: it is a
+ *   `GROUP BY street` roll-up of the register we already ingested — one row per (street_norm, postcode,
+ *   commune) carrying the street's CENTROID + bounding-box EXTENT + member-point count. The output feeds
+ *   `StreetCentroidSqliteLookup`, the street-level tier for a street-only query (a thoroughfare with NO
+ *   house number) that no address-POINT tier can serve by definition.
+ *
+ *   The commune is the arrondissement-STRIPPED base commune (`stripArrondissement` — BAN names
+ *   Paris/Lyon/Marseille rows per arrondissement, but a query names the base commune); the aggregation
+ *   groups on the full `locality_norm` and emits the base, so a rare (street, postcode, base) collision
+ *   across two arrondissements is merged harmlessly by the reader's weighted aggregate.
+ *
+ *   The SEALED input is opened READ-ONLY and NEVER modified. Build discipline (house rules): aggregate
+ *   in SQLite → stream via `.iterate()` → positional prepared INSERT (batched) into a staging DB →
+ *   indexes → ANALYZE → atomic swap into place → SEAL 0444 → record md5 + the derivation provenance in
+ *   `ban/street-centroids-<cc>.ATTRIBUTION.json`. Purely additive; it never touches the rooftop shard.
+ *
+ *   Usage:
+ *     node ban/out/scripts/build-street-centroid-shard.js            # fr, default paths
+ *     node ban/out/scripts/build-street-centroid-shard.js --country fr --out /tmp/sc-fr.db
+ */
+import { createHash } from "node:crypto";
+import { createReadStream, existsSync, mkdirSync, readFileSync, 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 { createStreetCentroidIndexes, createStreetCentroidTable, STREET_CENTROID_COLUMNS, } from "@mailwoman/resolver-wof-sqlite/street-centroid-schema";
+import { stripArrondissement } from "@mailwoman/resolver-wof-sqlite/street-normalize";
+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" },
+            source: { type: "string" },
+            release: { type: "string" },
+            out: { type: "string" },
+        },
+    });
+    const country = (values.country ?? "fr").toLowerCase();
+    // Throws for an unsupported country — fail loud, never derive a tier keyed with the wrong locale rules.
+    streetLocaleForBANCountry(country);
+    const source = values.source ?? dataRootPath("ban", `address-points-${country}.db`);
+    if (!existsSync(source))
+        throw new Error(`sealed BAN rooftop shard not found: ${source} (build it via #1012 first)`);
+    const release = values.release ?? "2026-05-18";
+    const output = values.out ?? dataRootPath("ban", `street-centroids-${country}.db`);
+    return { country, source, release, output };
+}
+/** 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");
+}
+/** The md5 the #1012 build recorded for the sealed rooftop input, for the derivation provenance chain. */
+function sourceMD5(country) {
+    try {
+        const rec = JSON.parse(readFileSync(dataRootPath("ban", "ATTRIBUTION.json"), "utf8"));
+        return rec.artifact === `address-points-${country}.db` ? (rec.md5 ?? null) : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function main() {
+    const args = parse();
+    const source = `ban:${args.country}`;
+    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 });
+    }
+    // The SEALED input — READ-ONLY, immutable; register the base-commune folder as a scalar SQL function.
+    const src = new DatabaseSync(args.source, { readOnly: true });
+    src.function("ban_base_commune", { deterministic: true }, (loc) => typeof loc === "string" && loc ? stripArrondissement(loc) : "");
+    const out = new DatabaseSync(tmp);
+    out.exec("PRAGMA page_size=8192; PRAGMA journal_mode=OFF; PRAGMA synchronous=OFF; PRAGMA cache_size=-1000000;");
+    const kdb = new DatabaseClient({ database: out });
+    await createStreetCentroidTable(kdb);
+    const insert = out.prepare(`INSERT INTO street_centroid VALUES (${STREET_CENTROID_COLUMNS.map(() => "?").join(", ")})`);
+    // GROUP BY the sealed rooftop points into per-(street, postcode, commune) roll-ups. AVG(lat/lon) over the group's
+    // member points is the exact centroid; MIN/MAX is the extent; COUNT is the weight for the reader's cross-group mean.
+    // The base commune is emitted per group (2.2M calls), NOT per source row.
+    const agg = src.prepare(`SELECT street_norm,
+		        postcode,
+		        ban_base_commune(locality_norm) AS locality_base,
+		        AVG(lat) AS lat, AVG(lon) AS lon,
+		        MIN(lat) AS min_lat, MAX(lat) AS max_lat, MIN(lon) AS min_lon, MAX(lon) AS max_lon,
+		        COUNT(*) AS n,
+		        MIN(street_raw) AS street_raw
+		 FROM address_point
+		 GROUP BY street_norm, postcode, locality_norm`);
+    let written = 0;
+    const BATCH = 50_000;
+    console.error(`[ban] deriving ${args.country} street-centroid tier from ${args.source}`);
+    out.exec("BEGIN");
+    for (const row of agg.iterate()) {
+        // Positional, in STREET_CENTROID_COLUMNS order.
+        insert.run(row.street_norm, row.postcode, row.locality_base, row.lat, row.lon, row.min_lat, row.max_lat, row.min_lon, row.max_lon, row.n, row.street_raw, source, args.release);
+        written++;
+        if (written % BATCH === 0) {
+            out.exec("COMMIT");
+            out.exec("BEGIN");
+            if (written % 500_000 === 0) {
+                console.error(`[ban]   ${written.toLocaleString()} streets…`);
+            }
+        }
+    }
+    out.exec("COMMIT");
+    src.close();
+    console.error(`[ban] indexing…`);
+    await createStreetCentroidIndexes(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;
+    const srcMD5 = sourceMD5(args.country);
+    // Provenance manifest — additive, written at creation (house discipline). Records the DERIVATION chain: this
+    // artifact is derived from the sealed #1012 rooftop shard, itself derived from the BAN release.
+    const attributionPath = dataRootPath("ban", `street-centroids-${args.country}.ATTRIBUTION.json`);
+    writeFileSync(attributionPath, JSON.stringify({
+        artifact: `street-centroids-${args.country}.db`,
+        derivedFrom: {
+            artifact: `address-points-${args.country}.db`,
+            source,
+            release: args.release,
+            md5: srcMD5,
+            note: `derived from ${source} release=${args.release}${srcMD5 ? ` (md5 ${srcMD5.slice(0, 8)})` : ""}`,
+        },
+        source,
+        sourceURL: BAN_CSV_BASE,
+        license: BAN_LICENSE,
+        attribution: BAN_ATTRIBUTION,
+        release: args.release,
+        streets: written,
+        bytes,
+        md5,
+        builtAt: new Date().toISOString(),
+    }, null, 2) + "\n");
+    console.error(`[ban] wrote ${attributionPath}`);
+    console.error(`[ban] DONE ${args.output}\n` +
+        `      streets (rows)                   : ${written.toLocaleString()}\n` +
+        `      bytes                            : ${bytes.toLocaleString()}\n` +
+        `      md5                              : ${md5}\n` +
+        `      derived from                     : address-points-${args.country}.db${srcMD5 ? ` (md5 ${srcMD5.slice(0, 8)})` : ""}  release=${args.release}`);
+}
+await main();
+//# sourceMappingURL=build-street-centroid-shard.js.map

package/out/scripts/build-street-centroid-shard.js.map

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

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

@@ -12,10 +12,12 @@
  *   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";
+import { AddressPointSqliteLookup, StreetCentroidSqliteLookup } 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;
+    /** The #1042 derived street-centroid tier — a `GROUP BY street` roll-up, for a street-only query (no house number). */
+    streetCentroids?: StreetCentroidSqliteLookup;
 }
 /**
  * Opens + caches per-country BAN rooftop lookups. A non-US geocode consults `for(country)`; the first hit for a country

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

@@ -1 +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"}
+{"version":3,"file":"shard-provider.d.ts","sourceRoot":"","sources":["../../sdk/shard-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAA;AAIrG,oGAAoG;AACpG,MAAM,WAAW,SAAS;IACzB,aAAa,CAAC,EAAE,wBAAwB,CAAA;IACxC,uHAAuH;IACvH,eAAe,CAAC,EAAE,0BAA0B,CAAA;CAC5C;AAED;;;GAGG;AACH,qBAAa,gBAAgB;;gBAIhB,QAAQ,EAAE,MAAM;IAY5B,uGAAuG;IACvG,QAAQ,CAAC,GAAG,GAAI,SAAS,MAAM,KAAG,SAAS,CA0B1C;IAED,KAAK,IAAI,IAAI;CAOb"}

package/out/sdk/shard-provider.js

@@ -13,7 +13,7 @@
  *   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 { AddressPointSqliteLookup, StreetCentroidSqliteLookup } 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
@@ -28,18 +28,27 @@ export class BANShardProvider {
     #shardPath(countryCode) {
         return `${this.#dataRoot}/ban/address-points-${countryCode}.db`;
     }
+    #streetCentroidPath(countryCode) {
+        return `${this.#dataRoot}/ban/street-centroids-${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 = {};
+        const entry = {};
         // Only countries with a registered street locale AND an on-disk shard — never key with the wrong rules.
         if (supportedBANCountries().includes(cc)) {
+            const locale = streetLocaleForBANCountry(cc);
             const path = this.#shardPath(cc);
             if (existsSync(path)) {
-                entry = { addressPoints: new AddressPointSqliteLookup(path, { streetLocale: streetLocaleForBANCountry(cc) }) };
+                entry.addressPoints = new AddressPointSqliteLookup(path, { streetLocale: locale });
+            }
+            // The #1042 derived street tier — purely additive, opened only when its artifact is on disk.
+            const streetPath = this.#streetCentroidPath(cc);
+            if (existsSync(streetPath)) {
+                entry.streetCentroids = new StreetCentroidSqliteLookup(streetPath, { streetLocale: locale });
             }
         }
         this.#cache.set(cc, entry);
@@ -48,6 +57,7 @@ export class BANShardProvider {
     close() {
         for (const entry of this.#cache.values()) {
             entry.addressPoints?.close();
+            entry.streetCentroids?.close();
         }
         this.#cache.clear();
     }

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

@@ -1 +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"}
+{"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,0BAA0B,EAAE,MAAM,gCAAgC,CAAA;AAErG,OAAO,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AASrF;;;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,mBAAmB,CAAC,WAAmB;QACtC,OAAO,GAAG,IAAI,CAAC,SAAS,yBAAyB,WAAW,KAAK,CAAA;IAClE,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,MAAM,KAAK,GAAc,EAAE,CAAA;QAE3B,wGAAwG;QACxG,IAAI,qBAAqB,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YAC1C,MAAM,MAAM,GAAG,yBAAyB,CAAC,EAAE,CAAC,CAAA;YAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAA;YAEhC,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBACtB,KAAK,CAAC,aAAa,GAAG,IAAI,wBAAwB,CAAC,IAAI,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,CAAA;YACnF,CAAC;YACD,6FAA6F;YAC7F,MAAM,UAAU,GAAG,IAAI,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAA;YAE/C,IAAI,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC5B,KAAK,CAAC,eAAe,GAAG,IAAI,0BAA0B,CAAC,UAAU,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,CAAA;YAC7F,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;YAC5B,KAAK,CAAC,eAAe,EAAE,KAAK,EAAE,CAAA;QAC/B,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;IACpB,CAAC;CACD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailwoman/ban",
-  "version": "5.7.0",
+  "version": "5.9.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",
@@ -46,8 +46,8 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@mailwoman/core": "5.7.0",
-    "@mailwoman/resolver-wof-sqlite": "5.7.0",
+    "@mailwoman/core": "5.9.0",
+    "@mailwoman/resolver-wof-sqlite": "5.9.0",
     "kysely": "^0.29.2",
     "spliterator": "^3.2.0"
   },