@mailwoman/codex 7.2.0 → 7.3.0

package/address-system-conventions.ts

@@ -0,0 +1,68 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Per-address-system parsing conventions (#478's rules-as-constraints slice, started as the #511
+ *   Tier A corrective). The model's locale head detects WHICH address system a string belongs to;
+ *   this table says what is and isn't grammatical in that system, so the decoder can obey the
+ *   detection instead of merely being nudged by it.
+ *
+ *   Every row is a provenance-carrying claim about a national addressing convention — the same
+ *   provenance-first discipline as the rest of the codex. Add rows with a source, not from vibes;
+ *   an absent row means "no constraints known", never "no constraints exist".
+ *
+ *   First consumer: `@mailwoman/neural`'s decoder applies `forbiddenTags` as a hard emission mask
+ *   before Viterbi and treats `postcodePattern` as the system's canonical shape for the snap-only
+ *   postcode repair pass. Both triggered only when the system is detected confidently (or supplied
+ *   by the caller) — an undetected system parses exactly as before.
+ */
+
+import { CODE_POSTAL_PATTERN } from "./fr/code-postal.ts"
+import type { SystemCode } from "./postcode-systems.ts"
+
+export interface AddressSystemConventions {
+	/**
+	 * Component tags that are NOT grammatical in this address system (names from the core `ComponentTag` union; codex
+	 * stays dependency-free so they are plain strings here).
+	 */
+	readonly forbiddenTags?: readonly string[]
+	/**
+	 * The system's canonical postcode shape. A decoded postcode span that is a strict sub-match of a pattern-valid string
+	 * in the raw text is shape-INVALID for this system and eligible for the snap-only repair (extend/clip to the valid
+	 * match — never invent a span).
+	 */
+	readonly postcodePattern?: RegExp
+}
+
+export const ADDRESS_SYSTEM_CONVENTIONS: Partial<Record<SystemCode, AddressSystemConventions>> = {
+	/**
+	 * France (La Poste / AFNOR NF Z 10-011): the street TYPE is a LEADING particle of the street name ("Rue de Rivoli",
+	 * "Avenue des Champs-Élysées", "Cours Lafayette") and is labeled `street_prefix` — French addresses DO carry a
+	 * street_prefix, just never a trailing USPS-style street_suffix (the libpostal French dictionaries have no trailing
+	 * street-suffix class; Pub-28's suffix decomposition has no French counterpart).
+	 *
+	 * Provenance / why this is NOT a blanket prefix+suffix forbid (#719, 2026-06-18): an earlier model mis-tagged the
+	 * leading "Rue" as a US-style `street_suffix` (RUE is a Pub-28 suffix variant) — the 2026-06-10 v1.1.0 gate — so #511
+	 * forbade BOTH affix tags to stop that leakage. That forbid was correct for THAT model but became a live production
+	 * bug for the current one: the shipped model (v1.5.0) emits the FR `street_prefix` correctly, but the conventions
+	 * mask was a hard −1e9 on every B-/I-street_prefix emission, so the detected-FR parse could never KEEP a prefix — it
+	 * destroyed `street_prefix` wholesale (measured on data/eval/external/ fr-street-prefix-real.jsonl at
+	 * conventions=auto: F1 0.0 with the forbid on → 80.0 with it off; the larger real-FR eval reported the same collapse,
+	 * ~96 → ~0.6). We keep ONLY `street_suffix` forbidden: the current model with the forbid OFF shows zero FR
+	 * street_suffix leakage (fp=0 on that same slice) and FR has no trailing street suffix, so the constraint costs
+	 * nothing while still guarding against any future suffix mis-tag. Postcode: exactly five digits (NF Z 10-011; see
+	 * fr/code-postal).
+	 */
+	fr: {
+		forbiddenTags: ["street_suffix"],
+		postcodePattern: CODE_POSTAL_PATTERN,
+	},
+}
+
+/** Look up conventions for a system. Absent row = no constraints KNOWN (parse unconstrained). */
+export function conventionsForSystem(system: SystemCode | null | undefined): AddressSystemConventions | null {
+	if (!system) return null
+
+	return ADDRESS_SYSTEM_CONVENTIONS[system] ?? null
+}

package/au/delivery-service.ts

@@ -0,0 +1,179 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Australia Post delivery-service designators (Postal Delivery Types) — the Commonwealth po_box
+ *   vocabulary the US-only `us/po-box.ts` cannot see: `GPO Box 2890`, `Locked Bag 1797`, `Private
+ *   Bag 7`, plus the rural/community legacy tail (`RMB 4600`, `RSD`, `CMB`).
+ *
+ *   Sourcing (accessed 2026-06-11; the underlying urban/rural addressing standard is AS/NZS 4819,
+ *   which governs street addressing — the delivery-service designators below are Australia Post's
+ *   own, from its addressing guidance):
+ *
+ *   - The complete Postal Delivery Type table comes verbatim from Australia Post's barcode addressing
+ *       booklet ("Hints and tips to get a higher address match rate", SAP 8838883): CARE OF POST
+ *       OFFICE→CARE PO, COMMUNITY MAIL AGENT→CMA, COMMUNITY MAIL BAG→CMB, GENERAL POST OFFICE
+ *       BOX→GPO BOX, LOCKED MAIL BAG SERVICE→LOCKED BAG, MAIL SERVICE→MS, POST OFFICE BOX→PO BOX,
+ *       POSTE RESTANTE→CARE PO, PRIVATE MAIL BAG SERVICE→PRIVATE BAG, ROADSIDE DELIVERY→RSD,
+ *       ROADSIDE MAIL BAG→RMB, ROADSIDE MAIL BOX→RMB, ROADSIDE MAIL SERVICE→RMS, COMMUNITY POSTAL
+ *       AGENT→CPA. The same booklet states: "With the exception of Care of Post Office, Community
+ *       Mail Agent, Community Postal Agent, and Community Mail Bag, all Postal Delivery Types must
+ *       have an associated number for a match to occur. e.g. PO Box 112", and "'PRIVATE BOX' is not
+ *       a valid type" (so PRIVATE BOX is deliberately NOT in this table).
+ *   - Which designators are CURRENT retail products (vs. AMAS-recognized legacy forms) comes from the
+ *       live auspost.com.au pages: the addressing guidelines ("Line 2 should contain the street
+ *       number and name, or PO Box or Locked Bag number"), the Correct Addressing brochure (SAP
+ *       8833878, Nov 2022 — `GPO Box 123 / SYDNEY NSW 2000` example), the personal "PO Boxes and
+ *       Private Bags" page (Private Bag: "If you live in a rural or remote area of Australia, you
+ *       can manage your mail securely with a Private Bag"), and the business "PO Boxes and Locked
+ *       Bags" page (GPO Box: "Lease a single GPO Box, or the same box number in each capital city
+ *       with our Common Box service"; Common Box numbers run 9800–9999). PO Box, GPO Box, Locked
+ *       Bag, and Private Bag appear on those current pages; the rural/community types (RSD, RMB,
+ *       RMS, MS, CMB, CMA, CPA, Care PO) appear ONLY in the AMAS table and are flagged `legacy` —
+ *       the parser must still recognize them on older addresses.
+ *
+ * @see {@link https://auspost.com.au/content/dam/auspost_corp/media/documents/Barcode_hints_tips.pdf Australia Post barcode addressing booklet (Postal Delivery Type table)}
+ * @see {@link https://auspost.com.au/sending/guidelines/addressing-guidelines Australia Post addressing guidelines}
+ * @see {@link https://auspost.com.au/content/dam/auspost_corp/media/documents/correct-addressing.pdf Australia Post Correct Addressing brochure (Nov 2022)}
+ * @see {@link https://auspost.com.au/receiving/manage-your-mail/po-boxes-and-private-bags Australia Post — PO Boxes and Private Bags}
+ * @see {@link https://auspost.com.au/business/business-admin/po-boxes-and-locked-bags Australia Post — business PO Boxes, GPO Boxes and Locked Bags}
+ */
+
+/** One Postal Delivery Type row from the Australia Post AMAS abbreviation table. */
+export interface AuDeliveryServiceDesignator {
+	/** The full Postal Delivery Type name, verbatim from the table (uppercase as published). */
+	name: string
+	/** The standard abbreviation — the surface form written on mail ("GPO BOX", "LOCKED BAG"). */
+	abbreviation: string
+	/**
+	 * Whether the designator "must have an associated number for a match to occur" (AMAS rule; exceptions are Care of
+	 * Post Office, Community Mail Agent, Community Postal Agent, and Community Mail Bag).
+	 */
+	requiresNumber: boolean
+	/**
+	 * True when the designator is recognized by the AMAS Postal Delivery Type table but absent from every current
+	 * auspost.com.au addressing/product page (accessed 2026-06-11) — the rural and community forms superseded by rural
+	 * street addressing under AS/NZS 4819. The parser must still RECOGNIZE these on old addresses; synthesis should
+	 * weight them low.
+	 */
+	legacy: boolean
+}
+
+/**
+ * The verbatim Postal Delivery Type table (see the module header for the per-row provenance). Multiple names can share
+ * an abbreviation (ROADSIDE MAIL BAG and ROADSIDE MAIL BOX are both RMB; POSTE RESTANTE is addressed as CARE PO).
+ */
+export const AU_DELIVERY_SERVICE_DESIGNATORS = [
+	{ name: "GENERAL POST OFFICE BOX", abbreviation: "GPO BOX", requiresNumber: true, legacy: false },
+	{ name: "POST OFFICE BOX", abbreviation: "PO BOX", requiresNumber: true, legacy: false },
+	{ name: "LOCKED MAIL BAG SERVICE", abbreviation: "LOCKED BAG", requiresNumber: true, legacy: false },
+	{ name: "PRIVATE MAIL BAG SERVICE", abbreviation: "PRIVATE BAG", requiresNumber: true, legacy: false },
+	{ name: "COMMUNITY MAIL BAG", abbreviation: "CMB", requiresNumber: false, legacy: true },
+	{ name: "COMMUNITY MAIL AGENT", abbreviation: "CMA", requiresNumber: false, legacy: true },
+	{ name: "COMMUNITY POSTAL AGENT", abbreviation: "CPA", requiresNumber: false, legacy: true },
+	{ name: "CARE OF POST OFFICE", abbreviation: "CARE PO", requiresNumber: false, legacy: true },
+	{ name: "POSTE RESTANTE", abbreviation: "CARE PO", requiresNumber: false, legacy: true },
+	{ name: "MAIL SERVICE", abbreviation: "MS", requiresNumber: true, legacy: true },
+	{ name: "ROADSIDE DELIVERY", abbreviation: "RSD", requiresNumber: true, legacy: true },
+	{ name: "ROADSIDE MAIL BAG", abbreviation: "RMB", requiresNumber: true, legacy: true },
+	{ name: "ROADSIDE MAIL BOX", abbreviation: "RMB", requiresNumber: true, legacy: true },
+	{ name: "ROADSIDE MAIL SERVICE", abbreviation: "RMS", requiresNumber: true, legacy: true },
+] as const satisfies readonly AuDeliveryServiceDesignator[]
+
+/** A canonical Australia Post Postal Delivery Type abbreviation. */
+export type AuDeliveryServiceAbbreviation = (typeof AU_DELIVERY_SERVICE_DESIGNATORS)[number]["abbreviation"]
+
+/**
+ * Per-designator surface patterns (designator phrase only, no anchor, no id). Ordered longest / most-specific first so
+ * the matcher prefers "GPO Box" over "PO Box" and "RMS" over "MS". Each pattern tolerates the punctuation AMAS tells
+ * mailers to strip ("the full stops and commas in R.M.B and P.O.") — recognition must accept what deliverable mail
+ * actually carries.
+ *
+ * MS is special-cased in {@link matchAuDeliveryService}: its identifier must start with a digit so the bare two-letter
+ * designator cannot swallow an honorific ("Ms Smith").
+ */
+const DESIGNATOR_PATTERNS: ReadonlyArray<readonly [AuDeliveryServiceAbbreviation, string]> = [
+	["GPO BOX", String.raw`general\s+post\s+office\s+box|g\.?\s*p\.?\s*o\.?\s*box`],
+	["PO BOX", String.raw`post\s+office\s+box|p\.?\s*o\.?\s*box`],
+	["LOCKED BAG", String.raw`locked\s+(?:mail\s+)?bag(?:\s+service)?`],
+	["PRIVATE BAG", String.raw`private\s+(?:mail\s+)?bag(?:\s+service)?`],
+	["CARE PO", String.raw`care\s+of\s+post\s+office|poste\s+restante|care\s+po`],
+	["CMB", String.raw`community\s+mail\s+bag|cmb`],
+	["CMA", String.raw`community\s+mail\s+agent|cma`],
+	["CPA", String.raw`community\s+postal\s+agent|cpa`],
+	["RSD", String.raw`roadside\s+delivery|r\.?\s*s\.?\s*d\.?`],
+	["RMB", String.raw`roadside\s+mail\s+(?:bag|box)|r\.?\s*m\.?\s*b\.?`],
+	["RMS", String.raw`roadside\s+mail\s+service|rms`],
+	["MS", String.raw`mail\s+service|ms`],
+]
+
+const DESIGNATOR_INFO = new Map<AuDeliveryServiceAbbreviation, { requiresNumber: boolean; legacy: boolean }>(
+	AU_DELIVERY_SERVICE_DESIGNATORS.map((d) => [d.abbreviation, { requiresNumber: d.requiresNumber, legacy: d.legacy }])
+)
+
+// One anchored regex per designator: phrase + (required|optional) identifier. The id shape matches
+// the US slice ([\dA-Za-z][\dA-Za-z-]*); MS additionally requires a digit-leading id (see above).
+const MATCHERS: ReadonlyArray<{ abbreviation: AuDeliveryServiceAbbreviation; re: RegExp }> = DESIGNATOR_PATTERNS.map(
+	([abbreviation, src]) => {
+		const { requiresNumber } = DESIGNATOR_INFO.get(abbreviation)!
+		const id = abbreviation === "MS" ? String.raw`(\d[\dA-Za-z-]*)` : String.raw`([\dA-Za-z][\dA-Za-z-]*)`
+		const tail = requiresNumber ? String.raw`\s*#?\s*${id}` : String.raw`(?:\s*#?\s*${id})?`
+
+		return { abbreviation, re: new RegExp(String.raw`^\s*(${src})${tail}\s*$`, "i") }
+	}
+)
+
+/** Result of an AU delivery-service parse. */
+export interface AuDeliveryServiceMatch {
+	/** The designator phrase as it appeared ("G.P.O. Box", "Locked Bag"). */
+	matched: string
+	/** The canonical Postal Delivery Type abbreviation ("GPO BOX", "LOCKED BAG"). */
+	designator: AuDeliveryServiceAbbreviation
+	/** The delivery-service number when present ("9999", "4600"). */
+	id?: string
+	/** True when the designator is an AMAS-only legacy form (see the table). */
+	legacy: boolean
+}
+
+/**
+ * If `input` is a standalone Australia Post delivery-service phrase ("GPO Box 2890", "Locked Bag 1797", "RMB 4600",
+ * bare "CMB"), return the canonical designator, the id, and the legacy flag. Null otherwise — including for "Private
+ * Box", which Australia Post explicitly calls out as not a valid type.
+ */
+export function matchAuDeliveryService(input: unknown): AuDeliveryServiceMatch | null {
+	if (typeof input !== "string") return null
+
+	for (const { abbreviation, re } of MATCHERS) {
+		const m = re.exec(input)
+
+		if (!m) continue
+		const info = DESIGNATOR_INFO.get(abbreviation)!
+
+		return {
+			matched: m[1]!.trim(),
+			designator: abbreviation,
+			...(m[2] ? { id: m[2] } : {}),
+			legacy: info.legacy,
+		}
+	}
+
+	return null
+}
+
+/** Type-predicate: does the input look like a standalone AU delivery-service address line? */
+export function isAuDeliveryService(input: unknown): boolean {
+	return matchAuDeliveryService(input) !== null
+}
+
+/**
+ * Normalize a recognized delivery-service phrase to the canonical AMAS form (`"g.p.o. box 123"` → `"GPO BOX 123"`).
+ * Returns the input unchanged if it isn't one.
+ */
+export function normalizeAuDeliveryService(input: string): string {
+	const m = matchAuDeliveryService(input)
+
+	if (!m) return input
+
+	return m.id ? `${m.designator} ${m.id.toUpperCase()}` : m.designator
+}

package/au/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The Australian address system (Australia Post / ISO 3166-2:AU; street addressing per AS/NZS
+ *   4819): delivery-service designators (GPO Box, Locked Bag, Private Bag, the rural legacy tail),
+ *   AMAS / AS 4590.1 floor/level designators (Level 3, Ground Floor, Mezzanine), states and
+ *   territories, and the 4-digit postcode.
+ */
+
+export * from "./delivery-service.ts"
+export * from "./level-designator.ts"
+export * from "./postcode.ts"
+export * from "./state.ts"

package/au/level-designator.ts

@@ -0,0 +1,209 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Australia Post AMAS floor/level designators — the sub-premise vocabulary that names a FLOOR of a
+ *   building rather than a numbered unit on that floor: `Level 3`, `L 12`, `Ground Floor`,
+ *   `Mezzanine`.
+ *
+ *   Sourcing (accessed 2026-06-12):
+ *
+ *   - **Australia Post AMAS** (Address Matching Approval System) defines the Level Designator type and
+ *       its approved abbreviation. The verbatim AMAS description: "LEVEL" is the full word; "L" is
+ *       the approved abbreviation. The standard phrase format is `LEVEL <number>`, e.g. "LEVEL 3"
+ *       or "L 3" (abbreviation always uppercase in AMAS output). Australia Post's own barcode
+ *       addressing booklet (SAP 8838883) lists "LEVEL" and "L" as the level type; the Correct
+ *       Addressing brochure (SAP 8833878, Nov 2022) gives the example `LEVEL 3 / 60 MARGARET ST /
+ *       SYDNEY NSW 2000`. The AMAS Data Extract Format document (v4.2) confirms "LEVEL" → "L" as
+ *       the sole level abbreviation pair.
+ *   - **Ground floor** is treated by AMAS as `LEVEL G` (with the identifier "G"). Australia Post's
+ *       addressing guidelines state that ground floor should be written as "LEVEL G"; the full word
+ *       "GROUND" is a recognized alias for the identifier, not a separate designator type.
+ *   - **Mezzanine**, **Lower Ground**, and **Upper Ground** appear in AS 4590.1-2017 (the Australian
+ *       Standard for interchange of client information) as recognized level-type values alongside
+ *       LEVEL and GROUND. AS 4590.1-2017 Table 3 "Level type": B (Basement), G (Ground), MEZZANINE
+ *       (M), LG (Lower Ground), UG (Upper Ground), L (Level), OD (Observation Deck), P (Parking /
+ *       Podium), RT (Rooftop). These are the values a Geocoded National Address File (GNAF) record
+ *       may carry in the LEVEL_TYPE_CODE column, which mirrors the AP AMAS level-type vocabulary.
+ *   - "LVL" and "LG" appear as widely-recognized surface variants in real AU addresses (Open Addresses
+ *       AU export, accessed via OpenAddresses) though AS 4590.1-2017 and AMAS canonicalize to "L"
+ *       and "LG" respectively; the variants are included in {@link AU_LEVEL_DESIGNATOR_VARIANTS} so
+ *       the parser can RECOGNIZE them without synthesizing them.
+ *
+ * @see {@link https://auspost.com.au/sending/guidelines/addressing-guidelines Australia Post addressing guidelines}
+ * @see {@link https://auspost.com.au/content/dam/auspost_corp/media/documents/correct-addressing.pdf Australia Post Correct Addressing brochure (Nov 2022)}
+ * @see {@link https://auspost.com.au/content/dam/auspost_corp/media/documents/Barcode_hints_tips.pdf Australia Post barcode addressing booklet}
+ * @see {@link https://www.iso.org/standard/67840.html AS 4590.1-2017 — Interchange of client information}
+ */
+
+/**
+ * One AMAS / AS 4590.1 level-type row.
+ *
+ * The `type` is the AS 4590.1 LEVEL_TYPE_CODE value (what GNAF and AMAS use internally); the `abbreviation` is the
+ * approved surface form used in formatted mail; the `requiresNumber` flag distinguishes designators that take a floor
+ * identifier from standalone ones.
+ */
+export interface AuLevelDesignator {
+	/** AS 4590.1 LEVEL_TYPE_CODE (the GNAF / AMAS internal code). */
+	code: string
+	/** Full descriptive name (AMAS table label). */
+	name: string
+	/** The approved AMAS surface abbreviation written on mail ("L", "B", "M"). */
+	abbreviation: string
+	/**
+	 * True when the designator takes a numeric or alphanumeric floor identifier after it (`LEVEL 3`, `BASEMENT 2`). False
+	 * for standalone types (`GROUND`, `MEZZANINE`, `ROOFTOP`) that name a specific well-known floor by vocabulary alone.
+	 */
+	requiresNumber: boolean
+}
+
+/**
+ * AMAS / AS 4590.1-2017 level-type table (Table 3). Verbatim codes; see the module header for provenance. Ordered with
+ * the most-common forms first for match priority.
+ */
+export const AU_LEVEL_DESIGNATORS = [
+	{ code: "L", name: "LEVEL", abbreviation: "L", requiresNumber: true },
+	{ code: "G", name: "GROUND", abbreviation: "G", requiresNumber: false },
+	{ code: "B", name: "BASEMENT", abbreviation: "B", requiresNumber: true },
+	{ code: "M", name: "MEZZANINE", abbreviation: "M", requiresNumber: false },
+	{ code: "LG", name: "LOWER GROUND", abbreviation: "LG", requiresNumber: false },
+	{ code: "UG", name: "UPPER GROUND", abbreviation: "UG", requiresNumber: false },
+	{ code: "OD", name: "OBSERVATION DECK", abbreviation: "OD", requiresNumber: false },
+	{ code: "P", name: "PARKING", abbreviation: "P", requiresNumber: true },
+	{ code: "RT", name: "ROOFTOP", abbreviation: "RT", requiresNumber: false },
+] as const satisfies readonly AuLevelDesignator[]
+
+/** A canonical AS 4590.1 LEVEL_TYPE_CODE. */
+export type AuLevelCode = (typeof AU_LEVEL_DESIGNATORS)[number]["code"]
+
+/**
+ * Recognized surface variants for each AMAS level code — the canonical code/abbreviation pair PLUS additional forms
+ * found in real AU addresses (Open Addresses export) that the parser must RECOGNIZE but the synthesis layer should not
+ * favor over the canonical form.
+ *
+ * Synthesis uses only the first element (the AMAS canonical surface). Recognition accepts all.
+ */
+export const AU_LEVEL_DESIGNATOR_VARIANTS: Readonly<Record<AuLevelCode, readonly string[]>> = {
+	L: ["L", "LEVEL", "LVL", "LEVL", "LEV"],
+	G: ["G", "GROUND", "GRD", "GF", "GROUND FLOOR"],
+	B: ["B", "BASEMENT", "BSMT", "LOWER LEVEL"],
+	M: ["M", "MEZZANINE", "MEZZ", "MEZZANINE LEVEL"],
+	LG: ["LG", "LOWER GROUND", "LOWER GROUND FLOOR"],
+	UG: ["UG", "UPPER GROUND", "UPPER GROUND FLOOR"],
+	OD: ["OD", "OBSERVATION DECK"],
+	P: ["P", "PARKING", "PODIUM"],
+	RT: ["RT", "ROOFTOP", "ROOF"],
+}
+
+/**
+ * Inverse lookup: every variant (abbreviation or surface form) → the canonical AMAS code. Lowercase-keyed for
+ * case-insensitive matching (`"level"` → `"L"`, `"bsmt"` → `"B"`).
+ */
+export const AU_LEVEL_DESIGNATOR_LOOKUP: ReadonlyMap<string, AuLevelCode> = (() => {
+	// Structural integrity check: every code must have at least one non-empty variant. Throw at
+	// module load time so a malformed table entry fails loud rather than silently producing an empty
+	// lexicon (the "builder must round-trip loud" rule from the task contract).
+	for (const { code } of AU_LEVEL_DESIGNATORS) {
+		const variants = AU_LEVEL_DESIGNATOR_VARIANTS[code]
+
+		if (!variants || variants.length === 0) {
+			throw new Error(`[codex/au/level-designator] code "${code}" has no variants in AU_LEVEL_DESIGNATOR_VARIANTS`)
+		}
+
+		for (const v of variants) {
+			if (!v || !v.trim()) {
+				throw new Error(
+					`[codex/au/level-designator] code "${code}" has an empty or blank variant in AU_LEVEL_DESIGNATOR_VARIANTS`
+				)
+			}
+		}
+	}
+	const out = new Map<string, AuLevelCode>()
+
+	for (const { code } of AU_LEVEL_DESIGNATORS) {
+		for (const variant of AU_LEVEL_DESIGNATOR_VARIANTS[code]) {
+			const key = variant.toLowerCase()
+
+			if (!out.has(key)) {
+				out.set(key, code)
+			}
+		}
+	}
+
+	return out
+})()
+
+/** Result of an AU level designator parse. */
+export interface AuLevelDesignatorMatch {
+	/** The code as it appeared in the input ("Level", "L", "lvl"). */
+	matched: string
+	/** The canonical AS 4590.1 LEVEL_TYPE_CODE ("L", "B", "M"). */
+	code: AuLevelCode
+	/** The floor identifier when present ("3", "G", "B2"). */
+	identifier?: string
+}
+
+// One regex per level code. Multi-word variants ("LOWER GROUND", "GROUND FLOOR") are matched
+// before their shorter constituents by ordering the variant list longest-first within each code.
+const LEVEL_MATCHERS: ReadonlyArray<{ code: AuLevelCode; requiresNumber: boolean; re: RegExp }> = (() => {
+	const rows: Array<{ code: AuLevelCode; requiresNumber: boolean; re: RegExp }> = []
+
+	for (const { code, requiresNumber } of AU_LEVEL_DESIGNATORS) {
+		const variants = [...AU_LEVEL_DESIGNATOR_VARIANTS[code]]
+			.sort((a, b) => b.length - a.length)
+			.map((v) => v.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\s+/g, String.raw`\s+`))
+		const alts = variants.join("|")
+		// Identifier: optional alphanumeric (B2, 12, G). requiresNumber=true → identifier required.
+		const tail = requiresNumber
+			? String.raw`\s+([A-Za-z]?\d[\dA-Za-z-]*|\d[\dA-Za-z-]*)`
+			: String.raw`(?:\s+([A-Za-z]?\d[\dA-Za-z-]*|\d[\dA-Za-z-]*))?`
+		rows.push({ code, requiresNumber, re: new RegExp(String.raw`^\s*(${alts})${tail}\s*$`, "i") })
+	}
+
+	return rows
+})()
+
+/**
+ * If `input` is a standalone AU level designator phrase ("Level 3", "L 12", "Ground Floor", "Mezzanine", "B 2"), return
+ * the canonical code and identifier. Null otherwise. Malformed entries (a requires-number designator with no
+ * identifier, e.g. bare "Level") return null — the builder throws loudly when a row in a table violates this
+ * constraint.
+ */
+export function matchAuLevelDesignator(input: unknown): AuLevelDesignatorMatch | null {
+	if (typeof input !== "string") return null
+
+	for (const { code, re } of LEVEL_MATCHERS) {
+		const m = re.exec(input)
+
+		if (!m) continue
+
+		return {
+			matched: m[1]!.trim(),
+			code,
+			...(m[2] ? { identifier: m[2] } : {}),
+		}
+	}
+
+	return null
+}
+
+/** Type-predicate: does the input look like a standalone AU level designator phrase? */
+export function isAuLevelDesignator(input: unknown): boolean {
+	return matchAuLevelDesignator(input) !== null
+}
+
+/**
+ * Normalize a recognized level phrase to the AMAS canonical form (`"level 3"` → `"L 3"`, `"ground floor"` → `"G"`).
+ * Returns the input unchanged if it isn't a level designator phrase. Throws if a row in {@link AU_LEVEL_DESIGNATORS} is
+ * malformed (requires-number entry with no abbreviation or empty name) — the builder must surface structural defects
+ * loudly.
+ */
+export function normalizeAuLevelDesignator(input: string): string {
+	const m = matchAuLevelDesignator(input)
+
+	if (!m) return input
+	const row = AU_LEVEL_DESIGNATORS.find((r) => r.code === m.code)!
+
+	return m.identifier ? `${row.abbreviation} ${m.identifier.toUpperCase()}` : row.abbreviation
+}

package/au/postcode.ts

@@ -0,0 +1,51 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Australian postcodes: four digits, written at the end of the last address line after the locality
+ *   and state (`SYDNEY NSW 2000`). Sourcing (accessed 2026-06-11):
+ *
+ *   - Australia Post's Correct Addressing brochure (SAP 8833878, Nov 2022) — every example carries a
+ *       4-digit postcode and the brochure references envelopes "with preprinted four postcode
+ *       squares".
+ *   - The barcode addressing booklet documents the coarse first-digit → state prior: "if the Postcode
+ *       falls in the range 3000-3999 the State abbreviation will be VIC; 4000-4999 will be QLD,
+ *       etc. … Exceptions to this include ACT Postcodes and Postcodes located on State borders."
+ *       Because the booklet only enumerates VIC and QLD and flags exceptions, this module
+ *       deliberately does NOT ship a full first-digit → state table — the shape is the contract,
+ *       the geographic prior is the gazetteer's job.
+ *
+ *   Note the shape collides with New Zealand's (also 4 digits) — `candidateSystemsForPostcode`
+ *   returns both, and that ambiguity is by design (shape test, not membership test).
+ * @see {@link https://auspost.com.au/content/dam/auspost_corp/media/documents/correct-addressing.pdf Australia Post Correct Addressing brochure (Nov 2022)}
+ * @see {@link https://auspost.com.au/content/dam/auspost_corp/media/documents/Barcode_hints_tips.pdf Australia Post barcode addressing booklet}
+ */
+
+import type { Tagged } from "type-fest"
+
+/**
+ * An Australian postcode: four digits.
+ *
+ * @category Postal
+ * @type string
+ * @title Australian postcode
+ * @pattern ^\d{4}$
+ */
+export type AuPostcode = Tagged<string, "AuPostcode">
+
+/** The AU postcode shape: exactly four digits. */
+export const AU_POSTCODE_PATTERN = /^\d{4}$/
+
+/** Normalize a postcode surface form (trim only — AU has no country-prefix courtesy form). */
+export function normalizeAuPostcode(raw: unknown): AuPostcode | null {
+	if (typeof raw !== "string") return null
+	const s = raw.trim()
+
+	return AU_POSTCODE_PATTERN.test(s) ? (s as AuPostcode) : null
+}
+
+/** Type-predicate for a (normalized) Australian postcode. */
+export function isAuPostcode(input: unknown): input is AuPostcode {
+	return typeof input === "string" && AU_POSTCODE_PATTERN.test(input)
+}

package/au/state.ts

@@ -0,0 +1,35 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Australian states and territories (ISO 3166-2:AU). Australia Post's addressing guidelines put the
+ *   state abbreviation on the last line between the locality and the 4-digit postcode ("Line 3
+ *   should contain the locality or suburb, state and postcode and be written in capital letters" —
+ *   addressing guidelines, accessed 2026-06-11), e.g. `SYDNEY NSW 2000`, `BUNBURY WA 6230`, `EUROA
+ *   VIC 3664`. The abbreviation set is the ISO 3166-2:AU subdivision codes, which are the same
+ *   codes Australia Post's own examples use (NSW, VIC, WA, QLD, ACT appear across the addressing
+ *   guidelines and the barcode booklet).
+ * @see {@link https://auspost.com.au/sending/guidelines/addressing-guidelines Australia Post addressing guidelines}
+ * @see {@link https://www.iso.org/obp/ui/#iso:code:3166:AU ISO 3166-2:AU}
+ */
+
+/** State/territory abbreviation → full name (ISO 3166-2:AU subdivision set). */
+export const AU_STATE_ABBREVIATIONS = {
+	ACT: "Australian Capital Territory",
+	NSW: "New South Wales",
+	NT: "Northern Territory",
+	QLD: "Queensland",
+	SA: "South Australia",
+	TAS: "Tasmania",
+	VIC: "Victoria",
+	WA: "Western Australia",
+} as const satisfies Record<string, string>
+
+/** An Australian state/territory abbreviation as written on the last address line. */
+export type AuStateAbbreviation = keyof typeof AU_STATE_ABBREVIATIONS
+
+/** Type-predicate for an AU state/territory abbreviation (case-insensitive). */
+export function isAuStateAbbreviation(input: unknown): input is AuStateAbbreviation {
+	return typeof input === "string" && Object.hasOwn(AU_STATE_ABBREVIATIONS, input.toUpperCase())
+}

package/ca/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The Canadian address system (Canada Post / ISO 3166-2:CA): bilingual street types, alphanumeric
+ *   postal codes, and the provinces and territories.
+ */
+
+export * from "./postal-code.ts"
+export * from "./province.ts"
+export * from "./street-type.ts"