agent-inspect 6.19.1 → 6.21.0

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

@@ -1,8 +1,10 @@
-import { L as LogicalTraceEvent, a as LogicalProjectionDiagnostic, T as TraceCheckInput, b as TraceCheckResult } from './index-DCR816Yt.cjs';
-export { B as BaselineRegressionRuleOptions, D as DecisionRuleOptions, G as GuardrailRuleOptions, c as LlmUsageRuleOptions, M as MaxStepDurationRuleOptions, O as ObservedOutcomeRuleOptions, R as RetrievalRuleOptions, d as RunDepthRuleOptions, e as RunDurationRuleOptions, f as RunEventCountRuleOptions, g as RunStatusRuleOptions, h as RunTraceChecksOptions, S as SafetyFindingCategory, i as SafetyFindingConfidence, j as SafetyOversizedAttributeRuleOptions, k as SafetyRawContentRuleOptions, l as SafetyRedactionRuleOptions, m as SafetySecretPattern, n as SafetySecretPatternRuleOptions, o as StallDetectionRuleOptions, p as StructureIncompleteRuleOptions, q as StructureOrphanRuleOptions, r as StructureParallelWidthRuleOptions, s as StructureRelationshipRuleOptions, t as ToolFailureRuleOptions, u as ToolOrderingRuleOptions, v as ToolUsageRuleOptions, w as TraceCheckContext, x as TraceCheckDiagnostic, y as TraceCheckDiagnosticCode, z as TraceCheckEvidence, A as TraceCheckFacts, C as TraceCheckFinding, E as TraceCheckFindingStatus, F as TraceCheckRule, H as TraceCheckRuleCategory, I as TraceCheckRuleExecution, J as TraceCheckRuleExecutionStatus, K as TraceCheckSeverity, N as TraceCheckStatus, P as TraceCheckSummary, Q as TraceSignalRuleOptions, U as createBaselineRegressionRule, V as createDecisionRule, W as createGuardrailRule, X as createLlmUsageRule, Y as createMaxStepDurationRule, Z as createObservedOutcomeRule, _ as createRequireCompletedRule, $ as createRetrievalRule, a0 as createRunDepthRule, a1 as createRunDurationRule, a2 as createRunEventCountRule, a3 as createRunStatusRule, a4 as createSafetyOversizedAttributeRule, a5 as createSafetyRawContentRule, a6 as createSafetyRedactionRule, a7 as createSafetySecretPatternRule, a8 as createStallDetectionRule, a9 as createStructureCycleRule, aa as createStructureIncompleteRule, ab as createStructureOrphanRule, ac as createStructureParallelWidthRule, ad as createStructureRelationshipRule, ae as createToolFailureRule, af as createToolOrderingRule, ag as createToolUsageRule, ah as projectLogicalEvents, ai as resolveCanonicalToolName, aj as runTraceChecks } from './index-DCR816Yt.cjs';
+import { L as LogicalTraceEvent, a as LogicalProjectionDiagnostic, T as TraceCheckInput, b as TraceCheckDiagnostic, S as SessionWorkflowMetadata, c as TraceCheckResult } from './index-BG-ZBESI.cjs';
+export { B as BaselineRegressionRuleOptions, D as DecisionRuleOptions, G as GuardrailRuleOptions, d as LlmUsageRuleOptions, M as MaxStepDurationRuleOptions, O as ObservedOutcomeRuleOptions, R as RetrievalRuleOptions, e as RunDepthRuleOptions, f as RunDurationRuleOptions, g as RunEventCountRuleOptions, h as RunStatusRuleOptions, i as RunTraceChecksOptions, j as SafetyFindingCategory, k as SafetyFindingConfidence, l as SafetyOversizedAttributeRuleOptions, m as SafetyRawContentRuleOptions, n as SafetyRedactionRuleOptions, o as SafetySecretPattern, p as SafetySecretPatternRuleOptions, q as StallDetectionRuleOptions, r as StructureIncompleteRuleOptions, s as StructureOrphanRuleOptions, t as StructureParallelWidthRuleOptions, u as StructureRelationshipRuleOptions, v as ToolFailureRuleOptions, w as ToolOrderingRuleOptions, x as ToolUsageRuleOptions, y as TraceCheckContext, z as TraceCheckDiagnosticCode, A as TraceCheckEvidence, C as TraceCheckFacts, E as TraceCheckFinding, F as TraceCheckFindingStatus, H as TraceCheckRule, I as TraceCheckRuleCategory, J as TraceCheckRuleExecution, K as TraceCheckRuleExecutionStatus, N as TraceCheckSeverity, P as TraceCheckStatus, Q as TraceCheckSummary, U as TraceSignalRuleOptions, V as createBaselineRegressionRule, W as createDecisionRule, X as createGuardrailRule, Y as createLlmUsageRule, Z as createMaxStepDurationRule, _ as createObservedOutcomeRule, $ as createRequireCompletedRule, a0 as createRetrievalRule, a1 as createRunDepthRule, a2 as createRunDurationRule, a3 as createRunEventCountRule, a4 as createRunStatusRule, a5 as createSafetyOversizedAttributeRule, a6 as createSafetyRawContentRule, a7 as createSafetyRedactionRule, a8 as createSafetySecretPatternRule, a9 as createStallDetectionRule, aa as createStructureCycleRule, ab as createStructureIncompleteRule, ac as createStructureOrphanRule, ad as createStructureParallelWidthRule, ae as createStructureRelationshipRule, af as createToolFailureRule, ag as createToolOrderingRule, ah as createToolUsageRule, ai as projectLogicalEvents, aj as resolveCanonicalToolName, ak as runTraceChecks } from './index-BG-ZBESI.cjs';
 export { PROGRAMMATIC_DIAGNOSTIC_SPECS, ProgrammaticDiagnosticCode, ProgrammaticDiagnosticSpec, formatProgrammaticDiagnostic } from './readers.cjs';
 import { a as TraceReadResult } from './index-vqr-g6ev.cjs';
 import { P as PersistedInspectEvent } from './persisted-inspect-event-CVZWZldL.cjs';
+import './types-VzKihKQo.cjs';
+import './log-config-CFlIJHTf.cjs';
 import './inspect-event-DRthdZlf.cjs';
 import './types-B562HgN_.cjs';
 
@@ -134,6 +136,44 @@ interface TraceFacts {
 declare function buildTraceFacts(input: TraceReadResult): TraceFacts;
 declare function buildTraceFacts(input: readonly PersistedInspectEvent[]): TraceFacts;
 
+/**
+ * Explicit actor/run projection for TraceContract evaluation (#320).
+ *
+ * Selectors use only declared metadata (or explicit event ids). Zero matches
+ * and singular-actor ambiguity fail closed. No timestamp or display-name
+ * inference.
+ *
+ * @experimental
+ */
+interface TraceContractScope {
+    runId?: string;
+    subAgentId?: string;
+    groupId?: string;
+    workflowStep?: string;
+    /** Explicit root event id; evaluation projects to that event and descendants. */
+    rootEventId?: string;
+}
+interface ResolvedContractScope {
+    runId: string;
+    rootEventId?: string;
+    matchedSelectors: Record<string, string>;
+    evidenceEventCount: number;
+    input: TraceCheckInput;
+}
+/**
+ * Collect explicit session/workflow metadata for a run from persisted events.
+ * Prefers RUN-kind attributes; never invents identity from timestamps.
+ */
+declare function workflowMetadataForRun(events: readonly PersistedInspectEvent[], runId: string): SessionWorkflowMetadata;
+/**
+ * Resolve TraceContract `scope` against a check input.
+ * Returns diagnostics on zero/ambiguous matches or missing root events.
+ */
+declare function resolveTraceContractScope(input: TraceCheckInput, scope: TraceContractScope | undefined): {
+    resolved?: ResolvedContractScope;
+    diagnostics: TraceCheckDiagnostic[];
+};
+
 /**
  * @experimental Typed trace contract input. Evolves during v6.5.x.
  */
@@ -146,7 +186,8 @@ interface TraceContractToolRules {
     /**
      * Unconditional tool presence invariant. Every named tool must appear at least
      * once. Do not use for cache-hit or alternate-path shortcuts — prefer
-     * `observations.required` until `alternatives.anyOf` ships (planned 6.20.0).
+     * `alternatives.anyOf` or `observations.required` when a legitimate path may
+     * skip the tool.
      *
      * @see docs/TRACE-CONTRACTS.md
      */
@@ -159,46 +200,130 @@ interface TraceContractToolRules {
     allowed?: string[];
     maxCalls?: number;
     /**
-     * Required tool order as adjacent first-occurrence pairs (start/encounter order).
+     * Required tool order expanded into adjacent pairs.
      *
      * `[A, B, C]` expands to “A before B” and “B before C”, each comparing the
-     * first occurrence of the named tool. Unlisted intermediate tools are
-     * allowed. Later repetitions do not invalidate an earlier valid order.
+     * selected `requiredOrderMode` to every pair. Unlisted intermediate tools
+     * are allowed.
      *
      * TraceContract `requiredOrder` **implies presence**: every listed name is
      * added to the effective required-tool set. Low-level `createToolOrderingRule`
      * alone may still pass vacuously when an endpoint is missing.
      *
-     * This is **not** causal happens-before. Overlapping intervals emit a
-     * non-failing overlap warning. Planned modes (6.20.0, GitHub #308):
-     * `happens-before`, `all-occurrences`.
+     * The default `first-occurrence` mode preserves first-occurrence encounter
+     * ordering; overlapping intervals emit a non-failing warning. `happens-before`
+     * requires the first before event to finish before the first after event starts.
+     * `all-occurrences` applies that causal boundary to every occurrence.
      *
      * @see docs/TRACE-CONTRACTS.md
      * @beta Available through `agent-inspect/checks`. Additive changes may ship
      * in minor releases; breaking changes require a future major.
      */
     requiredOrder?: string[];
+    /**
+     * Ordering semantics applied to every adjacent pair in `requiredOrder`.
+     * Causal modes fail closed when a required interval boundary is unavailable.
+     *
+     * @defaultValue `"first-occurrence"`
+     * @beta Available through `agent-inspect/checks`.
+     */
+    requiredOrderMode?: "first-occurrence" | "happens-before" | "all-occurrences";
 }
 interface TraceContractLlmRules {
     maxCalls?: number;
     maxTotalTokens?: number;
     allowedModels?: string[];
 }
+/**
+ * Structural provenance requirements for named observed outcomes (#321).
+ *
+ * These checks prove method/evidence linkage was recorded. They do **not**
+ * prove the claim is semantically true, authorized, complete, or externally
+ * trusted.
+ *
+ * @experimental
+ */
+interface TraceContractObservationProvenance {
+    /** Require a non-empty method from the bounded ObservedOutcomeMethod vocabulary. */
+    method?: boolean;
+    /**
+     * Require bounded evidence references. Supported shapes:
+     * `string` event id, `{ eventId }`, or `{ eventIds: string[] }` (max 16 ids).
+     */
+    evidence?: boolean;
+    /** When true with evidence, each referenced event id must exist in the same run. */
+    sameRunEventReference?: boolean;
+}
 interface TraceContractObservationRules {
     required?: string[];
     failOn?: Array<"failed" | "unknown" | "skipped">;
+    /**
+     * Structural provenance gates for `required` observation names.
+     *
+     * @experimental
+     */
+    requireProvenance?: TraceContractObservationProvenance;
 }
-interface TraceContractInput {
-    run?: TraceContractRunRules;
-    tools?: TraceContractToolRules;
-    llm?: TraceContractLlmRules;
-    observations?: TraceContractObservationRules;
+/**
+ * One deterministic alternate path. Branch contracts are one level only —
+ * nested `alternatives` are rejected.
+ *
+ * @experimental
+ */
+interface TraceContractAlternativeBranch {
+    /** Unique branch id within `alternatives.anyOf`. */
+    id: string;
+    description?: string;
+    /** Branch body: run/tools/llm/observations only (no nested alternatives). */
+    contract: TraceContractBody;
 }
-interface TraceContract {
+/**
+ * Bounded alternative valid paths for legitimate shortcuts (GitHub #309).
+ *
+ * @experimental
+ */
+interface TraceContractAlternatives {
+    /**
+     * One level of named branches. The overall contract passes when the base
+     * rules pass and **at least one** complete branch passes.
+     */
+    anyOf: TraceContractAlternativeBranch[];
+}
+/** Contract body without alternatives (base or branch). */
+type TraceContractBody = {
     run?: TraceContractRunRules;
     tools?: TraceContractToolRules;
     llm?: TraceContractLlmRules;
     observations?: TraceContractObservationRules;
+};
+interface TraceContractInput extends TraceContractBody {
+    /**
+     * Optional actor/run projection applied before evaluation (#320).
+     *
+     * @experimental
+     */
+    scope?: TraceContractScope;
+    alternatives?: TraceContractAlternatives;
+}
+interface TraceContract extends TraceContractBody {
+    /**
+     * Optional actor/run projection applied before evaluation (#320).
+     *
+     * @experimental
+     */
+    scope?: TraceContractScope;
+    alternatives?: TraceContractAlternatives;
+}
+/**
+ * Lint diagnostic for brittle or invalid TraceContract shapes.
+ *
+ * @experimental
+ */
+interface TraceContractLintDiagnostic {
+    code: string;
+    severity: "error" | "warning" | "info";
+    message: string;
+    path?: string;
 }
 /**
  * Define a normalized trace contract object.
@@ -209,6 +334,9 @@ declare function defineTraceContract(input: TraceContractInput): TraceContract;
 /**
  * Evaluate a trace contract against an opened trace read result.
  *
+ * Base rules always apply. When `alternatives.anyOf` is present, at least one
+ * complete branch must also pass.
+ *
  * @experimental
  */
 declare function evaluateTraceContract(input: TraceCheckInput, contract: TraceContract, options?: {
@@ -222,5 +350,17 @@ declare function evaluateTraceContract(input: TraceCheckInput, contract: TraceCo
 declare function evaluateTraceContractRead(read: TraceReadResult, contract: TraceContract, options?: {
     runId?: string;
 }): TraceCheckResult;
+/**
+ * Lint a TraceContract for invalid or brittle shapes (does not evaluate a trace).
+ *
+ * @experimental
+ */
+declare function lintTraceContract(contract: TraceContract): TraceContractLintDiagnostic[];
+/**
+ * Explain a TraceContract as short human-readable lines (does not evaluate a trace).
+ *
+ * @experimental
+ */
+declare function explainTraceContract(contract: TraceContract): string[];
 
-export { type DerivedFailureConfidence, type DerivedFailureFact, type DerivedFailureRole, type FailureRoleCounts, LogicalProjectionDiagnostic, LogicalTraceEvent, type SemanticParitySummary, TraceCheckInput, TraceCheckResult, type TraceContract, type TraceContractInput, type TraceContractLlmRules, type TraceContractObservationRules, type TraceContractRunRules, type TraceContractToolRules, type TraceFacts, buildTraceFacts, defineTraceContract, deriveFailureFacts, evaluateTraceContract, evaluateTraceContractRead, summarizeSemanticParity };
+export { type DerivedFailureConfidence, type DerivedFailureFact, type DerivedFailureRole, type FailureRoleCounts, LogicalProjectionDiagnostic, LogicalTraceEvent, type SemanticParitySummary, TraceCheckDiagnostic, TraceCheckInput, TraceCheckResult, type TraceContract, type TraceContractAlternativeBranch, type TraceContractAlternatives, type TraceContractBody, type TraceContractInput, type TraceContractLintDiagnostic, type TraceContractLlmRules, type TraceContractObservationProvenance, type TraceContractObservationRules, type TraceContractRunRules, type TraceContractScope, type TraceContractToolRules, type TraceFacts, buildTraceFacts, defineTraceContract, deriveFailureFacts, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, lintTraceContract, resolveTraceContractScope, summarizeSemanticParity, workflowMetadataForRun };

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

@@ -1,8 +1,10 @@
-import { L as LogicalTraceEvent, a as LogicalProjectionDiagnostic, T as TraceCheckInput, b as TraceCheckResult } from './index-DKwuGSe-.js';
-export { B as BaselineRegressionRuleOptions, D as DecisionRuleOptions, G as GuardrailRuleOptions, c as LlmUsageRuleOptions, M as MaxStepDurationRuleOptions, O as ObservedOutcomeRuleOptions, R as RetrievalRuleOptions, d as RunDepthRuleOptions, e as RunDurationRuleOptions, f as RunEventCountRuleOptions, g as RunStatusRuleOptions, h as RunTraceChecksOptions, S as SafetyFindingCategory, i as SafetyFindingConfidence, j as SafetyOversizedAttributeRuleOptions, k as SafetyRawContentRuleOptions, l as SafetyRedactionRuleOptions, m as SafetySecretPattern, n as SafetySecretPatternRuleOptions, o as StallDetectionRuleOptions, p as StructureIncompleteRuleOptions, q as StructureOrphanRuleOptions, r as StructureParallelWidthRuleOptions, s as StructureRelationshipRuleOptions, t as ToolFailureRuleOptions, u as ToolOrderingRuleOptions, v as ToolUsageRuleOptions, w as TraceCheckContext, x as TraceCheckDiagnostic, y as TraceCheckDiagnosticCode, z as TraceCheckEvidence, A as TraceCheckFacts, C as TraceCheckFinding, E as TraceCheckFindingStatus, F as TraceCheckRule, H as TraceCheckRuleCategory, I as TraceCheckRuleExecution, J as TraceCheckRuleExecutionStatus, K as TraceCheckSeverity, N as TraceCheckStatus, P as TraceCheckSummary, Q as TraceSignalRuleOptions, U as createBaselineRegressionRule, V as createDecisionRule, W as createGuardrailRule, X as createLlmUsageRule, Y as createMaxStepDurationRule, Z as createObservedOutcomeRule, _ as createRequireCompletedRule, $ as createRetrievalRule, a0 as createRunDepthRule, a1 as createRunDurationRule, a2 as createRunEventCountRule, a3 as createRunStatusRule, a4 as createSafetyOversizedAttributeRule, a5 as createSafetyRawContentRule, a6 as createSafetyRedactionRule, a7 as createSafetySecretPatternRule, a8 as createStallDetectionRule, a9 as createStructureCycleRule, aa as createStructureIncompleteRule, ab as createStructureOrphanRule, ac as createStructureParallelWidthRule, ad as createStructureRelationshipRule, ae as createToolFailureRule, af as createToolOrderingRule, ag as createToolUsageRule, ah as projectLogicalEvents, ai as resolveCanonicalToolName, aj as runTraceChecks } from './index-DKwuGSe-.js';
+import { L as LogicalTraceEvent, a as LogicalProjectionDiagnostic, T as TraceCheckInput, b as TraceCheckDiagnostic, S as SessionWorkflowMetadata, c as TraceCheckResult } from './index-xevIlqdd.js';
+export { B as BaselineRegressionRuleOptions, D as DecisionRuleOptions, G as GuardrailRuleOptions, d as LlmUsageRuleOptions, M as MaxStepDurationRuleOptions, O as ObservedOutcomeRuleOptions, R as RetrievalRuleOptions, e as RunDepthRuleOptions, f as RunDurationRuleOptions, g as RunEventCountRuleOptions, h as RunStatusRuleOptions, i as RunTraceChecksOptions, j as SafetyFindingCategory, k as SafetyFindingConfidence, l as SafetyOversizedAttributeRuleOptions, m as SafetyRawContentRuleOptions, n as SafetyRedactionRuleOptions, o as SafetySecretPattern, p as SafetySecretPatternRuleOptions, q as StallDetectionRuleOptions, r as StructureIncompleteRuleOptions, s as StructureOrphanRuleOptions, t as StructureParallelWidthRuleOptions, u as StructureRelationshipRuleOptions, v as ToolFailureRuleOptions, w as ToolOrderingRuleOptions, x as ToolUsageRuleOptions, y as TraceCheckContext, z as TraceCheckDiagnosticCode, A as TraceCheckEvidence, C as TraceCheckFacts, E as TraceCheckFinding, F as TraceCheckFindingStatus, H as TraceCheckRule, I as TraceCheckRuleCategory, J as TraceCheckRuleExecution, K as TraceCheckRuleExecutionStatus, N as TraceCheckSeverity, P as TraceCheckStatus, Q as TraceCheckSummary, U as TraceSignalRuleOptions, V as createBaselineRegressionRule, W as createDecisionRule, X as createGuardrailRule, Y as createLlmUsageRule, Z as createMaxStepDurationRule, _ as createObservedOutcomeRule, $ as createRequireCompletedRule, a0 as createRetrievalRule, a1 as createRunDepthRule, a2 as createRunDurationRule, a3 as createRunEventCountRule, a4 as createRunStatusRule, a5 as createSafetyOversizedAttributeRule, a6 as createSafetyRawContentRule, a7 as createSafetyRedactionRule, a8 as createSafetySecretPatternRule, a9 as createStallDetectionRule, aa as createStructureCycleRule, ab as createStructureIncompleteRule, ac as createStructureOrphanRule, ad as createStructureParallelWidthRule, ae as createStructureRelationshipRule, af as createToolFailureRule, ag as createToolOrderingRule, ah as createToolUsageRule, ai as projectLogicalEvents, aj as resolveCanonicalToolName, ak as runTraceChecks } from './index-xevIlqdd.js';
 export { PROGRAMMATIC_DIAGNOSTIC_SPECS, ProgrammaticDiagnosticCode, ProgrammaticDiagnosticSpec, formatProgrammaticDiagnostic } from './readers.js';
 import { a as TraceReadResult } from './index-AMAGuO_i.js';
 import { P as PersistedInspectEvent } from './persisted-inspect-event-BVucFVrP.js';
+import './types-Bx3mEZ04.js';
+import './log-config-OZRfpHED.js';
 import './inspect-event-DRthdZlf.js';
 import './types-B562HgN_.js';
 
@@ -134,6 +136,44 @@ interface TraceFacts {
 declare function buildTraceFacts(input: TraceReadResult): TraceFacts;
 declare function buildTraceFacts(input: readonly PersistedInspectEvent[]): TraceFacts;
 
+/**
+ * Explicit actor/run projection for TraceContract evaluation (#320).
+ *
+ * Selectors use only declared metadata (or explicit event ids). Zero matches
+ * and singular-actor ambiguity fail closed. No timestamp or display-name
+ * inference.
+ *
+ * @experimental
+ */
+interface TraceContractScope {
+    runId?: string;
+    subAgentId?: string;
+    groupId?: string;
+    workflowStep?: string;
+    /** Explicit root event id; evaluation projects to that event and descendants. */
+    rootEventId?: string;
+}
+interface ResolvedContractScope {
+    runId: string;
+    rootEventId?: string;
+    matchedSelectors: Record<string, string>;
+    evidenceEventCount: number;
+    input: TraceCheckInput;
+}
+/**
+ * Collect explicit session/workflow metadata for a run from persisted events.
+ * Prefers RUN-kind attributes; never invents identity from timestamps.
+ */
+declare function workflowMetadataForRun(events: readonly PersistedInspectEvent[], runId: string): SessionWorkflowMetadata;
+/**
+ * Resolve TraceContract `scope` against a check input.
+ * Returns diagnostics on zero/ambiguous matches or missing root events.
+ */
+declare function resolveTraceContractScope(input: TraceCheckInput, scope: TraceContractScope | undefined): {
+    resolved?: ResolvedContractScope;
+    diagnostics: TraceCheckDiagnostic[];
+};
+
 /**
  * @experimental Typed trace contract input. Evolves during v6.5.x.
  */
@@ -146,7 +186,8 @@ interface TraceContractToolRules {
     /**
      * Unconditional tool presence invariant. Every named tool must appear at least
      * once. Do not use for cache-hit or alternate-path shortcuts — prefer
-     * `observations.required` until `alternatives.anyOf` ships (planned 6.20.0).
+     * `alternatives.anyOf` or `observations.required` when a legitimate path may
+     * skip the tool.
      *
      * @see docs/TRACE-CONTRACTS.md
      */
@@ -159,46 +200,130 @@ interface TraceContractToolRules {
     allowed?: string[];
     maxCalls?: number;
     /**
-     * Required tool order as adjacent first-occurrence pairs (start/encounter order).
+     * Required tool order expanded into adjacent pairs.
      *
      * `[A, B, C]` expands to “A before B” and “B before C”, each comparing the
-     * first occurrence of the named tool. Unlisted intermediate tools are
-     * allowed. Later repetitions do not invalidate an earlier valid order.
+     * selected `requiredOrderMode` to every pair. Unlisted intermediate tools
+     * are allowed.
      *
      * TraceContract `requiredOrder` **implies presence**: every listed name is
      * added to the effective required-tool set. Low-level `createToolOrderingRule`
      * alone may still pass vacuously when an endpoint is missing.
      *
-     * This is **not** causal happens-before. Overlapping intervals emit a
-     * non-failing overlap warning. Planned modes (6.20.0, GitHub #308):
-     * `happens-before`, `all-occurrences`.
+     * The default `first-occurrence` mode preserves first-occurrence encounter
+     * ordering; overlapping intervals emit a non-failing warning. `happens-before`
+     * requires the first before event to finish before the first after event starts.
+     * `all-occurrences` applies that causal boundary to every occurrence.
      *
      * @see docs/TRACE-CONTRACTS.md
      * @beta Available through `agent-inspect/checks`. Additive changes may ship
      * in minor releases; breaking changes require a future major.
      */
     requiredOrder?: string[];
+    /**
+     * Ordering semantics applied to every adjacent pair in `requiredOrder`.
+     * Causal modes fail closed when a required interval boundary is unavailable.
+     *
+     * @defaultValue `"first-occurrence"`
+     * @beta Available through `agent-inspect/checks`.
+     */
+    requiredOrderMode?: "first-occurrence" | "happens-before" | "all-occurrences";
 }
 interface TraceContractLlmRules {
     maxCalls?: number;
     maxTotalTokens?: number;
     allowedModels?: string[];
 }
+/**
+ * Structural provenance requirements for named observed outcomes (#321).
+ *
+ * These checks prove method/evidence linkage was recorded. They do **not**
+ * prove the claim is semantically true, authorized, complete, or externally
+ * trusted.
+ *
+ * @experimental
+ */
+interface TraceContractObservationProvenance {
+    /** Require a non-empty method from the bounded ObservedOutcomeMethod vocabulary. */
+    method?: boolean;
+    /**
+     * Require bounded evidence references. Supported shapes:
+     * `string` event id, `{ eventId }`, or `{ eventIds: string[] }` (max 16 ids).
+     */
+    evidence?: boolean;
+    /** When true with evidence, each referenced event id must exist in the same run. */
+    sameRunEventReference?: boolean;
+}
 interface TraceContractObservationRules {
     required?: string[];
     failOn?: Array<"failed" | "unknown" | "skipped">;
+    /**
+     * Structural provenance gates for `required` observation names.
+     *
+     * @experimental
+     */
+    requireProvenance?: TraceContractObservationProvenance;
 }
-interface TraceContractInput {
-    run?: TraceContractRunRules;
-    tools?: TraceContractToolRules;
-    llm?: TraceContractLlmRules;
-    observations?: TraceContractObservationRules;
+/**
+ * One deterministic alternate path. Branch contracts are one level only —
+ * nested `alternatives` are rejected.
+ *
+ * @experimental
+ */
+interface TraceContractAlternativeBranch {
+    /** Unique branch id within `alternatives.anyOf`. */
+    id: string;
+    description?: string;
+    /** Branch body: run/tools/llm/observations only (no nested alternatives). */
+    contract: TraceContractBody;
 }
-interface TraceContract {
+/**
+ * Bounded alternative valid paths for legitimate shortcuts (GitHub #309).
+ *
+ * @experimental
+ */
+interface TraceContractAlternatives {
+    /**
+     * One level of named branches. The overall contract passes when the base
+     * rules pass and **at least one** complete branch passes.
+     */
+    anyOf: TraceContractAlternativeBranch[];
+}
+/** Contract body without alternatives (base or branch). */
+type TraceContractBody = {
     run?: TraceContractRunRules;
     tools?: TraceContractToolRules;
     llm?: TraceContractLlmRules;
     observations?: TraceContractObservationRules;
+};
+interface TraceContractInput extends TraceContractBody {
+    /**
+     * Optional actor/run projection applied before evaluation (#320).
+     *
+     * @experimental
+     */
+    scope?: TraceContractScope;
+    alternatives?: TraceContractAlternatives;
+}
+interface TraceContract extends TraceContractBody {
+    /**
+     * Optional actor/run projection applied before evaluation (#320).
+     *
+     * @experimental
+     */
+    scope?: TraceContractScope;
+    alternatives?: TraceContractAlternatives;
+}
+/**
+ * Lint diagnostic for brittle or invalid TraceContract shapes.
+ *
+ * @experimental
+ */
+interface TraceContractLintDiagnostic {
+    code: string;
+    severity: "error" | "warning" | "info";
+    message: string;
+    path?: string;
 }
 /**
  * Define a normalized trace contract object.
@@ -209,6 +334,9 @@ declare function defineTraceContract(input: TraceContractInput): TraceContract;
 /**
  * Evaluate a trace contract against an opened trace read result.
  *
+ * Base rules always apply. When `alternatives.anyOf` is present, at least one
+ * complete branch must also pass.
+ *
  * @experimental
  */
 declare function evaluateTraceContract(input: TraceCheckInput, contract: TraceContract, options?: {
@@ -222,5 +350,17 @@ declare function evaluateTraceContract(input: TraceCheckInput, contract: TraceCo
 declare function evaluateTraceContractRead(read: TraceReadResult, contract: TraceContract, options?: {
     runId?: string;
 }): TraceCheckResult;
+/**
+ * Lint a TraceContract for invalid or brittle shapes (does not evaluate a trace).
+ *
+ * @experimental
+ */
+declare function lintTraceContract(contract: TraceContract): TraceContractLintDiagnostic[];
+/**
+ * Explain a TraceContract as short human-readable lines (does not evaluate a trace).
+ *
+ * @experimental
+ */
+declare function explainTraceContract(contract: TraceContract): string[];
 
-export { type DerivedFailureConfidence, type DerivedFailureFact, type DerivedFailureRole, type FailureRoleCounts, LogicalProjectionDiagnostic, LogicalTraceEvent, type SemanticParitySummary, TraceCheckInput, TraceCheckResult, type TraceContract, type TraceContractInput, type TraceContractLlmRules, type TraceContractObservationRules, type TraceContractRunRules, type TraceContractToolRules, type TraceFacts, buildTraceFacts, defineTraceContract, deriveFailureFacts, evaluateTraceContract, evaluateTraceContractRead, summarizeSemanticParity };
+export { type DerivedFailureConfidence, type DerivedFailureFact, type DerivedFailureRole, type FailureRoleCounts, LogicalProjectionDiagnostic, LogicalTraceEvent, type SemanticParitySummary, TraceCheckDiagnostic, TraceCheckInput, TraceCheckResult, type TraceContract, type TraceContractAlternativeBranch, type TraceContractAlternatives, type TraceContractBody, type TraceContractInput, type TraceContractLintDiagnostic, type TraceContractLlmRules, type TraceContractObservationProvenance, type TraceContractObservationRules, type TraceContractRunRules, type TraceContractScope, type TraceContractToolRules, type TraceFacts, buildTraceFacts, defineTraceContract, deriveFailureFacts, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, lintTraceContract, resolveTraceContractScope, summarizeSemanticParity, workflowMetadataForRun };

package/packages/core/dist/checks.mjs

@@ -1,5 +1,5 @@
-export { buildTraceFacts, createBaselineRegressionRule, createDecisionRule, createGuardrailRule, createLlmUsageRule, createMaxStepDurationRule, createObservedOutcomeRule, createRequireCompletedRule, createRetrievalRule, createRunDepthRule, createRunDurationRule, createRunEventCountRule, createRunStatusRule, createSafetyOversizedAttributeRule, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createStallDetectionRule, createStructureCycleRule, createStructureIncompleteRule, createStructureOrphanRule, createStructureParallelWidthRule, createStructureRelationshipRule, createToolFailureRule, createToolOrderingRule, createToolUsageRule, defineTraceContract, deriveFailureFacts, evaluateTraceContract, evaluateTraceContractRead, projectLogicalEvents, resolveCanonicalToolName, runTraceChecks, summarizeSemanticParity } from './chunk-6LP2J5CA.mjs';
-import './chunk-3XS5O4JI.mjs';
+export { buildTraceFacts, createBaselineRegressionRule, createDecisionRule, createGuardrailRule, createLlmUsageRule, createMaxStepDurationRule, createObservedOutcomeRule, createRequireCompletedRule, createRetrievalRule, createRunDepthRule, createRunDurationRule, createRunEventCountRule, createRunStatusRule, createSafetyOversizedAttributeRule, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createStallDetectionRule, createStructureCycleRule, createStructureIncompleteRule, createStructureOrphanRule, createStructureParallelWidthRule, createStructureRelationshipRule, createToolFailureRule, createToolOrderingRule, createToolUsageRule, defineTraceContract, deriveFailureFacts, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, lintTraceContract, projectLogicalEvents, resolveCanonicalToolName, resolveTraceContractScope, runTraceChecks, summarizeSemanticParity, workflowMetadataForRun } from './chunk-43SHIPZM.mjs';
+import './chunk-R4SSYU6D.mjs';
 import './chunk-U25RHRSU.mjs';
 import './chunk-VU6O5QAH.mjs';
 export { PROGRAMMATIC_DIAGNOSTIC_SPECS, formatProgrammaticDiagnostic } from './chunk-FWK3Q3OJ.mjs';