@mailwoman/neural 2.2.0 → 4.1.0

package/out/postcode-anchor.js

@@ -0,0 +1,269 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Postcode anchor — the first member of the "anchor-based parsing" family (Direction D, #240). See
+ *   `docs/articles/plan/2026-06-03-anchor-based-parsing.md`.
+ *
+ *   A postcode is the most information-dense token in an address: a hierarchical geo-encoding that
+ *   places a query on Earth far more cheaply than the rest of the parse. This module lifts the
+ *   postcode out of the BIO sequence-labelling problem and treats it as a structured anchor. It
+ *   runs the same per-country shape regexes the decoder repair pass uses ({@link collectMatches}),
+ *   resolves each shaped span against a postcode gazetteer, and returns a SOFT signal: a country
+ *   posterior plus a calibrated confidence. It never decides a postcode's identity on its own — it
+ *   reports "this string is (or is not) a real postcode, in these countries, near here", and leaves
+ *   the parser to weigh that against the surrounding tokens.
+ *
+ *   Two design rules carried from the DeepSeek consult
+ *   (`.agents/skills/deepseek-consult/ds-pc-turn{1,2}-postcode-anchor.txt`):
+ *
+ *   - The country posterior is UNIFORM over the countries a string actually exists in. We never weight
+ *       by per-country postcode volume, because that skews "75001" toward whichever country owns
+ *       more 5-digit codes — the exact bias the anchor exists to avoid. Disambiguation is the
+ *       parser's job, using script, city tokens, and user locale.
+ *   - Confidence combines gazetteer MEMBERSHIP with country AMBIGUITY. A string that matches a postcode
+ *       regex but exists in no gazetteer (a bare `27`, or a 5-digit house number that is not a real
+ *       code) gets confidence 0, so the parser treats it as a house number. A real-but-ambiguous
+ *       code (`75001` in FR and US) gets moderate confidence. A real, single-country code gets
+ *       1.0.
+ */
+import { candidateSystemsForPostcode } from "@mailwoman/codex";
+import { isGermanStreetToken } from "@mailwoman/codex/de";
+import { isFrenchStreetWord } from "@mailwoman/codex/fr";
+import { isStreetSuffixToken, isUsStateAbbreviation } from "@mailwoman/codex/us";
+import { collectMatches } from "./postcode-repair.js";
+/**
+ * Entropy cap for the confidence formula: a k-way country split saturates toward 0 confidence at
+ * k=10.
+ */
+const MAX_COUNTRIES = 10;
+/** A fuzzy (typo-corrected) match is less certain than an exact one — scale its confidence down. */
+const FUZZY_PENALTY = 0.6;
+/**
+ * Class-aware edit-distance-1 variants of a postcode string: deletions, same-class substitutions
+ * (digit↔digit, letter↔letter), same-class insertions, and adjacent transpositions. Restricting
+ * substitutions/insertions to the character's class mirrors how humans mistype or OCR a postcode (a
+ * digit becomes another digit, not a letter) and keeps the candidate set small.
+ */
+export function editDistance1Variants(s) {
+    const classOf = (ch) => /[0-9]/.test(ch) ? "0123456789" : /[A-Z]/.test(ch) ? "ABCDEFGHIJKLMNOPQRSTUVWXYZ" : "";
+    const variants = new Set();
+    for (let i = 0; i < s.length; i++)
+        variants.add(s.slice(0, i) + s.slice(i + 1)); // deletions
+    for (let i = 0; i < s.length; i++) {
+        for (const c of classOf(s[i]))
+            if (c !== s[i])
+                variants.add(s.slice(0, i) + c + s.slice(i + 1)); // substitutions
+    }
+    for (let i = 0; i <= s.length; i++) {
+        for (const c of classOf(s[i] ?? s[i - 1] ?? ""))
+            variants.add(s.slice(0, i) + c + s.slice(i)); // insertions
+    }
+    for (let i = 0; i + 1 < s.length; i++)
+        variants.add(s.slice(0, i) + s[i + 1] + s[i] + s.slice(i + 2)); // transpositions
+    variants.delete(s);
+    return [...variants];
+}
+/**
+ * Normalize a shaped span to the canonical gazetteer key: uppercase, collapse internal whitespace
+ * to a single space, and strip the German `D-` courtesy prefix (the shards store `68161`, not
+ * `D-68161`).
+ */
+export function normalizePostcode(raw) {
+    let s = raw.trim().toUpperCase().replace(/\s+/g, " ");
+    if (/^D-\d{5}$/.test(s))
+        s = s.slice(2); // German courtesy prefix: D-68161 → 68161
+    if (/^\d{4} [A-Z]{2}$/.test(s))
+        s = s.replace(" ", ""); // Dutch: gazetteer stores 1012LM, not 1012 LM
+    return s;
+}
+/**
+ * The GB outward code of a normalized unit postcode — the part before the space when the inward
+ * half is `\d[A-Z]{2}` (`SO4 3RX` → `SO4`). The GB gazetteer is aggregated to outward codes (2.7M
+ * units is too large + too fine for an anchor), so the extractor retries the outward code when a
+ * full GB unit misses. Returns `null` for any string that isn't a GB unit postcode (so it never
+ * fires elsewhere).
+ */
+export function gbOutwardCode(normalized) {
+    const sp = normalized.indexOf(" ");
+    if (sp < 1)
+        return null;
+    return /^\d[A-Z]{2}$/.test(normalized.slice(sp + 1)) ? normalized.slice(0, sp) : null;
+}
+/**
+ * `1 - log2(k)/log2(MAX_COUNTRIES)`, clamped to [0, 1]. k=1 → 1.0; k=2 → ~0.70; k≥MAX_COUNTRIES →
+ * 0.
+ */
+function confidenceFromCountryCount(k) {
+    if (k <= 0)
+        return 0;
+    if (k === 1)
+        return 1;
+    const c = 1 - Math.log2(k) / Math.log2(MAX_COUNTRIES);
+    return Math.max(0, Math.min(1, c));
+}
+/**
+ * Confidence scale for a digit-only code that shares its segment with a street word. A house number
+ * and a 5-digit postcode are the same shape, so membership alone can't separate `12345 Main St`
+ * (house number that happens to be a real ZIP elsewhere) from `San Francisco 94105` (postcode). The
+ * structural tell is cheap and locale-general: house numbers sit beside the street, postcodes
+ * beside the city. We scale rather than zero — the gazetteer still vouches for the shape, so a lone
+ * code in a street-only line stays usable; the penalty just lets a real trailing postcode out-rank
+ * it.
+ */
+const HOUSE_NUMBER_PENALTY = 0.2;
+/**
+ * Standalone street-type words for the locales without a codex slice yet (ES/IT). US comes from
+ * `@mailwoman/codex/us`, German from `@mailwoman/codex/de`, French from `@mailwoman/codex/fr`; the
+ * Dutch compound suffixes are still inline below pending a `codex/nl` slice.
+ */
+const NON_US_STREET_WORDS = new Set([
+    // Spanish
+    "calle",
+    "avenida",
+    "avda",
+    "plaza",
+    "paseo",
+    "camino",
+    "carrera",
+    "ronda",
+    // Italian
+    "via",
+    "viale",
+    "piazza",
+    "corso",
+    "largo",
+    "vicolo",
+    "strada",
+    "contrada",
+]);
+/** Dutch compound street suffixes — matched against a token's tail (pending a `codex/nl` slice). */
+const NL_STREET_SUFFIXES = ["straat", "laan", "plein", "gracht", "kade", "dijk", "steeg", "dreef"];
+/**
+ * True when a token denotes a street. US suffixes come from the USPS Pub-28 table in
+ * `@mailwoman/codex/us` (complete, so `Trl`/`Holw`/`Xing` all match), EXCEPT the abbreviations that
+ * collide with a state code — `KY` (Key vs Kentucky), `PR` (Prairie vs Puerto Rico) — which sit in
+ * the postcode's own `City, ST ZIP` segment. German compounds come from `@mailwoman/codex/de`
+ * ({@link isGermanStreetToken}), whose suffix set already excludes the place-name endings (`-berg`,
+ * `-burg`, `-dorf`) that would otherwise flag a city token. French voie words come from
+ * `@mailwoman/codex/fr` ({@link isFrenchStreetWord}). ES/IT and Dutch fall back to the inline
+ * lists.
+ *
+ * `systems` GATES which vocabularies are consulted — only the systems the postcode plausibly
+ * belongs to (its gazetteer membership, e.g. a US-only ZIP gates to `{us}` and never checks the
+ * German or French vocab). This is what lets the check scale to 15-20 systems without a
+ * cross-locale collision (German `-ring` vs English `spring`): an unrelated system's vocabulary is
+ * simply never asked. The gate carries lowercase system/locale tags (`us`, `de`, `fr`, `es`, `it`,
+ * `nl`).
+ */
+function looksLikeStreetWord(token, systems) {
+    const t = token.toLowerCase().replace(/[^\p{L}]/gu, "");
+    if (t.length < 2)
+        return false;
+    if (systems.has("us") && isStreetSuffixToken(t) && !isUsStateAbbreviation(t))
+        return true;
+    if (systems.has("de") && isGermanStreetToken(t))
+        return true;
+    if (systems.has("fr") && isFrenchStreetWord(t))
+        return true;
+    if ((systems.has("es") || systems.has("it")) && NON_US_STREET_WORDS.has(t))
+        return true;
+    if (systems.has("nl"))
+        return NL_STREET_SUFFIXES.some((s) => t.length > s.length && t.endsWith(s));
+    return false;
+}
+/**
+ * Position-aware confidence factor for a postcode span: `1` for anything that cannot be confused
+ * with a house number, and {@link HOUSE_NUMBER_PENALTY} for a digit-only code sharing its
+ * comma-delimited segment with a street word. This is the structural prior that lets the anchor
+ * tell a leading `12345 Main St` house number from a trailing `San Francisco 94105` postcode with
+ * no model in the loop — and lets a consumer pick the right span by confidence instead of by raw
+ * position.
+ *
+ * `systems` narrows the street vocabularies to the ones this code plausibly belongs to (its
+ * gazetteer membership, or — for a code in no gazetteer — the format-shape candidates from codex).
+ */
+function positionFactor(text, start, normalized, systems) {
+    if (!/^\d+$/.test(normalized))
+        return 1; // only digit-only codes collide with house numbers
+    const segStart = text.lastIndexOf(",", start - 1) + 1;
+    let segEnd = text.indexOf(",", start);
+    if (segEnd < 0)
+        segEnd = text.length;
+    for (const token of text.slice(segStart, segEnd).split(/\s+/)) {
+        if (looksLikeStreetWord(token, systems))
+            return HOUSE_NUMBER_PENALTY;
+    }
+    return 1;
+}
+/**
+ * Extract postcode anchors from raw text. For each postcode-shaped span, resolve it against the
+ * gazetteer and emit a soft anchor (country posterior + confidence). Spans that match a shape but
+ * exist in no gazetteer are still returned, with an empty posterior and confidence 0 — an explicit
+ * "looks like a postcode, but isn't one" so the caller can see the extractor fired and chose not to
+ * anchor.
+ */
+export function extractPostcodeAnchors(text, resolver, opts = {}) {
+    const anchors = [];
+    for (const match of collectMatches(text)) {
+        const spanText = text.slice(match.start, match.end);
+        const normalized = normalizePostcode(spanText);
+        // Exact first; then the GB outward fallback (structural, not a guess); then edit-distance-1.
+        let hits = resolver.lookup(normalized);
+        let matchType = hits.length > 0 ? "exact" : "none";
+        if (matchType === "none") {
+            const outward = gbOutwardCode(normalized);
+            if (outward) {
+                const outwardHits = resolver.lookup(outward);
+                if (outwardHits.length > 0) {
+                    hits = outwardHits;
+                    matchType = "outward";
+                }
+            }
+        }
+        if (matchType === "none" && opts.fuzzy) {
+            const fuzzyHits = [];
+            for (const variant of editDistance1Variants(normalized)) {
+                for (const h of resolver.lookup(variant))
+                    fuzzyHits.push(h);
+            }
+            if (fuzzyHits.length > 0) {
+                hits = fuzzyHits;
+                matchType = "fuzzy";
+            }
+        }
+        // Membership: distinct countries the postcode exists in (regardless of whether we have a centroid).
+        const countries = [...new Set(hits.map((h) => h.country))].sort();
+        const k = countries.length;
+        const posterior = {};
+        for (const c of countries)
+            posterior[c] = 1 / k;
+        // Placement: one representative coordinate-bearing hit per country (the first with real coords).
+        const candidates = [];
+        for (const c of countries) {
+            const placed = hits.find((h) => h.country === c && h.lat !== 0 && h.lon !== 0);
+            if (placed)
+                candidates.push(placed);
+        }
+        // Gate the street-word check to the systems this code plausibly belongs to: its gazetteer
+        // membership when known (precise — a US-only ZIP never checks the German vocab), else the
+        // format-shape candidates from codex (for a code in no gazetteer; its confidence is 0 anyway).
+        const systems = countries.length > 0
+            ? new Set(countries.map((c) => c.toLowerCase()))
+            : new Set(candidateSystemsForPostcode(normalized));
+        const position = positionFactor(text, match.start, normalized, systems);
+        const confidence = confidenceFromCountryCount(k) * (matchType === "fuzzy" ? FUZZY_PENALTY : 1) * position;
+        anchors.push({
+            span: { text: spanText, start: match.start, end: match.end },
+            normalized,
+            candidates,
+            posterior,
+            confidence,
+            matchType,
+            positionFactor: position,
+        });
+    }
+    return anchors;
+}
+//# sourceMappingURL=postcode-anchor.js.map

package/out/postcode-anchor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postcode-anchor.js","sourceRoot":"","sources":["../postcode-anchor.ts"],"names":[],"mappings":"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"}

package/out/postcode-binary-resolver.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Browser-side postcode resolver for the anchor (#240). A pure-JS, zero-dependency
+ *   `PostcodeResolver` backed by a compact flat binary instead of SQLite, so the postcode anchor
+ *   runs in the WASM/browser parser behind the same `lookup()` seam as the server-side
+ *   `WofPostcodeLookup`.
+ *
+ *   This file owns BOTH ends of the format — `serializePostcodeBinary` (run in Node by
+ *   `scripts/build-postcode-binary.ts`) and `PostcodeBinaryResolver` (run in the browser) — so the
+ *   layout can never drift between writer and reader.
+ *
+ *   Binary layout (little-endian): magic "PCB1" (4 bytes) u32 recordCount u8 countryCount, then
+ *   countryCount × 2 ASCII bytes (the country table) u8 keyWidth (max postcode length in bytes)
+ *   records recordCount × { key[keyWidth] ASCII right-padded with 0x00, u8 countryIdx, i16 latQ,
+ *   i16 lonQ }, sorted by key bytes ascending. A postcode present in two countries appears as two
+ *   adjacent records (same key, different countryIdx).
+ *
+ *   Coordinates are quantized to i16: latQ = round(lat/90 × 32767), lonQ = round(lon/180 × 32767),
+ *   giving ~300 m resolution — ample for a "which city/region" anchor. A record with latQ = lonQ =
+ *   0 means "known postcode, no centroid" (membership only), matching the SQLite resolver's
+ *   convention.
+ */
+import type { AnchorLookup } from "./anchor-inference.js";
+import type { PostcodePlace } from "./postcode-anchor.js";
+export interface PostcodeBinaryEntry {
+    postcode: string;
+    country: string;
+    lat: number;
+    lon: number;
+}
+/**
+ * Serialize postcode entries into the flat binary. Entries are sorted by (postcode, country) so
+ * equal postcodes land in adjacent records. Run in Node; consumed by
+ * {@link PostcodeBinaryResolver}.
+ */
+export declare function serializePostcodeBinary(entries: readonly PostcodeBinaryEntry[]): Uint8Array;
+/**
+ * Pure-JS, browser-safe postcode resolver over the flat binary. Implements the same `lookup()` seam
+ * as the SQLite `WofPostcodeLookup`, so `extractPostcodeAnchors` is agnostic to which backs it.
+ */
+export declare class PostcodeBinaryResolver {
+    #private;
+    constructor(bytes: Uint8Array);
+    lookup(postcode: string): PostcodePlace[];
+    /**
+     * Decode the whole binary into an {@link AnchorLookup} (`Map<postcode, AnchorEntry>`) for the
+     * neural anchor channel (#239/#240): each postcode → a uniform posterior over its member
+     * countries
+     *
+     * - The mean of its non-zero centroids. This is the browser-side equivalent of the pilot
+     *   postcode→anchor lookup the model trained against, built live from the shipped binary instead
+     *   of a precomputed JSON. Records are stored sorted by (postcode, country), so equal keys are
+     *   contiguous.
+     */
+    toAnchorLookup(): AnchorLookup;
+}
+//# sourceMappingURL=postcode-binary-resolver.d.ts.map

package/out/postcode-binary-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postcode-binary-resolver.d.ts","sourceRoot":"","sources":["../postcode-binary-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAOzD,MAAM,WAAW,mBAAmB;IACnC,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;CACX;AAUD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,GAAG,UAAU,CA2C3F;AAED;;;GAGG;AACH,qBAAa,sBAAsB;;gBAStB,KAAK,EAAE,UAAU;IA2B7B,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,EAAE;IA2BzC;;;;;;;;;OASG;IACH,cAAc,IAAI,YAAY;CA+C9B"}

package/out/postcode-binary-resolver.js

@@ -0,0 +1,208 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Browser-side postcode resolver for the anchor (#240). A pure-JS, zero-dependency
+ *   `PostcodeResolver` backed by a compact flat binary instead of SQLite, so the postcode anchor
+ *   runs in the WASM/browser parser behind the same `lookup()` seam as the server-side
+ *   `WofPostcodeLookup`.
+ *
+ *   This file owns BOTH ends of the format — `serializePostcodeBinary` (run in Node by
+ *   `scripts/build-postcode-binary.ts`) and `PostcodeBinaryResolver` (run in the browser) — so the
+ *   layout can never drift between writer and reader.
+ *
+ *   Binary layout (little-endian): magic "PCB1" (4 bytes) u32 recordCount u8 countryCount, then
+ *   countryCount × 2 ASCII bytes (the country table) u8 keyWidth (max postcode length in bytes)
+ *   records recordCount × { key[keyWidth] ASCII right-padded with 0x00, u8 countryIdx, i16 latQ,
+ *   i16 lonQ }, sorted by key bytes ascending. A postcode present in two countries appears as two
+ *   adjacent records (same key, different countryIdx).
+ *
+ *   Coordinates are quantized to i16: latQ = round(lat/90 × 32767), lonQ = round(lon/180 × 32767),
+ *   giving ~300 m resolution — ample for a "which city/region" anchor. A record with latQ = lonQ =
+ *   0 means "known postcode, no centroid" (membership only), matching the SQLite resolver's
+ *   convention.
+ */
+const MAGIC = 0x31_42_43_50; // "PCB1" little-endian (P=0x50 C=0x43 B=0x42 1=0x31)
+const REC_TAIL = 5; // countryIdx(1) + latQ(2) + lonQ(2)
+const LAT_Q = 32767 / 90;
+const LON_Q = 32767 / 180;
+/**
+ * Right-pad an ASCII postcode to `width` with NUL; `\0` sorts below any real char, so shorter keys
+ * order before longer ones with the same prefix, which is what we want.
+ */
+function encodeKey(s, width, out, offset) {
+    for (let i = 0; i < width; i++)
+        out[offset + i] = i < s.length ? s.charCodeAt(i) & 0x7f : 0;
+}
+/**
+ * Serialize postcode entries into the flat binary. Entries are sorted by (postcode, country) so
+ * equal postcodes land in adjacent records. Run in Node; consumed by
+ * {@link PostcodeBinaryResolver}.
+ */
+export function serializePostcodeBinary(entries) {
+    const sorted = [...entries].sort((a, b) => a.postcode < b.postcode
+        ? -1
+        : a.postcode > b.postcode
+            ? 1
+            : a.country < b.country
+                ? -1
+                : a.country > b.country
+                    ? 1
+                    : 0);
+    const countries = [...new Set(sorted.map((e) => e.country))].sort();
+    const countryIdx = new Map(countries.map((c, i) => [c, i]));
+    const keyWidth = sorted.reduce((m, e) => Math.max(m, e.postcode.length), 1);
+    const recSize = keyWidth + REC_TAIL;
+    const headerSize = 4 + 4 + 1 + countries.length * 2 + 1;
+    const buf = new Uint8Array(headerSize + sorted.length * recSize);
+    const view = new DataView(buf.buffer);
+    let o = 0;
+    view.setUint32(o, MAGIC, true);
+    o += 4;
+    view.setUint32(o, sorted.length, true);
+    o += 4;
+    buf[o++] = countries.length;
+    for (const c of countries) {
+        buf[o++] = c.charCodeAt(0) & 0x7f;
+        buf[o++] = c.charCodeAt(1) & 0x7f;
+    }
+    buf[o++] = keyWidth;
+    for (const e of sorted) {
+        encodeKey(e.postcode, keyWidth, buf, o);
+        o += keyWidth;
+        buf[o++] = countryIdx.get(e.country);
+        view.setInt16(o, Math.max(-32767, Math.min(32767, Math.round(e.lat * LAT_Q))), true);
+        o += 2;
+        view.setInt16(o, Math.max(-32767, Math.min(32767, Math.round(e.lon * LON_Q))), true);
+        o += 2;
+    }
+    return buf;
+}
+/**
+ * Pure-JS, browser-safe postcode resolver over the flat binary. Implements the same `lookup()` seam
+ * as the SQLite `WofPostcodeLookup`, so `extractPostcodeAnchors` is agnostic to which backs it.
+ */
+export class PostcodeBinaryResolver {
+    #buf;
+    #view;
+    #count;
+    #countries;
+    #keyWidth;
+    #recSize;
+    #recBase;
+    constructor(bytes) {
+        this.#buf = bytes;
+        this.#view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        if (this.#view.getUint32(0, true) !== MAGIC)
+            throw new Error("postcode binary: bad magic");
+        this.#count = this.#view.getUint32(4, true);
+        let o = 8;
+        const countryCount = bytes[o++];
+        this.#countries = [];
+        for (let i = 0; i < countryCount; i++) {
+            this.#countries.push(String.fromCharCode(bytes[o], bytes[o + 1]));
+            o += 2;
+        }
+        this.#keyWidth = bytes[o++];
+        this.#recSize = this.#keyWidth + REC_TAIL;
+        this.#recBase = o;
+    }
+    /** Compare the keyWidth bytes of record `i` against a padded query key. */
+    #cmpKey(i, key) {
+        const base = this.#recBase + i * this.#recSize;
+        for (let j = 0; j < this.#keyWidth; j++) {
+            const d = this.#buf[base + j] - key[j];
+            if (d !== 0)
+                return d;
+        }
+        return 0;
+    }
+    lookup(postcode) {
+        if (postcode.length > this.#keyWidth)
+            return []; // longer than any stored key → impossible
+        const key = new Uint8Array(this.#keyWidth);
+        encodeKey(postcode, this.#keyWidth, key, 0);
+        // Binary search for the first record whose key >= the query.
+        let lo = 0;
+        let hi = this.#count;
+        while (lo < hi) {
+            const mid = (lo + hi) >>> 1;
+            if (this.#cmpKey(mid, key) < 0)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        // Collect the contiguous run of equal keys (one per country).
+        const out = [];
+        for (let i = lo; i < this.#count && this.#cmpKey(i, key) === 0; i++) {
+            const base = this.#recBase + i * this.#recSize + this.#keyWidth;
+            out.push({
+                country: this.#countries[this.#buf[base]],
+                lat: this.#view.getInt16(base + 1, true) / LAT_Q,
+                lon: this.#view.getInt16(base + 3, true) / LON_Q,
+            });
+        }
+        return out;
+    }
+    /**
+     * Decode the whole binary into an {@link AnchorLookup} (`Map<postcode, AnchorEntry>`) for the
+     * neural anchor channel (#239/#240): each postcode → a uniform posterior over its member
+     * countries
+     *
+     * - The mean of its non-zero centroids. This is the browser-side equivalent of the pilot
+     *   postcode→anchor lookup the model trained against, built live from the shipped binary instead
+     *   of a precomputed JSON. Records are stored sorted by (postcode, country), so equal keys are
+     *   contiguous.
+     */
+    toAnchorLookup() {
+        const out = new Map();
+        let i = 0;
+        while (i < this.#count) {
+            // Decode this record's postcode key (ASCII, 0x00-right-padded).
+            const keyBase = this.#recBase + i * this.#recSize;
+            let postcode = "";
+            for (let j = 0; j < this.#keyWidth; j++) {
+                const c = this.#buf[keyBase + j];
+                if (c === 0)
+                    break;
+                postcode += String.fromCharCode(c);
+            }
+            // Walk the contiguous run of records sharing this key (one per member country).
+            const posterior = {};
+            let latSum = 0;
+            let lonSum = 0;
+            let centroidCount = 0;
+            let k = i;
+            for (; k < this.#count; k++) {
+                const base = this.#recBase + k * this.#recSize;
+                let same = true;
+                for (let j = 0; j < this.#keyWidth; j++) {
+                    if (this.#buf[base + j] !== this.#buf[keyBase + j]) {
+                        same = false;
+                        break;
+                    }
+                }
+                if (!same)
+                    break;
+                const tail = base + this.#keyWidth;
+                posterior[this.#countries[this.#buf[tail]]] = 1; // uniform — anchorFeatureVector renormalizes
+                const lat = this.#view.getInt16(tail + 1, true) / LAT_Q;
+                const lon = this.#view.getInt16(tail + 3, true) / LON_Q;
+                if (lat !== 0 || lon !== 0) {
+                    latSum += lat;
+                    lonSum += lon;
+                    centroidCount++;
+                }
+            }
+            out.set(postcode, {
+                posterior,
+                lat: centroidCount ? latSum / centroidCount : 0,
+                lon: centroidCount ? lonSum / centroidCount : 0,
+            });
+            i = k;
+        }
+        return out;
+    }
+}
+//# sourceMappingURL=postcode-binary-resolver.js.map

package/out/postcode-binary-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postcode-binary-resolver.js","sourceRoot":"","sources":["../postcode-binary-resolver.ts"],"names":[],"mappings":"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"}

package/out/postcode-repair.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Postcode regex repair pass — v0.7 task #35 ("postcode regex pre-pass").
+ *
+ *   The 2026-05-29 postcode diagnostic showed the neural model fragments alphanumeric postcodes at
+ *   the SentencePiece layer (GB/CA/NL at 0%, US 80.5%, FR 70.1%). Three failure modes were visible
+ *   in the data:
+ *
+ *   1. Total miss — "London SW1A 1AA" → (no postcode label)
+ *   2. Truncation — "M5V 2T6" → "2T6"; "B12 8QX" → "B12"
+ *   3. Char-drift — "75008" → "5008"; "62701" → "2701" (and smear: "1200-030 Lisboa" → "200-030 Lis")
+ *
+ *   This pass runs AFTER the model's per-token BIO labels are decoded but BEFORE `buildAddressTree`.
+ *   It detects postcode-shaped substrings with per-country regexes and repairs the label sequence
+ *   so the postcode span matches the detected shape. The model is untouched — this is a
+ *   deterministic decoder-side correction, the "lowest risk" lever in the v0.7 plan (vs. #36's soft
+ *   FST shallow-fusion or #41's char-level encoder).
+ *
+ *   PRECISION GUARDS (so we never regress the countries already passing):
+ *
+ *   - Alphanumeric shapes (GB/CA/NL/DE-prefixed) are high-confidence "this IS a postcode" patterns →
+ *       eligible to ADD a span where the model emitted none, but only over non-structural labels
+ *       (never over house_number/street/etc.).
+ *   - Numeric shapes (\d{5}, ZIP+4, JP, PT, PL) are ambiguous (a bare 5-digit could be a house number)
+ *       → SNAP-only: they expand/clip an EXISTING postcode span, never create one from scratch.
+ *   - Smear cleanup is LOCAL: only postcode tokens immediately flanking a snapped span are cleared. We
+ *       never globally clear unmatched postcode tokens — that would regress shapes we don't
+ *       pattern-match (AU 4-digit, IN 6-digit, …).
+ */
+import type { DecoderToken } from "@mailwoman/core/decoder";
+/** A detected postcode-shaped substring with its char range and confidence class. */
+export interface PostcodeMatch {
+    start: number;
+    end: number;
+    /** "alnum" shapes may ADD; "numeric" shapes may only SNAP an existing span. */
+    kind: "alnum" | "numeric";
+    /** Pattern priority (lower = more specific, wins overlap resolution). */
+    priority: number;
+}
+/**
+ * Per-country postcode shape patterns, ordered most-specific → least. Alphanumeric patterns require
+ * uppercase letters (postcodes are conventionally uppercase, and the eval data has them uppercase)
+ * — this keeps them from matching ordinary lowercase prose.
+ */
+export declare const POSTCODE_PATTERNS: Array<{
+    label: string;
+    kind: "alnum" | "numeric";
+    re: RegExp;
+}>;
+/** Collect non-overlapping postcode matches, preferring more-specific (earlier) patterns. */
+export declare function collectMatches(text: string): PostcodeMatch[];
+export interface RepairResult {
+    tokens: DecoderToken[];
+    /** Number of token labels changed — for telemetry / logging. */
+    changed: number;
+}
+/**
+ * Repair postcode label spans in a decoded token sequence using per-country regexes. Returns a NEW
+ * token array (inputs are not mutated) plus a change count.
+ */
+export declare function repairPostcodeLabels(text: string, input: readonly DecoderToken[]): RepairResult;
+//# sourceMappingURL=postcode-repair.d.ts.map

package/out/postcode-repair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postcode-repair.d.ts","sourceRoot":"","sources":["../postcode-repair.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAE3D,qFAAqF;AACrF,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,+EAA+E;IAC/E,IAAI,EAAE,OAAO,GAAG,SAAS,CAAA;IACzB,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAA;CAChB;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,GAAG,SAAS,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAiB7F,CAAA;AA0BD,6FAA6F;AAC7F,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,EAAE,CAkB5D;AAED,MAAM,WAAW,YAAY;IAC5B,MAAM,EAAE,YAAY,EAAE,CAAA;IACtB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,YAAY,CAmE/F"}