horizon-code 0.5.1 → 0.6.1

package/src/strategy/replay.ts

@@ -0,0 +1,191 @@
+// Execution replay — structured event log for post-mortem analysis
+// Records orders, fills, position changes, and metrics snapshots
+
+import { homedir } from "os";
+import { resolve, join } from "path";
+import { existsSync, mkdirSync, appendFileSync, readFileSync } from "fs";
+
+const REPLAY_ROOT = resolve(homedir(), ".horizon", "replays");
+
+export type ReplayEventType = "start" | "order" | "fill" | "position_change" | "metric_snapshot" | "error" | "stop";
+
+export interface ReplayEvent {
+  timestamp: string;
+  elapsed_secs: number;
+  type: ReplayEventType;
+  data: Record<string, unknown>;
+}
+
+export interface ReplaySession {
+  pid: number;
+  strategy_name: string;
+  started_at: string;
+  events: ReplayEvent[];
+}
+
+function ensureDir(): void {
+  if (!existsSync(REPLAY_ROOT)) mkdirSync(REPLAY_ROOT, { recursive: true });
+}
+
+// Active replay sessions indexed by PID
+const activeSessions = new Map<number, { path: string; startedAt: number; strategyName: string }>();
+
+/** Start recording a replay session for a process */
+export function startReplay(pid: number, strategyName: string): void {
+  ensureDir();
+  const slug = strategyName.toLowerCase().replace(/[^a-z0-9]+/g, "_");
+  const ts = new Date().toISOString().replace(/[:.]/g, "-");
+  const fileName = `${slug}_${ts}.jsonl`;
+  const path = join(REPLAY_ROOT, fileName);
+
+  activeSessions.set(pid, { path, startedAt: Date.now(), strategyName });
+
+  // Write header
+  const header = JSON.stringify({
+    timestamp: new Date().toISOString(),
+    elapsed_secs: 0,
+    type: "start",
+    data: { pid, strategy_name: strategyName },
+  });
+  appendFileSync(path, header + "\n");
+}
+
+/** Record a replay event */
+export function recordEvent(pid: number, type: ReplayEventType, data: Record<string, unknown>): void {
+  const session = activeSessions.get(pid);
+  if (!session) return;
+
+  const event: ReplayEvent = {
+    timestamp: new Date().toISOString(),
+    elapsed_secs: (Date.now() - session.startedAt) / 1000,
+    type,
+    data,
+  };
+
+  try {
+    appendFileSync(session.path, JSON.stringify(event) + "\n");
+  } catch {}
+}
+
+/** Record metrics snapshot from parsed __HZ_METRICS__ data */
+export function recordMetrics(pid: number, metrics: Record<string, unknown>): void {
+  recordEvent(pid, "metric_snapshot", metrics);
+}
+
+/** Record an order event parsed from logs */
+export function recordOrder(pid: number, order: {
+  side: string;
+  market: string;
+  size: number;
+  price: number;
+  type?: string;
+}): void {
+  recordEvent(pid, "order", order);
+}
+
+/** Stop recording and finalize the replay */
+export function stopReplay(pid: number, exitCode?: number): void {
+  const session = activeSessions.get(pid);
+  if (!session) return;
+
+  recordEvent(pid, "stop", { exit_code: exitCode ?? null, duration_secs: (Date.now() - session.startedAt) / 1000 });
+  activeSessions.delete(pid);
+}
+
+/** Load a replay session from disk */
+export function loadReplay(fileName: string): ReplaySession | null {
+  const path = join(REPLAY_ROOT, fileName);
+  if (!existsSync(path)) return null;
+
+  const lines = readFileSync(path, "utf-8").split("\n").filter(Boolean);
+  const events: ReplayEvent[] = [];
+  let pid = 0;
+  let strategyName = "";
+  let startedAt = "";
+
+  for (const line of lines) {
+    try {
+      const event: ReplayEvent = JSON.parse(line);
+      events.push(event);
+      if (event.type === "start") {
+        pid = (event.data.pid as number) ?? 0;
+        strategyName = (event.data.strategy_name as string) ?? "";
+        startedAt = event.timestamp;
+      }
+    } catch {}
+  }
+
+  return { pid, strategy_name: strategyName, started_at: startedAt, events };
+}
+
+/** List all replay files, newest first */
+export function listReplays(): { fileName: string; strategy: string; date: string; eventCount: number }[] {
+  ensureDir();
+  const { readdirSync, statSync } = require("fs");
+  const files: string[] = readdirSync(REPLAY_ROOT).filter((f: string) => f.endsWith(".jsonl"));
+
+  return files
+    .map((fileName: string) => {
+      const path = join(REPLAY_ROOT, fileName);
+      const stat = statSync(path);
+      // Extract strategy name from filename
+      const parts = fileName.replace(".jsonl", "").split("_");
+      const strategy = parts.slice(0, -6).join("_") || parts[0] || "unknown";
+      const lineCount = readFileSync(path, "utf-8").split("\n").filter(Boolean).length;
+
+      return {
+        fileName,
+        strategy,
+        date: stat.mtime.toISOString(),
+        eventCount: lineCount,
+      };
+    })
+    .sort((a: any, b: any) => new Date(b.date).getTime() - new Date(a.date).getTime());
+}
+
+/** Generate a human-readable replay summary */
+export function summarizeReplay(session: ReplaySession): string {
+  const metrics = session.events.filter(e => e.type === "metric_snapshot");
+  const orders = session.events.filter(e => e.type === "order");
+  const errors = session.events.filter(e => e.type === "error");
+  const stopEvent = session.events.find(e => e.type === "stop");
+
+  const duration = stopEvent?.elapsed_secs ?? (metrics.length > 0 ? metrics[metrics.length - 1]!.elapsed_secs : 0);
+  const durationStr = duration > 3600 ? `${(duration / 3600).toFixed(1)}h` : `${(duration / 60).toFixed(1)}m`;
+
+  const lines: string[] = [];
+  lines.push(`Strategy: ${session.strategy_name} | Duration: ${durationStr} | Events: ${session.events.length}`);
+  lines.push(`Orders: ${orders.length} | Metric snapshots: ${metrics.length} | Errors: ${errors.length}`);
+
+  if (metrics.length >= 2) {
+    const first = metrics[0]!.data;
+    const last = metrics[metrics.length - 1]!.data;
+    lines.push(`P&L: $${first.pnl ?? 0} → $${last.pnl ?? 0}`);
+    lines.push(`Positions: ${first.positions ?? 0} → ${last.positions ?? 0}`);
+  }
+
+  if (orders.length > 0) {
+    lines.push("");
+    lines.push("Order timeline:");
+    for (const o of orders.slice(0, 20)) {
+      const elapsed = o.elapsed_secs > 60 ? `${(o.elapsed_secs / 60).toFixed(1)}m` : `${o.elapsed_secs.toFixed(0)}s`;
+      lines.push(`  ${elapsed}: ${o.data.side} ${o.data.size} @ ${o.data.price} on ${o.data.market}`);
+    }
+    if (orders.length > 20) lines.push(`  ... and ${orders.length - 20} more orders`);
+  }
+
+  if (errors.length > 0) {
+    lines.push("");
+    lines.push("Errors:");
+    for (const e of errors.slice(0, 5)) {
+      lines.push(`  ${e.elapsed_secs.toFixed(0)}s: ${e.data.message ?? JSON.stringify(e.data)}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/** Check if replay is active for a PID */
+export function isRecording(pid: number): boolean {
+  return activeSessions.has(pid);
+}