@mailwoman/corpus 9.3.0 → 10.0.0

package/out/tools/sub/venue/wikidata.js

@@ -0,0 +1,62 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   @file The Wikidata leg of the sub-venue lexicon — turning the designator-label SPARQL payload into
+ *   surfaces.
+ *
+ *   Reads an already-parsed payload rather than issuing a query: the acquisition lives in
+ *   `fetch/wikidata-subvenue.ts`, and keeping the conversion a pure function of parsed input is what
+ *   lets the builder stay deterministic and testable with no network and no fixture on disk.
+ *
+ *   Wikidata gives a CONCEPT NAME per language, not a designator as addressed. Q849706's Spanish label
+ *   is `terminal aeroportuaria`; the addressed form is `Terminal`. So every surface produced here lands
+ *   `curated: false`, and the head-noun derivation is what proposes the addressed form from it.
+ */
+import { normalizeSurface } from "#tools/sub/venue/surfaces";
+import { CONCEPT_QIDS } from "#tools/sub/venue/table";
+/**
+ * Turn the Wikidata designator-label payload into surfaces.
+ *
+ * A row is dropped when its language tag is empty (an untagged literal, which Wikidata occasionally carries), when the
+ * QID maps to no designator in {@link CONCEPT_QIDS}, or when the normalized phrase is empty. Everything that survives
+ * lands `curated: false` — see the module docstring.
+ */
+export function surfacesFromWikidata(payload, conceptQIDs = CONCEPT_QIDS) {
+    const byQID = new Map(Object.entries(conceptQIDs).map(([id, qid]) => [qid, id]));
+    const envelope = payload;
+    const seen = new Set();
+    const out = [];
+    for (const binding of envelope.results?.bindings ?? []) {
+        const qid = binding.item?.value?.split("/").pop();
+        const recordID = qid ? byQID.get(qid) : undefined;
+        const lang = binding.lang?.value;
+        const raw = binding.label?.value;
+        if (!recordID || !lang || !raw)
+            continue;
+        const phrase = normalizeSurface(raw);
+        if (!phrase)
+            continue;
+        const source = binding.kind?.value === "alt" ? "wikidata:alt" : "wikidata:label";
+        // A concept can carry the same string as both a label and an alias, and across dialect subtags
+        // (`zh`, `zh-cn`, `zh-hans` all say 航站楼). Key the dedupe on the tuple that identifies a row.
+        const key = `${phrase}\0${recordID}\0${lang}\0${source}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({
+            phrase,
+            recordID,
+            recordKind: "designator",
+            lang,
+            region: "",
+            source,
+            curated: false,
+            observations: 0,
+            context: {},
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=wikidata.js.map

package/out/tools/sub/venue/wikidata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wikidata.js","sourceRoot":"","sources":["../../../../lib/tools/sub/venue/wikidata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AAC5D,OAAO,EAAE,YAAY,EAAwB,MAAM,wBAAwB,CAAA;AAgB3E;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CACnC,OAAgB,EAChB,WAAW,GAAqC,YAAY;IAE5D,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,CAAA;IAChF,MAAM,QAAQ,GAAG,OAAyB,CAAA;IAC1C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,MAAM,GAAG,GAAsB,EAAE,CAAA;IAEjC,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,CAAC;QACxD,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAA;QACjD,MAAM,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;QACjD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,KAAK,CAAA;QAChC,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,EAAE,KAAK,CAAA;QAEhC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,IAAI,CAAC,GAAG;YAAE,SAAQ;QAExC,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAA;QAEpC,IAAI,CAAC,MAAM;YAAE,SAAQ;QAErB,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,gBAAgB,CAAA;QAChF,+FAA+F;QAC/F,6FAA6F;QAC7F,MAAM,GAAG,GAAG,GAAG,MAAM,KAAK,QAAQ,KAAK,IAAI,KAAK,MAAM,EAAE,CAAA;QAExD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAQ;QAC3B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAEb,GAAG,CAAC,IAAI,CAAC;YACR,MAAM;YACN,QAAQ;YACR,UAAU,EAAE,YAAY;YACxB,IAAI;YACJ,MAAM,EAAE,EAAE;YACV,MAAM;YACN,OAAO,EAAE,KAAK;YACd,YAAY,EAAE,CAAC;YACf,OAAO,EAAE,EAAE;SACX,CAAC,CAAA;IACH,CAAC;IAED,OAAO,GAAG,CAAA;AACX,CAAC"}

package/out/tw/tools/fetch/gcis.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Fetch Taiwan's company and business registers (公司登記資料, 商業登記資料) from the Ministry of
+ *   Economic Affairs' commerce open-data platform, data.gcis.nat.gov.tw. The platform publishes the
+ *   full registers as CSV files split by region (the six special municipalities each on their own,
+ *   the rest of the island in four bands) and by industry letter, 148 files in all, each row carrying
+ *   the registered address (公司地址) and, for companies, the tax office's business address
+ *   (營業地址) as free text. This is the NOISY source for Taiwanese addresses: a person typed these.
+ *
+ *   License: 政府資料開放授權條款－第1版 (Open Government Data License, Taiwan, v1.0). The platform's
+ *   own dialog states the condition that binds: attribution in the form it prescribes, or the grant is
+ *   void from the start ("未盡顯名標示義務者，視為自始未取得開放資料之授權"). The manifest records the
+ *   prescribed wording per file so the corpus build and the model card can carry it.
+ *
+ *   Invoke via `mailwoman corpus fetch gcis-tw --out-root <path>`.
+ */
+import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download/index";
+export type FetchGCISTWOptions = BaseFetchOptions;
+export declare function fetchGCISTW(options: FetchGCISTWOptions, report?: (line: string) => void): Promise<FetchSummary>;
+//# sourceMappingURL=gcis.d.ts.map

package/out/tw/tools/fetch/gcis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcis.d.ts","sourceRoot":"","sources":["../../../../lib/tw/tools/fetch/gcis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AASH,OAAO,KAAK,EACX,gBAAgB,EAChB,YAAY,EAGZ,MAAM,6BAA6B,CAAA;AAgBpC,MAAM,MAAM,kBAAkB,GAAG,gBAAgB,CAAA;AA+CjD,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAoFrH"}

package/out/tw/tools/fetch/gcis.js

@@ -0,0 +1,135 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Fetch Taiwan's company and business registers (公司登記資料, 商業登記資料) from the Ministry of
+ *   Economic Affairs' commerce open-data platform, data.gcis.nat.gov.tw. The platform publishes the
+ *   full registers as CSV files split by region (the six special municipalities each on their own,
+ *   the rest of the island in four bands) and by industry letter, 148 files in all, each row carrying
+ *   the registered address (公司地址) and, for companies, the tax office's business address
+ *   (營業地址) as free text. This is the NOISY source for Taiwanese addresses: a person typed these.
+ *
+ *   License: 政府資料開放授權條款－第1版 (Open Government Data License, Taiwan, v1.0). The platform's
+ *   own dialog states the condition that binds: attribution in the form it prescribes, or the grant is
+ *   void from the start ("未盡顯名標示義務者，視為自始未取得開放資料之授權"). The manifest records the
+ *   prescribed wording per file so the corpus build and the model card can carry it.
+ *
+ *   Invoke via `mailwoman corpus fetch gcis-tw --out-root <path>`.
+ */
+import { BYTES_PER_KIB } from "@mailwoman/core/fs/formatters";
+import { pathExists } from "@mailwoman/core/fs/readers";
+import { makeDirectories } from "@mailwoman/core/fs/writers";
+import { sha256File } from "@mailwoman/core/hash";
+import { sleep } from "@mailwoman/core/utils/sleep";
+import { join } from "path-ts";
+import { loadCollectionFiles, streamBodyToFile, withRetries, writeManifest } from "#tools/fetch/download/index";
+const SLUG = "gcis-tw";
+const PORTAL = "https://data.gcis.nat.gov.tw";
+const CATALOG_URL = `${PORTAL}/od/datacategory`;
+const LICENSE = "政府資料開放授權條款－第1版 (Open Government Data License, Taiwan, v1.0) — http://data.gov.tw/license";
+const ATTRIBUTION = "提供機關／經濟部商業發展署 [<dataset title>] — the 顯名聲明 each file's dialog prescribes";
+const PACE_MS = 300;
+/**
+ * The bulk register files: `<region><register>資料-<industry letter><industry>`. The per-industry API datasets and the
+ * monthly new-registration lists share the catalog and are not these.
+ */
+const BULK_TITLE = /(公司登記資料|商業登記資料)-[A-Z]/;
+/**
+ * A file name a shell and a manifest can carry: the title with its punctuation folded to underscores.
+ */
+function filenameFor(title) {
+    return `${title
+        .replaceAll(/[()（）、，/\\\s]+/g, "_")
+        .replaceAll(/_+/g, "_")
+        .replaceAll(/^_|_$/g, "")}.csv`;
+}
+async function listBulkDatasets() {
+    const res = await fetch(CATALOG_URL, { headers: { accept: "text/html" } });
+    if (!res.ok)
+        throw new Error(`gcis-tw: the catalog answered HTTP ${res.status}`);
+    const html = await res.text();
+    const datasets = [];
+    for (const [, path, rawTitle] of html.matchAll(/<a[^>]*href="(\/od\/detail[^"]*)"[^>]*>([^<]+)<\/a>/g)) {
+        const title = rawTitle?.trim();
+        if (!path || !title || !BULK_TITLE.test(title))
+            continue;
+        datasets.push({ title, detailPath: path.replace(/;jsessionid=[^?]*/, "") });
+    }
+    return datasets;
+}
+/**
+ * The `/od/file?oid=…` link a dataset's detail page hands its download dialog.
+ */
+async function fileURLFor(dataset) {
+    const res = await fetch(`${PORTAL}${dataset.detailPath}`, { headers: { accept: "text/html" } });
+    if (!res.ok)
+        return undefined;
+    const html = await res.text();
+    const path = /showDialog\('(\/od\/file\?oid=[^']+)'\)/.exec(html)?.[1];
+    return path ? `${PORTAL}${path}` : undefined;
+}
+export async function fetchGCISTW(options, report) {
+    const destDir = join(options.outRoot, SLUG);
+    await makeDirectories(destDir);
+    const manifestPath = join(destDir, "MANIFEST.json");
+    const datasets = await listBulkDatasets();
+    report?.(`=== ${SLUG}: ${datasets.length} bulk register files in the catalog`);
+    const previous = await loadCollectionFiles(manifestPath);
+    const files = new Map();
+    let fetched = 0;
+    let skipped = 0;
+    const failedCodes = [];
+    for (const dataset of datasets) {
+        const filename = filenameFor(dataset.title);
+        const dest = join(destDir, filename);
+        const before = previous.get(filename);
+        if (before && (await pathExists(dest))) {
+            files.set(filename, before);
+            skipped++;
+            continue;
+        }
+        await sleep(PACE_MS);
+        const url = await fileURLFor(dataset);
+        if (!url) {
+            report?.(`  ✗ no file link on the detail page for ${dataset.title}`);
+            failedCodes.push(dataset.title);
+            continue;
+        }
+        report?.(`--- ${dataset.title}`);
+        let bytes;
+        try {
+            bytes = await withRetries(async () => {
+                const res = await fetch(url, { headers: { accept: "*/*" }, signal: AbortSignal.timeout(1_800_000) });
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status} for ${dataset.title}`);
+                return streamBodyToFile(res, dest);
+            }, { report, label: dataset.title });
+        }
+        catch (error) {
+            report?.(`  ✗ ${error.message}`);
+            failedCodes.push(dataset.title);
+            continue;
+        }
+        if (bytes < BYTES_PER_KIB) {
+            report?.(`  ✗ ${bytes} bytes — an error page, not the register`);
+            failedCodes.push(dataset.title);
+            continue;
+        }
+        const sha = await sha256File(dest);
+        files.set(filename, { source_url: url, downloaded_at: new Date().toISOString(), filename, sha256: sha, bytes });
+        fetched++;
+        report?.(`  ✓ ${(bytes / 1024 / 1024).toFixed(1)} MB  sha256=${sha}`);
+        const manifest = {
+            source: SLUG,
+            source_url: CATALOG_URL,
+            license: LICENSE,
+            attribution: ATTRIBUTION,
+            downloaded_at: new Date().toISOString(),
+            files: [...files.values()],
+        };
+        await writeManifest(manifestPath, manifest);
+    }
+    return { fetched, skipped, failed: failedCodes.length, failedCodes };
+}
+//# sourceMappingURL=gcis.js.map

package/out/tw/tools/fetch/gcis.js.map

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

package/out/types.d.ts

@@ -15,7 +15,7 @@
  *   `CorpusAdapter` is the contract every data source implements; `AdapterOptions` is the
  *   per-invocation knob set (input path, optional country filter, row cap, abort signal).
  */
-import type { BIOLabel, ComponentTag } from "@mailwoman/core/types";
+import type { BIOLabel, ComponentTag } from "@mailwoman/codex/component";
 /**
  * Provenance + augmentation metadata that travels with every corpus row.
  *

package/out/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../lib/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEnE;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAChC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAA;IAEjB;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAA;IAEtB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC3B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAa,SAAQ,gBAAgB;IACrD;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IAEX;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAA;IAEjD;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IAEf;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;OAEG;IACH,KAAK,CAAC,EAAE,WAAW,CAAA;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAW,SAAQ,YAAY;IAC/C;;OAEG;IACH,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IAEzB;;OAEG;IACH,MAAM,EAAE,SAAS,QAAQ,EAAE,CAAA;IAE3B;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAE/B;;OAEG;IACH,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAE7B;;OAEG;IACH,SAAS,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;CACnC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,YAAY,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC9B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IAEjB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;CACpB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC7B;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IAEnB;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAE/B;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAE5B;;;;;;;;;;;;;;;OAeG;IACH,IAAI,CAAC,IAAI,EAAE,cAAc,GAAG,aAAa,CAAC,YAAY,CAAC,CAAA;CACvD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../lib/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAExE;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAChC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAA;IAEjB;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAA;IAEtB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC3B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAa,SAAQ,gBAAgB;IACrD;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IAEX;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAA;IAEjD;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IAEf;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;OAEG;IACH,KAAK,CAAC,EAAE,WAAW,CAAA;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAW,SAAQ,YAAY;IAC/C;;OAEG;IACH,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IAEzB;;OAEG;IACH,MAAM,EAAE,SAAS,QAAQ,EAAE,CAAA;IAE3B;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAE/B;;OAEG;IACH,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAE7B;;OAEG;IACH,SAAS,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;CACnC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,YAAY,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC9B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IAEjB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;CACpB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC7B;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IAEnB;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAE/B;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAE5B;;;;;;;;;;;;;;;OAeG;IACH,IAAI,CAAC,IAAI,EAAE,cAAc,GAAG,aAAa,CAAC,YAAY,CAAC,CAAA;CACvD"}

package/out/us/adapters/fcc-bdc/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../lib/us/adapters/fcc-bdc/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAOH,OAAO,KAAK,EAAgC,aAAa,EAAE,MAAM,QAAQ,CAAA;AAGzE;;;GAGG;AACH,eAAO,MAAM,kBAAkB,YAAY,CAAA;AAC3C;;;GAGG;AACH,eAAO,MAAM,uBAAuB,kBAAkB,CAAA;AActD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAWxE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CAwEnD;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,eAAwB,CAAA"}

package/out/us/adapters/fcc-bdc/adapter.js

@@ -0,0 +1,142 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `fcc-bdc`: FCC Broadband Data Collection (BDC) — Fabric-derived location consumer.
+ *
+ *   The first member of Phase 1.6's "adversarial sources" class. BDC ships the public-domain US
+ *   broadband-serviceable-location (BSL) fabric: ~120M addresses keyed by stable `location_id`,
+ *   carrying `address_primary` + `city` + `state` + `zip` + `zip_suffix`. Compared to the clean
+ *   gazetteer rows from WOF / TIGER / BAN, BDC carries the chaos of address data that has passed
+ *   through several layers of human entry + automated geocoding + revision: abbreviation drift,
+ *   inconsistent unit designators, "RR" / "HC" / "PSC" rural-route shapes, embedded apartment /
+ *   suite numbers that did not survive the address parser cleanly. This is the highest-signal,
+ *   hardest-to-normalize address corpus in the federal public-domain catalog.
+ *
+ *   Following the `tiger` / `wof-admin` pattern, this adapter consumes a SQLite database the operator
+ *   pre-builds via the isp-nexus BDC ETL (`/srv/isp-nexus/sync/fcc/bdc/`) or any equivalent
+ *   host-side pipeline. The mailwoman side does not download or parse the raw CSV/ZIP distribution
+ *   directly — that keeps the adapter narrow and the BDC ingest pluggable.
+ *
+ *   The SQLite schema is documented in README.md and modeled after `NTIARecord`
+ *   (`isp-nexus/fcc/bdc/data-collection.ts`): one row per `location_id`. The adapter splits
+ *   `address_primary` into `house_number` (leading numeric prefix, if any) + `street` (everything
+ *   after), and combines `zip` + `zip_suffix` into the canonical USPS `postcode` slot.
+ *
+ *   One CanonicalRow per fabric record. Unlike `tiger` (multiple postcode variants per segment) or
+ *   `wof-admin` (multiple hierarchy variants per place), BDC records already represent fully
+ *   specified addresses; no fan-out is warranted. Adversarial composition (Phase 1.6 §2.1) is the
+ *   mechanism for deriving multiple training rows per BDC record.
+ *
+ *   License: stamped `"Public Domain"` per the BDC fabric's US federal-government distribution terms.
+ *   The CostQuest Fabric source data has its own license; consumers who substitute that path should
+ *   re-stamp accordingly.
+ */
+import { formatAddressRow } from "@mailwoman/codex/address-format";
+import { DatabaseClient } from "@mailwoman/sqlite/client";
+import { splitStreetLine } from "#adapters/utils";
+import { lookupStateAbbreviation } from "#us/fips-state";
+/**
+ * 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 FCC_BDC_ADAPTER_ID = "fcc-bdc";
+/**
+ * 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 const FCC_BDC_DEFAULT_LICENSE = "Public Domain";
+/**
+ * Combine `zip` + optional `zip_suffix` into the canonical USPS postcode surface form.
+ *
+ * NTIARecord doc is ambiguous about whether `zip_suffix` is the 4-digit extension alone or the full ZIP+4 string. This
+ * handles both:
+ *
+ * - Bare 4-digit extension (`zip="94103"`, `zip_suffix="1234"`) → `"94103-1234"`
+ * - Already-joined form (`zip_suffix="94103-1234"`) → returned as-is
+ * - No suffix → bare `zip`
+ *
+ * Empty / whitespace-only suffix is treated as missing.
+ */
+export function buildPostcode(zip, suffix) {
+    const z = zip.trim();
+    if (!z)
+        return "";
+    const s = suffix?.trim() ?? "";
+    if (!s)
+        return z;
+    if (s.includes("-"))
+        return s;
+    return `${z}-${s}`;
+}
+/**
+ * Build a BDC adapter. Pure factory so multiple instances can be created in tests.
+ */
+export function createFccBdcAdapter() {
+    return {
+        id: FCC_BDC_ADAPTER_ID,
+        defaultLicense: FCC_BDC_DEFAULT_LICENSE,
+        description: "FCC Broadband Data Collection — Fabric-derived BSL addresses (public-domain); SQLite DB the operator builds via the isp-nexus BDC ETL.",
+        async *rows(opts) {
+            if (opts.country && opts.country !== "US") {
+                throw new Error(`fcc-bdc adapter: only US supported, got country=${opts.country}`);
+            }
+            const db = new DatabaseClient(opts.inputPath, { readOnly: true });
+            let emitted = 0;
+            try {
+                const stmt = db.prepare(`SELECT location_id, address_primary, city, state, zip, zip_suffix
+					 FROM bdc_locations
+					 ORDER BY location_id`);
+                for (const row of stmt.iterate()) {
+                    if (opts.signal?.aborted)
+                        return;
+                    if (opts.limit !== undefined && emitted >= opts.limit)
+                        return;
+                    const split = splitStreetLine(row.address_primary ?? "");
+                    if (!split)
+                        continue;
+                    const state = lookupStateAbbreviation(row.state);
+                    if (!state)
+                        continue;
+                    const locality = row.city?.trim();
+                    if (!locality)
+                        continue;
+                    const postcode = buildPostcode(row.zip ?? "", row.zip_suffix ?? null);
+                    if (!postcode)
+                        continue;
+                    const components = {
+                        ...(split.house_number ? { house_number: split.house_number } : {}),
+                        street: split.street,
+                        locality,
+                        region: state.abbreviation,
+                        postcode,
+                    };
+                    const rendered = formatAddressRow(components, "US", { singleLine: true });
+                    if (!rendered)
+                        continue;
+                    const { raw, components: aligned } = rendered;
+                    yield {
+                        raw,
+                        components: aligned,
+                        country: "US",
+                        locale: "en-US",
+                        source: FCC_BDC_ADAPTER_ID,
+                        source_id: `${FCC_BDC_ADAPTER_ID}-${row.location_id}`,
+                        corpus_version: "",
+                        license: FCC_BDC_DEFAULT_LICENSE,
+                    };
+                    emitted++;
+                }
+            }
+            finally {
+                await db.destroy();
+            }
+        },
+    };
+}
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const fccBdcAdapter = createFccBdcAdapter();
+//# sourceMappingURL=adapter.js.map

package/out/us/adapters/fcc-bdc/adapter.js.map

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

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

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

package/out/us/adapters/state/hi-schools/adapter.js

@@ -0,0 +1,136 @@
+/**
+ * @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 { formatAddressRow } from "@mailwoman/codex/address-format";
+import { CSVSpliterator, XLSXSpliterator } from "spliterator";
+import { splitStreetLine, stableSourceID } from "#adapters/utils";
+import { schoolCellText, STATE_HI_SCHOOL_SHEETS } from "#us/adapters/state/hi-schools/workbook";
+import { lookupStateAbbreviation } from "#us/fips-state";
+/**
+ * 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 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 const STATE_HI_SCHOOLS_DEFAULT_LICENSE = "Public Domain";
+const HI_STATE_ABBR = "HI";
+function normalizeZip(raw) {
+    const trimmed = schoolCellText(raw);
+    if (!trimmed)
+        return "";
+    // XLSX → CSV conversion may emit numeric ZIPs without leading zeros. HI ZIPs all begin
+    // with 96, so a 4-digit value indicates a leading-zero stripped during numeric coercion
+    // (defensive — has not been observed in the published file as of 2026-05).
+    if (/^\d{4}$/.test(trimmed))
+        return `0${trimmed}`;
+    return trimmed;
+}
+async function* readSchoolRows(inputPath) {
+    if (inputPath.toLowerCase().endsWith(".xlsx")) {
+        for (const sheet of STATE_HI_SCHOOL_SHEETS) {
+            yield* XLSXSpliterator.fromAsync(inputPath, {
+                sheet,
+                normalizeKeys: false,
+            });
+        }
+        return;
+    }
+    yield* CSVSpliterator.fromAsync(inputPath, {
+        normalizeKeys: false,
+    });
+}
+export function createStateHiSchoolsAdapter() {
+    return {
+        id: STATE_HI_SCHOOLS_ADAPTER_ID,
+        defaultLicense: STATE_HI_SCHOOLS_DEFAULT_LICENSE,
+        description: "Hawaii DOE School Directory — ~300 K-12 public + charter schools with venue+address (public-domain).",
+        async *rows(opts) {
+            if (opts.country && opts.country !== "US") {
+                throw new Error(`state-hi-schools adapter: only US supported, got country=${opts.country}`);
+            }
+            const state = lookupStateAbbreviation(HI_STATE_ABBR);
+            if (!state) {
+                throw new Error(`state-hi-schools adapter: HI not found in state codex (corpus bug)`);
+            }
+            let emitted = 0;
+            for await (const record of readSchoolRows(opts.inputPath)) {
+                if (opts.signal?.aborted)
+                    break;
+                if (opts.limit !== undefined && emitted >= opts.limit)
+                    break;
+                const name = schoolCellText(record.name);
+                const address = schoolCellText(record.address);
+                const city = schoolCellText(record.city);
+                const zip = normalizeZip(record.zip);
+                if (!name || !address || !city || !zip)
+                    continue;
+                const split = splitStreetLine(address);
+                if (!split)
+                    continue;
+                const components = {
+                    venue: name,
+                    ...(split.house_number ? { house_number: split.house_number } : {}),
+                    street: split.street,
+                    locality: city,
+                    region: state.abbreviation,
+                    postcode: zip,
+                };
+                const rendered = formatAddressRow(components, "US", { singleLine: true });
+                if (!rendered)
+                    continue;
+                const { raw, components: aligned } = rendered;
+                if (Object.keys(aligned).length <= 2)
+                    continue;
+                const code = schoolCellText(record.code);
+                const sourceID = code
+                    ? `${STATE_HI_SCHOOLS_ADAPTER_ID}-${code}`
+                    : stableSourceID(STATE_HI_SCHOOLS_ADAPTER_ID, aligned);
+                yield {
+                    raw,
+                    components: aligned,
+                    country: "US",
+                    locale: "en-US",
+                    source: STATE_HI_SCHOOLS_ADAPTER_ID,
+                    source_id: sourceID,
+                    corpus_version: "",
+                    license: STATE_HI_SCHOOLS_DEFAULT_LICENSE,
+                };
+                emitted++;
+            }
+        },
+    };
+}
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const stateHiSchoolsAdapter = createStateHiSchoolsAdapter();
+//# sourceMappingURL=adapter.js.map

package/out/us/adapters/state/hi-schools/adapter.js.map

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"workbook.d.ts","sourceRoot":"","sources":["../../../../../lib/us/adapters/state/hi-schools/workbook.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD;;GAEG;AACH,eAAO,MAAM,sBAAsB,YAAI,OAAO,EAAE,KAAK,CAAU,CAAA;AAE/D;;GAEG;AACH,eAAO,MAAM,gCAAgC,YAAI,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAU,CAAA;AAEnG;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,aAAa,GAAG,SAAS,CAAA;IAC/B,IAAI,EAAE,aAAa,GAAG,SAAS,CAAA;IAC/B,OAAO,EAAE,aAAa,GAAG,SAAS,CAAA;IAClC,IAAI,EAAE,aAAa,GAAG,SAAS,CAAA;IAC/B,GAAG,EAAE,aAAa,GAAG,SAAS,CAAA;CAC9B;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,GAAG,MAAM,CAEvE"}

package/out/us/adapters/state/hi-schools/workbook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workbook.js","sourceRoot":"","sources":["../../../../../lib/us/adapters/state/hi-schools/workbook.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,OAAO,EAAE,KAAK,CAAU,CAAA;AAE/D;;GAEG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAU,CAAA;AAanG;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,KAAgC;IAC9D,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAA;AACzE,CAAC"}

package/out/us/adapters/state/ia-contractors/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../../lib/us/adapters/state/ia-contractors/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH,OAAO,KAAK,EAAgC,aAAa,EAAE,MAAM,QAAQ,CAAA;AAGzE;;;GAGG;AACH,eAAO,MAAM,+BAA+B,yBAAyB,CAAA;AACrE;;;GAGG;AACH,eAAO,MAAM,oCAAoC,kBAAkB,CAAA;AAcnE,wBAAgB,+BAA+B,IAAI,aAAa,CAiF/D;AAED;;GAEG;AACH,eAAO,MAAM,yBAAyB,eAAoC,CAAA"}