@discretion/core 0.1.0

package/dist/src/mask/surrogatePools.js

@@ -0,0 +1,81 @@
+/**
+ * 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.
+ */
+export const PERSON_POOLS = [
+    {
+        script: 'latin', order: 'given-first', sep: ' ',
+        given: ['Alex', 'Maria', 'Sofia', 'Lucas', 'Elena', 'Marco', 'Nadia', 'Oscar', 'Petra', 'Ravi'],
+        surnames: ['Fontaine', 'Delacroix', 'Marchetti', 'Ellison', 'Vandel', 'Rourke', 'Sandoval', 'Keller'],
+    },
+    {
+        script: 'cyrillic', order: 'given-first', sep: ' ',
+        given: ['Ирина', 'Дмитрий', 'Ольга', 'Сергей', 'Наталья', 'Павел'],
+        surnames: ['Соколова', 'Морозов', 'Волкова', 'Лебедев', 'Козлова', 'Новиков'],
+    },
+    {
+        script: 'greek', order: 'given-first', sep: ' ',
+        given: ['Γιώργος', 'Ελένη', 'Νίκος', 'Μαρία', 'Κώστας'],
+        surnames: ['Παπαδόπουλος', 'Νικολάου', 'Γεωργίου', 'Δημητρίου'],
+    },
+    {
+        script: 'arabic', order: 'given-first', sep: ' ',
+        given: ['ليلى', 'أحمد', 'فاطمة', 'يوسف', 'زينب'],
+        surnames: ['الحسن', 'المنصور', 'الصالح', 'الرشيد'],
+    },
+    {
+        script: 'hebrew', order: 'given-first', sep: ' ',
+        given: ['נועה', 'איתי', 'תמר', 'יונתן'],
+        surnames: ['לוי', 'כהן', 'פרץ', 'ביטון'],
+    },
+    {
+        script: 'devanagari', order: 'given-first', sep: ' ',
+        given: ['आरव', 'दिया', 'विवान', 'सान्या'],
+        surnames: ['शर्मा', 'वर्मा', 'गुप्ता', 'सिंह'],
+    },
+    {
+        script: 'han', order: 'family-first', sep: '',
+        given: ['伟', '芳', '娜', '强', '敏', '静'],
+        surnames: ['王', '李', '张', '刘', '陈'],
+    },
+    {
+        script: 'kana', order: 'family-first', sep: '',
+        given: ['ゆき', 'はると', 'さくら', 'れん'],
+        surnames: ['田中', '佐藤', '鈴木', '高橋'],
+    },
+    {
+        script: 'hangul', order: 'family-first', sep: '',
+        given: ['민준', '서연', '지호', '하은'],
+        surnames: ['김', '이', '박', '최'],
+    },
+    {
+        script: 'thai', order: 'given-first', sep: ' ',
+        given: ['สมชาย', 'สุดา', 'ประเสริฐ'],
+        surnames: ['แซ่ตั้ง', 'ศรีสุข', 'บุญมี'],
+    },
+];
+/** Fallback pool when a detected script has no dedicated one. */
+export const DEFAULT_PERSON_POOL = PERSON_POOLS[0];
+/** Plausible fictional organization names. */
+export const ORG_POOL = [
+    'Northwind Systems', 'Brightpath Analytics', 'Cedar Grove Holdings', 'Meridian Labs',
+    'Quillfeather & Co.', 'Ashford Logistics', 'Blue Harbor Partners', 'Vireo Technologies',
+    'Sunspire Media', 'Gravel & Stone LLC',
+];
+/** Plausible fictional place names (cities). */
+export const LOCATION_POOL = [
+    'Fairmont', 'Elderbrook', 'Port Haven', 'Westmere', 'Ashville Bay',
+    'Cranleigh', 'Thornbury', 'Riverton', 'Oakmoor', 'Silverdale',
+];
+//# sourceMappingURL=surrogatePools.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"surrogatePools.js","sourceRoot":"","sources":["../../../src/mask/surrogatePools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAcH,MAAM,CAAC,MAAM,YAAY,GAA0B;IACjD;QACE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,GAAG;QAC/C,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC;QAC/F,QAAQ,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,CAAC;KACtG;IACD;QACE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,GAAG;QAClD,KAAK,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC;QAClE,QAAQ,EAAE,CAAC,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC;KAC9E;IACD;QACE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,GAAG;QAC/C,KAAK,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC;QACvD,QAAQ,EAAE,CAAC,cAAc,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,CAAC;KAChE;IACD;QACE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,GAAG;QAChD,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC;QAChD,QAAQ,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC;KACnD;IACD;QACE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,GAAG;QAChD,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC;QACvC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC;KACzC;IACD;QACE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,GAAG;QACpD,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC;QACzC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC;KAC/C;IACD;QACE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,EAAE;QAC7C,KAAK,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;QACrC,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;KACpC;IACD;QACE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,EAAE;QAC9C,KAAK,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC;QACjC,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC;KACnC;IACD;QACE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,EAAE;QAChD,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC;QAC/B,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;KAC/B;IACD;QACE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,GAAG;QAC9C,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC;QACpC,QAAQ,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC;KACzC;CACF,CAAC;AAEF,iEAAiE;AACjE,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAAC,CAAC,CAAE,CAAC;AAEpD,8CAA8C;AAC9C,MAAM,CAAC,MAAM,QAAQ,GAAsB;IACzC,mBAAmB,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,eAAe;IACpF,oBAAoB,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,oBAAoB;IACvF,gBAAgB,EAAE,oBAAoB;CACvC,CAAC;AAEF,gDAAgD;AAChD,MAAM,CAAC,MAAM,aAAa,GAAsB;IAC9C,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc;IAClE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY;CAC9D,CAAC"}

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

@@ -0,0 +1,45 @@
+/**
+ * The surrogate registry: given a detected entity, produce a same-shape
+ * replacement value.
+ *
+ * SPEC.md, substitution: replace a value with "a realistic value of the same
+ * type and shape" so the model reasons over coherent text, and for
+ * identifiers "a value passing that country's checksum, so downstream
+ * validation in the model's reasoning still behaves". We reuse the M2/M3
+ * generators as the source — a surrogate IBAN needs exactly the checksum
+ * validity a real one has, and that generator already exists.
+ *
+ * Two SPEC judgement calls, recorded in ARCHITECTURE.md D12:
+ *
+ *  • "Same country / same issuer." Honored where the detector's metadata
+ *    carries it: IBAN → same country, CREDIT_CARD → same issuer, national
+ *    identifiers → the SAME scheme's generator (a TCKN surrogate for a TCKN),
+ *    VAT → same member state, crypto → same chain, IP → same version.
+ *
+ *  • "SECRET → a same-shape dummy that is clearly non-functional." The reused
+ *    generators produce syntactically valid but RANDOM values (a JWT with a
+ *    random signature, a PEM with a random body, a provider token with a
+ *    random body) — non-functional because random, not because marked. That
+ *    satisfies "non-functional"; if a visibly-marked dummy is later wanted it
+ *    is a pool swap, not a structural change. Flagged, not silently resolved.
+ *
+ * `chooseSurrogate` returns `null` when no sensible surrogate exists for the
+ * type — the masker then falls back to a bracket token and records it, per
+ * SPEC.md's FALLBACK rule.
+ */
+import type { EntityType } from '../types.js';
+/** What the masker gives the registry about one detected value. */
+export interface SurrogateRequest {
+    readonly type: EntityType;
+    /** The matched text (normalized). Used for shape and script inference. */
+    readonly text: string;
+    /** Detector metadata: scheme, country, issuer, chain, version, kind. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Choose a surrogate for a detected entity. Returns the surrogate string, or
+ * `null` when the type has no sensible surrogate (masker → bracket token).
+ * `seed` varies across collision retries so a fresh value is produced.
+ */
+export declare function chooseSurrogate(req: SurrogateRequest, seed: number): string | null;
+//# sourceMappingURL=surrogates.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"surrogates.d.ts","sourceRoot":"","sources":["../../../src/mask/surrogates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAc,MAAM,aAAa,CAAC;AAK1D,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AA8FD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAwGlF"}

package/dist/src/mask/surrogates.js

@@ -0,0 +1,241 @@
+/**
+ * The surrogate registry: given a detected entity, produce a same-shape
+ * replacement value.
+ *
+ * SPEC.md, substitution: replace a value with "a realistic value of the same
+ * type and shape" so the model reasons over coherent text, and for
+ * identifiers "a value passing that country's checksum, so downstream
+ * validation in the model's reasoning still behaves". We reuse the M2/M3
+ * generators as the source — a surrogate IBAN needs exactly the checksum
+ * validity a real one has, and that generator already exists.
+ *
+ * Two SPEC judgement calls, recorded in ARCHITECTURE.md D12:
+ *
+ *  • "Same country / same issuer." Honored where the detector's metadata
+ *    carries it: IBAN → same country, CREDIT_CARD → same issuer, national
+ *    identifiers → the SAME scheme's generator (a TCKN surrogate for a TCKN),
+ *    VAT → same member state, crypto → same chain, IP → same version.
+ *
+ *  • "SECRET → a same-shape dummy that is clearly non-functional." The reused
+ *    generators produce syntactically valid but RANDOM values (a JWT with a
+ *    random signature, a PEM with a random body, a provider token with a
+ *    random body) — non-functional because random, not because marked. That
+ *    satisfies "non-functional"; if a visibly-marked dummy is later wanted it
+ *    is a pool swap, not a structural change. Flagged, not silently resolved.
+ *
+ * `chooseSurrogate` returns `null` when no sensible surrogate exists for the
+ * type — the masker then falls back to a bracket token and records it, per
+ * SPEC.md's FALLBACK rule.
+ */
+import * as generate from '../generate/index.js';
+import { detectScripts } from '../scripts.js';
+import { PERSON_POOLS, DEFAULT_PERSON_POOL, ORG_POOL, LOCATION_POOL } from './surrogatePools.js';
+const g = generate;
+const meta = (req, key) => {
+    const v = req.metadata?.[key];
+    return typeof v === 'string' ? v : undefined;
+};
+/** National/tax/vat scheme → the generator that produces a valid instance. */
+const SCHEME_GENERATORS = {
+    ssn: g.generateValidSsn, sin: g.generateValidSin, nino: g.generateValidNino, nhs: g.generateValidNhs,
+    pps: g.generateValidPps, 'steuer-id': g.generateValidSteuerId, personalausweis: g.generateValidAusweis,
+    nir: g.generateValidNir, dni: g.generateValidDni, nie: g.generateValidNie,
+    'codice-fiscale': g.generateValidCodiceFiscale, bsn: g.generateValidBsn, rijksregister: g.generateValidBeRrn,
+    pesel: g.generateValidPesel, nip: g.generateValidNip, regon: g.generateValidRegon,
+    personnummer: g.generateValidPersonnummer, fodselsnummer: g.generateValidFodselsnummer, cpr: g.generateValidCpr,
+    hetu: g.generateValidHetu, kennitala: g.generateValidKennitala, nif: g.generateValidPtNif, afm: g.generateValidAfm,
+    'rodne-cislo': g.generateValidRodneCislo, 'szemelyi-szam': g.generateValidSzemelyi, cnp: g.generateValidCnp,
+    egn: g.generateValidEgn, oib: g.generateValidOib, emso: g.generateValidEmso, tckn: g.generateValidTckn,
+    vkn: g.generateValidVkn, inn: g.generateValidInn12, snils: g.generateValidSnils, rnokpp: g.generateValidRnokpp,
+    iin: g.generateValidIin, 'teudat-zehut': g.generateValidTeudatZehut, 'saudi-id': g.generateValidSaudiId,
+    'emirates-id': g.generateValidEmiratesId, qid: g.generateValidQid, 'civil-id': g.generateValidKwCivilId,
+    aadhaar: g.generateValidAadhaar, pan: g.generateValidPan, ric: g.generateValidRic, 'tw-id': g.generateValidTwId,
+    'my-number': g.generateValidMyNumber, rrn: g.generateValidKrRrn, nric: g.generateValidNric, hkid: g.generateValidHkid,
+    cnic: g.generateValidCnic, nid: g.generateValidBdNid, mykad: g.generateValidMykad, nik: g.generateValidNik,
+    'thai-id': g.generateValidThaiId, cccd: g.generateValidCccd, psn: g.generateValidPsn, tfn: g.generateValidTfn,
+    medicare: g.generateValidMedicare, abn: g.generateValidAbn, ird: g.generateValidIrd, cpf: g.generateValidCpf,
+    cnpj: g.generateValidCnpj, curp: g.generateValidCurp, rfc: g.generateValidRfc, cuit: g.generateValidCuit,
+    rut: g.generateValidRut, nit: g.generateValidNit, 'za-id': g.generateValidZaId,
+};
+/** Bare-number schemes whose detector span is value-only but whose generator
+ *  emits a label — produce the bare value directly. */
+const BARE_VALUE_SCHEMES = {
+    cnie: (s) => {
+        const rng = g.mulberry32(s);
+        const L = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+        const prefix = rng() < 0.5 ? L[Math.floor(rng() * 26)] : L[Math.floor(rng() * 26)] + L[Math.floor(rng() * 26)];
+        let d = '';
+        for (let i = 0; i < 6; i++)
+            d += Math.floor(rng() * 10);
+        return `${prefix}${d}`;
+    },
+    nin: (s) => {
+        const rng = g.mulberry32(s);
+        let d = '';
+        for (let i = 0; i < 11; i++)
+            d += Math.floor(rng() * 10);
+        return d;
+    },
+    'ke-id': (s) => {
+        const rng = g.mulberry32(s);
+        let d = '';
+        for (let i = 0; i < 8; i++)
+            d += Math.floor(rng() * 10);
+        return d;
+    },
+    'ar-dni': (s) => {
+        const rng = g.mulberry32(s);
+        const n = 10_000_000 + Math.floor(rng() * 89_999_999);
+        return String(n).replace(/\B(?=(\d{3})+(?!\d))/g, '.');
+    },
+    'pe-dni': (s) => {
+        const rng = g.mulberry32(s);
+        let d = '';
+        for (let i = 0; i < 8; i++)
+            d += Math.floor(rng() * 10);
+        return d;
+    },
+    agencia: (s) => {
+        const rng = g.mulberry32(s);
+        let d = '';
+        for (let i = 0; i < 4; i++)
+            d += Math.floor(rng() * 10);
+        return rng() < 0.4 ? `${d}-${Math.floor(rng() * 10)}` : d;
+    },
+};
+/** Dominant script of the detected text, for PERSON surrogate matching. */
+function scriptOf(text) {
+    return detectScripts(text).dominant ?? 'latin';
+}
+function personSurrogate(text, seed) {
+    const script = scriptOf(text);
+    const pool = PERSON_POOLS.find((p) => p.script === script) ?? DEFAULT_PERSON_POOL;
+    const rng = g.mulberry32(seed);
+    const given = pool.given[Math.floor(rng() * pool.given.length)];
+    const surname = pool.surnames[Math.floor(rng() * pool.surnames.length)];
+    return pool.order === 'given-first' ? `${given}${pool.sep}${surname}` : `${surname}${pool.sep}${given}`;
+}
+/** A plausible ICD-10 code (letter + 2 digits + optional .subcode). */
+function icd10Surrogate(seed) {
+    const rng = g.mulberry32(seed);
+    const letters = 'ABCDEFGHIJKLMNOPRSTUVWXYZ';
+    const head = `${letters[Math.floor(rng() * letters.length)]}${Math.floor(rng() * 10)}${Math.floor(rng() * 10)}`;
+    return rng() < 0.6 ? `${head}.${Math.floor(rng() * 10)}` : head;
+}
+/**
+ * Choose a surrogate for a detected entity. Returns the surrogate string, or
+ * `null` when the type has no sensible surrogate (masker → bracket token).
+ * `seed` varies across collision retries so a fresh value is produced.
+ */
+export function chooseSurrogate(req, seed) {
+    switch (req.type) {
+        case 'EMAIL':
+            return g.generateValidEmail(seed);
+        case 'PHONE':
+            return g.generateValidPhone(seed);
+        case 'IP_ADDRESS':
+            return meta(req, 'version') === '6' || req.text.includes(':')
+                ? g.generateValidIpv6(seed)
+                : g.generateValidIpv4(seed);
+        case 'MAC_ADDRESS':
+            return g.generateValidMac(seed);
+        case 'URL_WITH_CREDENTIALS':
+            return g.generateValidCredentialUrl(seed);
+        case 'CREDIT_CARD':
+            return g.generateValidCardForIssuer(meta(req, 'issuer') ?? 'visa', seed);
+        case 'IBAN': {
+            const country = meta(req, 'country') ?? req.text.slice(0, 2).toUpperCase();
+            return g.generateValidIbanForCountry(country, seed);
+        }
+        case 'SWIFT_BIC':
+            return g.generateValidBic(seed);
+        case 'US_ROUTING_NUMBER':
+            return g.generateValidRouting(seed);
+        case 'UK_SORT_CODE':
+            return g.generateValidSortCode(seed);
+        case 'CA_TRANSIT_NUMBER':
+            return g.generateValidTransit(seed);
+        case 'AU_BSB':
+            return g.generateValidBsb(seed);
+        case 'IN_IFSC':
+            return g.generateValidIfsc(seed);
+        case 'BR_AGENCIA':
+            return BARE_VALUE_SCHEMES['agencia'](seed);
+        case 'CRYPTO_WALLET': {
+            const chain = meta(req, 'chain');
+            const byChain = {
+                btc: g.generateValidBtc, eth: g.generateValidEth, ltc: g.generateValidLtc, trx: g.generateValidTrx,
+                xmr: g.generateValidXmr, sol: g.generateValidSol, ada: g.generateValidAda, dot: g.generateValidDot,
+            };
+            return (chain !== undefined ? byChain[chain] : undefined)?.(seed) ?? g.generateValidBtc(seed);
+        }
+        case 'API_KEY':
+            return g.generateValidProviderToken(seed);
+        case 'JWT':
+            return g.generateValidJwt(seed);
+        case 'PRIVATE_KEY':
+            return g.generateValidPem(seed);
+        case 'GENERIC_SECRET':
+            return g.generateHighEntropySecret(seed);
+        case 'CONNECTION_STRING':
+            return g.generateValidConnectionString(seed);
+        case 'PASSPORT_MRZ':
+            return g.generateValidTd3(seed);
+        case 'DRIVERS_LICENSE':
+            return g.generateValidDvla(seed);
+        case 'VIN':
+            return g.generateValidVin(seed);
+        case 'US_NPI':
+            return g.generateValidNpi(seed);
+        case 'HEALTH_DATA': {
+            const kind = meta(req, 'kind');
+            if (kind === 'snomed')
+                return g.generateValidSctid(seed);
+            if (kind === 'lab-result')
+                return g.generateValidLabResult(seed);
+            if (kind === 'icd10')
+                return icd10Surrogate(seed);
+            return null; // bare-number SNOMED without kind, or an unmodeled shape
+        }
+        case 'POSTAL_CODE':
+            return g.generateValidPostal(seed);
+        case 'STREET_ADDRESS':
+            return g.generateValidStreet(seed);
+        case 'COORDINATES':
+            return g.generateValidCoordinates(seed);
+        case 'NATIONAL_ID':
+        case 'TAX_ID': {
+            const scheme = meta(req, 'scheme');
+            if (scheme !== undefined) {
+                const bare = BARE_VALUE_SCHEMES[scheme];
+                if (bare !== undefined)
+                    return bare(seed);
+                const gen = SCHEME_GENERATORS[scheme];
+                if (gen !== undefined)
+                    return gen(seed);
+            }
+            return null; // unknown scheme → token
+        }
+        case 'VAT_NUMBER': {
+            const country = meta(req, 'country') ?? req.text.slice(0, 2).toUpperCase();
+            const c = country === 'GR' ? 'EL' : country;
+            if (g.VAT_COUNTRIES.includes(c))
+                return g.generateValidVatFor(c, seed);
+            return g.generateValidEuVat(seed);
+        }
+        case 'PERSON':
+            return personSurrogate(req.text, seed);
+        case 'ORG':
+            return ORG_POOL[seed % ORG_POOL.length];
+        case 'LOCATION':
+            return LOCATION_POOL[seed % LOCATION_POOL.length];
+        case 'DATE_OF_BIRTH':
+            // Ordering-preserving date shifting needs a date detector (absent until
+            // a later milestone) and a session offset; until then no surrogate,
+            // so the masker uses a token. Recorded in ARCHITECTURE.md D12.
+            return null;
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=surrogates.js.map

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

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

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

@@ -0,0 +1,76 @@
+/**
+ * vault.ts — the in-memory bidirectional map between originals and their
+ * replacements.
+ *
+ * SPEC.md contract: deterministic and referentially consistent; normalized
+ * lookup so trivial variants (case, surrounding whitespace) resolve to one
+ * entry; clear() wipes it; and NO method exposes the full plaintext set
+ * except the egress guard, which needs it.
+ *
+ * That last rule is enforced by shape, not convention: the only bulk
+ * accessor is `createEgressAuditor()`, which returns a capability object
+ * whose sole consumer is `guardEgress`. Every other read requires already
+ * knowing the value being looked up (`getByOriginal`) or holds no plaintext
+ * (`getBySurrogate` returns the entry, whose `original` the restorer needs
+ * one at a time — that is restoration's whole job). There is deliberately
+ * no `entries()` / iteration API. (TypeScript cannot stop a caller from
+ * invoking the auditor factory, but the single, loudly-named door makes any
+ * misuse a visible code-review event rather than an accident. Recorded in
+ * ARCHITECTURE.md D11.)
+ *
+ * NORMALIZED LOOKUP is deliberately conservative. The lookup key folds
+ * case and trims/collapses whitespace, but a normalized key may be shared
+ * by DIFFERENT exact originals (two base58 values differing only in case
+ * are different values). The exact map always wins; the normalized index
+ * resolves a variant only when it maps to exactly one entry — an ambiguous
+ * normalized hit returns undefined rather than guessing.
+ */
+import type { EntityType, VaultEntry } from '../types.js';
+/** Case-folded, trimmed, inner-whitespace-collapsed lookup key. */
+export declare function normalizedKey(value: string): string;
+/** What the egress guard receives: the one deliberate door to plaintext. */
+export interface EgressAuditor {
+    /** Every entry: (exact original, canonical, id, type). Guard-only. */
+    auditEntries(): readonly {
+        original: string;
+        canonical: string;
+        id: string;
+        type: EntityType;
+    }[];
+}
+export declare class Vault {
+    private readonly byOriginal;
+    private readonly byCanonical;
+    private readonly byNormalized;
+    private readonly byReplacement;
+    private counter;
+    /**
+     * Register a new masked value. The caller (the masker) has already
+     * resolved consistency — `register` throws on a duplicate original or
+     * replacement rather than silently merging, because reaching that point
+     * means the masker's lookup logic is broken and restoration would be
+     * ambiguous.
+     */
+    register(entry: Omit<VaultEntry, 'id' | 'createdAt'>): VaultEntry;
+    /**
+     * Find the entry for an original: exact writing first, then the
+     * detector's canonical form (separator variants of one identifier), then
+     * the case/whitespace-normalized index — which only resolves when
+     * unambiguous.
+     */
+    getByOriginal(original: string, canonical?: string): VaultEntry | undefined;
+    /** Find the entry whose replacement is exactly `replacement`. */
+    getBySurrogate(replacement: string): VaultEntry | undefined;
+    /** True when `value` is already in use as a replacement or an original —
+     *  the collision check surrogate selection runs before committing. */
+    wouldCollide(value: string): boolean;
+    /** All current replacements (surrogates/tokens) — contains no originals;
+     *  the restorer builds its match tables from this. */
+    replacements(): readonly string[];
+    get size(): number;
+    /** Wipe everything. Called on navigation away and conversation switch. */
+    clear(): void;
+    /** THE one deliberate door to the plaintext set. Egress guard only. */
+    createEgressAuditor(): EgressAuditor;
+}
+//# sourceMappingURL=vault.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../../../src/mask/vault.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE1D,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,YAAY,IAAI,SAAS;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,UAAU,CAAA;KAAE,EAAE,CAAC;CAClG;AAED,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiC;IAC5D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiC;IAC7D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsC;IACnE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiC;IAC/D,OAAO,CAAC,OAAO,CAAK;IAEpB;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,GAAG,WAAW,CAAC,GAAG,UAAU;IA2BjE;;;;;OAKG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAc3E,iEAAiE;IACjE,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI3D;0EACsE;IACtE,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAapC;0DACsD;IACtD,YAAY,IAAI,SAAS,MAAM,EAAE;IAIjC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,0EAA0E;IAC1E,KAAK,IAAI,IAAI;IAOb,uEAAuE;IACvE,mBAAmB,IAAI,aAAa;CAWrC"}

package/dist/src/mask/vault.js

@@ -0,0 +1,141 @@
+/**
+ * vault.ts — the in-memory bidirectional map between originals and their
+ * replacements.
+ *
+ * SPEC.md contract: deterministic and referentially consistent; normalized
+ * lookup so trivial variants (case, surrounding whitespace) resolve to one
+ * entry; clear() wipes it; and NO method exposes the full plaintext set
+ * except the egress guard, which needs it.
+ *
+ * That last rule is enforced by shape, not convention: the only bulk
+ * accessor is `createEgressAuditor()`, which returns a capability object
+ * whose sole consumer is `guardEgress`. Every other read requires already
+ * knowing the value being looked up (`getByOriginal`) or holds no plaintext
+ * (`getBySurrogate` returns the entry, whose `original` the restorer needs
+ * one at a time — that is restoration's whole job). There is deliberately
+ * no `entries()` / iteration API. (TypeScript cannot stop a caller from
+ * invoking the auditor factory, but the single, loudly-named door makes any
+ * misuse a visible code-review event rather than an accident. Recorded in
+ * ARCHITECTURE.md D11.)
+ *
+ * NORMALIZED LOOKUP is deliberately conservative. The lookup key folds
+ * case and trims/collapses whitespace, but a normalized key may be shared
+ * by DIFFERENT exact originals (two base58 values differing only in case
+ * are different values). The exact map always wins; the normalized index
+ * resolves a variant only when it maps to exactly one entry — an ambiguous
+ * normalized hit returns undefined rather than guessing.
+ */
+/** Case-folded, trimmed, inner-whitespace-collapsed lookup key. */
+export function normalizedKey(value) {
+    return value.trim().replace(/\s+/g, ' ').toLowerCase();
+}
+export class Vault {
+    byOriginal = new Map();
+    byCanonical = new Map();
+    byNormalized = new Map();
+    byReplacement = new Map();
+    counter = 0;
+    /**
+     * Register a new masked value. The caller (the masker) has already
+     * resolved consistency — `register` throws on a duplicate original or
+     * replacement rather than silently merging, because reaching that point
+     * means the masker's lookup logic is broken and restoration would be
+     * ambiguous.
+     */
+    register(entry) {
+        if (this.byOriginal.has(entry.original)) {
+            throw new Error('vault: original already registered');
+        }
+        if (this.byReplacement.has(entry.replacement)) {
+            throw new Error('vault: replacement already in use');
+        }
+        const full = {
+            ...entry,
+            id: `v${++this.counter}`,
+            createdAt: Date.now(),
+        };
+        this.byOriginal.set(full.original, full);
+        if (full.canonical !== undefined) {
+            if (!this.byCanonical.has(full.canonical))
+                this.byCanonical.set(full.canonical, full);
+        }
+        const key = normalizedKey(full.original);
+        let set = this.byNormalized.get(key);
+        if (set === undefined) {
+            set = new Set();
+            this.byNormalized.set(key, set);
+        }
+        set.add(full);
+        this.byReplacement.set(full.replacement, full);
+        return full;
+    }
+    /**
+     * Find the entry for an original: exact writing first, then the
+     * detector's canonical form (separator variants of one identifier), then
+     * the case/whitespace-normalized index — which only resolves when
+     * unambiguous.
+     */
+    getByOriginal(original, canonical) {
+        const exact = this.byOriginal.get(original);
+        if (exact !== undefined)
+            return exact;
+        if (canonical !== undefined) {
+            const viaCanonical = this.byCanonical.get(canonical);
+            if (viaCanonical !== undefined)
+                return viaCanonical;
+        }
+        const set = this.byNormalized.get(normalizedKey(original));
+        if (set !== undefined && set.size === 1) {
+            return set.values().next().value;
+        }
+        return undefined;
+    }
+    /** Find the entry whose replacement is exactly `replacement`. */
+    getBySurrogate(replacement) {
+        return this.byReplacement.get(replacement);
+    }
+    /** True when `value` is already in use as a replacement or an original —
+     *  the collision check surrogate selection runs before committing. */
+    wouldCollide(value) {
+        if (this.byReplacement.has(value))
+            return true;
+        if (this.byOriginal.has(value))
+            return true;
+        // Case-insensitive replacement uniqueness: the restorer's fuzzy pass
+        // (case-changed surrogates) is only sound when no two replacements
+        // collide case-insensitively.
+        const key = normalizedKey(value);
+        for (const replacement of this.byReplacement.keys()) {
+            if (normalizedKey(replacement) === key)
+                return true;
+        }
+        return this.byNormalized.has(key);
+    }
+    /** All current replacements (surrogates/tokens) — contains no originals;
+     *  the restorer builds its match tables from this. */
+    replacements() {
+        return [...this.byReplacement.keys()];
+    }
+    get size() {
+        return this.byOriginal.size;
+    }
+    /** Wipe everything. Called on navigation away and conversation switch. */
+    clear() {
+        this.byOriginal.clear();
+        this.byCanonical.clear();
+        this.byNormalized.clear();
+        this.byReplacement.clear();
+    }
+    /** THE one deliberate door to the plaintext set. Egress guard only. */
+    createEgressAuditor() {
+        return {
+            auditEntries: () => [...this.byOriginal.values()].map((e) => ({
+                original: e.original,
+                canonical: e.canonical ?? e.original,
+                id: e.id,
+                type: e.type,
+            })),
+        };
+    }
+}
+//# sourceMappingURL=vault.js.map

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

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