@discretion/core 0.1.0

package/dist/src/normalization.js.map

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

package/dist/src/offsetMap.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Offset-map machinery for Stage 0 normalization.
+ *
+ * WHY THIS EXISTS
+ * ───────────────
+ * Detection runs on normalized text; substitution edits the ORIGINAL text.
+ * Every transform therefore produces, alongside its output text, an exact map
+ * back to its input. The final map for a whole pipeline is the composition of
+ * each stage's map — composing small verified maps is far easier to get right
+ * than building one map through four simultaneous transforms.
+ *
+ * MAP REPRESENTATION
+ * ──────────────────
+ * A map for a transform `input → output` is an Int32Array of length
+ * output.length + 1 (all indices are UTF-16 code units):
+ *
+ *   map[i]             = input index where the cluster that produced output
+ *                        index i begins
+ *   map[output.length] = input.length                            (sentinel)
+ *
+ * The sentinel entry is the classic off-by-one: without it, the end of a span
+ * covering the last character could not be mapped. With it, an output span
+ * [s, e) maps to the input span [map[s], map[e]).
+ *
+ * DELETION ATTRIBUTION (a deliberate choice — read before editing)
+ * ───────────────────────────────────────────────────────────────
+ * Deleted input (stripped invisibles) produces no output index, so it cannot
+ * appear in the map directly. Each deleted run is attributed to the cluster
+ * that FOLLOWS it; a deleted run at the very end of the input falls under the
+ * sentinel. Consequences:
+ *   • map[0] === 0 always holds when the output is non-empty, even if the
+ *     input began with deleted characters — a stated invariant of the format.
+ *   • A mapped span silently includes any deleted (invisible) characters
+ *     immediately before the characters it covers, and — via the sentinel —
+ *     any deleted characters at the end of the input. Substituting such a
+ *     span removes those invisibles along with it, which is exactly what a
+ *     masking pipeline wants: they are noise we would strip anyway.
+ *   • Values are STRICTLY increasing across real cluster boundaries; equal
+ *     adjacent values occur only inside a single cluster's multi-unit output
+ *     (an expansion). mapNormalizedSpan() relies on this.
+ *
+ * EDGE CASE — everything deleted: when the output is empty the map is the
+ * single sentinel entry [inputLength], so map[0] === inputLength, not 0.
+ * That is the one place the "map[0] === 0" invariant cannot hold; every
+ * consumer and test conditions that invariant on a non-empty output.
+ */
+import type { TransformKind } from './types.js';
+/** The identity map for a text of the given length: [0, 1, …, length]. */
+export declare function identityMap(length: number): Int32Array;
+/**
+ * Compose two offset maps.
+ *
+ *   outer: maps indices of text B to indices of text A  (length |B| + 1)
+ *   inner: maps indices of text C to indices of text B  (length |C| + 1)
+ *   result: maps indices of text C to indices of text A (length |C| + 1)
+ *
+ * Because inner[|C|] = |B| and outer[|B|] = |A|, the sentinel composes for
+ * free, and the composition of monotone maps is monotone — both facts are
+ * covered by tests.
+ */
+export declare function composeMaps(outer: Int32Array, inner: Int32Array): Int32Array;
+/**
+ * Build the reverse map (original index → normalized index) from a forward
+ * map.
+ *
+ *   reverseMap[j]              = normalized index of the start of the cluster
+ *                                whose original extent contains j; for a
+ *                                deleted character this is the normalized
+ *                                position where it was removed
+ *   reverseMap[originalLength] = normalizedLength                (sentinel)
+ *
+ * "Extent" is the half-open range [offsetMap[i], nextDistinctValue), i.e. it
+ * includes any deleted characters attributed to the cluster. The walk below
+ * precomputes each cluster's extent end (`ends`), then assigns every original
+ * index the FIRST normalized index whose extent reaches past it — which lands
+ * on the first unit of the covering cluster, also for expansions where several
+ * normalized units share one original cluster.
+ */
+export declare function buildReverseMap(offsetMap: Int32Array, originalLength: number): Int32Array;
+/**
+ * Map a normalized span [start, end) to the original span it covers.
+ *
+ * For spans whose endpooints sit on cluster boundaries this is exactly
+ * [offsetMap[start], offsetMap[end]). When an endpoint lands INSIDE an
+ * expansion (one original cluster → several normalized units — e.g. matching
+ * only the "f" of the "fi" produced by the ligature U+FB01), the span is
+ * widened to cover the WHOLE original cluster: you cannot substitute half a
+ * ligature. Widening is the only sound choice for masking — the alternative,
+ * an empty or truncated original span, would silently leave sensitive
+ * characters behind.
+ *
+ * NOTE: two non-overlapping normalized spans that split the same expansion
+ * both widen to the same original cluster, so mapped spans can overlap in
+ * that one case. Substitution must merge overlapping original spans before
+ * splicing (covered by the substitution-safety property test).
+ */
+export declare function mapNormalizedSpan(offsetMap: Int32Array, start: number, end: number): {
+    start: number;
+    end: number;
+};
+/**
+ * One change made by a single transform, in coordinates of THAT TRANSFORM'S
+ * INPUT. normalize() re-maps these to original-text coordinates before
+ * exposing them as TransformationRecord.
+ */
+export interface StepChange {
+    kind: TransformKind;
+    /** Range in the transform's input text. */
+    start: number;
+    end: number;
+    /** input.slice(start, end) — what was there. */
+    before: string;
+    /** What the transform emitted instead ('' for deletions). */
+    after: string;
+}
+/** What every transform returns; null means "nothing to do" (identity). */
+export interface TransformStepResult {
+    text: string;
+    /** output index → input index, with sentinel (length text.length + 1). */
+    map: Int32Array;
+    changes: StepChange[];
+}
+/**
+ * Streaming builder used by every transform to produce output text and its
+ * offset map in one left-to-right pass. It enforces the deletion-attribution
+ * convention documented in the file header, so transforms cannot get it wrong
+ * individually.
+ *
+ * Usage contract: calls must cover the input strictly left to right —
+ * copyVerbatim / replaceRange / deleteRange with monotonically increasing,
+ * non-overlapping [start, end) ranges, then finish(inputLength) exactly once.
+ */
+export declare class MappedTextBuilder {
+    private readonly parts;
+    private readonly map;
+    /** Start of the input region not yet attributed to any output. */
+    private claimFrom;
+    /** How far the input has been consumed (for misuse detection). */
+    private cursor;
+    private advance;
+    /**
+     * Copy input.slice(start, end) through unchanged. Mapping is fine-grained
+     * (each output unit → its own input position), except that the first unit
+     * claims any pending deleted region before it.
+     */
+    copyVerbatim(input: string, start: number, end: number): void;
+    /**
+     * Replace input.slice(start, end) with `replacement`. Every output unit
+     * maps to the start of the input cluster (including any pending deleted
+     * region before it) — a span covering part of the replacement covers the
+     * whole original cluster.
+     */
+    replaceRange(replacement: string, start: number, end: number): void;
+    /**
+     * Delete input.slice(start, end): emits nothing. The region stays
+     * unclaimed and will be attributed to the next output (or the sentinel).
+     */
+    deleteRange(start: number, end: number): void;
+    /** Finish the map with its sentinel entry and assemble the output text. */
+    finish(inputLength: number): {
+        text: string;
+        map: Int32Array;
+    };
+}
+//# sourceMappingURL=offsetMap.d.ts.map

package/dist/src/offsetMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offsetMap.d.ts","sourceRoot":"","sources":["../../src/offsetMap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAItD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,GAAG,UAAU,CAa5E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,GAAG,UAAU,CAyBzF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,UAAU,EACrB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,GACV;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAmBhC;AAMD;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,aAAa,CAAC;IACpB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;CACf;AAED,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,GAAG,EAAE,UAAU,CAAC;IAChB,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAgB;IACpC,kEAAkE;IAClE,OAAO,CAAC,SAAS,CAAK;IACtB,kEAAkE;IAClE,OAAO,CAAC,MAAM,CAAK;IAEnB,OAAO,CAAC,OAAO;IAUf;;;;OAIG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAS7D;;;;;OAKG;IACH,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAQnE;;;OAGG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAI7C,2EAA2E;IAC3E,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,UAAU,CAAA;KAAE;CAS/D"}

package/dist/src/offsetMap.js

@@ -0,0 +1,225 @@
+/**
+ * Offset-map machinery for Stage 0 normalization.
+ *
+ * WHY THIS EXISTS
+ * ───────────────
+ * Detection runs on normalized text; substitution edits the ORIGINAL text.
+ * Every transform therefore produces, alongside its output text, an exact map
+ * back to its input. The final map for a whole pipeline is the composition of
+ * each stage's map — composing small verified maps is far easier to get right
+ * than building one map through four simultaneous transforms.
+ *
+ * MAP REPRESENTATION
+ * ──────────────────
+ * A map for a transform `input → output` is an Int32Array of length
+ * output.length + 1 (all indices are UTF-16 code units):
+ *
+ *   map[i]             = input index where the cluster that produced output
+ *                        index i begins
+ *   map[output.length] = input.length                            (sentinel)
+ *
+ * The sentinel entry is the classic off-by-one: without it, the end of a span
+ * covering the last character could not be mapped. With it, an output span
+ * [s, e) maps to the input span [map[s], map[e]).
+ *
+ * DELETION ATTRIBUTION (a deliberate choice — read before editing)
+ * ───────────────────────────────────────────────────────────────
+ * Deleted input (stripped invisibles) produces no output index, so it cannot
+ * appear in the map directly. Each deleted run is attributed to the cluster
+ * that FOLLOWS it; a deleted run at the very end of the input falls under the
+ * sentinel. Consequences:
+ *   • map[0] === 0 always holds when the output is non-empty, even if the
+ *     input began with deleted characters — a stated invariant of the format.
+ *   • A mapped span silently includes any deleted (invisible) characters
+ *     immediately before the characters it covers, and — via the sentinel —
+ *     any deleted characters at the end of the input. Substituting such a
+ *     span removes those invisibles along with it, which is exactly what a
+ *     masking pipeline wants: they are noise we would strip anyway.
+ *   • Values are STRICTLY increasing across real cluster boundaries; equal
+ *     adjacent values occur only inside a single cluster's multi-unit output
+ *     (an expansion). mapNormalizedSpan() relies on this.
+ *
+ * EDGE CASE — everything deleted: when the output is empty the map is the
+ * single sentinel entry [inputLength], so map[0] === inputLength, not 0.
+ * That is the one place the "map[0] === 0" invariant cannot hold; every
+ * consumer and test conditions that invariant on a non-empty output.
+ */
+/** The identity map for a text of the given length: [0, 1, …, length]. */
+export function identityMap(length) {
+    const map = new Int32Array(length + 1);
+    for (let i = 0; i <= length; i++)
+        map[i] = i;
+    return map;
+}
+/**
+ * Compose two offset maps.
+ *
+ *   outer: maps indices of text B to indices of text A  (length |B| + 1)
+ *   inner: maps indices of text C to indices of text B  (length |C| + 1)
+ *   result: maps indices of text C to indices of text A (length |C| + 1)
+ *
+ * Because inner[|C|] = |B| and outer[|B|] = |A|, the sentinel composes for
+ * free, and the composition of monotone maps is monotone — both facts are
+ * covered by tests.
+ */
+export function composeMaps(outer, inner) {
+    const result = new Int32Array(inner.length);
+    const outerMax = outer.length - 1;
+    for (let i = 0; i < inner.length; i++) {
+        const via = inner[i];
+        if (via < 0 || via > outerMax) {
+            throw new Error(`composeMaps: inner map value ${via} at index ${i} is outside the outer map's domain [0, ${outerMax}]`);
+        }
+        result[i] = outer[via];
+    }
+    return result;
+}
+/**
+ * Build the reverse map (original index → normalized index) from a forward
+ * map.
+ *
+ *   reverseMap[j]              = normalized index of the start of the cluster
+ *                                whose original extent contains j; for a
+ *                                deleted character this is the normalized
+ *                                position where it was removed
+ *   reverseMap[originalLength] = normalizedLength                (sentinel)
+ *
+ * "Extent" is the half-open range [offsetMap[i], nextDistinctValue), i.e. it
+ * includes any deleted characters attributed to the cluster. The walk below
+ * precomputes each cluster's extent end (`ends`), then assigns every original
+ * index the FIRST normalized index whose extent reaches past it — which lands
+ * on the first unit of the covering cluster, also for expansions where several
+ * normalized units share one original cluster.
+ */
+export function buildReverseMap(offsetMap, originalLength) {
+    const normalizedLength = offsetMap.length - 1;
+    const reverse = new Int32Array(originalLength + 1);
+    // ends[i] = original index one past the extent of the cluster covering
+    // normalized index i (= the next distinct map value, or originalLength).
+    const ends = new Int32Array(normalizedLength);
+    let nextDistinct = originalLength;
+    for (let i = normalizedLength - 1; i >= 0; i--) {
+        ends[i] = nextDistinct;
+        if (i === 0 || offsetMap[i - 1] !== offsetMap[i]) {
+            nextDistinct = offsetMap[i];
+        }
+    }
+    let i = 0;
+    for (let j = 0; j < originalLength; j++) {
+        while (i < normalizedLength && ends[i] <= j)
+            i++;
+        // If every cluster ends at or before j (possible only when the trailing
+        // input was deleted and absorbed by the sentinel), i === normalizedLength,
+        // which is exactly "the position where it was removed".
+        reverse[j] = i;
+    }
+    reverse[originalLength] = normalizedLength;
+    return reverse;
+}
+/**
+ * Map a normalized span [start, end) to the original span it covers.
+ *
+ * For spans whose endpooints sit on cluster boundaries this is exactly
+ * [offsetMap[start], offsetMap[end]). When an endpoint lands INSIDE an
+ * expansion (one original cluster → several normalized units — e.g. matching
+ * only the "f" of the "fi" produced by the ligature U+FB01), the span is
+ * widened to cover the WHOLE original cluster: you cannot substitute half a
+ * ligature. Widening is the only sound choice for masking — the alternative,
+ * an empty or truncated original span, would silently leave sensitive
+ * characters behind.
+ *
+ * NOTE: two non-overlapping normalized spans that split the same expansion
+ * both widen to the same original cluster, so mapped spans can overlap in
+ * that one case. Substitution must merge overlapping original spans before
+ * splicing (covered by the substitution-safety property test).
+ */
+export function mapNormalizedSpan(offsetMap, start, end) {
+    const normalizedLength = offsetMap.length - 1;
+    if (!(start >= 0 && start <= end && end <= normalizedLength)) {
+        throw new Error(`mapNormalizedSpan: invalid span [${start}, ${end}) for normalized length ${normalizedLength}`);
+    }
+    if (start === end) {
+        const at = offsetMap[start];
+        return { start: at, end: at };
+    }
+    const origStart = offsetMap[start];
+    // Find the original end of the cluster containing normalized index end-1:
+    // advance past normalized units that still share that cluster's start value.
+    // (Equal adjacent values occur only within one cluster — see header.)
+    const lastClusterStart = offsetMap[end - 1];
+    let k = end;
+    while (k < normalizedLength && offsetMap[k] === lastClusterStart)
+        k++;
+    return { start: origStart, end: offsetMap[k] };
+}
+/**
+ * Streaming builder used by every transform to produce output text and its
+ * offset map in one left-to-right pass. It enforces the deletion-attribution
+ * convention documented in the file header, so transforms cannot get it wrong
+ * individually.
+ *
+ * Usage contract: calls must cover the input strictly left to right —
+ * copyVerbatim / replaceRange / deleteRange with monotonically increasing,
+ * non-overlapping [start, end) ranges, then finish(inputLength) exactly once.
+ */
+export class MappedTextBuilder {
+    parts = [];
+    map = [];
+    /** Start of the input region not yet attributed to any output. */
+    claimFrom = 0;
+    /** How far the input has been consumed (for misuse detection). */
+    cursor = 0;
+    advance(start, end) {
+        if (start !== this.cursor || end < start) {
+            throw new Error(`MappedTextBuilder: ranges must be contiguous and left-to-right ` +
+                `(cursor ${this.cursor}, got [${start}, ${end}))`);
+        }
+        this.cursor = end;
+    }
+    /**
+     * Copy input.slice(start, end) through unchanged. Mapping is fine-grained
+     * (each output unit → its own input position), except that the first unit
+     * claims any pending deleted region before it.
+     */
+    copyVerbatim(input, start, end) {
+        this.advance(start, end);
+        if (start === end)
+            return;
+        this.parts.push(input.slice(start, end));
+        this.map.push(this.claimFrom);
+        for (let k = start + 1; k < end; k++)
+            this.map.push(k);
+        this.claimFrom = end;
+    }
+    /**
+     * Replace input.slice(start, end) with `replacement`. Every output unit
+     * maps to the start of the input cluster (including any pending deleted
+     * region before it) — a span covering part of the replacement covers the
+     * whole original cluster.
+     */
+    replaceRange(replacement, start, end) {
+        this.advance(start, end);
+        const base = this.claimFrom;
+        for (let i = 0; i < replacement.length; i++)
+            this.map.push(base);
+        if (replacement.length > 0)
+            this.parts.push(replacement);
+        this.claimFrom = end;
+    }
+    /**
+     * Delete input.slice(start, end): emits nothing. The region stays
+     * unclaimed and will be attributed to the next output (or the sentinel).
+     */
+    deleteRange(start, end) {
+        this.advance(start, end);
+    }
+    /** Finish the map with its sentinel entry and assemble the output text. */
+    finish(inputLength) {
+        if (this.cursor !== inputLength) {
+            throw new Error(`MappedTextBuilder: input not fully consumed (cursor ${this.cursor} of ${inputLength})`);
+        }
+        this.map.push(inputLength);
+        return { text: this.parts.join(''), map: Int32Array.from(this.map) };
+    }
+}
+//# sourceMappingURL=offsetMap.js.map

package/dist/src/offsetMap.js.map

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

package/dist/src/pipeline.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The composed detection pipeline.
+ *
+ * Stages 0–3 in one supported entry point. Before this existed a caller had
+ * to run `runStage1`, then `runStage2`, then score the result — and Stage 3's
+ * evidence had to be threaded into Stage 1's validators by hand. That is not a
+ * detail a consumer should be trusted with: a caller who forgets the context
+ * hook silently gets a weaker pipeline, and one who forgets Stage 3 gets every
+ * false positive Stage 3 exists to remove.
+ *
+ * SPEC.md's non-negotiable applies to the whole composition: any detection
+ * error, timeout, or adapter failure must BLOCK, never degrade. Nothing here
+ * catches an error from a stage — a thrown `DetectionTimeoutError` or
+ * `DetectorError` propagates to the caller, which is what fail-closed means.
+ *
+ * The lower-level stage functions remain exported for tests and tooling that
+ * genuinely want one stage; `detect` is what consumers should use.
+ */
+import type { NormalizationResult } from './types.js';
+import { type Stage1Options } from './detect/runner.js';
+import type { NerRecognizer } from './ner/types.js';
+import { type ContextOptions } from './context/score.js';
+import type { ContextScoredCandidate, DocumentProfile } from './context/types.js';
+export interface DetectOptions {
+    /** Stage 1 configuration. The context hook is supplied automatically. */
+    readonly stage1?: Omit<Stage1Options, 'contextFor'>;
+    /**
+     * Stage 2 engine. Omit to run without named-entity recognition — the
+     * playground and the Stage-1 eval baseline both do.
+     */
+    readonly ner?: NerRecognizer;
+    /** Stage 3 configuration. Defaults to the bundled trigger lexicons. */
+    readonly context?: ContextOptions;
+}
+export interface DetectionOutcome {
+    /** Candidates Stage 3 kept, with their adjusted confidence and reasons. */
+    readonly emitted: readonly ContextScoredCandidate[];
+    /**
+     * Candidates Stage 3 suppressed, retained for eval and explanation.
+     *
+     * Kept rather than discarded because a suppression is a decision the
+     * pipeline must be able to justify: the review UI explains why something
+     * was NOT reported, and the eval measures whether a suppression rule is
+     * removing errors or removing detections.
+     */
+    readonly suppressed: readonly ContextScoredCandidate[];
+    readonly profile: DocumentProfile;
+}
+/**
+ * Run Stages 0–3 over an already-normalized document.
+ *
+ * Takes the `NormalizationResult` rather than a string for the same reason
+ * `runStage1` does: without the offset map a candidate cannot be mapped back
+ * to the original text, and accepting a bare string would let a caller lose
+ * it silently.
+ */
+export declare function detect(normalization: NormalizationResult, options?: DetectOptions): Promise<DetectionOutcome>;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/src/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAa,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,KAAK,EAAE,sBAAsB,EAAE,eAAe,EAAqB,MAAM,oBAAoB,CAAC;AAErG,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC;IACpD;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,aAAa,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACpD;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACvD,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,wBAAsB,MAAM,CAC1B,aAAa,EAAE,mBAAmB,EAClC,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,gBAAgB,CAAC,CA6B3B"}

package/dist/src/pipeline.js

@@ -0,0 +1,57 @@
+/**
+ * The composed detection pipeline.
+ *
+ * Stages 0–3 in one supported entry point. Before this existed a caller had
+ * to run `runStage1`, then `runStage2`, then score the result — and Stage 3's
+ * evidence had to be threaded into Stage 1's validators by hand. That is not a
+ * detail a consumer should be trusted with: a caller who forgets the context
+ * hook silently gets a weaker pipeline, and one who forgets Stage 3 gets every
+ * false positive Stage 3 exists to remove.
+ *
+ * SPEC.md's non-negotiable applies to the whole composition: any detection
+ * error, timeout, or adapter failure must BLOCK, never degrade. Nothing here
+ * catches an error from a stage — a thrown `DetectionTimeoutError` or
+ * `DetectorError` propagates to the caller, which is what fail-closed means.
+ *
+ * The lower-level stage functions remain exported for tests and tooling that
+ * genuinely want one stage; `detect` is what consumers should use.
+ */
+import { DOMAIN_LEXICONS, TRIGGER_LEXICONS } from '@discretion/data';
+import { runStage1 } from './detect/runner.js';
+import { runStage2 } from './ner/runStage2.js';
+import { analyzeContext } from './context/score.js';
+/**
+ * Run Stages 0–3 over an already-normalized document.
+ *
+ * Takes the `NormalizationResult` rather than a string for the same reason
+ * `runStage1` does: without the offset map a candidate cannot be mapped back
+ * to the original text, and accepting a bare string would let a caller lose
+ * it silently.
+ */
+export async function detect(normalization, options = {}) {
+    const analysis = analyzeContext(normalization.normalizedText, {
+        triggerLexicons: TRIGGER_LEXICONS,
+        domainLexicon: DOMAIN_LEXICONS,
+        ...options.context,
+    });
+    // Stage 1 validators receive Stage 3 evidence inline, which is what lets a
+    // detector that SPEC.md marks "requires context" see the signal at the
+    // moment it decides.
+    const stage1 = runStage1(normalization, {
+        ...options.stage1,
+        contextFor: (start, end) => analysis.signalAt(start, end),
+    });
+    const stage2 = options.ner === undefined ? [] : await runStage2(normalization, options.ner);
+    const candidates = [...stage1, ...stage2];
+    const scored = analysis.score(candidates);
+    // NO STAGE 2C. SPEC.md asks for a verification pass over an ambiguous
+    // confidence band, and requires it be removed if the eval shows it does not
+    // improve results. It was built, measured, and removed — see ARCHITECTURE.md
+    // D20 and the BENCHMARKS.md M7 section for the numbers.
+    return {
+        emitted: scored.filter((c) => !c.suppressed),
+        suppressed: scored.filter((c) => c.suppressed),
+        profile: analysis.profile,
+    };
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/src/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../../src/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGrE,OAAO,EAAE,SAAS,EAAsB,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,EAAE,cAAc,EAAuB,MAAM,oBAAoB,CAAC;AA8BzE;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAC1B,aAAkC,EAClC,UAAyB,EAAE;IAE3B,MAAM,QAAQ,GAAG,cAAc,CAAC,aAAa,CAAC,cAAc,EAAE;QAC5D,eAAe,EAAE,gBAAgB;QACjC,aAAa,EAAE,eAAe;QAC9B,GAAG,OAAO,CAAC,OAAO;KACnB,CAAC,CAAC;IAEH,2EAA2E;IAC3E,uEAAuE;IACvE,qBAAqB;IACrB,MAAM,MAAM,GAAG,SAAS,CAAC,aAAa,EAAE;QACtC,GAAG,OAAO,CAAC,MAAM;QACjB,UAAU,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC;KAC1D,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,SAAS,CAAC,aAAa,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IAE5F,MAAM,UAAU,GAAwB,CAAC,GAAG,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAE1C,sEAAsE;IACtE,4EAA4E;IAC5E,6EAA6E;IAC7E,wDAAwD;IACxD,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;QAC5C,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;QAC9C,OAAO,EAAE,QAAQ,CAAC,OAAO;KAC1B,CAAC;AACJ,CAAC"}