agentfootprint 6.28.1 → 6.29.0

package/README.md

@@ -107,6 +107,16 @@ A: verifyAuditBundle → valid: false, brokenAt: #16 — the tampered record, na
 
 And you don't have to read the trace yourself — **we provide the tools for an LLM to track it for you**: the trace toolpack let a debugger model find a planted bug while reading **9.5% of the trace** ([guide](docs/guides/trace-debugging.md)).
 
+**And all this watching costs the run nothing.** Your agent *is* the event loop: a stage runs on the call stack and feeds its trace events into a queue; in the idle beat the dispatcher delivers them to your listeners and files them in trace memory — **one beat behind**, never blocking the hot path:
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/event-loop-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="docs/assets/event-loop-light.svg">
+    <img alt="Your agent is the event loop — animated. Left: your agent code (Context, Call LLM, Tool Calls) looping turn after turn. Right: the JS event loop drawn as two bold curved arrows with a traveling cursor and two stops — the call stack, where each stage runs as a frame and feeds four trace events (structure, data, control, emit) into the trace queue at the loop's center; and idle time, where the dispatcher flies the queued events into TRACE MEMORY and every listener (onStageAdded, onCommit, onDecision, onEmit) receives every event, one beat behind. Grey is JavaScript's own machinery, green is footprintjs, colors are your code and its trace." src="docs/assets/event-loop-light.svg" width="100%"/>
+  </picture>
+</p>
+
 ## One contextual error, walked end to end
 
 The third question above, in full — every value below is the captured output of
@@ -140,6 +150,36 @@ flips APPROVED → DECLINED in **3/3 seeded reruns**; the benign style fact and
 the lookup tool come back not-confirmed, 0/3. Scores are proxies; only the
 ablation verdict makes a causal claim — the report says so itself.
 
+**And when the proxy *can't* rank — it says so.** Output-similarity scoring is
+structurally blind to **absence/crowding** bugs (a key instruction truncated out
+of the window, context diluted by filler): the culprit doesn't resemble the
+answer, so it ranks low under an innocent. `rankingConfidence` is the honesty
+marker for that — when no source clearly wins, it returns a **shortlist to
+confirm by ablation** instead of a confident, wrong #1:
+
+```typescript
+import { rankingConfidence, ratioStrategy } from 'agentfootprint/observe';
+
+const c = rankingConfidence(scores); // over a scoreInfluence() result
+if (!c.clearWinner) ablate(c.shortlist); // too flat to trust → escalate to truth
+// decisiveness rule is pluggable: marginStrategy (default) · ratioStrategy
+// (scale-invariant) · bring-your-own. See docs/guides/ranking-confidence.md
+```
+
+**Three interfaces, one for each shape of the bug** — ship-a-default, bring-your-own:
+
+| interface | finds the culprit when it is… | confirm by |
+|---|---|---|
+| **influence ranking** (`scoreInfluence` + `rankingConfidence`) | **present** — orders suspects, says when it can't | — |
+| **ablation** (`localizeContextBug`) | **present** — *remove* it, see the outcome flip | removal |
+| **missing-context finder** (`findDroppedContext`) | **absent** — available but never reached the model (`available − sent`) | restoration |
+
+The third closes the gap the first two are blind to — a key instruction truncated
+out of the window has nothing to ablate. `findDroppedContext` is a cheap, exact id
+diff (no embeddings, no LLM); confirm by *restoration* — add the dropped unit back,
+see if the outcome flips. [Guide](docs/guides/missing-context.md) ·
+[example](examples/observability/10-missing-context.ts).
+
 **The same walk, visual.** One call serializes the report for
 [AgentThinkingUI](https://github.com/footprintjs/agentThinkingUI)'s
 `<BacktrackView>` — the "why?" board, triggerable from **any** decision point
@@ -174,7 +214,7 @@ board is a `runtimeStageId` a debugger LLM can drill with the
 | 🔧 Building an agent? | 🐛 Agent misbehaving? | 🏛️ Need audit / compliance? |
 |---|---|---|
 | Typed agents with skills, steering, RAG, memory, guardrails — and the trace for free. | Lint your tool catalog in 5 minutes — works on **any** framework's tool list (plain JSON / MCP / OpenAI / Anthropic shapes). Then causal slices, context bisection, and the debugger-LLM toolpack. | Hash-chained, tamper-evident run records with an offline verifier — record-keeping in the EU-AI-Act shape. |
-| [→ Quick start](#quick-start--runs-offline-no-api-key) | [→ Tool-catalog lint](docs/guides/tool-catalog-lint.md) · [→ Trace debugging](docs/guides/trace-debugging.md) | [→ Tamper-evident audit](docs/guides/security.md) |
+| [→ Quick start](#quick-start--runs-offline-no-api-key) · [→ Build ↓](#-build--design-your-agent-or-system-of-agents) | [→ Debug ↓](#-debug--see-what-your-agent-did) · [→ Tool-catalog lint](docs/guides/tool-catalog-lint.md) · [→ Trace debugging](docs/guides/trace-debugging.md) | [→ Audit ↓](#-audit--prove-what-happened) · [→ Security guide](docs/guides/security.md) |
 
 ---
 
@@ -265,7 +305,7 @@ const pipeline = Sequence.create()
 await pipeline.run({ message: 'URGENT: refund dispute on order #4411' });
 ```
 
-The fourth primitive is `Loop` — `Loop.repeat(agent).until(guard).times(5)`, with a mandatory budget guard. And the named patterns from the research literature ship pre-composed from the same four: `selfConsistency` · `reflection` · `debate` · `mapReduce` · `tot` · `swarm`. Because every composition is a flowchart, the structure you wrote is the structure you see in the UI — and the trace spans the whole pipeline, not one agent at a time. [Designing systems of agents ↓](#how-do-i-design-my-agent-or-system-of-agents)
+The fourth primitive is `Loop` — `Loop.repeat(agent).until(guard).times(5)`, with a mandatory budget guard. And the named patterns from the research literature ship pre-composed from the same four: `selfConsistency` · `reflection` · `debate` · `mapReduce` · `tot` · `swarm`. Because every composition is a flowchart, the structure you wrote is the structure you see in the UI — and the trace spans the whole pipeline, not one agent at a time. [Designing systems of agents ↓](#-build--design-your-agent-or-system-of-agents)
 
 ---
 
@@ -348,7 +388,7 @@ So we used the budget those abstractions would have cost us to invest deeply in
 
 ---
 
-## How do I design my agent or system of agents?
+## 🔧 Build — design your agent or system of agents
 
 Two scales — same alphabet. Four control flows are the entire vocabulary.
 
@@ -510,7 +550,7 @@ Same trick as the injection model: instead of N libraries for N patterns, we fou
 
 ---
 
-## How do I see what my agent did?
+## 🐛 Debug — see what your agent did
 
 <p align="center">
   <img src="docs/assets/lens-run.png" alt="A real agent run in the Lens: the conversation (with live PII redaction), the executed path lit on the merge-tree flowchart, the WHAT-HAPPENED timeline of every iteration/context/LLM turn/route, run stats, and the step inspector — all generated from the run's own trace." width="100%">
@@ -618,6 +658,31 @@ off the hot path.
 
 ---
 
+## 🏛️ Audit — prove what happened
+
+Answering *"why was the loan rejected?"* from captured evidence is the [debug door above](#-debug--see-what-your-agent-did). The audit door adds the integrity layer: prove the **record itself** hasn't been edited since capture. `auditExport()` hash-chains every typed event — decisions, tool calls, validation rejections, permission verdicts, costs — into an append-only bundle (EU AI Act Art. 12 record-keeping shape); `verifyAuditBundle()` re-checks it **offline** — no agent, no LLM — and names the exact record any tamper broke.
+
+```ts
+import { auditExport, verifyAuditBundle } from 'agentfootprint/observability-providers';
+
+const audit = auditExport({ agent: 'ledger-auditor' });
+const stop = agent.enable.observability({ strategy: audit });
+await agent.run({ message: 'audit account ACCT-1142' });
+stop();
+
+const bundle = audit.bundle();           // plain JSON — store anywhere
+verifyAuditBundle(bundle);               // { valid: true, recordsChecked: 50 }
+// flip one byte anywhere → { valid: false, brokenAt: 13, reason: 'hash mismatch — …' }
+```
+
+Payloads are PII-bounded by default (tool args as key names, results as a type, content as `[N chars]` markers). And it's honest about its limits: tamper-**evident**, not tamper-proof — for non-repudiation, anchor both chain ends in external storage (WORM store, signed log).
+
+> 📖 **[Tamper-evident audit guide](docs/guides/security.md#tamper-evident-audit-export--auditexport--verifyauditbundle)** ·
+> [`examples/features/19-audit-export.ts`](examples/features/19-audit-export.ts) — capture → verify → tamper → drain ·
+> [`20-regulated-decisioning.ts`](examples/features/20-regulated-decisioning.ts) — an offline auditor reconstructs a loan decline from persisted files, both chain ends anchored
+
+---
+
 ## Mocks first, production second
 
 Build the entire app against in-memory mocks with **zero API cost**, then swap real infrastructure one boundary at a time.

package/dist/esm/lib/context-bisect/index.js

@@ -15,6 +15,8 @@
  * claims; slice completeness is bounded by tracking — and says so.
  */
 export { llmEdgeWeigher, stepOutputText, } from './llmEdgeWeigher.js';
+// Interface #3 — missing-context finder (available − sent; confirm by restoration).
+export { findDroppedContext, } from './missingContext.js';
 export { defaultSuspectClassifier, formatContextBugReport, llmCallIdsFromEvents, localizeContextBug, suspectLabel, } from './localize.js';
 export { toBacktrackTrace, } from './toBacktrackTrace.js';
 export { ablationForSuspect, applyAblations, defaultOutcomeComparator, probeFlipped, runAblationProbe, verdictFor, } from './ablation.js';

package/dist/esm/lib/context-bisect/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/context-bisect/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,cAAc,EACd,cAAc,GAIf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,YAAY,GAKb,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,gBAAgB,GAOjB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,wBAAwB,EACxB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GAGX,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,cAAc,GAIf,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,uBAAuB,GAoBxB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/context-bisect/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,cAAc,EACd,cAAc,GAIf,MAAM,qBAAqB,CAAC;AAE7B,oFAAoF;AACpF,OAAO,EACL,kBAAkB,GAInB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,YAAY,GAKb,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,gBAAgB,GAOjB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,wBAAwB,EACxB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GAGX,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,cAAc,GAIf,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,uBAAuB,GAoBxB,MAAM,YAAY,CAAC"}

package/dist/esm/lib/context-bisect/missingContext.js

@@ -0,0 +1,63 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function findDroppedContext(available, sent) {
+    const sentIds = new Set();
+    for (const u of sent)
+        sentIds.add(u.id);
+    const dropped = [];
+    const seenAvailable = new Set();
+    for (const u of available) {
+        if (seenAvailable.has(u.id))
+            continue; // de-dup by id, first wins
+        seenAvailable.add(u.id);
+        if (!sentIds.has(u.id))
+            dropped.push(u.content === undefined ? { id: u.id } : { id: u.id, content: u.content });
+    }
+    const availableCount = seenAvailable.size;
+    const sentCount = sentIds.size;
+    const anyDropped = dropped.length > 0;
+    const reason = anyDropped
+        ? `${dropped.length} of ${availableCount} available unit(s) never reached the model — candidate(s) for a missing-context bug (truncation / dilution). Confirm by RESTORATION: add a unit back and re-run; an outcome flip is the causal proof (mirror of ablation). Most dropped context is correctly dropped — only restoration confirms.`
+        : `All ${availableCount} available unit(s) reached the model — no missing-context bug here (nothing was dropped).`;
+    return { dropped, availableCount, sentCount, anyDropped, reason };
+}
+//# sourceMappingURL=missingContext.js.map

package/dist/esm/lib/context-bisect/missingContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"missingContext.js","sourceRoot":"","sources":["../../../../src/lib/context-bisect/missingContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAkCH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,kBAAkB,CAChC,SAAiC,EACjC,IAA4B;IAE5B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAExC,MAAM,OAAO,GAAkB,EAAE,CAAC;IAClC,MAAM,aAAa,GAAG,IAAI,GAAG,EAAU,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAAE,SAAS,CAAC,2BAA2B;QAClE,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACxB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IAClH,CAAC;IAED,MAAM,cAAc,GAAG,aAAa,CAAC,IAAI,CAAC;IAC1C,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAC/B,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,UAAU;QACvB,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,OAAO,cAAc,mSAAmS;QAC3U,CAAC,CAAC,OAAO,cAAc,2FAA2F,CAAC;IAErH,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AACpE,CAAC"}

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

@@ -0,0 +1,136 @@
+import { DEFAULT_CLEAR_WINNER_MARGIN, DEFAULT_CLEAR_WINNER_RATIO, DEFAULT_SHORTLIST_BAND } from './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.
+ */
+export function marginStrategy(threshold = DEFAULT_CLEAR_WINNER_MARGIN) {
+    nonNegative('marginStrategy: threshold', threshold);
+    return {
+        name: `margin>=${threshold}`,
+        isClearWinner: (s) => s.length >= 2 && s[0] - s[1] >= threshold,
+    };
+}
+/**
+ * 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 function ratioStrategy(threshold = 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;
+        },
+    };
+}
+/** 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.
+ */
+export 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 ?? DEFAULT_CLEAR_WINNER_MARGIN);
+    const shortlistBand = nonNegative('rankingConfidence: shortlistBand', options.shortlistBand ?? 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 };
+}
+//# sourceMappingURL=attributability.js.map

package/dist/esm/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/esm/lib/influence-core/index.js

@@ -24,7 +24,8 @@
  * embedding-geometry PROXY — semantic alignment, never model internals
  * and never causal attribution.
  */
-export { DEFAULT_INFLUENCE_WEIGHTS, DEFAULT_MARGIN_THRESHOLD, DEFAULT_PERSISTENCE_THRESHOLD, } 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, } from './attributability.js';
 export { contentHash, EmbeddingCache, embeddingCache, } from './cache.js';
 export { adaptWeights, averageRelevancy, compositeScore, finalAnswerSimilarity, persistence, scoreInfluence, structuralProximity, } from './signals.js';
 export { pairwiseSimilarity } from './similarity.js';

package/dist/esm/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,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,WAAW,EACX,cAAc,EACd,cAAc,GAGf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACrB,WAAW,EACX,cAAc,EACd,mBAAmB,GAEpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,kBAAkB,EAA+B,MAAM,iBAAiB,CAAC;AAElF,OAAO,EAAE,WAAW,EAAwB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/influence-core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAmBH,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,GAEd,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,WAAW,EACX,cAAc,EACd,cAAc,GAGf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACrB,WAAW,EACX,cAAc,EACd,mBAAmB,GAEpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,kBAAkB,EAA+B,MAAM,iBAAiB,CAAC;AAElF,OAAO,EAAE,WAAW,EAAwB,MAAM,aAAa,CAAC"}

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

@@ -32,4 +32,31 @@ export const DEFAULT_INFLUENCE_WEIGHTS = Object.freeze({
 export const DEFAULT_PERSISTENCE_THRESHOLD = 0.3;
 /** RFC-002 §4 default: margins below this flag the choice as `narrow`. */
 export 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 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 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 const DEFAULT_CLEAR_WINNER_RATIO = 0.05;
 //# sourceMappingURL=types.js.map

package/dist/esm/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;AACnE,MAAM,CAAC,MAAM,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;AACzD,MAAM,CAAC,MAAM,6BAA6B,GAAG,GAAG,CAAC;AAEjD,0EAA0E;AAC1E,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/lib/influence-core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AA0BH,mEAAmE;AACnE,MAAM,CAAC,MAAM,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;AACzD,MAAM,CAAC,MAAM,6BAA6B,GAAG,GAAG,CAAC;AAEjD,0EAA0E;AAC1E,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC;AAE7C;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAE1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC"}

package/dist/esm/observe.js

@@ -65,7 +65,7 @@ export { typedEmit } from './recorders/core/typedEmit.js';
 // edge weigher). Honest claim: every score is an embedding-geometry
 // PROXY — semantic alignment, never model internals, never causal
 // attribution.
-export { adaptWeights, averageRelevancy, compositeScore, contentHash, DEFAULT_INFLUENCE_WEIGHTS, DEFAULT_MARGIN_THRESHOLD, DEFAULT_PERSISTENCE_THRESHOLD, EmbeddingCache, embeddingCache, finalAnswerSimilarity, pairwiseSimilarity, persistence, scoreInfluence, scoreMargin, structuralProximity, } from './lib/influence-core/index.js';
+export { adaptWeights, averageRelevancy, compositeScore, contentHash, DEFAULT_CLEAR_WINNER_MARGIN, DEFAULT_CLEAR_WINNER_RATIO, DEFAULT_INFLUENCE_WEIGHTS, DEFAULT_MARGIN_THRESHOLD, DEFAULT_PERSISTENCE_THRESHOLD, DEFAULT_SHORTLIST_BAND, EmbeddingCache, embeddingCache, finalAnswerSimilarity, marginStrategy, pairwiseSimilarity, persistence, rankingConfidence, ratioStrategy, scoreInfluence, scoreMargin, structuralProximity, } from './lib/influence-core/index.js';
 // Introspection toolpack (RFC-003 Part C) — footprintjs trace evidence
 // exposed as TOOLS a debugging LLM calls over a COMPLETED run's artifacts.
 // Bounded, honest (⚠ markers), redaction-respecting, id-navigable.
@@ -81,7 +81,7 @@ export { buildSelfExplainSkill, buildSelfExplainToolProvider, SelfExplainBinding
 // counterfactual ablation. §B2 claim tiers: scores/weights are
 // embedding-geometry PROXIES; ablation verdicts are the ONLY causal
 // claims; slice completeness is bounded by tracking — and says so.
-export { ablationForSuspect, applyAblations, bisectCulprits, CONTEXT_BISECT_DEFAULTS, defaultOutcomeComparator, defaultSuspectClassifier, formatContextBugReport, llmCallIdsFromEvents, llmEdgeWeigher, localizeContextBug, probeFlipped, runAblationProbe, stepOutputText, suspectLabel, verdictFor, } from './lib/context-bisect/index.js';
+export { ablationForSuspect, applyAblations, bisectCulprits, CONTEXT_BISECT_DEFAULTS, defaultOutcomeComparator, defaultSuspectClassifier, findDroppedContext, formatContextBugReport, llmCallIdsFromEvents, llmEdgeWeigher, localizeContextBug, probeFlipped, runAblationProbe, stepOutputText, suspectLabel, verdictFor, } from './lib/context-bisect/index.js';
 // BacktrackTrace serializer — feeds agentThinkingUI's <BacktrackView>
 // (the "why?" board) straight off a localizer report. Pure mapping, no
 // UI dependency; the interfaces mirror agentthinkingui's contract.

package/dist/esm/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/lib/context-bisect/index.js

@@ -16,10 +16,13 @@
  * claims; slice completeness is bounded by tracking — and says so.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CONTEXT_BISECT_DEFAULTS = exports.bisectCulprits = exports.verdictFor = exports.runAblationProbe = exports.probeFlipped = exports.defaultOutcomeComparator = exports.applyAblations = exports.ablationForSuspect = exports.toBacktrackTrace = exports.suspectLabel = exports.localizeContextBug = exports.llmCallIdsFromEvents = exports.formatContextBugReport = exports.defaultSuspectClassifier = exports.stepOutputText = exports.llmEdgeWeigher = void 0;
+exports.CONTEXT_BISECT_DEFAULTS = exports.bisectCulprits = exports.verdictFor = exports.runAblationProbe = exports.probeFlipped = exports.defaultOutcomeComparator = exports.applyAblations = exports.ablationForSuspect = exports.toBacktrackTrace = exports.suspectLabel = exports.localizeContextBug = exports.llmCallIdsFromEvents = exports.formatContextBugReport = exports.defaultSuspectClassifier = exports.findDroppedContext = exports.stepOutputText = exports.llmEdgeWeigher = void 0;
 var llmEdgeWeigher_js_1 = require("./llmEdgeWeigher.js");
 Object.defineProperty(exports, "llmEdgeWeigher", { enumerable: true, get: function () { return llmEdgeWeigher_js_1.llmEdgeWeigher; } });
 Object.defineProperty(exports, "stepOutputText", { enumerable: true, get: function () { return llmEdgeWeigher_js_1.stepOutputText; } });
+// Interface #3 — missing-context finder (available − sent; confirm by restoration).
+var missingContext_js_1 = require("./missingContext.js");
+Object.defineProperty(exports, "findDroppedContext", { enumerable: true, get: function () { return missingContext_js_1.findDroppedContext; } });
 var localize_js_1 = require("./localize.js");
 Object.defineProperty(exports, "defaultSuspectClassifier", { enumerable: true, get: function () { return localize_js_1.defaultSuspectClassifier; } });
 Object.defineProperty(exports, "formatContextBugReport", { enumerable: true, get: function () { return localize_js_1.formatContextBugReport; } });

package/dist/lib/context-bisect/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/context-bisect/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAEH,yDAM6B;AAL3B,mHAAA,cAAc,OAAA;AACd,mHAAA,cAAc,OAAA;AAMhB,6CAUuB;AATrB,uHAAA,wBAAwB,OAAA;AACxB,qHAAA,sBAAsB,OAAA;AACtB,mHAAA,oBAAoB,OAAA;AACpB,iHAAA,kBAAkB,OAAA;AAClB,2GAAA,YAAY,OAAA;AAOd,6DAQ+B;AAP7B,uHAAA,gBAAgB,OAAA;AASlB,6CASuB;AARrB,iHAAA,kBAAkB,OAAA;AAClB,6GAAA,cAAc,OAAA;AACd,uHAAA,wBAAwB,OAAA;AACxB,2GAAA,YAAY,OAAA;AACZ,+GAAA,gBAAgB,OAAA;AAChB,yGAAA,UAAU,OAAA;AAKZ,yCAKqB;AAJnB,2GAAA,cAAc,OAAA;AAMhB,uCAqBoB;AApBlB,mHAAA,uBAAuB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/context-bisect/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAEH,yDAM6B;AAL3B,mHAAA,cAAc,OAAA;AACd,mHAAA,cAAc,OAAA;AAMhB,oFAAoF;AACpF,yDAK6B;AAJ3B,uHAAA,kBAAkB,OAAA;AAMpB,6CAUuB;AATrB,uHAAA,wBAAwB,OAAA;AACxB,qHAAA,sBAAsB,OAAA;AACtB,mHAAA,oBAAoB,OAAA;AACpB,iHAAA,kBAAkB,OAAA;AAClB,2GAAA,YAAY,OAAA;AAOd,6DAQ+B;AAP7B,uHAAA,gBAAgB,OAAA;AASlB,6CASuB;AARrB,iHAAA,kBAAkB,OAAA;AAClB,6GAAA,cAAc,OAAA;AACd,uHAAA,wBAAwB,OAAA;AACxB,2GAAA,YAAY,OAAA;AACZ,+GAAA,gBAAgB,OAAA;AAChB,yGAAA,UAAU,OAAA;AAKZ,yCAKqB;AAJnB,2GAAA,cAAc,OAAA;AAMhB,uCAqBoB;AApBlB,mHAAA,uBAAuB,OAAA"}

package/dist/lib/context-bisect/missingContext.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findDroppedContext = void 0;
+/**
+ * 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
+ *     }
+ *   }
+ */
+function findDroppedContext(available, sent) {
+    const sentIds = new Set();
+    for (const u of sent)
+        sentIds.add(u.id);
+    const dropped = [];
+    const seenAvailable = new Set();
+    for (const u of available) {
+        if (seenAvailable.has(u.id))
+            continue; // de-dup by id, first wins
+        seenAvailable.add(u.id);
+        if (!sentIds.has(u.id))
+            dropped.push(u.content === undefined ? { id: u.id } : { id: u.id, content: u.content });
+    }
+    const availableCount = seenAvailable.size;
+    const sentCount = sentIds.size;
+    const anyDropped = dropped.length > 0;
+    const reason = anyDropped
+        ? `${dropped.length} of ${availableCount} available unit(s) never reached the model — candidate(s) for a missing-context bug (truncation / dilution). Confirm by RESTORATION: add a unit back and re-run; an outcome flip is the causal proof (mirror of ablation). Most dropped context is correctly dropped — only restoration confirms.`
+        : `All ${availableCount} available unit(s) reached the model — no missing-context bug here (nothing was dropped).`;
+    return { dropped, availableCount, sentCount, anyDropped, reason };
+}
+exports.findDroppedContext = findDroppedContext;
+//# sourceMappingURL=missingContext.js.map

package/dist/lib/context-bisect/missingContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"missingContext.js","sourceRoot":"","sources":["../../../src/lib/context-bisect/missingContext.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;;AAkCH;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,kBAAkB,CAChC,SAAiC,EACjC,IAA4B;IAE5B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAExC,MAAM,OAAO,GAAkB,EAAE,CAAC;IAClC,MAAM,aAAa,GAAG,IAAI,GAAG,EAAU,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAAE,SAAS,CAAC,2BAA2B;QAClE,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACxB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IAClH,CAAC;IAED,MAAM,cAAc,GAAG,aAAa,CAAC,IAAI,CAAC;IAC1C,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAC/B,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,UAAU;QACvB,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,OAAO,cAAc,mSAAmS;QAC3U,CAAC,CAAC,OAAO,cAAc,2FAA2F,CAAC;IAErH,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AACpE,CAAC;AAvBD,gDAuBC"}