crumbtrail-core 0.1.0 → 0.2.1

package/dist/index.cjs

@@ -265,6 +265,7 @@ __export(index_exports, {
   REDACTED_STORAGE_KEY: () => REDACTED_STORAGE_KEY,
   REDACTED_VALUE: () => REDACTED_VALUE,
   RingBuffer: () => RingBuffer,
+  STACK_IDS: () => STACK_IDS,
   W3C_TRACEPARENT_HEADER: () => W3C_TRACEPARENT_HEADER,
   WebTargetDescriptorResolver: () => WebTargetDescriptorResolver,
   abandonedFlowDetector: () => abandonedFlowDetector,
@@ -4633,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,
@@ -4792,6 +4911,28 @@ function suggestCaptureDirectives(symptom, evidence, gaps) {
 
 // src/evidence-source.ts
 var EVIDENCE_SOURCE_SCHEMA_VERSION = "evidence-source.v1";
+
+// src/stacks.ts
+var STACK_IDS = [
+  "nextjs",
+  "react",
+  "vue",
+  "svelte",
+  "vite",
+  "express",
+  "hono",
+  "node",
+  "django",
+  "flask",
+  "fastapi",
+  "dotnet",
+  "go",
+  "rails",
+  "postgres",
+  "grafana",
+  "loki",
+  "docker"
+];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BROWSER_REDACTION_POLICY,
@@ -4820,6 +4961,7 @@ var EVIDENCE_SOURCE_SCHEMA_VERSION = "evidence-source.v1";
   REDACTED_STORAGE_KEY,
   REDACTED_VALUE,
   RingBuffer,
+  STACK_IDS,
   W3C_TRACEPARENT_HEADER,
   WebTargetDescriptorResolver,
   abandonedFlowDetector,

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),
@@ -957,4 +1037,18 @@ interface EvidenceSourceResult {
     };
 }
 
-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, type SessionStore, type Signal, type SignalDetector, type SlowResponseOptions, 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 };
+/**
+ * The stack vocabulary — the set of frameworks and runtimes Crumbtrail knows how
+ * to instrument.
+ *
+ * This lives in core because it is shared domain language, not presentation: the
+ * CLI uses it to pick an install recipe, install-shared uses it to build agent
+ * prompts, and the design system uses it to pick a brand mark. Core is the only
+ * package all three can depend on without dragging React into a Node CLI.
+ */
+/** The exact set of stacks with first-class support. */
+type Stack = "nextjs" | "react" | "vue" | "svelte" | "vite" | "express" | "hono" | "node" | "django" | "flask" | "fastapi" | "dotnet" | "go" | "rails" | "postgres" | "grafana" | "loki" | "docker";
+/** 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, 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),
@@ -957,4 +1037,18 @@ interface EvidenceSourceResult {
     };
 }
 
-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, type SessionStore, type Signal, type SignalDetector, type SlowResponseOptions, 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 };
+/**
+ * The stack vocabulary — the set of frameworks and runtimes Crumbtrail knows how
+ * to instrument.
+ *
+ * This lives in core because it is shared domain language, not presentation: the
+ * CLI uses it to pick an install recipe, install-shared uses it to build agent
+ * prompts, and the design system uses it to pick a brand mark. Core is the only
+ * package all three can depend on without dragging React into a Node CLI.
+ */
+/** The exact set of stacks with first-class support. */
+type Stack = "nextjs" | "react" | "vue" | "svelte" | "vite" | "express" | "hono" | "node" | "django" | "flask" | "fastapi" | "dotnet" | "go" | "rails" | "postgres" | "grafana" | "loki" | "docker";
+/** 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, 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,
@@ -4478,6 +4596,28 @@ function suggestCaptureDirectives(symptom, evidence, gaps) {
 
 // src/evidence-source.ts
 var EVIDENCE_SOURCE_SCHEMA_VERSION = "evidence-source.v1";
+
+// src/stacks.ts
+var STACK_IDS = [
+  "nextjs",
+  "react",
+  "vue",
+  "svelte",
+  "vite",
+  "express",
+  "hono",
+  "node",
+  "django",
+  "flask",
+  "fastapi",
+  "dotnet",
+  "go",
+  "rails",
+  "postgres",
+  "grafana",
+  "loki",
+  "docker"
+];
 export {
   BROWSER_REDACTION_POLICY,
   CRUMBTRAIL_EVENT_KINDS,
@@ -4505,6 +4645,7 @@ export {
   REDACTED_STORAGE_KEY,
   REDACTED_VALUE,
   RingBuffer,
+  STACK_IDS,
   W3C_TRACEPARENT_HEADER,
   WebTargetDescriptorResolver,
   abandonedFlowDetector,

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "crumbtrail-core",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Browser SDK for capturing Crumbtrail sessions and sending evidence to a local Crumbtrail server.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/oshabana/crumbtrail.git",
+    "url": "git+https://github.com/crumbtrail-dev/crumbtrail-js.git",
     "directory": "packages/core"
   },
   "keywords": [
@@ -33,6 +33,10 @@
   "publishConfig": {
     "access": "public"
   },
+  "homepage": "https://github.com/crumbtrail-dev/crumbtrail-js/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/crumbtrail-dev/crumbtrail-js/issues"
+  },
   "scripts": {
     "build": "tsup",
     "test": "vitest run",