euredact 0.5.0 → 0.6.0

package/dist/esm/rules/suppressors.js

@@ -309,9 +309,85 @@ function suppressSequential(_text, match) {
     const clean = match.text.replace(/[\s.\-]/g, "");
     return SEQUENTIAL_PATTERNS.test(clean);
 }
+// ── The engine's own output ───────────────────────────────────────────────
+//
+// Redaction has to be idempotent: running it over a document it already
+// produced must leave the placeholders it wrote alone. It did not.
+// `[POSTAL_CODE]` is thirteen characters of mixed case with an underscore, so
+// the entropy-based SECRET rule read it as a credential and a second pass
+// replaced it with `[SECRET]` (rules-engine#33).
+//
+// All three emitted forms are guarded, because all three come back as input in
+// a re-processing pipeline: `[TYPE]`, `TYPE_1` (referentialIntegrity) and
+// `TYPE_K7Q2` (tokenize -- where a false detection breaks restore()).
+//
+// Only real entity-type names count. Guarding any bracketed upper-case token
+// would be simpler and wrong: `[AKIAIOSFODNN7EXAMPLE]` is one, and also a live
+// AWS key. A placeholder for a *custom* pattern is therefore not covered.
+// The closing bracket is optional: another pattern's span need not agree with
+// this one about where the marker ends. The assigned-secret rule stops before
+// sentence punctuation (rules-engine#35), so it claims "[POSTAL_CODE" without
+// the "]". The opening bracket is still required.
+const PLACEHOLDER = /^(?:\[([A-Z][A-Z0-9_]*)\]?|([A-Z][A-Z0-9_]*?)_(?:\d+|[A-HJ-NP-Z2-9]{4}))$/;
+const KNOWN_TYPE_NAMES = new Set(Object.values(EntityType));
+function suppressRedactionPlaceholder(_text, match) {
+    const found = PLACEHOLDER.exec(match.text);
+    if (found === null)
+        return false;
+    const name = found[1] ?? found[2];
+    return KNOWN_TYPE_NAMES.has(name);
+}
 const RECENT_YEAR = /^(?:19[5-9]\d|20[0-3]\d)$/;
 const POSTAL_CONTEXT_NEAR = /(?:postcode|postal|code\s*postal|PLZ|Postleitzahl|postnummer|postinumero|póstnúmer|zip|straat|straße|strasse|rue\s|via\s|calle\s|rua\s|ulica|utca|street|avenue|laan\s|weg\s|plein|adres|adresse|address|woonplaats|wonende|woonachtig|gevestigd|domicili|demeurant|résidant|residant|bosatt|bopæl|wohnhaft|ansässig|stad\b|ville\b|city\b|Stadt|città|ciudad|cidade|miasto|město|város)/i;
 const DATE_KEYWORD_NEAR = /(?:født|fødselsdato|fødsel|Fødselsdato|född|födelsedatum|födelsedag|syntynyt|syntymäaika|fæddur|fæðingardagur|geboren|geboortedatum|Geburtsdatum|nascido|nacido|data di nascita|nato il|nata il|Tiltr[æa]delsesdato|Tiltredelsesdato|datum|date\b|Datum|jaar|year|année|Jahr|since|sinds|depuis|seit|\d{2}\.\d{2}\.|(?:januar|februar|marts|april|maj|juni|juli|august|september|oktober|november|december|januari|februari|mars|mei|juin|juillet|août))/i;
+// A sentence boundary: a full stop, question or exclamation mark followed by
+// space, or a line break. Written so it cannot fire inside "11.03.1970", where
+// the periods are not followed by whitespace -- that date is one of the false
+// positives this gate has to reject.
+const SENTENCE_BREAK = /[.!?][ \t\n]|\n/;
+const SENTENCE_BREAK_G = /[.!?][ \t\n]|\n/g;
+// The value's own sentence, bounded either side.
+function sentenceAround(text, start, end, reach = 160) {
+    let before = text.slice(Math.max(0, start - reach), start);
+    let after = text.slice(end, end + reach);
+    let lastEnd = -1;
+    SENTENCE_BREAK_G.lastIndex = 0;
+    for (let m = SENTENCE_BREAK_G.exec(before); m !== null; m = SENTENCE_BREAK_G.exec(before)) {
+        lastEnd = m.index + m[0].length;
+    }
+    if (lastEnd >= 0)
+        before = before.slice(lastEnd);
+    const found = SENTENCE_BREAK.exec(after);
+    if (found !== null)
+        after = after.slice(0, found.index);
+    return before + after;
+}
+// A postal label whose only distance from the value is punctuation:
+// "PLZ: 2011", "code postal : 2011", "Woonplaats: 1950".
+const POSTAL_LABEL_TOUCHING = new RegExp(`(?:${POSTAL_CONTEXT_NEAR.source})[\\s:.\\-]{0,4}$`, "i");
+// A capitalised place name after the code: "2000 Antwerpen". A following label
+// ("1970 Fødselsnummer:") is excluded by the colon.
+const CITY_AFTER = /^[ \t](?!\w+\s*:)[A-ZÀ-ÞŁŠŽ][\w\-']{2,}/u;
+// Every position is local to the value or inside its own sentence. Proximity to
+// an address *word* anywhere in a 300-character window is what the old rescue
+// asked, and that is a neighbourhood rather than a position (rules-engine#32).
+function yearSitsInAddressStructure(text, start, end) {
+    const before = text.slice(Math.max(0, start - 28), start);
+    // "Amsterdam, 2026" -- the comma of an address line.
+    if (/,[ \t]*$/.test(before))
+        return true;
+    // "PLZ: 2011" -- a postal label with nothing but punctuation between.
+    if (POSTAL_LABEL_TOUCHING.test(before))
+        return true;
+    // A capitalised place name immediately after.
+    if (CITY_AFTER.test(text.slice(end, end + 24)))
+        return true;
+    // An address word in the value's own sentence. "Te huur: Lange Nieuwstraat
+    // 12, rustige ligging in 2018, vlakbij openbaar vervoer." is an Antwerp
+    // postal code in prose; the false positives put the year and the address in
+    // different sentences.
+    return POSTAL_CONTEXT_NEAR.test(sentenceAround(text, start, end));
+}
 function suppressYearAsPostal(text, match) {
     if (match.patternDef.entityType !== EntityType.POSTAL_CODE)
         return false;
@@ -330,8 +406,10 @@ function suppressYearAsPostal(text, match) {
         return true;
     const [before, after] = getContext(text, match.start, match.end);
     const context = before + after;
-    // Keep as postal code if postal/address context nearby
-    if (POSTAL_CONTEXT_NEAR.test(context))
+    // Keep as postal code only when the value sits in address *structure* --
+    // see yearSitsInAddressStructure for why a 300-character window of address
+    // words was the defect rather than the keyword list.
+    if (yearSitsInAddressStructure(text, match.start, match.end))
         return false;
     // Keep if preceded by comma+space (address pattern: "Amsterdam, 2026")
     const immediateBefore = text.slice(Math.max(0, match.start - 3), match.start);
@@ -506,6 +584,35 @@ function suppressPostalInsideIban(text, match) {
     }
     return false;
 }
+// An IBAN-shaped run: two letters, two check digits, then grouped
+// alphanumerics. Deliberately not checksum-gated -- the point is to describe the
+// run a human wrote as one account number, including the ones that fail their
+// checksum, because those are exactly the ones no structured detector claims.
+const ACCOUNT_RUN = /\b[A-Z]{2}\d{2}(?:[ ]?[A-Z0-9]{2,4}){2,8}\b/g;
+// "Compte: FR76 3000 4008 0300 0109 5374" fails the IBAN checksum, so no
+// BANK_ACCOUNT candidate survives and the Danish eight-digit phone pattern took
+// "3000 4008" out of the middle of it, leaving the rest in the clear
+// (rules-engine#30). POSTAL_CODE has carried its own version of this guard
+// since 0.3.3, in suppressPostalInsideIban.
+function suppressPhoneInsideAccountRun(text, match) {
+    if (match.patternDef.entityType !== EntityType.PHONE)
+        return false;
+    const lineStart = text.lastIndexOf("\n", match.start) + 1;
+    let lineEnd = text.indexOf("\n", match.end);
+    if (lineEnd < 0)
+        lineEnd = text.length;
+    const line = text.slice(lineStart, lineEnd);
+    ACCOUNT_RUN.lastIndex = 0;
+    for (let m = ACCOUNT_RUN.exec(line); m !== null; m = ACCOUNT_RUN.exec(line)) {
+        const runStart = lineStart + m.index;
+        const runEnd = runStart + m[0].length;
+        if (runStart <= match.start && match.end <= runEnd
+            && runEnd - runStart > match.end - match.start) {
+            return true;
+        }
+    }
+    return false;
+}
 function suppressPostalAsHouseNumber(text, match) {
     if (match.patternDef.entityType !== EntityType.POSTAL_CODE)
         return false;
@@ -733,12 +840,19 @@ function suppressBicWithoutEvidence(text, match, scratch) {
 // Repeated per alternative, the engine retried the same unbounded prefix five
 // times per starting position — the most expensive single regex in the engine
 // at 197 ms per 1 MB document. Same language, 8x faster on the worst case.
+// An identifier cue that is really a postal label -- see the use below.
+const POSTAL_LABEL_CUE = /^post/i;
 const ID_CUE_BEFORE = /(?:[\w\-]*(?:Nr|N[°ºo]|Nummer|Numero|Numéro)|No|number|num|Kennzahl|Aktenzeichen|Az|e-?card|Polizze|Police|Policen)\.?\s*:?\s*$/i;
 // An international dialling prefix earlier on the same line, with nothing but
 // number punctuation in between: these digits belong to the phone detector.
 const DIALLING_PREFIX_BEFORE = /\+\d{1,3}[\d\s\-().]*$/;
 // A country prefix on a postal code — "A-1010 Wien", "B-2000", "L-1234".
-const COUNTRY_PREFIXED = /(?:^|[^A-Za-z0-9])[A-Z]{1,2}$/;
+// The boundary excludes a hyphen, which is what makes this a *prefix* rather
+// than a segment. It did not, so any `XX-NNNNN` tail of a hyphenated reference
+// read as a country-prefixed address: in "PV-2026-LU-09143" the `LU` is
+// preceded by `-` and the German five-digit postal pattern kept `09143`
+// (rules-engine#31).
+const COUNTRY_PREFIXED = /(?:^|[^A-Za-z0-9\-])[A-Z]{1,2}$/;
 /**
  * Suppress bare digit runs that belong to a longer number, not an address.
  *
@@ -782,7 +896,16 @@ function suppressPostalInLongerIdentifier(text, match) {
     if (/^[ \t]+\d/.test(text.slice(match.end, match.end + 4)))
         return true;
     // An identifier label introduces the digits: "DiNr. 4471", "Policen-Nr."
-    if (ID_CUE_BEFORE.test(text.slice(Math.max(0, match.start - 40), match.start)))
+    // Unless the label is a *postal* one. ID_CUE_BEFORE matches any word ending
+    // in "Nummer", "Nr", "Numero" or "Numéro" -- the wildcard is `[\w\-]*` -- so
+    // it matches `postnummer`, `postnr` and `postinumero`, the canonical postal
+    // labels of Norway, Denmark and Finland. Those countries write a bare
+    // four- or five-digit code, so the isdigit() guard above lets this run and
+    // the code was suppressed by its own label: `postnummer: 5020 Bergen`
+    // produced nothing at all (rules-engine#41).
+    const before = text.slice(Math.max(0, match.start - 40), match.start);
+    const cue = ID_CUE_BEFORE.exec(before);
+    if (cue !== null && !POSTAL_LABEL_CUE.test(cue[0].trimStart()))
         return true;
     // Digits after an international dialling prefix belong to PHONE
     const [lineStart] = enclosingLine(text, match.start, match.end);
@@ -834,7 +957,7 @@ function suppressRequiresContext(text, match) {
     return !match.patternDef.contextKeywords.some(kw => context.includes(kw.toLowerCase()));
 }
 const TYPE_SUPPRESSORS = {
-    [EntityType.PHONE]: [suppressCurrency, suppressUnits, suppressReference, suppressMath, suppressPhoneServiceNumber, suppressPhoneDateOverlap, suppressPhoneAsNumberRange],
+    [EntityType.PHONE]: [suppressCurrency, suppressUnits, suppressReference, suppressMath, suppressPhoneServiceNumber, suppressPhoneInsideAccountRun, suppressPhoneDateOverlap, suppressPhoneAsNumberRange],
     [EntityType.NATIONAL_ID]: [suppressCurrency, suppressUnits, suppressReference, suppressLegal, suppressMath, suppressNatidAsPassport, suppressSeNatidAsOrg],
     [EntityType.SSN]: [suppressCurrency, suppressUnits, suppressReference, suppressMath],
     [EntityType.TAX_ID]: [suppressCurrency, suppressUnits, suppressReference, suppressMath, suppressTaxidAsIpAddress],
@@ -848,6 +971,8 @@ const TYPE_SUPPRESSORS = {
 export function shouldSuppress(text, match, scratch) {
     if (suppressSequential(text, match))
         return true;
+    if (suppressRedactionPlaceholder(text, match))
+        return true;
     const typeSups = TYPE_SUPPRESSORS[match.patternDef.entityType];
     if (typeSups) {
         for (const s of typeSups) {

package/dist/esm/rules/validators.js

@@ -467,10 +467,24 @@ export function validatePortugueseNif(candidate) {
     const check = remainder < 2 ? 0 : 11 - remainder;
     return parseInt(c[8]) === check;
 }
+// PESEL carries the century in the month field: +0 is the 1900s, +20 the 2000s,
+// +40 the 2100s, +60 the 2200s, +80 the 1800s. Without a date check this
+// accepted 80666603210 -- day 66 -- as NATIONAL_ID at high confidence
+// (rules-engine#43).
 export function validatePolishPesel(candidate) {
     const c = candidate.replace(/[\s\-]/g, "");
     if (c.length !== 11 || !/^\d{11}$/.test(c))
         return false;
+    const rawMonth = parseInt(c.slice(2, 4), 10);
+    let month = null;
+    for (const off of [0, 20, 40, 60, 80]) {
+        if (rawMonth - off >= 1 && rawMonth - off <= 12) {
+            month = rawMonth - off;
+            break;
+        }
+    }
+    if (month === null || !isRealDay(month, parseInt(c.slice(4, 6), 10)))
+        return false;
     const d = c.split("").map(Number);
     const weights = [1, 3, 7, 9, 1, 3, 7, 9, 1, 3];
     let total = 0;
@@ -489,18 +503,53 @@ export function validatePolishNip(candidate) {
         total += d[i] * weights[i];
     return total % 11 === d[9];
 }
+// Days per month for the rodné číslo date check. February is 29 because the
+// century is not recoverable from a two-digit year, so a leap year cannot be
+// ruled out -- being permissive by one day is the right direction here.
+const RC_DAYS = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+// The calendar month a rodné číslo month field encodes, or null. Four ranges
+// are legal: 1-12 is a man, +50 a woman, and since 2004 +20 marks a birth on a
+// day whose sequence numbers were exhausted (so +70 is a woman on such a day).
+// Whether `day` exists in `month`, February permissive at 29 because a
+// two-digit year does not reveal the century.
+function isRealDay(month, day) {
+    return month >= 1 && month <= 12 && day >= 1 && day <= RC_DAYS[month - 1];
+}
+function czechMonth(raw) {
+    for (const offset of [0, 20, 50, 70]) {
+        if (raw - offset >= 1 && raw - offset <= 12)
+            return raw - offset;
+    }
+    return null;
+}
+// The date is checked, not only the checksum. Without it the validator accepted
+// an impossible month, and a Czech mobile number is the same shape -- nine
+// digits opening 6 or 7 -- so any mobile that happened to pass mod 11 was typed
+// NATIONAL_ID at high confidence: 606666032 (MM=66), 778836400 (MM=88),
+// 728990603 (MM=89). 284 per corpus pass, the largest single false-positive
+// bucket in the evaluation (rules-engine#37).
 export function validateCzechBirthNumber(candidate) {
     const c = candidate.replace(/[/\s]/g, "");
     if (!/^\d+$/.test(c) || (c.length !== 9 && c.length !== 10))
         return false;
+    const month = czechMonth(parseInt(c.slice(2, 4), 10));
+    if (month === null)
+        return false;
+    const day = parseInt(c.slice(4, 6), 10);
+    if (day < 1 || day > RC_DAYS[month - 1])
+        return false;
     if (c.length === 10)
         return parseInt(c) % 11 === 0;
     return true;
 }
+// S YY MM DD JJ NNN C -- the leading S carries the century, so the month needs
+// no offset convention here (rules-engine#43).
 export function validateRomanianCnp(candidate) {
     const c = candidate.replace(/[\s\-]/g, "");
     if (c.length !== 13 || !/^\d{13}$/.test(c) || !"12345678".includes(c[0]))
         return false;
+    if (!isRealDay(parseInt(c.slice(3, 5), 10), parseInt(c.slice(5, 7), 10)))
+        return false;
     const key = "279146358279";
     let total = 0;
     for (let i = 0; i < 12; i++)
@@ -547,10 +596,14 @@ export function validateCroatianOib(candidate) {
     const check = (11 - product) % 10;
     return check === parseInt(c[10]);
 }
+// DD MM YYY RR BBB K -- note EMSO opens with the *day*, where the Czech, Polish
+// and Romanian forms open with the year or a century digit (rules-engine#43).
 export function validateSlovenianEmso(candidate) {
     const c = candidate.replace(/[\s\-]/g, "");
     if (c.length !== 13 || !/^\d{13}$/.test(c))
         return false;
+    if (!isRealDay(parseInt(c.slice(2, 4), 10), parseInt(c.slice(0, 2), 10)))
+        return false;
     const d = c.split("").map(Number);
     const weights = [7, 6, 5, 4, 3, 2, 7, 6, 5, 4, 3, 2];
     let total = 0;

package/dist/esm/sdk.d.ts

@@ -136,7 +136,16 @@ export declare class EuRedact {
     /** The label function for one call, given its output options. */
     private labelFor;
     /**
-     * Send a document to the cloud tier.
+     * Run the rules here, then send what they left to the cloud tier.
+     *
+     * Local-first: the rules engine masks everything it can find on the caller's
+     * machine, and only that masked text is sent. The service looks for what has
+     * no shape to match on — names, employers, diagnoses — and answers with
+     * spans relative to the text it received, which are mapped back onto the
+     * original here.
+     *
+     * This is minimisation, not an exemption: what the rules miss, and the names
+     * and diagnoses the model is there to find, still travel.
      *
      * Options the service cannot honour throw rather than being ignored. Silently
      * dropping one would mean returning a result that does not match what was
@@ -144,21 +153,9 @@ export declare class EuRedact {
      * under-redaction wearing a plausible face.
      */
     private redactViaCloud;
-    /**
-     * Rebuild the masked text from the service's spans, in place.
-     *
-     * The service masks with bracketed labels only. Any other output option is
-     * applied here, from its spans: the service builds its `redacted_text` from
-     * exactly the spans it returns (entities it reports but cannot place are
-     * listed separately and never applied), so nothing it masked is lost by
-     * masking again from the same spans.
-     *
-     * The service reports offsets in code points and this SDK slices UTF-16
-     * units, so the slice check is what stands between an emoji in the document
-     * and a rebuilt text with the wrong characters masked.
-     */
-    private remaskCloudResult;
     redact(text: string, options?: RedactOptions): RedactResult;
+    /** The local pipeline: normalise, detect, exempt, mask. */
+    private redactRules;
     /**
      * Redact, awaiting the cloud tier when `mode: "cloud"` is asked for.
      *

package/dist/esm/sdk.js

@@ -48,6 +48,96 @@ export function applyReplacements(text, detections, labelFor) {
     parts.push(text.slice(pos));
     return parts.join("");
 }
+/**
+ * Bracket-mask `text` and record where each label landed.
+ *
+ * Returns what is sent to the cloud tier, plus one `WireLabel` per label.
+ * Everything between labels is copied unchanged, so the labels are all it
+ * takes to carry an offset from the masked text back to the original.
+ *
+ * Always `[TYPE]`, whatever label scheme the caller asked for. That is the
+ * syntax the model was trained on, where a placeholder means "already handled,
+ * do not list it". A token or a numbered label would be read as ordinary text,
+ * so the format on the wire is a model contract and not an output option.
+ */
+function maskForCloud(text, detections) {
+    const parts = [];
+    const labels = [];
+    let pos = 0;
+    let out = 0;
+    for (const det of detections) {
+        const start = Math.max(det.start, pos);
+        if (det.end <= start)
+            continue;
+        const label = `[${det.entityType}]`;
+        out += start - pos;
+        parts.push(text.slice(pos, start), label);
+        labels.push([out, out + label.length, start, det.end]);
+        out += label.length;
+        pos = det.end;
+    }
+    parts.push(text.slice(pos));
+    return [parts.join(""), labels];
+}
+/** Index of the last label starting at or before `offset` — strictly before
+ *  when `strict` — or -1. */
+function labelBefore(labels, offset, strict) {
+    let lo = 0;
+    let hi = labels.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (strict ? labels[mid][0] < offset : labels[mid][0] <= offset)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo - 1;
+}
+/**
+ * Carry the service's spans from the masked text onto the original.
+ *
+ * The service only ever saw `masked`, so its offsets index that. An offset in
+ * copied text shifts by whatever the labels before it added or removed. An
+ * offset inside a label has no counterpart in the original, so it snaps
+ * outward to the edge of the value the label replaced: an address the model
+ * reports around `[POSTAL_CODE]` covers the postal code, never half of it.
+ * Over-masking is the safe direction.
+ *
+ * A span lying wholly inside one label describes the label, not the document.
+ * It is dropped; the local detection behind the label stands.
+ *
+ * Throws `Unplaceable` when a span does not match the text that was sent. Such
+ * a span cannot be placed, and masking where it points would cover the wrong
+ * characters and leave the right ones in the clear.
+ */
+function ontoOriginal(spans, masked, text, labels, Unplaceable) {
+    const placed = [];
+    for (const span of spans) {
+        if (!(0 <= span.start && span.start <= span.end && span.end <= masked.length) ||
+            masked.slice(span.start, span.end) !== span.text) {
+            throw new Unplaceable("span offsets do not match the text that was sent; cannot place the " +
+                "service's detections in the document");
+        }
+        if (span.start === span.end)
+            continue;
+        let start = span.start;
+        let at = labelBefore(labels, span.start, false);
+        if (at >= 0) {
+            const [, maskedEnd, origStart, origEnd] = labels[at];
+            if (span.end <= maskedEnd)
+                continue;
+            start = span.start < maskedEnd ? origStart : origEnd + span.start - maskedEnd;
+        }
+        let end = span.end;
+        at = labelBefore(labels, span.end, true);
+        if (at >= 0) {
+            const [, maskedEnd, , origEnd] = labels[at];
+            end = origEnd + Math.max(0, span.end - maskedEnd);
+        }
+        placed.push({ ...span, start, end, text: text.slice(start, end) });
+    }
+    return placed;
+}
 /**
  * Characters a token suffix is drawn from. No vowels, so a suffix never spells
  * a word; no 0/1/I/O, so it survives being read back by a person; no
@@ -386,7 +476,16 @@ export class EuRedact {
         return (det) => `[${det.entityType}]`;
     }
     /**
-     * Send a document to the cloud tier.
+     * Run the rules here, then send what they left to the cloud tier.
+     *
+     * Local-first: the rules engine masks everything it can find on the caller's
+     * machine, and only that masked text is sent. The service looks for what has
+     * no shape to match on — names, employers, diagnoses — and answers with
+     * spans relative to the text it received, which are mapped back onto the
+     * original here.
+     *
+     * This is minimisation, not an exemption: what the rules miss, and the names
+     * and diagnoses the model is there to find, still travel.
      *
      * Options the service cannot honour throw rather than being ignored. Silently
      * dropping one would mean returning a result that does not match what was
@@ -395,6 +494,7 @@ export class EuRedact {
      */
     async redactViaCloud(text, options) {
         const { CloudClient } = await import("./cloud/client.js");
+        const { CloudError } = await import("./cloud/errors.js");
         const countries = options.countries ?? null;
         if (!countries || countries.length !== 1) {
             throw new Error('cloud mode needs exactly one country, e.g. { countries: ["BE"] }. The ' +
@@ -412,43 +512,34 @@ export class EuRedact {
         if (options.referentialIntegrity) {
             throw new Error("referentialIntegrity is not supported in cloud mode");
         }
-        // detectDates is deliberately NOT forwarded. The service always runs its
-        // rules engine with dates on, because that is what the model was trained
-        // against; the caller's value cannot change that. It is the one ignored
-        // option that is safe to ignore — it can only cause MORE to be detected,
-        // never less, so it cannot produce under-redaction.
         const allowed = this.allowedFor(options);
         const domains = this.domainsFor(options);
-        const result = await new CloudClient().redact(text, { country: countries[0] });
-        if (options.tokenize || allowed.size > 0 || domains.size > 0) {
-            await this.remaskCloudResult(result, text, { tokenize: options.tokenize ?? false, allowed, domains });
-        }
-        return result;
-    }
-    /**
-     * Rebuild the masked text from the service's spans, in place.
-     *
-     * The service masks with bracketed labels only. Any other output option is
-     * applied here, from its spans: the service builds its `redacted_text` from
-     * exactly the spans it returns (entities it reports but cannot place are
-     * listed separately and never applied), so nothing it masked is lost by
-     * masking again from the same spans.
-     *
-     * The service reports offsets in code points and this SDK slices UTF-16
-     * units, so the slice check is what stands between an emoji in the document
-     * and a rebuilt text with the wrong characters masked.
-     */
-    async remaskCloudResult(result, text, opts) {
-        const { CloudError } = await import("./cloud/errors.js");
-        for (const det of result.detections) {
-            if (text.slice(det.start, det.end) !== det.text) {
-                throw new CloudError("span offsets do not match the document; cannot apply tokenize/allowlist locally");
-            }
-        }
-        [result.detections, result.exempted] = applyAllowlist(text, result.detections, opts.allowed, opts.domains);
-        const tokenMapper = opts.tokenize ? new TokenMapper(text, result.detections) : null;
-        result.redactedText = applyReplacements(text, result.detections, this.labelFor(false, tokenMapper));
-        result.tokens = tokenMapper ? tokenMapper.tokens : {};
+        const client = new CloudClient();
+        // Dates are always on, whatever detectDates says: that is the rules output
+        // the model was trained against, and a date of birth the rules can place
+        // has no reason to travel. It is the one ignored option that is safe to
+        // ignore — it can only cause MORE to be detected, never less.
+        //
+        // No allowlist and no tokens on this pass. An exemption says what the
+        // caller wants back, not what may leave; both are applied below, after the
+        // response, to the merged spans.
+        const local = this.redactRules(text, { countries, detectDates: true, cache: options.cache }, new Map(), new Map());
+        const [masked, labels] = maskForCloud(text, local.detections);
+        // The client converts the service's code-point offsets to UTF-16 units of
+        // the text it sent, so everything from here on is in one unit.
+        const remote = await client.redact(masked, { country: countries[0] });
+        // A new array throughout: `local` may be the cached rules result.
+        const [detections, exempted] = applyAllowlist(text, [...local.detections, ...ontoOriginal(remote.detections, masked, text, labels, CloudError)], allowed, domains);
+        detections.sort((a, b) => a.start - b.start || b.end - a.end);
+        const tokenMapper = options.tokenize ? new TokenMapper(text, detections) : null;
+        return {
+            ...local,
+            redactedText: applyReplacements(text, detections, this.labelFor(false, tokenMapper)),
+            detections,
+            source: "cloud",
+            tokens: tokenMapper ? tokenMapper.tokens : {},
+            exempted,
+        };
     }
     redact(text, options = {}) {
         checkCountryArg(options.countries, "countries");
@@ -469,12 +560,16 @@ export class EuRedact {
         if (requestedMode !== "rules") {
             throw new Error(`unknown mode ${JSON.stringify(requestedMode)}: expected "rules" or "cloud"`);
         }
+        return this.redactRules(text, options, allowed, domains);
+    }
+    /** The local pipeline: normalise, detect, exempt, mask. */
+    redactRules(text, options, allowed, domains) {
         if (text.length > this.maxInputLength) {
             throw new Error(`Input text length (${text.length.toLocaleString()} chars) exceeds the maximum ` +
                 `(${this.maxInputLength.toLocaleString()} chars). Split the input or ` +
                 `increase maxInputLength when constructing EuRedact.`);
         }
-        const { countries = null, countryHint = null, context = null, chunkOffset = 0, mode = "rules", referentialIntegrity = false, tokenize = false, detectDates = false, } = options;
+        const { countries = null, countryHint = null, context = null, chunkOffset = 0, referentialIntegrity = false, tokenize = false, detectDates = false, } = options;
         // A context makes the result depend on evidence from other chunks, so the
         // text no longer identifies the result. Caching is disabled rather than
         // keyed on the context, whose contents change as chunks arrive.
@@ -492,7 +587,7 @@ export class EuRedact {
         // separator, and two different lists must never share a key.
         const allowKey = (allowed.size ? JSON.stringify([...allowed.keys()].sort()) : "")
             + (domains.size ? "|dom=" + JSON.stringify([...domains.keys()].sort()) : "");
-        const cacheMode = `${mode}|dates=${detectDates}|hint=${hintKey}|ri=${referentialIntegrity}|tok=${tokenize}|allow=${allowKey}`;
+        const cacheMode = `rules|dates=${detectDates}|hint=${hintKey}|ri=${referentialIntegrity}|tok=${tokenize}|allow=${allowKey}`;
         let cacheKey;
         if (cache) {
             cacheKey = this.cache.key(normalizedText, countriesTuple, cacheMode);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "euredact",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "European PII redaction SDK -- fast, zero-dependency, rule-based detection and redaction of personal data across 31 European countries",
   "homepage": "https://euredact.dev",
   "license": "Apache-2.0",