@openfinclaw/fin-strategy-engine 0.0.1

package/src/strategy-registry.test.ts

@@ -0,0 +1,235 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { StrategyRegistry } from "./strategy-registry.js";
+import type { StrategyDefinition, BacktestResult, WalkForwardResult } from "./types.js";
+
+function mockDefinition(id = "test-strat"): StrategyDefinition {
+  return {
+    id,
+    name: "Test Strategy",
+    version: "1.0",
+    markets: ["crypto"],
+    symbols: ["BTC/USDT"],
+    timeframes: ["1d"],
+    parameters: { fast: 10, slow: 30 },
+    async onBar() {
+      return null;
+    },
+  };
+}
+
+function mockBacktestResult(strategyId: string): BacktestResult {
+  return {
+    strategyId,
+    startDate: 1000000,
+    endDate: 2000000,
+    initialCapital: 10000,
+    finalEquity: 12000,
+    totalReturn: 20,
+    sharpe: 1.5,
+    sortino: 2.0,
+    maxDrawdown: -5,
+    calmar: 4,
+    winRate: 60,
+    profitFactor: 1.8,
+    totalTrades: 10,
+    trades: [],
+    equityCurve: [10000, 12000],
+    dailyReturns: [0.2],
+  };
+}
+
+describe("StrategyRegistry", () => {
+  let tempDir: string;
+  let filePath: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "fin-registry-test-"));
+    filePath = join(tempDir, "state", "fin-strategies.json");
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("creates and lists strategies", () => {
+    const reg = new StrategyRegistry(filePath);
+    const record = reg.create(mockDefinition("s1"));
+
+    expect(record.id).toBe("s1");
+    expect(record.level).toBe("L0_INCUBATE");
+
+    const all = reg.list();
+    expect(all.length).toBe(1);
+    expect(all[0]!.id).toBe("s1");
+  });
+
+  it("gets a strategy by ID", () => {
+    const reg = new StrategyRegistry(filePath);
+    reg.create(mockDefinition("s1"));
+
+    const found = reg.get("s1");
+    expect(found).toBeDefined();
+    expect(found!.name).toBe("Test Strategy");
+
+    const notFound = reg.get("nonexistent");
+    expect(notFound).toBeUndefined();
+  });
+
+  it("filters by level", () => {
+    const reg = new StrategyRegistry(filePath);
+    reg.create(mockDefinition("s1"));
+    reg.create(mockDefinition("s2"));
+    reg.updateLevel("s2", "L1_BACKTEST");
+
+    const incubating = reg.list({ level: "L0_INCUBATE" });
+    expect(incubating.length).toBe(1);
+    expect(incubating[0]!.id).toBe("s1");
+
+    const backtested = reg.list({ level: "L1_BACKTEST" });
+    expect(backtested.length).toBe(1);
+    expect(backtested[0]!.id).toBe("s2");
+  });
+
+  it("updates level and persists", () => {
+    const reg = new StrategyRegistry(filePath);
+    reg.create(mockDefinition("s1"));
+    reg.updateLevel("s1", "L2_PAPER");
+
+    // Reload from disk
+    const reg2 = new StrategyRegistry(filePath);
+    const record = reg2.get("s1");
+    expect(record).toBeDefined();
+    expect(record!.level).toBe("L2_PAPER");
+  });
+
+  it("stores backtest result", () => {
+    const reg = new StrategyRegistry(filePath);
+    reg.create(mockDefinition("s1"));
+
+    const bt = mockBacktestResult("s1");
+    reg.updateBacktest("s1", bt);
+
+    const record = reg.get("s1");
+    expect(record!.lastBacktest).toBeDefined();
+    expect(record!.lastBacktest!.sharpe).toBe(1.5);
+  });
+
+  it("stores walk-forward result", () => {
+    const reg = new StrategyRegistry(filePath);
+    reg.create(mockDefinition("s1"));
+
+    const wf: WalkForwardResult = {
+      passed: true,
+      windows: [],
+      combinedTestSharpe: 1.2,
+      avgTrainSharpe: 1.5,
+      ratio: 0.8,
+      threshold: 0.6,
+    };
+    reg.updateWalkForward("s1", wf);
+
+    const record = reg.get("s1");
+    expect(record!.lastWalkForward).toBeDefined();
+    expect(record!.lastWalkForward!.passed).toBe(true);
+  });
+
+  it("throws when updating nonexistent strategy", () => {
+    const reg = new StrategyRegistry(filePath);
+    expect(() => reg.updateLevel("nope", "L1_BACKTEST")).toThrow("not found");
+  });
+
+  it("handles missing file gracefully", () => {
+    const reg = new StrategyRegistry(join(tempDir, "nonexistent", "file.json"));
+    expect(reg.list()).toEqual([]);
+  });
+
+  it("persists across instances", () => {
+    const reg1 = new StrategyRegistry(filePath);
+    reg1.create(mockDefinition("s1"));
+    reg1.create(mockDefinition("s2"));
+
+    const reg2 = new StrategyRegistry(filePath);
+    expect(reg2.list().length).toBe(2);
+  });
+
+  it("increments version when definition changes", () => {
+    const reg = new StrategyRegistry(filePath);
+    const def = mockDefinition("s1");
+    reg.create(def);
+
+    const updatedDef: StrategyDefinition = {
+      id: "s1",
+      name: "Test Strategy",
+      version: "1.0",
+      markets: ["crypto"],
+      symbols: ["BTC/USDT"],
+      timeframes: ["1d"],
+      parameters: { fast: 15, slow: 30 },
+      async onBar() {
+        return null;
+      },
+    };
+    reg.updateDefinition("s1", updatedDef);
+
+    const record = reg.get("s1");
+    expect(record!.version).toBe("1.1");
+    expect(record!.definition.parameters.fast).toBe(15);
+  });
+
+  it("does not increment version when definition is identical", () => {
+    const reg = new StrategyRegistry(filePath);
+    reg.create(mockDefinition("s1"));
+
+    const sameDef: StrategyDefinition = {
+      ...mockDefinition("s1"),
+      async onBar() {
+        return null;
+      },
+    };
+    reg.updateDefinition("s1", sameDef);
+
+    const record = reg.get("s1");
+    expect(record!.version).toBe("1.0");
+  });
+
+  it("increments semver version correctly", () => {
+    const reg = new StrategyRegistry(filePath);
+    reg.create({
+      id: "s1",
+      name: "Test Strategy",
+      version: "1.0.0",
+      markets: ["crypto"],
+      symbols: ["BTC/USDT"],
+      timeframes: ["1d"],
+      parameters: { fast: 10, slow: 30 },
+      async onBar() {
+        return null;
+      },
+    });
+
+    const updatedDef: StrategyDefinition = {
+      id: "s1",
+      name: "Test Strategy",
+      version: "1.0.0",
+      markets: ["crypto"],
+      symbols: ["BTC/USDT"],
+      timeframes: ["1d"],
+      parameters: { fast: 15, slow: 30 },
+      async onBar() {
+        return null;
+      },
+    };
+    reg.updateDefinition("s1", updatedDef);
+
+    const record = reg.get("s1");
+    expect(record!.version).toBe("1.0.1");
+  });
+
+  it("throws when updating definition of nonexistent strategy", () => {
+    const reg = new StrategyRegistry(filePath);
+    expect(() => reg.updateDefinition("nonexistent", mockDefinition())).toThrow("not found");
+  });
+});

package/src/strategy-registry.ts

@@ -0,0 +1,183 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import type {
+  BacktestResult,
+  StrategyDefinition,
+  StrategyLevel,
+  StrategyRecord,
+  StrategyStatus,
+  WalkForwardResult,
+} from "./types.js";
+
+/**
+ * Increment version string. Supports semver (x.y.z) and simple numeric versions.
+ */
+function incrementVersion(version: string): string {
+  const semverMatch = version.match(/^(\d+)\.(\d+)\.(\d+)$/);
+  if (semverMatch) {
+    const [, major, minor, patch] = semverMatch;
+    return `${major}.${minor}.${Number(patch) + 1}`;
+  }
+  const numericMatch = version.match(/^(\d+)$/);
+  if (numericMatch) {
+    return String(Number(numericMatch[1]) + 1);
+  }
+  const doubleMatch = version.match(/^(\d+)\.(\d+)$/);
+  if (doubleMatch) {
+    return `${doubleMatch[1]}.${Number(doubleMatch[2]) + 1}`;
+  }
+  return version + ".1";
+}
+
+/**
+ * Deep compare two objects to detect changes.
+ * Only compares serializable fields (ignores functions like onBar/init/onDayEnd).
+ */
+function hasDefinitionChangeded(oldDef: StrategyDefinition, newDef: StrategyDefinition): boolean {
+  const oldSerializable = {
+    id: oldDef.id,
+    name: oldDef.name,
+    version: oldDef.version,
+    markets: oldDef.markets,
+    symbols: oldDef.symbols,
+    timeframes: oldDef.timeframes,
+    parameters: oldDef.parameters,
+    parameterRanges: oldDef.parameterRanges,
+  };
+  const newSerializable = {
+    id: newDef.id,
+    name: newDef.name,
+    version: newDef.version,
+    markets: newDef.markets,
+    symbols: newDef.symbols,
+    timeframes: newDef.timeframes,
+    parameters: newDef.parameters,
+    parameterRanges: newDef.parameterRanges,
+  };
+  return JSON.stringify(oldSerializable) !== JSON.stringify(newSerializable);
+}
+
+/**
+ * Persistent strategy registry backed by a JSON file.
+ * Stores strategy metadata, backtest results, and walk-forward results.
+ */
+export class StrategyRegistry {
+  private records: Map<string, StrategyRecord> = new Map();
+  private definitionSnapshots: Map<string, string> = new Map();
+
+  constructor(private filePath: string) {
+    this.load();
+  }
+
+  /** Create a new strategy record. Returns the created record. */
+  create(definition: StrategyDefinition): StrategyRecord {
+    const now = Date.now();
+    const record: StrategyRecord = {
+      id: definition.id,
+      name: definition.name,
+      version: definition.version,
+      level: "L0_INCUBATE",
+      definition,
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.records.set(definition.id, record);
+    this.definitionSnapshots.set(definition.id, JSON.stringify(definition));
+    this.save();
+    return record;
+  }
+
+  /** Get a strategy record by ID. */
+  get(id: string): StrategyRecord | undefined {
+    return this.records.get(id);
+  }
+
+  /** List all strategies, optionally filtered by level. */
+  list(filter?: { level?: StrategyLevel }): StrategyRecord[] {
+    const all = [...this.records.values()];
+    if (filter?.level) {
+      return all.filter((r) => r.level === filter.level);
+    }
+    return all;
+  }
+
+  /** Update the promotion level of a strategy. */
+  updateLevel(id: string, level: StrategyLevel): void {
+    const record = this.records.get(id);
+    if (!record) throw new Error(`Strategy ${id} not found`);
+    record.level = level;
+    record.updatedAt = Date.now();
+    this.save();
+  }
+
+  /** Store a backtest result for a strategy. */
+  updateBacktest(id: string, result: BacktestResult): void {
+    const record = this.records.get(id);
+    if (!record) throw new Error(`Strategy ${id} not found`);
+    record.lastBacktest = result;
+    record.updatedAt = Date.now();
+    this.save();
+  }
+
+  /** Store a walk-forward result for a strategy. */
+  updateWalkForward(id: string, result: WalkForwardResult): void {
+    const record = this.records.get(id);
+    if (!record) throw new Error(`Strategy ${id} not found`);
+    record.lastWalkForward = result;
+    record.updatedAt = Date.now();
+    this.save();
+  }
+
+  /** Update the running status of a strategy. */
+  updateStatus(id: string, status: StrategyStatus): void {
+    const record = this.records.get(id);
+    if (!record) throw new Error(`Strategy ${id} not found`);
+    record.status = status;
+    record.updatedAt = Date.now();
+    this.save();
+  }
+
+  /** Update the definition of a strategy. Increments version if definition changed. */
+  updateDefinition(id: string, definition: StrategyDefinition): void {
+    const record = this.records.get(id);
+    if (!record) throw new Error(`Strategy ${id} not found`);
+    
+    const oldDefinition = record.definition;
+    if (hasDefinitionChangeded(oldDefinition, definition)) {
+      record.definition = definition;
+      record.version = incrementVersion(record.version);
+      record.updatedAt = Date.now();
+      this.definitionSnapshots.set(id, JSON.stringify(definition));
+      this.save();
+    }
+  }
+
+  /** Persist current state to disk. */
+  save(): void {
+    const dir = dirname(this.filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    const data = [...this.records.values()];
+    writeFileSync(this.filePath, JSON.stringify(data, null, 2), "utf-8");
+  }
+
+  /** Load state from disk. */
+  private load(): void {
+    if (!existsSync(this.filePath)) return;
+    try {
+      const raw = readFileSync(this.filePath, "utf-8");
+      const data = JSON.parse(raw) as StrategyRecord[];
+      this.records.clear();
+      this.definitionSnapshots.clear();
+      for (const record of data) {
+        this.records.set(record.id, record);
+        this.definitionSnapshots.set(record.id, JSON.stringify(record.definition));
+      }
+    } catch {
+      // Corrupted file — start fresh
+      this.records.clear();
+      this.definitionSnapshots.clear();
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,19 @@
+// Canonical definitions live in @openfinclaw/fin-shared-types.
+// Re-exported here for backward compatibility within fin-strategy-engine.
+export type {
+  OHLCV,
+  MarketRegime,
+  MarketType,
+  StrategyLevel,
+  StrategyStatus,
+  Signal,
+  Position,
+  IndicatorLib,
+  StrategyContext,
+  StrategyDefinition,
+  BacktestConfig,
+  TradeRecord,
+  BacktestResult,
+  WalkForwardResult,
+  StrategyRecord,
+} from "../../fin-shared-types/src/types.js";

package/src/walk-forward.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, it } from "vitest";
+import type { OHLCV } from "../../fin-shared-types/src/types.js";
+import { BacktestEngine } from "./backtest-engine.js";
+import type { BacktestConfig, Signal, StrategyContext, StrategyDefinition } from "./types.js";
+import { WalkForward } from "./walk-forward.js";
+
+function linearData(bars: number, startPrice: number, endPrice: number): OHLCV[] {
+  const data: OHLCV[] = [];
+  for (let i = 0; i < bars; i++) {
+    const price = startPrice + ((endPrice - startPrice) * i) / (bars - 1);
+    data.push({
+      timestamp: 1000000 + i * 86400000,
+      open: price,
+      high: price * 1.01,
+      low: price * 0.99,
+      close: price,
+      volume: 1000,
+    });
+  }
+  return data;
+}
+
+/** Strategy that consistently buys and holds → stable returns. Stateless so it works across walk-forward windows. */
+function stableStrategy(): StrategyDefinition {
+  return {
+    id: "stable",
+    name: "Stable",
+    version: "1.0",
+    markets: ["crypto"],
+    symbols: ["TEST"],
+    timeframes: ["1d"],
+    parameters: {},
+    async onBar(_bar: OHLCV, ctx: StrategyContext): Promise<Signal | null> {
+      // Buy if no position; fully stateless so walk-forward can reuse across windows
+      if (ctx.portfolio.positions.length === 0) {
+        return {
+          action: "buy",
+          symbol: "TEST",
+          sizePct: 100,
+          orderType: "market",
+          reason: "enter",
+          confidence: 1,
+        };
+      }
+      return null;
+    },
+  };
+}
+
+/**
+ * Strategy that only works on bars with indices < 30 (overfitting).
+ * Buys at bar 0, sells at bar 10, but does nothing on later bars.
+ */
+function overfitStrategy(): StrategyDefinition {
+  let barCount = 0;
+  let bought = false;
+  return {
+    id: "overfit",
+    name: "Overfit",
+    version: "1.0",
+    markets: ["crypto"],
+    symbols: ["TEST"],
+    timeframes: ["1d"],
+    parameters: {},
+    async onBar(_bar: OHLCV, ctx: StrategyContext): Promise<Signal | null> {
+      barCount++;
+      if (barCount === 1 && !bought) {
+        bought = true;
+        return {
+          action: "buy",
+          symbol: "TEST",
+          sizePct: 100,
+          orderType: "market",
+          reason: "overfit-buy",
+          confidence: 1,
+        };
+      }
+      return null;
+    },
+  };
+}
+
+const engine = new BacktestEngine();
+const wf = new WalkForward(engine);
+
+describe("WalkForward", () => {
+  it("validates a stable strategy on rising data → passed=true", async () => {
+    // 500 bars of rising data — consistent returns across all windows
+    const data = linearData(500, 100, 300);
+    const config: BacktestConfig = {
+      capital: 10000,
+      commissionRate: 0,
+      slippageBps: 0,
+      market: "crypto",
+    };
+
+    const result = await wf.validate(stableStrategy(), data, config, { windows: 5 });
+
+    expect(result.windows.length).toBe(5);
+    expect(result.passed).toBe(true);
+    expect(result.ratio).toBeGreaterThanOrEqual(0.6);
+  });
+
+  it("window boundaries do not overlap", async () => {
+    const data = linearData(500, 100, 300);
+    const config: BacktestConfig = {
+      capital: 10000,
+      commissionRate: 0,
+      slippageBps: 0,
+      market: "crypto",
+    };
+
+    const result = await wf.validate(stableStrategy(), data, config, { windows: 5 });
+
+    for (let i = 0; i < result.windows.length; i++) {
+      const w = result.windows[i]!;
+      // Train ends before test starts
+      expect(w.trainEnd).toBeLessThanOrEqual(w.testStart);
+
+      // No overlap with next window
+      if (i < result.windows.length - 1) {
+        const next = result.windows[i + 1]!;
+        expect(w.testEnd).toBeLessThanOrEqual(next.trainStart);
+      }
+    }
+  });
+
+  it("returns all window metrics", async () => {
+    const data = linearData(200, 100, 200);
+    const config: BacktestConfig = {
+      capital: 10000,
+      commissionRate: 0,
+      slippageBps: 0,
+      market: "crypto",
+    };
+
+    const result = await wf.validate(stableStrategy(), data, config, { windows: 4 });
+
+    expect(result.windows.length).toBe(4);
+    for (const w of result.windows) {
+      expect(w.trainStart).toBeDefined();
+      expect(w.trainEnd).toBeDefined();
+      expect(w.testStart).toBeDefined();
+      expect(w.testEnd).toBeDefined();
+      expect(typeof w.trainSharpe).toBe("number");
+      expect(typeof w.testSharpe).toBe("number");
+    }
+    expect(typeof result.combinedTestSharpe).toBe("number");
+    expect(typeof result.avgTrainSharpe).toBe("number");
+    expect(typeof result.ratio).toBe("number");
+    expect(result.threshold).toBe(0.6);
+  });
+
+  it("respects custom threshold", async () => {
+    const data = linearData(200, 100, 200);
+    const config: BacktestConfig = {
+      capital: 10000,
+      commissionRate: 0,
+      slippageBps: 0,
+      market: "crypto",
+    };
+
+    const result = await wf.validate(stableStrategy(), data, config, {
+      windows: 3,
+      threshold: 0.9,
+    });
+
+    expect(result.threshold).toBe(0.9);
+  });
+
+  it("handles too-small data gracefully", async () => {
+    const data = linearData(5, 100, 110);
+    const config: BacktestConfig = {
+      capital: 10000,
+      commissionRate: 0,
+      slippageBps: 0,
+      market: "crypto",
+    };
+
+    const result = await wf.validate(stableStrategy(), data, config, { windows: 10 });
+
+    expect(result.passed).toBe(false);
+    expect(result.windows.length).toBe(0);
+  });
+});