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

package/packages/experience-replay/dist/types.d.ts.map

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

package/packages/experience-replay/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Experience Replay Types (RFC-0059)
+ *
+ * Interfaces for replaying prior runtime execution.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/packages/experience-replay/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/packages/experience-replay/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@pi-harness/experience-replay",
+  "version": "0.6.3-beta.13",
+  "description": "Experience replay for debugging and reproducibility (RFC-0059)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --experimental-vm-modules ../../node_modules/jest/bin/jest.js",
+    "lint": "eslint src --ext .ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  }
+}

package/packages/experience-replay/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Experience Replay (RFC-0059)
+ *
+ * Re-exports all public types and classes.
+ */
+
+export { ExperienceReplay, createExperienceReplay } from "./replay.js";
+export type {
+	ReplayRequest,
+	ReplayResult,
+	ReplayEvent,
+	ReplayDivergence,
+	JobStateSnapshot,
+	ReplaySources,
+	DivergenceCheck,
+	DivergenceReason,
+	ReplayRuntimeEvent,
+	ReplayMode,
+} from "./types.js";

package/packages/experience-replay/src/replay.ts

@@ -0,0 +1,348 @@
+/**
+ * Experience Replay (RFC-0059)
+ *
+ * Reconstructs prior runtime execution from persisted events and checkpoints.
+ */
+
+import type {
+	ReplayRequest,
+	ReplayResult,
+	ReplayEvent,
+	ReplayDivergence,
+	JobStateSnapshot,
+	ReplaySources,
+	DivergenceReason,
+	ReplayRuntimeEvent,
+	RuntimeEvent,
+	RuntimeCheckpoint,
+	TaskGraph,
+} from "./types.js";
+
+// ─── Event Timeline Reconstruction ───────────────────────────────────────────
+
+function reconstructTimeline(
+	events: RuntimeEvent[],
+	startSequence = 0,
+): ReplayEvent[] {
+	return events.map((event, index) => ({
+		sequence: startSequence + index,
+		timestamp: event.ts,
+		type: event.type,
+		data: event.data || {},
+	}));
+}
+
+// ─── State Reconstruction ─────────────────────────────────────────────────────
+
+function reconstructState(
+	jobId: string,
+	checkpoint: RuntimeCheckpoint | undefined,
+	events: RuntimeEvent[],
+	taskGraph: TaskGraph | undefined,
+): JobStateSnapshot {
+	// Apply events to checkpoint to get final state
+	let currentTaskId = checkpoint?.currentTaskId;
+	let status = checkpoint?.status || "unknown";
+
+	// Process events to find latest state
+	for (const event of events) {
+		if (event.type === "task.started" && event.data?.taskId) {
+			currentTaskId = event.data.taskId as string;
+		}
+		if (event.type === "job.status") {
+			status = (event.data?.status as string) || status;
+		}
+	}
+
+	return {
+		jobId,
+		status,
+		currentTaskId,
+		checkpoint: checkpoint || {
+			version: 0,
+			jobId,
+			status: "unknown",
+			requirement: "",
+			createdAt: new Date().toISOString(),
+			updatedAt: new Date().toISOString(),
+		},
+		taskGraph: taskGraph || { nodes: [], edges: [] },
+		events,
+		timestamp: new Date().toISOString(),
+	};
+}
+
+// ─── Divergence Detection ────────────────────────────────────────────────────
+
+// ─── Source Validation ────────────────────────────────────────────────────────
+
+function validateSources(sources: ReplaySources): {
+	valid: boolean;
+	missing: string[];
+} {
+	const missing: string[] = [];
+
+	if (!sources.checkpoint && !sources.events) {
+		missing.push("checkpoint or events");
+	}
+
+	return { valid: missing.length === 0, missing };
+}
+
+// ─── Mode Handlers ────────────────────────────────────────────────────────────
+
+async function handleInspect(
+	sources: ReplaySources,
+	jobId: string,
+	fromSequence?: number,
+	toSequence?: number,
+): Promise<{ state: JobStateSnapshot; timeline: ReplayEvent[] }> {
+	const events = sources.events || [];
+	const filteredEvents =
+		fromSequence !== undefined || toSequence !== undefined
+			? events.slice(fromSequence, toSequence)
+			: events;
+
+	const timeline = reconstructTimeline(filteredEvents, fromSequence ?? 0);
+	const state = reconstructState(
+		jobId,
+		sources.checkpoint,
+		filteredEvents,
+		sources.taskGraph,
+	);
+
+	return { state, timeline };
+}
+
+async function handleSimulate(
+	sources: ReplaySources,
+	jobId: string,
+	fromSequence?: number,
+	toSequence?: number,
+): Promise<{
+	state: JobStateSnapshot;
+	timeline: ReplayEvent[];
+	divergences: ReplayDivergence[];
+}> {
+	const events = sources.events || [];
+	const filteredEvents =
+		fromSequence !== undefined || toSequence !== undefined
+			? events.slice(fromSequence, toSequence)
+			: events;
+
+	const timeline = reconstructTimeline(filteredEvents, fromSequence ?? 0);
+	const state = reconstructState(
+		jobId,
+		sources.checkpoint,
+		filteredEvents,
+		sources.taskGraph,
+	);
+
+	// Check for divergent events
+	const divergences: ReplayDivergence[] = [];
+	for (let i = 0; i < timeline.length; i++) {
+		const event = timeline[i];
+		if (event.type.includes("error") || event.type.includes("failure")) {
+			divergences.push({
+				sequence: event.sequence,
+				reason: "Provider output differs" as DivergenceReason,
+				severity: "warning",
+			});
+		}
+	}
+
+	return { state, timeline, divergences };
+}
+
+async function handleReexecute(
+	sources: ReplaySources,
+	jobId: string,
+	allowExternalCalls: boolean,
+): Promise<{
+	state: JobStateSnapshot;
+	timeline: ReplayEvent[];
+	divergences: ReplayDivergence[];
+}> {
+	// Reexecute requires explicit approval and valid sources
+	const validation = validateSources(sources);
+	if (!validation.valid) {
+		throw new Error(
+			`Missing required sources: ${validation.missing.join(", ")}`,
+		);
+	}
+
+	if (!allowExternalCalls) {
+		throw new Error(
+			"Reexecution with external calls requires explicit approval",
+		);
+	}
+
+	// For reexecution, we simulate first then mark for actual reexecution
+	const result = await handleSimulate(sources, jobId);
+
+	// Add informational divergence for reexecution mode
+	result.divergences.push({
+		sequence: 0,
+		reason: "Runtime version differs" as DivergenceReason,
+		severity: "info",
+	});
+
+	return result;
+}
+
+// ─── Main Engine ───────────────────────────────────────────────────────────────
+
+export class ExperienceReplay {
+	private eventListeners: Array<(event: ReplayRuntimeEvent) => void> = [];
+
+	/**
+	 * Replay a prior job execution
+	 */
+	async replay(
+		request: ReplayRequest,
+		sources: ReplaySources,
+	): Promise<ReplayResult> {
+		const { jobId, mode } = request;
+
+		// Emit start event
+		this.emit({ type: "replay.started", jobId, mode });
+
+		// Validate sources
+		const validation = validateSources(sources);
+		if (!validation.valid) {
+			return {
+				jobId,
+				reconstructedState: {
+					jobId,
+					status: "error",
+					checkpoint: sources.checkpoint || ({} as RuntimeCheckpoint),
+					taskGraph: sources.taskGraph || { nodes: [], edges: [] },
+					events: [],
+					timestamp: new Date().toISOString(),
+				},
+				timeline: [],
+				divergences: [
+					{
+						sequence: 0,
+						reason: `Missing sources: ${validation.missing.join(", ")}`,
+						severity: "error",
+					},
+				],
+				artifacts: [],
+				replayedAt: new Date().toISOString(),
+			};
+		}
+
+		try {
+			let result: {
+				state: JobStateSnapshot;
+				timeline: ReplayEvent[];
+				divergences?: ReplayDivergence[];
+			};
+
+			switch (mode) {
+				case "inspect":
+					result = await handleInspect(
+						sources,
+						jobId,
+						request.fromSequence,
+						request.toSequence,
+					);
+					break;
+				case "simulate":
+					result = await handleSimulate(
+						sources,
+						jobId,
+						request.fromSequence,
+						request.toSequence,
+					);
+					break;
+				case "reexecute":
+					result = await handleReexecute(
+						sources,
+						jobId,
+						request.allowExternalCalls,
+					);
+					break;
+			}
+
+			// Emit divergence events
+			if (result.divergences) {
+				for (const div of result.divergences) {
+					this.emit({
+						type: "replay.divergence.detected",
+						jobId,
+						reason: div.reason,
+					});
+				}
+			}
+
+			// Collect artifacts
+			const artifacts: string[] = [];
+			if (sources.prompts) artifacts.push(...Object.keys(sources.prompts));
+			if (sources.outputs) artifacts.push(...Object.keys(sources.outputs));
+
+			// Emit completion event
+			this.emit({ type: "replay.completed", jobId });
+
+			return {
+				jobId,
+				reconstructedState: result.state,
+				timeline: result.timeline,
+				divergences: result.divergences || [],
+				artifacts,
+				replayedAt: new Date().toISOString(),
+			};
+		} catch (error) {
+			const errorMessage =
+				error instanceof Error ? error.message : String(error);
+			return {
+				jobId,
+				reconstructedState: {
+					jobId,
+					status: "error",
+					checkpoint: sources.checkpoint || ({} as RuntimeCheckpoint),
+					taskGraph: sources.taskGraph || { nodes: [], edges: [] },
+					events: [],
+					timestamp: new Date().toISOString(),
+				},
+				timeline: [],
+				divergences: [
+					{
+						sequence: 0,
+						reason: errorMessage,
+						severity: "error",
+					},
+				],
+				artifacts: [],
+				replayedAt: new Date().toISOString(),
+			};
+		}
+	}
+
+	/**
+	 * Subscribe to replay events
+	 */
+	onEvent(listener: (event: ReplayRuntimeEvent) => void): () => void {
+		this.eventListeners.push(listener);
+		return () => {
+			this.eventListeners = this.eventListeners.filter((l) => l !== listener);
+		};
+	}
+
+	private emit(event: ReplayRuntimeEvent): void {
+		for (const listener of this.eventListeners) {
+			try {
+				listener(event);
+			} catch {
+				// Best effort
+			}
+		}
+	}
+}
+
+// ─── Factory ─────────────────────────────────────────────────────────────────
+
+export function createExperienceReplay(): ExperienceReplay {
+	return new ExperienceReplay();
+}

package/packages/experience-replay/src/types.ts

@@ -0,0 +1,128 @@
+/**
+ * Experience Replay Types (RFC-0059)
+ *
+ * Interfaces for replaying prior runtime execution.
+ */
+
+// ─── Local Type Definitions ───────────────────────────────────────────────
+
+export interface RuntimeEvent {
+	ts: string;
+	jobId: string;
+	type: string;
+	message: string;
+	data?: Record<string, unknown>;
+}
+
+export interface RuntimeCheckpoint {
+	version: number;
+	jobId: string;
+	status: string;
+	requirement: string;
+	currentTaskId?: string;
+	provider?: string;
+	resumeAt?: string;
+	lastError?: string;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface TaskGraphNode {
+	id: string;
+	title: string;
+	description: string;
+	status: string;
+	dependencies: string[];
+}
+
+export interface TaskGraph {
+	nodes: TaskGraphNode[];
+	edges: Array<{ from: string; to: string }>;
+}
+
+// ─── Replay Types ─────────────────────────────────────────────────────────────
+
+export type ReplayMode = "inspect" | "simulate" | "reexecute";
+
+export interface ReplayRequest {
+	jobId: string;
+	mode: ReplayMode;
+	fromSequence?: number;
+	toSequence?: number;
+	allowExternalCalls: boolean;
+}
+
+export interface JobStateSnapshot {
+	jobId: string;
+	status: string;
+	currentTaskId?: string;
+	checkpoint: RuntimeCheckpoint;
+	taskGraph: TaskGraph;
+	events: RuntimeEvent[];
+	timestamp: string;
+}
+
+export interface ReplayEvent {
+	sequence: number;
+	timestamp: string;
+	type: string;
+	data: Record<string, unknown>;
+}
+
+export interface ReplayDivergence {
+	sequence: number;
+	reason: string;
+	expected?: unknown;
+	actual?: unknown;
+	severity: "info" | "warning" | "error";
+}
+
+export interface ReplayResult {
+	jobId: string;
+	reconstructedState: JobStateSnapshot;
+	timeline: ReplayEvent[];
+	divergences: ReplayDivergence[];
+	artifacts: string[];
+	replayedAt: string;
+}
+
+// ─── Replay Sources ───────────────────────────────────────────────────────────
+
+export interface ReplaySources {
+	checkpoint?: RuntimeCheckpoint;
+	events?: RuntimeEvent[];
+	taskGraph?: TaskGraph;
+	prompts?: Record<string, string>;
+	outputs?: Record<string, string>;
+	testResults?: Record<string, unknown>;
+	evaluation?: Record<string, unknown>;
+	repairs?: Record<string, unknown>;
+	knowledgeRefs?: string[];
+	/** Filter events by sequence range */
+	fromSequence?: number;
+	toSequence?: number;
+}
+
+// ─── Divergence Detection ─────────────────────────────────────────────────────
+
+export type DivergenceReason =
+	| "source_file_changed"
+	| "project_rules_changed"
+	| "provider_output_differs"
+	| "test_environment_changed"
+	| "required_artifact_missing"
+	| "runtime_version_differs";
+
+export interface DivergenceCheck {
+	type: DivergenceReason;
+	check: () => Promise<boolean>;
+	severity: "info" | "warning" | "error";
+}
+
+// ─── Runtime Events ───────────────────────────────────────────────────────────
+
+export type ReplayRuntimeEvent =
+	| { type: "replay.started"; jobId: string; mode: ReplayMode }
+	| { type: "replay.state.reconstructed"; jobId: string; sequence: number }
+	| { type: "replay.divergence.detected"; jobId: string; reason: string }
+	| { type: "replay.completed"; jobId: string };