@discretion/core 0.1.0

package/src/offsetMap.ts

@@ -0,0 +1,271 @@
+/**
+ * Offset-map machinery for Stage 0 normalization.
+ *
+ * WHY THIS EXISTS
+ * ───────────────
+ * Detection runs on normalized text; substitution edits the ORIGINAL text.
+ * Every transform therefore produces, alongside its output text, an exact map
+ * back to its input. The final map for a whole pipeline is the composition of
+ * each stage's map — composing small verified maps is far easier to get right
+ * than building one map through four simultaneous transforms.
+ *
+ * MAP REPRESENTATION
+ * ──────────────────
+ * A map for a transform `input → output` is an Int32Array of length
+ * output.length + 1 (all indices are UTF-16 code units):
+ *
+ *   map[i]             = input index where the cluster that produced output
+ *                        index i begins
+ *   map[output.length] = input.length                            (sentinel)
+ *
+ * The sentinel entry is the classic off-by-one: without it, the end of a span
+ * covering the last character could not be mapped. With it, an output span
+ * [s, e) maps to the input span [map[s], map[e]).
+ *
+ * DELETION ATTRIBUTION (a deliberate choice — read before editing)
+ * ───────────────────────────────────────────────────────────────
+ * Deleted input (stripped invisibles) produces no output index, so it cannot
+ * appear in the map directly. Each deleted run is attributed to the cluster
+ * that FOLLOWS it; a deleted run at the very end of the input falls under the
+ * sentinel. Consequences:
+ *   • map[0] === 0 always holds when the output is non-empty, even if the
+ *     input began with deleted characters — a stated invariant of the format.
+ *   • A mapped span silently includes any deleted (invisible) characters
+ *     immediately before the characters it covers, and — via the sentinel —
+ *     any deleted characters at the end of the input. Substituting such a
+ *     span removes those invisibles along with it, which is exactly what a
+ *     masking pipeline wants: they are noise we would strip anyway.
+ *   • Values are STRICTLY increasing across real cluster boundaries; equal
+ *     adjacent values occur only inside a single cluster's multi-unit output
+ *     (an expansion). mapNormalizedSpan() relies on this.
+ *
+ * EDGE CASE — everything deleted: when the output is empty the map is the
+ * single sentinel entry [inputLength], so map[0] === inputLength, not 0.
+ * That is the one place the "map[0] === 0" invariant cannot hold; every
+ * consumer and test conditions that invariant on a non-empty output.
+ */
+
+import type { TransformKind } from './types.js';
+
+/** The identity map for a text of the given length: [0, 1, …, length]. */
+export function identityMap(length: number): Int32Array {
+  const map = new Int32Array(length + 1);
+  for (let i = 0; i <= length; i++) map[i] = i;
+  return map;
+}
+
+/**
+ * Compose two offset maps.
+ *
+ *   outer: maps indices of text B to indices of text A  (length |B| + 1)
+ *   inner: maps indices of text C to indices of text B  (length |C| + 1)
+ *   result: maps indices of text C to indices of text A (length |C| + 1)
+ *
+ * Because inner[|C|] = |B| and outer[|B|] = |A|, the sentinel composes for
+ * free, and the composition of monotone maps is monotone — both facts are
+ * covered by tests.
+ */
+export function composeMaps(outer: Int32Array, inner: Int32Array): Int32Array {
+  const result = new Int32Array(inner.length);
+  const outerMax = outer.length - 1;
+  for (let i = 0; i < inner.length; i++) {
+    const via = inner[i]!;
+    if (via < 0 || via > outerMax) {
+      throw new Error(
+        `composeMaps: inner map value ${via} at index ${i} is outside the outer map's domain [0, ${outerMax}]`,
+      );
+    }
+    result[i] = outer[via]!;
+  }
+  return result;
+}
+
+/**
+ * Build the reverse map (original index → normalized index) from a forward
+ * map.
+ *
+ *   reverseMap[j]              = normalized index of the start of the cluster
+ *                                whose original extent contains j; for a
+ *                                deleted character this is the normalized
+ *                                position where it was removed
+ *   reverseMap[originalLength] = normalizedLength                (sentinel)
+ *
+ * "Extent" is the half-open range [offsetMap[i], nextDistinctValue), i.e. it
+ * includes any deleted characters attributed to the cluster. The walk below
+ * precomputes each cluster's extent end (`ends`), then assigns every original
+ * index the FIRST normalized index whose extent reaches past it — which lands
+ * on the first unit of the covering cluster, also for expansions where several
+ * normalized units share one original cluster.
+ */
+export function buildReverseMap(offsetMap: Int32Array, originalLength: number): Int32Array {
+  const normalizedLength = offsetMap.length - 1;
+  const reverse = new Int32Array(originalLength + 1);
+
+  // ends[i] = original index one past the extent of the cluster covering
+  // normalized index i (= the next distinct map value, or originalLength).
+  const ends = new Int32Array(normalizedLength);
+  let nextDistinct = originalLength;
+  for (let i = normalizedLength - 1; i >= 0; i--) {
+    ends[i] = nextDistinct;
+    if (i === 0 || offsetMap[i - 1]! !== offsetMap[i]!) {
+      nextDistinct = offsetMap[i]!;
+    }
+  }
+
+  let i = 0;
+  for (let j = 0; j < originalLength; j++) {
+    while (i < normalizedLength && ends[i]! <= j) i++;
+    // If every cluster ends at or before j (possible only when the trailing
+    // input was deleted and absorbed by the sentinel), i === normalizedLength,
+    // which is exactly "the position where it was removed".
+    reverse[j] = i;
+  }
+  reverse[originalLength] = normalizedLength;
+  return reverse;
+}
+
+/**
+ * Map a normalized span [start, end) to the original span it covers.
+ *
+ * For spans whose endpooints sit on cluster boundaries this is exactly
+ * [offsetMap[start], offsetMap[end]). When an endpoint lands INSIDE an
+ * expansion (one original cluster → several normalized units — e.g. matching
+ * only the "f" of the "fi" produced by the ligature U+FB01), the span is
+ * widened to cover the WHOLE original cluster: you cannot substitute half a
+ * ligature. Widening is the only sound choice for masking — the alternative,
+ * an empty or truncated original span, would silently leave sensitive
+ * characters behind.
+ *
+ * NOTE: two non-overlapping normalized spans that split the same expansion
+ * both widen to the same original cluster, so mapped spans can overlap in
+ * that one case. Substitution must merge overlapping original spans before
+ * splicing (covered by the substitution-safety property test).
+ */
+export function mapNormalizedSpan(
+  offsetMap: Int32Array,
+  start: number,
+  end: number,
+): { start: number; end: number } {
+  const normalizedLength = offsetMap.length - 1;
+  if (!(start >= 0 && start <= end && end <= normalizedLength)) {
+    throw new Error(
+      `mapNormalizedSpan: invalid span [${start}, ${end}) for normalized length ${normalizedLength}`,
+    );
+  }
+  if (start === end) {
+    const at = offsetMap[start]!;
+    return { start: at, end: at };
+  }
+  const origStart = offsetMap[start]!;
+  // Find the original end of the cluster containing normalized index end-1:
+  // advance past normalized units that still share that cluster's start value.
+  // (Equal adjacent values occur only within one cluster — see header.)
+  const lastClusterStart = offsetMap[end - 1]!;
+  let k = end;
+  while (k < normalizedLength && offsetMap[k]! === lastClusterStart) k++;
+  return { start: origStart, end: offsetMap[k]! };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Transform plumbing shared by the individual transforms
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * One change made by a single transform, in coordinates of THAT TRANSFORM'S
+ * INPUT. normalize() re-maps these to original-text coordinates before
+ * exposing them as TransformationRecord.
+ */
+export interface StepChange {
+  kind: TransformKind;
+  /** Range in the transform's input text. */
+  start: number;
+  end: number;
+  /** input.slice(start, end) — what was there. */
+  before: string;
+  /** What the transform emitted instead ('' for deletions). */
+  after: string;
+}
+
+/** What every transform returns; null means "nothing to do" (identity). */
+export interface TransformStepResult {
+  text: string;
+  /** output index → input index, with sentinel (length text.length + 1). */
+  map: Int32Array;
+  changes: StepChange[];
+}
+
+/**
+ * Streaming builder used by every transform to produce output text and its
+ * offset map in one left-to-right pass. It enforces the deletion-attribution
+ * convention documented in the file header, so transforms cannot get it wrong
+ * individually.
+ *
+ * Usage contract: calls must cover the input strictly left to right —
+ * copyVerbatim / replaceRange / deleteRange with monotonically increasing,
+ * non-overlapping [start, end) ranges, then finish(inputLength) exactly once.
+ */
+export class MappedTextBuilder {
+  private readonly parts: string[] = [];
+  private readonly map: number[] = [];
+  /** Start of the input region not yet attributed to any output. */
+  private claimFrom = 0;
+  /** How far the input has been consumed (for misuse detection). */
+  private cursor = 0;
+
+  private advance(start: number, end: number): void {
+    if (start !== this.cursor || end < start) {
+      throw new Error(
+        `MappedTextBuilder: ranges must be contiguous and left-to-right ` +
+          `(cursor ${this.cursor}, got [${start}, ${end}))`,
+      );
+    }
+    this.cursor = end;
+  }
+
+  /**
+   * Copy input.slice(start, end) through unchanged. Mapping is fine-grained
+   * (each output unit → its own input position), except that the first unit
+   * claims any pending deleted region before it.
+   */
+  copyVerbatim(input: string, start: number, end: number): void {
+    this.advance(start, end);
+    if (start === end) return;
+    this.parts.push(input.slice(start, end));
+    this.map.push(this.claimFrom);
+    for (let k = start + 1; k < end; k++) this.map.push(k);
+    this.claimFrom = end;
+  }
+
+  /**
+   * Replace input.slice(start, end) with `replacement`. Every output unit
+   * maps to the start of the input cluster (including any pending deleted
+   * region before it) — a span covering part of the replacement covers the
+   * whole original cluster.
+   */
+  replaceRange(replacement: string, start: number, end: number): void {
+    this.advance(start, end);
+    const base = this.claimFrom;
+    for (let i = 0; i < replacement.length; i++) this.map.push(base);
+    if (replacement.length > 0) this.parts.push(replacement);
+    this.claimFrom = end;
+  }
+
+  /**
+   * Delete input.slice(start, end): emits nothing. The region stays
+   * unclaimed and will be attributed to the next output (or the sentinel).
+   */
+  deleteRange(start: number, end: number): void {
+    this.advance(start, end);
+  }
+
+  /** Finish the map with its sentinel entry and assemble the output text. */
+  finish(inputLength: number): { text: string; map: Int32Array } {
+    if (this.cursor !== inputLength) {
+      throw new Error(
+        `MappedTextBuilder: input not fully consumed (cursor ${this.cursor} of ${inputLength})`,
+      );
+    }
+    this.map.push(inputLength);
+    return { text: this.parts.join(''), map: Int32Array.from(this.map) };
+  }
+}

package/src/pipeline.ts

@@ -0,0 +1,96 @@
+/**
+ * The composed detection pipeline.
+ *
+ * Stages 0–3 in one supported entry point. Before this existed a caller had
+ * to run `runStage1`, then `runStage2`, then score the result — and Stage 3's
+ * evidence had to be threaded into Stage 1's validators by hand. That is not a
+ * detail a consumer should be trusted with: a caller who forgets the context
+ * hook silently gets a weaker pipeline, and one who forgets Stage 3 gets every
+ * false positive Stage 3 exists to remove.
+ *
+ * SPEC.md's non-negotiable applies to the whole composition: any detection
+ * error, timeout, or adapter failure must BLOCK, never degrade. Nothing here
+ * catches an error from a stage — a thrown `DetectionTimeoutError` or
+ * `DetectorError` propagates to the caller, which is what fail-closed means.
+ *
+ * The lower-level stage functions remain exported for tests and tooling that
+ * genuinely want one stage; `detect` is what consumers should use.
+ */
+
+import { DOMAIN_LEXICONS, TRIGGER_LEXICONS } from '@discretion/data';
+
+import type { NormalizationResult } from './types.js';
+import { runStage1, type Stage1Options } from './detect/runner.js';
+import { runStage2 } from './ner/runStage2.js';
+import type { NerRecognizer } from './ner/types.js';
+import { analyzeContext, type ContextOptions } from './context/score.js';
+import type { ContextScoredCandidate, DocumentProfile, PipelineCandidate } from './context/types.js';
+
+export interface DetectOptions {
+  /** Stage 1 configuration. The context hook is supplied automatically. */
+  readonly stage1?: Omit<Stage1Options, 'contextFor'>;
+  /**
+   * Stage 2 engine. Omit to run without named-entity recognition — the
+   * playground and the Stage-1 eval baseline both do.
+   */
+  readonly ner?: NerRecognizer;
+  /** Stage 3 configuration. Defaults to the bundled trigger lexicons. */
+  readonly context?: ContextOptions;
+}
+
+export interface DetectionOutcome {
+  /** Candidates Stage 3 kept, with their adjusted confidence and reasons. */
+  readonly emitted: readonly ContextScoredCandidate[];
+  /**
+   * Candidates Stage 3 suppressed, retained for eval and explanation.
+   *
+   * Kept rather than discarded because a suppression is a decision the
+   * pipeline must be able to justify: the review UI explains why something
+   * was NOT reported, and the eval measures whether a suppression rule is
+   * removing errors or removing detections.
+   */
+  readonly suppressed: readonly ContextScoredCandidate[];
+  readonly profile: DocumentProfile;
+}
+
+/**
+ * Run Stages 0–3 over an already-normalized document.
+ *
+ * Takes the `NormalizationResult` rather than a string for the same reason
+ * `runStage1` does: without the offset map a candidate cannot be mapped back
+ * to the original text, and accepting a bare string would let a caller lose
+ * it silently.
+ */
+export async function detect(
+  normalization: NormalizationResult,
+  options: DetectOptions = {},
+): Promise<DetectionOutcome> {
+  const analysis = analyzeContext(normalization.normalizedText, {
+    triggerLexicons: TRIGGER_LEXICONS,
+    domainLexicon: DOMAIN_LEXICONS,
+    ...options.context,
+  });
+
+  // Stage 1 validators receive Stage 3 evidence inline, which is what lets a
+  // detector that SPEC.md marks "requires context" see the signal at the
+  // moment it decides.
+  const stage1 = runStage1(normalization, {
+    ...options.stage1,
+    contextFor: (start, end) => analysis.signalAt(start, end),
+  });
+
+  const stage2 = options.ner === undefined ? [] : await runStage2(normalization, options.ner);
+
+  const candidates: PipelineCandidate[] = [...stage1, ...stage2];
+  const scored = analysis.score(candidates);
+
+  // NO STAGE 2C. SPEC.md asks for a verification pass over an ambiguous
+  // confidence band, and requires it be removed if the eval shows it does not
+  // improve results. It was built, measured, and removed — see ARCHITECTURE.md
+  // D20 and the BENCHMARKS.md M7 section for the numbers.
+  return {
+    emitted: scored.filter((c) => !c.suppressed),
+    suppressed: scored.filter((c) => c.suppressed),
+    profile: analysis.profile,
+  };
+}

package/src/protect.ts

@@ -0,0 +1,284 @@
+/**
+ * protect.ts — the one-call entry point: text in, masked text and a report out.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * WHY THIS EXISTS (M12)
+ *
+ * Every stage of the pipeline was already exported, and that is not the same
+ * as being usable. Getting from a string to "here is the masked text and what
+ * was found" meant composing eight core calls in a specific order, holding an
+ * identity map between two of them, and importing the fitted calibration model
+ * from a SECOND package through an unchecked cast. The extension's
+ * `analyzeText` does exactly that in about ninety lines.
+ *
+ * SPEC's M12 acceptance test is that "a developer who has never seen this repo
+ * can npm install the package and run detection and masking from the docs
+ * alone". Documenting those ninety lines would satisfy the letter of it and
+ * miss the point: the order matters for correctness, not just for convenience,
+ * and a consumer who gets it wrong gets quietly worse results rather than an
+ * error. Two of the orderings below were bugs found in earlier milestones.
+ *
+ * The individual stages remain exported. This is the supported path, not the
+ * only one.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * WHAT `mask()` IS, AND WHY IT IS NOT THIS
+ *
+ * `mask()` in `mask/masker.ts` also takes a string and returns masked text,
+ * and it looks like this function's smaller sibling. It runs STAGE 1 ONLY —
+ * no context scoring, no calibration, no profile decision, no NER. It exists
+ * for tests and for the playground's Stage-1 baseline. A consumer who reached
+ * for it expecting the full engine would get uncalibrated confidences and none
+ * of Stage 3's false-positive suppression, with nothing to indicate the
+ * difference. `stagesRun` on this function's result is what makes the
+ * distinction legible.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * FAIL-CLOSED IS THE CALLER'S JOB, AND THIS FUNCTION PRESERVES IT
+ *
+ * Nothing here catches an error from a stage. `detect` propagates
+ * `DetectionTimeoutError` and `DetectorError` deliberately, and so does this.
+ * A caller that wrapped it in a try/catch and treated the failure as "nothing
+ * found" would have built the exact failure SPEC.md calls a critical bug, so
+ * the failure is left where it cannot be mistaken for a result.
+ */
+
+import { CALIBRATION_MODEL } from '@discretion/data';
+
+import { computeExposure } from './exposure/index.js';
+import { calibrate, type CalibrationModel } from './fuse/calibrate.js';
+import { toCalibrationModel } from './fuse/defaultCalibration.js';
+import { toDetectedEntity } from './fuse/explain.js';
+import { PROFILES, decide, type ProfileName, type SensitivityProfile, type UserLists } from './fuse/profiles.js';
+import { resolveOverlaps } from './fuse/resolve.js';
+import { maskOriginal } from './mask/masker.js';
+import { Vault } from './mask/vault.js';
+import { normalize } from './normalization.js';
+import { detect } from './pipeline.js';
+import type { ContextScoredCandidate, PipelineCandidate } from './context/types.js';
+import type { ExposureReport } from './exposure/index.js';
+import type { NerRecognizer } from './ner/types.js';
+import type {
+  DetectionStage,
+  EntityExplanation,
+  EntityType,
+  SubstitutionMode,
+} from './types.js';
+
+/** The shipped model, converted once and checked rather than cast. */
+const DEFAULT_CALIBRATION: CalibrationModel = toCalibrationModel(CALIBRATION_MODEL).model;
+
+export interface ProtectOptions {
+  /**
+   * Which findings are worth reporting. A `ProfileName` selects one of the
+   * three SPEC profiles; a `SensitivityProfile` supplies your own.
+   * Default: `'balanced'`.
+   */
+  readonly profile?: ProfileName | SensitivityProfile;
+  /** Values to always report (`deny`) or never report (`allow`). */
+  readonly lists?: UserLists;
+  /**
+   * The region used for identifiers that are ambiguous without one.
+   *
+   * Not a tie-breaker: a phone number written in national form cannot be
+   * validated at all without a region, so leaving this unset does not lower
+   * its confidence — the detector reports nothing.
+   */
+  readonly defaultRegion?: string;
+  /** Per-type opt-out, applied before a surrogate is minted. */
+  readonly typeAllowed?: (type: EntityType) => boolean;
+  /** `'surrogate'` (realistic stand-ins, default) or `'token'` (`[EMAIL_1]`). */
+  readonly mode?: SubstitutionMode;
+  /** Varies surrogate selection. Fixed input plus fixed seed is reproducible. */
+  readonly seed?: number;
+  /**
+   * The vault that remembers which surrogate stood in for which value.
+   *
+   * REQUIRED FOR RESTORATION, and required for consistency across calls: pass
+   * the same vault to every `protect()` in a conversation and a value seen
+   * twice gets the same surrogate. Omit it and a fresh vault is created for
+   * this call alone, which is correct for one-shot masking and wrong for
+   * anything that restores a reply later.
+   */
+  readonly vault?: Vault;
+  /**
+   * Stage 2. Omit to run Stages 0, 1, 3 and 4 only.
+   *
+   * Not defaulted to a model on purpose: the recogniser pulls in the ONNX
+   * runtime, which this package does not depend on. See the "Stage 2" section
+   * of the usage guide.
+   */
+  readonly ner?: NerRecognizer;
+  /** Overrides the shipped calibration model. For eval work, not for use. */
+  readonly calibration?: CalibrationModel;
+}
+
+/** One finding, with everything needed to show it and nothing that leaks it. */
+export interface ProtectedEntity {
+  /**
+   * The vault id, stable across re-analyses of the same value.
+   *
+   * Derived from the value rather than from position, so a caller tracking a
+   * user's per-item decisions keeps them when text is edited earlier in the
+   * document. An index-based id would silently move the decision.
+   */
+  readonly id: string;
+  readonly type: EntityType;
+  /** Calibrated, comparable across types. Never the raw detector score. */
+  readonly confidence: number;
+  /** Which evidence fired. Structured, so callers can render it in any language. */
+  readonly explanation: EntityExplanation;
+  /** What replaced it in `maskedText`. */
+  readonly surrogate: string;
+  /** Offsets into the ORIGINAL text, not the normalized text. */
+  readonly originalStart: number;
+  readonly originalEnd: number;
+}
+
+export interface ProtectResult {
+  /** The input with every reported value replaced. Safe to send. */
+  readonly maskedText: string;
+  readonly entities: readonly ProtectedEntity[];
+  /** How exposed the document was, before masking. */
+  readonly exposure: ExposureReport;
+  /**
+   * Which stages actually ran.
+   *
+   * DERIVED from the options, never declared, so "Stage 2 ran" is a claim the
+   * code supports rather than a comment. Absence of `'stage2-ner'` is how a
+   * caller knows names were not looked for.
+   */
+  readonly stagesRun: readonly DetectionStage[];
+  /**
+   * The vault holding the originals. Pass it to `restore()` to reverse this.
+   *
+   * The same instance passed in `options.vault`, or the one created for this
+   * call. It holds plaintext originals in memory: SPEC.md forbids persisting
+   * it, and the extension clears it per tab session.
+   */
+  readonly vault: Vault;
+}
+
+function resolveProfile(profile: ProtectOptions['profile']): SensitivityProfile {
+  if (profile === undefined) return PROFILES.balanced;
+  if (typeof profile !== 'string') return profile;
+  if (profile === 'custom') {
+    throw new Error(
+      "protect: profile 'custom' names a shape, not a policy - pass a SensitivityProfile",
+    );
+  }
+  return PROFILES[profile];
+}
+
+/**
+ * Detect sensitive values in `text` and replace them with stand-ins.
+ *
+ * Throws on any stage failure rather than returning an empty result. See the
+ * fail-closed note in this file's header.
+ */
+export async function protect(text: string, options: ProtectOptions = {}): Promise<ProtectResult> {
+  const profile = resolveProfile(options.profile);
+  const calibration = options.calibration ?? DEFAULT_CALIBRATION;
+  const vault = options.vault ?? new Vault();
+
+  const normalization = normalize(text);
+  const outcome = await detect(normalization, {
+    ...(options.ner === undefined ? {} : { ner: options.ner }),
+    ...(options.defaultRegion === undefined
+      ? {}
+      : { stage1: { defaultRegion: options.defaultRegion } }),
+  });
+
+  // Resolve overlaps BEFORE calibrating or scoring exposure. An unresolved set
+  // double-counts every overlap, so one credential matched by three detectors
+  // would appear three times and inflate the exposure score threefold.
+  const resolution = resolveOverlaps(
+    outcome.emitted
+      .filter((scored) => scored.candidate.sensitive)
+      .map((scored) => ({ candidate: scored.candidate, confidence: scored.contextConfidence })),
+  );
+
+  // Keyed by object identity: `resolveOverlaps` returns the same candidate
+  // objects it was given, and the scored record carries the Stage 3
+  // contributions the explanation needs.
+  const scoredByCandidate = new Map<PipelineCandidate, ContextScoredCandidate>();
+  for (const scored of outcome.emitted) scoredByCandidate.set(scored.candidate, scored);
+
+  const reported: { scored: ContextScoredCandidate; confidence: number }[] = [];
+  for (const item of resolution.emitted) {
+    const scored = scoredByCandidate.get(item.candidate);
+    if (scored === undefined) continue;
+    const confidence = calibrate(calibration, item.candidate.type, item.confidence);
+    const decision = decide(
+      { type: item.candidate.type, text: item.candidate.text, calibratedConfidence: confidence },
+      profile,
+      options.lists ?? {},
+    );
+    if (!decision.report) continue;
+    if (options.typeAllowed?.(item.candidate.type) === false) continue;
+    reported.push({ scored, confidence });
+  }
+
+  // Surrogates come from the masker rather than from `chooseSurrogate`
+  // directly, because the masker enforces the properties a surrogate must
+  // have before it is shown: consistency through the vault, and the collision
+  // check that stops a surrogate from containing the very value it replaces.
+  // Computing them any other way shows the user one string and substitutes
+  // another.
+  const masked = maskOriginal(
+    text,
+    reported.map((entry) => entry.scored.candidate),
+    vault,
+    {
+      ...(options.mode === undefined ? {} : { mode: options.mode }),
+      ...(options.seed === undefined ? {} : { seed: options.seed }),
+    },
+  );
+
+  const surrogateAt = new Map<number, { replacement: string; vaultId: string }>();
+  for (const entity of masked.entities) {
+    surrogateAt.set(entity.originalStart, {
+      replacement: entity.replacement,
+      vaultId: entity.vaultId,
+    });
+  }
+
+  const entities: ProtectedEntity[] = [];
+  for (const { scored, confidence } of reported) {
+    const candidate = scored.candidate;
+    const surrogate = surrogateAt.get(candidate.originalStart);
+    if (surrogate === undefined) continue;
+    entities.push({
+      id: surrogate.vaultId,
+      type: candidate.type,
+      confidence,
+      explanation: toDetectedEntity({ scored, calibratedConfidence: confidence }).explanation,
+      surrogate: surrogate.replacement,
+      originalStart: candidate.originalStart,
+      originalEnd: candidate.originalEnd,
+    });
+  }
+
+  // Not a warning. A reported detection with no surrogate is one the caller
+  // cannot show and cannot let the user revert, while the masker substitutes
+  // it anyway.
+  if (entities.length !== reported.length) {
+    throw new Error(
+      `protect: masking produced ${String(entities.length)} surrogates for ${String(reported.length)} reported detections`,
+    );
+  }
+
+  const stagesRun: DetectionStage[] = ['stage1-validated-identifier'];
+  if (options.ner !== undefined) stagesRun.push('stage2-ner');
+  stagesRun.push('stage3-context', 'stage4-fusion');
+
+  return {
+    maskedText: masked.maskedText,
+    entities,
+    exposure: computeExposure(
+      entities.map((entity) => ({ type: entity.type, calibratedConfidence: entity.confidence })),
+    ),
+    stagesRun,
+    vault,
+  };
+}