@doccloak/core 0.8.0 → 0.10.0

package/dist/session.d.ts

@@ -1,15 +1,65 @@
 import type { EntityType, DetectedEntity, ReplacementEntry } from './types.js';
-export type ReplacementMode = 'labeled' | 'blanked';
+export * from './restore-tokens.js';
+export type ReplacementMode = 'labeled' | 'blanked' | 'surrogate';
+export interface SessionOptions {
+    /** Initial replacement mode; defaults to 'labeled' (typed placeholders). */
+    mode?: ReplacementMode;
+    /**
+     * Per-session surrogate salt; defaults to a fresh random one. Passing an
+     * explicit salt makes surrogate generation fully reproducible (tests,
+     * deserialization).
+     */
+    salt?: string;
+}
 export declare class AnonymizationSession {
     private forwardMap;
     private reverseMap;
     private entityTypeMap;
-    private counter;
+    private typeCounters;
     private mode;
+    /** Surrogate-mode salt (T043); constant for the session's lifetime. */
+    private salt;
+    constructor(options?: SessionOptions);
     setMode(mode: ReplacementMode): void;
     getMode(): ReplacementMode;
+    getSalt(): string;
+    /**
+     * Issue the next typed placeholder for the given entity type using a
+     * per-type counter: [PERSON_1], [PERSON_2], [EMAIL_1], ... Numbers
+     * already present in the reverse map (a renamed label or an entry
+     * restored via deserialize) are skipped so a fresh placeholder never
+     * collides with an existing one.
+     */
+    private nextPlaceholder;
+    /**
+     * Surrogate-mode replacement (T043): deterministic in (salt, type,
+     * original), collision-safe against every original value already in the
+     * session and every already-issued replacement. The map API is
+     * unchanged: the surrogate simply IS the replacement string, so
+     * deanonymize restores it via the same exact-literal lookup.
+     */
+    private nextSurrogate;
+    /**
+     * The already-mapped PERSON value that best matches a new variant
+     * (T057): most shared tokens wins; ties keep the first-mapped value.
+     * Deterministic; returns null when nothing matches.
+     */
+    private findPersonVariant;
     anonymize(original: string, entityType: EntityType): string;
     deanonymize(text: string): string;
+    /**
+     * Tolerant pass (T098) over text the exact pass already handled: scan
+     * for remaining token-shaped candidates and restore each one that
+     * unambiguously identifies a single map key (see
+     * buildTolerantTokenIndex). Anything else - unknown tokens, ambiguous
+     * canonical forms, partial tokens the candidate regex cannot even see -
+     * stays exactly as written: a missed restore is visible and
+     * recoverable, a guessed one silently corrupts the document. Runs after
+     * the exact pass, so an exact key never reaches this code; originals
+     * restored by the exact pass are plain user text and canonicalize to
+     * forms no key owns.
+     */
+    private deanonymizeMangledTokens;
     anonymizeText(text: string, entities: DetectedEntity[]): string;
     getEntries(): ReplacementEntry[];
     getForward(original: string): string | undefined;
@@ -23,15 +73,15 @@ export declare class AnonymizationSession {
      *   [
      *     {
      *       "original": string,      // the original sensitive value
-     *       "replacement": string,   // its placeholder, e.g. "<<REDACTED_1>>" or a renamed label
+     *       "replacement": string,   // its placeholder, e.g. "[PERSON_1]" or a renamed label
      *       "entity_type": string    // EntityType value, e.g. "PERSON" (snake_case key, matching Python)
      *     },
      *     ...
      *   ]
      *
      * - Top level is a JSON array; one object per mapping, in insertion order.
-     * - The counter is NOT stored as a field. Like Python's load_map, deserialize
-     *   derives it from the number of entries.
+     * - Counters are NOT stored as fields. Like Python's load_map, deserialize
+     *   derives them from the entries themselves.
      * - The mode is NOT stored as a field. Like Python's load_map (which returns
      *   `cls()` with the default mode), deserialize yields a 'labeled' session.
      * - Blanked entries are intentionally OMITTED from the output: blanked
@@ -40,19 +90,44 @@ export declare class AnonymizationSession {
      *   defeat that. Only reversible entries are serialized.
      * - Output formatting matches Python's json.dumps(entries, indent=2,
      *   ensure_ascii=False): 2-space indent, non-ASCII characters kept raw.
+     *
+     * Surrogate mode (T043) is the one exception to the top-level-array
+     * schema: it wraps the same entry objects in
+     * `{ "mode": "surrogate", "salt": "...", "entries": [...] }` so
+     * deserialize can restore the mode and the salt (new values anonymized
+     * after a restore then derive the same surrogates, and the per-session
+     * date offset stays stable). Placeholder ('labeled') and blanked
+     * sessions keep emitting the plain array byte-identically, so the
+     * Python-parity schema is untouched and absent fields mean placeholder
+     * mode.
      */
     serialize(): string;
+    /**
+     * Seed the live session with previously issued mappings (T106: the
+     * matter-persistence interface). Each entry lands in the forward map
+     * (value -> replacement, so anonymizing the same value again reuses
+     * the stored replacement instead of issuing a new one), the reverse
+     * map (replacement -> value, so deanonymize restores text produced in
+     * an earlier session; when several entries share a replacement, e.g.
+     * T057 person variants, the LONGEST original stays canonical
+     * regardless of entry order) and the type map. Per-type counters are
+     * raised to the highest N found among '[TYPE_N]' replacements so new
+     * entities anonymized afterwards continue numbering without colliding
+     * (nextPlaceholder additionally skips any taken number, which also
+     * covers renamed labels shaped like '[TYPE_N]'). Legacy
+     * '<<REDACTED_N>>' replacements are kept verbatim in both maps; they
+     * never collide with newly issued bracket placeholders and therefore
+     * need no counter. Blanked entries ('________') are kept in the
+     * forward map but excluded from the reverse map, preserving their
+     * irreversibility. Entries merge into whatever the session already
+     * holds; call clear() first for a fresh seeded session.
+     */
+    importEntries(entries: ReplacementEntry[]): void;
     /**
      * Rebuild a session from JSON produced by serialize() or by the Python
-     * CLI's save_map. Mirrors Python's load_map: forward/reverse/type maps are
-     * repopulated per entry and the counter is incremented once per entry.
-     * Additionally, the counter is raised to the highest N found among
-     * '<<REDACTED_N>>' placeholders (a map serialized with gaps, e.g. after
-     * blanked entries were omitted, would otherwise reissue a taken number),
-     * so new entities anonymized after restore continue numbering without
-     * colliding with restored placeholders. Blanked entries ('________') that a
-     * Python-produced map may contain are kept in the forward map but excluded
-     * from the reverse map, preserving their irreversibility.
+     * CLI's save_map. Mirrors Python's load_map: the per-entry map and
+     * counter population is importEntries (see its doc for the exact
+     * semantics, including legacy and blanked entries).
      */
     static deserialize(json: string): AnonymizationSession;
     clear(): void;

package/dist/session.js

@@ -1,10 +1,59 @@
+import { buildTolerantTokenIndex, resolveMangledToken } from "./restore-tokens.js";
+import { generateSessionSalt, generateUniqueSurrogate } from "./surrogates.js";
+export * from "./restore-tokens.js";
+// T099: credentials never get realistic stand-ins - a same-shape fake key
+// still looks like a live credential to anyone (or any scanner) reading the
+// prompt. Surrogate mode falls back to typed placeholders for these types.
+const PLACEHOLDER_ONLY_TYPES = new Set(['SECRET', 'API_KEY']);
+/**
+ * Person-variant tokenization (T057): lowercase word tokens with edge
+ * punctuation stripped. EVERY token participates in the subset test -
+ * dropping short ones would collapse "Person 1" into "Person 11".
+ */
+function personTokens(value) {
+    return value
+        .toLowerCase()
+        .split(/\s+/)
+        .map((t) => t.replace(/^[.,;:!?()"'\u201E\u201C\u201D]+|[.,;:!?()"'\u201E\u201C\u201D]+$/g, ''))
+        .filter((t) => t.length > 0);
+}
+/**
+ * Whether two PERSON values plausibly name the same person (T057): the
+ * token set of one must be a subset of the other's, and the shared part
+ * must contain at least one substantive token (>= 3 chars) so initials,
+ * digits or stray marks alone never unify. "John" and "Smith" both match
+ * "John Smith"; "Mr. Smith" does NOT (the 'mr' token has no counterpart,
+ * and honorific guessing would be overreach); "Person 1" never matches
+ * "Person 11" (the '1' token has no counterpart in the other value).
+ */
+function isPersonVariant(a, b) {
+    const ta = personTokens(a);
+    const tb = personTokens(b);
+    if (ta.length === 0 || tb.length === 0)
+        return false;
+    const [small, big] = ta.length <= tb.length ? [ta, tb] : [tb, ta];
+    return small.every((t) => big.includes(t)) && small.some((t) => t.length >= 3);
+}
+/**
+ * Typed placeholder token, e.g. "[PERSON_1]" or "[CREDIT_CARD_2]".
+ * EntityType ids are stable uppercase ASCII ([A-Z_]), so generated tokens
+ * always match the candidate pattern `\[[A-Z_]+_\d+\]`.
+ */
+const TYPED_PLACEHOLDER_RE = /^\[([A-Z_]+)_(\d+)\]$/;
+/**
+ * Candidate scan for the tolerant deanonymize pass: bracketed tokens,
+ * legacy angle tokens, or strict bare typed tokens. Broad candidates are
+ * safe - replacement still requires an unambiguous index hit.
+ */
+const MANGLED_CANDIDATE_RE = /\[[^[\]\n]+\]|<<[^<>\n]+>>|(?<![\p{L}\p{N}_[<])[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*_\d+(?![\p{L}\p{N}_])/gu;
 export class AnonymizationSession {
-    constructor() {
+    constructor(options) {
         this.forwardMap = new Map();
         this.reverseMap = new Map();
         this.entityTypeMap = new Map();
-        this.counter = 0;
-        this.mode = 'labeled';
+        this.typeCounters = new Map();
+        this.mode = options?.mode ?? 'labeled';
+        this.salt = options?.salt ?? generateSessionSalt();
     }
     setMode(mode) {
         this.mode = mode;
@@ -12,14 +61,89 @@ export class AnonymizationSession {
     getMode() {
         return this.mode;
     }
+    getSalt() {
+        return this.salt;
+    }
+    /**
+     * Issue the next typed placeholder for the given entity type using a
+     * per-type counter: [PERSON_1], [PERSON_2], [EMAIL_1], ... Numbers
+     * already present in the reverse map (a renamed label or an entry
+     * restored via deserialize) are skipped so a fresh placeholder never
+     * collides with an existing one.
+     */
+    nextPlaceholder(entityType) {
+        let n = this.typeCounters.get(entityType) ?? 0;
+        let placeholder;
+        do {
+            n++;
+            placeholder = `[${entityType}_${n}]`;
+        } while (this.reverseMap.has(placeholder));
+        this.typeCounters.set(entityType, n);
+        return placeholder;
+    }
+    /**
+     * Surrogate-mode replacement (T043): deterministic in (salt, type,
+     * original), collision-safe against every original value already in the
+     * session and every already-issued replacement. The map API is
+     * unchanged: the surrogate simply IS the replacement string, so
+     * deanonymize restores it via the same exact-literal lookup.
+     */
+    nextSurrogate(original, entityType) {
+        return generateUniqueSurrogate(original, entityType, { salt: this.salt, entries: this.getEntries() }, (candidate) => this.forwardMap.has(candidate) || this.reverseMap.has(candidate));
+    }
+    /**
+     * The already-mapped PERSON value that best matches a new variant
+     * (T057): most shared tokens wins; ties keep the first-mapped value.
+     * Deterministic; returns null when nothing matches.
+     */
+    findPersonVariant(value) {
+        const tokens = personTokens(value);
+        if (tokens.length === 0)
+            return null;
+        let best = null;
+        let bestShared = 0;
+        for (const [original] of this.forwardMap) {
+            if (this.entityTypeMap.get(original) !== 'PERSON')
+                continue;
+            if (!isPersonVariant(value, original))
+                continue;
+            const shared = personTokens(original).filter((t) => tokens.includes(t)).length;
+            if (shared > bestShared) {
+                bestShared = shared;
+                best = original;
+            }
+        }
+        return best;
+    }
     anonymize(original, entityType) {
         if (this.forwardMap.has(original)) {
             return this.forwardMap.get(original);
         }
-        this.counter++;
+        // T057 person-variant unification: "John Smith", "John" and "Smith"
+        // in one session are the same person and share one replacement (in
+        // every mode - the variant simply reuses the matched value's
+        // placeholder/surrogate). The reverse map keeps the LONGEST variant,
+        // so restore always yields the fullest known form.
+        if (entityType === 'PERSON') {
+            const match = this.findPersonVariant(original);
+            if (match) {
+                const placeholder = this.forwardMap.get(match);
+                this.forwardMap.set(original, placeholder);
+                this.entityTypeMap.set(original, entityType);
+                if (this.mode !== 'blanked') {
+                    const canonical = this.reverseMap.get(placeholder);
+                    if (canonical === undefined || original.length > canonical.length) {
+                        this.reverseMap.set(placeholder, original);
+                    }
+                }
+                return placeholder;
+            }
+        }
         const placeholder = this.mode === 'blanked'
             ? '________'
-            : `<<REDACTED_${this.counter}>>`;
+            : this.mode === 'surrogate' && !PLACEHOLDER_ONLY_TYPES.has(entityType)
+                ? this.nextSurrogate(original, entityType)
+                : this.nextPlaceholder(entityType);
         this.forwardMap.set(original, placeholder);
         // Blanked placeholders all collide on the same string; they are not
         // reversible, so keep them out of the restore map.
@@ -37,9 +161,58 @@ export class AnonymizationSession {
             // Replacer function keeps '$' sequences in the original value inert
             result = result.replaceAll(placeholder, () => original);
         }
-        return result;
+        // T098: exact-literal replacement above is the unchanged fast path;
+        // tokens an LLM mangled (case, spacing, markdown, dropped brackets)
+        // survive it untouched and get one tolerant pass.
+        return this.deanonymizeMangledTokens(result);
+    }
+    /**
+     * Tolerant pass (T098) over text the exact pass already handled: scan
+     * for remaining token-shaped candidates and restore each one that
+     * unambiguously identifies a single map key (see
+     * buildTolerantTokenIndex). Anything else - unknown tokens, ambiguous
+     * canonical forms, partial tokens the candidate regex cannot even see -
+     * stays exactly as written: a missed restore is visible and
+     * recoverable, a guessed one silently corrupts the document. Runs after
+     * the exact pass, so an exact key never reaches this code; originals
+     * restored by the exact pass are plain user text and canonicalize to
+     * forms no key owns.
+     */
+    deanonymizeMangledTokens(text) {
+        const index = buildTolerantTokenIndex(this.reverseMap.keys());
+        if (index.byCanonical.size === 0)
+            return text;
+        MANGLED_CANDIDATE_RE.lastIndex = 0;
+        let out = '';
+        let last = 0;
+        let match;
+        while ((match = MANGLED_CANDIDATE_RE.exec(text)) !== null) {
+            const key = resolveMangledToken(match[0], index);
+            if (key === null)
+                continue;
+            const original = this.reverseMap.get(key);
+            if (original === undefined)
+                continue;
+            out += text.slice(last, match.index) + original;
+            last = match.index + match[0].length;
+        }
+        if (last === 0)
+            return text;
+        return out + text.slice(last);
     }
     anonymizeText(text, entities) {
+        // Surrogate mode (T043): map PERSON entities first, in reading order,
+        // so an email appearing before/after its owner in the text can derive
+        // its local part from the person's surrogate (jan.kowalski maps to
+        // adam.nowak style). anonymize() is idempotent per value, so the
+        // replacement pass below reuses these mappings. Labeled mode keeps its
+        // historical end-to-start issuing order (placeholder numbering).
+        if (this.mode === 'surrogate') {
+            for (const entity of [...entities].sort((a, b) => a.start - b.start)) {
+                if (entity.type === 'PERSON')
+                    this.anonymize(entity.value, entity.type);
+            }
+        }
         // Sort entities by position (end to start) to preserve indices during replacement
         const sorted = [...entities].sort((a, b) => b.start - a.start);
         let result = text;
@@ -69,9 +242,15 @@ export class AnonymizationSession {
         const oldLabel = this.forwardMap.get(original);
         if (!oldLabel)
             return;
-        this.forwardMap.set(original, newLabel);
+        // T057: variants share one label; renaming any of them renames the
+        // whole group, and the canonical restore value carries over.
+        const canonical = this.reverseMap.get(oldLabel) ?? original;
+        for (const [orig, label] of this.forwardMap) {
+            if (label === oldLabel)
+                this.forwardMap.set(orig, newLabel);
+        }
         this.reverseMap.delete(oldLabel);
-        this.reverseMap.set(newLabel, original);
+        this.reverseMap.set(newLabel, canonical);
     }
     /**
      * Serialize the session map to JSON.
@@ -82,15 +261,15 @@ export class AnonymizationSession {
      *   [
      *     {
      *       "original": string,      // the original sensitive value
-     *       "replacement": string,   // its placeholder, e.g. "<<REDACTED_1>>" or a renamed label
+     *       "replacement": string,   // its placeholder, e.g. "[PERSON_1]" or a renamed label
      *       "entity_type": string    // EntityType value, e.g. "PERSON" (snake_case key, matching Python)
      *     },
      *     ...
      *   ]
      *
      * - Top level is a JSON array; one object per mapping, in insertion order.
-     * - The counter is NOT stored as a field. Like Python's load_map, deserialize
-     *   derives it from the number of entries.
+     * - Counters are NOT stored as fields. Like Python's load_map, deserialize
+     *   derives them from the entries themselves.
      * - The mode is NOT stored as a field. Like Python's load_map (which returns
      *   `cls()` with the default mode), deserialize yields a 'labeled' session.
      * - Blanked entries are intentionally OMITTED from the output: blanked
@@ -99,6 +278,16 @@ export class AnonymizationSession {
      *   defeat that. Only reversible entries are serialized.
      * - Output formatting matches Python's json.dumps(entries, indent=2,
      *   ensure_ascii=False): 2-space indent, non-ASCII characters kept raw.
+     *
+     * Surrogate mode (T043) is the one exception to the top-level-array
+     * schema: it wraps the same entry objects in
+     * `{ "mode": "surrogate", "salt": "...", "entries": [...] }` so
+     * deserialize can restore the mode and the salt (new values anonymized
+     * after a restore then derive the same surrogates, and the per-session
+     * date offset stays stable). Placeholder ('labeled') and blanked
+     * sessions keep emitting the plain array byte-identically, so the
+     * Python-parity schema is untouched and absent fields mean placeholder
+     * mode.
      */
     serialize() {
         const entries = this.getEntries()
@@ -108,46 +297,90 @@ export class AnonymizationSession {
             replacement,
             entity_type: entityType,
         }));
+        if (this.mode === 'surrogate') {
+            return JSON.stringify({ mode: 'surrogate', salt: this.salt, entries }, null, 2);
+        }
         return JSON.stringify(entries, null, 2);
     }
     /**
-     * Rebuild a session from JSON produced by serialize() or by the Python
-     * CLI's save_map. Mirrors Python's load_map: forward/reverse/type maps are
-     * repopulated per entry and the counter is incremented once per entry.
-     * Additionally, the counter is raised to the highest N found among
-     * '<<REDACTED_N>>' placeholders (a map serialized with gaps, e.g. after
-     * blanked entries were omitted, would otherwise reissue a taken number),
-     * so new entities anonymized after restore continue numbering without
-     * colliding with restored placeholders. Blanked entries ('________') that a
-     * Python-produced map may contain are kept in the forward map but excluded
-     * from the reverse map, preserving their irreversibility.
+     * Seed the live session with previously issued mappings (T106: the
+     * matter-persistence interface). Each entry lands in the forward map
+     * (value -> replacement, so anonymizing the same value again reuses
+     * the stored replacement instead of issuing a new one), the reverse
+     * map (replacement -> value, so deanonymize restores text produced in
+     * an earlier session; when several entries share a replacement, e.g.
+     * T057 person variants, the LONGEST original stays canonical
+     * regardless of entry order) and the type map. Per-type counters are
+     * raised to the highest N found among '[TYPE_N]' replacements so new
+     * entities anonymized afterwards continue numbering without colliding
+     * (nextPlaceholder additionally skips any taken number, which also
+     * covers renamed labels shaped like '[TYPE_N]'). Legacy
+     * '<<REDACTED_N>>' replacements are kept verbatim in both maps; they
+     * never collide with newly issued bracket placeholders and therefore
+     * need no counter. Blanked entries ('________') are kept in the
+     * forward map but excluded from the reverse map, preserving their
+     * irreversibility. Entries merge into whatever the session already
+     * holds; call clear() first for a fresh seeded session.
      */
-    static deserialize(json) {
-        const data = JSON.parse(json);
-        if (!Array.isArray(data)) {
-            throw new Error('Invalid session map JSON: expected a top-level array');
-        }
-        const session = new AnonymizationSession();
-        let maxPlaceholderNumber = 0;
-        for (const entry of data) {
-            session.forwardMap.set(entry.original, entry.replacement);
+    importEntries(entries) {
+        for (const entry of entries) {
+            this.forwardMap.set(entry.original, entry.replacement);
             if (entry.replacement !== '________') {
-                session.reverseMap.set(entry.replacement, entry.original);
+                const canonical = this.reverseMap.get(entry.replacement);
+                if (canonical === undefined || entry.original.length > canonical.length) {
+                    this.reverseMap.set(entry.replacement, entry.original);
+                }
             }
-            session.entityTypeMap.set(entry.original, entry.entity_type);
-            session.counter++;
-            const match = /^<<REDACTED_(\d+)>>$/.exec(entry.replacement);
+            this.entityTypeMap.set(entry.original, entry.entityType);
+            const match = TYPED_PLACEHOLDER_RE.exec(entry.replacement);
             if (match) {
-                maxPlaceholderNumber = Math.max(maxPlaceholderNumber, Number(match[1]));
+                const [, type, num] = match;
+                const current = this.typeCounters.get(type) ?? 0;
+                this.typeCounters.set(type, Math.max(current, Number(num)));
             }
         }
-        session.counter = Math.max(session.counter, maxPlaceholderNumber);
+    }
+    /**
+     * Rebuild a session from JSON produced by serialize() or by the Python
+     * CLI's save_map. Mirrors Python's load_map: the per-entry map and
+     * counter population is importEntries (see its doc for the exact
+     * semantics, including legacy and blanked entries).
+     */
+    static deserialize(json) {
+        const data = JSON.parse(json);
+        let entries;
+        let session;
+        if (Array.isArray(data)) {
+            entries = data;
+            session = new AnonymizationSession();
+        }
+        else if (typeof data === 'object' &&
+            data !== null &&
+            data.mode === 'surrogate' &&
+            Array.isArray(data.entries)) {
+            // Surrogate-mode wrapper (T043): restore mode + salt so surrogate
+            // derivation stays consistent after the round trip.
+            const wrapper = data;
+            entries = wrapper.entries;
+            session = new AnonymizationSession({
+                mode: 'surrogate',
+                salt: typeof wrapper.salt === 'string' ? wrapper.salt : undefined,
+            });
+        }
+        else {
+            throw new Error('Invalid session map JSON: expected a top-level array');
+        }
+        session.importEntries(entries.map((entry) => ({
+            original: entry.original,
+            replacement: entry.replacement,
+            entityType: entry.entity_type,
+        })));
         return session;
     }
     clear() {
         this.forwardMap.clear();
         this.reverseMap.clear();
         this.entityTypeMap.clear();
-        this.counter = 0;
+        this.typeCounters.clear();
     }
 }

package/dist/surrogates.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @doccloak/core - realistic, shape-preserving surrogate generator (T043).
+ *
+ * Generates fake-but-plausible replacements for detected entities instead
+ * of bracket placeholders: locale-aware names, dates shifted while keeping
+ * their format, IBANs/phones/IDs that keep their shape (checksum-valid
+ * where the checksum is cheap to compute).
+ *
+ * Determinism contract: every surrogate is a pure function of
+ * (session salt, entity type, original value, attempt). No Math.random or
+ * Date.now is ever consulted at module or generation scope, so the same
+ * original always yields the same surrogate within a session and tests are
+ * reproducible. The salt itself is created once per session (see
+ * generateSessionSalt, called from the AnonymizationSession constructor)
+ * and persisted with the map so a deserialized session keeps producing
+ * consistent surrogates.
+ *
+ * Fake-identifier policy: we never deliberately generate a real person's
+ * identifier. Generated PESELs encode a 19th-century birth date (a range
+ * the registry never issued numbers for), generated SSN shapes use the
+ * 900-999 area (never allocated by the SSA) with a group outside every
+ * valid ITIN range (T101: a 9xx area alone could still form a real ITIN),
+ * generated EIN shapes use campus prefixes the IRS has never assigned,
+ * generated ABA routing shapes are checksum-valid but carry the 99 leading
+ * pair (the ABA assigns only 00-12, 21-32, 61-72, and 80), generated NHS
+ * numbers sit in the mod-11-valid 999 test range (never issued to
+ * patients), and generated NINOs use the QQ prefix HMRC reserves for
+ * documentation examples. Random collisions with real identifiers of other
+ * kinds are statistically possible but not targetable: nothing about the
+ * original value survives into the surrogate beyond its shape.
+ */
+import type { EntityType } from './types.js';
+/**
+ * One salt per session, created at session construction time (never at
+ * module scope). WebCrypto when available; a constructor-time Math.random
+ * fallback otherwise (the salt only needs to be unique-ish per session,
+ * not cryptographically strong - surrogates are not secrets).
+ */
+export declare function generateSessionSalt(): string;
+/** Reserved/example domains only (RFC 2606 / RFC 6761): never routable. */
+export declare const FAKE_EMAIL_DOMAINS: readonly ["example.com", "example.org", "example.net", "mail.example", "post.example", "inbox.test", "mail.test", "poczta.test"];
+export interface SurrogateContext {
+    /** Per-session salt; the sole source of randomness. */
+    salt: string;
+    /**
+     * Already-issued session mappings, used to derive an email local part
+     * from the surrogate of the matching PERSON (jan.kowalski maps to
+     * adam.nowak style). Optional; without it emails get an unrelated
+     * deterministic fake identity.
+     */
+    entries?: ReadonlyArray<{
+        original: string;
+        replacement: string;
+        entityType: EntityType;
+    }>;
+}
+/**
+ * Per-session day offset in [-30, -1] or [1, 30]: derived from the salt
+ * only, so every date in a session shifts by the same amount and relative
+ * spacing between dates is preserved. Never 0 (a zero shift would leak the
+ * original date unchanged).
+ */
+export declare function sessionDayOffset(salt: string): number;
+/**
+ * Test/diagnostic probe (T073): which locale pack a PERSON value would
+ * use. Not part of the anonymization data path.
+ */
+export declare function detectSurrogateLocale(value: string): string;
+/**
+ * Generate a surrogate for one entity. Pure and deterministic in
+ * (ctx.salt, type, original, attempt); bump `attempt` to re-derive after
+ * a collision.
+ */
+export declare function generateSurrogate(original: string, type: EntityType, ctx: SurrogateContext, attempt?: number): string;
+/**
+ * Collision-safe wrapper: re-derives with a bumped attempt while the
+ * candidate equals the original or `isTaken` reports a clash (another
+ * original value or an already-issued replacement); after bounded retries
+ * it appends digits until unique. Termination is guaranteed because the
+ * taken set is finite.
+ */
+export declare function generateUniqueSurrogate(original: string, type: EntityType, ctx: SurrogateContext, isTaken: (candidate: string) => boolean): string;