@mailwoman/codex 7.2.0 → 7.3.0

package/nz/delivery-service.ts

@@ -0,0 +1,211 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   NZ Post delivery-service types — the second half of the Commonwealth po_box vocabulary: `PO Box
+ *   24999`, `Private Bag 106999`, `CMB B99`, plus the identifier-less counter services, plus the
+ *   colloquial "Private Box" alias documented here for recognition with its 'invalid' citation.
+ *
+ *   Sourcing (accessed 2026-06-11):
+ *
+ *   - NZ Post Address Standards (ADV358, October 2021 edition hosted on nzpost.co.nz) is the
+ *       authoritative document. Verbatim: "The Delivery Service Type is mandatory. It may be PO
+ *       Box, Private Bag, CMB, Response Bag, Counter Delivery or Poste Restante." Its Delivery
+ *       Service Elements table gives the descriptions reproduced in
+ *       {@link NZ_DELIVERY_SERVICE_TYPES}, and the identifier rules: "The Delivery Service
+ *       Identifier must have no leading zeros and no spaces, separators or other punctuation"; "The
+ *       Delivery Service Identifier is not used for Counter Delivery or Poste Restante. It is also
+ *       not used for Private Bags that do not have an identifier allocated by New Zealand Post".
+ *       Examples: `PO Box 24999`, `Private Bag 106999`, `Response Bag 500999`, `CMB B99`, `Counter
+ *       Delivery`, `Poste Restante`. The standard's incorrect-form examples show `P O Box 4 099`
+ *       and `PB 39990` as wrong — `PB` is a common error, not a designator, so it is NOT in this
+ *       table.
+ *   - The live addressing-standards page repeats the format rules: "PO Box and Private Bag numbers are
+ *       space-free (eg. 'PO Box 23226', not 'PO Box 23 226')", "'PO' is space-free … and
+ *       punctuation-free".
+ *
+ *   All six types are CURRENT in the October 2021 ADV358 (including CMB — no legacy flag is needed
+ *   for the NZ slice).
+ *
+ *   **"Private Box" — colloquial alias, officially invalid:** ADV358 does not list "Private Box" as a
+ *   Delivery Service Type and NZ Post's live standards pages (addressing-standards, how-to-address-
+ *   mail, accessed 2026-06-11) name only the six types above. However, real NZ mail and the postal
+ *   arena's gold rows carry "Private Box" as a colloquial synonym for a numbered PO Box (same
+ *   numbered format, different label). Operator ruling 2026-06-11: "Private Box = recognize-as-used
+ *   — codex documents it unofficial/colloquial WITH the 'officially invalid' citation; the shard
+ *   teaches recognition (validity and recognition are separate disciplines, same as the AU legacy
+ *   flags)." This is encoded in {@link NZ_PRIVATE_BOX_ALIAS} — a distinct export from
+ *   {@link NZ_DELIVERY_SERVICE_TYPES} so callers can choose whether to include the unofficial form.
+ * @see {@link https://www.nzpost.co.nz/sites/nz/files/2021-10/adv358-address-standards.pdf NZ Post Address Standards (ADV358, Oct 2021)}
+ * @see {@link https://www.nzpost.co.nz/business/shipping-in-nz/addressing-standards NZ Post addressing standards}
+ * @see {@link https://www.nzpost.co.nz/personal/sending-in-nz/how-to-address-mail NZ Post — how to address mail}
+ */
+
+/** Identifier requirement per ADV358's Delivery Service Elements rules. */
+export type NzIdentifierRule = "required-if-allocated" | "optional" | "not-used"
+
+/** One Delivery Service Type row from ADV358. */
+export interface NzDeliveryServiceType {
+	/** The Delivery Service Type, verbatim casing per ADV358 ("PO Box", "Private Bag", "CMB"). */
+	type: string
+	/** The ADV358 description, verbatim. */
+	description: string
+	/**
+	 * Identifier rule: PO Box/Response Bag/CMB identifiers are mandatory if allocated; Private Bag may legitimately have
+	 * none ("not used … for Private Bags that do not have an identifier allocated by New Zealand Post"); Counter Delivery
+	 * and Poste Restante never carry one.
+	 */
+	identifier: NzIdentifierRule
+}
+
+/** The six Delivery Service Types, verbatim from ADV358 (see the module header). */
+export const NZ_DELIVERY_SERVICE_TYPES = [
+	{ type: "PO Box", description: "Post Box, PO Box", identifier: "required-if-allocated" },
+	{ type: "Private Bag", description: "Private Bag", identifier: "optional" },
+	{ type: "Response Bag", description: "Response Bag (used for competitions)", identifier: "required-if-allocated" },
+	{
+		type: "CMB",
+		description: "Community Mail Box in postal outlet or on a thoroughfare",
+		identifier: "required-if-allocated",
+	},
+	{
+		type: "Counter Delivery",
+		description: "Hold for Counter Delivery collection - domestic mail",
+		identifier: "not-used",
+	},
+	{
+		type: "Poste Restante",
+		description: "Hold for Poste Restante collection - international mail",
+		identifier: "not-used",
+	},
+] as const satisfies readonly NzDeliveryServiceType[]
+
+/** A canonical NZ Delivery Service Type. */
+export type NzDeliveryServiceTypeName = (typeof NZ_DELIVERY_SERVICE_TYPES)[number]["type"]
+
+/**
+ * Metadata for the colloquial "Private Box" alias (see the module header and operator ruling 2026-06-11). Kept separate
+ * from {@link NZ_DELIVERY_SERVICE_TYPES} because it is NOT a valid ADV358 Delivery Service Type — recognition and
+ * validity are separate concerns.
+ *
+ * Sourcing: ADV358 (Oct 2021) omits "Private Box" from its Delivery Service Type list entirely. NZ Post's live
+ * standards pages (nzpost.co.nz/business/shipping-in-nz/addressing-standards and
+ * nzpost.co.nz/personal/sending-in-nz/how-to-address-mail, accessed 2026-06-11) do not list it as a valid type. Real NZ
+ * mail and the postal arena's gold rows nonetheless carry it as a colloquial synonym for a numbered PO Box. Operator
+ * ruling 2026-06-11 authorizes its inclusion here for recognition only, with this citation; corpus synthesis should
+ * treat it as a non-prescriptive form.
+ */
+export const NZ_PRIVATE_BOX_ALIAS = {
+	/** The surface form as it appears on real mail and in postal-arena gold rows. */
+	type: "Private Box",
+	/**
+	 * The description of validity status — NOT a valid ADV358 Delivery Service Type; a colloquial NZ synonym for a
+	 * numbered PO Box (same format as "PO Box <number>").
+	 */
+	description: "Colloquial NZ synonym for a numbered PO Box — NOT a valid ADV358 Delivery Service Type",
+	/** Identifier rule mirrors PO Box: a number is expected when the alias is used with one. */
+	identifier: "required-if-allocated" satisfies NzIdentifierRule,
+	/**
+	 * True — this form is NOT valid per ADV358 or NZ Post's live standards pages (accessed 2026-06-11).
+	 */
+	officiallyInvalid: true,
+} as const
+
+/**
+ * Per-type surface patterns (designator phrase only). Recognition is deliberately wider than the prescriptive standard
+ * — mail in the wild writes "P.O. Box" even though ADV358 says `PO` is punctuation-free — but it does NOT admit forms
+ * the standard names as errors of TYPE (`PB`).
+ *
+ * The colloquial "Private Box" alias is included for recognition (see {@link NZ_PRIVATE_BOX_ALIAS} and operator ruling
+ * 2026-06-11); it maps to a distinct synthetic type string so callers can distinguish it from the ADV358 types.
+ */
+const TYPE_PATTERNS: ReadonlyArray<readonly [NzDeliveryServiceTypeName | "Private Box", string]> = [
+	["PO Box", String.raw`p\.?\s*o\.?\s*box|post\s+box`],
+	["Private Bag", String.raw`private\s+bag`],
+	["Private Box", String.raw`private\s+box`],
+	["Response Bag", String.raw`response\s+bag`],
+	["CMB", String.raw`community\s+mail\s+box|cmb`],
+	["Counter Delivery", String.raw`counter\s+delivery`],
+	["Poste Restante", String.raw`poste\s+restante`],
+]
+
+/** Extended type name union including the colloquial alias recognized for parsing. */
+export type NzDeliveryServiceMatchTypeName = NzDeliveryServiceTypeName | "Private Box"
+
+const IDENTIFIER_RULES = new Map<NzDeliveryServiceMatchTypeName, NzIdentifierRule>([
+	...NZ_DELIVERY_SERVICE_TYPES.map((t) => [t.type, t.identifier] as const),
+	// "Private Box" mirrors PO Box identifier rules (required-if-allocated) per the alias metadata.
+	["Private Box", NZ_PRIVATE_BOX_ALIAS.identifier],
+])
+
+// One anchored regex per type. The identifier shape follows ADV358 (alphanumeric, no spaces or
+// separators — `24999`, `B99`); the identifier-less counter services take no tail at all.
+const MATCHERS: ReadonlyArray<{ type: NzDeliveryServiceMatchTypeName; re: RegExp }> = TYPE_PATTERNS.map(
+	([type, src]) => {
+		const rule = IDENTIFIER_RULES.get(type)!
+		const tail = rule === "not-used" ? "" : String.raw`(?:\s+([\dA-Za-z]+))${rule === "optional" ? "?" : ""}`
+
+		return { type, re: new RegExp(String.raw`^\s*(${src})${tail}\s*$`, "i") }
+	}
+)
+
+/** Result of an NZ delivery-service parse. */
+export interface NzDeliveryServiceMatch {
+	/** The designator phrase as it appeared ("PO Box", "private bag", "Private Box"). */
+	matched: string
+	/**
+	 * The canonical Delivery Service Type or recognized alias ("PO Box", "Private Bag", "CMB", …, "Private Box"). When
+	 * `type` is "Private Box", `colloquial` is true and `officiallyInvalid` is true — the form is not a valid ADV358
+	 * type.
+	 */
+	type: NzDeliveryServiceMatchTypeName
+	/** The Delivery Service Identifier when present ("24999", "B99"). */
+	id?: string
+	/**
+	 * True when the matched form is the colloquial "Private Box" alias — not a valid ADV358 Delivery Service Type. Absent
+	 * (undefined) for all standard ADV358 types.
+	 */
+	colloquial?: true
+}
+
+/**
+ * If `input` is a standalone NZ delivery-service phrase ("PO Box 24999", "Private Bag 106999", "CMB B99", bare "Private
+ * Bag", "Counter Delivery", "Private Box 102"), return the canonical type and identifier. Null otherwise — including
+ * for "PB 39990" (an error of form per ADV358).
+ *
+ * When `type` is "Private Box", the result carries `colloquial: true` — indicating the colloquial alias (not an ADV358
+ * Delivery Service Type; see {@link NZ_PRIVATE_BOX_ALIAS} and operator ruling 2026-06-11). Callers that want only
+ * formally-valid ADV358 types should check `!result.colloquial`.
+ */
+export function matchNzDeliveryService(input: unknown): NzDeliveryServiceMatch | null {
+	if (typeof input !== "string") return null
+
+	for (const { type, re } of MATCHERS) {
+		const m = re.exec(input)
+
+		if (!m) continue
+		const colloquial = type === "Private Box" ? ({ colloquial: true } as const) : {}
+
+		return { matched: m[1]!.trim(), type, ...(m[2] ? { id: m[2] } : {}), ...colloquial }
+	}
+
+	return null
+}
+
+/** Type-predicate: does the input look like a standalone NZ delivery-service address line? */
+export function isNzDeliveryService(input: unknown): boolean {
+	return matchNzDeliveryService(input) !== null
+}
+
+/**
+ * Normalize a recognized phrase to the ADV358 form (`"p.o. box 24999"` → `"PO Box 24999"`). Returns the input unchanged
+ * if it isn't a delivery-service phrase.
+ */
+export function normalizeNzDeliveryService(input: string): string {
+	const m = matchNzDeliveryService(input)
+
+	if (!m) return input
+
+	return m.id ? `${m.type} ${m.id.toUpperCase()}` : m.type
+}

package/nz/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The New Zealand address system (NZ Post / ISO 3166-2:NZ; ADV358 Address Standards):
+ *   delivery-service types (PO Box, Private Bag, CMB, Response Bag, Counter Delivery, Poste
+ *   Restante) and the 4-digit postcode. NZ addresses carry no state/region line.
+ */
+
+export * from "./delivery-service.ts"
+export * from "./postcode.ts"

package/nz/postcode.ts

@@ -0,0 +1,42 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   New Zealand postcodes: four digits, after the town/city on the last line (`Timaru 7942`).
+ *   Verbatim from NZ Post's Address Standards (ADV358, Oct 2021, accessed 2026-06-11): "Postcode is
+ *   mandatory and is four digits. It follows the city or town." Note NZ has no state/region line —
+ *   "The province, region, district or territory is not to be used."
+ *
+ *   The shape collides with Australia's (also 4 digits) — `candidateSystemsForPostcode` returns both,
+ *   by design (shape test, not membership test).
+ * @see {@link https://www.nzpost.co.nz/sites/nz/files/2021-10/adv358-address-standards.pdf NZ Post Address Standards (ADV358, Oct 2021)}
+ */
+
+import type { Tagged } from "type-fest"
+
+/**
+ * A New Zealand postcode: four digits.
+ *
+ * @category Postal
+ * @type string
+ * @title New Zealand postcode
+ * @pattern ^\d{4}$
+ */
+export type NzPostcode = Tagged<string, "NzPostcode">
+
+/** The NZ postcode shape: exactly four digits. */
+export const NZ_POSTCODE_PATTERN = /^\d{4}$/
+
+/** Normalize a postcode surface form (trim only — NZ has no country-prefix courtesy form). */
+export function normalizeNzPostcode(raw: unknown): NzPostcode | null {
+	if (typeof raw !== "string") return null
+	const s = raw.trim()
+
+	return NZ_POSTCODE_PATTERN.test(s) ? (s as NzPostcode) : null
+}
+
+/** Type-predicate for a (normalized) New Zealand postcode. */
+export function isNzPostcode(input: unknown): input is NzPostcode {
+	return typeof input === "string" && NZ_POSTCODE_PATTERN.test(input)
+}

package/out/country/index.d.ts

@@ -11,4 +11,5 @@ export * from "./names.ts";
 export * from "./official-languages.ts";
 export * from "./reference-data.ts";
 export * from "./reference.ts";
+export * from "./subdivision.ts";
 //# sourceMappingURL=index.d.ts.map

package/out/country/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../country/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../country/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA"}

package/out/country/index.js

@@ -11,4 +11,5 @@ export * from "./names.js";
 export * from "./official-languages.js";
 export * from "./reference-data.js";
 export * from "./reference.js";
+export * from "./subdivision.js";
 //# sourceMappingURL=index.js.map

package/out/country/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../country/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../country/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA"}

package/out/country/subdivision.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   ISO 3166-2 subdivision → country reference, the cross-country complement to `country.ts`'s
+ *   ISO 3166-1 `matchCountry`. A subdivision token ("QC", "Ontario", "Illinois") names a first-level
+ *   admin unit whose COUNTRY is the piece the resolver needs when a region qualifier is the only
+ *   signal that the locale-inferred default country is wrong ("Montreal QC" under a US locale).
+ *
+ *   Scope is deliberately minimal: the two subdivision systems whose two-letter codes people write
+ *   ON THE ADDRESS LINE and whose homonymous localities collide across the border — US states
+ *   (`us/state.ts`) and Canadian provinces (`ca/province.ts`). Both directions are covered: the ISO
+ *   code (`QC` → Quebec) and the full name (`Quebec` / `Québec` → the `QC` record), so a resolver
+ *   can expand the abbreviation the gazetteer FTS index lacks ("QC" is not an alt-name of Québec)
+ *   into the full name it does carry. This is a soft prior, not a routing decision — the gazetteer
+ *   still does the geographic confirmation (per the registry-backed-soft-prior doctrine).
+ *
+ *   The US and Canadian code sets are disjoint (no two-letter code, and no full name, collides
+ *   between the two), so the combined lookup below is unambiguous. `CA` resolves to California the
+ *   US state (Canada's provinces carry no `CA` subdivision code), never to Canada the country —
+ *   country recognition stays with `matchCountry`.
+ *
+ *   Source: the underlying `US_STATE_BY_ABBREVIATION` (USPS Publication 28, Appendix B) and
+ *   `CA_PROVINCES` (ISO 3166-2:CA) tables. No new provenance is introduced here — this module only
+ *   re-keys those two existing tables into one subdivision→country view.
+ */
+/** A resolved subdivision: its ISO 3166-2 code (sans country prefix), canonical English name, and ISO 3166-1 country. */
+export interface SubdivisionMatch {
+    /** ISO 3166-2 subdivision code without the country prefix (e.g. `QC` for `CA-QC`, `IL` for `US-IL`). */
+    code: string;
+    /** Canonical English name (e.g. `Quebec`, `Illinois`). */
+    name: string;
+    /** ISO 3166-1 alpha-2 country the subdivision belongs to (`CA`, `US`). */
+    country: string;
+}
+/**
+ * Resolve a first-level subdivision surface form (ISO 3166-2 code, English name, or co-official French name for CA;
+ * accents optional) to its `{ code, name, country }`. Case- and diacritic-insensitive. Returns null for anything that
+ * isn't a US state or Canadian province/territory — including bare country tokens (use {@link matchCountry} for
+ * those).
+ */
+export declare function matchSubdivision(token: string | null | undefined): SubdivisionMatch | null;
+//# sourceMappingURL=subdivision.d.ts.map

package/out/country/subdivision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subdivision.d.ts","sourceRoot":"","sources":["../../country/subdivision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,yHAAyH;AACzH,MAAM,WAAW,gBAAgB;IAChC,wGAAwG;IACxG,IAAI,EAAE,MAAM,CAAA;IACZ,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAA;IACZ,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAA;CACf;AA2CD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,gBAAgB,GAAG,IAAI,CAI1F"}

package/out/country/subdivision.js

@@ -0,0 +1,76 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   ISO 3166-2 subdivision → country reference, the cross-country complement to `country.ts`'s
+ *   ISO 3166-1 `matchCountry`. A subdivision token ("QC", "Ontario", "Illinois") names a first-level
+ *   admin unit whose COUNTRY is the piece the resolver needs when a region qualifier is the only
+ *   signal that the locale-inferred default country is wrong ("Montreal QC" under a US locale).
+ *
+ *   Scope is deliberately minimal: the two subdivision systems whose two-letter codes people write
+ *   ON THE ADDRESS LINE and whose homonymous localities collide across the border — US states
+ *   (`us/state.ts`) and Canadian provinces (`ca/province.ts`). Both directions are covered: the ISO
+ *   code (`QC` → Quebec) and the full name (`Quebec` / `Québec` → the `QC` record), so a resolver
+ *   can expand the abbreviation the gazetteer FTS index lacks ("QC" is not an alt-name of Québec)
+ *   into the full name it does carry. This is a soft prior, not a routing decision — the gazetteer
+ *   still does the geographic confirmation (per the registry-backed-soft-prior doctrine).
+ *
+ *   The US and Canadian code sets are disjoint (no two-letter code, and no full name, collides
+ *   between the two), so the combined lookup below is unambiguous. `CA` resolves to California the
+ *   US state (Canada's provinces carry no `CA` subdivision code), never to Canada the country —
+ *   country recognition stays with `matchCountry`.
+ *
+ *   Source: the underlying `US_STATE_BY_ABBREVIATION` (USPS Publication 28, Appendix B) and
+ *   `CA_PROVINCES` (ISO 3166-2:CA) tables. No new provenance is introduced here — this module only
+ *   re-keys those two existing tables into one subdivision→country view.
+ */
+import { CA_PROVINCES } from "../ca/province.js";
+import { US_STATE_BY_ABBREVIATION } from "../us/state.js";
+/** Strip diacritics + lowercase so `Québec`, `Quebec`, and `quebec` all key alike (mirrors `ca/province.ts`). */
+function foldName(s) {
+    return s
+        .toLowerCase()
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .replace(/[^a-z0-9]+/g, " ")
+        .trim();
+}
+/**
+ * Folded surface form (ISO code, English name, or — for CA — co-official French name) → subdivision. Built once. US
+ * states are inserted first and never overwritten, so on the (currently empty) event of a future code/name collision
+ * the US entry wins deterministically; today the two sets are disjoint.
+ */
+const SUBDIVISION_LOOKUP = (() => {
+    const out = new Map();
+    const put = (key, match) => {
+        const folded = foldName(key);
+        if (folded.length > 0 && !out.has(folded)) {
+            out.set(folded, match);
+        }
+    };
+    for (const [code, name] of Object.entries(US_STATE_BY_ABBREVIATION)) {
+        const match = { code, name, country: "US" };
+        put(code, match);
+        put(name, match);
+    }
+    for (const info of Object.values(CA_PROVINCES)) {
+        const match = { code: info.code, name: info.name, country: "CA" };
+        put(info.code, match);
+        put(info.name, match);
+        put(info.french, match);
+    }
+    return out;
+})();
+/**
+ * Resolve a first-level subdivision surface form (ISO 3166-2 code, English name, or co-official French name for CA;
+ * accents optional) to its `{ code, name, country }`. Case- and diacritic-insensitive. Returns null for anything that
+ * isn't a US state or Canadian province/territory — including bare country tokens (use {@link matchCountry} for
+ * those).
+ */
+export function matchSubdivision(token) {
+    if (!token || typeof token !== "string")
+        return null;
+    return SUBDIVISION_LOOKUP.get(foldName(token)) ?? null;
+}
+//# sourceMappingURL=subdivision.js.map

package/out/country/subdivision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subdivision.js","sourceRoot":"","sources":["../../country/subdivision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAA;AAYzD,iHAAiH;AACjH,SAAS,QAAQ,CAAC,CAAS;IAC1B,OAAO,CAAC;SACN,WAAW,EAAE;SACb,SAAS,CAAC,KAAK,CAAC;SAChB,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC;SAC/B,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,IAAI,EAAE,CAAA;AACT,CAAC;AAED;;;;GAIG;AACH,MAAM,kBAAkB,GAA0C,CAAC,GAAG,EAAE;IACvE,MAAM,GAAG,GAAG,IAAI,GAAG,EAA4B,CAAA;IAC/C,MAAM,GAAG,GAAG,CAAC,GAAW,EAAE,KAAuB,EAAQ,EAAE;QAC1D,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAA;QAE5B,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3C,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;QACvB,CAAC;IACF,CAAC,CAAA;IAED,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,wBAAwB,CAAC,EAAE,CAAC;QACrE,MAAM,KAAK,GAAqB,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;QAC7D,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QAChB,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;IACjB,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC;QAChD,MAAM,KAAK,GAAqB,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;QACnF,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QACrB,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QACrB,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;IACxB,CAAC;IAED,OAAO,GAAG,CAAA;AACX,CAAC,CAAC,EAAE,CAAA;AAEJ;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAgC;IAChE,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IAEpD,OAAO,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,IAAI,IAAI,CAAA;AACvD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailwoman/codex",
-  "version": "7.2.0",
+  "version": "7.3.0",
   "description": "Per-address-system postal reference data + branded types (USPS street suffixes, US ZIP codes). Pure, zero-runtime-dep — the shared canonical home for postal-system primitives the parser, resolver, and synthesis layers all reach for.",
   "license": "AGPL-3.0-only OR LicenseRef-Commercial",
   "repository": {
@@ -12,74 +12,118 @@
     "out/**/*.js",
     "out/**/*.js.map",
     "out/**/*.d.ts",
-    "out/**/*.d.ts.map"
+    "out/**/*.d.ts.map",
+    "*.ts",
+    "*.tsx",
+    "**/*.ts",
+    "**/*.tsx",
+    "!*.test.ts",
+    "!*.test.tsx",
+    "!**/*.test.ts",
+    "!**/*.test.tsx"
   ],
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
     ".": {
-      "node": "./index.ts",
-      "default": "./out/index.js",
-      "types": "./out/index.d.ts"
+      "types": "./out/index.d.ts",
+      "default": "./out/index.js"
     },
     "./country": {
-      "node": "./country/index.ts",
-      "default": "./out/country/index.js",
-      "types": "./out/country/index.d.ts"
+      "types": "./out/country/index.d.ts",
+      "default": "./out/country/index.js"
     },
     "./us": {
-      "node": "./us/index.ts",
-      "default": "./out/us/index.js",
-      "types": "./out/us/index.d.ts"
+      "types": "./out/us/index.d.ts",
+      "default": "./out/us/index.js"
     },
     "./de": {
-      "node": "./de/index.ts",
-      "default": "./out/de/index.js",
-      "types": "./out/de/index.d.ts"
+      "types": "./out/de/index.d.ts",
+      "default": "./out/de/index.js"
     },
     "./fr": {
-      "node": "./fr/index.ts",
-      "default": "./out/fr/index.js",
-      "types": "./out/fr/index.d.ts"
+      "types": "./out/fr/index.d.ts",
+      "default": "./out/fr/index.js"
     },
     "./ca": {
-      "node": "./ca/index.ts",
-      "default": "./out/ca/index.js",
-      "types": "./out/ca/index.d.ts"
+      "types": "./out/ca/index.d.ts",
+      "default": "./out/ca/index.js"
     },
     "./gb": {
-      "node": "./gb/index.ts",
-      "default": "./out/gb/index.js",
-      "types": "./out/gb/index.d.ts"
+      "types": "./out/gb/index.d.ts",
+      "default": "./out/gb/index.js"
     },
     "./jp": {
-      "node": "./jp/index.ts",
-      "default": "./out/jp/index.js",
-      "types": "./out/jp/index.d.ts"
+      "types": "./out/jp/index.d.ts",
+      "default": "./out/jp/index.js"
     },
     "./au": {
-      "node": "./au/index.ts",
-      "default": "./out/au/index.js",
-      "types": "./out/au/index.d.ts"
+      "types": "./out/au/index.d.ts",
+      "default": "./out/au/index.js"
     },
     "./nz": {
-      "node": "./nz/index.ts",
-      "default": "./out/nz/index.js",
-      "types": "./out/nz/index.d.ts"
+      "types": "./out/nz/index.d.ts",
+      "default": "./out/nz/index.js"
     },
     "./tools": {
-      "node": "./tools/index.ts",
-      "default": "./out/tools/index.js",
-      "types": "./out/tools/index.d.ts"
+      "types": "./out/tools/index.d.ts",
+      "default": "./out/tools/index.js"
     }
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "exports": {
+      "./package.json": "./package.json",
+      ".": {
+        "types": "./out/index.d.ts",
+        "default": "./out/index.js"
+      },
+      "./country": {
+        "types": "./out/country/index.d.ts",
+        "default": "./out/country/index.js"
+      },
+      "./us": {
+        "types": "./out/us/index.d.ts",
+        "default": "./out/us/index.js"
+      },
+      "./de": {
+        "types": "./out/de/index.d.ts",
+        "default": "./out/de/index.js"
+      },
+      "./fr": {
+        "types": "./out/fr/index.d.ts",
+        "default": "./out/fr/index.js"
+      },
+      "./ca": {
+        "types": "./out/ca/index.d.ts",
+        "default": "./out/ca/index.js"
+      },
+      "./gb": {
+        "types": "./out/gb/index.d.ts",
+        "default": "./out/gb/index.js"
+      },
+      "./jp": {
+        "types": "./out/jp/index.d.ts",
+        "default": "./out/jp/index.js"
+      },
+      "./au": {
+        "types": "./out/au/index.d.ts",
+        "default": "./out/au/index.js"
+      },
+      "./nz": {
+        "types": "./out/nz/index.d.ts",
+        "default": "./out/nz/index.js"
+      },
+      "./tools": {
+        "types": "./out/tools/index.d.ts",
+        "default": "./out/tools/index.js"
+      }
+    }
   },
   "dependencies": {
     "type-fest": "^5.8.0"
   },
   "devDependencies": {
-    "@mailwoman/annotations": "7.2.0"
+    "@mailwoman/annotations": "7.3.0"
   }
 }

package/postcode-systems.ts

@@ -0,0 +1,68 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The inverse of the per-slice postcode patterns: given a postcode string, which address SYSTEMS
+ *   could it belong to? Each codex slice owns its own postcode shape (`us` accepts
+ *   `\d{5}(-\d{4})?`, `ca` accepts `A1A 1A1`, `jp` accepts `NNN-NNNN`, …); this is the single place
+ *   that asks all of them at once and collects the matches.
+ *
+ *   It is the shared source of truth for "which systems can this shape be" — consumed by the postcode
+ *   anchor (to narrow which systems' street vocabularies it checks) and, in time, by the runtime
+ *   pipeline's locale gate (so its format→locale scoring derives from the same patterns rather than
+ *   a second, divergent copy). The point is to unify the DATA, not to couple the modules: callers
+ *   depend on this pure function, never on each other.
+ *
+ *   Note this is a SHAPE test, not a gazetteer-membership test. A bare `68161` matches the US,
+ *   German, AND French 5-digit shapes, so it returns `["us", "de", "fr"]` — the shape alone cannot
+ *   split the numeric-postcode systems. The anchor uses real gazetteer membership for the finer
+ *   call; this function answers the coarser, model-free "which systems is this shape even eligible
+ *   for".
+ */
+
+import { normalizeAuPostcode } from "./au/index.ts"
+import { normalizeCaPostalCode } from "./ca/index.ts"
+import { normalizePLZ } from "./de/index.ts"
+import { normalizeCodePostal } from "./fr/index.ts"
+import { normalizeUkPostcode } from "./gb/index.ts"
+import { normalizeJpPostalCode } from "./jp/index.ts"
+import { normalizeNzPostcode } from "./nz/index.ts"
+import { isZipCode } from "./us/index.ts"
+
+/** A codex address-system code — the subpath under `@mailwoman/codex/<system>`. */
+export type SystemCode = "us" | "de" | "fr" | "ca" | "gb" | "jp" | "au" | "nz"
+
+/**
+ * Per-system membership test: each entry returns true when the string is accepted by that system's own postcode shape
+ * (after that system's normalization — so `D-68161` reaches `de`, `1012 LM` reaches nothing here since NL has no slice
+ * yet, etc.). Ordered for a stable, alphabetical-ish result.
+ */
+const SYSTEM_ACCEPTS: ReadonlyArray<readonly [SystemCode, (s: string) => boolean]> = [
+	["us", (s) => isZipCode(s)],
+	["de", (s) => normalizePLZ(s) !== null],
+	["fr", (s) => normalizeCodePostal(s) !== null],
+	["ca", (s) => normalizeCaPostalCode(s) !== null],
+	["gb", (s) => normalizeUkPostcode(s) !== null],
+	["jp", (s) => normalizeJpPostalCode(s) !== null],
+	["au", (s) => normalizeAuPostcode(s) !== null],
+	["nz", (s) => normalizeNzPostcode(s) !== null],
+]
+
+/**
+ * Every address system whose own postcode shape accepts `postcode`. Empty when no system recognizes the shape (e.g. a
+ * bare `27`, or a 7-digit run). O(number of systems) — a handful of cheap regex tests, run only on the few
+ * postcode-shaped spans an address contains.
+ */
+export function candidateSystemsForPostcode(postcode: string): SystemCode[] {
+	if (typeof postcode !== "string" || postcode.length === 0) return []
+	const out: SystemCode[] = []
+
+	for (const [system, accepts] of SYSTEM_ACCEPTS) {
+		if (accepts(postcode)) {
+			out.push(system)
+		}
+	}
+
+	return out
+}