euredact 0.3.8 → 0.4.0

package/dist/esm/rules/cues.js

@@ -33,12 +33,28 @@
  *   the *tail* of an ordinary word. "NIS" matched "tālru**nis**", the Latvian
  *   for telephone, and suppressed 653 real phone numbers; "iva" matched
  *   "Pr**iva**t:" and read a personal e-mail address as a VAT number.
- * * The qualifier class is spelled out rather than written `[^\W\d_]`, which
- *   would reject "εταιρειας" here for the same ASCII reason.
+ * * Neither the qualifier nor the run-on may use `\w`. The qualifier is a
+ *   negated ASCII class, fixed for this in 0.3.8; `[^\W\d_]` would reject
+ *   "εταιρειας" here for the same ASCII reason. The run-on was *not* fixed then
+ *   and went on diverging for another release: Slovak "telefón 0956550012"
+ *   needs it to absorb "efón" after `tel`, and Bulgarian
+ *   "пощенски кодове 4000-4999" needs "ове" after `пощенски код`. Python's
+ *   Unicode `\w` did; this SDK's ASCII `\w` did not, so one engine said `PHONE`
+ *   and the other `NATIONAL_ID` on the same document. They were the last two
+ *   type divergences on the corpus, and only the type-aware half of
+ *   `make parity` could see them.
  *
- * Every label ends in `(?:\w*|\s+<one word>)`: the label either runs on into a
- * longer word ("telefoon" → "telefoonnummer") **or** takes one qualifier word
- * naming whose identifier it is ("ΑΦΜ εταιρειας:", "Tel Nr:") — never both.
+ *   The run-on is spelled `(?:[A-Za-z0-9_]|[^\x00-\x7F])` — an ASCII word
+ *   character, or any non-ASCII character — rather than as a negated class of
+ *   separators. A negated class also admits `'`, `%`, `&`, `@` and the rest of
+ *   ASCII punctuation, which `\w` never did, and widening it that far was
+ *   measured at 46 extra false positives with hints and 57 blind over the
+ *   152,300-document corpus. This is `\w` plus the non-ASCII letters `\w`
+ *   should have matched all along, and nothing else.
+ *
+ * Every label ends in `(?:<run-on>|\s+<one word>)`: the label either runs on
+ * into a longer word ("telefoon" → "telefoonnummer") **or** takes one qualifier
+ * word naming whose identifier it is ("ΑΦΜ εταιρειας:", "Tel Nr:") — never both.
  * Allowing both let "nie" grow into the surname "Nieminen" and then swallow the
  * real label in "Matti Nieminen\nDOB: 08.05.1994", reading a date of birth as a
  * Spanish NIE: 52 false positives across the corpus.
@@ -49,7 +65,7 @@ import { EntityType } from "../types.js";
  * the value it introduces, which is the lesson of the postal-code year defect,
  * where a cue 150 characters away licensed every number in the window.
  */
-export const CUE_WINDOW = 22;
+export const CUE_WINDOW = 32;
 /**
  * (entity type, label pattern). Ordered: the first match wins, so the narrower
  * label comes first where two could read the same text.
@@ -59,46 +75,63 @@ export const CUES = [
     // front of a span that no phone pattern matched says the document is laid out
     // unusually, not that the value is a phone number.
     [EntityType.PHONE,
-        /(?<![A-Za-z0-9_])(?:phone|tel|telephone|téléphone|telefoon|telefon|telefono|teléfono|tlf|mobil|mobile|gsm|handy|sími|puh|móvil|cell|tālrunis|τηλέφωνο|τηλ)(?:\w*|\s+[^\s:.\-\d,;()/]{2,20})\s*[:.\-]?\s*$/i],
+        /(?<![A-Za-z0-9_])(?:phone|tel|telephone|téléphone|telefoon|telefon|telefono|teléfono|tlf|mobil|mobile|gsm|handy|sími|puh|móvil|cell|tālrunis|τηλέφωνο|τηλ)(?:(?:[A-Za-z0-9_]|[^\x00-\x7F])*|\s+[^\s:.\-\d,;()\/]{2,20})\s*\)?\s*[:.\-]*\s*$/i],
     // National identity number.
     [EntityType.NATIONAL_ID,
-        /(?<![A-Za-z0-9_])(?:bsn|personnummer|rijksregisternummer|nationaal\s*nummer|numéro\s*national|national\s*(?:id|number)|identiteitsnummer|henkilötunnus|kennitala|cpr(?:-?nummer)?|nif|nie|dni|rr|nn|nir|insz|niss|nis|matricule|ausweisnummer|personalausweis|osobní\s*číslo|ЕГН|EGN)(?:\w*|\s+[^\s:.\-\d,;()/]{2,20})\s*[:.\-]?\s*$/i],
+        /(?<![A-Za-z0-9_])(?:bsn|burgerservicenummer(?:\s*\(bsn\))?|personnummer|rijksregisternummer|nationaal\s*nummer|numéro\s*national|national\s*(?:id|number)|identiteitsnummer|henkilötunnus|kennitala|cpr(?:-?nummer)?|nif|nie|dni|rr|nn|nir|insz|niss|nis|matricule|ausweisnummer|personalausweis|osobní\s*číslo|ЕГН|EGN)(?:(?:[A-Za-z0-9_]|[^\x00-\x7F])*|\s+[^\s:.\-\d,;()\/]{2,20})\s*\)?\s*[:.\-]*\s*$/i],
     // Cyprus: "ID number" in both official languages, plus the Greek abbreviation
     // ΑΔΤ (Αστυνομική Ταυτότητα). Neither has a phone reading.
     [EntityType.NATIONAL_ID,
-        /(?<![A-Za-z0-9_])(?:αρ\.?\s*ταυτότητας|ταυτότητας|αδτ|kimlik\s*numaras[ıi])(?:\w*|\s+[^\s:.\-\d,;()/]{2,20})\s*[:.\-]?\s*$/i],
+        /(?<![A-Za-z0-9_])(?:αρ\.?\s*ταυτότητας|ταυτότητας|αδτ|kimlik\s*numaras[ıi])(?:(?:[A-Za-z0-9_]|[^\x00-\x7F])*|\s+[^\s:.\-\d,;()\/]{2,20})\s*\)?\s*[:.\-]*\s*$/i],
     // Social security.
     [EntityType.SSN,
-        /(?<![A-Za-z0-9_])(?:ssn|social\s*security|sozialversicherungsnummer|svnr|sofi)(?:\w*|\s+[^\s:.\-\d,;()/]{2,20})\s*[:.\-]?\s*$/i],
+        /(?<![A-Za-z0-9_])(?:ssn|social\s*security|sozialversicherungsnummer|svnr|sofi)(?:(?:[A-Za-z0-9_]|[^\x00-\x7F])*|\s+[^\s:.\-\d,;()\/]{2,20})\s*\)?\s*[:.\-]*\s*$/i],
     // Tax number. Greece's ΑΦΜ is issued by the tax authority; the identity-card
-    // number is the ΑΔΤ, above. The engine used to return NATIONAL_ID for a value
-    // cued ΑΦΜ, which is wrong independently of the phone problem.
+    // number is the ΑΔΤ, above.
     [EntityType.TAX_ID,
-        /(?<![A-Za-z0-9_])(?:αφμ|α\.φ\.μ\.|steuer-?id|steuernummer|st\.?-?nr|stnr|tin|finanzamt\s+ist|tax\s*(?:id|no|number)|daňové\s*číslo|numer\s*podatkowy)(?:\w*|\s+[^\s:.\-\d,;()/]{2,20})\s*[:.\-]?\s*$/i],
-    // Health insurance.
+        /(?<![A-Za-z0-9_])(?:αφμ|α\.φ\.μ\.|steuer-?id|steuernummer|st\.?-?nr|stnr|tin|finanzamt\s+ist|tax\s*(?:id|no|number)|daňové\s*číslo|numer\s*podatkowy)(?:(?:[A-Za-z0-9_]|[^\x00-\x7F])*|\s+[^\s:.\-\d,;()\/]{2,20})\s*\)?\s*[:.\-]*\s*$/i],
+    // Health insurance: the insured person.
     [EntityType.HEALTH_INSURANCE,
-        /(?<![A-Za-z0-9_])(?:versichertennummer|krankenversicherung|kvnr|kv-?nr|mutualité|ziekenfonds|aansluitingsnummer)(?:\w*|\s+[^\s:.\-\d,;()/]{2,20})\s*[:.\-]?\s*$/i],
-    // Company / trade register.
+        /(?<![A-Za-z0-9_])(?:versichertennummer|krankenversicherung|kvnr|kv-?nr|mutualité|ziekenfonds|aansluitingsnummer|medical\s*card(?:\s*(?:no|number))?)(?:(?:[A-Za-z0-9_]|[^\x00-\x7F])*|\s+[^\s:.\-\d,;()\/]{2,20})\s*\)?\s*[:.\-]*\s*$/i],
+    // Healthcare provider: the clinician or practice, not the patient — the Dutch
+    // AGB-code, the German LANR, the UK GMC number.
+    [EntityType.HEALTHCARE_PROVIDER,
+        /(?<![A-Za-z0-9_])(?:agb-?code|lanr|bsnr|gmc(?:\s*(?:no|number|reg))?|big-?nummer|zorgverlener(?:snummer)?)(?:(?:[A-Za-z0-9_]|[^\x00-\x7F])*|\s+[^\s:.\-\d,;()\/]{2,20})\s*\)?\s*[:.\-]*\s*$/i],
+    // Company / trade register. "Companies House" and "Company Registration
+    // Number" are written out: the tail allows a run-on *or* one qualifier word,
+    // never a second word, so a three-word label needs to be spelled.
     [EntityType.CHAMBER_OF_COMMERCE,
-        /(?<![A-Za-z0-9_])(?:siren|siret|kbo|bce|kvk|ondernemingsnummer|ondernemingen\s+onder\s+nummer|kruispuntbank|numéro\s*d'entreprise|enterprise\s*number|handelsregister|company\s*(?:no|number|reg)|organisationsnummer|orgnr|i[čc]o|identifikační\s*číslo|ЕИК|eik|bulstat|cvr(?:-?nummer)?|virksomhedsnummer)(?:\w*|\s+[^\s:.\-\d,;()/]{2,20})\s*[:.\-]?\s*$/i],
+        /(?<![A-Za-z0-9_])(?:siren|siret|kbo|bce|kvk|ondernemingsnummer|ondernemingen\s+onder\s+nummer|kruispuntbank|numéro\s*d'entreprise|enterprise\s*number|handelsregister|companies\s*house(?:\s*(?:registration|reg|no|number))?|company\s*registration(?:\s*(?:number|no))?|company\s*(?:no|number|reg)|organisationsnummer|orgnr|i[čc]o|identifikační\s*číslo|ЕИК|eik|bulstat|cvr(?:-?nummer)?|virksomhedsnummer)(?:(?:[A-Za-z0-9_]|[^\x00-\x7F])*|\s+[^\s:.\-\d,;()\/]{2,20})\s*\)?\s*[:.\-]*\s*$/i],
     // VAT.
     [EntityType.VAT,
-        /(?<![A-Za-z0-9_])(?:vat|btw|tva|ust|iva|moms|alv|mwst|dič|vsk)(?:[\w.\-]*|\s+[^\s:.\-\d,;()/]{2,20})\s*[:.\-]?\s*$/i],
+        /(?<![A-Za-z0-9_])(?:vat|btw|tva|ust|iva|moms|alv|mwst|dič|vsk)(?:(?:[A-Za-z0-9_.\-]|[^\x00-\x7F])*|\s+[^\s:.\-\d,;()\/]{2,20})\s*\)?\s*[:.\-]*\s*$/i],
+    // Bank account. A UK sort code is NN-NN-NN, also a licence-plate shape, so
+    // "sort code 20-45-91" was typed LICENSE_PLATE with the label in front of it.
+    // Retype target only — a failed mod-97 is never rescued by a label.
+    [EntityType.BANK_ACCOUNT,
+        /(?<![A-Za-z0-9_])(?:sort\s*code|account\s*(?:no|number)|rekeningnummer|kontonummer|numéro\s*de\s*compte|sort-?code)(?:(?:[A-Za-z0-9_]|[^\x00-\x7F])*|\s+[^\s:.\-\d,;()\/]{2,20})\s*\)?\s*[:.\-]*\s*$/i],
+    // Passport.
+    [EntityType.PASSPORT,
+        /(?<![A-Za-z0-9_])(?:passport(?:\s*(?:no|number))?|paspoort(?:nummer)?|reisepass(?:nummer)?|passeport|passnummer)(?:(?:[A-Za-z0-9_]|[^\x00-\x7F])*|\s+[^\s:.\-\d,;()\/]{2,20})\s*\)?\s*[:.\-]*\s*$/i],
     // BIC / SWIFT.
     [EntityType.BIC,
-        /(?<![A-Za-z0-9_])(?:bic|swift)[\w/]*\s*[:.\-]?\s*\(?\s*$/i],
+        /(?<![A-Za-z0-9_])(?:bic|swift)(?:[A-Za-z0-9_\/]|[^\x00-\x7F])*\s*[:.\-]?\s*\(?\s*$/i],
     // Postal code. A postal code loses every contested span on priority (it is
     // the weakest evidence the engine has), so without a cue entry
     // "Cod postal: 040171" was handed to a German phone pattern.
     [EntityType.POSTAL_CODE,
-        /(?<![A-Za-z0-9_])(?:cod\s*po[sș]tal|postnummer|postnr|postleitzahl|plz|postcode|code\s*postal|codice\s*postale|kod\s*pocztowy|ps[čc]|τ\.?κ\.?|пощенски\s*код)(?:\w*|\s+[^\s:.\-\d,;()/]{2,20})\s*[:.\-]?\s*$/i],
+        /(?<![A-Za-z0-9_])(?:cod\s*po[sș]tal|postnummer|postnr|postleitzahl|plz(?:-?bereiche?)?|postcode|code\s*postal|codice\s*postale|kod\s*pocztowy|ps[čc]|τ\.?κ\.?|пощенски\s*код)(?:(?:[A-Za-z0-9_]|[^\x00-\x7F])*|\s+[^\s:.\-\d,;()\/]{2,20})\s*\)?\s*[:.\-]*\s*$/i],
     // Internal / employee identifier. The canon calls these INTERNAL_ID and
     // annotates them with an LLM, so the engine has no pattern for them — but it
     // does have a phone pattern that was happily claiming them. The cue is the
     // only thing that identifies one, which is why the engine emits this type
     // from here and nowhere else.
     [EntityType.INTERNAL_ID,
-        /(?<![A-Za-z0-9_])(?:medarbejdernummer|ansattnummer|anställningsnummer|personalnummer|personeelsnummer|matricule\s*salarié|employee\s*(?:no|number|id)|badge\s*(?:no|number)|osobní\s*(?:číslo\s*)?zaměstnance)(?:\w*|\s+[^\s:.\-\d,;()/]{2,20})\s*[:.\-]?\s*$/i],
+        /(?<![A-Za-z0-9_])(?:medarbejdernummer|ansattnummer|anställningsnummer|personalnummer|personeelsnummer|matricule\s*salarié|employee\s*(?:no|number|id)|badge(?:\s*(?:no|number))?|betriebsstätten(?:nr|nummer)|grundstücks(?:nr|nummer)|dossier-?(?:nr|nummer)|aktenzeichen|osobní\s*(?:číslo\s*)?zaměstnance)(?:(?:[A-Za-z0-9_]|[^\x00-\x7F])*|\s+[^\s:.\-\d,;()\/]{2,20})\s*\)?\s*[:.\-]*\s*$/i],
+    // Credential. Typed SECRET because that is the type this SDK has; the
+    // training pipeline's report asks for CREDENTIAL, which does not exist here.
+    [EntityType.SECRET,
+        /(?<![A-Za-z0-9_])(?:tan-?activatiecode|activatiecode|activation\s*code|verificatiecode|verification\s*code|otp|pincode)(?:(?:[A-Za-z0-9_]|[^\x00-\x7F])*|\s+[^\s:.\-\d,;()\/]{2,20})\s*\)?\s*[:.\-]*\s*$/i],
 ];
 /**
  * The entity type a label immediately before `start` names, or null.
@@ -124,22 +157,56 @@ const RETYPABLE = new Set([
     EntityType.PHONE, EntityType.POSTAL_CODE, EntityType.LICENSE_PLATE,
 ]);
 /**
- * Types a label can assert on its own. Also the types eligible for the rescue
- * in `engine.ts`, for the same reason read the other way — a label may vouch
- * for one of these, so it may also vouch for a malformed one.
+ * Retypable, but only when the document gives its country no support at all.
+ *
+ * These carry a checksum, so normally the pattern outranks any label. But a
+ * checksum only says the digits fit *some* national scheme, and a weak one fits
+ * by luck — the same reasoning that demotes an uncorroborated validated
+ * candidate to priority 1 in `engine.ts`. At a country score of 0.0 the engine
+ * is already saying "this passed a Czech checksum in a document with nothing
+ * Czech about it", and an explicit "Passport No.:" is the better evidence.
+ *
+ * Restricted to zero country support on purpose: a Dutch BSN in a Dutch
+ * document scores above zero and stays a NATIONAL_ID whatever label sits near
+ * it, so this cannot relabel a domestic identifier — only the coincidental
+ * foreign ones, which is where "Passport No.: 512847603" and
+ * "Betriebsstättennr. 260326822" both landed, each reported as Czech.
+ */
+const RETYPABLE_UNCORROBORATED = new Set([EntityType.NATIONAL_ID]);
+/**
+ * Types a label can assert on its own.
  *
  * PHONE is absent on purpose: "Tel:" in front of something no phone pattern
  * matched means the document is laid out oddly, not that the value is a phone
- * number. So are EMAIL, SECRET, DOB, VIN and the rest — those carry their own
+ * number. So are EMAIL, DOB, VIN and the rest — those carry their own
  * structure, and a nearby word is not entitled to overrule it.
+ */
+export const CUE_TARGETS = new Set([
+    EntityType.NATIONAL_ID, EntityType.SSN, EntityType.TAX_ID,
+    EntityType.HEALTH_INSURANCE, EntityType.HEALTHCARE_PROVIDER,
+    EntityType.CHAMBER_OF_COMMERCE, EntityType.VAT, EntityType.POSTAL_CODE,
+    EntityType.PASSPORT, EntityType.INTERNAL_ID, EntityType.BANK_ACCOUNT,
+    EntityType.SECRET,
+]);
+/**
+ * Which of those a label may also *rescue* — re-admit after its checksum
+ * failed. Until 0.3.9 this was the same set as CUE_TARGETS and it cannot stay
+ * that way: re-typing a span the engine already decided to mask is cheap to be
+ * wrong about, while rescuing one asserts that a value which failed its check
+ * digit is a real identifier anyway.
  *
  * BIC's absence is what keeps the rescue honest. Its validator is a *registry
  * lookup*, not a checksum, so a failure means "no such bank", which no label can
  * talk you out of. Rescuing it read 34 unlisted codes behind a "BIC:" label as
  * real ones. The same reasoning keeps CREDIT_CARD and BANK_ACCOUNT out: Luhn and
  * mod-97 are strong enough that a failure really does mean "not one of these".
+ * BANK_ACCOUNT joined CUE_TARGETS in 0.3.9 so "sort code 20-45-91" stops being a
+ * LICENSE_PLATE, and is kept out here for exactly the 0.3.8 reason.
+ *
+ * HEALTHCARE_PROVIDER and SECRET are absent because neither is checksummed;
+ * there is no failed validation for a label to overrule in the first place.
  */
-export const CUE_TARGETS = new Set([
+export const RESCUE_TARGETS = new Set([
     EntityType.NATIONAL_ID, EntityType.SSN, EntityType.TAX_ID,
     EntityType.HEALTH_INSURANCE, EntityType.CHAMBER_OF_COMMERCE,
     EntityType.VAT, EntityType.POSTAL_CODE, EntityType.PASSPORT,
@@ -152,9 +219,14 @@ export const CUE_TARGETS = new Set([
  * without them fired 52 times and got roughly 30 of those wrong — EMAIL read as
  * VAT, a date of birth as a phone number, a VIN as VAT — against 20 real fixes.
  * With them: 14 re-typings, every one of them PHONE to a structured identifier.
+ *
+ * `countryScore` is the document's support for the country the winning pattern
+ * came from; see RETYPABLE_UNCORROBORATED.
  */
-export function retypedBy(text, start, entityType) {
-    if (!RETYPABLE.has(String(entityType)))
+export function retypedBy(text, start, entityType, countryScore) {
+    const type = String(entityType);
+    if (!RETYPABLE.has(type)
+        && !(RETYPABLE_UNCORROBORATED.has(type) && countryScore === 0))
         return null;
     const cued = cuedType(text, start);
     if (cued === null || cued === entityType || !CUE_TARGETS.has(String(cued)))

package/dist/esm/rules/engine.d.ts

@@ -8,6 +8,38 @@ import { type RawMatch } from "./matchers.js";
 export declare const COUNTRY_CODE_ALIASES: Record<string, string>;
 /** Map a caller-supplied code to a registered one, or null if unknown. */
 export declare function resolveCountryCode(countryCode: string): string | null;
+/**
+ * Last-resort ordering for candidates every other field has tied on.
+ *
+ * Reaching this means the engine has no evidence left: same span, no cue, same
+ * priority, the same (usually zero) country score, and the same declared scope.
+ * Something still has to win, and before this the winner was whichever candidate
+ * happened to be generated first — which is country *registration* order, and
+ * the two SDKs do not share one. Python registers alphabetically
+ * (`AT, BE, BG, CH, CY, CZ, ...`); this SDK uses a curated order
+ * (`NL, BE, DE, AT, CH, FR, ..., PT, LU, PL, ..., CZ`). So a bare digit run that
+ * several national schemes accept was filed as a Czech `NATIONAL_ID` by Python
+ * and a Portuguese `PHONE` here — identical characters masked, contradictory
+ * labels, and `make parity` compared only characters, so it stayed green through
+ * the whole of 0.3.8.
+ *
+ * The order reproduces what Python already did rather than inventing a new one,
+ * because every accuracy figure this engine has published was measured with
+ * Python resolving these ties by its registration order. Ordering on the entity
+ * type instead was tried first and re-tuned the corpus twice over: it turned the
+ * German `Steuerß12345678911` from `TAX_ID`/DE into `NATIONAL_ID`/EL, and moved
+ * 820 further spans from `DOB` to `DATE_OF_DEATH`. So the key is deliberately
+ * not total — candidates from the same country are left to the stable sort,
+ * which preserves the order that country's pattern list was written in, and both
+ * SDKs write theirs in the same order.
+ *
+ * Taken from the **pattern**, never the finished detection: this SDK re-types a
+ * cued candidate before the sort and Python re-types after it, so keying on the
+ * final type would reintroduce the divergence in a subtler form.
+ *
+ * Kept character-for-character in step with `tie_key` in `rules/engine.py`.
+ */
+export declare function tieKey(countryCode: string): string;
 export declare class RuleEngine {
     private matcher;
     private loadedCountries;

package/dist/esm/rules/engine.js

@@ -1,7 +1,7 @@
 import { DetectionSource, EntityType } from "../types.js";
 import { MultiPatternMatcher } from "./matchers.js";
 import { shouldSuppress, SuppressionScratch } from "./suppressors.js";
-import { CUE_TARGETS, cuedType, retypedBy } from "./cues.js";
+import { RESCUE_TARGETS, cuedType, retypedBy } from "./cues.js";
 import { detectStructuralDob } from "./structural.js";
 import { COUNTRY_CONFIGS } from "./countries/index.js";
 import * as evidenceMod from "./evidence.js";
@@ -44,6 +44,48 @@ export function resolveCountryCode(countryCode) {
     code = COUNTRY_CODE_ALIASES[code] ?? code;
     return code in COUNTRY_CONFIGS && code !== "SHARED" ? code : null;
 }
+/**
+ * Last-resort ordering for candidates every other field has tied on.
+ *
+ * Reaching this means the engine has no evidence left: same span, no cue, same
+ * priority, the same (usually zero) country score, and the same declared scope.
+ * Something still has to win, and before this the winner was whichever candidate
+ * happened to be generated first — which is country *registration* order, and
+ * the two SDKs do not share one. Python registers alphabetically
+ * (`AT, BE, BG, CH, CY, CZ, ...`); this SDK uses a curated order
+ * (`NL, BE, DE, AT, CH, FR, ..., PT, LU, PL, ..., CZ`). So a bare digit run that
+ * several national schemes accept was filed as a Czech `NATIONAL_ID` by Python
+ * and a Portuguese `PHONE` here — identical characters masked, contradictory
+ * labels, and `make parity` compared only characters, so it stayed green through
+ * the whole of 0.3.8.
+ *
+ * The order reproduces what Python already did rather than inventing a new one,
+ * because every accuracy figure this engine has published was measured with
+ * Python resolving these ties by its registration order. Ordering on the entity
+ * type instead was tried first and re-tuned the corpus twice over: it turned the
+ * German `Steuerß12345678911` from `TAX_ID`/DE into `NATIONAL_ID`/EL, and moved
+ * 820 further spans from `DOB` to `DATE_OF_DEATH`. So the key is deliberately
+ * not total — candidates from the same country are left to the stable sort,
+ * which preserves the order that country's pattern list was written in, and both
+ * SDKs write theirs in the same order.
+ *
+ * Taken from the **pattern**, never the finished detection: this SDK re-types a
+ * cued candidate before the sort and Python re-types after it, so keying on the
+ * final type would reintroduce the divergence in a subtler form.
+ *
+ * Kept character-for-character in step with `tie_key` in `rules/engine.py`.
+ */
+export function tieKey(countryCode) {
+    // "SHARED" and "CUSTOM" are not countries and sort as themselves under a
+    // plain alphabetical key — landing between PT and SK, rather than ahead of
+    // every country the way the registry loads them. The bucket restores that.
+    const bucket = countryCode === "SHARED" ? "0" : countryCode === "CUSTOM" ? "1" : "2";
+    // NUL separator, written as an escape so this file stays plain ASCII, and
+    // matching Python byte for byte. It must sort below every character a code
+    // or type name can contain, or a code that is a prefix of another would
+    // order differently in the two SDKs.
+    return `${bucket}\u0000${countryCode}`;
+}
 const warnedCountries = new Set();
 function warnUnknownCountry(code) {
     if (warnedCountries.has(code))
@@ -203,7 +245,7 @@ export class RuleEngine {
             else if (m.patternDef.validator !== null && !m.patternDef.requiresContext) {
                 failedSpans.push({ start: m.start, end: m.end, code: m.countryCode,
                     etype: String(m.patternDef.entityType) });
-                if (CUE_TARGETS.has(String(m.patternDef.entityType))
+                if (RESCUE_TARGETS.has(String(m.patternDef.entityType))
                     && cuedType(text, m.start) === m.patternDef.entityType)
                     rescued.push(m);
             }
@@ -415,7 +457,7 @@ export class RuleEngine {
             // the value is filed as a Cypriot identity number. Dropping it also clears
             // outOfScope, which would otherwise claim the detection belongs to a
             // country the caller did not declare while naming no country at all.
-            const retyped = retypedBy(text, match.start, entityType);
+            const retyped = retypedBy(text, match.start, entityType, countryScores.get(match.countryCode) ?? 0);
             if (retyped !== null) {
                 entityType = retyped;
                 country = null;
@@ -429,6 +471,7 @@ export class RuleEngine {
                 length: match.end - match.start,
                 countryScore: countryScores.get(match.countryCode) ?? 0,
                 inScope: declared === null || declared.has(match.countryCode) ? 1 : 0,
+                tie: tieKey(match.countryCode),
                 tier: 0,
                 det: {
                     entityType,
@@ -467,6 +510,7 @@ export class RuleEngine {
                 length: match.end - match.start,
                 countryScore: countryScores.get(match.countryCode) ?? 0,
                 inScope: declared === null || declared.has(match.countryCode) ? 1 : 0,
+                tie: tieKey(match.countryCode),
                 tier: 0,
                 det: {
                     entityType: match.patternDef.entityType,
@@ -482,7 +526,8 @@ export class RuleEngine {
         }
         for (const d of detectStructuralDob(text)) {
             candidates.push({ blindPriority: 1, cue: 0, priority: 1, length: d.end - d.start,
-                countryScore: 0, inScope: 1, tier: 0, det: d });
+                countryScore: 0, inScope: 1, tier: 0, det: d,
+                tie: tieKey(d.country ?? "") });
         }
         const detections = this.deduplicate(candidates);
         detections.sort((a, b) => a.start - b.start || b.end - a.end);
@@ -550,7 +595,8 @@ export class RuleEngine {
             b.cue - a.cue || // local cue         } country-aware
             b.priority - a.priority || // country priority  } — decides the
             b.countryScore - a.countryScore || // country evidence  } LABEL only
-            b.inScope - a.inScope); // declared scope    }
+            b.inScope - a.inScope || // declared scope    }
+            (a.tie < b.tie ? -1 : a.tie > b.tie ? 1 : 0)); // total   } — see tieKey
         const result = [];
         const occupied = new Set();
         for (const { det } of sorted) {

package/dist/esm/rules/suppressors.js

@@ -343,6 +343,53 @@ function suppressYearAsPostal(text, match) {
     // Suppress: recent years without postal context are almost never postal codes
     return true;
 }
+// ── Postal code: disqualified by the word in front of it ───────────────
+//
+// The mirror image of `rules/cues.ts`. There a label promotes a type; here a
+// word refuses one. Both were reported together: a bare four-digit run becomes
+// a POSTAL_CODE as soon as *any* real postal code establishes the country,
+// which is to say in almost every real document, because POSTAL_CONTEXT_NEAR
+// above then rescues it from suppressYearAsPostal. Measured on the training
+// corpus: 55 bare years in prose ("Opgericht in 2016", "Fondée en 2017") plus
+// telephone extensions ("(toest. 3841)", "(poste interne 3318)", "(ext. 2219)").
+/**
+ * Prepositions that can only be temporal. Nothing is ever located "since 2018",
+ * so these disqualify a postal code on their own.
+ */
+const YEAR_WORD_BEFORE = /(?<![A-Za-z0-9_])(?:sinds|since|depuis|seit|siden|sedan|desde|vuonna|anno|dal)\s+$/i;
+/**
+ * "in", "en" and "im" are *both* temporal and locative, and in exactly the
+ * countries whose postal codes are year-shaped. Belgian 2000 is Antwerp and
+ * 2018 is one of its districts, so "Rustige ligging in 2018, vlakbij openbaar
+ * vervoer" is an address, not a date — an earlier version of this rule
+ * suppressed it and lost a real postal code, which is the worse error for a
+ * redaction tool. So an ambiguous preposition needs a founding or payment
+ * participle in front of it, which is what every case in the report had:
+ * "Opgericht in 2016", "Fondée en 2017", "versé en 2025".
+ */
+const YEAR_VERB_BEFORE = /(?<![A-Za-z0-9_])(?:opgericht|gesticht|opgestart|founded|established|created|fond[ée]e?|cr[ée][ée]e?|gegründet|gegruendet|errichtet|grundlagt|grundad|perustettu|fundada|fundado|fondata|costituita|vers[ée]|betaald|uitbetaald|ausgezahlt|paid|geboren|born)\s+(?:in|en|im|op|the)\s+$/i;
+/**
+ * A capitalised word immediately after keeps the candidate: "in 2000 Antwerpen"
+ * really is a postal code, and so is the "AZ" of a Dutch "1105 AZ". Without
+ * this the rule would suppress the very addresses it is meant to leave alone.
+ */
+const TOWN_AFTER = /^\s*[A-ZÀ-ÞĀ-Ž]/;
+/**
+ * A telephone extension marker. "poste interne 3318" puts one qualifier word
+ * between the marker and the number, so allow exactly one.
+ */
+const EXTENSION_BEFORE = /(?<![A-Za-z0-9_])(?:toest(?:el)?|ext|extension|poste|durchwahl|doorkiesnummer|tst|nebenstelle)\.?\s*(?:[a-zà-ÿ]{2,10}\s*)?[:.]?\s*$/i;
+/** Suppress a postal code the word in front of it rules out. */
+function suppressPostalAfterDisqualifyingWord(text, match) {
+    if (match.patternDef.entityType !== EntityType.POSTAL_CODE)
+        return false;
+    const before = text.slice(Math.max(0, match.start - 24), match.start);
+    if (EXTENSION_BEFORE.test(before))
+        return true;
+    return RECENT_YEAR.test(match.text.trim())
+        && (YEAR_WORD_BEFORE.test(before) || YEAR_VERB_BEFORE.test(before))
+        && !TOWN_AFTER.test(text.slice(match.end, match.end + 3));
+}
 function suppressPhoneServiceNumber(_text, match) {
     if (match.patternDef.entityType !== EntityType.PHONE)
         return false;
@@ -791,7 +838,7 @@ const TYPE_SUPPRESSORS = {
     [EntityType.NATIONAL_ID]: [suppressCurrency, suppressUnits, suppressReference, suppressLegal, suppressMath, suppressNatidAsPassport, suppressSeNatidAsOrg],
     [EntityType.SSN]: [suppressCurrency, suppressUnits, suppressReference, suppressMath],
     [EntityType.TAX_ID]: [suppressCurrency, suppressUnits, suppressReference, suppressMath, suppressTaxidAsIpAddress],
-    [EntityType.POSTAL_CODE]: [suppressCurrency, suppressUnits, suppressMath, suppressLegal, suppressYearAsPostal, suppressPostalInsideIban, suppressPostalAsHouseNumber, suppressPostalInLongerIdentifier, suppressReference],
+    [EntityType.POSTAL_CODE]: [suppressCurrency, suppressUnits, suppressMath, suppressLegal, suppressYearAsPostal, suppressPostalAfterDisqualifyingWord, suppressPostalInsideIban, suppressPostalAsHouseNumber, suppressPostalInLongerIdentifier, suppressReference],
     [EntityType.BIC]: [suppressBicWithoutEvidence],
     [EntityType.BANK_ACCOUNT]: [suppressReference],
     [EntityType.LICENSE_PLATE]: [suppressPlateInCompound, suppressDePlateUnknownDistrict, suppressPlateAsCurrencyAmount],

package/dist/esm/sdk.d.ts

@@ -40,5 +40,12 @@ export declare class EuRedact {
      *  Call this in long-running processes to free PII from memory. */
     clear(): void;
     redact(text: string, options?: RedactOptions): RedactResult;
+    /**
+     * Redact, awaiting the cloud tier when `mode: "cloud"` is asked for.
+     *
+     * `mode: "rules"` resolves immediately with exactly what `redact()` returns,
+     * so callers that may or may not use the cloud tier can hold one code path.
+     */
+    redactAsync(text: string, options?: RedactOptions): Promise<RedactResult>;
     redactBatch(texts: string[], options?: RedactOptions): RedactResult[];
 }

package/dist/esm/sdk.js

@@ -45,6 +45,40 @@ class ReferentialMapper {
     }
 }
 const DEFAULT_MAX_INPUT_LENGTH = 10_485_760; // ~10 MB of text
+/**
+ * Send a document to the cloud tier.
+ *
+ * Options the service cannot honour throw rather than being ignored. Silently
+ * dropping one would mean returning a result that does not match what was
+ * asked for — which, for anything that changes which spans come back, is
+ * under-redaction wearing a plausible face.
+ */
+async function redactViaCloud(text, options) {
+    const { CloudClient } = await import("./cloud/client.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 ' +
+            "model is trained and evaluated per country, so a multi-country request " +
+            "has no defined behaviour.");
+    }
+    if (options.countryHint) {
+        throw new Error("countryHint is not supported in cloud mode");
+    }
+    if (options.context || options.chunkOffset) {
+        throw new Error("context/chunkOffset are not supported in cloud mode: the model has never " +
+            "seen a chunk boundary, so the service rejects oversized input rather " +
+            "than splitting it");
+    }
+    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.
+    return new CloudClient().redact(text, { country: countries[0] });
+}
 /**
  * Reject a bare string where a list of country codes is expected.
  *
@@ -92,6 +126,19 @@ export class EuRedact {
     redact(text, options = {}) {
         checkCountryArg(options.countries, "countries");
         checkCountryArg(options.countryHint, "countryHint");
+        const requestedMode = options.mode ?? "rules";
+        if (requestedMode === "cloud") {
+            // Cannot be served synchronously: the cloud tier is a network call, and
+            // returning rules-only output instead would be the silent under-redaction
+            // this guard exists to prevent. Point at the async entry point rather
+            // than inventing a Promise-or-value union return type.
+            throw new Error('mode: "cloud" is asynchronous — use redactAsync(text, { mode: "cloud" }) ' +
+                "(or EuRedact#redactAsync). redact() is synchronous and can only serve " +
+                'mode: "rules".');
+        }
+        if (requestedMode !== "rules") {
+            throw new Error(`unknown mode ${JSON.stringify(requestedMode)}: expected "rules" or "cloud"`);
+        }
         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 ` +
@@ -175,6 +222,18 @@ export class EuRedact {
         }
         return result;
     }
+    /**
+     * Redact, awaiting the cloud tier when `mode: "cloud"` is asked for.
+     *
+     * `mode: "rules"` resolves immediately with exactly what `redact()` returns,
+     * so callers that may or may not use the cloud tier can hold one code path.
+     */
+    async redactAsync(text, options = {}) {
+        const mode = options.mode ?? "rules";
+        if (mode !== "cloud")
+            return this.redact(text, options);
+        return redactViaCloud(text, options);
+    }
     redactBatch(texts, options = {}) {
         // Generation is country-blind, so every country's patterns are loaded
         // regardless of what the caller declared.

package/dist/esm/types.d.ts

@@ -1,5 +1,20 @@
 export declare enum EntityType {
-    NAME = "NAME",
+    /**
+     * Canonical name for a person's name. `NAME` is kept below as a legacy alias
+     * with the same value, exactly as `IBAN` aliases `BANK_ACCOUNT`, so
+     * `EntityType.NAME === EntityType.PERSON_NAME` and existing code keeps
+     * working — but the emitted value, and therefore the `[PERSON_NAME]`
+     * placeholder written into redacted text, is canonical.
+     *
+     * Renamed rather than translated at the cloud boundary: two names for one
+     * type is how a whole category goes missing when someone filters on the
+     * spelling they happened to know. Nothing could have depended on the old
+     * value — the type is cloud-only and the cloud tier was stubbed, so it was
+     * never emitted.
+     */
+    PERSON_NAME = "PERSON_NAME",
+    /** @deprecated legacy alias of {@link EntityType.PERSON_NAME} */
+    NAME = "PERSON_NAME",
     ADDRESS = "ADDRESS",
     /**
      * Canonical name for a bank account identifier. `IBAN` is kept below as a
@@ -47,6 +62,15 @@ export declare enum EntityType {
     UUID = "UUID",
     SOCIAL_HANDLE = "SOCIAL_HANDLE",
     SECRET = "SECRET",
+    ORGANISATION_NAME = "ORGANISATION_NAME",
+    JOB_TITLE = "JOB_TITLE",
+    MEDICAL_CONDITION = "MEDICAL_CONDITION",
+    SENSITIVE_ATTRIBUTE = "SENSITIVE_ATTRIBUTE",
+    BIOMETRIC_REF = "BIOMETRIC_REF",
+    FINANCIAL_AMOUNT = "FINANCIAL_AMOUNT",
+    QUASI_IDENTIFIER = "QUASI_IDENTIFIER",
+    CREDENTIAL = "CREDENTIAL",
+    URL = "URL",
     OTHER = "OTHER"
 }
 /**
@@ -55,6 +79,14 @@ export declare enum EntityType {
  * legacy_aliases). The engine never *emits* these names.
  */
 export declare const LEGACY_TYPE_ALIASES: Record<string, string>;
+/**
+ * Resolve a possibly-legacy type name to its canonical form.
+ *
+ * Mirrors `EntityType._missing_` in the Python SDK. An unrecognised name is
+ * returned unchanged rather than dropped: a client one release behind the
+ * service must not silently lose a whole category of PII.
+ */
+export declare function canonicalType(name: string): string;
 export declare enum DetectionSource {
     RULES = "rules",
     CLOUD = "cloud"

package/dist/esm/types.js

@@ -1,6 +1,21 @@
 export var EntityType;
 (function (EntityType) {
-    EntityType["NAME"] = "NAME";
+    /**
+     * Canonical name for a person's name. `NAME` is kept below as a legacy alias
+     * with the same value, exactly as `IBAN` aliases `BANK_ACCOUNT`, so
+     * `EntityType.NAME === EntityType.PERSON_NAME` and existing code keeps
+     * working — but the emitted value, and therefore the `[PERSON_NAME]`
+     * placeholder written into redacted text, is canonical.
+     *
+     * Renamed rather than translated at the cloud boundary: two names for one
+     * type is how a whole category goes missing when someone filters on the
+     * spelling they happened to know. Nothing could have depended on the old
+     * value — the type is cloud-only and the cloud tier was stubbed, so it was
+     * never emitted.
+     */
+    EntityType["PERSON_NAME"] = "PERSON_NAME";
+    /** @deprecated legacy alias of {@link EntityType.PERSON_NAME} */
+    EntityType["NAME"] = "PERSON_NAME";
     EntityType["ADDRESS"] = "ADDRESS";
     /**
      * Canonical name for a bank account identifier. `IBAN` is kept below as a
@@ -48,6 +63,20 @@ export var EntityType;
     EntityType["UUID"] = "UUID";
     EntityType["SOCIAL_HANDLE"] = "SOCIAL_HANDLE";
     EntityType["SECRET"] = "SECRET";
+    // ── [CLOUD EXTENSION] ────────────────────────────────────────────────────
+    // Types only the cloud tier can detect. The rule engine never emits these —
+    // there is no shape to match on — which is exactly why they exist: the
+    // model's job is what the rules cannot catch. Named to match the detection
+    // canon the service is trained and evaluated against.
+    EntityType["ORGANISATION_NAME"] = "ORGANISATION_NAME";
+    EntityType["JOB_TITLE"] = "JOB_TITLE";
+    EntityType["MEDICAL_CONDITION"] = "MEDICAL_CONDITION";
+    EntityType["SENSITIVE_ATTRIBUTE"] = "SENSITIVE_ATTRIBUTE";
+    EntityType["BIOMETRIC_REF"] = "BIOMETRIC_REF";
+    EntityType["FINANCIAL_AMOUNT"] = "FINANCIAL_AMOUNT";
+    EntityType["QUASI_IDENTIFIER"] = "QUASI_IDENTIFIER";
+    EntityType["CREDENTIAL"] = "CREDENTIAL";
+    EntityType["URL"] = "URL";
     EntityType["OTHER"] = "OTHER";
 })(EntityType || (EntityType = {}));
 /**
@@ -57,7 +86,21 @@ export var EntityType;
  */
 export const LEGACY_TYPE_ALIASES = {
     IBAN: "BANK_ACCOUNT",
+    NAME: "PERSON_NAME",
+    STREET_ADDRESS: "ADDRESS",
+    NATIONALITY_ETHNICITY: "SENSITIVE_ATTRIBUTE",
 };
+/**
+ * Resolve a possibly-legacy type name to its canonical form.
+ *
+ * Mirrors `EntityType._missing_` in the Python SDK. An unrecognised name is
+ * returned unchanged rather than dropped: a client one release behind the
+ * service must not silently lose a whole category of PII.
+ */
+export function canonicalType(name) {
+    const upper = String(name ?? "").trim().toUpperCase();
+    return LEGACY_TYPE_ALIASES[upper] ?? upper;
+}
 export var DetectionSource;
 (function (DetectionSource) {
     DetectionSource["RULES"] = "rules";