@discretion/core 0.1.0

package/src/transforms/stripInvisibles.ts

@@ -0,0 +1,158 @@
+/**
+ * Transform 1: STRIP INVISIBLES.
+ *
+ * Removes zero-width and bidi control characters:
+ *   U+200B–U+200F  (ZWSP, ZWNJ, ZWJ, LRM, RLM)
+ *   U+202A–U+202E  (bidi embedding/override controls)
+ *   U+2060–U+2064  (word joiner, invisible operators)
+ *   U+FEFF         (BOM / zero-width no-break space)
+ *   U+00AD         (soft hyphen)
+ *
+ * These are pure noise for detection and are the classic obfuscation vector
+ * (a ZWSP dropped into the middle of "john@example.com"), so they go first —
+ * they interfere with every transform downstream.
+ *
+ * TWO CHARACTERS IN THE SET ARE SOMETIMES STRUCTURAL, NOT NOISE:
+ *
+ * THE EMOJI EXCEPTION — ZWJ (U+200D) inside an emoji sequence joins the
+ * sequence together; stripping it would corrupt 👨‍👩‍👧 into 👨👩👧. Per UAX #29,
+ * ZWJ and ZWNJ are the only characters in the strip set that can sit INSIDE
+ * a grapheme cluster (all the others have Grapheme_Cluster_Break=Control and
+ * form their own clusters), so the rule is: leave any cluster containing an
+ * Extended_Pictographic code point completely untouched.
+ *
+ * THE JOINING-SCRIPT EXCEPTION — ZWNJ (U+200C) is linguistically MEANINGFUL
+ * in scripts with cursive joining or conjunct formation: in Persian/Urdu and
+ * other Arabic-script languages it controls letter shaping and word
+ * segmentation (می‌خواهم), and in Indic scripts it suppresses conjuncts
+ * (क्‌ष renders dead consonant + ssa instead of the kṣa ligature). Stripping
+ * it there CORRUPTS the text. Rule (mirroring the emoji reasoning): preserve
+ * ZWNJ when its nearest substantive neighbors on BOTH sides — skipping other
+ * invisibles and combining marks — belong to a ZWNJ-using script. Everywhere
+ * else (Latin ligature suppression, obfuscation, stray controls) it is noise
+ * and is stripped.
+ */
+import { MappedTextBuilder, type TransformStepResult, type StepChange } from '../offsetMap.js';
+import { graphemeSegmenter } from './graphemes.js';
+
+// The character class is assembled from code points rather than written as
+// literals so no invisible characters hide in this source file.
+const cc = (cp: number): string => String.fromCharCode(cp);
+const INVISIBLE = new RegExp(
+  `[${cc(0x00ad)}${cc(0x200b)}-${cc(0x200f)}${cc(0x202a)}-${cc(0x202e)}` +
+    `${cc(0x2060)}-${cc(0x2064)}${cc(0xfeff)}]`,
+);
+const EXTENDED_PICTOGRAPHIC = /\p{Extended_Pictographic}/u;
+
+/**
+ * Scripts in which ZWNJ carries meaning: the cursive-joining family (Arabic
+ * script as used by Persian, Urdu, Kurdish, …; Syriac; Mongolian) and the
+ * Brahmic/Indic family (conjunct and ligature control). Note these are
+ * Unicode Script properties, deliberately independent of the coarser
+ * ScriptName buckets used for dominance elsewhere.
+ */
+const ZWNJ_SCRIPT =
+  /[\p{Script=Arabic}\p{Script=Syriac}\p{Script=Mongolian}\p{Script=Devanagari}\p{Script=Bengali}\p{Script=Gurmukhi}\p{Script=Gujarati}\p{Script=Oriya}\p{Script=Tamil}\p{Script=Telugu}\p{Script=Kannada}\p{Script=Malayalam}\p{Script=Sinhala}\p{Script=Myanmar}\p{Script=Khmer}]/u;
+const COMBINING_MARK = /\p{M}/u;
+
+function isInvisible(cp: number): boolean {
+  return (
+    cp === 0x00ad ||
+    (cp >= 0x200b && cp <= 0x200f) ||
+    (cp >= 0x202a && cp <= 0x202e) ||
+    (cp >= 0x2060 && cp <= 0x2064) ||
+    cp === 0xfeff
+  );
+}
+
+/**
+ * Walk from `from` in `step` direction to the nearest code point that is
+ * neither a strippable invisible nor a combining mark, and report whether it
+ * belongs to a ZWNJ-using script.
+ *
+ * Marks are skippable because ZWNJ legitimately follows them (the canonical
+ * Hindi use is ZWNJ directly after the virama; Arabic harakat may also sit
+ * between the letter and the ZWNJ) — but a mark that itself carries a
+ * ZWNJ-script Script property (like the virama, Script=Devanagari) already
+ * answers the question and short-circuits to true.
+ */
+function neighborSupportsZwnj(text: string, from: number, step: -1 | 1): boolean {
+  let i = from;
+  while (step === -1 ? i > 0 : i < text.length) {
+    let j: number;
+    let cp: number;
+    if (step === -1) {
+      // Move one code point left, respecting surrogate pairs.
+      j = i - 1;
+      cp = text.charCodeAt(j);
+      if (cp >= 0xdc00 && cp <= 0xdfff && j > 0) {
+        const high = text.charCodeAt(j - 1);
+        if (high >= 0xd800 && high <= 0xdbff) {
+          j -= 1;
+          cp = text.codePointAt(j)!;
+        }
+      }
+    } else {
+      j = i;
+      cp = text.codePointAt(j)!;
+    }
+    const char = String.fromCodePoint(cp);
+    if (ZWNJ_SCRIPT.test(char)) return true;
+    if (!isInvisible(cp) && !COMBINING_MARK.test(char)) return false;
+    i = step === -1 ? j : j + char.length;
+  }
+  return false; // ran off the edge of the text
+}
+
+/** True when the ZWNJ at `zwnjIndex` sits between ZWNJ-using-script text. */
+function shouldPreserveZwnj(text: string, zwnjIndex: number): boolean {
+  return neighborSupportsZwnj(text, zwnjIndex, -1) && neighborSupportsZwnj(text, zwnjIndex + 1, 1);
+}
+
+export function stripInvisibles(text: string): TransformStepResult | null {
+  if (!INVISIBLE.test(text)) return null; // fast path: nothing to strip
+
+  const builder = new MappedTextBuilder();
+  const changes: StepChange[] = [];
+
+  for (const { segment, index } of graphemeSegmenter.segment(text)) {
+    const segmentEnd = index + segment.length;
+    if (!INVISIBLE.test(segment)) {
+      builder.copyVerbatim(text, index, segmentEnd);
+      continue;
+    }
+    if (EXTENDED_PICTOGRAPHIC.test(segment)) {
+      // Emoji cluster: its ZWJs (and any variation selectors) are structural.
+      builder.copyVerbatim(text, index, segmentEnd);
+      continue;
+    }
+    // Non-emoji cluster containing at least one invisible: strip code-point-wise.
+    let pos = index;
+    for (const char of segment) {
+      const charEnd = pos + char.length;
+      const cp = char.codePointAt(0)!;
+      if (cp === 0x200c && shouldPreserveZwnj(text, pos)) {
+        // Joining-script ZWNJ: structural, keep it (see header).
+        builder.copyVerbatim(text, pos, charEnd);
+      } else if (isInvisible(cp)) {
+        builder.deleteRange(pos, charEnd);
+        changes.push({
+          kind: 'strip-invisibles',
+          start: pos,
+          end: charEnd,
+          before: char,
+          after: '',
+        });
+      } else {
+        builder.copyVerbatim(text, pos, charEnd);
+      }
+      pos = charEnd;
+    }
+  }
+
+  // Every invisible was structural (emoji ZWJ / joining-script ZWNJ).
+  if (changes.length === 0) return null;
+
+  const { text: out, map } = builder.finish(text.length);
+  return { text: out, map, changes };
+}

package/src/transforms/whitespacePunct.ts

@@ -0,0 +1,100 @@
+/**
+ * Transform 4: WHITESPACE AND PUNCTUATION NORMALIZATION.
+ *
+ *   • exotic space characters → U+0020 regular space
+ *   • dash variants (hyphen, non-breaking hyphen, figure/en/em dash,
+ *     horizontal bar, minus sign) → '-' hyphen-minus
+ *   • curly and angle quotes → straight ' and "
+ *
+ * All replacements are strictly 1 code unit → 1 code unit, so this transform
+ * never changes offsets relative to its input. Runs of spaces are NOT
+ * collapsed and nothing is trimmed — that would change offsets in ways that
+ * damage code and formatted text.
+ *
+ * Most exotic spaces are already folded to U+0020 by NFKC; this transform
+ * exists so the guarantee holds even when the NFKC step is disabled, and for
+ * the few characters NFKC leaves alone (e.g. U+1680 OGHAM SPACE MARK and the
+ * dash/quote variants, which are not compatibility-decomposable).
+ */
+import { MappedTextBuilder, type TransformStepResult, type StepChange } from '../offsetMap.js';
+
+/**
+ * code unit → replacement. Every source is a BMP non-surrogate code point and
+ * every replacement is a single ASCII character, keeping the transform 1:1.
+ * Invisible-looking space characters are keyed by code point to keep literal
+ * invisibles out of this file; dashes and quotes are visible and literal.
+ */
+const REPLACEMENTS: ReadonlyMap<number, string> = new Map<number, string>([
+  // Spaces (the complete Zs category except U+0020 itself).
+  [0x00a0, ' '], // NO-BREAK SPACE
+  [0x1680, ' '], // OGHAM SPACE MARK
+  [0x2000, ' '], // EN QUAD
+  [0x2001, ' '], // EM QUAD
+  [0x2002, ' '], // EN SPACE
+  [0x2003, ' '], // EM SPACE
+  [0x2004, ' '], // THREE-PER-EM SPACE
+  [0x2005, ' '], // FOUR-PER-EM SPACE
+  [0x2006, ' '], // SIX-PER-EM SPACE
+  [0x2007, ' '], // FIGURE SPACE
+  [0x2008, ' '], // PUNCTUATION SPACE
+  [0x2009, ' '], // THIN SPACE
+  [0x200a, ' '], // HAIR SPACE
+  [0x202f, ' '], // NARROW NO-BREAK SPACE
+  [0x205f, ' '], // MEDIUM MATHEMATICAL SPACE
+  [0x3000, ' '], // IDEOGRAPHIC SPACE
+  // Dashes.
+  ['‐'.charCodeAt(0), '-'], // U+2010 HYPHEN
+  ['‑'.charCodeAt(0), '-'], // U+2011 NON-BREAKING HYPHEN
+  ['‒'.charCodeAt(0), '-'], // U+2012 FIGURE DASH
+  ['–'.charCodeAt(0), '-'], // U+2013 EN DASH
+  ['—'.charCodeAt(0), '-'], // U+2014 EM DASH
+  ['―'.charCodeAt(0), '-'], // U+2015 HORIZONTAL BAR
+  ['−'.charCodeAt(0), '-'], // U+2212 MINUS SIGN
+  // Single quotes.
+  ['‘'.charCodeAt(0), "'"], // U+2018
+  ['’'.charCodeAt(0), "'"], // U+2019
+  ['‚'.charCodeAt(0), "'"], // U+201A
+  ['‛'.charCodeAt(0), "'"], // U+201B
+  ['‹'.charCodeAt(0), "'"], // U+2039
+  ['›'.charCodeAt(0), "'"], // U+203A
+  // Double quotes.
+  ['“'.charCodeAt(0), '"'], // U+201C
+  ['”'.charCodeAt(0), '"'], // U+201D
+  ['„'.charCodeAt(0), '"'], // U+201E
+  ['‟'.charCodeAt(0), '"'], // U+201F
+  ['«'.charCodeAt(0), '"'], // U+00AB
+  ['»'.charCodeAt(0), '"'], // U+00BB
+]);
+
+export function normalizeWhitespacePunct(text: string): TransformStepResult | null {
+  // Fast path: scan for the first replaceable unit; most text has none.
+  let first = -1;
+  for (let i = 0; i < text.length; i++) {
+    if (REPLACEMENTS.has(text.charCodeAt(i))) {
+      first = i;
+      break;
+    }
+  }
+  if (first === -1) return null;
+
+  const builder = new MappedTextBuilder();
+  const changes: StepChange[] = [];
+  let cursor = 0;
+  for (let i = first; i < text.length; i++) {
+    const replacement = REPLACEMENTS.get(text.charCodeAt(i));
+    if (replacement === undefined) continue;
+    builder.copyVerbatim(text, cursor, i);
+    builder.replaceRange(replacement, i, i + 1);
+    changes.push({
+      kind: 'whitespace-punct',
+      start: i,
+      end: i + 1,
+      before: text[i]!,
+      after: replacement,
+    });
+    cursor = i + 1;
+  }
+  builder.copyVerbatim(text, cursor, text.length);
+  const { text: out, map } = builder.finish(text.length);
+  return { text: out, map, changes };
+}

package/src/types.ts

@@ -0,0 +1,339 @@
+/**
+ * Shared types for the whole Discretion project.
+ *
+ * These are contracts that later milestones (detectors, fusion, vault,
+ * substitution, egress guard, extension, playground) depend on. This file
+ * defines TYPES ONLY — no logic, no constants with behavior.
+ *
+ * EntityType membership comes directly from SPEC.md: the Stage 1 "Validated
+ * identifier detection" detector list and the Stage 2 NER types. Names use
+ * the spec's own SCREAMING_SNAKE_CASE spelling so a detector's declared
+ * entity type reads identically in the spec and in the code.
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Entities
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Every entity type the pipeline can detect, grouped as SPEC.md groups them.
+ *
+ * Three deliberate design choices, each recorded in ARCHITECTURE.md:
+ *
+ *  1. National identifiers are FAMILIES, not one member per country. SPEC.md
+ *     requires that "adding a new national identifier must require touching
+ *     exactly one new file" — a per-country union member would force every
+ *     new scheme to edit this file too, breaking that requirement. The
+ *     concrete scheme (SSN, TCKN, PESEL, Aadhaar, …) and its country travel
+ *     in Candidate.metadata. The substitution section's singular
+ *     "NATIONAL_ID → a value passing that country's checksum" confirms the
+ *     family reading.
+ *  2. Tax and VAT registrations are split out from NATIONAL_ID because their
+ *     sensitivity genuinely differs — a company VAT number is often public
+ *     registry data, a personal national ID never is — so the sensitivity
+ *     profiles must be able to threshold them independently.
+ *  3. PEM private keys get their own member rather than sharing API_KEY.
+ *     SPEC.md lists them in the same bullet, but a leaked private key and a
+ *     leaked API key differ in blast radius and in how each is surrogated.
+ */
+export type EntityType =
+  // ── Contact and network ──
+  | 'EMAIL'
+  | 'PHONE'
+  | 'IP_ADDRESS'
+  | 'MAC_ADDRESS'
+  | 'URL_WITH_CREDENTIALS'
+  // ── Financial ──
+  | 'CREDIT_CARD'
+  | 'IBAN'
+  | 'SWIFT_BIC'
+  | 'US_ROUTING_NUMBER'
+  | 'UK_SORT_CODE'
+  | 'CA_TRANSIT_NUMBER'
+  | 'AU_BSB'
+  | 'IN_IFSC'
+  | 'BR_AGENCIA'
+  | 'CRYPTO_WALLET'
+  // ── National and tax identifiers (families — see note 1 above) ──
+  | 'NATIONAL_ID'
+  | 'TAX_ID'
+  | 'VAT_NUMBER'
+  // ── Documents ──
+  | 'PASSPORT_MRZ'
+  | 'DRIVERS_LICENSE'
+  | 'VIN'
+  | 'US_NPI'
+  // ── Health (ICD-10/ICD-11, SNOMED, lab results) ──
+  | 'HEALTH_DATA'
+  // ── Secrets and credentials ──
+  | 'API_KEY'
+  | 'PRIVATE_KEY'
+  | 'JWT'
+  | 'GENERIC_SECRET'
+  | 'CONNECTION_STRING'
+  // ── Location ──
+  | 'POSTAL_CODE'
+  | 'STREET_ADDRESS'
+  | 'COORDINATES'
+  // ── Stage 2: named-entity recognition ──
+  | 'PERSON'
+  | 'ORG'
+  | 'LOCATION'
+  // ── Dates ──
+  // Absent from the Stage 1 detector list, but required by two other SPEC.md
+  // sections: the Strict profile ("adds ... dates of birth") and the
+  // substitution table ("DATE → a shifted date preserving relative ordering
+  // across the document"). Carried here so both stay implementable.
+  | 'DATE_OF_BIRTH';
+
+/**
+ * Which pipeline stage produced a candidate, or contributed to an entity.
+ * One member per stage of SPEC.md's core detection pipeline.
+ */
+export type DetectionStage =
+  | 'stage0-normalization' // text canonicalization (M1)
+  | 'stage1-validated-identifier' // regex candidate generation + validator
+  | 'stage2-ner' // multilingual ONNX token classification
+  | 'stage2b-gazetteer' // bundled name / place / org lookup sets
+  | 'stage2c-verification' // second opinion over the ambiguous band
+  | 'stage3-context' // trigger proximity, structural and negative context
+  | 'stage4-fusion'; // calibration, overlap resolution, profile thresholds
+
+/**
+ * A pre-fusion detection produced by a single detector.
+ * Offsets are indices into the NORMALIZED text (see NormalizationResult for
+ * how they map back to the original).
+ */
+export interface Candidate {
+  /** The matched substring of the normalized text. */
+  text: string;
+  type: EntityType;
+  /** Start offset (inclusive), UTF-16 code units into the normalized text. */
+  start: number;
+  /** End offset (exclusive). */
+  end: number;
+  /** Detector-local confidence in [0, 1]; NOT calibrated across detectors. */
+  rawConfidence: number;
+  stage: DetectionStage;
+  /** Stable identifier of the detector that produced this, e.g. "email-rfc5322". */
+  detectorId: string;
+  /** Detector-specific extras (e.g. { scheme: 'ssn', country: 'US' } for national_id). */
+  metadata?: Readonly<Record<string, unknown>>;
+}
+
+/** Why an entity was reported — surfaced in the review UI and in eval output. */
+export interface EntityExplanation {
+  /** Which stages fired for this entity. */
+  stages: readonly DetectionStage[];
+  /** Which triggers matched (detector ids, trigger names, context words). */
+  triggers: readonly string[];
+  /** Name of the validator that passed (checksum, format check), if any. */
+  validatorPassed?: string;
+}
+
+/** A post-fusion entity: what the pipeline actually reports. */
+export interface DetectedEntity {
+  /** The matched substring of the normalized text. */
+  text: string;
+  type: EntityType;
+  /** Start offset (inclusive), UTF-16 code units into the normalized text. */
+  start: number;
+  /** End offset (exclusive). */
+  end: number;
+  /** Calibrated confidence in [0, 1], comparable across types and stages. */
+  calibratedConfidence: number;
+  explanation: EntityExplanation;
+}
+
+// `StageTiming` and `DetectionResult` were declared here at M1 as shapes for
+// "later milestones" and were never implemented: no function ever returned
+// one, and nothing outside this file ever referenced them. M12 removed them
+// rather than publish them.
+//
+// A type in a published API is a promise that something produces it. Shipping
+// these would have put two entries in the generated reference that a reader
+// could search the whole package for and never find - the documentation
+// equivalent of a stub, which SPEC.md's fourth non-negotiable forbids.
+//
+// `protect()` is what M12 shipped for this job. Its result carries
+// `stagesRun`, which is DERIVED from the options, in place of `timings`,
+// which was merely declared.
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Policy / substitution
+// ─────────────────────────────────────────────────────────────────────────────
+
+// `SensitivityProfile` used to be declared here as the string union
+// 'minimal' | 'balanced' | 'strict' | 'custom'. It was DEAD and worse than
+// dead: `index.ts` re-exports the same name from `fuse/profiles.ts`, where it
+// is the profile OBJECT, so the union was unreachable through the package's
+// public API while still being the first definition a reader finds by name.
+// The union it described is `ProfileName`, which fuse/profiles.ts already
+// exports. Removed rather than renamed - two names for one idea is what
+// created the collision.
+
+export type SubstitutionMode = 'surrogate' | 'token';
+
+/** One masked value held locally so the original can be restored later. */
+export interface VaultEntry {
+  /** Stable unique id of this entry. */
+  id: string;
+  type: EntityType;
+  /** The original text that was masked (first-seen writing). */
+  original: string;
+  /** What it was replaced with (a surrogate value or an opaque token). */
+  replacement: string;
+  /** Epoch milliseconds when the entry was created. */
+  createdAt: number;
+  /**
+   * Canonical form of the original (separators stripped, case-normalized by
+   * the detector) — the consistency key that makes "4111 1111…" and
+   * "4111-1111…" share one entry, and the egress guard's
+   * separator-insensitive search term. Added in M4; optional because token
+   * bracket entries for unknown shapes have no canonical beyond the text.
+   */
+  canonical?: string;
+  /**
+   * True when no sensible surrogate could be produced and a bracket token
+   * was used instead — SPEC.md requires the fallback be recorded in the
+   * session record. Added in M4.
+   */
+  fallback?: boolean;
+}
+
+/** Result of masking a piece of text. */
+export interface MaskResult {
+  maskedText: string;
+  /** The entities that were substituted. */
+  entities: readonly DetectedEntity[];
+  /** Vault entries created for this mask operation. */
+  vaultEntries: readonly VaultEntry[];
+}
+
+/** Result of restoring masked values in a piece of text. */
+export interface RestoreResult {
+  restoredText: string;
+  /** How many replacements were restored to their originals. */
+  restoredCount: number;
+  /** Replacements found in the text with no matching vault entry. */
+  unmatchedReplacements: readonly string[];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Scripts
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Writing systems the pipeline distinguishes. Everything else is 'other'. */
+export type ScriptName =
+  | 'latin'
+  | 'cyrillic'
+  | 'arabic'
+  | 'hebrew'
+  | 'han'
+  | 'kana'
+  | 'hangul'
+  | 'devanagari'
+  | 'greek'
+  | 'thai'
+  | 'armenian'
+  | 'georgian'
+  | 'ethiopic'
+  | 'other';
+
+/** Per-script breakdown of a piece of text. */
+export interface ScriptInfo {
+  /**
+   * Letter counts per script. Script-neutral characters — whitespace, digits,
+   * punctuation, symbols, combining marks — are not counted at all; letters of
+   * scripts outside the supported list are counted under 'other'.
+   */
+  counts: Readonly<Record<ScriptName, number>>;
+  /**
+   * The script with the strictly highest letter count among the supported
+   * (non-'other') scripts, or null when the text has no such letters or the
+   * top count is tied.
+   */
+  dominant: ScriptName | null;
+  /** True when letters of two or more supported scripts are present. */
+  mixed: boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Normalization (Stage 0)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The individual transforms of the Stage 0 pipeline, in execution order. */
+export type TransformKind =
+  | 'strip-invisibles'
+  | 'nfkc'
+  | 'homoglyph-fold'
+  | 'whitespace-punct'
+  | 'fold-digits';
+
+/** One transform application, recorded for debugging and for the review UI. */
+export interface TransformationRecord {
+  kind: TransformKind;
+  /** Start of the affected range in the ORIGINAL text (inclusive). */
+  originalStart: number;
+  /** End of the affected range in the ORIGINAL text (exclusive). */
+  originalEnd: number;
+  /** The affected slice of the ORIGINAL text. */
+  original: string;
+  /** What this transform emitted for that range ('' for deletions). */
+  replacement: string;
+}
+
+/** Every transform can be disabled individually; all default to enabled. */
+export interface NormalizationOptions {
+  stripInvisibles?: boolean;
+  nfkc?: boolean;
+  homoglyphFold?: boolean;
+  whitespacePunct?: boolean;
+  /** Fold non-ASCII decimal digits (Arabic-Indic, Devanagari, Thai, …) to ASCII. */
+  foldDigits?: boolean;
+}
+
+/**
+ * The result of Stage 0 normalization.
+ *
+ * THE OFFSET MAP CONTRACT
+ * ───────────────────────
+ * Detection runs on `normalizedText`; substitution edits the ORIGINAL text.
+ * `offsetMap` connects the two:
+ *
+ *   offsetMap[i]  = index in the original string where the cluster that
+ *                   produced normalized index i begins.
+ *   offsetMap[normalizedText.length] = originalText.length   (sentinel)
+ *
+ * A normalized span [s, e) therefore maps to the original span
+ * [offsetMap[s], offsetMap[e]).  Invariants (tested exhaustively):
+ *   • offsetMap is monotonically non-decreasing
+ *   • offsetMap[0] === 0 whenever normalizedText is non-empty
+ *   • offsetMap[normalizedLength] === originalLength
+ *   • every value is a valid index into the original string (0..length incl.)
+ *   • identity inputs produce offsetMap[i] === i for every i
+ *
+ * Deleted characters (invisibles) do not appear in offsetMap; each deleted
+ * run is attributed to the cluster that FOLLOWS it (or to the sentinel when
+ * the run is at the very end), which is what makes offsetMap[0] === 0 hold.
+ *
+ * `reverseMap` goes the other way:
+ *   reverseMap[j] = normalized index of the start of the cluster whose
+ *                   original extent contains original index j; for a deleted
+ *                   character this is the normalized position where it was
+ *                   removed.
+ *   reverseMap[originalText.length] = normalizedText.length   (sentinel)
+ */
+export interface NormalizationResult {
+  normalizedText: string;
+  /** normalized index → original index; length is normalizedText.length + 1. */
+  offsetMap: Int32Array;
+  /** original index → normalized index; length is originalText.length + 1. */
+  reverseMap: Int32Array;
+  /** Script breakdown of the NORMALIZED text. */
+  scripts: ScriptInfo;
+  /** Every transform that fired, with ranges in original-text coordinates. */
+  transformations: readonly TransformationRecord[];
+  originalLength: number;
+  normalizedLength: number;
+}