@discretion/core 0.1.0

package/dist/src/fuse/explain.js

@@ -0,0 +1,91 @@
+/**
+ * Stage 4 — EXPLANATIONS.
+ *
+ * SPEC.md: "Every emitted entity carries an EXPLANATION: which stages fired,
+ * which triggers were found, which validator passed. This drives the review UI
+ * and makes failures diagnosable."
+ *
+ * The last clause is the one that shapes this module. An explanation is not
+ * decoration for the UI — it is how a wrong detection gets diagnosed without
+ * re-running the pipeline under a debugger. So it records what actually
+ * happened rather than a summary of it: which stages contributed, which named
+ * Stage 3 signals fired and with what sign, and what the profile decided.
+ *
+ * NO PLAINTEXT IN EXPLANATIONS, which is why triggers are lexicon terms and
+ * signal names rather than document text. Explanations flow into eval reports,
+ * the review panel, and the popup; a value that reached any of those would
+ * breach SPEC's third non-negotiable. The one exception is the entity's own
+ * text, which the caller already holds and which `DetectedEntity` carries in
+ * its own field.
+ */
+/**
+ * Build the explanation for one entity.
+ *
+ * `triggers` carries the Stage 3 signal names rather than only lexicon
+ * matches, because "why was this reported" is answered as much by
+ * `structure:key-names-API_KEY` as by a trigger word — and a reviewer chasing
+ * a false positive needs the negative signals too, which is why suppression
+ * and penalty signals appear with their sign rather than being filtered out.
+ */
+export function explain(input) {
+    const { scored } = input;
+    const stages = [scored.candidate.stage];
+    // Stage 3 fired if it contributed anything at all.
+    if (scored.contributions.length > 0)
+        stages.push('stage3-context');
+    stages.push('stage4-fusion');
+    const triggers = scored.contributions.map((c) => {
+        const sign = c.delta >= 0 ? '+' : '';
+        const detail = c.detail === undefined ? '' : ` (${c.detail})`;
+        return `${c.signal}${detail} ${sign}${c.delta.toFixed(2)}`;
+    });
+    if (input.absorbedOverlap === true) {
+        triggers.push('stage4:absorbed-overlapping-span +0.00');
+    }
+    for (const type of input.wonAgainst ?? []) {
+        triggers.push(`stage4:more-specific-than-${type} +0.00`);
+    }
+    return {
+        stages,
+        triggers,
+        ...(scored.candidate.validatorPassed !== undefined
+            ? { validatorPassed: scored.candidate.validatorPassed }
+            : {}),
+    };
+}
+/** Assemble the entity a consumer actually receives. */
+export function toDetectedEntity(input) {
+    const { candidate } = input.scored;
+    return {
+        text: candidate.text,
+        type: candidate.type,
+        start: candidate.start,
+        end: candidate.end,
+        calibratedConfidence: input.calibratedConfidence,
+        explanation: explain(input),
+    };
+}
+/**
+ * A one-line reason a candidate was NOT reported.
+ *
+ * SPEC's explanation requirement covers emitted entities, but the review UI
+ * has to answer "why did you miss this?" too, and a suppression with no
+ * recorded reason is exactly the failure D18 was written about. Kept in the
+ * same module so the two stay consistent.
+ */
+export function explainOmission(scored, decision) {
+    if (scored.suppressed) {
+        return `suppressed by ${scored.suppressionReason ?? 'an unnamed rule'}`;
+    }
+    switch (decision?.reason) {
+        case 'allowlist':
+            return 'on the user allowlist';
+        case 'type-out-of-profile':
+            return 'entity type is outside the active sensitivity profile';
+        case 'below-threshold':
+            return 'calibrated confidence below the profile threshold';
+        default:
+            return 'not reported';
+    }
+}
+//# sourceMappingURL=explain.js.map

package/dist/src/fuse/explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../../src/fuse/explain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAiBH;;;;;;;;GAQG;AACH,MAAM,UAAU,OAAO,CAAC,KAAkB;IACxC,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IACzB,MAAM,MAAM,GAAqB,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAE1D,mDAAmD;IACnD,IAAI,MAAM,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;IACnE,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAE7B,MAAM,QAAQ,GAAG,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC9C,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC;QAC9D,OAAO,GAAG,CAAC,CAAC,MAAM,GAAG,MAAM,IAAI,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7D,CAAC,CAAC,CAAC;IAEH,IAAI,KAAK,CAAC,eAAe,KAAK,IAAI,EAAE,CAAC;QACnC,QAAQ,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAC;IAC1D,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;QAC1C,QAAQ,CAAC,IAAI,CAAC,6BAA6B,IAAI,QAAQ,CAAC,CAAC;IAC3D,CAAC;IAED,OAAO;QACL,MAAM;QACN,QAAQ;QACR,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,eAAe,KAAK,SAAS;YAChD,CAAC,CAAC,EAAE,eAAe,EAAE,MAAM,CAAC,SAAS,CAAC,eAAe,EAAE;YACvD,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;AACJ,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,gBAAgB,CAAC,KAAkB;IACjD,MAAM,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC;IACnC,OAAO;QACL,IAAI,EAAE,SAAS,CAAC,IAAI;QACpB,IAAI,EAAE,SAAS,CAAC,IAAI;QACpB,KAAK,EAAE,SAAS,CAAC,KAAK;QACtB,GAAG,EAAE,SAAS,CAAC,GAAG;QAClB,oBAAoB,EAAE,KAAK,CAAC,oBAAoB;QAChD,WAAW,EAAE,OAAO,CAAC,KAAK,CAAC;KAC5B,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,MAA8B,EAC9B,QAA0B;IAE1B,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACtB,OAAO,iBAAiB,MAAM,CAAC,iBAAiB,IAAI,iBAAiB,EAAE,CAAC;IAC1E,CAAC;IACD,QAAQ,QAAQ,EAAE,MAAM,EAAE,CAAC;QACzB,KAAK,WAAW;YACd,OAAO,uBAAuB,CAAC;QACjC,KAAK,qBAAqB;YACxB,OAAO,uDAAuD,CAAC;QACjE,KAAK,iBAAiB;YACpB,OAAO,mDAAmD,CAAC;QAC7D;YACE,OAAO,cAAc,CAAC;IAC1B,CAAC;AACH,CAAC"}

package/dist/src/fuse/profiles.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Stage 4 — SENSITIVITY PROFILES, allowlist and denylist.
+ *
+ * SPEC.md:
+ *   "Apply the active SENSITIVITY PROFILE, which sets thresholds:
+ *      Minimal — secrets and financial identifiers only.
+ *      Balanced — default. Secrets, financial, national IDs, contact details,
+ *        person names.
+ *      Strict — adds health data, addresses, dates of birth, organizations,
+ *        low-confidence candidates.
+ *      Custom — per-entity-type threshold control."
+ *   "Apply user allowlist (never mask …) and denylist (always mask …).
+ *    Denylist beats everything."
+ *
+ * A profile does two things at once and it is worth separating them: it says
+ * WHICH TYPES are in scope, and it says HOW SURE the pipeline must be before
+ * reporting one. The second only became meaningful with calibration — before
+ * a confidence meant something comparable across types, a threshold was an
+ * arbitrary cut. That is why profiles land in the same milestone as the
+ * calibration curve rather than earlier.
+ *
+ * Thresholds are stated as CALIBRATED probabilities, so "0.5" reads as "report
+ * this when it is more likely right than wrong" rather than as a detector-local
+ * number whose meaning varies by type.
+ */
+import type { EntityType } from '../types.js';
+export type ProfileName = 'minimal' | 'balanced' | 'strict' | 'custom';
+export interface SensitivityProfile {
+    readonly name: ProfileName;
+    /** Types the profile reports at all. */
+    readonly types: ReadonlySet<EntityType>;
+    /**
+     * Minimum CALIBRATED confidence to report, per type, with a default.
+     * Meaningful only because Stage 4 calibrated the scale (D23).
+     */
+    readonly threshold: (type: EntityType) => number;
+}
+/**
+ * The three named profiles.
+ *
+ * Thresholds differ by INTENT, not by tuning. Minimal exists for a developer
+ * who wants surgical protection and would rather miss a weak signal than see
+ * a spurious one, so it demands high confidence. Strict exists for someone who
+ * would rather over-mask, so it deliberately admits low-confidence candidates
+ * — SPEC names "low-confidence candidates" as part of what Strict adds.
+ */
+export declare const PROFILES: Readonly<Record<Exclude<ProfileName, 'custom'>, SensitivityProfile>>;
+/** A user's own additions to whatever profile is active. */
+export interface UserLists {
+    /**
+     * Never mask these. Matched case- and whitespace-insensitively on the
+     * entity's text — a user's own employer name, say.
+     */
+    readonly allow?: readonly string[];
+    /** Always mask these, whatever the profile or confidence says. */
+    readonly deny?: readonly string[];
+}
+export interface ProfileDecision {
+    readonly report: boolean;
+    /** Why, in one stable token, for the explanation and for tests. */
+    readonly reason: 'denylist' | 'allowlist' | 'type-out-of-profile' | 'below-threshold' | 'in-profile';
+}
+/**
+ * Decide whether one entity is reported under a profile.
+ *
+ * ORDER IS THE WHOLE CONTRACT, and it follows SPEC exactly: "Denylist beats
+ * everything." A denylisted value is reported even when its type is out of
+ * profile and even when confidence is far below threshold — it is the one
+ * override a user can state absolutely. The allowlist is checked next, before
+ * type and threshold, so that suppressing a value the user has vouched for
+ * does not depend on which profile happens to be active.
+ */
+export declare function decide(entity: {
+    readonly type: EntityType;
+    readonly text: string;
+    readonly calibratedConfidence: number;
+}, profileIn: SensitivityProfile, lists?: UserLists): ProfileDecision;
+/** Build a custom profile from explicit per-type thresholds. */
+export declare function customProfile(thresholds: Partial<Record<EntityType, number>>, defaultThreshold?: number): SensitivityProfile;
+//# sourceMappingURL=profiles.d.ts.map

package/dist/src/fuse/profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../../src/fuse/profiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;AA6CvE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;IACxC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,MAAM,CAAC;CAClD;AAeD;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,QAAQ,CAAC,EAAE,kBAAkB,CAAC,CAezF,CAAC;AAEF,4DAA4D;AAC5D,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAMD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,qBAAqB,GAAG,iBAAiB,GAAG,YAAY,CAAC;CACtG;AAED;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CACpB,MAAM,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAA;CAAE,EACnG,SAAS,EAAE,kBAAkB,EAC7B,KAAK,GAAE,SAAc,GACpB,eAAe,CAgBjB;AAED,gEAAgE;AAChE,wBAAgB,aAAa,CAC3B,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,EAC/C,gBAAgB,SAAM,GACrB,kBAAkB,CAMpB"}

package/dist/src/fuse/profiles.js

@@ -0,0 +1,126 @@
+/**
+ * Stage 4 — SENSITIVITY PROFILES, allowlist and denylist.
+ *
+ * SPEC.md:
+ *   "Apply the active SENSITIVITY PROFILE, which sets thresholds:
+ *      Minimal — secrets and financial identifiers only.
+ *      Balanced — default. Secrets, financial, national IDs, contact details,
+ *        person names.
+ *      Strict — adds health data, addresses, dates of birth, organizations,
+ *        low-confidence candidates.
+ *      Custom — per-entity-type threshold control."
+ *   "Apply user allowlist (never mask …) and denylist (always mask …).
+ *    Denylist beats everything."
+ *
+ * A profile does two things at once and it is worth separating them: it says
+ * WHICH TYPES are in scope, and it says HOW SURE the pipeline must be before
+ * reporting one. The second only became meaningful with calibration — before
+ * a confidence meant something comparable across types, a threshold was an
+ * arbitrary cut. That is why profiles land in the same milestone as the
+ * calibration curve rather than earlier.
+ *
+ * Thresholds are stated as CALIBRATED probabilities, so "0.5" reads as "report
+ * this when it is more likely right than wrong" rather than as a detector-local
+ * number whose meaning varies by type.
+ */
+/** Broad families, used to state the profiles in SPEC's own vocabulary. */
+const SECRETS = [
+    'API_KEY',
+    'PRIVATE_KEY',
+    'JWT',
+    'GENERIC_SECRET',
+    'CONNECTION_STRING',
+    'URL_WITH_CREDENTIALS',
+];
+const FINANCIAL = [
+    'CREDIT_CARD',
+    'IBAN',
+    'SWIFT_BIC',
+    'US_ROUTING_NUMBER',
+    'UK_SORT_CODE',
+    'CA_TRANSIT_NUMBER',
+    'AU_BSB',
+    'IN_IFSC',
+    'BR_AGENCIA',
+    'CRYPTO_WALLET',
+    'VAT_NUMBER',
+];
+const GOVERNMENT_ID = [
+    'NATIONAL_ID',
+    'TAX_ID',
+    'PASSPORT_MRZ',
+    'DRIVERS_LICENSE',
+    'VIN',
+    'US_NPI',
+];
+const CONTACT = ['EMAIL', 'PHONE', 'IP_ADDRESS', 'MAC_ADDRESS'];
+const LOCATION_TYPES = ['STREET_ADDRESS', 'POSTAL_CODE', 'COORDINATES', 'LOCATION'];
+const HEALTH = ['HEALTH_DATA'];
+const PEOPLE = ['PERSON'];
+const ORGS = ['ORG'];
+const DATES = ['DATE_OF_BIRTH'];
+function profile(name, types, defaultThreshold, overrides = {}) {
+    return {
+        name,
+        types: new Set(types.flat()),
+        threshold: (type) => overrides[type] ?? defaultThreshold,
+    };
+}
+/**
+ * The three named profiles.
+ *
+ * Thresholds differ by INTENT, not by tuning. Minimal exists for a developer
+ * who wants surgical protection and would rather miss a weak signal than see
+ * a spurious one, so it demands high confidence. Strict exists for someone who
+ * would rather over-mask, so it deliberately admits low-confidence candidates
+ * — SPEC names "low-confidence candidates" as part of what Strict adds.
+ */
+export const PROFILES = {
+    minimal: profile('minimal', [SECRETS, FINANCIAL], 0.7),
+    balanced: profile('balanced', [SECRETS, FINANCIAL, GOVERNMENT_ID, CONTACT, PEOPLE], 0.5, {
+        // A leaked credential is unrecoverable, so it is reported on weaker
+        // evidence than a name, which the user can dismiss at no cost.
+        API_KEY: 0.35,
+        PRIVATE_KEY: 0.35,
+        CONNECTION_STRING: 0.35,
+    }),
+    strict: profile('strict', [SECRETS, FINANCIAL, GOVERNMENT_ID, CONTACT, PEOPLE, HEALTH, LOCATION_TYPES, ORGS, DATES], 0.25, { API_KEY: 0.2, PRIVATE_KEY: 0.2, CONNECTION_STRING: 0.2 }),
+};
+function fold(value) {
+    return value.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+/**
+ * Decide whether one entity is reported under a profile.
+ *
+ * ORDER IS THE WHOLE CONTRACT, and it follows SPEC exactly: "Denylist beats
+ * everything." A denylisted value is reported even when its type is out of
+ * profile and even when confidence is far below threshold — it is the one
+ * override a user can state absolutely. The allowlist is checked next, before
+ * type and threshold, so that suppressing a value the user has vouched for
+ * does not depend on which profile happens to be active.
+ */
+export function decide(entity, profileIn, lists = {}) {
+    const text = fold(entity.text);
+    if ((lists.deny ?? []).some((d) => fold(d) === text)) {
+        return { report: true, reason: 'denylist' };
+    }
+    if ((lists.allow ?? []).some((a) => fold(a) === text)) {
+        return { report: false, reason: 'allowlist' };
+    }
+    if (!profileIn.types.has(entity.type)) {
+        return { report: false, reason: 'type-out-of-profile' };
+    }
+    if (entity.calibratedConfidence < profileIn.threshold(entity.type)) {
+        return { report: false, reason: 'below-threshold' };
+    }
+    return { report: true, reason: 'in-profile' };
+}
+/** Build a custom profile from explicit per-type thresholds. */
+export function customProfile(thresholds, defaultThreshold = 0.5) {
+    return {
+        name: 'custom',
+        types: new Set(Object.keys(thresholds)),
+        threshold: (type) => thresholds[type] ?? defaultThreshold,
+    };
+}
+//# sourceMappingURL=profiles.js.map

package/dist/src/fuse/profiles.js.map

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

package/dist/src/fuse/resolve.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Stage 4 — OVERLAP RESOLUTION.
+ *
+ * SPEC.md: "Resolve overlapping candidates: prefer the more specific type,
+ * then higher calibrated confidence, then longer span. Never emit overlapping
+ * entities."
+ *
+ * THE SAFETY PROPERTY THAT GOVERNS THIS FILE. Resolution DROPS candidates, so
+ * D18 applies to it exactly as it applies to a suppression rule — but it has a
+ * failure mode a suppression rule does not. Dropping a WIDE candidate in
+ * favour of a narrow one it contains does not merely relabel a span: the
+ * characters outside the narrow span stop being masked. A rule that naively
+ * "prefers the more specific type" would take CONNECTION_STRING over the
+ * credentialled URL containing it and leave the scheme, host and port of a
+ * live database URI in the outgoing text.
+ *
+ * So the ordering here is deliberately NOT SPEC's literal order. It is:
+ *
+ *   1. WIDEST SPAN first — never reduce masked coverage.
+ *   2. then the more specific TYPE, for spans of equal extent.
+ *   3. then higher confidence.
+ *
+ * Coverage is promoted above specificity because coverage is the property
+ * that cannot be recovered downstream: a mislabelled span is a cosmetic
+ * defect in the review UI, an unmasked one is a leak. Where spans are equal
+ * the two orderings agree, which is the case SPEC's wording is really about.
+ * `resolveOverlaps` asserts the coverage property on its own output.
+ *
+ * THE SPECIFICITY ORDER IS MEASURED, NOT ASSUMED. A census over the 2,600
+ * document corpus found 66.8% of Stage 1 candidates in at least one cross-type
+ * overlap, and for each pair recorded which type ground truth actually agreed
+ * with. Every rank below cites that measurement.
+ */
+import type { EntityType } from '../types.js';
+import type { PipelineCandidate } from '../context/types.js';
+/** A candidate with the confidence Stage 3 gave it. */
+export interface ScoredForResolution {
+    readonly candidate: PipelineCandidate;
+    readonly confidence: number;
+}
+export interface ResolutionResult {
+    /** Non-overlapping survivors, in document order. */
+    readonly emitted: readonly ScoredForResolution[];
+    /** Candidates yielded to a winner, retained so the choice is explainable. */
+    readonly dropped: readonly {
+        readonly item: ScoredForResolution;
+        readonly toType: EntityType;
+    }[];
+}
+/**
+ * Resolve a candidate set into a non-overlapping one.
+ *
+ * Greedy by the ordering above. Because the widest span is always taken
+ * first, any candidate it contains is dropped only after its characters are
+ * already covered — which is what makes the coverage property hold rather
+ * than merely being hoped for.
+ *
+ * Non-sensitive candidates (known test values) never displace a sensitive
+ * one: they are detected so the eval can assert they were seen, and letting
+ * one win an overlap would unmask the value it covers.
+ */
+export declare function resolveOverlaps(items: readonly ScoredForResolution[]): ResolutionResult;
+/**
+ * Every character a sensitive candidate covered is still covered.
+ *
+ * The invariant resolution exists to preserve, exposed so callers and tests
+ * can assert it directly rather than trusting the ordering to imply it.
+ */
+export declare function coverageHoles(before: readonly ScoredForResolution[], after: readonly ScoredForResolution[]): {
+    readonly start: number;
+    readonly end: number;
+}[];
+//# sourceMappingURL=resolve.d.ts.map

package/dist/src/fuse/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../../src/fuse/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AA6E7D,uDAAuD;AACvD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACjD,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;KAAE,EAAE,CAAC;CAClG;AAUD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,GAAG,gBAAgB,CA6DvF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,mBAAmB,EAAE,EACtC,KAAK,EAAE,SAAS,mBAAmB,EAAE,GACpC;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,CAmBpD"}

package/dist/src/fuse/resolve.js

@@ -0,0 +1,206 @@
+/**
+ * Stage 4 — OVERLAP RESOLUTION.
+ *
+ * SPEC.md: "Resolve overlapping candidates: prefer the more specific type,
+ * then higher calibrated confidence, then longer span. Never emit overlapping
+ * entities."
+ *
+ * THE SAFETY PROPERTY THAT GOVERNS THIS FILE. Resolution DROPS candidates, so
+ * D18 applies to it exactly as it applies to a suppression rule — but it has a
+ * failure mode a suppression rule does not. Dropping a WIDE candidate in
+ * favour of a narrow one it contains does not merely relabel a span: the
+ * characters outside the narrow span stop being masked. A rule that naively
+ * "prefers the more specific type" would take CONNECTION_STRING over the
+ * credentialled URL containing it and leave the scheme, host and port of a
+ * live database URI in the outgoing text.
+ *
+ * So the ordering here is deliberately NOT SPEC's literal order. It is:
+ *
+ *   1. WIDEST SPAN first — never reduce masked coverage.
+ *   2. then the more specific TYPE, for spans of equal extent.
+ *   3. then higher confidence.
+ *
+ * Coverage is promoted above specificity because coverage is the property
+ * that cannot be recovered downstream: a mislabelled span is a cosmetic
+ * defect in the review UI, an unmasked one is a leak. Where spans are equal
+ * the two orderings agree, which is the case SPEC's wording is really about.
+ * `resolveOverlaps` asserts the coverage property on its own output.
+ *
+ * THE SPECIFICITY ORDER IS MEASURED, NOT ASSUMED. A census over the 2,600
+ * document corpus found 66.8% of Stage 1 candidates in at least one cross-type
+ * overlap, and for each pair recorded which type ground truth actually agreed
+ * with. Every rank below cites that measurement.
+ */
+/**
+ * Type specificity: LOWER wins a tie between spans of equal extent.
+ *
+ * Derived from the overlap census — the "which type did ground truth agree
+ * with" column — not from intuition about which type sounds more precise.
+ */
+const SPECIFICITY = {
+    // Self-verifying structure. A valid MRZ or PEM block is what it says it is.
+    PASSPORT_MRZ: 0,
+    PRIVATE_KEY: 0,
+    JWT: 0,
+    // A connection string and a credentialled URL claim IDENTICAL spans 140
+    // times in the corpus, and ground truth agreed with CONNECTION_STRING in
+    // 140 of 140. The DB/queue scheme is the more specific reading of the same
+    // characters, exactly as the M7 taxonomy predicted.
+    CONNECTION_STRING: 1,
+    URL_WITH_CREDENTIALS: 2,
+    // Checksum-validated identifiers.
+    IBAN: 3,
+    CREDIT_CARD: 3,
+    CRYPTO_WALLET: 3,
+    API_KEY: 3,
+    VAT_NUMBER: 3,
+    US_NPI: 3,
+    VIN: 3,
+    SWIFT_BIC: 3,
+    US_ROUTING_NUMBER: 3,
+    UK_SORT_CODE: 3,
+    CA_TRANSIT_NUMBER: 3,
+    AU_BSB: 3,
+    IN_IFSC: 3,
+    BR_AGENCIA: 3,
+    // Structured but not self-verifying.
+    EMAIL: 4,
+    PHONE: 4,
+    IP_ADDRESS: 4,
+    MAC_ADDRESS: 4,
+    COORDINATES: 4,
+    STREET_ADDRESS: 4,
+    HEALTH_DATA: 5,
+    // National and tax identifiers. Deliberately EQUAL: the census found
+    // TAX_ID-over-NATIONAL_ID and NATIONAL_ID-over-TAX_ID both occurring on
+    // equal spans with ground truth split roughly evenly between them (28/10/10
+    // and 19/11/11). No static ordering is honest about that — it is a genuine
+    // cross-scheme ambiguity that calibrated confidence has to settle, so they
+    // tie here and fall through to the confidence comparison.
+    NATIONAL_ID: 6,
+    TAX_ID: 6,
+    // Named entities: statistical proposals, not validated claims.
+    PERSON: 7,
+    ORG: 7,
+    LOCATION: 7,
+    // Shape-only, no validator behind it.
+    POSTAL_CODE: 8,
+    DRIVERS_LICENSE: 8,
+    DATE_OF_BIRTH: 8,
+    // Entropy alone. The census is unambiguous: a specific type covering the
+    // same characters was right in 2,047 of 2,053 measured overlaps.
+    GENERIC_SECRET: 9,
+};
+/** Types absent from the table sort between shape-only and generic. */
+const DEFAULT_SPECIFICITY = 8;
+function specificityOf(type) {
+    return SPECIFICITY[type] ?? DEFAULT_SPECIFICITY;
+}
+function overlaps(a, b) {
+    return a.start < b.end && b.start < a.end;
+}
+function width(item) {
+    return item.candidate.end - item.candidate.start;
+}
+/**
+ * Resolve a candidate set into a non-overlapping one.
+ *
+ * Greedy by the ordering above. Because the widest span is always taken
+ * first, any candidate it contains is dropped only after its characters are
+ * already covered — which is what makes the coverage property hold rather
+ * than merely being hoped for.
+ *
+ * Non-sensitive candidates (known test values) never displace a sensitive
+ * one: they are detected so the eval can assert they were seen, and letting
+ * one win an overlap would unmask the value it covers.
+ */
+export function resolveOverlaps(items) {
+    const ordered = [...items].sort((a, b) => {
+        // Sensitive first: a non-sensitive candidate must never displace one that
+        // would otherwise be masked.
+        if (a.candidate.sensitive !== b.candidate.sensitive)
+            return a.candidate.sensitive ? -1 : 1;
+        const byWidth = width(b) - width(a);
+        if (byWidth !== 0)
+            return byWidth;
+        const bySpecificity = specificityOf(a.candidate.type) - specificityOf(b.candidate.type);
+        if (bySpecificity !== 0)
+            return bySpecificity;
+        const byConfidence = b.confidence - a.confidence;
+        if (byConfidence !== 0)
+            return byConfidence;
+        // Total order, so the result cannot depend on input order.
+        return a.candidate.start - b.candidate.start || a.candidate.detectorId.localeCompare(b.candidate.detectorId);
+    });
+    const emitted = [];
+    const dropped = [];
+    for (const item of ordered) {
+        const at = emitted.findIndex((kept) => overlaps(kept.candidate, item.candidate));
+        if (at === -1) {
+            emitted.push(item);
+            continue;
+        }
+        const winner = emitted[at];
+        const contained = winner.candidate.start <= item.candidate.start && item.candidate.end <= winner.candidate.end;
+        // CONTAINED: the winner already covers every character, so dropping the
+        // loser costs nothing but a label.
+        if (contained || !item.candidate.sensitive) {
+            dropped.push({ item, toType: winner.candidate.type });
+            continue;
+        }
+        // PARTIAL: the loser extends beyond the winner, so dropping it would
+        // leave the overhang unmasked. Measured on the corpus, this is rare (8
+        // spans in 2,600 documents, every one a Korean street address abutting
+        // another entity) but it is a leak, not a mislabelling. The winner
+        // absorbs the union instead.
+        //
+        // Widening in BOTH coordinate spaces is sound without re-consulting the
+        // offset map: the map is monotonic, so the union of two mapped spans
+        // contains the mapping of the union, and erring wider only ever masks
+        // more.
+        emitted[at] = {
+            ...winner,
+            candidate: {
+                ...winner.candidate,
+                start: Math.min(winner.candidate.start, item.candidate.start),
+                end: Math.max(winner.candidate.end, item.candidate.end),
+                originalStart: Math.min(winner.candidate.originalStart, item.candidate.originalStart),
+                originalEnd: Math.max(winner.candidate.originalEnd, item.candidate.originalEnd),
+            },
+        };
+        dropped.push({ item, toType: winner.candidate.type });
+    }
+    emitted.sort((a, b) => a.candidate.start - b.candidate.start);
+    return { emitted, dropped };
+}
+/**
+ * Every character a sensitive candidate covered is still covered.
+ *
+ * The invariant resolution exists to preserve, exposed so callers and tests
+ * can assert it directly rather than trusting the ordering to imply it.
+ */
+export function coverageHoles(before, after) {
+    const covered = after
+        .filter((i) => i.candidate.sensitive)
+        .map((i) => ({ start: i.candidate.start, end: i.candidate.end }))
+        .sort((a, b) => a.start - b.start);
+    const holes = [];
+    for (const item of before) {
+        if (!item.candidate.sensitive)
+            continue;
+        let cursor = item.candidate.start;
+        for (const span of covered) {
+            if (span.end <= cursor)
+                continue;
+            if (span.start > cursor)
+                break;
+            cursor = Math.max(cursor, span.end);
+            if (cursor >= item.candidate.end)
+                break;
+        }
+        if (cursor < item.candidate.end)
+            holes.push({ start: cursor, end: item.candidate.end });
+    }
+    return holes;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/src/fuse/resolve.js.map

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

package/dist/src/gazetteer/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Stage 2b — GAZETTEER lookup.
+ *
+ * SPEC.md: "Bundled compressed lookup sets, checked in parallel with the
+ * model … Gazetteer hit alone is medium confidence; gazetteer plus model
+ * agreement is high."
+ *
+ * The bundled sets are Bloom filters (see `@discretion/data`'s
+ * gazetteers.ts for why). Two consequences shape this module:
+ *
+ *   • A filter can report a false POSITIVE and never a false negative. So a
+ *     hit is corroboration, never proof — which is exactly the weight SPEC.md
+ *     assigns it — while a miss is conclusive.
+ *   • The hash here must match the builder's byte for byte, so it is written
+ *     out explicitly rather than pulled from a library that might change.
+ */
+import type { EntityType } from '../types.js';
+/** Entity types a gazetteer can speak to. */
+export type GazetteerType = 'PERSON' | 'ORG' | 'LOCATION';
+export declare function isGazetteerType(type: EntityType): type is GazetteerType;
+/** How a value matched the gazetteer. */
+export interface GazetteerHit {
+    readonly type: GazetteerType;
+    /** True when the whole value matched, rather than one of its words. */
+    readonly whole: boolean;
+    /** Number of the value's words that matched, for multi-word names. */
+    readonly matchedWords: number;
+    readonly totalWords: number;
+}
+/**
+ * Look a value up as `type`.
+ *
+ * A person's full name is rarely a single gazetteer entry — the sets hold
+ * given names and family names separately — so a multi-word value is checked
+ * whole first, then word by word. `matchedWords` lets the caller weigh
+ * "every word is a known name" differently from "one word out of four is".
+ */
+export declare function lookupGazetteer(value: string, type: GazetteerType): GazetteerHit | undefined;
+/** Entry counts per set, for reporting and for BENCHMARKS.md. */
+export declare function gazetteerSizes(): Readonly<Record<GazetteerType, number>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/gazetteer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/gazetteer/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,6CAA6C;AAC7C,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,KAAK,GAAG,UAAU,CAAC;AAI1D,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,IAAI,aAAa,CAEvE;AAkED,yCAAyC;AACzC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAKD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,YAAY,GAAG,SAAS,CAe5F;AAED,iEAAiE;AACjE,wBAAgB,cAAc,IAAI,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,CAMxE"}