@mailwoman/codex 7.2.0 → 7.3.0

package/gb/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The United Kingdom address system (Royal Mail / ISO 3166-2:GB): the variable-length alphanumeric
+ *   postcode and its Royal-Mail postcode areas, the four constituent countries, and British street
+ *   vocabulary.
+ */
+
+export * from "./country.ts"
+export * from "./postcode-area.ts"
+export * from "./postcode.ts"
+export * from "./street-type.ts"

package/gb/postcode-area.ts

@@ -0,0 +1,107 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Postcode AREA → constituent country, the Royal Mail mapping — and the concrete proof of the
+ *   lesson in `postcode.ts` that UK postcodes do NOT track administrative geography.
+ *
+ *   A postcode area is the leading one or two letters of a postcode (`SW`, `M`, `EH`, `BT`), named
+ *   after the sorting town Royal Mail routes it through, NOT after a county or a constituent
+ *   country. There is no clean postcode→admin hierarchy to inherit the way France gives you a
+ *   département from the first two digits. The only honest thing we _can_ derive is which of the
+ *   four UK countries an area predominantly falls in — and even that has border exceptions:
+ *
+ *   - **TD** (Galashiels) and **SY** (Shrewsbury) straddle the Scotland/England and Wales/England
+ *       borders respectively; each is assigned to its MAJORITY country here (TD → Scotland, SY →
+ *       Wales). A handful of individual postcodes on the wrong side of the line are a gazetteer
+ *       concern, not a thing this coarse table tries to model.
+ *
+ *   So this is the ROYAL MAIL area→country mapping, and the fact that it needs a hand-built
+ *   non-England set with documented border fudges — rather than a tidy prefix rule — is exactly why
+ *   a UK postcode is not a county.
+ */
+
+import type { UkCountryCode } from "./country.ts"
+
+/** Northern Ireland is a single postcode area: BT (Belfast). */
+const NORTHERN_IRELAND_AREAS = ["BT"] as const
+
+/**
+ * Scotland's postcode areas. TD (Galashiels) straddles the border with England and is assigned to Scotland as its
+ * majority country.
+ */
+const SCOTLAND_AREAS = [
+	"AB", // Aberdeen
+	"DD", // Dundee
+	"DG", // Dumfries
+	"EH", // Edinburgh
+	"FK", // Falkirk
+	"G", //  Glasgow
+	"HS", // Outer Hebrides (Na h-Eileanan Siar)
+	"IV", // Inverness
+	"KA", // Kilmarnock
+	"KW", // Kirkwall (Orkney + Caithness)
+	"KY", // Kirkcaldy (Fife)
+	"ML", // Motherwell
+	"PA", // Paisley
+	"PH", // Perth
+	"TD", // Galashiels (Scottish Borders) — straddles the England border, majority Scotland
+	"ZE", // Lerwick (Shetland)
+] as const
+
+/**
+ * Wales's postcode areas. SY (Shrewsbury) straddles the border with England and is assigned to Wales as its majority
+ * country.
+ */
+const WALES_AREAS = [
+	"CF", // Cardiff
+	"LD", // Llandrindod Wells
+	"LL", // Llandudno
+	"NP", // Newport
+	"SA", // Swansea
+	"SY", // Shrewsbury — straddles the Wales/England border, majority Wales
+] as const
+
+/**
+ * The explicit non-England postcode areas, area → constituent country. England is intentionally absent: it is the
+ * DEFAULT (the great majority of UK areas are English), so listing it would be both enormous and a maintenance trap.
+ * Keeping only the non-England set makes the default transparent — anything not named here is England.
+ */
+export const GB_POSTCODE_AREA_COUNTRY: Record<string, UkCountryCode> = {
+	...Object.fromEntries(NORTHERN_IRELAND_AREAS.map((a) => [a, "NIR" as const])),
+	...Object.fromEntries(SCOTLAND_AREAS.map((a) => [a, "SCT" as const])),
+	...Object.fromEntries(WALES_AREAS.map((a) => [a, "WLS" as const])),
+}
+
+/** True when `area` looks like a valid postcode-area string: one or two ASCII letters. */
+function isAreaShape(area: unknown): area is string {
+	return typeof area === "string" && /^[A-Z]{1,2}$/i.test(area)
+}
+
+/**
+ * The constituent country a postcode AREA belongs to. Returns the explicit country for a known non-England area (e.g.
+ * `BT` → `NIR`, `G` → `SCT`, `CF` → `WLS`), and `ENG` as the default for any other validly-shaped area — England is by
+ * far the largest, so the default is transparent and the non-England exceptions live in
+ * {@link GB_POSTCODE_AREA_COUNTRY}. Returns null for clearly-invalid input (not one-or-two letters), so a malformed
+ * token is not silently called England.
+ */
+export function countryOfPostcodeArea(area: unknown): UkCountryCode | null {
+	if (!isAreaShape(area)) return null
+
+	return GB_POSTCODE_AREA_COUNTRY[area.toUpperCase()] ?? "ENG"
+}
+
+/**
+ * The constituent country a whole postcode resolves to, by extracting its area. `BT1 1AA` → `NIR`, `EH1 1BB` → `SCT`,
+ * `CF10 1AA` → `WLS`, `SW1A 1AA` → `ENG`. Null if the input has no extractable postcode area.
+ */
+export function countryOfPostcode(postcode: unknown): UkCountryCode | null {
+	if (typeof postcode !== "string") return null
+	// Extract the leading 1-2 letters directly, tolerating the inward code / spacing.
+	const match = /^\s*([A-Z]{1,2})/i.exec(postcode)
+
+	if (!match) return null
+
+	return countryOfPostcodeArea(match[1])
+}

package/gb/postcode.ts

@@ -0,0 +1,109 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   UK postcodes: the branded type, the validation shape, normalization, and the outward/inward
+ *   split.
+ *
+ *   This is the MOST COMPLEX postcode of any system in the codex, and the contrast is the whole point
+ *   of the file. A US ZIP, a German PLZ, and a French code postal are all a fixed five digits — the
+ *   shape is trivial and the only interesting question is what admin unit the prefix maps to. The
+ *   UK postcode is none of that:
+ *
+ *   - It is **variable-length alphanumeric**, from six characters (`M1 1AE`) to eight (`SW1A 1AA`),
+ *       across forms like `B33 8TH`, `CR2 6XH`, `DN55 1PT`.
+ *   - It splits into an **OUTWARD code** (area + district, the part before the space — `SW1A`) and an
+ *       **INWARD code** (sector + unit, the three chars after — `1AA`). Royal Mail sorts on the
+ *       outward to a delivery office, then on the inward to a walk.
+ *   - And — the lesson that propagates to `postcode-area.ts` — it does **NOT align with administrative
+ *       geography**. A postcode area is a Royal Mail routing construct named after a sorting town
+ *       (`SW` = south-west London, `EH` = Edinburgh), NOT a county or a constituent country. You
+ *       cannot read a county off a UK postcode the way you read a département off a French one; the
+ *       postcode→country mapping in `postcode-area.ts` exists precisely _because_ there is no clean
+ *       hierarchy to inherit.
+ *
+ *   So unlike the other systems, the hard work here is the shape itself — validating, normalizing the
+ *   internal space, and cleaving outward from inward — not a prefix→admin lookup.
+ */
+
+import type { Tagged } from "type-fest"
+
+/**
+ * A UK postcode: variable-length alphanumeric, outward + inward (`SW1A 1AA`, `M1 1AE`). The canonical form carries
+ * exactly one space before the final three characters. Unlike a US/DE/FR postcode, the shape is not a fixed-width
+ * numeric string — see {@link UK_POSTCODE_PATTERN}.
+ *
+ * @category Postal
+ * @type string
+ * @title UK postcode
+ * @pattern ^[A-Z]{1,2}\d[A-Z\d]? ?\d[A-Z]{2}$
+ */
+export type Postcode = Tagged<string, "UkPostcode">
+
+/**
+ * UK postcode shape. A permissive form of the Royal Mail / UK-gov regex: one or two leading letters (the area), a
+ * district digit, an optional district letter-or-digit, then the inward sector digit and two unit letters, with the
+ * inward space optional so an un-spaced `SW1A1AA` still validates. The full UK-gov pattern additionally whitelists the
+ * British Overseas Territory codes (`ASCN`, `STHL`, `BBND`, …); those are rare enough to leave to the gazetteer.
+ */
+export const UK_POSTCODE_PATTERN = /^[A-Z]{1,2}\d[A-Z\d]? ?\d[A-Z]{2}$/i
+
+/**
+ * Normalize a UK postcode surface form: uppercase, strip surrounding whitespace, and ensure exactly one space before
+ * the final three characters (the inward code). `sw1a1aa` → `SW1A 1AA`, `M11AE` → `M1 1AE`, `b33 8th` → `B33 8TH`.
+ * Returns null if the result is not a valid postcode.
+ */
+export function normalizeUkPostcode(raw: unknown): Postcode | null {
+	if (typeof raw !== "string") return null
+	// Drop all whitespace, uppercase, then re-insert the single canonical space before the inward 3.
+	const compact = raw.replace(/\s+/g, "").toUpperCase()
+
+	if (compact.length < 5) return null
+	const spaced = `${compact.slice(0, -3)} ${compact.slice(-3)}`
+
+	return UK_POSTCODE_PATTERN.test(spaced) ? (spaced as Postcode) : null
+}
+
+/** Type-predicate for a UK postcode surface form (space optional). */
+export function isUkPostcode(input: unknown): input is Postcode {
+	return typeof input === "string" && UK_POSTCODE_PATTERN.test(input.trim())
+}
+
+/**
+ * The OUTWARD code — the part before the space (area + district), e.g. `SW1A 1AA` → `SW1A`, `M1 1AE` → `M1`. Normalizes
+ * first so an un-spaced input still cleaves correctly; null if invalid.
+ */
+export function outwardCode(pc: unknown): string | null {
+	const normalized = normalizeUkPostcode(pc)
+
+	if (!normalized) return null
+
+	return normalized.slice(0, normalized.indexOf(" "))
+}
+
+/**
+ * The INWARD code — the three characters after the space (sector + unit), e.g. `SW1A 1AA` → `1AA`, `M1 1AE` → `1AE`.
+ * Null if invalid.
+ */
+export function inwardCode(pc: unknown): string | null {
+	const normalized = normalizeUkPostcode(pc)
+
+	if (!normalized) return null
+
+	return normalized.slice(normalized.indexOf(" ") + 1)
+}
+
+/**
+ * The POSTCODE AREA — the leading one or two LETTERS of the outward code, the Royal Mail routing region named after a
+ * sorting town: `SW1A 1AA` → `SW`, `M1 1AE` → `M`, `B33 8TH` → `B`. This is the key into `postcode-area.ts`'s
+ * area→country map. Null if the input is not a valid postcode.
+ */
+export function postcodeArea(pc: unknown): string | null {
+	const outward = outwardCode(pc)
+
+	if (!outward) return null
+	const match = /^[A-Z]{1,2}/.exec(outward)
+
+	return match ? match[0] : null
+}

package/gb/street-type.ts

@@ -0,0 +1,90 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   British street vocabulary (thoroughfare types).
+ *
+ *   The contrast across the codex's street files is structural. A US street type is a trailing word
+ *   with a USPS-standardized abbreviation (`Main Street` → `ST`). A German street type is a fused
+ *   agglutinative suffix (`Hauptstraße`). A French type is a leading standalone word (`Rue de la
+ *   Paix`). British practice is the US shape — a separate TRAILING word — but with a notably RICHER
+ *   and more local vocabulary: alongside the everyday `Road`/`Street`/`Avenue` sit `Crescent`,
+ *   `Mews`, `Close`, `Wynd`, `Brae`, `Gait`, `Croft`, `Dene` and a long tail of landscape words
+ *   (`Brook`, `Copse`, `Dell`, `Hollow`, `Spinney`) that read as thoroughfare types in the UK and
+ *   essentially nowhere else.
+ *
+ *   So detection is, like French, a whole-token match — {@link isBritishStreetWord} asks "is this
+ *   token a known British thoroughfare word" rather than testing a suffix — because these are
+ *   distinct trailing words, not fused endings.
+ */
+
+/**
+ * The British thoroughfare vocabulary. Lowercase canonical forms, matched as whole tokens. Spans the common core
+ * (`street`, `road`, `lane`, `avenue`) through the distinctively British (`crescent`, `mews`, `close`, `terrace`) and
+ * the regional/landscape tail (`wynd`, `brae`, `gait`, `croft`, `dene`, `spinney`, `dell`, `hollow`).
+ */
+export const GB_STREET_TYPES = [
+	"street",
+	"road",
+	"lane",
+	"avenue",
+	"close",
+	"crescent",
+	"court",
+	"drive",
+	"place",
+	"way",
+	"gardens",
+	"grove",
+	"terrace",
+	"mews",
+	"walk",
+	"hill",
+	"green",
+	"park",
+	"rise",
+	"view",
+	"row",
+	"square",
+	"parade",
+	"vale",
+	"wharf",
+	"yard",
+	"gate",
+	"croft",
+	"dene",
+	"end",
+	"fields",
+	"meadow",
+	"brook",
+	"chase",
+	"copse",
+	"dale",
+	"dell",
+	"glen",
+	"hollow",
+	"paddock",
+	"ridge",
+	"spinney",
+	"wynd",
+	"brae",
+	"gait",
+] as const
+
+/** A canonical British thoroughfare word (e.g. `street`, `crescent`, `mews`). */
+export type BritishStreetType = (typeof GB_STREET_TYPES)[number]
+
+const STREET_TYPE_SET: ReadonlySet<string> = new Set(GB_STREET_TYPES)
+
+/**
+ * True when a token is a British thoroughfare type word (case-insensitive, whole-token match) — `Crescent`, `Mews`,
+ * `Close`, `Road`. Matches the WHOLE token, not a suffix, so an unrelated place name (`Tokyo`, `Bordeaux`) is not
+ * flagged the way an `-endsWith` test might.
+ */
+export function isBritishStreetWord(token: unknown): boolean {
+	if (typeof token !== "string") return false
+	const t = token.toLowerCase().replace(/[^a-z]/g, "")
+
+	return t.length > 0 && STREET_TYPE_SET.has(t)
+}

package/index.ts

@@ -0,0 +1,38 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/codex` — per-address-system postal reference data and branded types.
+ *
+ *   Each address system (the USPS for the United States, La Poste for France, Deutsche Post for
+ *   Germany, …) has its own conventions for what a postcode, a street suffix, or a unit designator
+ *   looks like. This package is the shared, dependency-free home for that reference knowledge, kept
+ *   apart from the locale-agnostic tokenizer/solver in `@mailwoman/core` and from the training
+ *   pipeline in `@mailwoman/corpus`. The parser, the resolver, and the synthesis layer all reach
+ *   for the same tables instead of each carrying their own copy.
+ *
+ *   Systems are exposed as namespaces (`import { us } from "@mailwoman/codex"`) and as subpaths
+ *   (`import { lookupStreetSuffix } from "@mailwoman/codex/us"`). The cross-system
+ *   `candidateSystemsForPostcode` (the inverse of the per-slice postcode patterns) is a top-level
+ *   export. `levels` is the per-locale LEVEL/floor ordinal-semantics table (#1100) — like
+ *   `candidateSystemsForPostcode`, it's inherently multi-locale, so it lives at the codex root
+ *   (`./level-semantics.ts`) and is namespaced rather than given its own `@mailwoman/codex/<x>`
+ *   subpath.
+ */
+
+export {
+	ADDRESS_SYSTEM_CONVENTIONS,
+	conventionsForSystem,
+	type AddressSystemConventions,
+} from "./address-system-conventions.ts"
+export * as au from "./au/index.ts"
+export * as ca from "./ca/index.ts"
+export * as de from "./de/index.ts"
+export * as fr from "./fr/index.ts"
+export * as gb from "./gb/index.ts"
+export * as jp from "./jp/index.ts"
+export * as levels from "./level-semantics.ts"
+export * as nz from "./nz/index.ts"
+export { candidateSystemsForPostcode, type SystemCode } from "./postcode-systems.ts"
+export * as us from "./us/index.ts"

package/jp/address-unit.ts

@@ -0,0 +1,87 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Japan's analog of a "street-type" module — except the lesson here is the absence. Where
+ *   `us/street-suffix.ts` and `de/street-type.ts` exist to recognize the named-street part of an
+ *   address, Japan has **no street names** to recognize. A Japanese address is built from nested
+ *   administrative units and numbered blocks/lots, written largest-to-smallest:
+ *
+ *   ```
+ *   東京都 千代田区 千代田 1丁目 1番 1号
+ *   Tokyo-to · Chiyoda-ku · Chiyoda · 1-chōme · 1-ban · 1-gō
+ * ```
+ *
+ *   So instead of a street-suffix table this file ships two marker sets:
+ *
+ *   - {@link JP_ADMIN_SUFFIXES} — the kanji that close an administrative-area name (都/道/府/県 at the
+ *       prefecture level, then 市/区/郡/町/村 for city / ward / district / town / village). These are
+ *       the Japanese equivalent of a US street suffix in the parsing sense: the token-final marker
+ *       that tells you what KIND of unit the preceding name is.
+ *   - {@link JP_BLOCK_MARKERS} — the markers that close the numbered tail (丁目 / 番地 / 番 / 号), the part
+ *       that actually does the "house number" job in the absence of streets.
+ *
+ *   Note the reverse field order: the admin suffixes appear FIRST in the string (prefecture leads),
+ *   and the block markers LAST — the mirror image of a US line, where the house number leads and
+ *   the ZIP trails. See `postal-code.ts` for why, with no street name, the postcode is the primary
+ *   anchor.
+ */
+
+/**
+ * The kanji suffixes that close an administrative-area name, largest unit to smallest:
+ *
+ * - 都 (to) — metropolis; only Tokyo.
+ * - 道 (dō) — circuit; only Hokkaido.
+ * - 府 (fu) — urban prefecture; Osaka and Kyoto.
+ * - 県 (ken) — prefecture; the other 43.
+ * - 市 (shi) — city.
+ * - 区 (ku) — ward (a subdivision of a designated city, e.g. Tokyo's 23 special wards).
+ * - 郡 (gun) — district / county (rural grouping of towns and villages).
+ * - 町 (chō / machi) — town.
+ * - 村 (son / mura) — village.
+ */
+export const JP_ADMIN_SUFFIXES = ["都", "道", "府", "県", "市", "区", "郡", "町", "村"] as const
+
+/** A single administrative-area suffix kanji (`都`, `市`, `区`, …). */
+export type JapaneseAdminSuffix = (typeof JP_ADMIN_SUFFIXES)[number]
+
+/**
+ * The markers that close the numbered tail of an address — Japan's stand-in for a house number, since there is no named
+ * street to hang one on:
+ *
+ * - 丁目 (chōme) — a district block within a neighbourhood.
+ * - 番地 (banchi) — a lot number.
+ * - 番 (ban) — block number (the `番` in the modern `chōme-ban-gō` triple).
+ * - 号 (gō) — building number (the final element of the triple).
+ */
+export const JP_BLOCK_MARKERS = ["丁目", "番地", "番", "号"] as const
+
+/** A numbered-tail marker (`丁目`, `番地`, `番`, `号`). */
+export type JapaneseBlockMarker = (typeof JP_BLOCK_MARKERS)[number]
+
+const ADMIN_SUFFIX_SET: ReadonlySet<string> = new Set(JP_ADMIN_SUFFIXES)
+
+/**
+ * True when a single kanji is one of the {@link JP_ADMIN_SUFFIXES} admin-area markers (`都`, `市`, `区`, …). Strictly
+ * single-character: a multi-character input (even one ending in a suffix) is not a suffix on its own.
+ */
+export function isJapaneseAdminSuffix(ch: unknown): ch is JapaneseAdminSuffix {
+	return typeof ch === "string" && ADMIN_SUFFIX_SET.has(ch)
+}
+
+/**
+ * Strip a trailing admin-area suffix kanji from a place name, exposing the bare name (`東京都` → `東京`, `大阪市` → `大阪`,
+ * `千代田区` → `千代田`). Leaves a name untouched if it does not end in an admin suffix.
+ *
+ * Hokkaido (`北海道`) is the deliberate exception: its name ends in 道 but is indivisible, so it is returned whole rather
+ * than clipped to `北海` — mirroring the same carve-out in `prefecture.ts`.
+ */
+export function stripAdminSuffix(name: string): string {
+	if (typeof name !== "string" || name.length === 0) return name
+
+	if (name === "北海道") return name
+	const last = name[name.length - 1]!
+
+	return ADMIN_SUFFIX_SET.has(last) ? name.slice(0, -1) : name
+}

package/jp/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The Japanese address system (Japan Post / ISO 3166-2:JP): the 47 prefectures, the postal code
+ *   that is the country's most reliable geographic anchor, and the address-unit markers that stand
+ *   in for the street names Japan does not use.
+ */
+
+export * from "./address-unit.ts"
+export * from "./postal-code.ts"
+export * from "./prefecture.ts"

package/jp/postal-code.ts

@@ -0,0 +1,93 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Japanese postal codes (郵便番号, yūbin-bangō): the branded type, the shape, normalization, and the
+ *   first-digit → coarse-region prior.
+ *
+ *   This file is the far end of a spectrum whose other end is `us/zipcode.ts`. A US address leans on
+ *   the street line — a named street plus a house number — and the ZIP is a routing convenience. A
+ *   Japanese address is the inverse on two counts:
+ *
+ *   - It is written **largest-to-smallest**: prefecture → city/ward → district → block → lot (`東京都 千代田区
+ *       千代田 1-1`), the reverse of the US smallest-to-largest line order.
+ *   - There are **essentially no street names**. Outside a few Kyoto-style exceptions, you do not
+ *       navigate by named streets; you navigate by nested administrative areas and numbered
+ *       blocks/lots (丁目 / 番地 / 号 — see `address-unit.ts`).
+ *
+ *   With no street name to anchor on and a reverse field order, the **postal code is the single most
+ *   reliable geographic anchor** for a Japanese address — it pins the chōme-level area directly,
+ *   far tighter than a US ZIP pins a US address. So where the US parser treats the postcode as a
+ *   tie-breaker behind the street, the Japan parser should treat it as the primary key.
+ */
+
+import type { Tagged } from "type-fest"
+
+/**
+ * A Japanese postal code: three digits, a hyphen, then four digits (`100-0001`), conventionally written after the 〒
+ * mark (`〒100-0001`). Branded so a normalized code is distinct from an arbitrary string — the 7-digit shape alone does
+ * not prove a code is real, only well-formed.
+ *
+ * @category Postal
+ * @type string
+ * @title 郵便番号
+ * @pattern ^\d{3}-?\d{4}$
+ */
+export type PostalCode = Tagged<string, "JpPostalCode">
+
+/** The postal-code shape: `NNN-NNNN`, the hyphen optional on input (`1000001` or `100-0001`). */
+export const JP_POSTAL_CODE_PATTERN = /^\d{3}-?\d{4}$/
+
+/**
+ * Normalize a postal-code surface form to the canonical hyphenated `NNN-NNNN`: strip a leading 〒 mark and any
+ * whitespace, then re-insert the hyphen if the input gave the bare seven digits (`〒100-0001` → `100-0001`, `1000001` →
+ * `100-0001`). Returns null if the result is not seven digits.
+ */
+export function normalizeJpPostalCode(raw: unknown): PostalCode | null {
+	if (typeof raw !== "string") return null
+	// Drop the 〒 mark and all whitespace, then keep only the digits.
+	const digits = raw.replace(/〒/g, "").replace(/\s+/g, "").replace(/-/g, "")
+
+	if (!/^\d{7}$/.test(digits)) return null
+
+	return `${digits.slice(0, 3)}-${digits.slice(3)}` as PostalCode
+}
+
+/** Type-predicate for a Japanese postal code (hyphen optional, `100-0001` or `1000001`). */
+export function isJpPostalCode(input: unknown): input is PostalCode {
+	return typeof input === "string" && JP_POSTAL_CODE_PATTERN.test(input)
+}
+
+/**
+ * First digit of the postal code → a coarse region label. Japan Post's numbering grows roughly outward from Tokyo
+ * (`1xx`) and is **approximate** at this granularity — a single leading digit spans large, irregular areas and the
+ * boundaries are postal-routing, not administrative. Use it as a weak prior, never as a hard region assignment; the
+ * full code is what actually anchors the address.
+ *
+ * Approximate — the labels below are illustrative routing regions, not precise prefecture sets.
+ */
+export const JP_FIRST_DIGIT_REGION: Record<string, string> = {
+	"0": "Hokkaido & northern Tōhoku",
+	"1": "Tokyo & Kanto",
+	"2": "Kanagawa / Shizuoka & central",
+	"3": "northern Kanto / Tōhoku",
+	"4": "Tōkai / Chūbu",
+	"5": "Kinki / Kansai",
+	"6": "Kinki / Chūgoku west",
+	"7": "Chūgoku / Shikoku",
+	"8": "Kyūshū",
+	"9": "Tōhoku north / other",
+}
+
+/**
+ * The coarse region label for a postal code's first digit, or null if the input is not a Japanese postal code. A weak,
+ * approximate prior (see {@link JP_FIRST_DIGIT_REGION}); the full code anchors the address.
+ */
+export function firstDigitRegion(postalCode: unknown): string | null {
+	const normalized = normalizeJpPostalCode(postalCode)
+
+	if (!normalized) return null
+
+	return JP_FIRST_DIGIT_REGION[normalized[0]!] ?? null
+}