@discretion/core 0.1.0

package/dist/src/ner/align.d.ts

@@ -0,0 +1,36 @@
+/**
+ * align.ts — map model token pieces back to exact character spans.
+ *
+ * Transformers.js exposes no offset mapping, so spans are recovered by
+ * scanning the input LEFT TO RIGHT and matching each piece at (or just
+ * after) the cursor. This is exact for pieces that are verbatim substrings
+ * — the overwhelming case, since Stage 2 runs on Stage-0-normalized text
+ * and the candidate models' tokenizers (mBERT WordPiece, XLM-R
+ * SentencePiece) do NFKC-compatible normalization the input has already
+ * been through. The exceptions are handled explicitly:
+ *
+ *  • '##piece'  — WordPiece continuation: match the bare piece.
+ *  • '▁piece'   — SentencePiece word start: match the bare piece ('▁'
+ *                 alone is a zero-width word boundary).
+ *  • '[UNK]' / '<unk>' — unlocatable: recorded as zero-width at the
+ *                 cursor; the entity merger bridges across them.
+ *  • normalization stragglers — a bounded forward search (SEARCH_WINDOW)
+ *                 recovers when the tokenizer skipped or rewrote a
+ *                 character; a piece not found within the window is
+ *                 treated like [UNK] rather than being guessed at.
+ *
+ * Whitespace between pieces is consumed by skipping it before each match.
+ * Greedy left-to-right matching is order-safe because pieces arrive in
+ * input order.
+ */
+export interface AlignedPiece {
+    /** Start offset in the input (inclusive); equals `end` when unlocated. */
+    readonly start: number;
+    /** End offset in the input (exclusive). */
+    readonly end: number;
+    /** False for [UNK]/unfindable pieces — zero-width placeholders. */
+    readonly located: boolean;
+}
+/** Align every piece to its character span in `text`. */
+export declare function alignPieces(text: string, pieces: readonly string[]): AlignedPiece[];
+//# sourceMappingURL=align.d.ts.map

package/dist/src/ner/align.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"align.d.ts","sourceRoot":"","sources":["../../../src/ner/align.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAOH,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAiBD,yDAAyD;AACzD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,YAAY,EAAE,CA6BnF"}

package/dist/src/ner/align.js

@@ -0,0 +1,73 @@
+/**
+ * align.ts — map model token pieces back to exact character spans.
+ *
+ * Transformers.js exposes no offset mapping, so spans are recovered by
+ * scanning the input LEFT TO RIGHT and matching each piece at (or just
+ * after) the cursor. This is exact for pieces that are verbatim substrings
+ * — the overwhelming case, since Stage 2 runs on Stage-0-normalized text
+ * and the candidate models' tokenizers (mBERT WordPiece, XLM-R
+ * SentencePiece) do NFKC-compatible normalization the input has already
+ * been through. The exceptions are handled explicitly:
+ *
+ *  • '##piece'  — WordPiece continuation: match the bare piece.
+ *  • '▁piece'   — SentencePiece word start: match the bare piece ('▁'
+ *                 alone is a zero-width word boundary).
+ *  • '[UNK]' / '<unk>' — unlocatable: recorded as zero-width at the
+ *                 cursor; the entity merger bridges across them.
+ *  • normalization stragglers — a bounded forward search (SEARCH_WINDOW)
+ *                 recovers when the tokenizer skipped or rewrote a
+ *                 character; a piece not found within the window is
+ *                 treated like [UNK] rather than being guessed at.
+ *
+ * Whitespace between pieces is consumed by skipping it before each match.
+ * Greedy left-to-right matching is order-safe because pieces arrive in
+ * input order.
+ */
+/** How far past the cursor a piece may be found before we refuse to guess. */
+const SEARCH_WINDOW = 24;
+const UNKNOWN_PIECES = new Set(['[UNK]', '<unk>']);
+const WHITESPACE = /\s/;
+function skipWhitespace(text, from) {
+    let i = from;
+    while (i < text.length && WHITESPACE.test(text[i]))
+        i += 1;
+    return i;
+}
+/** Strip subword markers down to the piece's surface text. */
+function surfaceOf(piece) {
+    if (piece.startsWith('##'))
+        return piece.slice(2);
+    if (piece.startsWith('▁'))
+        return piece.slice(1); // '▁'
+    return piece;
+}
+/** Align every piece to its character span in `text`. */
+export function alignPieces(text, pieces) {
+    const aligned = [];
+    let cursor = 0;
+    for (const raw of pieces) {
+        const piece = surfaceOf(raw);
+        if (piece.length === 0 || UNKNOWN_PIECES.has(raw)) {
+            aligned.push({ start: cursor, end: cursor, located: false });
+            continue;
+        }
+        const from = skipWhitespace(text, cursor);
+        let at = -1;
+        if (text.startsWith(piece, from)) {
+            at = from;
+        }
+        else {
+            const found = text.indexOf(piece, from);
+            if (found !== -1 && found - from <= SEARCH_WINDOW)
+                at = found;
+        }
+        if (at === -1) {
+            aligned.push({ start: cursor, end: cursor, located: false });
+            continue;
+        }
+        aligned.push({ start: at, end: at + piece.length, located: true });
+        cursor = at + piece.length;
+    }
+    return aligned;
+}
+//# sourceMappingURL=align.js.map

package/dist/src/ner/align.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"align.js","sourceRoot":"","sources":["../../../src/ner/align.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,8EAA8E;AAC9E,MAAM,aAAa,GAAG,EAAE,CAAC;AAEzB,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;AAWnD,MAAM,UAAU,GAAG,IAAI,CAAC;AAExB,SAAS,cAAc,CAAC,IAAY,EAAE,IAAY;IAChD,IAAI,CAAC,GAAG,IAAI,CAAC;IACb,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC;QAAE,CAAC,IAAI,CAAC,CAAC;IAC5D,OAAO,CAAC,CAAC;AACX,CAAC;AAED,8DAA8D;AAC9D,SAAS,SAAS,CAAC,KAAa;IAC9B,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAClD,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM;IACxD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,MAAyB;IACjE,MAAM,OAAO,GAAmB,EAAE,CAAC;IACnC,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAClD,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;YAC7D,SAAS;QACX,CAAC;QAED,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC1C,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;QACZ,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC;YACjC,EAAE,GAAG,IAAI,CAAC;QACZ,CAAC;aAAM,CAAC;YACN,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YACxC,IAAI,KAAK,KAAK,CAAC,CAAC,IAAI,KAAK,GAAG,IAAI,IAAI,aAAa;gBAAE,EAAE,GAAG,KAAK,CAAC;QAChE,CAAC;QAED,IAAI,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;YACd,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;YAC7D,SAAS;QACX,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,GAAG,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QACnE,MAAM,GAAG,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/src/ner/chunk.d.ts

@@ -0,0 +1,27 @@
+/**
+ * chunk.ts — window long inputs so the model sees ALL of the text.
+ *
+ * Transformer runtimes silently truncate past their token limit (verified
+ * against the actual runtime: a 3000-character input stopped producing
+ * predictions at token 512 with no error). Undetected text would be
+ * undetected sensitive data, so the engine windows the input in CHARACTER
+ * units — safe because the worst tokenizer ratio is one token per
+ * character (CJK) — with an overlap wide enough that any entity split by
+ * one window boundary lies fully inside a neighbouring window.
+ *
+ * De-duplication rule for the overlap: a window "owns" the entities whose
+ * span midpoint falls in its core (the window minus half an overlap at
+ * each interior edge). Every midpoint lands in exactly one core, so each
+ * entity is emitted exactly once, and — because overlap/2 exceeds any
+ * plausible entity length — the owning window saw the whole entity.
+ */
+export interface Chunk {
+    /** Offset of this window's first character in the full text. */
+    readonly offset: number;
+    readonly text: string;
+    /** Core region (absolute offsets): this window owns midpoints in it. */
+    readonly coreStart: number;
+    readonly coreEnd: number;
+}
+export declare function chunkText(text: string, maxChars: number, overlapChars: number): Chunk[];
+//# sourceMappingURL=chunk.d.ts.map

package/dist/src/ner/chunk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../../../src/ner/chunk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,KAAK;IACpB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAKD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,KAAK,EAAE,CAkCvF"}

package/dist/src/ner/chunk.js

@@ -0,0 +1,55 @@
+/**
+ * chunk.ts — window long inputs so the model sees ALL of the text.
+ *
+ * Transformer runtimes silently truncate past their token limit (verified
+ * against the actual runtime: a 3000-character input stopped producing
+ * predictions at token 512 with no error). Undetected text would be
+ * undetected sensitive data, so the engine windows the input in CHARACTER
+ * units — safe because the worst tokenizer ratio is one token per
+ * character (CJK) — with an overlap wide enough that any entity split by
+ * one window boundary lies fully inside a neighbouring window.
+ *
+ * De-duplication rule for the overlap: a window "owns" the entities whose
+ * span midpoint falls in its core (the window minus half an overlap at
+ * each interior edge). Every midpoint lands in exactly one core, so each
+ * entity is emitted exactly once, and — because overlap/2 exceeds any
+ * plausible entity length — the owning window saw the whole entity.
+ */
+/** Look this far back from a hard cut for a whitespace break. */
+const BREAK_LOOKBACK = 80;
+export function chunkText(text, maxChars, overlapChars) {
+    if (maxChars <= overlapChars * 2) {
+        throw new Error(`chunkText: maxChars ${maxChars} must exceed twice the overlap ${overlapChars}`);
+    }
+    if (text.length <= maxChars) {
+        return [{ offset: 0, text, coreStart: 0, coreEnd: text.length }];
+    }
+    const chunks = [];
+    let start = 0;
+    while (start < text.length) {
+        let end = Math.min(start + maxChars, text.length);
+        if (end < text.length) {
+            // Prefer to cut at whitespace so a word (and usually an entity) is
+            // not split at the hard boundary of BOTH neighbouring windows.
+            for (let i = end; i > end - BREAK_LOOKBACK && i > start + overlapChars; i--) {
+                if (/\s/.test(text[i - 1])) {
+                    end = i;
+                    break;
+                }
+            }
+        }
+        const isFirst = start === 0;
+        const isLast = end === text.length;
+        chunks.push({
+            offset: start,
+            text: text.slice(start, end),
+            coreStart: isFirst ? 0 : start + Math.floor(overlapChars / 2),
+            coreEnd: isLast ? text.length : end - Math.floor(overlapChars / 2),
+        });
+        if (isLast)
+            break;
+        start = end - overlapChars;
+    }
+    return chunks;
+}
+//# sourceMappingURL=chunk.js.map

package/dist/src/ner/chunk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.js","sourceRoot":"","sources":["../../../src/ner/chunk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAWH,iEAAiE;AACjE,MAAM,cAAc,GAAG,EAAE,CAAC;AAE1B,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,QAAgB,EAAE,YAAoB;IAC5E,IAAI,QAAQ,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,uBAAuB,QAAQ,kCAAkC,YAAY,EAAE,CAAC,CAAC;IACnG,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC5B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACnE,CAAC;IAED,MAAM,MAAM,GAAY,EAAE,CAAC;IAC3B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAC3B,IAAI,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAClD,IAAI,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACtB,mEAAmE;YACnE,+DAA+D;YAC/D,KAAK,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG,GAAG,cAAc,IAAI,CAAC,GAAG,KAAK,GAAG,YAAY,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC5E,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC,EAAE,CAAC;oBAC5B,GAAG,GAAG,CAAC,CAAC;oBACR,MAAM;gBACR,CAAC;YACH,CAAC;QACH,CAAC;QACD,MAAM,OAAO,GAAG,KAAK,KAAK,CAAC,CAAC;QAC5B,MAAM,MAAM,GAAG,GAAG,KAAK,IAAI,CAAC,MAAM,CAAC;QACnC,MAAM,CAAC,IAAI,CAAC;YACV,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC;YAC5B,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,CAAC,CAAC;YAC7D,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,CAAC,CAAC;SACnE,CAAC,CAAC;QACH,IAAI,MAAM;YAAE,MAAM;QAClB,KAAK,GAAG,GAAG,GAAG,YAAY,CAAC;IAC7B,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/src/ner/chunkCache.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Per-session reuse of Stage 2 results for unchanged chunks.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * WHY THIS EXISTS, WHICH IS AN OMISSION BEING CLOSED RATHER THAN A FEATURE
+ *
+ * ARCHITECTURE.md D28 reasons about window size using "the content-hash cache
+ * keys on chunk text", and BENCHMARKS.md's incremental figures — the ones
+ * SPEC's "pressing send is instant" rests on — were measured against exactly
+ * that behaviour. It did not exist. The benchmark harness SIMULATED it, by
+ * computing which chunks an edit invalidated and re-inferring only those,
+ * while `NerEngine.recognize()` re-inferred every chunk on every call.
+ *
+ * So the published incremental number described a design, and the shipped
+ * behaviour was the cold number on every debounced keystroke. This closes the
+ * gap so that the two agree.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * IT IS PER SESSION, AND THAT IS A PRIVACY CONSTRAINT, NOT A SIZE ONE
+ *
+ * The keys ARE the user's text, and the values are the entities found in it.
+ * SPEC.md: "Originals live in memory only, per-tab-session, cleared on
+ * nav-away/close." The model lives in an offscreen document that outlives any
+ * one tab and is shared by all of them, so a cache owned by the ENGINE would
+ * quietly retain one tab's composer text after that tab was gone, and expose
+ * it to the next.
+ *
+ * Ownership therefore sits with the caller, one instance per connection, so
+ * its lifetime is the connection's: the content script's session opens it and
+ * closing that session destroys it. That is the same lifetime the unmask vault
+ * already has, so this adds no new retention — it just must not be allowed to
+ * add any.
+ *
+ * NOT KEYED BY HASH. A 64-bit digest would shorten the keys and remove the
+ * plaintext, and a collision would return one chunk's entities for a different
+ * chunk's text — silently attaching the wrong spans at the wrong offsets. The
+ * retention question is settled by the per-connection lifetime above; trading
+ * a correctness risk for a privacy property already held would be a bad deal.
+ *
+ * SPANS ARE STORED WITHOUT THEIR TEXT and it is re-sliced on read. Not for
+ * privacy — the key is the text anyway — but because a stored `text` could
+ * drift from the chunk it is served against, and re-slicing makes that
+ * impossible by construction.
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+import type { NerSpan } from './types.js';
+export declare class ChunkCache {
+    /** Insertion order IS the LRU order: Map iterates oldest-first. */
+    private readonly entries;
+    private hitCount;
+    private missCount;
+    get(chunkText: string): NerSpan[] | undefined;
+    set(chunkText: string, spans: readonly NerSpan[]): void;
+    /** Drops every original. Called when the session it belongs to ends. */
+    clear(): void;
+    /** Counts only — never keys, never values. For the diagnostic. */
+    get stats(): {
+        readonly size: number;
+        readonly hits: number;
+        readonly misses: number;
+    };
+}
+//# sourceMappingURL=chunkCache.d.ts.map

package/dist/src/ner/chunkCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunkCache.d.ts","sourceRoot":"","sources":["../../../src/ner/chunkCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAgB1C,qBAAa,UAAU;IACrB,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4C;IACpE,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,SAAS,CAAK;IAEtB,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,EAAE,GAAG,SAAS;IAa7C,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI;IAmBvD,wEAAwE;IACxE,KAAK,IAAI,IAAI;IAIb,kEAAkE;IAClE,IAAI,KAAK,IAAI;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAErF;CACF"}

package/dist/src/ner/chunkCache.js

@@ -0,0 +1,99 @@
+/**
+ * Per-session reuse of Stage 2 results for unchanged chunks.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * WHY THIS EXISTS, WHICH IS AN OMISSION BEING CLOSED RATHER THAN A FEATURE
+ *
+ * ARCHITECTURE.md D28 reasons about window size using "the content-hash cache
+ * keys on chunk text", and BENCHMARKS.md's incremental figures — the ones
+ * SPEC's "pressing send is instant" rests on — were measured against exactly
+ * that behaviour. It did not exist. The benchmark harness SIMULATED it, by
+ * computing which chunks an edit invalidated and re-inferring only those,
+ * while `NerEngine.recognize()` re-inferred every chunk on every call.
+ *
+ * So the published incremental number described a design, and the shipped
+ * behaviour was the cold number on every debounced keystroke. This closes the
+ * gap so that the two agree.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * IT IS PER SESSION, AND THAT IS A PRIVACY CONSTRAINT, NOT A SIZE ONE
+ *
+ * The keys ARE the user's text, and the values are the entities found in it.
+ * SPEC.md: "Originals live in memory only, per-tab-session, cleared on
+ * nav-away/close." The model lives in an offscreen document that outlives any
+ * one tab and is shared by all of them, so a cache owned by the ENGINE would
+ * quietly retain one tab's composer text after that tab was gone, and expose
+ * it to the next.
+ *
+ * Ownership therefore sits with the caller, one instance per connection, so
+ * its lifetime is the connection's: the content script's session opens it and
+ * closing that session destroys it. That is the same lifetime the unmask vault
+ * already has, so this adds no new retention — it just must not be allowed to
+ * add any.
+ *
+ * NOT KEYED BY HASH. A 64-bit digest would shorten the keys and remove the
+ * plaintext, and a collision would return one chunk's entities for a different
+ * chunk's text — silently attaching the wrong spans at the wrong offsets. The
+ * retention question is settled by the per-connection lifetime above; trading
+ * a correctness risk for a privacy property already held would be a bad deal.
+ *
+ * SPANS ARE STORED WITHOUT THEIR TEXT and it is re-sliced on read. Not for
+ * privacy — the key is the text anyway — but because a stored `text` could
+ * drift from the chunk it is served against, and re-slicing makes that
+ * impossible by construction.
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+/**
+ * How many chunks one session may keep.
+ *
+ * A 2,000-character message is 7 chunks at the shipped 400-character window,
+ * so this holds a long message plus the history of edits that produced it.
+ * Bounded because a session lasts as long as a tab does, and an unbounded map
+ * keyed on everything a user has typed is exactly what SPEC's memory-only rule
+ * is trying to avoid.
+ */
+const MAX_ENTRIES = 256;
+export class ChunkCache {
+    /** Insertion order IS the LRU order: Map iterates oldest-first. */
+    entries = new Map();
+    hitCount = 0;
+    missCount = 0;
+    get(chunkText) {
+        const stored = this.entries.get(chunkText);
+        if (stored === undefined) {
+            this.missCount += 1;
+            return undefined;
+        }
+        // Re-inserted so a chunk that keeps being reused stays warm.
+        this.entries.delete(chunkText);
+        this.entries.set(chunkText, stored);
+        this.hitCount += 1;
+        return stored.map((span) => ({ ...span, text: chunkText.slice(span.start, span.end) }));
+    }
+    set(chunkText, spans) {
+        if (this.entries.has(chunkText))
+            this.entries.delete(chunkText);
+        this.entries.set(chunkText, spans.map((span) => ({
+            type: span.type,
+            start: span.start,
+            end: span.end,
+            score: span.score,
+            ...(span.gazetteer === undefined ? {} : { gazetteer: span.gazetteer }),
+        })));
+        while (this.entries.size > MAX_ENTRIES) {
+            const oldest = this.entries.keys().next();
+            if (oldest.done === true)
+                break;
+            this.entries.delete(oldest.value);
+        }
+    }
+    /** Drops every original. Called when the session it belongs to ends. */
+    clear() {
+        this.entries.clear();
+    }
+    /** Counts only — never keys, never values. For the diagnostic. */
+    get stats() {
+        return { size: this.entries.size, hits: this.hitCount, misses: this.missCount };
+    }
+}
+//# sourceMappingURL=chunkCache.js.map

package/dist/src/ner/chunkCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunkCache.js","sourceRoot":"","sources":["../../../src/ner/chunkCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAOH;;;;;;;;GAQG;AACH,MAAM,WAAW,GAAG,GAAG,CAAC;AAExB,MAAM,OAAO,UAAU;IACrB,mEAAmE;IAClD,OAAO,GAAG,IAAI,GAAG,EAAiC,CAAC;IAC5D,QAAQ,GAAG,CAAC,CAAC;IACb,SAAS,GAAG,CAAC,CAAC;IAEtB,GAAG,CAAC,SAAiB;QACnB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC;YACpB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,6DAA6D;QAC7D,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC/B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;QACnB,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1F,CAAC;IAED,GAAG,CAAC,SAAiB,EAAE,KAAyB;QAC9C,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAChE,IAAI,CAAC,OAAO,CAAC,GAAG,CACd,SAAS,EACT,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACnB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;SACvE,CAAC,CAAC,CACJ,CAAC;QACF,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,WAAW,EAAE,CAAC;YACvC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;YAC1C,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI;gBAAE,MAAM;YAChC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAED,wEAAwE;IACxE,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED,kEAAkE;IAClE,IAAI,KAAK;QACP,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;IAClF,CAAC;CACF"}

package/dist/src/ner/engine.d.ts

@@ -0,0 +1,53 @@
+/**
+ * engine.ts — Stage 2 orchestration: window → classify → align → decode,
+ * under a HARD deadline with fail-closed semantics.
+ *
+ * The deadline covers the whole recognize() call (all windows), not one
+ * inference: SPEC.md's budget is per user action. On exceed the engine
+ * throws DetectionTimeoutError — the same fail-closed contract the Stage 1
+ * runner enforces; callers treat it as "block the send", never as "send
+ * what we found so far", because a partial scan is indistinguishable from
+ * a clean scan on exactly the text that was never reached.
+ *
+ * warmup() runs one tiny inference so the first real interaction does not
+ * absorb model-initialization latency (SPEC: warm at init, not first use).
+ */
+import type { ChunkCache } from './chunkCache.js';
+import type { NerRecognizer, NerSpan, TokenClassifier } from './types.js';
+export interface NerEngineOptions {
+    /** Hard deadline for one recognize() call. Default 2000 ms. */
+    readonly timeBudgetMs?: number;
+    /** Window overlap in characters. Default 96. */
+    readonly overlapChars?: number;
+    /**
+     * Stage 2b gazetteer corroboration. Default true.
+     *
+     * Lives here rather than in Stage 3's options because the lookup lives here:
+     * SPEC places the gazetteers in Stage 2, checked in parallel with the model.
+     */
+    readonly useGazetteers?: boolean;
+}
+export declare class NerEngine implements NerRecognizer {
+    private readonly classifier;
+    private readonly budgetMs;
+    private readonly overlap;
+    private readonly useGazetteers;
+    private warmedUp;
+    constructor(classifier: TokenClassifier, options?: NerEngineOptions);
+    get id(): string;
+    /** One tiny inference so model init cost is paid before first real use. */
+    warmup(): Promise<void>;
+    /**
+     * Recognize entities in (normalized) `text`. Spans are in the text's own
+     * coordinates; runStage2 maps them back through the Stage 0 offset map.
+     */
+    /**
+     * Recognize entities in (normalized) `text`.
+     *
+     * `cache` is passed IN rather than owned here because its keys are the
+     * user's text: it must live and die with one session, and this engine is
+     * shared across every session in the process. See chunkCache.ts.
+     */
+    recognize(text: string, cache?: ChunkCache): Promise<NerSpan[]>;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/src/ner/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/ner/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE1E,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAKD,qBAAa,SAAU,YAAW,aAAa;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkB;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IACxC,OAAO,CAAC,QAAQ,CAAS;gBAEb,UAAU,EAAE,eAAe,EAAE,OAAO,GAAE,gBAAqB;IAOvE,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,2EAA2E;IACrE,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAM7B;;;OAGG;IACH;;;;;;OAMG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAiDtE"}

package/dist/src/ner/engine.js

@@ -0,0 +1,113 @@
+/**
+ * engine.ts — Stage 2 orchestration: window → classify → align → decode,
+ * under a HARD deadline with fail-closed semantics.
+ *
+ * The deadline covers the whole recognize() call (all windows), not one
+ * inference: SPEC.md's budget is per user action. On exceed the engine
+ * throws DetectionTimeoutError — the same fail-closed contract the Stage 1
+ * runner enforces; callers treat it as "block the send", never as "send
+ * what we found so far", because a partial scan is indistinguishable from
+ * a clean scan on exactly the text that was never reached.
+ *
+ * warmup() runs one tiny inference so the first real interaction does not
+ * absorb model-initialization latency (SPEC: warm at init, not first use).
+ */
+import { DetectionTimeoutError } from '../detect/runner.js';
+import { alignPieces } from './align.js';
+import { chunkText } from './chunk.js';
+import { decodeEntities } from './merge.js';
+import { attachGazetteerHits } from './stage2b.js';
+const DEFAULT_BUDGET_MS = 2000;
+const DEFAULT_OVERLAP = 96;
+export class NerEngine {
+    classifier;
+    budgetMs;
+    overlap;
+    useGazetteers;
+    warmedUp = false;
+    constructor(classifier, options = {}) {
+        this.classifier = classifier;
+        this.budgetMs = options.timeBudgetMs ?? DEFAULT_BUDGET_MS;
+        this.overlap = options.overlapChars ?? DEFAULT_OVERLAP;
+        this.useGazetteers = options.useGazetteers ?? true;
+    }
+    get id() {
+        return this.classifier.id;
+    }
+    /** One tiny inference so model init cost is paid before first real use. */
+    async warmup() {
+        if (this.warmedUp)
+            return;
+        await this.classifier.classify('warmup.');
+        this.warmedUp = true;
+    }
+    /**
+     * Recognize entities in (normalized) `text`. Spans are in the text's own
+     * coordinates; runStage2 maps them back through the Stage 0 offset map.
+     */
+    /**
+     * Recognize entities in (normalized) `text`.
+     *
+     * `cache` is passed IN rather than owned here because its keys are the
+     * user's text: it must live and die with one session, and this engine is
+     * shared across every session in the process. See chunkCache.ts.
+     */
+    async recognize(text, cache) {
+        if (text.length === 0)
+            return [];
+        const started = Date.now();
+        const deadline = started + this.budgetMs;
+        const chunks = chunkText(text, this.classifier.maxInputChars, this.overlap);
+        const spans = [];
+        for (const chunk of chunks) {
+            // A cache hit costs no inference and therefore no deadline: the budget
+            // exists to bound model time, and there is none to bound. Checking the
+            // deadline before the lookup would let a document time out on work it
+            // was never going to do.
+            let local = cache?.get(chunk.text);
+            if (local === undefined) {
+                const remaining = deadline - Date.now();
+                if (remaining <= 0) {
+                    throw new DetectionTimeoutError(this.budgetMs, Date.now() - started);
+                }
+                const predictions = await withDeadline(this.classifier.classify(chunk.text), remaining, () => new DetectionTimeoutError(this.budgetMs, Date.now() - started));
+                const aligned = alignPieces(chunk.text, predictions.map((p) => p.piece));
+                // Stored in CHUNK-LOCAL coordinates, before the offset shift below:
+                // the same chunk text can appear at different offsets in different
+                // documents, and a cache keyed on the text must not remember where it
+                // happened to sit the first time.
+                local = decodeEntities(chunk.text, predictions, aligned);
+                cache?.set(chunk.text, local);
+            }
+            for (const span of local) {
+                const mid = chunk.offset + (span.start + span.end) / 2;
+                // The owning-core rule from chunk.ts: emit each entity exactly once.
+                if (mid >= chunk.coreStart && mid < chunk.coreEnd) {
+                    spans.push({ ...span, start: chunk.offset + span.start, end: chunk.offset + span.end });
+                }
+            }
+        }
+        const ordered = spans.sort((a, b) => a.start - b.start);
+        // Stage 2b, on the same side of any process boundary as the model: SPEC
+        // has the gazetteers "checked in parallel with the model", and they can
+        // only corroborate types the model produces.
+        return this.useGazetteers ? attachGazetteerHits(ordered) : ordered;
+    }
+}
+/** Race a promise against a deadline; the loser's result is discarded. */
+async function withDeadline(work, ms, onTimeout) {
+    let timer;
+    try {
+        return await Promise.race([
+            work,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(onTimeout()), ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/src/ner/engine.js.map

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

package/dist/src/ner/merge.d.ts

@@ -0,0 +1,26 @@
+/**
+ * merge.ts — decode per-token BIO labels into entity spans.
+ *
+ * Handles BOTH tagging conventions the candidate models use:
+ *  • IOB2 (mBERT/distilmBERT NER-HRL): entities start with B-X.
+ *  • IOB1 (XLM-R CoNLL fine-tunes): entities may start with I-X after O
+ *    or at sequence start; B-X appears only to split adjacent same-type
+ *    entities.
+ * Decoding rule that satisfies both: a token starts a NEW entity when its
+ * label is B-X, or when it is I-X and the previous token was not part of
+ * an X entity. Same-type I-X continues; any other label ends the entity.
+ *
+ * Unlocated pieces ([UNK] and friends) inside an entity are BRIDGED: the
+ * entity's span runs from its first located piece to its last located
+ * piece. An entity with no located piece at all is dropped — emitting a
+ * guessed span would violate the exact-offsets contract.
+ *
+ * The entity score is the MINIMUM token score — one uncertain token makes
+ * the whole span uncertain. Scores are uncalibrated model softmax until
+ * Stage 4 (M8) calibrates; the eval buckets measure what they are worth.
+ */
+import type { AlignedPiece } from './align.js';
+import type { NerSpan, TokenPrediction } from './types.js';
+/** Decode predictions + aligned spans into merged entity spans. */
+export declare function decodeEntities(text: string, predictions: readonly TokenPrediction[], aligned: readonly AlignedPiece[]): NerSpan[];
+//# sourceMappingURL=merge.d.ts.map

package/dist/src/ner/merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../../src/ner/merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAiB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAgC1E,mEAAmE;AACnE,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,SAAS,eAAe,EAAE,EACvC,OAAO,EAAE,SAAS,YAAY,EAAE,GAC/B,OAAO,EAAE,CAkDX"}