@mailwoman/neural 2.1.0 → 4.0.0

package/out/anchor-inference.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Inference-side postcode-anchor features (#239/#240) — the mirror of the Python training pipeline
+ *   (`mailwoman_train/tokenizer.py::anchor_feature_vector` + `realign_anchor_to_pieces`). At inference
+ *   the model conditions on per-piece anchor features fed alongside `input_ids`; this builds them from
+ *   a raw address + its SentencePiece pieces, using the SAME postcode→anchor lookup the model trained
+ *   against (`scripts/build-pilot-anchor-lookup.py`), so the feature layout matches byte-for-byte.
+ *
+ *   The layout is LOAD-BEARING and cross-language: a wrong locale order or centroid scale feeds the
+ *   model garbage. `anchor-inference.test.ts` pins both `LOCALE_ORDER` and the vector to values emitted
+ *   by the Python `anchor_feature_vector` — any drift fails the test.
+ */
+import type { TokenizedPiece } from "./tokenizer.js";
+/**
+ * The locale class order — MUST match Python `mailwoman_train/labels.py::LOCALE_COUNTRIES`. The
+ * posterior occupies indices `[0, LOCALE_ORDER.length)`; the normalized centroid the last two.
+ * (Pinned by the test; do not reorder.)
+ */
+export declare const LOCALE_ORDER: readonly ["US", "FR", "DE", "CA", "GB", "JP", "ES", "IT", "NL"];
+/** Anchor feature width = posterior over the locale set + a 2-d centroid. */
+export declare const ANCHOR_FEATURE_DIM: number;
+/** One postcode's anchor record (from the pilot lookup): country posterior + a single centroid. */
+export interface AnchorEntry {
+    posterior: Record<string, number>;
+    lat: number;
+    lon: number;
+}
+export type AnchorLookup = Map<string, AnchorEntry>;
+/**
+ * Build the fixed-width anchor feature vector — the exact mirror of Python `anchor_feature_vector`:
+ * a uniform country posterior over {@linkcode LOCALE_ORDER} (renormalized over the in-set mass) + a
+ * normalized centroid (`lat/90`, `lon/180` ∈ [-1, 1]).
+ */
+export declare function anchorFeatureVector(posterior: Record<string, number>, lat: number, lon: number): number[];
+/**
+ * Parse the pilot postcode→anchor lookup JSON (`{postcode: [posterior, lat, lon]}`) into a Map. Pure
+ * (takes the parsed object, not a path) so this module stays browser-safe — the file read lives in
+ * the Node-side caller (the eval).
+ */
+export declare function parseAnchorLookup(raw: Record<string, [Record<string, number>, number, number]>): AnchorLookup;
+/**
+ * Per-piece anchor features + confidence for `text`, projected onto its SP `pieces` by the SAME
+ * char→piece rule the labels use (a piece takes the anchor of the postcode span its first
+ * non-whitespace char falls inside) — so the anchor lands on exactly the postcode's sub-tokens.
+ *
+ * Postcode spans are the alphanumeric runs in `text` that the lookup recognizes (gold-equivalent on
+ * clean rendered addresses); a recognized span yields a confidence-1.0 anchor, like training's
+ * gold-span. Returns `(pieces × ANCHOR_FEATURE_DIM)` features + `(pieces,)` confidence.
+ */
+export declare function buildAnchorFeatures(text: string, pieces: ReadonlyArray<TokenizedPiece>, lookup: AnchorLookup): {
+    features: number[][];
+    confidence: number[];
+};
+//# sourceMappingURL=anchor-inference.d.ts.map

package/out/anchor-inference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor-inference.d.ts","sourceRoot":"","sources":["../anchor-inference.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAEpD;;;;GAIG;AACH,eAAO,MAAM,YAAY,iEAAkE,CAAA;AAE3F,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB,QAA0B,CAAA;AAEzD,mGAAmG;AACnG,MAAM,WAAW,WAAW;IAC3B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;CACX;AAED,MAAM,MAAM,YAAY,GAAG,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;AAEnD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAgBzG;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,YAAY,CAI7G;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAClC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,EACrC,MAAM,EAAE,YAAY,GAClB;IAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CA0BhD"}

package/out/anchor-inference.js

@@ -0,0 +1,94 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Inference-side postcode-anchor features (#239/#240) — the mirror of the Python training pipeline
+ *   (`mailwoman_train/tokenizer.py::anchor_feature_vector` + `realign_anchor_to_pieces`). At inference
+ *   the model conditions on per-piece anchor features fed alongside `input_ids`; this builds them from
+ *   a raw address + its SentencePiece pieces, using the SAME postcode→anchor lookup the model trained
+ *   against (`scripts/build-pilot-anchor-lookup.py`), so the feature layout matches byte-for-byte.
+ *
+ *   The layout is LOAD-BEARING and cross-language: a wrong locale order or centroid scale feeds the
+ *   model garbage. `anchor-inference.test.ts` pins both `LOCALE_ORDER` and the vector to values emitted
+ *   by the Python `anchor_feature_vector` — any drift fails the test.
+ */
+/**
+ * The locale class order — MUST match Python `mailwoman_train/labels.py::LOCALE_COUNTRIES`. The
+ * posterior occupies indices `[0, LOCALE_ORDER.length)`; the normalized centroid the last two.
+ * (Pinned by the test; do not reorder.)
+ */
+export const LOCALE_ORDER = ["US", "FR", "DE", "CA", "GB", "JP", "ES", "IT", "NL"];
+/** Anchor feature width = posterior over the locale set + a 2-d centroid. */
+export const ANCHOR_FEATURE_DIM = LOCALE_ORDER.length + 2;
+/**
+ * Build the fixed-width anchor feature vector — the exact mirror of Python `anchor_feature_vector`:
+ * a uniform country posterior over {@linkcode LOCALE_ORDER} (renormalized over the in-set mass) + a
+ * normalized centroid (`lat/90`, `lon/180` ∈ [-1, 1]).
+ */
+export function anchorFeatureVector(posterior, lat, lon) {
+    const vec = new Array(ANCHOR_FEATURE_DIM).fill(0);
+    let total = 0;
+    for (const [country, weight] of Object.entries(posterior)) {
+        const idx = LOCALE_ORDER.indexOf(country.toUpperCase());
+        if (idx >= 0) {
+            vec[idx] = weight;
+            total += weight;
+        }
+    }
+    if (total > 0) {
+        for (let i = 0; i < LOCALE_ORDER.length; i++)
+            vec[i] /= total;
+    }
+    vec[LOCALE_ORDER.length] = Math.max(-1, Math.min(1, lat / 90));
+    vec[LOCALE_ORDER.length + 1] = Math.max(-1, Math.min(1, lon / 180));
+    return vec;
+}
+/**
+ * Parse the pilot postcode→anchor lookup JSON (`{postcode: [posterior, lat, lon]}`) into a Map. Pure
+ * (takes the parsed object, not a path) so this module stays browser-safe — the file read lives in
+ * the Node-side caller (the eval).
+ */
+export function parseAnchorLookup(raw) {
+    const out = new Map();
+    for (const [pc, [posterior, lat, lon]] of Object.entries(raw))
+        out.set(pc, { posterior, lat, lon });
+    return out;
+}
+/**
+ * Per-piece anchor features + confidence for `text`, projected onto its SP `pieces` by the SAME
+ * char→piece rule the labels use (a piece takes the anchor of the postcode span its first
+ * non-whitespace char falls inside) — so the anchor lands on exactly the postcode's sub-tokens.
+ *
+ * Postcode spans are the alphanumeric runs in `text` that the lookup recognizes (gold-equivalent on
+ * clean rendered addresses); a recognized span yields a confidence-1.0 anchor, like training's
+ * gold-span. Returns `(pieces × ANCHOR_FEATURE_DIM)` features + `(pieces,)` confidence.
+ */
+export function buildAnchorFeatures(text, pieces, lookup) {
+    const features = pieces.map(() => new Array(ANCHOR_FEATURE_DIM).fill(0));
+    const confidence = pieces.map(() => 0);
+    const tokenRe = /[A-Za-z0-9]+/g;
+    let m;
+    while ((m = tokenRe.exec(text)) !== null) {
+        const entry = lookup.get(m[0].toUpperCase());
+        if (!entry)
+            continue;
+        const spanBegin = m.index;
+        const spanEnd = m.index + m[0].length;
+        const vec = anchorFeatureVector(entry.posterior, entry.lat, entry.lon);
+        for (let i = 0; i < pieces.length; i++) {
+            const p = pieces[i];
+            for (let c = p.start; c < p.end; c++) {
+                if (c < text.length && !/\s/.test(text[c])) {
+                    if (c >= spanBegin && c < spanEnd) {
+                        features[i] = vec;
+                        confidence[i] = 1.0;
+                    }
+                    break; // first non-whitespace char of the piece decides (mirrors realign_anchor_to_pieces)
+                }
+            }
+        }
+    }
+    return { features, confidence };
+}
+//# sourceMappingURL=anchor-inference.js.map

package/out/anchor-inference.js.map

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

package/out/browser.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Browser-safe re-export surface. Excludes `./onnx-runner.js` + `./weights.js` (Node-only — they
+ *   statically reference `onnxruntime-node` + `node:fs`), the dynamic `loadFromWeights` /
+ *   `loadFromFile` paths from those modules guard the corresponding imports with `webpackIgnore` so
+ *   Node callers still get them via the main `@mailwoman/neural` entry without bundling them into a
+ *   browser graph.
+ */
+export * from "./classifier.js";
+export * from "./labels.js";
+export * from "./tokenizer.js";
+export * from "./anchor-inference.js";
+export * from "./postcode-binary-resolver.js";
+export type { InferResult } from "./onnx-runner.js";
+//# sourceMappingURL=browser.d.ts.map

package/out/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAG9B,cAAc,uBAAuB,CAAA;AACrC,cAAc,+BAA+B,CAAA;AAG7C,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA"}

package/out/browser.js

@@ -0,0 +1,19 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Browser-safe re-export surface. Excludes `./onnx-runner.js` + `./weights.js` (Node-only — they
+ *   statically reference `onnxruntime-node` + `node:fs`), the dynamic `loadFromWeights` /
+ *   `loadFromFile` paths from those modules guard the corresponding imports with `webpackIgnore` so
+ *   Node callers still get them via the main `@mailwoman/neural` entry without bundling them into a
+ *   browser graph.
+ */
+export * from "./classifier.js";
+export * from "./labels.js";
+export * from "./tokenizer.js";
+// Browser-safe anchor channel (#239/#240): the pure-JS feature builder + the postcode binary resolver
+// (zero-dep) the demo wires together to feed the anchor at inference.
+export * from "./anchor-inference.js";
+export * from "./postcode-binary-resolver.js";
+//# sourceMappingURL=browser.js.map

package/out/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,sGAAsG;AACtG,sEAAsE;AACtE,cAAc,uBAAuB,CAAA;AACrC,cAAc,+BAA+B,CAAA"}

package/out/classifier.d.ts

@@ -9,19 +9,68 @@
  *
  *   Convenience wrappers `parseJson` / `parseTuples` / `parseXml` project the tree on the way out.
  */
-import { type AddressTree, type ComponentTag, decodeAsXml } from "@mailwoman/core/decoder";
-import { OnnxRunner } from "./onnx-runner.js";
+import { decodeAsXml, type AddressTree, type ComponentTag } from "@mailwoman/core/decoder";
+import { type FstMatcherLike } from "./fst-prior.js";
+import type { InferResult } from "./onnx-runner.js";
+import { type QueryShapeLike } from "./query-shape-prior.js";
+import { type StreetMorphologyPriorOpts } from "./street-morphology-prior.js";
 import { MailwomanTokenizer } from "./tokenizer.js";
-import { type ResolveWeightsOpts } from "./weights.js";
+import { type AnchorLookup } from "./anchor-inference.js";
+import type { ResolveWeightsOpts } from "./weights.js";
+/**
+ * Structural type the classifier needs from a runner. Lets callers swap the Node-side `OnnxRunner`
+ * for a browser-side runner (e.g. `@mailwoman/neural-web`'s `WebOnnxRunner`) without inheritance —
+ * the classifier only ever calls `infer(ids)`.
+ */
+export interface NeuralRunner {
+    infer(tokenIds: number[], anchor?: {
+        features: ReadonlyArray<ReadonlyArray<number>>;
+        confidence: ReadonlyArray<number>;
+    }): Promise<InferResult>;
+}
 export interface NeuralAddressClassifierConfig {
     tokenizer: MailwomanTokenizer;
-    runner: OnnxRunner;
-    /** Label vocabulary in the order the model emits them. Defaults to Stage 1 (v0.1.0/v0.2.0). */
+    runner: NeuralRunner;
+    /**
+     * Label vocabulary in the order the model emits them. Defaults to Stage 2 (v0.3.0). Stage 2
+     * strictly extends Stage 1 at the same indices, so a v0.2.0 Stage 1 model loaded with this
+     * default still decodes correctly — its emissions only span the first 15 entries.
+     */
     labels?: readonly string[];
+    /**
+     * Decoding strategy:
+     *
+     * - `"viterbi"` (default) — linear-chain CRF Viterbi with the BIO structural mask. Prevents
+     *   orphan-`I-*` sequences. If `transitions` is provided, uses learned scores on top.
+     * - `"argmax"` — per-token argmax. Faster but produces structurally invalid sequences. Use only for
+     *   debugging / comparison.
+     */
+    decode?: "viterbi" | "argmax";
+    /**
+     * Optional learned CRF transition scores. Square matrix of size `labels.length × labels.length`.
+     * Added on top of the structural BIO mask. Future weights releases ship this; today's v3.0.0
+     * weights don't, so the structural mask alone is used.
+     */
+    transitions?: number[][];
+    /** Optional learned start-of-sequence transition scores per label. */
+    startTransitions?: number[];
+    /** Optional learned end-of-sequence transition scores per label. */
+    endTransitions?: number[];
+    /**
+     * Optional postcode-anchor lookup (#239/#240). When set, `parse` builds per-piece anchor features
+     * from the text + this lookup and feeds them to the runner — for models trained with the anchor
+     * channel (exported with the `anchor_features`/`anchor_confidence` ONNX inputs). Omit for plain
+     * models. Load via `loadAnchorLookup` from `./anchor-inference.js`.
+     */
+    postcodeAnchorLookup?: AnchorLookup;
 }
 export declare class NeuralAddressClassifier {
     private readonly cfg;
     private readonly labels;
+    private readonly decodeMode;
+    private readonly transitions;
+    private readonly startTransitions;
+    private readonly endTransitions;
     constructor(cfg: NeuralAddressClassifierConfig);
     /**
      * One-call factory that resolves the weights package (or explicit paths), loads the tokenizer and
@@ -29,12 +78,97 @@ export declare class NeuralAddressClassifier {
      *
      * Resolution order: explicit paths in `opts` → `@mailwoman/neural-weights-<locale>` package →
      * throws a single actionable error.
+     *
+     * **Node-only.** The dynamic imports keep `OnnxRunner` (onnxruntime-node) + `resolveWeights`
+     * (uses Node fs) out of the static dependency graph, so this file can be bundled for the browser
+     * by `@mailwoman/neural-web`. Calling this method in a browser will throw at runtime — use
+     * `loadNeuralClassifierFromUrls` from `@mailwoman/neural-web` instead.
+     */
+    static loadFromWeights(opts?: ResolveWeightsOpts & {
+        postcodeAnchorLookup?: AnchorLookup;
+    }): Promise<NeuralAddressClassifier>;
+    /** Tokenize → infer → Viterbi (or argmax) → decoder tree. */
+    parse(text: string, opts?: ParseOpts): Promise<AddressTree>;
+    /**
+     * Like `parse`, but also returns the raw per-token logits and piece offsets needed for per-span
+     * logit aggregation (Option C joint-reconcile integration).
+     */
+    parseWithLogits(text: string, opts?: ParseOpts): Promise<ParseWithLogitsResult>;
+    parseJson(text: string, opts?: ParseOpts): Promise<Partial<Record<ComponentTag, string>>>;
+    parseTuples(text: string, opts?: ParseOpts): Promise<Array<[ComponentTag, string]>>;
+    parseXml(text: string, opts?: ParseOpts & {
+        xml?: Parameters<typeof decodeAsXml>[1];
+    }): Promise<string>;
+    /**
+     * Guard against a silent label/emission shape overrun. When the model emits MORE logits per token
+     * than the configured label vocabulary (e.g. a Stage 3 bundle loaded with the default Stage 2
+     * labels), viterbi indexes past the transition matrix and dies with an opaque `Cannot read
+     * properties of undefined (reading '0')`. Fail fast here with a message that names the contract
+     * the caller violated.
+     *
+     * The opposite shape (model narrower than labels) is intentionally permitted — STAGE2_BIO_LABELS
+     * prefix-extends STAGE1_BIO_LABELS so a Stage 1 model loaded with Stage 2 labels decodes
+     * correctly via the first 15 logits. See labels.ts for the contract.
+     */
+    private assertEmissionWidth;
+}
+/** Result of `parseWithLogits` — tree + raw material for per-span logit aggregation. */
+export interface ParseWithLogitsResult {
+    tree: AddressTree;
+    logits: number[][];
+    pieces: Array<{
+        start: number;
+        end: number;
+    }>;
+}
+/**
+ * Per-call opts for `parse()`. Threading a precomputed `QueryShape` here turns on the soft-prior
+ * bias path in the Viterbi decoder (Stage 2.4 boundary → Stage 3 encoder integration).
+ */
+export interface ParseOpts {
+    /**
+     * Precomputed `QueryShape` for this input (from `@mailwoman/query-shape`'s `computeQueryShape`).
+     * Known-format hits in the shape produce additive emission biases toward the matching BIO label.
+     * Typed structurally — no runtime dependency on `@mailwoman/query-shape`.
+     */
+    queryShape?: QueryShapeLike;
+    /**
+     * 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.
+     */
+    queryShapeBiasScale?: number;
+    /**
+     * Pre-built FST gazetteer matcher. When provided, gazetteer matches produce additive emission
+     * biases.
+     */
+    fst?: FstMatcherLike;
+    /** Bias magnitude for FST gazetteer matches. Default 1.0. */
+    fstBiasScale?: number;
+    /**
+     * Pre-built street-morphology FST matcher. When provided, street-type affixes (Avenue, rue,
+     * Calle, Straße, …) produce additive emission biases toward `street_prefix`/`street_suffix` on
+     * the matched tokens AND toward `street` / away from `dependent_locality` on the adjacent name
+     * tokens. Closes the v0.6.1 dependent_locality vacuum; see
+     * `docs/articles/concepts/street-supplement-architecture.md` for the layered design.
+     */
+    fstStreetMorphology?: FstMatcherLike;
+    /** Override bias magnitudes for the morphology prior. */
+    fstStreetMorphologyOpts?: StreetMorphologyPriorOpts;
+    /**
+     * When true, run the deterministic postcode regex repair pass (v0.7 #35) on the decoded label
+     * sequence before tree-building. Detects postcode-shaped substrings (GB/CA/NL/US/FR/… patterns)
+     * and snaps/adds the postcode span to the matched shape, fixing the SentencePiece-fragmentation
+     * failures catalogued in the 2026-05-29 postcode diagnostic. Off by default — opt-in until the
+     * v0.7 gate confirms it. See `./postcode-repair.ts`.
+     */
+    postcodeRepair?: boolean;
+    /**
+     * When true, run the deterministic secondary-unit regex repair pass on the decoded label
+     * sequence before tree-building. Detects designator-shaped substrings ("Apt 4B", "Ste 12",
+     * "Unit 9400", bare "#104", …) and snaps/adds the unit span, fixing the unit-drop weakness the
+     * three-arena capability eval surfaced (postal secondary-unit 0% neural). Off by default —
+     * opt-in until the v0.7.2 arena re-run quantifies its delta. See `./unit-repair.ts`.
      */
-    static loadFromWeights(opts?: ResolveWeightsOpts): Promise<NeuralAddressClassifier>;
-    /** Tokenize → infer → argmax/softmax → decoder tree. */
-    parse(text: string): Promise<AddressTree>;
-    parseJson(text: string): Promise<Partial<Record<ComponentTag, string>>>;
-    parseTuples(text: string): Promise<Array<[ComponentTag, string]>>;
-    parseXml(text: string, opts?: Parameters<typeof decodeAsXml>[1]): Promise<string>;
+    unitRepair?: boolean;
 }
 //# sourceMappingURL=classifier.d.ts.map

package/out/classifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"classifier.d.ts","sourceRoot":"","sources":["../classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,YAAY,EAKjB,WAAW,EACX,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACnD,OAAO,EAAE,KAAK,kBAAkB,EAAkB,MAAM,cAAc,CAAA;AAEtE,MAAM,WAAW,6BAA6B;IAC7C,SAAS,EAAE,kBAAkB,CAAA;IAC7B,MAAM,EAAE,UAAU,CAAA;IAClB,+FAA+F;IAC/F,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1B;AAED,qBAAa,uBAAuB;IAGvB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAFhC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;gBAEb,GAAG,EAAE,6BAA6B;IAI/D;;;;;;OAMG;WACU,eAAe,CAAC,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAS7F,wDAAwD;IAClD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAqBzC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;IAIvE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;IAIjE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;CAGvF"}
+{"version":3,"file":"classifier.d.ts","sourceRoot":"","sources":["../classifier.ts"],"names":[],"mappings":"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"}

package/out/classifier.js

@@ -10,16 +10,35 @@
  *   Convenience wrappers `parseJson` / `parseTuples` / `parseXml` project the tree on the way out.
  */
 import { buildAddressTree, decodeAsJson, decodeAsTuples, decodeAsXml, } from "@mailwoman/core/decoder";
-import { STAGE1_BIO_LABELS } from "./labels.js";
-import { OnnxRunner } from "./onnx-runner.js";
+import { buildFstEmissionPriors } from "./fst-prior.js";
+import { STAGE2_BIO_LABELS } from "./labels.js";
+import { repairPostcodeLabels } from "./postcode-repair.js";
+import { repairUnitLabels } from "./unit-repair.js";
+import { addEmissionMatrix, buildEmissionPriors } from "./query-shape-prior.js";
+import { buildStreetMorphologyEmissionPriors } from "./street-morphology-prior.js";
 import { MailwomanTokenizer } from "./tokenizer.js";
-import { resolveWeights } from "./weights.js";
+import { buildAnchorFeatures } from "./anchor-inference.js";
+import { buildBioEndMask, buildBioStartMask, buildBioTransitionMask, softmax, viterbi } from "./viterbi.js";
 export class NeuralAddressClassifier {
     cfg;
     labels;
+    decodeMode;
+    transitions;
+    startTransitions;
+    endTransitions;
     constructor(cfg) {
         this.cfg = cfg;
-        this.labels = cfg.labels ?? STAGE1_BIO_LABELS;
+        this.labels = cfg.labels ?? STAGE2_BIO_LABELS;
+        this.decodeMode = cfg.decode ?? "viterbi";
+        const structural = buildBioTransitionMask(this.labels);
+        if (cfg.transitions) {
+            this.transitions = addMatrices(structural, cfg.transitions);
+        }
+        else {
+            this.transitions = structural;
+        }
+        this.startTransitions = cfg.startTransitions ?? buildBioStartMask(this.labels);
+        this.endTransitions = cfg.endTransitions ?? buildBioEndMask(this.labels);
     }
     /**
      * One-call factory that resolves the weights package (or explicit paths), loads the tokenizer and
@@ -27,42 +46,176 @@ export class NeuralAddressClassifier {
      *
      * Resolution order: explicit paths in `opts` → `@mailwoman/neural-weights-<locale>` package →
      * throws a single actionable error.
+     *
+     * **Node-only.** The dynamic imports keep `OnnxRunner` (onnxruntime-node) + `resolveWeights`
+     * (uses Node fs) out of the static dependency graph, so this file can be bundled for the browser
+     * by `@mailwoman/neural-web`. Calling this method in a browser will throw at runtime — use
+     * `loadNeuralClassifierFromUrls` from `@mailwoman/neural-web` instead.
      */
     static async loadFromWeights(opts = {}) {
-        const { modelPath, tokenizerPath } = resolveWeights(opts);
+        // /* webpackIgnore: true */ tells webpack to leave the dynamic import statement intact —
+        // it becomes a runtime native ESM import that resolves in Node (which has onnxruntime-node
+        // + node:fs) and throws cleanly in a browser if called. Without the directive, webpack
+        // pulls onnx-runner / weights into the browser chunk graph + then chokes on the Node-only
+        // builtins they reference.
+        const [{ OnnxRunner }, { resolveWeights, readLabelsFromModelCard, readCrfTransitions }] = await Promise.all([
+            import(/* webpackIgnore: true */ "./onnx-runner.js"),
+            import(/* webpackIgnore: true */ "./weights.js"),
+        ]);
+        const resolved = resolveWeights(opts);
+        const labels = readLabelsFromModelCard(resolved.modelCardPath);
+        const crf = readCrfTransitions(resolved.crfTransitionsPath);
         const [tokenizer, runner] = await Promise.all([
-            MailwomanTokenizer.loadFromFile(tokenizerPath),
-            OnnxRunner.create(modelPath),
+            MailwomanTokenizer.loadFromFile(resolved.tokenizerPath),
+            OnnxRunner.create(resolved.modelPath),
         ]);
-        return new NeuralAddressClassifier({ tokenizer, runner });
+        return new NeuralAddressClassifier({
+            tokenizer,
+            runner,
+            labels,
+            transitions: crf?.transitions,
+            startTransitions: crf?.startTransitions,
+            endTransitions: crf?.endTransitions,
+            ...(opts.postcodeAnchorLookup ? { postcodeAnchorLookup: opts.postcodeAnchorLookup } : {}),
+        });
     }
-    /** Tokenize → infer → argmax/softmax → decoder tree. */
-    async parse(text) {
+    /** Tokenize → infer → Viterbi (or argmax) → decoder tree. */
+    async parse(text, opts) {
         if (text.length === 0)
             return { raw: text, roots: [] };
         const { pieces, ids } = this.cfg.tokenizer.encode(text);
-        const { logits } = await this.cfg.runner.infer(ids);
-        const tokens = pieces.map((p, i) => {
-            const row = logits[i];
-            const { idx, conf } = argmaxSoftmax(row);
+        // Postcode-anchor channel (#239/#240): build per-piece anchor features from the same lookup the
+        // model trained on, fed alongside the ids. No-op when no lookup is configured.
+        const anchor = this.cfg.postcodeAnchorLookup
+            ? buildAnchorFeatures(text, pieces, this.cfg.postcodeAnchorLookup)
+            : undefined;
+        const { logits } = await this.cfg.runner.infer(ids, anchor);
+        this.assertEmissionWidth(logits);
+        let emissions = opts?.queryShape
+            ? addEmissionMatrix(logits, buildEmissionPriors(opts.queryShape, pieces, this.labels, {
+                biasScale: opts.queryShapeBiasScale ?? 1.0,
+                inputText: text,
+            }))
+            : logits;
+        if (opts?.fst) {
+            emissions = addEmissionMatrix(emissions, buildFstEmissionPriors(opts.fst, pieces, this.labels, {
+                biasScale: opts.fstBiasScale ?? 1.0,
+            }));
+        }
+        if (opts?.fstStreetMorphology) {
+            emissions = addEmissionMatrix(emissions, buildStreetMorphologyEmissionPriors(opts.fstStreetMorphology, pieces, this.labels, opts.fstStreetMorphologyOpts ?? {}));
+        }
+        const labelIndices = this.decodeMode === "viterbi"
+            ? viterbi({
+                emissions,
+                transitions: this.transitions,
+                startTransitions: this.startTransitions,
+                endTransitions: this.endTransitions,
+            }).path
+            : emissions.map((row) => argmaxSoftmax(row).idx);
+        let tokens = pieces.map((p, i) => {
+            const idx = labelIndices[i];
+            const probs = softmax(logits[i]);
             return {
                 piece: p.piece,
                 start: p.start,
                 end: p.end,
                 label: (this.labels[idx] ?? "O"),
-                confidence: conf,
+                confidence: probs[idx],
             };
         });
+        if (opts?.postcodeRepair) {
+            tokens = repairPostcodeLabels(text, tokens).tokens;
+        }
+        if (opts?.unitRepair) {
+            tokens = repairUnitLabels(text, tokens).tokens;
+        }
         return buildAddressTree(text, tokens);
     }
-    async parseJson(text) {
-        return decodeAsJson(await this.parse(text));
+    /**
+     * Like `parse`, but also returns the raw per-token logits and piece offsets needed for per-span
+     * logit aggregation (Option C joint-reconcile integration).
+     */
+    async parseWithLogits(text, opts) {
+        if (text.length === 0) {
+            return { tree: { raw: text, roots: [] }, logits: [], pieces: [] };
+        }
+        const { pieces, ids } = this.cfg.tokenizer.encode(text);
+        // Postcode-anchor channel (#239/#240): build per-piece anchor features from the same lookup the
+        // model trained on, fed alongside the ids. No-op when no lookup is configured.
+        const anchor = this.cfg.postcodeAnchorLookup
+            ? buildAnchorFeatures(text, pieces, this.cfg.postcodeAnchorLookup)
+            : undefined;
+        const { logits } = await this.cfg.runner.infer(ids, anchor);
+        this.assertEmissionWidth(logits);
+        let emissions = opts?.queryShape
+            ? addEmissionMatrix(logits, buildEmissionPriors(opts.queryShape, pieces, this.labels, {
+                biasScale: opts.queryShapeBiasScale ?? 1.0,
+                inputText: text,
+            }))
+            : logits;
+        if (opts?.fst) {
+            emissions = addEmissionMatrix(emissions, buildFstEmissionPriors(opts.fst, pieces, this.labels, {
+                biasScale: opts.fstBiasScale ?? 1.0,
+            }));
+        }
+        if (opts?.fstStreetMorphology) {
+            emissions = addEmissionMatrix(emissions, buildStreetMorphologyEmissionPriors(opts.fstStreetMorphology, pieces, this.labels, opts.fstStreetMorphologyOpts ?? {}));
+        }
+        const labelIndices = this.decodeMode === "viterbi"
+            ? viterbi({
+                emissions,
+                transitions: this.transitions,
+                startTransitions: this.startTransitions,
+                endTransitions: this.endTransitions,
+            }).path
+            : emissions.map((row) => argmaxSoftmax(row).idx);
+        const tokens = pieces.map((p, i) => {
+            const idx = labelIndices[i];
+            const probs = softmax(logits[i]);
+            return {
+                piece: p.piece,
+                start: p.start,
+                end: p.end,
+                label: (this.labels[idx] ?? "O"),
+                confidence: probs[idx],
+            };
+        });
+        return {
+            tree: buildAddressTree(text, tokens),
+            logits,
+            pieces: pieces.map((p) => ({ start: p.start, end: p.end })),
+        };
+    }
+    async parseJson(text, opts) {
+        return decodeAsJson(await this.parse(text, opts));
     }
-    async parseTuples(text) {
-        return decodeAsTuples(await this.parse(text));
+    async parseTuples(text, opts) {
+        return decodeAsTuples(await this.parse(text, opts));
     }
     async parseXml(text, opts) {
-        return decodeAsXml(await this.parse(text), opts);
+        return decodeAsXml(await this.parse(text, opts), opts?.xml);
+    }
+    /**
+     * Guard against a silent label/emission shape overrun. When the model emits MORE logits per token
+     * than the configured label vocabulary (e.g. a Stage 3 bundle loaded with the default Stage 2
+     * labels), viterbi indexes past the transition matrix and dies with an opaque `Cannot read
+     * properties of undefined (reading '0')`. Fail fast here with a message that names the contract
+     * the caller violated.
+     *
+     * The opposite shape (model narrower than labels) is intentionally permitted — STAGE2_BIO_LABELS
+     * prefix-extends STAGE1_BIO_LABELS so a Stage 1 model loaded with Stage 2 labels decodes
+     * correctly via the first 15 logits. See labels.ts for the contract.
+     */
+    assertEmissionWidth(logits) {
+        if (logits.length === 0)
+            return;
+        const width = logits[0].length;
+        if (width > this.labels.length) {
+            throw new Error(`Label/emission mismatch: model emits ${width} logits per token but the classifier was ` +
+                `configured with only ${this.labels.length} labels. Did you load a Stage 3 bundle without ` +
+                `passing its model-card labels? See loadFromWeights / loadNeuralClassifierFromUrls.`);
+        }
     }
 }
 function argmaxSoftmax(row) {
@@ -80,4 +233,16 @@ function argmaxSoftmax(row) {
     const conf = 1 / sumExp;
     return { idx: maxIdx, conf };
 }
+/** Element-wise add two square matrices. Used to compose the structural mask + learned transitions. */
+function addMatrices(a, b) {
+    const n = a.length;
+    const out = [];
+    for (let i = 0; i < n; i++) {
+        const row = new Array(n);
+        for (let j = 0; j < n; j++)
+            row[j] = a[i][j] + b[i][j];
+        out.push(row);
+    }
+    return out;
+}
 //# sourceMappingURL=classifier.js.map