/**
 * @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 "@mailwoman/corpus/types";
export interface PoBoxBaseTuple {
    locality: string;
    region: string;
    postcode: string;
    country: string;
}
export interface LocaleTemplate {
    locale: string;
    leaders: ReadonlyArray<string>;
    pmb?: ReadonlyArray<string>;
}
/**
 * The per-locale PO-box designator vocabulary (DeepSeek-signed list, see the header). Exported so shard builders
 * (scripts/build-po-box-cedex-shard.mjs) can reuse THIS list as the single source of truth for non-US leaders instead
 * of re-deriving it — the US slice additionally has `@mailwoman/codex/us` `US_PO_BOX_DESIGNATORS`/`isPOBox` as its
 * matcher-side truth.
 */
export declare const PO_BOX_LOCALE_TEMPLATES: ReadonlyArray<LocaleTemplate>;
/**
 * 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" | "military-po-box";
}
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;
/**
 * Generate one US military/diplomatic PO-box row (#517). Self-contained — draws no base tuple.
 */
export declare function synthesizeMilitaryPoBoxRow(opts?: PoBoxSynthesisOpts): SynthesizedPoBoxRow;
/**
 * 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>;
/**
 * Locales whose standard PO-box delivery line carries NO region token — the address reads `<po_box>, <locality>
 * <postcode>` with nothing between locality and postcode (#517). NZ is the canonical case (`Private Bag 12, Auckland
 * 1010`). Consumers (e.g. the synth-po-box adapter) use this to avoid discarding region-less input tuples for these
 * locales as "missing region".
 */
export declare const REGION_OPTIONAL_LOCALES: ReadonlySet<string>;
//# sourceMappingURL=po-box.d.ts.map