agent-inspect 6.14.1 → 6.15.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 6.15.0
+
+### Minor Changes
+
+- e70e3be: LangGraph fidelity classes A–E and persisted-trace developer APIs: relationship conformance, scaffolding diagnostics, openTraceFile/Directory/Text, TraceFacts/TraceContract conveniences, and stable AI\_\* remediation codes. No schema break; no new packages; no default network.
+
+## 6.14.2
+
+### Patch Changes
+
+- 4850b62: Swarm relationship and safety precision: fix self-parent capture/ordering, normalize legacy self-edges, cycle-safe trees, and stop treating token-configuration fields as credentials.
+
 ## 6.14.1
 
 ### Patch Changes
@@ -8,9 +20,9 @@
 
 ## Unreleased
 
-### Patch
+### Minor
 
-- (pending 6.14.1) Public positioning, documentation truth, and AI discoverability refresh.
+- LangGraph fidelity classes A–E and persisted-trace developer APIs (6.15.0): relationship conformance corpus, ambiguous scaffolding diagnostics, `openTraceFile` / `openTraceDirectory` / `openTraceText`, `buildTraceFacts(TraceReadResult)`, `evaluateTraceContractRead`, stable `AI_*` programmatic diagnostics with remediation, ESM/CJS quickstarts, and A–E cross-surface semantic parity. No schema break; no new packages; no default network.
 
 ## 6.14.0
 

package/README.md

@@ -157,7 +157,7 @@ Details: [Safe sharing](https://github.com/rajudandigam/agent-inspect/blob/main/
 
 ## Project status
 
-**Current release:** **6.14.1** · schema **1.0** · Node.js **≥ 20** · **MIT** · **actively maintained** (eighteen linked npm packages).
+**Current release:** **6.14.2** · schema **1.0** · Node.js **≥ 20** · **MIT** · **actively maintained** (eighteen linked npm packages).
 
 The 6.14 line is actively maintained for correctness, compatibility, documentation, security, and framework evolution.
 

package/docs/API.md

@@ -487,8 +487,12 @@ import {
   detectTraceFormat,
   openInferenceJsonReader,
   openTrace,
+  openTraceDirectory,
+  openTraceFile,
+  openTraceText,
   otlpJsonReader,
   readTrace,
+  formatProgrammaticDiagnostic,
 } from "agent-inspect/readers";
 import type { TraceReader } from "agent-inspect/readers";
 ```
@@ -498,12 +502,14 @@ import type { TraceReader } from "agent-inspect/readers";
 - **`detectTraceFormat(input, { readers?, format? })`**: deterministic, conservative format detection. Explicit `format` acts as an override only when a matching reader is registered.
 - **`readTrace(input, { readers?, format? })`**: detects a reader and returns `TraceReadResult`; unsupported or ambiguous input throws `TraceReadError`.
 - **`openTrace(input, options?)`**: alias for `readTrace()` and the API path used by the universal `agent-inspect open` command.
+- **`openTraceFile(path)` / `openTraceDirectory(path)` / `openTraceText(content)`**: additive conveniences that wrap structured `TraceInput` (prefer these over bare path strings).
+- **`assertTraceInput` / `formatProgrammaticDiagnostic`**: runtime input guard and stable `AI_*` message helpers (lowercase `TraceReadError.code` values remain published).
 - **`agentInspectJsonlReader`**: built-in local AgentInspect JSONL reader for v0.1, v0.2, and mixed files/directories.
 - **`openInferenceJsonReader`**: local OpenInference JSON compatibility reader. Prompt/output-like attributes are summarized and bounded rather than stored as raw content.
 - **`otlpJsonReader`**: local OTLP/HTTP JSON trace payload reader. Resource, scope, span, status, event, and parent metadata are preserved where possible with warnings for unsupported fields.
 - **`DEFAULT_TRACE_READERS`**: ordered built-in reader registry used when no custom `readers` array is supplied.
 
-The reader contract does not silently accept arbitrary JSON and does not add OTel SDK, database, hosted ingestion, or network upload dependencies.
+The reader contract does not silently accept arbitrary JSON and does not add OTel SDK, database, hosted ingestion, or network upload dependencies. See also [PROGRAMMATIC-TRACE-ANALYSIS.md](./PROGRAMMATIC-TRACE-ANALYSIS.md).
 
 ## 21. Experimental Checks
 
@@ -512,11 +518,21 @@ The reader contract does not silently accept arbitrary JSON and does not add OTe
 Import from `agent-inspect/checks`:
 
 ```ts
-import { runTraceChecks } from "agent-inspect/checks";
-import type { TraceCheckRule, TraceCheckResult } from "agent-inspect/checks";
+import {
+  runTraceChecks,
+  buildTraceFacts,
+  defineTraceContract,
+  evaluateTraceContract,
+  evaluateTraceContractRead,
+  formatProgrammaticDiagnostic,
+} from "agent-inspect/checks";
+import type { TraceCheckRule, TraceCheckResult, TraceFacts } from "agent-inspect/checks";
 ```
 
 - **`runTraceChecks({ read }, { rules?, select?, runId? })`**: executes provided rules against a `TraceReadResult` from `agent-inspect/readers`.
+- **`buildTraceFacts(read | events)`**: experimental TraceFacts over logical projection; accepts `TraceReadResult` or normalized `PersistedInspectEvent[]`.
+- **`defineTraceContract` / `evaluateTraceContract` / `evaluateTraceContractRead`**: experimental contract helpers; `evaluateTraceContractRead(read, contract)` wraps `{ read }`.
+- **`formatProgrammaticDiagnostic` / `PROGRAMMATIC_DIAGNOSTIC_SPECS`**: stable `AI_*` codes with remediation hints.
 - **Built-in rule factories**: run, tool, LLM, structure, retrieval, guardrail, decision, safety, and baseline helpers including `createRunStatusRule`, `createToolUsageRule`, `createLlmUsageRule`, `createStructureOrphanRule`, `createStructureCycleRule`, `createStructureRelationshipRule`, `createRetrievalRule`, `createGuardrailRule`, `createDecisionRule`, `createSafetyRawContentRule`, `createSafetySecretPatternRule`, and `createBaselineRegressionRule`.
 - **`TraceCheckRule`**: synchronous pure rule contract.
 - **`TraceCheckResult`**: deterministic aggregate result with findings, evidence, summary counts, and execution diagnostics.

package/docs/KNOWN-ISSUES.md

@@ -33,8 +33,9 @@ AgentInspect is **local-first** and **CLI-first**. These behaviors are intention
 - **LangGraph support** is currently a documented boundary through `@agent-inspect/langchain`, not a dedicated package.
 - **LangChain adapter** captures **metadata-oriented** signals by default; it does not replace full framework observability.
 - **LangChain `stream: true`** records chunk counts and timing only — not a full token replay. Per-token JSONL events are not emitted.
+- **Deep swarm / nested RunnableSequence (6.14.2+):** capture resolves parents before registering child indexes and rejects `parentId === stepId`. Legacy traces that still contain self-parent edges are normalized in logical projection (`AI_LOGICAL_SELF_PARENT_REMOVED`) and rendered with visibility-first, cycle-safe trees so nested LLM/tool steps remain visible.
 - **Correlation metadata** (`correlationId`, `requestId`, `decisionId`, `groupId`) is written on `run_started` but **CLI list/view does not filter by correlation fields** yet.
-- **Built-in check/contract semantics (6.12.2+)** use an additive `logicalEvents` projection that pairs v0.1 start/complete rows. Custom rules that only read raw `context.events` still see bridged `running` TOOL starts and separate LOGIC completions—opt into `logicalEvents` for lifecycle-aware matching. Formal `TraceFacts` promotion is planned for 6.13.
+- **Built-in check/contract semantics (6.12.2+)** use an additive `logicalEvents` projection that pairs v0.1 start/complete rows. Custom rules that only read raw `context.events` still see bridged `running` TOOL starts and separate LOGIC completions—opt into `logicalEvents` for lifecycle-aware matching. Formal `TraceFacts` promotion shipped experimentally in 6.13.
 
 ## Structured log parsing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "6.14.1",
+  "version": "6.15.0",
   "license": "MIT",
   "type": "module",
   "description": "Local evidence debugger and trajectory-test toolkit for TypeScript AI agents — execution trees, TraceContract checks, Evidence v2, and read-only MCP",
@@ -234,7 +234,7 @@
     "test:all": "pnpm run typecheck && pnpm run linked-versions:check && pnpm run build && pnpm run test && pnpm run size",
     "prepublish:checks": "pnpm run typecheck && pnpm run test && pnpm run test:coverage && pnpm run build && pnpm run fixtures:check && pnpm run recipes:check && pnpm run size && pnpm run linked-versions:check && pnpm run pack:smoke",
     "pack:dry-run": "pnpm run build && npm pack --dry-run",
-    "pack:smoke": "pnpm run build && node scripts/package-smoke.mjs && node scripts/packed-quickstart-e2e.mjs && node scripts/packed-semantic-loop-e2e.mjs",
+    "pack:smoke": "pnpm run build && node scripts/package-smoke.mjs && node scripts/packed-quickstart-e2e.mjs && node scripts/packed-semantic-loop-e2e.mjs && node scripts/packed-swarm-loop-e2e.mjs",
     "linked-versions:check": "node scripts/check-linked-versions.mjs",
     "docs:commands": "node scripts/validate-doc-commands.mjs",
     "docs:links": "node scripts/validate-doc-links.mjs",

package/packages/cli/dist/{chunk-MEO2Z3KE.mjs → chunk-LFSBMUCD.mjs}

@@ -5852,6 +5852,59 @@ function defaultSuiteConfigTemplate() {
   };
 }
 
+// packages/core/src/diagnostics/programmatic.ts
+var PROGRAMMATIC_DIAGNOSTIC_SPECS = Object.freeze({
+  AI_TRACE_INPUT_INVALID: {
+    code: "AI_TRACE_INPUT_INVALID",
+    summary: 'Expected { type: "file", path }, { type: "directory", path }, { type: "string", content }, { type: "buffer", content }, or { type: "stdin" }.',
+    remediation: "For a file path, use openTraceFile(path).",
+    relatedCodes: ["invalid_input"]
+  },
+  AI_TRACE_FORMAT_UNSUPPORTED: {
+    code: "AI_TRACE_FORMAT_UNSUPPORTED",
+    summary: "No trace reader could detect the input format.",
+    remediation: "Pass an AgentInspect JSONL file via openTraceFile, or set options.format to a registered reader.",
+    relatedCodes: ["unsupported_format"]
+  },
+  AI_TRACE_FORMAT_AMBIGUOUS: {
+    code: "AI_TRACE_FORMAT_AMBIGUOUS",
+    summary: "Multiple trace readers matched the input with equal confidence.",
+    remediation: "Set options.format explicitly to disambiguate the reader.",
+    relatedCodes: ["ambiguous_format"]
+  },
+  AI_TRACE_FACTS_INPUT_NOT_NORMALIZED: {
+    code: "AI_TRACE_FACTS_INPUT_NOT_NORMALIZED",
+    summary: "TraceFacts requires TraceReadResult or PersistedInspectEvent[].",
+    remediation: "Use openTraceFile() to normalize a JSONL trace first."
+  },
+  AI_TRACE_CONTRACT_RUN_SELECTION_REQUIRED: {
+    code: "AI_TRACE_CONTRACT_RUN_SELECTION_REQUIRED",
+    summary: "Multiple runs are available; select a run before executing checks.",
+    remediation: "Pass options.runId or TraceCheckInput.selectedRun.",
+    relatedCodes: ["AI_CHECK_RUN_SELECTION_REQUIRED"]
+  },
+  AI_TRACE_RELATIONSHIP_SELF_PARENT: {
+    code: "AI_TRACE_RELATIONSHIP_SELF_PARENT",
+    summary: "A parentId equals its own event/step id.",
+    remediation: "Reject at capture (AI_LANGGRAPH_SELF_PARENT_REJECTED) or drop via logical projection; do not invent replacement parents.",
+    relatedCodes: [
+      "AI_LANGGRAPH_SELF_PARENT_REJECTED",
+      "AI_LOGICAL_SELF_PARENT_REMOVED"
+    ]
+  },
+  AI_TRACE_RELATIONSHIP_CYCLE: {
+    code: "AI_TRACE_RELATIONSHIP_CYCLE",
+    summary: "Trace contains a parentId cycle.",
+    remediation: "Use visibility-first tree linking for legacy fixtures; prefer acyclic capture for new adapter output.",
+    relatedCodes: ["structure.cycle"]
+  }
+});
+function formatProgrammaticDiagnostic(code, detail) {
+  const spec = PROGRAMMATIC_DIAGNOSTIC_SPECS[code];
+  const summary = detail?.trim() ? detail.trim() : spec.summary;
+  return `${code}: ${summary} Remediation: ${spec.remediation}`;
+}
+
 // packages/core/src/checks/logical-events.ts
 function isRecord7(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -6047,6 +6100,26 @@ function projectLogicalEvents(events) {
       }
     }
     if (!remapped) {
+      if (originalParentId === event.eventId) {
+        diagnostics.push({
+          code: "AI_LOGICAL_SELF_PARENT_REMOVED",
+          message: formatProgrammaticDiagnostic(
+            "AI_TRACE_RELATIONSHIP_SELF_PARENT",
+            `Removed self-parent edge on ${event.eventId}.`
+          ),
+          eventIds: [event.eventId]
+        });
+        const { parentId: _drop, ...rest } = event;
+        normalized.push({
+          ...rest,
+          projection: {
+            ...event.projection,
+            parentNormalized: true,
+            originalParentId
+          }
+        });
+        continue;
+      }
       if (!logicalById.has(originalParentId) && !logicalByRawId.has(originalParentId)) {
         const mapping = event.attributes?.parentMapping;
         const unresolved = mapping === "unresolved" || event.attributes?.parentUnresolved === true || event.attributes?.unresolvedParent === true || // LangGraph/framework scaffolding sentinel labels are not event ids.
@@ -6062,6 +6135,26 @@ function projectLogicalEvents(events) {
       normalized.push(event);
       continue;
     }
+    if (nextParent === event.eventId) {
+      diagnostics.push({
+        code: "AI_LOGICAL_SELF_PARENT_REMOVED",
+        message: formatProgrammaticDiagnostic(
+          "AI_TRACE_RELATIONSHIP_SELF_PARENT",
+          `Removed self-parent edge on ${event.eventId} (was ${originalParentId}).`
+        ),
+        eventIds: [event.eventId]
+      });
+      const { parentId: _drop, ...rest } = event;
+      normalized.push({
+        ...rest,
+        projection: {
+          ...event.projection,
+          parentNormalized: true,
+          originalParentId
+        }
+      });
+      continue;
+    }
     diagnostics.push({
       code: "AI_LOGICAL_PARENT_REMAPPED",
       message: `Remapped parent ${originalParentId} \u2192 ${nextParent} for ${event.eventId}.`,
@@ -6134,6 +6227,76 @@ function summarizeSemanticParity(events) {
     diagnostics: projection.diagnostics
   };
 }
+formatProgrammaticDiagnostic(
+  "AI_TRACE_FACTS_INPUT_NOT_NORMALIZED"
+);
+
+// packages/core/src/safety/sensitive-key.ts
+function normalizeSensitiveKey(value) {
+  return value.toLowerCase().replace(/[^a-z0-9_]/g, "");
+}
+var NON_CREDENTIAL_TOKEN_CONFIG_KEYS = new Set(
+  [
+    "tokens",
+    "max_tokens",
+    "min_tokens",
+    "ls_max_tokens",
+    "token_count",
+    "token_limit",
+    "token_budget",
+    "input_tokens",
+    "output_tokens",
+    "total_tokens",
+    "cached_tokens",
+    "prompt_tokens",
+    "completion_tokens"
+  ].map(normalizeSensitiveKey)
+);
+var DEFAULT_CREDENTIAL_SENSITIVE_KEYS = [
+  "authorization",
+  "cookie",
+  "token",
+  "access_token",
+  "accesstoken",
+  "auth_token",
+  "authtoken",
+  "refresh_token",
+  "refreshtoken",
+  "id_token",
+  "idtoken",
+  "bearer_token",
+  "bearertoken",
+  "api_token",
+  "apitoken",
+  "apikey",
+  "api_key",
+  "password",
+  "secret",
+  "email"
+];
+function isTokenCredentialKey(normalized) {
+  if (NON_CREDENTIAL_TOKEN_CONFIG_KEYS.has(normalized)) return false;
+  if (normalized === "token") return true;
+  if (normalized.endsWith("tokens")) return false;
+  return normalized.endsWith("token");
+}
+function isCredentialSensitiveKey(key, sensitiveKeys = DEFAULT_CREDENTIAL_SENSITIVE_KEYS) {
+  if (!key) return false;
+  const normalized = normalizeSensitiveKey(key);
+  if (!normalized) return false;
+  if (NON_CREDENTIAL_TOKEN_CONFIG_KEYS.has(normalized)) return false;
+  for (const sensitive of sensitiveKeys) {
+    const s = normalizeSensitiveKey(sensitive);
+    if (!s) continue;
+    if (s === "token") {
+      if (isTokenCredentialKey(normalized)) return true;
+      continue;
+    }
+    if (normalized === s) return true;
+    if (normalized.endsWith(`_${s}`) || normalized.startsWith(`${s}_`)) return true;
+  }
+  return false;
+}
 
 // packages/core/src/checks/index.ts
 var SEVERITY_RANK = {
@@ -6152,16 +6315,7 @@ var CONFIDENCE_RANK = {
   correlated: 2,
   explicit: 3
 };
-var DEFAULT_SENSITIVE_KEYS = [
-  "authorization",
-  "cookie",
-  "token",
-  "apikey",
-  "api_key",
-  "password",
-  "secret",
-  "email"
-];
+var DEFAULT_SENSITIVE_KEYS = DEFAULT_CREDENTIAL_SENSITIVE_KEYS;
 var DEFAULT_RAW_CONTENT_KEYS = [
   "body",
   "headers",
@@ -6319,7 +6473,13 @@ function resolveSelectedRun(input, runId) {
   if (input.read.runs.length === 0) {
     return {
       diagnostics: [
-        diagnostic3("AI_CHECK_RUN_SELECTION_REQUIRED", "No runs are available for checks.")
+        diagnostic3(
+          "AI_CHECK_RUN_SELECTION_REQUIRED",
+          formatProgrammaticDiagnostic(
+            "AI_TRACE_CONTRACT_RUN_SELECTION_REQUIRED",
+            "No runs are available for checks."
+          )
+        )
       ]
     };
   }
@@ -6327,7 +6487,7 @@ function resolveSelectedRun(input, runId) {
     diagnostics: [
       diagnostic3(
         "AI_CHECK_RUN_SELECTION_REQUIRED",
-        "Multiple runs are available; select a run before executing checks."
+        formatProgrammaticDiagnostic("AI_TRACE_CONTRACT_RUN_SELECTION_REQUIRED")
       )
     ]
   };
@@ -6583,9 +6743,7 @@ function hasRedactionMarker(value, markers) {
   return markers.some((marker) => value.includes(marker)) || /^\[HASH:[A-Za-z0-9_-]+\]$/.test(value);
 }
 function isSensitiveKey(key, sensitiveKeys) {
-  if (!key) return false;
-  const normalized = normalizedKey(key);
-  return sensitiveKeys.some((sensitive) => normalized.includes(normalizedKey(sensitive)));
+  return isCredentialSensitiveKey(key, sensitiveKeys);
 }
 function isRawContentKey(key, forbiddenKeys) {
   if (!key) return false;
@@ -6908,7 +7066,7 @@ function createToolUsageRule(options) {
         }
       }
       const forbidden = new Set(options.forbidden ?? []);
-      const allowed = options.allowed ? new Set(options.allowed) : void 0;
+      const allowed = options.allowed?.length ? new Set(options.allowed) : void 0;
       for (const event of tools) {
         const name = toolName(event);
         if (forbidden.has(name)) {
@@ -6944,9 +7102,9 @@ function createLlmUsageRule(options) {
     evaluate(context) {
       const llms = finishedEvents(context, "LLM");
       const findings = [];
-      const allowedModels = options.allowedModels ? new Set(options.allowedModels) : void 0;
-      const allowedProviders = options.allowedProviders ? new Set(options.allowedProviders) : void 0;
-      const finishReasons = options.finishReasons ? new Set(options.finishReasons) : void 0;
+      const allowedModels = options.allowedModels?.length ? new Set(options.allowedModels) : void 0;
+      const allowedProviders = options.allowedProviders?.length ? new Set(options.allowedProviders) : void 0;
+      const finishReasons = options.finishReasons?.length ? new Set(options.finishReasons) : void 0;
       if (options.maxCalls !== void 0 && llms.length > options.maxCalls) {
         findings.push(
           failFinding(
@@ -7058,7 +7216,7 @@ function createStructureCycleRule() {
               findings.push(
                 failFinding(
                   "structure.cycle",
-                  "Trace contains a parentId cycle.",
+                  formatProgrammaticDiagnostic("AI_TRACE_RELATIONSHIP_CYCLE"),
                   cycle.map((item) => eventEvidence(item, "parentId")),
                   "acyclic parentId graph",
                   cycle.map((item) => item.eventId).sort()
@@ -7895,6 +8053,20 @@ function traceEventsToPersistedInspectEvents(events, options) {
 function inc(map, key) {
   map[key] = (map[key] ?? 0) + 1;
 }
+function confidenceRank(confidence) {
+  switch (confidence) {
+    case "unknown":
+      return 0;
+    case "heuristic":
+      return 1;
+    case "correlated":
+      return 2;
+    case "explicit":
+      return 3;
+    default:
+      return 0;
+  }
+}
 function computeRunStatus(events) {
   let runTerminal;
   let sawRunEvent = false;
@@ -7915,6 +8087,84 @@ function computeRunStatus(events) {
   }
   return hasRunning ? "running" : "ok";
 }
+function linkNodesVisibilityFirst(nodes) {
+  let selfParentCount = 0;
+  let unresolvedParentCount = 0;
+  let normalizedEdgeCount = 0;
+  let cycleCount = 0;
+  const pending = [];
+  for (const node of nodes.values()) {
+    const parentId = node.event.parentId;
+    if (!parentId) continue;
+    if (parentId === node.event.eventId) {
+      selfParentCount += 1;
+      normalizedEdgeCount += 1;
+      continue;
+    }
+    if (!nodes.has(parentId)) {
+      unresolvedParentCount += 1;
+      continue;
+    }
+    pending.push({
+      childId: node.event.eventId,
+      parentId,
+      childTimestamp: node.event.timestamp,
+      childConfidence: node.event.confidence
+    });
+  }
+  pending.sort((a, b) => {
+    const conf = confidenceRank(b.childConfidence) - confidenceRank(a.childConfidence);
+    if (conf !== 0) return conf;
+    return a.childTimestamp - b.childTimestamp;
+  });
+  const parentOf = /* @__PURE__ */ new Map();
+  for (const edge of pending) {
+    parentOf.set(edge.childId, edge.parentId);
+    let cursor = edge.parentId;
+    const seen = /* @__PURE__ */ new Set([edge.childId]);
+    let cyclic = false;
+    while (cursor) {
+      if (seen.has(cursor)) {
+        cyclic = true;
+        break;
+      }
+      seen.add(cursor);
+      cursor = parentOf.get(cursor);
+    }
+    if (cyclic) {
+      parentOf.delete(edge.childId);
+      cycleCount += 1;
+      normalizedEdgeCount += 1;
+    }
+  }
+  for (const [childId, parentId] of parentOf) {
+    nodes.get(parentId).children.push(nodes.get(childId));
+  }
+  const roots = [];
+  for (const node of nodes.values()) {
+    if (!parentOf.has(node.event.eventId)) {
+      roots.push(node);
+    }
+  }
+  const assignDepth = (n, depth, stack) => {
+    if (stack.has(n.event.eventId)) return;
+    n.depth = depth;
+    stack.add(n.event.eventId);
+    for (const c of n.children) assignDepth(c, depth + 1, stack);
+    stack.delete(n.event.eventId);
+  };
+  for (const r of roots) assignDepth(r, 0, /* @__PURE__ */ new Set());
+  return {
+    roots,
+    summary: {
+      rootCount: roots.length,
+      selfParentCount,
+      cycleCount,
+      unresolvedParentCount,
+      normalizedEdgeCount
+    }
+  };
+}
 var TreeBuilder = class {
   constructor(options) {
     void options?.config;
@@ -7932,20 +8182,7 @@ var TreeBuilder = class {
       for (const e of sorted) {
         nodes.set(e.eventId, { event: e, children: [], depth: 0 });
       }
-      const roots = [];
-      for (const node of nodes.values()) {
-        const parentId = node.event.parentId;
-        if (parentId && nodes.has(parentId)) {
-          nodes.get(parentId).children.push(node);
-        } else {
-          roots.push(node);
-        }
-      }
-      const assignDepth = (n, depth) => {
-        n.depth = depth;
-        for (const c of n.children) assignDepth(c, depth + 1);
-      };
-      for (const r of roots) assignDepth(r, 0);
+      const { roots, summary } = linkNodesVisibilityFirst(nodes);
       const confidenceBreakdown = {
         explicit: 0,
         correlated: 0,
@@ -7973,7 +8210,8 @@ var TreeBuilder = class {
         metadata: {
           totalEvents: sorted.length,
           confidenceBreakdown,
-          kinds
+          kinds,
+          relationshipSummary: summary
         }
       });
     }
@@ -8202,6 +8440,38 @@ var TraceReadError = class extends Error {
     this.warnings = warnings;
   }
 };
+var TRACE_INPUT_INVALID_MESSAGE = formatProgrammaticDiagnostic(
+  "AI_TRACE_INPUT_INVALID"
+);
+function isTraceInput(input) {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    return false;
+  }
+  const record = input;
+  switch (record.type) {
+    case "file":
+    case "directory":
+      return typeof record.path === "string";
+    case "string":
+      return typeof record.content === "string";
+    case "buffer":
+      return Buffer.isBuffer(record.content);
+    case "stdin":
+      return true;
+    default:
+      return false;
+  }
+}
+function assertTraceInput(input) {
+  if (isTraceInput(input)) return;
+  throw new TraceReadError("invalid_input", TRACE_INPUT_INVALID_MESSAGE, [
+    {
+      code: "AI_TRACE_INPUT_INVALID",
+      message: TRACE_INPUT_INVALID_MESSAGE,
+      severity: "error"
+    }
+  ]);
+}
 function normalizeCandidate(reader, candidate) {
   const confidence = Number.isFinite(candidate.confidence) ? Math.max(0, Math.min(1, candidate.confidence)) : 0;
   return {
@@ -9556,6 +9826,7 @@ var DEFAULT_TRACE_READERS = [
   otlpJsonReader
 ];
 async function detectTraceFormat(input, options = {}) {
+  assertTraceInput(input);
   const readers = options.readers ?? DEFAULT_TRACE_READERS;
   if (options.format !== void 0) {
     const reader = findReaderByFormat(options.format, readers);
@@ -9652,19 +9923,20 @@ async function detectTraceFormat(input, options = {}) {
   };
 }
 async function readTrace(input, options = {}) {
+  assertTraceInput(input);
   const readers = options.readers ?? DEFAULT_TRACE_READERS;
   const detection = await detectTraceFormat(input, options);
   if (detection.status === "unsupported" || detection.format === void 0) {
     throw new TraceReadError(
       "unsupported_format",
-      "No trace reader could detect the input format.",
+      formatProgrammaticDiagnostic("AI_TRACE_FORMAT_UNSUPPORTED"),
       detection.warnings
     );
   }
   if (detection.status === "ambiguous") {
     throw new TraceReadError(
       "ambiguous_format",
-      "Multiple trace readers matched the input with equal confidence.",
+      formatProgrammaticDiagnostic("AI_TRACE_FORMAT_AMBIGUOUS"),
       detection.warnings
     );
   }
@@ -9672,7 +9944,10 @@ async function readTrace(input, options = {}) {
   if (!reader) {
     throw new TraceReadError(
       "unsupported_format",
-      `No trace reader is registered for format "${detection.format}".`,
+      formatProgrammaticDiagnostic(
+        "AI_TRACE_FORMAT_UNSUPPORTED",
+        `No trace reader is registered for format "${detection.format}".`
+      ),
       detection.warnings
     );
   }
@@ -11045,6 +11320,6 @@ function renderGateReport(result, options = {}) {
   return renderGateSummaryMarkdown(result);
 }
 
-export { COHORT_METRIC_IDS, DEFAULT_SUITE_ARTIFACTS_DIR, EVIDENCE_FORMAT_VERSION, EVIDENCE_HTML_FILENAME, EVIDENCE_MANIFEST_FILENAME, Redactor, TraceDirectory, TraceReadError, TreeBuilder, aggregateBundleSafeStatus, aggregateSessionCheckResults, analyzeCohort, applyProfileMetadataCaps, assertBundlePathContained, assertEvidenceRelativePath, buildActivitySummary, buildBundleMetadata, buildBundleSummaryMarkdown, buildEvidenceCausalFailureViewHtml, buildEvidenceCiPackage, buildEvidenceCircuitViewHtml, buildEvidenceContractsViewHtml, buildEvidenceDiffViewHtml, buildEvidenceHtmlShell, buildEvidenceManifest, buildEvidenceOutcomesViewHtml, buildEvidenceProvenanceViewHtml, buildEvidenceSafetyViewHtml, buildEvidenceTimelineViewHtml, buildEvidenceToolsLlmViewHtml, buildEvidenceTreeViewHtml, buildLocalExplanation, buildPlaceholderArtifact, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildSessionIndex, buildTraceStats, buildZipArchive, bundleFailsOnSafety, bundleRunAssetRelativePath, collectTraceSchemaVersions, compactAttributes, createBaselineRegressionRule, createLlmUsageRule, createMaxStepDurationRule, createObservedOutcomeRule, createRequireCompletedRule, createRunDepthRule, createRunDurationRule, createRunStatusRule, createSafetyOversizedAttributeRule, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createStallDetectionRule, createStructureCycleRule, createStructureOrphanRule, createStructureParallelWidthRule, createStructureRelationshipRule, createToolUsageRule, defaultBundleOutputPath, defaultSuiteConfigTemplate, diffRuns, diffTraceEvents, enrichSessionRunRecord, escapeHtml, escapeMarkdown, extractMetadata, extractOutcomesFromTraceEvents, filterMetasBySessionScope, filterTraces, flattenTree, formatDuration2 as formatDuration, formatTimestamp, gateHasThresholds, getIndent, getTraceFilePath, inferEvidenceFileRole, isAgentInspectTrace, isPersistedInspectEvent, loadSessionRunRecords, loadSuiteConfig, loadTraceMetadataList, manualTraceEventsToComparableRun, nanoid, normalizeBundleOutputPath, openTrace, parseCohortMetricList, parseDuration, parseDurationFilter, parseGateList, parseTraceJsonl, persistedInspectEventsToTraceEvents, renderActivitySummaryHuman, renderCohortReport, renderErrorLine, renderGateReport, renderObservedOutcomesHtml, renderObservedOutcomesMarkdown, renderRunDiff, renderRunWhat, renderStepLine, renderSuiteReport, renderTimeline, renderTraceStats, resolveBundleRunIds, resolveRedactionProfile, resolveSuiteTemplate, resolveTraceDir, runGate, runSuite, runTraceChecks, safeString, sanitizeBundleRunId, searchTraces, serializeEvidenceManifest, sha256Hex, stableJson, summarizeObservedOutcomes, summarizeSemanticParity, traceEventToPersistedInspectEvent, truncateName, truncateStringForProfile, validateEvent, validateSuiteConfig, verifyEvidenceDirectory, zeroKinds };
-//# sourceMappingURL=chunk-MEO2Z3KE.mjs.map
-//# sourceMappingURL=chunk-MEO2Z3KE.mjs.map
+export { COHORT_METRIC_IDS, DEFAULT_SUITE_ARTIFACTS_DIR, EVIDENCE_FORMAT_VERSION, EVIDENCE_HTML_FILENAME, EVIDENCE_MANIFEST_FILENAME, Redactor, TraceDirectory, TraceReadError, TreeBuilder, aggregateBundleSafeStatus, aggregateSessionCheckResults, analyzeCohort, applyProfileMetadataCaps, assertBundlePathContained, assertEvidenceRelativePath, buildActivitySummary, buildBundleMetadata, buildBundleSummaryMarkdown, buildEvidenceCausalFailureViewHtml, buildEvidenceCiPackage, buildEvidenceCircuitViewHtml, buildEvidenceContractsViewHtml, buildEvidenceDiffViewHtml, buildEvidenceHtmlShell, buildEvidenceManifest, buildEvidenceOutcomesViewHtml, buildEvidenceProvenanceViewHtml, buildEvidenceSafetyViewHtml, buildEvidenceTimelineViewHtml, buildEvidenceToolsLlmViewHtml, buildEvidenceTreeViewHtml, buildLocalExplanation, buildPlaceholderArtifact, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildSessionIndex, buildTraceStats, buildZipArchive, bundleFailsOnSafety, bundleRunAssetRelativePath, collectTraceSchemaVersions, compactAttributes, createBaselineRegressionRule, createLlmUsageRule, createMaxStepDurationRule, createObservedOutcomeRule, createRequireCompletedRule, createRunDepthRule, createRunDurationRule, createRunStatusRule, createSafetyOversizedAttributeRule, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createStallDetectionRule, createStructureCycleRule, createStructureOrphanRule, createStructureParallelWidthRule, createStructureRelationshipRule, createToolUsageRule, defaultBundleOutputPath, defaultSuiteConfigTemplate, diffRuns, diffTraceEvents, enrichSessionRunRecord, escapeHtml, escapeMarkdown, extractMetadata, extractOutcomesFromTraceEvents, filterMetasBySessionScope, filterTraces, flattenTree, formatDuration2 as formatDuration, formatStepLabel, formatTimestamp, gateHasThresholds, getIndent, getTraceFilePath, inferEvidenceFileRole, isAgentInspectTrace, isPersistedInspectEvent, loadSessionRunRecords, loadSuiteConfig, loadTraceMetadataList, manualTraceEventsToComparableRun, nanoid, normalizeBundleOutputPath, openTrace, parseCohortMetricList, parseDuration, parseDurationFilter, parseGateList, parseTraceJsonl, persistedInspectEventsToTraceEvents, renderActivitySummaryHuman, renderCohortReport, renderErrorLine, renderGateReport, renderObservedOutcomesHtml, renderObservedOutcomesMarkdown, renderRunDiff, renderRunWhat, renderStepLine, renderSuiteReport, renderTimeline, renderTraceStats, resolveBundleRunIds, resolveRedactionProfile, resolveSuiteTemplate, resolveTraceDir, runGate, runSuite, runTraceChecks, safeString, sanitizeBundleRunId, searchTraces, serializeEvidenceManifest, sha256Hex, stableJson, summarizeObservedOutcomes, summarizeSemanticParity, traceEventToPersistedInspectEvent, truncateName, truncateStringForProfile, validateEvent, validateSuiteConfig, verifyEvidenceDirectory, zeroKinds };
+//# sourceMappingURL=chunk-LFSBMUCD.mjs.map
+//# sourceMappingURL=chunk-LFSBMUCD.mjs.map