@replayci/replay 0.1.7 → 0.1.8

package/dist/index.d.cts

@@ -375,6 +375,41 @@ interface Store {
  * @see specs/replay-v1.md § SDK API surface
  */
 
+/**
+ * Stage identifiers for the enforcement pipeline decision trace.
+ * @see specs/decision-trace.md § Core types
+ */
+type TraceStage = "extract" | "narrow" | "pre_check" | "validate" | "cross_step" | "phase" | "policy" | "limit" | "gate" | "execute" | "finalize";
+/**
+ * A single decision entry in the enforcement trace.
+ * @see specs/decision-trace.md § Core types
+ */
+type TraceEntry = {
+    stage: TraceStage;
+    tool: string | null;
+    verdict: "allow" | "remove" | "block" | "narrow" | "skip" | "info" | "error";
+    reason: string;
+    checked: Record<string, unknown>;
+    found: Record<string, unknown>;
+};
+/**
+ * Push-only interface passed to stage functions.
+ * @see specs/decision-trace.md § TraceContext
+ */
+type TraceContext = {
+    push(entry: TraceEntry): void;
+    readonly entries: readonly TraceEntry[];
+};
+/**
+ * Full decision trace for one enforcement cycle.
+ * @see specs/decision-trace.md § Core types
+ */
+type DecisionTrace = {
+    sessionId: string;
+    stepIndex: number;
+    complete: boolean;
+    entries: TraceEntry[];
+};
 /**
  * Workflow attachment options for `replay()`.
  * Either root-create or child-attach — never both.
@@ -536,6 +571,12 @@ type ReplaySession<T> = {
      * Returns null when not in shadow mode or before first call.
      */
     getLastShadowDelta: () => ShadowDelta | null;
+    /**
+     * Return the DecisionTrace for the most recent enforcement cycle.
+     * Returns null before the first call. Returns partial traces (complete: false) after faults.
+     * @see specs/decision-trace.md § session.getLastTrace()
+     */
+    getLastTrace: () => DecisionTrace | null;
     /**
      * v3: Manually restrict available tools within compiled legal space.
      * Cannot add tools that the compiled session would remove.
@@ -744,6 +785,8 @@ type ReplayCapture = CapturedCall & {
         phase: string | null;
         phase_transition: string | null;
         shadow_delta?: ShadowDelta;
+        /** Decision trace for this enforcement cycle. Optional for backward compat. */
+        trace?: DecisionTrace;
         receipt: null;
     };
 };
@@ -850,6 +893,10 @@ type ReplayDiagnosticEvent = {
     type: "replay_capture_error";
     session_id: string;
     details: string;
+} | {
+    type: "replay_trace";
+    session_id: string;
+    trace: DecisionTrace;
 };
 /**
  * Workflow state snapshot returned by `session.getWorkflowState()`.
@@ -1171,4 +1218,4 @@ declare class RuntimeClient {
     private recordFailure;
 }
 
-export { type BlockReason, type BlockedToolCall, type CircuitBreakerResult, type CompareAndSetResult, type CompletedStep, type CompletedStepSnapshot, type CompletedToolCall, type CompletedToolCallSnapshot, type ConstraintFailure, type ConstraintVerdict, type ContractFailure, type CrossStepCaptureResult, type CrossStepFailure, type CrossStepResult, type DecisionOutcome, type FlushResult, type GateMode, type LoopDetectionResult, MemoryStore, type NarrowRemovalReason, type NarrowResult, type NarrowedTool, type ObserveActivationReasonCode, type ObserveDiagnosticEvent, type ObserveHandle, type ObserveHealthSnapshot, type ObserveOptions, type ObserveSessionState, type PendingEntry, type PhaseTransitionResult, type PolicyVerdict, type PreconditionEvidence, type ReplayCapture, ReplayConfigError, ReplayContractError, type ReplayDecision, type ReplayDiagnosticEvent, type ReplayHealthSnapshot, ReplayKillError, type ReplayMode, type ReplayOptions, type ReplaySession, type ReplayTiming, type ResponseMetadata, RuntimeClient, RuntimeClientError, type RuntimeClientHealth, type RuntimeClientOptions, type RuntimeSessionInit, type RuntimeSessionResult, type SessionState, type SessionStateSnapshot, type ShadowDelta, type Store, type ToolDefinition, type ToolExecutor, type ValidationResult, type WrappedExecutorResult, type WrappedToolExecutor, createRuntimeClient, observe, prepareContracts, replay, validate };
+export { type BlockReason, type BlockedToolCall, type CircuitBreakerResult, type CompareAndSetResult, type CompletedStep, type CompletedStepSnapshot, type CompletedToolCall, type CompletedToolCallSnapshot, type ConstraintFailure, type ConstraintVerdict, type ContractFailure, type CrossStepCaptureResult, type CrossStepFailure, type CrossStepResult, type DecisionOutcome, type DecisionTrace, type FlushResult, type GateMode, type LoopDetectionResult, MemoryStore, type NarrowRemovalReason, type NarrowResult, type NarrowedTool, type ObserveActivationReasonCode, type ObserveDiagnosticEvent, type ObserveHandle, type ObserveHealthSnapshot, type ObserveOptions, type ObserveSessionState, type PendingEntry, type PhaseTransitionResult, type PolicyVerdict, type PreconditionEvidence, type ReplayCapture, ReplayConfigError, ReplayContractError, type ReplayDecision, type ReplayDiagnosticEvent, type ReplayHealthSnapshot, ReplayKillError, type ReplayMode, type ReplayOptions, type ReplaySession, type ReplayTiming, type ResponseMetadata, RuntimeClient, RuntimeClientError, type RuntimeClientHealth, type RuntimeClientOptions, type RuntimeSessionInit, type RuntimeSessionResult, type SessionState, type SessionStateSnapshot, type ShadowDelta, type Store, type ToolDefinition, type ToolExecutor, type TraceContext, type TraceEntry, type TraceStage, type ValidationResult, type WrappedExecutorResult, type WrappedToolExecutor, createRuntimeClient, observe, prepareContracts, replay, validate };

package/dist/index.d.ts

@@ -375,6 +375,41 @@ interface Store {
  * @see specs/replay-v1.md § SDK API surface
  */
 
+/**
+ * Stage identifiers for the enforcement pipeline decision trace.
+ * @see specs/decision-trace.md § Core types
+ */
+type TraceStage = "extract" | "narrow" | "pre_check" | "validate" | "cross_step" | "phase" | "policy" | "limit" | "gate" | "execute" | "finalize";
+/**
+ * A single decision entry in the enforcement trace.
+ * @see specs/decision-trace.md § Core types
+ */
+type TraceEntry = {
+    stage: TraceStage;
+    tool: string | null;
+    verdict: "allow" | "remove" | "block" | "narrow" | "skip" | "info" | "error";
+    reason: string;
+    checked: Record<string, unknown>;
+    found: Record<string, unknown>;
+};
+/**
+ * Push-only interface passed to stage functions.
+ * @see specs/decision-trace.md § TraceContext
+ */
+type TraceContext = {
+    push(entry: TraceEntry): void;
+    readonly entries: readonly TraceEntry[];
+};
+/**
+ * Full decision trace for one enforcement cycle.
+ * @see specs/decision-trace.md § Core types
+ */
+type DecisionTrace = {
+    sessionId: string;
+    stepIndex: number;
+    complete: boolean;
+    entries: TraceEntry[];
+};
 /**
  * Workflow attachment options for `replay()`.
  * Either root-create or child-attach — never both.
@@ -536,6 +571,12 @@ type ReplaySession<T> = {
      * Returns null when not in shadow mode or before first call.
      */
     getLastShadowDelta: () => ShadowDelta | null;
+    /**
+     * Return the DecisionTrace for the most recent enforcement cycle.
+     * Returns null before the first call. Returns partial traces (complete: false) after faults.
+     * @see specs/decision-trace.md § session.getLastTrace()
+     */
+    getLastTrace: () => DecisionTrace | null;
     /**
      * v3: Manually restrict available tools within compiled legal space.
      * Cannot add tools that the compiled session would remove.
@@ -744,6 +785,8 @@ type ReplayCapture = CapturedCall & {
         phase: string | null;
         phase_transition: string | null;
         shadow_delta?: ShadowDelta;
+        /** Decision trace for this enforcement cycle. Optional for backward compat. */
+        trace?: DecisionTrace;
         receipt: null;
     };
 };
@@ -850,6 +893,10 @@ type ReplayDiagnosticEvent = {
     type: "replay_capture_error";
     session_id: string;
     details: string;
+} | {
+    type: "replay_trace";
+    session_id: string;
+    trace: DecisionTrace;
 };
 /**
  * Workflow state snapshot returned by `session.getWorkflowState()`.
@@ -1171,4 +1218,4 @@ declare class RuntimeClient {
     private recordFailure;
 }
 
-export { type BlockReason, type BlockedToolCall, type CircuitBreakerResult, type CompareAndSetResult, type CompletedStep, type CompletedStepSnapshot, type CompletedToolCall, type CompletedToolCallSnapshot, type ConstraintFailure, type ConstraintVerdict, type ContractFailure, type CrossStepCaptureResult, type CrossStepFailure, type CrossStepResult, type DecisionOutcome, type FlushResult, type GateMode, type LoopDetectionResult, MemoryStore, type NarrowRemovalReason, type NarrowResult, type NarrowedTool, type ObserveActivationReasonCode, type ObserveDiagnosticEvent, type ObserveHandle, type ObserveHealthSnapshot, type ObserveOptions, type ObserveSessionState, type PendingEntry, type PhaseTransitionResult, type PolicyVerdict, type PreconditionEvidence, type ReplayCapture, ReplayConfigError, ReplayContractError, type ReplayDecision, type ReplayDiagnosticEvent, type ReplayHealthSnapshot, ReplayKillError, type ReplayMode, type ReplayOptions, type ReplaySession, type ReplayTiming, type ResponseMetadata, RuntimeClient, RuntimeClientError, type RuntimeClientHealth, type RuntimeClientOptions, type RuntimeSessionInit, type RuntimeSessionResult, type SessionState, type SessionStateSnapshot, type ShadowDelta, type Store, type ToolDefinition, type ToolExecutor, type ValidationResult, type WrappedExecutorResult, type WrappedToolExecutor, createRuntimeClient, observe, prepareContracts, replay, validate };
+export { type BlockReason, type BlockedToolCall, type CircuitBreakerResult, type CompareAndSetResult, type CompletedStep, type CompletedStepSnapshot, type CompletedToolCall, type CompletedToolCallSnapshot, type ConstraintFailure, type ConstraintVerdict, type ContractFailure, type CrossStepCaptureResult, type CrossStepFailure, type CrossStepResult, type DecisionOutcome, type DecisionTrace, type FlushResult, type GateMode, type LoopDetectionResult, MemoryStore, type NarrowRemovalReason, type NarrowResult, type NarrowedTool, type ObserveActivationReasonCode, type ObserveDiagnosticEvent, type ObserveHandle, type ObserveHealthSnapshot, type ObserveOptions, type ObserveSessionState, type PendingEntry, type PhaseTransitionResult, type PolicyVerdict, type PreconditionEvidence, type ReplayCapture, ReplayConfigError, ReplayContractError, type ReplayDecision, type ReplayDiagnosticEvent, type ReplayHealthSnapshot, ReplayKillError, type ReplayMode, type ReplayOptions, type ReplaySession, type ReplayTiming, type ResponseMetadata, RuntimeClient, RuntimeClientError, type RuntimeClientHealth, type RuntimeClientOptions, type RuntimeSessionInit, type RuntimeSessionResult, type SessionState, type SessionStateSnapshot, type ShadowDelta, type Store, type ToolDefinition, type ToolExecutor, type TraceContext, type TraceEntry, type TraceStage, type ValidationResult, type WrappedExecutorResult, type WrappedToolExecutor, createRuntimeClient, observe, prepareContracts, replay, validate };