@mailwoman/corpus 9.1.0 → 9.3.0

package/out/adapters/state-ny-notaries/adapter.js

@@ -0,0 +1,119 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `state-ny-notaries`: New York Commissioned Notaries CSV consumer.
+ *
+ *   The New York Department of State publishes a registry of commissioned notaries public. Each row
+ *   optionally carries a business name and business address (~1-5% fill rate).
+ *
+ *   The adapter consumes the CSV the operator pre-downloads via `fetch-state-sources.ts`. Column
+ *   names match the data.ny.gov export header (note: some columns have leading spaces).
+ *
+ *   License: stamped `"Public Domain"` per New York state government open-data terms.
+ */
+import { isPresent } from "@mailwoman/core/objects";
+import { reconcileComponents } from "@mailwoman/formatter";
+import { CSVSpliterator } from "spliterator";
+import { splitStreetLine, stableSourceID } from "#adapters/utils";
+import { lookupStateAbbreviation } from "#codex/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_NY_NOTARIES_ADAPTER_ID = "state-ny-notaries";
+/**
+ * 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_NY_NOTARIES_DEFAULT_LICENSE = "Public Domain";
+export function createStateNyNotariesAdapter() {
+    return {
+        id: STATE_NY_NOTARIES_ADAPTER_ID,
+        defaultLicense: STATE_NY_NOTARIES_DEFAULT_LICENSE,
+        description: "New York Commissioned Notaries — name + optional business address (public-domain).",
+        async *rows(opts) {
+            if (opts.country && opts.country !== "US") {
+                throw new Error(`state-ny-notaries adapter: only US supported, got country=${opts.country}`);
+            }
+            const rows = CSVSpliterator.fromAsync(opts.inputPath, {
+                mode: "object",
+                normalizeKeys: false,
+                enableQuoteHandling: true,
+            });
+            let emitted = 0;
+            for await (const rawRecord of rows) {
+                if (opts.signal?.aborted)
+                    break;
+                if (opts.limit !== undefined && emitted >= opts.limit)
+                    break;
+                // NY CSV has columns with leading spaces, so we normalize by trimming keys.
+                const record = {};
+                for (const key of Object.keys(rawRecord)) {
+                    record[key.trim()] = rawRecord[key] ?? "";
+                }
+                const holderName = (record["Commission Holder Name"] ?? "").trim();
+                const businessName = (record["Business Name (if available)"] ?? "").trim();
+                const address1 = (record["Business Address 1 (if available)"] ?? "").trim();
+                const address2 = (record["Business Address 2 (if available)"] ?? "").trim();
+                const city = (record["Business City (if available)"] ?? "").trim();
+                const stateAbbr = (record["Business State (if available)"] ?? "").trim();
+                const zip = (record["Business Zip (if available)"] ?? "").trim();
+                const county = (record["Commissioned County"] ?? "").trim();
+                if (!city || !stateAbbr || !zip)
+                    continue;
+                if (!address1 && !address2)
+                    continue;
+                const state = lookupStateAbbreviation(stateAbbr);
+                if (!state)
+                    continue;
+                const fullAddress = [address1, address2].filter(isPresent).join(" ");
+                const split = splitStreetLine(fullAddress);
+                if (!split)
+                    continue;
+                const venue = businessName || holderName || undefined;
+                const components = {
+                    ...(venue ? { venue } : {}),
+                    ...(split.house_number ? { house_number: split.house_number } : {}),
+                    street: split.street,
+                    locality: city,
+                    region: state.abbreviation,
+                    postcode: zip,
+                    ...(county ? { subregion: county } : {}),
+                };
+                const streetPart = [split.house_number, split.street].filter(isPresent).join(" ").trim();
+                const raw = [
+                    venue,
+                    streetPart,
+                    [city, [stateAbbr, zip].filter(isPresent).join(" ")].filter(isPresent).join(", "),
+                ]
+                    .filter(isPresent)
+                    .join(", ");
+                const aligned = reconcileComponents(components, raw);
+                if (Object.keys(aligned).length <= 2)
+                    continue;
+                const commNum = (record["Commission Number (UID)"] ?? "").trim();
+                const sourceID = commNum
+                    ? `${STATE_NY_NOTARIES_ADAPTER_ID}-${commNum}`
+                    : stableSourceID(STATE_NY_NOTARIES_ADAPTER_ID, aligned);
+                yield {
+                    raw,
+                    components: aligned,
+                    country: "US",
+                    locale: "en-US",
+                    source: STATE_NY_NOTARIES_ADAPTER_ID,
+                    source_id: sourceID,
+                    corpus_version: "",
+                    license: STATE_NY_NOTARIES_DEFAULT_LICENSE,
+                };
+                emitted++;
+            }
+        },
+    };
+}
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const stateNyNotariesAdapter = createStateNyNotariesAdapter();
+//# sourceMappingURL=adapter.js.map

package/out/adapters/state-ny-notaries/adapter.js.map

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

package/out/adapters/state-tx-notaries/adapter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `state-tx-notaries`: Texas Notary Public Commissions CSV consumer.
+ *
+ *   The Texas Secretary of State publishes a registry of commissioned notaries public. Each row
+ *   optionally carries a mailing address in free-form text (often multi-line with embedded
+ *   city/state/zip). Address fill rate is ~5-10%.
+ *
+ *   The adapter parses the embedded `Address` field for city/state/zip using a trailing `"CITY, ST
+ *   ZIP"` pattern.
+ *
+ *   License: stamped `"Public Domain"` per Texas 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_TX_NOTARIES_ADAPTER_ID = "state-tx-notaries";
+/**
+ * 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_TX_NOTARIES_DEFAULT_LICENSE = "Public Domain";
+export declare function createStateTxNotariesAdapter(): CorpusAdapter;
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export declare const stateTxNotariesAdapter: CorpusAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/out/adapters/state-tx-notaries/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../lib/adapters/state-tx-notaries/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAQH,OAAO,KAAK,EAAgC,aAAa,EAAE,MAAM,QAAQ,CAAA;AAEzE;;;GAGG;AACH,eAAO,MAAM,4BAA4B,sBAAsB,CAAA;AAC/D;;;GAGG;AACH,eAAO,MAAM,iCAAiC,kBAAkB,CAAA;AAchE,wBAAgB,4BAA4B,IAAI,aAAa,CAuG5D;AAED;;GAEG;AACH,eAAO,MAAM,sBAAsB,eAAiC,CAAA"}

package/out/adapters/state-tx-notaries/adapter.js

@@ -0,0 +1,125 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `state-tx-notaries`: Texas Notary Public Commissions CSV consumer.
+ *
+ *   The Texas Secretary of State publishes a registry of commissioned notaries public. Each row
+ *   optionally carries a mailing address in free-form text (often multi-line with embedded
+ *   city/state/zip). Address fill rate is ~5-10%.
+ *
+ *   The adapter parses the embedded `Address` field for city/state/zip using a trailing `"CITY, ST
+ *   ZIP"` pattern.
+ *
+ *   License: stamped `"Public Domain"` per Texas state government open-data terms.
+ */
+import { isPresent } from "@mailwoman/core/objects";
+import { reconcileComponents } from "@mailwoman/formatter";
+import { CSVSpliterator } from "spliterator";
+import { splitStreetLine, stableSourceID } from "#adapters/utils";
+import { lookupStateAbbreviation } from "#codex/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_TX_NOTARIES_ADAPTER_ID = "state-tx-notaries";
+/**
+ * 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_TX_NOTARIES_DEFAULT_LICENSE = "Public Domain";
+/**
+ * Match trailing "CITY, ST ZIP" or "CITY, ST" at the end of an address line.
+ */
+const CITY_STATE_ZIP_SUFFIX = /[,]?\s*([^,]+),\s*([A-Z]{2})\s*(\d{5}(?:-\d{4})?)?\s*$/i;
+export function createStateTxNotariesAdapter() {
+    return {
+        id: STATE_TX_NOTARIES_ADAPTER_ID,
+        defaultLicense: STATE_TX_NOTARIES_DEFAULT_LICENSE,
+        description: "Texas Notary Public Commissions — name + mailing address with embedded city/state/zip (public-domain).",
+        async *rows(opts) {
+            if (opts.country && opts.country !== "US") {
+                throw new Error(`state-tx-notaries adapter: only US supported, got country=${opts.country}`);
+            }
+            const rows = CSVSpliterator.fromAsync(opts.inputPath, {
+                mode: "object",
+                normalizeKeys: false,
+                enableQuoteHandling: true,
+            });
+            let emitted = 0;
+            for await (const record of rows) {
+                if (opts.signal?.aborted)
+                    break;
+                if (opts.limit !== undefined && emitted >= opts.limit)
+                    break;
+                const rawAddress = (record.Address ?? "").trim();
+                if (!rawAddress)
+                    continue;
+                const firstName = (record["First Name"] ?? "").trim();
+                const lastName = (record["Last Name"] ?? "").trim();
+                const notaryID = (record["Notary ID"] ?? "").trim();
+                // Parse embedded city/state/zip from the trailing portion of the address.
+                // Addresses look like: "1215 MCMILLAN DR\nCEDAR HILL, TX 75104"
+                const addrSingleLine = rawAddress.replaceAll("\n", ", ");
+                const cszMatch = CITY_STATE_ZIP_SUFFIX.exec(addrSingleLine);
+                if (!cszMatch)
+                    continue;
+                const city = (cszMatch[1] ?? "").trim();
+                const stateAbbr = (cszMatch[2] ?? "").trim();
+                const zip = (cszMatch[3] ?? "").trim();
+                if (!city || !stateAbbr)
+                    continue;
+                const state = lookupStateAbbreviation(stateAbbr);
+                if (!state)
+                    continue;
+                // Extract the street portion (everything before the city/state/zip)
+                const streetPortion = addrSingleLine.slice(0, cszMatch.index).replace(/,\s*$/, "").trim();
+                if (!streetPortion)
+                    continue;
+                const split = splitStreetLine(streetPortion);
+                if (!split)
+                    continue;
+                const venue = [firstName, lastName].filter(isPresent).join(" ") || undefined;
+                const components = {
+                    ...(venue ? { venue } : {}),
+                    ...(split.house_number ? { house_number: split.house_number } : {}),
+                    street: split.street,
+                    locality: city,
+                    region: state.abbreviation,
+                    ...(zip ? { postcode: zip } : {}),
+                };
+                const streetPart = [split.house_number, split.street].filter(isPresent).join(" ").trim();
+                const raw = [
+                    venue,
+                    streetPart,
+                    [city, [stateAbbr, zip].filter(isPresent).join(" ")].filter(isPresent).join(", "),
+                ]
+                    .filter(isPresent)
+                    .join(", ");
+                const aligned = reconcileComponents(components, raw);
+                if (Object.keys(aligned).length <= 2)
+                    continue;
+                const sourceID = notaryID
+                    ? `${STATE_TX_NOTARIES_ADAPTER_ID}-${notaryID}`
+                    : stableSourceID(STATE_TX_NOTARIES_ADAPTER_ID, aligned);
+                yield {
+                    raw,
+                    components: aligned,
+                    country: "US",
+                    locale: "en-US",
+                    source: STATE_TX_NOTARIES_ADAPTER_ID,
+                    source_id: sourceID,
+                    corpus_version: "",
+                    license: STATE_TX_NOTARIES_DEFAULT_LICENSE,
+                };
+                emitted++;
+            }
+        },
+    };
+}
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const stateTxNotariesAdapter = createStateTxNotariesAdapter();
+//# sourceMappingURL=adapter.js.map

package/out/adapters/state-tx-notaries/adapter.js.map

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

package/out/adapters/synth-po-box/adapter.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `synth-po-box`: PO box / PMB / Apartado / BP synthesizer adapter.
+ *
+ *   Consumes a JSONL stream of (locality, region, postcode, country) tuples — typically extracted
+ *   from existing corpus output (TIGER/NAD/BAN/WOF) — and emits synthetic PO box training rows. See
+ *   `@mailwoman/corpus/synthesizers/po-box` for the per-locale templates and number-noise logic.
+ *
+ *   Why an adapter and not an augmenter:
+ *
+ *   - Per USPS Pub 28 / DMM 508, a PO box delivery line is mutually exclusive with a street line.
+ *       Synthesizing PO boxes by mutating a street row would teach the model an invalid pattern.
+ *       The clean shape is: read just (locality, region, postcode, country) and produce a fresh
+ *       PO-box-shaped row.
+ *   - Per-DeepSeek (3-turn consult, 2026-05-28): PMB rows that COMBINE a street line with a PMB number
+ *       ARE valid (CMRA addresses). Those are produced when `pmbRatio > 0` AND the input tuple
+ *       carries a `street` field.
+ */
+import { type PoBoxBaseTuple } from "#synthesizers/po-box";
+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 SYNTH_PO_BOX_ADAPTER_ID = "synth-po-box";
+/**
+ * License for the synthetic PO-box rows. The output is generated, but it inherits the terms of the real tuples it is
+ * derived from, so the attribution travels with it.
+ */
+export declare const SYNTH_PO_BOX_LICENSE = "Synthetic \u2014 derived from CC-BY / public-domain input tuples";
+export interface PoBoxInputRow extends PoBoxBaseTuple {
+    street?: string;
+    houseNumber?: string;
+}
+export interface SynthPoBoxAdapterOptions {
+    /**
+     * How many PO box variants to emit per input tuple. Each variant picks a different leader (and possibly a different
+     * number / noise level). Default 1.
+     */
+    variantsPerInput?: number;
+    /**
+     * Probability (0..1) of emitting a PMB-with-street variant when both the input has a street and the locale supports
+     * PMB. Default 0.15.
+     */
+    pmbRatio?: number;
+    /**
+     * Deterministic seed for reproducible synthesis. Default Date.now().
+     */
+    seed?: number;
+    /**
+     * Probability (0..1), evaluated per input tuple, of ALSO emitting one US military/diplomatic PO-box row
+     * (`PSC/CMR/Unit <id> Box <box>, APO/FPO/DPO AA/AE/AP <zip>`, #517). These rows are self-contained — they draw no
+     * field from the input tuple, so military volume scales with the input stream size. Default 0 (off) — the adapter's
+     * contract is "one row per input"; the corpus build recipe opts in to seed the rare-but-real military class without
+     * changing the default.
+     */
+    militaryRatio?: number;
+}
+export declare function createSynthPoBoxAdapter(opts?: SynthPoBoxAdapterOptions): CorpusAdapter;
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export declare const synthPoBoxAdapter: CorpusAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/out/adapters/synth-po-box/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../lib/adapters/synth-po-box/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAOH,OAAO,EAKN,KAAK,cAAc,EACnB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,KAAK,EAAgC,aAAa,EAAE,MAAM,QAAQ,CAAA;AAEzE;;;GAGG;AACH,eAAO,MAAM,uBAAuB,iBAAiB,CAAA;AACrD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,qEAAgE,CAAA;AAEjG,MAAM,WAAW,aAAc,SAAQ,cAAc;IACpD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,wBAAwB;IACxC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,wBAAgB,uBAAuB,CAAC,IAAI,GAAE,wBAA6B,GAAG,aAAa,CAyH1F;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,eAA4B,CAAA"}

package/out/adapters/synth-po-box/adapter.js

@@ -0,0 +1,140 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `synth-po-box`: PO box / PMB / Apartado / BP synthesizer adapter.
+ *
+ *   Consumes a JSONL stream of (locality, region, postcode, country) tuples — typically extracted
+ *   from existing corpus output (TIGER/NAD/BAN/WOF) — and emits synthetic PO box training rows. See
+ *   `@mailwoman/corpus/synthesizers/po-box` for the per-locale templates and number-noise logic.
+ *
+ *   Why an adapter and not an augmenter:
+ *
+ *   - Per USPS Pub 28 / DMM 508, a PO box delivery line is mutually exclusive with a street line.
+ *       Synthesizing PO boxes by mutating a street row would teach the model an invalid pattern.
+ *       The clean shape is: read just (locality, region, postcode, country) and produce a fresh
+ *       PO-box-shaped row.
+ *   - Per-DeepSeek (3-turn consult, 2026-05-28): PMB rows that COMBINE a street line with a PMB number
+ *       ARE valid (CMRA addresses). Those are produced when `pmbRatio > 0` AND the input tuple
+ *       carries a `street` field.
+ */
+import { tryParsingJSON } from "@mailwoman/core/json";
+import { makeLcg } from "@mailwoman/core/random";
+import { TextSpliterator } from "spliterator";
+import { stableSourceID } from "#adapters/utils";
+import { countryToLocale, REGION_OPTIONAL_LOCALES, synthesizeMilitaryPoBoxRow, synthesizePoBoxRow, } from "#synthesizers/po-box";
+/**
+ * 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 SYNTH_PO_BOX_ADAPTER_ID = "synth-po-box";
+/**
+ * License for the synthetic PO-box rows. The output is generated, but it inherits the terms of the real tuples it is
+ * derived from, so the attribution travels with it.
+ */
+export const SYNTH_PO_BOX_LICENSE = "Synthetic — derived from CC-BY / public-domain input tuples";
+export function createSynthPoBoxAdapter(opts = {}) {
+    const variantsPerInput = opts.variantsPerInput ?? 1;
+    const pmbRatio = opts.pmbRatio ?? 0.15;
+    const militaryRatio = opts.militaryRatio ?? 0;
+    return {
+        id: SYNTH_PO_BOX_ADAPTER_ID,
+        defaultLicense: SYNTH_PO_BOX_LICENSE,
+        description: "Synthetic PO box / PMB / Apartado / Boîte Postale rows. Consumes JSONL of (locality, region, postcode, country) tuples and emits locale-appropriate PO box variants.",
+        async *rows(options) {
+            const random = makeLcg(opts.seed ?? Date.now());
+            // TextSpliterator streams string lines; the per-line tryParsingJSON below keeps this reader
+            // tolerant of malformed rows (skipped++), so TextSpliterator + a non-throwing parse — not
+            // JSONSpliterator, which would throw on the first bad line.
+            const lines = TextSpliterator.fromAsync(options.inputPath);
+            let emitted = 0;
+            let skipped = 0;
+            let militarySeq = 0;
+            for await (const line of lines) {
+                if (options.signal?.aborted)
+                    break;
+                if (options.limit !== undefined && emitted >= options.limit)
+                    break;
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                const input = tryParsingJSON(trimmed);
+                if (input === null) {
+                    skipped++;
+                    continue;
+                }
+                // Region is required EXCEPT for region-less locales (NZ: `Private Bag 12, Auckland 1010`
+                // has no region token, #517). synthesizePoBoxRow handles region absence; the guard just
+                // must not discard those tuples as "missing region".
+                const regionOptional = input.country ? REGION_OPTIONAL_LOCALES.has(countryToLocale(input.country)) : false;
+                if (!input.locality || !input.postcode || !input.country || (!input.region && !regionOptional)) {
+                    skipped++;
+                    continue;
+                }
+                if (options.country && options.country !== input.country)
+                    continue;
+                for (let v = 0; v < variantsPerInput; v++) {
+                    const synth = synthesizePoBoxRow(input, { random, pmbRatio });
+                    if (!synth)
+                        continue;
+                    // Include `v` in dependent_locality slot to vary the digest across variants;
+                    // stableSourceID only accepts ComponentTag keys.
+                    const sourceID = stableSourceID(SYNTH_PO_BOX_ADAPTER_ID, {
+                        locality: `${input.locality}#${v}`,
+                        region: input.region,
+                        postcode: input.postcode,
+                        country: input.country,
+                    });
+                    yield {
+                        raw: synth.raw,
+                        components: synth.components,
+                        country: input.country,
+                        locale: synth.locale,
+                        source: SYNTH_PO_BOX_ADAPTER_ID,
+                        source_id: sourceID,
+                        corpus_version: "",
+                        license: SYNTH_PO_BOX_LICENSE,
+                    };
+                    emitted++;
+                    if (options.limit !== undefined && emitted >= options.limit)
+                        break;
+                }
+                // US military/diplomatic PO-box rows (#517): self-contained — draw nothing from the input
+                // tuple — emitted per input line with probability `militaryRatio` (off by default, so the
+                // default random stream and output are byte-identical). Military volume scales with the
+                // stream rather than the US-tuple count. US-only: suppressed under a non-US country filter
+                // and counted against `limit` like any other row.
+                const militaryAllowed = !options.country || options.country === "US";
+                if (militaryRatio > 0 &&
+                    militaryAllowed &&
+                    (options.limit === undefined || emitted < options.limit) &&
+                    random() < militaryRatio) {
+                    const mil = synthesizeMilitaryPoBoxRow({ random });
+                    const sourceID = stableSourceID(SYNTH_PO_BOX_ADAPTER_ID, {
+                        po_box: `${mil.components.po_box}#mil${militarySeq++}`,
+                        locality: mil.components.locality,
+                        region: mil.components.region,
+                        postcode: mil.components.postcode,
+                    });
+                    yield {
+                        raw: mil.raw,
+                        components: mil.components,
+                        country: "US",
+                        locale: mil.locale,
+                        source: SYNTH_PO_BOX_ADAPTER_ID,
+                        source_id: sourceID,
+                        corpus_version: "",
+                        license: SYNTH_PO_BOX_LICENSE,
+                    };
+                    emitted++;
+                }
+            }
+        },
+    };
+}
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const synthPoBoxAdapter = createSynthPoBoxAdapter();
+//# sourceMappingURL=adapter.js.map

package/out/adapters/synth-po-box/adapter.js.map

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

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

@@ -0,0 +1,55 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `tiger`: US Census TIGER/Line consumer adapter.
+ *
+ *   TIGER/Line is the canonical US street + locality dataset published by the Census Bureau as a
+ *   **public-domain** product (no ODbL share-alike concerns for US-only corpora). Coverage extends
+ *   to every named street segment + every incorporated place + CDP across the 50 states + DC + the
+ *   five primary territories — substantially better US street-name coverage than OSM, especially in
+ *   rural areas.
+ *
+ *   Following the `wof-admin` / `wof-postalcode` pattern, this adapter consumes a SQLite database the
+ *   operator pre-builds from the raw TIGER shapefiles (see the README for the schema and a
+ *   suggested `ogr2ogr` pipeline). The mailwoman side does not parse Shapefile binary directly —
+ *   keeping the adapter narrow lets the operator pick their own ingestion tool (ogr2ogr / shp2pgsql
+ *   / a custom Python script / etc.) without forcing a heavy native dep into `@mailwoman/corpus`.
+ *
+ *   Two row classes are emitted:
+ *
+ *   - **Street-level** (`tiger_streets`): one row per segment, optionally with up to two postcode
+ *       variants if `zipl` / `zipr` differ. Components: `{ street, region, postcode? }`. Streets
+ *       without a recognized state FIPS are dropped — there's no useful row without `region`.
+ *   - **Locality-level** (`tiger_places`): up to three variants per place: locality-only,
+ *       locality-with-region, locality-with-region-country (mirrors `wof-admin`'s fan-out for
+ *       consistency).
+ *   - `packages/corpus/lib/codex/us-fips-state.ts` — the FIPS → `{abbreviation, name}` lookup table
+ *       (originally `tiger/state.ts`, AGPL-3.0 → AGPL-3.0). The full isp-nexus TIGER module ships a
+ *       TypeORM-backed service layer; mailwoman only needs the lookup data so we don't carry the
+ *       service layer over.
+ *
+ *   License: stamped `"Public Domain"` per Census Bureau guidance on TIGER/Line. No per-row override
+ *   needed — every row in TIGER is the same license.
+ */
+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 TIGER_ADAPTER_ID = "tiger";
+/**
+ * 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 TIGER_DEFAULT_LICENSE = "Public Domain";
+/**
+ * Build a TIGER adapter. Pure factory so multiple instances can be created in tests.
+ */
+export declare function createTigerAdapter(): CorpusAdapter;
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export declare const tigerAdapter: CorpusAdapter;
+//# sourceMappingURL=adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../lib/adapters/tiger/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAQH,OAAO,KAAK,EAAgC,aAAa,EAAE,MAAM,QAAQ,CAAA;AAEzE;;;GAGG;AACH,eAAO,MAAM,gBAAgB,UAAU,CAAA;AACvC;;;GAGG;AACH,eAAO,MAAM,qBAAqB,kBAAkB,CAAA;AAiHpD;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,aAAa,CA6ElD;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,eAAuB,CAAA"}