@discretion/core 0.1.0

package/src/generate/prng.ts

@@ -0,0 +1,17 @@
+/**
+ * Deterministic PRNG for the value generators.
+ *
+ * mulberry32 — the same generator the fuzz suites use, copied here so the
+ * generators are part of core's public API (the eval corpus builder and
+ * M4's format-preserving surrogates both consume them) without src code
+ * reaching into test code.
+ */
+export function mulberry32(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}

package/src/generate/secrets.ts

@@ -0,0 +1,141 @@
+/**
+ * Valid-value generators for the secrets family.
+ *
+ * The provider tokens have no universal checksum except GitHub's, so most
+ * generators synthesize a shape the validator accepts; the GitHub generator
+ * computes a real CRC32 so its output passes the checksum gate (and a
+ * mutation of the random body fails it). JWT synthesis builds a real
+ * base64url header with a valid alg. GENERIC_SECRET is context-gated, so its
+ * generator produces high-entropy strings the entropy half accepts.
+ */
+
+import { mulberry32 } from './prng.js';
+
+function pick<T>(rng: () => number, items: readonly T[]): T {
+  return items[Math.floor(rng() * items.length)]!;
+}
+
+const BASE62 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+const HEX = '0123456789abcdef';
+const B64URL = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+
+function chars(rng: () => number, alphabet: string, n: number): string {
+  let out = '';
+  for (let i = 0; i < n; i++) out += alphabet[Math.floor(rng() * alphabet.length)]!;
+  return out;
+}
+
+// ── GitHub token with a real CRC32 checksum ──
+
+function crc32(s: string): number {
+  let crc = 0xffffffff;
+  for (let i = 0; i < s.length; i++) {
+    crc ^= s.charCodeAt(i);
+    for (let b = 0; b < 8; b++) crc = crc & 1 ? (crc >>> 1) ^ 0xedb88320 : crc >>> 1;
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function githubCheck(random: string): string {
+  let value = crc32(random);
+  let encoded = '';
+  for (let i = 0; i < 6; i++) {
+    encoded = BASE62[value % 62]! + encoded;
+    value = Math.floor(value / 62);
+  }
+  return encoded;
+}
+
+/** A GitHub PAT (ghp_) whose CRC32 checksum is correct. */
+export function generateValidGithubToken(seed: number): string {
+  const rng = mulberry32(seed);
+  const random = chars(rng, BASE62, 30);
+  return `ghp_${random}${githubCheck(random)}`;
+}
+
+/** A non-GitHub provider token that satisfies its shape entry. */
+export function generateValidProviderToken(seed: number): string {
+  const rng = mulberry32(seed);
+  const shapes: readonly (() => string)[] = [
+    () => `sk-${chars(rng, BASE62, 48)}`, // OpenAI
+    () => `AIza${chars(rng, B64URL, 35)}`, // Google
+    () => `AKIA${chars(rng, BASE62, 16)}`, // AWS
+    () => `glpat-${chars(rng, B64URL, 20)}`, // GitLab
+    () => `xoxb-${chars(rng, BASE62, 24)}`, // Slack
+    () => `sk_live_${chars(rng, BASE62, 24)}`, // Stripe
+    () => `SK${chars(rng, HEX, 32)}`, // Twilio
+    () => `npm_${chars(rng, BASE62, 36)}`, // npm
+    () => `hf_${chars(rng, BASE62, 34)}`, // Hugging Face
+  ];
+  return pick(rng, shapes)();
+}
+
+// ── JWT ──
+
+function b64url(s: string): string {
+  const chars64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+  let out = '';
+  let acc = 0;
+  let bits = 0;
+  for (let i = 0; i < s.length; i++) {
+    acc = (acc << 8) | s.charCodeAt(i);
+    bits += 8;
+    while (bits >= 6) {
+      bits -= 6;
+      out += chars64[(acc >> bits) & 0x3f]!;
+    }
+  }
+  if (bits > 0) out += chars64[(acc << (6 - bits)) & 0x3f]!;
+  return out.replace(/\+/g, '-').replace(/\//g, '_');
+}
+
+const JWT_ALGS = ['HS256', 'RS256', 'ES256', 'PS384', 'EdDSA'];
+
+/** A structurally valid JWT with a real header carrying a valid alg. */
+export function generateValidJwt(seed: number): string {
+  const rng = mulberry32(seed);
+  const alg = pick(rng, JWT_ALGS);
+  const header = b64url(JSON.stringify({ alg, typ: 'JWT' }));
+  const payload = b64url(JSON.stringify({ sub: chars(rng, BASE62, 8), iat: 1_600_000_000 + Math.floor(rng() * 1e7) }));
+  const signature = chars(rng, B64URL, 43);
+  return `${header}.${payload}.${signature}`;
+}
+
+// ── PEM ──
+
+/** A PEM private-key block with matching armor labels and base64 body. */
+export function generateValidPem(seed: number): string {
+  const rng = mulberry32(seed);
+  const label = pick(rng, ['PRIVATE KEY', 'RSA PRIVATE KEY', 'EC PRIVATE KEY', 'OPENSSH PRIVATE KEY']);
+  const lines: string[] = [];
+  const lineCount = 4 + Math.floor(rng() * 6);
+  for (let i = 0; i < lineCount; i++) lines.push(chars(rng, `${BASE62}+/`, 64));
+  return `-----BEGIN ${label}-----\n${lines.join('\n')}\n-----END ${label}-----`;
+}
+
+// ── Connection strings ──
+
+const DB_SCHEMES = ['postgres', 'mysql', 'mongodb', 'redis', 'mongodb+srv', 'mariadb', 'amqp'];
+
+/** A database connection URI with a password in userinfo. */
+export function generateValidConnectionString(seed: number): string {
+  const rng = mulberry32(seed);
+  const scheme = pick(rng, DB_SCHEMES);
+  const user = pick(rng, ['app', 'admin', 'svc', 'root']);
+  const pass = chars(rng, BASE62, 12 + Math.floor(rng() * 8));
+  const host = pick(rng, ['db.internal', 'prod-db.corp', 'cluster0.mongodb.net', '10.0.3.4']);
+  return `${scheme}://${user}:${pass}@${host}:5432/appdb`;
+}
+
+// ── Generic secret (high-entropy) ──
+
+/** A high-entropy mixed-class token the entropy gate accepts. */
+export function generateHighEntropySecret(seed: number): string {
+  const rng = mulberry32(seed);
+  const len = 24 + Math.floor(rng() * 24);
+  // Guarantee at least two character classes and high diversity.
+  let out = chars(rng, `${BASE62}-_`, len);
+  // Force a digit and a letter to be present.
+  out = `A9${out.slice(2)}`;
+  return out;
+}

package/src/generate/vat.ts

@@ -0,0 +1,239 @@
+/**
+ * Valid-value generators for EU VAT — one synthesizer per member state,
+ * each closing its national checksum with the shared primitives, plus a
+ * country-random wrapper. Reused by M3's corpus generator.
+ */
+
+import {
+  toDigits,
+  weightedSum,
+  weightedMod,
+  weightedModBy,
+  cyclicWeightedMod,
+  luhnCheckDigit,
+  mod11_10CheckDigit,
+} from '../checksums/index.js';
+import { mulberry32 } from './prng.js';
+
+function pick<T>(rng: () => number, items: readonly T[]): T {
+  return items[Math.floor(rng() * items.length)]!;
+}
+
+function int(rng: () => number, min: number, max: number): number {
+  return min + Math.floor(rng() * (max - min + 1));
+}
+
+function digits(rng: () => number, n: number): string {
+  let out = '';
+  for (let i = 0; i < n; i++) out += String(int(rng, 0, 9));
+  return out;
+}
+
+type Synth = (rng: () => number) => string;
+
+const SYNTHS: Readonly<Record<string, Synth>> = {
+  AT: (rng) => {
+    const seven = digits(rng, 7);
+    const d = toDigits(seven)!;
+    let s = 0;
+    for (let i = 0; i < 7; i++) {
+      const product = d[i]! * (i % 2 === 0 ? 1 : 2);
+      s += product > 9 ? product - 9 : product;
+    }
+    return `U${seven}${(10 - ((s + 4) % 10)) % 10}`;
+  },
+  BE: (rng) => {
+    const eight = `0${digits(rng, 7)}`;
+    return `${eight}${String(97 - (Number(eight) % 97)).padStart(2, '0')}`;
+  },
+  BG: (rng) => {
+    for (;;) {
+      const eight = digits(rng, 8);
+      const d = toDigits(eight)!;
+      let r = weightedModBy(d, (i) => i + 1, 11)!;
+      if (r === 10) {
+        r = weightedModBy(d, (i) => i + 3, 11)!;
+        if (r === 10) r = 0;
+      }
+      return `${eight}${r}`;
+    }
+  },
+  CY: (rng) => {
+    const TRANSFORM = [1, 0, 5, 7, 9, 13, 15, 17, 19, 21];
+    const eight = digits(rng, 8);
+    let sum = 0;
+    for (let i = 0; i < 8; i++) {
+      const d = Number(eight[i]);
+      sum += i % 2 === 0 ? TRANSFORM[d]! : d;
+    }
+    return `${eight}${String.fromCharCode(65 + (sum % 26))}`;
+  },
+  CZ: (rng) => {
+    const seven = digits(rng, 7);
+    const r = weightedModBy(toDigits(seven)!, (i) => 8 - i, 11)!;
+    const c = r === 0 ? 1 : r === 1 ? 0 : 11 - r;
+    return `${seven}${c}`;
+  },
+  DE: (rng) => {
+    const eight = String(int(rng, 1, 9)) + digits(rng, 7);
+    return `${eight}${mod11_10CheckDigit(eight)!}`;
+  },
+  DK: (rng) => {
+    for (;;) {
+      const seven = String(int(rng, 1, 9)) + digits(rng, 6);
+      const partial = weightedSum(toDigits(seven)!, [2, 7, 6, 5, 4, 3, 2])!;
+      for (let d = 0; d <= 9; d++) {
+        if ((partial + d) % 11 === 0) return `${seven}${d}`;
+      }
+    }
+  },
+  EE: (rng) => {
+    const eight = digits(rng, 8);
+    const sum = cyclicWeightedMod(toDigits(eight)!, [3, 7, 1], 10)!;
+    return `${eight}${(10 - sum) % 10}`;
+  },
+  EL: (rng) => {
+    const eight = String(int(rng, 1, 9)) + digits(rng, 7);
+    const sum = weightedModBy(toDigits(eight)!, (i) => 2 ** (8 - i), 11)!;
+    return `${eight}${sum % 10}`;
+  },
+  ES: (rng) => {
+    const eight = digits(rng, 8);
+    return `${eight}${'TRWAGMYFPDXBNJZSQVHLCKE'[Number(eight) % 23]}`;
+  },
+  FI: (rng) => {
+    for (;;) {
+      const seven = digits(rng, 7);
+      const r = weightedMod(toDigits(seven)!, [7, 9, 10, 5, 8, 4, 2], 11)!;
+      if (r === 1) continue;
+      return `${seven}${r === 0 ? 0 : 11 - r}`;
+    }
+  },
+  FR: (rng) => {
+    const siren = String(int(rng, 1, 9)) + digits(rng, 7);
+    const full = `${siren}${luhnCheckDigit(siren)!}`;
+    const key = (12 + 3 * (Number(full) % 97)) % 97;
+    return `${String(key).padStart(2, '0')}${full}`;
+  },
+  HR: (rng) => {
+    const ten = digits(rng, 10);
+    return `${ten}${mod11_10CheckDigit(ten)!}`;
+  },
+  HU: (rng) => {
+    const seven = String(int(rng, 1, 9)) + digits(rng, 6);
+    const sum = weightedMod(toDigits(seven)!, [9, 7, 3, 1, 9, 7, 3], 10)!;
+    return `${seven}${(10 - sum) % 10}`;
+  },
+  IE: (rng) => {
+    const seven = digits(rng, 7);
+    const second = rng() < 0.4 ? pick(rng, ['A', 'H']) : undefined;
+    let sum = weightedSum(toDigits(seven)!, [8, 7, 6, 5, 4, 3, 2])!;
+    if (second !== undefined) sum += 9 * (second.charCodeAt(0) - 64);
+    return `${seven}${'WABCDEFGHIJKLMNOPQRSTUV'[sum % 23]}${second ?? ''}`;
+  },
+  IT: (rng) => {
+    const ten = String(int(rng, 1, 9)) + digits(rng, 6) + '0' + digits(rng, 2);
+    return `${ten}${luhnCheckDigit(ten)!}`;
+  },
+  LT: (rng) => {
+    for (;;) {
+      const eight = digits(rng, 8);
+      const d = toDigits(eight)!;
+      let r = weightedModBy(d, (i) => (i % 9) + 1, 11)!;
+      if (r === 10) {
+        r = weightedModBy(d, (i) => ((i + 2) % 9) + 1, 11)!;
+        if (r === 10) r = 0;
+      }
+      return `${eight}${r}`;
+    }
+  },
+  LU: (rng) => {
+    const six = digits(rng, 6);
+    return `${six}${String(Number(six) % 89).padStart(2, '0')}`;
+  },
+  LV: (rng) => {
+    for (;;) {
+      const ten = String(int(rng, 4, 9)) + digits(rng, 9);
+      const d = toDigits(ten)!;
+      let sum = 0;
+      const weights = [9, 1, 4, 8, 3, 10, 2, 5, 7, 6];
+      for (let i = 0; i < 10; i++) sum += d[i]! * weights[i]!;
+      const c = (((3 - sum) % 11) + 11) % 11;
+      if (c === 10) continue;
+      return `${ten}${c}`;
+    }
+  },
+  MT: (rng) => {
+    for (;;) {
+      const six = String(int(rng, 1, 9)) + digits(rng, 5);
+      const r = weightedMod(toDigits(six)!, [3, 4, 6, 7, 8, 9], 37)!;
+      const check = 37 - r === 0 ? 37 : 37 - r;
+      return `${six}${String(check).padStart(2, '0')}`;
+    }
+  },
+  NL: (rng) => {
+    for (;;) {
+      const eight = digits(rng, 8);
+      const r = weightedModBy(toDigits(eight)!, (i) => 9 - i, 11)!;
+      if (r === 10) continue;
+      return `${eight}${r}B${String(int(rng, 1, 99)).padStart(2, '0')}`;
+    }
+  },
+  PL: (rng) => {
+    for (;;) {
+      const nine = digits(rng, 9);
+      const r = weightedMod(toDigits(nine)!, [6, 5, 7, 2, 3, 4, 5, 6, 7], 11)!;
+      if (r === 10) continue;
+      return `${nine}${r}`;
+    }
+  },
+  PT: (rng) => {
+    const eight = String(int(rng, 1, 9)) + digits(rng, 7);
+    const r = weightedModBy(toDigits(eight)!, (i) => 9 - i, 11)!;
+    return `${eight}${r < 2 ? 0 : 11 - r}`;
+  },
+  RO: (rng) => {
+    const body = String(int(rng, 1, 9)) + digits(rng, int(rng, 1, 8));
+    const padded = body.padStart(9, '0');
+    const sum = weightedMod(toDigits(padded)!, [7, 5, 3, 2, 1, 7, 5, 3, 2], 11)!;
+    return `${body}${((sum * 10) % 11) % 10}`;
+  },
+  SE: (rng) => {
+    const nine = String(int(rng, 1, 9)) + digits(rng, 8);
+    return `${nine}${luhnCheckDigit(nine)!}01`;
+  },
+  SI: (rng) => {
+    for (;;) {
+      const seven = String(int(rng, 1, 9)) + digits(rng, 6);
+      const r = weightedModBy(toDigits(seven)!, (i) => 8 - i, 11)!;
+      const c = 11 - r;
+      if (c === 10) continue;
+      return `${seven}${c === 11 ? 0 : c}`;
+    }
+  },
+  SK: (rng) => {
+    for (;;) {
+      const body =
+        String(int(rng, 1, 9)) + String(int(rng, 0, 9)) + pick(rng, ['2', '3', '4', '7', '8', '9']) + digits(rng, 6);
+      const base = Number(`${body}0`);
+      for (let d = 0; d <= 9; d++) {
+        if ((base + d) % 11 === 0) return `${body}${d}`;
+      }
+    }
+  },
+};
+
+export const VAT_COUNTRIES: readonly string[] = Object.keys(SYNTHS);
+
+/** A checksum-valid VAT number for one member state (with prefix). */
+export function generateValidVatFor(country: string, seed: number): string {
+  const rng = mulberry32(seed);
+  return `${country}${SYNTHS[country]!(rng)}`;
+}
+
+/** A checksum-valid VAT number for a random member state. */
+export function generateValidEuVat(seed: number): string {
+  const rng = mulberry32(seed);
+  const country = pick(rng, VAT_COUNTRIES);
+  return `${country}${SYNTHS[country]!(rng)}`;
+}

package/src/index.ts

@@ -0,0 +1,186 @@
+/**
+ * @discretion/core — public API.
+ *
+ * M1 surface: shared types, script detection, Stage 0 normalization with an
+ * exact bidirectional offset map.
+ */
+export type * from './types.js';
+
+export { detectScripts, getCharScript, classifyCodePoint, scriptsCompatible } from './scripts.js';
+export type { CodePointClass } from './scripts.js';
+
+export { normalize } from './normalization.js';
+export { labelOf } from './entityLabel.js';
+export { familyOf } from './entityFamily.js';
+export type { EntityFamily } from './entityFamily.js';
+
+export {
+  composeMaps,
+  identityMap,
+  buildReverseMap,
+  mapNormalizedSpan,
+  MappedTextBuilder,
+} from './offsetMap.js';
+export type { StepChange, TransformStepResult } from './offsetMap.js';
+
+// The individual transforms are exported so they stay independently testable
+// and reusable; normalize() is the supported entry point.
+export { stripInvisibles } from './transforms/stripInvisibles.js';
+export { nfkcByGrapheme } from './transforms/nfkc.js';
+export { foldHomoglyphs } from './transforms/homoglyphFold.js';
+export { normalizeWhitespacePunct } from './transforms/whitespacePunct.js';
+export { foldDigits, asciiDigitFor } from './transforms/foldDigits.js';
+
+// ── Stage 1: validated identifier detection (M2) ──
+// Importing the package registers every bundled detector.
+import './detect/detectors/index.js';
+
+export {
+  registerDetector,
+  allDetectors,
+  getDetector,
+  detectorsForRegion,
+  detectorsForEntityType,
+  detectorCount,
+} from './detect/registry.js';
+export { runStage1, DetectionTimeoutError, DetectorError } from './detect/runner.js';
+export { CONFIDENCE, GLOBAL_REGION, invalid, valid } from './detect/types.js';
+export type {
+  Detector,
+  RegionCode,
+  ContextSignal,
+  ValidationContext,
+  ValidationResult,
+  ValidationSuccess,
+  ValidationFailure,
+  Stage1Candidate,
+} from './detect/types.js';
+export type { Stage1Options } from './detect/runner.js';
+
+// The checksum library is public API: M3's corpus generator and M4's
+// format-preserving surrogates both need to CREATE valid identifiers.
+export * as checksums from './checksums/index.js';
+
+// Seeded valid-value generators: consumed by the eval corpus builder (M3)
+// and by format-preserving surrogate synthesis (M4).
+export * as generate from './generate/index.js';
+
+// ── Stage 2: multilingual NER (M6) ──
+// Pure logic only. The Transformers.js-backed classifier is exported through
+// the './ner-transformers' entry point so that importing the core root never
+// loads the ONNX runtime.
+export { alignPieces } from './ner/align.js';
+export type { AlignedPiece } from './ner/align.js';
+export { decodeEntities } from './ner/merge.js';
+export { chunkText } from './ner/chunk.js';
+export type { Chunk } from './ner/chunk.js';
+export { NerEngine } from './ner/engine.js';
+export { ChunkCache } from './ner/chunkCache.js';
+export type { NerEngineOptions } from './ner/engine.js';
+export { runStage2 } from './ner/runStage2.js';
+export type {
+  NerEntityType,
+  NerRecognizer,
+  NerSpan,
+  Stage2Candidate,
+  TokenClassifier,
+  TokenPrediction,
+} from './ner/types.js';
+
+// ── Stage 3: context scoring (M7) ──
+export { analyzeContext } from './context/score.js';
+export type { ContextAnalysis, ContextOptions } from './context/score.js';
+export { buildStructureIndex } from './context/structure.js';
+export type { StructureIndex, StructuredSlot, StructureKind } from './context/structure.js';
+export { buildTriggerIndex, foldForMatch } from './context/triggers.js';
+export type { LanguageTriggers, TriggerIndex, TriggerMatch } from './context/triggers.js';
+export { profileDocument } from './context/documentProfile.js';
+export type { DomainLexicon } from './context/documentProfile.js';
+export { NEGATIVE_RULES, ruleApplies } from './context/negativeRules.js';
+export type {
+  ContextContribution,
+  ContextScoredCandidate,
+  DocumentDomain,
+  DocumentFormat,
+  DocumentProfile,
+  NegativeRule,
+  PipelineCandidate,
+  RuleContext,
+} from './context/types.js';
+
+// ── Stage 2b: gazetteers (M7) ──
+export { lookupGazetteer, gazetteerSizes, isGazetteerType } from './gazetteer/index.js';
+export type { GazetteerHit, GazetteerType } from './gazetteer/index.js';
+
+// ── Stage 4: overlap resolution (M8) ──
+export { resolveOverlaps, coverageHoles } from './fuse/resolve.js';
+export { fitCalibration, calibrate, reliability } from './fuse/calibrate.js';
+export { PROFILES, decide, customProfile } from './fuse/profiles.js';
+export { explain, toDetectedEntity, explainOmission } from './fuse/explain.js';
+export type { FusionInput } from './fuse/explain.js';
+export type { ProfileName, SensitivityProfile, UserLists, ProfileDecision } from './fuse/profiles.js';
+export { computeExposure, exposureBand, EXPOSURE_LIMITATION } from './exposure/index.js';
+export type {
+  ExposureReport,
+  ExposureInput,
+  ExposureContribution,
+  CategoryBreakdown,
+} from './exposure/index.js';
+export type {
+  CalibrationBin,
+  CalibrationCurve,
+  CalibrationModel,
+  CalibrationSample,
+  ReliabilityPoint,
+} from './fuse/calibrate.js';
+export type { ScoredForResolution, ResolutionResult } from './fuse/resolve.js';
+
+// ── The composed pipeline (M7) ──
+// Stages 0–3 in one call. This is what consumers should use; the individual
+// stage functions remain exported for tooling that wants one stage.
+export { detect } from './pipeline.js';
+export type { DetectOptions, DetectionOutcome } from './pipeline.js';
+
+// ── Stage: masking (M4) ──
+export { Vault, normalizedKey } from './mask/vault.js';
+export type { EgressAuditor } from './mask/vault.js';
+export { chooseSurrogate } from './mask/surrogates.js';
+export type { SurrogateRequest } from './mask/surrogates.js';
+export { PERSON_POOLS, ORG_POOL, LOCATION_POOL } from './mask/surrogatePools.js';
+export { mask, maskOriginal, resolveForMasking } from './mask/masker.js';
+export type { MaskOptions, MaskResult, MaskedEntity } from './mask/masker.js';
+export { Restorer, restore } from './mask/restorer.js';
+export type { RestorerOptions } from './mask/restorer.js';
+export { guardEgress } from './mask/egressGuard.js';
+export type { EgressLeak, EgressVerdict } from './mask/egressGuard.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// M12: the supported entry point, and the surface finalised for publication
+// ─────────────────────────────────────────────────────────────────────────────
+
+// `protect()` composes Stages 0-4 in the one order that is correct, so that a
+// consumer does not have to reproduce the extension's ninety lines of
+// orchestration to get a masked string. Everything above stays exported: this
+// is the supported path, not the only one.
+export { protect } from './protect.js';
+export type { ProtectOptions, ProtectResult, ProtectedEntity } from './protect.js';
+
+// A runtime enumeration of `EntityType`, which a TypeScript union does not
+// have. `detectableEntityTypes()` is DERIVED from the detector registry rather
+// than declared - see the header of entityTypes.ts for the M11 bug that makes
+// the distinction worth the indirection.
+export { ALL_ENTITY_TYPES, NER_ENTITY_TYPES, detectableEntityTypes } from './entityTypes.js';
+
+// The shipped calibration model, converted with a key check instead of the
+// `as unknown as CalibrationModel` cast every consumer used before M12.
+export { toCalibrationModel } from './fuse/defaultCalibration.js';
+export type { CalibrationConversion, GeneratedCalibrationModel } from './fuse/defaultCalibration.js';
+
+// ── leaks closed at M12 ──
+// Both of these were named in a public signature but not exported, so a
+// consumer could receive one and had no way to name its type.
+//   SeverityCategory  reached through ExposureReport, which computeExposure()
+//                     returns; it originates in @discretion/data.
+//   PersonPool        the element type of the exported PERSON_POOLS.
+export type { SeverityCategory } from '@discretion/data';
+export type { PersonPool } from './mask/surrogatePools.js';

package/src/mask/egressGuard.ts

@@ -0,0 +1,88 @@
+/**
+ * egressGuard.ts — the assertion that makes the guarantee real.
+ *
+ * Before any send is permitted, the outgoing payload is scanned for every
+ * plaintext original currently in the vault. Any hit blocks the send and
+ * reports WHICH entity leaked — by vault id and type only; the report never
+ * carries the plaintext itself, because reports get logged and displayed
+ * and must not become a second leak.
+ *
+ * Comparison is deliberately paranoid, in the fail-closed direction:
+ *
+ *  1. NORMALIZED + CASE-FOLDED substring search: payload and originals both
+ *     go through Stage 0 normalization (stripping zero-width obfuscation,
+ *     folding homoglyphs, canonicalizing punctuation variants) and are
+ *     case-folded. Catches raw leaks, case variants, ZWSP-stuffed and
+ *     confusable-substituted forms.
+ *
+ *  2. SEPARATOR-INSENSITIVE canonical search: for entries whose canonical
+ *     (the detector's separator-stripped form) differs from the original,
+ *     the payload is additionally searched with spacing/hyphen/dot
+ *     separators removed — so "4111-1111-1111-1111" is caught when the
+ *     vault holds "4111 1111 1111 1111".
+ *
+ * No word-boundary requirement: a plaintext original appearing INSIDE a
+ * longer token is still a leak. Over-blocking is a usability bug;
+ * under-blocking is the critical failure. SPEC.md: fail closed.
+ */
+
+import { normalize } from '../normalization.js';
+import type { EntityType } from '../types.js';
+import type { EgressAuditor } from './vault.js';
+
+export interface EgressLeak {
+  /** Vault entry id — never the value. */
+  readonly entryId: string;
+  readonly type: EntityType;
+  /** Which comparison caught it (for diagnostics/UI copy). */
+  readonly via: 'normalized' | 'separator-insensitive';
+}
+
+export interface EgressVerdict {
+  /** True = safe to send. False = BLOCK; SPEC.md forbids fail-open. */
+  readonly ok: boolean;
+  readonly leaks: readonly EgressLeak[];
+}
+
+/** Case-folded Stage 0 normalization — the guard's comparison space.
+ *  Exported so the MASKER's collision check runs in the same space: a
+ *  surrogate that would trip this guard must never be chosen at all. */
+export function comparisonForm(text: string): string {
+  return normalize(text).normalizedText.toLowerCase();
+}
+
+/** Additionally remove the separators identifiers are grouped with. */
+export function separatorFree(text: string): string {
+  return text.replace(/[ \t.\-/]/g, '');
+}
+
+/**
+ * Scan `payload` for every plaintext original in the vault. The auditor is
+ * the vault's single plaintext door (`vault.createEgressAuditor()`); this
+ * function is its intended sole consumer.
+ */
+export function guardEgress(payload: string, auditor: EgressAuditor): EgressVerdict {
+  const leaks: EgressLeak[] = [];
+  if (payload.length === 0) return { ok: true, leaks };
+
+  const haystack = comparisonForm(payload);
+  const haystackNoSep = separatorFree(haystack);
+
+  for (const entry of auditor.auditEntries()) {
+    const needle = comparisonForm(entry.original);
+    if (needle.length > 0 && haystack.includes(needle)) {
+      leaks.push({ entryId: entry.id, type: entry.type, via: 'normalized' });
+      continue;
+    }
+    const canonicalNeedle = separatorFree(comparisonForm(entry.canonical));
+    if (canonicalNeedle.length >= 6 && haystackNoSep.includes(canonicalNeedle)) {
+      // The ≥6 floor keeps the separator-stripped pass from degenerating on
+      // very short canonicals, where stripped-substring hits stop meaning
+      // anything (any 4-digit run would "leak"). The normalized pass above
+      // still covers those entries in full.
+      leaks.push({ entryId: entry.id, type: entry.type, via: 'separator-insensitive' });
+    }
+  }
+
+  return { ok: leaks.length === 0, leaks };
+}