@replayci/replay 0.1.4 → 0.1.6

package/dist/index.d.cts

@@ -1,5 +1,66 @@
-import { Contract } from '@replayci/contracts-core';
+import { Contract, CommitRequirement, ToolCallResult, ProviderConstraints } from '@replayci/contracts-core';
 
+declare const CAPTURE_SCHEMA_VERSION_CURRENT: "2026-03-09";
+type CaptureProvider = "openai" | "anthropic";
+type CaptureMessage = Record<string, unknown>;
+type CapturedRequestTool = {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+    input_schema?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+type CapturedToolCall = {
+    name: string;
+    arguments?: string;
+};
+type CaptureRequest = {
+    messages?: CaptureMessage[];
+    tools: CapturedRequestTool[];
+    tool_choice?: string;
+};
+type CaptureResponse = {
+    tool_calls: CapturedToolCall[];
+    content: string | null;
+    text_blocks?: string[];
+};
+type CaptureValidation = {
+    pass: boolean;
+    failures: ContractFailure[];
+    retries_used: number;
+    contracts_evaluated: string[];
+};
+type CaptureUsage = {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+};
+type CapturedCall = {
+    schema_version: typeof CAPTURE_SCHEMA_VERSION_CURRENT;
+    agent: string;
+    timestamp: string;
+    provider: CaptureProvider;
+    model_id: string;
+    primary_tool_name: string | null;
+    tool_names: string[];
+    request: CaptureRequest;
+    response: CaptureResponse;
+    validation?: CaptureValidation;
+    usage?: CaptureUsage;
+    latency_ms: number;
+    sdk_session_id?: string;
+};
+
+interface FlushResult {
+    /** Number of captures in the buffer when flush was called */
+    captured: number;
+    /** Number of captures successfully sent to the server */
+    sent: number;
+    /** Whether the handle is active (false = no apiKey or disabled) */
+    active: boolean;
+    /** Error messages from send attempts */
+    errors: string[];
+}
 type ContractFailure = {
     path: string;
     operator: string;
@@ -93,6 +154,11 @@ type ObserveDiagnosticEvent = {
     type: "unsupported_client";
     mode: "observe";
     detail: string;
+} | {
+    type: "activation_warning";
+    message: string;
+} | {
+    type: "flush_empty";
 };
 type ObserveOptions = {
     agent?: string;
@@ -109,7 +175,7 @@ type ObserveOptions = {
 };
 type ObserveHandle<T> = {
     client: T;
-    flush: () => Promise<void>;
+    flush: () => Promise<FlushResult>;
     restore: () => void;
     getHealth: () => ObserveHealthSnapshot;
 };
@@ -123,4 +189,957 @@ type ValidateOptions = {
 declare function prepareContracts(input: string | string[] | Contract | Contract[]): Contract[];
 declare function validate(response: unknown, opts?: ValidateOptions): ValidationResult;
 
-export { type ContractFailure, type ObserveActivationReasonCode, type ObserveDiagnosticEvent, type ObserveHandle, type ObserveHealthSnapshot, type ObserveOptions, type ObserveSessionState, type ValidationResult, observe, prepareContracts, validate };
+type SupportedProvider = "openai" | "anthropic";
+
+/**
+ * Session state types for cross-step enforcement (v2).
+ * @see specs/runtime-replay.md § Stage 6: Finalize executed step
+ * @see specs/replay-v2.md § Session state model
+ * @see specs/replay-governance-evidence-spine.md § Session state model
+ */
+
+/**
+ * Authoritative session state. Steps contains only committed executed steps.
+ * @see specs/replay-v2.md § Session state model
+ */
+type SessionState = {
+    sessionId: string;
+    agent: string | null;
+    principal: Record<string, unknown> | null;
+    startedAt: Date;
+    /** Current enforcement tier. Strong = authoritative server round-trip; compat = local only. */
+    tier: "strong" | "compat";
+    stateVersion: number;
+    controlRevision: number;
+    currentPhase: string | null;
+    totalStepCount: number;
+    totalToolCalls: number;
+    actualCost: number;
+    totalCost: number;
+    toolCallCounts: Map<string, number>;
+    forbiddenTools: Set<string>;
+    satisfiedPreconditions: Map<string, PreconditionEvidence>;
+    steps: CompletedStep[];
+    pendingEntries: PendingEntry[];
+    lastStep: CompletedStep | null;
+    consecutiveBlockCount: number;
+    consecutiveErrorCount: number;
+    totalBlockCount: number;
+    totalUnguardedCalls: number;
+    killed: boolean;
+    /** Hash of compiled contracts when state was written. Used for drift detection on resume. */
+    contractHash: string | null;
+};
+/**
+ * A committed executed step in the session record.
+ * @see specs/replay-v2.md § Session state model — CompletedStep
+ */
+type CompletedStep = {
+    stepIndex: number;
+    stepId: string;
+    toolCalls: CompletedToolCall[];
+    proposal_decision: "allowed";
+    commit_state: "committed";
+    commit_tier: "strong" | "compat";
+    max_evidence_level: "acknowledged";
+    invariantFailures: ContractFailure[];
+    phase: string | null;
+    phaseTransition: string | null;
+    completedAt: string;
+    outputExtract: Record<string, unknown>;
+    finish_reason: string | null;
+    model: string | null;
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+    } | null;
+};
+/**
+ * A committed tool call within a step.
+ * @see specs/replay-v2.md § Session state model — CompletedToolCall
+ */
+type CompletedToolCall = {
+    toolName: string;
+    arguments_hash: string;
+    proposal_decision: "allowed";
+    execution_state: "outcome_recorded";
+    evidence_level: "acknowledged";
+    commit_requirement: CommitRequirement;
+    commit_state: "committed";
+    commit_tier: "strong" | "compat";
+    executor_attested: boolean;
+    contractFile: string | null;
+    resourceValues: Record<string, unknown> | null;
+    policyVerdict: unknown | null;
+    constraintVerdict: unknown | null;
+};
+/**
+ * Result of cross-step validation (preconditions + forbids_after).
+ * @see specs/replay-v2.md § Stage 3 extensions: Validate
+ */
+type CrossStepResult = {
+    passed: boolean;
+    failures: CrossStepFailure[];
+};
+type CrossStepFailure = {
+    toolName: string;
+    reason: CrossStepFailureReason;
+    detail: string;
+};
+type CrossStepFailureReason = "precondition_not_met" | "forbidden_tool" | "argument_value_mismatch";
+/**
+ * A tool call pending execution evidence.
+ * @see specs/replay-v2.md § Stage 6: Finalize executed step
+ */
+type PendingEntry = {
+    stepId: string;
+    toolName: string;
+    arguments_hash: string;
+    tool_call_id: string | null;
+    position_index: number;
+    createdAt: string;
+};
+/**
+ * Evidence stored in the satisfiedPreconditions cache.
+ * Key format: "tool_name" or "tool_name:resource_value".
+ */
+type PreconditionEvidence = unknown;
+type LoopDetectionResult = {
+    triggered: boolean;
+    matchCount: number;
+    threshold: number;
+    window: number;
+};
+type CircuitBreakerResult = {
+    triggered: boolean;
+    reason: "consecutive_blocks" | "consecutive_errors" | null;
+};
+type DecisionOutcome = "allowed" | "blocked" | "error";
+
+/**
+ * Store interface for durable session state persistence.
+ *
+ * compareAndSet() provides atomic version-checked state updates.
+ * load() retrieves the current state.
+ * appendCapture() appends a capture to the durable log.
+ *
+ * @see specs/replay-v2.md § Store interface in v2
+ */
+
+/**
+ * Result of a compareAndSet operation.
+ */
+type CompareAndSetResult = {
+    /** Whether the update was applied. False if currentVersion didn't match. */
+    success: boolean;
+};
+/**
+ * Durable store interface for session state and captures.
+ *
+ * The default in-memory implementation (MemoryStore) replicates current
+ * closure-variable behavior. Custom implementations can persist to
+ * databases, files, or external services.
+ */
+interface Store {
+    /**
+     * Atomic state update with version check.
+     * Only applies the update if the store's current stateVersion matches
+     * `currentVersion`. Prevents stale writes from concurrent access.
+     *
+     * @param currentVersion - Expected current stateVersion
+     * @param newState - New state to write
+     * @returns Whether the update was applied
+     */
+    compareAndSet(currentVersion: number, newState: SessionState): CompareAndSetResult | Promise<CompareAndSetResult>;
+    /**
+     * Load the current session state.
+     * Returns null if no state has been stored yet.
+     */
+    load(): SessionState | null | Promise<SessionState | null>;
+    /**
+     * Append a capture to the durable log.
+     * Called for every decision (including blocked calls that don't advance state).
+     */
+    appendCapture(capture: CapturedCall): void | Promise<void>;
+}
+
+/**
+ * Types for the replay() enforcement pipeline.
+ * @see specs/runtime-replay.md § SDK API surface
+ * @see specs/replay-v1.md § SDK API surface
+ */
+
+/**
+ * Workflow attachment options for `replay()`.
+ * Either root-create or child-attach — never both.
+ * @see specs/replay-v4.md § SDK workflow surface
+ */
+type WorkflowOptions = WorkflowRootOptions | WorkflowChildOptions;
+/** Root session workflow options. */
+type WorkflowRootOptions = {
+    type: "root";
+    /** Workflow ID. Generated by SDK if omitted. */
+    workflowId?: string;
+    /** Role name this root session fulfils in the workflow. */
+    role: string;
+    /** Explicit path to workflow.yaml. Overrides auto-discovery from contractsDir. */
+    workflowYamlPath?: string;
+};
+/** Child session workflow options. */
+type WorkflowChildOptions = {
+    type: "child";
+    /** Workflow ID of the parent workflow to attach to. */
+    workflowId: string;
+    /** Role name this child session fulfils in the workflow. */
+    role: string;
+    /** Session ID of the parent session that offered the handoff. */
+    parentSessionId: string;
+    /** Handoff ID to claim. */
+    handoffId: string;
+};
+type ReplayMode = "enforce" | "shadow" | "log-only";
+/** @see specs/runtime-replay.md § Stage 4: Gate */
+type GateMode = "reject_all" | "strip_partial" | "strip_blocked";
+/** @see specs/replay-v1.md § SDK API surface — replay() */
+type ReplayOptions = {
+    contracts?: Contract | Contract[];
+    contractsDir?: string;
+    /** Explicit path to session.yaml. Overrides auto-discovery from contractsDir. */
+    sessionYamlPath?: string;
+    /**
+     * v4: Workflow attachment block.
+     * When present, the session participates in a durable workflow.
+     * Root sessions create the workflow; child sessions claim a handoff.
+     * @see specs/replay-v4.md § SDK workflow surface
+     */
+    workflow?: WorkflowOptions;
+    agent?: string;
+    sessionId?: string;
+    mode?: ReplayMode;
+    gate?: GateMode;
+    onError?: "block" | "allow";
+    unmatchedPolicy?: "block" | "allow";
+    /** Caller-supplied identity for policy evaluation (P1). */
+    principal?: unknown;
+    /** Execution wrapper map — required for state-bearing tools in govern mode. */
+    tools?: Record<string, ToolExecutor>;
+    onBlock?: (decision: ReplayDecision) => void;
+    /** v3: Called when tools are filtered by Stage 1 narrowing. */
+    onNarrow?: (narrowing: NarrowResult) => void;
+    /** Retry on block (hard cap 5, no prompt modification). */
+    maxRetries?: number;
+    /**
+     * Max unguarded calls before auto-kill (default: 3).
+     * Only applies when `onError: "allow"`. Bounds the state-fiction window.
+     * @see specs/runtime-replay.md § Failure semantics
+     */
+    maxUnguardedCalls?: number;
+    /** Provider constraints for blocking/warning on incompatible providers. */
+    providerConstraints?: ProviderConstraints;
+    /**
+     * Compat-tier enforcement behavior.
+     * - "protective": enforce locally, block illegal calls (default)
+     * - "advisory": evaluate but don't block, emit diagnostics only
+     * Only applies when tier is "compat" (no authoritative server round-trip).
+     * @see specs/replay-v2.md § v2 enforcement tier implications
+     */
+    compatEnforcement?: "protective" | "advisory";
+    /**
+     * Optional durable store for session state and captures.
+     * When provided, state reads use store.load() and state writes use
+     * store.compareAndSet(). Captures are appended via store.appendCapture().
+     * When absent, default in-memory store is used (current behavior).
+     * @see specs/replay-v2.md § Store interface in v2
+     */
+    store?: Store;
+    /**
+     * How narrowing is communicated to the LLM.
+     * - "silent" (default): tools removed silently, LLM doesn't know why
+     * - "metadata": narrowing info exposed via getState()/getLastNarrowing() only
+     * - "inject": a system message is prepended explaining which tools were removed and why.
+     *   Only non-sensitive reasons are injected (phase, manual_filter, no_contract).
+     *   policy_denied reasons are redacted to "restricted".
+     */
+    narrowingFeedback?: "silent" | "metadata" | "inject";
+    apiKey?: string;
+    /** Runtime API URL for authoritative sessions. Defaults to apiKey endpoint. */
+    runtimeUrl?: string;
+    captureLevel?: CapturePrivacyTier;
+    diagnostics?: (event: ObserveDiagnosticEvent | ReplayDiagnosticEvent) => void;
+};
+/**
+ * Raw tool executor provided by the user in `replay()` options.
+ * @see specs/runtime-replay.md § Execution constraints — ToolExecutor
+ */
+type ToolExecutor = (args: Record<string, unknown>) => unknown | Promise<unknown>;
+/**
+ * Wrapped tool executor exposed on `session.tools`.
+ * Enforces `execution_constraints` before forwarding to the real executor.
+ * @see specs/runtime-replay.md § Execution constraints — WrappedToolExecutor
+ */
+type WrappedToolExecutor = (args: Record<string, unknown>) => Promise<WrappedExecutorResult>;
+/**
+ * Result returned by a wrapped tool executor.
+ * @see specs/runtime-replay.md § Execution constraints
+ */
+type WrappedExecutorResult = {
+    result: unknown;
+    constraint_verdict: ConstraintVerdict;
+};
+/**
+ * Result of policy evaluation for a single tool call.
+ * @see specs/runtime-replay.md § Authorization kernel — PolicyVerdict
+ */
+type PolicyVerdict = {
+    allowed: boolean;
+    reason: string | null;
+};
+/**
+ * Result of execution constraint validation on tool arguments.
+ * @see specs/runtime-replay.md § Execution constraints — ConstraintVerdict
+ */
+type ConstraintVerdict = {
+    passed: boolean;
+    failures: ConstraintFailure[];
+};
+type ConstraintFailure = {
+    path: string;
+    operator: string;
+    expected: unknown;
+    actual: unknown;
+};
+/**
+ * @see specs/replay-v1.md § Return type: ReplaySession
+ * @see specs/replay-v2.md § ReplaySession extensions
+ */
+type ReplaySession<T> = {
+    client: T;
+    flush: () => Promise<FlushResult>;
+    restore: () => void;
+    kill: () => void;
+    getHealth: () => ReplayHealthSnapshot;
+    /** v2: Return redacted session state snapshot. */
+    getState: () => Readonly<SessionStateSnapshot>;
+    /**
+     * v3: Return the most recent narrowing snapshot.
+     * Returns null before first call or when no narrowing occurred.
+     */
+    getLastNarrowing: () => NarrowingSnapshot | null;
+    /**
+     * v3: Return the most recent ShadowDelta (shadow mode only).
+     * Returns null when not in shadow mode or before first call.
+     */
+    getLastShadowDelta: () => ShadowDelta | null;
+    /**
+     * v3: Manually restrict available tools within compiled legal space.
+     * Cannot add tools that the compiled session would remove.
+     * @see specs/replay-v3.md § narrow() / widen()
+     */
+    narrow: (toolFilter: string[]) => void;
+    /**
+     * v3: Remove manual restriction, return to contract-driven narrowing.
+     * Does NOT bypass phase/state restrictions.
+     * @see specs/replay-v3.md § narrow() / widen()
+     */
+    widen: () => void;
+    /** Present only when `tools` provided at init. */
+    tools: Record<string, WrappedToolExecutor>;
+    /**
+     * v4: Return workflow state from the runtime.
+     * Returns null when the session is not part of a workflow.
+     * @see specs/replay-v4.md § SDK workflow surface
+     */
+    getWorkflowState: () => Promise<WorkflowStateSnapshot | null>;
+    /**
+     * v4: Offer a handoff to another role in the workflow.
+     * Returns null when the session is not part of a workflow.
+     * @see specs/replay-v4.md § SDK workflow surface
+     */
+    handoff: (offer: HandoffOfferInput$1) => Promise<HandoffOfferResult$1 | null>;
+};
+/** @see specs/runtime-replay.md § ReplayHealthSnapshot */
+type ReplayHealthSnapshot = {
+    status: "healthy" | "degraded" | "inactive";
+    authorityState: "active" | "advisory" | "compromised" | "recovering" | "killed" | "inactive";
+    protectionLevel: "monitor" | "protect" | "govern";
+    durability: "server" | "degraded-local" | "inactive";
+    tier: "strong" | "compat";
+    compatEnforcement: "protective" | "advisory";
+    cluster_detected: boolean;
+    bypass_detected: boolean;
+    totalSteps: number;
+    totalBlocks: number;
+    totalErrors: number;
+    killed: boolean;
+    /** Number of shadow-mode evaluations performed (always 0 in enforce/log-only). */
+    shadowEvaluations: number;
+};
+/**
+ * Public, redacted, JSON-serializable snapshot of session state.
+ * Maps/Sets are converted to plain objects/arrays.
+ * @see specs/replay-v2.md § getState() contract
+ */
+type SessionStateSnapshot = {
+    sessionId: string;
+    agent: string | null;
+    principal: null;
+    startedAt: Date;
+    stateVersion: number;
+    controlRevision: number;
+    currentPhase: string | null;
+    totalStepCount: number;
+    totalToolCalls: number;
+    totalCost: number;
+    actualCost: number;
+    toolCallCounts: Record<string, number>;
+    forbiddenTools: string[];
+    satisfiedPreconditions: Record<string, unknown>;
+    lastStep: CompletedStepSnapshot | null;
+    /** Last narrowing result from the most recent create() call. Null before first call. */
+    lastNarrowing: NarrowingSnapshot | null;
+    killed: boolean;
+    totalUnguardedCalls: number;
+    consecutiveBlockCount: number;
+    totalBlockCount: number;
+};
+/** Redacted narrowing snapshot for external consumption. */
+type NarrowingSnapshot = {
+    removed: Array<{
+        tool: string;
+        reason: NarrowRemovalReason;
+        detail?: string;
+    }>;
+    removedCount: number;
+    allowedCount: number;
+};
+type CompletedStepSnapshot = {
+    stepIndex: number;
+    stepId: string;
+    toolCalls: CompletedToolCallSnapshot[];
+    invariantFailures: ContractFailure[];
+    phase: string | null;
+    phaseTransition: string | null;
+    completedAt: string;
+    outputExtract: Record<string, unknown>;
+    finish_reason: string | null;
+    model: string | null;
+};
+type CompletedToolCallSnapshot = {
+    toolName: string;
+    arguments_hash: string;
+    contractFile: string | null;
+};
+/** @see specs/replay-v1.md § Stage 4: Gate */
+type ReplayDecision = {
+    action: "allow";
+    tool_calls: ToolCallResult[];
+} | {
+    action: "block";
+    tool_calls: ToolCallResult[];
+    blocked: BlockedToolCall[];
+    response_modification: GateMode;
+};
+type BlockedToolCall = {
+    tool_name: string;
+    arguments: string;
+    reason: BlockReason;
+    contract_file: string;
+    failures: ContractFailure[];
+};
+/**
+ * Block reasons for v1 + v2.
+ * @see specs/replay-v1.md § Stage 4: Gate — BlockReason
+ * @see specs/replay-v2.md § Stage 4 extensions: Gate
+ */
+type BlockReason = "output_invariant_failed" | "input_invariant_failed" | "response_format_invalid" | "unmatched_tool_blocked" | "policy_denied" | "execution_constraint_violated" | "killed" | "argument_value_mismatch" | "precondition_not_met" | "forbidden_tool" | "session_limit_exceeded" | "loop_detected" | "illegal_phase_transition" | "ambiguous_phase_transition" | "risk_gate_blocked";
+/**
+ * A tool definition from the provider request.
+ * Must have at least a `name`; other fields vary by provider.
+ */
+type ToolDefinition = Record<string, unknown> & {
+    name: string;
+};
+/**
+ * Result of Stage 1 narrowing.
+ * @see specs/replay-v3.md § Stage 1: Narrow
+ */
+type NarrowResult = {
+    allowed: ToolDefinition[];
+    removed: NarrowedTool[];
+};
+/** @see specs/replay-v3.md § Stage 1: Narrow */
+type NarrowedTool = {
+    tool: string;
+    reason: NarrowRemovalReason;
+    detail?: string;
+    contract_file?: string;
+};
+type NarrowRemovalReason = "manual_filter" | "no_contract" | "wrong_phase" | "precondition_not_met" | "forbidden_in_state" | "policy_denied";
+/**
+ * Result of Stage 3 phase transition validation.
+ * @see specs/replay-v3.md § Stage 3 extension: Phase transition validation
+ */
+type PhaseTransitionResult = {
+    legal: true;
+    newPhase: string | null;
+} | {
+    legal: false;
+    newPhase: string | null;
+    blockedTool: string;
+    attemptedTransition: string;
+    reason: "illegal_phase_transition" | "ambiguous_phase_transition";
+};
+/**
+ * Per-stage timing breakdown for the enforcement pipeline.
+ * All values in milliseconds. `total_ms` = wall clock from guard start to capture.
+ * `enforcement_ms` = `total_ms - llm_call_ms` (actual enforcement overhead).
+ */
+type ReplayTiming = {
+    narrow_ms: number;
+    pre_check_ms: number;
+    llm_call_ms: number;
+    validate_ms: number;
+    cross_step_ms: number;
+    phase_ms: number;
+    argument_values_ms: number;
+    policy_ms: number;
+    gate_ms: number;
+    finalize_ms: number;
+    runtime_ms: number;
+    total_ms: number;
+    enforcement_ms: number;
+};
+/**
+ * @see specs/replay-v1.md § Stage 7: Capture
+ * @see specs/replay-v2.md § Stage 7 extensions: Capture
+ */
+type ReplayCapture = CapturedCall & {
+    replay: {
+        session_id: string;
+        step_index: number;
+        mode: ReplayMode;
+        decision: ReplayDecision;
+        contract_hashes: string[];
+        guard_overhead_ms: number;
+        timing?: ReplayTiming;
+        commit_tier: "strong" | "compat";
+        principal: unknown | null;
+        policy_verdict: PolicyVerdict | null;
+        execution_constraint_verdict: ConstraintVerdict | null;
+        counterfactual: {
+            tools_removed: NarrowedTool[];
+            calls_blocked: BlockedToolCall[];
+        };
+        cross_step: CrossStepCaptureResult | null;
+        session_state_hash: string | null;
+        state_version: number;
+        narrowing: NarrowResult | null;
+        phase: string | null;
+        phase_transition: string | null;
+        shadow_delta?: ShadowDelta;
+        receipt: null;
+    };
+};
+type CrossStepCaptureResult = {
+    passed: boolean;
+    failures: Array<{
+        toolName: string;
+        reason: string;
+        detail: string;
+    }>;
+};
+/**
+ * Shadow mode delta: what would have happened under enforce mode.
+ * @see specs/replay-v3.md § Shadow mode extensions
+ */
+type ShadowDelta = {
+    would_have_blocked: BlockedToolCall[];
+    would_have_narrowed: NarrowedTool[];
+    current_phase: string | null;
+    legal_next_phases: string[];
+};
+/** Provider-agnostic response metadata extracted for format invariant checks. */
+type ResponseMetadata = {
+    finish_reason: string | null;
+    content: string | null;
+    tool_calls_present: boolean;
+    has_content: boolean;
+};
+type ReplayDiagnosticEvent = {
+    type: "replay_activated";
+    session_id: string;
+    provider: SupportedProvider;
+    agent: string;
+    mode: ReplayMode;
+} | {
+    type: "replay_inactive";
+    reason: string;
+    error_message?: string;
+} | {
+    type: "replay_contract_error";
+    details: string;
+} | {
+    type: "replay_bypass_detected";
+    session_id: string;
+} | {
+    type: "replay_kill";
+    session_id: string;
+} | {
+    type: "replay_block";
+    session_id: string;
+    tool_name: string;
+    reason: BlockReason;
+} | {
+    type: "replay_narrow";
+    session_id: string;
+    removed: NarrowedTool[];
+} | {
+    type: "replay_provider_warning";
+    provider: string;
+    warnings: string[];
+} | {
+    type: "replay_compat_advisory";
+    session_id: string;
+    would_block: BlockedToolCall[];
+    details: string;
+} | {
+    type: "replay_resumed";
+    session_id: string;
+    state_version: number;
+    contract_drift: boolean;
+} | {
+    type: "replay_narrow_injected";
+    session_id: string;
+    message: string;
+} | {
+    type: "replay_workflow_attached";
+    session_id: string;
+    workflow_id: string;
+    role: string;
+    attach_type: "root" | "child";
+} | {
+    type: "replay_workflow_error";
+    session_id: string;
+    details: string;
+};
+/**
+ * Workflow state snapshot returned by `session.getWorkflowState()`.
+ * Server-authoritative — SDK caches but does not derive.
+ * @see specs/replay-v4.md § SDK workflow surface
+ */
+type WorkflowStateSnapshot = {
+    workflowId: string;
+    rootSessionId: string;
+    status: string;
+    stateVersion: number;
+    controlRevision: number;
+    totalSessionCount: number;
+    activeSessionCount: number;
+    totalStepCount: number;
+    totalCost: number;
+    totalHandoffCount: number;
+    unresolvedHandoffCount: number;
+    lastEventSeq: number;
+    killScope: string;
+    createdAt: string;
+    updatedAt: string;
+};
+/**
+ * Input for `session.handoff()`.
+ * @see specs/replay-v4.md § SDK workflow surface
+ */
+type HandoffOfferInput$1 = {
+    toRole: string;
+    handoffId: string;
+    artifactRefs?: unknown;
+    summary?: unknown;
+};
+/**
+ * Result from `session.handoff()`.
+ * @see specs/replay-v4.md § SDK workflow surface
+ */
+type HandoffOfferResult$1 = {
+    handoffId: string;
+    eventSeq: number;
+    stateVersion: number;
+};
+
+/**
+ * Create an enforcement session wrapper around a provider client.
+ *
+ * @see specs/replay-v1.md § SDK API surface — replay()
+ */
+declare function replay<T extends object>(client: T, opts?: ReplayOptions): ReplaySession<T>;
+
+declare class ReplayConfigurationError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Replay-specific error types.
+ * @see specs/replay-v1.md § Error types
+ */
+
+/**
+ * Thrown when enforcement blocks tool calls in `reject_all` or `strip_partial` (all-blocked) mode.
+ */
+declare class ReplayContractError extends Error {
+    readonly decision: ReplayDecision;
+    readonly contractFile: string;
+    readonly failures: ContractFailure[];
+    constructor(message: string, decision: ReplayDecision, contractFile: string, failures: ContractFailure[]);
+}
+/**
+ * Thrown on all create() calls after session.kill().
+ */
+declare class ReplayKillError extends Error {
+    readonly sessionId: string;
+    readonly killedAt: string;
+    constructor(sessionId: string, killedAt: string);
+}
+/**
+ * Thrown at replay() init time for configuration errors.
+ * Extends existing ReplayConfigurationError.
+ * @see specs/replay-v1.md § Config errors (fail-closed)
+ */
+declare class ReplayConfigError extends ReplayConfigurationError {
+    readonly condition: "policy_without_principal" | "constraints_without_wrapper" | "compilation_failed" | "provider_incompatible";
+    readonly details: string;
+    constructor(condition: "policy_without_principal" | "constraints_without_wrapper" | "compilation_failed" | "provider_incompatible", details: string);
+}
+
+/**
+ * In-memory Store implementation.
+ * Default store when no custom store is provided — replicates
+ * current closure-variable behavior.
+ *
+ * @see specs/replay-v2.md § Store interface in v2
+ */
+
+declare class MemoryStore implements Store {
+    private state;
+    private readonly captures;
+    compareAndSet(currentVersion: number, newState: SessionState): CompareAndSetResult;
+    load(): SessionState | null;
+    appendCapture(capture: CapturedCall): void;
+    /** @internal Test-only: get all captured calls. */
+    getCapturedCalls(): ReadonlyArray<CapturedCall>;
+}
+
+type RuntimeClientOptions = {
+    apiKey: string;
+    apiUrl?: string;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+};
+type RuntimeSessionInit = {
+    agent: string;
+    sessionId?: string;
+    requestedMode: "authoritative" | "advisory";
+    requestedTier: "strong" | "compat";
+    adapterCapability: "full" | "partial" | "transcript_only";
+    allowAdvisoryDowngrade?: boolean;
+    provider?: string;
+    modelId?: string | null;
+    principal?: unknown | null;
+    compiledSession?: {
+        schemaVersion: string;
+        hash: string;
+        body: unknown;
+    };
+    contractHash: string;
+    sessionContractHash?: string | null;
+    /** v4: Workflow attachment block for root-create or child-attach. */
+    workflow?: RuntimeWorkflowInit;
+};
+/** v4: Workflow block in session creation. */
+type RuntimeWorkflowInit = {
+    workflowId: string;
+    role: string;
+    compiledWorkflow?: {
+        hash: string;
+        body: string;
+    };
+    parentSessionId?: string;
+    handoffId?: string;
+};
+type RuntimeSessionResult = {
+    sessionId: string;
+    mode: string;
+    tier: string;
+    status: string;
+    stateVersion: number;
+    controlRevision: number;
+    leaseFence: string | null;
+    /** v4: Workflow attachment result, present when workflow block was sent. */
+    workflow?: RuntimeWorkflowResult;
+};
+/** v4: Workflow block in session creation response. */
+type RuntimeWorkflowResult = {
+    workflowId: string;
+    role: string;
+    stateVersion: number;
+    controlRevision?: number;
+    linkId?: string;
+    generation?: number;
+    depth?: number;
+    status?: string;
+};
+type PreflightInput = {
+    sessionId: string;
+    leaseFence: string;
+    requestEnvelope: unknown;
+    provider: string;
+    modelId: string | null;
+};
+type PreflightResult = {
+    preparedRequestId: string;
+    stateVersion: number;
+    controlRevision: number;
+    leaseFence: string;
+    requestEnvelope: unknown;
+    removedTools: unknown[];
+};
+type ProposalInput = {
+    sessionId: string;
+    leaseFence: string;
+    preparedRequestId: string;
+    responseEnvelope: unknown;
+};
+type ProposalResult = {
+    decision: "allowed" | "blocked";
+    advisory: boolean;
+    stateVersion: number;
+    pendingCalls: ProposalPendingCall[];
+    blockedCalls: ProposalBlockedCall[];
+};
+type ProposalPendingCall = {
+    pendingCallId: string;
+    toolCallId: string;
+    toolName: string;
+    argumentsHash: string;
+};
+type ProposalBlockedCall = {
+    toolName: string;
+    reason: string;
+};
+type ReceiptInput = {
+    sessionId: string;
+    leaseFence: string;
+    pendingCallId: string;
+    executorKind: "WRAPPED_EXECUTOR" | "GATEWAY_EXECUTOR" | "SERVICE_EXECUTOR";
+    executorId?: string | null;
+    toolName: string;
+    argumentsHash: string;
+    status: "SUCCEEDED" | "FAILED" | "DISCARDED";
+    outputHash?: string | null;
+    outputExtract?: Record<string, unknown> | null;
+    resourceValues?: Record<string, unknown> | null;
+    evidenceArtifactHash?: string | null;
+    startedAt: string;
+    completedAt: string;
+};
+type ReceiptResult = {
+    accepted: boolean;
+    commitState: "committed" | "uncommitted";
+    stateAdvanced: boolean;
+    stateVersion: number;
+};
+type ToolFilterInput = {
+    sessionId: string;
+    leaseFence: string;
+    allowedTools: string[] | null;
+};
+type ToolFilterResult = {
+    controlRevision: number;
+};
+type ReportBypassInput = {
+    sessionId: string;
+    source: string;
+    detail?: string | null;
+};
+type ReportBypassResult = {
+    status: string;
+};
+type KillSessionInput = {
+    sessionId: string;
+    leaseFence: string;
+    reason: string;
+};
+type KillSessionResult = {
+    status: string;
+};
+/** v4: Workflow state query result. */
+type WorkflowStateResult = {
+    workflowId: string;
+    rootSessionId: string;
+    status: string;
+    stateVersion: number;
+    controlRevision: number;
+    totalSessionCount: number;
+    activeSessionCount: number;
+    totalStepCount: number;
+    totalCost: number;
+    totalHandoffCount: number;
+    unresolvedHandoffCount: number;
+    lastEventSeq: number;
+    killScope: string;
+    createdAt: string;
+    updatedAt: string;
+};
+/** v4: Handoff offer input. */
+type HandoffOfferInput = {
+    sessionId: string;
+    workflowId: string;
+    fromRole: string;
+    toRole: string;
+    handoffId: string;
+    artifactRefs?: unknown;
+    summary?: unknown;
+};
+/** v4: Handoff offer result. */
+type HandoffOfferResult = {
+    handoffId: string;
+    eventSeq: number;
+    stateVersion: number;
+};
+type RuntimeClientHealth = {
+    circuitOpen: boolean;
+    failureCount: number;
+    circuitOpenUntil: number;
+};
+declare class RuntimeClientError extends Error {
+    readonly code: string;
+    readonly httpStatus: number;
+    constructor(code: string, message: string, httpStatus: number);
+}
+declare function createRuntimeClient(opts: RuntimeClientOptions): RuntimeClient;
+declare class RuntimeClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private readonly now;
+    private failureCount;
+    private circuitOpenUntil;
+    constructor(opts: RuntimeClientOptions);
+    createSession(input: RuntimeSessionInit): Promise<RuntimeSessionResult>;
+    preflight(input: PreflightInput): Promise<PreflightResult>;
+    submitProposal(input: ProposalInput): Promise<ProposalResult>;
+    submitReceipt(input: ReceiptInput): Promise<ReceiptResult>;
+    setToolFilter(input: ToolFilterInput): Promise<ToolFilterResult>;
+    reportBypass(input: ReportBypassInput): Promise<ReportBypassResult>;
+    killSession(input: KillSessionInput): Promise<KillSessionResult>;
+    /** v4: Get workflow state from the runtime. */
+    getWorkflowState(workflowId: string): Promise<WorkflowStateResult>;
+    /** v4: Offer a handoff from a session. */
+    offerHandoff(input: HandoffOfferInput): Promise<HandoffOfferResult>;
+    getHealth(): RuntimeClientHealth;
+    isCircuitOpen(): boolean;
+    private get;
+    private post;
+    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 };