@discretion/core 0.1.0

package/src/mask/surrogates.ts

@@ -0,0 +1,248 @@
+/**
+ * The surrogate registry: given a detected entity, produce a same-shape
+ * replacement value.
+ *
+ * SPEC.md, substitution: replace a value with "a realistic value of the same
+ * type and shape" so the model reasons over coherent text, and for
+ * identifiers "a value passing that country's checksum, so downstream
+ * validation in the model's reasoning still behaves". We reuse the M2/M3
+ * generators as the source — a surrogate IBAN needs exactly the checksum
+ * validity a real one has, and that generator already exists.
+ *
+ * Two SPEC judgement calls, recorded in ARCHITECTURE.md D12:
+ *
+ *  • "Same country / same issuer." Honored where the detector's metadata
+ *    carries it: IBAN → same country, CREDIT_CARD → same issuer, national
+ *    identifiers → the SAME scheme's generator (a TCKN surrogate for a TCKN),
+ *    VAT → same member state, crypto → same chain, IP → same version.
+ *
+ *  • "SECRET → a same-shape dummy that is clearly non-functional." The reused
+ *    generators produce syntactically valid but RANDOM values (a JWT with a
+ *    random signature, a PEM with a random body, a provider token with a
+ *    random body) — non-functional because random, not because marked. That
+ *    satisfies "non-functional"; if a visibly-marked dummy is later wanted it
+ *    is a pool swap, not a structural change. Flagged, not silently resolved.
+ *
+ * `chooseSurrogate` returns `null` when no sensible surrogate exists for the
+ * type — the masker then falls back to a bracket token and records it, per
+ * SPEC.md's FALLBACK rule.
+ */
+
+import * as generate from '../generate/index.js';
+import { detectScripts } from '../scripts.js';
+import type { EntityType, ScriptName } from '../types.js';
+import { PERSON_POOLS, DEFAULT_PERSON_POOL, ORG_POOL, LOCATION_POOL } from './surrogatePools.js';
+
+const g = generate;
+
+/** What the masker gives the registry about one detected value. */
+export interface SurrogateRequest {
+  readonly type: EntityType;
+  /** The matched text (normalized). Used for shape and script inference. */
+  readonly text: string;
+  /** Detector metadata: scheme, country, issuer, chain, version, kind. */
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+const meta = (req: SurrogateRequest, key: string): string | undefined => {
+  const v = req.metadata?.[key];
+  return typeof v === 'string' ? v : undefined;
+};
+
+/** National/tax/vat scheme → the generator that produces a valid instance. */
+const SCHEME_GENERATORS: Readonly<Record<string, (seed: number) => string>> = {
+  ssn: g.generateValidSsn, sin: g.generateValidSin, nino: g.generateValidNino, nhs: g.generateValidNhs,
+  pps: g.generateValidPps, 'steuer-id': g.generateValidSteuerId, personalausweis: g.generateValidAusweis,
+  nir: g.generateValidNir, dni: g.generateValidDni, nie: g.generateValidNie,
+  'codice-fiscale': g.generateValidCodiceFiscale, bsn: g.generateValidBsn, rijksregister: g.generateValidBeRrn,
+  pesel: g.generateValidPesel, nip: g.generateValidNip, regon: g.generateValidRegon,
+  personnummer: g.generateValidPersonnummer, fodselsnummer: g.generateValidFodselsnummer, cpr: g.generateValidCpr,
+  hetu: g.generateValidHetu, kennitala: g.generateValidKennitala, nif: g.generateValidPtNif, afm: g.generateValidAfm,
+  'rodne-cislo': g.generateValidRodneCislo, 'szemelyi-szam': g.generateValidSzemelyi, cnp: g.generateValidCnp,
+  egn: g.generateValidEgn, oib: g.generateValidOib, emso: g.generateValidEmso, tckn: g.generateValidTckn,
+  vkn: g.generateValidVkn, inn: g.generateValidInn12, snils: g.generateValidSnils, rnokpp: g.generateValidRnokpp,
+  iin: g.generateValidIin, 'teudat-zehut': g.generateValidTeudatZehut, 'saudi-id': g.generateValidSaudiId,
+  'emirates-id': g.generateValidEmiratesId, qid: g.generateValidQid, 'civil-id': g.generateValidKwCivilId,
+  aadhaar: g.generateValidAadhaar, pan: g.generateValidPan, ric: g.generateValidRic, 'tw-id': g.generateValidTwId,
+  'my-number': g.generateValidMyNumber, rrn: g.generateValidKrRrn, nric: g.generateValidNric, hkid: g.generateValidHkid,
+  cnic: g.generateValidCnic, nid: g.generateValidBdNid, mykad: g.generateValidMykad, nik: g.generateValidNik,
+  'thai-id': g.generateValidThaiId, cccd: g.generateValidCccd, psn: g.generateValidPsn, tfn: g.generateValidTfn,
+  medicare: g.generateValidMedicare, abn: g.generateValidAbn, ird: g.generateValidIrd, cpf: g.generateValidCpf,
+  cnpj: g.generateValidCnpj, curp: g.generateValidCurp, rfc: g.generateValidRfc, cuit: g.generateValidCuit,
+  rut: g.generateValidRut, nit: g.generateValidNit, 'za-id': g.generateValidZaId,
+};
+
+/** Bare-number schemes whose detector span is value-only but whose generator
+ *  emits a label — produce the bare value directly. */
+const BARE_VALUE_SCHEMES: Readonly<Record<string, (seed: number) => string>> = {
+  cnie: (s) => {
+    const rng = g.mulberry32(s);
+    const L = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+    const prefix = rng() < 0.5 ? L[Math.floor(rng() * 26)]! : L[Math.floor(rng() * 26)]! + L[Math.floor(rng() * 26)]!;
+    let d = '';
+    for (let i = 0; i < 6; i++) d += Math.floor(rng() * 10);
+    return `${prefix}${d}`;
+  },
+  nin: (s) => {
+    const rng = g.mulberry32(s);
+    let d = '';
+    for (let i = 0; i < 11; i++) d += Math.floor(rng() * 10);
+    return d;
+  },
+  'ke-id': (s) => {
+    const rng = g.mulberry32(s);
+    let d = '';
+    for (let i = 0; i < 8; i++) d += Math.floor(rng() * 10);
+    return d;
+  },
+  'ar-dni': (s) => {
+    const rng = g.mulberry32(s);
+    const n = 10_000_000 + Math.floor(rng() * 89_999_999);
+    return String(n).replace(/\B(?=(\d{3})+(?!\d))/g, '.');
+  },
+  'pe-dni': (s) => {
+    const rng = g.mulberry32(s);
+    let d = '';
+    for (let i = 0; i < 8; i++) d += Math.floor(rng() * 10);
+    return d;
+  },
+  agencia: (s) => {
+    const rng = g.mulberry32(s);
+    let d = '';
+    for (let i = 0; i < 4; i++) d += Math.floor(rng() * 10);
+    return rng() < 0.4 ? `${d}-${Math.floor(rng() * 10)}` : d;
+  },
+};
+
+/** Dominant script of the detected text, for PERSON surrogate matching. */
+function scriptOf(text: string): ScriptName {
+  return detectScripts(text).dominant ?? 'latin';
+}
+
+function personSurrogate(text: string, seed: number): string {
+  const script = scriptOf(text);
+  const pool = PERSON_POOLS.find((p) => p.script === script) ?? DEFAULT_PERSON_POOL;
+  const rng = g.mulberry32(seed);
+  const given = pool.given[Math.floor(rng() * pool.given.length)]!;
+  const surname = pool.surnames[Math.floor(rng() * pool.surnames.length)]!;
+  return pool.order === 'given-first' ? `${given}${pool.sep}${surname}` : `${surname}${pool.sep}${given}`;
+}
+
+/** A plausible ICD-10 code (letter + 2 digits + optional .subcode). */
+function icd10Surrogate(seed: number): string {
+  const rng = g.mulberry32(seed);
+  const letters = 'ABCDEFGHIJKLMNOPRSTUVWXYZ';
+  const head = `${letters[Math.floor(rng() * letters.length)]}${Math.floor(rng() * 10)}${Math.floor(rng() * 10)}`;
+  return rng() < 0.6 ? `${head}.${Math.floor(rng() * 10)}` : head;
+}
+
+/**
+ * Choose a surrogate for a detected entity. Returns the surrogate string, or
+ * `null` when the type has no sensible surrogate (masker → bracket token).
+ * `seed` varies across collision retries so a fresh value is produced.
+ */
+export function chooseSurrogate(req: SurrogateRequest, seed: number): string | null {
+  switch (req.type) {
+    case 'EMAIL':
+      return g.generateValidEmail(seed);
+    case 'PHONE':
+      return g.generateValidPhone(seed);
+    case 'IP_ADDRESS':
+      return meta(req, 'version') === '6' || req.text.includes(':')
+        ? g.generateValidIpv6(seed)
+        : g.generateValidIpv4(seed);
+    case 'MAC_ADDRESS':
+      return g.generateValidMac(seed);
+    case 'URL_WITH_CREDENTIALS':
+      return g.generateValidCredentialUrl(seed);
+    case 'CREDIT_CARD':
+      return g.generateValidCardForIssuer(meta(req, 'issuer') ?? 'visa', seed);
+    case 'IBAN': {
+      const country = meta(req, 'country') ?? req.text.slice(0, 2).toUpperCase();
+      return g.generateValidIbanForCountry(country, seed);
+    }
+    case 'SWIFT_BIC':
+      return g.generateValidBic(seed);
+    case 'US_ROUTING_NUMBER':
+      return g.generateValidRouting(seed);
+    case 'UK_SORT_CODE':
+      return g.generateValidSortCode(seed);
+    case 'CA_TRANSIT_NUMBER':
+      return g.generateValidTransit(seed);
+    case 'AU_BSB':
+      return g.generateValidBsb(seed);
+    case 'IN_IFSC':
+      return g.generateValidIfsc(seed);
+    case 'BR_AGENCIA':
+      return BARE_VALUE_SCHEMES['agencia']!(seed);
+    case 'CRYPTO_WALLET': {
+      const chain = meta(req, 'chain');
+      const byChain: Record<string, (s: number) => string> = {
+        btc: g.generateValidBtc, eth: g.generateValidEth, ltc: g.generateValidLtc, trx: g.generateValidTrx,
+        xmr: g.generateValidXmr, sol: g.generateValidSol, ada: g.generateValidAda, dot: g.generateValidDot,
+      };
+      return (chain !== undefined ? byChain[chain] : undefined)?.(seed) ?? g.generateValidBtc(seed);
+    }
+    case 'API_KEY':
+      return g.generateValidProviderToken(seed);
+    case 'JWT':
+      return g.generateValidJwt(seed);
+    case 'PRIVATE_KEY':
+      return g.generateValidPem(seed);
+    case 'GENERIC_SECRET':
+      return g.generateHighEntropySecret(seed);
+    case 'CONNECTION_STRING':
+      return g.generateValidConnectionString(seed);
+    case 'PASSPORT_MRZ':
+      return g.generateValidTd3(seed);
+    case 'DRIVERS_LICENSE':
+      return g.generateValidDvla(seed);
+    case 'VIN':
+      return g.generateValidVin(seed);
+    case 'US_NPI':
+      return g.generateValidNpi(seed);
+    case 'HEALTH_DATA': {
+      const kind = meta(req, 'kind');
+      if (kind === 'snomed') return g.generateValidSctid(seed);
+      if (kind === 'lab-result') return g.generateValidLabResult(seed);
+      if (kind === 'icd10') return icd10Surrogate(seed);
+      return null; // bare-number SNOMED without kind, or an unmodeled shape
+    }
+    case 'POSTAL_CODE':
+      return g.generateValidPostal(seed);
+    case 'STREET_ADDRESS':
+      return g.generateValidStreet(seed);
+    case 'COORDINATES':
+      return g.generateValidCoordinates(seed);
+    case 'NATIONAL_ID':
+    case 'TAX_ID': {
+      const scheme = meta(req, 'scheme');
+      if (scheme !== undefined) {
+        const bare = BARE_VALUE_SCHEMES[scheme];
+        if (bare !== undefined) return bare(seed);
+        const gen = SCHEME_GENERATORS[scheme];
+        if (gen !== undefined) return gen(seed);
+      }
+      return null; // unknown scheme → token
+    }
+    case 'VAT_NUMBER': {
+      const country = meta(req, 'country') ?? req.text.slice(0, 2).toUpperCase();
+      const c = country === 'GR' ? 'EL' : country;
+      if (g.VAT_COUNTRIES.includes(c)) return g.generateValidVatFor(c, seed);
+      return g.generateValidEuVat(seed);
+    }
+    case 'PERSON':
+      return personSurrogate(req.text, seed);
+    case 'ORG':
+      return ORG_POOL[seed % ORG_POOL.length]!;
+    case 'LOCATION':
+      return LOCATION_POOL[seed % LOCATION_POOL.length]!;
+    case 'DATE_OF_BIRTH':
+      // Ordering-preserving date shifting needs a date detector (absent until
+      // a later milestone) and a session offset; until then no surrogate,
+      // so the masker uses a token. Recorded in ARCHITECTURE.md D12.
+      return null;
+    default:
+      return null;
+  }
+}

package/src/mask/vault.ts

@@ -0,0 +1,153 @@
+/**
+ * vault.ts — the in-memory bidirectional map between originals and their
+ * replacements.
+ *
+ * SPEC.md contract: deterministic and referentially consistent; normalized
+ * lookup so trivial variants (case, surrounding whitespace) resolve to one
+ * entry; clear() wipes it; and NO method exposes the full plaintext set
+ * except the egress guard, which needs it.
+ *
+ * That last rule is enforced by shape, not convention: the only bulk
+ * accessor is `createEgressAuditor()`, which returns a capability object
+ * whose sole consumer is `guardEgress`. Every other read requires already
+ * knowing the value being looked up (`getByOriginal`) or holds no plaintext
+ * (`getBySurrogate` returns the entry, whose `original` the restorer needs
+ * one at a time — that is restoration's whole job). There is deliberately
+ * no `entries()` / iteration API. (TypeScript cannot stop a caller from
+ * invoking the auditor factory, but the single, loudly-named door makes any
+ * misuse a visible code-review event rather than an accident. Recorded in
+ * ARCHITECTURE.md D11.)
+ *
+ * NORMALIZED LOOKUP is deliberately conservative. The lookup key folds
+ * case and trims/collapses whitespace, but a normalized key may be shared
+ * by DIFFERENT exact originals (two base58 values differing only in case
+ * are different values). The exact map always wins; the normalized index
+ * resolves a variant only when it maps to exactly one entry — an ambiguous
+ * normalized hit returns undefined rather than guessing.
+ */
+
+import type { EntityType, VaultEntry } from '../types.js';
+
+/** Case-folded, trimmed, inner-whitespace-collapsed lookup key. */
+export function normalizedKey(value: string): string {
+  return value.trim().replace(/\s+/g, ' ').toLowerCase();
+}
+
+/** What the egress guard receives: the one deliberate door to plaintext. */
+export interface EgressAuditor {
+  /** Every entry: (exact original, canonical, id, type). Guard-only. */
+  auditEntries(): readonly { original: string; canonical: string; id: string; type: EntityType }[];
+}
+
+export class Vault {
+  private readonly byOriginal = new Map<string, VaultEntry>();
+  private readonly byCanonical = new Map<string, VaultEntry>();
+  private readonly byNormalized = new Map<string, Set<VaultEntry>>();
+  private readonly byReplacement = new Map<string, VaultEntry>();
+  private counter = 0;
+
+  /**
+   * Register a new masked value. The caller (the masker) has already
+   * resolved consistency — `register` throws on a duplicate original or
+   * replacement rather than silently merging, because reaching that point
+   * means the masker's lookup logic is broken and restoration would be
+   * ambiguous.
+   */
+  register(entry: Omit<VaultEntry, 'id' | 'createdAt'>): VaultEntry {
+    if (this.byOriginal.has(entry.original)) {
+      throw new Error('vault: original already registered');
+    }
+    if (this.byReplacement.has(entry.replacement)) {
+      throw new Error('vault: replacement already in use');
+    }
+    const full: VaultEntry = {
+      ...entry,
+      id: `v${++this.counter}`,
+      createdAt: Date.now(),
+    };
+    this.byOriginal.set(full.original, full);
+    if (full.canonical !== undefined) {
+      if (!this.byCanonical.has(full.canonical)) this.byCanonical.set(full.canonical, full);
+    }
+    const key = normalizedKey(full.original);
+    let set = this.byNormalized.get(key);
+    if (set === undefined) {
+      set = new Set();
+      this.byNormalized.set(key, set);
+    }
+    set.add(full);
+    this.byReplacement.set(full.replacement, full);
+    return full;
+  }
+
+  /**
+   * Find the entry for an original: exact writing first, then the
+   * detector's canonical form (separator variants of one identifier), then
+   * the case/whitespace-normalized index — which only resolves when
+   * unambiguous.
+   */
+  getByOriginal(original: string, canonical?: string): VaultEntry | undefined {
+    const exact = this.byOriginal.get(original);
+    if (exact !== undefined) return exact;
+    if (canonical !== undefined) {
+      const viaCanonical = this.byCanonical.get(canonical);
+      if (viaCanonical !== undefined) return viaCanonical;
+    }
+    const set = this.byNormalized.get(normalizedKey(original));
+    if (set !== undefined && set.size === 1) {
+      return set.values().next().value;
+    }
+    return undefined;
+  }
+
+  /** Find the entry whose replacement is exactly `replacement`. */
+  getBySurrogate(replacement: string): VaultEntry | undefined {
+    return this.byReplacement.get(replacement);
+  }
+
+  /** True when `value` is already in use as a replacement or an original —
+   *  the collision check surrogate selection runs before committing. */
+  wouldCollide(value: string): boolean {
+    if (this.byReplacement.has(value)) return true;
+    if (this.byOriginal.has(value)) return true;
+    // Case-insensitive replacement uniqueness: the restorer's fuzzy pass
+    // (case-changed surrogates) is only sound when no two replacements
+    // collide case-insensitively.
+    const key = normalizedKey(value);
+    for (const replacement of this.byReplacement.keys()) {
+      if (normalizedKey(replacement) === key) return true;
+    }
+    return this.byNormalized.has(key);
+  }
+
+  /** All current replacements (surrogates/tokens) — contains no originals;
+   *  the restorer builds its match tables from this. */
+  replacements(): readonly string[] {
+    return [...this.byReplacement.keys()];
+  }
+
+  get size(): number {
+    return this.byOriginal.size;
+  }
+
+  /** Wipe everything. Called on navigation away and conversation switch. */
+  clear(): void {
+    this.byOriginal.clear();
+    this.byCanonical.clear();
+    this.byNormalized.clear();
+    this.byReplacement.clear();
+  }
+
+  /** THE one deliberate door to the plaintext set. Egress guard only. */
+  createEgressAuditor(): EgressAuditor {
+    return {
+      auditEntries: () =>
+        [...this.byOriginal.values()].map((e) => ({
+          original: e.original,
+          canonical: e.canonical ?? e.original,
+          id: e.id,
+          type: e.type,
+        })),
+    };
+  }
+}

package/src/ner/align.ts

@@ -0,0 +1,86 @@
+/**
+ * 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>']);
+
+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;
+}
+
+const WHITESPACE = /\s/;
+
+function skipWhitespace(text: string, from: number): number {
+  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: string): string {
+  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: string, pieces: readonly string[]): AlignedPiece[] {
+  const aligned: AlignedPiece[] = [];
+  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;
+}

package/src/ner/chunk.ts

@@ -0,0 +1,65 @@
+/**
+ * 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;
+}
+
+/** Look this far back from a hard cut for a whitespace break. */
+const BREAK_LOOKBACK = 80;
+
+export function chunkText(text: string, maxChars: number, overlapChars: number): Chunk[] {
+  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: Chunk[] = [];
+  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;
+}

package/src/ner/chunkCache.ts

@@ -0,0 +1,110 @@
+/**
+ * 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';
+
+/** A span with its text elided; re-derived from the chunk on read. */
+type StoredSpan = Omit<NerSpan, 'text'>;
+
+/**
+ * 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. */
+  private readonly entries = new Map<string, readonly StoredSpan[]>();
+  private hitCount = 0;
+  private missCount = 0;
+
+  get(chunkText: string): NerSpan[] | undefined {
+    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: string, spans: readonly NerSpan[]): void {
+    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(): void {
+    this.entries.clear();
+  }
+
+  /** Counts only — never keys, never values. For the diagnostic. */
+  get stats(): { readonly size: number; readonly hits: number; readonly misses: number } {
+    return { size: this.entries.size, hits: this.hitCount, misses: this.missCount };
+  }
+}