@mailwoman/codex 7.2.0 → 7.2.1

package/us/street-suffix.ts

@@ -0,0 +1,345 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   USPS Publication 28, Appendix C — Postal Service Standard Suffix Abbreviations.
+ *
+ *   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).
+ *
+ *   This module is the single home for the USPS suffix table. It carries both the synthesis-layer
+ *   helpers (`US_STREET_SUFFIX_PREFERRED_ABBR`, `matchCase`, `matchTrailingSuffix` — used by
+ *   `@mailwoman/corpus`) and the richer branded-type lookup (`StreetSuffix`, `lookupStreetSuffix`,
+ *   `isStreetSuffix`) The data is verbatim USPS Pub-28; the two APIs share one underlying record.
+ * @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"],
+} as const satisfies Record<string, readonly string[]>
+
+/** 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,
+ * lowercase-keyed for case-insensitive matching (`street` → `"STREET"`, `st` → `"STREET"`, `strt` → `"STREET"`, …).
+ */
+export const US_STREET_SUFFIX_LOOKUP: ReadonlyMap<string, USStreetSuffix> = (() => {
+	const out = new Map<string, USStreetSuffix>()
+
+	for (const canonical of Object.keys(US_STREET_SUFFIX_VARIANTS) as USStreetSuffix[]) {
+		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: Readonly<Record<USStreetSuffix, string>> = Object.fromEntries(
+	(Object.keys(US_STREET_SUFFIX_VARIANTS) as USStreetSuffix[]).map((k) => [k, US_STREET_SUFFIX_VARIANTS[k][0]])
+) as 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 function matchCase(target: string, reference: string): string {
+	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: string): { canonical: USStreetSuffix; matched: string } | null {
+	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 }
+}
+
+/**
+ * The USPS suffix record, under its original isp-nexus name. Aliases {@link US_STREET_SUFFIX_VARIANTS}.
+ */
+export const StreetSuffixAbbreviationRecord = US_STREET_SUFFIX_VARIANTS
+export type StreetSuffixAbbreviationRecord = typeof US_STREET_SUFFIX_VARIANTS
+
+/**
+ * A canonical USPS street suffix, i.e. "STREET", "AVENUE", "BOULEVARD". Aliases {@link USStreetSuffix}.
+ */
+export type StreetSuffix = USStreetSuffix
+
+/** A standardized USPS street suffix abbreviation (the preferred form), i.e. "ST", "AVE", "BLVD". */
+export type USPSStandardSuffixAbbreviation = StreetSuffixAbbreviationRecord[StreetSuffix][0]
+
+/** Any USPS-recognized suffix variant or abbreviation. */
+export type StreetSuffixAbbreviation = StreetSuffixAbbreviationRecord[StreetSuffix][number]
+
+/** Result of a successful USPS street suffix lookup. */
+export interface StreetSuffixMatch<S extends StreetSuffix = StreetSuffix> {
+	/** The matched canonical USPS street suffix, i.e. "STREET", "AVENUE". */
+	suffix: S
+	/** The preferred USPS street suffix abbreviation, i.e. "ST", "AVE". */
+	abbreviation: StreetSuffixAbbreviationRecord[S][0]
+}
+
+/**
+ * Look up a USPS street suffix (by canonical word, abbreviation, or any variant) and its preferred abbreviation.
+ */
+export function lookupStreetSuffix<S extends StreetSuffix>(suffix: S): StreetSuffixMatch<S>
+export function lookupStreetSuffix(input: string | null | undefined): StreetSuffixMatch | null
+export function lookupStreetSuffix(input: string | null | undefined): StreetSuffixMatch | null {
+	if (!input || typeof input !== "string") return null
+	const suffix = US_STREET_SUFFIX_LOOKUP.get(input.trim().toLowerCase())
+
+	if (!suffix) return null
+
+	return { suffix, abbreviation: US_STREET_SUFFIX_VARIANTS[suffix][0] }
+}
+
+/** Type-predicate: is the input a canonical USPS street suffix (uppercase full word, e.g. "STREET")? */
+export function isStreetSuffix(input: unknown): input is StreetSuffix {
+	return typeof input === "string" && Object.hasOwn(US_STREET_SUFFIX_VARIANTS, input)
+}
+
+/**
+ * True when a token is any USPS street suffix or abbreviation (case-insensitive) — `"St"`, `"BLVD"`, `"trail"`.
+ */
+export function isStreetSuffixToken(input: unknown): boolean {
+	return typeof input === "string" && US_STREET_SUFFIX_LOOKUP.has(input.trim().toLowerCase())
+}

package/us/unit-designator.ts

@@ -0,0 +1,223 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   USPS Publication 28, Appendix C2 — Secondary Unit Designators.
+ *
+ *   The sibling of {@link ./street-suffix.ts}: where that table standardizes the trailing street
+ *   _type_ (AVENUE → AVE), this one standardizes the _secondary unit_ designator that introduces an
+ *   apartment / suite / floor / room (APARTMENT → APT, SUITE → STE). For each canonical designator
+ *   the value lists recognized variants in USPS order; the first is the approved USPS abbreviation
+ *   (what the post office prints).
+ *
+ *   Used by `@mailwoman/corpus`'s synthesis layer (the `unit-{expand,abbreviate}` augmentations) to
+ *   vary the designator in a `unit` component while preserving the identifier — the data-generation
+ *   counterpart to the runtime `UnitDesignatorClassifier` (which matches the broader libpostal
+ *   `unit_types` lexicon). Designators are LEADING ("Apt 4B"), unlike street suffixes which trail.
+ *
+ *   `US_UNIT_DESIGNATOR_REQUIRES_RANGE` (added for #1100, the secondary-address epic; retrieved from
+ *   Appendix C2 2026-07-13) is Pub-28's own "Requires a Secondary Number" column: APT, BLDG, DEPT,
+ *   FL, HNGR, KEY, LOT, PIER, RM, SLIP, SPC, STOP, STE, TRLR, and UNIT must be followed by an
+ *   identifier ("Apt 4B", never bare "Apt"); BSMT, FRNT, LBBY, LOWR, OFC, PH, REAR, SIDE, and UPPR
+ *   may stand alone. This formalizes, as provenance-tracked reference data, the split that
+ *   `corpus/src/shard-recipes/unit.ts` previously hand-rolled (and only partially covered) as
+ *   in-file `ID_DESIGNATORS`/`STANDALONE_DESIGNATORS` arrays for synthesis weighting. A SEPARATE,
+ *   not-yet-built deliverable of #1100 is the per-locale *level-semantics* table (étage/RDC, EG/OG/UG,
+ *   planta/piso/bajo, piano/terra, 階/F/B1, …) — this module stays US/Pub-28 only.
+ *
+ *   Data is verbatim USPS Pub-28 C2.
+ * @see {@link https://pe.usps.com/text/pub28/28apc_003.htm USPS Secondary Unit Designators}
+ */
+
+/**
+ * Canonical USPS secondary unit designator → recognized variants. The first variant is the approved USPS abbreviation.
+ * Keys + values uppercase per the publication. The designators marked by USPS as "requires a secondary number" (APT,
+ * BLDG, FL, …) and the standalone ones (BSMT, LBBY, PH, …) are both included — synthesis treats them uniformly.
+ */
+export const US_UNIT_DESIGNATOR_VARIANTS = {
+	APARTMENT: ["APT", "APRT", "APMT"],
+	BASEMENT: ["BSMT"],
+	BUILDING: ["BLDG", "BLD"],
+	DEPARTMENT: ["DEPT"],
+	FLOOR: ["FL", "FLR"],
+	FRONT: ["FRNT"],
+	HANGAR: ["HNGR"],
+	KEY: ["KEY"],
+	LOBBY: ["LBBY"],
+	LOT: ["LOT"],
+	LOWER: ["LOWR"],
+	OFFICE: ["OFC"],
+	PENTHOUSE: ["PH"],
+	PIER: ["PIER"],
+	REAR: ["REAR"],
+	ROOM: ["RM"],
+	SIDE: ["SIDE"],
+	SLIP: ["SLIP"],
+	SPACE: ["SPC"],
+	STOP: ["STOP"],
+	SUITE: ["STE", "SUIT"],
+	TRAILER: ["TRLR"],
+	UNIT: ["UNIT"],
+	UPPER: ["UPPR"],
+} as const satisfies Record<string, readonly string[]>
+
+/** Canonical USPS secondary unit designator (full word, uppercase per the publication). */
+export type USUnitDesignator = keyof typeof US_UNIT_DESIGNATOR_VARIANTS
+
+/**
+ * Inverse lookup: every variant abbreviation OR full canonical word → its canonical key, built once at module load,
+ * lowercase-keyed for case-insensitive matching (`apt` → `"APARTMENT"`, `ste` → `"SUITE"`, `suite` → `"SUITE"`).
+ */
+export const US_UNIT_DESIGNATOR_LOOKUP: ReadonlyMap<string, USUnitDesignator> = (() => {
+	const out = new Map<string, USUnitDesignator>()
+
+	for (const canonical of Object.keys(US_UNIT_DESIGNATOR_VARIANTS) as USUnitDesignator[]) {
+		out.set(canonical.toLowerCase(), canonical)
+
+		for (const variant of US_UNIT_DESIGNATOR_VARIANTS[canonical]) {
+			// First canonical that claims a variant wins (matches the publication's ordering).
+			if (!out.has(variant.toLowerCase())) {
+				out.set(variant.toLowerCase(), canonical)
+			}
+		}
+	}
+
+	return out
+})()
+
+/** Approved USPS abbreviation per canonical (`APARTMENT → "APT"`, `SUITE → "STE"`). */
+export const US_UNIT_DESIGNATOR_PREFERRED_ABBR: Readonly<Record<USUnitDesignator, string>> = Object.fromEntries(
+	(Object.keys(US_UNIT_DESIGNATOR_VARIANTS) as USUnitDesignator[]).map((k) => [k, US_UNIT_DESIGNATOR_VARIANTS[k][0]])
+) as Readonly<Record<USUnitDesignator, string>>
+
+/**
+ * Canonical designators Appendix C2 marks as "Requires a Secondary Number" — the designator must be followed by an
+ * identifier ("Apt 4B", "Rm 12"), never appearing bare. The remaining designators (BASEMENT, FRONT, LOBBY, LOWER,
+ * OFFICE, PENTHOUSE, REAR, SIDE, UPPER) may stand alone with no trailing identifier. Verbatim from USPS Pub-28 C2; see
+ * the module header for provenance (#1100).
+ */
+export const US_UNIT_DESIGNATOR_REQUIRES_RANGE: Readonly<Record<USUnitDesignator, boolean>> = {
+	APARTMENT: true,
+	BASEMENT: false,
+	BUILDING: true,
+	DEPARTMENT: true,
+	FLOOR: true,
+	FRONT: false,
+	HANGAR: true,
+	KEY: true,
+	LOBBY: false,
+	LOT: true,
+	LOWER: false,
+	OFFICE: false,
+	PENTHOUSE: false,
+	PIER: true,
+	REAR: false,
+	ROOM: true,
+	SIDE: false,
+	SLIP: true,
+	SPACE: true,
+	STOP: true,
+	SUITE: true,
+	TRAILER: true,
+	UNIT: true,
+	UPPER: false,
+} as const satisfies Record<USUnitDesignator, boolean>
+
+/**
+ * If the FIRST whitespace-separated word of `unit` is a known USPS designator variant, return the canonical key and the
+ * matched word. Returns null if the leading word isn't a known designator (e.g. a bare `"4B"` or `"#210"`).
+ * Leading-word-only — designators introduce the unit, unlike street suffixes which trail.
+ */
+export function matchLeadingDesignator(unit: string): { canonical: USUnitDesignator; matched: string } | null {
+	const trimmed = unit.trim()
+
+	if (!trimmed) return null
+	const first = trimmed.split(/\s+/)[0]!
+	const canonical = US_UNIT_DESIGNATOR_LOOKUP.get(first.toLowerCase())
+
+	if (!canonical) return null
+
+	return { canonical, matched: first }
+}
+
+/** Result of {@link matchLeadingDesignatorWithRange}: the leading designator plus its optional secondary range. */
+export interface UnitDesignatorRangeMatch {
+	/** The matched canonical designator, i.e. "APARTMENT", "SUITE". */
+	canonical: USUnitDesignator
+	/** The designator's own matched surface form, i.e. "Apt". */
+	matched: string
+	/**
+	 * The secondary range/identifier token immediately following the designator, i.e. "4B" in "Apt 4B". Undefined when
+	 * the designator appears standalone (e.g. bare "Basement"). This module does not validate the range's own shape —
+	 * numeric, letter, or alphanumeric ranges are all USPS-valid.
+	 */
+	range: string | undefined
+	/**
+	 * Whether USPS Pub-28 Appendix C2 marks this designator as requiring a secondary range (see
+	 * {@link US_UNIT_DESIGNATOR_REQUIRES_RANGE}). Informational only — not enforced by this matcher.
+	 */
+	requiresRange: boolean
+}
+
+/**
+ * Like {@link matchLeadingDesignator}, but also captures the secondary range/identifier token immediately following the
+ * designator, if present ("Apt 4B" → designator "APARTMENT", range "4B"; "Basement" → range `undefined`). Mirrors
+ * `street-suffix`/`street-directional`'s designator+adjacent-token matchers.
+ */
+export function matchLeadingDesignatorWithRange(unit: string): UnitDesignatorRangeMatch | null {
+	const trimmed = unit.trim()
+
+	if (!trimmed) return null
+	const parts = trimmed.split(/\s+/)
+	const first = parts[0]!
+	const canonical = US_UNIT_DESIGNATOR_LOOKUP.get(first.toLowerCase())
+
+	if (!canonical) return null
+
+	return {
+		canonical,
+		matched: first,
+		range: parts[1],
+		requiresRange: US_UNIT_DESIGNATOR_REQUIRES_RANGE[canonical],
+	}
+}
+
+/** Result of a successful USPS secondary-unit designator lookup. */
+export interface UnitDesignatorMatch<D extends USUnitDesignator = USUnitDesignator> {
+	/** The matched canonical designator, i.e. "APARTMENT", "SUITE". */
+	designator: D
+	/** The approved USPS abbreviation, i.e. "APT", "STE". */
+	abbreviation: (typeof US_UNIT_DESIGNATOR_VARIANTS)[D][0]
+}
+
+/**
+ * Look up a USPS secondary unit designator (by canonical word, abbreviation, or any variant) and its approved
+ * abbreviation.
+ */
+export function lookupUnitDesignator<D extends USUnitDesignator>(designator: D): UnitDesignatorMatch<D>
+export function lookupUnitDesignator(input: string | null | undefined): UnitDesignatorMatch | null
+export function lookupUnitDesignator(input: string | null | undefined): UnitDesignatorMatch | null {
+	if (!input || typeof input !== "string") return null
+	const designator = US_UNIT_DESIGNATOR_LOOKUP.get(input.trim().toLowerCase())
+
+	if (!designator) return null
+
+	return { designator, abbreviation: US_UNIT_DESIGNATOR_VARIANTS[designator][0] }
+}
+
+/**
+ * True when a token is any USPS secondary unit designator or abbreviation (case-insensitive) — `"Apt"`, `"STE"`,
+ * `"floor"`.
+ */
+export function isUnitDesignatorToken(input: unknown): boolean {
+	return typeof input === "string" && US_UNIT_DESIGNATOR_LOOKUP.has(input.trim().toLowerCase())
+}
+
+/**
+ * Alias of {@link isUnitDesignatorToken} under Pub-28's own term ("secondary unit designator"). Added for #1100 so
+ * secondary-address call sites can spell the predicate after the publication's vocabulary.
+ */
+export function isSecondaryUnitDesignatorToken(input: unknown): boolean {
+	return isUnitDesignatorToken(input)
+}