@mailwoman/corpus 9.2.0 → 9.3.0

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.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":"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"}

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

@@ -0,0 +1,48 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `overture`: Overture Maps Addresses adapter (epic #470 — the conditional corpus adapter, realized
+ *   2026-06-20). Overture's global Addresses theme is the single-schema, well-normalized address
+ *   dataset that fixes OpenAddresses' per-country patchiness (OA dropped Spain; OA-DE omits the
+ *   Bundesland) — it even re-hosts the OA Spain data the standalone OA bucket no longer serves.
+ *
+ *   This adapter consumes a per-country LINE-DELIMITED JSON dump of the corpus-relevant fields (`{
+ *   street, number, unit, postcode, locality }`), produced by `scripts/ingest-overture-addresses.ts
+ *   --corpus-jsonl` (which does the DuckDB / S3 heavy lifting and flattens `address_levels` → the
+ *   municipality locality). The split keeps `@mailwoman/corpus` — a RUNTIME dep of the `mailwoman`
+ *   CLI — free of the heavy native `@duckdb/node-api`; the adapter just streams JSONL line-by-line,
+ *   exactly like `openaddresses`.
+ *
+ *   The `street` surface carries the locale's street keyword verbatim (`"CALLE JULAN"`, `"VIA
+ *   ROMA"`). We map it to `street` whole and let the downstream affix-relabel split `street_prefix`
+ *   — the same path every other source rides. This slice exists because the model was
+ *   en-us/fr-trained and never saw non-en/fr street formats (the 2026-06-19 EU parse-blocker
+ *   measured loc-correct ES 21% / IT 59% / NL 64% vs FR/US ~98%).
+ *
+ *   `--country` is REQUIRED (the JSONL is per-country and the rows omit a country field), matching
+ *   `openaddresses`. License is Overture's CDLA-Permissive-2.0 (attribution; not share-alike).
+ *
+ *   | Field | ComponentTag | | --------- | ---------------------------------------------- | |
+ *   `street` | `street` (keyword incl.; affix-relabel splits prefix) | | `number` | `house_number`
+ *   (skipped when "S-N"/"S/N" = sin número) | | `unit` | `unit` (if non-empty) | | `postcode`|
+ *   `postcode` | | `locality`| `locality` (Overture address_levels municipality, or postal_city) |
+ */
+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 OVERTURE_ADAPTER_ID = "overture";
+/**
+ * License carried by this source (CDLA-Permissive-2.0), attached to each row so downstream consumers inherit the terms
+ * rather than having to look them up.
+ */
+export declare const OVERTURE_DEFAULT_LICENSE = "CDLA-Permissive-2.0";
+export declare function createOvertureAdapter(): CorpusAdapter;
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export declare const overtureAdapter: CorpusAdapter;
+//# sourceMappingURL=adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../lib/adapters/overture/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAOH,OAAO,KAAK,EAAgC,aAAa,EAAE,MAAM,QAAQ,CAAA;AAEzE;;;GAGG;AACH,eAAO,MAAM,mBAAmB,aAAa,CAAA;AAC7C;;;GAGG;AACH,eAAO,MAAM,wBAAwB,wBAAwB,CAAA;AAuB7D,wBAAgB,qBAAqB,IAAI,aAAa,CAqFrD;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,eAA0B,CAAA"}

package/out/adapters/overture/adapter.js

@@ -0,0 +1,125 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `overture`: Overture Maps Addresses adapter (epic #470 — the conditional corpus adapter, realized
+ *   2026-06-20). Overture's global Addresses theme is the single-schema, well-normalized address
+ *   dataset that fixes OpenAddresses' per-country patchiness (OA dropped Spain; OA-DE omits the
+ *   Bundesland) — it even re-hosts the OA Spain data the standalone OA bucket no longer serves.
+ *
+ *   This adapter consumes a per-country LINE-DELIMITED JSON dump of the corpus-relevant fields (`{
+ *   street, number, unit, postcode, locality }`), produced by `scripts/ingest-overture-addresses.ts
+ *   --corpus-jsonl` (which does the DuckDB / S3 heavy lifting and flattens `address_levels` → the
+ *   municipality locality). The split keeps `@mailwoman/corpus` — a RUNTIME dep of the `mailwoman`
+ *   CLI — free of the heavy native `@duckdb/node-api`; the adapter just streams JSONL line-by-line,
+ *   exactly like `openaddresses`.
+ *
+ *   The `street` surface carries the locale's street keyword verbatim (`"CALLE JULAN"`, `"VIA
+ *   ROMA"`). We map it to `street` whole and let the downstream affix-relabel split `street_prefix`
+ *   — the same path every other source rides. This slice exists because the model was
+ *   en-us/fr-trained and never saw non-en/fr street formats (the 2026-06-19 EU parse-blocker
+ *   measured loc-correct ES 21% / IT 59% / NL 64% vs FR/US ~98%).
+ *
+ *   `--country` is REQUIRED (the JSONL is per-country and the rows omit a country field), matching
+ *   `openaddresses`. License is Overture's CDLA-Permissive-2.0 (attribution; not share-alike).
+ *
+ *   | Field | ComponentTag | | --------- | ---------------------------------------------- | |
+ *   `street` | `street` (keyword incl.; affix-relabel splits prefix) | | `number` | `house_number`
+ *   (skipped when "S-N"/"S/N" = sin número) | | `unit` | `unit` (if non-empty) | | `postcode`|
+ *   `postcode` | | `locality`| `locality` (Overture address_levels municipality, or postal_city) |
+ */
+import { tryParsingJSON } from "@mailwoman/core/json";
+import { formatAddress, reconcileComponents } from "@mailwoman/formatter";
+import { TextSpliterator } from "spliterator";
+import { stableSourceID } from "#adapters/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 OVERTURE_ADAPTER_ID = "overture";
+/**
+ * License carried by this source (CDLA-Permissive-2.0), attached to each row so downstream consumers inherit the terms
+ * rather than having to look them up.
+ */
+export const OVERTURE_DEFAULT_LICENSE = "CDLA-Permissive-2.0";
+function parseLine(line) {
+    const t = line.trim();
+    if (!t || t.startsWith("#"))
+        return null;
+    const o = tryParsingJSON(t);
+    return o && typeof o === "object" ? o : null;
+}
+export function createOvertureAdapter() {
+    return {
+        id: OVERTURE_ADAPTER_ID,
+        defaultLicense: OVERTURE_DEFAULT_LICENSE,
+        description: "Overture Maps Addresses (global): per-country JSONL of street/number/postcode/locality.",
+        async *rows(opts) {
+            if (!opts.country) {
+                throw new Error("overture adapter: --country is required (the Overture JSONL is per-country and rows omit a country field)");
+            }
+            const country = opts.country;
+            // TextSpliterator streams string lines (parseLine keeps tolerating blank/`#`/malformed
+            // lines by returning null); the path string lets the lib own + dispose the file handle,
+            // including on an early `break`.
+            const lines = TextSpliterator.fromAsync(opts.inputPath);
+            let emitted = 0;
+            for await (const line of lines) {
+                if (opts.signal?.aborted)
+                    break;
+                if (opts.limit !== undefined && emitted >= opts.limit)
+                    break;
+                const r = parseLine(line);
+                if (!r)
+                    continue;
+                const street = r.street?.trim() ?? "";
+                const number = r.number?.trim() ?? "";
+                const unit = r.unit?.trim() ?? "";
+                const postcode = r.postcode?.trim() ?? "";
+                const locality = r.locality?.trim() ?? "";
+                // Only useful with a street + (postcode OR locality); point-only rows quarantine anyway.
+                if (!street)
+                    continue;
+                if (!postcode && !locality)
+                    continue;
+                const components = {};
+                // Overture "S-N" / "S/N" = sin número; only keep a real numeric house number.
+                if (/^\d/.test(number)) {
+                    components.house_number = number;
+                }
+                components.street = street;
+                if (unit) {
+                    components.unit = unit;
+                }
+                if (postcode) {
+                    components.postcode = postcode;
+                }
+                if (locality) {
+                    components.locality = locality;
+                }
+                const raw = formatAddress(components, country, { separator: ", " });
+                if (!raw)
+                    continue;
+                const aligned = reconcileComponents(components, raw);
+                if (!Object.keys(aligned).length)
+                    continue;
+                yield {
+                    raw,
+                    components: aligned,
+                    country,
+                    source: OVERTURE_ADAPTER_ID,
+                    source_id: stableSourceID(OVERTURE_ADAPTER_ID, aligned),
+                    corpus_version: "",
+                    license: OVERTURE_DEFAULT_LICENSE,
+                };
+                emitted++;
+            }
+        },
+    };
+}
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const overtureAdapter = createOvertureAdapter();
+//# sourceMappingURL=adapter.js.map

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

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

package/out/adapters/state-hi-schools/adapter.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `state-hi-schools`: Hawaii DOE public + charter school workbook consumer.
+ *
+ *   The Hawaii State Department of Education publishes a directory of all HIDOE schools and public
+ *   charter schools (PCS) as an XLSX workbook (`SchoolList.xlsx`) with two sheets: `HIDOE` (~258
+ *   rows) and `PCS` (~38 rows). Total ~296 rows statewide. Each row carries a school name,
+ *   single-line street address, city, ZIP, a numeric `code`, and HI-specific administrative columns
+ *   (complex, complex_area, district, island, charter).
+ *
+ *   The adapter consumes the original XLSX retained by the fetcher and reads both worksheets directly.
+ *   Legacy flat CSV artifacts remain accepted so existing source caches do not need conversion.
+ *
+ *   Address parsing notes: Hawaii's residential numbering is hyphenated on Oahu (`47-470 Hui Aeko
+ *   Place`), Kauai (`2-4035 Kaumualii Hwy`), and elsewhere. The shared HOUSE_NUMBER_PREFIX regex
+ *   covers this via its optional `(?:-\d+)?` group.
+ *
+ *   The `island` and `district` columns are HIDOE administrative labels (Honolulu, Central, Leeward,
+ *   Windward, Hilo, Hawaii, Maui, Kauai) — they are NOT US counties and intentionally are not
+ *   surfaced as `subregion`.
+ *
+ *   Output: one row per school with `venue` (school name), `(house_number?, street, locality,
+ *   region=HI, postcode)`, and a stable `source_id` derived from the school `code`.
+ *
+ *   License: stamped `"Public Domain"` per Hawaii state government open-data terms.
+ */
+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 STATE_HI_SCHOOLS_ADAPTER_ID = "state-hi-schools";
+/**
+ * License carried by this source (Public Domain), attached to each row so downstream consumers inherit the terms rather
+ * than having to look them up.
+ */
+export declare const STATE_HI_SCHOOLS_DEFAULT_LICENSE = "Public Domain";
+export declare function createStateHiSchoolsAdapter(): CorpusAdapter;
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export declare const stateHiSchoolsAdapter: CorpusAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/out/adapters/state-hi-schools/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../lib/adapters/state-hi-schools/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AASH,OAAO,KAAK,EAAgC,aAAa,EAAE,MAAM,QAAQ,CAAA;AAEzE;;;GAGG;AACH,eAAO,MAAM,2BAA2B,qBAAqB,CAAA;AAC7D;;;GAGG;AACH,eAAO,MAAM,gCAAgC,kBAAkB,CAAA;AAqC/D,wBAAgB,2BAA2B,IAAI,aAAa,CA+E3D;AAED;;GAEG;AACH,eAAO,MAAM,qBAAqB,eAAgC,CAAA"}