@mailwoman/neural 2.1.0 → 4.0.0

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

package/out/postcode-repair.js

@@ -0,0 +1,171 @@
+/**
+ * @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, …).
+ */
+/**
+ * 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 const POSTCODE_PATTERNS = [
+    // --- Alphanumeric (eligible to ADD) ---
+    // GB: outward + space + inward, e.g. SW1A 1AA, EH8 9YL, W1J 9PN, IP13 6SU, B12 8QX
+    { label: "GB", kind: "alnum", re: /\b[A-Z]{1,2}\d[A-Z\d]?\s+\d[A-Z]{2}\b/g },
+    // CA: A1A 1A1 (space optional), e.g. M5V 2T6, H2X 2T6, H3B 1A3
+    { label: "CA", kind: "alnum", re: /\b[A-Z]\d[A-Z]\s?\d[A-Z]\d\b/g },
+    // DE-prefixed: D-68161
+    { label: "DE", kind: "alnum", re: /\bD-\d{5}\b/g },
+    // NL: 1234 AB / 1234AB — space optional (glued is common). The US "2737 CA" (ZIP+4 tail +
+    // state) collision is resolved by longest-match-wins below, which lets the ZIP+4 claim it.
+    { label: "NL", kind: "alnum", re: /\b\d{4}\s?[A-Z]{2}\b/g },
+    // --- Numeric (SNAP-only) ---
+    { label: "ZIP4", kind: "numeric", re: /\b\d{5}-\d{4}\b/g }, // US ZIP+4
+    { label: "JP", kind: "numeric", re: /\b\d{3}-\d{4}\b/g }, // 100-0001
+    { label: "PT", kind: "numeric", re: /\b\d{4}-\d{3}\b/g }, // 3060-187
+    { label: "PL", kind: "numeric", re: /\b\d{2}-\d{3}\b/g }, // 47-400
+    { label: "NUM5", kind: "numeric", re: /\b\d{5}\b/g }, // US/FR/DE/ES 5-digit
+];
+/**
+ * Labels a postcode span is allowed to overwrite when the model emitted no postcode at all (ADD
+ * path). These are the geographic-container tags postcodes get confused with per the diagnostic
+ * ("often labeled as locality or O"). Structural tags (house_number, street*, unit, po_box, venue,
+ * …) are intentionally absent so we never clobber a confidently-labeled street/number with a false
+ * postcode.
+ */
+const ADD_OVER_TAGS = new Set(["locality", "dependent_locality", "region", "subregion", "country"]);
+const POSTCODE_B = "B-postcode";
+const POSTCODE_I = "I-postcode";
+const LOCALITY_B = "B-locality";
+const LOCALITY_I = "I-locality";
+const OUTSIDE = "O";
+function isPostcodeLabel(label) {
+    return label === "B-postcode" || label === "I-postcode";
+}
+/** Extract the bare tag from a BIO label ("B-locality" → "locality", "O" → null). */
+function tagOf(label) {
+    return label === "O" ? null : label.slice(2);
+}
+/** Collect non-overlapping postcode matches, preferring more-specific (earlier) patterns. */
+export function collectMatches(text) {
+    const candidates = [];
+    POSTCODE_PATTERNS.forEach((pat, priority) => {
+        pat.re.lastIndex = 0;
+        for (let m = pat.re.exec(text); m; m = pat.re.exec(text)) {
+            candidates.push({ start: m.index, end: m.index + m[0].length, kind: pat.kind, priority });
+        }
+    });
+    // Greedy longest-match-wins: accept by (length desc, then priority asc); reject anything
+    // overlapping an accepted match. Longest-first lets a US ZIP+4 ("94610-2737") claim its span
+    // before the shorter NL-shaped false positive in its tail ("2737 CA") can.
+    candidates.sort((a, b) => b.end - b.start - (a.end - a.start) || a.priority - b.priority);
+    const accepted = [];
+    for (const c of candidates) {
+        if (accepted.some((a) => c.start < a.end && a.start < c.end))
+            continue;
+        accepted.push(c);
+    }
+    return accepted;
+}
+/**
+ * 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 function repairPostcodeLabels(text, input) {
+    const matches = collectMatches(text);
+    const tokens = input.map((t) => ({ ...t }));
+    if (matches.length === 0)
+        return { tokens, changed: 0 };
+    let changed = 0;
+    const setLabel = (i, label) => {
+        if (tokens[i].label !== label) {
+            tokens[i].label = label;
+            changed++;
+        }
+    };
+    for (const m of matches) {
+        // Tokens whose char span intersects the match.
+        const overlap = [];
+        for (let i = 0; i < tokens.length; i++) {
+            const t = tokens[i];
+            if (t.start < m.end && m.start < t.end)
+                overlap.push(i);
+        }
+        if (overlap.length === 0)
+            continue;
+        const hasPostcode = overlap.some((i) => isPostcodeLabel(tokens[i].label));
+        if (!hasPostcode) {
+            // ADD path — only for high-confidence alphanumeric shapes, only over safe labels.
+            if (m.kind !== "alnum")
+                continue;
+            const safe = overlap.every((i) => {
+                const tag = tagOf(tokens[i].label);
+                return tag === null || ADD_OVER_TAGS.has(tag);
+            });
+            if (!safe)
+                continue;
+        }
+        // SNAP/ADD: relabel the matched run as a single postcode span.
+        overlap.forEach((i, k) => setLabel(i, k === 0 ? POSTCODE_B : POSTCODE_I));
+        // Leading smear clip: postcode tokens immediately BEFORE the snapped run are noise (e.g. a
+        // house-number digit the model over-labeled) — clear to O as before.
+        for (let j = overlap[0] - 1; j >= 0 && isPostcodeLabel(tokens[j].label); j--)
+            setLabel(j, OUTSIDE);
+        // Trailing smear: the model over-extended the postcode to the RIGHT. In postcode-before-city
+        // locales (DE/FR/ES/IT, "08523 Plauen") this swallows the leading characters of the city, which
+        // the historical clip-to-O then DISCARDED ("08523 Pl|auen Vogtl" → postcode "08523" + O +
+        // locality "auen Vogtl", dropping the "Pl"). When the smear connects to a following locality run,
+        // hand those characters BACK to the city — reassign them to locality and demote the city's
+        // leading B so the prefix + city form ONE span ("Pl"+"auen"+"Vogtl" → "Plauen Vogtl"). A
+        // standalone neighbour with no following locality (a country, "Paris 75008 France") keeps the
+        // historical clip-to-O. This is the decoder-side repair for the cross-tag postcode→city
+        // absorption diagnosed in the PR3 Pilot A postmortem (+36pp DE exact-locality, no-op on US,
+        // where the postcode sits at the end with nothing to trim).
+        const trailing = [];
+        for (let j = overlap[overlap.length - 1] + 1; j < tokens.length && isPostcodeLabel(tokens[j].label); j++) {
+            trailing.push(j);
+        }
+        if (trailing.length > 0) {
+            const after = trailing[trailing.length - 1] + 1;
+            const connectsToCity = after < tokens.length && tagOf(tokens[after].label) === "locality";
+            if (connectsToCity) {
+                trailing.forEach((j, k) => setLabel(j, k === 0 ? LOCALITY_B : LOCALITY_I));
+                if (tokens[after].label === "B-locality")
+                    setLabel(after, LOCALITY_I);
+            }
+            else {
+                for (const j of trailing)
+                    setLabel(j, OUTSIDE);
+            }
+        }
+    }
+    return { tokens, changed };
+}
+//# sourceMappingURL=postcode-repair.js.map

package/out/postcode-repair.js.map

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

package/out/proposal-classifier.d.ts

@@ -24,7 +24,11 @@ export interface NeuralProposalClassifierConfig {
     id: string;
     /** The underlying neural classifier instance. */
     classifier: NeuralAddressClassifier;
-    /** Component tags this classifier may emit. Defaults to Stage 1 coarse tags. */
+    /**
+     * Component tags this classifier may emit. Defaults to the Stage 2 tag set (coarse +
+     * venue/street/house_number). v0.2.0 Stage 1 models never decode to the fine tags anyway, so the
+     * broader default is forwards-compat without back-compat risk.
+     */
     emits?: readonly ComponentTag[];
     /** Locales this classifier is active for. `["*"]` (locale-agnostic) by default. */
     locales?: readonly (string | "*")[];

package/out/proposal-classifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proposal-classifier.d.ts","sourceRoot":"","sources":["../proposal-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAGX,YAAY,EACZ,kBAAkB,EAElB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAA;AAG9D,MAAM,WAAW,8BAA8B;IAC9C,wFAAwF;IACxF,EAAE,EAAE,MAAM,CAAA;IACV,iDAAiD;IACjD,UAAU,EAAE,uBAAuB,CAAA;IACnC,gFAAgF;IAChF,KAAK,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IAC/B,mFAAmF;IACnF,OAAO,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,GAAG,CAAC,EAAE,CAAA;IACnC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,0EAA0E;AAC1E,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,8BAA8B,GAAG,kBAAkB,CA6CtG"}
+{"version":3,"file":"proposal-classifier.d.ts","sourceRoot":"","sources":["../proposal-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAGX,YAAY,EACZ,kBAAkB,EAElB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAA;AAG9D,MAAM,WAAW,8BAA8B;IAC9C,wFAAwF;IACxF,EAAE,EAAE,MAAM,CAAA;IACV,iDAAiD;IACjD,UAAU,EAAE,uBAAuB,CAAA;IACnC;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IAC/B,mFAAmF;IACnF,OAAO,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,GAAG,CAAC,EAAE,CAAA;IACnC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,0EAA0E;AAC1E,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,8BAA8B,GAAG,kBAAkB,CA+CtG"}

package/out/proposal-classifier.js

@@ -17,14 +17,16 @@
  *   inference is a future optimization once the policy layer has a way to invoke a classifier "once
  *   per parse" instead of per section.
  */
-import { STAGE1_COARSE_TAGS } from "./labels.js";
+import { STAGE2_TAGS } from "./labels.js";
 /** Build a `ProposalClassifier` backed by a `NeuralAddressClassifier`. */
 export function createNeuralProposalClassifier(cfg) {
-    const emits = cfg.emits ?? STAGE1_COARSE_TAGS;
+    const emits = cfg.emits ?? STAGE2_TAGS;
     const emitsSet = new Set(emits);
     const penalty = cfg.penalty ?? 0;
     async function classify(section, _ctx) {
-        const tree = await cfg.classifier.parse(section.body);
+        // Postcode regex repair on by default (v0.7 #35, operator-signed): +135/0 on the postcode
+        // harness, model-independent. Fixes the SentencePiece-fragmentation misses (GB/CA/NL/…).
+        const tree = await cfg.classifier.parse(section.body, { postcodeRepair: true });
         const proposals = [];
         const sectionOffset = section.start;
         const visit = (node) => {

package/out/proposal-classifier.js.map

@@ -1 +1 @@
-{"version":3,"file":"proposal-classifier.js","sourceRoot":"","sources":["../proposal-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAYH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAehD,0EAA0E;AAC1E,MAAM,UAAU,8BAA8B,CAAC,GAAmC;IACjF,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,IAAI,kBAAkB,CAAA;IAC7C,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAe,KAAgC,CAAC,CAAA;IACxE,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,CAAC,CAAA;IAEhC,KAAK,UAAU,QAAQ,CAAC,OAAgB,EAAE,IAAuB;QAChE,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;QACrD,MAAM,SAAS,GAA6B,EAAE,CAAA;QAC9C,MAAM,aAAa,GAAG,OAAO,CAAC,KAAK,CAAA;QAEnC,MAAM,KAAK,GAAG,CAAC,IAAiB,EAAQ,EAAE;YACzC,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC5B,wFAAwF;gBACxF,oFAAoF;gBACpF,uFAAuF;gBACvF,iFAAiF;gBACjF,mFAAmF;gBACnF,2EAA2E;gBAC3E,MAAM,IAAI,GAAG;oBACZ,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC,KAAK;oBACjC,GAAG,EAAE,aAAa,GAAG,IAAI,CAAC,GAAG;oBAC7B,IAAI,EAAE,IAAI,CAAC,KAAK;iBACG,CAAA;gBACpB,SAAS,CAAC,IAAI,CAAC;oBACd,IAAI;oBACJ,SAAS,EAAE,IAAI,CAAC,GAAG;oBACnB,UAAU,EAAE,IAAI,CAAC,UAAU;oBAC3B,MAAM,EAAE,QAAQ;oBAChB,SAAS,EAAE,GAAG,CAAC,EAAE;oBACjB,OAAO;iBACP,CAAC,CAAA;YACH,CAAC;YACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;gBAAE,KAAK,CAAC,KAAK,CAAC,CAAA;QAChD,CAAC,CAAA;QAED,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK;YAAE,KAAK,CAAC,IAAI,CAAC,CAAA;QAC1C,OAAO,SAAS,CAAA;IACjB,CAAC;IAED,OAAO;QACN,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,KAAK;QACL,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC;QAC7B,QAAQ;KACR,CAAA;AACF,CAAC"}
+{"version":3,"file":"proposal-classifier.js","sourceRoot":"","sources":["../proposal-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAYH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAmBzC,0EAA0E;AAC1E,MAAM,UAAU,8BAA8B,CAAC,GAAmC;IACjF,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,IAAI,WAAW,CAAA;IACtC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAe,KAAgC,CAAC,CAAA;IACxE,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,CAAC,CAAA;IAEhC,KAAK,UAAU,QAAQ,CAAC,OAAgB,EAAE,IAAuB;QAChE,0FAA0F;QAC1F,yFAAyF;QACzF,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,CAAA;QAC/E,MAAM,SAAS,GAA6B,EAAE,CAAA;QAC9C,MAAM,aAAa,GAAG,OAAO,CAAC,KAAK,CAAA;QAEnC,MAAM,KAAK,GAAG,CAAC,IAAiB,EAAQ,EAAE;YACzC,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC5B,wFAAwF;gBACxF,oFAAoF;gBACpF,uFAAuF;gBACvF,iFAAiF;gBACjF,mFAAmF;gBACnF,2EAA2E;gBAC3E,MAAM,IAAI,GAAG;oBACZ,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC,KAAK;oBACjC,GAAG,EAAE,aAAa,GAAG,IAAI,CAAC,GAAG;oBAC7B,IAAI,EAAE,IAAI,CAAC,KAAK;iBACG,CAAA;gBACpB,SAAS,CAAC,IAAI,CAAC;oBACd,IAAI;oBACJ,SAAS,EAAE,IAAI,CAAC,GAAG;oBACnB,UAAU,EAAE,IAAI,CAAC,UAAU;oBAC3B,MAAM,EAAE,QAAQ;oBAChB,SAAS,EAAE,GAAG,CAAC,EAAE;oBACjB,OAAO;iBACP,CAAC,CAAA;YACH,CAAC;YACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;gBAAE,KAAK,CAAC,KAAK,CAAC,CAAA;QAChD,CAAC,CAAA;QAED,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK;YAAE,KAAK,CAAC,IAAI,CAAC,CAAA;QAC1C,OAAO,SAAS,CAAA;IACjB,CAAC;IAED,OAAO;QACN,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,KAAK;QACL,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC;QAC7B,QAAQ;KACR,CAAA;AACF,CAAC"}

package/out/query-shape-prior.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Soft-prior emission biases derived from `QueryShape`.
+ *
+ *   When the QueryShape sub-system has identified a known-format span (US ZIP, UK postcode, PO box,
+ *   etc.), this module produces an additive bias matrix that nudges the encoder's per-token
+ *   emissions toward the matching BIO label. The biases compose with the structural BIO mask in the
+ *   Viterbi decoder — confident encoder predictions still win, but uncertain ones get pulled toward
+ *   the format-implied label.
+ *
+ *   Bitter-lesson-safe boundary: we don't override the encoder, just bias it. The encoder remains the
+ *   authority on context-dependent calls (the "Buffalo Wild Wings, Buffalo, NY" disambiguation);
+ *   the QueryShape prior helps on the easy cases (a 5-digit token is _probably_ a postcode).
+ *
+ *   Uses structural typing for the QueryShape input so this module has zero dependencies on
+ *   `@mailwoman/query-shape` — consumers compute the shape with that package, pass it in here.
+ */
+/**
+ * Minimal subset of `QueryShape` this module consumes. Compatible with `@mailwoman/query-shape`'s
+ * exported `QueryShape` type by shape — no import required.
+ */
+export interface QueryShapeLike {
+    knownFormats: ReadonlyArray<KnownFormatHitLike>;
+    regionAbbreviations?: ReadonlyArray<RegionAbbreviationHitLike>;
+}
+export interface RegionAbbreviationHitLike {
+    start: number;
+    span: string;
+}
+export interface KnownFormatHitLike {
+    format: string;
+    span: {
+        start: number;
+        end: number;
+    };
+    /** 0..1; ambiguous patterns (e.g. 5-digit US/FR/DE overlap) score lower. */
+    confidence: number;
+}
+/** Minimal subset of `TokenizedPiece` this module consumes. */
+export interface TokenLike {
+    start: number;
+    end: number;
+}
+export interface BuildPriorsOpts {
+    /**
+     * Maximum bias magnitude (in log-odds units). Default 1.0 — adds up to ~e^1 ≈ 2.7× odds to the
+     * favored label. Confidence-scaled, so a 0.6-confidence format hit gets +0.6 max bias.
+     */
+    biasScale?: number;
+    /**
+     * Bias magnitude for the locality soft prior (in log-odds units). Default 2.0 — adds ~e^2 ≈ 7.4×
+     * odds to B-locality / I-locality for tokens preceding a detected region abbreviation.
+     */
+    localityBiasScale?: number;
+    /** Raw input text for region-name matching in the locality bias guard. */
+    inputText?: string;
+}
+/**
+ * Build a `[seqLen][numLabels]` matrix of additive log-bias to be added to encoder emissions before
+ * Viterbi decoding.
+ *
+ * For each (token, format-hit) pair where the token's character span overlaps the hit's span, the
+ * matrix entry for the format's mapped label receives `hit.confidence × biasScale`. Tokens that
+ * don't overlap any hit, or for which no label mapping exists, get 0.
+ *
+ * Returns the all-zeros matrix if `shape.knownFormats` is empty — composes harmlessly.
+ */
+export declare function buildEmissionPriors(shape: QueryShapeLike, tokens: ReadonlyArray<TokenLike>, labels: ReadonlyArray<string>, opts?: BuildPriorsOpts): number[][];
+/** Element-wise add two matrices of equal shape. Returns a new matrix. */
+export declare function addEmissionMatrix(emissions: number[][], priors: number[][]): number[][];
+//# sourceMappingURL=query-shape-prior.d.ts.map

package/out/query-shape-prior.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-shape-prior.d.ts","sourceRoot":"","sources":["../query-shape-prior.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,YAAY,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAA;IAC/C,mBAAmB,CAAC,EAAE,aAAa,CAAC,yBAAyB,CAAC,CAAA;CAC9D;AAED,MAAM,WAAW,yBAAyB;IACzC,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,kBAAkB;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;IACpC,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAA;CAClB;AAED,+DAA+D;AAC/D,MAAM,WAAW,SAAS;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;CACX;AAiBD,MAAM,WAAW,eAAe;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,EAChC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,EAC7B,IAAI,GAAE,eAAoB,GACxB,MAAM,EAAE,EAAE,CAoCZ;AA2ID,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,EAAE,CAWvF"}