euredact 0.3.0 → 0.3.2

package/dist/esm/rules/engine.js

@@ -3,6 +3,7 @@ import { MultiPatternMatcher } from "./matchers.js";
 import { shouldSuppress } from "./suppressors.js";
 import { detectStructuralDob } from "./structural.js";
 import { COUNTRY_CONFIGS } from "./countries/index.js";
+import * as evidenceMod from "./evidence.js";
 /**
  * Heuristic to detect nested quantifiers that cause catastrophic backtracking.
  * After stripping escaped chars and character classes, look for an unbounded
@@ -100,118 +101,248 @@ export class RuleEngine {
         if (newCountries)
             this.matcher.compile();
     }
-    detect(text, countryCodes) {
-        this.loadCountries(countryCodes);
-        // Scope the scan to requested countries for efficiency
-        // Resolve through the alias table so `countries: ["GB"]` actually scans
-        // the patterns registered under "UK".
-        let scanCodes = null;
+    /**
+     * Generate candidate matches. Country-blind, by contract.
+     *
+     * This is the only caller of {@link MultiPatternMatcher.scan}, and it takes
+     * no country argument. Which country the caller declared may influence how a
+     * match is *scored*; it may never influence whether the match is *found*.
+     * Before this held, `countries: ["BE"]` made a valid Dutch BSN vanish
+     * entirely because the Dutch patterns were never run.
+     */
+    generateCandidates(text) {
+        this.loadCountries(null);
+        return this.matcher.scan(text, null);
+    }
+    detect(text, countryCodes, countryHint) {
+        return this.detectWithEvidence(text, countryCodes, countryHint).detections;
+    }
+    /**
+     * {@link RuleEngine.detect}, plus the country evidence it reasoned from.
+     *
+     * `countryCodes` is **scope**: it flags detections from elsewhere as
+     * `outOfScope` and, like `countryHint`, contributes a prior. `countryHint` is
+     * **only** a prior — it helps resolve ambiguity without marking anything out
+     * of scope. Neither gates what is looked for.
+     */
+    detectWithEvidence(text, countryCodes, countryHint, priorEvidence) {
+        const rawMatches = this.generateCandidates(text);
+        // The declared countries are a scoring signal from here on: they rank
+        // candidates and flag out-of-scope detections. They do not gate.
+        let declared = null;
         if (countryCodes !== null) {
-            scanCodes = new Set();
+            declared = new Set();
             for (const c of countryCodes) {
                 const code = resolveCountryCode(c);
-                if (code !== null)
-                    scanCodes.add(code);
+                if (code === null)
+                    warnUnknownCountry(c);
+                else
+                    declared.add(code);
             }
-            scanCodes.add("SHARED");
-            scanCodes.add("CUSTOM");
+            declared.add("SHARED");
+            declared.add("CUSTOM");
+        }
+        // The prior fed to the evidence bus. Declared countries count too — a
+        // caller naming a country is asserting context, which is exactly what a
+        // prior is — but a hint never narrows scope, so it is kept out of
+        // `declared` and cannot flag anything out of scope.
+        const prior = new Set(declared ?? []);
+        for (const c of countryHint ?? []) {
+            const code = resolveCountryCode(c);
+            if (code === null)
+                warnUnknownCountry(c);
+            else
+                prior.add(code);
         }
-        let rawMatches = this.matcher.scan(text, scanCodes);
-        // Matches that have a validator but fail it create suppression zones:
-        // the span is recognisably a specific entity (e.g. IBAN-shaped) so
-        // overlapping regex-only matches (license plate, phone) are false
-        // positives and must be suppressed.
+        // Pass 1: checksum validation. A span that matched a checksummed pattern
+        // but failed the checksum is recorded with its country and entity type;
+        // what it is allowed to demote is decided below, once the document's
+        // countries are known.
         const validated = [];
-        const rawZones = [];
+        const failedSpans = [];
         for (const m of rawMatches) {
-            const isValid = this.matcher.validate(m);
-            if (isValid) {
+            if (this.matcher.validate(m)) {
                 validated.push({ match: m, hasValidValidator: m.patternDef.validator !== null });
             }
             else if (m.patternDef.validator !== null && !m.patternDef.requiresContext) {
-                rawZones.push([m.start, m.end]);
+                failedSpans.push({ start: m.start, end: m.end, code: m.countryCode,
+                    etype: String(m.patternDef.entityType) });
             }
         }
-        // Merge overlapping suppression zones for O(log n) containment checks
-        let zoneStarts = [];
-        let zoneEnds = [];
-        if (rawZones.length > 0) {
-            rawZones.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
-            let [ms, me] = rawZones[0];
-            for (let i = 1; i < rawZones.length; i++) {
-                const [zs, ze] = rawZones[i];
-                if (zs <= me) {
+        // Evidence pass: work out which countries this document belongs to, from
+        // the entities that carry their country in the string.
+        //
+        // Every surviving candidate is eligible, not only checksum-backed ones. An
+        // earlier version required a validator here, which silently dropped the
+        // email ccTLD — the second-strongest signal at 4.50 log-odds and present in
+        // 98,949 of 152,300 corpus documents — because EMAIL has nothing to
+        // checksum. Candidates that failed a validator never reach `validated`, so
+        // this admits the unvalidatable, not the invalid.
+        const evidenceDets = [];
+        for (const { match } of validated) {
+            if (!evidenceMod.EVIDENCE_TYPES.has(String(match.patternDef.entityType)))
+                continue;
+            evidenceDets.push({
+                entityType: match.patternDef.entityType,
+                start: match.start, end: match.end, text: match.text,
+                source: DetectionSource.RULES,
+                country: (match.countryCode !== "SHARED" && match.countryCode !== "CUSTOM")
+                    ? match.countryCode : null,
+                confidence: "high",
+            });
+        }
+        const countryEvidence = evidenceMod.collect(evidenceDets);
+        const countryScores = evidenceMod.accumulate(priorEvidence && priorEvidence.length ? [...countryEvidence, ...priorEvidence] : countryEvidence, prior);
+        const hasScores = countryScores.size > 0;
+        const corroborated = (code) => !hasScores || code === "SHARED" || code === "CUSTOM" || countryScores.has(code);
+        // Now that the document's countries are known, decide which failed
+        // validators are entitled to demote anything. A checksum failure only means
+        // "not a valid X"; it says nothing about the span unless X was plausible
+        // here in the first place. A Belgian national-ID pattern failing on
+        // 0612345678 is not evidence against that span being a Dutch phone number.
+        //
+        // Zones are also per entity type. A failed checksum is evidence against
+        // *that type*, not against the span: Sweden's own personnummer checksum
+        // failing on 0708787668 used to demote the Swedish *phone* candidate for
+        // the same digits, handing the span to a Danish CPR that happened to
+        // validate. Worth 878 mistyped phone numbers per 30,000 documents.
+        const zonesByType = new Map();
+        for (const f of failedSpans) {
+            if (!corroborated(f.code))
+                continue;
+            const list = zonesByType.get(f.etype);
+            if (list)
+                list.push([f.start, f.end]);
+            else
+                zonesByType.set(f.etype, [[f.start, f.end]]);
+        }
+        const mergedZones = new Map();
+        for (const [etype, spans] of zonesByType) {
+            spans.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+            const starts = [];
+            const ends = [];
+            let [ms, me] = spans[0];
+            for (let i = 1; i < spans.length; i++) {
+                const [zs, ze] = spans[i];
+                if (zs <= me)
                     me = Math.max(me, ze);
-                }
                 else {
-                    zoneStarts.push(ms);
-                    zoneEnds.push(me);
+                    starts.push(ms);
+                    ends.push(me);
                     ms = zs;
                     me = ze;
                 }
             }
-            zoneStarts.push(ms);
-            zoneEnds.push(me);
+            starts.push(ms);
+            ends.push(me);
+            mergedZones.set(etype, { starts, ends });
         }
-        // Build candidates with priority: validated (3) > custom (2) > regex-only (1)
         const candidates = [];
         for (const { match, hasValidValidator } of validated) {
             if (shouldSuppress(text, match))
                 continue;
-            // O(log n) binary-search containment check on merged zones
-            if (match.patternDef.validator === null && zoneStarts.length > 0) {
-                let lo = 0, hi = zoneStarts.length;
-                while (lo < hi) {
-                    const mid = (lo + hi) >>> 1;
-                    if (zoneStarts[mid] <= match.start)
-                        lo = mid + 1;
-                    else
-                        hi = mid;
+            // A validator-less match inside a failed-validation span of its own type
+            // is demoted below every other candidate rather than deleted. Demotion
+            // cannot silence a detection, which is the property deletion lacked:
+            // measured across the corpus, deletion removed 454 detections of which
+            // 454 overlapped real labelled PII.
+            let demoted = false;
+            if (match.patternDef.validator === null) {
+                const zone = mergedZones.get(String(match.patternDef.entityType));
+                if (zone) {
+                    let lo = 0, hi = zone.starts.length;
+                    while (lo < hi) {
+                        const mid = (lo + hi) >>> 1;
+                        if (zone.starts[mid] <= match.start)
+                            lo = mid + 1;
+                        else
+                            hi = mid;
+                    }
+                    const idx = lo - 1;
+                    demoted = idx >= 0 && zone.ends[idx] >= match.end;
                 }
-                const idx = lo - 1;
-                if (idx >= 0 && zoneEnds[idx] >= match.end)
-                    continue;
             }
-            // A bare digit run is the weakest evidence in the engine and must never
-            // re-cut a span a structured detector claims (PHONE, SSN, NATIONAL_ID,
-            // BANK_ACCOUNT, VAT...). Postal codes take unclaimed spans only,
-            // whatever the span lengths.
-            const priority = hasValidValidator
-                ? 3
-                : match.countryCode === "CUSTOM"
-                    ? 2
-                    : match.patternDef.entityType === EntityType.POSTAL_CODE
-                        ? 0
-                        : 1;
-            const spanLength = match.end - match.start;
-            const score = priority * 1_000_000 + spanLength;
+            let priority;
+            if (demoted) {
+                priority = -1;
+            }
+            else if (hasValidValidator) {
+                // A passing checksum normally outranks everything. But a checksum only
+                // says the digits fit *some* national scheme, and weak ones fit by luck
+                // — a mod-11 scheme accepts a random number about one time in eleven.
+                // So a validated candidate from a country the document shows no trace
+                // of is treated as coincidence, not evidence.
+                //
+                // Concretely: the Dutch phone number 0612345678 also passes the Danish
+                // CPR checksum. Entities that carry their own country vouch for
+                // themselves — an IBAN emits evidence for its own country — so a
+                // foreign IBAN in a domestic invoice keeps its rank.
+                priority = corroborated(match.countryCode) ? 3 : 1;
+            }
+            else if (match.countryCode === "CUSTOM") {
+                priority = 2;
+            }
+            else if (match.patternDef.entityType === EntityType.POSTAL_CODE) {
+                // A bare digit run is the weakest evidence in the engine and must never
+                // re-cut a span a structured detector claims (PHONE, SSN, NATIONAL_ID,
+                // BANK_ACCOUNT, VAT...). Postal codes take unclaimed spans only,
+                // whatever the span lengths.
+                priority = 0;
+            }
+            else {
+                priority = 1;
+            }
+            const country = (match.countryCode !== "SHARED" && match.countryCode !== "CUSTOM")
+                ? match.countryCode : null;
             candidates.push({
+                priority,
+                length: match.end - match.start,
+                countryScore: countryScores.get(match.countryCode) ?? 0,
+                inScope: declared === null || declared.has(match.countryCode) ? 1 : 0,
                 det: {
                     entityType: match.patternDef.entityType,
                     start: match.start,
                     end: match.end,
                     text: match.text,
                     source: DetectionSource.RULES,
-                    country: (match.countryCode !== "SHARED" && match.countryCode !== "CUSTOM") ? match.countryCode : null,
+                    country,
                     confidence: "high",
+                    outOfScope: declared !== null && country !== null && !declared.has(match.countryCode),
                 },
-                score,
             });
         }
         for (const d of detectStructuralDob(text)) {
-            candidates.push({ det: d, score: 1_000_000 + (d.end - d.start) });
+            candidates.push({ priority: 1, length: d.end - d.start, countryScore: 0, inScope: 1, det: d });
+        }
+        const detections = this.deduplicate(candidates);
+        detections.sort((a, b) => a.start - b.start || b.end - a.end);
+        // Attach the confidence behind each country attribution, so a caller can
+        // tell "Danish, and the document is plainly Danish" from "Danish, on a
+        // checksum alone".
+        const ranking = evidenceMod.weightsToRanking(countryScores);
+        for (const d of detections) {
+            d.countryConfidence = (d.country !== null ? ranking.get(d.country) : undefined) ?? 0;
         }
-        return this.deduplicate(candidates);
+        return { detections, evidence: countryEvidence, scores: countryScores };
     }
     /**
      * Remove overlapping detections with priority-aware resolution.
-     * Priority: validated (3) > custom (2) > regex-only (1).
-     * Within the same tier, longer span wins.
+     * Priority: validated (3) > custom (2) > regex-only (1) > postal (0) >
+     * demoted (-1). Within a tier, longer span wins, then country evidence.
      */
     deduplicate(candidates) {
         if (candidates.length === 0)
             return [];
-        const sorted = [...candidates].sort((a, b) => b.score - a.score);
+        // Span length outranks scope: preferring the declared country over the
+        // longest match can truncate an entity. Measured: with countries ["BE"],
+        // the Belgian phone pattern claims 11 of the 14 characters of
+        // "06 12 34 56 78" and leaves three digits exposed. Scope only breaks ties
+        // between candidates of equal length, so it can change WHICH country is
+        // attributed, never WHAT is masked.
+        const sorted = [...candidates].sort((a, b) => b.priority - a.priority ||
+            b.length - a.length ||
+            b.countryScore - a.countryScore ||
+            b.inScope - a.inScope);
         const result = [];
         const occupied = new Set();
         for (const { det } of sorted) {

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

@@ -0,0 +1,63 @@
+/**
+ * Country evidence: what a document says about which country it belongs to.
+ *
+ * Some entities carry their country in the string — an IBAN's country code, a
+ * `+CC` dialling prefix, a VAT prefix, an email ccTLD. Those are used to work
+ * out which country a document belongs to, which in turn decides which
+ * national scheme owns an ambiguous value elsewhere in the same document.
+ * 36.6% of national-ID values in the corpus validate under more than one
+ * country's checksum, so without this the engine cannot tell a Dutch BSN from
+ * a Polish PESEL.
+ *
+ * Evidence influences **scoring only**. It ranks candidates that already exist
+ * and annotates the result; it never decides what is looked for. A wrong
+ * inference must not be able to cause a miss.
+ *
+ * Weights are derived, not chosen — measured as P(document country = X |
+ * signal claims X) across the corpus. Kept identical to the Python SDK's
+ * `rules/evidence.py`; re-derive there and port, rather than tuning by feel.
+ */
+import { type CountryEvidence, type Detection } from "../types.js";
+export declare const WEIGHTS: Record<string, number>;
+/**
+ * E.164 calling code -> country, for the countries this engine supports. Codes
+ * are unique within this set; a shared code (+1, +7) would have to emit
+ * evidence for every candidate country rather than one.
+ */
+export declare const DIALLING_CODES: Record<string, string>;
+/**
+ * ccTLD -> country. Deliberately excludes .eu/.com/.org/.net: those are not
+ * weak evidence, they are no evidence, and treating them as weak would let a
+ * .com address outvote a genuine national signal.
+ */
+export declare const CC_TLDS: Record<string, string>;
+/** Entity types that can carry country evidence. */
+export declare const EVIDENCE_TYPES: ReadonlySet<string>;
+/**
+ * Country evidence carried by *detections*, in document order.
+ *
+ * Deduplicated by (span, source): several countries' patterns can match the
+ * same IBAN, and counting that span once per pattern would let a single entity
+ * outvote the rest of the document.
+ */
+export declare function collect(detections: Detection[]): CountryEvidence[];
+/**
+ * Sum evidence into a per-country log-odds score.
+ *
+ * Returns a weighted set, never a single winner: a Belgian supplier invoicing a
+ * German customer is not "70% Belgian", both countries are genuinely present,
+ * and an ambiguous value must be resolvable against either.
+ */
+export declare function accumulate(evidence: CountryEvidence[], declared?: Iterable<string> | null): Map<string, number>;
+/**
+ * Convert per-country log-odds into confidences in [0, 1].
+ *
+ * Each country is scored independently — a logistic on its own log-odds —
+ * because document countries are not mutually exclusive. A Belgian supplier
+ * invoicing a German customer is genuinely both; softmaxing across countries
+ * would report the German side of that invoice at 0.00 and make cross-border
+ * documents indistinguishable from misattributions.
+ *
+ * Confidences therefore do not sum to 1, by design.
+ */
+export declare function weightsToRanking(scores: Map<string, number>): Map<string, number>;

package/dist/esm/rules/evidence.js

@@ -0,0 +1,195 @@
+/**
+ * Country evidence: what a document says about which country it belongs to.
+ *
+ * Some entities carry their country in the string — an IBAN's country code, a
+ * `+CC` dialling prefix, a VAT prefix, an email ccTLD. Those are used to work
+ * out which country a document belongs to, which in turn decides which
+ * national scheme owns an ambiguous value elsewhere in the same document.
+ * 36.6% of national-ID values in the corpus validate under more than one
+ * country's checksum, so without this the engine cannot tell a Dutch BSN from
+ * a Polish PESEL.
+ *
+ * Evidence influences **scoring only**. It ranks candidates that already exist
+ * and annotates the result; it never decides what is looked for. A wrong
+ * inference must not be able to cause a miss.
+ *
+ * Weights are derived, not chosen — measured as P(document country = X |
+ * signal claims X) across the corpus. Kept identical to the Python SDK's
+ * `rules/evidence.py`; re-derive there and port, rather than tuning by feel.
+ */
+import { EntityType } from "../types.js";
+// ── Derived weights ─────────────────────────────────────────────────────
+//
+// Measured on 152,300 documents:
+//
+//   signal          agree    total   P(doc=X|signal)   raw log-odds
+//   e164Prefix     41,402   41,402          0.9999             9.21
+//   bicCountry      2,588    2,588          0.9999             9.21
+//   emailTld       97,865   98,949          0.9890             4.50
+//   vatPrefix      19,022   20,136          0.9447             2.84
+//   ibanPrefix    110,572  126,428          0.8746             1.94
+//
+// The IBAN prefix being the *weakest* signal is real and worth knowing: a
+// Belgian IBAN in a Dutch invoice is ordinary, so the account's country is only
+// weak evidence about the document's.
+//
+// The perfect scores are capped. They are perfect because the generator emits
+// country-consistent values, not because a foreign mobile number never appears
+// in a real document. Treating a synthetic 1.0 as certainty would make a single
+// phone number unfalsifiable by any amount of contrary evidence.
+const MAX_LOG_ODDS = 4.0;
+export const WEIGHTS = {
+    e164Prefix: Math.min(9.21, MAX_LOG_ODDS),
+    bicCountry: Math.min(9.21, MAX_LOG_ODDS),
+    emailTld: Math.min(4.5, MAX_LOG_ODDS),
+    vatPrefix: 2.84,
+    ibanPrefix: 1.94,
+    declared: 2.0, // the caller's `countries`, a prior rather than a measurement
+};
+// ── Signal tables ───────────────────────────────────────────────────────
+/**
+ * E.164 calling code -> country, for the countries this engine supports. Codes
+ * are unique within this set; a shared code (+1, +7) would have to emit
+ * evidence for every candidate country rather than one.
+ */
+export const DIALLING_CODES = {
+    "43": "AT", "32": "BE", "359": "BG", "41": "CH", "357": "CY", "420": "CZ",
+    "49": "DE", "45": "DK", "372": "EE", "30": "EL", "34": "ES", "358": "FI",
+    "33": "FR", "385": "HR", "36": "HU", "353": "IE", "354": "IS", "39": "IT",
+    "370": "LT", "352": "LU", "371": "LV", "356": "MT", "31": "NL", "47": "NO",
+    "48": "PL", "351": "PT", "40": "RO", "46": "SE", "386": "SI", "421": "SK",
+    "44": "UK",
+};
+/**
+ * ccTLD -> country. Deliberately excludes .eu/.com/.org/.net: those are not
+ * weak evidence, they are no evidence, and treating them as weak would let a
+ * .com address outvote a genuine national signal.
+ */
+export const CC_TLDS = {
+    at: "AT", be: "BE", bg: "BG", ch: "CH", cy: "CY", cz: "CZ",
+    de: "DE", dk: "DK", ee: "EE", gr: "EL", es: "ES", fi: "FI",
+    fr: "FR", hr: "HR", hu: "HU", ie: "IE", is: "IS", it: "IT",
+    lt: "LT", lu: "LU", lv: "LV", mt: "MT", nl: "NL", no: "NO",
+    pl: "PL", pt: "PT", ro: "RO", se: "SE", si: "SI", sk: "SK",
+    uk: "UK",
+};
+/** VAT prefixes that are not the ISO code: Greece trades as EL, Northern
+ *  Ireland as XI. Naive alpha-2 handling gets both wrong. */
+const VAT_PREFIX_OVERRIDES = { EL: "EL", XI: "UK" };
+const emitIban = (det) => {
+    const code = det.text.slice(0, 2).toUpperCase();
+    if (!/^[A-Z]{2}$/.test(code))
+        return [];
+    return [{ country: code, source: "ibanPrefix", logOdds: WEIGHTS.ibanPrefix,
+            span: [det.start, det.end] }];
+};
+const emitE164 = (det) => {
+    if (!det.text.trimStart().startsWith("+"))
+        return [];
+    const digits = det.text.replace(/\D/g, "");
+    for (const len of [3, 2]) {
+        const country = DIALLING_CODES[digits.slice(0, len)];
+        if (country) {
+            return [{ country, source: "e164Prefix", logOdds: WEIGHTS.e164Prefix,
+                    span: [det.start, det.end] }];
+        }
+    }
+    return [];
+};
+const emitVat = (det) => {
+    const prefix = det.text.slice(0, 2).toUpperCase();
+    if (!/^[A-Z]{2}$/.test(prefix))
+        return [];
+    const country = VAT_PREFIX_OVERRIDES[prefix] ?? prefix;
+    return [{ country, source: "vatPrefix", logOdds: WEIGHTS.vatPrefix,
+            span: [det.start, det.end] }];
+};
+const emitBic = (det) => {
+    const clean = det.text.replace(/ /g, "").toUpperCase();
+    if (clean.length < 6)
+        return [];
+    return [{ country: clean.slice(4, 6), source: "bicCountry",
+            logOdds: WEIGHTS.bicCountry, span: [det.start, det.end] }];
+};
+const emitTld = (det) => {
+    const parts = det.text.split(".");
+    const country = CC_TLDS[parts[parts.length - 1].toLowerCase()];
+    if (!country)
+        return [];
+    return [{ country, source: "emailTld", logOdds: WEIGHTS.emailTld,
+            span: [det.start, det.end] }];
+};
+/** Dispatch by entity type, mirroring the suppressor tables. */
+const TYPE_EMITTERS = {
+    [EntityType.BANK_ACCOUNT]: [emitIban],
+    [EntityType.PHONE]: [emitE164],
+    [EntityType.VAT]: [emitVat],
+    [EntityType.BIC]: [emitBic],
+    [EntityType.EMAIL]: [emitTld],
+};
+/** Entity types that can carry country evidence. */
+export const EVIDENCE_TYPES = new Set(Object.keys(TYPE_EMITTERS));
+/**
+ * Country evidence carried by *detections*, in document order.
+ *
+ * Deduplicated by (span, source): several countries' patterns can match the
+ * same IBAN, and counting that span once per pattern would let a single entity
+ * outvote the rest of the document.
+ */
+export function collect(detections) {
+    const evidence = [];
+    const seen = new Set();
+    for (const det of detections) {
+        for (const emit of TYPE_EMITTERS[det.entityType] ?? []) {
+            for (const ev of emit(det)) {
+                const key = `${ev.span[0]}:${ev.span[1]}:${ev.source}`;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    evidence.push(ev);
+                }
+            }
+        }
+    }
+    // Document order, not pattern-registration order: this list is an audit
+    // trail, and a reader checking it against the text should not have to jump
+    // around. Also keeps the two SDKs byte-comparable.
+    evidence.sort((a, b) => a.span[0] - b.span[0] || a.span[1] - b.span[1]);
+    return evidence;
+}
+/**
+ * Sum evidence into a per-country log-odds score.
+ *
+ * Returns a weighted set, never a single winner: a Belgian supplier invoicing a
+ * German customer is not "70% Belgian", both countries are genuinely present,
+ * and an ambiguous value must be resolvable against either.
+ */
+export function accumulate(evidence, declared) {
+    const scores = new Map();
+    for (const ev of evidence) {
+        scores.set(ev.country, (scores.get(ev.country) ?? 0) + ev.logOdds);
+    }
+    for (const country of declared ?? []) {
+        if (country !== "SHARED" && country !== "CUSTOM") {
+            scores.set(country, (scores.get(country) ?? 0) + WEIGHTS.declared);
+        }
+    }
+    return scores;
+}
+/**
+ * Convert per-country log-odds into confidences in [0, 1].
+ *
+ * Each country is scored independently — a logistic on its own log-odds —
+ * because document countries are not mutually exclusive. A Belgian supplier
+ * invoicing a German customer is genuinely both; softmaxing across countries
+ * would report the German side of that invoice at 0.00 and make cross-border
+ * documents indistinguishable from misattributions.
+ *
+ * Confidences therefore do not sum to 1, by design.
+ */
+export function weightsToRanking(scores) {
+    const out = new Map();
+    for (const [country, score] of scores) {
+        out.set(country, 1 / (1 + Math.exp(-score)));
+    }
+    return out;
+}

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

@@ -7,6 +7,16 @@ export declare class MultiPatternMatcher {
     addPattern(patternDef: PatternDef, countryCode: string): void;
     addCountry(config: CountryConfig): void;
     compile(): void;
+    /**
+     * Scan text against patterns.
+     *
+     * `countryCodes` restricts which patterns run. **The engine never passes
+     * it.** Generation is country-blind by contract — see
+     * `RuleEngine.generateCandidates` and `src/__tests__/inference.ts` — because
+     * gating generation on the caller's declared country caused silent misses.
+     * The parameter is kept for a future opt-in fast mode, which would be the
+     * only caller permitted to trade recall for speed.
+     */
     scan(text: string, countryCodes?: Set<string> | null): RawMatch[];
     validate(match: RawMatch): boolean;
 }

package/dist/esm/rules/matchers.js

@@ -19,6 +19,16 @@ export class MultiPatternMatcher {
     compile() {
         this.compiled = true;
     }
+    /**
+     * Scan text against patterns.
+     *
+     * `countryCodes` restricts which patterns run. **The engine never passes
+     * it.** Generation is country-blind by contract — see
+     * `RuleEngine.generateCandidates` and `src/__tests__/inference.ts` — because
+     * gating generation on the caller's declared country caused silent misses.
+     * The parameter is kept for a future opt-in fast mode, which would be the
+     * only caller permitted to trade recall for speed.
+     */
     scan(text, countryCodes = null) {
         if (!this.compiled)
             this.compile();