@mailwoman/corpus 10.0.0 → 10.2.0

package/out/adapters/{synth-po-box → po-box}/adapter.js

@@ -3,50 +3,52 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `synth-po-box`: PO box / PMB / Apartado / BP synthesizer adapter.
+ * PO box / PMB / Apartado / BP synthesizer adapter. It emits {@linkcode PO_BOX_ADAPTER_ID}.
  *
- *   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.
+ * A PO box delivery line is mutually exclusive with a street line (USPS Pub 28 / DMM 508), so rows
+ * are generated fresh from a tuple rather than by mutating a street row.
  */
 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";
+import { stableSourceID } from "#adapters/source-id";
+import { defaultRecipeSource } from "#recipes/sources";
+import { poBoxTemplateLocale, REGION_OPTIONAL_LOCALES, synthesizeMilitaryPoBoxRow, synthesizePoBoxRow, } from "#synthesizers/po-box";
+import { AddressRole, SurfaceOrigin } 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.
+ * Registry id stamped into every row this adapter emits, so a corpus record traces back to its dataset.
+ *
+ * The value comes from `RECIPE_SOURCES` because `recipes/po/box/index.ts` writes rows under the same id.
+ * Two producers of one id have to spell it the same way, or a rewrite of a corpus through that table
+ * moves the recipe's rows and leaves this adapter's behind under a name the table no longer answers for.
  */
-export const SYNTH_PO_BOX_ADAPTER_ID = "synth-po-box";
+export const PO_BOX_ADAPTER_ID = defaultRecipeSource("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.
+ * License for synthetic PO-box rows.
+ *
+ * They inherit the terms of the real tuples used to derive them.
+ *
+ * The value is stored in each row's `license` column and read by `licenseNamedIn`,
+ * so it stays byte-for-byte.
  */
-export const SYNTH_PO_BOX_LICENSE = "Synthetic — derived from CC-BY / public-domain input tuples";
-export function createSynthPoBoxAdapter(opts = {}) {
+export const PO_BOX_LICENSE = "Synthetic — derived from CC-BY / public-domain input tuples";
+export function createPoBoxAdapter(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,
+        id: PO_BOX_ADAPTER_ID,
+        defaultLicense: PO_BOX_LICENSE,
+        addressRole: AddressRole.Mailing,
+        // No register asserts these boxes exist.
+        // The rows teach the shape of a post-office box line.
+        register: null,
+        surface: SurfaceOrigin.Invented,
         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.
+            // A non-throwing parse (the `skipped++` below) tolerates malformed rows,
+            // unlike `JSONSpliterator`, which would throw on the first bad line.
             const lines = TextSpliterator.fromAsync(options.inputPath);
             let emitted = 0;
             let skipped = 0;
@@ -60,14 +62,13 @@ export function createSynthPoBoxAdapter(opts = {}) {
                 if (!trimmed)
                     continue;
                 const input = tryParsingJSON(trimmed);
-                if (input === null) {
+                if (!input) {
                     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;
+                // Region is required except for region-less locales (NZ: `Private Bag 12, Auckland 1010` has
+                // no region token), where the guard must not discard the tuple as missing region.
+                const regionOptional = input.country ? REGION_OPTIONAL_LOCALES.has(poBoxTemplateLocale(input.country)) : false;
                 if (!input.locality || !input.postcode || !input.country || (!input.region && !regionOptional)) {
                     skipped++;
                     continue;
@@ -78,9 +79,9 @@ export function createSynthPoBoxAdapter(opts = {}) {
                     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, {
+                    // Include `v` in the locality slot to vary the digest across variants;
+                    // `stableSourceID` only accepts `ComponentTag` keys.
+                    const sourceID = stableSourceID(PO_BOX_ADAPTER_ID, {
                         locality: `${input.locality}#${v}`,
                         region: input.region,
                         postcode: input.postcode,
@@ -91,27 +92,27 @@ export function createSynthPoBoxAdapter(opts = {}) {
                         components: synth.components,
                         country: input.country,
                         locale: synth.locale,
-                        source: SYNTH_PO_BOX_ADAPTER_ID,
+                        source: PO_BOX_ADAPTER_ID,
                         source_id: sourceID,
                         corpus_version: "",
-                        license: SYNTH_PO_BOX_LICENSE,
+                        license: 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.
+                // US military/diplomatic rows are self-contained and off by default,
+                // so the default random stream and output stay byte-identical.
+                // They are US-only and count against `limit`. country-branch: APO/FPO/DPO
+                // rows exist in the US postal system only.
+                // A postal-regime flag in the codex would replace this.
                 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, {
+                    const sourceID = stableSourceID(PO_BOX_ADAPTER_ID, {
                         po_box: `${mil.components.po_box}#mil${militarySeq++}`,
                         locality: mil.components.locality,
                         region: mil.components.region,
@@ -122,10 +123,10 @@ export function createSynthPoBoxAdapter(opts = {}) {
                         components: mil.components,
                         country: "US",
                         locale: mil.locale,
-                        source: SYNTH_PO_BOX_ADAPTER_ID,
+                        source: PO_BOX_ADAPTER_ID,
                         source_id: sourceID,
                         corpus_version: "",
-                        license: SYNTH_PO_BOX_LICENSE,
+                        license: PO_BOX_LICENSE,
                     };
                     emitted++;
                 }
@@ -136,5 +137,5 @@ export function createSynthPoBoxAdapter(opts = {}) {
 /**
  * The configured adapter instance registered with the corpus builder.
  */
-export const synthPoBoxAdapter = createSynthPoBoxAdapter();
+export const poBoxAdapter = createPoBoxAdapter();
 //# sourceMappingURL=adapter.js.map

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

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

package/out/adapters/registry.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The lookup table that resolves an adapter id to its implementation.
+ *
+ * `mailwoman corpus run <adapter-id>` and the `corpus build` pipeline both resolve `<adapter-id>`
+ * through this registry. Adapters do not self-register at module load; `adapters.ts` adds each one
+ * explicitly, so the dependency graph stays traceable.
+ */
+import type { CorpusAdapter } from "#types";
+/**
+ * Lookup table for corpus adapters.
+ */
+export interface AdapterRegistry {
+    /**
+     * Add an adapter.
+     *
+     * @throws If `adapter.id` is already registered.
+     */
+    register(adapter: CorpusAdapter): void;
+    /**
+     * Return the adapter for `id`, or `null`.
+     */
+    get(id: string): CorpusAdapter | null;
+    /**
+     * All registered adapters, in insertion order.
+     */
+    list(): readonly CorpusAdapter[];
+    /**
+     * Convenience: ids only, in insertion order.
+     */
+    ids(): readonly string[];
+}
+/**
+ * Default in-memory registry.
+ *
+ * The runner constructs one per invocation.
+ * The CLI re-uses {@linkcode defaultAdapterRegistry}, which `adapters.ts` populates.
+ */
+export declare class InMemoryAdapterRegistry implements AdapterRegistry {
+    #private;
+    register(adapter: CorpusAdapter): void;
+    get(id: string): CorpusAdapter | null;
+    list(): readonly CorpusAdapter[];
+    ids(): readonly string[];
+}
+/**
+ * Process-wide default registry, populated by `adapters.ts`.
+ *
+ * A test constructs its own {@linkcode InMemoryAdapterRegistry} rather than mutating this one.
+ */
+export declare const defaultAdapterRegistry: InMemoryAdapterRegistry;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../lib/adapters/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AAE3C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAA;IAEtC;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAAA;IAErC;;OAEG;IACH,IAAI,IAAI,SAAS,aAAa,EAAE,CAAA;IAEhC;;OAEG;IACH,GAAG,IAAI,SAAS,MAAM,EAAE,CAAA;CACxB;AAED;;;;;GAKG;AACH,qBAAa,uBAAwB,YAAW,eAAe;;IAG9D,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAMrC;IAED,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAEpC;IAED,IAAI,IAAI,SAAS,aAAa,EAAE,CAE/B;IAED,GAAG,IAAI,SAAS,MAAM,EAAE,CAEvB;CACD;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,yBAAgC,CAAA"}

package/out/adapters/registry.js

@@ -0,0 +1,43 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The lookup table that resolves an adapter id to its implementation.
+ *
+ * `mailwoman corpus run <adapter-id>` and the `corpus build` pipeline both resolve `<adapter-id>`
+ * through this registry. Adapters do not self-register at module load; `adapters.ts` adds each one
+ * explicitly, so the dependency graph stays traceable.
+ */
+import { stringifyJSON } from "@mailwoman/core/json";
+/**
+ * Default in-memory registry.
+ *
+ * The runner constructs one per invocation.
+ * The CLI re-uses {@linkcode defaultAdapterRegistry}, which `adapters.ts` populates.
+ */
+export class InMemoryAdapterRegistry {
+    #byID = new Map();
+    register(adapter) {
+        if (this.#byID.has(adapter.id)) {
+            throw new Error(`AdapterRegistry: id ${stringifyJSON(adapter.id)} already registered`);
+        }
+        this.#byID.set(adapter.id, adapter);
+    }
+    get(id) {
+        return this.#byID.get(id) ?? null;
+    }
+    list() {
+        return Array.from(this.#byID.values());
+    }
+    ids() {
+        return Array.from(this.#byID.keys());
+    }
+}
+/**
+ * Process-wide default registry, populated by `adapters.ts`.
+ *
+ * A test constructs its own {@linkcode InMemoryAdapterRegistry} rather than mutating this one.
+ */
+export const defaultAdapterRegistry = new InMemoryAdapterRegistry();
+//# sourceMappingURL=registry.js.map

package/out/adapters/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../lib/adapters/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AA+BpD;;;;;GAKG;AACH,MAAM,OAAO,uBAAuB;IACnC,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAA;IAExC,QAAQ,CAAC,OAAsB;QAC9B,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CAAC,uBAAuB,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC,qBAAqB,CAAC,CAAA;QACvF,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA;IACpC,CAAC;IAED,GAAG,CAAC,EAAU;QACb,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,CAAA;IAClC,CAAC;IAED,IAAI;QACH,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAA;IACvC,CAAC;IAED,GAAG;QACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;IACrC,CAAC;CACD;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,uBAAuB,EAAE,CAAA"}

package/out/adapters/sha256-stream.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The incremental digest the runner records in `manifest.json`.
+ */
+/**
+ * A digest built from chunks rather than from one value.
+ *
+ * `@mailwoman/core/hash` covers one-shot digests with `sha256Hex` and whole-file digests with `sha256File`.
+ * The runner needs neither, because it hashes each jsonl line as it streams past
+ * and would otherwise read the file a second time for the manifest checksum.
+ */
+export interface StreamingHasher {
+    update(chunk: string | Uint8Array): void;
+    digest(): string;
+}
+/**
+ * A SHA-256 {@linkcode StreamingHasher} returning a hex digest.
+ *
+ * `digest()` is idempotent and `update()` after it throws, so a caller cannot
+ * extend a digest it has already recorded.
+ */
+export declare function streamingSha256(): StreamingHasher;
+//# sourceMappingURL=sha256-stream.d.ts.map

package/out/adapters/sha256-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sha256-stream.d.ts","sourceRoot":"","sources":["../../lib/adapters/sha256-stream.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC/B,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAA;IACxC,MAAM,IAAI,MAAM,CAAA;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,eAAe,CAoBjD"}

package/out/adapters/sha256-stream.js

@@ -0,0 +1,34 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The incremental digest the runner records in `manifest.json`.
+ */
+import { createHash } from "@mailwoman/core/hash";
+/**
+ * A SHA-256 {@linkcode StreamingHasher} returning a hex digest.
+ *
+ * `digest()` is idempotent and `update()` after it throws, so a caller cannot
+ * extend a digest it has already recorded.
+ */
+export function streamingSha256() {
+    const h = createHash("sha256");
+    let finalized = false;
+    let digestHex = "";
+    return {
+        update(chunk) {
+            if (finalized)
+                throw new Error("streamingSha256: update() called after digest()");
+            h.update(chunk);
+        },
+        digest() {
+            if (!finalized) {
+                digestHex = h.digest("hex");
+                finalized = true;
+            }
+            return digestHex;
+        },
+    };
+}
+//# sourceMappingURL=sha256-stream.js.map

package/out/adapters/sha256-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sha256-stream.js","sourceRoot":"","sources":["../../lib/adapters/sha256-stream.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAa,MAAM,sBAAsB,CAAA;AAc5D;;;;;GAKG;AACH,MAAM,UAAU,eAAe;IAC9B,MAAM,CAAC,GAAS,UAAU,CAAC,QAAQ,CAAC,CAAA;IACpC,IAAI,SAAS,GAAG,KAAK,CAAA;IACrB,IAAI,SAAS,GAAG,EAAE,CAAA;IAElB,OAAO;QACN,MAAM,CAAC,KAAK;YACX,IAAI,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAA;YAEjF,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAChB,CAAC;QACD,MAAM;YACL,IAAI,CAAC,SAAS,EAAE,CAAC;gBAChB,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;gBAC3B,SAAS,GAAG,IAAI,CAAA;YACjB,CAAC;YAED,OAAO,SAAS,CAAA;QACjB,CAAC;KACD,CAAA;AACF,CAAC"}

package/out/adapters/source-id.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The deterministic row id for a source that publishes no primary key of its own.
+ *
+ * A CSV row or GeoJSON feature often has no stable identifier. The runner still needs one, so
+ * deduplication and holdout manifests agree across reruns and a run can resume. These functions
+ * derive it by hashing the adapter id together with a canonical serialization of the row's values.
+ *
+ * The separator bytes are part of the hashed stream, so changing them changes every id in every
+ * built corpus.
+ */
+import type { ComponentTag } from "@mailwoman/codex/component";
+/**
+ * The deterministic content-addressed source id for a row, keyed by its components.
+ *
+ * The output is `<adapterID>-<first 12 hex characters of sha256>`.
+ * Twelve hex characters give 48 bits, about 17 million rows per adapter
+ * before the expected collision count passes 1.
+ * An adapter above that extends the prefix.
+ */
+export declare function stableSourceID(adapterID: string, components: Partial<Record<ComponentTag, string>>): string;
+/**
+ * {@linkcode stableSourceID} over arbitrary disambiguator keys, such as a variant index
+ * or a slot number that is not a `ComponentTag`.
+ *
+ * Both functions sort and hash every key handed in, so only the key vocabulary differs.
+ * The narrower signature above stops an adapter from hashing a misspelled component name.
+ */
+export declare function stableSourceIDFromParts(adapterID: string, parts: Readonly<Record<string, string | undefined>>): string;
+//# sourceMappingURL=source-id.d.ts.map

package/out/adapters/source-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-id.d.ts","sourceRoot":"","sources":["../../lib/adapters/source-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAG9D;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,GAAG,MAAM,CAE3G;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACtC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GACjD,MAAM,CAQR"}

package/out/adapters/source-id.js

@@ -0,0 +1,42 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The deterministic row id for a source that publishes no primary key of its own.
+ *
+ * A CSV row or GeoJSON feature often has no stable identifier. The runner still needs one, so
+ * deduplication and holdout manifests agree across reruns and a run can resume. These functions
+ * derive it by hashing the adapter id together with a canonical serialization of the row's values.
+ *
+ * The separator bytes are part of the hashed stream, so changing them changes every id in every
+ * built corpus.
+ */
+import { sha256Hex } from "@mailwoman/core/hash";
+/**
+ * The deterministic content-addressed source id for a row, keyed by its components.
+ *
+ * The output is `<adapterID>-<first 12 hex characters of sha256>`.
+ * Twelve hex characters give 48 bits, about 17 million rows per adapter
+ * before the expected collision count passes 1.
+ * An adapter above that extends the prefix.
+ */
+export function stableSourceID(adapterID, components) {
+    return stableSourceIDFromParts(adapterID, components);
+}
+/**
+ * {@linkcode stableSourceID} over arbitrary disambiguator keys, such as a variant index
+ * or a slot number that is not a `ComponentTag`.
+ *
+ * Both functions sort and hash every key handed in, so only the key vocabulary differs.
+ * The narrower signature above stops an adapter from hashing a misspelled component name.
+ */
+export function stableSourceIDFromParts(adapterID, parts) {
+    const sortedKeys = Object.keys(parts).toSorted();
+    const payload = sortedKeys.map((k) => `${k}=${parts[k] ?? ""}`).join("\u001F");
+    // One `update` over the joined string rather than three chained ones — identical byte stream
+    // either way, but the separator has to stay inline or every id in every built corpus changes.
+    const digest = sha256Hex(`${adapterID}\u001E${payload}`);
+    return `${adapterID}-${digest.slice(0, 12)}`;
+}
+//# sourceMappingURL=source-id.js.map

package/out/adapters/source-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-id.js","sourceRoot":"","sources":["../../lib/adapters/source-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAEhD;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB,EAAE,UAAiD;IAClG,OAAO,uBAAuB,CAAC,SAAS,EAAE,UAAU,CAAC,CAAA;AACtD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CACtC,SAAiB,EACjB,KAAmD;IAEnD,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAA;IAChD,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IAC9E,6FAA6F;IAC7F,8FAA8F;IAC9F,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,SAAS,OAAO,EAAE,CAAC,CAAA;IAExD,OAAO,GAAG,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAA;AAC7C,CAAC"}

package/out/adapters/street-line.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   This module reads a house number and a street out of the columns a publisher supplies.
+ *
+ * Publishers divide the same address two ways. Some write one street line that holds the number and
+ * the street together. {@linkcode splitStreetLine} separates that line for a number-first country and
+ * {@linkcode splitTrailingStreetLine} for a number-last one. Others write the number across
+ * two columns. {@linkcode composeHouseNumber} joins those. Every adapter facing either shape uses
+ * these, so an edge case fixed here is fixed for all of them.
+ *
+ * Which of the two split functions a country takes is `STREET_ORDERS` in
+ * `packages/mailwoman/tools/dev-tools/codex/street-orders.ts`, whose values reach the generated
+ * layouts `@mailwoman/codex/address/layouts` serves.
+ */
+/**
+ * A leading house number on a US-style street line contains digits and an optional hyphenated range
+ * (Queens `40-12`), an optional single alpha suffix (`101A`), then whitespace, then the rest.
+ *
+ * The remainder must stay `(\S.*)` and must not become `(.+)`: `\s+` and `.` both match a tab,
+ * so `\s+(.+)$` lets the engine split a run of tabs between the two groups every possible way
+ * before failing — quadratic backtracking on attacker-shaped input.
+ * The required non-space start removes the overlap.
+ *
+ * Group 2 is trimmed by the caller either way, so the two forms are indistinguishable on real input.
+ * Only the failure cost differs.
+ */
+export declare const HOUSE_NUMBER_PREFIX: RegExp;
+/**
+ * A street line split into its house number and the remainder.
+ */
+export interface SplitStreetLine {
+    house_number?: string;
+    street: string;
+}
+/**
+ * Split a US-style street line on {@link HOUSE_NUMBER_PREFIX}.
+ *
+ * The US CSV sources follow USPS Publication 28 conventions with hand-entry drift.
+ * The leading digit run is the house number (`"123 Main St"`, `"6450 W Indian School Rd"`),
+ * and the regex tolerates one trailing letter (`"123A Main St"`) plus an optional
+ * hyphenated half (`"40-12 Bell Blvd"`, common in NYC and suburban garden-apartment
+ * numbering. Hawaii uses it island-wide — `"47-470 Hui Aeko Place"`).
+ *
+ * @returns `null` for blank input.
+ * An input that does not match the prefix shape, including `"PO Box 1234"`,
+ * `"RR 2 Box 67"` and `"HC 1"`, becomes a single `street` value rather than being mangled,
+ * so the model sees the original surface form and downstream classifiers pick it up.
+ * A caller that needs those forms recognized as something other than a street
+ * (see `usgov-irs-bmf`) tests for them before calling this.
+ */
+export declare function splitStreetLine(line: string): SplitStreetLine | null;
+/**
+ * A trailing house number on a number-last street line contains digits,
+ * an optional single alpha suffix written against them (`39A`), and an optional slash-
+ * or hyphen-joined subdivision (`2/TER`, `16/18`, `12-B`).
+ *
+ * The street and the number are separated by whitespace, a comma, or both,
+ * because a publisher in a number-last country may write either: Italy's ANAC release
+ * holds `VIA INDIPENDENZA, 41` and `VIA MAZZINI 7` in the same column.
+ * The separator is required, so `VIA1` stays one street name.
+ *
+ * Group 1 starts at `\S` and the lazy `.*?` is bounded by that required separator,
+ * so a run of whitespace between the two groups has one split rather than every possible split.
+ * That is the same backtracking argument {@linkcode HOUSE_NUMBER_PREFIX} records, read from the other end.
+ */
+export declare const HOUSE_NUMBER_SUFFIX: RegExp;
+/**
+ * Split a number-last street line on {@link HOUSE_NUMBER_SUFFIX}.
+ *
+ * A number-last country writes the number after the street name.
+ * `STREET_ORDERS` records that order for Italy, Germany, Finland and 150 other jurisdictions.
+ *
+ * Whitespace inside the line is collapsed, and the separators inside a subdivided
+ * number are closed up, so `VIA PERUGIA 2 / A` yields `2/A`.
+ *
+ * @returns `null` for blank input.
+ * A line that ends in anything but a number becomes a single `street` value
+ * rather than being mangled, as `PIAZZA CASTELLO` and `VIALE ROMA SNC` do.
+ * A caller that treats an unplaced number inside such a line as a defect tests
+ * the returned `street` for a digit.
+ * This function leaves that decision to the caller, because a street name can legitimately hold a digit.
+ */
+export declare function splitTrailingStreetLine(line: string): SplitStreetLine | null;
+/**
+ * Joins a house number to the suffix a publisher stores in its own column.
+ *
+ * Several registers split a house number across two columns: BAN writes `10`
+ * and `bis`, Kartverket writes `12` and `B`.
+ * The separator differs per publisher, so the caller states it, and the two values are
+ * trimmed here because a publisher's padding is not part of the number.
+ *
+ * @param number The numeric part, from the publisher's number column.
+ * @param suffix The letter or word that follows it, from the publisher's suffix column.
+ * @param separator What to place between them.
+ * Kartverket joins `12` and `B` as `12B`; BAN joins `10` and `bis` as `10 bis`.
+ * @returns The joined number, or an empty string when the numeric part is absent.
+ * A caller treats the empty string as a row with no house number rather than assigning it.
+ */
+export declare function composeHouseNumber(number: string, suffix: string, separator?: string): string;
+//# sourceMappingURL=street-line.d.ts.map

package/out/adapters/street-line.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"street-line.d.ts","sourceRoot":"","sources":["../../lib/adapters/street-line.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,QAAuC,CAAA;AAEvE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAUpE;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,QAAkE,CAAA;AAElG;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAU5E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,SAAK,GAAG,MAAM,CAQzF"}