@mailwoman/corpus 3.0.0 → 4.0.0

package/out/src/synthesize-no-street.js

@@ -0,0 +1,279 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   No-street address synthesizer — the counter-distribution that v0.6.1's synth-street shard is
+ *   missing. Generates BIO-labelable rows where there is NO street, NO house_number, NO
+ *   street_prefix, NO street_suffix, NO intersection — only some subset of {venue, locality,
+ *   region, postcode, country}.
+ *
+ *   Rationale: the [2026-05-28 night-2
+ *   postmortem](../../docs/articles/evals/2026-05-28-night-2-postmortem.md) and the [layer-1
+ *   eval](../../docs/articles/evals/2026-05-28-layer-1-morphology-fst.md) showed that synth-street
+ *   pushed the model into a high-confidence "decompose mode" that leaked into `dependent_locality`.
+ *   Per DeepSeek's turn-2 recipe, the model needs explicit counter-examples: addresses where the
+ *   model should NOT emit street labels. This synthesizer is that source.
+ *
+ *   Six row templates, each producing a {raw, components} pair with no street-side tags:
+ *
+ *   1. **Plain venue + locality + region + postcode** `"Bob's Pizza, Boston, MA 02101"`
+ *   2. **Adversarial venue (containing street-typing words)** `"Wall Street Industries, NY 10005"`,
+ *        `"5th Avenue Theater, Seattle, WA"`, `"Highway 61 Diner, Memphis TN"`. These are the rows
+ *        that v0.6.1's decompose-mode would mis-tag as street_prefix/suffix; explicit negative
+ *        training kills that signal.
+ *   3. **Locality + region + postcode (minimal)** — `"Boston, MA 02101"`
+ *   4. **Locality + region** — `"Boston, MA"`
+ *   5. **Postcode-only** — `"02101"`
+ *   6. **Country-only** — `"United States"`, `"France"` (rare in real data, but the model has seen these
+ *        and should not hallucinate streets on them).
+ *
+ *   Output is a `CanonicalRow` with no street-side components. Alignment will produce BIO labels
+ *   where every token is one of {`B-venue`, `I-venue`, `B-locality`, `I-locality`, `B-region`,
+ *   `B-postcode`, `B-country`, `I-country`, `O`} — explicitly never any street tag. That IS the
+ *   counter-example signal the model is missing.
+ *
+ *   This complements (does not replace) the existing US-base-tuple source used by
+ *   `synthesize-po-box.ts`; the same `NoStreetBaseTuple` shape is consumed.
+ */
+// -------------------------------------------------------------------------------------------------
+// Venue name pools
+// -------------------------------------------------------------------------------------------------
+/**
+ * Plain venue names — businesses without street-typing words in the name. Used as the easy-mode
+ * positive class for venue detection.
+ */
+const PLAIN_VENUES = [
+    "Bob's Pizza",
+    "Acme Corporation",
+    "Joe's Diner",
+    "Sunrise Bakery",
+    "Maple Leaf Cafe",
+    "Riverside Garden Center",
+    "Tech Solutions Inc",
+    "Pacific Industries",
+    "Atlantic Holdings",
+    "Stellar Consulting",
+    "Greenfield Partners",
+    "Mountain View Studio",
+    "The Daily Grind",
+    "Sunset Bistro",
+    "Harvest Moon Florist",
+    "Iron Forge Brewing",
+    "Crescent City Bookstore",
+    "Lighthouse Insurance Group",
+    "Pinecrest Veterinary",
+    "Westwood Realty",
+];
+/**
+ * Adversarial venue names — businesses whose names contain street-typing tokens (Avenue, Street,
+ * Highway, Lane, Drive, Court, Plaza, Park, ...) but are themselves venues, not streets. The model
+ * must learn that these are venues despite the street-typing tokens.
+ *
+ * **No leading digit+ordinal venues** (e.g. "5th Avenue Theatre", "7th Street Bistro"). The v0.6.2
+ * 2026-05-29 step-20K eval showed that synthesized rows starting with `<digits><ordinal>` confused
+ * the model about house_number recognition — tokens like "5th" (which should be `B-house_number` in
+ * real addresses) were being labeled `B-venue` because adversarial venues placed them in venue
+ * position. v0.6.3 omits these patterns; the `synth-house-venue` shard separately teaches that
+ * house_number and venue coexist.
+ */
+const ADVERSARIAL_VENUES = [
+    "Wall Street Industries",
+    "Highway 61 Diner",
+    "Lane Bryant",
+    "Park Avenue Dental",
+    "Broadway Theatre Company",
+    "Madison Square Garden",
+    "Main Street Bakery",
+    "Sunset Boulevard Studios",
+    "Ocean Drive Cafe",
+    "Mountain Road Outfitters",
+    "Hollywood Boulevard Salon",
+    "East Bay Auto",
+    "West End Pharmacy",
+    "North Shore Insurance",
+    "South Park Children's Center",
+    "River Road Animal Hospital",
+    "Hill Street Blues Bar",
+    "Court House Square Realty",
+    "Plaza Hotel",
+    "Lincoln Park Zoo",
+    "Central Park Conservancy",
+    "Lakeshore Boulevard Apartments",
+    "Memorial Drive Medical Center",
+    "Wabash Avenue Press",
+    "State Street Bank",
+    "Market Street Grill",
+    "Beach Boulevard Diner",
+    "Garden Lane Florist",
+];
+// Compile-time guard: every venue must NOT start with the digit+ordinal pattern that
+// confuses house_number recognition. If a future contributor adds a "5th Avenue Theatre"-
+// style entry, this assertion will fire at module load time.
+for (const v of ADVERSARIAL_VENUES) {
+    if (/^\d+(st|nd|rd|th)\b/i.test(v)) {
+        throw new Error(`ADVERSARIAL_VENUES entry "${v}" starts with digit+ordinal; this pattern confuses ` +
+            `house_number recognition (see v0.6.3 eval doc). Use a non-numeric venue name.`);
+    }
+}
+const COUNTRY_NAMES = new Map([
+    ["US", ["United States", "USA", "U.S.A.", "United States of America"]],
+    ["FR", ["France"]],
+    ["DE", ["Germany", "Deutschland"]],
+    ["GB", ["United Kingdom", "UK", "Great Britain"]],
+    ["CA", ["Canada"]],
+    ["AU", ["Australia"]],
+]);
+// -------------------------------------------------------------------------------------------------
+// Synthesis
+// -------------------------------------------------------------------------------------------------
+function pick(arr, random) {
+    return arr[Math.floor(random() * arr.length)];
+}
+function countryToLocale(country) {
+    switch (country) {
+        case "US":
+            return "en-US";
+        case "CA":
+            return "en-CA";
+        case "GB":
+            return "en-GB";
+        case "AU":
+            return "en-AU";
+        case "FR":
+            return "fr-FR";
+        case "DE":
+            return "de-DE";
+        default:
+            return "en-US";
+    }
+}
+/**
+ * Generate one no-street counter-example row for a base (locality, region, postcode, country)
+ * tuple. Picks a template by weighted random; the venue templates are the load-bearing
+ * counter-distribution against synth-street's decompose-mode pressure.
+ */
+export function synthesizeNoStreetRow(base, opts = {}) {
+    const random = opts.random ?? Math.random;
+    const locale = countryToLocale(base.country);
+    const template = opts.forceTemplate ?? pickTemplate(random);
+    switch (template) {
+        case "venue-plain": {
+            const venue = pick(PLAIN_VENUES, random);
+            const raw = `${venue}, ${base.locality}, ${base.region} ${base.postcode}`;
+            return {
+                raw,
+                components: {
+                    venue,
+                    locality: base.locality,
+                    region: base.region,
+                    postcode: base.postcode,
+                },
+                locale,
+                template,
+            };
+        }
+        case "venue-adversarial": {
+            // The venue-adversarial template name is descriptive — when selected, this branch
+            // always draws from the adversarial pool. The `adversarialVenueRatio` opt is what
+            // the OUTER template picker uses to bias toward this template versus the plain one;
+            // once we're inside this branch the choice is already made.
+            const venue = pick(ADVERSARIAL_VENUES, random);
+            const raw = `${venue}, ${base.locality}, ${base.region} ${base.postcode}`;
+            return {
+                raw,
+                components: {
+                    venue,
+                    locality: base.locality,
+                    region: base.region,
+                    postcode: base.postcode,
+                },
+                locale,
+                template,
+            };
+        }
+        case "locality-region-postcode": {
+            const raw = `${base.locality}, ${base.region} ${base.postcode}`;
+            return {
+                raw,
+                components: {
+                    locality: base.locality,
+                    region: base.region,
+                    postcode: base.postcode,
+                },
+                locale,
+                template,
+            };
+        }
+        case "locality-region": {
+            const raw = `${base.locality}, ${base.region}`;
+            return {
+                raw,
+                components: {
+                    locality: base.locality,
+                    region: base.region,
+                },
+                locale,
+                template,
+            };
+        }
+        case "postcode-only": {
+            return {
+                raw: base.postcode,
+                components: { postcode: base.postcode },
+                locale,
+                template,
+            };
+        }
+        case "country-only": {
+            const names = COUNTRY_NAMES.get(base.country) ?? [base.country];
+            const country = pick(names, random);
+            return {
+                raw: country,
+                components: { country },
+                locale,
+                template,
+            };
+        }
+    }
+}
+/**
+ * Template weights chosen so that the venue-* templates dominate (they're the counter-example shape
+ * that matters), with the minimal templates as long-tail noise.
+ */
+function pickTemplate(random) {
+    const r = random();
+    if (r < 0.35)
+        return "venue-adversarial"; // 35% — the load-bearing slice
+    if (r < 0.6)
+        return "venue-plain"; // 25%
+    if (r < 0.8)
+        return "locality-region-postcode"; // 20%
+    if (r < 0.92)
+        return "locality-region"; // 12%
+    if (r < 0.98)
+        return "postcode-only"; // 6%
+    return "country-only"; // 2%
+}
+/**
+ * Convenience: assert at type-level that a synthesized row carries no street-side components. Used
+ * by tests + downstream consumers who want to verify the contract at runtime.
+ */
+export const STREET_SIDE_TAGS = [
+    "street",
+    "street_prefix",
+    "street_prefix_particle",
+    "street_suffix",
+    "house_number",
+    "intersection_a",
+    "intersection_b",
+    "unit",
+];
+export function hasAnyStreetSideTag(components) {
+    for (const t of STREET_SIDE_TAGS) {
+        if (components[t])
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=synthesize-no-street.js.map

package/out/src/synthesize-no-street.js.map

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

package/out/src/synthesize-po-box.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   PO box / PMB / Apartado / Boîte Postale synthesizer.
+ *
+ *   Generates BIO-labeled corpus rows where the delivery line is a PO box (mutually exclusive with
+ *   street + house_number per USPS Pub 28 / DMM 508). Locale-aware: emits idiomatic forms for
+ *   en-US, en-CA, en-GB, en-AU, fr-FR, fr-CA, es-ES, es-MX, es-AR.
+ *
+ *   Per-DeepSeek design:
+ *
+ *   - PMB ("Private Mailbox" — at CMRAs like UPS Store) shares the `po_box` tag with USPS PO Box.
+ *       Disambiguation is a downstream heuristic (presence of a street line).
+ *   - Whole-phrase span ("PO Box 123") not number-only ("123"). Matches existing golden eval.
+ *   - 10% of outputs receive number-format noise (commas, dashes, embedded spaces) to harden against
+ *       real-world OCR/transcription input.
+ *   - PO boxes drop street/house_number/unit/street_prefix/street_suffix from input components.
+ *
+ *   References:
+ *
+ *   - USPS Pub 28 §28C2.040 — Private Mailbox formatting
+ *   - USPS DMM 508 §4.1.4 / §4.5.4 — PO Box and street-addressed PO Box
+ */
+import type { CanonicalRow } from "./types.js";
+export interface PoBoxBaseTuple {
+    locality: string;
+    region: string;
+    postcode: string;
+    country: string;
+}
+/**
+ * Inject number-format noise into a box number string. Returns the noisy variant or the original
+ * (10% probability of noise per the design).
+ */
+export declare function maybeNoisifyBoxNumber(num: string, random: () => number): string;
+/**
+ * Compose a PO box phrase like "PO Box 123" or "PMB 200".
+ *
+ * Returns both the phrase and the canonical leader+number so the BIO aligner can mark the entire
+ * span as `po_box`.
+ */
+export declare function composePoBoxPhrase(leader: string, number: string): string;
+export interface SynthesizedPoBoxRow {
+    raw: string;
+    components: CanonicalRow["components"];
+    locale: string;
+    template: "po-box" | "pmb-with-street";
+}
+export interface PoBoxSynthesisOpts {
+    /** Random function — pass deterministic seed for tests. Default Math.random. */
+    random?: () => number;
+    /** Number generator. Default uniform over 1..99999. */
+    pickNumber?: (random: () => number) => string;
+    /** PMB probability when locale supports it (and a street is provided in the base tuple). */
+    pmbRatio?: number;
+}
+/**
+ * Generate one PO box row for a base (locality, region, postcode, country) tuple. Picks a
+ * locale-appropriate leader and number. Optionally generates a PMB variant when the base tuple
+ * includes a street.
+ */
+export declare function synthesizePoBoxRow(base: PoBoxBaseTuple & {
+    street?: string;
+    houseNumber?: string;
+}, opts?: PoBoxSynthesisOpts): SynthesizedPoBoxRow | null;
+/**
+ * Map a country code (ISO-3166-1 alpha-2 or alpha-3, or country display name) to the locale code we
+ * have a PO box template for.
+ */
+export declare function countryToLocale(country: string): string;
+/** All locales we synthesize for. Exposed for tests and for source-weight tuning. */
+export declare function supportedLocales(): ReadonlyArray<string>;
+//# sourceMappingURL=synthesize-po-box.d.ts.map

package/out/src/synthesize-po-box.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesize-po-box.d.ts","sourceRoot":"","sources":["../../src/synthesize-po-box.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,MAAM,WAAW,cAAc;IAC9B,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CACf;AAoDD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,MAAM,GAAG,MAAM,CAY/E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED,MAAM,WAAW,mBAAmB;IACnC,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,YAAY,CAAC,YAAY,CAAC,CAAA;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,QAAQ,GAAG,iBAAiB,CAAA;CACtC;AAED,MAAM,WAAW,kBAAkB;IAClC,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,MAAM,CAAA;IACrB,uDAAuD;IACvD,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,MAAM,KAAK,MAAM,CAAA;IAC7C,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAA;CACjB;AAWD;;;;GAIG;AACH,wBAAgB,kBAAkB,CACjC,IAAI,EAAE,cAAc,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EAChE,IAAI,GAAE,kBAAuB,GAC3B,mBAAmB,GAAG,IAAI,CAkD5B;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAWvD;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,IAAI,aAAa,CAAC,MAAM,CAAC,CAExD"}

package/out/src/synthesize-po-box.js

@@ -0,0 +1,186 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   PO box / PMB / Apartado / Boîte Postale synthesizer.
+ *
+ *   Generates BIO-labeled corpus rows where the delivery line is a PO box (mutually exclusive with
+ *   street + house_number per USPS Pub 28 / DMM 508). Locale-aware: emits idiomatic forms for
+ *   en-US, en-CA, en-GB, en-AU, fr-FR, fr-CA, es-ES, es-MX, es-AR.
+ *
+ *   Per-DeepSeek design:
+ *
+ *   - PMB ("Private Mailbox" — at CMRAs like UPS Store) shares the `po_box` tag with USPS PO Box.
+ *       Disambiguation is a downstream heuristic (presence of a street line).
+ *   - Whole-phrase span ("PO Box 123") not number-only ("123"). Matches existing golden eval.
+ *   - 10% of outputs receive number-format noise (commas, dashes, embedded spaces) to harden against
+ *       real-world OCR/transcription input.
+ *   - PO boxes drop street/house_number/unit/street_prefix/street_suffix from input components.
+ *
+ *   References:
+ *
+ *   - USPS Pub 28 §28C2.040 — Private Mailbox formatting
+ *   - USPS DMM 508 §4.1.4 / §4.5.4 — PO Box and street-addressed PO Box
+ */
+const LOCALE_TEMPLATES = [
+    {
+        locale: "en-US",
+        leaders: ["PO Box", "P.O. Box", "P.O.Box", "PO BOX", "POB", "Post Office Box", "Box"],
+        pmb: ["PMB", "#"],
+    },
+    {
+        locale: "en-CA",
+        leaders: ["PO Box", "P.O. Box", "POB", "Post Office Box"],
+        pmb: ["PMB", "#"],
+    },
+    {
+        locale: "en-GB",
+        leaders: ["PO Box", "P.O. Box", "Post Office Box"],
+    },
+    {
+        locale: "en-AU",
+        leaders: ["PO Box", "P.O. Box", "Post Office Box", "GPO Box", "Locked Bag"],
+    },
+    {
+        locale: "fr-FR",
+        leaders: ["BP", "B.P.", "Boîte Postale", "BP."],
+    },
+    {
+        locale: "fr-CA",
+        leaders: ["CP", "C.P.", "Case Postale", "BP", "B.P."],
+    },
+    {
+        locale: "es-ES",
+        leaders: ["Apdo.", "Apdo", "Apartado", "Apartado de Correos"],
+    },
+    {
+        locale: "es-MX",
+        leaders: ["Apdo.", "Apartado", "Apartado Postal", "AP"],
+    },
+    {
+        locale: "es-AR",
+        leaders: ["Casilla", "Casilla de Correo", "CC"],
+    },
+];
+const LEADERS_BY_LOCALE = new Map(LOCALE_TEMPLATES.map((t) => [t.locale, t]));
+/**
+ * Inject number-format noise into a box number string. Returns the noisy variant or the original
+ * (10% probability of noise per the design).
+ */
+export function maybeNoisifyBoxNumber(num, random) {
+    if (random() > 0.1)
+        return num;
+    const variants = [
+        // Thousand-separator comma (real input: "Box 1,234")
+        (s) => (s.length >= 4 ? `${s.slice(0, -3)},${s.slice(-3)}` : s),
+        // Embedded dash (real input: "PMB-200")
+        (s) => (s.length >= 3 ? `${s.slice(0, -2)}-${s.slice(-2)}` : s),
+        // Embedded spaces (real input from OCR: "1 2 3 4")
+        (s) => s.split("").join(" "),
+    ];
+    const f = variants[Math.floor(random() * variants.length)];
+    return f(num);
+}
+/**
+ * Compose a PO box phrase like "PO Box 123" or "PMB 200".
+ *
+ * Returns both the phrase and the canonical leader+number so the BIO aligner can mark the entire
+ * span as `po_box`.
+ */
+export function composePoBoxPhrase(leader, number) {
+    return `${leader} ${number}`;
+}
+function defaultPickNumber(random) {
+    // 70% of real PO boxes are 1-5 digits; long ones exist (USPS allows up to ~6 digits).
+    const r = random();
+    if (r < 0.3)
+        return String(1 + Math.floor(random() * 99)); // 1-99
+    if (r < 0.7)
+        return String(100 + Math.floor(random() * 900)); // 100-999
+    if (r < 0.95)
+        return String(1000 + Math.floor(random() * 9000)); // 1000-9999
+    return String(10000 + Math.floor(random() * 90000)); // 10000-99999
+}
+/**
+ * Generate one PO box row for a base (locality, region, postcode, country) tuple. Picks a
+ * locale-appropriate leader and number. Optionally generates a PMB variant when the base tuple
+ * includes a street.
+ */
+export function synthesizePoBoxRow(base, opts = {}) {
+    const random = opts.random ?? Math.random;
+    const pickNumber = opts.pickNumber ?? defaultPickNumber;
+    const pmbRatio = opts.pmbRatio ?? 0.0;
+    const locale = countryToLocale(base.country);
+    const tpl = LEADERS_BY_LOCALE.get(locale);
+    if (!tpl)
+        return null;
+    const number = maybeNoisifyBoxNumber(pickNumber(random), random);
+    const leader = tpl.leaders[Math.floor(random() * tpl.leaders.length)];
+    const poBoxPhrase = composePoBoxPhrase(leader, number);
+    // PMB variant: requires both a street and a PMB-supporting locale.
+    const wantPmb = base.street && tpl.pmb && random() < pmbRatio;
+    if (wantPmb) {
+        const pmbLeader = tpl.pmb[Math.floor(random() * tpl.pmb.length)];
+        const pmbPhrase = composePoBoxPhrase(pmbLeader, number);
+        const streetLine = base.houseNumber ? `${base.houseNumber} ${base.street}` : base.street;
+        const raw = `${streetLine}, ${pmbPhrase}, ${base.locality}, ${base.region} ${base.postcode}`;
+        return {
+            raw,
+            components: {
+                ...(base.houseNumber ? { house_number: base.houseNumber } : {}),
+                street: base.street,
+                po_box: pmbPhrase,
+                locality: base.locality,
+                region: base.region,
+                postcode: base.postcode,
+                country: base.country,
+            },
+            locale,
+            template: "pmb-with-street",
+        };
+    }
+    // Standard PO box: replaces the street line entirely.
+    const raw = `${poBoxPhrase}, ${base.locality}, ${base.region} ${base.postcode}`;
+    return {
+        raw,
+        components: {
+            po_box: poBoxPhrase,
+            locality: base.locality,
+            region: base.region,
+            postcode: base.postcode,
+            country: base.country,
+        },
+        locale,
+        template: "po-box",
+    };
+}
+/**
+ * Map a country code (ISO-3166-1 alpha-2 or alpha-3, or country display name) to the locale code we
+ * have a PO box template for.
+ */
+export function countryToLocale(country) {
+    const c = country.trim().toUpperCase();
+    if (c === "US" || c === "USA" || c === "UNITED STATES")
+        return "en-US";
+    if (c === "CA" || c === "CAN" || c === "CANADA")
+        return "en-CA";
+    if (c === "GB" || c === "UK" || c === "GBR" || c === "UNITED KINGDOM")
+        return "en-GB";
+    if (c === "AU" || c === "AUS" || c === "AUSTRALIA")
+        return "en-AU";
+    if (c === "FR" || c === "FRA" || c === "FRANCE")
+        return "fr-FR";
+    if (c === "ES" || c === "ESP" || c === "SPAIN")
+        return "es-ES";
+    if (c === "MX" || c === "MEX" || c === "MEXICO")
+        return "es-MX";
+    if (c === "AR" || c === "ARG" || c === "ARGENTINA")
+        return "es-AR";
+    return "en-US";
+}
+/** All locales we synthesize for. Exposed for tests and for source-weight tuning. */
+export function supportedLocales() {
+    return LOCALE_TEMPLATES.map((t) => t.locale);
+}
+//# sourceMappingURL=synthesize-po-box.js.map

package/out/src/synthesize-po-box.js.map

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

package/out/src/synthesize-street.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Street-decomposition synthesizer for Stage 3 training. Generates address rows where
+ *   `street_prefix`, `street`, and `street_suffix` are emitted as separate BIO spans (instead of
+ *   monolithic `street`). Mirrors the PO box synthesizer pattern.
+ *
+ *   Why this exists: TIGER/NAD/BAN adapter changes (committed earlier tonight) emit decomposed
+ *   components from raw source data, but the v0.4.0 parquet shards on Modal were built BEFORE those
+ *   changes. Rebuilding the full corpus requires downloading raw TIGER/NAD/BAN data and re-running
+ *   adapters end-to-end — out of scope for a single night shift. This synthesizer takes (locality,
+ *   region, postcode) tuples and produces freshly-decomposed Stage 3 training rows, same shape as
+ *   the PO box pipeline.
+ *
+ *   Note: uses the SAME decomposition logic as TIGER's `decomposeStreet()` so the synthetic
+ *   distribution matches what the model would see if/when TIGER shards are rebuilt with the new
+ *   adapter.
+ */
+import type { CanonicalRow } from "./types.js";
+export interface StreetBaseTuple {
+    locality: string;
+    region: string;
+    postcode: string;
+    country: string;
+}
+export interface SynthesizedStreetRow {
+    raw: string;
+    components: CanonicalRow["components"];
+    locale: string;
+}
+export interface StreetSynthesisOpts {
+    random?: () => number;
+    /** Probability of emitting house_number alongside the street. Default 0.85. */
+    includeHouseNumberProb?: number;
+    /**
+     * Probability of emitting the street BARE — no `, City, ST ZIP` tail and no region/locality/
+     * postcode components (just `street_prefix`/`street`/`street_suffix` + optional `house_number`).
+     * Default 0 (preserves the original full-address behavior exactly, including the RNG sequence).
+     * Set >0 to teach the model that a bare `10th Ave` / `Main St` is a STREET, not a locality — the
+     * functional-test failure cluster (bare streets mislabeled `locality`), the bare-format analogue of
+     * the v0.7.x intersection-bare fix.
+     */
+    bareProb?: number;
+}
+/**
+ * Synthesize a US street address with decomposed Stage 3 components. The street is built from
+ * PREFIX + NAME + SUFFIX, then passed through the same `decomposeStreet()` utility the TIGER
+ * adapter uses — guarantees the synthetic distribution matches the canonical decomposition logic.
+ */
+export declare function synthesizeStreetRow(base: StreetBaseTuple, opts?: StreetSynthesisOpts): SynthesizedStreetRow | null;
+//# sourceMappingURL=synthesize-street.d.ts.map

package/out/src/synthesize-street.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesize-street.d.ts","sourceRoot":"","sources":["../../src/synthesize-street.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAkI9C,MAAM,WAAW,eAAe;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,oBAAoB;IACpC,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,YAAY,CAAC,YAAY,CAAC,CAAA;IACtC,MAAM,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,mBAAmB;IACnC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAA;IACrB,+EAA+E;IAC/E,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CACjB;AAgBD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAClC,IAAI,EAAE,eAAe,EACrB,IAAI,GAAE,mBAAwB,GAC5B,oBAAoB,GAAG,IAAI,CAgD7B"}