@mailwoman/codex 7.2.0 → 7.2.1

package/us/military-address.ts

@@ -0,0 +1,199 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   USPS Publication 28 — Military / Diplomatic Post Office designators.
+ *
+ *   Military and diplomatic overseas addresses use a distinct addressing scheme: instead of a city
+ *   name, a standardized location-class code (APO, FPO, DPO) appears on the city line, followed by
+ *   the armed-forces "state" code (AA, AE, AP) and a 09xxx ZIP code. The unit/PSC/CMR line
+ *   appearing above the city line identifies the specific installation unit, postal service center,
+ *   or community mail room.
+ *
+ *   Sourcing (accessed 2026-06-12):
+ *
+ *   - **USPS Publication 28, Chapter 7** ("Armed Forces and Diplomatic Post Offices") defines the three
+ *       armed-forces location codes and three state-code regions, and states: "Use APO with AA
+ *       (Americas), AE (Europe/Middle East/Africa/Canada), or AP (Pacific)"; "FPO (Fleet Post
+ *       Office) for Navy ships and shore installations"; "DPO (Diplomatic Post Office) for US
+ *       embassies and missions." Full URL: https://pe.usps.com/text/pub28/28c7_001.htm
+ *   - **USPS Publication 28, Appendix B** gives the complete list of accepted unit-line formats: `UNIT
+ *       <id>`, `PSC <id> BOX <box>`, `CMR <id> BOX <box>`, and `UNIT <id> BOX <box>`. The same
+ *       appendix notes the two-digit unit ranges for PSC/CMR/UNIT assignment by theater. Full URL:
+ *       https://pe.usps.com/text/pub28/28apb_001.htm
+ *   - The **Armed Forces "state" codes** (AA, AE, AP) are defined in the same USPS appendix and are
+ *       also the official USPS abbreviations for the three Armed Forces addressing regions. See:
+ *       https://pe.usps.com/text/pub28/28apb_002.htm
+ *   - "DPO" for Diplomatic Post Offices was added as a distinct code in 2011 (USPS Customer/ Industry
+ *       Notice 61). It does NOT replace APO in diplomatic mail — both exist, with DPO used
+ *       specifically for State Department overseas posts and APO/FPO retained for DoD.
+ *
+ * @see {@link https://pe.usps.com/text/pub28/28c7_001.htm USPS Pub 28 Chapter 7 — Military Addresses}
+ * @see {@link https://pe.usps.com/text/pub28/28apb_001.htm USPS Pub 28 Appendix B — Armed Forces Addresses}
+ */
+
+/** USPS military / diplomatic post-office location codes (the "city" substitute on the city line). */
+export const US_MILITARY_POST_OFFICE_CODES = [
+	/**
+	 * Army Post Office — domestic USPS gateway for Army and Air Force overseas mail; also used for some diplomatic
+	 * addresses (DPO is preferred for State Dept posts since 2011).
+	 */
+	{ code: "APO", name: "Army Post Office", armedForces: true },
+	/** Fleet Post Office — Navy ships and shore installations. */
+	{ code: "FPO", name: "Fleet Post Office", armedForces: true },
+	/** Diplomatic Post Office — US embassies and missions (added 2011). */
+	{ code: "DPO", name: "Diplomatic Post Office", armedForces: false },
+] as const
+
+export type USMilitaryPostOfficeCode = (typeof US_MILITARY_POST_OFFICE_CODES)[number]["code"]
+
+/**
+ * USPS Armed Forces "state" codes used in place of state names on military/diplomatic addresses. These appear where a
+ * US state abbreviation (NY, CA, …) would appear in a civilian address.
+ */
+export const US_ARMED_FORCES_REGIONS = [
+	{ code: "AA", name: "Armed Forces Americas", description: "Americas (excluding Canada)" },
+	{ code: "AE", name: "Armed Forces Europe", description: "Europe, Middle East, Africa, and Canada" },
+	{ code: "AP", name: "Armed Forces Pacific", description: "Pacific" },
+] as const
+
+export type USArmedForcesRegionCode = (typeof US_ARMED_FORCES_REGIONS)[number]["code"]
+
+/**
+ * USPS Pub 28 Appendix B unit-line designators for military/diplomatic overseas addresses. Each designator introduces
+ * an installation identifier and optionally a box number.
+ *
+ * Format rules per Appendix B:
+ *
+ * - `PSC <id> BOX <box>` — Postal Service Center
+ * - `CMR <id> BOX <box>` — Community Mail Room
+ * - `UNIT <id> BOX <box>` — numbered unit (battalion/company); UNIT may stand alone with just an id and no BOX when the
+ *   unit has direct mail delivery
+ *
+ * BOX is required for PSC and CMR; UNIT may omit BOX.
+ */
+export const US_MILITARY_UNIT_DESIGNATORS = [
+	{
+		code: "PSC",
+		name: "Postal Service Center",
+		requiresBox: true,
+		description: "Installation-level postal service center; format: PSC <id> BOX <box>",
+	},
+	{
+		code: "CMR",
+		name: "Community Mail Room",
+		requiresBox: true,
+		description: "Sub-installation mail room; format: CMR <id> BOX <box>",
+	},
+	{
+		code: "UNIT",
+		name: "Unit",
+		requiresBox: false,
+		description: "Numbered military unit (battalion/company); format: UNIT <id> [BOX <box>]",
+	},
+] as const
+
+export type USMilitaryUnitDesignatorCode = (typeof US_MILITARY_UNIT_DESIGNATORS)[number]["code"]
+
+/** Result of a military address line parse (the unit line: PSC/CMR/UNIT). */
+export interface USMilitaryUnitMatch {
+	/** The designator as it appeared ("PSC", "CMR", "Unit"). */
+	matched: string
+	/** The canonical designator code ("PSC", "CMR", "UNIT"). */
+	code: USMilitaryUnitDesignatorCode
+	/** The installation identifier ("1520", "453"). */
+	id: string
+	/** The box number when present ("4620", "1234A"). */
+	box?: string
+}
+
+// Unit-line regex: PSC/CMR/UNIT <id> [BOX <box>]
+// Identifiers are numeric; box numbers are alphanumeric. UNIT may stand without BOX.
+const UNIT_LINE_RE = /^\s*(psc|cmr|unit)\s+(\d+)(?:\s+box\s+([\dA-Za-z]+))?\s*$/i
+
+/**
+ * If `input` is a USPS military unit-line ("PSC 1520 BOX 4620", "CMR 453 BOX 100", "UNIT 7 BOX 234A", "UNIT 7"), return
+ * the canonical designator, installation id, and optional box. Null otherwise. Throws on a PSC or CMR line without a
+ * BOX component (per Appendix B, BOX is required for PSC/CMR; a bare "PSC 1520" is malformed).
+ */
+export function matchMilitaryUnitLine(input: unknown): USMilitaryUnitMatch | null {
+	if (typeof input !== "string") return null
+	const m = UNIT_LINE_RE.exec(input)
+
+	if (!m) return null
+	const code = m[1]!.toUpperCase() as USMilitaryUnitDesignatorCode
+	const id = m[2]!
+	const box = m[3]
+
+	const row = US_MILITARY_UNIT_DESIGNATORS.find((r) => r.code === code)!
+
+	if (row.requiresBox && !box) {
+		throw new Error(
+			`[codex/us/military-address] ${code} line requires a BOX component per USPS Pub 28 Appendix B; got bare "${input.trim()}"`
+		)
+	}
+
+	return { matched: m[1]!, code, id, ...(box ? { box } : {}) }
+}
+
+/** Type-predicate: does the input look like a USPS military unit line (PSC/CMR/UNIT)? */
+export function isMilitaryUnitLine(input: unknown): boolean {
+	try {
+		return matchMilitaryUnitLine(input) !== null
+	} catch {
+		return false // PSC/CMR without BOX is structurally malformed (not a false negative)
+	}
+}
+
+/** Result of a military city-line parse (APO/FPO/DPO + region code + ZIP). */
+export interface USMilitaryCityMatch {
+	/** The post-office code as it appeared ("APO", "FPO", "DPO"). */
+	matched: string
+	/** The canonical post-office code. */
+	code: USMilitaryPostOfficeCode
+	/** The Armed Forces region code ("AA", "AE", "AP"). */
+	region: USArmedForcesRegionCode
+	/**
+	 * The 5-digit or 9-digit ZIP code. Typical ranges per Pub 28: 09xxx (AE), 34xxx (AA), 96xxx (AP) — range validation
+	 * per region is caller responsibility.
+	 */
+	zip: string
+}
+
+// City-line regex: APO/FPO/DPO <region> <zip>
+// USPS military ZIP assignment per Pub 28 and the Armed Forces zip code list:
+//   - AA (Americas): 340xx range
+//   - AE (Europe/ME/Africa/Canada): 09xxx range
+//   - AP (Pacific): 962xx-966xx range
+// The regex accepts any 5-digit or 9-digit ZIP code in combination with a valid region code —
+// validating the specific numeric range for each region is left to the caller (region+ZIP
+// co-validation is operational policy, not structural syntax).
+const CITY_LINE_RE = /^\s*(apo|fpo|dpo)\s+(aa|ae|ap)\s+(\d{5}(?:-\d{4})?)\s*$/i
+
+/**
+ * If `input` is a USPS military city line ("APO AE 09165", "FPO AP 96602-1254", "DPO AE 09498", "APO AA 34022", "APO AP
+ * 96525"), return the canonical code, region, and ZIP. Null otherwise.
+ *
+ * ZIP ranges per Pub 28: AE (Europe/ME/Africa/Canada) → 09xxx; AP (Pacific) → 96xxx; AA (Americas) → 34xxx. Range
+ * validation per region is left to the caller; the matcher accepts any 5. or 9-digit ZIP paired with a valid region
+ * code.
+ */
+export function matchMilitaryCityLine(input: unknown): USMilitaryCityMatch | null {
+	if (typeof input !== "string") return null
+	const m = CITY_LINE_RE.exec(input)
+
+	if (!m) return null
+
+	return {
+		matched: m[1]!.toUpperCase(),
+		code: m[1]!.toUpperCase() as USMilitaryPostOfficeCode,
+		region: m[2]!.toUpperCase() as USArmedForcesRegionCode,
+		zip: m[3]!,
+	}
+}
+
+/** Type-predicate: does the input look like a USPS military city line (APO/FPO/DPO + region + ZIP)? */
+export function isMilitaryCityLine(input: unknown): boolean {
+	return matchMilitaryCityLine(input) !== null
+}

package/us/po-box.ts

@@ -0,0 +1,82 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   USPS PO Box recognition + normalization to the surface forms that actually occur
+ *   (case-insensitive, punctuated "P.O. Box", spelled-out "Post Office Box", bare "Box"). A PO box
+ *   isn't a closed vocabulary like street suffixes — it's a designator phrase + a box id — so the
+ *   API is a detector ({@link isPOBox}), a normalizer ({@link normalizePOBox}), and an extractor
+ *   ({@link matchPOBox}) the corpus po_box synth/parsing can reuse instead of re-deriving the
+ *   regex.
+ * @see {@link https://pe.usps.com/text/pub28/28c2_012.htm USPS Pub 28 §29 (PO Box / Caller service)}
+ */
+
+/**
+ * USPS designator phrases that introduce a post-office-box identifier, longest-first so the matcher prefers the most
+ * specific phrase ("Post Office Box" before "Box"). Each is matched case-insensitively with flexible internal
+ * punctuation/spacing.
+ */
+export const US_PO_BOX_DESIGNATORS = [
+	"POST OFFICE BOX",
+	"PO BOX",
+	"P O BOX",
+	"FIRM CALLER",
+	"CALLER",
+	"DRAWER",
+	"LOCKBOX",
+	"BOX",
+] as const satisfies readonly string[]
+
+export type USPoBoxDesignator = (typeof US_PO_BOX_DESIGNATORS)[number]
+
+// Matches a leading PO-box designator + its identifier. Allows "P.O. Box", "PO BOX", "Post Office
+// Box", "Box 12-A", etc. The id is alphanumeric with optional dashes (USPS caller/firm ids exist).
+const PO_BOX_RE =
+	/^\s*(?:(p\.?\s*o\.?\s*box)|(post\s+office\s+box)|(firm\s+caller)|(caller)|(drawer)|(lockbox)|(box))\s*#?\s*([\dA-Za-z][\dA-Za-z-]*)\s*$/i
+
+/**
+ * Type-predicate: does the input look like a standalone PO Box address? Case-insensitive and tolerant of "P.O. Box",
+ * "Post Office Box", "Box 12", "PMB"-style ids. (Widens the original isp-nexus `/^PO BOX [\d-]+$/`, which only matched
+ * all-caps "PO BOX 123".)
+ */
+export function isPOBox(input: unknown): boolean {
+	return typeof input === "string" && PO_BOX_RE.test(input)
+}
+
+/** Result of a PO-box parse: the matched designator phrase and the box identifier. */
+export interface PoBoxMatch {
+	/** The designator phrase as it appeared, e.g. "P.O. Box", "Post Office Box". */
+	matched: string
+	/** The box identifier, e.g. "123", "12-A". */
+	id: string
+}
+
+/**
+ * If `input` is a PO-box phrase ("PO Box 123", "P.O. Box 12-A", "Post Office Box 7"), return the designator phrase and
+ * the id. Null otherwise. Useful for the corpus po_box shard (split the designator from the number) and for
+ * resolver/parsing reuse.
+ */
+export function matchPOBox(input: unknown): PoBoxMatch | null {
+	if (typeof input !== "string") return null
+	const m = PO_BOX_RE.exec(input)
+
+	if (!m) return null
+	const matched = (m[1] ?? m[2] ?? m[3] ?? m[4] ?? m[5] ?? m[6] ?? m[7] ?? "").trim()
+	const id = m[8]!
+
+	return { matched, id }
+}
+
+/**
+ * Normalize any recognized PO-box phrase to the canonical USPS "PO BOX <id>" form. Returns the input unchanged if it
+ * isn't a PO box. (Widens the original isp-nexus normalizer, which only collapsed the "P.O. BOX" spelling and left the
+ * id/casing alone.)
+ */
+export function normalizePOBox(input: string): string {
+	const m = matchPOBox(input)
+
+	if (!m) return input
+
+	return `PO BOX ${m.id.toUpperCase()}`
+}

package/us/state.ts

@@ -0,0 +1,156 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   US two-letter postal abbreviations for the 50 states, DC, and the five primary territories.
+ *
+ *   This is the minimal state primitive `zipcode.ts` needs (a closed abbreviation set + predicate)
+ *   without pulling in `@mailwoman/tiger`'s FIPS enums and their `shapefile-parser` dependency —
+ *   the point of the codex being a zero-runtime-dep package the browser-pure parser can consume.
+ *   The full FIPS-keyed table still lives in `@mailwoman/tiger` (`tiger/state.ts`) and in the
+ *   corpus TIGER adapter; folding those onto this set is a deliberate follow-up, not a v1 concern.
+ */
+
+/**
+ * USPS two-letter abbreviations: the 50 states, the District of Columbia, and the five primary territories (Puerto
+ * Rico, Guam, US Virgin Islands, Northern Mariana Islands, American Samoa).
+ */
+export const US_STATE_ABBREVIATIONS = [
+	"AL",
+	"AK",
+	"AZ",
+	"AR",
+	"CA",
+	"CO",
+	"CT",
+	"DE",
+	"DC",
+	"FL",
+	"GA",
+	"HI",
+	"ID",
+	"IL",
+	"IN",
+	"IA",
+	"KS",
+	"KY",
+	"LA",
+	"ME",
+	"MD",
+	"MA",
+	"MI",
+	"MN",
+	"MS",
+	"MO",
+	"MT",
+	"NE",
+	"NV",
+	"NH",
+	"NJ",
+	"NM",
+	"NY",
+	"NC",
+	"ND",
+	"OH",
+	"OK",
+	"OR",
+	"PA",
+	"RI",
+	"SC",
+	"SD",
+	"TN",
+	"TX",
+	"UT",
+	"VT",
+	"VA",
+	"WA",
+	"WV",
+	"WI",
+	"WY",
+	"PR",
+	"GU",
+	"VI",
+	"MP",
+	"AS",
+] as const satisfies readonly string[]
+
+/** A USPS two-letter state-or-territory abbreviation. */
+export type USStateAbbreviation = (typeof US_STATE_ABBREVIATIONS)[number]
+
+const STATE_ABBREVIATION_SET: ReadonlySet<string> = new Set(US_STATE_ABBREVIATIONS)
+
+/**
+ * Type-predicate for a USPS state-or-territory abbreviation. Case-insensitive (`"ca"` and `"CA"` both pass), since the
+ * abbreviation arrives from raw address text.
+ */
+export function isUSStateAbbreviation(input: unknown): input is USStateAbbreviation {
+	return typeof input === "string" && STATE_ABBREVIATION_SET.has(input.toUpperCase())
+}
+
+/**
+ * Full names for the 50 states, DC, and the five primary territories, keyed by USPS abbreviation. The names half of the
+ * closed region vocabulary — where the country/state homographs live ("Georgia", "Washington"), which the
+ * gazetteer-anchor lexicon needs to flag candidate-tag collisions. Source: USPS Publication 28, Appendix B.
+ */
+export const US_STATE_BY_ABBREVIATION = {
+	AL: "Alabama",
+	AK: "Alaska",
+	AZ: "Arizona",
+	AR: "Arkansas",
+	CA: "California",
+	CO: "Colorado",
+	CT: "Connecticut",
+	DE: "Delaware",
+	DC: "District of Columbia",
+	FL: "Florida",
+	GA: "Georgia",
+	HI: "Hawaii",
+	ID: "Idaho",
+	IL: "Illinois",
+	IN: "Indiana",
+	IA: "Iowa",
+	KS: "Kansas",
+	KY: "Kentucky",
+	LA: "Louisiana",
+	ME: "Maine",
+	MD: "Maryland",
+	MA: "Massachusetts",
+	MI: "Michigan",
+	MN: "Minnesota",
+	MS: "Mississippi",
+	MO: "Missouri",
+	MT: "Montana",
+	NE: "Nebraska",
+	NV: "Nevada",
+	NH: "New Hampshire",
+	NJ: "New Jersey",
+	NM: "New Mexico",
+	NY: "New York",
+	NC: "North Carolina",
+	ND: "North Dakota",
+	OH: "Ohio",
+	OK: "Oklahoma",
+	OR: "Oregon",
+	PA: "Pennsylvania",
+	RI: "Rhode Island",
+	SC: "South Carolina",
+	SD: "South Dakota",
+	TN: "Tennessee",
+	TX: "Texas",
+	UT: "Utah",
+	VT: "Vermont",
+	VA: "Virginia",
+	WA: "Washington",
+	WV: "West Virginia",
+	WI: "Wisconsin",
+	WY: "Wyoming",
+	PR: "Puerto Rico",
+	GU: "Guam",
+	VI: "US Virgin Islands",
+	MP: "Northern Mariana Islands",
+	AS: "American Samoa",
+} as const satisfies Record<USStateAbbreviation, string>
+
+/** The full state/territory names, derived from {@link US_STATE_BY_ABBREVIATION}. */
+export const US_STATE_NAMES: readonly string[] = Object.values(US_STATE_BY_ABBREVIATION)

package/us/street-directional.ts

@@ -0,0 +1,220 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   USPS street **directionals** — the 8 cardinal/intercardinal prefixes (N, S, E, W, NE, NW, SE,
+ *   SW). The leading-directional counterpart to {@link ./street-suffix.ts} (trailing street type):
+ *   "N Main St" splits into a `street_prefix` directional ("N"), a `street` name ("Main"), and a
+ *   `street_suffix` type ("St").
+ * @see {@link https://pe.usps.com/text/pub28/28apc_002.htm USPS Pub 28 Appendix C1}
+ */
+
+import { matchCase } from "./street-suffix.ts"
+
+/**
+ * The 8 directional abbreviations accepted by the USPS. The USPS prefers the abbreviation over the fully-spelled-out
+ * name.
+ */
+export const DirectionalAbbreviation = {
+	NORTH: "N",
+	EAST: "E",
+	SOUTH: "S",
+	WEST: "W",
+	NORTHEAST: "NE",
+	NORTHWEST: "NW",
+	SOUTHEAST: "SE",
+	SOUTHWEST: "SW",
+} as const
+
+export type DirectionalAbbreviation = (typeof DirectionalAbbreviation)[keyof typeof DirectionalAbbreviation]
+
+/** The 8 directional names accepted by the USPS (intercardinals spaced, per the publication). */
+export const DirectionalNames = [
+	"NORTH",
+	"EAST",
+	"SOUTH",
+	"WEST",
+	"NORTH EAST",
+	"NORTH WEST",
+	"SOUTH EAST",
+	"SOUTH WEST",
+] as const satisfies readonly string[]
+
+export type DirectionalName = (typeof DirectionalNames)[number]
+
+export const DirectionalNameVariations = [
+	...DirectionalNames,
+	// Without spaces (the common US street form: "Northeast Main St")…
+	"NORTHEAST",
+	"NORTHWEST",
+	"SOUTHEAST",
+	"SOUTHWEST",
+	// Title-case…
+	"North",
+	"East",
+	"South",
+	"West",
+	"North East",
+	"North West",
+	"South East",
+	"South West",
+	"Northeast",
+	"Northwest",
+	"Southeast",
+	"Southwest",
+	// Lower-case…
+	"north east",
+	"north west",
+	"south east",
+	"south west",
+	"northeast",
+	"northwest",
+	"southeast",
+	"southwest",
+] as const satisfies readonly string[]
+
+export type DirectionalNameVariation = (typeof DirectionalNameVariations)[number]
+
+/**
+ * Abbreviation → full name.
+ */
+export const DirectionalAbbreviationRecord = {
+	N: "NORTH",
+	E: "EAST",
+	S: "SOUTH",
+	W: "WEST",
+	NE: "NORTH EAST",
+	NW: "NORTH WEST",
+	SE: "SOUTH EAST",
+	SW: "SOUTH WEST",
+} as const satisfies Record<DirectionalAbbreviation, DirectionalName>
+
+export type DirectionalAbbreviationRecord = typeof DirectionalAbbreviationRecord
+
+/**
+ * Name (and its variations) → abbreviation.
+ */
+export const DirectionAbbreviationRecord = {
+	NORTH: DirectionalAbbreviation.NORTH,
+	EAST: DirectionalAbbreviation.EAST,
+	SOUTH: DirectionalAbbreviation.SOUTH,
+	WEST: DirectionalAbbreviation.WEST,
+	NORTHEAST: DirectionalAbbreviation.NORTHEAST,
+	NORTHWEST: DirectionalAbbreviation.NORTHWEST,
+	SOUTHEAST: DirectionalAbbreviation.SOUTHEAST,
+	SOUTHWEST: DirectionalAbbreviation.SOUTHWEST,
+	"NORTH EAST": DirectionalAbbreviation.NORTHEAST,
+	"NORTH WEST": DirectionalAbbreviation.NORTHWEST,
+	"SOUTH EAST": DirectionalAbbreviation.SOUTHEAST,
+	"SOUTH WEST": DirectionalAbbreviation.SOUTHWEST,
+} as const satisfies Partial<Record<string, DirectionalAbbreviation>>
+
+export type DirectionAbbreviationRecord = typeof DirectionAbbreviationRecord
+
+/**
+ * Abbreviation (verbatim or normalized) → full name.
+ */
+export const AbbreviationToDirectional: ReadonlyMap<string, DirectionalName> = new Map(
+	Object.entries(DirectionalAbbreviationRecord)
+)
+
+/**
+ * Name (verbatim or normalized) → abbreviation.
+ */
+export const DirectionalToAbbreviationMap: ReadonlyMap<string, DirectionalAbbreviation> = new Map(
+	Object.entries(DirectionAbbreviationRecord)
+)
+
+/**
+ * Given a possible directional abbreviation, return the corresponding full name (or null).
+ */
+export function pluckDirectionalName(input: unknown): DirectionalName | null {
+	if (!input || typeof input !== "string") return null
+
+	return AbbreviationToDirectional.get(input) || AbbreviationToDirectional.get(input.trim().toUpperCase()) || null
+}
+
+/**
+ * Given a possible directional name, return the corresponding abbreviation (or null).
+ */
+export function lookupDirectionalAbbreviation(input: unknown): DirectionalAbbreviation | null {
+	if (!input || typeof input !== "string") return null
+
+	return (
+		DirectionalToAbbreviationMap.get(input) ||
+		DirectionalToAbbreviationMap.get(input.trim().toUpperCase().replace(/\s+/g, " ")) ||
+		null
+	)
+}
+
+/**
+ * Result of a directional lookup: the canonical full name + its preferred abbreviation.
+ */
+export interface DirectionalMatch {
+	/** The matched directional name, e.g. "NORTH", "NORTH EAST". */
+	directional: DirectionalName
+	/** The corresponding USPS abbreviation, e.g. "N", "NE". */
+	abbreviation: DirectionalAbbreviation
+}
+
+/**
+ * Look up a directional by abbreviation OR name (any variation), returning both forms.
+ */
+export function lookupDirectional(input: unknown): DirectionalMatch | null {
+	if (!input || typeof input !== "string") return null
+	const abbreviation = lookupDirectionalAbbreviation(input)
+
+	if (abbreviation) return { directional: DirectionalAbbreviationRecord[abbreviation], abbreviation }
+	const directional = pluckDirectionalName(input)
+
+	if (directional) return { directional, abbreviation: DirectionalToAbbreviationMap.get(directional)! }
+
+	return null
+}
+
+// ── Codex shard-facing helpers (mirror street-suffix's matchTrailingSuffix) ───────────────────────
+
+/**
+ * If the FIRST whitespace-separated word of `street` is a known USPS directional (abbrev or name), return the canonical
+ * name, its abbreviation, and the matched surface word. Null otherwise. (The leading-end counterpart of
+ * {@link matchTrailingSuffix}; mirrors unit-designator's `matchLeadingDesignator`.) Single-word only — the spaced "NORTH
+ * EAST" form is normalized to its one-word variant in real US streets, which this matches via the lookup.
+ */
+export function matchLeadingDirectional(
+	street: string
+): { canonical: DirectionalName; abbreviation: DirectionalAbbreviation; matched: string } | null {
+	const trimmed = street.trim()
+
+	if (!trimmed) return null
+	const first = trimmed.split(/\s+/)[0]!
+	const m = lookupDirectional(first)
+
+	if (!m) return null
+
+	return { canonical: m.directional, abbreviation: m.abbreviation, matched: first }
+}
+
+/**
+ * Render a directional in the requested surface form, in `reference`'s case pattern:
+ *
+ * - `"abbr"` → the USPS abbreviation ("N", "NE").
+ * - `"full"` → the one-word spelled-out form ("North", "Northeast") — the common US street form, not the publication's
+ *   spaced "NORTH EAST".
+ */
+export function renderDirectional(
+	match: { canonical: DirectionalName; abbreviation: DirectionalAbbreviation },
+	form: "abbr" | "full",
+	reference: string
+): string {
+	const target = form === "abbr" ? match.abbreviation : match.canonical.replace(/\s+/g, "")
+
+	return matchCase(target, reference)
+}
+
+/**
+ * Case-insensitive check: is the token any USPS directional or abbreviation (`"N"`, `"north"`, `"NW"`)?
+ */
+export function isStreetDirectionalToken(input: unknown): boolean {
+	return lookupDirectional(typeof input === "string" ? input.trim() : input) !== null
+}