@mailwoman/corpus 9.1.0 → 9.3.0

package/out/adapters/gnaf/assemble.js

@@ -0,0 +1,154 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Assemble a sampled, component-labeled Australian address set from G-NAF (the Geocoded National
+ *   Address File — Geoscape Australia, Open G-NAF licence; any derived artifact must attribute
+ *   "Geoscape Australia"). G-NAF is a relational PSV distribution (~16.9M addresses);
+ *   reconstructing a street address joins three tables — ADDRESS_DETAIL (number, postcode, the
+ *   PIDs) → STREET_LOCALITY (street name + type) → LOCALITY (suburb). State is the per-file prefix
+ *   (ACT/NSW/…).
+ *
+ *   Streaming + in-memory join via the house {@link PSVSpliterator} (pipe-separated; `mode: "object"`
+ *   keys each row by its header) — NOT raw `read_csv` SQL, which a flat-file join doesn't need and
+ *   which the #183–190 cleanup retired. The two lookup tables (STREET_LOCALITY ~765k rows, LOCALITY
+ *   ~16k) fit as Maps; ADDRESS_DETAIL is streamed once and reservoir-sampled, so memory stays
+ *   bounded (the OOM lesson from the Overture ingest).
+ *
+ *   No coordinates: the output feeds the PARSER ({@link ../gnaf/adapter}, #208) — teaching the model
+ *   AU's postcode-first / house-number-last word order, the gap `scripts/eval/au-order-probe.ts`
+ *   pinned (65%→87% if the parse were order-robust). The parser needs the address string +
+ *   component labels, not lat/lon.
+ *
+ *   Output: component tuples as JSONL, consumed by the `gnaf` corpus adapter (which renders them in
+ *   multiple orders + the corpus aligner BIO-labels them). An optional held-out eval set is
+ *   excluded by (street, locality, postcode) so the training slice never overlaps the benchmark.
+ */
+import { readDirectory } from "@mailwoman/core/fs/readers";
+import { openWriteStream } from "@mailwoman/core/fs/streams";
+import { tryParsingJSON } from "@mailwoman/core/json";
+import { join } from "path-ts";
+import { PSVSpliterator, TextSpliterator } from "spliterator";
+/**
+ * UPPERCASE → Title Case, preserving intra-word apostrophes/hyphens (O'Brien, Coff's Harbour).
+ */
+export function titlecase(s) {
+    return s
+        .toLowerCase()
+        .replaceAll(/(^|[\s'\-/])([a-z])/g, (_m, p, c) => p + c.toUpperCase())
+        .trim();
+}
+/**
+ * Holdout/dedup key: a street within a locality+postcode (house-number-agnostic — conservative).
+ */
+export function gnafHoldoutKey(street, locality, postcode) {
+    return `${street}|${locality}|${postcode}`.toLowerCase();
+}
+async function* psvObjects(path) {
+    yield* PSVSpliterator.fromAsync(path, { mode: "object", header: true });
+}
+/**
+ * Load a small lookup table fully into a Map keyed by `keyCol`.
+ */
+async function loadMap(paths, keyCol, pick) {
+    const m = new Map();
+    for (const p of paths) {
+        for await (const r of psvObjects(p)) {
+            const k = r[keyCol];
+            if (k != null && k !== "") {
+                m.set(String(k), pick(r));
+            }
+        }
+    }
+    return m;
+}
+/**
+ * Build the held-out key set from an eval JSONL whose rows carry a `components` object.
+ */
+async function loadHoldout(path) {
+    const keys = new Set();
+    for await (const line of TextSpliterator.fromAsync(path)) {
+        if (!line.trim())
+            continue;
+        const c = tryParsingJSON(line)?.components;
+        if (c?.street && c?.locality && c?.postcode) {
+            keys.add(gnafHoldoutKey(c.street, c.locality, c.postcode));
+        }
+    }
+    return keys;
+}
+export async function assembleGNAF(opts) {
+    const progress = opts.onProgress ?? (() => { });
+    const files = await readDirectory(opts.standardDir);
+    const pick = (re, exclude) => files.filter((f) => re.test(f) && !(exclude && exclude.test(f))).map((f) => join(opts.standardDir, f));
+    // `*_LOCALITY_psv.psv` also globs `*_STREET_LOCALITY_psv.psv` — exclude the latter explicitly.
+    const streetPaths = pick(/_STREET_LOCALITY_psv\.psv$/);
+    const localityPaths = pick(/_LOCALITY_psv\.psv$/, /_STREET_LOCALITY_psv\.psv$/);
+    const addressPaths = pick(/_ADDRESS_DETAIL_psv\.psv$/);
+    const holdout = opts.holdoutPath ? await loadHoldout(opts.holdoutPath) : new Set();
+    if (opts.holdoutPath) {
+        progress(`held-out eval keys: ${holdout.size}`);
+    }
+    progress(`loading STREET_LOCALITY (${streetPaths.length} files) + LOCALITY (${localityPaths.length})…`);
+    const streetMap = await loadMap(streetPaths, "STREET_LOCALITY_PID", (r) => ({
+        name: String(r.STREET_NAME ?? ""),
+        type: String(r.STREET_TYPE_CODE ?? ""),
+        suffix: String(r.STREET_SUFFIX_CODE ?? ""),
+    }));
+    const localityMap = await loadMap(localityPaths, "LOCALITY_PID", (r) => String(r.LOCALITY_NAME ?? ""));
+    progress(`streets=${streetMap.size.toLocaleString()} localities=${localityMap.size.toLocaleString()}`);
+    const reservoir = [];
+    let seen = 0;
+    let heldOut = 0;
+    for (const p of addressPaths) {
+        const state = (p.match(/\/([A-Z]+)_ADDRESS_DETAIL/) ?? [])[1] ?? "";
+        for await (const r of psvObjects(p)) {
+            const numberFirst = String(r.NUMBER_FIRST ?? "");
+            if (!numberFirst || r.DATE_RETIRED || !r.POSTCODE)
+                continue;
+            const st = streetMap.get(String(r.STREET_LOCALITY_PID ?? ""));
+            const suburbRaw = localityMap.get(String(r.LOCALITY_PID ?? ""));
+            if (!st?.name || !suburbRaw)
+                continue;
+            const street = `${titlecase(st.name)} ${titlecase(st.type)}${st.suffix ? " " + titlecase(st.suffix) : ""}`.trim();
+            const locality = titlecase(suburbRaw);
+            const postcode = String(r.POSTCODE);
+            if (holdout.has(gnafHoldoutKey(street, locality, postcode))) {
+                heldOut++;
+                continue;
+            }
+            let house = numberFirst + (r.NUMBER_FIRST_SUFFIX ? String(r.NUMBER_FIRST_SUFFIX) : "");
+            if (r.NUMBER_LAST) {
+                house = `${house}-${String(r.NUMBER_LAST)}`;
+            }
+            if (r.FLAT_NUMBER) {
+                house = `${String(r.FLAT_NUMBER)}/${house}`;
+            }
+            const tuple = { house_number: house, street, locality, region: state, postcode };
+            seen++;
+            if (reservoir.length < opts.sampleSize) {
+                reservoir.push(tuple);
+            }
+            else {
+                const j = Math.floor(Math.random() * seen);
+                if (j < opts.sampleSize) {
+                    reservoir[j] = tuple;
+                }
+            }
+        }
+        progress(`${state}: ${seen.toLocaleString()} valid joinable seen`);
+    }
+    const out = openWriteStream(opts.out);
+    const byState = {};
+    for (const t of reservoir) {
+        out.write(JSON.stringify(t) + "\n");
+        byState[t.region] = (byState[t.region] ?? 0) + 1;
+    }
+    await new Promise((res) => {
+        out.end(res);
+    });
+    progress(`wrote ${reservoir.length.toLocaleString()} tuples → ${opts.out}`);
+    return { written: reservoir.length, seen, heldOut, byState };
+}
+//# sourceMappingURL=assemble.js.map

package/out/adapters/gnaf/assemble.js.map

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

package/out/adapters/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Adapter registry bootstrap.
+ *
+ *   Importing this module registers every built-in adapter with `defaultAdapterRegistry`. The CLI
+ *   (`commands/corpus/list.tsx`, `commands/corpus/run.tsx`) imports it once at startup.
+ *
+ *   Adapters under construction live in their own subdirectories (`./wof-admin-json/`, `./ban/`, ...)
+ *   and are added to the `BUILTIN_ADAPTERS` list here as they come online. Tests that need a
+ *   pristine registry should construct their own `InMemoryAdapterRegistry` instead of mutating the
+ *   default.
+ *
+ *   The WOF adapters export their canonical ids — `wof-admin` and `wof-postalcode` — so existing
+ *   `mailwoman corpus build` callsites do not need to change despite the Phase 1.5.1 SQLite →
+ *   JSON-bundle pivot (`./wof-admin-json/` and `./wof-postalcode-json/` directories hold the
+ *   implementations; the registered ids are unchanged).
+ */
+import type { CorpusAdapter } from "#types";
+/**
+ * Built-in adapters. Order is significant: `corpus build` iterates this list to drive every adapter in turn.
+ * Coarse-first (admin → postcode), then street-level (BAN FR, TIGER US, OpenAddresses global), then adversarial-source
+ * (FCC BDC US, HRSA FQHC US).
+ *
+ * The `usgov-samhsa-treatment-locator` adapter is intentionally absent from this list — the SAMHSA Open Data Foundry
+ * bulk CSV the adapter was written against is no longer publicly distributed (see issue #33, 2026-05-17 investigation).
+ * The factory + named export remain available so the adapter can be hand-registered if an operator obtains a compatible
+ * CSV (FOIA, partner channel, upstream restoration). Re-add it here once a stable public source returns.
+ */
+export declare const BUILTIN_ADAPTERS: readonly CorpusAdapter[];
+export { BAN_ADAPTER_ID, banAdapter } from "#adapters/ban/adapter";
+export { FCC_BDC_ADAPTER_ID, FCC_BDC_DEFAULT_LICENSE, fccBdcAdapter } from "#adapters/fcc-bdc/adapter";
+export { GEONAMES_POSTAL_ADAPTER_ID, GEONAMES_POSTAL_DEFAULT_LICENSE, geonamesPostalAdapter, } from "#adapters/geonames-postal/adapter";
+export { GEONAMES_ADAPTER_ID, GEONAMES_DEFAULT_LICENSE, geonamesAdapter } from "#adapters/geonames/adapter";
+export { OPENADDRESSES_ADAPTER_ID, OPENADDRESSES_DEFAULT_LICENSE, openaddressesAdapter, } from "#adapters/openaddresses/adapter";
+export { STATE_HI_SCHOOLS_ADAPTER_ID, STATE_HI_SCHOOLS_DEFAULT_LICENSE, stateHiSchoolsAdapter, } from "#adapters/state-hi-schools/adapter";
+export { STATE_IA_CONTRACTORS_ADAPTER_ID, STATE_IA_CONTRACTORS_DEFAULT_LICENSE, stateIaContractorsAdapter, } from "#adapters/state-ia-contractors/adapter";
+export { STATE_NY_NOTARIES_ADAPTER_ID, STATE_NY_NOTARIES_DEFAULT_LICENSE, stateNyNotariesAdapter, } from "#adapters/state-ny-notaries/adapter";
+export { STATE_TX_NOTARIES_ADAPTER_ID, STATE_TX_NOTARIES_DEFAULT_LICENSE, stateTxNotariesAdapter, } from "#adapters/state-tx-notaries/adapter";
+export { TIGER_ADAPTER_ID, TIGER_DEFAULT_LICENSE, tigerAdapter } from "#adapters/tiger/adapter";
+export { USGOV_HRSA_FQHC_ADAPTER_ID, USGOV_HRSA_FQHC_DEFAULT_LICENSE, usgovHrsaFqhcAdapter, } from "#adapters/usgov-hrsa-fqhc/adapter";
+export { USGOV_IMLS_PLS_ADAPTER_ID, USGOV_IMLS_PLS_DEFAULT_LICENSE, usgovImlsPlsAdapter, } from "#adapters/usgov-imls-pls/adapter";
+export { USGOV_IRS_BMF_ADAPTER_ID, USGOV_IRS_BMF_DEFAULT_LICENSE, USGovIRSBMFAdapter, } from "#adapters/usgov-irs-bmf/adapter";
+export { USGOV_NAD_ADAPTER_ID, USGOV_NAD_DEFAULT_LICENSE, usgovNADAdapter } from "#adapters/usgov-nad/adapter";
+export { USGOV_NPPES_ADAPTER_ID, USGOV_NPPES_DEFAULT_LICENSE, usgovNPPESAdapter } from "#adapters/usgov-nppes/adapter";
+export { USGOV_SAMHSA_ADAPTER_ID, USGOV_SAMHSA_DEFAULT_LICENSE, usgovSamhsaTreatmentLocatorAdapter, } from "#adapters/usgov-samhsa-treatment-locator/adapter";
+export { WOF_ADMIN_ADAPTER_ID, wofAdminAdapter } from "#adapters/wof-admin-json/adapter";
+export { WOF_POSTALCODE_ADAPTER_ID, wofPostalcodeAdapter } from "#adapters/wof-postalcode-json/adapter";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAsBH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AAE3C;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,aAAa,EAoBpD,CAAA;AAQD,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClE,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAEtG,OAAO,EACN,0BAA0B,EAC1B,+BAA+B,EAC/B,qBAAqB,GACrB,MAAM,mCAAmC,CAAA;AAE1C,OAAO,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAE3G,OAAO,EACN,wBAAwB,EACxB,6BAA6B,EAC7B,oBAAoB,GACpB,MAAM,iCAAiC,CAAA;AAExC,OAAO,EACN,2BAA2B,EAC3B,gCAAgC,EAChC,qBAAqB,GACrB,MAAM,oCAAoC,CAAA;AAE3C,OAAO,EACN,+BAA+B,EAC/B,oCAAoC,EACpC,yBAAyB,GACzB,MAAM,wCAAwC,CAAA;AAE/C,OAAO,EACN,4BAA4B,EAC5B,iCAAiC,EACjC,sBAAsB,GACtB,MAAM,qCAAqC,CAAA;AAE5C,OAAO,EACN,4BAA4B,EAC5B,iCAAiC,EACjC,sBAAsB,GACtB,MAAM,qCAAqC,CAAA;AAE5C,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAE/F,OAAO,EACN,0BAA0B,EAC1B,+BAA+B,EAC/B,oBAAoB,GACpB,MAAM,mCAAmC,CAAA;AAE1C,OAAO,EACN,yBAAyB,EACzB,8BAA8B,EAC9B,mBAAmB,GACnB,MAAM,kCAAkC,CAAA;AAEzC,OAAO,EACN,wBAAwB,EACxB,6BAA6B,EAC7B,kBAAkB,GAClB,MAAM,iCAAiC,CAAA;AAExC,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAA;AAC9G,OAAO,EAAE,sBAAsB,EAAE,2BAA2B,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAA;AAEtH,OAAO,EACN,uBAAuB,EACvB,4BAA4B,EAC5B,kCAAkC,GAClC,MAAM,kDAAkD,CAAA;AAEzD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAA;AACxF,OAAO,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAA"}

package/out/adapters/index.js

@@ -0,0 +1,95 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Adapter registry bootstrap.
+ *
+ *   Importing this module registers every built-in adapter with `defaultAdapterRegistry`. The CLI
+ *   (`commands/corpus/list.tsx`, `commands/corpus/run.tsx`) imports it once at startup.
+ *
+ *   Adapters under construction live in their own subdirectories (`./wof-admin-json/`, `./ban/`, ...)
+ *   and are added to the `BUILTIN_ADAPTERS` list here as they come online. Tests that need a
+ *   pristine registry should construct their own `InMemoryAdapterRegistry` instead of mutating the
+ *   default.
+ *
+ *   The WOF adapters export their canonical ids — `wof-admin` and `wof-postalcode` — so existing
+ *   `mailwoman corpus build` callsites do not need to change despite the Phase 1.5.1 SQLite →
+ *   JSON-bundle pivot (`./wof-admin-json/` and `./wof-postalcode-json/` directories hold the
+ *   implementations; the registered ids are unchanged).
+ */
+import { banAdapter } from "#adapters/ban/adapter";
+import { fccBdcAdapter } from "#adapters/fcc-bdc/adapter";
+import { geonamesPostalAdapter } from "#adapters/geonames-postal/adapter";
+import { geonamesAdapter } from "#adapters/geonames/adapter";
+import { gnafAdapter } from "#adapters/gnaf/adapter";
+import { openaddressesAdapter } from "#adapters/openaddresses/adapter";
+import { overtureAdapter } from "#adapters/overture/adapter";
+import { stateHiSchoolsAdapter } from "#adapters/state-hi-schools/adapter";
+import { stateIaContractorsAdapter } from "#adapters/state-ia-contractors/adapter";
+import { stateNyNotariesAdapter } from "#adapters/state-ny-notaries/adapter";
+import { stateTxNotariesAdapter } from "#adapters/state-tx-notaries/adapter";
+import { tigerAdapter } from "#adapters/tiger/adapter";
+import { usgovHrsaFqhcAdapter } from "#adapters/usgov-hrsa-fqhc/adapter";
+import { usgovImlsPlsAdapter } from "#adapters/usgov-imls-pls/adapter";
+import { USGovIRSBMFAdapter } from "#adapters/usgov-irs-bmf/adapter";
+import { usgovNADAdapter } from "#adapters/usgov-nad/adapter";
+import { usgovNPPESAdapter } from "#adapters/usgov-nppes/adapter";
+import { defaultAdapterRegistry } from "#adapters/utils";
+import { wofAdminAdapter } from "#adapters/wof-admin-json/adapter";
+import { wofPostalcodeAdapter } from "#adapters/wof-postalcode-json/adapter";
+/**
+ * Built-in adapters. Order is significant: `corpus build` iterates this list to drive every adapter in turn.
+ * Coarse-first (admin → postcode), then street-level (BAN FR, TIGER US, OpenAddresses global), then adversarial-source
+ * (FCC BDC US, HRSA FQHC US).
+ *
+ * The `usgov-samhsa-treatment-locator` adapter is intentionally absent from this list — the SAMHSA Open Data Foundry
+ * bulk CSV the adapter was written against is no longer publicly distributed (see issue #33, 2026-05-17 investigation).
+ * The factory + named export remain available so the adapter can be hand-registered if an operator obtains a compatible
+ * CSV (FOIA, partner channel, upstream restoration). Re-add it here once a stable public source returns.
+ */
+export const BUILTIN_ADAPTERS = [
+    wofAdminAdapter,
+    wofPostalcodeAdapter,
+    geonamesAdapter,
+    geonamesPostalAdapter,
+    banAdapter,
+    tigerAdapter,
+    openaddressesAdapter,
+    overtureAdapter,
+    gnafAdapter,
+    fccBdcAdapter,
+    usgovHrsaFqhcAdapter,
+    usgovNPPESAdapter,
+    usgovNADAdapter,
+    usgovImlsPlsAdapter,
+    USGovIRSBMFAdapter,
+    stateIaContractorsAdapter,
+    stateTxNotariesAdapter,
+    stateNyNotariesAdapter,
+    stateHiSchoolsAdapter,
+];
+for (const adapter of BUILTIN_ADAPTERS) {
+    if (!defaultAdapterRegistry.get(adapter.id)) {
+        defaultAdapterRegistry.register(adapter);
+    }
+}
+export { BAN_ADAPTER_ID, banAdapter } from "#adapters/ban/adapter";
+export { FCC_BDC_ADAPTER_ID, FCC_BDC_DEFAULT_LICENSE, fccBdcAdapter } from "#adapters/fcc-bdc/adapter";
+export { GEONAMES_POSTAL_ADAPTER_ID, GEONAMES_POSTAL_DEFAULT_LICENSE, geonamesPostalAdapter, } from "#adapters/geonames-postal/adapter";
+export { GEONAMES_ADAPTER_ID, GEONAMES_DEFAULT_LICENSE, geonamesAdapter } from "#adapters/geonames/adapter";
+export { OPENADDRESSES_ADAPTER_ID, OPENADDRESSES_DEFAULT_LICENSE, openaddressesAdapter, } from "#adapters/openaddresses/adapter";
+export { STATE_HI_SCHOOLS_ADAPTER_ID, STATE_HI_SCHOOLS_DEFAULT_LICENSE, stateHiSchoolsAdapter, } from "#adapters/state-hi-schools/adapter";
+export { STATE_IA_CONTRACTORS_ADAPTER_ID, STATE_IA_CONTRACTORS_DEFAULT_LICENSE, stateIaContractorsAdapter, } from "#adapters/state-ia-contractors/adapter";
+export { STATE_NY_NOTARIES_ADAPTER_ID, STATE_NY_NOTARIES_DEFAULT_LICENSE, stateNyNotariesAdapter, } from "#adapters/state-ny-notaries/adapter";
+export { STATE_TX_NOTARIES_ADAPTER_ID, STATE_TX_NOTARIES_DEFAULT_LICENSE, stateTxNotariesAdapter, } from "#adapters/state-tx-notaries/adapter";
+export { TIGER_ADAPTER_ID, TIGER_DEFAULT_LICENSE, tigerAdapter } from "#adapters/tiger/adapter";
+export { USGOV_HRSA_FQHC_ADAPTER_ID, USGOV_HRSA_FQHC_DEFAULT_LICENSE, usgovHrsaFqhcAdapter, } from "#adapters/usgov-hrsa-fqhc/adapter";
+export { USGOV_IMLS_PLS_ADAPTER_ID, USGOV_IMLS_PLS_DEFAULT_LICENSE, usgovImlsPlsAdapter, } from "#adapters/usgov-imls-pls/adapter";
+export { USGOV_IRS_BMF_ADAPTER_ID, USGOV_IRS_BMF_DEFAULT_LICENSE, USGovIRSBMFAdapter, } from "#adapters/usgov-irs-bmf/adapter";
+export { USGOV_NAD_ADAPTER_ID, USGOV_NAD_DEFAULT_LICENSE, usgovNADAdapter } from "#adapters/usgov-nad/adapter";
+export { USGOV_NPPES_ADAPTER_ID, USGOV_NPPES_DEFAULT_LICENSE, usgovNPPESAdapter } from "#adapters/usgov-nppes/adapter";
+export { USGOV_SAMHSA_ADAPTER_ID, USGOV_SAMHSA_DEFAULT_LICENSE, usgovSamhsaTreatmentLocatorAdapter, } from "#adapters/usgov-samhsa-treatment-locator/adapter";
+export { WOF_ADMIN_ADAPTER_ID, wofAdminAdapter } from "#adapters/wof-admin-json/adapter";
+export { WOF_POSTALCODE_ADAPTER_ID, wofPostalcodeAdapter } from "#adapters/wof-postalcode-json/adapter";
+//# sourceMappingURL=index.js.map

package/out/adapters/index.js.map

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

package/out/adapters/openaddresses/adapter.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `openaddresses`: Line-delimited GeoJSON adapter for openaddresses.io exports.
+ *
+ *   OpenAddresses publishes country-partitioned address dumps as either CSV or line-delimited GeoJSON
+ *   (one `Feature` per line, also called ND-GeoJSON / GeoJSONL). This adapter consumes the
+ *   line-delimited GeoJSON shape — it streams cleanly without holding the file in memory, which
+ *   matters for the multi-gigabyte national dumps (e.g. `us-northeast.geojsonl`, ~20M rows).
+ *
+ *   The collection aggregates **hundreds** of underlying sources with **per-source licenses** (city
+ *   open-data portals, county GIS departments, state DOTs). The adapter therefore prefers the
+ *   per-row `LICENSE` property when present and falls back to the configured `defaultLicense`. The
+ *   propagated license travels with each `CanonicalRow` so downstream code can stratify, exclude,
+ *   or re-attribute by license at training time.
+ *
+ *   Country must be explicit (`opts.country` REQUIRED): OpenAddresses files are organized by country
+ *   but the row-level data doesn't include a country code, so the adapter refuses to run without
+ *   one. This matches how a `mailwoman corpus build` invocation pins each file to a country via the
+ *   inputs JSON.
+ *
+ *   Properties consumed (per the canonical OpenAddresses schema; both UPPERCASE and lowercase
+ *   variants are accepted because legacy dumps used UPPERCASE):
+ *
+ *   | Property | ComponentTag | | ------------- |
+ *   -------------------------------------------------------------- | | `number` | `house_number` |
+ *   | `street` | `street` | | `unit` | `unit` (if non-empty) | | `city` | `locality` | | `region` |
+ *   `region` (state code for US, province for CA, etc.) | | `postcode` | `postcode` | | `LICENSE` |
+ *   per-row `license` override | | `hash` / `id` | `source_id` (prefer `hash`; fall back to `id`;
+ *   then synthesize)|
+ *
+ *   `district` is intentionally NOT mapped — for US data it carries borough or county and would
+ *   inflate alignment quarantine because postal addresses don't include it. Phase 6+ may revisit
+ *   for non-US locales where district names DO appear on the envelope.
+ */
+import type { CorpusAdapter } from "#types";
+/**
+ * Registry id for this adapter. Stamped into every row it emits, so a corpus record can be traced back to the dataset
+ * it came from.
+ */
+export declare const OPENADDRESSES_ADAPTER_ID = "openaddresses";
+/**
+ * License carried by this source (CC-BY-4.0), attached to each row so downstream consumers inherit the terms rather
+ * than having to look them up.
+ */
+export declare const OPENADDRESSES_DEFAULT_LICENSE = "CC-BY-4.0";
+export interface OpenaddressesAdapterOptions {
+    /**
+     * Per-row license used when a Feature lacks an explicit `LICENSE` property. Defaults to `CC-BY-4.0` — the most common
+     * license across the OpenAddresses collection. Override per dump via the runner's adapter-options passthrough.
+     */
+    defaultLicense?: string;
+    /**
+     * Per-adapter share-alike drop. Default **true** (include) as of 2026-06-19: exclusion is a deliberate BUILD-level
+     * act (`buildCorpus({ excludeLicenses })` / `--exclude-share-alike`), NOT a silent adapter default (#26 — "purposely
+     * exclude, don't opt in to include"). Set false only for an explicit adapter-scoped drop; the build-level
+     * `--exclude-share-alike` is the normal path.
+     */
+    allowShareAlike?: boolean;
+}
+/**
+ * Build an OpenAddresses adapter. The optional `defaultLicense` lets callers stamp a non-default fallback for dumps
+ * known to carry a single license throughout (e.g. a PDDL-only state slice).
+ */
+export declare function createOpenaddressesAdapter(opts?: OpenaddressesAdapterOptions): CorpusAdapter;
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export declare const openaddressesAdapter: CorpusAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/out/adapters/openaddresses/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../lib/adapters/openaddresses/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAOH,OAAO,KAAK,EAAgC,aAAa,EAAE,MAAM,QAAQ,CAAA;AAGzE;;;GAGG;AACH,eAAO,MAAM,wBAAwB,kBAAkB,CAAA;AACvD;;;GAGG;AACH,eAAO,MAAM,6BAA6B,cAAc,CAAA;AAsDxD,MAAM,WAAW,2BAA2B;IAC3C;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;CACzB;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,GAAE,2BAAgC,GAAG,aAAa,CAoHhG;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB,eAA+B,CAAA"}

package/out/adapters/openaddresses/adapter.js

@@ -0,0 +1,186 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `openaddresses`: Line-delimited GeoJSON adapter for openaddresses.io exports.
+ *
+ *   OpenAddresses publishes country-partitioned address dumps as either CSV or line-delimited GeoJSON
+ *   (one `Feature` per line, also called ND-GeoJSON / GeoJSONL). This adapter consumes the
+ *   line-delimited GeoJSON shape — it streams cleanly without holding the file in memory, which
+ *   matters for the multi-gigabyte national dumps (e.g. `us-northeast.geojsonl`, ~20M rows).
+ *
+ *   The collection aggregates **hundreds** of underlying sources with **per-source licenses** (city
+ *   open-data portals, county GIS departments, state DOTs). The adapter therefore prefers the
+ *   per-row `LICENSE` property when present and falls back to the configured `defaultLicense`. The
+ *   propagated license travels with each `CanonicalRow` so downstream code can stratify, exclude,
+ *   or re-attribute by license at training time.
+ *
+ *   Country must be explicit (`opts.country` REQUIRED): OpenAddresses files are organized by country
+ *   but the row-level data doesn't include a country code, so the adapter refuses to run without
+ *   one. This matches how a `mailwoman corpus build` invocation pins each file to a country via the
+ *   inputs JSON.
+ *
+ *   Properties consumed (per the canonical OpenAddresses schema; both UPPERCASE and lowercase
+ *   variants are accepted because legacy dumps used UPPERCASE):
+ *
+ *   | Property | ComponentTag | | ------------- |
+ *   -------------------------------------------------------------- | | `number` | `house_number` |
+ *   | `street` | `street` | | `unit` | `unit` (if non-empty) | | `city` | `locality` | | `region` |
+ *   `region` (state code for US, province for CA, etc.) | | `postcode` | `postcode` | | `LICENSE` |
+ *   per-row `license` override | | `hash` / `id` | `source_id` (prefer `hash`; fall back to `id`;
+ *   then synthesize)|
+ *
+ *   `district` is intentionally NOT mapped — for US data it carries borough or county and would
+ *   inflate alignment quarantine because postal addresses don't include it. Phase 6+ may revisit
+ *   for non-US locales where district names DO appear on the envelope.
+ */
+import { tryParsingJSON } from "@mailwoman/core/json";
+import { formatAddress, reconcileComponents } from "@mailwoman/formatter";
+import { TextSpliterator } from "spliterator";
+import { stableSourceID } from "#adapters/utils";
+import { SHARE_ALIKE_PATTERN } from "#utils";
+/**
+ * Registry id for this adapter. Stamped into every row it emits, so a corpus record can be traced back to the dataset
+ * it came from.
+ */
+export const OPENADDRESSES_ADAPTER_ID = "openaddresses";
+/**
+ * License carried by this source (CC-BY-4.0), attached to each row so downstream consumers inherit the terms rather
+ * than having to look them up.
+ */
+export const OPENADDRESSES_DEFAULT_LICENSE = "CC-BY-4.0";
+/**
+ * Return a lowercase-keyed view of a Feature's properties so case variants both work.
+ */
+function normalizeProperties(raw) {
+    if (!raw || typeof raw !== "object")
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        if (typeof v === "string") {
+            out[k.toLowerCase()] = v;
+        }
+        else if (typeof v === "number") {
+            out[k.toLowerCase()] = String(v);
+        }
+    }
+    return out;
+}
+/**
+ * Parse a single ND-GeoJSON line; return null for blanks, comments, or non-Feature shapes.
+ */
+function parseFeatureLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#"))
+        return null;
+    const parsed = tryParsingJSON(trimmed);
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const obj = parsed;
+    if (obj.type !== "Feature")
+        return null;
+    return normalizeProperties(obj.properties);
+}
+/**
+ * Build an OpenAddresses adapter. The optional `defaultLicense` lets callers stamp a non-default fallback for dumps
+ * known to carry a single license throughout (e.g. a PDDL-only state slice).
+ */
+export function createOpenaddressesAdapter(opts = {}) {
+    const defaultLicense = opts.defaultLicense ?? OPENADDRESSES_DEFAULT_LICENSE;
+    const allowShareAlike = opts.allowShareAlike ?? true;
+    return {
+        id: OPENADDRESSES_ADAPTER_ID,
+        defaultLicense,
+        description: "OpenAddresses (global): line-delimited GeoJSON dumps with per-row licenses.",
+        async *rows(adapterOpts) {
+            if (!adapterOpts.country) {
+                throw new Error("openaddresses adapter: --country is required (OpenAddresses files are country-partitioned but rows lack a country field)");
+            }
+            const country = adapterOpts.country;
+            // TextSpliterator streams string lines (parseFeatureLine keeps tolerating blank/`#`/
+            // malformed lines by returning null); passing the path string lets the lib own + dispose
+            // the file handle, including on an early `break`.
+            const lines = TextSpliterator.fromAsync(adapterOpts.inputPath);
+            let emitted = 0;
+            let shareAlikeBlocked = 0;
+            try {
+                for await (const line of lines) {
+                    if (adapterOpts.signal?.aborted)
+                        break;
+                    if (adapterOpts.limit !== undefined && emitted >= adapterOpts.limit)
+                        break;
+                    const props = parseFeatureLine(line);
+                    if (!props)
+                        continue;
+                    const houseNumber = props.number?.trim() ?? "";
+                    const street = props.street?.trim() ?? "";
+                    const unit = props.unit?.trim() ?? "";
+                    const city = props.city?.trim() ?? "";
+                    const region = props.region?.trim() ?? "";
+                    const postcode = props.postcode?.trim() ?? "";
+                    // A row is only useful if it has, at minimum, a street + (postcode OR locality).
+                    // Pure point-only rows would land in quarantine anyway.
+                    if (!street)
+                        continue;
+                    if (!city && !postcode)
+                        continue;
+                    const license = (props.license?.trim() || defaultLicense).trim();
+                    if (!allowShareAlike && SHARE_ALIKE_PATTERN.test(license)) {
+                        shareAlikeBlocked++;
+                        continue;
+                    }
+                    const components = {};
+                    if (houseNumber) {
+                        components.house_number = houseNumber;
+                    }
+                    if (street) {
+                        components.street = street;
+                    }
+                    if (unit) {
+                        components.unit = unit;
+                    }
+                    if (city) {
+                        components.locality = city;
+                    }
+                    if (region) {
+                        components.region = region;
+                    }
+                    if (postcode) {
+                        components.postcode = postcode;
+                    }
+                    const raw = formatAddress(components, country, { separator: ", " });
+                    if (!raw)
+                        continue;
+                    const aligned = reconcileComponents(components, raw);
+                    if (!Object.keys(aligned).length)
+                        continue;
+                    const sourceIDSeed = props.hash?.trim() || props.id?.trim();
+                    const sourceID = sourceIDSeed
+                        ? `${OPENADDRESSES_ADAPTER_ID}-${sourceIDSeed}`
+                        : stableSourceID(OPENADDRESSES_ADAPTER_ID, aligned);
+                    yield {
+                        raw,
+                        components: aligned,
+                        country,
+                        source: OPENADDRESSES_ADAPTER_ID,
+                        source_id: sourceID,
+                        corpus_version: "",
+                        license,
+                    };
+                    emitted++;
+                }
+            }
+            finally {
+                if (shareAlikeBlocked > 0) {
+                    process.stderr.write(`  openaddresses: ${shareAlikeBlocked} share-alike rows dropped, ${emitted} kept\n`);
+                }
+            }
+        },
+    };
+}
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const openaddressesAdapter = createOpenaddressesAdapter();
+//# sourceMappingURL=adapter.js.map

package/out/adapters/openaddresses/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../lib/adapters/openaddresses/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AACzE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,OAAO,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAA;AAE5C;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,eAAe,CAAA;AACvD;;;GAGG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,WAAW,CAAA;AAmBxD;;GAEG;AACH,SAAS,mBAAmB,CAAC,GAAY;IACxC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAA;IAC9C,MAAM,GAAG,GAA2B,EAAE,CAAA;IAEtC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAA8B,CAAC,EAAE,CAAC;QACrE,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC3B,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,GAAG,CAAC,CAAA;QACzB,CAAC;aAAM,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YAClC,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAA;QACjC,CAAC;IACF,CAAC;IAED,OAAO,GAAmB,CAAA;AAC3B,CAAC;AAED;;GAEG;AACH,SAAS,gBAAgB,CAAC,IAAY;IACrC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;IAE3B,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IACpD,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,CAAA;IAEtC,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IACtD,MAAM,GAAG,GAAG,MAAiD,CAAA;IAE7D,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA;IAEvC,OAAO,mBAAmB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAA;AAC3C,CAAC;AAkBD;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CAAC,OAAoC,EAAE;IAChF,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,6BAA6B,CAAA;IAC3E,MAAM,eAAe,GAAG,IAAI,CAAC,eAAe,IAAI,IAAI,CAAA;IAEpD,OAAO;QACN,EAAE,EAAE,wBAAwB;QAC5B,cAAc;QACd,WAAW,EAAE,6EAA6E;QAE1F,KAAK,CAAC,CAAC,IAAI,CAAC,WAA2B;YACtC,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;gBAC1B,MAAM,IAAI,KAAK,CACd,0HAA0H,CAC1H,CAAA;YACF,CAAC;YAED,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAA;YAEnC,qFAAqF;YACrF,yFAAyF;YACzF,kDAAkD;YAClD,MAAM,KAAK,GAAG,eAAe,CAAC,SAAS,CAAC,WAAW,CAAC,SAAS,CAAC,CAAA;YAE9D,IAAI,OAAO,GAAG,CAAC,CAAA;YACf,IAAI,iBAAiB,GAAG,CAAC,CAAA;YAEzB,IAAI,CAAC;gBACJ,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;oBAChC,IAAI,WAAW,CAAC,MAAM,EAAE,OAAO;wBAAE,MAAK;oBAEtC,IAAI,WAAW,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,IAAI,WAAW,CAAC,KAAK;wBAAE,MAAK;oBAE1E,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAA;oBAEpC,IAAI,CAAC,KAAK;wBAAE,SAAQ;oBAEpB,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;oBAC9C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;oBACzC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;oBACrC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;oBACrC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;oBACzC,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;oBAE7C,iFAAiF;oBACjF,wDAAwD;oBACxD,IAAI,CAAC,MAAM;wBAAE,SAAQ;oBAErB,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ;wBAAE,SAAQ;oBAEhC,MAAM,OAAO,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,cAAc,CAAC,CAAC,IAAI,EAAE,CAAA;oBAEhE,IAAI,CAAC,eAAe,IAAI,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;wBAC3D,iBAAiB,EAAE,CAAA;wBAEnB,SAAQ;oBACT,CAAC;oBAED,MAAM,UAAU,GAA+B,EAAE,CAAA;oBAEjD,IAAI,WAAW,EAAE,CAAC;wBACjB,UAAU,CAAC,YAAY,GAAG,WAAW,CAAA;oBACtC,CAAC;oBAED,IAAI,MAAM,EAAE,CAAC;wBACZ,UAAU,CAAC,MAAM,GAAG,MAAM,CAAA;oBAC3B,CAAC;oBAED,IAAI,IAAI,EAAE,CAAC;wBACV,UAAU,CAAC,IAAI,GAAG,IAAI,CAAA;oBACvB,CAAC;oBAED,IAAI,IAAI,EAAE,CAAC;wBACV,UAAU,CAAC,QAAQ,GAAG,IAAI,CAAA;oBAC3B,CAAC;oBAED,IAAI,MAAM,EAAE,CAAC;wBACZ,UAAU,CAAC,MAAM,GAAG,MAAM,CAAA;oBAC3B,CAAC;oBAED,IAAI,QAAQ,EAAE,CAAC;wBACd,UAAU,CAAC,QAAQ,GAAG,QAAQ,CAAA;oBAC/B,CAAC;oBAED,MAAM,GAAG,GAAG,aAAa,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;oBAEnE,IAAI,CAAC,GAAG;wBAAE,SAAQ;oBAElB,MAAM,OAAO,GAAG,mBAAmB,CAAC,UAAU,EAAE,GAAG,CAAC,CAAA;oBAEpD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM;wBAAE,SAAQ;oBAE1C,MAAM,YAAY,GAAG,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,CAAA;oBAE3D,MAAM,QAAQ,GAAG,YAAY;wBAC5B,CAAC,CAAC,GAAG,wBAAwB,IAAI,YAAY,EAAE;wBAC/C,CAAC,CAAC,cAAc,CAAC,wBAAwB,EAAE,OAAO,CAAC,CAAA;oBAEpD,MAAM;wBACL,GAAG;wBACH,UAAU,EAAE,OAAO;wBACnB,OAAO;wBACP,MAAM,EAAE,wBAAwB;wBAChC,SAAS,EAAE,QAAQ;wBACnB,cAAc,EAAE,EAAE;wBAClB,OAAO;qBACP,CAAA;oBAED,OAAO,EAAE,CAAA;gBACV,CAAC;YACF,CAAC;oBAAS,CAAC;gBACV,IAAI,iBAAiB,GAAG,CAAC,EAAE,CAAC;oBAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oBAAoB,iBAAiB,8BAA8B,OAAO,SAAS,CAAC,CAAA;gBAC1G,CAAC;YACF,CAAC;QACF,CAAC;KACD,CAAA;AACF,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,0BAA0B,EAAE,CAAA"}