tradelab 1.1.0 → 1.2.1

package/docs/superpowers/plans/2026-04-async-signals-seeding.md

@@ -1,981 +0,0 @@
-# Async Signals, Seeding & LlmSignal Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Let `signal()` be `async` (so an LLM/agent can be the live decision-maker) with a per-bar time budget, response caching, no-lookahead guarding, and a decision log — plus make tick-backtest randomness reproducible via a configurable seed.
-
-**Architecture:** Rather than fork the 200-line engine loop, refactor `BarSystemRunner.step()` into `_preSignal()` (all position/pending management, unchanged behavior) + `_applyRawSignal()` (the signal→pending tail) + thin `step()`/`stepAsync()` wrappers. A new `backtestAsync()` drives `stepAsync()` in an async loop and awaits the signal. `LlmSignal` wraps an async resolver with cache + timeout budget + strict no-lookahead view + decision log. The live engine awaits async signals. `backtestTicks()` gains a `seed` option.
-
-**Tech Stack:** Node ESM, `node:test`.
-
----
-
-### Task 1: Configurable seed for tick backtests
-
-**Files:**
-
-- Modify: `src/engine/backtestTicks.js`
-- Test: `test/tickSeed.test.js`
-
-The tick engine already has `deterministicFill(probability, seedParts)` but the seed
-is fixed by `[symbol, time, entry, stop, side]`. Add a `seed` option so two runs of
-the same data with the same `seed` are identical, and different seeds differ.
-
-- [ ] **Step 1: Write the failing test**
-
-```js
-// test/tickSeed.test.js
-import test from "node:test";
-import assert from "node:assert/strict";
-import { backtestTicks } from "../src/index.js";
-
-function buildTicks(n = 200) {
-  const start = Date.UTC(2025, 0, 2, 14, 30, 0);
-  return Array.from({ length: n }, (_, i) => ({
-    time: start + i * 1000,
-    bid: 100 + Math.sin(i / 5),
-    ask: 100.02 + Math.sin(i / 5),
-  }));
-}
-
-const signal = ({ index, bar }) =>
-  index % 20 === 0 ? { side: "long", entry: bar.close - 0.05, stop: bar.close - 0.2, rr: 2 } : null;
-
-test("same seed + queueFillProbability < 1 is reproducible", () => {
-  const ticks = buildTicks();
-  const a = backtestTicks({ ticks, signal, queueFillProbability: 0.5, seed: "run-1" });
-  const b = backtestTicks({ ticks, signal, queueFillProbability: 0.5, seed: "run-1" });
-  assert.equal(a.trades.length, b.trades.length);
-  assert.equal(a.metrics.totalPnL, b.metrics.totalPnL);
-});
-
-test("different seeds can produce different fill outcomes", () => {
-  const ticks = buildTicks();
-  const a = backtestTicks({ ticks, signal, queueFillProbability: 0.5, seed: "run-1" });
-  const c = backtestTicks({ ticks, signal, queueFillProbability: 0.5, seed: "run-999" });
-  // Not guaranteed different, but the seed must reach the fill RNG; assert it is accepted.
-  assert.equal(typeof a.metrics.totalPnL, "number");
-  assert.equal(typeof c.metrics.totalPnL, "number");
-});
-```
-
-- [ ] **Step 2: Run to verify it fails**
-
-Run: `node --test test/tickSeed.test.js`
-Expected: FAIL — `seed` is ignored; the first test may pass by luck (the existing
-seed parts are already deterministic), so to force a real failure first confirm the
-option is plumbed by the next steps. If both pass already, proceed — the change is
-making `seed` an explicit, documented contract.
-
-- [ ] **Step 3: Add `seed` to the function signature**
-
-In `backtestTicks({...})` destructured params, add after `queueFillProbability = 1,`:
-
-```js
-  seed = "tradelab-ticks",
-```
-
-- [ ] **Step 4: Thread the seed into the fill RNG**
-
-Find the limit-fill call:
-
-```js
-        if (
-          touched &&
-          deterministicFill(queueFillProbability, [
-            symbol,
-            tick.time,
-            pending.entry,
-            pending.stop,
-            pending.side,
-          ])
-        ) {
-```
-
-Replace the seed-parts array's first element so the user seed prefixes it:
-
-```js
-        if (
-          touched &&
-          deterministicFill(queueFillProbability, [
-            seed,
-            symbol,
-            tick.time,
-            pending.entry,
-            pending.stop,
-            pending.side,
-          ])
-        ) {
-```
-
-- [ ] **Step 5: Run test + suite**
-
-Run: `node --test test/tickSeed.test.js`
-Expected: PASS.
-
-Run: `node --test test/backtest.test.js`
-Expected: PASS (no behavior change for `queueFillProbability: 1`).
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/engine/backtestTicks.js test/tickSeed.test.js
-git commit -m "feat: configurable seed for tick backtest fills
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-### Task 2: Async signal invocation helper
-
-**Files:**
-
-- Modify: `src/engine/barSystemRunner.js` (add `callSignalWithContextAsync`)
-- Create: `src/engine/asyncSignal.js` (timeout budget)
-- Test: `test/engine/asyncSignal.test.js`
-
-- [ ] **Step 1: Write the failing test**
-
-```js
-// test/engine/asyncSignal.test.js
-import test from "node:test";
-import assert from "node:assert/strict";
-import { withBudget, BudgetExceededError } from "../../src/engine/asyncSignal.js";
-
-test("withBudget resolves when the promise beats the deadline", async () => {
-  const value = await withBudget(Promise.resolve(42), 50);
-  assert.equal(value, 42);
-});
-
-test("withBudget rejects with BudgetExceededError on timeout", async () => {
-  const slow = new Promise((resolve) => setTimeout(() => resolve(1), 100));
-  await assert.rejects(
-    () => withBudget(slow, 10),
-    (err) => err instanceof BudgetExceededError
-  );
-});
-
-test("withBudget of 0 or undefined disables the timeout", async () => {
-  const slow = new Promise((resolve) => setTimeout(() => resolve(7), 20));
-  assert.equal(await withBudget(slow, 0), 7);
-});
-```
-
-- [ ] **Step 2: Run to verify it fails**
-
-Run: `node --test test/engine/asyncSignal.test.js`
-Expected: FAIL — cannot find module.
-
-- [ ] **Step 3: Implement src/engine/asyncSignal.js**
-
-```js
-// src/engine/asyncSignal.js
-
-export class BudgetExceededError extends Error {
-  constructor(ms) {
-    super(`signal() exceeded its ${ms}ms per-bar budget`);
-    this.name = "BudgetExceededError";
-    this.budgetMs = ms;
-  }
-}
-
-/**
- * Race a promise against a per-bar time budget. `budgetMs` of 0/undefined
- * disables the timeout. Rejects with BudgetExceededError on overrun.
- */
-export function withBudget(promise, budgetMs) {
-  if (!budgetMs || budgetMs <= 0) return Promise.resolve(promise);
-  return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => reject(new BudgetExceededError(budgetMs)), budgetMs);
-    Promise.resolve(promise).then(
-      (value) => {
-        clearTimeout(timer);
-        resolve(value);
-      },
-      (err) => {
-        clearTimeout(timer);
-        reject(err);
-      }
-    );
-  });
-}
-```
-
-- [ ] **Step 4: Add callSignalWithContextAsync to barSystemRunner.js**
-
-In `src/engine/barSystemRunner.js`, below the existing `callSignalWithContext`
-export, add:
-
-```js
-export async function callSignalWithContextAsync({ signal, context, index, bar, symbol }) {
-  try {
-    return await signal(context);
-  } catch (error) {
-    const cause = error instanceof Error ? error.message : String(error);
-    throw new Error(
-      `signal() threw at index=${index}, time=${formatIsoTime(bar?.time)}, symbol=${symbol}: ${cause}`
-    );
-  }
-}
-```
-
-- [ ] **Step 5: Run test + suite**
-
-Run: `node --test test/engine/asyncSignal.test.js`
-Expected: PASS (3 tests).
-
-Run: `node --test`
-Expected: PASS.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/engine/asyncSignal.js src/engine/barSystemRunner.js test/engine/asyncSignal.test.js
-git commit -m "feat: add async signal budget helper and async invoker
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-### Task 3: Refactor BarSystemRunner.step into reusable phases
-
-**Files:**
-
-- Modify: `src/engine/barSystemRunner.js`
-- Test: `test/portfolio.test.js` (existing — must stay green)
-
-**Goal:** extract the signal-generation tail of `step()` so a sync `step()` and a
-new async `stepAsync()` share all position/pending management without duplication.
-
-- [ ] **Step 1: Confirm the baseline is green**
-
-Run: `node --test test/portfolio.test.js test/backtest.test.js`
-Expected: PASS. (We must not change behavior.)
-
-- [ ] **Step 2: Rename `step` to `_preSignal` and change its tail**
-
-In `src/engine/barSystemRunner.js`, locate the method `step({ signalEquity, canTrade = true, resolveEntrySize } = {})`. Make these exact changes:
-
-1. Rename it to `_preSignal({ signalEquity, canTrade = true, resolveEntrySize } = {})`.
-
-2. The method currently ends with this tail (the signal block + recordFrame +
-   index++ + return):
-
-```js
-    if (!this.pending) {
-      const rawSignal = callSignalWithContext({
-        signal: this.options.signal,
-        context: this.buildSignalContext(this.index, bar, signalEquity),
-        index: this.index,
-        bar,
-        symbol: this.symbol,
-      });
-      const nextSignal = normalizeSignal(rawSignal, bar, this.options.finalTP_R);
-
-      if (nextSignal) {
-        const signalRiskFraction = Number.isFinite(nextSignal.riskFraction)
-          ? nextSignal.riskFraction
-          : Number.isFinite(nextSignal.riskPct)
-            ? nextSignal.riskPct / 100
-            : this.options.riskPct / 100;
-        const expiryBars = nextSignal._entryExpiryBars ?? 5;
-        this.pending = {
-          side: nextSignal.side,
-          entry: nextSignal.entry,
-          stop: nextSignal.stop,
-          tp: nextSignal.takeProfit,
-          riskFrac: signalRiskFraction,
-          fixedQty: nextSignal.qty,
-          expiresAt: this.index + Math.max(1, expiryBars),
-          startedAtIndex: this.index,
-          meta: nextSignal,
-          plannedRiskAbs: Math.abs(nextSignal._initRisk ?? nextSignal.entry - nextSignal.stop),
-        };
-
-        if (touchedLimit(this.pending.side, this.pending.entry, bar, trigger)) {
-          if (
-            !this.openFromPending(bar, signalEquity, this.pending.entry, "limit", resolveEntrySize)
-          ) {
-            this.pending = null;
-          }
-        }
-      }
-    }
-
-    this.recordFrame(bar);
-    this.index += 1;
-    return bar;
-  }
-```
-
-Replace that entire tail with a return of a "needs signal" descriptor (DO NOT
-record the frame or advance the index here — the wrappers do that):
-
-```js
-    if (this.pending) {
-      this.recordFrame(bar);
-      this.index += 1;
-      return { handled: true, bar };
-    }
-
-    return {
-      handled: false,
-      bar,
-      trigger,
-      signalEquity,
-      resolveEntrySize,
-    };
-  }
-```
-
-3. Every OTHER early `return` inside the method body currently looks like
-   `this.recordFrame(bar); this.index += 1; return bar;`. Change each of those
-   `return bar;` statements to `return { handled: true, bar };`. There are two such
-   blocks: the `if (this.open || this.cooldown > 0)` block and the
-   `if (!canTrade || dailyLossHit || dailyTradeCapHit)` block. Also the very first
-   guard `if (!this.hasNext()) return null;` becomes
-   `if (!this.hasNext()) return { handled: true, bar: null };`.
-
-- [ ] **Step 3: Add `_applyRawSignal`, `step`, and `stepAsync`**
-
-Immediately after `_preSignal`, add these three methods:
-
-```js
-  _applyRawSignal(rawSignal, pre) {
-    const { bar, trigger, signalEquity, resolveEntrySize } = pre;
-    const nextSignal = normalizeSignal(rawSignal, bar, this.options.finalTP_R);
-
-    if (nextSignal) {
-      const signalRiskFraction = Number.isFinite(nextSignal.riskFraction)
-        ? nextSignal.riskFraction
-        : Number.isFinite(nextSignal.riskPct)
-          ? nextSignal.riskPct / 100
-          : this.options.riskPct / 100;
-      const expiryBars = nextSignal._entryExpiryBars ?? 5;
-      this.pending = {
-        side: nextSignal.side,
-        entry: nextSignal.entry,
-        stop: nextSignal.stop,
-        tp: nextSignal.takeProfit,
-        riskFrac: signalRiskFraction,
-        fixedQty: nextSignal.qty,
-        expiresAt: this.index + Math.max(1, expiryBars),
-        startedAtIndex: this.index,
-        meta: nextSignal,
-        plannedRiskAbs: Math.abs(nextSignal._initRisk ?? nextSignal.entry - nextSignal.stop),
-      };
-
-      if (touchedLimit(this.pending.side, this.pending.entry, bar, trigger)) {
-        if (!this.openFromPending(bar, signalEquity, this.pending.entry, "limit", resolveEntrySize)) {
-          this.pending = null;
-        }
-      }
-    }
-
-    this.recordFrame(bar);
-    this.index += 1;
-    return bar;
-  }
-
-  step(options = {}) {
-    const pre = this._preSignal(options);
-    if (pre.handled) return pre.bar;
-    const rawSignal = callSignalWithContext({
-      signal: this.options.signal,
-      context: this.buildSignalContext(this.index, pre.bar, pre.signalEquity),
-      index: this.index,
-      bar: pre.bar,
-      symbol: this.symbol,
-    });
-    return this._applyRawSignal(rawSignal, pre);
-  }
-
-  async stepAsync(options = {}) {
-    const pre = this._preSignal(options);
-    if (pre.handled) return pre.bar;
-    const rawSignal = await callSignalWithContextAsync({
-      signal: this.options.signal,
-      context: this.buildSignalContext(this.index, pre.bar, pre.signalEquity),
-      index: this.index,
-      bar: pre.bar,
-      symbol: this.symbol,
-    });
-    return this._applyRawSignal(rawSignal, pre);
-  }
-```
-
-- [ ] **Step 4: Add the import for the async invoker**
-
-`callSignalWithContextAsync` is defined in this same file (Task 2 Step 4), so no
-import is needed. Confirm `callSignalWithContext`, `normalizeSignal`, and
-`touchedLimit` are already in scope (they are — used by the original `step`).
-
-- [ ] **Step 5: Run the existing suites — behavior must be unchanged**
-
-Run: `node --test test/portfolio.test.js test/backtest.test.js`
-Expected: PASS. Portfolio uses `runner.step(...)`; the sync wrapper reproduces the
-original behavior exactly.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/engine/barSystemRunner.js
-git commit -m "refactor: split BarSystemRunner.step into reusable phases
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-### Task 4: `backtestAsync()`
-
-**Files:**
-
-- Create: `src/engine/backtestAsync.js`
-- Modify: `src/index.js`
-- Test: `test/backtestAsync.test.js`
-
-- [ ] **Step 1: Write the failing test**
-
-```js
-// test/backtestAsync.test.js
-import test from "node:test";
-import assert from "node:assert/strict";
-import { backtest, backtestAsync } from "../src/index.js";
-
-function buildCandles(count = 30) {
-  const start = Date.UTC(2025, 0, 2, 14, 30, 0);
-  return Array.from({ length: count }, (_, i) => ({
-    time: start + i * 5 * 60 * 1000,
-    open: 100 + i,
-    high: 101 + i,
-    low: 99 + i,
-    close: 100.5 + i,
-    volume: 1000 + i,
-  }));
-}
-
-const entryAt =
-  (idx) =>
-  ({ index, bar }) =>
-    index === idx ? { side: "buy", stop: bar.close - 1, rr: 2 } : null;
-
-test("backtestAsync with a sync signal matches backtest exactly", async () => {
-  const candles = buildCandles();
-  const opts = { candles, interval: "5m", warmupBars: 1, flattenAtClose: false };
-  const sync = backtest({ ...opts, signal: entryAt(1) });
-  const asyncResult = await backtestAsync({ ...opts, signal: entryAt(1) });
-  assert.equal(asyncResult.positions.length, sync.positions.length);
-  assert.equal(asyncResult.metrics.totalPnL, sync.metrics.totalPnL);
-});
-
-test("backtestAsync awaits a promise-returning signal", async () => {
-  const candles = buildCandles();
-  const result = await backtestAsync({
-    candles,
-    interval: "5m",
-    warmupBars: 1,
-    flattenAtClose: false,
-    async signal({ index, bar }) {
-      await Promise.resolve();
-      return index === 2 ? { side: "long", stop: bar.close - 1, rr: 2 } : null;
-    },
-  });
-  assert.equal(result.positions.length, 1);
-});
-
-test("backtestAsync enforces a per-bar signalBudgetMs", async () => {
-  const candles = buildCandles();
-  await assert.rejects(() =>
-    backtestAsync({
-      candles,
-      interval: "5m",
-      warmupBars: 1,
-      signalBudgetMs: 5,
-      async signal() {
-        await new Promise((r) => setTimeout(r, 50));
-        return null;
-      },
-    })
-  );
-});
-```
-
-- [ ] **Step 2: Run to verify it fails**
-
-Run: `node --test test/backtestAsync.test.js`
-Expected: FAIL — `backtestAsync` not exported.
-
-- [ ] **Step 3: Implement src/engine/backtestAsync.js**
-
-```js
-// src/engine/backtestAsync.js
-import { BarSystemRunner, callSignalWithContextAsync } from "./barSystemRunner.js";
-import { withBudget } from "./asyncSignal.js";
-
-/**
- * Async sibling of backtest(). Identical result shape, but `signal()` may return
- * a Promise. Each bar's signal is raced against `signalBudgetMs` (0 disables).
- *
- * Built on BarSystemRunner so position/pending/exit logic is shared with the
- * sync engine and portfolio mode — no duplicated loop.
- */
-export async function backtestAsync(rawOptions = {}) {
-  const budgetMs = rawOptions.signalBudgetMs ?? 0;
-
-  // Wrap the user signal so the per-bar budget is enforced where the runner
-  // awaits it. callSignalWithContextAsync awaits signal(context); we wrap the
-  // user's signal to apply the timeout to that single call.
-  const userSignal = rawOptions.signal;
-  const budgetedSignal = (context) =>
-    withBudget(
-      Promise.resolve().then(() => userSignal(context)),
-      budgetMs
-    );
-
-  const runner = new BarSystemRunner({ ...rawOptions, signal: budgetedSignal });
-
-  while (runner.hasNext()) {
-    await runner.stepAsync({ signalEquity: runner.getMarkedEquity() });
-  }
-
-  return runner.buildResult();
-}
-```
-
-Note: `callSignalWithContextAsync` is imported only to keep the dependency
-explicit for readers; the runner already uses it internally. If your linter flags
-the unused import, drop it.
-
-- [ ] **Step 4: Export from src/index.js**
-
-Add below `export { backtest } ...`:
-
-```js
-export { backtestAsync } from "./engine/backtestAsync.js";
-```
-
-- [ ] **Step 5: Run test + full suite**
-
-Run: `node --test test/backtestAsync.test.js`
-Expected: PASS (3 tests).
-
-Run: `node --test`
-Expected: PASS.
-
-- [ ] **Step 6: Lint + commit**
-
-```bash
-npm run lint
-git add src/engine/backtestAsync.js src/index.js test/backtestAsync.test.js
-git commit -m "feat: add backtestAsync with per-bar signal budget
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-### Task 5: `LlmSignal` — cached, budgeted, no-lookahead, logged
-
-**Files:**
-
-- Create: `src/engine/llmSignal.js`
-- Modify: `src/index.js`
-- Test: `test/engine/llmSignal.test.js`
-
-- [ ] **Step 1: Write the failing test**
-
-```js
-// test/engine/llmSignal.test.js
-import test from "node:test";
-import assert from "node:assert/strict";
-import { LlmSignal } from "../../src/engine/llmSignal.js";
-
-function ctx(index, candles) {
-  return { index, bar: candles[index], candles: candles.slice(0, index + 1), equity: 10_000 };
-}
-
-test("LlmSignal caches by bar time so resolve runs once per bar", async () => {
-  const candles = Array.from({ length: 5 }, (_, i) => ({
-    time: i * 1000,
-    close: 100 + i,
-    high: 101 + i,
-    low: 99 + i,
-  }));
-  let calls = 0;
-  const sig = new LlmSignal({
-    async resolve() {
-      calls += 1;
-      return { side: "long", stop: 99, rr: 2 };
-    },
-  });
-  const c = ctx(2, candles);
-  await sig.signal(c);
-  await sig.signal(c); // same bar => cached
-  assert.equal(calls, 1);
-  assert.equal(sig.log.length, 1);
-  assert.equal(sig.log[0].index, 2);
-});
-
-test("LlmSignal records a timeout decision when the budget is exceeded", async () => {
-  const candles = Array.from({ length: 3 }, (_, i) => ({
-    time: i * 1000,
-    close: 100,
-    high: 101,
-    low: 99,
-  }));
-  const sig = new LlmSignal({
-    budgetMs: 5,
-    onError: "skip",
-    async resolve() {
-      await new Promise((r) => setTimeout(r, 40));
-      return { side: "long", stop: 99, rr: 2 };
-    },
-  });
-  const out = await sig.signal(ctx(1, candles));
-  assert.equal(out, null); // skipped on timeout
-  assert.equal(sig.log[0].error.includes("budget"), true);
-});
-
-test("LlmSignal blocks lookahead access to future candles", async () => {
-  const candles = Array.from({ length: 5 }, (_, i) => ({
-    time: i * 1000,
-    close: 100 + i,
-    high: 101 + i,
-    low: 99 + i,
-  }));
-  let leaked = false;
-  const sig = new LlmSignal({
-    async resolve({ candles: view, index }) {
-      try {
-        // eslint-disable-next-line no-unused-expressions
-        view[index + 1].close;
-        leaked = true;
-      } catch {
-        leaked = false;
-      }
-      return null;
-    },
-  });
-  await sig.signal(ctx(2, candles));
-  assert.equal(leaked, false);
-});
-```
-
-- [ ] **Step 2: Run to verify it fails**
-
-Run: `node --test test/engine/llmSignal.test.js`
-Expected: FAIL — cannot find module.
-
-- [ ] **Step 3: Implement src/engine/llmSignal.js**
-
-```js
-// src/engine/llmSignal.js
-import { withBudget } from "./asyncSignal.js";
-
-function isArrayIndexKey(property) {
-  if (typeof property !== "string") return false;
-  const n = Number(property);
-  return Number.isInteger(n) && n >= 0;
-}
-
-// Same no-lookahead proxy the strict engine uses: reading candles beyond the
-// current index throws, so an LLM cannot peek at the future.
-function noLookaheadView(candles, index) {
-  return new Proxy(candles, {
-    get(target, property, receiver) {
-      if (isArrayIndexKey(property) && Number(property) > index) {
-        throw new Error(
-          `LlmSignal: lookahead access to candles[${String(property)}] (current index ${index})`
-        );
-      }
-      return Reflect.get(target, property, receiver);
-    },
-  });
-}
-
-/**
- * Wraps an async model-backed decision function for use as a tradelab signal.
- *
- * - Caches by bar time: resolve() runs at most once per bar.
- * - Enforces a per-bar `budgetMs` time budget.
- * - Exposes a no-lookahead candle view to resolve().
- * - Logs every decision (context summary, result or error) in `this.log`.
- *
- * `onError`: "skip" (return null, default) or "throw".
- * Use the instance's `.signal` bound method as the engine's `signal` option.
- */
-export class LlmSignal {
-  constructor({ resolve, budgetMs = 0, onError = "skip" } = {}) {
-    if (typeof resolve !== "function") {
-      throw new Error("LlmSignal requires a resolve(context) function");
-    }
-    this.resolve = resolve;
-    this.budgetMs = budgetMs;
-    this.onError = onError;
-    this.log = [];
-    this._cache = new Map(); // bar time -> resolved signal
-    this.signal = this.signal.bind(this);
-  }
-
-  async signal(context) {
-    const key = context.bar?.time ?? context.index;
-    if (this._cache.has(key)) return this._cache.get(key);
-
-    const safeContext = {
-      ...context,
-      candles: noLookaheadView(context.candles, context.index),
-    };
-
-    const startedAt = Date.now();
-    try {
-      const result = await withBudget(
-        Promise.resolve().then(() => this.resolve(safeContext)),
-        this.budgetMs
-      );
-      this._cache.set(key, result ?? null);
-      this.log.push({
-        index: context.index,
-        time: context.bar?.time,
-        close: context.bar?.close,
-        latencyMs: Date.now() - startedAt,
-        result: result ?? null,
-      });
-      return result ?? null;
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      this.log.push({
-        index: context.index,
-        time: context.bar?.time,
-        close: context.bar?.close,
-        latencyMs: Date.now() - startedAt,
-        error: message,
-      });
-      this._cache.set(key, null);
-      if (this.onError === "throw") throw error;
-      return null;
-    }
-  }
-}
-```
-
-- [ ] **Step 4: Export from src/index.js**
-
-```js
-export { LlmSignal } from "./engine/llmSignal.js";
-```
-
-- [ ] **Step 5: Run test + suite**
-
-Run: `node --test test/engine/llmSignal.test.js`
-Expected: PASS (3 tests).
-
-Run: `node --test`
-Expected: PASS.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/engine/llmSignal.js src/index.js test/engine/llmSignal.test.js
-git commit -m "feat: add LlmSignal cached/budgeted/no-lookahead wrapper
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-### Task 6: Live engine awaits async signals
-
-**Files:**
-
-- Modify: `src/live/engine/liveEngine.js`
-- Test: `test/live/liveEngine.test.js` (append)
-
-`handleBar` is already `async`; it calls `callSignalWithContext` synchronously.
-Switch it to await so `LlmSignal` / async signals work live.
-
-- [ ] **Step 1: Write the failing test (append to test/live/liveEngine.test.js)**
-
-Match the existing imports/harness in that file (it constructs a `LiveEngine`
-with a `PaperEngine` broker). Add:
-
-```js
-test("LiveEngine awaits an async signal", async () => {
-  // Reuse the file's existing helpers to build engine + paper broker + feed.
-  // Drive one bar through handleBar with an async signal that resolves a long.
-  // Assert a position opens (engine.openPosition is set or a position:opened event fired).
-  // See existing tests in this file for the exact construction pattern.
-});
-```
-
-Implement the body using the same construction the other tests in the file use,
-asserting that after feeding a bar that should trigger entry, `engine.getStatus().openPosition`
-is non-null (or a `position:opened` event was emitted).
-
-- [ ] **Step 2: Run to verify it fails or is flaky**
-
-Run: `node --test test/live/liveEngine.test.js`
-Expected: FAIL — an async signal returns a Promise, which `normalizeSignal`
-treats as truthy-but-invalid (no `side`), so no order is submitted.
-
-- [ ] **Step 3: Edit handleBar to await the signal**
-
-In `src/live/engine/liveEngine.js`, find:
-
-```js
-    if (!this.openPosition && !this.pendingOrder) {
-      const context = this._signalContext(bar);
-      const rawSignal = callSignalWithContext({
-        signal: this.options.signal,
-        context,
-        index: context.index,
-        bar,
-        symbol: this.symbol,
-      });
-```
-
-Replace `callSignalWithContext` with the async invoker and await it:
-
-```js
-    if (!this.openPosition && !this.pendingOrder) {
-      const context = this._signalContext(bar);
-      const rawSignal = await callSignalWithContextAsync({
-        signal: this.options.signal,
-        context,
-        index: context.index,
-        bar,
-        symbol: this.symbol,
-      });
-```
-
-- [ ] **Step 4: Update the import in liveEngine.js**
-
-Find:
-
-```js
-import {
-  callSignalWithContext,
-  normalizeSignal,
-  snapshotOpenPosition,
-} from "../../engine/barSystemRunner.js";
-```
-
-Replace with:
-
-```js
-import {
-  callSignalWithContextAsync,
-  normalizeSignal,
-  snapshotOpenPosition,
-} from "../../engine/barSystemRunner.js";
-```
-
-(`callSignalWithContext` was the only other use; if any remain, keep both in the
-import list.)
-
-- [ ] **Step 5: Run live suite + full suite**
-
-Run: `node --test test/live/liveEngine.test.js`
-Expected: PASS — sync signals still work (await of a non-Promise is a no-op) and
-async signals now resolve.
-
-Run: `node --test`
-Expected: PASS.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/live/engine/liveEngine.js test/live/liveEngine.test.js
-git commit -m "feat: live engine awaits async signals
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-### Task 7: Docs + example
-
-**Files:**
-
-- Create: `examples/llmSignal.js`
-- Modify: `docs/backtest-engine.md` and `docs/live-trading.md`
-- Modify: `README.md`
-
-- [ ] **Step 1: Write examples/llmSignal.js**
-
-```js
-// examples/llmSignal.js
-// Run: node examples/llmSignal.js
-import { backtestAsync, LlmSignal, getHistoricalCandles } from "../src/index.js";
-
-const candles = await getHistoricalCandles({
-  source: "yahoo",
-  symbol: "SPY",
-  interval: "1d",
-  period: "1y",
-  cache: true,
-});
-
-// Stand-in for a real model call. Replace `resolve` with an LLM/agent request.
-const llm = new LlmSignal({
-  budgetMs: 2000,
-  onError: "skip",
-  async resolve({ candles: history, bar }) {
-    const closes = history.map((c) => c.close);
-    const recent = closes.slice(-5);
-    const rising = recent.every((c, i) => i === 0 || c >= recent[i - 1]);
-    return rising ? { side: "long", stop: bar.close * 0.98, rr: 2 } : null;
-  },
-});
-
-const result = await backtestAsync({
-  candles,
-  symbol: "SPY",
-  interval: "1d",
-  signal: llm.signal,
-  signalBudgetMs: 3000,
-});
-
-console.log("trades:", result.metrics.trades, "PnL:", result.metrics.totalPnL.toFixed(2));
-console.log("decisions logged:", llm.log.length);
-```
-
-- [ ] **Step 2: Run the example**
-
-Run: `node examples/llmSignal.js`
-Expected: prints trade count, PnL, and a non-zero decision-log length (network
-permitting; if Yahoo is unavailable, swap to a local CSV via `getHistoricalCandles`).
-
-- [ ] **Step 3: Document in docs/backtest-engine.md**
-
-Add an "Async signals" section covering `backtestAsync`, `signalBudgetMs`, and how
-`LlmSignal` enforces caching, budget, no-lookahead, and the decision log. Cross-link
-`docs/live-trading.md` for the live path.
-
-- [ ] **Step 4: Mention seed reproducibility in docs**
-
-In the tick-backtest section, document the new `seed` option and that identical
-seed + data + params produces identical fills.
-
-- [ ] **Step 5: Lint, format, full test, commit**
-
-```bash
-npm run lint && npm run format:check && npm test
-git add examples/llmSignal.js docs/backtest-engine.md docs/live-trading.md README.md
-git commit -m "docs: async signals, LlmSignal example, tick seeding
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-## Self-review checklist
-
-- [ ] Sync `backtest()` and portfolio behavior unchanged — the refactor preserves `step()` semantics; the regression suites (`backtest.test.js`, `portfolio.test.js`) are the guard. ✔ (Task 3)
-- [ ] `_preSignal` return contract is consistent: `{ handled: true, bar }` for every early/terminal path, `{ handled: false, bar, trigger, signalEquity, resolveEntrySize }` only when a signal is needed. ✔
-- [ ] `backtestAsync` with a sync signal is asserted byte-equal to `backtest` on PnL/positions. ✔ (Task 4 Step 1)
-- [ ] `withBudget` is the single budget primitive used by both `backtestAsync` and `LlmSignal`. ✔
-- [ ] `LlmSignal` reuses the same no-lookahead proxy idea as engine `strict` mode. ✔
-- [ ] Live engine still accepts plain sync signals (await of non-Promise is a no-op). ✔ (Task 6)