@mailwoman/codex 9.2.0 → 9.4.0

package/{it → lib/it}/cap.ts

@@ -30,10 +30,28 @@ export type CAP = Tagged<string, "CAP">
 export const CAP_PATTERN = /^\d{5}$/
 
 /**
- * Narrow a string to a {@link CAP}, or `null` when it is not one.
+ * Normalize a CAP surface form to the bare five digits: trim surrounding whitespace (`" 00184 "` → `"00184"`). Returns
+ * null when the result is not a five-digit code.
  */
-export function parseCAP(input: string): CAP | null {
-	const s = input.trim()
+export function normalizeCAP(raw: unknown): CAP | null {
+	if (typeof raw !== "string") return null
+	const s = raw.trim()
 
 	return CAP_PATTERN.test(s) ? (s as CAP) : null
 }
+
+/**
+ * Type-predicate for a (normalized) Italian CAP.
+ */
+export function isCAP(input: unknown): input is CAP {
+	return typeof input === "string" && CAP_PATTERN.test(input)
+}
+
+/**
+ * Narrow a string to a {@link CAP}, or `null` when it is not one.
+ *
+ * @deprecated Use {@link normalizeCAP}.
+ */
+export function parseCAP(input: string): CAP | null {
+	return normalizeCAP(input)
+}

package/{it → lib/it}/index.ts

@@ -6,4 +6,4 @@
  *   Italian (IT) address-system reference data.
  */
 
-export * from "./cap.ts"
+export * from "#it/cap"

package/{jp → lib/jp}/index.ts

@@ -8,6 +8,7 @@
  *   in for the street names Japan does not use.
  */
 
-export * from "./address-unit.ts"
-export * from "./postal-code.ts"
-export * from "./prefecture.ts"
+export * from "#jp/address-unit"
+export * from "#jp/municipality-register"
+export * from "#jp/postal-code"
+export * from "#jp/prefecture"

package/lib/jp/municipality-register.ts

@@ -0,0 +1,62 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The towns whose own name carries the city marker 市 (shi) before the town suffix 町 / 村 (chō / son).
+ *
+ *   A Japanese municipality span closes at 市 in the ordinary case (`富山市`, `神戸市西区`), and a character model
+ *   learns that boundary from 1,700 cities. A town whose NAME contains 市 defeats it: `中新川郡上市町` reads as the
+ *   city `上市` plus a district beginning with 町. Over the 1,892 municipalities in Japan Post's KEN_ALL list the
+ *   shape has six members, so the boundary is stated here rather than learned — a positive attestation from the
+ *   postal register, consumed after decode by `@mailwoman/neural`'s JP municipality repair. Two of the six (`上市町`,
+ *   `下市町`) put 市 immediately before the suffix, the boundary the model closes at; the other four are listed for the same
+ *   repair so an early close inside them is also repaired.
+ */
+
+import { completeFromRegister } from "#register-completion"
+
+/**
+ * One town from Japan Post's KEN_ALL municipality list whose own name contains 市.
+ */
+export interface JapaneseInnerShiTown {
+	/**
+	 * The prefecture, as written (`富山県`).
+	 */
+	prefecture: string
+	/**
+	 * The county (郡) the town belongs to, as the postal form writes it before the town.
+	 */
+	county: string
+	/**
+	 * The town's own name with its suffix (`上市町`).
+	 */
+	town: string
+}
+
+/**
+ * The six towns, from KEN_ALL (1,892 municipalities). Ordered by prefecture code.
+ */
+export const JP_INNER_SHI_TOWNS: readonly JapaneseInnerShiTown[] = [
+	{ prefecture: "北海道", county: "余市郡", town: "余市町" },
+	{ prefecture: "栃木県", county: "芳賀郡", town: "市貝町" },
+	{ prefecture: "富山県", county: "中新川郡", town: "上市町" },
+	{ prefecture: "山梨県", county: "西八代郡", town: "市川三郷町" },
+	{ prefecture: "奈良県", county: "吉野郡", town: "下市町" },
+	{ prefecture: "兵庫県", county: "神崎郡", town: "市川町" },
+]
+
+/**
+ * Every surface a municipality span may legitimately close on for these towns: the postal form with the county
+ * (`中新川郡上市町`) and the bare town (`上市町`).
+ */
+export const JP_INNER_SHI_TOWN_NAMES: readonly string[] = JP_INNER_SHI_TOWNS.flatMap((t) => [t.county + t.town, t.town])
+
+/**
+ * The characters a municipality surface must absorb from what follows it to become one of the register's names, or null
+ * when no name extends it. `following` is the text after the surface; the answer is a prefix of it. A surface that
+ * already IS a register name answers null: nothing to absorb.
+ */
+export function jpMunicipalityCompletion(surface: string, following: string): string | null {
+	return completeFromRegister(JP_INNER_SHI_TOWN_NAMES, surface, following)
+}

package/{jp → lib/jp}/prefecture.ts

@@ -6,7 +6,10 @@
  *   The 47 Japanese prefectures (都道府県, todōfuken), keyed by their ISO 3166-2:JP code — the two-digit
  *   numeric string `"01"`..`"47"` standing in for `JP-01`..`JP-47`.
  *
- *   The contrast with `fr/region.ts`, `de/bundesland.ts`, and `us/state.ts` is in the name itself.
+ *   Compared to `fr/region.ts`, `de/bundesland.ts`, and `us/state.ts`,
+ * 	 this is a more complex case because the top-level admin unit comes in four legally distinct flavours,
+ *   and the prefecture name is written on the address line (not inferred from postcode).
+ *
  *   "都道府県" is four kanji because the top-level admin unit comes in four legally distinct flavours,
  *   even though all 47 are peers in practice:
  *
@@ -23,6 +26,8 @@
  *   `postal-code.ts` for why the postcode is nonetheless the single most reliable anchor.
  */
 
+import { foldToken } from "#normalize"
+
 /**
  * A to/dō/fu/ken classification of the top-level admin unit.
  */
@@ -130,10 +135,7 @@ export function isJapanesePrefectureCode(input: unknown): input is JapanesePrefe
  * them. We never strip from an unseparated bare name, so `kyoto` stays `kyoto`.
  */
 function foldRomaji(s: string): string {
-	const lowered = s
-		.toLowerCase()
-		.normalize("NFD")
-		.replaceAll(/[\u0300-\u036F]/g, "")
+	const lowered = foldToken(s)
 
 	// Strip an appended type-suffix only when a separator (hyphen / space / middle dot) precedes it.
 	const desuffixed = lowered.replace(/[-\s·][\s]*(to|do|fu|ken)$/, "")

package/lib/kr/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The Korean address system as the road-name address register (도로명주소) writes it: the 시군구 register the
+ *   decode-time boundary repair reads.
+ */
+
+export * from "#kr/sigungu-register"

package/lib/kr/sigungu-register.ts

@@ -0,0 +1,294 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The Korean 시군구 (si / gun / gu: the second administrative tier) as the road-name address register writes them,
+ *   each under its 시/도 (the first tier). 249 pairs over 226 distinct names; a compound city is
+ *   one name (`성남시분당구`), the way the register keys it. 세종특별자치시 has no second tier and is absent.
+ *
+ *   Why a register: a character model closes a `subregion` span where the training set taught it names end, and a
+ *   name it never saw (`해운대구`, held out of the training corpus by the board's design and unseen by the shipped
+ *   model for the same reason) closes early, at `해` or `해운대`. The register states every boundary outright, so the
+ *   decode-time repair in `@mailwoman/neural` extends a run to the one name the following characters spell.
+ *
+ *   Source: 행정안전부 (Ministry of the Interior and Safety), 도로명주소 (juso.go.kr), 공공누리 제1유형 (KOGL Type 1):
+ *   attribution required; commercial use, derivatives and redistribution permitted.
+ */
+
+import { completeFromRegister } from "#register-completion"
+
+/**
+ * One second-tier unit under its first-tier region, both as the register writes them.
+ */
+export interface KoreanSigungu {
+	region: string
+	city: string
+}
+
+/**
+ * The register: every (시/도, 시군구) pair the road-name address register carries, in register order.
+ */
+export const KR_SIGUNGU: readonly KoreanSigungu[] = [
+	{ region: "강원도", city: "강릉시" },
+	{ region: "강원도", city: "고성군" },
+	{ region: "강원도", city: "동해시" },
+	{ region: "강원도", city: "삼척시" },
+	{ region: "강원도", city: "속초시" },
+	{ region: "강원도", city: "양구군" },
+	{ region: "강원도", city: "양양군" },
+	{ region: "강원도", city: "영월군" },
+	{ region: "강원도", city: "원주시" },
+	{ region: "강원도", city: "인제군" },
+	{ region: "강원도", city: "정선군" },
+	{ region: "강원도", city: "철원군" },
+	{ region: "강원도", city: "춘천시" },
+	{ region: "강원도", city: "태백시" },
+	{ region: "강원도", city: "평창군" },
+	{ region: "강원도", city: "홍천군" },
+	{ region: "강원도", city: "화천군" },
+	{ region: "강원도", city: "횡성군" },
+	{ region: "경기도", city: "가평군" },
+	{ region: "경기도", city: "고양시덕양구" },
+	{ region: "경기도", city: "고양시일산동구" },
+	{ region: "경기도", city: "고양시일산서구" },
+	{ region: "경기도", city: "과천시" },
+	{ region: "경기도", city: "광명시" },
+	{ region: "경기도", city: "광주시" },
+	{ region: "경기도", city: "구리시" },
+	{ region: "경기도", city: "군포시" },
+	{ region: "경기도", city: "김포시" },
+	{ region: "경기도", city: "남양주시" },
+	{ region: "경기도", city: "동두천시" },
+	{ region: "경기도", city: "부천시" },
+	{ region: "경기도", city: "성남시분당구" },
+	{ region: "경기도", city: "성남시수정구" },
+	{ region: "경기도", city: "성남시중원구" },
+	{ region: "경기도", city: "수원시권선구" },
+	{ region: "경기도", city: "수원시영통구" },
+	{ region: "경기도", city: "수원시장안구" },
+	{ region: "경기도", city: "수원시팔달구" },
+	{ region: "경기도", city: "시흥시" },
+	{ region: "경기도", city: "안산시단원구" },
+	{ region: "경기도", city: "안산시상록구" },
+	{ region: "경기도", city: "안성시" },
+	{ region: "경기도", city: "안양시동안구" },
+	{ region: "경기도", city: "안양시만안구" },
+	{ region: "경기도", city: "양주시" },
+	{ region: "경기도", city: "양평군" },
+	{ region: "경기도", city: "여주시" },
+	{ region: "경기도", city: "연천군" },
+	{ region: "경기도", city: "오산시" },
+	{ region: "경기도", city: "용인시기흥구" },
+	{ region: "경기도", city: "용인시수지구" },
+	{ region: "경기도", city: "용인시처인구" },
+	{ region: "경기도", city: "의왕시" },
+	{ region: "경기도", city: "의정부시" },
+	{ region: "경기도", city: "이천시" },
+	{ region: "경기도", city: "파주시" },
+	{ region: "경기도", city: "평택시" },
+	{ region: "경기도", city: "포천시" },
+	{ region: "경기도", city: "하남시" },
+	{ region: "경기도", city: "화성시" },
+	{ region: "경상남도", city: "거제시" },
+	{ region: "경상남도", city: "거창군" },
+	{ region: "경상남도", city: "고성군" },
+	{ region: "경상남도", city: "김해시" },
+	{ region: "경상남도", city: "남해군" },
+	{ region: "경상남도", city: "밀양시" },
+	{ region: "경상남도", city: "사천시" },
+	{ region: "경상남도", city: "산청군" },
+	{ region: "경상남도", city: "양산시" },
+	{ region: "경상남도", city: "의령군" },
+	{ region: "경상남도", city: "진주시" },
+	{ region: "경상남도", city: "창녕군" },
+	{ region: "경상남도", city: "창원시마산합포구" },
+	{ region: "경상남도", city: "창원시마산회원구" },
+	{ region: "경상남도", city: "창원시성산구" },
+	{ region: "경상남도", city: "창원시의창구" },
+	{ region: "경상남도", city: "창원시진해구" },
+	{ region: "경상남도", city: "통영시" },
+	{ region: "경상남도", city: "하동군" },
+	{ region: "경상남도", city: "함안군" },
+	{ region: "경상남도", city: "함양군" },
+	{ region: "경상남도", city: "합천군" },
+	{ region: "경상북도", city: "경산시" },
+	{ region: "경상북도", city: "경주시" },
+	{ region: "경상북도", city: "고령군" },
+	{ region: "경상북도", city: "구미시" },
+	{ region: "경상북도", city: "군위군" },
+	{ region: "경상북도", city: "김천시" },
+	{ region: "경상북도", city: "문경시" },
+	{ region: "경상북도", city: "봉화군" },
+	{ region: "경상북도", city: "상주시" },
+	{ region: "경상북도", city: "성주군" },
+	{ region: "경상북도", city: "안동시" },
+	{ region: "경상북도", city: "영덕군" },
+	{ region: "경상북도", city: "영양군" },
+	{ region: "경상북도", city: "영주시" },
+	{ region: "경상북도", city: "영천시" },
+	{ region: "경상북도", city: "예천군" },
+	{ region: "경상북도", city: "울릉군" },
+	{ region: "경상북도", city: "울진군" },
+	{ region: "경상북도", city: "의성군" },
+	{ region: "경상북도", city: "청도군" },
+	{ region: "경상북도", city: "청송군" },
+	{ region: "경상북도", city: "칠곡군" },
+	{ region: "경상북도", city: "포항시남구" },
+	{ region: "경상북도", city: "포항시북구" },
+	{ region: "광주광역시", city: "광산구" },
+	{ region: "광주광역시", city: "남구" },
+	{ region: "광주광역시", city: "동구" },
+	{ region: "광주광역시", city: "북구" },
+	{ region: "광주광역시", city: "서구" },
+	{ region: "대구광역시", city: "남구" },
+	{ region: "대구광역시", city: "달서구" },
+	{ region: "대구광역시", city: "달성군" },
+	{ region: "대구광역시", city: "동구" },
+	{ region: "대구광역시", city: "북구" },
+	{ region: "대구광역시", city: "서구" },
+	{ region: "대구광역시", city: "수성구" },
+	{ region: "대구광역시", city: "중구" },
+	{ region: "대전광역시", city: "대덕구" },
+	{ region: "대전광역시", city: "동구" },
+	{ region: "대전광역시", city: "서구" },
+	{ region: "대전광역시", city: "유성구" },
+	{ region: "대전광역시", city: "중구" },
+	{ region: "부산광역시", city: "강서구" },
+	{ region: "부산광역시", city: "금정구" },
+	{ region: "부산광역시", city: "기장군" },
+	{ region: "부산광역시", city: "남구" },
+	{ region: "부산광역시", city: "동구" },
+	{ region: "부산광역시", city: "동래구" },
+	{ region: "부산광역시", city: "부산진구" },
+	{ region: "부산광역시", city: "북구" },
+	{ region: "부산광역시", city: "사상구" },
+	{ region: "부산광역시", city: "사하구" },
+	{ region: "부산광역시", city: "서구" },
+	{ region: "부산광역시", city: "수영구" },
+	{ region: "부산광역시", city: "연제구" },
+	{ region: "부산광역시", city: "영도구" },
+	{ region: "부산광역시", city: "중구" },
+	{ region: "부산광역시", city: "해운대구" },
+	{ region: "서울특별시", city: "강남구" },
+	{ region: "서울특별시", city: "강동구" },
+	{ region: "서울특별시", city: "강북구" },
+	{ region: "서울특별시", city: "강서구" },
+	{ region: "서울특별시", city: "관악구" },
+	{ region: "서울특별시", city: "광진구" },
+	{ region: "서울특별시", city: "구로구" },
+	{ region: "서울특별시", city: "금천구" },
+	{ region: "서울특별시", city: "노원구" },
+	{ region: "서울특별시", city: "도봉구" },
+	{ region: "서울특별시", city: "동대문구" },
+	{ region: "서울특별시", city: "동작구" },
+	{ region: "서울특별시", city: "마포구" },
+	{ region: "서울특별시", city: "서대문구" },
+	{ region: "서울특별시", city: "서초구" },
+	{ region: "서울특별시", city: "성동구" },
+	{ region: "서울특별시", city: "성북구" },
+	{ region: "서울특별시", city: "송파구" },
+	{ region: "서울특별시", city: "양천구" },
+	{ region: "서울특별시", city: "영등포구" },
+	{ region: "서울특별시", city: "용산구" },
+	{ region: "서울특별시", city: "은평구" },
+	{ region: "서울특별시", city: "종로구" },
+	{ region: "서울특별시", city: "중구" },
+	{ region: "서울특별시", city: "중랑구" },
+	{ region: "울산광역시", city: "남구" },
+	{ region: "울산광역시", city: "동구" },
+	{ region: "울산광역시", city: "북구" },
+	{ region: "울산광역시", city: "울주군" },
+	{ region: "울산광역시", city: "중구" },
+	{ region: "인천광역시", city: "강화군" },
+	{ region: "인천광역시", city: "계양구" },
+	{ region: "인천광역시", city: "남구" },
+	{ region: "인천광역시", city: "남동구" },
+	{ region: "인천광역시", city: "동구" },
+	{ region: "인천광역시", city: "부평구" },
+	{ region: "인천광역시", city: "서구" },
+	{ region: "인천광역시", city: "연수구" },
+	{ region: "인천광역시", city: "옹진군" },
+	{ region: "인천광역시", city: "중구" },
+	{ region: "전라남도", city: "강진군" },
+	{ region: "전라남도", city: "고흥군" },
+	{ region: "전라남도", city: "곡성군" },
+	{ region: "전라남도", city: "광양시" },
+	{ region: "전라남도", city: "구례군" },
+	{ region: "전라남도", city: "나주시" },
+	{ region: "전라남도", city: "담양군" },
+	{ region: "전라남도", city: "목포시" },
+	{ region: "전라남도", city: "무안군" },
+	{ region: "전라남도", city: "보성군" },
+	{ region: "전라남도", city: "순천시" },
+	{ region: "전라남도", city: "신안군" },
+	{ region: "전라남도", city: "여수시" },
+	{ region: "전라남도", city: "영광군" },
+	{ region: "전라남도", city: "영암군" },
+	{ region: "전라남도", city: "완도군" },
+	{ region: "전라남도", city: "장성군" },
+	{ region: "전라남도", city: "장흥군" },
+	{ region: "전라남도", city: "진도군" },
+	{ region: "전라남도", city: "함평군" },
+	{ region: "전라남도", city: "해남군" },
+	{ region: "전라남도", city: "화순군" },
+	{ region: "전라북도", city: "고창군" },
+	{ region: "전라북도", city: "군산시" },
+	{ region: "전라북도", city: "김제시" },
+	{ region: "전라북도", city: "남원시" },
+	{ region: "전라북도", city: "무주군" },
+	{ region: "전라북도", city: "부안군" },
+	{ region: "전라북도", city: "순창군" },
+	{ region: "전라북도", city: "완주군" },
+	{ region: "전라북도", city: "익산시" },
+	{ region: "전라북도", city: "임실군" },
+	{ region: "전라북도", city: "장수군" },
+	{ region: "전라북도", city: "전주시덕진구" },
+	{ region: "전라북도", city: "전주시완산구" },
+	{ region: "전라북도", city: "정읍시" },
+	{ region: "전라북도", city: "진안군" },
+	{ region: "제주특별자치도", city: "서귀포시" },
+	{ region: "제주특별자치도", city: "제주시" },
+	{ region: "충청남도", city: "계룡시" },
+	{ region: "충청남도", city: "공주시" },
+	{ region: "충청남도", city: "금산군" },
+	{ region: "충청남도", city: "논산시" },
+	{ region: "충청남도", city: "당진시" },
+	{ region: "충청남도", city: "보령시" },
+	{ region: "충청남도", city: "부여군" },
+	{ region: "충청남도", city: "서산시" },
+	{ region: "충청남도", city: "서천군" },
+	{ region: "충청남도", city: "아산시" },
+	{ region: "충청남도", city: "예산군" },
+	{ region: "충청남도", city: "천안시동남구" },
+	{ region: "충청남도", city: "천안시서북구" },
+	{ region: "충청남도", city: "청양군" },
+	{ region: "충청남도", city: "태안군" },
+	{ region: "충청남도", city: "홍성군" },
+	{ region: "충청북도", city: "괴산군" },
+	{ region: "충청북도", city: "단양군" },
+	{ region: "충청북도", city: "보은군" },
+	{ region: "충청북도", city: "영동군" },
+	{ region: "충청북도", city: "옥천군" },
+	{ region: "충청북도", city: "음성군" },
+	{ region: "충청북도", city: "제천시" },
+	{ region: "충청북도", city: "증평군" },
+	{ region: "충청북도", city: "진천군" },
+	{ region: "충청북도", city: "청주시상당구" },
+	{ region: "충청북도", city: "청주시서원구" },
+	{ region: "충청북도", city: "청주시청원구" },
+	{ region: "충청북도", city: "청주시흥덕구" },
+	{ region: "충청북도", city: "충주시" },
+]
+
+/**
+ * Every 시군구 name a `subregion` span may close on.
+ */
+export const KR_SIGUNGU_NAMES: readonly string[] = [...new Set(KR_SIGUNGU.map((s) => s.city))]
+
+/**
+ * The characters a `subregion` surface must absorb from what follows it to become a register name, or null.
+ */
+export function krSubregionCompletion(surface: string, following: string): string | null {
+	return completeFromRegister(KR_SIGUNGU_NAMES, surface, following)
+}

package/{normalize.ts → lib/normalize.ts}

@@ -41,7 +41,7 @@ export function wordNorm(s: string): string {
 	return s
 		.split(/\s+/)
 		.map((w) => w.replaceAll(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, ""))
-		.filter(Boolean)
+		.filter((w) => w.length > 0)
 		.join(" ")
 }
 
@@ -51,3 +51,17 @@ export function wordNorm(s: string): string {
 export function wordNormLower(s: string): string {
 	return wordNorm(s).toLowerCase()
 }
+
+/**
+ * Fold a single token to its lowercase, diacritic-free form: lower-cased, NFD-decomposed, combining marks stripped —
+ * `"Côte"` → `"cote"`, `"Tōkyō"` → `"tokyo"`.
+ *
+ * The shared core of the per-country token matchers. Unlike {@link foldName} it does not touch punctuation or whitespace
+ * — each matcher layers its own character filtering (letters-only, hyphen-keeping, suffix-stripping) on top.
+ */
+export function foldToken(s: string): string {
+	return s
+		.toLowerCase()
+		.normalize("NFD")
+		.replaceAll(/[\u0300-\u036F]/g, "")
+}

package/{nz → lib/nz}/delivery-service.ts

@@ -33,7 +33,7 @@
  *   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
+ *   — codex documents it unofficial/colloquial WITH the 'officially invalid' citation; the extract
  *   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.

package/{nz → lib/nz}/index.ts

@@ -8,5 +8,5 @@
  *   Restante) and the 4-digit postcode. NZ addresses carry no state/region line.
  */
 
-export * from "./delivery-service.ts"
-export * from "./postcode.ts"
+export * from "#nz/delivery-service"
+export * from "#nz/postcode"

package/{postcode-systems.ts → lib/postcode-systems.ts}

@@ -10,30 +10,32 @@
  *
  *   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
+ *   pipeline's `@mailwoman/locale-hint` stage (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
+ *   German, French, Spanish and Italian 5-digit shapes, so it returns `["us", "de", "fr", "es", "it"]` —
+ *   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"
+import { normalizeAuPostcode } from "#au/index"
+import { normalizeCaPostalCode } from "#ca/index"
+import { normalizePLZ } from "#de/index"
+import { normalizeCodigoPostal } from "#es/index"
+import { normalizeCodePostal } from "#fr/index"
+import { normalizeUkPostcode } from "#gb/index"
+import { normalizeCAP } from "#it/index"
+import { normalizeJpPostalCode } from "#jp/index"
+import { normalizeNZPostcode } from "#nz/index"
+import { isZipCode } from "#us/index"
 
 /**
  * A codex address-system code — the subpath under `@mailwoman/codex/<system>`.
  */
-export type SystemCode = "us" | "de" | "fr" | "ca" | "gb" | "jp" | "au" | "nz"
+export type SystemCode = "us" | "de" | "fr" | "es" | "it" | "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
@@ -44,6 +46,8 @@ const SYSTEM_ACCEPTS: ReadonlyArray<readonly [SystemCode, (s: string) => boolean
 	["us", (s) => isZipCode(s)],
 	["de", (s) => normalizePLZ(s) !== null],
 	["fr", (s) => normalizeCodePostal(s) !== null],
+	["es", (s) => normalizeCodigoPostal(s) !== null],
+	["it", (s) => normalizeCAP(s) !== null],
 	["ca", (s) => normalizeCaPostalCode(s) !== null],
 	["gb", (s) => normalizeUkPostcode(s) !== null],
 	["jp", (s) => normalizeJpPostalCode(s) !== null],
@@ -51,6 +55,12 @@ const SYSTEM_ACCEPTS: ReadonlyArray<readonly [SystemCode, (s: string) => boolean
 	["nz", (s) => normalizeNZPostcode(s) !== null],
 ]
 
+/**
+ * Every address system with a postcode shape, in {@link SYSTEM_ACCEPTS} order. The one list a consumer that needs the
+ * universe of systems (rather than the systems a given code fits) should read, so it cannot drift from the table.
+ */
+export const SYSTEM_CODES: readonly SystemCode[] = SYSTEM_ACCEPTS.map(([system]) => system)
+
 /**
  * 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
@@ -156,22 +166,28 @@ export function isUnitGradePostcodeHit(parsed: string, resolverName: string | un
  * Membership is earned by a full-panel measurement, the same bar {@link UNIT_GRADE_POSTCODE} sets for CA. Coordinate
  * p50 on the OpenAddresses panels, locality-first (the default) against the postcode point:
  *
- * | country | rows  | locality-first | postcode point | verdict                                                            |
- * | ------- | ----: | -------------: | -------------: | ------------------------------------------------------------------ |
- * | **DE**  | 2,997 | 5.84 km        | **1.24 km**    | postcode, on EVERY percentile incl. p99 (21.50 → 10.57)            |
- * | FR      | 3,000 | **0.97 km**    | 2.64 km        | locality, closer on 77.5% of rows                                  |
- * | IT      | 2,833 | **1.34 km**    | 3.05 km        | locality, closer on 66.4%                                          |
- * | ES      | 2,929 | **0.68 km**    | 0.97 km        | locality, but near a coin flip — 46.1% of rows prefer the postcode |
- * | US      | 577   | **2.28 km**    | 4.15 km        | locality (see below)                                               |
+ * | country | rows  | locality-first | postcode point | verdict                                                                |
+ * | ------- | ----: | -------------: | -------------: | ---------------------------------------------------------------------- |
+ * | **DE**  | 2,997 | 5.84 km        | **1.24 km**    | postcode, on EVERY percentile incl. p99 (21.50 → 10.57)                |
+ * | FR      | 3,000 | **0.97 km**    | 2.64 km        | locality, closer on 77.5% of rows                                      |
+ * | IT      | 2,833 | **1.34 km**    | 3.05 km        | locality, closer on 66.4%                                              |
+ * | ES      | 2,929 | **0.68 km**    | 0.97 km        | locality, but near a coin flip — 46.1% of rows prefer the postcode     |
+ * | US      | 577   | **2.28 km**    | 4.15 km        | locality (see below)                                                   |
+ * | **JP**  | 586   | 4.93 km        | **0.48 km**    | postcode, closer on 97.3% of rows (p90 13.55 → 1.21, p99 19.63 → 3.54) |
  *
  * **The US row is measured on the population production actually sends to the ladder.** Its rooftop cascade is US-only
  * by construction (`selectAddressPointsDB` composes `address-points-us-<slug>.db`), and it serves 94.2% of US queries,
- * so only 577 of 10,000 panel rows reach an admin decision at all. Those are the rows no rooftop or interpolation shard
- * could place, which skews rural — exactly where a locality centroid sits close and a ZIP zone is wide. Measured over
- * all 10,000 rows instead, the US looks like a postcode-first country (2.41 km vs 3.63); that is a selection effect,
- * and it is why this table reports 577 rows for the US and full panels for the others, which have no such cascade.
+ * so only 577 of 10,000 panel rows reach an admin decision at all. Those are the rows no rooftop or interpolation
+ * extract could place, which skews rural — exactly where a locality centroid sits close and a ZIP zone is wide.
+ * Measured over all 10,000 rows instead, the US looks like a postcode-first country (2.41 km vs 3.63); that is a
+ * selection effect, and it is why this table reports 577 rows for the US and full panels for the others, which have no
+ * such cascade.
+ *
+ * **The JP row is the JP board through the served path** (`jp-served-resolve.run.ts`, 2,000 rows, seed 42): the 586
+ * rows carrying a postcode the candidate table keys, graded on the row's own entrance point — the locality-first answer
+ * is the municipality centroid, the postcode answer the code's 町域 centroid from the WOF extract.
  */
-export const AREA_POSTCODE_FINER_THAN_LOCALITY: ReadonlySet<string> = new Set(["DE"])
+export const AREA_POSTCODE_FINER_THAN_LOCALITY: ReadonlySet<string> = new Set(["DE", "JP"])
 
 /**
  * True when this country's area-grade postal code outranks its locality. Absent or unknown country → false, so the

package/lib/register-completion.ts

@@ -0,0 +1,24 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The one read every name register offers a decode-time repair: given the surface a model closed a span on and the
+ *   text that follows, the characters that would extend the surface to a register name. A surface that already IS a
+ *   name and is not the prefix of a longer one answers null.
+ */
+
+/**
+ * The remainder of the first register name that begins with `surface` and continues into `following`, or null.
+ */
+export function completeFromRegister(names: readonly string[], surface: string, following: string): string | null {
+	for (const name of names) {
+		if (name.length > surface.length && name.startsWith(surface)) {
+			const remainder = name.slice(surface.length)
+
+			if (following.startsWith(remainder)) return remainder
+		}
+	}
+
+	return null
+}