crumbtrail-core 0.2.0 → 0.2.2

package/README.md

@@ -1,12 +1,91 @@
 # crumbtrail-core
 
-Browser SDK for Crumbtrail session capture.
+The capture engine behind [Crumbtrail](https://crumbtrail.dev). It records what
+actually happened around a bug — the console, the network calls, the DOM
+interactions, the state — and hands it over as evidence a coding agent can act on,
+instead of a screenshot and a vague repro.
 
-Use this package in browser applications that need to capture user interactions,
-network context, and runtime evidence for a local Crumbtrail server.
+Framework-agnostic, with **no dependencies**.
+
+## Install
 
 ```bash
-npm i crumbtrail-core
+npm install crumbtrail-core
+```
+
+Or let the wizard install and wire it for you:
+
+```bash
+npx crumbtrail
+```
+
+## Setup
+
+Call `Crumbtrail.init()` once, at your app's entry point:
+
+```ts
+import { Crumbtrail, PRESET_PASSIVE } from "crumbtrail-core";
+
+Crumbtrail.init({
+  ...PRESET_PASSIVE,
+  httpEndpoint: "https://api.crumbtrail.dev",
+  httpAuthToken: process.env.CRUMBTRAIL_KEY,
+});
 ```
 
-For the local server, CLI, and MCP evidence tools, install `crumbtrail-node`.
+That's the whole integration — capture runs in the background from there.
+
+### Presets
+
+| Preset | Behaviour |
+| --- | --- |
+| `PRESET_PASSIVE` | Capture continuously and auto-flag on errors and signals. The default. |
+| `PRESET_LIGHT` | Leaner capture, less overhead. |
+| `PRESET_FULL` | Everything, for a heavy debugging session. |
+
+### Flagging a bug yourself
+
+`init()` returns the instance, so you can mark moments explicitly:
+
+```ts
+const crumbtrail = Crumbtrail.init({ ...PRESET_PASSIVE, httpEndpoint });
+
+crumbtrail.mark("checkout: submitted");
+
+await crumbtrail.flagBug({
+  note: "Payment failed with no error toast",
+  tags: ["checkout"],
+});
+```
+
+Also on the instance: `addEvent`, `registerStateProvider`, `setEnv`,
+`createRequestHeaders`, `pause`, `resume`, `stop`, `getSessionId`.
+
+## Redaction is on by default
+
+Crumbtrail is meant to be pointed at real traffic, so scrubbing isn't opt-in.
+Tokens, cookies, storage values and sensitive input values are redacted before an
+event ever leaves the browser. See `BROWSER_REDACTION_POLICY` and the `redact*`
+helpers if you want to inspect or tighten the policy.
+
+## Related packages
+
+| Package | Use it for |
+| --- | --- |
+| [`crumbtrail`](https://www.npmjs.com/package/crumbtrail) | The `npx crumbtrail` setup wizard |
+| [`crumbtrail-node`](https://www.npmjs.com/package/crumbtrail-node) | Self-hosted server, Express middleware, MCP evidence tools |
+| [`crumbtrail-react`](https://www.npmjs.com/package/crumbtrail-react) | React error boundary and state-capture hook |
+| [`crumbtrail-react-native`](https://www.npmjs.com/package/crumbtrail-react-native) | React Native bindings |
+| [`crumbtrail-tauri`](https://www.npmjs.com/package/crumbtrail-tauri) | Tauri desktop bindings |
+
+## Links
+
+- **Website** — https://crumbtrail.dev
+- **Docs** — https://crumbtrail.dev/docs
+- **How it works** — https://crumbtrail.dev/how-it-works
+- **Source** — https://github.com/crumbtrail-dev/crumbtrail-js
+- **Issues** — https://github.com/crumbtrail-dev/crumbtrail-js/issues
+
+## License
+
+MIT

package/dist/index.cjs

@@ -4634,21 +4634,139 @@ function inferIntent(evidence, commits) {
 var FUSION_SCHEMA_VERSION = "fusion.v1";
 function assembleBundle(input) {
   const evidence = rankEvidence(input.symptom, input.evidence);
-  const hypotheses = classifyHypotheses(
+  const classified = classifyHypotheses(
     input.symptom,
     input.evidence,
     input.intent
   );
   const gaps = input.gaps ?? [];
+  const located = input.located;
+  const hypotheses = classified.map((hypothesis) => {
+    const verification = deriveVerification(hypothesis, evidence);
+    return verification.length > 0 ? { ...hypothesis, verification } : hypothesis;
+  });
+  const contextCompleteness = deriveContextCompleteness(
+    evidence,
+    gaps,
+    hypotheses,
+    located
+  );
+  const escalation = deriveEscalation(contextCompleteness, hypotheses);
   return {
     schemaVersion: FUSION_SCHEMA_VERSION,
     symptom: input.symptom,
     evidence,
     opinion: { stance: "advisory", hypotheses },
     gaps,
-    directives: suggestCaptureDirectives(input.symptom, input.evidence, gaps)
+    directives: suggestCaptureDirectives(input.symptom, input.evidence, gaps),
+    contextCompleteness,
+    escalation,
+    ...located ? { located } : {}
   };
 }
+function clamp01(value) {
+  if (Number.isNaN(value)) return 0;
+  return Math.max(0, Math.min(1, value));
+}
+var COMPLETENESS_LANES = [
+  "network",
+  "db",
+  "flow",
+  "browser",
+  "env"
+];
+function deriveContextCompleteness(evidence, gaps, hypotheses, located) {
+  const lanesPresent = new Set(evidence.map((item) => item.lane));
+  const informativePresent = COMPLETENESS_LANES.filter(
+    (lane) => lanesPresent.has(lane)
+  );
+  const breadth = Math.min(1, informativePresent.length / 3);
+  const volume = Math.min(1, evidence.length / 5);
+  const top = hypotheses[0];
+  const hypothesisStrength = !top || top.kind === "inconclusive" ? 0 : top.confidence;
+  let score = 0.4 * breadth + 0.25 * volume + 0.35 * hypothesisStrength;
+  if (located) {
+    score = located.outcome === "matched" ? 0.85 * score + 0.15 * clamp01(located.confidence) : score * 0.6;
+  }
+  const hardGaps = gaps.filter((gap) => gap.kind === "source-unavailable").length;
+  const softGaps = gaps.length - hardGaps;
+  const gapPenalty = Math.min(0.5, softGaps * 0.1 + hardGaps * 0.3);
+  score = clamp01(score - gapPenalty);
+  const level = score < 0.34 ? "low" : score < 0.67 ? "medium" : "high";
+  const reasons = [];
+  const missingLanes = COMPLETENESS_LANES.filter(
+    (lane) => !lanesPresent.has(lane)
+  );
+  if (informativePresent.length === 0) {
+    reasons.push("no network/db/flow/browser/env evidence captured");
+  } else if (missingLanes.length > 0) {
+    reasons.push(`missing evidence lanes: ${missingLanes.join(", ")}`);
+  }
+  if (evidence.length > 0 && evidence.length < 3) {
+    reasons.push(`thin evidence (${evidence.length} item(s))`);
+  }
+  if (hardGaps > 0) reasons.push(`source unavailable for ${hardGaps} lane(s)`);
+  if (softGaps > 0) reasons.push(`${softGaps} evidence gap(s)`);
+  if (located?.outcome === "inconclusive") {
+    reasons.push("incident location inconclusive");
+  }
+  if (!top || top.kind === "inconclusive") {
+    reasons.push("no distinguishing hypothesis");
+  }
+  return { score, level, reasons };
+}
+function pkString(pk) {
+  return Object.keys(pk).sort().map((key) => `${key}=${String(pk[key])}`).join(", ");
+}
+function deriveVerification(hypothesis, evidence) {
+  if (hypothesis.kind === "inconclusive") return [];
+  const cited = new Set(hypothesis.evidenceIds);
+  const out = [];
+  for (const item of evidence) {
+    if (!cited.has(item.id)) continue;
+    const ref = item.ref;
+    if (item.lane === "db" && ref.table && ref.pk && Object.keys(ref.pk).length > 0) {
+      out.push({
+        observation: `row in ${ref.table} (${pkString(ref.pk)}) matches the intended post-fix state`,
+        evidenceIds: [item.id],
+        how: "db"
+      });
+    } else if (ref.requestId) {
+      const sigPart = ref.sig ? ` for signature ${ref.sig}` : "";
+      out.push({
+        observation: `request ${ref.requestId} succeeds${sigPart} on a fresh run (no error response)`,
+        evidenceIds: [item.id],
+        how: "request"
+      });
+    } else if (ref.sig) {
+      out.push({
+        observation: `error signature ${ref.sig} no longer appears in a fresh session over the same route`,
+        evidenceIds: [item.id],
+        how: "session"
+      });
+    }
+  }
+  return out;
+}
+function deriveEscalation(completeness, hypotheses) {
+  const allInconclusive = hypotheses.length > 0 && hypotheses.every((hypothesis) => hypothesis.kind === "inconclusive");
+  const recommended = completeness.level === "low" || allInconclusive;
+  if (!recommended) return { recommended: false, when: [] };
+  const when = [
+    "if you cannot reproduce the symptom via the anchored request or session, stop and request human triage \u2014 do not widen the search"
+  ];
+  if (completeness.level === "low") {
+    when.push(
+      "context is thin: confirm the missing evidence lanes before acting on the top hypothesis"
+    );
+  }
+  if (allInconclusive) {
+    when.push(
+      "no hypothesis is distinguished; treat the listed causes as equally unproven"
+    );
+  }
+  return { recommended, when };
+}
 var LANE_PRIOR = {
   db: 0.2,
   network: 0.2,

package/dist/index.d.cts

@@ -831,6 +831,76 @@ interface Hypothesis {
     rationale: string;
     /** EvidenceItem.id values backing this hypothesis. */
     evidenceIds: string[];
+    /**
+     * Advisory, additive: concrete observations that would confirm a fix for
+     * THIS hypothesis worked. Emitted only for non-inconclusive hypotheses whose
+     * cited evidence carries a concrete anchor (signature / requestId /
+     * table+pk); absent otherwise. Sparse-and-concrete by design — never vacuous
+     * prose like "verify the bug is gone". See {@link Verification}.
+     */
+    verification?: Verification[];
+}
+/**
+ * A concrete, post-fix observation that would confirm a hypothesis's fix
+ * worked. `observation` always names a concrete signal (an error signature, a
+ * request id, or a table + primary key) — the derivation emits nothing when it
+ * cannot anchor to one, so an emitted verification is never a vacuous
+ * restatement.
+ */
+interface Verification {
+    /** Names a concrete signal — signature, request id, or table/pk. */
+    observation: string;
+    /** EvidenceItem.id values this observation is anchored to. */
+    evidenceIds: string[];
+    how: "session" | "request" | "db";
+}
+/**
+ * Where the incident was located, when a locate ran. Advisory and optional
+ * (absent for explicit baseline/current comparison bundles that never locate).
+ * Shape shared with the node locate engine's `LocateMatch` and War-game 02's
+ * deterministic token join — `method` distinguishes the two so 02 can populate
+ * "token" without a schema change (War-game 02 Fork C: one definition, reused).
+ */
+interface Located {
+    outcome: "matched" | "inconclusive";
+    /** 0..1 locate confidence. */
+    confidence: number;
+    /**
+     * How the incident was located. "fuzzy" = the scored locate engine;
+     * "token" = a deterministic token join (War-game 02). Absent when a caller
+     * supplies neither.
+     */
+    method?: "fuzzy" | "token";
+    /** The matched session, present ONLY when outcome === "matched". Never fabricated. */
+    sessionId?: string;
+    reasons?: string[];
+}
+/**
+ * Bundle-level answer to "how much context do we actually have here?" — the
+ * LOW_CONTEXT signal. Derived purely from the assembled bundle (evidence
+ * lanes, gaps, hypothesis strength, locate confidence). Advisory: it NEVER
+ * gates or blocks bundle emission. `reasons` is the load-bearing part; `score`
+ * and `level` summarize it.
+ */
+interface ContextCompleteness {
+    /** 0..1; higher = richer, more actionable context. */
+    score: number;
+    level: "high" | "medium" | "low";
+    /** Human-legible drivers: missing lanes, thin evidence, inconclusive locate. */
+    reasons: string[];
+}
+/**
+ * Consumer-side advisory: what the CONSUMING agent should do when context is
+ * thin. Distinct from {@link EvidenceGap} (capture-side: what evidence is
+ * missing) — escalation is what to do about it. Always present; `recommended`
+ * is false with an empty `when` when context is adequate. Never gates the
+ * bundle (VISION: advisory, never a boolean verdict on the bug itself).
+ */
+interface Escalation {
+    recommended: boolean;
+    /** Conditions phrased for the consuming agent, e.g. "if you cannot reproduce
+     *  via the anchored request, stop and request human triage". */
+    when: string[];
 }
 interface EvidenceGap {
     lane: EvidenceLane;
@@ -871,12 +941,22 @@ interface RankedBundle {
     gaps: EvidenceGap[];
     /** Advisory-only: suggested capture escalations when evidence is thin. */
     directives: CaptureDirective[];
+    /** How much actionable context this bundle carries. Advisory, never gates. */
+    contextCompleteness: ContextCompleteness;
+    /** What the consuming agent should do when context is thin. Advisory. */
+    escalation: Escalation;
+    /** Where the incident was located, when a locate ran. Absent otherwise. */
+    located?: Located;
 }
 interface AssembleBundleInput {
     symptom: Symptom;
     evidence: EvidenceItem[];
     intent: IntentSignal[];
     gaps?: EvidenceGap[];
+    /** The locate decision, when one ran (auto-locate / token join). Threaded
+     *  onto the bundle as {@link RankedBundle.located} and folded into
+     *  completeness. Omit for explicit baseline/current comparison bundles. */
+    located?: Located;
 }
 /**
  * Compose the RankedBundle: rank the complete evidence set (nothing dropped),
@@ -971,4 +1051,4 @@ type Stack = "nextjs" | "react" | "vue" | "svelte" | "vite" | "express" | "hono"
 /** Stable ordered id list, handy for iterating or building pickers. */
 declare const STACK_IDS: readonly Stack[];
 
-export { type AbandonedFlowOptions, type AddBugEventOptions, type AssembleBundleInput, type AutoFlagController, type AutoFlagOptions, BROWSER_REDACTION_POLICY, type BodyRedactionOptions, type BodyRedactionResult, type BugEvent, type BugReport, CRUMBTRAIL_EVENT_KINDS, CRUMBTRAIL_REQUEST_HEADER, CRUMBTRAIL_REQUEST_HEADER_LOWER, CRUMBTRAIL_REQUEST_ID_MAX_LENGTH, CRUMBTRAIL_SCHEMA_VERSION, CRUMBTRAIL_SESSION_HEADER, CRUMBTRAIL_SESSION_HEADER_LOWER, type CaptureDirective, type CollectorCleanup, type CollectorContext, type CommitInfo, Crumbtrail, type CrumbtrailCapabilities, type CrumbtrailConfig, type CrumbtrailPlatform, type CrumbtrailPreset, type CrumbtrailSdkDescriptor, type CrumbtrailTransport, DB_DIFF_BULK_EVENT_KIND, DB_DIFF_EVENT_KIND, DB_READ_BULK_EVENT_KIND, DB_READ_EVENT_KIND, DEFAULT_CONFIG, DEFAULT_SESSION_STORAGE_KEY, type DbDiffBulkEventData, type DbDiffEventData, type DbDiffOp, type DbEngine, type DbReadBulkEventData, type DbReadEventData, EVIDENCE_SCHEMA_VERSION, EVIDENCE_SOURCE_SCHEMA_VERSION, type ElementSignature, type EnvDeclaration, type EnvSnapshot, EventBus, type EvidenceGap, type EvidenceItem, type EvidenceJoinKey, type EvidenceLane, type EvidenceQuery, type EvidenceRef, type EvidenceSourceDescriptor, type EvidenceSourceResult, FUSION_SCHEMA_VERSION, type FlagBugOptions, type GitHostClient, type GitHostRef, HttpTransport, type Hypothesis, type HypothesisKind, type InputValueRedactionOptions, type IntentSignal, type InteractionElementDescriptor, type InteractionElementDescriptorFactory, type OutboundCorrelation, PRESET_FULL, PRESET_LIGHT, PRESET_PASSIVE, type PayloadSummary, type PersistedSession, REDACTED_STORAGE_KEY, REDACTED_VALUE, type RageClickOptions, type RankedBundle, type RedactionAction, type RedactionField, type RedactionMetadata, type RedactionResult, type RetryStormOptions, RingBuffer, STACK_IDS, type SessionStore, type Signal, type SignalDetector, type SlowResponseOptions, type Stack, type StoredValueRedactionOptions, type Symptom, type TargetDescriptor, type TargetDescriptorResolver, type W3CTraceContext, W3C_TRACEPARENT_HEADER, WebTargetDescriptorResolver, abandonedFlowDetector, assembleBundle, attachRedactionMetadata, buildEnvDelta, buildEnvSnapshot, canInjectCorrelationHeaders, computeElementPath, computeElementSignature, createAutoFlagController, createCrumbtrailRequestHeaders, createWebSessionStore, environmentCollector, errorDetector, errorSignature, formatTraceparent, generateRequestId, generateSpanId, generateTraceContext, generateTraceId, hashString, inferIntent, mergeRedactionMetadata, parseTraceparent, rageClickDetector, redactCookieMap, redactCookieName, redactCookieValue, redactHeaders, redactInputValue, redactNetworkTextBody, redactStorageKey, redactStoredValue, redactTokenLikeString, redactUrl, redactUrlsInText, redactValue, resolveOutboundCorrelation, retryStormDetector, slowResponseDetector, summarizeBinaryPayload, summarizeOmittedPayload, webTargetDescriptorResolver };
+export { type AbandonedFlowOptions, type AddBugEventOptions, type AssembleBundleInput, type AutoFlagController, type AutoFlagOptions, BROWSER_REDACTION_POLICY, type BodyRedactionOptions, type BodyRedactionResult, type BugEvent, type BugReport, CRUMBTRAIL_EVENT_KINDS, CRUMBTRAIL_REQUEST_HEADER, CRUMBTRAIL_REQUEST_HEADER_LOWER, CRUMBTRAIL_REQUEST_ID_MAX_LENGTH, CRUMBTRAIL_SCHEMA_VERSION, CRUMBTRAIL_SESSION_HEADER, CRUMBTRAIL_SESSION_HEADER_LOWER, type CaptureDirective, type CollectorCleanup, type CollectorContext, type CommitInfo, type ContextCompleteness, Crumbtrail, type CrumbtrailCapabilities, type CrumbtrailConfig, type CrumbtrailPlatform, type CrumbtrailPreset, type CrumbtrailSdkDescriptor, type CrumbtrailTransport, DB_DIFF_BULK_EVENT_KIND, DB_DIFF_EVENT_KIND, DB_READ_BULK_EVENT_KIND, DB_READ_EVENT_KIND, DEFAULT_CONFIG, DEFAULT_SESSION_STORAGE_KEY, type DbDiffBulkEventData, type DbDiffEventData, type DbDiffOp, type DbEngine, type DbReadBulkEventData, type DbReadEventData, EVIDENCE_SCHEMA_VERSION, EVIDENCE_SOURCE_SCHEMA_VERSION, type ElementSignature, type EnvDeclaration, type EnvSnapshot, type Escalation, EventBus, type EvidenceGap, type EvidenceItem, type EvidenceJoinKey, type EvidenceLane, type EvidenceQuery, type EvidenceRef, type EvidenceSourceDescriptor, type EvidenceSourceResult, FUSION_SCHEMA_VERSION, type FlagBugOptions, type GitHostClient, type GitHostRef, HttpTransport, type Hypothesis, type HypothesisKind, type InputValueRedactionOptions, type IntentSignal, type InteractionElementDescriptor, type InteractionElementDescriptorFactory, type Located, type OutboundCorrelation, PRESET_FULL, PRESET_LIGHT, PRESET_PASSIVE, type PayloadSummary, type PersistedSession, REDACTED_STORAGE_KEY, REDACTED_VALUE, type RageClickOptions, type RankedBundle, type RedactionAction, type RedactionField, type RedactionMetadata, type RedactionResult, type RetryStormOptions, RingBuffer, STACK_IDS, type SessionStore, type Signal, type SignalDetector, type SlowResponseOptions, type Stack, type StoredValueRedactionOptions, type Symptom, type TargetDescriptor, type TargetDescriptorResolver, type Verification, type W3CTraceContext, W3C_TRACEPARENT_HEADER, WebTargetDescriptorResolver, abandonedFlowDetector, assembleBundle, attachRedactionMetadata, buildEnvDelta, buildEnvSnapshot, canInjectCorrelationHeaders, computeElementPath, computeElementSignature, createAutoFlagController, createCrumbtrailRequestHeaders, createWebSessionStore, environmentCollector, errorDetector, errorSignature, formatTraceparent, generateRequestId, generateSpanId, generateTraceContext, generateTraceId, hashString, inferIntent, mergeRedactionMetadata, parseTraceparent, rageClickDetector, redactCookieMap, redactCookieName, redactCookieValue, redactHeaders, redactInputValue, redactNetworkTextBody, redactStorageKey, redactStoredValue, redactTokenLikeString, redactUrl, redactUrlsInText, redactValue, resolveOutboundCorrelation, retryStormDetector, slowResponseDetector, summarizeBinaryPayload, summarizeOmittedPayload, webTargetDescriptorResolver };

package/dist/index.d.ts

@@ -831,6 +831,76 @@ interface Hypothesis {
     rationale: string;
     /** EvidenceItem.id values backing this hypothesis. */
     evidenceIds: string[];
+    /**
+     * Advisory, additive: concrete observations that would confirm a fix for
+     * THIS hypothesis worked. Emitted only for non-inconclusive hypotheses whose
+     * cited evidence carries a concrete anchor (signature / requestId /
+     * table+pk); absent otherwise. Sparse-and-concrete by design — never vacuous
+     * prose like "verify the bug is gone". See {@link Verification}.
+     */
+    verification?: Verification[];
+}
+/**
+ * A concrete, post-fix observation that would confirm a hypothesis's fix
+ * worked. `observation` always names a concrete signal (an error signature, a
+ * request id, or a table + primary key) — the derivation emits nothing when it
+ * cannot anchor to one, so an emitted verification is never a vacuous
+ * restatement.
+ */
+interface Verification {
+    /** Names a concrete signal — signature, request id, or table/pk. */
+    observation: string;
+    /** EvidenceItem.id values this observation is anchored to. */
+    evidenceIds: string[];
+    how: "session" | "request" | "db";
+}
+/**
+ * Where the incident was located, when a locate ran. Advisory and optional
+ * (absent for explicit baseline/current comparison bundles that never locate).
+ * Shape shared with the node locate engine's `LocateMatch` and War-game 02's
+ * deterministic token join — `method` distinguishes the two so 02 can populate
+ * "token" without a schema change (War-game 02 Fork C: one definition, reused).
+ */
+interface Located {
+    outcome: "matched" | "inconclusive";
+    /** 0..1 locate confidence. */
+    confidence: number;
+    /**
+     * How the incident was located. "fuzzy" = the scored locate engine;
+     * "token" = a deterministic token join (War-game 02). Absent when a caller
+     * supplies neither.
+     */
+    method?: "fuzzy" | "token";
+    /** The matched session, present ONLY when outcome === "matched". Never fabricated. */
+    sessionId?: string;
+    reasons?: string[];
+}
+/**
+ * Bundle-level answer to "how much context do we actually have here?" — the
+ * LOW_CONTEXT signal. Derived purely from the assembled bundle (evidence
+ * lanes, gaps, hypothesis strength, locate confidence). Advisory: it NEVER
+ * gates or blocks bundle emission. `reasons` is the load-bearing part; `score`
+ * and `level` summarize it.
+ */
+interface ContextCompleteness {
+    /** 0..1; higher = richer, more actionable context. */
+    score: number;
+    level: "high" | "medium" | "low";
+    /** Human-legible drivers: missing lanes, thin evidence, inconclusive locate. */
+    reasons: string[];
+}
+/**
+ * Consumer-side advisory: what the CONSUMING agent should do when context is
+ * thin. Distinct from {@link EvidenceGap} (capture-side: what evidence is
+ * missing) — escalation is what to do about it. Always present; `recommended`
+ * is false with an empty `when` when context is adequate. Never gates the
+ * bundle (VISION: advisory, never a boolean verdict on the bug itself).
+ */
+interface Escalation {
+    recommended: boolean;
+    /** Conditions phrased for the consuming agent, e.g. "if you cannot reproduce
+     *  via the anchored request, stop and request human triage". */
+    when: string[];
 }
 interface EvidenceGap {
     lane: EvidenceLane;
@@ -871,12 +941,22 @@ interface RankedBundle {
     gaps: EvidenceGap[];
     /** Advisory-only: suggested capture escalations when evidence is thin. */
     directives: CaptureDirective[];
+    /** How much actionable context this bundle carries. Advisory, never gates. */
+    contextCompleteness: ContextCompleteness;
+    /** What the consuming agent should do when context is thin. Advisory. */
+    escalation: Escalation;
+    /** Where the incident was located, when a locate ran. Absent otherwise. */
+    located?: Located;
 }
 interface AssembleBundleInput {
     symptom: Symptom;
     evidence: EvidenceItem[];
     intent: IntentSignal[];
     gaps?: EvidenceGap[];
+    /** The locate decision, when one ran (auto-locate / token join). Threaded
+     *  onto the bundle as {@link RankedBundle.located} and folded into
+     *  completeness. Omit for explicit baseline/current comparison bundles. */
+    located?: Located;
 }
 /**
  * Compose the RankedBundle: rank the complete evidence set (nothing dropped),
@@ -971,4 +1051,4 @@ type Stack = "nextjs" | "react" | "vue" | "svelte" | "vite" | "express" | "hono"
 /** Stable ordered id list, handy for iterating or building pickers. */
 declare const STACK_IDS: readonly Stack[];
 
-export { type AbandonedFlowOptions, type AddBugEventOptions, type AssembleBundleInput, type AutoFlagController, type AutoFlagOptions, BROWSER_REDACTION_POLICY, type BodyRedactionOptions, type BodyRedactionResult, type BugEvent, type BugReport, CRUMBTRAIL_EVENT_KINDS, CRUMBTRAIL_REQUEST_HEADER, CRUMBTRAIL_REQUEST_HEADER_LOWER, CRUMBTRAIL_REQUEST_ID_MAX_LENGTH, CRUMBTRAIL_SCHEMA_VERSION, CRUMBTRAIL_SESSION_HEADER, CRUMBTRAIL_SESSION_HEADER_LOWER, type CaptureDirective, type CollectorCleanup, type CollectorContext, type CommitInfo, Crumbtrail, type CrumbtrailCapabilities, type CrumbtrailConfig, type CrumbtrailPlatform, type CrumbtrailPreset, type CrumbtrailSdkDescriptor, type CrumbtrailTransport, DB_DIFF_BULK_EVENT_KIND, DB_DIFF_EVENT_KIND, DB_READ_BULK_EVENT_KIND, DB_READ_EVENT_KIND, DEFAULT_CONFIG, DEFAULT_SESSION_STORAGE_KEY, type DbDiffBulkEventData, type DbDiffEventData, type DbDiffOp, type DbEngine, type DbReadBulkEventData, type DbReadEventData, EVIDENCE_SCHEMA_VERSION, EVIDENCE_SOURCE_SCHEMA_VERSION, type ElementSignature, type EnvDeclaration, type EnvSnapshot, EventBus, type EvidenceGap, type EvidenceItem, type EvidenceJoinKey, type EvidenceLane, type EvidenceQuery, type EvidenceRef, type EvidenceSourceDescriptor, type EvidenceSourceResult, FUSION_SCHEMA_VERSION, type FlagBugOptions, type GitHostClient, type GitHostRef, HttpTransport, type Hypothesis, type HypothesisKind, type InputValueRedactionOptions, type IntentSignal, type InteractionElementDescriptor, type InteractionElementDescriptorFactory, type OutboundCorrelation, PRESET_FULL, PRESET_LIGHT, PRESET_PASSIVE, type PayloadSummary, type PersistedSession, REDACTED_STORAGE_KEY, REDACTED_VALUE, type RageClickOptions, type RankedBundle, type RedactionAction, type RedactionField, type RedactionMetadata, type RedactionResult, type RetryStormOptions, RingBuffer, STACK_IDS, type SessionStore, type Signal, type SignalDetector, type SlowResponseOptions, type Stack, type StoredValueRedactionOptions, type Symptom, type TargetDescriptor, type TargetDescriptorResolver, type W3CTraceContext, W3C_TRACEPARENT_HEADER, WebTargetDescriptorResolver, abandonedFlowDetector, assembleBundle, attachRedactionMetadata, buildEnvDelta, buildEnvSnapshot, canInjectCorrelationHeaders, computeElementPath, computeElementSignature, createAutoFlagController, createCrumbtrailRequestHeaders, createWebSessionStore, environmentCollector, errorDetector, errorSignature, formatTraceparent, generateRequestId, generateSpanId, generateTraceContext, generateTraceId, hashString, inferIntent, mergeRedactionMetadata, parseTraceparent, rageClickDetector, redactCookieMap, redactCookieName, redactCookieValue, redactHeaders, redactInputValue, redactNetworkTextBody, redactStorageKey, redactStoredValue, redactTokenLikeString, redactUrl, redactUrlsInText, redactValue, resolveOutboundCorrelation, retryStormDetector, slowResponseDetector, summarizeBinaryPayload, summarizeOmittedPayload, webTargetDescriptorResolver };
+export { type AbandonedFlowOptions, type AddBugEventOptions, type AssembleBundleInput, type AutoFlagController, type AutoFlagOptions, BROWSER_REDACTION_POLICY, type BodyRedactionOptions, type BodyRedactionResult, type BugEvent, type BugReport, CRUMBTRAIL_EVENT_KINDS, CRUMBTRAIL_REQUEST_HEADER, CRUMBTRAIL_REQUEST_HEADER_LOWER, CRUMBTRAIL_REQUEST_ID_MAX_LENGTH, CRUMBTRAIL_SCHEMA_VERSION, CRUMBTRAIL_SESSION_HEADER, CRUMBTRAIL_SESSION_HEADER_LOWER, type CaptureDirective, type CollectorCleanup, type CollectorContext, type CommitInfo, type ContextCompleteness, Crumbtrail, type CrumbtrailCapabilities, type CrumbtrailConfig, type CrumbtrailPlatform, type CrumbtrailPreset, type CrumbtrailSdkDescriptor, type CrumbtrailTransport, DB_DIFF_BULK_EVENT_KIND, DB_DIFF_EVENT_KIND, DB_READ_BULK_EVENT_KIND, DB_READ_EVENT_KIND, DEFAULT_CONFIG, DEFAULT_SESSION_STORAGE_KEY, type DbDiffBulkEventData, type DbDiffEventData, type DbDiffOp, type DbEngine, type DbReadBulkEventData, type DbReadEventData, EVIDENCE_SCHEMA_VERSION, EVIDENCE_SOURCE_SCHEMA_VERSION, type ElementSignature, type EnvDeclaration, type EnvSnapshot, type Escalation, EventBus, type EvidenceGap, type EvidenceItem, type EvidenceJoinKey, type EvidenceLane, type EvidenceQuery, type EvidenceRef, type EvidenceSourceDescriptor, type EvidenceSourceResult, FUSION_SCHEMA_VERSION, type FlagBugOptions, type GitHostClient, type GitHostRef, HttpTransport, type Hypothesis, type HypothesisKind, type InputValueRedactionOptions, type IntentSignal, type InteractionElementDescriptor, type InteractionElementDescriptorFactory, type Located, type OutboundCorrelation, PRESET_FULL, PRESET_LIGHT, PRESET_PASSIVE, type PayloadSummary, type PersistedSession, REDACTED_STORAGE_KEY, REDACTED_VALUE, type RageClickOptions, type RankedBundle, type RedactionAction, type RedactionField, type RedactionMetadata, type RedactionResult, type RetryStormOptions, RingBuffer, STACK_IDS, type SessionStore, type Signal, type SignalDetector, type SlowResponseOptions, type Stack, type StoredValueRedactionOptions, type Symptom, type TargetDescriptor, type TargetDescriptorResolver, type Verification, type W3CTraceContext, W3C_TRACEPARENT_HEADER, WebTargetDescriptorResolver, abandonedFlowDetector, assembleBundle, attachRedactionMetadata, buildEnvDelta, buildEnvSnapshot, canInjectCorrelationHeaders, computeElementPath, computeElementSignature, createAutoFlagController, createCrumbtrailRequestHeaders, createWebSessionStore, environmentCollector, errorDetector, errorSignature, formatTraceparent, generateRequestId, generateSpanId, generateTraceContext, generateTraceId, hashString, inferIntent, mergeRedactionMetadata, parseTraceparent, rageClickDetector, redactCookieMap, redactCookieName, redactCookieValue, redactHeaders, redactInputValue, redactNetworkTextBody, redactStorageKey, redactStoredValue, redactTokenLikeString, redactUrl, redactUrlsInText, redactValue, resolveOutboundCorrelation, retryStormDetector, slowResponseDetector, summarizeBinaryPayload, summarizeOmittedPayload, webTargetDescriptorResolver };

package/dist/index.js

@@ -4319,21 +4319,139 @@ function inferIntent(evidence, commits) {
 var FUSION_SCHEMA_VERSION = "fusion.v1";
 function assembleBundle(input) {
   const evidence = rankEvidence(input.symptom, input.evidence);
-  const hypotheses = classifyHypotheses(
+  const classified = classifyHypotheses(
     input.symptom,
     input.evidence,
     input.intent
   );
   const gaps = input.gaps ?? [];
+  const located = input.located;
+  const hypotheses = classified.map((hypothesis) => {
+    const verification = deriveVerification(hypothesis, evidence);
+    return verification.length > 0 ? { ...hypothesis, verification } : hypothesis;
+  });
+  const contextCompleteness = deriveContextCompleteness(
+    evidence,
+    gaps,
+    hypotheses,
+    located
+  );
+  const escalation = deriveEscalation(contextCompleteness, hypotheses);
   return {
     schemaVersion: FUSION_SCHEMA_VERSION,
     symptom: input.symptom,
     evidence,
     opinion: { stance: "advisory", hypotheses },
     gaps,
-    directives: suggestCaptureDirectives(input.symptom, input.evidence, gaps)
+    directives: suggestCaptureDirectives(input.symptom, input.evidence, gaps),
+    contextCompleteness,
+    escalation,
+    ...located ? { located } : {}
   };
 }
+function clamp01(value) {
+  if (Number.isNaN(value)) return 0;
+  return Math.max(0, Math.min(1, value));
+}
+var COMPLETENESS_LANES = [
+  "network",
+  "db",
+  "flow",
+  "browser",
+  "env"
+];
+function deriveContextCompleteness(evidence, gaps, hypotheses, located) {
+  const lanesPresent = new Set(evidence.map((item) => item.lane));
+  const informativePresent = COMPLETENESS_LANES.filter(
+    (lane) => lanesPresent.has(lane)
+  );
+  const breadth = Math.min(1, informativePresent.length / 3);
+  const volume = Math.min(1, evidence.length / 5);
+  const top = hypotheses[0];
+  const hypothesisStrength = !top || top.kind === "inconclusive" ? 0 : top.confidence;
+  let score = 0.4 * breadth + 0.25 * volume + 0.35 * hypothesisStrength;
+  if (located) {
+    score = located.outcome === "matched" ? 0.85 * score + 0.15 * clamp01(located.confidence) : score * 0.6;
+  }
+  const hardGaps = gaps.filter((gap) => gap.kind === "source-unavailable").length;
+  const softGaps = gaps.length - hardGaps;
+  const gapPenalty = Math.min(0.5, softGaps * 0.1 + hardGaps * 0.3);
+  score = clamp01(score - gapPenalty);
+  const level = score < 0.34 ? "low" : score < 0.67 ? "medium" : "high";
+  const reasons = [];
+  const missingLanes = COMPLETENESS_LANES.filter(
+    (lane) => !lanesPresent.has(lane)
+  );
+  if (informativePresent.length === 0) {
+    reasons.push("no network/db/flow/browser/env evidence captured");
+  } else if (missingLanes.length > 0) {
+    reasons.push(`missing evidence lanes: ${missingLanes.join(", ")}`);
+  }
+  if (evidence.length > 0 && evidence.length < 3) {
+    reasons.push(`thin evidence (${evidence.length} item(s))`);
+  }
+  if (hardGaps > 0) reasons.push(`source unavailable for ${hardGaps} lane(s)`);
+  if (softGaps > 0) reasons.push(`${softGaps} evidence gap(s)`);
+  if (located?.outcome === "inconclusive") {
+    reasons.push("incident location inconclusive");
+  }
+  if (!top || top.kind === "inconclusive") {
+    reasons.push("no distinguishing hypothesis");
+  }
+  return { score, level, reasons };
+}
+function pkString(pk) {
+  return Object.keys(pk).sort().map((key) => `${key}=${String(pk[key])}`).join(", ");
+}
+function deriveVerification(hypothesis, evidence) {
+  if (hypothesis.kind === "inconclusive") return [];
+  const cited = new Set(hypothesis.evidenceIds);
+  const out = [];
+  for (const item of evidence) {
+    if (!cited.has(item.id)) continue;
+    const ref = item.ref;
+    if (item.lane === "db" && ref.table && ref.pk && Object.keys(ref.pk).length > 0) {
+      out.push({
+        observation: `row in ${ref.table} (${pkString(ref.pk)}) matches the intended post-fix state`,
+        evidenceIds: [item.id],
+        how: "db"
+      });
+    } else if (ref.requestId) {
+      const sigPart = ref.sig ? ` for signature ${ref.sig}` : "";
+      out.push({
+        observation: `request ${ref.requestId} succeeds${sigPart} on a fresh run (no error response)`,
+        evidenceIds: [item.id],
+        how: "request"
+      });
+    } else if (ref.sig) {
+      out.push({
+        observation: `error signature ${ref.sig} no longer appears in a fresh session over the same route`,
+        evidenceIds: [item.id],
+        how: "session"
+      });
+    }
+  }
+  return out;
+}
+function deriveEscalation(completeness, hypotheses) {
+  const allInconclusive = hypotheses.length > 0 && hypotheses.every((hypothesis) => hypothesis.kind === "inconclusive");
+  const recommended = completeness.level === "low" || allInconclusive;
+  if (!recommended) return { recommended: false, when: [] };
+  const when = [
+    "if you cannot reproduce the symptom via the anchored request or session, stop and request human triage \u2014 do not widen the search"
+  ];
+  if (completeness.level === "low") {
+    when.push(
+      "context is thin: confirm the missing evidence lanes before acting on the top hypothesis"
+    );
+  }
+  if (allInconclusive) {
+    when.push(
+      "no hypothesis is distinguished; treat the listed causes as equally unproven"
+    );
+  }
+  return { recommended, when };
+}
 var LANE_PRIOR = {
   db: 0.2,
   network: 0.2,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crumbtrail-core",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Browser SDK for capturing Crumbtrail sessions and sending evidence to a local Crumbtrail server.",
   "license": "MIT",
   "repository": {