@mailwoman/neural 2.1.0 → 4.0.0

package/out/query-shape-prior.js

@@ -0,0 +1,223 @@
+/**
+ * @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.
+ */
+/**
+ * Mapping from `KnownFormat` strings to the BIO label that should be boosted. Multiple formats may
+ * map to the same label (all postcode flavors → `B-postcode`).
+ */
+const FORMAT_TO_LABEL = new Map([
+    ["us_zip", "B-postcode"],
+    ["us_zip4", "B-postcode"],
+    ["fr_postcode", "B-postcode"],
+    ["de_postcode", "B-postcode"],
+    ["uk_postcode", "B-postcode"],
+    ["ca_postcode", "B-postcode"],
+    ["jp_postcode", "B-postcode"],
+    ["po_box", "B-po_box"],
+]);
+/**
+ * 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 function buildEmissionPriors(shape, tokens, labels, opts = {}) {
+    const T = tokens.length;
+    const L = labels.length;
+    const biasScale = opts.biasScale ?? 1.0;
+    const matrix = [];
+    for (let t = 0; t < T; t++)
+        matrix.push(new Array(L).fill(0));
+    // Index label → column for fast lookup.
+    const labelToCol = new Map();
+    for (let k = 0; k < labels.length; k++)
+        labelToCol.set(labels[k], k);
+    if (shape.knownFormats.length === 0 && (!shape.regionAbbreviations || shape.regionAbbreviations.length === 0)) {
+        return matrix;
+    }
+    for (const hit of shape.knownFormats) {
+        const targetLabel = FORMAT_TO_LABEL.get(hit.format);
+        if (!targetLabel)
+            continue;
+        const col = labelToCol.get(targetLabel);
+        if (col === undefined)
+            continue;
+        const bias = hit.confidence * biasScale;
+        for (let t = 0; t < T; t++) {
+            const tok = tokens[t];
+            if (overlaps(tok, hit.span)) {
+                matrix[t][col] = Math.max(matrix[t][col], bias);
+            }
+        }
+    }
+    // Locality soft prior: when a region abbreviation is detected (e.g., "DC", "NY"), bias
+    // preceding alphabetic tokens toward B-locality / I-locality. This counters the WOF
+    // bare-name frequency dominance that makes the model over-emit B-region on ambiguous
+    // place names like "Washington" or "New York".
+    applyLocalityBias(matrix, shape, tokens, labelToCol, opts.localityBiasScale ?? 2.0, opts.inputText);
+    return matrix;
+}
+/**
+ * Apply locality bias to tokens preceding a detected region abbreviation.
+ *
+ * For "Washington, DC" — "DC" is the region abbreviation; "Washington" gets biased toward
+ * B-locality. For "New York, NY" — "New" gets B-locality and "York" gets I-locality.
+ *
+ * Guard: if the preceding text matches the full name of the region that the abbreviation represents
+ * (e.g., "Washington" before "WA"), the locality bias is NOT applied — the text IS the region, not
+ * a locality within it.
+ *
+ * Constraint: only bias tokens that appear BEFORE the abbreviation's character offset and are
+ * alphabetic (start with uppercase). Tokens that are part of a known postcode format or are
+ * themselves region abbreviations are skipped.
+ */
+function applyLocalityBias(matrix, shape, tokens, labelToCol, localityBias, inputText) {
+    const abbrevs = shape.regionAbbreviations;
+    if (!abbrevs || abbrevs.length === 0)
+        return;
+    const bLocCol = labelToCol.get("B-locality");
+    const iLocCol = labelToCol.get("I-locality");
+    if (bLocCol === undefined)
+        return;
+    for (const abbrev of abbrevs) {
+        const candidates = [];
+        let prevStart = abbrev.start;
+        for (let t = tokens.length - 1; t >= 0; t--) {
+            const tok = tokens[t];
+            if (tok.end > abbrev.start)
+                continue;
+            const gap = prevStart - tok.end;
+            if (candidates.length === 0 && gap > 4)
+                break;
+            if (candidates.length > 0 && gap > 2)
+                break;
+            let isPostcode = false;
+            for (const fmt of shape.knownFormats) {
+                if (overlaps(tok, fmt.span)) {
+                    isPostcode = true;
+                    break;
+                }
+            }
+            if (isPostcode)
+                break;
+            candidates.push(t);
+            prevStart = tok.start;
+        }
+        if (candidates.length === 0)
+            continue;
+        candidates.reverse();
+        if (inputText) {
+            const firstTok = tokens[candidates[0]];
+            const lastTok = tokens[candidates[candidates.length - 1]];
+            const candidateText = inputText.slice(firstTok.start, lastTok.end).toLowerCase();
+            const regionNames = ABBREV_TO_REGION.get(abbrev.span);
+            if (regionNames?.some((name) => candidateText === name))
+                continue;
+        }
+        for (let i = 0; i < candidates.length; i++) {
+            const t = candidates[i];
+            const col = i === 0 ? bLocCol : iLocCol;
+            if (col === undefined)
+                continue;
+            matrix[t][col] = Math.max(matrix[t][col], localityBias);
+        }
+    }
+}
+const ABBREV_TO_REGION = new Map([
+    ["AL", ["alabama"]],
+    ["AK", ["alaska"]],
+    ["AZ", ["arizona"]],
+    ["AR", ["arkansas"]],
+    ["CA", ["california"]],
+    ["CO", ["colorado"]],
+    ["CT", ["connecticut"]],
+    ["DE", ["delaware"]],
+    ["DC", ["district of columbia"]],
+    ["FL", ["florida"]],
+    ["GA", ["georgia"]],
+    ["HI", ["hawaii"]],
+    ["ID", ["idaho"]],
+    ["IL", ["illinois"]],
+    ["IN", ["indiana"]],
+    ["IA", ["iowa"]],
+    ["KS", ["kansas"]],
+    ["KY", ["kentucky"]],
+    ["LA", ["louisiana"]],
+    ["ME", ["maine"]],
+    ["MD", ["maryland"]],
+    ["MA", ["massachusetts"]],
+    ["MI", ["michigan"]],
+    ["MN", ["minnesota"]],
+    ["MS", ["mississippi"]],
+    ["MO", ["missouri"]],
+    ["MT", ["montana"]],
+    ["NE", ["nebraska"]],
+    ["NV", ["nevada"]],
+    ["NH", ["new hampshire"]],
+    ["NJ", ["new jersey"]],
+    ["NM", ["new mexico"]],
+    ["NY", ["new york"]],
+    ["NC", ["north carolina"]],
+    ["ND", ["north dakota"]],
+    ["OH", ["ohio"]],
+    ["OK", ["oklahoma"]],
+    ["OR", ["oregon"]],
+    ["PA", ["pennsylvania"]],
+    ["RI", ["rhode island"]],
+    ["SC", ["south carolina"]],
+    ["SD", ["south dakota"]],
+    ["TN", ["tennessee"]],
+    ["TX", ["texas"]],
+    ["UT", ["utah"]],
+    ["VT", ["vermont"]],
+    ["VA", ["virginia"]],
+    ["WA", ["washington"]],
+    ["WV", ["west virginia"]],
+    ["WI", ["wisconsin"]],
+    ["WY", ["wyoming"]],
+    ["AS", ["american samoa"]],
+    ["GU", ["guam"]],
+    ["MP", ["northern mariana islands"]],
+    ["PR", ["puerto rico"]],
+    ["VI", ["virgin islands"]],
+]);
+function overlaps(a, b) {
+    return a.start < b.end && b.start < a.end;
+}
+/** Element-wise add two matrices of equal shape. Returns a new matrix. */
+export function addEmissionMatrix(emissions, priors) {
+    if (priors.length === 0)
+        return emissions.map((row) => row.slice());
+    const out = [];
+    for (let t = 0; t < emissions.length; t++) {
+        const e = emissions[t];
+        const p = priors[t] ?? new Array(e.length).fill(0);
+        const row = new Array(e.length);
+        for (let k = 0; k < e.length; k++)
+            row[k] = e[k] + (p[k] ?? 0);
+        out.push(row);
+    }
+    return out;
+}
+//# sourceMappingURL=query-shape-prior.js.map

package/out/query-shape-prior.js.map

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

package/out/street-morphology-prior.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Street-morphology emission bias — Layer 1 of the four-layer street-supplement architecture (see
+ *   `docs/articles/concepts/street-supplement-architecture.md`).
+ *
+ *   This module composes with {@linkcode buildFstEmissionPriors} (admin FST) and the QueryShape prior
+ *   via {@linkcode addEmissionMatrix} — same shape, same additive semantics. Where the admin FST
+ *   biases admin BIO labels (`B/I-locality`, `B/I-region`, ...), the morphology FST biases:
+ *
+ *   - **Affix-token (the matched span):** toward `B/I-street_prefix` AND `B/I-street_suffix` (position
+ *       unknown — let the model + context disambiguate).
+ *   - **Adjacent token (one before AND one after each match):** toward `B/I-street`, AWAY from
+ *       `B/I-dependent_locality`. The negative bias on `dependent_locality` is the load-bearing
+ *       piece — it closes the inference-time vacuum that caused v0.6.1's 1066 dep_locality
+ *       hallucinations (see [[project-v061-failure-mechanism]]).
+ *
+ *   The morphology FST itself is built by `resolver-wof-sqlite/street-morphology-fst-builder.ts` and
+ *   ships as a separate binary (`fst-street-morphology.bin`) loaded into a second `FstMatcher`
+ *   instance.
+ */
+import { type FstMatcherLike } from "./fst-prior.js";
+import type { TokenLike } from "./query-shape-prior.js";
+export interface StreetMorphologyPriorOpts {
+    /** Multiplier on the base bias before {@linkcode maxBias} is applied. Default 1.0. */
+    biasScale?: number;
+    /**
+     * Maximum bias magnitude (logits) on the affix span itself. Default 3.0 — same as the admin FST.
+     * The morphology signal is structurally less ambiguous than admin names (`Avenue` is almost never
+     * anything but street-typing), so equal magnitude is justified.
+     */
+    maxAffixBias?: number;
+    /**
+     * Maximum bias magnitude (logits) on the adjacent (neighbour) tokens for the `street` label.
+     * Default 2.0 — a touch weaker than the affix bias because the neighbour is inferred from
+     * adjacency, not direct match.
+     */
+    maxNeighbourStreetBias?: number;
+    /**
+     * Magnitude of the negative bias applied to `dependent_locality` BIO labels on the adjacent
+     * tokens. Default 2.0. This is the load-bearing piece.
+     */
+    dependentLocalityPenalty?: number;
+}
+/**
+ * Build a `[seqLen][numLabels]` bias matrix from street-morphology FST matches.
+ *
+ * The output composes with the admin FST bias matrix via {@linkcode addEmissionMatrix} — same
+ * `addEmissionMatrix(emissions, fstBias) → biasedEmissions` pattern as the existing admin prior.
+ */
+export declare function buildStreetMorphologyEmissionPriors(fst: FstMatcherLike, pieces: ReadonlyArray<TokenLike & {
+    piece: string;
+}>, labels: ReadonlyArray<string>, opts?: StreetMorphologyPriorOpts): number[][];
+//# sourceMappingURL=street-morphology-prior.d.ts.map

package/out/street-morphology-prior.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"street-morphology-prior.d.ts","sourceRoot":"","sources":["../street-morphology-prior.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAwB,KAAK,cAAc,EAAkB,MAAM,gBAAgB,CAAA;AAC1F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAEvD,MAAM,WAAW,yBAAyB;IACzC,sFAAsF;IACtF,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B;;;OAGG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAA;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CAClD,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,aAAa,CAAC,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,EACpD,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,EAC7B,IAAI,GAAE,yBAA8B,GAClC,MAAM,EAAE,EAAE,CAgIZ"}

package/out/street-morphology-prior.js

@@ -0,0 +1,159 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Street-morphology emission bias — Layer 1 of the four-layer street-supplement architecture (see
+ *   `docs/articles/concepts/street-supplement-architecture.md`).
+ *
+ *   This module composes with {@linkcode buildFstEmissionPriors} (admin FST) and the QueryShape prior
+ *   via {@linkcode addEmissionMatrix} — same shape, same additive semantics. Where the admin FST
+ *   biases admin BIO labels (`B/I-locality`, `B/I-region`, ...), the morphology FST biases:
+ *
+ *   - **Affix-token (the matched span):** toward `B/I-street_prefix` AND `B/I-street_suffix` (position
+ *       unknown — let the model + context disambiguate).
+ *   - **Adjacent token (one before AND one after each match):** toward `B/I-street`, AWAY from
+ *       `B/I-dependent_locality`. The negative bias on `dependent_locality` is the load-bearing
+ *       piece — it closes the inference-time vacuum that caused v0.6.1's 1066 dep_locality
+ *       hallucinations (see [[project-v061-failure-mechanism]]).
+ *
+ *   The morphology FST itself is built by `resolver-wof-sqlite/street-morphology-fst-builder.ts` and
+ *   ships as a separate binary (`fst-street-morphology.bin`) loaded into a second `FstMatcher`
+ *   instance.
+ */
+import { groupPiecesIntoWords } from "./fst-prior.js";
+/**
+ * Build a `[seqLen][numLabels]` bias matrix from street-morphology FST matches.
+ *
+ * The output composes with the admin FST bias matrix via {@linkcode addEmissionMatrix} — same
+ * `addEmissionMatrix(emissions, fstBias) → biasedEmissions` pattern as the existing admin prior.
+ */
+export function buildStreetMorphologyEmissionPriors(fst, pieces, labels, opts = {}) {
+    const T = pieces.length;
+    const L = labels.length;
+    const biasScale = opts.biasScale ?? 1.0;
+    const maxAffixBias = opts.maxAffixBias ?? 3.0;
+    const maxNeighbourStreetBias = opts.maxNeighbourStreetBias ?? 2.0;
+    const dependentLocalityPenalty = opts.dependentLocalityPenalty ?? 2.0;
+    const matrix = [];
+    for (let t = 0; t < T; t++)
+        matrix.push(new Array(L).fill(0));
+    const labelToCol = new Map();
+    for (let k = 0; k < labels.length; k++)
+        labelToCol.set(labels[k], k);
+    const bStreetPrefix = labelToCol.get("B-street_prefix");
+    const iStreetPrefix = labelToCol.get("I-street_prefix");
+    const bStreetSuffix = labelToCol.get("B-street_suffix");
+    const iStreetSuffix = labelToCol.get("I-street_suffix");
+    const bStreet = labelToCol.get("B-street");
+    const iStreet = labelToCol.get("I-street");
+    const bDepLoc = labelToCol.get("B-dependent_locality");
+    const iDepLoc = labelToCol.get("I-dependent_locality");
+    // If the label vocabulary doesn't include street tags at all (e.g. a Stage 1 model), there's
+    // nothing to bias toward. Return zero-matrix and let the additive pipeline no-op.
+    if (bStreet === undefined || bStreetPrefix === undefined || bStreetSuffix === undefined) {
+        return matrix;
+    }
+    const wordGroups = groupPiecesIntoWords(pieces);
+    if (wordGroups.length === 0)
+        return matrix;
+    const affixMatches = [];
+    // Pass 1 — walk every contiguous subpath, collect accepting morphology matches, and apply
+    // the affix bias to matched tokens.
+    for (let start = 0; start < wordGroups.length; start++) {
+        const group = wordGroups[start];
+        if (group.fstToken === "")
+            continue;
+        const initial = fst.walk([group.fstToken]);
+        if (!initial)
+            continue;
+        let bestEnd = -1;
+        let bestStateId = -1;
+        if (initial.accepted) {
+            bestEnd = start;
+            bestStateId = initial.stateId;
+        }
+        let current = initial;
+        for (let end = start + 1; end < wordGroups.length; end++) {
+            const nextGroup = wordGroups[end];
+            if (nextGroup.fstToken === "")
+                continue;
+            const next = fst.walkFrom(current, nextGroup.fstToken);
+            if (!next)
+                break;
+            if (next.accepted) {
+                bestEnd = end;
+                bestStateId = next.stateId;
+            }
+            current = next;
+        }
+        if (bestEnd === -1)
+            continue;
+        // Verify the accepting entries are street_affix (the morphology FST may eventually contain
+        // other placetypes if the binary format is reused for related priors).
+        const entries = fst.accepting(bestStateId);
+        const hasAffix = entries.some((e) => e.placetype === "street_affix");
+        if (!hasAffix)
+            continue;
+        affixMatches.push({ startGroupIdx: start, endGroupIdx: bestEnd });
+        // Collect piece indices for the matched span.
+        const affixPieceIndices = [];
+        for (let g = start; g <= bestEnd; g++) {
+            const wg = wordGroups[g];
+            if (wg.fstToken === "")
+                continue;
+            for (const pi of wg.pieceIndices)
+                affixPieceIndices.push(pi);
+        }
+        // Apply affix bias: positive bias toward both prefix and suffix BIO labels on the matched
+        // tokens. The model's existing logits + the QueryShape prior + the adjacent context (via
+        // pass 2) determine which of {prefix, suffix} actually wins. We don't pre-commit to one.
+        const affixBias = biasScale * maxAffixBias;
+        for (let k = 0; k < affixPieceIndices.length; k++) {
+            const pi = affixPieceIndices[k];
+            const prefixCol = k === 0 ? bStreetPrefix : (iStreetPrefix ?? bStreetPrefix);
+            const suffixCol = k === 0 ? bStreetSuffix : (iStreetSuffix ?? bStreetSuffix);
+            matrix[pi][prefixCol] = Math.max(matrix[pi][prefixCol], affixBias);
+            matrix[pi][suffixCol] = Math.max(matrix[pi][suffixCol], affixBias);
+        }
+    }
+    if (affixMatches.length === 0)
+        return matrix;
+    // Pass 2 — for each affix match, identify the immediately-adjacent word groups (skipping
+    // empty/punctuation groups) on either side and bias them toward street, away from
+    // dependent_locality.
+    const neighbourStreetBias = biasScale * maxNeighbourStreetBias;
+    for (const match of affixMatches) {
+        const before = findNeighbour(wordGroups, match.startGroupIdx, -1);
+        const after = findNeighbour(wordGroups, match.endGroupIdx, +1);
+        for (const neighbour of [before, after]) {
+            if (!neighbour)
+                continue;
+            const indices = neighbour.pieceIndices;
+            for (let k = 0; k < indices.length; k++) {
+                const pi = indices[k];
+                const streetCol = k === 0 ? bStreet : (iStreet ?? bStreet);
+                matrix[pi][streetCol] = Math.max(matrix[pi][streetCol], neighbourStreetBias);
+                if (bDepLoc !== undefined) {
+                    const depLocCol = k === 0 ? bDepLoc : (iDepLoc ?? bDepLoc);
+                    matrix[pi][depLocCol] = Math.min(matrix[pi][depLocCol], -dependentLocalityPenalty);
+                }
+            }
+        }
+    }
+    return matrix;
+}
+/**
+ * Walk word groups outward from `fromGroupIdx` in `direction` (+1 or -1), skipping empty groups
+ * (whitespace / punctuation), and return the first non-empty group encountered — or `null` if no
+ * such neighbour exists.
+ */
+function findNeighbour(groups, fromGroupIdx, direction) {
+    for (let i = fromGroupIdx + direction; i >= 0 && i < groups.length; i += direction) {
+        const g = groups[i];
+        if (g.fstToken !== "")
+            return g;
+    }
+    return null;
+}
+//# sourceMappingURL=street-morphology-prior.js.map

package/out/street-morphology-prior.js.map

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

package/out/tokenizer.d.ts

@@ -51,7 +51,12 @@ export declare class MailwomanTokenizer {
     private constructor();
     /** Load from a base64-encoded `tokenizer.model`. Use for in-memory / test setups. */
     static loadFromBase64(b64: string): Promise<MailwomanTokenizer>;
-    /** Load from a path to a `tokenizer.model` file on disk. Node-only convenience. */
+    /**
+     * Load from a path to a `tokenizer.model` file on disk. **Node-only** — the dynamic `node:fs`
+     * import keeps this method out of the static dependency graph so the rest of the tokenizer
+     * bundles cleanly for the browser. Calling it in a browser throws at runtime; use
+     * `loadFromBase64` (or the URL-fetching loaders in `@mailwoman/neural-web`) instead.
+     */
     static loadFromFile(modelPath: string): Promise<MailwomanTokenizer>;
     /**
      * Tokenize `text` to pieces + ids + realigned char offsets.

package/out/tokenizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokenizer.d.ts","sourceRoot":"","sources":["../tokenizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH,4EAA4E;AAC5E,eAAO,MAAM,cAAc,WAAM,CAAA;AAEjC,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC9B,wFAAwF;IACxF,KAAK,EAAE,MAAM,CAAA;IACb,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAA;IACV,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAA;IACb,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAA;CACX;AAED,MAAM,WAAW,YAAY;IAC5B,MAAM,EAAE,cAAc,EAAE,CAAA;IACxB,GAAG,EAAE,MAAM,EAAE,CAAA;CACb;AAED,qBAAa,kBAAkB;IACV,OAAO,CAAC,QAAQ,CAAC,SAAS;IAA9C,OAAO;IAEP,qFAAqF;WACxE,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAMrE,mFAAmF;WACtE,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAKzE;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY;IA2BlC,oFAAoF;IACpF,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,UAAU,GAAG,MAAM;CAI1C"}
+{"version":3,"file":"tokenizer.d.ts","sourceRoot":"","sources":["../tokenizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH,4EAA4E;AAC5E,eAAO,MAAM,cAAc,WAAM,CAAA;AAEjC,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC9B,wFAAwF;IACxF,KAAK,EAAE,MAAM,CAAA;IACb,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAA;IACV,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAA;IACb,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAA;CACX;AAED,MAAM,WAAW,YAAY;IAC5B,MAAM,EAAE,cAAc,EAAE,CAAA;IACxB,GAAG,EAAE,MAAM,EAAE,CAAA;CACb;AAED,qBAAa,kBAAkB;IACV,OAAO,CAAC,QAAQ,CAAC,SAAS;IAA9C,OAAO;IAEP,qFAAqF;WACxE,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAMrE;;;;;OAKG;WACU,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAMzE;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY;IA2BlC,oFAAoF;IACpF,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,UAAU,GAAG,MAAM;CAI1C"}

package/out/tokenizer.js

@@ -30,7 +30,6 @@
  *   - `loadFromFile(path)` — convenience helper that does the read + b64 + load.
  */
 import { SentencePieceProcessor } from "@sctg/sentencepiece-js";
-import { promises as fs } from "node:fs";
 /** SentencePiece's word-boundary marker (U+2581 LOWER ONE EIGHTH BLOCK). */
 export const SPACE_SENTINEL = "▁";
 export class MailwomanTokenizer {
@@ -44,9 +43,15 @@ export class MailwomanTokenizer {
         await processor.loadFromB64StringModel(b64);
         return new MailwomanTokenizer(processor);
     }
-    /** Load from a path to a `tokenizer.model` file on disk. Node-only convenience. */
+    /**
+     * Load from a path to a `tokenizer.model` file on disk. **Node-only** — the dynamic `node:fs`
+     * import keeps this method out of the static dependency graph so the rest of the tokenizer
+     * bundles cleanly for the browser. Calling it in a browser throws at runtime; use
+     * `loadFromBase64` (or the URL-fetching loaders in `@mailwoman/neural-web`) instead.
+     */
     static async loadFromFile(modelPath) {
-        const buf = await fs.readFile(modelPath);
+        const { readFile } = await import(/* webpackIgnore: true */ "node:fs/promises");
+        const buf = await readFile(modelPath);
         return MailwomanTokenizer.loadFromBase64(buf.toString("base64"));
     }
     /**

package/out/tokenizer.js.map

@@ -1 +1 @@
-{"version":3,"file":"tokenizer.js","sourceRoot":"","sources":["../tokenizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAC/D,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAA;AAExC,4EAA4E;AAC5E,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAA;AAmBjC,MAAM,OAAO,kBAAkB;IACO;IAArC,YAAqC,SAAiC;QAAjC,cAAS,GAAT,SAAS,CAAwB;IAAG,CAAC;IAE1E,qFAAqF;IACrF,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,GAAW;QACtC,MAAM,SAAS,GAAG,IAAI,sBAAsB,EAAE,CAAA;QAC9C,MAAM,SAAS,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAA;QAC3C,OAAO,IAAI,kBAAkB,CAAC,SAAS,CAAC,CAAA;IACzC,CAAC;IAED,mFAAmF;IACnF,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,SAAiB;QAC1C,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAA;QACxC,OAAO,kBAAkB,CAAC,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAA;IACjE,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,IAAY;QAClB,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,CAAC,CAAA;QAChD,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;QAE1C,MAAM,SAAS,GAAqB,EAAE,CAAA;QACtC,IAAI,MAAM,GAAG,CAAC,CAAA;QAEd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAE,CAAA;YACxB,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;YACvB,MAAM,WAAW,GAAG,KAAK,CAAC,UAAU,CAAC,cAAc,CAAC,CAAA;YACpD,MAAM,OAAO,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;YAExE,IAAI,WAAW,EAAE,CAAC;gBACjB,OAAO,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAE,CAAC;oBAAE,MAAM,EAAE,CAAA;YAClE,CAAC;YAED,MAAM,KAAK,GAAG,MAAM,CAAA;YACpB,MAAM,IAAI,OAAO,CAAC,MAAM,CAAA;YACxB,MAAM,GAAG,GAAG,MAAM,CAAA;YAElB,SAAS,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAA;QAC1C,CAAC;QAED,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,CAAA;IAClC,CAAC;IAED,oFAAoF;IACpF,MAAM,CAAC,GAA0B;QAChC,MAAM,GAAG,GAAG,GAAG,YAAY,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QAClE,OAAO,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,GAAG,CAAW,CAAA;IAC/C,CAAC;CACD"}
+{"version":3,"file":"tokenizer.js","sourceRoot":"","sources":["../tokenizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAE/D,4EAA4E;AAC5E,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAA;AAmBjC,MAAM,OAAO,kBAAkB;IACO;IAArC,YAAqC,SAAiC;QAAjC,cAAS,GAAT,SAAS,CAAwB;IAAG,CAAC;IAE1E,qFAAqF;IACrF,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,GAAW;QACtC,MAAM,SAAS,GAAG,IAAI,sBAAsB,EAAE,CAAA;QAC9C,MAAM,SAAS,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAA;QAC3C,OAAO,IAAI,kBAAkB,CAAC,SAAS,CAAC,CAAA;IACzC,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,SAAiB;QAC1C,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,kBAAkB,CAAC,CAAA;QAC/E,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAC,CAAA;QACrC,OAAO,kBAAkB,CAAC,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAA;IACjE,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,IAAY;QAClB,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,CAAC,CAAA;QAChD,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;QAE1C,MAAM,SAAS,GAAqB,EAAE,CAAA;QACtC,IAAI,MAAM,GAAG,CAAC,CAAA;QAEd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAE,CAAA;YACxB,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;YACvB,MAAM,WAAW,GAAG,KAAK,CAAC,UAAU,CAAC,cAAc,CAAC,CAAA;YACpD,MAAM,OAAO,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;YAExE,IAAI,WAAW,EAAE,CAAC;gBACjB,OAAO,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAE,CAAC;oBAAE,MAAM,EAAE,CAAA;YAClE,CAAC;YAED,MAAM,KAAK,GAAG,MAAM,CAAA;YACpB,MAAM,IAAI,OAAO,CAAC,MAAM,CAAA;YACxB,MAAM,GAAG,GAAG,MAAM,CAAA;YAElB,SAAS,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAA;QAC1C,CAAC;QAED,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,CAAA;IAClC,CAAC;IAED,oFAAoF;IACpF,MAAM,CAAC,GAA0B;QAChC,MAAM,GAAG,GAAG,GAAG,YAAY,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QAClE,OAAO,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,GAAG,CAAW,CAAA;IAC/C,CAAC;CACD"}

package/out/unit-repair.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Secondary-unit regex repair pass — parser-improvement backlog (2026-05-30).
+ *
+ *   The three-arena capability eval surfaced a persistent neural weakness: the
+ *   model DROPS secondary units. "123 Main St Apt 456" → no unit label; the
+ *   postal-standards secondary-unit edge class scored 0% neural. Units have a
+ *   rigid surface shape (a designator keyword + an identifier), so — exactly
+ *   like the postcode-repair pass (#35) — we can detect them deterministically
+ *   and repair the BIO labels AFTER decode but BEFORE `buildAddressTree`. The
+ *   model is untouched; this is a decoder-side correction, the same "lowest
+ *   risk" lever family as postcode-repair.
+ *
+ *   PRECISION GUARDS (mirror postcode-repair — never regress a confident parse):
+ *     - We only fire on EXPLICIT designators (Apt, Ste, Suite, Unit, Rm, Floor,
+ *       Bldg, Flat, … + bare "#<n>"). Ambiguous tokens are deliberately excluded:
+ *       "Box" (that's po_box), bare "F"/"No" (too greedy), "Space"/"Stop" (common
+ *       words).
+ *     - ADD path (model emitted no unit over the matched run): allowed ONLY over
+ *       `O` tokens — never over house_number / street* / postcode / po_box / a
+ *       geographic container. So a confidently-labeled street or number is safe.
+ *     - SNAP path: when the model already started a unit span inside the match,
+ *       we expand/clip it to the full detected shape.
+ *     - Local smear-clip: unit tokens immediately flanking a snapped run are
+ *       cleared (mirrors postcode-repair) so "Apt 4 Springfield" can't leave a
+ *       stray I-unit on "Springfield".
+ *
+ *   Opt-in via `ParseOpts.unitRepair` (postcode-repair earned default-on only
+ *   after a measured +135/0; unit-repair stays opt-in until the v0.7.2 arena
+ *   re-run quantifies its delta).
+ */
+import type { DecoderToken } from "@mailwoman/core/decoder";
+export interface RepairResult {
+    tokens: DecoderToken[];
+    /** Number of token labels changed — for telemetry / logging. */
+    changed: number;
+}
+/**
+ * Repair secondary-unit label spans in a decoded token sequence using designator
+ * regexes. Returns a NEW token array (inputs are not mutated) plus a change count.
+ */
+export declare function repairUnitLabels(text: string, input: readonly DecoderToken[]): RepairResult;
+//# sourceMappingURL=unit-repair.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"unit-repair.d.ts","sourceRoot":"","sources":["../unit-repair.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AA+E3D,MAAM,WAAW,YAAY;IAC5B,MAAM,EAAE,YAAY,EAAE,CAAA;IACtB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,YAAY,CA8C3F"}