@mailwoman/codex 4.0.0

package/out/gb/country.js

@@ -0,0 +1,56 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The four constituent countries of the United Kingdom, keyed by their ISO 3166-2:GB code: England
+ *   (`ENG`), Scotland (`SCT`), Wales (`WLS`), Northern Ireland (`NIR`).
+ *
+ *   The UK's top-level admin tier is itself the first oddity of this system. France has régions,
+ *   Germany has Bundesländer, the US has states — a single flat layer. The UK has _countries_
+ *   inside a country, and an address almost never names which one: a line reads `street, town,
+ *   postcode`, and the constituent country is inferred — usually, but not always cleanly, from the
+ *   postcode area (see `postcode-area.ts`). So this file is the coarse admin label, and the
+ *   postcode is the thing that actually carries the geography.
+ */
+/** ISO 3166-2:GB country code → info, for all four constituent countries. */
+export const GB_COUNTRIES = {
+    ENG: { code: "ENG", name: "England" },
+    SCT: { code: "SCT", name: "Scotland" },
+    WLS: { code: "WLS", name: "Wales" },
+    NIR: { code: "NIR", name: "Northern Ireland" },
+};
+const COUNTRY_CODE_SET = new Set(Object.keys(GB_COUNTRIES));
+/** Type-predicate for an ISO 3166-2:GB country code. Case-insensitive. */
+export function isUkCountryCode(input) {
+    return typeof input === "string" && COUNTRY_CODE_SET.has(input.toUpperCase());
+}
+/** Lowercase + collapse non-alphanumerics so `Northern Ireland`, `northern-ireland` key alike. */
+function foldName(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, " ")
+        .trim();
+}
+/** Folded country name / code → ISO 3166-2:GB code, so a surface form maps regardless of casing. */
+const COUNTRY_NAME_TO_CODE = (() => {
+    const out = new Map();
+    for (const code of Object.keys(GB_COUNTRIES)) {
+        out.set(foldName(GB_COUNTRIES[code].name), code);
+        out.set(code.toLowerCase(), code);
+    }
+    return out;
+})();
+/**
+ * Resolve a UK constituent-country surface form (ISO code or English name) to its ISO code; null if
+ * unknown. Accepts `ENG`, `England`, `Northern Ireland`, `scotland`, etc.
+ */
+export function lookupUkCountry(input) {
+    if (!input || typeof input !== "string")
+        return null;
+    const upper = input.trim().toUpperCase();
+    if (COUNTRY_CODE_SET.has(upper))
+        return upper;
+    return COUNTRY_NAME_TO_CODE.get(foldName(input)) ?? null;
+}
+//# sourceMappingURL=country.js.map

package/out/gb/country.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"country.js","sourceRoot":"","sources":["../../gb/country.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAUH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,YAAY,GAAG;IAC3B,GAAG,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE;IACrC,GAAG,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE;IACtC,GAAG,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE;IACnC,GAAG,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,kBAAkB,EAAE;CACG,CAAA;AAKlD,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAA;AAEhF,0EAA0E;AAC1E,MAAM,UAAU,eAAe,CAAC,KAAc;IAC7C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAA;AAC9E,CAAC;AAED,kGAAkG;AAClG,SAAS,QAAQ,CAAC,CAAS;IAC1B,OAAO,CAAC;SACN,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,IAAI,EAAE,CAAA;AACT,CAAC;AAED,oGAAoG;AACpG,MAAM,oBAAoB,GAAuC,CAAC,GAAG,EAAE;IACtE,MAAM,GAAG,GAAG,IAAI,GAAG,EAAyB,CAAA;IAC5C,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,YAAY,CAAoB,EAAE,CAAC;QACjE,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAA;QAChD,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,IAAI,CAAC,CAAA;IAClC,CAAC;IACD,OAAO,GAAG,CAAA;AACX,CAAC,CAAC,EAAE,CAAA;AAEJ;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAgC;IAC/D,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IACpD,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IACxC,IAAI,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,KAAsB,CAAA;IAC9D,OAAO,oBAAoB,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,IAAI,IAAI,CAAA;AACzD,CAAC"}

package/out/gb/index.d.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.js";
+export * from "./postcode-area.js";
+export * from "./postcode.js";
+export * from "./street-type.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../gb/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA"}

package/out/gb/index.js

@@ -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.js";
+export * from "./postcode-area.js";
+export * from "./postcode.js";
+export * from "./street-type.js";
+//# sourceMappingURL=index.js.map

package/out/gb/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../gb/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA"}

package/out/gb/postcode-area.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @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.js";
+/**
+ * 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 declare const GB_POSTCODE_AREA_COUNTRY: Record<string, UkCountryCode>;
+/**
+ * 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 declare function countryOfPostcodeArea(area: unknown): UkCountryCode | null;
+/**
+ * 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 declare function countryOfPostcode(postcode: unknown): UkCountryCode | null;
+//# sourceMappingURL=postcode-area.d.ts.map

package/out/gb/postcode-area.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postcode-area.d.ts","sourceRoot":"","sources":["../../gb/postcode-area.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAyCjD;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAIlE,CAAA;AAOD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CAGzE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CAMzE"}

package/out/gb/postcode-area.js

@@ -0,0 +1,101 @@
+/**
+ * @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.
+ */
+/** Northern Ireland is a single postcode area: BT (Belfast). */
+const NORTHERN_IRELAND_AREAS = ["BT"];
+/**
+ * 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)
+];
+/**
+ * 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
+];
+/**
+ * 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 = {
+    ...Object.fromEntries(NORTHERN_IRELAND_AREAS.map((a) => [a, "NIR"])),
+    ...Object.fromEntries(SCOTLAND_AREAS.map((a) => [a, "SCT"])),
+    ...Object.fromEntries(WALES_AREAS.map((a) => [a, "WLS"])),
+};
+/** True when `area` looks like a valid postcode-area string: one or two ASCII letters. */
+function isAreaShape(area) {
+    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) {
+    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) {
+    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]);
+}
+//# sourceMappingURL=postcode-area.js.map

package/out/gb/postcode-area.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postcode-area.js","sourceRoot":"","sources":["../../gb/postcode-area.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,gEAAgE;AAChE,MAAM,sBAAsB,GAAG,CAAC,IAAI,CAAU,CAAA;AAE9C;;;GAGG;AACH,MAAM,cAAc,GAAG;IACtB,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,SAAS;IACf,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,YAAY;IAClB,IAAI,EAAE,UAAU;IAChB,GAAG,EAAE,WAAW;IAChB,IAAI,EAAE,sCAAsC;IAC5C,IAAI,EAAE,YAAY;IAClB,IAAI,EAAE,aAAa;IACnB,IAAI,EAAE,gCAAgC;IACtC,IAAI,EAAE,mBAAmB;IACzB,IAAI,EAAE,aAAa;IACnB,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,kFAAkF;IACxF,IAAI,EAAE,qBAAqB;CAClB,CAAA;AAEV;;;GAGG;AACH,MAAM,WAAW,GAAG;IACnB,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,oBAAoB;IAC1B,IAAI,EAAE,YAAY;IAClB,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,kEAAkE;CAC/D,CAAA;AAEV;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAkC;IACtE,GAAG,MAAM,CAAC,WAAW,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAc,CAAC,CAAC,CAAC;IAC7E,GAAG,MAAM,CAAC,WAAW,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAc,CAAC,CAAC,CAAC;IACrE,GAAG,MAAM,CAAC,WAAW,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAc,CAAC,CAAC,CAAC;CAClE,CAAA;AAED,0FAA0F;AAC1F,SAAS,WAAW,CAAC,IAAa;IACjC,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAC9D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAa;IAClD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IACnC,OAAO,wBAAwB,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,IAAI,KAAK,CAAA;AAC7D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAiB;IAClD,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IAC7C,kFAAkF;IAClF,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IAChD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAA;IACvB,OAAO,qBAAqB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;AACvC,CAAC"}

package/out/gb/postcode.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @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 robust, slightly 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 declare const UK_POSTCODE_PATTERN: RegExp;
+/**
+ * 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 declare function normalizeUkPostcode(raw: unknown): Postcode | null;
+/** Type-predicate for a UK postcode surface form (space optional). */
+export declare function isUkPostcode(input: unknown): input is Postcode;
+/**
+ * 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 declare function outwardCode(pc: unknown): string | null;
+/**
+ * The INWARD code — the three characters after the space (sector + unit), e.g. `SW1A 1AA` → `1AA`,
+ * `M1 1AE` → `1AE`. Null if invalid.
+ */
+export declare function inwardCode(pc: unknown): string | null;
+/**
+ * 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 declare function postcodeArea(pc: unknown): string | null;
+//# sourceMappingURL=postcode.d.ts.map

package/out/gb/postcode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postcode.d.ts","sourceRoot":"","sources":["../../gb/postcode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAEvC;;;;;;;;;GASG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,QAAwC,CAAA;AAExE;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAOjE;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE9D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAItD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAIrD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAKvD"}

package/out/gb/postcode.js

@@ -0,0 +1,88 @@
+/**
+ * @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.
+ */
+/**
+ * UK postcode shape. A robust, slightly 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) {
+    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 : null;
+}
+/** Type-predicate for a UK postcode surface form (space optional). */
+export function isUkPostcode(input) {
+    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) {
+    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) {
+    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) {
+    const outward = outwardCode(pc);
+    if (!outward)
+        return null;
+    const match = /^[A-Z]{1,2}/.exec(outward);
+    return match ? match[0] : null;
+}
+//# sourceMappingURL=postcode.js.map

package/out/gb/postcode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postcode.js","sourceRoot":"","sources":["../../gb/postcode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAgBH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,qCAAqC,CAAA;AAExE;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC/C,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IACxC,iGAAiG;IACjG,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAA;IACrD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IACnC,MAAM,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IAC7D,OAAO,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAE,MAAmB,CAAC,CAAC,CAAC,IAAI,CAAA;AACtE,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,YAAY,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;AAC3E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,EAAW;IACtC,MAAM,UAAU,GAAG,mBAAmB,CAAC,EAAE,CAAC,CAAA;IAC1C,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAA;IAC5B,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAA;AACpD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,EAAW;IACrC,MAAM,UAAU,GAAG,mBAAmB,CAAC,EAAE,CAAC,CAAA;IAC1C,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAA;IAC5B,OAAO,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAA;AACrD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,EAAW;IACvC,MAAM,OAAO,GAAG,WAAW,CAAC,EAAE,CAAC,CAAA;IAC/B,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAA;IACzB,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IACzC,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AAC/B,CAAC"}

package/out/gb/street-type.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @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 declare const GB_STREET_TYPES: readonly ["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"];
+/** A canonical British thoroughfare word (e.g. `street`, `crescent`, `mews`). */
+export type BritishStreetType = (typeof GB_STREET_TYPES)[number];
+/**
+ * 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 declare function isBritishStreetWord(token: unknown): boolean;
+//# sourceMappingURL=street-type.d.ts.map

package/out/gb/street-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"street-type.d.ts","sourceRoot":"","sources":["../../gb/street-type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,0ZA8ClB,CAAA;AAEV,iFAAiF;AACjF,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAA;AAIhE;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAI3D"}

package/out/gb/street-type.js

@@ -0,0 +1,86 @@
+/**
+ * @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",
+];
+const STREET_TYPE_SET = 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) {
+    if (typeof token !== "string")
+        return false;
+    const t = token.toLowerCase().replace(/[^a-z]/g, "");
+    return t.length > 0 && STREET_TYPE_SET.has(t);
+}
+//# sourceMappingURL=street-type.js.map

package/out/gb/street-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"street-type.js","sourceRoot":"","sources":["../../gb/street-type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC9B,QAAQ;IACR,MAAM;IACN,MAAM;IACN,QAAQ;IACR,OAAO;IACP,UAAU;IACV,OAAO;IACP,OAAO;IACP,OAAO;IACP,KAAK;IACL,SAAS;IACT,OAAO;IACP,SAAS;IACT,MAAM;IACN,MAAM;IACN,MAAM;IACN,OAAO;IACP,MAAM;IACN,MAAM;IACN,MAAM;IACN,KAAK;IACL,QAAQ;IACR,QAAQ;IACR,MAAM;IACN,OAAO;IACP,MAAM;IACN,MAAM;IACN,OAAO;IACP,MAAM;IACN,KAAK;IACL,QAAQ;IACR,QAAQ;IACR,OAAO;IACP,OAAO;IACP,OAAO;IACP,MAAM;IACN,MAAM;IACN,MAAM;IACN,QAAQ;IACR,SAAS;IACT,OAAO;IACP,SAAS;IACT,MAAM;IACN,MAAM;IACN,MAAM;CACG,CAAA;AAKV,MAAM,eAAe,GAAwB,IAAI,GAAG,CAAC,eAAe,CAAC,CAAA;AAErE;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc;IACjD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IAC3C,MAAM,CAAC,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAA;IACpD,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;AAC9C,CAAC"}

package/out/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @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.
+ */
+export * as ca from "./ca/index.js";
+export * as de from "./de/index.js";
+export * as fr from "./fr/index.js";
+export * as gb from "./gb/index.js";
+export * as jp from "./jp/index.js";
+export { candidateSystemsForPostcode, type SystemCode } from "./postcode-systems.js";
+export * as us from "./us/index.js";
+//# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,EAAE,2BAA2B,EAAE,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACpF,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA"}

package/out/index.js

@@ -0,0 +1,27 @@
+/**
+ * @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.
+ */
+export * as ca from "./ca/index.js";
+export * as de from "./de/index.js";
+export * as fr from "./fr/index.js";
+export * as gb from "./gb/index.js";
+export * as jp from "./jp/index.js";
+export { candidateSystemsForPostcode } from "./postcode-systems.js";
+export * as us from "./us/index.js";
+//# sourceMappingURL=index.js.map

package/out/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,EAAE,2BAA2B,EAAmB,MAAM,uBAAuB,CAAA;AACpF,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA"}