@mailwoman/corpus 2.0.0

package/out/src/codex/us-street-suffix.d.ts

@@ -0,0 +1,259 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   USPS Publication 28, Appendix C — Postal Service Standard Suffix Abbreviations.
+ *
+ *   This module exposes the codex (the dataset itself) plus a small set of pure helpers used by the
+ *   synthesis layer's `us-street-suffix-abbreviate` / `us-street-suffix-expand` augmentations.
+ *
+ *   For each canonical suffix the value lists every recognized variant in USPS-published order; the
+ *   first variant is the preferred USPS abbreviation (e.g. `AVENUE → ["AVE", "AV", "AVEN", "AVENU",
+ *   "AVN", "AVNUE"]` — `AVE` is what the post office prints).
+ *
+ *   Salvaged 2026-05-17 from `isp-nexus/universe@6eeb7bd99643a6d62a8b8abbd50968a1e492b90b`
+ *   `mailwoman/postal/suffix.ts` (originally copyright OpenISP, Inc.; both projects are AGPL-3.0).
+ *   The dataset is verbatim; the helper API was reshaped to match mailwoman's synthesis registry
+ *   (the original isp-nexus `lookupStreetSuffix` was geared toward parsing, not augmentation).
+ * @see {@link https://pe.usps.com/text/pub28/28apc_002.htm USPS Street Suffix Abbreviations}
+ */
+/**
+ * Canonical USPS street suffix → list of recognized variants. The first variant in each list is the
+ * preferred USPS abbreviation. Keys + values are uppercase per the publication.
+ */
+export declare const US_STREET_SUFFIX_VARIANTS: {
+    readonly ALLEY: readonly ["ALY", "ALLEE", "ALLY"];
+    readonly ANEX: readonly ["ANX", "ANNEX", "ANNX"];
+    readonly ARCADE: readonly ["ARC"];
+    readonly AVENUE: readonly ["AVE", "AV", "AVEN", "AVENU", "AVN", "AVNUE"];
+    readonly BAYOU: readonly ["BYU", "BAYOO"];
+    readonly BEACH: readonly ["BCH"];
+    readonly BEND: readonly ["BND"];
+    readonly BLUFF: readonly ["BLF", "BLUF"];
+    readonly BLUFFS: readonly ["BLFS"];
+    readonly BOTTOM: readonly ["BTM", "BOT", "BOTTM"];
+    readonly BOULEVARD: readonly ["BLVD", "BOUL", "BOULV"];
+    readonly BRANCH: readonly ["BR", "BRNCH"];
+    readonly BRIDGE: readonly ["BRG", "BRDGE"];
+    readonly BROOK: readonly ["BRK"];
+    readonly BROOKS: readonly ["BRKS"];
+    readonly BURG: readonly ["BG"];
+    readonly BURGS: readonly ["BGS"];
+    readonly BYPASS: readonly ["BYP", "BYPA", "BYPAS", "BYPS"];
+    readonly CAMP: readonly ["CP", "CMP"];
+    readonly CANYON: readonly ["CYN", "CANYN", "CNYN"];
+    readonly CAPE: readonly ["CPE"];
+    readonly CAUSEWAY: readonly ["CSWY", "CAUSWA"];
+    readonly CENTER: readonly ["CTR", "CEN", "CENT", "CENTR", "CENTRE", "CNTER", "CNTR"];
+    readonly CENTERS: readonly ["CTRS"];
+    readonly CIRCLE: readonly ["CIR", "CIRC", "CIRCL", "CRCL", "CRCLE"];
+    readonly CIRCLES: readonly ["CIRS"];
+    readonly CLIFF: readonly ["CLF"];
+    readonly CLIFFS: readonly ["CLFS"];
+    readonly CLUB: readonly ["CLB"];
+    readonly COMMON: readonly ["CMN"];
+    readonly COMMONS: readonly ["CMNS"];
+    readonly CORNER: readonly ["COR"];
+    readonly CORNERS: readonly ["CORS"];
+    readonly COURSE: readonly ["CRSE"];
+    readonly COURT: readonly ["CT"];
+    readonly COURTS: readonly ["CTS"];
+    readonly COVE: readonly ["CV"];
+    readonly COVES: readonly ["CVS"];
+    readonly CREEK: readonly ["CRK"];
+    readonly CRESCENT: readonly ["CRES", "CRSENT", "CRSNT"];
+    readonly CREST: readonly ["CRST"];
+    readonly CROSSING: readonly ["XING", "CRSSNG"];
+    readonly CROSSROAD: readonly ["XRD"];
+    readonly CROSSROADS: readonly ["XRDS"];
+    readonly CURVE: readonly ["CURV"];
+    readonly DALE: readonly ["DL"];
+    readonly DAM: readonly ["DM"];
+    readonly DIVIDE: readonly ["DV", "DIV", "DVD"];
+    readonly DRIVE: readonly ["DR", "DRIV", "DRV"];
+    readonly DRIVES: readonly ["DRS"];
+    readonly ESTATE: readonly ["EST"];
+    readonly ESTATES: readonly ["ESTS"];
+    readonly EXPRESSWAY: readonly ["EXPY", "EXP", "EXPR", "EXPRESS", "EXPW"];
+    readonly EXTENSION: readonly ["EXT", "EXTN", "EXTNSN"];
+    readonly EXTENSIONS: readonly ["EXTS"];
+    readonly FALL: readonly ["FALL"];
+    readonly FALLS: readonly ["FLS"];
+    readonly FERRY: readonly ["FRY", "FRRY"];
+    readonly FIELD: readonly ["FLD"];
+    readonly FIELDS: readonly ["FLDS"];
+    readonly FLAT: readonly ["FLT"];
+    readonly FLATS: readonly ["FLTS"];
+    readonly FORD: readonly ["FRD"];
+    readonly FORDS: readonly ["FRDS"];
+    readonly FOREST: readonly ["FRST", "FORESTS"];
+    readonly FORGE: readonly ["FRG", "FORG"];
+    readonly FORGES: readonly ["FRGS"];
+    readonly FORK: readonly ["FRK"];
+    readonly FORKS: readonly ["FRKS"];
+    readonly FORT: readonly ["FT", "FRT"];
+    readonly FREEWAY: readonly ["FWY", "FREEWY", "FRWAY", "FRWY"];
+    readonly GARDEN: readonly ["GDN", "GARDN", "GRDEN", "GRDN"];
+    readonly GARDENS: readonly ["GDNS", "GRDNS"];
+    readonly GATEWAY: readonly ["GTWY", "GATEWY", "GATWAY", "GTWAY"];
+    readonly GLEN: readonly ["GLN"];
+    readonly GLENS: readonly ["GLNS"];
+    readonly GREEN: readonly ["GRN"];
+    readonly GREENS: readonly ["GRNS"];
+    readonly GROVE: readonly ["GRV", "GROV"];
+    readonly GROVES: readonly ["GRVS"];
+    readonly HARBOR: readonly ["HBR", "HARB", "HARBR", "HRBOR"];
+    readonly HARBORS: readonly ["HBRS"];
+    readonly HAVEN: readonly ["HVN"];
+    readonly HEIGHTS: readonly ["HTS", "HT"];
+    readonly HIGHWAY: readonly ["HWY", "HIGHWY", "HIWAY", "HIWY", "HWAY"];
+    readonly HILL: readonly ["HL"];
+    readonly HILLS: readonly ["HLS"];
+    readonly HOLLOW: readonly ["HOLW", "HLLW", "HOLLOWS", "HOLWS"];
+    readonly INLET: readonly ["INLT"];
+    readonly ISLAND: readonly ["IS", "ISLND"];
+    readonly ISLANDS: readonly ["ISS", "ISLNDS"];
+    readonly ISLE: readonly ["ISLE", "ISLES"];
+    readonly JUNCTION: readonly ["JCT", "JCTION", "JCTN", "JUNCTN", "JUNCTON"];
+    readonly JUNCTIONS: readonly ["JCTS", "JCTNS"];
+    readonly KEY: readonly ["KY"];
+    readonly KEYS: readonly ["KYS"];
+    readonly KNOLL: readonly ["KNL", "KNOL"];
+    readonly KNOLLS: readonly ["KNLS"];
+    readonly LAKE: readonly ["LK"];
+    readonly LAKES: readonly ["LKS"];
+    readonly LAND: readonly ["LAND"];
+    readonly LANDING: readonly ["LNDG", "LNDNG"];
+    readonly LANE: readonly ["LN"];
+    readonly LIGHT: readonly ["LGT"];
+    readonly LIGHTS: readonly ["LGTS"];
+    readonly LOAF: readonly ["LF"];
+    readonly LOCK: readonly ["LCK"];
+    readonly LOCKS: readonly ["LCKS"];
+    readonly LODGE: readonly ["LDG", "LDGE", "LODG"];
+    readonly LOOP: readonly ["LOOP", "LOOPS"];
+    readonly MALL: readonly ["MALL"];
+    readonly MANOR: readonly ["MNR"];
+    readonly MANORS: readonly ["MNRS"];
+    readonly MEADOW: readonly ["MDW"];
+    readonly MEADOWS: readonly ["MDWS", "MDW", "MEDOWS"];
+    readonly MEWS: readonly ["MEWS"];
+    readonly MILL: readonly ["ML"];
+    readonly MILLS: readonly ["MLS"];
+    readonly MISSION: readonly ["MSN", "MISSN", "MSSN"];
+    readonly MOTORWAY: readonly ["MTWY"];
+    readonly MOUNT: readonly ["MT", "MNT"];
+    readonly MOUNTAIN: readonly ["MTN", "MNTAIN", "MNTN", "MOUNTIN", "MTIN"];
+    readonly MOUNTAINS: readonly ["MTNS", "MNTNS"];
+    readonly NECK: readonly ["NCK"];
+    readonly ORCHARD: readonly ["ORCH", "ORCHRD"];
+    readonly OVAL: readonly ["OVAL", "OVL"];
+    readonly OVERPASS: readonly ["OPAS"];
+    readonly PARK: readonly ["PARK", "PRK", "PARKS"];
+    readonly PARKWAY: readonly ["PKWY", "PARKWY", "PKWAY", "PKY"];
+    readonly PARKWAYS: readonly ["PKWY", "PKWYS"];
+    readonly PASS: readonly ["PASS"];
+    readonly PASSAGE: readonly ["PSGE"];
+    readonly PATH: readonly ["PATH", "PATHS"];
+    readonly PIKE: readonly ["PIKE", "PIKES"];
+    readonly PINE: readonly ["PNE"];
+    readonly PINES: readonly ["PNES"];
+    readonly PLACE: readonly ["PL"];
+    readonly PLAIN: readonly ["PLN"];
+    readonly PLAINS: readonly ["PLNS"];
+    readonly PLAZA: readonly ["PLZ", "PLZA"];
+    readonly POINT: readonly ["PT"];
+    readonly POINTS: readonly ["PTS"];
+    readonly PORT: readonly ["PRT"];
+    readonly PORTS: readonly ["PRTS"];
+    readonly PRAIRIE: readonly ["PR", "PRR"];
+    readonly RADIAL: readonly ["RADL", "RAD", "RADIEL"];
+    readonly RAMP: readonly ["RAMP"];
+    readonly RANCH: readonly ["RNCH", "RANCHES", "RNCHS"];
+    readonly RAPID: readonly ["RPD"];
+    readonly RAPIDS: readonly ["RPDS"];
+    readonly REST: readonly ["RST"];
+    readonly RIDGE: readonly ["RDG", "RDGE"];
+    readonly RIDGES: readonly ["RDGS"];
+    readonly RIVER: readonly ["RIV", "RVR", "RIVR"];
+    readonly ROAD: readonly ["RD"];
+    readonly ROADS: readonly ["RDS"];
+    readonly ROUTE: readonly ["RTE"];
+    readonly ROW: readonly ["ROW"];
+    readonly RUE: readonly ["RUE"];
+    readonly RUN: readonly ["RUN"];
+    readonly SHOAL: readonly ["SHL"];
+    readonly SHOALS: readonly ["SHLS"];
+    readonly SHORE: readonly ["SHR", "SHOAR"];
+    readonly SHORES: readonly ["SHRS", "SHOARS"];
+    readonly SKYWAY: readonly ["SKWY"];
+    readonly SPRING: readonly ["SPG", "SPNG", "SPRNG"];
+    readonly SPRINGS: readonly ["SPGS", "SPNGS", "SPRNGS"];
+    readonly SPUR: readonly ["SPUR"];
+    readonly SPURS: readonly ["SPUR"];
+    readonly SQUARE: readonly ["SQ", "SQR", "SQRE", "SQU"];
+    readonly SQUARES: readonly ["SQS", "SQRS"];
+    readonly STATION: readonly ["STA", "STATN", "STN"];
+    readonly STRAVENUE: readonly ["STRA", "STRAV", "STRAVEN", "STRAVN", "STRVN", "STRVNUE"];
+    readonly STREAM: readonly ["STRM", "STREME"];
+    readonly STREET: readonly ["ST", "STRT", "STR"];
+    readonly STREETS: readonly ["STS"];
+    readonly SUMMIT: readonly ["SMT", "SUMIT", "SUMITT"];
+    readonly TERRACE: readonly ["TER", "TERR"];
+    readonly THROUGHWAY: readonly ["TRWY"];
+    readonly TRACE: readonly ["TRCE", "TRACES"];
+    readonly TRACK: readonly ["TRAK", "TRACKS", "TRK", "TRKS"];
+    readonly TRAFFICWAY: readonly ["TRFY"];
+    readonly TRAIL: readonly ["TRL", "TRAILS", "TRLS"];
+    readonly TRAILER: readonly ["TRLR", "TRLRS"];
+    readonly TUNNEL: readonly ["TUNL", "TUNEL", "TUNLS", "TUNNELS", "TUNNL"];
+    readonly TURNPIKE: readonly ["TPKE", "TRNPK", "TURNPK"];
+    readonly UNDERPASS: readonly ["UPAS"];
+    readonly UNION: readonly ["UN"];
+    readonly UNIONS: readonly ["UNS"];
+    readonly VALLEY: readonly ["VLY", "VALLY", "VLLY"];
+    readonly VALLEYS: readonly ["VLYS"];
+    readonly VIADUCT: readonly ["VIA", "VDCT", "VIADCT"];
+    readonly VIEW: readonly ["VW"];
+    readonly VIEWS: readonly ["VWS"];
+    readonly VILLAGE: readonly ["VLG", "VILL", "VILLAG", "VILLG", "VILLIAGE"];
+    readonly VILLAGES: readonly ["VLGS"];
+    readonly VILLE: readonly ["VL"];
+    readonly VISTA: readonly ["VIS", "VIST", "VST", "VSTA"];
+    readonly WALK: readonly ["WALK"];
+    readonly WALKS: readonly ["WALK"];
+    readonly WALL: readonly ["WALL"];
+    readonly WAY: readonly ["WAY", "WY"];
+    readonly WAYS: readonly ["WAYS"];
+    readonly WELL: readonly ["WL"];
+    readonly WELLS: readonly ["WLS"];
+};
+/** Canonical USPS suffix (full word, uppercase per the publication). */
+export type UsStreetSuffix = keyof typeof US_STREET_SUFFIX_VARIANTS;
+/**
+ * Inverse lookup: every variant abbreviation OR full canonical word → its canonical key.
+ *
+ * Built once at module load. `STREET` → `"STREET"`, `ST` → `"STREET"`, `STRT` → `"STREET"`, etc.
+ * Built lowercase-keyed for case-insensitive matching.
+ */
+export declare const US_STREET_SUFFIX_LOOKUP: ReadonlyMap<string, UsStreetSuffix>;
+/** Preferred USPS abbreviation per canonical (`AVENUE → "AVE"`, `STREET → "ST"`). */
+export declare const US_STREET_SUFFIX_PREFERRED_ABBR: Readonly<Record<UsStreetSuffix, string>>;
+/**
+ * Apply `target`'s letters in the same case-pattern as `reference`. Three patterns covered:
+ *
+ * - All-uppercase reference (`"AVE"`) → uppercase target (`"AVENUE"`).
+ * - All-lowercase reference (`"ave"`) → lowercase target (`"avenue"`).
+ * - Anything else (`"Ave"`, `"aVe"`) → title-case target (`"Avenue"`).
+ */
+export declare function matchCase(target: string, reference: string): string;
+/**
+ * If the last whitespace-separated word of `street` is a known USPS suffix variant, return the
+ * canonical key and the matched word. Returns null if the trailing word isn't a known suffix.
+ */
+export declare function matchTrailingSuffix(street: string): {
+    canonical: UsStreetSuffix;
+    matched: string;
+} | null;
+//# sourceMappingURL=us-street-suffix.d.ts.map

package/out/src/codex/us-street-suffix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"us-street-suffix.d.ts","sourceRoot":"","sources":["../../../src/codex/us-street-suffix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;GAGG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8MgB,CAAA;AAEtD,wEAAwE;AACxE,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,yBAAyB,CAAA;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAYpE,CAAA;AAEJ,qFAAqF;AACrF,eAAO,MAAM,+BAA+B,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAExC,CAAA;AAE7C;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAKnE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQzG"}

package/out/src/codex/us-street-suffix.js

@@ -0,0 +1,285 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   USPS Publication 28, Appendix C — Postal Service Standard Suffix Abbreviations.
+ *
+ *   This module exposes the codex (the dataset itself) plus a small set of pure helpers used by the
+ *   synthesis layer's `us-street-suffix-abbreviate` / `us-street-suffix-expand` augmentations.
+ *
+ *   For each canonical suffix the value lists every recognized variant in USPS-published order; the
+ *   first variant is the preferred USPS abbreviation (e.g. `AVENUE → ["AVE", "AV", "AVEN", "AVENU",
+ *   "AVN", "AVNUE"]` — `AVE` is what the post office prints).
+ *
+ *   Salvaged 2026-05-17 from `isp-nexus/universe@6eeb7bd99643a6d62a8b8abbd50968a1e492b90b`
+ *   `mailwoman/postal/suffix.ts` (originally copyright OpenISP, Inc.; both projects are AGPL-3.0).
+ *   The dataset is verbatim; the helper API was reshaped to match mailwoman's synthesis registry
+ *   (the original isp-nexus `lookupStreetSuffix` was geared toward parsing, not augmentation).
+ * @see {@link https://pe.usps.com/text/pub28/28apc_002.htm USPS Street Suffix Abbreviations}
+ */
+/**
+ * Canonical USPS street suffix → list of recognized variants. The first variant in each list is the
+ * preferred USPS abbreviation. Keys + values are uppercase per the publication.
+ */
+export const US_STREET_SUFFIX_VARIANTS = {
+    ALLEY: ["ALY", "ALLEE", "ALLY"],
+    ANEX: ["ANX", "ANNEX", "ANNX"],
+    ARCADE: ["ARC"],
+    AVENUE: ["AVE", "AV", "AVEN", "AVENU", "AVN", "AVNUE"],
+    BAYOU: ["BYU", "BAYOO"],
+    BEACH: ["BCH"],
+    BEND: ["BND"],
+    BLUFF: ["BLF", "BLUF"],
+    BLUFFS: ["BLFS"],
+    BOTTOM: ["BTM", "BOT", "BOTTM"],
+    BOULEVARD: ["BLVD", "BOUL", "BOULV"],
+    BRANCH: ["BR", "BRNCH"],
+    BRIDGE: ["BRG", "BRDGE"],
+    BROOK: ["BRK"],
+    BROOKS: ["BRKS"],
+    BURG: ["BG"],
+    BURGS: ["BGS"],
+    BYPASS: ["BYP", "BYPA", "BYPAS", "BYPS"],
+    CAMP: ["CP", "CMP"],
+    CANYON: ["CYN", "CANYN", "CNYN"],
+    CAPE: ["CPE"],
+    CAUSEWAY: ["CSWY", "CAUSWA"],
+    CENTER: ["CTR", "CEN", "CENT", "CENTR", "CENTRE", "CNTER", "CNTR"],
+    CENTERS: ["CTRS"],
+    CIRCLE: ["CIR", "CIRC", "CIRCL", "CRCL", "CRCLE"],
+    CIRCLES: ["CIRS"],
+    CLIFF: ["CLF"],
+    CLIFFS: ["CLFS"],
+    CLUB: ["CLB"],
+    COMMON: ["CMN"],
+    COMMONS: ["CMNS"],
+    CORNER: ["COR"],
+    CORNERS: ["CORS"],
+    COURSE: ["CRSE"],
+    COURT: ["CT"],
+    COURTS: ["CTS"],
+    COVE: ["CV"],
+    COVES: ["CVS"],
+    CREEK: ["CRK"],
+    CRESCENT: ["CRES", "CRSENT", "CRSNT"],
+    CREST: ["CRST"],
+    CROSSING: ["XING", "CRSSNG"],
+    CROSSROAD: ["XRD"],
+    CROSSROADS: ["XRDS"],
+    CURVE: ["CURV"],
+    DALE: ["DL"],
+    DAM: ["DM"],
+    DIVIDE: ["DV", "DIV", "DVD"],
+    DRIVE: ["DR", "DRIV", "DRV"],
+    DRIVES: ["DRS"],
+    ESTATE: ["EST"],
+    ESTATES: ["ESTS"],
+    EXPRESSWAY: ["EXPY", "EXP", "EXPR", "EXPRESS", "EXPW"],
+    EXTENSION: ["EXT", "EXTN", "EXTNSN"],
+    EXTENSIONS: ["EXTS"],
+    FALL: ["FALL"],
+    FALLS: ["FLS"],
+    FERRY: ["FRY", "FRRY"],
+    FIELD: ["FLD"],
+    FIELDS: ["FLDS"],
+    FLAT: ["FLT"],
+    FLATS: ["FLTS"],
+    FORD: ["FRD"],
+    FORDS: ["FRDS"],
+    FOREST: ["FRST", "FORESTS"],
+    FORGE: ["FRG", "FORG"],
+    FORGES: ["FRGS"],
+    FORK: ["FRK"],
+    FORKS: ["FRKS"],
+    FORT: ["FT", "FRT"],
+    FREEWAY: ["FWY", "FREEWY", "FRWAY", "FRWY"],
+    GARDEN: ["GDN", "GARDN", "GRDEN", "GRDN"],
+    GARDENS: ["GDNS", "GRDNS"],
+    GATEWAY: ["GTWY", "GATEWY", "GATWAY", "GTWAY"],
+    GLEN: ["GLN"],
+    GLENS: ["GLNS"],
+    GREEN: ["GRN"],
+    GREENS: ["GRNS"],
+    GROVE: ["GRV", "GROV"],
+    GROVES: ["GRVS"],
+    HARBOR: ["HBR", "HARB", "HARBR", "HRBOR"],
+    HARBORS: ["HBRS"],
+    HAVEN: ["HVN"],
+    HEIGHTS: ["HTS", "HT"],
+    HIGHWAY: ["HWY", "HIGHWY", "HIWAY", "HIWY", "HWAY"],
+    HILL: ["HL"],
+    HILLS: ["HLS"],
+    HOLLOW: ["HOLW", "HLLW", "HOLLOWS", "HOLWS"],
+    INLET: ["INLT"],
+    ISLAND: ["IS", "ISLND"],
+    ISLANDS: ["ISS", "ISLNDS"],
+    ISLE: ["ISLE", "ISLES"],
+    JUNCTION: ["JCT", "JCTION", "JCTN", "JUNCTN", "JUNCTON"],
+    JUNCTIONS: ["JCTS", "JCTNS"],
+    KEY: ["KY"],
+    KEYS: ["KYS"],
+    KNOLL: ["KNL", "KNOL"],
+    KNOLLS: ["KNLS"],
+    LAKE: ["LK"],
+    LAKES: ["LKS"],
+    LAND: ["LAND"],
+    LANDING: ["LNDG", "LNDNG"],
+    LANE: ["LN"],
+    LIGHT: ["LGT"],
+    LIGHTS: ["LGTS"],
+    LOAF: ["LF"],
+    LOCK: ["LCK"],
+    LOCKS: ["LCKS"],
+    LODGE: ["LDG", "LDGE", "LODG"],
+    LOOP: ["LOOP", "LOOPS"],
+    MALL: ["MALL"],
+    MANOR: ["MNR"],
+    MANORS: ["MNRS"],
+    MEADOW: ["MDW"],
+    MEADOWS: ["MDWS", "MDW", "MEDOWS"],
+    MEWS: ["MEWS"],
+    MILL: ["ML"],
+    MILLS: ["MLS"],
+    MISSION: ["MSN", "MISSN", "MSSN"],
+    MOTORWAY: ["MTWY"],
+    MOUNT: ["MT", "MNT"],
+    MOUNTAIN: ["MTN", "MNTAIN", "MNTN", "MOUNTIN", "MTIN"],
+    MOUNTAINS: ["MTNS", "MNTNS"],
+    NECK: ["NCK"],
+    ORCHARD: ["ORCH", "ORCHRD"],
+    OVAL: ["OVAL", "OVL"],
+    OVERPASS: ["OPAS"],
+    PARK: ["PARK", "PRK", "PARKS"],
+    PARKWAY: ["PKWY", "PARKWY", "PKWAY", "PKY"],
+    PARKWAYS: ["PKWY", "PKWYS"],
+    PASS: ["PASS"],
+    PASSAGE: ["PSGE"],
+    PATH: ["PATH", "PATHS"],
+    PIKE: ["PIKE", "PIKES"],
+    PINE: ["PNE"],
+    PINES: ["PNES"],
+    PLACE: ["PL"],
+    PLAIN: ["PLN"],
+    PLAINS: ["PLNS"],
+    PLAZA: ["PLZ", "PLZA"],
+    POINT: ["PT"],
+    POINTS: ["PTS"],
+    PORT: ["PRT"],
+    PORTS: ["PRTS"],
+    PRAIRIE: ["PR", "PRR"],
+    RADIAL: ["RADL", "RAD", "RADIEL"],
+    RAMP: ["RAMP"],
+    RANCH: ["RNCH", "RANCHES", "RNCHS"],
+    RAPID: ["RPD"],
+    RAPIDS: ["RPDS"],
+    REST: ["RST"],
+    RIDGE: ["RDG", "RDGE"],
+    RIDGES: ["RDGS"],
+    RIVER: ["RIV", "RVR", "RIVR"],
+    ROAD: ["RD"],
+    ROADS: ["RDS"],
+    ROUTE: ["RTE"],
+    ROW: ["ROW"],
+    RUE: ["RUE"],
+    RUN: ["RUN"],
+    SHOAL: ["SHL"],
+    SHOALS: ["SHLS"],
+    SHORE: ["SHR", "SHOAR"],
+    SHORES: ["SHRS", "SHOARS"],
+    SKYWAY: ["SKWY"],
+    SPRING: ["SPG", "SPNG", "SPRNG"],
+    SPRINGS: ["SPGS", "SPNGS", "SPRNGS"],
+    SPUR: ["SPUR"],
+    SPURS: ["SPUR"],
+    SQUARE: ["SQ", "SQR", "SQRE", "SQU"],
+    SQUARES: ["SQS", "SQRS"],
+    STATION: ["STA", "STATN", "STN"],
+    STRAVENUE: ["STRA", "STRAV", "STRAVEN", "STRAVN", "STRVN", "STRVNUE"],
+    STREAM: ["STRM", "STREME"],
+    STREET: ["ST", "STRT", "STR"],
+    STREETS: ["STS"],
+    SUMMIT: ["SMT", "SUMIT", "SUMITT"],
+    TERRACE: ["TER", "TERR"],
+    THROUGHWAY: ["TRWY"],
+    TRACE: ["TRCE", "TRACES"],
+    TRACK: ["TRAK", "TRACKS", "TRK", "TRKS"],
+    TRAFFICWAY: ["TRFY"],
+    TRAIL: ["TRL", "TRAILS", "TRLS"],
+    TRAILER: ["TRLR", "TRLRS"],
+    TUNNEL: ["TUNL", "TUNEL", "TUNLS", "TUNNELS", "TUNNL"],
+    TURNPIKE: ["TPKE", "TRNPK", "TURNPK"],
+    UNDERPASS: ["UPAS"],
+    UNION: ["UN"],
+    UNIONS: ["UNS"],
+    VALLEY: ["VLY", "VALLY", "VLLY"],
+    VALLEYS: ["VLYS"],
+    VIADUCT: ["VIA", "VDCT", "VIADCT"],
+    VIEW: ["VW"],
+    VIEWS: ["VWS"],
+    VILLAGE: ["VLG", "VILL", "VILLAG", "VILLG", "VILLIAGE"],
+    VILLAGES: ["VLGS"],
+    VILLE: ["VL"],
+    VISTA: ["VIS", "VIST", "VST", "VSTA"],
+    WALK: ["WALK"],
+    WALKS: ["WALK"],
+    WALL: ["WALL"],
+    WAY: ["WAY", "WY"],
+    WAYS: ["WAYS"],
+    WELL: ["WL"],
+    WELLS: ["WLS"],
+};
+/**
+ * Inverse lookup: every variant abbreviation OR full canonical word → its canonical key.
+ *
+ * Built once at module load. `STREET` → `"STREET"`, `ST` → `"STREET"`, `STRT` → `"STREET"`, etc.
+ * Built lowercase-keyed for case-insensitive matching.
+ */
+export const US_STREET_SUFFIX_LOOKUP = (() => {
+    const out = new Map();
+    for (const canonical of Object.keys(US_STREET_SUFFIX_VARIANTS)) {
+        out.set(canonical.toLowerCase(), canonical);
+        for (const variant of US_STREET_SUFFIX_VARIANTS[canonical]) {
+            // Don't overwrite — first canonical that claims a variant wins (matches USPS Pub-28's
+            // ordering). E.g. "WALK" and "WALKS" both list "WALK" as a variant; "WALK" wins because
+            // it sorts first in `Object.keys`.
+            if (!out.has(variant.toLowerCase()))
+                out.set(variant.toLowerCase(), canonical);
+        }
+    }
+    return out;
+})();
+/** Preferred USPS abbreviation per canonical (`AVENUE → "AVE"`, `STREET → "ST"`). */
+export const US_STREET_SUFFIX_PREFERRED_ABBR = Object.fromEntries(Object.keys(US_STREET_SUFFIX_VARIANTS).map((k) => [k, US_STREET_SUFFIX_VARIANTS[k][0]]));
+/**
+ * Apply `target`'s letters in the same case-pattern as `reference`. Three patterns covered:
+ *
+ * - All-uppercase reference (`"AVE"`) → uppercase target (`"AVENUE"`).
+ * - All-lowercase reference (`"ave"`) → lowercase target (`"avenue"`).
+ * - Anything else (`"Ave"`, `"aVe"`) → title-case target (`"Avenue"`).
+ */
+export function matchCase(target, reference) {
+    if (!reference)
+        return target;
+    if (reference === reference.toUpperCase())
+        return target.toUpperCase();
+    if (reference === reference.toLowerCase())
+        return target.toLowerCase();
+    return target.charAt(0).toUpperCase() + target.slice(1).toLowerCase();
+}
+/**
+ * If the last whitespace-separated word of `street` is a known USPS suffix variant, return the
+ * canonical key and the matched word. Returns null if the trailing word isn't a known suffix.
+ */
+export function matchTrailingSuffix(street) {
+    const trimmed = street.trim();
+    if (!trimmed)
+        return null;
+    const parts = trimmed.split(/\s+/);
+    const last = parts[parts.length - 1];
+    const canonical = US_STREET_SUFFIX_LOOKUP.get(last.toLowerCase());
+    if (!canonical)
+        return null;
+    return { canonical, matched: last };
+}
+//# sourceMappingURL=us-street-suffix.js.map

package/out/src/codex/us-street-suffix.js.map

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

package/out/src/format.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Render a `ComponentTag`-keyed dict into a country-localized string.
+ *
+ *   Phase 1's adapters carry ground-truth components but need a plausible `raw` string for the model
+ *   to learn from. This module bridges Mailwoman's `ComponentTag` schema to OpenCage's
+ *   `address-formatting` templates (vendored via `@fragaria/address-formatter`, MIT) so adapters
+ *   can synthesize idiomatic per-country output without each one reinventing the template logic.
+ *
+ *   `@fragaria/address-formatter` returns multi-line strings (newline-separated). This module honors
+ *   that by default and exposes a `separator` option to coerce to single-line when an adapter wants
+ *   `", "` joined output for the corpus.
+ *
+ *   Limitations (documented, not blockers for Phase 1):
+ *
+ *   - `unit`: OpenCage's vocabulary doesn't have a slot, so units are appended to the road line
+ *       (`"Pennsylvania Ave NW Apt 4B"`). Phase 2 or beyond can change this if needed.
+ *   - `intersection_a` / `intersection_b`: joined as `"<a> & <b>"` into the road field.
+ *   - `cedex` (FR): folded into `postcode` (e.g. `"75008 CEDEX 08"`) so the FR template renders it in
+ *       the right slot.
+ *   - JP-specific tags (`prefecture`, `municipality`, ...): no mapping yet — left for Phase 6 when JP
+ *       becomes a live locale.
+ */
+import type { ComponentTag } from "@mailwoman/core/types";
+/** Options accepted by `formatAddress`. */
+export interface FormatAddressOptions {
+    /**
+     * Append the country name as a final line (`"USA"`, `"France"`). Default `false`: most corpus
+     * rows are intra-country and the country prefix is redundant noise.
+     */
+    appendCountry?: boolean;
+    /**
+     * Apply OpenCage's per-country abbreviation rules (e.g. `"Avenue"` → `"Ave"`, `"Boulevard"` →
+     * `"Blvd"`). Default `false`. Phase 1 prefers unabbreviated output because synthesis
+     * (`synthesize.ts`) handles abbreviation swaps as its own augmentation pass.
+     */
+    abbreviate?: boolean;
+    /**
+     * Replace the template's newlines with this separator. Default `undefined` (keep newlines). Use
+     * `", "` to get a single-line output, or `" "` to remove all internal punctuation.
+     */
+    separator?: string;
+}
+type ComponentDict = Partial<Record<ComponentTag, string>>;
+/**
+ * After rendering, drop any component whose value isn't actually present in the formatted `raw`.
+ * OpenCage's per-country templates legitimately omit some inputs:
+ *
+ * - **FR**: regions are absorbed by the postcode and rarely render verbatim (`"75008 Paris, France"`
+ *   — `"Île-de-France"` is dropped).
+ * - **US**: state names are abbreviated (`"Oregon"` → `"OR"`); the verbatim form may not survive.
+ *
+ * Alignment downstream requires `components[tag]` to occur in `raw` (within fuzzy-match tolerance).
+ * If a component was dropped or transformed beyond Levenshtein reach, keeping it in the dict
+ * guarantees a quarantine reject. Reconciliation prunes the dropouts up front so the row arrives at
+ * alignment with a self-consistent (`raw`, `components`) pair.
+ *
+ * Comparison is case- and whitespace-insensitive. The retained value in `components` is the
+ * **original** input — alignment will fuzzy-match it against the raw character span.
+ */
+export declare function reconcileComponents(components: ComponentDict, raw: string): ComponentDict;
+/**
+ * Render a component dict into an idiomatic per-country address string.
+ *
+ * Returns an empty string if `components` is empty after translation. Throws nothing — bad inputs
+ * (empty dict, unsupported tag) silently degrade to the longest meaningful prefix.
+ */
+export declare function formatAddress(components: ComponentDict, country: string, opts?: FormatAddressOptions): string;
+/**
+ * Translate a `ComponentTag` dict to the OpenCage vocabulary that `@fragaria/address-formatter`
+ * expects. Exported for testing and for adapters that want to pre-build the dict for batch
+ * formatting.
+ */
+export declare function toOpenCageComponents(components: ComponentDict, country: string): Record<string, string>;
+export {};
+//# sourceMappingURL=format.d.ts.map

package/out/src/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEzD,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACpC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IAEvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IAEpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,KAAK,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAA;AAE1D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAWzF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,oBAAyB,GAAG,MAAM,CAWjH;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA8BvG"}