agentfootprint 6.28.1 → 6.29.0

package/dist/lib/influence-core/attributability.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rankingConfidence = exports.ratioStrategy = exports.marginStrategy = void 0;
+const types_js_1 = require("./types.js");
+const nonNegative = (label, x) => {
+    // `!(x >= 0)` rejects negatives AND NaN (a plain `< 0` would let NaN through).
+    if (!(x >= 0))
+        throw new Error(`${label} must be >= 0 (got ${x})`);
+    return x;
+};
+/**
+ * Default strategy: ABSOLUTE top-2 gap `s0 − s1 >= threshold`. Simple and
+ * interpretable, but embedder-relative (the gap scale depends on the embedding
+ * geometry). Use `ratioStrategy` for cross-embedder transfer.
+ */
+function marginStrategy(threshold = types_js_1.DEFAULT_CLEAR_WINNER_MARGIN) {
+    nonNegative('marginStrategy: threshold', threshold);
+    return {
+        name: `margin>=${threshold}`,
+        isClearWinner: (s) => s.length >= 2 && s[0] - s[1] >= threshold,
+    };
+}
+exports.marginStrategy = marginStrategy;
+/**
+ * Scale-invariant strategy: top-2 gap as a FRACTION of the top score,
+ * `(s0 − s1) / |s0| >= threshold`. Transfers across embedders / answer lengths
+ * where the absolute margin does not. A zero (or all-equal) top is never a
+ * clear winner.
+ */
+function ratioStrategy(threshold = types_js_1.DEFAULT_CLEAR_WINNER_RATIO) {
+    nonNegative('ratioStrategy: threshold', threshold);
+    return {
+        name: `ratio>=${threshold}`,
+        isClearWinner: (s) => {
+            if (s.length < 2)
+                return false;
+            const denom = Math.abs(s[0]);
+            if (denom === 0)
+                return false; // flat at zero → no clear winner (avoid div-by-zero)
+            return (s[0] - s[1]) / denom >= threshold;
+        },
+    };
+}
+exports.ratioStrategy = ratioStrategy;
+/** Finite score, or −Infinity for a malformed (NaN/+Infinity/−Infinity) one —
+ *  so a bad embedder degrades that item to "ranked last", never corrupts the
+ *  ordering. Note +Infinity is demoted too: a meaningless score is never a win. */
+const finiteScore = (s) => (Number.isFinite(s.score) ? s.score : -Infinity);
+/** Total, NaN-free comparator (descending) — correctness does not rest on the
+ *  engine's handling of a NaN comparator return for the all-malformed case. */
+const byScoreDesc = (a, b) => {
+    const x = finiteScore(a);
+    const y = finiteScore(b);
+    return x > y ? -1 : x < y ? 1 : 0;
+};
+/**
+ * Assess whether an influence ranking has a clear winner to trust as a lead,
+ * or is too close to call and should be confirmed by ablation.
+ *
+ * Guarantees (relied on by the localizer): the returned `shortlist` always
+ * contains `lead` when there is one, and — when there is NO clear winner and
+ * there are ≥2 suspects — always contains the runner-up too (so ablation over
+ * the shortlist covers the real culprit even if it ranked below an innocent).
+ *
+ * @param scores `scoreInfluence` output (any order — re-sorted defensively).
+ *               Ids are assumed unique (as `scoreInfluence` enforces); the
+ *               shortlist is de-duplicated defensively regardless.
+ * @throws Error on negative or NaN options.
+ */
+function rankingConfidence(scores, options = {}) {
+    // strategy WINS over clearWinnerMargin; the default builds a margin strategy
+    // (which validates its own threshold).
+    const strategy = options.strategy ?? marginStrategy(options.clearWinnerMargin ?? types_js_1.DEFAULT_CLEAR_WINNER_MARGIN);
+    const shortlistBand = nonNegative('rankingConfidence: shortlistBand', options.shortlistBand ?? types_js_1.DEFAULT_SHORTLIST_BAND);
+    if (scores.length === 0) {
+        return { clearWinner: false, margin: undefined, lead: undefined, shortlist: [], reason: 'No suspects to rank.' };
+    }
+    const ranked = [...scores].sort(byScoreDesc);
+    const top = ranked[0];
+    const topScore = finiteScore(top);
+    if (ranked.length === 1) {
+        return {
+            clearWinner: true,
+            margin: undefined,
+            lead: top.id,
+            shortlist: [top.id],
+            reason: `Only one suspect "${top.id}" — clear by default (nothing to compare against); confirm by ablation for a causal claim.`,
+        };
+    }
+    const secondScore = finiteScore(ranked[1]);
+    // Clear winner, robust to malformed scores (framework invariants, NOT the
+    // strategy's concern):
+    //  - top itself malformed (e.g. all-malformed) → no clear winner, no margin.
+    //  - clean finite top, malformed runner-up → unambiguous lead → clear winner
+    //    (the inverse of suppressing it); no meaningful finite gap to report.
+    //  - both finite → the pluggable STRATEGY decides, over all finite scores.
+    let clearWinner;
+    let margin;
+    if (!Number.isFinite(topScore)) {
+        clearWinner = false;
+        margin = undefined;
+    }
+    else if (!Number.isFinite(secondScore)) {
+        clearWinner = true;
+        margin = undefined;
+    }
+    else {
+        margin = topScore - secondScore;
+        const finiteRanked = ranked.map(finiteScore).filter((x) => Number.isFinite(x));
+        clearWinner = strategy.isClearWinner(finiteRanked);
+    }
+    // Shortlist = the band of FINITE scores within shortlistBand of a finite top.
+    // Then enforce the guarantees: lead always present; when there is no clear
+    // winner with ≥2 suspects, the runner-up is present too.
+    const shortlist = [];
+    const seen = new Set();
+    const add = (id) => {
+        if (!seen.has(id)) {
+            seen.add(id);
+            shortlist.push(id);
+        }
+    };
+    if (Number.isFinite(topScore)) {
+        for (const s of ranked) {
+            const sc = finiteScore(s);
+            if (Number.isFinite(sc) && topScore - sc <= shortlistBand)
+                add(s.id);
+        }
+    }
+    add(top.id); // guarantee: lead always in the shortlist
+    if (!clearWinner)
+        add(ranked[1].id); // guarantee: no-clear-winner shortlist covers the runner-up
+    const gap = margin === undefined ? 'n/a' : margin.toFixed(3);
+    const reason = clearWinner
+        ? margin === undefined
+            ? `Clear winner [${strategy.name}]: "${top.id}" leads clearly (runner-up score unavailable). A clear lead is a similarity PROXY, not a proven cause — confirm by ablation.`
+            : `Clear winner [${strategy.name}]: "${top.id}" leads (top-2 margin ${gap}). A clear lead is a similarity PROXY, not a proven cause — confirm by ablation.`
+        : `Too close to call [${strategy.name}]: top-2 margin ${gap} — no suspect stands out by output similarity. Double-check the ${shortlist.length} shortlisted suspect(s) by ABLATION. Similarity scoring is blind to absence/crowding bugs (history truncation, context dilution), where the culprit need not resemble the answer; a flat top can also mean genuinely co-equal sources.`;
+    return { clearWinner, margin, lead: top.id, shortlist, reason };
+}
+exports.rankingConfidence = rankingConfidence;
+//# sourceMappingURL=attributability.js.map

package/dist/lib/influence-core/attributability.js.map

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

package/dist/lib/influence-core/index.js

@@ -26,11 +26,18 @@
  * and never causal attribution.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.scoreMargin = exports.pairwiseSimilarity = exports.structuralProximity = exports.scoreInfluence = exports.persistence = exports.finalAnswerSimilarity = exports.compositeScore = exports.averageRelevancy = exports.adaptWeights = exports.embeddingCache = exports.EmbeddingCache = exports.contentHash = exports.DEFAULT_PERSISTENCE_THRESHOLD = exports.DEFAULT_MARGIN_THRESHOLD = exports.DEFAULT_INFLUENCE_WEIGHTS = void 0;
+exports.scoreMargin = exports.pairwiseSimilarity = exports.structuralProximity = exports.scoreInfluence = exports.persistence = exports.finalAnswerSimilarity = exports.compositeScore = exports.averageRelevancy = exports.adaptWeights = exports.embeddingCache = exports.EmbeddingCache = exports.contentHash = exports.ratioStrategy = exports.rankingConfidence = exports.marginStrategy = exports.DEFAULT_SHORTLIST_BAND = exports.DEFAULT_PERSISTENCE_THRESHOLD = exports.DEFAULT_MARGIN_THRESHOLD = exports.DEFAULT_INFLUENCE_WEIGHTS = exports.DEFAULT_CLEAR_WINNER_RATIO = exports.DEFAULT_CLEAR_WINNER_MARGIN = void 0;
 var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "DEFAULT_CLEAR_WINNER_MARGIN", { enumerable: true, get: function () { return types_js_1.DEFAULT_CLEAR_WINNER_MARGIN; } });
+Object.defineProperty(exports, "DEFAULT_CLEAR_WINNER_RATIO", { enumerable: true, get: function () { return types_js_1.DEFAULT_CLEAR_WINNER_RATIO; } });
 Object.defineProperty(exports, "DEFAULT_INFLUENCE_WEIGHTS", { enumerable: true, get: function () { return types_js_1.DEFAULT_INFLUENCE_WEIGHTS; } });
 Object.defineProperty(exports, "DEFAULT_MARGIN_THRESHOLD", { enumerable: true, get: function () { return types_js_1.DEFAULT_MARGIN_THRESHOLD; } });
 Object.defineProperty(exports, "DEFAULT_PERSISTENCE_THRESHOLD", { enumerable: true, get: function () { return types_js_1.DEFAULT_PERSISTENCE_THRESHOLD; } });
+Object.defineProperty(exports, "DEFAULT_SHORTLIST_BAND", { enumerable: true, get: function () { return types_js_1.DEFAULT_SHORTLIST_BAND; } });
+var attributability_js_1 = require("./attributability.js");
+Object.defineProperty(exports, "marginStrategy", { enumerable: true, get: function () { return attributability_js_1.marginStrategy; } });
+Object.defineProperty(exports, "rankingConfidence", { enumerable: true, get: function () { return attributability_js_1.rankingConfidence; } });
+Object.defineProperty(exports, "ratioStrategy", { enumerable: true, get: function () { return attributability_js_1.ratioStrategy; } });
 var cache_js_1 = require("./cache.js");
 Object.defineProperty(exports, "contentHash", { enumerable: true, get: function () { return cache_js_1.contentHash; } });
 Object.defineProperty(exports, "EmbeddingCache", { enumerable: true, get: function () { return cache_js_1.EmbeddingCache; } });

package/dist/lib/influence-core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/influence-core/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAiBH,uCAIoB;AAHlB,qHAAA,yBAAyB,OAAA;AACzB,oHAAA,wBAAwB,OAAA;AACxB,yHAAA,6BAA6B,OAAA;AAG/B,uCAMoB;AALlB,uGAAA,WAAW,OAAA;AACX,0GAAA,cAAc,OAAA;AACd,0GAAA,cAAc,OAAA;AAKhB,2CASsB;AARpB,0GAAA,YAAY,OAAA;AACZ,8GAAA,gBAAgB,OAAA;AAChB,4GAAA,cAAc,OAAA;AACd,mHAAA,qBAAqB,OAAA;AACrB,yGAAA,WAAW,OAAA;AACX,4GAAA,cAAc,OAAA;AACd,iHAAA,mBAAmB,OAAA;AAIrB,iDAAkF;AAAzE,mHAAA,kBAAkB,OAAA;AAE3B,yCAAgE;AAAvD,wGAAA,WAAW,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/influence-core/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAmBH,uCAOoB;AANlB,uHAAA,2BAA2B,OAAA;AAC3B,sHAAA,0BAA0B,OAAA;AAC1B,qHAAA,yBAAyB,OAAA;AACzB,oHAAA,wBAAwB,OAAA;AACxB,yHAAA,6BAA6B,OAAA;AAC7B,kHAAA,sBAAsB,OAAA;AAGxB,2DAK8B;AAJ5B,oHAAA,cAAc,OAAA;AACd,uHAAA,iBAAiB,OAAA;AACjB,mHAAA,aAAa,OAAA;AAIf,uCAMoB;AALlB,uGAAA,WAAW,OAAA;AACX,0GAAA,cAAc,OAAA;AACd,0GAAA,cAAc,OAAA;AAKhB,2CASsB;AARpB,0GAAA,YAAY,OAAA;AACZ,8GAAA,gBAAgB,OAAA;AAChB,4GAAA,cAAc,OAAA;AACd,mHAAA,qBAAqB,OAAA;AACrB,yGAAA,WAAW,OAAA;AACX,4GAAA,cAAc,OAAA;AACd,iHAAA,mBAAmB,OAAA;AAIrB,iDAAkF;AAAzE,mHAAA,kBAAkB,OAAA;AAE3B,yCAAgE;AAAvD,wGAAA,WAAW,OAAA"}

package/dist/lib/influence-core/types.js

@@ -23,7 +23,7 @@
  * live.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_MARGIN_THRESHOLD = exports.DEFAULT_PERSISTENCE_THRESHOLD = exports.DEFAULT_INFLUENCE_WEIGHTS = void 0;
+exports.DEFAULT_CLEAR_WINNER_RATIO = exports.DEFAULT_SHORTLIST_BAND = exports.DEFAULT_CLEAR_WINNER_MARGIN = exports.DEFAULT_MARGIN_THRESHOLD = exports.DEFAULT_PERSISTENCE_THRESHOLD = exports.DEFAULT_INFLUENCE_WEIGHTS = void 0;
 /** Paper defaults: α=0.40, β=0.30, γ=0.20, δ=0.10 (sum to 1.0). */
 exports.DEFAULT_INFLUENCE_WEIGHTS = Object.freeze({
     fa: 0.4,
@@ -35,4 +35,31 @@ exports.DEFAULT_INFLUENCE_WEIGHTS = Object.freeze({
 exports.DEFAULT_PERSISTENCE_THRESHOLD = 0.3;
 /** RFC-002 §4 default: margins below this flag the choice as `narrow`. */
 exports.DEFAULT_MARGIN_THRESHOLD = 0.05;
+/**
+ * RFC-003 default: an influence ranking whose top-1 vs top-2 score margin is
+ * below this has NO clear winner — a shortlist, not a verdict. Escalate to
+ * ablation.
+ *
+ * UNCALIBRATED proxy starting point, chosen for interpretability. `margin`
+ * is an ABSOLUTE difference on the same scale as `scoreInfluence`'s composite
+ * (S ∈ ≈[−0.7, 1]), so this threshold is EMBEDDER-RELATIVE — recalibrate by
+ * sweeping clear-winner vs flat rankings on your embedder. The numeric
+ * coincidence with `DEFAULT_MARGIN_THRESHOLD` is NOT a shared derivation: that
+ * one measures `scoreMargin`'s chosen-vs-not-chosen distribution, a different
+ * statistic.
+ */
+exports.DEFAULT_CLEAR_WINNER_MARGIN = 0.05;
+/**
+ * RFC-003 default: when there is no clear winner, suspects scoring within this
+ * band of the top form the shortlist ablation should COVER (the culprit may be
+ * any of them — or, for absence bugs, none). UNCALIBRATED proxy; embedder-
+ * relative (see `DEFAULT_CLEAR_WINNER_MARGIN`).
+ */
+exports.DEFAULT_SHORTLIST_BAND = 0.1;
+/**
+ * RFC-003 default for `ratioStrategy`: the top-2 gap as a FRACTION of the top
+ * score `(s0 − s1) / |s0|`. Unlike the absolute margin this is scale-invariant,
+ * so it transfers across embedders / answer lengths. UNCALIBRATED proxy.
+ */
+exports.DEFAULT_CLEAR_WINNER_RATIO = 0.05;
 //# sourceMappingURL=types.js.map

package/dist/lib/influence-core/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/influence-core/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;;AA0BH,mEAAmE;AACtD,QAAA,yBAAyB,GAAqB,MAAM,CAAC,MAAM,CAAC;IACvE,EAAE,EAAE,GAAG;IACP,GAAG,EAAE,GAAG;IACR,OAAO,EAAE,GAAG;IACZ,KAAK,EAAE,GAAG;CACX,CAAC,CAAC;AAEH,yDAAyD;AAC5C,QAAA,6BAA6B,GAAG,GAAG,CAAC;AAEjD,0EAA0E;AAC7D,QAAA,wBAAwB,GAAG,IAAI,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/influence-core/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;;AA0BH,mEAAmE;AACtD,QAAA,yBAAyB,GAAqB,MAAM,CAAC,MAAM,CAAC;IACvE,EAAE,EAAE,GAAG;IACP,GAAG,EAAE,GAAG;IACR,OAAO,EAAE,GAAG;IACZ,KAAK,EAAE,GAAG;CACX,CAAC,CAAC;AAEH,yDAAyD;AAC5C,QAAA,6BAA6B,GAAG,GAAG,CAAC;AAEjD,0EAA0E;AAC7D,QAAA,wBAAwB,GAAG,IAAI,CAAC;AAE7C;;;;;;;;;;;;GAYG;AACU,QAAA,2BAA2B,GAAG,IAAI,CAAC;AAEhD;;;;;GAKG;AACU,QAAA,sBAAsB,GAAG,GAAG,CAAC;AAE1C;;;;GAIG;AACU,QAAA,0BAA0B,GAAG,IAAI,CAAC"}

package/dist/observe.js

@@ -32,8 +32,8 @@
  * directly; Tier 3 dashboards are opt-in.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildSelfExplainSkill = exports.traceToolpack = exports.TOOLPACK_HARD_CAPS = exports.NO_COMPLETED_RUN_MESSAGE = exports.lazyTraceToolpack = exports.callTraceTool = exports.structuralProximity = exports.scoreMargin = exports.scoreInfluence = exports.persistence = exports.pairwiseSimilarity = exports.finalAnswerSimilarity = exports.embeddingCache = exports.EmbeddingCache = exports.DEFAULT_PERSISTENCE_THRESHOLD = exports.DEFAULT_MARGIN_THRESHOLD = exports.DEFAULT_INFLUENCE_WEIGHTS = exports.contentHash = exports.compositeScore = exports.averageRelevancy = exports.adaptWeights = exports.typedEmit = exports.agentThinkingTrace = exports.toolLineageRecorder = exports.attachStatus = exports.LoggingDomains = exports.attachLogging = exports.skillRecorder = exports.permissionRecorder = exports.memoryRecorder = exports.evalRecorder = exports.contextEvaluatedRecorder = exports.toolsRecorder = exports.costRecorder = exports.LiveAgentTurnTracker = exports.LiveToolTracker = exports.LiveLLMTracker = exports.LiveStateRecorder = exports.liveStateRecorder = exports.buildStepGraph = exports.attachFlowchart = exports.runStepRecorder = exports.RunStepRecorder = exports.buildRunSteps = exports.BoundaryRecorder = exports.boundaryRecorder = exports.agentRecorder = exports.compositionRecorder = exports.streamRecorder = exports.ContextRecorder = void 0;
-exports.toolChoiceRecorder = exports.buildChoiceContext = exports.saysWhatNotWhenRule = exports.runToolLintCli = exports.optionalParamRule = exports.MOCK_EMBEDDER_CALIBRATION = exports.formatToolCatalogReport = exports.enumInProseRule = exports.differentiationHint = exports.descriptionRule = exports.defaultStructuralRules = exports.DEFAULT_WHEN_CUES = exports.DEFAULT_WATCH_BAND = exports.DEFAULT_OMISSION_CUES = exports.DEFAULT_CONFUSABILITY_THRESHOLD = exports.confusabilityText = exports.coerceCatalog = exports.catalogFromTools = exports.analyzeToolCatalog = exports.toBacktrackTrace = exports.verdictFor = exports.suspectLabel = exports.stepOutputText = exports.runAblationProbe = exports.probeFlipped = exports.localizeContextBug = exports.llmEdgeWeigher = exports.llmCallIdsFromEvents = exports.formatContextBugReport = exports.defaultSuspectClassifier = exports.defaultOutcomeComparator = exports.CONTEXT_BISECT_DEFAULTS = exports.bisectCulprits = exports.applyAblations = exports.ablationForSuspect = exports.traceDebugAgent = exports.SelfExplainBinding = exports.buildSelfExplainToolProvider = void 0;
+exports.structuralProximity = exports.scoreMargin = exports.scoreInfluence = exports.ratioStrategy = exports.rankingConfidence = exports.persistence = exports.pairwiseSimilarity = exports.marginStrategy = exports.finalAnswerSimilarity = exports.embeddingCache = exports.EmbeddingCache = exports.DEFAULT_SHORTLIST_BAND = exports.DEFAULT_PERSISTENCE_THRESHOLD = exports.DEFAULT_MARGIN_THRESHOLD = exports.DEFAULT_INFLUENCE_WEIGHTS = exports.DEFAULT_CLEAR_WINNER_RATIO = exports.DEFAULT_CLEAR_WINNER_MARGIN = exports.contentHash = exports.compositeScore = exports.averageRelevancy = exports.adaptWeights = exports.typedEmit = exports.agentThinkingTrace = exports.toolLineageRecorder = exports.attachStatus = exports.LoggingDomains = exports.attachLogging = exports.skillRecorder = exports.permissionRecorder = exports.memoryRecorder = exports.evalRecorder = exports.contextEvaluatedRecorder = exports.toolsRecorder = exports.costRecorder = exports.LiveAgentTurnTracker = exports.LiveToolTracker = exports.LiveLLMTracker = exports.LiveStateRecorder = exports.liveStateRecorder = exports.buildStepGraph = exports.attachFlowchart = exports.runStepRecorder = exports.RunStepRecorder = exports.buildRunSteps = exports.BoundaryRecorder = exports.boundaryRecorder = exports.agentRecorder = exports.compositionRecorder = exports.streamRecorder = exports.ContextRecorder = void 0;
+exports.toolChoiceRecorder = exports.buildChoiceContext = exports.saysWhatNotWhenRule = exports.runToolLintCli = exports.optionalParamRule = exports.MOCK_EMBEDDER_CALIBRATION = exports.formatToolCatalogReport = exports.enumInProseRule = exports.differentiationHint = exports.descriptionRule = exports.defaultStructuralRules = exports.DEFAULT_WHEN_CUES = exports.DEFAULT_WATCH_BAND = exports.DEFAULT_OMISSION_CUES = exports.DEFAULT_CONFUSABILITY_THRESHOLD = exports.confusabilityText = exports.coerceCatalog = exports.catalogFromTools = exports.analyzeToolCatalog = exports.toBacktrackTrace = exports.verdictFor = exports.suspectLabel = exports.stepOutputText = exports.runAblationProbe = exports.probeFlipped = exports.localizeContextBug = exports.llmEdgeWeigher = exports.llmCallIdsFromEvents = exports.formatContextBugReport = exports.findDroppedContext = exports.defaultSuspectClassifier = exports.defaultOutcomeComparator = exports.CONTEXT_BISECT_DEFAULTS = exports.bisectCulprits = exports.applyAblations = exports.ablationForSuspect = exports.traceDebugAgent = exports.SelfExplainBinding = exports.buildSelfExplainToolProvider = exports.buildSelfExplainSkill = exports.traceToolpack = exports.TOOLPACK_HARD_CAPS = exports.NO_COMPLETED_RUN_MESSAGE = exports.lazyTraceToolpack = exports.callTraceTool = void 0;
 // Tier 1 — context + stream
 var ContextRecorder_js_1 = require("./recorders/core/ContextRecorder.js");
 Object.defineProperty(exports, "ContextRecorder", { enumerable: true, get: function () { return ContextRecorder_js_1.ContextRecorder; } });
@@ -103,14 +103,20 @@ Object.defineProperty(exports, "adaptWeights", { enumerable: true, get: function
 Object.defineProperty(exports, "averageRelevancy", { enumerable: true, get: function () { return index_js_1.averageRelevancy; } });
 Object.defineProperty(exports, "compositeScore", { enumerable: true, get: function () { return index_js_1.compositeScore; } });
 Object.defineProperty(exports, "contentHash", { enumerable: true, get: function () { return index_js_1.contentHash; } });
+Object.defineProperty(exports, "DEFAULT_CLEAR_WINNER_MARGIN", { enumerable: true, get: function () { return index_js_1.DEFAULT_CLEAR_WINNER_MARGIN; } });
+Object.defineProperty(exports, "DEFAULT_CLEAR_WINNER_RATIO", { enumerable: true, get: function () { return index_js_1.DEFAULT_CLEAR_WINNER_RATIO; } });
 Object.defineProperty(exports, "DEFAULT_INFLUENCE_WEIGHTS", { enumerable: true, get: function () { return index_js_1.DEFAULT_INFLUENCE_WEIGHTS; } });
 Object.defineProperty(exports, "DEFAULT_MARGIN_THRESHOLD", { enumerable: true, get: function () { return index_js_1.DEFAULT_MARGIN_THRESHOLD; } });
 Object.defineProperty(exports, "DEFAULT_PERSISTENCE_THRESHOLD", { enumerable: true, get: function () { return index_js_1.DEFAULT_PERSISTENCE_THRESHOLD; } });
+Object.defineProperty(exports, "DEFAULT_SHORTLIST_BAND", { enumerable: true, get: function () { return index_js_1.DEFAULT_SHORTLIST_BAND; } });
 Object.defineProperty(exports, "EmbeddingCache", { enumerable: true, get: function () { return index_js_1.EmbeddingCache; } });
 Object.defineProperty(exports, "embeddingCache", { enumerable: true, get: function () { return index_js_1.embeddingCache; } });
 Object.defineProperty(exports, "finalAnswerSimilarity", { enumerable: true, get: function () { return index_js_1.finalAnswerSimilarity; } });
+Object.defineProperty(exports, "marginStrategy", { enumerable: true, get: function () { return index_js_1.marginStrategy; } });
 Object.defineProperty(exports, "pairwiseSimilarity", { enumerable: true, get: function () { return index_js_1.pairwiseSimilarity; } });
 Object.defineProperty(exports, "persistence", { enumerable: true, get: function () { return index_js_1.persistence; } });
+Object.defineProperty(exports, "rankingConfidence", { enumerable: true, get: function () { return index_js_1.rankingConfidence; } });
+Object.defineProperty(exports, "ratioStrategy", { enumerable: true, get: function () { return index_js_1.ratioStrategy; } });
 Object.defineProperty(exports, "scoreInfluence", { enumerable: true, get: function () { return index_js_1.scoreInfluence; } });
 Object.defineProperty(exports, "scoreMargin", { enumerable: true, get: function () { return index_js_1.scoreMargin; } });
 Object.defineProperty(exports, "structuralProximity", { enumerable: true, get: function () { return index_js_1.structuralProximity; } });
@@ -145,6 +151,7 @@ Object.defineProperty(exports, "bisectCulprits", { enumerable: true, get: functi
 Object.defineProperty(exports, "CONTEXT_BISECT_DEFAULTS", { enumerable: true, get: function () { return index_js_4.CONTEXT_BISECT_DEFAULTS; } });
 Object.defineProperty(exports, "defaultOutcomeComparator", { enumerable: true, get: function () { return index_js_4.defaultOutcomeComparator; } });
 Object.defineProperty(exports, "defaultSuspectClassifier", { enumerable: true, get: function () { return index_js_4.defaultSuspectClassifier; } });
+Object.defineProperty(exports, "findDroppedContext", { enumerable: true, get: function () { return index_js_4.findDroppedContext; } });
 Object.defineProperty(exports, "formatContextBugReport", { enumerable: true, get: function () { return index_js_4.formatContextBugReport; } });
 Object.defineProperty(exports, "llmCallIdsFromEvents", { enumerable: true, get: function () { return index_js_4.llmCallIdsFromEvents; } });
 Object.defineProperty(exports, "llmEdgeWeigher", { enumerable: true, get: function () { return index_js_4.llmEdgeWeigher; } });

package/dist/observe.js.map

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

package/dist/types/lib/context-bisect/index.d.ts

@@ -15,6 +15,7 @@
  * claims; slice completeness is bounded by tracking — and says so.
  */
 export { llmEdgeWeigher, stepOutputText, type LlmEdgeWeigherHandle, type LlmEdgeWeigherOptions, type RankedParentEdge, } from './llmEdgeWeigher.js';
+export { findDroppedContext, type ContextUnit, type DroppedUnit, type MissingContextResult, } from './missingContext.js';
 export { defaultSuspectClassifier, formatContextBugReport, llmCallIdsFromEvents, localizeContextBug, suspectLabel, type ClassifyContext, type LocalizeContextBugOptions, type SuspectClassifier, type SuspectSeed, } from './localize.js';
 export { toBacktrackTrace, type BacktrackCustodyHop, type BacktrackHop, type BacktrackSuspectCard, type BacktrackTrace, type BacktrackTrail, type ToBacktrackTraceOptions, } from './toBacktrackTrace.js';
 export { ablationForSuspect, applyAblations, defaultOutcomeComparator, probeFlipped, runAblationProbe, verdictFor, type AblationTargets, type ProbeConfig, } from './ablation.js';

package/dist/types/lib/context-bisect/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/context-bisect/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,cAAc,EACd,cAAc,EACd,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,GACtB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,WAAW,GACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,gBAAgB,EAChB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,uBAAuB,GAC7B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,wBAAwB,EACxB,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,WAAW,GACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,uBAAuB,EACvB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,KAAK,WAAW,GACjB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/context-bisect/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,cAAc,EACd,cAAc,EACd,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,GACtB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,kBAAkB,EAClB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,oBAAoB,GAC1B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,WAAW,GACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,gBAAgB,EAChB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,uBAAuB,GAC7B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,wBAAwB,EACxB,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,WAAW,GACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,uBAAuB,EACvB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,KAAK,WAAW,GACjB,MAAM,YAAY,CAAC"}

package/dist/types/lib/context-bisect/missingContext.d.ts

@@ -0,0 +1,72 @@
+/**
+ * missingContext — interface #3: find context that was AVAILABLE but never
+ * reached the model (RFC-003).
+ *
+ * The localizer's influence ranking (#1) + ablation (#2) handle culprits that
+ * are PRESENT in the context. They are blind to the opposite failure: a needed
+ * unit that was *dropped* — truncated out of the window, or never selected —
+ * so the model never saw it. You cannot ablate what isn't there.
+ *
+ * This finder is the cheap, exact, deterministic half of that case: a SET
+ * DIFFERENCE over unit ids. The library tracks context as identified units
+ * (each injection / memory entry / tool result has a stable id), so "what got
+ * dropped" is `available − sent` — no embeddings, no LLM, O(n).
+ *
+ * Causal confirmation is the MIRROR of ablation: RESTORATION. Add a dropped
+ * unit back, re-run, and an outcome flip is the causal proof. Like ablation,
+ * the re-run is consumer-supplied (the library doesn't own your agent loop);
+ * see `findDroppedContext` docs + example 10 for the pattern.
+ *
+ * Honest claim: a dropped unit is a CANDIDATE missing-context culprit, never a
+ * confirmed cause — most dropped context is correctly dropped. Only restoration
+ * makes a causal claim.
+ */
+/** One unit of context, identified by a stable id (injection id, memory id,
+ *  tool-result id, ...). `content` is optional — carried through for display
+ *  and for the restoration re-run. */
+export interface ContextUnit {
+    readonly id: string;
+    readonly content?: string;
+}
+/** A unit that was available for the turn but never reached the model. */
+export interface DroppedUnit {
+    readonly id: string;
+    readonly content?: string;
+}
+export interface MissingContextResult {
+    /**
+     * Units available for the turn that did NOT reach the model (`available −
+     * sent`, matched by id, input order preserved). Each is a CANDIDATE
+     * missing-context culprit — confirm by restoration, never assume.
+     */
+    readonly dropped: readonly DroppedUnit[];
+    /** Distinct available units considered. */
+    readonly availableCount: number;
+    /** Distinct sent units that reached the model. */
+    readonly sentCount: number;
+    /** True when anything was dropped — a missing-context bug is possible. */
+    readonly anyDropped: boolean;
+    /** Human-readable explanation. PRESENTATION ONLY — read `dropped` /
+     *  `anyDropped` as data, never parse this string. */
+    readonly reason: string;
+}
+/**
+ * Find context that was available for a turn but never reached the model —
+ * `available − sent` by id. Pure, deterministic, O(n); no model or embedder.
+ *
+ * Ids are assumed stable and unique per side (duplicates are de-duplicated,
+ * first occurrence wins). Units in `sent` but not `available` are ignored.
+ *
+ * Confirm a candidate causally by RESTORATION (the mirror of ablation): add the
+ * dropped unit back into the context and re-run; an outcome flip is the proof.
+ *
+ * @example
+ *   const { dropped, anyDropped } = findDroppedContext(assembled, sentToModel);
+ *   if (anyDropped) {
+ *     for (const unit of dropped) {
+ *       if (await rerunWith(unit).outcomeFlips()) report(unit); // restoration = causal
+ *     }
+ *   }
+ */
+export declare function findDroppedContext(available: readonly ContextUnit[], sent: readonly ContextUnit[]): MissingContextResult;
+//# sourceMappingURL=missingContext.d.ts.map

package/dist/types/lib/context-bisect/missingContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"missingContext.d.ts","sourceRoot":"","sources":["../../../../src/lib/context-bisect/missingContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;sCAEsC;AACtC,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,2CAA2C;IAC3C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B;yDACqD;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,WAAW,EAAE,EACjC,IAAI,EAAE,SAAS,WAAW,EAAE,GAC3B,oBAAoB,CAoBtB"}

package/dist/types/lib/influence-core/attributability.d.ts

@@ -0,0 +1,73 @@
+/**
+ * rankingConfidence — honesty marker for an influence ranking (RFC-003 honesty
+ * marker; influence-core block D6). Internal concept: "attributability".
+ *
+ * Pattern: pure, embedder-free function over a `scoreInfluence` result.
+ *          Deterministic; no I/O.
+ * Role:    `src/lib/influence-core/` leaf. The honesty companion to the
+ *          four-signal scorer: it says when the ranking is a SHORTLIST,
+ *          not a verdict.
+ *
+ * ## Why this exists (the measured blind spot)
+ *
+ * Output-similarity influence ranks sources by how much they resemble the
+ * final answer. That is structurally blind to ABSENCE / CROWDING bugs: a
+ * culprit that caused the error by *displacing* context (history truncation,
+ * context dilution) need not resemble the answer — so it ranks low, or below
+ * an innocent that the answer happens to talk about. The tell is not a low
+ * absolute score; it is a FLAT top — no source clearly dominates. This
+ * function reports that flatness honestly so consumers escalate to ablation
+ * (the causal tier) instead of trusting a confident-but-wrong rank-1.
+ *
+ * Honest claim (RFC-002 §2 discipline): `clearWinner` is a proxy for "the
+ * ranking has a clear lead", never "the lead is the cause". A clear lead can
+ * still be an innocent the answer rationalizes over — only ablation makes
+ * causal claims.
+ */
+import type { ConfidenceStrategy, InfluenceScore, RankingConfidence } from './types.js';
+/**
+ * Default strategy: ABSOLUTE top-2 gap `s0 − s1 >= threshold`. Simple and
+ * interpretable, but embedder-relative (the gap scale depends on the embedding
+ * geometry). Use `ratioStrategy` for cross-embedder transfer.
+ */
+export declare function marginStrategy(threshold?: number): ConfidenceStrategy;
+/**
+ * Scale-invariant strategy: top-2 gap as a FRACTION of the top score,
+ * `(s0 − s1) / |s0| >= threshold`. Transfers across embedders / answer lengths
+ * where the absolute margin does not. A zero (or all-equal) top is never a
+ * clear winner.
+ */
+export declare function ratioStrategy(threshold?: number): ConfidenceStrategy;
+export interface RankingConfidenceOptions {
+    /**
+     * The decisiveness rule. Default: `marginStrategy(clearWinnerMargin)`.
+     * When set, it WINS — `clearWinnerMargin` is ignored. Bring your own
+     * (e.g. entropy / dispersion) or use the shipped `ratioStrategy`.
+     */
+    readonly strategy?: ConfidenceStrategy;
+    /** Threshold for the DEFAULT margin strategy (ignored when `strategy` is
+     *  set). Default: `DEFAULT_CLEAR_WINNER_MARGIN` (0.05). */
+    readonly clearWinnerMargin?: number;
+    /** Score band below the top defining the shortlist to double-check.
+     *  Default: `DEFAULT_SHORTLIST_BAND` (0.1). Recommended >=
+     *  `clearWinnerMargin` so the shortlist is at least as wide as the
+     *  winning gap (the function also guarantees the runner-up is shortlisted
+     *  when there is no clear winner, so a smaller value is safe). */
+    readonly shortlistBand?: number;
+}
+/**
+ * Assess whether an influence ranking has a clear winner to trust as a lead,
+ * or is too close to call and should be confirmed by ablation.
+ *
+ * Guarantees (relied on by the localizer): the returned `shortlist` always
+ * contains `lead` when there is one, and — when there is NO clear winner and
+ * there are ≥2 suspects — always contains the runner-up too (so ablation over
+ * the shortlist covers the real culprit even if it ranked below an innocent).
+ *
+ * @param scores `scoreInfluence` output (any order — re-sorted defensively).
+ *               Ids are assumed unique (as `scoreInfluence` enforces); the
+ *               shortlist is de-duplicated defensively regardless.
+ * @throws Error on negative or NaN options.
+ */
+export declare function rankingConfidence(scores: readonly InfluenceScore[], options?: RankingConfidenceOptions): RankingConfidence;
+//# sourceMappingURL=attributability.d.ts.map

package/dist/types/lib/influence-core/attributability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attributability.d.ts","sourceRoot":"","sources":["../../../../src/lib/influence-core/attributability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AASxF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,GAAE,MAAoC,GAAG,kBAAkB,CAMlG;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,GAAE,MAAmC,GAAG,kBAAkB,CAWhG;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IACvC;+DAC2D;IAC3D,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;;sEAIkE;IAClE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAeD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,OAAO,GAAE,wBAA6B,GACrC,iBAAiB,CA0EnB"}

package/dist/types/lib/influence-core/index.d.ts

@@ -24,8 +24,9 @@
  * embedding-geometry PROXY — semantic alignment, never model internals
  * and never causal attribution.
  */
-export type { CandidateScore, EmbedArgs, EmbedBatchArgs, Embedder, EvidenceInput, InfluenceScore, InfluenceWeights, MarginCandidate, MarginResult, PairwiseSimilarityResult, SignalScores, SimilarityItem, SimilarityPair, } from './types.js';
-export { DEFAULT_INFLUENCE_WEIGHTS, DEFAULT_MARGIN_THRESHOLD, DEFAULT_PERSISTENCE_THRESHOLD, } from './types.js';
+export type { CandidateScore, ConfidenceStrategy, EmbedArgs, EmbedBatchArgs, Embedder, EvidenceInput, InfluenceScore, InfluenceWeights, MarginCandidate, MarginResult, PairwiseSimilarityResult, RankingConfidence, SignalScores, SimilarityItem, SimilarityPair, } from './types.js';
+export { DEFAULT_CLEAR_WINNER_MARGIN, DEFAULT_CLEAR_WINNER_RATIO, DEFAULT_INFLUENCE_WEIGHTS, DEFAULT_MARGIN_THRESHOLD, DEFAULT_PERSISTENCE_THRESHOLD, DEFAULT_SHORTLIST_BAND, } from './types.js';
+export { marginStrategy, rankingConfidence, ratioStrategy, type RankingConfidenceOptions, } from './attributability.js';
 export { contentHash, EmbeddingCache, embeddingCache, type EmbeddingCacheOptions, type EmbeddingCacheStats, } from './cache.js';
 export { adaptWeights, averageRelevancy, compositeScore, finalAnswerSimilarity, persistence, scoreInfluence, structuralProximity, type ScoreInfluenceArgs, } from './signals.js';
 export { pairwiseSimilarity, type PairwiseSimilarityArgs } from './similarity.js';

package/dist/types/lib/influence-core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/influence-core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,YAAY,EACV,cAAc,EACd,SAAS,EACT,cAAc,EACd,QAAQ,EACR,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,wBAAwB,EACxB,YAAY,EACZ,cAAc,EACd,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,WAAW,EACX,cAAc,EACd,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,GACzB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACrB,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAElF,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/influence-core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,YAAY,EACV,cAAc,EACd,kBAAkB,EAClB,SAAS,EACT,cAAc,EACd,QAAQ,EACR,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,wBAAwB,EACxB,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,6BAA6B,EAC7B,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,KAAK,wBAAwB,GAC9B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,WAAW,EACX,cAAc,EACd,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,GACzB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACrB,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAElF,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/types/lib/influence-core/types.d.ts

@@ -46,6 +46,101 @@ export declare const DEFAULT_INFLUENCE_WEIGHTS: InfluenceWeights;
 export declare const DEFAULT_PERSISTENCE_THRESHOLD = 0.3;
 /** RFC-002 §4 default: margins below this flag the choice as `narrow`. */
 export declare const DEFAULT_MARGIN_THRESHOLD = 0.05;
+/**
+ * RFC-003 default: an influence ranking whose top-1 vs top-2 score margin is
+ * below this has NO clear winner — a shortlist, not a verdict. Escalate to
+ * ablation.
+ *
+ * UNCALIBRATED proxy starting point, chosen for interpretability. `margin`
+ * is an ABSOLUTE difference on the same scale as `scoreInfluence`'s composite
+ * (S ∈ ≈[−0.7, 1]), so this threshold is EMBEDDER-RELATIVE — recalibrate by
+ * sweeping clear-winner vs flat rankings on your embedder. The numeric
+ * coincidence with `DEFAULT_MARGIN_THRESHOLD` is NOT a shared derivation: that
+ * one measures `scoreMargin`'s chosen-vs-not-chosen distribution, a different
+ * statistic.
+ */
+export declare const DEFAULT_CLEAR_WINNER_MARGIN = 0.05;
+/**
+ * RFC-003 default: when there is no clear winner, suspects scoring within this
+ * band of the top form the shortlist ablation should COVER (the culprit may be
+ * any of them — or, for absence bugs, none). UNCALIBRATED proxy; embedder-
+ * relative (see `DEFAULT_CLEAR_WINNER_MARGIN`).
+ */
+export declare const DEFAULT_SHORTLIST_BAND = 0.1;
+/**
+ * RFC-003 default for `ratioStrategy`: the top-2 gap as a FRACTION of the top
+ * score `(s0 − s1) / |s0|`. Unlike the absolute margin this is scale-invariant,
+ * so it transfers across embedders / answer lengths. UNCALIBRATED proxy.
+ */
+export declare const DEFAULT_CLEAR_WINNER_RATIO = 0.05;
+/**
+ * Pluggable rule for "does one source clearly win this ranking?" — the
+ * decisiveness test inside `rankingConfidence`. The library ships
+ * `marginStrategy` (default, absolute gap) and `ratioStrategy` (scale-
+ * invariant); consumers may bring their own (e.g. entropy / dispersion). The
+ * framework around it — always shortlisting the lead, covering the runner-up
+ * when there is no clear winner, malformed-score robustness — is NOT the
+ * strategy's concern; the strategy only judges the clean, all-finite case.
+ */
+export interface ConfidenceStrategy {
+    /** Identifies the rule — shown in `reason`, and the key on a benchmark
+     *  leaderboard of strategies. */
+    readonly name: string;
+    /**
+     * Given the FINITE scores sorted DESCENDING (length >= 2), decide whether
+     * one source clearly dominates. Pure and deterministic.
+     */
+    isClearWinner(rankedScores: readonly number[]): boolean;
+}
+/**
+ * Confidence in an influence ranking (`scoreInfluence` output) — the honesty
+ * companion to the scorer.
+ *
+ * Output-similarity influence is a PROXY: it ranks sources by how much they
+ * resemble the final answer. It is structurally BLIND to absence/crowding bugs
+ * — a culprit that caused the error by *displacing* context (history
+ * truncation, context dilution) need not resemble the answer at all, so it can
+ * rank low or off the top. This result makes that honesty explicit: when no
+ * source clearly dominates, the ranking is a SHORTLIST to confirm by ablation,
+ * never a verdict. Mirrors the causal slice's incompleteness markers — the
+ * library says what its proxy cannot see.
+ */
+export interface RankingConfidence {
+    /**
+     * True when one source clearly dominates (`margin >= clearWinnerMargin`),
+     * so the ranking can be trusted as a LEAD. False = treat as shortlist +
+     * ablate. (A single suspect is trivially a clear winner — by absence of
+     * alternatives, not strength of signal.) NOTE: this is the inverse of the
+     * sibling `MarginResult.flags.narrow`. Honesty: a clear winner means the
+     * proxy has a clear top, NOT that the top is the cause — a high-similarity
+     * innocent the answer rationalizes over can win; ablation is the only causal
+     * confirmation in either branch.
+     */
+    readonly clearWinner: boolean;
+    /**
+     * `score(#1) − score(#2)`, an ABSOLUTE difference on the composite-score
+     * scale (embedder-relative). `undefined` when fewer than 2 suspects, when
+     * all scores are malformed, or when the runner-up score is unavailable
+     * (a clean top over a malformed #2). Read `clearWinner` to disambiguate.
+     */
+    readonly margin: number | undefined;
+    /** Id of the top-ranked suspect (the lead). `undefined` only when there are
+     *  none. Under an exact top tie this is the input-order first and not
+     *  meaningful (there is no clear winner anyway). */
+    readonly lead: string | undefined;
+    /**
+     * Suspects within the band of the top score — the set ablation should COVER.
+     * CONSUME ONLY WHEN `clearWinner` IS FALSE; when there is a clear winner this
+     * is informational (the band near the top), not an ablation worklist. Always
+     * includes `lead` when present, and — when no clear winner with ≥2 suspects —
+     * the runner-up too. De-duplicated.
+     */
+    readonly shortlist: readonly string[];
+    /** Human-readable explanation for narratives / reports. PRESENTATION ONLY —
+     *  read `clearWinner` / `margin` / `shortlist` as data, never parse this
+     *  string. */
+    readonly reason: string;
+}
 /** The four signal values for one evidence item (paper Eq. 1–4). */
 export interface SignalScores {
     /** FA — cosine(evidence, finalAnswer). Range [-1, 1]. */

package/dist/types/lib/influence-core/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/lib/influence-core/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/lib/influence-core/types.ts"],"names":[],"mappings":"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"}