@llm4ts/shell 2.12.0 → 2.13.0

package/kits/soap-ace/flows/lib/soap/Mapping.js

@@ -0,0 +1,130 @@
+import * as Schema from "effect/Schema";
+import { elementByName, localName } from "./Catalog.js";
+import { schemaPaths } from "./Analysis.js";
+import { simpleView } from "./Instance.js";
+// The deterministic 1:1 mapping: every XSD path of every request and
+// response, with the JSON path and JSON type a literal facade would give it.
+// It is the traceability base the REST design overlays: a design property
+// cites one of these paths, and the design check verifies the path exists.
+export class MappedField extends Schema.Class("MappedField")({
+    /** XSD path relative to the message element, `[]` for repeated elements. */
+    xsd: Schema.String,
+    /** The same field in a literal JSON facade, `$.a[*].b`. */
+    json: Schema.String,
+    jsonType: Schema.Literals(["string", "integer", "number", "boolean", "object", "array"]),
+    format: Schema.optionalKey(Schema.String),
+    xsdType: Schema.String,
+    required: Schema.Boolean,
+    repeated: Schema.Boolean,
+    enumeration: Schema.optionalKey(Schema.Array(Schema.String))
+}) {
+}
+export class OperationMapping extends Schema.Class("OperationMapping")({
+    operation: Schema.String,
+    request: Schema.String,
+    response: Schema.optionalKey(Schema.String),
+    requestFields: Schema.Array(MappedField),
+    responseFields: Schema.Array(MappedField)
+}) {
+}
+export class ServiceMapping extends Schema.Class("ServiceMapping")({
+    version: Schema.Literal(1),
+    operations: Schema.Array(OperationMapping)
+}) {
+}
+const integerBuiltins = new Set([
+    "int",
+    "integer",
+    "short",
+    "byte",
+    "nonNegativeInteger",
+    "positiveInteger",
+    "nonPositiveInteger",
+    "negativeInteger",
+    "unsignedInt",
+    "unsignedShort",
+    "unsignedByte"
+]);
+/** JSON type and format for an XSD type; decimals stay strings (exact amounts). */
+export const jsonTypeOf = (catalog, type) => {
+    const builtin = simpleView(catalog, type).builtin;
+    if (integerBuiltins.has(builtin))
+        return { jsonType: "integer", format: "int32" };
+    if (builtin === "long" || builtin === "unsignedLong")
+        return { jsonType: "integer", format: "int64" };
+    if (builtin === "decimal")
+        return { jsonType: "string", format: "decimal" };
+    if (builtin === "float" || builtin === "double")
+        return { jsonType: "number", format: builtin };
+    if (builtin === "boolean")
+        return { jsonType: "boolean" };
+    if (builtin === "date")
+        return { jsonType: "string", format: "date" };
+    if (builtin === "dateTime")
+        return { jsonType: "string", format: "date-time" };
+    if (builtin === "base64Binary")
+        return { jsonType: "string", format: "byte" };
+    return { jsonType: "string" };
+};
+const jsonPath = (xsd) => `$.${xsd.replace(/\[\]/g, "[*]").replace(/@/g, "")}`;
+export const mapElement = (catalog, element) => schemaPaths(catalog, element).map((path) => {
+    const container = !path.leaf;
+    const typed = container ? { jsonType: "object" } : jsonTypeOf(catalog, path.type);
+    const enumeration = container
+        ? undefined
+        : simpleView(catalog, path.type).facets.find((facets) => facets.enumeration !== undefined)
+            ?.enumeration;
+    return new MappedField({
+        xsd: path.path,
+        json: jsonPath(path.path),
+        jsonType: path.repeated ? "array" : typed.jsonType,
+        ...("format" in typed && typed.format !== undefined ? { format: typed.format } : {}),
+        xsdType: localName(path.type).replace(/^~/, ""),
+        required: !path.optional,
+        repeated: path.repeated,
+        ...(enumeration === undefined ? {} : { enumeration })
+    });
+});
+export const mapService = (catalog) => new ServiceMapping({
+    version: 1,
+    operations: catalog.operations.map((operation) => {
+        const input = elementByName(catalog, operation.input);
+        const output = operation.output === undefined ? undefined : elementByName(catalog, operation.output);
+        return new OperationMapping({
+            operation: operation.name,
+            request: localName(operation.input),
+            ...(operation.output === undefined ? {} : { response: localName(operation.output) }),
+            requestFields: input === undefined ? [] : mapElement(catalog, input),
+            responseFields: output === undefined ? [] : mapElement(catalog, output)
+        });
+    })
+});
+const row = (field) => `| ${field.xsd} | ${field.json} | ${field.jsonType}${field.format === undefined ? "" : ` (${field.format})`} | ${field.xsdType} | ${field.required ? "yes" : "no"} | ${field.enumeration?.join(", ") ?? ""} |`;
+export const renderMapping = (mapping) => [
+    "# 1:1 mapping",
+    "",
+    "Every request and response field with the JSON path and type a literal facade would use.",
+    "The REST design cites these XSD paths; generated by soap-design, regenerate rather than edit.",
+    "",
+    ...mapping.operations.flatMap((operation) => [
+        `## ${operation.operation}`,
+        "",
+        `Request \`${operation.request}\`:`,
+        "",
+        "| XSD path | JSON path | JSON type | XSD type | required | enumeration |",
+        "| --- | --- | --- | --- | --- | --- |",
+        ...operation.requestFields.map(row),
+        "",
+        ...(operation.response === undefined
+            ? ["One-way operation: no response.", ""]
+            : [
+                `Response \`${operation.response}\`:`,
+                "",
+                "| XSD path | JSON path | JSON type | XSD type | required | enumeration |",
+                "| --- | --- | --- | --- | --- | --- |",
+                ...operation.responseFields.map(row),
+                ""
+            ])
+    ])
+].join("\n");
+export const encodeMapping = (mapping) => `${JSON.stringify(Schema.encodeSync(ServiceMapping)(mapping), null, 2)}\n`;

package/kits/soap-ace/flows/lib/soap/Masking.js

@@ -0,0 +1,508 @@
+import { createHmac } from "node:crypto";
+import * as Schema from "effect/Schema";
+import { ComplexTypeDef, localName } from "./Catalog.js";
+// Always-on masking of SOAP samples before they are persisted or shown to a
+// model. Two signals decide what is personal data: the field (its element
+// name, or its XSD type in the catalog) and the value itself (checksummed
+// identifiers found anywhere in text). Every replacement is a keyed,
+// deterministic, format-preserving pseudonym: the same input maps to the same
+// output under one service key, so "the account in the request is the
+// account echoed in the response" survives masking, and a masked IBAN, codice
+// fiscale, partita IVA, or PAN still passes its checksum. There is no switch
+// to turn this off.
+export const MaskKind = Schema.Literals([
+    "iban",
+    "codice-fiscale",
+    "partita-iva",
+    "pan",
+    "email",
+    "phone",
+    "personal-text",
+    "birth-date",
+    "secret"
+]);
+export const MaskOverride = Schema.Literals(["mask", "keep"]);
+/** `masking.json`: per-field overrides keyed by element local name. */
+export class MaskingOverrides extends Schema.Class("MaskingOverrides")({
+    fields: Schema.Record(Schema.String, MaskOverride)
+}) {
+}
+export const MaskSource = Schema.Literals(["field-name", "field-type", "value", "override"]);
+export class MaskEntry extends Schema.Class("MaskEntry")({
+    /** Element path from the document root, local names joined by `/`. */
+    path: Schema.String,
+    kind: MaskKind,
+    source: MaskSource,
+    count: Schema.Int
+}) {
+}
+export class MaskingReport extends Schema.Class("MaskingReport")({
+    entries: Schema.Array(MaskEntry),
+    /** Fields a `keep` override left untouched even though a rule matched. */
+    kept: Schema.Array(Schema.String)
+}) {
+}
+// ---------------------------------------------------------------------------
+// Checksums
+const digitsOnly = /^\d+$/;
+/** Italian CIN / codice fiscale tables: value of a character at an odd (1-based) position. */
+const oddValues = (() => {
+    const table = [
+        1, 0, 5, 7, 9, 13, 15, 17, 19, 21, 2, 4, 18, 20, 11, 3, 6, 8, 12, 14, 16, 10, 22, 25, 24, 23
+    ];
+    const values = {};
+    for (let index = 0; index < 10; index++)
+        values[String(index)] = table[index] ?? 0;
+    for (let index = 0; index < 26; index++) {
+        values[String.fromCharCode(65 + index)] = table[index] ?? 0;
+    }
+    return values;
+})();
+const evenValue = (char) => /\d/.test(char) ? Number(char) : char.charCodeAt(0) - 65;
+/** Check letter over `chars` using the codice fiscale / CIN odd-even tables. */
+export const italianCheckLetter = (chars) => {
+    let sum = 0;
+    for (let index = 0; index < chars.length; index++) {
+        const char = chars[index] ?? "0";
+        sum += index % 2 === 0 ? (oddValues[char] ?? 0) : evenValue(char);
+    }
+    return String.fromCharCode(65 + (sum % 26));
+};
+const ibanRemainder = (iban) => {
+    const rearranged = `${iban.slice(4)}${iban.slice(0, 4)}`;
+    let remainder = 0;
+    for (const char of rearranged) {
+        const value = /\d/.test(char) ? char : String(char.charCodeAt(0) - 55);
+        for (const digit of value)
+            remainder = (remainder * 10 + Number(digit)) % 97;
+    }
+    return remainder;
+};
+export const isValidIban = (value) => /^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/.test(value) && ibanRemainder(value) === 1;
+const withIbanCheckDigits = (country, bban) => {
+    const check = 98 - ibanRemainder(`${country}00${bban}`);
+    return `${country}${String(check).padStart(2, "0")}${bban}`;
+};
+const cfPattern = /^[A-Z]{6}[0-9LMNPQRSTUV]{2}[ABCDEHLMPRST][0-9LMNPQRSTUV]{2}[A-Z][0-9LMNPQRSTUV]{3}[A-Z]$/;
+export const isValidCodiceFiscale = (value) => cfPattern.test(value) && italianCheckLetter(value.slice(0, 15)) === value[15];
+const luhnSum = (digits, doubleFirst) => {
+    let sum = 0;
+    let double = doubleFirst;
+    for (let index = digits.length - 1; index >= 0; index--) {
+        let digit = Number(digits[index]);
+        if (double) {
+            digit *= 2;
+            if (digit > 9)
+                digit -= 9;
+        }
+        sum += digit;
+        double = !double;
+    }
+    return sum;
+};
+export const isValidLuhn = (value) => digitsOnly.test(value) && luhnSum(value, false) % 10 === 0;
+const luhnCheckDigit = (payload) => String((10 - (luhnSum(payload, true) % 10)) % 10);
+export const isValidPan = (value) => /^[2-6]\d{12,18}$/.test(value) && isValidLuhn(value);
+const partitaIvaCheck = (first10) => {
+    let sum = 0;
+    for (let index = 0; index < 10; index++) {
+        let digit = Number(first10[index]);
+        if (index % 2 === 1) {
+            digit *= 2;
+            if (digit > 9)
+                digit -= 9;
+        }
+        sum += digit;
+    }
+    return String((10 - (sum % 10)) % 10);
+};
+export const isValidPartitaIva = (value) => /^\d{11}$/.test(value) && partitaIvaCheck(value.slice(0, 10)) === value[10];
+const makeDrawer = (key, kind, value) => {
+    let block = 0;
+    let bytes = new Uint8Array(0);
+    let offset = 0;
+    const next = () => {
+        if (offset >= bytes.length) {
+            bytes = createHmac("sha256", key).update(`${kind}\u0000${value}\u0000${block}`).digest();
+            block++;
+            offset = 0;
+        }
+        const byte = bytes[offset] ?? 0;
+        offset++;
+        return byte;
+    };
+    const int = (bound) => {
+        // Rejection sampling over two bytes keeps the draw unbiased.
+        const limit = 65536 - (65536 % bound);
+        for (;;) {
+            const candidate = next() * 256 + next();
+            if (candidate < limit)
+                return candidate % bound;
+        }
+    };
+    return {
+        digit: () => String(int(10)),
+        letter: () => String.fromCharCode(65 + int(26)),
+        int
+    };
+};
+/** Replace every letter and digit by one of the same class and case; keep the rest. */
+const scramble = (draw, value) => Array.from(value, (char) => {
+    if (/\d/.test(char))
+        return draw.digit();
+    if (/[A-Z]/.test(char))
+        return draw.letter();
+    if (/[a-z]/.test(char))
+        return draw.letter().toLowerCase();
+    if (/\p{Lu}/u.test(char))
+        return draw.letter();
+    if (/\p{Ll}/u.test(char))
+        return draw.letter().toLowerCase();
+    return char;
+}).join("");
+const omocodia = {
+    L: "0",
+    M: "1",
+    N: "2",
+    P: "3",
+    Q: "4",
+    R: "5",
+    S: "6",
+    T: "7",
+    U: "8",
+    V: "9"
+};
+const pseudonyms = {
+    // Country, ABI and CAB are bank data, not personal: kept, so analysis can
+    // still tell banks apart. The account part is replaced class for class and
+    // the Italian CIN and the IBAN check digits are recomputed.
+    iban: (draw, value) => {
+        const country = value.slice(0, 2);
+        if (country === "IT" && value.length === 27) {
+            const abiCab = value.slice(5, 15);
+            const account = scramble(draw, value.slice(15));
+            const cin = italianCheckLetter(`${abiCab}${account}`);
+            return withIbanCheckDigits("IT", `${cin}${abiCab}${account}`);
+        }
+        return withIbanCheckDigits(country, scramble(draw, value.slice(4)));
+    },
+    // New surname/name letters, birth year, month, day (sex kept), and comune;
+    // omocodia is normalized away; the check letter is recomputed.
+    "codice-fiscale": (draw, value) => {
+        const letters = Array.from({ length: 6 }, () => draw.letter()).join("");
+        const year = `${draw.digit()}${draw.digit()}`;
+        const month = "ABCDEHLMPRST"[draw.int(12)] ?? "A";
+        const originalDay = Number(Array.from(value.slice(9, 11), (char) => omocodia[char] ?? char).join(""));
+        const day = String(1 + draw.int(28) + (originalDay > 40 ? 40 : 0)).padStart(2, "0");
+        const comune = `${draw.letter()}${draw.digit()}${draw.digit()}${draw.digit()}`;
+        const body = `${letters}${year}${month}${day}${comune}`;
+        return `${body}${italianCheckLetter(body)}`;
+    },
+    // Matricola replaced, provincial office code kept, check digit recomputed.
+    "partita-iva": (draw, value) => {
+        const first10 = `${Array.from({ length: 7 }, () => draw.digit()).join("")}${value.slice(7, 10)}`;
+        return `${first10}${partitaIvaCheck(first10)}`;
+    },
+    // Issuer BIN (first six) kept, account digits replaced, Luhn recomputed.
+    pan: (draw, value) => {
+        const payload = `${value.slice(0, 6)}${Array.from({ length: value.length - 7 }, () => draw.digit()).join("")}`;
+        return `${payload}${luhnCheckDigit(payload)}`;
+    },
+    email: (draw, value) => {
+        const at = value.lastIndexOf("@");
+        return `${scramble(draw, value.slice(0, at))}@example.invalid`;
+    },
+    // International prefix and the first three digits (operator or area) kept.
+    phone: (draw, value) => {
+        const prefix = /^(\+\d{2}|00\d{2})?\s*\d{0,3}/.exec(value)?.[0] ?? "";
+        return `${prefix}${scramble(draw, value.slice(prefix.length))}`;
+    },
+    "personal-text": scramble,
+    // Shifted by up to a year either way; format kept.
+    "birth-date": (draw, value) => {
+        const match = /^(\d{4})-(\d{2})-(\d{2})(.*)$/.exec(value);
+        if (match === null)
+            return scramble(draw, value);
+        const date = new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3])));
+        date.setUTCDate(date.getUTCDate() + draw.int(731) - 365);
+        return `${date.toISOString().slice(0, 10)}${match[4] ?? ""}`;
+    },
+    secret: scramble
+};
+// A field named for one kind can hold another shape (a company's
+// `codiceFiscale` is its 11-digit partita IVA). The structured pseudonym
+// only applies when the value has its kind's shape; otherwise the value is
+// scrambled class for class, which keeps its length and character classes.
+const shapes = {
+    iban: /^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/,
+    "codice-fiscale": cfPattern,
+    "partita-iva": /^\d{11}$/,
+    pan: /^\d{13,19}$/,
+    email: /^[^@\s]+@[^@\s]+$/
+};
+const effectiveKind = (kind, value) => {
+    const shape = shapes[kind];
+    if (shape === undefined || shape.test(value))
+        return kind;
+    if (kind === "codice-fiscale" && /^\d{11}$/.test(value))
+        return "partita-iva";
+    return "personal-text";
+};
+/** The pseudonym of one value; stable for a given key. */
+export const pseudonymize = (key, kind, value) => {
+    const effective = effectiveKind(kind, value);
+    return pseudonyms[effective](makeDrawer(key, effective, value), value);
+};
+// ---------------------------------------------------------------------------
+// Detection
+/** camelCase, PascalCase, snake_case and kebab-case words, lower-cased. */
+export const nameWords = (name) => name
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+    .split(/[\s_\-.]+/)
+    .filter((word) => word !== "")
+    .map((word) => word.toLowerCase());
+const wordRules = [
+    ["iban", ["iban"]],
+    ["codice-fiscale", ["cf", "codicefiscale", "codfisc", "fiscalcode", "taxcode"]],
+    ["partita-iva", ["piva", "partitaiva", "vat", "vatnumber"]],
+    ["pan", ["pan", "cardnumber"]],
+    ["email", ["email", "mail", "pec"]],
+    ["phone", ["telefono", "cellulare", "phone", "mobile", "fax", "tel"]],
+    ["birth-date", []],
+    ["secret", ["otp", "pin", "cvv", "cvc", "password", "pwd", "segreto"]],
+    [
+        "personal-text",
+        [
+            "nome",
+            "cognome",
+            "intestatario",
+            "cointestatario",
+            "cointestatari",
+            "nominativo",
+            "nominativi",
+            "firmatario",
+            "delegato",
+            "referente",
+            "beneficiario",
+            "ordinante",
+            "titolare",
+            "ragione",
+            "denominazione",
+            "name",
+            "surname",
+            "firstname",
+            "lastname",
+            "fullname",
+            "holder",
+            "indirizzo",
+            "via",
+            "civico",
+            "cap",
+            "localita",
+            "residenza",
+            "address",
+            "street",
+            "zip",
+            "postcode"
+        ]
+    ]
+];
+// Multi-word names whose words alone would not match.
+const phraseRules = [
+    ["codice-fiscale", /^codice fiscale$|^cod fisc$/],
+    ["partita-iva", /partita iva/],
+    ["pan", /numero carta|card number|pan carta/],
+    ["birth-date", /data (di )?nascita|birth ?date|date of birth|dob/],
+    ["personal-text", /luogo (di )?nascita|ragione sociale|place of birth/],
+    ["secret", /codice (otp|pin|segreto)/]
+];
+/** The kind a field's name implies, if any. */
+export const kindForName = (name) => {
+    const words = nameWords(name);
+    const phrase = words.join(" ");
+    for (const [kind, pattern] of phraseRules)
+        if (pattern.test(phrase))
+            return kind;
+    const joined = words.join("");
+    for (const [kind, candidates] of wordRules) {
+        if (candidates.includes(joined) || words.some((word) => candidates.includes(word)))
+            return kind;
+    }
+    return undefined;
+};
+/**
+ * Field names whose declared XSD type implies a kind (`iban` of type
+ * `IbanType`, `cf` of type `CodiceFiscaleType`), from the catalog.
+ */
+export const kindsFromCatalog = (catalog) => {
+    const kinds = new Map();
+    for (const type of catalog.types) {
+        if (!(type instanceof ComplexTypeDef))
+            continue;
+        for (const field of type.fields) {
+            const kind = kindForName(localName(field.type).replace(/Type$/, ""));
+            if (kind !== undefined && !kinds.has(field.name))
+                kinds.set(field.name, kind);
+        }
+    }
+    return kinds;
+};
+const compact = (value) => value.replace(/\s+/g, "").toUpperCase();
+// Identifiers as people type them: upper or lower case, IBANs in groups of
+// four. A match is normalized (spaces out, upper case) before the checksum
+// and the pseudonym, so every spelling of one IBAN maps to one pseudonym.
+const valueDetectors = [
+    {
+        kind: "iban",
+        // Compact, or in groups of four as printed on statements.
+        pattern: /\b[A-Za-z]{2}\d{2}(?:(?: [A-Za-z0-9]{4}){2,7}(?: [A-Za-z0-9]{1,3})?|[A-Za-z0-9]{11,30})\b/g,
+        normalize: compact,
+        accept: isValidIban
+    },
+    {
+        kind: "codice-fiscale",
+        pattern: /\b[A-Za-z]{6}[0-9LMNPQRSTUVlmnpqrstuv]{2}[A-Za-z][0-9LMNPQRSTUVlmnpqrstuv]{2}[A-Za-z][0-9LMNPQRSTUVlmnpqrstuv]{3}[A-Za-z]\b/g,
+        normalize: compact,
+        accept: isValidCodiceFiscale
+    },
+    { kind: "pan", pattern: /\b[2-6]\d{12,18}\b/g, normalize: (match) => match, accept: isValidPan },
+    {
+        kind: "partita-iva",
+        pattern: /(?<=\bIT ?)\d{11}\b/gi,
+        normalize: (match) => match,
+        accept: isValidPartitaIva
+    },
+    {
+        kind: "email",
+        pattern: /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g,
+        normalize: (match) => match,
+        accept: () => true
+    },
+    {
+        kind: "phone",
+        pattern: /(?:\+39|0039)[\s-]?(?:\d[\s-]?){6,11}\d/g,
+        normalize: (match) => match,
+        accept: () => true
+    }
+];
+class Tally {
+    counts = new Map();
+    kept = new Set();
+    add(path, kind, source) {
+        const key = `${path}\u0000${kind}\u0000${source}`;
+        const current = this.counts.get(key);
+        if (current === undefined)
+            this.counts.set(key, { path, kind, source, count: 1 });
+        else
+            current.count++;
+    }
+    report() {
+        return new MaskingReport({
+            entries: [...this.counts.values()]
+                .sort((left, right) => left.path.localeCompare(right.path) || left.kind.localeCompare(right.kind))
+                .map((entry) => new MaskEntry(entry)),
+            kept: [...this.kept].sort()
+        });
+    }
+}
+/**
+ * Mask detected identifiers inside free text; returns the text and what was
+ * found. Every detector runs on the original text and overlapping matches
+ * go to the earlier detector, so a pseudonym is never masked again.
+ */
+export const maskText = (key, text) => {
+    const found = [];
+    for (const detector of valueDetectors) {
+        for (const match of text.matchAll(detector.pattern)) {
+            const start = match.index;
+            const end = start + match[0].length;
+            const normalized = detector.normalize(match[0]);
+            if (!detector.accept(normalized))
+                continue;
+            if (found.some((other) => start < other.end && end > other.start))
+                continue;
+            found.push({ start, end, kind: detector.kind, normalized });
+        }
+    }
+    found.sort((left, right) => left.start - right.start);
+    let result = "";
+    let cursor = 0;
+    for (const match of found) {
+        result += text.slice(cursor, match.start) + pseudonymize(key, match.kind, match.normalized);
+        cursor = match.end;
+    }
+    return { text: result + text.slice(cursor), kinds: found.map((match) => match.kind) };
+};
+const ruleFor = (name, options) => {
+    const override = options.overrides?.fields[name];
+    const named = kindForName(name);
+    const typed = options.typeKinds?.get(name);
+    const kind = named ?? typed;
+    if (override === "keep")
+        return { kind, source: undefined, keep: true };
+    if (override === "mask") {
+        return { kind: kind ?? "personal-text", source: "override", keep: false };
+    }
+    return {
+        kind,
+        source: named !== undefined ? "field-name" : typed !== undefined ? "field-type" : undefined,
+        keep: false
+    };
+};
+/**
+ * Mask one parsed document (a SOAP envelope, request or response). Returns
+ * the masked tree and the report of what was replaced where. Element and
+ * attribute names, structure, and namespaces are never changed.
+ */
+export const maskDocument = (root, options) => {
+    const tally = new Tally();
+    const maskValue = (value, path, rule) => {
+        if (rule.keep) {
+            if (rule.kind !== undefined || maskText(options.key, value).kinds.length > 0) {
+                tally.kept.add(path);
+            }
+            return value;
+        }
+        if (rule.kind !== undefined && rule.source !== undefined && value.trim() !== "") {
+            tally.add(path, rule.kind, rule.source);
+            const leading = /^\s*/.exec(value)?.[0] ?? "";
+            const trailing = /\s*$/.exec(value)?.[0] ?? "";
+            const core = value.trim();
+            return `${leading}${pseudonymize(options.key, rule.kind, core)}${trailing}`;
+        }
+        const found = maskText(options.key, value);
+        for (const kind of found.kinds)
+            tally.add(path, kind, "value");
+        return found.text;
+    };
+    const walk = (element, parentPath) => {
+        const path = parentPath === "" ? element.name.local : `${parentPath}/${element.name.local}`;
+        const rule = ruleFor(element.name.local, options);
+        const attributes = element.attributes.map((attribute) => {
+            const attributePath = `${path}/@${attribute.name.local}`;
+            return {
+                ...attribute,
+                value: maskValue(attribute.value, attributePath, ruleFor(attribute.name.local, options))
+            };
+        });
+        const children = element.children.map((child) => child._tag === "text"
+            ? { _tag: "text", value: maskValue(child.value, path, rule) }
+            : walk(child, path));
+        return { ...element, attributes, children };
+    };
+    return { document: walk(root, ""), report: tally.report() };
+};
+/** Merge per-document reports into one (counts summed per path, kind, source). */
+export const mergeReports = (reports) => {
+    const tally = new Tally();
+    for (const report of reports) {
+        for (const entry of report.entries) {
+            for (let index = 0; index < entry.count; index++)
+                tally.add(entry.path, entry.kind, entry.source);
+        }
+        for (const kept of report.kept)
+            tally.kept.add(kept);
+    }
+    return tally.report();
+};