@wundr.io/langgraph-orchestrator 1.0.3

package/dist/checkpointing.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Checkpointing - State persistence and time-travel debugging
+ * @module @wundr.io/langgraph-orchestrator
+ */
+import { z } from 'zod';
+import type { AgentState, Checkpoint, CheckpointSummary, GraphCheckpointer } from './types';
+/**
+ * In-memory checkpointer implementation
+ * Useful for development and testing
+ */
+export declare class MemoryCheckpointer implements GraphCheckpointer {
+    private checkpoints;
+    private executionIndex;
+    /**
+     * Save a checkpoint
+     */
+    save(checkpoint: Checkpoint): Promise<void>;
+    /**
+     * Load a checkpoint by ID
+     */
+    load(checkpointId: string): Promise<Checkpoint | null>;
+    /**
+     * List checkpoints for an execution
+     */
+    list(executionId: string): Promise<CheckpointSummary[]>;
+    /**
+     * Delete a checkpoint
+     */
+    delete(checkpointId: string): Promise<void>;
+    /**
+     * Get the latest checkpoint for an execution
+     */
+    getLatest(executionId: string): Promise<Checkpoint | null>;
+    /**
+     * Clear all checkpoints
+     */
+    clear(): void;
+    /**
+     * Get statistics about stored checkpoints
+     */
+    getStats(): {
+        totalCheckpoints: number;
+        totalExecutions: number;
+    };
+}
+/**
+ * File-based checkpointer implementation
+ * Persists checkpoints to the filesystem
+ */
+export declare class FileCheckpointer implements GraphCheckpointer {
+    private readonly basePath;
+    private readonly fs;
+    /**
+     * Create a file-based checkpointer
+     * @param basePath - Directory to store checkpoints
+     * @param fs - FileSystem interface (allows for mocking)
+     */
+    constructor(basePath: string, fs?: FileSystem);
+    /**
+     * Save a checkpoint
+     */
+    save(checkpoint: Checkpoint): Promise<void>;
+    /**
+     * Load a checkpoint by ID
+     */
+    load(checkpointId: string): Promise<Checkpoint | null>;
+    /**
+     * List checkpoints for an execution
+     */
+    list(executionId: string): Promise<CheckpointSummary[]>;
+    /**
+     * Delete a checkpoint
+     */
+    delete(checkpointId: string): Promise<void>;
+    /**
+     * Get the latest checkpoint for an execution
+     */
+    getLatest(executionId: string): Promise<Checkpoint | null>;
+    /**
+     * Load index file
+     */
+    private loadIndex;
+}
+/**
+ * FileSystem interface for abstraction
+ */
+export interface FileSystem {
+    readFile(path: string, encoding: string): Promise<string>;
+    writeFile(path: string, data: string): Promise<void>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    unlink(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+}
+/**
+ * Time-travel debugger for workflow state
+ */
+export declare class TimeTravelDebugger<TState extends AgentState = AgentState> {
+    private readonly checkpointer;
+    /**
+     * Create a time-travel debugger
+     * @param checkpointer - Checkpointer to use for state access
+     */
+    constructor(checkpointer: GraphCheckpointer);
+    /**
+     * Get the execution timeline
+     * @param executionId - Execution to get timeline for
+     * @returns Array of checkpoint summaries
+     */
+    getTimeline(executionId: string): Promise<CheckpointSummary[]>;
+    /**
+     * Travel to a specific checkpoint
+     * @param checkpointId - Checkpoint to travel to
+     * @returns The state at that checkpoint
+     */
+    travelTo(checkpointId: string): Promise<TState | null>;
+    /**
+     * Get state at a specific step number
+     * @param executionId - Execution ID
+     * @param stepNumber - Step number to travel to
+     * @returns The state at that step
+     */
+    travelToStep(executionId: string, stepNumber: number): Promise<TState | null>;
+    /**
+     * Compare two checkpoints
+     * @param checkpointId1 - First checkpoint
+     * @param checkpointId2 - Second checkpoint
+     * @returns Differences between the checkpoints
+     */
+    compare(checkpointId1: string, checkpointId2: string): Promise<StateDiff[]>;
+    /**
+     * Get the state history (changes over time)
+     * @param executionId - Execution ID
+     * @returns Array of state changes
+     */
+    getStateHistory(executionId: string): Promise<StateHistoryItem<TState>[]>;
+    /**
+     * Find checkpoints where a condition became true
+     * @param executionId - Execution ID
+     * @param condition - Condition to check
+     * @returns Checkpoints where condition became true
+     */
+    findTransitions(executionId: string, condition: (state: TState) => boolean): Promise<CheckpointSummary[]>;
+    /**
+     * Compute differences between two states
+     */
+    private diffStates;
+}
+/**
+ * State difference record
+ */
+export interface StateDiff {
+    /** Path to the changed value */
+    path: string;
+    /** Type of change */
+    type: 'added' | 'removed' | 'changed';
+    /** Previous value */
+    oldValue?: unknown;
+    /** New value */
+    newValue?: unknown;
+}
+/**
+ * State history item
+ */
+export interface StateHistoryItem<TState extends AgentState = AgentState> {
+    /** Checkpoint summary */
+    checkpoint: CheckpointSummary;
+    /** Full state at this point */
+    state: TState;
+    /** Changes from previous state */
+    changes: StateDiff[];
+}
+/**
+ * Create a checkpoint
+ *
+ * @example
+ * ```typescript
+ * const checkpoint = createCheckpoint({
+ *   executionId: 'exec-123',
+ *   stepNumber: 5,
+ *   nodeName: 'process-node',
+ *   state: currentState
+ * });
+ *
+ * await checkpointer.save(checkpoint);
+ * ```
+ *
+ * @param options - Checkpoint options
+ * @returns Checkpoint object
+ */
+export declare function createCheckpoint<TState extends AgentState = AgentState>(options: {
+    executionId: string;
+    stepNumber: number;
+    nodeName: string;
+    state: TState;
+    parentId?: string;
+    metadata?: Record<string, unknown>;
+}): Checkpoint;
+/**
+ * Checkpoint retention policy
+ */
+export interface RetentionPolicy {
+    /** Maximum number of checkpoints to keep per execution */
+    maxCheckpointsPerExecution?: number;
+    /** Maximum age of checkpoints in milliseconds */
+    maxAge?: number;
+    /** Keep every Nth checkpoint (for sampling) */
+    keepEveryN?: number;
+    /** Always keep checkpoints for these nodes */
+    alwaysKeepNodes?: string[];
+}
+/**
+ * Apply retention policy to checkpoints
+ *
+ * @example
+ * ```typescript
+ * await applyRetentionPolicy(checkpointer, 'exec-123', {
+ *   maxCheckpointsPerExecution: 100,
+ *   maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
+ *   keepEveryN: 10,
+ *   alwaysKeepNodes: ['decision', 'error-handler']
+ * });
+ * ```
+ *
+ * @param checkpointer - Checkpointer to clean up
+ * @param executionId - Execution to apply policy to
+ * @param policy - Retention policy
+ * @returns Number of checkpoints deleted
+ */
+export declare function applyRetentionPolicy(checkpointer: GraphCheckpointer, executionId: string, policy: RetentionPolicy): Promise<number>;
+/**
+ * Schema for checkpoint validation
+ */
+export declare const CheckpointSchema: z.ZodObject<{
+    id: z.ZodString;
+    executionId: z.ZodString;
+    stepNumber: z.ZodNumber;
+    nodeName: z.ZodString;
+    timestamp: z.ZodDate;
+    parentId: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    timestamp: Date;
+    executionId: string;
+    stepNumber: number;
+    nodeName: string;
+    metadata?: Record<string, unknown> | undefined;
+    parentId?: string | undefined;
+}, {
+    id: string;
+    timestamp: Date;
+    executionId: string;
+    stepNumber: number;
+    nodeName: string;
+    metadata?: Record<string, unknown> | undefined;
+    parentId?: string | undefined;
+}>;
+/**
+ * Validate a checkpoint
+ */
+export declare function validateCheckpoint(checkpoint: unknown): checkpoint is Checkpoint;
+//# sourceMappingURL=checkpointing.d.ts.map

package/dist/checkpointing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpointing.d.ts","sourceRoot":"","sources":["../src/checkpointing.ts"],"names":[],"mappings":"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"}