@discretion/core 0.1.0

package/dist/src/mask/masker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"masker.d.ts","sourceRoot":"","sources":["../../../src/mask/masker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAMxC,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACjC,oEAAoE;IACpE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,CAAC;CAC9C;AAOD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,iBAAiB,EAC3D,UAAU,EAAE,SAAS,CAAC,EAAE,GACvB,CAAC,EAAE,CAgBL;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,SAAS,iBAAiB,EAAE,EACxC,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE,WAAgB,GACxB,UAAU,CAgEZ;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,GAAE,WAAW,GAAG,aAAkB,GAAG,UAAU,CAUtG"}

package/dist/src/mask/masker.js

@@ -0,0 +1,201 @@
+/**
+ * masker.ts — replace detected sensitive spans with surrogates (or tokens),
+ * building the vault as it goes.
+ *
+ * Operates on Stage 1 candidates in ORIGINAL-text coordinates (the offsets
+ * the runner resolved through the Stage 0 map), so the edited text is the
+ * user's real text with exactly the sensitive spans replaced.
+ *
+ * FOUR GUARANTEES, each enforced here:
+ *  • CONSISTENT — the same original (by exact, canonical, or normalized key)
+ *    always maps to the same surrogate within a session; a repeat reuses the
+ *    vault entry rather than minting a new one.
+ *  • COLLISION-SAFE — before committing a surrogate, verify it appears
+ *    nowhere in the source text and nowhere in the vault; on collision, retry
+ *    with a fresh seed up to a bound. Exhausting the bound falls back to a
+ *    bracket token.
+ *  • REVERSIBLE — every substitution is a vault entry, so the restorer can
+ *    invert it.
+ *  • NON-OVERLAPPING — overlapping candidates would corrupt the edit. Stage 4
+ *    (M8) does calibrated overlap resolution; here a documented pre-fusion
+ *    stopgap picks a non-overlapping subset (higher confidence, then longer
+ *    span, then more-specific type) purely so masking is well-defined.
+ *
+ * Non-sensitive candidates (known test values) are NOT masked — they are
+ * detected precisely so they can be left alone.
+ */
+import { normalize } from '../normalization.js';
+import { runStage1 } from '../detect/runner.js';
+import { chooseSurrogate } from './surrogates.js';
+import { comparisonForm, separatorFree } from './egressGuard.js';
+const MAX_SURROGATE_ATTEMPTS = 24;
+/** A stable bracket token, used in token mode and as the surrogate fallback. */
+function bracketToken(type, ordinal) {
+    return `[${type}_${ordinal}]`;
+}
+/**
+ * Pre-fusion overlap resolution: greedily keep non-overlapping candidates,
+ * preferring higher confidence, then longer span, then a stable detector id
+ * for determinism. A documented stopgap until Stage 4 fusion (M8) resolves
+ * overlaps against calibrated scores.
+ */
+export function resolveForMasking(candidates) {
+    const sensitive = candidates.filter((c) => c.sensitive);
+    const ranked = [...sensitive].sort((a, b) => {
+        if (b.rawConfidence !== a.rawConfidence)
+            return b.rawConfidence - a.rawConfidence;
+        const lenA = a.originalEnd - a.originalStart;
+        const lenB = b.originalEnd - b.originalStart;
+        if (lenB !== lenA)
+            return lenB - lenA;
+        return a.detectorId < b.detectorId ? -1 : 1;
+    });
+    const kept = [];
+    for (const c of ranked) {
+        if (!kept.some((k) => c.originalStart < k.originalEnd && k.originalStart < c.originalEnd)) {
+            kept.push(c);
+        }
+    }
+    return kept.sort((a, b) => a.originalStart - b.originalStart);
+}
+/**
+ * Mask the given ORIGINAL text using the candidates found in it.
+ * The candidates' `originalStart`/`originalEnd` must index into `original`.
+ *
+ * Takes `PipelineCandidate` rather than `Stage1Candidate` because Stage 2's
+ * PERSON/ORG/LOCATION entities must be masked too, and nothing in this file
+ * reads the `stage` discriminant — the two candidate shapes are otherwise
+ * identical. Typing it to Stage 1 alone was the narrower claim, not the safer
+ * one: it silently excluded the entities SPEC most wants surrogates for.
+ */
+export function maskOriginal(original, candidates, vault, options = {}) {
+    const mode = options.mode ?? 'surrogate';
+    const baseSeed = options.seed ?? 0x5eed;
+    const resolved = resolveForMasking(candidates);
+    // The collision check must run in the EGRESS GUARD'S comparison space:
+    // the guard scans in normalized+case-folded form plus a separator-free
+    // canonical pass, so a surrogate is acceptable only if none of this
+    // document's sensitive values would be found inside it under those same
+    // comparisons. The bug this prevents was found by the integration
+    // property: a phone surrogate drawn from the same small pool was the SAME
+    // number as the original in different formatting — the literal string
+    // check passed, and the masked text then failed its own guard.
+    const forbiddenNeedles = resolved.map((c) => {
+        const value = original.slice(c.originalStart, c.originalEnd);
+        const form = comparisonForm(value);
+        const strip = separatorFree(separatorFreeCanonical(c, value));
+        return { form, strip };
+    });
+    const entities = [];
+    const vaultEntries = [];
+    const tokenOrdinals = new Map();
+    const out = [];
+    let cursor = 0;
+    for (const c of resolved) {
+        const value = original.slice(c.originalStart, c.originalEnd);
+        out.push(original.slice(cursor, c.originalStart));
+        cursor = c.originalEnd;
+        // Consistency: a value already masked this session reuses its surrogate.
+        const existing = vault.getByOriginal(value, c.canonical);
+        if (existing !== undefined) {
+            out.push(existing.replacement);
+            entities.push({
+                type: c.type, originalStart: c.originalStart, originalEnd: c.originalEnd,
+                original: value, replacement: existing.replacement, vaultId: existing.id,
+                fallback: existing.fallback ?? false,
+            });
+            continue;
+        }
+        const { replacement, fallback } = selectReplacement(c, value, original, vault, mode, baseSeed, tokenOrdinals, forbiddenNeedles);
+        const entry = vault.register({
+            type: c.type,
+            original: value,
+            replacement,
+            ...(c.canonical !== undefined ? { canonical: c.canonical } : {}),
+            ...(fallback ? { fallback: true } : {}),
+        });
+        vaultEntries.push(entry);
+        out.push(replacement);
+        entities.push({
+            type: c.type, originalStart: c.originalStart, originalEnd: c.originalEnd,
+            original: value, replacement, vaultId: entry.id, fallback,
+        });
+    }
+    out.push(original.slice(cursor));
+    return { maskedText: out.join(''), entities, vaultEntries };
+}
+/**
+ * End-to-end: normalize, run Stage 1, and mask the original text. The
+ * convenience entry point for the playground (M5) and the tests; the
+ * extension (M9) wires the same pieces with its own detection options.
+ */
+export function mask(text, vault, options = {}) {
+    const normalization = normalize(text);
+    const { mode, seed, ...stage1 } = options;
+    const candidates = runStage1(normalization, stage1);
+    return maskOriginal(text, candidates, vault, { ...(mode !== undefined ? { mode } : {}), ...(seed !== undefined ? { seed } : {}) });
+}
+/** The candidate's canonical in comparison form (falls back to the value). */
+function separatorFreeCanonical(c, value) {
+    return comparisonForm(c.canonical ?? value);
+}
+/** Pick a collision-free, consistent replacement for one value. */
+function selectReplacement(c, value, sourceDoc, vault, mode, baseSeed, tokenOrdinals, forbiddenNeedles) {
+    if (mode === 'token') {
+        return { replacement: nextToken(c.type, vault, sourceDoc, tokenOrdinals), fallback: false };
+    }
+    const seedBase = baseSeed ^ hashString(c.canonical ?? value);
+    for (let attempt = 0; attempt < MAX_SURROGATE_ATTEMPTS; attempt++) {
+        const surrogate = chooseSurrogate({ type: c.type, text: value, ...(c.metadata !== undefined ? { metadata: c.metadata } : {}) }, (seedBase + attempt * 0x9e37) & 0x7fffffff);
+        if (surrogate === null)
+            break; // no surrogate for this type → token
+        if (!collides(surrogate, sourceDoc, vault, forbiddenNeedles)) {
+            return { replacement: surrogate, fallback: false };
+        }
+    }
+    // Pool exhausted or no surrogate: fall back to a bracket token, recorded.
+    return { replacement: nextToken(c.type, vault, sourceDoc, tokenOrdinals), fallback: true };
+}
+/**
+ * A surrogate collides if it appears in the source text or the vault — or
+ * if any of this document's sensitive values would be FOUND WITHIN IT under
+ * the egress guard's comparisons (normalized case-folded substring, or the
+ * ≥6-char separator-free canonical pass). Masker and guard sharing one
+ * comparison space is what guarantees masked text passes its own guard.
+ */
+function collides(surrogate, sourceDoc, vault, forbiddenNeedles) {
+    if (vault.wouldCollide(surrogate))
+        return true;
+    // Case-insensitive appearance in the source, so the restorer's fuzzy pass
+    // cannot later confuse the surrogate with pre-existing text.
+    if (sourceDoc.toLowerCase().includes(surrogate.toLowerCase()))
+        return true;
+    const surrogateForm = comparisonForm(surrogate);
+    const surrogateStrip = separatorFree(surrogateForm);
+    for (const needle of forbiddenNeedles) {
+        if (needle.form.length > 0 && surrogateForm.includes(needle.form))
+            return true;
+        if (needle.strip.length >= 6 && surrogateStrip.includes(needle.strip))
+            return true;
+    }
+    return false;
+}
+/** The next unused bracket token for a type (unique in source and vault). */
+function nextToken(type, vault, sourceDoc, tokenOrdinals) {
+    let ordinal = tokenOrdinals.get(type) ?? 1;
+    let token = bracketToken(type, ordinal);
+    while (vault.wouldCollide(token) || sourceDoc.includes(token)) {
+        ordinal += 1;
+        token = bracketToken(type, ordinal);
+    }
+    tokenOrdinals.set(type, ordinal + 1);
+    return token;
+}
+/** Deterministic 31-bit string hash so a value's seed is stable per session. */
+function hashString(s) {
+    let h = 0;
+    for (let i = 0; i < s.length; i++)
+        h = (Math.imul(h, 31) + s.charCodeAt(i)) | 0;
+    return h & 0x7fffffff;
+}
+//# sourceMappingURL=masker.js.map

package/dist/src/mask/masker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"masker.js","sourceRoot":"","sources":["../../../src/mask/masker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAMhD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjE,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAyBlC,gFAAgF;AAChF,SAAS,YAAY,CAAC,IAAY,EAAE,OAAe;IACjD,OAAO,IAAI,IAAI,IAAI,OAAO,GAAG,CAAC;AAChC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,UAAwB;IAExB,MAAM,SAAS,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACxD,MAAM,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAC1C,IAAI,CAAC,CAAC,aAAa,KAAK,CAAC,CAAC,aAAa;YAAE,OAAO,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,aAAa,CAAC;QAClF,MAAM,IAAI,GAAG,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,aAAa,CAAC;QAC7C,MAAM,IAAI,GAAG,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,aAAa,CAAC;QAC7C,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,IAAI,GAAG,IAAI,CAAC;QACtC,OAAO,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IACH,MAAM,IAAI,GAAQ,EAAE,CAAC;IACrB,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC;YAC1F,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,QAAgB,EAChB,UAAwC,EACxC,KAAY,EACZ,UAAuB,EAAE;IAEzB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,WAAW,CAAC;IACzC,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC;IACxC,MAAM,QAAQ,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;IAE/C,uEAAuE;IACvE,uEAAuE;IACvE,oEAAoE;IACpE,wEAAwE;IACxE,kEAAkE;IAClE,0EAA0E;IAC1E,sEAAsE;IACtE,+DAA+D;IAC/D,MAAM,gBAAgB,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC1C,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC;QAC7D,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;QACnC,MAAM,KAAK,GAAG,aAAa,CAAC,sBAAsB,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;QAC9D,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IACzB,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAmB,EAAE,CAAC;IACpC,MAAM,YAAY,GAAiB,EAAE,CAAC;IACtC,MAAM,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEhD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC;QAC7D,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC;QAClD,MAAM,GAAG,CAAC,CAAC,WAAW,CAAC;QAEvB,yEAAyE;QACzE,MAAM,QAAQ,GAAG,KAAK,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;QACzD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;YAC/B,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC,aAAa,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW;gBACxE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,CAAC,WAAW,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE;gBACxE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,IAAI,KAAK;aACrC,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,GAAG,iBAAiB,CACjD,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,aAAa,EAAE,gBAAgB,CAC3E,CAAC;QACF,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC;YAC3B,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,QAAQ,EAAE,KAAK;YACf,WAAW;YACX,GAAG,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxC,CAAC,CAAC;QACH,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACtB,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC,aAAa,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW;YACxE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,QAAQ;SAC1D,CAAC,CAAC;IACL,CAAC;IACD,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAEjC,OAAO,EAAE,UAAU,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAAC,IAAY,EAAE,KAAY,EAAE,UAAuC,EAAE;IACxF,MAAM,aAAa,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;IAC1C,MAAM,UAAU,GAAG,SAAS,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IACpD,OAAO,YAAY,CACjB,IAAI,EACJ,UAAU,EACV,KAAK,EACL,EAAE,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CACrF,CAAC;AACJ,CAAC;AAOD,8EAA8E;AAC9E,SAAS,sBAAsB,CAAC,CAAoB,EAAE,KAAa;IACjE,OAAO,cAAc,CAAC,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC,CAAC;AAC9C,CAAC;AAED,mEAAmE;AACnE,SAAS,iBAAiB,CACxB,CAAoB,EACpB,KAAa,EACb,SAAiB,EACjB,KAAY,EACZ,IAAsB,EACtB,QAAgB,EAChB,aAAkC,EAClC,gBAA4C;IAE5C,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACrB,OAAO,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,aAAa,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAC9F,CAAC;IAED,MAAM,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC,CAAC;IAC7D,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,sBAAsB,EAAE,OAAO,EAAE,EAAE,CAAC;QAClE,MAAM,SAAS,GAAG,eAAe,CAC/B,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAC5F,CAAC,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC,GAAG,UAAU,CAC3C,CAAC;QACF,IAAI,SAAS,KAAK,IAAI;YAAE,MAAM,CAAC,qCAAqC;QACpE,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,gBAAgB,CAAC,EAAE,CAAC;YAC7D,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;QACrD,CAAC;IACH,CAAC;IACD,0EAA0E;IAC1E,OAAO,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,aAAa,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAC7F,CAAC;AAED;;;;;;GAMG;AACH,SAAS,QAAQ,CACf,SAAiB,EACjB,SAAiB,EACjB,KAAY,EACZ,gBAA4C;IAE5C,IAAI,KAAK,CAAC,YAAY,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/C,0EAA0E;IAC1E,6DAA6D;IAC7D,IAAI,SAAS,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IAE3E,MAAM,aAAa,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IAChD,MAAM,cAAc,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC;IACpD,KAAK,MAAM,MAAM,IAAI,gBAAgB,EAAE,CAAC;QACtC,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,aAAa,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAC/E,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,IAAI,cAAc,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;IACrF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,6EAA6E;AAC7E,SAAS,SAAS,CAAC,IAAY,EAAE,KAAY,EAAE,SAAiB,EAAE,aAAkC;IAClG,IAAI,OAAO,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,KAAK,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACxC,OAAO,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9D,OAAO,IAAI,CAAC,CAAC;QACb,KAAK,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;IACD,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;IACrC,OAAO,KAAK,CAAC;AACf,CAAC;AAED,gFAAgF;AAChF,SAAS,UAAU,CAAC,CAAS;IAC3B,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAChF,OAAO,CAAC,GAAG,UAAU,CAAC;AACxB,CAAC"}

package/dist/src/mask/restorer.d.ts

@@ -0,0 +1,96 @@
+/**
+ * restorer.ts — the unmasker, correct against fragmented streaming text.
+ *
+ * The model's response arrives in chunks, and a surrogate may be split across
+ * a chunk boundary. The restorer therefore operates on ACCUMULATED text and
+ * emits only what is safe to finalize:
+ *
+ *  • HOLD ON PARTIAL MATCH. If a suffix of the accumulated buffer is a proper
+ *    prefix of any known surrogate, that suffix is held unrendered until more
+ *    text resolves it. This is the guarantee behind the key test: no partial
+ *    surrogate is ever wrongly replaced, however the stream is chunked.
+ *
+ *  • EXACT REPLACEMENT is longest-match, left to right — a surrogate that is a
+ *    prefix of a longer surrogate never steals the longer one's match.
+ *
+ *  • FUZZY FALLBACK is a controlled, per-token pass for a surrogate the model
+ *    transformed: case change, possessive ('s), or plural (s/es). It fires
+ *    ONLY when exactly one surrogate matches a settled token under those
+ *    relaxations; ANY ambiguity (two surrogates match, or none) leaves the
+ *    token untouched — SPEC.md's hard rule. Cross-script "translation" of a
+ *    surrogate is deliberately NOT attempted; such a surrogate stays visible
+ *    rather than being guessed at (ARCHITECTURE.md D13).
+ *
+ *  • IDEMPOTENT. Only newly-buffered text is ever processed; rendered text is
+ *    never revisited. Re-restoring already-restored text is a no-op because
+ *    originals are collision-guaranteed distinct from every surrogate, so
+ *    nothing in the output matches a surrogate to replace again.
+ */
+import type { RestoreResult } from '../types.js';
+import type { Vault } from './vault.js';
+export interface RestorerOptions {
+    /** Enable the transformed-surrogate fuzzy fallback. Default true. */
+    readonly fuzzy?: boolean;
+}
+export declare class Restorer {
+    private buffer;
+    private out;
+    private restored;
+    private done;
+    private readonly surrogatesByLength;
+    private readonly maxLen;
+    private readonly fuzzyByLower;
+    private readonly fuzzy;
+    private readonly vault;
+    constructor(vault: Vault, options?: RestorerOptions);
+    /** Push the next stream chunk; returns the text newly rendered this call. */
+    push(chunk: string): string;
+    /** Flush the remainder; no more holding. Returns the final rendered text. */
+    finish(): string;
+    /** Everything rendered so far. */
+    get rendered(): string;
+    /** How many surrogate occurrences have been restored. */
+    get restoredCount(): number;
+    /** Emit every settled portion of the buffer, holding what is still risky. */
+    private drain;
+    /**
+     * The earliest position from which the buffer must be held back:
+     *  • the start of any suffix that is a proper prefix of a surrogate, and
+     *  • (fuzzy on) the start of a trailing non-whitespace run, so the fuzzy
+     *    pass always sees whole tokens rather than a word still being typed.
+     */
+    private holdPoint;
+    private isProperPrefixOfSurrogate;
+    /** Exact longest-match replacement, then the controlled fuzzy pass. */
+    private replaceSettled;
+    /**
+     * Longest surrogate matching at `pos` WITH word-boundary semantics: a
+     * surrogate whose first/last character is a word character must not be
+     * glued to another word character in the text. Without this, a short
+     * surrogate ('Cat') corrupts an ordinary word ('Catalog' -> 'Org Onealog').
+     * Structured surrogates (emails, IBANs, PEM blocks) are unaffected because
+     * their neighbours in real text are punctuation or whitespace, and a
+     * surrogate ending in punctuation imposes no trailing constraint at all.
+     * Model-added affixes ('Northwinds') are handled by the fuzzy pass, which
+     * re-attaches what it strips.
+     */
+    private longestSurrogateAt;
+    /**
+     * Per-token fuzzy restoration of transformed surrogates. Splits on
+     * whitespace, keeps the separators, and rewrites only tokens that resolve
+     * to exactly one surrogate under case / possessive / plural relaxation.
+     */
+    private fuzzyPass;
+    /** Try to restore one whitespace-free token; null = leave it alone. */
+    private fuzzyToken;
+    /**
+     * Resolve a core token to exactly one original, under case-fold plus
+     * possessive/plural stripping, carrying the affix that was stripped.
+     * Returns null when zero or MORE THAN ONE distinct original is reachable —
+     * SPEC.md's hard rule that ambiguous matches are left alone.
+     */
+    private resolveFuzzyCore;
+}
+/** One-shot restoration of a complete (non-streamed) response. */
+export declare function restore(text: string, vault: Vault, options?: RestorerOptions): RestoreResult;
+//# sourceMappingURL=restorer.d.ts.map

package/dist/src/mask/restorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restorer.d.ts","sourceRoot":"","sources":["../../../src/mask/restorer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAWxC,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,GAAG,CAAM;IACjB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,IAAI,CAAS;IAErB,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAoB;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6C;IAC1E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;gBAElB,KAAK,EAAE,KAAK,EAAE,OAAO,GAAE,eAAoB;IAmBvD,6EAA6E;IAC7E,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAM3B,6EAA6E;IAC7E,MAAM,IAAI,MAAM;IAOhB,kCAAkC;IAClC,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,yDAAyD;IACzD,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,6EAA6E;IAC7E,OAAO,CAAC,KAAK;IAiBb;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAwBjB,OAAO,CAAC,yBAAyB;IAQjC,uEAAuE;IACvE,OAAO,CAAC,cAAc;IAqBtB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,kBAAkB;IAa1B;;;;OAIG;IACH,OAAO,CAAC,SAAS;IAcjB,uEAAuE;IACvE,OAAO,CAAC,UAAU;IAsBlB;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;CAuBzB;AAED,kEAAkE;AAClE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,GAAE,eAAoB,GAAG,aAAa,CAKhG"}

package/dist/src/mask/restorer.js

@@ -0,0 +1,263 @@
+/**
+ * restorer.ts — the unmasker, correct against fragmented streaming text.
+ *
+ * The model's response arrives in chunks, and a surrogate may be split across
+ * a chunk boundary. The restorer therefore operates on ACCUMULATED text and
+ * emits only what is safe to finalize:
+ *
+ *  • HOLD ON PARTIAL MATCH. If a suffix of the accumulated buffer is a proper
+ *    prefix of any known surrogate, that suffix is held unrendered until more
+ *    text resolves it. This is the guarantee behind the key test: no partial
+ *    surrogate is ever wrongly replaced, however the stream is chunked.
+ *
+ *  • EXACT REPLACEMENT is longest-match, left to right — a surrogate that is a
+ *    prefix of a longer surrogate never steals the longer one's match.
+ *
+ *  • FUZZY FALLBACK is a controlled, per-token pass for a surrogate the model
+ *    transformed: case change, possessive ('s), or plural (s/es). It fires
+ *    ONLY when exactly one surrogate matches a settled token under those
+ *    relaxations; ANY ambiguity (two surrogates match, or none) leaves the
+ *    token untouched — SPEC.md's hard rule. Cross-script "translation" of a
+ *    surrogate is deliberately NOT attempted; such a surrogate stays visible
+ *    rather than being guessed at (ARCHITECTURE.md D13).
+ *
+ *  • IDEMPOTENT. Only newly-buffered text is ever processed; rendered text is
+ *    never revisited. Re-restoring already-restored text is a no-op because
+ *    originals are collision-guaranteed distinct from every surrogate, so
+ *    nothing in the output matches a surrogate to replace again.
+ */
+/** ASCII/Unicode word character, for exact-match boundary checks. */
+const WORD_CHAR = /[\p{L}\p{N}_]/u;
+export class Restorer {
+    buffer = '';
+    out = '';
+    restored = 0;
+    done = false;
+    surrogatesByLength;
+    maxLen;
+    fuzzyByLower;
+    fuzzy;
+    vault;
+    constructor(vault, options = {}) {
+        this.vault = vault;
+        this.fuzzy = options.fuzzy ?? true;
+        const surrogates = vault.replacements();
+        this.surrogatesByLength = [...surrogates].sort((a, b) => b.length - a.length);
+        this.maxLen = surrogates.reduce((m, s) => Math.max(m, s.length), 0);
+        const fuzzyMap = new Map();
+        for (const surrogate of surrogates) {
+            const entry = vault.getBySurrogate(surrogate);
+            if (entry === undefined)
+                continue;
+            const lower = surrogate.toLowerCase();
+            const list = fuzzyMap.get(lower) ?? [];
+            list.push({ surrogate, lower, original: entry.original });
+            fuzzyMap.set(lower, list);
+        }
+        this.fuzzyByLower = fuzzyMap;
+    }
+    /** Push the next stream chunk; returns the text newly rendered this call. */
+    push(chunk) {
+        if (this.done)
+            throw new Error('restorer: push after finish');
+        this.buffer += chunk;
+        return this.drain(false);
+    }
+    /** Flush the remainder; no more holding. Returns the final rendered text. */
+    finish() {
+        if (this.done)
+            return '';
+        const tail = this.drain(true);
+        this.done = true;
+        return tail;
+    }
+    /** Everything rendered so far. */
+    get rendered() {
+        return this.out;
+    }
+    /** How many surrogate occurrences have been restored. */
+    get restoredCount() {
+        return this.restored;
+    }
+    /** Emit every settled portion of the buffer, holding what is still risky. */
+    drain(final) {
+        if (this.surrogatesByLength.length === 0) {
+            // Nothing to restore: pure passthrough, no holding.
+            const emit = this.buffer;
+            this.buffer = '';
+            this.out += emit;
+            return emit;
+        }
+        const holdFrom = final ? this.buffer.length : this.holdPoint();
+        const settled = this.buffer.slice(0, holdFrom);
+        this.buffer = this.buffer.slice(holdFrom);
+        const emitted = this.replaceSettled(settled);
+        this.out += emitted;
+        return emitted;
+    }
+    /**
+     * The earliest position from which the buffer must be held back:
+     *  • the start of any suffix that is a proper prefix of a surrogate, and
+     *  • (fuzzy on) the start of a trailing non-whitespace run, so the fuzzy
+     *    pass always sees whole tokens rather than a word still being typed.
+     */
+    holdPoint() {
+        const n = this.buffer.length;
+        let hold = n;
+        // A prefix-to-end can only begin within maxLen characters of the end.
+        const scanStart = Math.max(0, n - this.maxLen);
+        for (let p = scanStart; p < n; p++) {
+            const tail = this.buffer.slice(p);
+            if (this.isProperPrefixOfSurrogate(tail)) {
+                hold = Math.min(hold, p);
+                break; // earliest such p found
+            }
+        }
+        if (this.fuzzy) {
+            // Trailing run of non-whitespace = a token that may still be growing.
+            let w = n;
+            while (w > 0 && !/\s/.test(this.buffer[w - 1]))
+                w--;
+            if (w < n)
+                hold = Math.min(hold, w);
+        }
+        return hold;
+    }
+    isProperPrefixOfSurrogate(tail) {
+        if (tail.length === 0)
+            return false;
+        for (const s of this.surrogatesByLength) {
+            if (s.length > tail.length && s.startsWith(tail))
+                return true;
+        }
+        return false;
+    }
+    /** Exact longest-match replacement, then the controlled fuzzy pass. */
+    replaceSettled(text) {
+        if (text.length === 0)
+            return '';
+        // Exact pass.
+        let exact = '';
+        let i = 0;
+        while (i < text.length) {
+            const match = this.longestSurrogateAt(text, i);
+            if (match !== null) {
+                exact += this.vault.getBySurrogate(match).original;
+                this.restored += 1;
+                i += match.length;
+            }
+            else {
+                exact += text[i];
+                i += 1;
+            }
+        }
+        return this.fuzzy ? this.fuzzyPass(exact) : exact;
+    }
+    /**
+     * Longest surrogate matching at `pos` WITH word-boundary semantics: a
+     * surrogate whose first/last character is a word character must not be
+     * glued to another word character in the text. Without this, a short
+     * surrogate ('Cat') corrupts an ordinary word ('Catalog' -> 'Org Onealog').
+     * Structured surrogates (emails, IBANs, PEM blocks) are unaffected because
+     * their neighbours in real text are punctuation or whitespace, and a
+     * surrogate ending in punctuation imposes no trailing constraint at all.
+     * Model-added affixes ('Northwinds') are handled by the fuzzy pass, which
+     * re-attaches what it strips.
+     */
+    longestSurrogateAt(text, pos) {
+        for (const s of this.surrogatesByLength) {
+            if (pos + s.length > text.length || !text.startsWith(s, pos))
+                continue;
+            const end = pos + s.length;
+            const startsWord = WORD_CHAR.test(s[0]);
+            const endsWord = WORD_CHAR.test(s[s.length - 1]);
+            if (startsWord && pos > 0 && WORD_CHAR.test(text[pos - 1]))
+                continue;
+            if (endsWord && end < text.length && WORD_CHAR.test(text[end]))
+                continue;
+            return s;
+        }
+        return null;
+    }
+    /**
+     * Per-token fuzzy restoration of transformed surrogates. Splits on
+     * whitespace, keeps the separators, and rewrites only tokens that resolve
+     * to exactly one surrogate under case / possessive / plural relaxation.
+     */
+    fuzzyPass(text) {
+        const pieces = text.split(/(\s+)/); // keep whitespace as odd-indexed pieces
+        for (let k = 0; k < pieces.length; k += 2) {
+            const token = pieces[k];
+            if (token === undefined || token.length === 0)
+                continue;
+            const rewritten = this.fuzzyToken(token);
+            if (rewritten !== null) {
+                pieces[k] = rewritten;
+                this.restored += 1;
+            }
+        }
+        return pieces.join('');
+    }
+    /** Try to restore one whitespace-free token; null = leave it alone. */
+    fuzzyToken(token) {
+        // Peel surrounding punctuation so "Nils," and "(Nils)" still resolve;
+        // the peeled affixes are re-attached around the restored original.
+        const m = /^(\p{P}*)(.*?)(\p{P}*)$/u.exec(token);
+        if (m === null)
+            return null;
+        const [, lead, coreRaw, trail] = m;
+        if (coreRaw.length === 0)
+            return null;
+        const resolved = this.resolveFuzzyCore(coreRaw);
+        if (resolved === null)
+            return null; // zero or ambiguous → leave alone
+        // The stripped affix is re-attached to the ORIGINAL, so a model plural
+        // survives restoration ('Northwinds' -> 'Acme Corps') — except when the
+        // original already ends with the same letters, where re-attaching would
+        // only stutter ('Acme Holdings' + 's'). Either way the restored VALUE is
+        // right; perfect cross-language morphology is out of scope here.
+        const suffix = resolved.suffix.length > 0 && resolved.original.toLowerCase().endsWith(resolved.suffix.toLowerCase())
+            ? ''
+            : resolved.suffix;
+        return `${lead}${resolved.original}${suffix}${trail}`;
+    }
+    /**
+     * Resolve a core token to exactly one original, under case-fold plus
+     * possessive/plural stripping, carrying the affix that was stripped.
+     * Returns null when zero or MORE THAN ONE distinct original is reachable —
+     * SPEC.md's hard rule that ambiguous matches are left alone.
+     */
+    resolveFuzzyCore(core) {
+        const lower = core.toLowerCase();
+        const forms = [
+            [lower, ''],
+            [lower.replace(/['’]s$|['’]$/u, ''), core.slice(lower.replace(/['’]s$|['’]$/u, '').length)],
+            ...(/es$/i.test(core) ? [[lower.replace(/es$/i, ''), core.slice(core.length - 2)]] : []),
+            ...(/s$/i.test(core) ? [[lower.replace(/s$/i, ''), core.slice(core.length - 1)]] : []),
+        ];
+        const byOriginal = new Map();
+        for (const [form, suffix] of forms) {
+            if (form === '' || form === lower && suffix !== '')
+                continue;
+            const entries = this.fuzzyByLower.get(form);
+            if (entries === undefined)
+                continue;
+            for (const e of entries) {
+                if (!byOriginal.has(e.original))
+                    byOriginal.set(e.original, suffix);
+            }
+        }
+        if (byOriginal.size !== 1)
+            return null;
+        const [original, suffix] = [...byOriginal.entries()][0];
+        return { original, suffix };
+    }
+}
+/** One-shot restoration of a complete (non-streamed) response. */
+export function restore(text, vault, options = {}) {
+    const r = new Restorer(vault, options);
+    r.push(text);
+    r.finish();
+    return { restoredText: r.rendered, restoredCount: r.restoredCount, unmatchedReplacements: [] };
+}
+//# sourceMappingURL=restorer.js.map

package/dist/src/mask/restorer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restorer.js","sourceRoot":"","sources":["../../../src/mask/restorer.ts"],"names":[],"mappings":"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"}

package/dist/src/mask/surrogatePools.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Starter surrogate pools for the NER entity types (PERSON, ORG, LOCATION)
+ * and dates.
+ *
+ * These types are produced by Stage 2 (M6), which does not exist yet, so
+ * nothing in the M4 pipeline reaches them — but SPEC.md's substitution table
+ * requires them, and building the pools now lets the surrogate registry be
+ * complete and lets M6 plug in without touching this file's consumers.
+ *
+ * PERSON pools are grouped by SCRIPT and broad naming convention so that
+ * "Yuki Tanaka" is replaced by another East-Asian-convention name rather than
+ * "Bob Smith" (SPEC.md's explicit example). These are deliberately small,
+ * hand-picked, unmistakably-fictional pools; M7's gazetteers replace them
+ * with broad real-name coverage. Recorded in ARCHITECTURE.md D12.
+ */
+import type { ScriptName } from '../types.js';
+export interface PersonPool {
+    readonly script: ScriptName;
+    readonly given: readonly string[];
+    readonly surnames: readonly string[];
+    /** Order: given-first (Western) or family-first (East Asian). */
+    readonly order: 'given-first' | 'family-first';
+    /** Separator between the two parts. */
+    readonly sep: string;
+}
+export declare const PERSON_POOLS: readonly PersonPool[];
+/** Fallback pool when a detected script has no dedicated one. */
+export declare const DEFAULT_PERSON_POOL: PersonPool;
+/** Plausible fictional organization names. */
+export declare const ORG_POOL: readonly string[];
+/** Plausible fictional place names (cities). */
+export declare const LOCATION_POOL: readonly string[];
+//# sourceMappingURL=surrogatePools.d.ts.map

package/dist/src/mask/surrogatePools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surrogatePools.d.ts","sourceRoot":"","sources":["../../../src/mask/surrogatePools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,cAAc,CAAC;IAC/C,uCAAuC;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAmD7C,CAAC;AAEF,iEAAiE;AACjE,eAAO,MAAM,mBAAmB,YAAmB,CAAC;AAEpD,8CAA8C;AAC9C,eAAO,MAAM,QAAQ,EAAE,SAAS,MAAM,EAIrC,CAAC;AAEF,gDAAgD;AAChD,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAG1C,CAAC"}