agent-inspect 6.20.0 → 6.22.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-rVpX5PPh.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-rVpX5PPh.cjs';
-export { PROGRAMMATIC_DIAGNOSTIC_SPECS, ProgrammaticDiagnosticCode, ProgrammaticDiagnosticSpec, formatProgrammaticDiagnostic } from './readers.cjs';
-import { a as TraceReadResult } from './index-vqr-g6ev.cjs';
+import { L as LogicalTraceEvent, a as LogicalProjectionDiagnostic, T as TraceCheckInput, b as TraceCheckDiagnostic, S as SessionWorkflowMetadata, c as TraceCheckResult } from './index-CR4CCRqP.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-CR4CCRqP.cjs';
+export { P as PROGRAMMATIC_DIAGNOSTIC_SPECS, a as ProgrammaticDiagnosticCode, b as ProgrammaticDiagnosticSpec, f as formatProgrammaticDiagnostic } from './programmatic-gZTWLObB.cjs';
+import { g as TraceReadResult } from './index-DLLz9sce.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';
 
@@ -65,6 +67,43 @@ declare function deriveFailureFacts(logicalEvents: readonly LogicalTraceEvent[])
     failureRoleCounts: FailureRoleCounts;
 };
 
+/**
+ * Read-time typed relationship facts (6.22).
+ *
+ * Facts never rewrite parent hierarchy. Confidence is explicit or correlated only —
+ * never inferred from timestamps alone.
+ *
+ * @experimental Available through `agent-inspect/checks`.
+ */
+
+type TraceRelationshipType = "parent-child" | "source-lineage" | "attempt-of" | "retry-of" | "fallback-of" | "remediation-of" | "evidence-for" | "accepted-by" | "supersedes";
+type TraceRelationshipConfidence = "explicit" | "correlated" | "unknown";
+/**
+ * Bounded relationship edge derived at read time.
+ *
+ * @experimental
+ */
+interface TraceRelationship {
+    type: TraceRelationshipType;
+    fromEventId: string;
+    toEventId?: string;
+    externalRef?: string;
+    confidence: TraceRelationshipConfidence;
+    basis: readonly string[];
+}
+interface TraceRelationshipDiagnostic {
+    code: string;
+    message: string;
+    eventId?: string;
+}
+/**
+ * Derive typed relationship facts from persisted events without mutating hierarchy.
+ */
+declare function deriveRelationshipFacts(events: readonly PersistedInspectEvent[]): {
+    relationships: readonly TraceRelationship[];
+    diagnostics: readonly TraceRelationshipDiagnostic[];
+};
+
 /**
  * Shared semantic parity summary over logical lifecycle projection.
  *
@@ -125,6 +164,18 @@ interface TraceFacts {
      * @experimental Additive in 6.19.
      */
     readonly failuresByRole: ReadonlyMap<DerivedFailureRole, readonly DerivedFailureFact[]>;
+    /**
+     * Read-time typed relationship facts. Does not rewrite parent hierarchy.
+     *
+     * @experimental Additive in 6.22.
+     */
+    readonly relationships: readonly TraceRelationship[];
+    /**
+     * Diagnostics for unsupported or unresolved relationships.
+     *
+     * @experimental Additive in 6.22.
+     */
+    readonly relationshipDiagnostics: readonly TraceRelationshipDiagnostic[];
 }
 /**
  * Build TraceFacts from a TraceReadResult or normalized persisted events.
@@ -134,6 +185,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.
  */
@@ -194,9 +283,35 @@ interface TraceContractLlmRules {
     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;
 }
 /**
  * One deterministic alternate path. Branch contracts are one level only —
@@ -231,9 +346,21 @@ type TraceContractBody = {
     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;
 }
 /**
@@ -285,4 +412,4 @@ declare function lintTraceContract(contract: TraceContract): TraceContractLintDi
  */
 declare function explainTraceContract(contract: TraceContract): string[];
 
-export { type DerivedFailureConfidence, type DerivedFailureFact, type DerivedFailureRole, type FailureRoleCounts, LogicalProjectionDiagnostic, LogicalTraceEvent, type SemanticParitySummary, TraceCheckInput, TraceCheckResult, type TraceContract, type TraceContractAlternativeBranch, type TraceContractAlternatives, type TraceContractBody, type TraceContractInput, type TraceContractLintDiagnostic, type TraceContractLlmRules, type TraceContractObservationRules, type TraceContractRunRules, type TraceContractToolRules, type TraceFacts, buildTraceFacts, defineTraceContract, deriveFailureFacts, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, lintTraceContract, 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, type TraceRelationship, type TraceRelationshipConfidence, type TraceRelationshipDiagnostic, type TraceRelationshipType, buildTraceFacts, defineTraceContract, deriveFailureFacts, deriveRelationshipFacts, 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-Bg9ZdsdS.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-Bg9ZdsdS.js';
-export { PROGRAMMATIC_DIAGNOSTIC_SPECS, ProgrammaticDiagnosticCode, ProgrammaticDiagnosticSpec, formatProgrammaticDiagnostic } from './readers.js';
-import { a as TraceReadResult } from './index-AMAGuO_i.js';
+import { L as LogicalTraceEvent, a as LogicalProjectionDiagnostic, T as TraceCheckInput, b as TraceCheckDiagnostic, S as SessionWorkflowMetadata, c as TraceCheckResult } from './index-CtK_p-ps.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-CtK_p-ps.js';
+export { P as PROGRAMMATIC_DIAGNOSTIC_SPECS, a as ProgrammaticDiagnosticCode, b as ProgrammaticDiagnosticSpec, f as formatProgrammaticDiagnostic } from './programmatic-gZTWLObB.js';
+import { g as TraceReadResult } from './index-D72DPqAF.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';
 
@@ -65,6 +67,43 @@ declare function deriveFailureFacts(logicalEvents: readonly LogicalTraceEvent[])
     failureRoleCounts: FailureRoleCounts;
 };
 
+/**
+ * Read-time typed relationship facts (6.22).
+ *
+ * Facts never rewrite parent hierarchy. Confidence is explicit or correlated only —
+ * never inferred from timestamps alone.
+ *
+ * @experimental Available through `agent-inspect/checks`.
+ */
+
+type TraceRelationshipType = "parent-child" | "source-lineage" | "attempt-of" | "retry-of" | "fallback-of" | "remediation-of" | "evidence-for" | "accepted-by" | "supersedes";
+type TraceRelationshipConfidence = "explicit" | "correlated" | "unknown";
+/**
+ * Bounded relationship edge derived at read time.
+ *
+ * @experimental
+ */
+interface TraceRelationship {
+    type: TraceRelationshipType;
+    fromEventId: string;
+    toEventId?: string;
+    externalRef?: string;
+    confidence: TraceRelationshipConfidence;
+    basis: readonly string[];
+}
+interface TraceRelationshipDiagnostic {
+    code: string;
+    message: string;
+    eventId?: string;
+}
+/**
+ * Derive typed relationship facts from persisted events without mutating hierarchy.
+ */
+declare function deriveRelationshipFacts(events: readonly PersistedInspectEvent[]): {
+    relationships: readonly TraceRelationship[];
+    diagnostics: readonly TraceRelationshipDiagnostic[];
+};
+
 /**
  * Shared semantic parity summary over logical lifecycle projection.
  *
@@ -125,6 +164,18 @@ interface TraceFacts {
      * @experimental Additive in 6.19.
      */
     readonly failuresByRole: ReadonlyMap<DerivedFailureRole, readonly DerivedFailureFact[]>;
+    /**
+     * Read-time typed relationship facts. Does not rewrite parent hierarchy.
+     *
+     * @experimental Additive in 6.22.
+     */
+    readonly relationships: readonly TraceRelationship[];
+    /**
+     * Diagnostics for unsupported or unresolved relationships.
+     *
+     * @experimental Additive in 6.22.
+     */
+    readonly relationshipDiagnostics: readonly TraceRelationshipDiagnostic[];
 }
 /**
  * Build TraceFacts from a TraceReadResult or normalized persisted events.
@@ -134,6 +185,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.
  */
@@ -194,9 +283,35 @@ interface TraceContractLlmRules {
     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;
 }
 /**
  * One deterministic alternate path. Branch contracts are one level only —
@@ -231,9 +346,21 @@ type TraceContractBody = {
     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;
 }
 /**
@@ -285,4 +412,4 @@ declare function lintTraceContract(contract: TraceContract): TraceContractLintDi
  */
 declare function explainTraceContract(contract: TraceContract): string[];
 
-export { type DerivedFailureConfidence, type DerivedFailureFact, type DerivedFailureRole, type FailureRoleCounts, LogicalProjectionDiagnostic, LogicalTraceEvent, type SemanticParitySummary, TraceCheckInput, TraceCheckResult, type TraceContract, type TraceContractAlternativeBranch, type TraceContractAlternatives, type TraceContractBody, type TraceContractInput, type TraceContractLintDiagnostic, type TraceContractLlmRules, type TraceContractObservationRules, type TraceContractRunRules, type TraceContractToolRules, type TraceFacts, buildTraceFacts, defineTraceContract, deriveFailureFacts, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, lintTraceContract, 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, type TraceRelationship, type TraceRelationshipConfidence, type TraceRelationshipDiagnostic, type TraceRelationshipType, buildTraceFacts, defineTraceContract, deriveFailureFacts, deriveRelationshipFacts, 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, explainTraceContract, lintTraceContract, projectLogicalEvents, resolveCanonicalToolName, runTraceChecks, summarizeSemanticParity } from './chunk-G47KQB42.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, deriveRelationshipFacts, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, lintTraceContract, projectLogicalEvents, resolveCanonicalToolName, resolveTraceContractScope, runTraceChecks, summarizeSemanticParity, workflowMetadataForRun } from './chunk-OG3GAWCX.mjs';
+import './chunk-R4SSYU6D.mjs';
 import './chunk-U25RHRSU.mjs';
 import './chunk-VU6O5QAH.mjs';
 export { PROGRAMMATIC_DIAGNOSTIC_SPECS, formatProgrammaticDiagnostic } from './chunk-FWK3Q3OJ.mjs';

package/packages/core/dist/{chunk-HT54OLPE.mjs → chunk-NDRMIL7Z.mjs}

@@ -4,6 +4,106 @@ import { parseTraceJsonl } from './chunk-WRE4CNPF.mjs';
 import { readFile, readdir } from 'fs/promises';
 import path from 'path';
 
+// packages/core/src/readers/mapping-ledger.ts
+var OPENINFERENCE_MAPPING_LEDGER = {
+  id: "openinference-to-agent-inspect",
+  sourceFormat: "openinference-json",
+  targetFormat: "agent-inspect-persisted-1.0",
+  convention: {
+    name: "OpenInference",
+    version: "0.2.x",
+    specUrl: "https://github.com/Arize-ai/openinference"
+  },
+  entries: [
+    {
+      source: "span.context.span_id",
+      target: "eventId / trace.spanId",
+      transformation: "hex identity when present",
+      confidence: "explicit",
+      loss: "none"
+    },
+    {
+      source: "span.context.trace_id",
+      target: "trace.traceId",
+      transformation: "hex identity when present",
+      confidence: "explicit",
+      loss: "none"
+    },
+    {
+      source: "span.parent_id",
+      target: "parentId",
+      transformation: "direct when resolvable in batch",
+      confidence: "explicit",
+      loss: "none"
+    },
+    {
+      source: "attributes.openinference.span.kind",
+      target: "kind",
+      transformation: "enumerated kind map with degrade-to-LOGIC",
+      confidence: "correlated",
+      loss: "kind-degraded",
+      privacyDecision: "unknown kinds preserved under bounds as attributes"
+    },
+    {
+      source: "attributes.llm.input_messages / output_messages",
+      target: "inputSummary / outputSummary",
+      transformation: "bounded summaries only",
+      confidence: "heuristic",
+      loss: "privacy-redacted",
+      privacyDecision: "raw message bodies are not required and may be omitted"
+    }
+  ],
+  knownLosses: [
+    "Chain-of-thought / private reasoning fields are never imported as raw content.",
+    "Oversized attributes are bounded or marked unsupported.",
+    "Unknown OpenInference kinds degrade to LOGIC with a warning."
+  ]
+};
+var OTLP_JSON_MAPPING_LEDGER = {
+  id: "otlp-json-to-agent-inspect",
+  sourceFormat: "otlp-json",
+  targetFormat: "agent-inspect-persisted-1.0",
+  convention: {
+    name: "OpenTelemetry GenAI semantic conventions",
+    version: "1.36.0",
+    specUrl: "https://opentelemetry.io/docs/specs/semconv/gen-ai/"
+  },
+  entries: [
+    {
+      source: "resourceSpans[].scopeSpans[].spans[]",
+      target: "PersistedInspectEvent[]",
+      transformation: "one span \u2192 one event when mappable",
+      confidence: "explicit",
+      loss: "none"
+    },
+    {
+      source: "span.attributes[gen_ai.*]",
+      target: "attributes / tokenUsage / kind",
+      transformation: "pinned GenAI attribute family",
+      confidence: "correlated",
+      loss: "bounded"
+    },
+    {
+      source: "span.attributes (unknown keys)",
+      target: "attributes.* / unsupportedFields",
+      transformation: "preserve under bounds or list as unsupported",
+      confidence: "unknown",
+      loss: "unsupported"
+    }
+  ],
+  knownLosses: [
+    "Schema 1.0 is not bound to Development-status OTel GenAI revisions.",
+    "Status rewrite to fit a local narrative is forbidden.",
+    "Payload bodies may be omitted; digests are optional application metadata."
+  ]
+};
+var BUILTIN_MAPPING_LEDGERS = Object.freeze([
+  OPENINFERENCE_MAPPING_LEDGER,
+  OTLP_JSON_MAPPING_LEDGER
+]);
+function getMappingLedger(id) {
+  return BUILTIN_MAPPING_LEDGERS.find((ledger) => ledger.id === id);
+}
 var DEFAULT_MAX_TRACE_INPUT_BYTES = 10 * 1024 * 1024;
 var MIN_DETECTION_CONFIDENCE = 0.5;
 var AMBIGUOUS_CONFIDENCE_DELTA = 0.05;
@@ -1623,6 +1723,6 @@ function openTraceText(content, options = {}) {
   return openTrace({ type: "string", content }, options);
 }
 
-export { DEFAULT_TRACE_READERS, TraceReadError, agentInspectJsonlReader, assertTraceInput, detectTraceFormat, openInferenceJsonReader, openTrace, openTraceDirectory, openTraceFile, openTraceText, otlpJsonReader, readTrace };
-//# sourceMappingURL=chunk-HT54OLPE.mjs.map
-//# sourceMappingURL=chunk-HT54OLPE.mjs.map
+export { BUILTIN_MAPPING_LEDGERS, DEFAULT_TRACE_READERS, OPENINFERENCE_MAPPING_LEDGER, OTLP_JSON_MAPPING_LEDGER, TraceReadError, agentInspectJsonlReader, assertTraceInput, detectTraceFormat, getMappingLedger, openInferenceJsonReader, openTrace, openTraceDirectory, openTraceFile, openTraceText, otlpJsonReader, readTrace };
+//# sourceMappingURL=chunk-NDRMIL7Z.mjs.map
+//# sourceMappingURL=chunk-NDRMIL7Z.mjs.map