@agent-inspect/viewer 6.31.10 → 6.31.12

package/dist/index.cjs

@@ -1170,870 +1170,870 @@ function buildRunTimeline(events, options = {}) {
   };
 }
 
-// packages/core/src/search.ts
-async function loadTraceMetadataList(_traceDir, fileNames, getPath) {
-  const metas = [];
-  for (const fileName of fileNames) {
-    try {
-      const filePath = getPath(fileName);
-      const meta = await extractMetadata(filePath);
-      metas.push(meta);
-    } catch {
-    }
+// 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"]
+  },
+  AI_TRACE_CONTRACT_INPUT_INVALID: {
+    code: "AI_TRACE_CONTRACT_INPUT_INVALID",
+    summary: "evaluateTraceContract expects ({ read }, contract) or use evaluateTraceContractRead(read, contract).",
+    remediation: "Pass TraceCheckInput as the first argument: evaluateTraceContract({ read }, contract).",
+    relatedCodes: ["AI_CHECK_INVALID_ARGUMENTS"]
+  },
+  AI_INSPECT_RUN_UNSUPPORTED_OPTION: {
+    code: "AI_INSPECT_RUN_UNSUPPORTED_OPTION",
+    summary: 'inspectRun does not accept a "writer" option.',
+    remediation: "Use createInspector({ writer }) then inspector.run(...). inspectRun persists via the global JSONL path (schema 0.1)."
   }
-  return metas;
+});
+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/sessions/metadata.ts
-function isNonEmptyString3(value) {
-  return typeof value === "string" && value.trim() !== "";
-}
-function finitePositiveInt(value) {
-  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) {
-    return void 0;
-  }
-  return Math.trunc(value);
+// packages/core/src/checks/logical-events.ts
+function isRecord5(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function extractSessionWorkflowMetadata(record) {
-  if (!record) return void 0;
-  const out = {};
-  let found = false;
-  const assignString = (key, value) => {
-    if (isNonEmptyString3(value)) {
-      out[key] = value.trim();
-      found = true;
-    }
-  };
-  assignString("sessionId", record.sessionId);
-  assignString("conversationId", record.conversationId);
-  assignString("groupId", record.groupId);
-  assignString("parentGroupId", record.parentGroupId);
-  assignString("retryOf", record.retryOf);
-  assignString("retryReason", record.retryReason);
-  assignString("handoffFrom", record.handoffFrom);
-  assignString("handoffTo", record.handoffTo);
-  assignString("subAgentId", record.subAgentId);
-  assignString("subAgentName", record.subAgentName);
-  assignString("jobId", record.jobId);
-  assignString("queueName", record.queueName);
-  assignString("workflowName", record.workflowName);
-  assignString("workflowStep", record.workflowStep);
-  assignString("toolCallId", record.toolCallId);
-  assignString("mcpToolCallId", record.mcpToolCallId);
-  assignString("linkedStepId", record.linkedStepId);
-  assignString("operationId", record.operationId);
-  assignString("attemptId", record.attemptId);
-  assignString("fallbackOf", record.fallbackOf);
-  assignString("idempotencyKey", record.idempotencyKey);
-  assignString("correlationId", record.correlationId);
-  assignString("requestId", record.requestId);
-  assignString("decisionId", record.decisionId);
-  const attempt = finitePositiveInt(record.attempt);
-  if (attempt !== void 0) {
-    out.attempt = attempt;
-    found = true;
-  }
-  const attemptNumber = finitePositiveInt(record.attemptNumber);
-  if (attemptNumber !== void 0) {
-    out.attemptNumber = attemptNumber;
-    found = true;
-  }
-  return found ? out : void 0;
+function legacyEvent(event) {
+  const value = event.attributes?.legacyEvent;
+  return typeof value === "string" ? value : void 0;
 }
-function sessionKeyForRun(meta, options) {
-  if (meta?.sessionId) return meta.sessionId;
-  if (options?.correlateByGroupId && meta?.groupId) {
-    return `group:${meta.groupId}`;
-  }
+function stepIdOf(event) {
+  const value = event.attributes?.stepId;
+  if (typeof value === "string" && value.trim() !== "") return value;
   return void 0;
 }
-
-// packages/core/src/sessions/status.ts
-var DEFAULT_STALE_THRESHOLD_MS = 864e5;
-var EXPLICIT_STATUS_PRIORITY = {
-  error: 5,
-  waiting_input: 4,
-  idle: 3,
-  stale: 2,
-  completed: 1
-};
-var EXPLICIT_SESSION_STATUSES = /* @__PURE__ */ new Set([
-  "running",
-  "waiting_input",
-  "idle",
-  "completed",
-  "error",
-  "stale",
-  "unknown"
-]);
-function isExplicitSessionStatus(value) {
-  return typeof value === "string" && EXPLICIT_SESSION_STATUSES.has(value);
-}
-function activityMs(run) {
-  return run.endedAt ?? run.startedAt ?? 0;
+function cloneEvent(event) {
+  return {
+    ...event,
+    ...event.attributes !== void 0 ? { attributes: { ...event.attributes } } : {},
+    ...event.error !== void 0 ? { error: { ...event.error } } : {},
+    ...event.tokenUsage !== void 0 ? { tokenUsage: { ...event.tokenUsage } } : {},
+    ...event.source !== void 0 ? { source: { ...event.source } } : {}
+  };
 }
-function latestActivityMs(runs) {
-  let latest = 0;
-  for (const run of runs) {
-    const ms = activityMs(run);
-    if (ms > latest) latest = ms;
+function mergeAttributes(start, complete) {
+  const merged = {
+    ...isRecord5(complete.attributes) ? complete.attributes : {},
+    ...isRecord5(start.attributes) ? start.attributes : {}
+  };
+  merged.legacyEvent = start.attributes?.legacyEvent ?? complete.attributes?.legacyEvent;
+  merged.legacyCompleteEvent = complete.attributes?.legacyEvent;
+  if (complete.attributes?.errorStack !== void 0) {
+    merged.errorStack = complete.attributes.errorStack;
   }
-  return latest;
+  return Object.keys(merged).length > 0 ? merged : void 0;
 }
-function earliestStart(runs) {
-  let earliest;
-  for (const run of runs) {
-    if (run.startedAt === void 0) continue;
-    if (earliest === void 0 || run.startedAt < earliest) {
-      earliest = run.startedAt;
+function pairStartComplete(start, complete) {
+  const attributes = mergeAttributes(start, complete);
+  const paired = {
+    ...cloneEvent(start),
+    status: complete.status,
+    timestamp: complete.timestamp ?? start.timestamp,
+    ...complete.endedAt !== void 0 ? { endedAt: complete.endedAt } : {},
+    ...complete.durationMs !== void 0 ? { durationMs: complete.durationMs } : {},
+    ...complete.error !== void 0 ? { error: { ...complete.error } } : {},
+    ...complete.tokenUsage !== void 0 && start.tokenUsage === void 0 ? { tokenUsage: { ...complete.tokenUsage } } : {},
+    ...attributes !== void 0 ? { attributes } : {}
+  };
+  return {
+    ...paired,
+    sourceEventIds: Object.freeze([start.eventId, complete.eventId]),
+    projection: {
+      paired: true,
+      absorbedEventIds: Object.freeze([complete.eventId]),
+      parentNormalized: false,
+      ...start.parentId !== void 0 ? { originalParentId: start.parentId } : {}
     }
-  }
-  return earliest;
-}
-function latestEndWhenAllEnded(runs) {
-  if (runs.length === 0) return void 0;
-  let latest;
-  for (const run of runs) {
-    if (run.endedAt === void 0) return void 0;
-    if (latest === void 0 || run.endedAt > latest) latest = run.endedAt;
-  }
-  return latest;
+  };
 }
-function pickExplicitStatus(runs) {
-  let best;
-  let bestPriority = 0;
-  for (const run of runs) {
-    const raw = run.metadata?.sessionStatus;
-    if (!isExplicitSessionStatus(raw)) continue;
-    const priority = EXPLICIT_STATUS_PRIORITY[raw] ?? 0;
-    if (priority > bestPriority) {
-      bestPriority = priority;
-      best = raw;
+function asLogical(event, extras) {
+  return {
+    ...cloneEvent(event),
+    sourceEventIds: Object.freeze([event.eventId]),
+    projection: {
+      paired: false,
+      absorbedEventIds: Object.freeze([]),
+      parentNormalized: extras?.parentNormalized === true,
+      ...{}
     }
-  }
-  return best;
+  };
 }
-function deriveLastError(runs) {
-  const errorRuns = runs.filter((run) => run.status === "error").sort((a, b) => activityMs(b) - activityMs(a));
-  const latest = errorRuns[0];
-  if (!latest) return void 0;
-  const meta = latest.metadata ?? {};
-  const message = typeof meta.errorMessage === "string" && meta.errorMessage.trim() !== "" ? meta.errorMessage.trim() : latest.name ?? latest.runId;
-  const code = typeof meta.errorCode === "string" && meta.errorCode.trim() !== "" ? meta.errorCode.trim() : void 0;
-  return { runId: latest.runId, message, code };
-}
-function deriveCheckSummary(runs) {
-  let pass = 0;
-  let fail = 0;
-  let warn2 = 0;
-  let found = false;
-  for (const run of runs) {
-    const summary = run.metadata?.checkSummary;
-    if (!summary || typeof summary !== "object") continue;
-    const record = summary;
-    if (typeof record.pass === "number") {
-      pass += record.pass;
-      found = true;
+function projectLogicalEvents(events) {
+  const diagnostics = [];
+  const byRun = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    const list = byRun.get(event.runId) ?? [];
+    list.push(event);
+    byRun.set(event.runId, list);
+  }
+  const absorbedIds = /* @__PURE__ */ new Set();
+  const logicalByRawId = /* @__PURE__ */ new Map();
+  const stepIdToLogicalId = /* @__PURE__ */ new Map();
+  const logical = [];
+  const orderedRuns = [...byRun.keys()].sort((a, b) => a.localeCompare(b));
+  for (const runId of orderedRuns) {
+    const runEvents = byRun.get(runId) ?? [];
+    const starts = [];
+    const completes = [];
+    const others = [];
+    for (const event of runEvents) {
+      const legacy = legacyEvent(event);
+      if (legacy === "step_started" || legacy === "run_started" && event.status === "running") {
+        starts.push(event);
+      } else if (legacy === "step_completed" || legacy === "run_completed") {
+        completes.push(event);
+      } else {
+        others.push(event);
+      }
     }
-    if (typeof record.fail === "number") {
-      fail += record.fail;
-      found = true;
+    const usedCompletes = /* @__PURE__ */ new Set();
+    for (const start of starts) {
+      const stepId = stepIdOf(start);
+      let match;
+      if (legacyEvent(start) === "run_started") {
+        const candidates = completes.filter(
+          (c) => !usedCompletes.has(c.eventId) && legacyEvent(c) === "run_completed"
+        );
+        if (candidates.length > 1) {
+          diagnostics.push({
+            code: "AI_LOGICAL_PAIR_AMBIGUOUS",
+            message: `Multiple run_completed rows for run ${runId}; using first by eventId.`,
+            eventIds: candidates.map((c) => c.eventId)
+          });
+          candidates.sort((a, b) => a.eventId.localeCompare(b.eventId));
+        }
+        match = candidates[0];
+      } else if (stepId) {
+        const candidates = completes.filter(
+          (c) => !usedCompletes.has(c.eventId) && legacyEvent(c) === "step_completed" && stepIdOf(c) === stepId
+        );
+        if (candidates.length > 1) {
+          diagnostics.push({
+            code: "AI_LOGICAL_PAIR_AMBIGUOUS",
+            message: `Multiple step_completed rows for stepId ${stepId}; using first by eventId.`,
+            eventIds: candidates.map((c) => c.eventId)
+          });
+          candidates.sort((a, b) => a.eventId.localeCompare(b.eventId));
+        }
+        match = candidates[0];
+      }
+      if (match) {
+        usedCompletes.add(match.eventId);
+        absorbedIds.add(match.eventId);
+        const paired = pairStartComplete(start, match);
+        logical.push(paired);
+        logicalByRawId.set(start.eventId, paired);
+        logicalByRawId.set(match.eventId, paired);
+        if (stepId) stepIdToLogicalId.set(`${runId}:${stepId}`, paired.eventId);
+      } else {
+        diagnostics.push({
+          code: "AI_LOGICAL_PAIR_UNMATCHED_START",
+          message: `No matching complete for start ${start.eventId}.`,
+          eventIds: [start.eventId]
+        });
+        const alone = asLogical(start);
+        logical.push(alone);
+        logicalByRawId.set(start.eventId, alone);
+        if (stepId) stepIdToLogicalId.set(`${runId}:${stepId}`, alone.eventId);
+      }
     }
-    if (typeof record.warn === "number") {
-      warn2 += record.warn;
-      found = true;
+    for (const complete of completes) {
+      if (usedCompletes.has(complete.eventId)) continue;
+      diagnostics.push({
+        code: "AI_LOGICAL_PAIR_UNMATCHED_COMPLETE",
+        message: `No matching start for complete ${complete.eventId}.`,
+        eventIds: [complete.eventId]
+      });
+      const alone = asLogical(complete);
+      logical.push(alone);
+      logicalByRawId.set(complete.eventId, alone);
+      const stepId = stepIdOf(complete);
+      if (stepId && !stepIdToLogicalId.has(`${runId}:${stepId}`)) {
+        stepIdToLogicalId.set(`${runId}:${stepId}`, alone.eventId);
+      }
+    }
+    for (const event of others) {
+      const alone = asLogical(event);
+      logical.push(alone);
+      logicalByRawId.set(event.eventId, alone);
+      const stepId = stepIdOf(event);
+      if (stepId && !stepIdToLogicalId.has(`${runId}:${stepId}`)) {
+        stepIdToLogicalId.set(`${runId}:${stepId}`, alone.eventId);
+      }
     }
   }
-  return found ? { pass, fail, warn: warn2 } : void 0;
-}
-function deriveObservationSummary(runs) {
-  for (const run of [...runs].sort((a, b) => activityMs(b) - activityMs(a))) {
-    const value = run.metadata?.observationSummary;
-    if (typeof value === "string" && value.trim() !== "") {
-      return value.trim();
+  const logicalById = new Map(logical.map((e) => [e.eventId, e]));
+  const normalized = [];
+  for (const event of logical) {
+    const originalParentId = event.parentId;
+    if (!originalParentId) {
+      normalized.push(event);
+      continue;
+    }
+    let nextParent = originalParentId;
+    let remapped = false;
+    const viaAbsorbed = logicalByRawId.get(originalParentId);
+    if (viaAbsorbed && viaAbsorbed.eventId !== originalParentId) {
+      nextParent = viaAbsorbed.eventId;
+      remapped = true;
+    } else if (!logicalById.has(originalParentId)) {
+      const viaStep = stepIdToLogicalId.get(`${event.runId}:${originalParentId}`);
+      if (viaStep) {
+        nextParent = viaStep;
+        remapped = true;
+      }
+    }
+    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.
+        /^LangGraph$/i.test(originalParentId) || originalParentId.startsWith("unresolved:");
+        if (!unresolved) {
+          diagnostics.push({
+            code: "AI_LOGICAL_PARENT_UNRESOLVED",
+            message: `Parent ${originalParentId} unresolved for ${event.eventId}.`,
+            eventIds: [event.eventId]
+          });
+        }
+      }
+      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}.`,
+      eventIds: [event.eventId]
+    });
+    normalized.push({
+      ...event,
+      parentId: nextParent,
+      projection: {
+        ...event.projection,
+        parentNormalized: true,
+        originalParentId
+      }
+    });
   }
-  return void 0;
+  const rawIndex = new Map(events.map((e, i) => [e.eventId, i]));
+  normalized.sort((a, b) => {
+    const ai = rawIndex.get(a.sourceEventIds[0]) ?? 0;
+    const bi = rawIndex.get(b.sourceEventIds[0]) ?? 0;
+    return ai - bi || a.eventId.localeCompare(b.eventId);
+  });
+  return {
+    logicalEvents: Object.freeze(normalized),
+    diagnostics: Object.freeze(diagnostics)
+  };
 }
-function deriveSessionStatus(runs, options = {}) {
-  if (runs.length === 0) return "unknown";
-  if (runs.some((run) => run.status === "running")) return "running";
-  const explicit = pickExplicitStatus(runs);
-  if (explicit && explicit !== "running") return explicit;
-  if (runs.some((run) => run.status === "error")) return "error";
-  if (runs.every((run) => run.status === "success")) return "completed";
-  const nowMs = options.nowMs ?? Date.now();
-  const staleThresholdMs = options.staleThresholdMs ?? DEFAULT_STALE_THRESHOLD_MS;
-  const lastMs = latestActivityMs(runs);
-  if (lastMs > 0 && nowMs - lastMs > staleThresholdMs) return "stale";
-  return "unknown";
+function resolveCanonicalToolName(event) {
+  const attrs = event.attributes;
+  const direct = pickString(attrs, ["toolName", "tool"]);
+  if (direct) return direct;
+  const metadata = attrs?.metadata;
+  if (isRecord5(metadata)) {
+    const nested = pickString(metadata, ["toolName", "tool"]);
+    if (nested) return nested;
+  }
+  for (const prefix of ["tool:", "function:", "mcp-tools:"]) {
+    if (event.name.startsWith(prefix)) return event.name.slice(prefix.length);
+  }
+  return event.name;
 }
-function enrichSessionSummary(summary, runs, options = {}) {
-  const sessionRuns = runs.filter((run) => summary.runIds.includes(run.runId)).sort((a, b) => a.runId.localeCompare(b.runId));
-  const startedAt = earliestStart(sessionRuns);
-  const endedAt = latestEndWhenAllEnded(sessionRuns);
-  const durationMs = startedAt !== void 0 && endedAt !== void 0 ? endedAt - startedAt : void 0;
-  let correlationId;
-  let jobId;
-  let workflowId;
-  for (const run of sessionRuns) {
-    const meta = extractSessionWorkflowMetadata(run.metadata);
-    if (!correlationId && meta?.correlationId) correlationId = meta.correlationId;
-    if (!jobId && meta?.jobId) jobId = meta.jobId;
-    if (!workflowId && meta?.workflowName) workflowId = meta.workflowName;
-    else if (!workflowId && meta?.workflowStep) workflowId = meta.workflowStep;
+function pickString(record, keys) {
+  if (!record) return void 0;
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim() !== "") return value.trim();
   }
-  const lastMs = latestActivityMs(sessionRuns);
-  const lastActivity = lastMs > 0 ? new Date(lastMs).toISOString() : (/* @__PURE__ */ new Date(0)).toISOString();
-  const retryCount2 = summary.retries.filter(
-    (retry) => retry.retryOf !== void 0 || (retry.attempt ?? 0) > 1
-  ).length;
-  return {
-    ...summary,
-    status: deriveSessionStatus(sessionRuns, options),
-    startedAt,
-    endedAt,
-    durationMs,
-    correlationId,
-    jobId,
-    workflowId,
-    lastError: deriveLastError(sessionRuns),
-    lastActivity,
-    retryCount: retryCount2,
-    observationSummary: deriveObservationSummary(sessionRuns),
-    checkSummary: deriveCheckSummary(sessionRuns)
-  };
+  return void 0;
 }
 
-// packages/core/src/sessions/load.ts
-async function enrichSessionRunRecord(meta) {
-  let metadata;
-  try {
-    const events = await readTraceEventsFromFile(meta.filePath);
-    for (const event of events) {
-      if (event.event !== "run_started") continue;
-      if (event.metadata && typeof event.metadata === "object") {
-        metadata = event.metadata;
-      }
-      break;
+// packages/core/src/search.ts
+async function loadTraceMetadataList(_traceDir, fileNames, getPath) {
+  const metas = [];
+  for (const fileName of fileNames) {
+    try {
+      const filePath = getPath(fileName);
+      const meta = await extractMetadata(filePath);
+      metas.push(meta);
+    } catch {
     }
-  } catch {
   }
-  return {
-    runId: meta.runId,
-    name: meta.name,
-    status: meta.status,
-    startedAt: meta.startedAt,
-    endedAt: meta.endedAt,
-    durationMs: meta.durationMs,
-    filePath: meta.filePath,
-    metadata
-  };
+  return metas;
 }
-async function loadSessionRunRecords(metas) {
-  const out = [];
-  for (const meta of metas) {
-    out.push(await enrichSessionRunRecord(meta));
+
+// packages/core/src/sessions/metadata.ts
+function isNonEmptyString3(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+function finitePositiveInt(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) {
+    return void 0;
+  }
+  return Math.trunc(value);
+}
+function extractSessionWorkflowMetadata(record) {
+  if (!record) return void 0;
+  const out = {};
+  let found = false;
+  const assignString = (key, value) => {
+    if (isNonEmptyString3(value)) {
+      out[key] = value.trim();
+      found = true;
+    }
+  };
+  assignString("sessionId", record.sessionId);
+  assignString("conversationId", record.conversationId);
+  assignString("groupId", record.groupId);
+  assignString("parentGroupId", record.parentGroupId);
+  assignString("retryOf", record.retryOf);
+  assignString("retryReason", record.retryReason);
+  assignString("handoffFrom", record.handoffFrom);
+  assignString("handoffTo", record.handoffTo);
+  assignString("subAgentId", record.subAgentId);
+  assignString("subAgentName", record.subAgentName);
+  assignString("jobId", record.jobId);
+  assignString("queueName", record.queueName);
+  assignString("workflowName", record.workflowName);
+  assignString("workflowStep", record.workflowStep);
+  assignString("toolCallId", record.toolCallId);
+  assignString("mcpToolCallId", record.mcpToolCallId);
+  assignString("linkedStepId", record.linkedStepId);
+  assignString("operationId", record.operationId);
+  assignString("attemptId", record.attemptId);
+  assignString("fallbackOf", record.fallbackOf);
+  assignString("idempotencyKey", record.idempotencyKey);
+  assignString("correlationId", record.correlationId);
+  assignString("requestId", record.requestId);
+  assignString("decisionId", record.decisionId);
+  const attempt = finitePositiveInt(record.attempt);
+  if (attempt !== void 0) {
+    out.attempt = attempt;
+    found = true;
+  }
+  const attemptNumber = finitePositiveInt(record.attemptNumber);
+  if (attemptNumber !== void 0) {
+    out.attemptNumber = attemptNumber;
+    found = true;
   }
-  return out;
+  return found ? out : void 0;
+}
+function sessionKeyForRun(meta, options) {
+  if (meta?.sessionId) return meta.sessionId;
+  if (options?.correlateByGroupId && meta?.groupId) {
+    return `group:${meta.groupId}`;
+  }
+  return void 0;
 }
 
-// packages/core/src/sessions/index.ts
-function compareRuns(a, b) {
-  const aStart = a.startedAt ?? 0;
-  const bStart = b.startedAt ?? 0;
-  if (aStart !== bStart) return aStart - bStart;
-  return a.runId.localeCompare(b.runId);
+// packages/core/src/sessions/status.ts
+var DEFAULT_STALE_THRESHOLD_MS = 864e5;
+var EXPLICIT_STATUS_PRIORITY = {
+  error: 5,
+  waiting_input: 4,
+  idle: 3,
+  stale: 2,
+  completed: 1
+};
+var EXPLICIT_SESSION_STATUSES = /* @__PURE__ */ new Set([
+  "running",
+  "waiting_input",
+  "idle",
+  "completed",
+  "error",
+  "stale",
+  "unknown"
+]);
+function isExplicitSessionStatus(value) {
+  return typeof value === "string" && EXPLICIT_SESSION_STATUSES.has(value);
 }
-function buildGroups(runIds, metaByRunId) {
-  const byGroup = /* @__PURE__ */ new Map();
-  for (const runId of runIds) {
-    const groupId = metaByRunId.get(runId)?.groupId;
-    if (!groupId) continue;
-    const existing = byGroup.get(groupId);
-    if (existing) {
-      existing.runIds.push(runId);
-    } else {
-      byGroup.set(groupId, {
-        groupId,
-        parentGroupId: metaByRunId.get(runId)?.parentGroupId,
-        runIds: [runId]
-      });
-    }
-  }
-  return [...byGroup.values()].map((group) => ({
-    ...group,
-    runIds: [...group.runIds].sort((a, b) => a.localeCompare(b))
-  }));
+function activityMs(run) {
+  return run.endedAt ?? run.startedAt ?? 0;
 }
-function buildHandoffs(runIds, metaByRunId, warnings, sessionId) {
-  const edges = [];
-  const seen = /* @__PURE__ */ new Set();
-  const pushEdge = (edge) => {
-    const key = `${edge.from}->${edge.to}:${edge.confidence}`;
-    if (seen.has(key)) return;
-    seen.add(key);
-    edges.push(edge);
-  };
-  for (const runId of runIds) {
-    const meta = metaByRunId.get(runId);
-    if (!meta) continue;
-    if (meta.handoffFrom && meta.handoffTo) {
-      pushEdge({
-        from: meta.handoffFrom,
-        to: meta.handoffTo,
-        source: "manual",
-        confidence: "explicit"
-      });
-      continue;
-    }
-    if (meta.handoffFrom) {
-      pushEdge({
-        from: meta.handoffFrom,
-        to: runId,
-        source: "manual",
-        confidence: "explicit"
-      });
-    }
-    if (meta.handoffTo) {
-      pushEdge({
-        from: runId,
-        to: meta.handoffTo,
-        source: "manual",
-        confidence: "explicit"
-      });
-    }
-    if (meta.subAgentId && meta.parentGroupId && !meta.handoffFrom && !meta.handoffTo) {
-      pushEdge({
-        from: meta.parentGroupId,
-        to: meta.subAgentId,
-        source: "inferred",
-        confidence: "correlated"
-      });
-      warnings.push({
-        code: "ambiguous-handoff-endpoints",
-        message: "Handoff inferred from parentGroupId and subAgentId without explicit handoffFrom/handoffTo.",
-        runId,
-        sessionId
-      });
-    }
+function latestActivityMs(runs) {
+  let latest = 0;
+  for (const run of runs) {
+    const ms = activityMs(run);
+    if (ms > latest) latest = ms;
   }
-  return edges.sort((a, b) => {
-    const from = a.from.localeCompare(b.from);
-    if (from !== 0) return from;
-    return a.to.localeCompare(b.to);
-  });
+  return latest;
 }
-function buildRetries(runIds, metaByRunId, warnings, sessionId) {
-  const retries = [];
-  for (const runId of runIds) {
-    const meta = metaByRunId.get(runId);
-    if (!meta) continue;
-    if (meta.retryOf) {
-      retries.push({
-        runId,
-        retryOf: meta.retryOf,
-        attempt: meta.attempt,
-        source: "manual",
-        confidence: "explicit"
-      });
-      continue;
-    }
-    if (meta.attempt !== void 0 && meta.attempt > 1) {
-      retries.push({
-        runId,
-        attempt: meta.attempt,
-        source: "inferred",
-        confidence: "correlated"
-      });
-      warnings.push({
-        code: "ambiguous-retry-link",
-        message: "attempt > 1 without retryOf; retry link is correlated only.",
-        runId,
-        sessionId
-      });
+function earliestStart(runs) {
+  let earliest;
+  for (const run of runs) {
+    if (run.startedAt === void 0) continue;
+    if (earliest === void 0 || run.startedAt < earliest) {
+      earliest = run.startedAt;
     }
   }
-  return retries.sort((a, b) => a.runId.localeCompare(b.runId));
+  return earliest;
 }
-function buildCriticalPath(runs, handoffs) {
-  const runById = new Map(runs.map((run) => [run.runId, run]));
-  const explicitTargets = new Set(
-    handoffs.filter((edge) => edge.confidence === "explicit").map((edge) => edge.to)
-  );
-  const explicitSources = new Set(
-    handoffs.filter((edge) => edge.confidence === "explicit").map((edge) => edge.from)
-  );
-  const ordered = [...runs].sort(compareRuns);
-  const path18 = [];
-  const visited = /* @__PURE__ */ new Set();
-  const pushRun = (run, confidence, source) => {
-    if (visited.has(run.runId)) return;
-    visited.add(run.runId);
-    path18.push({
-      runId: run.runId,
-      name: run.name,
-      startedAt: run.startedAt,
-      durationMs: run.durationMs,
-      confidence,
-      source
-    });
-  };
-  for (const edge of handoffs) {
-    if (edge.confidence !== "explicit") continue;
-    const fromRun = [...runById.values()].find(
-      (run) => run.runId === edge.from || metaRunIdMatches(run, edge.from, runById)
-    );
-    const toRun = [...runById.values()].find(
-      (run) => run.runId === edge.to || metaRunIdMatches(run, edge.to, runById)
-    );
-    if (fromRun) pushRun(fromRun, "explicit", "manual");
-    if (toRun) pushRun(toRun, "explicit", "manual");
-  }
-  for (const run of ordered) {
-    if (visited.has(run.runId)) continue;
-    const confidence = explicitTargets.has(run.runId) || explicitSources.has(run.runId) ? "explicit" : "correlated";
-    pushRun(run, confidence, confidence === "explicit" ? "manual" : "inferred");
+function latestEndWhenAllEnded(runs) {
+  if (runs.length === 0) return void 0;
+  let latest;
+  for (const run of runs) {
+    if (run.endedAt === void 0) return void 0;
+    if (latest === void 0 || run.endedAt > latest) latest = run.endedAt;
   }
-  return path18;
-}
-function metaRunIdMatches(run, token, runById) {
-  const meta = extractSessionWorkflowMetadata(run.metadata);
-  return meta?.subAgentId === token || meta?.groupId === token || runById.has(token);
+  return latest;
 }
-function buildSessionIndex(inputRuns, options = {}) {
-  const warnings = [];
-  const runs = [...inputRuns].sort(compareRuns);
-  const metaByRunId = /* @__PURE__ */ new Map();
+function pickExplicitStatus(runs) {
+  let best;
+  let bestPriority = 0;
   for (const run of runs) {
-    metaByRunId.set(run.runId, extractSessionWorkflowMetadata(run.metadata));
+    const raw = run.metadata?.sessionStatus;
+    if (!isExplicitSessionStatus(raw)) continue;
+    const priority = EXPLICIT_STATUS_PRIORITY[raw] ?? 0;
+    if (priority > bestPriority) {
+      bestPriority = priority;
+      best = raw;
+    }
   }
-  const sessionsByKey = /* @__PURE__ */ new Map();
-  const unscopedRunIds = [];
+  return best;
+}
+function deriveLastError(runs) {
+  const errorRuns = runs.filter((run) => run.status === "error").sort((a, b) => activityMs(b) - activityMs(a));
+  const latest = errorRuns[0];
+  if (!latest) return void 0;
+  const meta = latest.metadata ?? {};
+  const message = typeof meta.errorMessage === "string" && meta.errorMessage.trim() !== "" ? meta.errorMessage.trim() : latest.name ?? latest.runId;
+  const code = typeof meta.errorCode === "string" && meta.errorCode.trim() !== "" ? meta.errorCode.trim() : void 0;
+  return { runId: latest.runId, message, code };
+}
+function deriveCheckSummary(runs) {
+  let pass = 0;
+  let fail = 0;
+  let warn2 = 0;
+  let found = false;
   for (const run of runs) {
-    const meta = metaByRunId.get(run.runId);
-    const key = sessionKeyForRun(meta, {
-      correlateByGroupId: options.correlateByGroupId === true
-    });
-    if (!key) {
-      unscopedRunIds.push(run.runId);
-      continue;
+    const summary = run.metadata?.checkSummary;
+    if (!summary || typeof summary !== "object") continue;
+    const record = summary;
+    if (typeof record.pass === "number") {
+      pass += record.pass;
+      found = true;
+    }
+    if (typeof record.fail === "number") {
+      fail += record.fail;
+      found = true;
+    }
+    if (typeof record.warn === "number") {
+      warn2 += record.warn;
+      found = true;
     }
-    const bucket = sessionsByKey.get(key) ?? [];
-    bucket.push(run);
-    sessionsByKey.set(key, bucket);
   }
-  const sessions = [...sessionsByKey.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([sessionId, sessionRuns]) => {
-    const runIds = sessionRuns.map((run) => run.runId).sort();
-    const handoffs = buildHandoffs(runIds, metaByRunId, warnings, sessionId);
-    const retries = buildRetries(runIds, metaByRunId, warnings, sessionId);
-    const groups = buildGroups(runIds, metaByRunId);
-    const criticalPath = buildCriticalPath(sessionRuns, handoffs);
-    const confidences = new Set(handoffs.map((edge) => edge.confidence));
-    if (confidences.has("explicit") && confidences.has("correlated")) {
-      warnings.push({
-        code: "mixed-confidence-group",
-        message: "Session aggregates explicit and correlated handoff edges.",
-        sessionId
-      });
+  return found ? { pass, fail, warn: warn2 } : void 0;
+}
+function deriveObservationSummary(runs) {
+  for (const run of [...runs].sort((a, b) => activityMs(b) - activityMs(a))) {
+    const value = run.metadata?.observationSummary;
+    if (typeof value === "string" && value.trim() !== "") {
+      return value.trim();
     }
-    return enrichSessionSummary(
-      {
-        sessionId,
-        runIds,
-        groups,
-        handoffs,
-        retries,
-        criticalPath
-      },
-      runs,
-      {
-        nowMs: options.nowMs,
-        staleThresholdMs: options.staleThresholdMs
-      }
-    );
-  });
-  if (sessions.length === 0 && runs.length > 0) {
-    warnings.push({
-      code: "missing-session-id",
-      message: "No sessionId (or correlated groupId) found on input runs."
-    });
   }
-  warnings.sort((a, b) => {
-    const code = a.code.localeCompare(b.code);
-    if (code !== 0) return code;
-    return (a.runId ?? "").localeCompare(b.runId ?? "");
-  });
+  return void 0;
+}
+function deriveSessionStatus(runs, options = {}) {
+  if (runs.length === 0) return "unknown";
+  if (runs.some((run) => run.status === "running")) return "running";
+  const explicit = pickExplicitStatus(runs);
+  if (explicit && explicit !== "running") return explicit;
+  if (runs.some((run) => run.status === "error")) return "error";
+  if (runs.every((run) => run.status === "success")) return "completed";
+  const nowMs = options.nowMs ?? Date.now();
+  const staleThresholdMs = options.staleThresholdMs ?? DEFAULT_STALE_THRESHOLD_MS;
+  const lastMs = latestActivityMs(runs);
+  if (lastMs > 0 && nowMs - lastMs > staleThresholdMs) return "stale";
+  return "unknown";
+}
+function enrichSessionSummary(summary, runs, options = {}) {
+  const sessionRuns = runs.filter((run) => summary.runIds.includes(run.runId)).sort((a, b) => a.runId.localeCompare(b.runId));
+  const startedAt = earliestStart(sessionRuns);
+  const endedAt = latestEndWhenAllEnded(sessionRuns);
+  const durationMs = startedAt !== void 0 && endedAt !== void 0 ? endedAt - startedAt : void 0;
+  let correlationId;
+  let jobId;
+  let workflowId;
+  for (const run of sessionRuns) {
+    const meta = extractSessionWorkflowMetadata(run.metadata);
+    if (!correlationId && meta?.correlationId) correlationId = meta.correlationId;
+    if (!jobId && meta?.jobId) jobId = meta.jobId;
+    if (!workflowId && meta?.workflowName) workflowId = meta.workflowName;
+    else if (!workflowId && meta?.workflowStep) workflowId = meta.workflowStep;
+  }
+  const lastMs = latestActivityMs(sessionRuns);
+  const lastActivity = lastMs > 0 ? new Date(lastMs).toISOString() : (/* @__PURE__ */ new Date(0)).toISOString();
+  const retryCount2 = summary.retries.filter(
+    (retry) => retry.retryOf !== void 0 || (retry.attempt ?? 0) > 1
+  ).length;
   return {
-    runs,
-    sessions,
-    unscopedRunIds: unscopedRunIds.sort(),
-    warnings
+    ...summary,
+    status: deriveSessionStatus(sessionRuns, options),
+    startedAt,
+    endedAt,
+    durationMs,
+    correlationId,
+    jobId,
+    workflowId,
+    lastError: deriveLastError(sessionRuns),
+    lastActivity,
+    retryCount: retryCount2,
+    observationSummary: deriveObservationSummary(sessionRuns),
+    checkSummary: deriveCheckSummary(sessionRuns)
   };
 }
 
-// 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"]
-  },
-  AI_TRACE_CONTRACT_INPUT_INVALID: {
-    code: "AI_TRACE_CONTRACT_INPUT_INVALID",
-    summary: "evaluateTraceContract expects ({ read }, contract) or use evaluateTraceContractRead(read, contract).",
-    remediation: "Pass TraceCheckInput as the first argument: evaluateTraceContract({ read }, contract).",
-    relatedCodes: ["AI_CHECK_INVALID_ARGUMENTS"]
-  },
-  AI_INSPECT_RUN_UNSUPPORTED_OPTION: {
-    code: "AI_INSPECT_RUN_UNSUPPORTED_OPTION",
-    summary: 'inspectRun does not accept a "writer" option.',
-    remediation: "Use createInspector({ writer }) then inspector.run(...). inspectRun persists via the global JSONL path (schema 0.1)."
+// packages/core/src/sessions/load.ts
+async function enrichSessionRunRecord(meta) {
+  let metadata;
+  try {
+    const events = await readTraceEventsFromFile(meta.filePath);
+    for (const event of events) {
+      if (event.event !== "run_started") continue;
+      if (event.metadata && typeof event.metadata === "object") {
+        metadata = event.metadata;
+      }
+      break;
+    }
+  } catch {
   }
-});
-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 isRecord5(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function legacyEvent(event) {
-  const value = event.attributes?.legacyEvent;
-  return typeof value === "string" ? value : void 0;
-}
-function stepIdOf(event) {
-  const value = event.attributes?.stepId;
-  if (typeof value === "string" && value.trim() !== "") return value;
-  return void 0;
-}
-function cloneEvent(event) {
   return {
-    ...event,
-    ...event.attributes !== void 0 ? { attributes: { ...event.attributes } } : {},
-    ...event.error !== void 0 ? { error: { ...event.error } } : {},
-    ...event.tokenUsage !== void 0 ? { tokenUsage: { ...event.tokenUsage } } : {},
-    ...event.source !== void 0 ? { source: { ...event.source } } : {}
+    runId: meta.runId,
+    name: meta.name,
+    status: meta.status,
+    startedAt: meta.startedAt,
+    endedAt: meta.endedAt,
+    durationMs: meta.durationMs,
+    filePath: meta.filePath,
+    metadata
   };
 }
-function mergeAttributes(start, complete) {
-  const merged = {
-    ...isRecord5(complete.attributes) ? complete.attributes : {},
-    ...isRecord5(start.attributes) ? start.attributes : {}
-  };
-  merged.legacyEvent = start.attributes?.legacyEvent ?? complete.attributes?.legacyEvent;
-  merged.legacyCompleteEvent = complete.attributes?.legacyEvent;
-  if (complete.attributes?.errorStack !== void 0) {
-    merged.errorStack = complete.attributes.errorStack;
+async function loadSessionRunRecords(metas) {
+  const out = [];
+  for (const meta of metas) {
+    out.push(await enrichSessionRunRecord(meta));
   }
-  return Object.keys(merged).length > 0 ? merged : void 0;
+  return out;
 }
-function pairStartComplete(start, complete) {
-  const attributes = mergeAttributes(start, complete);
-  const paired = {
-    ...cloneEvent(start),
-    status: complete.status,
-    timestamp: complete.timestamp ?? start.timestamp,
-    ...complete.endedAt !== void 0 ? { endedAt: complete.endedAt } : {},
-    ...complete.durationMs !== void 0 ? { durationMs: complete.durationMs } : {},
-    ...complete.error !== void 0 ? { error: { ...complete.error } } : {},
-    ...complete.tokenUsage !== void 0 && start.tokenUsage === void 0 ? { tokenUsage: { ...complete.tokenUsage } } : {},
-    ...attributes !== void 0 ? { attributes } : {}
-  };
-  return {
-    ...paired,
-    sourceEventIds: Object.freeze([start.eventId, complete.eventId]),
-    projection: {
-      paired: true,
-      absorbedEventIds: Object.freeze([complete.eventId]),
-      parentNormalized: false,
-      ...start.parentId !== void 0 ? { originalParentId: start.parentId } : {}
+
+// packages/core/src/sessions/index.ts
+function compareRuns(a, b) {
+  const aStart = a.startedAt ?? 0;
+  const bStart = b.startedAt ?? 0;
+  if (aStart !== bStart) return aStart - bStart;
+  return a.runId.localeCompare(b.runId);
+}
+function buildGroups(runIds, metaByRunId) {
+  const byGroup = /* @__PURE__ */ new Map();
+  for (const runId of runIds) {
+    const groupId = metaByRunId.get(runId)?.groupId;
+    if (!groupId) continue;
+    const existing = byGroup.get(groupId);
+    if (existing) {
+      existing.runIds.push(runId);
+    } else {
+      byGroup.set(groupId, {
+        groupId,
+        parentGroupId: metaByRunId.get(runId)?.parentGroupId,
+        runIds: [runId]
+      });
     }
-  };
+  }
+  return [...byGroup.values()].map((group) => ({
+    ...group,
+    runIds: [...group.runIds].sort((a, b) => a.localeCompare(b))
+  }));
 }
-function asLogical(event, extras) {
-  return {
-    ...cloneEvent(event),
-    sourceEventIds: Object.freeze([event.eventId]),
-    projection: {
-      paired: false,
-      absorbedEventIds: Object.freeze([]),
-      parentNormalized: extras?.parentNormalized === true,
-      ...{}
-    }
+function buildHandoffs(runIds, metaByRunId, warnings, sessionId) {
+  const edges = [];
+  const seen = /* @__PURE__ */ new Set();
+  const pushEdge = (edge) => {
+    const key = `${edge.from}->${edge.to}:${edge.confidence}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    edges.push(edge);
   };
-}
-function projectLogicalEvents(events) {
-  const diagnostics = [];
-  const byRun = /* @__PURE__ */ new Map();
-  for (const event of events) {
-    const list = byRun.get(event.runId) ?? [];
-    list.push(event);
-    byRun.set(event.runId, list);
-  }
-  const absorbedIds = /* @__PURE__ */ new Set();
-  const logicalByRawId = /* @__PURE__ */ new Map();
-  const stepIdToLogicalId = /* @__PURE__ */ new Map();
-  const logical = [];
-  const orderedRuns = [...byRun.keys()].sort((a, b) => a.localeCompare(b));
-  for (const runId of orderedRuns) {
-    const runEvents = byRun.get(runId) ?? [];
-    const starts = [];
-    const completes = [];
-    const others = [];
-    for (const event of runEvents) {
-      const legacy = legacyEvent(event);
-      if (legacy === "step_started" || legacy === "run_started" && event.status === "running") {
-        starts.push(event);
-      } else if (legacy === "step_completed" || legacy === "run_completed") {
-        completes.push(event);
-      } else {
-        others.push(event);
-      }
+  for (const runId of runIds) {
+    const meta = metaByRunId.get(runId);
+    if (!meta) continue;
+    if (meta.handoffFrom && meta.handoffTo) {
+      pushEdge({
+        from: meta.handoffFrom,
+        to: meta.handoffTo,
+        source: "manual",
+        confidence: "explicit"
+      });
+      continue;
     }
-    const usedCompletes = /* @__PURE__ */ new Set();
-    for (const start of starts) {
-      const stepId = stepIdOf(start);
-      let match;
-      if (legacyEvent(start) === "run_started") {
-        const candidates = completes.filter(
-          (c) => !usedCompletes.has(c.eventId) && legacyEvent(c) === "run_completed"
-        );
-        if (candidates.length > 1) {
-          diagnostics.push({
-            code: "AI_LOGICAL_PAIR_AMBIGUOUS",
-            message: `Multiple run_completed rows for run ${runId}; using first by eventId.`,
-            eventIds: candidates.map((c) => c.eventId)
-          });
-          candidates.sort((a, b) => a.eventId.localeCompare(b.eventId));
-        }
-        match = candidates[0];
-      } else if (stepId) {
-        const candidates = completes.filter(
-          (c) => !usedCompletes.has(c.eventId) && legacyEvent(c) === "step_completed" && stepIdOf(c) === stepId
-        );
-        if (candidates.length > 1) {
-          diagnostics.push({
-            code: "AI_LOGICAL_PAIR_AMBIGUOUS",
-            message: `Multiple step_completed rows for stepId ${stepId}; using first by eventId.`,
-            eventIds: candidates.map((c) => c.eventId)
-          });
-          candidates.sort((a, b) => a.eventId.localeCompare(b.eventId));
-        }
-        match = candidates[0];
-      }
-      if (match) {
-        usedCompletes.add(match.eventId);
-        absorbedIds.add(match.eventId);
-        const paired = pairStartComplete(start, match);
-        logical.push(paired);
-        logicalByRawId.set(start.eventId, paired);
-        logicalByRawId.set(match.eventId, paired);
-        if (stepId) stepIdToLogicalId.set(`${runId}:${stepId}`, paired.eventId);
-      } else {
-        diagnostics.push({
-          code: "AI_LOGICAL_PAIR_UNMATCHED_START",
-          message: `No matching complete for start ${start.eventId}.`,
-          eventIds: [start.eventId]
-        });
-        const alone = asLogical(start);
-        logical.push(alone);
-        logicalByRawId.set(start.eventId, alone);
-        if (stepId) stepIdToLogicalId.set(`${runId}:${stepId}`, alone.eventId);
-      }
+    if (meta.handoffFrom) {
+      pushEdge({
+        from: meta.handoffFrom,
+        to: runId,
+        source: "manual",
+        confidence: "explicit"
+      });
     }
-    for (const complete of completes) {
-      if (usedCompletes.has(complete.eventId)) continue;
-      diagnostics.push({
-        code: "AI_LOGICAL_PAIR_UNMATCHED_COMPLETE",
-        message: `No matching start for complete ${complete.eventId}.`,
-        eventIds: [complete.eventId]
+    if (meta.handoffTo) {
+      pushEdge({
+        from: runId,
+        to: meta.handoffTo,
+        source: "manual",
+        confidence: "explicit"
       });
-      const alone = asLogical(complete);
-      logical.push(alone);
-      logicalByRawId.set(complete.eventId, alone);
-      const stepId = stepIdOf(complete);
-      if (stepId && !stepIdToLogicalId.has(`${runId}:${stepId}`)) {
-        stepIdToLogicalId.set(`${runId}:${stepId}`, alone.eventId);
-      }
     }
-    for (const event of others) {
-      const alone = asLogical(event);
-      logical.push(alone);
-      logicalByRawId.set(event.eventId, alone);
-      const stepId = stepIdOf(event);
-      if (stepId && !stepIdToLogicalId.has(`${runId}:${stepId}`)) {
-        stepIdToLogicalId.set(`${runId}:${stepId}`, alone.eventId);
-      }
+    if (meta.subAgentId && meta.parentGroupId && !meta.handoffFrom && !meta.handoffTo) {
+      pushEdge({
+        from: meta.parentGroupId,
+        to: meta.subAgentId,
+        source: "inferred",
+        confidence: "correlated"
+      });
+      warnings.push({
+        code: "ambiguous-handoff-endpoints",
+        message: "Handoff inferred from parentGroupId and subAgentId without explicit handoffFrom/handoffTo.",
+        runId,
+        sessionId
+      });
     }
   }
-  const logicalById = new Map(logical.map((e) => [e.eventId, e]));
-  const normalized = [];
-  for (const event of logical) {
-    const originalParentId = event.parentId;
-    if (!originalParentId) {
-      normalized.push(event);
+  return edges.sort((a, b) => {
+    const from = a.from.localeCompare(b.from);
+    if (from !== 0) return from;
+    return a.to.localeCompare(b.to);
+  });
+}
+function buildRetries(runIds, metaByRunId, warnings, sessionId) {
+  const retries = [];
+  for (const runId of runIds) {
+    const meta = metaByRunId.get(runId);
+    if (!meta) continue;
+    if (meta.retryOf) {
+      retries.push({
+        runId,
+        retryOf: meta.retryOf,
+        attempt: meta.attempt,
+        source: "manual",
+        confidence: "explicit"
+      });
       continue;
     }
-    let nextParent = originalParentId;
-    let remapped = false;
-    const viaAbsorbed = logicalByRawId.get(originalParentId);
-    if (viaAbsorbed && viaAbsorbed.eventId !== originalParentId) {
-      nextParent = viaAbsorbed.eventId;
-      remapped = true;
-    } else if (!logicalById.has(originalParentId)) {
-      const viaStep = stepIdToLogicalId.get(`${event.runId}:${originalParentId}`);
-      if (viaStep) {
-        nextParent = viaStep;
-        remapped = true;
-      }
+    if (meta.attempt !== void 0 && meta.attempt > 1) {
+      retries.push({
+        runId,
+        attempt: meta.attempt,
+        source: "inferred",
+        confidence: "correlated"
+      });
+      warnings.push({
+        code: "ambiguous-retry-link",
+        message: "attempt > 1 without retryOf; retry link is correlated only.",
+        runId,
+        sessionId
+      });
     }
-    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.
-        /^LangGraph$/i.test(originalParentId) || originalParentId.startsWith("unresolved:");
-        if (!unresolved) {
-          diagnostics.push({
-            code: "AI_LOGICAL_PARENT_UNRESOLVED",
-            message: `Parent ${originalParentId} unresolved for ${event.eventId}.`,
-            eventIds: [event.eventId]
-          });
-        }
-      }
-      normalized.push(event);
+  }
+  return retries.sort((a, b) => a.runId.localeCompare(b.runId));
+}
+function buildCriticalPath(runs, handoffs) {
+  const runById = new Map(runs.map((run) => [run.runId, run]));
+  const explicitTargets = new Set(
+    handoffs.filter((edge) => edge.confidence === "explicit").map((edge) => edge.to)
+  );
+  const explicitSources = new Set(
+    handoffs.filter((edge) => edge.confidence === "explicit").map((edge) => edge.from)
+  );
+  const ordered = [...runs].sort(compareRuns);
+  const path18 = [];
+  const visited = /* @__PURE__ */ new Set();
+  const pushRun = (run, confidence, source) => {
+    if (visited.has(run.runId)) return;
+    visited.add(run.runId);
+    path18.push({
+      runId: run.runId,
+      name: run.name,
+      startedAt: run.startedAt,
+      durationMs: run.durationMs,
+      confidence,
+      source
+    });
+  };
+  for (const edge of handoffs) {
+    if (edge.confidence !== "explicit") continue;
+    const fromRun = [...runById.values()].find(
+      (run) => run.runId === edge.from || metaRunIdMatches(run, edge.from, runById)
+    );
+    const toRun = [...runById.values()].find(
+      (run) => run.runId === edge.to || metaRunIdMatches(run, edge.to, runById)
+    );
+    if (fromRun) pushRun(fromRun, "explicit", "manual");
+    if (toRun) pushRun(toRun, "explicit", "manual");
+  }
+  for (const run of ordered) {
+    if (visited.has(run.runId)) continue;
+    const confidence = explicitTargets.has(run.runId) || explicitSources.has(run.runId) ? "explicit" : "correlated";
+    pushRun(run, confidence, confidence === "explicit" ? "manual" : "inferred");
+  }
+  return path18;
+}
+function metaRunIdMatches(run, token, runById) {
+  const meta = extractSessionWorkflowMetadata(run.metadata);
+  return meta?.subAgentId === token || meta?.groupId === token || runById.has(token);
+}
+function buildSessionIndex(inputRuns, options = {}) {
+  const warnings = [];
+  const runs = [...inputRuns].sort(compareRuns);
+  const metaByRunId = /* @__PURE__ */ new Map();
+  for (const run of runs) {
+    metaByRunId.set(run.runId, extractSessionWorkflowMetadata(run.metadata));
+  }
+  const sessionsByKey = /* @__PURE__ */ new Map();
+  const unscopedRunIds = [];
+  for (const run of runs) {
+    const meta = metaByRunId.get(run.runId);
+    const key = sessionKeyForRun(meta, {
+      correlateByGroupId: options.correlateByGroupId === true
+    });
+    if (!key) {
+      unscopedRunIds.push(run.runId);
       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
-        }
+    const bucket = sessionsByKey.get(key) ?? [];
+    bucket.push(run);
+    sessionsByKey.set(key, bucket);
+  }
+  const sessions = [...sessionsByKey.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([sessionId, sessionRuns]) => {
+    const runIds = sessionRuns.map((run) => run.runId).sort();
+    const handoffs = buildHandoffs(runIds, metaByRunId, warnings, sessionId);
+    const retries = buildRetries(runIds, metaByRunId, warnings, sessionId);
+    const groups = buildGroups(runIds, metaByRunId);
+    const criticalPath = buildCriticalPath(sessionRuns, handoffs);
+    const confidences = new Set(handoffs.map((edge) => edge.confidence));
+    if (confidences.has("explicit") && confidences.has("correlated")) {
+      warnings.push({
+        code: "mixed-confidence-group",
+        message: "Session aggregates explicit and correlated handoff edges.",
+        sessionId
       });
-      continue;
     }
-    diagnostics.push({
-      code: "AI_LOGICAL_PARENT_REMAPPED",
-      message: `Remapped parent ${originalParentId} \u2192 ${nextParent} for ${event.eventId}.`,
-      eventIds: [event.eventId]
-    });
-    normalized.push({
-      ...event,
-      parentId: nextParent,
-      projection: {
-        ...event.projection,
-        parentNormalized: true,
-        originalParentId
+    return enrichSessionSummary(
+      {
+        sessionId,
+        runIds,
+        groups,
+        handoffs,
+        retries,
+        criticalPath
+      },
+      runs,
+      {
+        nowMs: options.nowMs,
+        staleThresholdMs: options.staleThresholdMs
       }
+    );
+  });
+  if (sessions.length === 0 && runs.length > 0) {
+    warnings.push({
+      code: "missing-session-id",
+      message: "No sessionId (or correlated groupId) found on input runs."
     });
   }
-  const rawIndex = new Map(events.map((e, i) => [e.eventId, i]));
-  normalized.sort((a, b) => {
-    const ai = rawIndex.get(a.sourceEventIds[0]) ?? 0;
-    const bi = rawIndex.get(b.sourceEventIds[0]) ?? 0;
-    return ai - bi || a.eventId.localeCompare(b.eventId);
+  warnings.sort((a, b) => {
+    const code = a.code.localeCompare(b.code);
+    if (code !== 0) return code;
+    return (a.runId ?? "").localeCompare(b.runId ?? "");
   });
   return {
-    logicalEvents: Object.freeze(normalized),
-    diagnostics: Object.freeze(diagnostics)
+    runs,
+    sessions,
+    unscopedRunIds: unscopedRunIds.sort(),
+    warnings
   };
 }
-function resolveCanonicalToolName(event) {
-  const attrs = event.attributes;
-  const direct = pickString(attrs, ["toolName", "tool"]);
-  if (direct) return direct;
-  const metadata = attrs?.metadata;
-  if (isRecord5(metadata)) {
-    const nested = pickString(metadata, ["toolName", "tool"]);
-    if (nested) return nested;
-  }
-  for (const prefix of ["tool:", "function:", "mcp-tools:"]) {
-    if (event.name.startsWith(prefix)) return event.name.slice(prefix.length);
-  }
-  return event.name;
-}
-function pickString(record, keys) {
-  if (!record) return void 0;
-  for (const key of keys) {
-    const value = record[key];
-    if (typeof value === "string" && value.trim() !== "") return value.trim();
-  }
-  return void 0;
-}
 
 // packages/core/src/checks/trace-facts.ts
 formatProgrammaticDiagnostic(
@@ -2068,7 +2068,11 @@ function emptySummary() {
     failed: 0,
     warnings: 0,
     errors: 0,
-    rulesEvaluated: 0
+    rulesEvaluated: 0,
+    rulesPassed: 0,
+    rulesWarning: 0,
+    rulesFailed: 0,
+    rulesError: 0
   };
 }
 function errorResult(input, diagnostics, selectedRun, ruleExecutions = []) {
@@ -2080,7 +2084,11 @@ function errorResult(input, diagnostics, selectedRun, ruleExecutions = []) {
     summary: {
       ...emptySummary(),
       errors: diagnostics.filter((item) => item.severity === "error").length,
-      rulesEvaluated: ruleExecutions.length
+      rulesEvaluated: ruleExecutions.length,
+      rulesPassed: ruleExecutions.filter((item) => item.status === "pass").length,
+      rulesWarning: ruleExecutions.filter((item) => item.status === "warning").length,
+      rulesFailed: ruleExecutions.filter((item) => item.status === "fail").length,
+      rulesError: ruleExecutions.filter((item) => item.status === "error").length
     },
     findings: [],
     diagnostics: [...diagnostics],
@@ -2240,7 +2248,7 @@ function normalizeFinding(rule, finding) {
     ...finding.action !== void 0 ? { action: finding.action } : {}
   };
 }
-function summarize(findings, diagnostics, rulesEvaluated) {
+function summarize(findings, diagnostics, ruleExecutions) {
   return {
     passed: findings.filter((finding) => finding.status === "pass").length,
     failed: findings.filter(
@@ -2250,7 +2258,11 @@ function summarize(findings, diagnostics, rulesEvaluated) {
       (finding) => finding.status === "warning" || finding.severity === "warning"
     ).length,
     errors: diagnostics.filter((item) => item.severity === "error").length,
-    rulesEvaluated
+    rulesEvaluated: ruleExecutions.length,
+    rulesPassed: ruleExecutions.filter((item) => item.status === "pass").length,
+    rulesWarning: ruleExecutions.filter((item) => item.status === "warning").length,
+    rulesFailed: ruleExecutions.filter((item) => item.status === "fail").length,
+    rulesError: ruleExecutions.filter((item) => item.status === "error").length
   };
 }
 function classifyRuleExecution(findings, threw) {
@@ -2727,7 +2739,7 @@ function runTraceChecks(input, options = {}) {
   }
   const eventById = new Map(input.read.events.map((event) => [event.eventId, event]));
   const sortedFindings = findings.sort(compareFindings(eventById));
-  const summary = summarize(sortedFindings, diagnostics, ruleExecutions.length);
+  const summary = summarize(sortedFindings, diagnostics, ruleExecutions);
   const status = summary.failed > 0 ? "fail" : "pass";
   return {
     ok: status === "pass",
@@ -3162,10 +3174,143 @@ function asStringArray(value, label) {
 function asPositiveNumber(value, label) {
   if (value === void 0) return void 0;
   if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
-    throw new Error(`${label} must be a non-negative number.`);
+    throw new Error(`${label} must be a non-negative finite number.`);
+  }
+  return value;
+}
+function asBoolean(value, label) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "boolean") {
+    throw new Error(`${label} must be a boolean (not a string or other type).`);
+  }
+  return value;
+}
+function assertObject(value, label) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(`${label} must be an object.`);
   }
   return value;
 }
+function assertKnownKeys(raw, allowed, label) {
+  const allowedSet = new Set(allowed);
+  for (const key of Object.keys(raw)) {
+    if (!allowedSet.has(key)) {
+      throw new Error(`${label} has unknown key "${key}".`);
+    }
+  }
+}
+var CASE_KEYS = [
+  "id",
+  "trace",
+  "runId",
+  "input",
+  "requireTools",
+  "forbidTools",
+  "maxDurationMs",
+  "expectedObservations",
+  "expect"
+];
+var EXPECT_KEYS = [
+  "checkStatus",
+  "findingRuleIds",
+  "rejectUnexpectedFindings",
+  "minAssertions"
+];
+var CHECKS_KEYS = ["select", "run", "tool", "llm"];
+var CHECKS_RUN_KEYS = ["maxDurationMs", "maxDepth"];
+var CHECKS_TOOL_KEYS = ["required", "forbidden"];
+var CHECKS_LLM_KEYS = ["allowedModels", "maxTotalTokens"];
+var EVAL_KEYS = [
+  "requireSuccess",
+  "requiredTools",
+  "forbiddenTools",
+  "maxDurationMs",
+  "maxDepth",
+  "maxRetries",
+  "maxTotalTokens"
+];
+var ROOT_KEYS = [
+  "name",
+  "traces",
+  "cases",
+  "checks",
+  "eval",
+  "redactionProfile",
+  "artifacts",
+  "baseline",
+  "candidate"
+];
+function asExpectConfig(value, label) {
+  if (value === void 0) return void 0;
+  const raw = assertObject(value, label);
+  assertKnownKeys(raw, EXPECT_KEYS, label);
+  const checkStatus = raw.checkStatus;
+  if (checkStatus !== "pass" && checkStatus !== "fail" && checkStatus !== "error") {
+    throw new Error(`${label}.checkStatus must be "pass", "fail", or "error".`);
+  }
+  const findingRuleIds = asStringArray(raw.findingRuleIds, `${label}.findingRuleIds`);
+  const minAssertions = asPositiveNumber(raw.minAssertions, `${label}.minAssertions`);
+  const rejectUnexpectedFindings = asBoolean(
+    raw.rejectUnexpectedFindings,
+    `${label}.rejectUnexpectedFindings`
+  );
+  return {
+    checkStatus,
+    ...findingRuleIds !== void 0 ? { findingRuleIds } : {},
+    ...rejectUnexpectedFindings !== void 0 ? { rejectUnexpectedFindings } : {},
+    ...minAssertions !== void 0 ? { minAssertions } : {}
+  };
+}
+function asChecksConfig(value, label) {
+  const raw = assertObject(value, label);
+  assertKnownKeys(raw, CHECKS_KEYS, label);
+  const checks = {};
+  const select = asStringArray(raw.select, `${label}.select`);
+  if (select !== void 0) checks.select = select;
+  if (raw.run !== void 0) {
+    const run = assertObject(raw.run, `${label}.run`);
+    assertKnownKeys(run, CHECKS_RUN_KEYS, `${label}.run`);
+    checks.run = {
+      ...asPositiveNumber(run.maxDurationMs, `${label}.run.maxDurationMs`) !== void 0 ? { maxDurationMs: asPositiveNumber(run.maxDurationMs, `${label}.run.maxDurationMs`) } : {},
+      ...asPositiveNumber(run.maxDepth, `${label}.run.maxDepth`) !== void 0 ? { maxDepth: asPositiveNumber(run.maxDepth, `${label}.run.maxDepth`) } : {}
+    };
+  }
+  if (raw.tool !== void 0) {
+    const tool = assertObject(raw.tool, `${label}.tool`);
+    assertKnownKeys(tool, CHECKS_TOOL_KEYS, `${label}.tool`);
+    checks.tool = {
+      ...asStringArray(tool.required, `${label}.tool.required`) !== void 0 ? { required: asStringArray(tool.required, `${label}.tool.required`) } : {},
+      ...asStringArray(tool.forbidden, `${label}.tool.forbidden`) !== void 0 ? { forbidden: asStringArray(tool.forbidden, `${label}.tool.forbidden`) } : {}
+    };
+  }
+  if (raw.llm !== void 0) {
+    const llm = assertObject(raw.llm, `${label}.llm`);
+    assertKnownKeys(llm, CHECKS_LLM_KEYS, `${label}.llm`);
+    checks.llm = {
+      ...asStringArray(llm.allowedModels, `${label}.llm.allowedModels`) !== void 0 ? { allowedModels: asStringArray(llm.allowedModels, `${label}.llm.allowedModels`) } : {},
+      ...asPositiveNumber(llm.maxTotalTokens, `${label}.llm.maxTotalTokens`) !== void 0 ? {
+        maxTotalTokens: asPositiveNumber(
+          llm.maxTotalTokens,
+          `${label}.llm.maxTotalTokens`
+        )
+      } : {}
+    };
+  }
+  return checks;
+}
+function asEvalConfig(value, label) {
+  const raw = assertObject(value, label);
+  assertKnownKeys(raw, EVAL_KEYS, label);
+  return {
+    ...asBoolean(raw.requireSuccess, `${label}.requireSuccess`) !== void 0 ? { requireSuccess: asBoolean(raw.requireSuccess, `${label}.requireSuccess`) } : {},
+    ...asStringArray(raw.requiredTools, `${label}.requiredTools`) !== void 0 ? { requiredTools: asStringArray(raw.requiredTools, `${label}.requiredTools`) } : {},
+    ...asStringArray(raw.forbiddenTools, `${label}.forbiddenTools`) !== void 0 ? { forbiddenTools: asStringArray(raw.forbiddenTools, `${label}.forbiddenTools`) } : {},
+    ...asPositiveNumber(raw.maxDurationMs, `${label}.maxDurationMs`) !== void 0 ? { maxDurationMs: asPositiveNumber(raw.maxDurationMs, `${label}.maxDurationMs`) } : {},
+    ...asPositiveNumber(raw.maxDepth, `${label}.maxDepth`) !== void 0 ? { maxDepth: asPositiveNumber(raw.maxDepth, `${label}.maxDepth`) } : {},
+    ...asPositiveNumber(raw.maxRetries, `${label}.maxRetries`) !== void 0 ? { maxRetries: asPositiveNumber(raw.maxRetries, `${label}.maxRetries`) } : {},
+    ...asPositiveNumber(raw.maxTotalTokens, `${label}.maxTotalTokens`) !== void 0 ? { maxTotalTokens: asPositiveNumber(raw.maxTotalTokens, `${label}.maxTotalTokens`) } : {}
+  };
+}
 function validateCaseConfig(value, index) {
   const diagnostics = [];
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
@@ -3176,6 +3321,7 @@ function validateCaseConfig(value, index) {
   }
   const raw = value;
   try {
+    assertKnownKeys(raw, CASE_KEYS, `cases[${index}]`);
     const id = asString(raw.id, `cases[${index}].id`);
     if (id === void 0) {
       diagnostics.push(
@@ -3208,7 +3354,8 @@ function validateCaseConfig(value, index) {
             raw.expectedObservations,
             `cases[${index}].expectedObservations`
           )
-        } : {}
+        } : {},
+        ...asExpectConfig(raw.expect, `cases[${index}].expect`) !== void 0 ? { expect: asExpectConfig(raw.expect, `cases[${index}].expect`) } : {}
       },
       diagnostics
     };
@@ -3223,6 +3370,7 @@ function normalizeSuiteConfig(value) {
     throw new Error("Suite config must export an object.");
   }
   const raw = value;
+  assertKnownKeys(raw, ROOT_KEYS, "suite config");
   const name = asString(raw.name, "name");
   const traces = asString(raw.traces, "traces");
   if (name === void 0) throw new Error("name is required.");
@@ -3251,25 +3399,15 @@ function normalizeSuiteConfig(value) {
   }
   const config = { name, traces, cases };
   if (raw.checks !== void 0) {
-    if (typeof raw.checks !== "object" || Array.isArray(raw.checks)) {
-      throw new Error("checks must be an object.");
-    }
-    config.checks = raw.checks;
+    config.checks = asChecksConfig(raw.checks, "checks");
   }
   if (raw.eval !== void 0) {
-    if (typeof raw.eval !== "object" || Array.isArray(raw.eval)) {
-      throw new Error("eval must be an object.");
-    }
-    config.eval = raw.eval;
+    config.eval = asEvalConfig(raw.eval, "eval");
   }
   if (raw.artifacts !== void 0) {
-    if (typeof raw.artifacts !== "object" || Array.isArray(raw.artifacts)) {
-      throw new Error("artifacts must be an object.");
-    }
-    const outputDir = asString(
-      raw.artifacts.outputDir,
-      "artifacts.outputDir"
-    );
+    const artifacts = assertObject(raw.artifacts, "artifacts");
+    assertKnownKeys(artifacts, ["outputDir"], "artifacts");
+    const outputDir = asString(artifacts.outputDir, "artifacts.outputDir");
     config.artifacts = outputDir !== void 0 ? { outputDir } : {};
   }
   if (raw.baseline !== void 0) {
@@ -5794,6 +5932,78 @@ function validateExpectedObservations(suiteCase, read) {
   }
   return { ok: diagnostics.length === 0, diagnostics };
 }
+function evaluateCaseExpect(suiteCase, checkResult, observationCount) {
+  const expectation = suiteCase.expect;
+  if (expectation === void 0) {
+    return { ok: true, diagnostics: [] };
+  }
+  const diagnostics = [];
+  if (checkResult.status !== expectation.checkStatus) {
+    diagnostics.push(
+      diagnostic4(
+        "AI_SUITE_EXPECT_MISMATCH",
+        `Expected check status "${expectation.checkStatus}", got "${checkResult.status}".`,
+        "error",
+        suiteCase.id
+      )
+    );
+  }
+  const failedFindings = checkResult.findings.filter(
+    (finding) => finding.status === "fail" && finding.severity === "error"
+  );
+  const requiredIds = expectation.findingRuleIds ?? [];
+  for (const ruleId of requiredIds) {
+    if (!failedFindings.some((finding) => finding.ruleId === ruleId)) {
+      diagnostics.push(
+        diagnostic4(
+          "AI_SUITE_EXPECT_MISMATCH",
+          `Expected failing finding for rule "${ruleId}" was not present.`,
+          "error",
+          suiteCase.id
+        )
+      );
+    }
+  }
+  const rejectUnexpected = expectation.rejectUnexpectedFindings !== false;
+  if (rejectUnexpected && requiredIds.length > 0) {
+    for (const finding of failedFindings) {
+      if (!requiredIds.includes(finding.ruleId)) {
+        diagnostics.push(
+          diagnostic4(
+            "AI_SUITE_EXPECT_MISMATCH",
+            `Unexpected failing finding for rule "${finding.ruleId}".`,
+            "error",
+            suiteCase.id
+          )
+        );
+      }
+    }
+  }
+  if (expectation.minAssertions !== void 0) {
+    const assertionCount = checkResult.ruleExecutions.length + observationCount;
+    if (assertionCount < expectation.minAssertions) {
+      diagnostics.push(
+        diagnostic4(
+          "AI_SUITE_EXPECT_MISMATCH",
+          `Expected at least ${expectation.minAssertions} assertion(s), got ${assertionCount}.`,
+          "error",
+          suiteCase.id
+        )
+      );
+    }
+  }
+  if (expectation.checkStatus === "fail" && checkResult.diagnostics.some((item) => item.severity === "error") && checkResult.status === "error") {
+    diagnostics.push(
+      diagnostic4(
+        "AI_SUITE_EXPECT_MISMATCH",
+        'Check ended in evaluator/config error; semantic failure expectation requires status "fail".',
+        "error",
+        suiteCase.id
+      )
+    );
+  }
+  return { ok: diagnostics.length === 0, diagnostics };
+}
 async function runSuiteCase(suiteCase, config, options) {
   const resolved = await resolveSuiteCaseTrace(suiteCase, options);
   if (resolved.missing || resolved.tracePath === void 0) {
@@ -5846,9 +6056,21 @@ async function runSuiteCase(suiteCase, config, options) {
     status: "pass",
     format: read.format,
     findings: [],
-    diagnostics: []};
+    diagnostics: [],
+    ruleExecutions: []
+  };
   const observationResult = validateExpectedObservations(suiteCase, read);
-  const diagnostics = [
+  const checkOk = checkResult.ok;
+  const observationsOk = observationResult.ok;
+  const evalOk = config.eval?.requireSuccess === true ? checkResult.findings.every(
+    (finding) => finding.ruleId !== "run.status" || finding.status !== "fail"
+  ) && checkResult.diagnostics.every((item) => item.severity !== "error") : void 0;
+  const expectResult = evaluateCaseExpect(
+    suiteCase,
+    checkResult,
+    compiled.observationCount
+  );
+  const checkFailureDiagnostics = [
     ...checkResult.diagnostics.map(
       (item) => diagnostic4(
         "AI_SUITE_CASE_CHECK_FAILED",
@@ -5864,15 +6086,24 @@ async function runSuiteCase(suiteCase, config, options) {
         finding.severity,
         suiteCase.id
       )
-    ),
-    ...observationResult.diagnostics
+    )
   ];
-  const checkOk = checkResult.ok;
-  const observationsOk = observationResult.ok;
-  const evalOk = config.eval?.requireSuccess === true ? checkResult.findings.every(
-    (finding) => finding.ruleId !== "run.status" || finding.status !== "fail"
-  ) && checkResult.diagnostics.every((item) => item.severity !== "error") : void 0;
-  const ok = checkOk && observationsOk;
+  const expectMatched = suiteCase.expect !== void 0 && expectResult.ok && observationsOk;
+  const diagnostics = expectMatched ? [
+    ...observationResult.diagnostics,
+    ...expectResult.diagnostics,
+    diagnostic4(
+      "AI_SUITE_CASE_CHECK_FAILED",
+      `Expected semantic failure matched (check.status=${checkResult.status}).`,
+      "info",
+      suiteCase.id
+    )
+  ] : [
+    ...checkFailureDiagnostics,
+    ...observationResult.diagnostics,
+    ...expectResult.diagnostics
+  ];
+  const ok = suiteCase.expect !== void 0 ? expectResult.ok && observationsOk : checkOk && observationsOk;
   const status = ok ? "pass" : checkResult.status === "error" ? "error" : "fail";
   return {
     id: suiteCase.id,