agent-inspect 6.10.0 → 6.12.0

package/packages/core/dist/advanced.d.cts

@@ -230,7 +230,7 @@ interface TimelineOptions {
     focus?: TimelineFocus;
     slowTopN?: number;
 }
-declare function buildRunTimeline(events: TraceEvent[], options?: TimelineOptions): RunTimeline;
+declare function buildRunTimeline(events: readonly TraceEvent[], options?: TimelineOptions): RunTimeline;
 interface RenderTimelineOptions {
     focus?: TimelineFocus;
 }
@@ -276,6 +276,44 @@ interface RenderWhatOptions {
  */
 declare function renderRunWhat(summary: RunWhatSummary, options?: RenderWhatOptions): string;
 
+type CausalFailureKind = "explicit_error_event" | "failed_observed_outcome" | "contract_failure" | "failed_ancestor_or_child" | "none";
+interface CausalContractFindingInput {
+    ruleId: string;
+    status: "fail" | "pass" | "warning" | string;
+    /** Linked event/step ids from check evidence. */
+    evidenceIds?: string[];
+    message?: string;
+}
+interface FirstCausalFailure {
+    kind: CausalFailureKind;
+    /** Stable evidence ids (stepId / outcomeId / event-linked ids). No raw paths. */
+    evidenceIds: string[];
+    rationale: string;
+    /** 1–4 when matched; 0 when none. */
+    orderIndex: 0 | 1 | 2 | 3 | 4;
+    runId?: string;
+    primary?: {
+        stepId?: string;
+        outcomeId?: string;
+        ruleId?: string;
+        name?: string;
+    };
+    relationship?: {
+        role: "self" | "ancestor" | "child";
+        relatedIds: string[];
+    };
+    engine: "conservative-causal-v1";
+}
+interface FindFirstCausalFailureOptions {
+    /** Optional contract/check failures (step 3). Omitted → skip contract stage. */
+    contractFindings?: readonly CausalContractFindingInput[];
+}
+/**
+ * Find the first causal failure using the locked conservative order.
+ * Does not infer from timing correlation alone.
+ */
+declare function findFirstCausalFailure(events: readonly TraceEvent[], options?: FindFirstCausalFailureOptions): FirstCausalFailure;
+
 type ExplainMode = "dry-run" | "local";
 interface ExplainFact {
     id: string;
@@ -1374,4 +1412,4 @@ declare function renderGateGithubStepSummary(result: GateResult): string;
 declare function renderGateJUnit(result: GateResult): string;
 declare function renderGateReport(result: GateResult, options?: RenderGateReportOptions): string;
 
-export { type ActivityEntry, type ActivitySummary, type AnalyzeCohortOptions, type BuildActivitySummaryOptions, type BuildSessionIndexOptions, type BundleCheckResults, type BundleCheckRunResult, type BundleMetadata, type BundlePlaceholderArtifact, type BundleRedactionProfile, type BundleRedactionReport, type BundleRedactionReportRun, type BundleResolveOptions, type BundleResolveResult, type BundleSafeStatus, type BundleSafeStatusMetadata, COHORT_METRIC_IDS, type CohortAggregateMetrics, type CohortAnalysisResult, type CohortMetricComparison, type CohortMetricId, type CohortRunMetrics, type CriticalPathStep, DEFAULT_SUITE_ARTIFACTS_DIR, DEFAULT_SUITE_CONFIG_NAMES, DEFAULT_TRACE_DIR_NAME, type DurationStats, EVIDENCE_ASSESSMENT_NOTE, EVIDENCE_FORMAT_VERSION, EVIDENCE_HTML_FILENAME, EVIDENCE_MANIFEST_FILENAME, EVIDENCE_VIEW_CSS, EVIDENCE_VIEW_IDS, type EnrichSessionSummaryOptions, ErrorInfo, type EvidenceCheckFindingSummary, type EvidenceCiPackageFiles, type EvidenceCiPackageInput, type EvidenceContractsViewInput, type EvidenceFileEntry, type EvidenceFileRole, type EvidenceFormatVersion, type EvidenceHtmlShellInput, type EvidenceManifest, type EvidencePackagedFile, type EvidenceProvenanceViewInput, type EvidenceRedactionProfile, type EvidenceSafeStatus, type EvidenceSafetyViewInput, type EvidenceSourceHash, type EvidenceVerificationPolicy, type EvidenceVerifyIssue, type EvidenceVerifyOptions, type EvidenceVerifyResult, type EvidenceVerifyStatus, type EvidenceViewId, type ExplainFact, type ExplainInference, type ExplainMode, type ExplainOptions, type ExplainResult, FALLBACK_TRACE_DIR, type GateCheckId, type GateCheckResult, type GateExitCode, type GateResult, type GroupSessionCohortsOptions, type HandoffEdge, InspectRunTree, type LoadSuiteConfigOptions, MAX_NAME_LENGTH, MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, ObservedOutcome, type ParseTraceJsonlOptions, type ParseTraceJsonlResult, type ParsedDurationFilter, RUNS_DIR_NAME, RedactionProfile, type RenderCohortReportOptions, type RenderGateReportOptions, type RenderSuiteReportOptions, type RenderTimelineOptions, type RenderWhatOptions, type ResolvedRedactionProfile, type ResolvedSuiteCase, type RetryLink, type RunGateOptions, RunStatus, type RunSuiteOptions, RunSummary, type RunTimeline, type RunWhatSummary, SESSION_WORKFLOW_KEYS, SUITE_TEMPLATE_IDS, type SessionCheckSummary, type SessionCohort, type SessionCohortKind, type SessionConfidence, type SessionEdgeSource, type SessionGroup, type SessionIndex, type SessionLastError, type SessionRunRecord, type SessionScopeOptions, type SessionScopeResult, type SessionStatus, type SessionSummary, type SessionWarning, type SessionWorkflowKey, type SessionWorkflowMetadata, StepStatus, StepType, type SuiteArtifactsConfig, type SuiteCaseConfig, type SuiteCaseResult, type SuiteCaseStatus, type SuiteChecksConfig, type SuiteConfig, type SuiteDiagnostic, type SuiteDiagnosticCode, type SuiteEvalConfig, type SuiteRunResult, type SuiteRunSummary, type SuiteTemplateId, TERMINAL_INDENT, type TimelineEntry, type TimelineFocus, type TimelineOptions, TraceCorrelationMetadata, TraceDirectory, type TraceDirectoryOptions, TraceEvent, type TraceFilterOptions, type TraceJsonlFormat, TraceMetadata, TraceMetadataStatus, type TraceSearchOptions, type TraceSearchResult, type TraceSessionCheckResult, type TraceStats, type TraceStatsOptions, type TraceStatsRankedRun, type TraceStatsRankedStep, type ValidateSuiteConfigResult, type ZipEntry, aggregateBundleSafeStatus, aggregateSessionCheckResults, analyzeCohort, assertBundlePathContained, assertEvidenceRelativePath, buildActivitySummary, buildBundleMetadata, buildBundleSummaryMarkdown, buildEvidenceCausalFailureViewHtml, buildEvidenceCiPackage, buildEvidenceCircuitViewHtml, buildEvidenceContractsViewHtml, buildEvidenceDiffViewHtml, buildEvidenceFileEntries, buildEvidenceHtmlShell, buildEvidenceHtmlShellFromManifest, buildEvidenceManifest, buildEvidenceOutcomesViewHtml, buildEvidenceProvenanceViewHtml, buildEvidenceSafetyViewHtml, buildEvidenceTimelineViewHtml, buildEvidenceToolsLlmViewHtml, buildEvidenceTreeViewHtml, buildLocalExplanation, buildPlaceholderArtifact, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildSessionIndex, buildTraceStats, buildZipArchive, bundleFailsOnSafety, bundleRunAssetRelativePath, collectTraceSchemaVersions, compareCohortAggregates, createRunId, createStepId, defaultBundleOutputPath, defaultSuiteConfigTemplate, deriveSessionStatus, encodeEmbeddedEvidenceJson, enrichSessionRunRecord, enrichSessionSummary, ensureTraceDir, extractMetadata, extractOutcomesFromPersistedEvents, extractOutcomesFromTraceEvents, extractSessionWorkflowMetadata, filterMetasBySessionScope, filterTraces, formatDuration, formatError, formatTerminalName, formatTimestamp, gateHasThresholds, getDefaultTraceDir, getIndent, getRunIdFromTraceFileName, getSuiteTemplate, getTraceFilePath, groupSessionCohorts, inferEvidenceFileRole, initializeTraceFile, isAgentInspectTrace, isSha256Hex, listSuiteTemplates, listTraceFiles, loadSessionRunRecords, loadSuiteConfig, loadTraceMetadataList, normalizeBundleOutputPath, normalizeSuiteConfig, parseCohortMetricList, parseDuration, parseDurationFilter, parseEvidenceManifestJson, parseGateList, parseGateNumber, parseGroupBySpec, parseTraceJsonl, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, readTraceEvents, readTraceFile, renderActivitySummaryHuman, renderCohortReport, renderCohortSummaryMarkdown, renderErrorLine, renderGateGithubStepSummary, renderGateJUnit, renderGateReport, renderGateSummaryMarkdown, renderRunSummary, renderRunWhat, renderStepLine, renderSuiteReport, renderSuiteReportMarkdown, renderTimeline, renderTraceStats, resolveBundleRunIds, resolveRedactionProfile, resolveSuiteCaseTrace, resolveSuiteConfigPath, resolveSuiteTemplate, resolveTraceDir, runGate, runSuite, sanitizeBundleRunId, searchTraces, serializeEvent, serializeEvidenceManifest, sessionKeyForRun, sha256Equals, sha256Hex, toMetadataSafeStatus, traceMetasToSessionRunRecords, truncateName, unknownTraceFormatMessage, validateEvent, validateEvidenceManifest, validateSuiteConfig, verifyEvidenceDirectory, warn, writeTraceEvent };
+export { type ActivityEntry, type ActivitySummary, type AnalyzeCohortOptions, type BuildActivitySummaryOptions, type BuildSessionIndexOptions, type BundleCheckResults, type BundleCheckRunResult, type BundleMetadata, type BundlePlaceholderArtifact, type BundleRedactionProfile, type BundleRedactionReport, type BundleRedactionReportRun, type BundleResolveOptions, type BundleResolveResult, type BundleSafeStatus, type BundleSafeStatusMetadata, COHORT_METRIC_IDS, type CausalContractFindingInput, type CausalFailureKind, type CohortAggregateMetrics, type CohortAnalysisResult, type CohortMetricComparison, type CohortMetricId, type CohortRunMetrics, type CriticalPathStep, DEFAULT_SUITE_ARTIFACTS_DIR, DEFAULT_SUITE_CONFIG_NAMES, DEFAULT_TRACE_DIR_NAME, type DurationStats, EVIDENCE_ASSESSMENT_NOTE, EVIDENCE_FORMAT_VERSION, EVIDENCE_HTML_FILENAME, EVIDENCE_MANIFEST_FILENAME, EVIDENCE_VIEW_CSS, EVIDENCE_VIEW_IDS, type EnrichSessionSummaryOptions, ErrorInfo, type EvidenceCheckFindingSummary, type EvidenceCiPackageFiles, type EvidenceCiPackageInput, type EvidenceContractsViewInput, type EvidenceFileEntry, type EvidenceFileRole, type EvidenceFormatVersion, type EvidenceHtmlShellInput, type EvidenceManifest, type EvidencePackagedFile, type EvidenceProvenanceViewInput, type EvidenceRedactionProfile, type EvidenceSafeStatus, type EvidenceSafetyViewInput, type EvidenceSourceHash, type EvidenceVerificationPolicy, type EvidenceVerifyIssue, type EvidenceVerifyOptions, type EvidenceVerifyResult, type EvidenceVerifyStatus, type EvidenceViewId, type ExplainFact, type ExplainInference, type ExplainMode, type ExplainOptions, type ExplainResult, FALLBACK_TRACE_DIR, type FindFirstCausalFailureOptions, type FirstCausalFailure, type GateCheckId, type GateCheckResult, type GateExitCode, type GateResult, type GroupSessionCohortsOptions, type HandoffEdge, InspectRunTree, type LoadSuiteConfigOptions, MAX_NAME_LENGTH, MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, ObservedOutcome, type ParseTraceJsonlOptions, type ParseTraceJsonlResult, type ParsedDurationFilter, RUNS_DIR_NAME, RedactionProfile, type RenderCohortReportOptions, type RenderGateReportOptions, type RenderSuiteReportOptions, type RenderTimelineOptions, type RenderWhatOptions, type ResolvedRedactionProfile, type ResolvedSuiteCase, type RetryLink, type RunGateOptions, RunStatus, type RunSuiteOptions, RunSummary, type RunTimeline, type RunWhatSummary, SESSION_WORKFLOW_KEYS, SUITE_TEMPLATE_IDS, type SessionCheckSummary, type SessionCohort, type SessionCohortKind, type SessionConfidence, type SessionEdgeSource, type SessionGroup, type SessionIndex, type SessionLastError, type SessionRunRecord, type SessionScopeOptions, type SessionScopeResult, type SessionStatus, type SessionSummary, type SessionWarning, type SessionWorkflowKey, type SessionWorkflowMetadata, StepStatus, StepType, type SuiteArtifactsConfig, type SuiteCaseConfig, type SuiteCaseResult, type SuiteCaseStatus, type SuiteChecksConfig, type SuiteConfig, type SuiteDiagnostic, type SuiteDiagnosticCode, type SuiteEvalConfig, type SuiteRunResult, type SuiteRunSummary, type SuiteTemplateId, TERMINAL_INDENT, type TimelineEntry, type TimelineFocus, type TimelineOptions, TraceCorrelationMetadata, TraceDirectory, type TraceDirectoryOptions, TraceEvent, type TraceFilterOptions, type TraceJsonlFormat, TraceMetadata, TraceMetadataStatus, type TraceSearchOptions, type TraceSearchResult, type TraceSessionCheckResult, type TraceStats, type TraceStatsOptions, type TraceStatsRankedRun, type TraceStatsRankedStep, type ValidateSuiteConfigResult, type ZipEntry, aggregateBundleSafeStatus, aggregateSessionCheckResults, analyzeCohort, assertBundlePathContained, assertEvidenceRelativePath, buildActivitySummary, buildBundleMetadata, buildBundleSummaryMarkdown, buildEvidenceCausalFailureViewHtml, buildEvidenceCiPackage, buildEvidenceCircuitViewHtml, buildEvidenceContractsViewHtml, buildEvidenceDiffViewHtml, buildEvidenceFileEntries, buildEvidenceHtmlShell, buildEvidenceHtmlShellFromManifest, buildEvidenceManifest, buildEvidenceOutcomesViewHtml, buildEvidenceProvenanceViewHtml, buildEvidenceSafetyViewHtml, buildEvidenceTimelineViewHtml, buildEvidenceToolsLlmViewHtml, buildEvidenceTreeViewHtml, buildLocalExplanation, buildPlaceholderArtifact, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildSessionIndex, buildTraceStats, buildZipArchive, bundleFailsOnSafety, bundleRunAssetRelativePath, collectTraceSchemaVersions, compareCohortAggregates, createRunId, createStepId, defaultBundleOutputPath, defaultSuiteConfigTemplate, deriveSessionStatus, encodeEmbeddedEvidenceJson, enrichSessionRunRecord, enrichSessionSummary, ensureTraceDir, extractMetadata, extractOutcomesFromPersistedEvents, extractOutcomesFromTraceEvents, extractSessionWorkflowMetadata, filterMetasBySessionScope, filterTraces, findFirstCausalFailure, formatDuration, formatError, formatTerminalName, formatTimestamp, gateHasThresholds, getDefaultTraceDir, getIndent, getRunIdFromTraceFileName, getSuiteTemplate, getTraceFilePath, groupSessionCohorts, inferEvidenceFileRole, initializeTraceFile, isAgentInspectTrace, isSha256Hex, listSuiteTemplates, listTraceFiles, loadSessionRunRecords, loadSuiteConfig, loadTraceMetadataList, normalizeBundleOutputPath, normalizeSuiteConfig, parseCohortMetricList, parseDuration, parseDurationFilter, parseEvidenceManifestJson, parseGateList, parseGateNumber, parseGroupBySpec, parseTraceJsonl, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, readTraceEvents, readTraceFile, renderActivitySummaryHuman, renderCohortReport, renderCohortSummaryMarkdown, renderErrorLine, renderGateGithubStepSummary, renderGateJUnit, renderGateReport, renderGateSummaryMarkdown, renderRunSummary, renderRunWhat, renderStepLine, renderSuiteReport, renderSuiteReportMarkdown, renderTimeline, renderTraceStats, resolveBundleRunIds, resolveRedactionProfile, resolveSuiteCaseTrace, resolveSuiteConfigPath, resolveSuiteTemplate, resolveTraceDir, runGate, runSuite, sanitizeBundleRunId, searchTraces, serializeEvent, serializeEvidenceManifest, sessionKeyForRun, sha256Equals, sha256Hex, toMetadataSafeStatus, traceMetasToSessionRunRecords, truncateName, unknownTraceFormatMessage, validateEvent, validateEvidenceManifest, validateSuiteConfig, verifyEvidenceDirectory, warn, writeTraceEvent };

package/packages/core/dist/advanced.d.ts

@@ -230,7 +230,7 @@ interface TimelineOptions {
     focus?: TimelineFocus;
     slowTopN?: number;
 }
-declare function buildRunTimeline(events: TraceEvent[], options?: TimelineOptions): RunTimeline;
+declare function buildRunTimeline(events: readonly TraceEvent[], options?: TimelineOptions): RunTimeline;
 interface RenderTimelineOptions {
     focus?: TimelineFocus;
 }
@@ -276,6 +276,44 @@ interface RenderWhatOptions {
  */
 declare function renderRunWhat(summary: RunWhatSummary, options?: RenderWhatOptions): string;
 
+type CausalFailureKind = "explicit_error_event" | "failed_observed_outcome" | "contract_failure" | "failed_ancestor_or_child" | "none";
+interface CausalContractFindingInput {
+    ruleId: string;
+    status: "fail" | "pass" | "warning" | string;
+    /** Linked event/step ids from check evidence. */
+    evidenceIds?: string[];
+    message?: string;
+}
+interface FirstCausalFailure {
+    kind: CausalFailureKind;
+    /** Stable evidence ids (stepId / outcomeId / event-linked ids). No raw paths. */
+    evidenceIds: string[];
+    rationale: string;
+    /** 1–4 when matched; 0 when none. */
+    orderIndex: 0 | 1 | 2 | 3 | 4;
+    runId?: string;
+    primary?: {
+        stepId?: string;
+        outcomeId?: string;
+        ruleId?: string;
+        name?: string;
+    };
+    relationship?: {
+        role: "self" | "ancestor" | "child";
+        relatedIds: string[];
+    };
+    engine: "conservative-causal-v1";
+}
+interface FindFirstCausalFailureOptions {
+    /** Optional contract/check failures (step 3). Omitted → skip contract stage. */
+    contractFindings?: readonly CausalContractFindingInput[];
+}
+/**
+ * Find the first causal failure using the locked conservative order.
+ * Does not infer from timing correlation alone.
+ */
+declare function findFirstCausalFailure(events: readonly TraceEvent[], options?: FindFirstCausalFailureOptions): FirstCausalFailure;
+
 type ExplainMode = "dry-run" | "local";
 interface ExplainFact {
     id: string;
@@ -1374,4 +1412,4 @@ declare function renderGateGithubStepSummary(result: GateResult): string;
 declare function renderGateJUnit(result: GateResult): string;
 declare function renderGateReport(result: GateResult, options?: RenderGateReportOptions): string;
 
-export { type ActivityEntry, type ActivitySummary, type AnalyzeCohortOptions, type BuildActivitySummaryOptions, type BuildSessionIndexOptions, type BundleCheckResults, type BundleCheckRunResult, type BundleMetadata, type BundlePlaceholderArtifact, type BundleRedactionProfile, type BundleRedactionReport, type BundleRedactionReportRun, type BundleResolveOptions, type BundleResolveResult, type BundleSafeStatus, type BundleSafeStatusMetadata, COHORT_METRIC_IDS, type CohortAggregateMetrics, type CohortAnalysisResult, type CohortMetricComparison, type CohortMetricId, type CohortRunMetrics, type CriticalPathStep, DEFAULT_SUITE_ARTIFACTS_DIR, DEFAULT_SUITE_CONFIG_NAMES, DEFAULT_TRACE_DIR_NAME, type DurationStats, EVIDENCE_ASSESSMENT_NOTE, EVIDENCE_FORMAT_VERSION, EVIDENCE_HTML_FILENAME, EVIDENCE_MANIFEST_FILENAME, EVIDENCE_VIEW_CSS, EVIDENCE_VIEW_IDS, type EnrichSessionSummaryOptions, ErrorInfo, type EvidenceCheckFindingSummary, type EvidenceCiPackageFiles, type EvidenceCiPackageInput, type EvidenceContractsViewInput, type EvidenceFileEntry, type EvidenceFileRole, type EvidenceFormatVersion, type EvidenceHtmlShellInput, type EvidenceManifest, type EvidencePackagedFile, type EvidenceProvenanceViewInput, type EvidenceRedactionProfile, type EvidenceSafeStatus, type EvidenceSafetyViewInput, type EvidenceSourceHash, type EvidenceVerificationPolicy, type EvidenceVerifyIssue, type EvidenceVerifyOptions, type EvidenceVerifyResult, type EvidenceVerifyStatus, type EvidenceViewId, type ExplainFact, type ExplainInference, type ExplainMode, type ExplainOptions, type ExplainResult, FALLBACK_TRACE_DIR, type GateCheckId, type GateCheckResult, type GateExitCode, type GateResult, type GroupSessionCohortsOptions, type HandoffEdge, InspectRunTree, type LoadSuiteConfigOptions, MAX_NAME_LENGTH, MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, ObservedOutcome, type ParseTraceJsonlOptions, type ParseTraceJsonlResult, type ParsedDurationFilter, RUNS_DIR_NAME, RedactionProfile, type RenderCohortReportOptions, type RenderGateReportOptions, type RenderSuiteReportOptions, type RenderTimelineOptions, type RenderWhatOptions, type ResolvedRedactionProfile, type ResolvedSuiteCase, type RetryLink, type RunGateOptions, RunStatus, type RunSuiteOptions, RunSummary, type RunTimeline, type RunWhatSummary, SESSION_WORKFLOW_KEYS, SUITE_TEMPLATE_IDS, type SessionCheckSummary, type SessionCohort, type SessionCohortKind, type SessionConfidence, type SessionEdgeSource, type SessionGroup, type SessionIndex, type SessionLastError, type SessionRunRecord, type SessionScopeOptions, type SessionScopeResult, type SessionStatus, type SessionSummary, type SessionWarning, type SessionWorkflowKey, type SessionWorkflowMetadata, StepStatus, StepType, type SuiteArtifactsConfig, type SuiteCaseConfig, type SuiteCaseResult, type SuiteCaseStatus, type SuiteChecksConfig, type SuiteConfig, type SuiteDiagnostic, type SuiteDiagnosticCode, type SuiteEvalConfig, type SuiteRunResult, type SuiteRunSummary, type SuiteTemplateId, TERMINAL_INDENT, type TimelineEntry, type TimelineFocus, type TimelineOptions, TraceCorrelationMetadata, TraceDirectory, type TraceDirectoryOptions, TraceEvent, type TraceFilterOptions, type TraceJsonlFormat, TraceMetadata, TraceMetadataStatus, type TraceSearchOptions, type TraceSearchResult, type TraceSessionCheckResult, type TraceStats, type TraceStatsOptions, type TraceStatsRankedRun, type TraceStatsRankedStep, type ValidateSuiteConfigResult, type ZipEntry, aggregateBundleSafeStatus, aggregateSessionCheckResults, analyzeCohort, assertBundlePathContained, assertEvidenceRelativePath, buildActivitySummary, buildBundleMetadata, buildBundleSummaryMarkdown, buildEvidenceCausalFailureViewHtml, buildEvidenceCiPackage, buildEvidenceCircuitViewHtml, buildEvidenceContractsViewHtml, buildEvidenceDiffViewHtml, buildEvidenceFileEntries, buildEvidenceHtmlShell, buildEvidenceHtmlShellFromManifest, buildEvidenceManifest, buildEvidenceOutcomesViewHtml, buildEvidenceProvenanceViewHtml, buildEvidenceSafetyViewHtml, buildEvidenceTimelineViewHtml, buildEvidenceToolsLlmViewHtml, buildEvidenceTreeViewHtml, buildLocalExplanation, buildPlaceholderArtifact, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildSessionIndex, buildTraceStats, buildZipArchive, bundleFailsOnSafety, bundleRunAssetRelativePath, collectTraceSchemaVersions, compareCohortAggregates, createRunId, createStepId, defaultBundleOutputPath, defaultSuiteConfigTemplate, deriveSessionStatus, encodeEmbeddedEvidenceJson, enrichSessionRunRecord, enrichSessionSummary, ensureTraceDir, extractMetadata, extractOutcomesFromPersistedEvents, extractOutcomesFromTraceEvents, extractSessionWorkflowMetadata, filterMetasBySessionScope, filterTraces, formatDuration, formatError, formatTerminalName, formatTimestamp, gateHasThresholds, getDefaultTraceDir, getIndent, getRunIdFromTraceFileName, getSuiteTemplate, getTraceFilePath, groupSessionCohorts, inferEvidenceFileRole, initializeTraceFile, isAgentInspectTrace, isSha256Hex, listSuiteTemplates, listTraceFiles, loadSessionRunRecords, loadSuiteConfig, loadTraceMetadataList, normalizeBundleOutputPath, normalizeSuiteConfig, parseCohortMetricList, parseDuration, parseDurationFilter, parseEvidenceManifestJson, parseGateList, parseGateNumber, parseGroupBySpec, parseTraceJsonl, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, readTraceEvents, readTraceFile, renderActivitySummaryHuman, renderCohortReport, renderCohortSummaryMarkdown, renderErrorLine, renderGateGithubStepSummary, renderGateJUnit, renderGateReport, renderGateSummaryMarkdown, renderRunSummary, renderRunWhat, renderStepLine, renderSuiteReport, renderSuiteReportMarkdown, renderTimeline, renderTraceStats, resolveBundleRunIds, resolveRedactionProfile, resolveSuiteCaseTrace, resolveSuiteConfigPath, resolveSuiteTemplate, resolveTraceDir, runGate, runSuite, sanitizeBundleRunId, searchTraces, serializeEvent, serializeEvidenceManifest, sessionKeyForRun, sha256Equals, sha256Hex, toMetadataSafeStatus, traceMetasToSessionRunRecords, truncateName, unknownTraceFormatMessage, validateEvent, validateEvidenceManifest, validateSuiteConfig, verifyEvidenceDirectory, warn, writeTraceEvent };
+export { type ActivityEntry, type ActivitySummary, type AnalyzeCohortOptions, type BuildActivitySummaryOptions, type BuildSessionIndexOptions, type BundleCheckResults, type BundleCheckRunResult, type BundleMetadata, type BundlePlaceholderArtifact, type BundleRedactionProfile, type BundleRedactionReport, type BundleRedactionReportRun, type BundleResolveOptions, type BundleResolveResult, type BundleSafeStatus, type BundleSafeStatusMetadata, COHORT_METRIC_IDS, type CausalContractFindingInput, type CausalFailureKind, type CohortAggregateMetrics, type CohortAnalysisResult, type CohortMetricComparison, type CohortMetricId, type CohortRunMetrics, type CriticalPathStep, DEFAULT_SUITE_ARTIFACTS_DIR, DEFAULT_SUITE_CONFIG_NAMES, DEFAULT_TRACE_DIR_NAME, type DurationStats, EVIDENCE_ASSESSMENT_NOTE, EVIDENCE_FORMAT_VERSION, EVIDENCE_HTML_FILENAME, EVIDENCE_MANIFEST_FILENAME, EVIDENCE_VIEW_CSS, EVIDENCE_VIEW_IDS, type EnrichSessionSummaryOptions, ErrorInfo, type EvidenceCheckFindingSummary, type EvidenceCiPackageFiles, type EvidenceCiPackageInput, type EvidenceContractsViewInput, type EvidenceFileEntry, type EvidenceFileRole, type EvidenceFormatVersion, type EvidenceHtmlShellInput, type EvidenceManifest, type EvidencePackagedFile, type EvidenceProvenanceViewInput, type EvidenceRedactionProfile, type EvidenceSafeStatus, type EvidenceSafetyViewInput, type EvidenceSourceHash, type EvidenceVerificationPolicy, type EvidenceVerifyIssue, type EvidenceVerifyOptions, type EvidenceVerifyResult, type EvidenceVerifyStatus, type EvidenceViewId, type ExplainFact, type ExplainInference, type ExplainMode, type ExplainOptions, type ExplainResult, FALLBACK_TRACE_DIR, type FindFirstCausalFailureOptions, type FirstCausalFailure, type GateCheckId, type GateCheckResult, type GateExitCode, type GateResult, type GroupSessionCohortsOptions, type HandoffEdge, InspectRunTree, type LoadSuiteConfigOptions, MAX_NAME_LENGTH, MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, ObservedOutcome, type ParseTraceJsonlOptions, type ParseTraceJsonlResult, type ParsedDurationFilter, RUNS_DIR_NAME, RedactionProfile, type RenderCohortReportOptions, type RenderGateReportOptions, type RenderSuiteReportOptions, type RenderTimelineOptions, type RenderWhatOptions, type ResolvedRedactionProfile, type ResolvedSuiteCase, type RetryLink, type RunGateOptions, RunStatus, type RunSuiteOptions, RunSummary, type RunTimeline, type RunWhatSummary, SESSION_WORKFLOW_KEYS, SUITE_TEMPLATE_IDS, type SessionCheckSummary, type SessionCohort, type SessionCohortKind, type SessionConfidence, type SessionEdgeSource, type SessionGroup, type SessionIndex, type SessionLastError, type SessionRunRecord, type SessionScopeOptions, type SessionScopeResult, type SessionStatus, type SessionSummary, type SessionWarning, type SessionWorkflowKey, type SessionWorkflowMetadata, StepStatus, StepType, type SuiteArtifactsConfig, type SuiteCaseConfig, type SuiteCaseResult, type SuiteCaseStatus, type SuiteChecksConfig, type SuiteConfig, type SuiteDiagnostic, type SuiteDiagnosticCode, type SuiteEvalConfig, type SuiteRunResult, type SuiteRunSummary, type SuiteTemplateId, TERMINAL_INDENT, type TimelineEntry, type TimelineFocus, type TimelineOptions, TraceCorrelationMetadata, TraceDirectory, type TraceDirectoryOptions, TraceEvent, type TraceFilterOptions, type TraceJsonlFormat, TraceMetadata, TraceMetadataStatus, type TraceSearchOptions, type TraceSearchResult, type TraceSessionCheckResult, type TraceStats, type TraceStatsOptions, type TraceStatsRankedRun, type TraceStatsRankedStep, type ValidateSuiteConfigResult, type ZipEntry, aggregateBundleSafeStatus, aggregateSessionCheckResults, analyzeCohort, assertBundlePathContained, assertEvidenceRelativePath, buildActivitySummary, buildBundleMetadata, buildBundleSummaryMarkdown, buildEvidenceCausalFailureViewHtml, buildEvidenceCiPackage, buildEvidenceCircuitViewHtml, buildEvidenceContractsViewHtml, buildEvidenceDiffViewHtml, buildEvidenceFileEntries, buildEvidenceHtmlShell, buildEvidenceHtmlShellFromManifest, buildEvidenceManifest, buildEvidenceOutcomesViewHtml, buildEvidenceProvenanceViewHtml, buildEvidenceSafetyViewHtml, buildEvidenceTimelineViewHtml, buildEvidenceToolsLlmViewHtml, buildEvidenceTreeViewHtml, buildLocalExplanation, buildPlaceholderArtifact, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildSessionIndex, buildTraceStats, buildZipArchive, bundleFailsOnSafety, bundleRunAssetRelativePath, collectTraceSchemaVersions, compareCohortAggregates, createRunId, createStepId, defaultBundleOutputPath, defaultSuiteConfigTemplate, deriveSessionStatus, encodeEmbeddedEvidenceJson, enrichSessionRunRecord, enrichSessionSummary, ensureTraceDir, extractMetadata, extractOutcomesFromPersistedEvents, extractOutcomesFromTraceEvents, extractSessionWorkflowMetadata, filterMetasBySessionScope, filterTraces, findFirstCausalFailure, formatDuration, formatError, formatTerminalName, formatTimestamp, gateHasThresholds, getDefaultTraceDir, getIndent, getRunIdFromTraceFileName, getSuiteTemplate, getTraceFilePath, groupSessionCohorts, inferEvidenceFileRole, initializeTraceFile, isAgentInspectTrace, isSha256Hex, listSuiteTemplates, listTraceFiles, loadSessionRunRecords, loadSuiteConfig, loadTraceMetadataList, normalizeBundleOutputPath, normalizeSuiteConfig, parseCohortMetricList, parseDuration, parseDurationFilter, parseEvidenceManifestJson, parseGateList, parseGateNumber, parseGroupBySpec, parseTraceJsonl, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, readTraceEvents, readTraceFile, renderActivitySummaryHuman, renderCohortReport, renderCohortSummaryMarkdown, renderErrorLine, renderGateGithubStepSummary, renderGateJUnit, renderGateReport, renderGateSummaryMarkdown, renderRunSummary, renderRunWhat, renderStepLine, renderSuiteReport, renderSuiteReportMarkdown, renderTimeline, renderTraceStats, resolveBundleRunIds, resolveRedactionProfile, resolveSuiteCaseTrace, resolveSuiteConfigPath, resolveSuiteTemplate, resolveTraceDir, runGate, runSuite, sanitizeBundleRunId, searchTraces, serializeEvent, serializeEvidenceManifest, sessionKeyForRun, sha256Equals, sha256Hex, toMetadataSafeStatus, traceMetasToSessionRunRecords, truncateName, unknownTraceFormatMessage, validateEvent, validateEvidenceManifest, validateSuiteConfig, verifyEvidenceDirectory, warn, writeTraceEvent };

package/packages/core/dist/advanced.mjs

@@ -1,8 +1,8 @@
 import { runTraceChecks, createRunStatusRule, createToolUsageRule, createRunDurationRule, createLlmUsageRule, createObservedOutcomeRule } from './chunk-QT6CQ2XA.mjs';
 export { MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, TERMINAL_INDENT, TraceDirectory, createInspector, createInspectorRuntime, formatTerminalName, getCurrentContext, getCurrentCorrelationMetadata, getCurrentDepth, getCurrentRunId, getCurrentRunName, getCurrentStepId, getIndent, getParentStepId, getTraceDirFromContext, getTraceSafetyFromContext, hasActiveContext, isAgentInspectEnabled, isSilentContext, maybeInspectRun, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, renderErrorLine, renderRunSummary, renderStepLine, resolveTraceDir, runWithContext, runWithStepContext } from './chunk-ZWA5RWMV.mjs';
-import { filterTraces, extractMetadata, buildRunSummary } from './chunk-KDDU2R5P.mjs';
-export { buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildTraceStats, extractMetadata, filterTraces, renderRunWhat, renderTimeline, renderTraceStats } from './chunk-KDDU2R5P.mjs';
-import { parseObservationFilter, extractOutcomesFromTraceEvents, summarizeObservedOutcomes, extractOutcomesFromPersistedEvents, renderObservedOutcomesHtml } from './chunk-VFO76UH3.mjs';
+import { buildRunTimeline, filterTraces, extractMetadata, buildRunSummary } from './chunk-LFWZEO2L.mjs';
+export { buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildTraceStats, extractMetadata, filterTraces, renderRunWhat, renderTimeline, renderTraceStats } from './chunk-LFWZEO2L.mjs';
+import { extractOutcomesFromTraceEvents, parseObservationFilter, summarizeObservedOutcomes, extractOutcomesFromPersistedEvents, renderObservedOutcomesHtml } from './chunk-VFO76UH3.mjs';
 export { extractOutcomesFromPersistedEvents, extractOutcomesFromTraceEvents } from './chunk-VFO76UH3.mjs';
 import { diffTraceEvents, renderRunDiff } from './chunk-F7STQ5JF.mjs';
 import './chunk-BT7CATSD.mjs';
@@ -25,6 +25,148 @@ import { createHash } from 'crypto';
 import { stat, readFile, access, readdir } from 'fs/promises';
 import { pathToFileURL } from 'url';
 
+// packages/core/src/causal-failure.ts
+function runIdFromEvents(events) {
+  for (const event of events) {
+    if ("runId" in event && typeof event.runId === "string") return event.runId;
+  }
+  return void 0;
+}
+function noneResult(runId, rationale) {
+  return {
+    kind: "none",
+    evidenceIds: [],
+    rationale,
+    orderIndex: 0,
+    runId,
+    engine: "conservative-causal-v1"
+  };
+}
+function findFirstCausalFailure(events, options = {}) {
+  const runId = runIdFromEvents(events);
+  const timeline = buildRunTimeline(events);
+  const firstError = timeline.entries.find((entry) => entry.isError);
+  if (firstError) {
+    return {
+      kind: "explicit_error_event",
+      evidenceIds: [firstError.stepId],
+      rationale: "First timeline step with status error (explicit failure; no timing-only inference).",
+      orderIndex: 1,
+      runId: timeline.runId || runId,
+      primary: {
+        stepId: firstError.stepId,
+        name: firstError.name
+      },
+      relationship: { role: "self", relatedIds: [] },
+      engine: "conservative-causal-v1"
+    };
+  }
+  const runCompletedError = events.find(
+    (event) => event.event === "run_completed" && event.status === "error"
+  );
+  if (runCompletedError) {
+    return {
+      kind: "explicit_error_event",
+      evidenceIds: [runCompletedError.runId],
+      rationale: "Run completed with status error and no earlier errored step.",
+      orderIndex: 1,
+      runId: runCompletedError.runId,
+      primary: { name: "run", stepId: runCompletedError.runId },
+      relationship: { role: "self", relatedIds: [] },
+      engine: "conservative-causal-v1"
+    };
+  }
+  const outcomes = extractOutcomesFromTraceEvents(events);
+  const failedOutcome = outcomes.find((outcome) => outcome.status === "failed");
+  if (failedOutcome) {
+    const evidenceIds = [failedOutcome.outcomeId];
+    if (failedOutcome.parentId) evidenceIds.push(failedOutcome.parentId);
+    return {
+      kind: "failed_observed_outcome",
+      evidenceIds,
+      rationale: "First observed outcome with status failed.",
+      orderIndex: 2,
+      runId: failedOutcome.runId || runId,
+      primary: {
+        outcomeId: failedOutcome.outcomeId,
+        stepId: failedOutcome.parentId,
+        name: failedOutcome.name
+      },
+      relationship: failedOutcome.parentId ? { role: "child", relatedIds: [failedOutcome.parentId] } : { role: "self", relatedIds: [] },
+      engine: "conservative-causal-v1"
+    };
+  }
+  const contractFail = (options.contractFindings ?? []).find(
+    (finding) => finding.status === "fail" && (finding.evidenceIds?.length ?? 0) > 0
+  );
+  if (contractFail) {
+    const evidenceIds = [...contractFail.evidenceIds ?? []];
+    return {
+      kind: "contract_failure",
+      evidenceIds,
+      rationale: contractFail.message ?? `Contract rule ${contractFail.ruleId} failed with linked evidence ids.`,
+      orderIndex: 3,
+      runId,
+      primary: {
+        ruleId: contractFail.ruleId,
+        stepId: evidenceIds[0],
+        name: contractFail.ruleId
+      },
+      relationship: { role: "self", relatedIds: [] },
+      engine: "conservative-causal-v1"
+    };
+  }
+  const completed = events.filter(
+    (event) => event.event === "step_completed"
+  );
+  const started = events.filter(
+    (event) => event.event === "step_started"
+  );
+  const parentByStep = /* @__PURE__ */ new Map();
+  for (const start of started) {
+    parentByStep.set(start.stepId, start.parentId);
+  }
+  const errorSteps = completed.filter((event) => event.status === "error");
+  if (errorSteps.length > 0) {
+    const sorted = [...errorSteps].sort((a, b) => {
+      const depth = (id) => {
+        let d = 0;
+        let cur = id;
+        const seen = /* @__PURE__ */ new Set();
+        while (cur && parentByStep.has(cur) && !seen.has(cur)) {
+          seen.add(cur);
+          const parent = parentByStep.get(cur);
+          if (!parent) break;
+          d += 1;
+          cur = parent;
+        }
+        return d;
+      };
+      return depth(b.stepId) - depth(a.stepId);
+    });
+    const tip = sorted[0];
+    const parentId = parentByStep.get(tip.stepId);
+    const relatedIds = parentId ? [parentId] : [];
+    return {
+      kind: "failed_ancestor_or_child",
+      evidenceIds: [tip.stepId, ...relatedIds],
+      rationale: parentId ? "Deepest explicit error step with parent link (nearest ancestor relationship)." : "Explicit error step used as structural tip (no parent id).",
+      orderIndex: 4,
+      runId: tip.runId || runId,
+      primary: { stepId: tip.stepId, name: started.find((s) => s.stepId === tip.stepId)?.name },
+      relationship: {
+        role: parentId ? "child" : "self",
+        relatedIds
+      },
+      engine: "conservative-causal-v1"
+    };
+  }
+  return noneResult(
+    runId,
+    "No explicit error event, failed outcome, or linked contract failure; refusing timing-only inference."
+  );
+}
+
 // packages/core/src/explain.ts
 function toDisplayStatus(status) {
   if (status === "ok") return "success";
@@ -4252,6 +4394,6 @@ function renderGateReport(result, options = {}) {
   return renderGateSummaryMarkdown(result);
 }
 
-export { COHORT_METRIC_IDS, DEFAULT_SUITE_ARTIFACTS_DIR, DEFAULT_SUITE_CONFIG_NAMES, EVIDENCE_ASSESSMENT_NOTE, EVIDENCE_FORMAT_VERSION, EVIDENCE_HTML_FILENAME, EVIDENCE_MANIFEST_FILENAME, EVIDENCE_VIEW_CSS, EVIDENCE_VIEW_IDS, SESSION_WORKFLOW_KEYS, SUITE_TEMPLATE_IDS, aggregateBundleSafeStatus, aggregateSessionCheckResults, analyzeCohort, assertBundlePathContained, assertEvidenceRelativePath, buildActivitySummary, buildBundleMetadata, buildBundleSummaryMarkdown, buildEvidenceCausalFailureViewHtml, buildEvidenceCiPackage, buildEvidenceCircuitViewHtml, buildEvidenceContractsViewHtml, buildEvidenceDiffViewHtml, buildEvidenceFileEntries, buildEvidenceHtmlShell, buildEvidenceHtmlShellFromManifest, buildEvidenceManifest, buildEvidenceOutcomesViewHtml, buildEvidenceProvenanceViewHtml, buildEvidenceSafetyViewHtml, buildEvidenceTimelineViewHtml, buildEvidenceToolsLlmViewHtml, buildEvidenceTreeViewHtml, buildLocalExplanation, buildPlaceholderArtifact, buildSessionIndex, buildZipArchive, bundleFailsOnSafety, bundleRunAssetRelativePath, collectTraceSchemaVersions, compareCohortAggregates, defaultBundleOutputPath, defaultSuiteConfigTemplate, deriveSessionStatus, encodeEmbeddedEvidenceJson, enrichSessionRunRecord, enrichSessionSummary, extractSessionWorkflowMetadata, filterMetasBySessionScope, gateHasThresholds, getSuiteTemplate, groupSessionCohorts, inferEvidenceFileRole, isAgentInspectTrace, isSha256Hex, listSuiteTemplates, loadSessionRunRecords, loadSuiteConfig, loadTraceMetadataList, normalizeBundleOutputPath, normalizeSuiteConfig, parseCohortMetricList, parseDurationFilter, parseEvidenceManifestJson, parseGateList, parseGateNumber, parseGroupBySpec, renderActivitySummaryHuman, renderCohortReport, renderCohortSummaryMarkdown, renderGateGithubStepSummary, renderGateJUnit, renderGateReport, renderGateSummaryMarkdown, renderSuiteReport, renderSuiteReportMarkdown, resolveBundleRunIds, resolveSuiteCaseTrace, resolveSuiteConfigPath, resolveSuiteTemplate, runGate, runSuite, sanitizeBundleRunId, searchTraces, serializeEvidenceManifest, sessionKeyForRun, sha256Equals, sha256Hex, toMetadataSafeStatus, traceMetasToSessionRunRecords, validateEvidenceManifest, validateSuiteConfig, verifyEvidenceDirectory };
+export { COHORT_METRIC_IDS, DEFAULT_SUITE_ARTIFACTS_DIR, DEFAULT_SUITE_CONFIG_NAMES, EVIDENCE_ASSESSMENT_NOTE, EVIDENCE_FORMAT_VERSION, EVIDENCE_HTML_FILENAME, EVIDENCE_MANIFEST_FILENAME, EVIDENCE_VIEW_CSS, EVIDENCE_VIEW_IDS, SESSION_WORKFLOW_KEYS, SUITE_TEMPLATE_IDS, aggregateBundleSafeStatus, aggregateSessionCheckResults, analyzeCohort, assertBundlePathContained, assertEvidenceRelativePath, buildActivitySummary, buildBundleMetadata, buildBundleSummaryMarkdown, buildEvidenceCausalFailureViewHtml, buildEvidenceCiPackage, buildEvidenceCircuitViewHtml, buildEvidenceContractsViewHtml, buildEvidenceDiffViewHtml, buildEvidenceFileEntries, buildEvidenceHtmlShell, buildEvidenceHtmlShellFromManifest, buildEvidenceManifest, buildEvidenceOutcomesViewHtml, buildEvidenceProvenanceViewHtml, buildEvidenceSafetyViewHtml, buildEvidenceTimelineViewHtml, buildEvidenceToolsLlmViewHtml, buildEvidenceTreeViewHtml, buildLocalExplanation, buildPlaceholderArtifact, buildSessionIndex, buildZipArchive, bundleFailsOnSafety, bundleRunAssetRelativePath, collectTraceSchemaVersions, compareCohortAggregates, defaultBundleOutputPath, defaultSuiteConfigTemplate, deriveSessionStatus, encodeEmbeddedEvidenceJson, enrichSessionRunRecord, enrichSessionSummary, extractSessionWorkflowMetadata, filterMetasBySessionScope, findFirstCausalFailure, gateHasThresholds, getSuiteTemplate, groupSessionCohorts, inferEvidenceFileRole, isAgentInspectTrace, isSha256Hex, listSuiteTemplates, loadSessionRunRecords, loadSuiteConfig, loadTraceMetadataList, normalizeBundleOutputPath, normalizeSuiteConfig, parseCohortMetricList, parseDurationFilter, parseEvidenceManifestJson, parseGateList, parseGateNumber, parseGroupBySpec, renderActivitySummaryHuman, renderCohortReport, renderCohortSummaryMarkdown, renderGateGithubStepSummary, renderGateJUnit, renderGateReport, renderGateSummaryMarkdown, renderSuiteReport, renderSuiteReportMarkdown, resolveBundleRunIds, resolveSuiteCaseTrace, resolveSuiteConfigPath, resolveSuiteTemplate, runGate, runSuite, sanitizeBundleRunId, searchTraces, serializeEvidenceManifest, sessionKeyForRun, sha256Equals, sha256Hex, toMetadataSafeStatus, traceMetasToSessionRunRecords, validateEvidenceManifest, validateSuiteConfig, verifyEvidenceDirectory };
 //# sourceMappingURL=advanced.mjs.map
 //# sourceMappingURL=advanced.mjs.map