workglow-dev
diff --git a/‎packages/task-graph/src/checkpoint/CheckpointSaver.ts‎
Lines changed: 30 additions & 0 deletions b/‎packages/task-graph/src/checkpoint/CheckpointSaver.ts‎
Lines changed: 30 additions & 0 deletions
diff --git a/‎packages/task-graph/src/checkpoint/CheckpointTypes.ts‎
Lines changed: 48 additions & 0 deletions b/‎packages/task-graph/src/checkpoint/CheckpointTypes.ts‎
Lines changed: 48 additions & 0 deletions
diff --git a/‎packages/task-graph/src/checkpoint/InMemoryCheckpointSaver.ts‎
Lines changed: 61 additions & 0 deletions b/‎packages/task-graph/src/checkpoint/InMemoryCheckpointSaver.ts‎
Lines changed: 61 additions & 0 deletions
diff --git a/‎packages/task-graph/src/checkpoint/TabularCheckpointSaver.ts‎
Lines changed: 165 additions & 0 deletions b/‎packages/task-graph/src/checkpoint/TabularCheckpointSaver.ts‎
Lines changed: 165 additions & 0 deletions
diff --git a/‎packages/task-graph/src/checkpoint/index.ts‎
Lines changed: 10 additions & 0 deletions b/‎packages/task-graph/src/checkpoint/index.ts‎
Lines changed: 10 additions & 0 deletions
diff --git a/‎packages/task-graph/src/common.ts‎
Lines changed: 2 additions & 0 deletions b/‎packages/task-graph/src/common.ts‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎packages/task-graph/src/task-graph/TaskGraph.ts‎
Lines changed: 14 additions & 0 deletions b/‎packages/task-graph/src/task-graph/TaskGraph.ts‎
Lines changed: 14 additions & 0 deletions
diff --git a/‎packages/task-graph/src/task-graph/TaskGraphEvents.ts‎
Lines changed: 2 additions & 0 deletions b/‎packages/task-graph/src/task-graph/TaskGraphEvents.ts‎
Lines changed: 2 additions & 0 deletions
@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { createServiceToken } from "@workglow/util";
+import type { CheckpointData, CheckpointId, ThreadId } from "./CheckpointTypes";
+
+/**
+ * Service token for CheckpointSaver
+ */
+export const CHECKPOINT_SAVER = createServiceToken<CheckpointSaver>("taskgraph.checkpointSaver");
+
+/**
+ * Abstract class for saving and retrieving execution checkpoints.
+ * Implementations provide persistence for checkpoint data to enable
+ * resume-from-failure and execution history features.
+ */
+export abstract class CheckpointSaver {
+  abstract saveCheckpoint(data: CheckpointData): Promise<void>;
+  abstract getCheckpoint(checkpointId: CheckpointId): Promise<CheckpointData | undefined>;
+  abstract getLatestCheckpoint(threadId: ThreadId): Promise<CheckpointData | undefined>;
+  abstract getCheckpointHistory(threadId: ThreadId): Promise<CheckpointData[]>;
+  abstract getCheckpointsForIteration(
+    threadId: ThreadId,
+    iterationParentTaskId: unknown
+  ): Promise<CheckpointData[]>;
+  abstract deleteCheckpoints(threadId: ThreadId): Promise<void>;
+}
@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { TaskGraphJson } from "../task/TaskJSON";
+import type { TaskInput, TaskOutput, TaskStatus } from "../task/TaskTypes";
+
+export type CheckpointId = string;
+export type ThreadId = string;
+
+export type CheckpointGranularity = "every-task" | "top-level-only" | "none";
+
+export interface TaskCheckpointState {
+  taskId: unknown;
+  taskType: string;
+  status: TaskStatus;
+  inputData: TaskInput;
+  outputData: TaskOutput;
+  progress: number;
+  error?: string;
+  startedAt?: string;
+  completedAt?: string;
+}
+
+export interface DataflowCheckpointState {
+  id: string;
+  sourceTaskId: unknown;
+  targetTaskId: unknown;
+  status: TaskStatus;
+  portData?: TaskOutput;
+}
+
+export interface CheckpointData {
+  checkpointId: CheckpointId;
+  threadId: ThreadId;
+  parentCheckpointId?: CheckpointId;
+  graphJson: TaskGraphJson;
+  taskStates: TaskCheckpointState[];
+  dataflowStates: DataflowCheckpointState[];
+  metadata: {
+    createdAt: string;
+    triggerTaskId?: unknown;
+    iterationIndex?: number;
+    iterationParentTaskId?: unknown;
+  };
+}
@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { CheckpointSaver } from "./CheckpointSaver";
+import type { CheckpointData, CheckpointId, ThreadId } from "./CheckpointTypes";
+
+/**
+ * In-memory implementation of CheckpointSaver.
+ * Uses a Map with a secondary index on threadId for efficient lookups.
+ */
+export class InMemoryCheckpointSaver extends CheckpointSaver {
+  private checkpoints: Map<CheckpointId, CheckpointData> = new Map();
+  private threadIndex: Map<ThreadId, CheckpointId[]> = new Map();
+
+  async saveCheckpoint(data: CheckpointData): Promise<void> {
+    this.checkpoints.set(data.checkpointId, data);
+
+    const threadCheckpoints = this.threadIndex.get(data.threadId) ?? [];
+    threadCheckpoints.push(data.checkpointId);
+    this.threadIndex.set(data.threadId, threadCheckpoints);
+  }
+
+  async getCheckpoint(checkpointId: CheckpointId): Promise<CheckpointData | undefined> {
+    return this.checkpoints.get(checkpointId);
+  }
+
+  async getLatestCheckpoint(threadId: ThreadId): Promise<CheckpointData | undefined> {
+    const ids = this.threadIndex.get(threadId);
+    if (!ids || ids.length === 0) return undefined;
+    return this.checkpoints.get(ids[ids.length - 1]);
+  }
+
+  async getCheckpointHistory(threadId: ThreadId): Promise<CheckpointData[]> {
+    const ids = this.threadIndex.get(threadId);
+    if (!ids) return [];
+    return ids
+      .map((id) => this.checkpoints.get(id))
+      .filter((cp): cp is CheckpointData => cp !== undefined);
+  }
+
+  async getCheckpointsForIteration(
+    threadId: ThreadId,
+    iterationParentTaskId: unknown
+  ): Promise<CheckpointData[]> {
+    const history = await this.getCheckpointHistory(threadId);
+    return history.filter((cp) => cp.metadata.iterationParentTaskId === iterationParentTaskId);
+  }
+
+  async deleteCheckpoints(threadId: ThreadId): Promise<void> {
+    const ids = this.threadIndex.get(threadId);
+    if (ids) {
+      for (const id of ids) {
+        this.checkpoints.delete(id);
+      }
+      this.threadIndex.delete(threadId);
+    }
+  }
+}
@@ -0,0 +1,165 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { BaseTabularStorage } from "@workglow/storage";
+import { compress, DataPortSchemaObject, decompress } from "@workglow/util";
+import { CheckpointSaver } from "./CheckpointSaver";
+import type { CheckpointData, CheckpointId, ThreadId } from "./CheckpointTypes";
+
+export const CheckpointSchema = {
+  type: "object",
+  properties: {
+    checkpoint_id: { type: "string" },
+    thread_id: { type: "string" },
+    parent_checkpoint_id: { type: "string" },
+    graph_json: { type: "string", contentEncoding: "blob" },
+    task_states: { type: "string", contentEncoding: "blob" },
+    dataflow_states: { type: "string", contentEncoding: "blob" },
+    metadata: { type: "string" },
+    created_at: { type: "string", format: "date-time" },
+  },
+  additionalProperties: false,
+} satisfies DataPortSchemaObject;
+
+export const CheckpointPrimaryKeyNames = ["checkpoint_id"] as const;
+
+export type CheckpointStorage = BaseTabularStorage<
+  typeof CheckpointSchema,
+  typeof CheckpointPrimaryKeyNames
+>;
+
+export type TabularCheckpointSaverOptions = {
+  tabularRepository: CheckpointStorage;
+  compression?: boolean;
+};
+
+/**
+ * Tabular storage implementation of CheckpointSaver.
+ * Uses the existing ITabularStorage interface for persistence,
+ * giving access to SQLite, Postgres, IndexedDB, Supabase, and
+ * file-backed checkpoint storage via existing backends.
+ */
+export class TabularCheckpointSaver extends CheckpointSaver {
+  tabularRepository: CheckpointStorage;
+  compression: boolean;
+
+  constructor({ tabularRepository, compression = true }: TabularCheckpointSaverOptions) {
+    super();
+    this.tabularRepository = tabularRepository;
+    this.compression = compression;
+  }
+
+  async setupDatabase(): Promise<void> {
+    await this.tabularRepository.setupDatabase?.();
+  }
+
+  private async compressJson(value: string): Promise<unknown> {
+    if (this.compression) {
+      return (await compress(value)) as unknown;
+    }
+    return Buffer.from(value) as unknown;
+  }
+
+  private async decompressJson(raw: unknown): Promise<string> {
+    if (this.compression) {
+      const bytes: Uint8Array =
+        raw instanceof Uint8Array
+          ? raw
+          : Array.isArray(raw)
+            ? new Uint8Array(raw as number[])
+            : raw && typeof raw === "object"
+              ? new Uint8Array(
+                  Object.keys(raw as Record<string, number>)
+                    .filter((k) => /^\d+$/.test(k))
+                    .sort((a, b) => Number(a) - Number(b))
+                    .map((k) => (raw as Record<string, number>)[k])
+                )
+              : new Uint8Array();
+      return await decompress(bytes);
+    }
+    return (raw as Buffer).toString();
+  }
+
+  async saveCheckpoint(data: CheckpointData): Promise<void> {
+    await this.tabularRepository.put({
+      checkpoint_id: data.checkpointId,
+      thread_id: data.threadId,
+      parent_checkpoint_id: data.parentCheckpointId ?? "",
+      graph_json: (await this.compressJson(JSON.stringify(data.graphJson))) as string,
+      task_states: (await this.compressJson(JSON.stringify(data.taskStates))) as string,
+      dataflow_states: (await this.compressJson(JSON.stringify(data.dataflowStates))) as string,
+      metadata: JSON.stringify(data.metadata),
+      created_at: data.metadata.createdAt,
+    });
+  }
+
+  async getCheckpoint(checkpointId: CheckpointId): Promise<CheckpointData | undefined> {
+    const row = await this.tabularRepository.get({ checkpoint_id: checkpointId });
+    if (!row) return undefined;
+    return this.rowToCheckpointData(row);
+  }
+
+  async getLatestCheckpoint(threadId: ThreadId): Promise<CheckpointData | undefined> {
+    const rows = await this.tabularRepository.search({ thread_id: threadId });
+    if (!rows || rows.length === 0) return undefined;
+
+    // Sort by created_at descending and return the latest
+    rows.sort((a, b) => {
+      const aTime = a.created_at ?? "";
+      const bTime = b.created_at ?? "";
+      return bTime.localeCompare(aTime);
+    });
+
+    return this.rowToCheckpointData(rows[0]);
+  }
+
+  async getCheckpointHistory(threadId: ThreadId): Promise<CheckpointData[]> {
+    const rows = await this.tabularRepository.search({ thread_id: threadId });
+    if (!rows || rows.length === 0) return [];
+
+    // Sort by created_at ascending
+    rows.sort((a, b) => {
+      const aTime = a.created_at ?? "";
+      const bTime = b.created_at ?? "";
+      return aTime.localeCompare(bTime);
+    });
+
+    const results: CheckpointData[] = [];
+    for (const row of rows) {
+      results.push(await this.rowToCheckpointData(row));
+    }
+    return results;
+  }
+
+  async getCheckpointsForIteration(
+    threadId: ThreadId,
+    iterationParentTaskId: unknown
+  ): Promise<CheckpointData[]> {
+    const history = await this.getCheckpointHistory(threadId);
+    return history.filter((cp) => cp.metadata.iterationParentTaskId === iterationParentTaskId);
+  }
+
+  async deleteCheckpoints(threadId: ThreadId): Promise<void> {
+    await this.tabularRepository.deleteSearch({ thread_id: threadId });
+  }
+
+  private async rowToCheckpointData(row: Record<string, unknown>): Promise<CheckpointData> {
+    const graphJson = JSON.parse(await this.decompressJson(row.graph_json));
+    const taskStates = JSON.parse(await this.decompressJson(row.task_states));
+    const dataflowStates = JSON.parse(await this.decompressJson(row.dataflow_states));
+    const metadata = JSON.parse(row.metadata as string);
+
+    return {
+      checkpointId: row.checkpoint_id as string,
+      threadId: row.thread_id as string,
+      parentCheckpointId: (row.parent_checkpoint_id as string) || undefined,
+      graphJson,
+      taskStates,
+      dataflowStates,
+      metadata,
+    };
+  }
+}
@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./CheckpointSaver";
+export * from "./CheckpointTypes";
+export * from "./InMemoryCheckpointSaver";
+export * from "./TabularCheckpointSaver";
@@ -22,3 +22,5 @@ export * from "./storage/TaskGraphRepository";
 export * from "./storage/TaskGraphTabularRepository";
 export * from "./storage/TaskOutputRepository";
 export * from "./storage/TaskOutputTabularRepository";
+
+export * from "./checkpoint";
@@ -5,6 +5,8 @@
  */
 
 import { DirectedAcyclicGraph, EventEmitter, ServiceRegistry, uuid4 } from "@workglow/util";
+import type { CheckpointSaver } from "../checkpoint/CheckpointSaver";
+import type { CheckpointGranularity, CheckpointId, ThreadId } from "../checkpoint/CheckpointTypes";
 import { TaskOutputRepository } from "../storage/TaskOutputRepository";
 import type { ITask } from "../task/ITask";
 import { JsonTaskItem, TaskGraphJson } from "../task/TaskJSON";
@@ -39,6 +41,14 @@ export interface TaskGraphRunConfig {
   parentSignal?: AbortSignal;
   /** Optional service registry to use for this task graph (creates child from global if not provided) */
   registry?: ServiceRegistry;
+  /** Optional checkpoint saver for persisting execution state */
+  checkpointSaver?: CheckpointSaver;
+  /** Thread ID for checkpoint isolation; auto-generated if not provided */
+  threadId?: ThreadId;
+  /** Resume execution from a specific checkpoint */
+  resumeFromCheckpoint?: CheckpointId;
+  /** Controls when checkpoints are captured. Default: "every-task" */
+  checkpointGranularity?: CheckpointGranularity;
 }
 
 class TaskGraphDAG extends DirectedAcyclicGraph<
@@ -103,6 +113,10 @@ export class TaskGraph implements ITaskGraph {
     return this.runner.runGraph<ExecuteOutput>(input, {
       outputCache: config?.outputCache || this.outputCache,
       parentSignal: config?.parentSignal || undefined,
+      checkpointSaver: config?.checkpointSaver,
+      threadId: config?.threadId,
+      resumeFromCheckpoint: config?.resumeFromCheckpoint,
+      checkpointGranularity: config?.checkpointGranularity,
     });
   }
 
 
@@ -5,6 +5,7 @@
  */
 
 import { EventParameters } from "@workglow/util";
+import type { CheckpointData } from "../checkpoint/CheckpointTypes";
 import { TaskIdType } from "../task/TaskTypes";
 import { DataflowIdType } from "./Dataflow";
 
@@ -19,6 +20,7 @@ export type TaskGraphStatusListeners = {
   error: (error: Error) => void;
   abort: () => void;
   disabled: () => void;
+  checkpoint: (data: CheckpointData) => void;
 };
 export type TaskGraphStatusEvents = keyof TaskGraphStatusListeners;
 export type TaskGraphStatusListener<Event extends TaskGraphStatusEvents> =