@mailwoman/codex 7.2.0 → 7.2.1

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailwoman/codex",
-  "version": "7.2.0",
+  "version": "7.2.1",
   "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.2.1"
   }
 }

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
+}

package/tools/build-country-surface-lexicon.ts

@@ -0,0 +1,166 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Build the COUNTRY-SURFACE LEXICON for the country-lexicon soft-feed channel (#1104). This is the
+ *   third atlas channel, a sibling of the postcode anchor (#239/#240) and the gazetteer anchor
+ *   (#464): a per-token multi-hot clue the neural GRAMMAR conditions on but never obeys. Country is a
+ *   CLOSED, ENUMERABLE class (~250 surfaces) — atlas, not grammar — so a dictionary phrase-lookup
+ *   recovers the WOF-admin / resolver hierarchy case ("United States of America, Wyoming, <locality>")
+ *   the learned tagger reads as a leading STREET. Pelias handled the same class the same way
+ *   (`WhosOnFirstClassifier extends PhraseClassifier`); this is the model-first analogue.
+ *
+ *   WHY A DEDICATED LEXICON (not just the gazetteer's `country` slot): the gazetteer already carries
+ *   these surfaces in slot 0, and the shipped model already consumes them — yet the WOF-admin case
+ *   still fails (model-card #1104: golden country recall 82.0% vs 88.6%). The country bit is one of a
+ *   5-hot vector sharing ONE learned projection with region/po_box/cedex/homograph, and it is ZEROED
+ *   adjacent to a postcode by `suppress_gazetteer_near_postcode` (exactly where a trailing "…12345
+ *   USA" sits). A dedicated channel de-entangles the country signal (its own projection + confidence
+ *   weight) and is immune to that suppression. See
+ *   docs/superpowers/plans/2026-07-14-country-lexicon-channel.md.
+ *
+ *   The matcher REUSES the gazetteer's phrase-scan (longest-first n-gram over whitespace words,
+ *   case-insensitive `entries` + uppercase-exact `code_entries`, char→piece projection) — one tested
+ *   algorithm, two vocabularies. Only the vocabulary + the emitted feature differ. The emitted
+ *   feature is 2-dim per piece: `[country_surface, country_ambiguous]`.
+ *
+ *   - `country_surface` (bit 1): the piece is part of a recognized country surface phrase.
+ *   - `country_ambiguous` (bit 2): the SURFACE is a homograph (also a US region) or a common-word
+ *     name ("Georgia", "America", "England", "IN") — a SOFT version of Pelias's hard blacklist. The
+ *     model learns to trust `surface & !ambiguous` (unambiguous long/code forms) strongly and
+ *     `surface & ambiguous` weakly, using context — model-first, never a hard drop, so recall on
+ *     "Republic of Georgia" is preserved.
+ *
+ *   Source of truth: `@mailwoman/codex` (COUNTRY_SURFACE_FORMS + ISO2_TO_NAME) — the SAME data the
+ *   corpus-python bridge `country-surfaces.json` is generated from (export-country-surfaces.ts), so
+ *   the channel and the corpus shard synthesizer cannot diverge on what a country surface IS.
+ *
+ *   Output: data/gazetteer/country-surface-lexicon-v1.json (small, committed, provenance-tracked).
+ *   Regenerate: `node codex/tools/build-country-surface-lexicon.ts`
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+
+import { COUNTRY_SURFACE_FORMS, ISO2_TO_NAME } from "../country/country.ts"
+import { US_STATE_ABBREVIATIONS, US_STATE_NAMES } from "../us/state.ts"
+
+const BIT = { country_surface: 1, country_ambiguous: 2 }
+const SLOTS = ["country_surface", "country_ambiguous"]
+
+// Committed output path (a codex-derived artifact, like export-country-surfaces.ts — no argv, so the
+// no-process-globals lint policy holds; codex stays zero-runtime-dep).
+const OUTPUT = resolve(import.meta.dirname, "../../data/gazetteer/country-surface-lexicon-v1.json")
+
+/**
+ * THE shared word-normalization rule (identical to build-gazetteer-anchor-lexicon.mjs and mirrored in
+ * gazetteer_char_paint on both sides): per whitespace-word, strip LEADING/TRAILING characters that are not Unicode
+ * letters or digits (keep internal ones: "u.s.a", "timor-leste"), rejoin single-spaced. Entry keys and scanned tokens
+ * both pass through it, so "U.S.A." ≡ "u.s.a".
+ */
+const wordNorm = (s: string): string =>
+	s
+		.split(/\s+/)
+		.map((w) => w.replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, ""))
+		.filter(Boolean)
+		.join(" ")
+
+const norm = (s: string): string => wordNorm(s).toLowerCase()
+
+/** Short alphabetic code (≤3 letters once punctuation is dropped) → exact-uppercase matching. */
+const isShortCode = (s: string): boolean => {
+	const letters = s.replace(/[^\p{L}]/gu, "")
+
+	return letters.length > 0 && letters.length <= 3 && /^[\p{L}.\s]+$/u.test(s)
+}
+
+// Homograph set: a single-word country surface that is ALSO a US region (name or abbreviation) reads
+// ambiguously (Georgia the country vs the state, IN = India vs Indiana). Computed from codex so it
+// tracks the US region table, never hand-maintained.
+const usStateNames = new Set(US_STATE_NAMES.map((n) => n.toLowerCase()))
+const usStateAbbrevs = new Set<string>(US_STATE_ABBREVIATIONS as readonly string[])
+
+// Curated common-word country surfaces — single tokens that appear far more often as ordinary
+// street/venue/locality words than as a trailing country. A SOFT flag (the model still decides), the
+// model-first analogue of Pelias's blacklist (north/south/east/west/street/city/king). Tunable.
+const COMMON_WORD_AMBIGUOUS = new Set(["america", "england", "britain", "turkey", "chad", "jordan", "jersey", "guinea"])
+
+const isAmbiguousName = (lowerKey: string): boolean => usStateNames.has(lowerKey) || COMMON_WORD_AMBIGUOUS.has(lowerKey)
+
+// surface → bits, split across the two match-rule maps (mirrors the gazetteer builder).
+const entries = new Map<string, number>() // lowercase key
+const codeEntries = new Map<string, number>() // exact-uppercase key
+let maxNgram = 1
+
+function add(surface: string): void {
+	const s = surface.trim()
+
+	if (!s) return
+
+	if (isShortCode(s)) {
+		const key = wordNorm(s).toUpperCase()
+
+		if (!key) return
+		// A code that collides with a US-state abbreviation (CA/IN/AL/CO/…) is a homograph → ambiguous.
+		const bits = BIT.country_surface | (usStateAbbrevs.has(key) ? BIT.country_ambiguous : 0)
+		codeEntries.set(key, (codeEntries.get(key) ?? 0) | bits)
+
+		return
+	}
+	const key = norm(s)
+
+	if (!key) return
+	const words = key.split(" ")
+	maxNgram = Math.max(maxNgram, words.length)
+	// Multi-word phrases are unambiguous by construction; single tokens consult the homograph +
+	// common-word rule.
+	const ambiguous = words.length === 1 && isAmbiguousName(key)
+	const bits = BIT.country_surface | (ambiguous ? BIT.country_ambiguous : 0)
+	entries.set(key, (entries.get(key) ?? 0) | bits)
+}
+
+// Curated rich surface forms first (US/GB/DE/… endonyms + abbreviations), then the canonical English
+// name for every remaining ISO 3166-1 alpha-2 — exactly the merge country-surfaces.json performs.
+for (const forms of Object.values(COUNTRY_SURFACE_FORMS)) {
+	for (const f of forms) {
+		add(f)
+	}
+}
+
+for (const [, name] of ISO2_TO_NAME) {
+	add(name)
+}
+
+const ambiguousEntries = [...entries, ...codeEntries].filter(([, b]) => b & BIT.country_ambiguous).map(([k]) => k)
+
+const lexicon = {
+	version: 1,
+	generated_by:
+		"codex/tools/build-country-surface-lexicon.ts (source: @mailwoman/codex COUNTRY_SURFACE_FORMS + ISO2_TO_NAME)",
+	feature_dim: SLOTS.length,
+	slots: SLOTS,
+	bits: BIT,
+	max_ngram: maxNgram,
+	rules: {
+		word_norm:
+			"per whitespace-word: strip leading/trailing chars that are not Unicode letters/digits " +
+			"(keep internal: 'timor-leste', 'u.s.a'); rejoin single-spaced. Applied to BOTH entry keys and scanned tokens.",
+		entries:
+			"case-insensitive; key = word_norm lowercased. country_surface always set; country_ambiguous set for single-token homographs (US region) or curated common-word names.",
+		code_entries:
+			"case-SENSITIVE exact: word_norm(token) == key (keys uppercase; 'in' the word ≠ 'IN' India). n-gram length 1. country_ambiguous set when the code is also a US-state abbreviation.",
+		scan: "longest-first n-gram over whitespace words, left to right, non-overlapping (shared with the gazetteer matcher)",
+		feature:
+			"emitted per-piece row = [country_surface, country_ambiguous] (the raw bits); confidence = 1.0 where country_surface fires.",
+	},
+	entries: Object.fromEntries([...entries].sort(([a], [b]) => a.localeCompare(b))),
+	code_entries: Object.fromEntries([...codeEntries].sort(([a], [b]) => a.localeCompare(b))),
+}
+
+mkdirSync(dirname(OUTPUT), { recursive: true })
+writeFileSync(OUTPUT, JSON.stringify(lexicon, null, 1) + "\n")
+process.stderr.write(
+	`wrote ${OUTPUT}: ${entries.size} entries + ${codeEntries.size} code_entries, ` +
+		`max_ngram=${maxNgram}, ${ambiguousEntries.length} ambiguous: ${ambiguousEntries.slice(0, 12).join(", ")}${ambiguousEntries.length > 12 ? ", …" : ""}\n`
+)