pi-harness-runtime 0.5.0 → 0.6.3-beta.13

package/packages/checkpoint/src/types.ts

@@ -0,0 +1,348 @@
+/**
+ * Checkpoint Engine - Types
+ *
+ * Core types for the enhanced checkpoint system.
+ */
+
+// ─── SDK Version ────────────────────────────────────────────────────────────
+
+/**
+ * SDK version for compatibility checks
+ */
+export const SDK_VERSION = "1.0.0";
+
+// ─── Task Types ─────────────────────────────────────────────────────────
+
+/**
+ * Task status
+ */
+export type TaskStatus = "pending" | "running" | "done" | "failed" | "blocked";
+
+/**
+ * Runtime task
+ */
+export interface RuntimeTask {
+	id: string;
+	title: string;
+	description: string;
+	status: TaskStatus;
+	assignedProvider?: string;
+	worktreePath?: string;
+	acceptanceCriteria?: string[];
+}
+
+// ─── Job Types ──────────────────────────────────────────────────────────
+
+/**
+ * Job status
+ */
+export type JobStatus =
+	| "pending"
+	| "running"
+	| "blocked"
+	| "completed"
+	| "failed"
+	| "cancelled"
+	| "archived";
+
+// ─── State Types ─────────────────────────────────────────────────────────
+
+/**
+ * Runtime state to be checkpointed
+ */
+export interface RuntimeState {
+	version: number;
+	jobId: string;
+	status: JobStatus;
+	requirement: string;
+	currentTaskId?: string;
+	provider?: string;
+	resumeAt?: string;
+	lastError?: string;
+	tasks: RuntimeTask[];
+	createdAt: string;
+	updatedAt: string;
+	metadata?: Record<string, unknown>;
+}
+
+// ─── Checkpoint Types ────────────────────────────────────────────────────
+
+/**
+ * Checkpoint type
+ */
+export type CheckpointType = "full" | "incremental";
+
+/**
+ * Checkpoint metadata
+ */
+export interface CheckpointMetadata {
+	jobId: string;
+	version: number;
+	type: CheckpointType;
+	sizeBytes: number;
+	compressed: boolean;
+	checksum: string;
+	taskProgress: {
+		total: number;
+		completed: number;
+		failed: number;
+		running: number;
+	};
+	createdAt: string;
+	expiresAt?: string;
+	baseVersion?: number; // For incremental checkpoints
+}
+
+/**
+ * Full checkpoint data
+ */
+export interface FullCheckpoint {
+	jobId: string;
+	version: number;
+	type: "full";
+	state: RuntimeState;
+	metadata: CheckpointMetadata;
+}
+
+/**
+ * State delta for incremental checkpoints
+ */
+export interface StateDelta {
+	jobId: string;
+	baseVersion: number;
+	targetVersion: number;
+	changes: {
+		status?: JobStatus;
+		tasks?: TaskDelta[];
+		context?: ContextDiff;
+		errors?: ErrorEntry[];
+		metadata?: Record<string, unknown>;
+	};
+	timestamp: string;
+	checksum: string;
+}
+
+/**
+ * Task delta
+ */
+export interface TaskDelta {
+	taskId: string;
+	action: "added" | "updated" | "removed";
+	before?: Partial<RuntimeTask>;
+	after?: Partial<RuntimeTask>;
+}
+
+/**
+ * Context diff
+ */
+export interface ContextDiff {
+	added?: Record<string, unknown>;
+	removed?: string[];
+	updated?: Record<string, { before: unknown; after: unknown }>;
+}
+
+/**
+ * Error entry
+ */
+export interface ErrorEntry {
+	taskId?: string;
+	error: string;
+	timestamp: string;
+	recoverable: boolean;
+}
+
+/**
+ * Incremental checkpoint data
+ */
+export interface IncrementalCheckpoint {
+	jobId: string;
+	version: number;
+	type: "incremental";
+	delta: StateDelta;
+	metadata: CheckpointMetadata;
+}
+
+// ─── Recovery Types ──────────────────────────────────────────────────────
+
+/**
+ * Recovery strategy
+ */
+export type RecoveryStrategy =
+	| "latest" // Use most recent checkpoint
+	| "fullest" // Use checkpoint with most completed tasks
+	| `specific:${number}` // Use specific version number
+	| `timestamp:${string}` // Use checkpoint closest to timestamp
+	| "interactive"; // User selects from list
+
+/**
+ * Recovery result
+ */
+export interface RecoveryResult {
+	success: boolean;
+	recoveredVersion: number;
+	recoveredState?: RuntimeState;
+	lostEvents: number;
+	recoveryTimeMs: number;
+	errors?: string[];
+	warnings?: string[];
+}
+
+/**
+ * Verification result
+ */
+export interface VerificationResult {
+	valid: boolean;
+	checksumMatch: boolean;
+	corruptionDetails?: string[];
+}
+
+/**
+ * Prune result
+ */
+export interface PruneResult {
+	deletedCount: number;
+	freedBytes: number;
+	remainingCount: number;
+	errors?: string[];
+}
+
+// ─── Storage Types ───────────────────────────────────────────────────────
+
+/**
+ * Checkpoint file stored on disk
+ */
+export interface CheckpointFile {
+	jobId: string;
+	version: number;
+	type: CheckpointType;
+	data: string;
+	metadata: CheckpointMetadata;
+}
+
+/**
+ * Index entry for a checkpoint
+ */
+export interface IndexEntry {
+	jobId: string;
+	version: number;
+	type: CheckpointType;
+	path: string;
+	compressed: boolean;
+	checksum: string;
+	size: number;
+	createdAt: string;
+	baseVersion?: number;
+}
+
+/**
+ * Checkpoint index for a job
+ */
+export interface CheckpointIndex {
+	jobId: string;
+	entries: IndexEntry[];
+	currentVersion: number;
+	lastUpdated: string;
+}
+
+// ─── Configuration ────────────────────────────────────────────────────────
+
+/**
+ * Checkpoint engine configuration
+ */
+export interface CheckpointEngineConfig {
+	/**
+	 * Root directory for checkpoint storage
+	 */
+	rootDir?: string;
+
+	/**
+	 * Enable compression for checkpoints
+	 */
+	compression?: boolean;
+
+	/**
+	 * Enable incremental checkpoints
+	 */
+	incremental?: boolean;
+
+	/**
+	 * Maximum number of checkpoints to keep
+	 */
+	maxCheckpoints?: number;
+
+	/**
+	 * Automatically prune old checkpoints on save
+	 */
+	autoPrune?: boolean;
+
+	/**
+	 * Checksum algorithm
+	 */
+	checksumAlgorithm?: "md5" | "sha256";
+
+	/**
+	 * Enable parallel file writes
+	 */
+	parallelWrites?: boolean;
+
+	/**
+	 * Build metadata index
+	 */
+	metadataIndex?: boolean;
+}
+
+// ─── Event Types ─────────────────────────────────────────────────────────
+
+/**
+ * Checkpoint event
+ */
+export interface CheckpointEvent {
+	type: "checkpoint" | "recovery" | "prune" | "verify";
+	jobId: string;
+	version?: number;
+	timestamp: string;
+	data?: Record<string, unknown>;
+}
+
+/**
+ * Event log entry
+ */
+export interface EventLogEntry {
+	id: string;
+	event: CheckpointEvent;
+	correlationId?: string;
+}
+
+// ─── Legacy Types ────────────────────────────────────────────────────────
+
+/**
+ * Legacy checkpoint format
+ */
+export interface LegacyCheckpoint {
+	version: number;
+	jobId: string;
+	status: string;
+	state: Record<string, unknown>;
+	timestamp: string;
+}
+
+/**
+ * Check if a checkpoint is in legacy format
+ */
+export function isLegacyCheckpoint(
+	checkpoint: unknown,
+): checkpoint is LegacyCheckpoint {
+	if (typeof checkpoint !== "object" || checkpoint === null) {
+		return false;
+	}
+
+	const cp = checkpoint as Record<string, unknown>;
+
+	return (
+		typeof cp.version === "number" &&
+		typeof cp.jobId === "string" &&
+		typeof cp.status === "string" &&
+		cp.state !== undefined &&
+		typeof cp.timestamp === "string"
+	);
+}

package/packages/checkpoint/test/engine.test.ts

@@ -0,0 +1,265 @@
+/**
+ * Checkpoint Engine - Tests
+ */
+
+import { describe, it, expect, beforeEach, afterAll } from "bun:test";
+import { createCheckpointEngine, SDK_VERSION } from "../src/index.js";
+import type { RuntimeState } from "../src/types.js";
+
+describe("CheckpointEngine", () => {
+	describe("SDK_VERSION", () => {
+		it("should export SDK_VERSION", () => {
+			expect(SDK_VERSION).toBeDefined();
+			expect(typeof SDK_VERSION).toBe("string");
+		});
+	});
+
+	describe("createCheckpointEngine", () => {
+		it("should create a checkpoint engine instance", () => {
+			const engine = createCheckpointEngine({
+				rootDir: "/tmp/test-checkpoints",
+			});
+			expect(engine).toBeDefined();
+		});
+
+		it("should create with default config", () => {
+			const engine = createCheckpointEngine();
+			expect(engine).toBeDefined();
+		});
+	});
+
+	describe("save and load", () => {
+		const engine = createCheckpointEngine({
+			rootDir: "/tmp/checkpoint-test",
+			compression: false,
+			incremental: false,
+			autoPrune: false,
+		});
+
+		const testState: RuntimeState = {
+			version: 1,
+			jobId: "test-job-1",
+			status: "running",
+			requirement: "Test requirement",
+			tasks: [
+				{
+					id: "task-1",
+					title: "Task 1",
+					description: "First task",
+					status: "done",
+				},
+				{
+					id: "task-2",
+					title: "Task 2",
+					description: "Second task",
+					status: "pending",
+				},
+			],
+			createdAt: new Date().toISOString(),
+			updatedAt: new Date().toISOString(),
+		};
+
+		it("should save a checkpoint", async () => {
+			const metadata = await engine.save("test-job-1", testState);
+
+			expect(metadata).toBeDefined();
+			expect(metadata.jobId).toBe("test-job-1");
+			expect(metadata.version).toBe(1);
+			expect(metadata.type).toBe("full");
+		});
+
+		it("should increment version on save", async () => {
+			const state2 = {
+				...testState,
+				version: 2,
+				updatedAt: new Date().toISOString(),
+			};
+			const metadata = await engine.save("test-job-1", state2);
+
+			expect(metadata.version).toBe(2);
+		});
+
+		it("should load the latest checkpoint", async () => {
+			const loaded = await engine.load("test-job-1");
+
+			expect(loaded).toBeDefined();
+			expect(loaded?.jobId).toBe("test-job-1");
+			expect(loaded?.status).toBe("running");
+		});
+
+		it("should return null for non-existent job", async () => {
+			const loaded = await engine.load("non-existent-job");
+
+			expect(loaded).toBeNull();
+		});
+
+		it("should get metadata for all checkpoints", async () => {
+			const metadata = await engine.getMetadata("test-job-1");
+
+			expect(metadata.length).toBeGreaterThan(0);
+			expect(metadata[0].jobId).toBe("test-job-1");
+		});
+
+		it("should delete all checkpoints", async () => {
+			await engine.deleteAll("test-job-1");
+
+			const loaded = await engine.load("test-job-1");
+			expect(loaded).toBeNull();
+		});
+	});
+
+	describe("incremental checkpoints", () => {
+		const engine = createCheckpointEngine({
+			rootDir: "/tmp/checkpoint-incremental",
+			compression: false,
+			incremental: true,
+			autoPrune: false,
+		});
+
+		it("should save incremental checkpoint", async () => {
+			const state1: RuntimeState = {
+				version: 1,
+				jobId: "incremental-test",
+				status: "running",
+				requirement: "Test",
+				tasks: [],
+				createdAt: new Date().toISOString(),
+				updatedAt: new Date().toISOString(),
+			};
+
+			await engine.save("incremental-test", state1);
+
+			const state2: RuntimeState = {
+				...state1,
+				version: 2,
+				status: "completed",
+				updatedAt: new Date().toISOString(),
+			};
+
+			const metadata = await engine.save("incremental-test", state2);
+
+			// Should be incremental after first full checkpoint
+			expect(["full", "incremental"]).toContain(metadata.type);
+		});
+
+		afterAll(async () => {
+			await engine.deleteAll("incremental-test");
+		});
+	});
+
+	describe("recovery", () => {
+		const engine = createCheckpointEngine({
+			rootDir: "/tmp/checkpoint-recovery",
+			compression: false,
+			incremental: false,
+			autoPrune: false,
+		});
+
+		beforeEach(async () => {
+			// Clear any stale checkpoints from previous runs so version starts at 1
+			await engine.deleteAll("recovery-test");
+
+			const state: RuntimeState = {
+				version: 1,
+				jobId: "recovery-test",
+				status: "running",
+				requirement: "Recovery test",
+				tasks: [],
+				createdAt: new Date().toISOString(),
+				updatedAt: new Date().toISOString(),
+			};
+			await engine.save("recovery-test", state);
+		});
+
+		it("should recover with latest strategy", async () => {
+			const result = await engine.recover("recovery-test", "latest");
+
+			expect(result.success).toBe(true);
+			expect(result.recoveredVersion).toBe(1);
+			expect(result.recoveredState?.jobId).toBe("recovery-test");
+		});
+
+		it("should recover with specific version", async () => {
+			const result = await engine.recover("recovery-test", "specific:1");
+
+			expect(result.success).toBe(true);
+			expect(result.recoveredVersion).toBe(1);
+		});
+
+		it("should fail for non-existent job", async () => {
+			const result = await engine.recover("non-existent", "latest");
+
+			expect(result.success).toBe(false);
+		});
+	});
+
+	describe("pruning", () => {
+		const engine = createCheckpointEngine({
+			rootDir: "/tmp/checkpoint-prune",
+			compression: false,
+			incremental: false,
+			autoPrune: false,
+		});
+
+		it("should prune old checkpoints", async () => {
+			// Create multiple checkpoints
+			for (let i = 1; i <= 5; i++) {
+				const state: RuntimeState = {
+					version: i,
+					jobId: "prune-test",
+					status: "running",
+					requirement: `Version ${i}`,
+					tasks: [],
+					createdAt: new Date().toISOString(),
+					updatedAt: new Date().toISOString(),
+				};
+				await engine.save("prune-test", state);
+			}
+
+			// Prune to keep only 2
+			const result = await engine.prune("prune-test", 2);
+
+			expect(result.deletedCount).toBeGreaterThan(0);
+			expect(result.remainingCount).toBe(2);
+		});
+
+		afterAll(async () => {
+			await engine.deleteAll("prune-test");
+		});
+	});
+
+	describe("verification", () => {
+		const engine = createCheckpointEngine({
+			rootDir: "/tmp/checkpoint-verify",
+			compression: false,
+			incremental: false,
+			autoPrune: false,
+		});
+
+		beforeEach(async () => {
+			const state: RuntimeState = {
+				version: 1,
+				jobId: "verify-test",
+				status: "running",
+				requirement: "Verify test",
+				tasks: [],
+				createdAt: new Date().toISOString(),
+				updatedAt: new Date().toISOString(),
+			};
+			await engine.save("verify-test", state);
+		});
+
+		it("should verify checkpoint", async () => {
+			const result = await engine.verify("verify-test", 1);
+
+			expect(result.valid).toBe(true);
+			expect(result.checksumMatch).toBe(true);
+		});
+
+		it("should fail verification for non-existent checkpoint", async () => {
+			const result = await engine.verify("verify-test", 999);
+
+			expect(result.valid).toBe(false);
+		});
+	});
+});

package/packages/checkpoint/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "lib": [
+      "ES2022",
+      "DOM"
+    ],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "composite": true,
+    "types": [
+      "node"
+    ]
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "test"
+  ]
+}