tradelab 1.1.0 → 1.2.0

package/docs/superpowers/plans/2026-07-funding-carry-costs.md

@@ -1,535 +0,0 @@
-# Funding, Borrow & Overnight Carry Costs 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:** Model the time-based costs the current engine ignores — overnight financing/borrow (annualized carry) and perpetual-futures funding — so leveraged longs and shorts don't show phantom edge.
-
-**Architecture:** Per-fill costs (slippage/spread/commission) already live in `applyFill`. Carry is _time_-based, not fill-based, so add a pure `financingCost({ side, notional, fromMs, toMs, costs })` to `execution.js` and deduct it inside each engine's leg-close accounting (`backtest.js`, `barSystemRunner.js`, `backtestTicks.js`). Each closed leg pays carry on its own quantity for its own hold duration. Config lives under `costs.carry` (annualized bps) and `costs.funding` (per-interval bps).
-
-**Tech Stack:** Node ESM, `node:test`. No new dependencies.
-
----
-
-### Task 1: `financingCost` + funding-event counting
-
-**Files:**
-
-- Modify: `src/engine/execution.js`
-- Test: `test/engine/financing.test.js`
-
-- [ ] **Step 1: Write the failing test**
-
-```js
-// test/engine/financing.test.js
-import test from "node:test";
-import assert from "node:assert/strict";
-import { financingCost, fundingEvents } from "../../src/engine/execution.js";
-
-const YEAR = 365 * 24 * 60 * 60 * 1000;
-
-test("carry: a long held one year at 5% annual on 10k notional costs 500", () => {
-  const cost = financingCost({
-    side: "long",
-    notional: 10_000,
-    fromMs: 0,
-    toMs: YEAR,
-    costs: { carry: { longAnnualBps: 500, shortAnnualBps: 800 } },
-  });
-  assert.ok(Math.abs(cost - 500) < 1e-6);
-});
-
-test("carry: a short uses shortAnnualBps", () => {
-  const cost = financingCost({
-    side: "short",
-    notional: 10_000,
-    fromMs: 0,
-    toMs: YEAR / 2,
-    costs: { carry: { longAnnualBps: 500, shortAnnualBps: 800 } },
-  });
-  assert.ok(Math.abs(cost - 400) < 1e-6); // 8% * 0.5yr * 10k
-});
-
-test("fundingEvents counts boundaries strictly after from and up to to", () => {
-  const h8 = 8 * 60 * 60 * 1000;
-  // anchor 0, interval 8h: boundaries at 8h,16h,24h within (0, 24h] => 3
-  assert.equal(fundingEvents(0, 24 * 60 * 60 * 1000, h8, 0), 3);
-  assert.equal(fundingEvents(0, h8 - 1, h8, 0), 0);
-  assert.equal(fundingEvents(h8, 24 * 60 * 60 * 1000, h8, 0), 2);
-});
-
-test("funding: a long pays when rate is positive, a short receives", () => {
-  const h8 = 8 * 60 * 60 * 1000;
-  const base = { funding: { rateBps: 10, intervalMs: h8, anchorMs: 0 } };
-  const longCost = financingCost({
-    side: "long",
-    notional: 10_000,
-    fromMs: 0,
-    toMs: 24 * 60 * 60 * 1000,
-    costs: base,
-  });
-  const shortCost = financingCost({
-    side: "short",
-    notional: 10_000,
-    fromMs: 0,
-    toMs: 24 * 60 * 60 * 1000,
-    costs: base,
-  });
-  assert.ok(Math.abs(longCost - 30) < 1e-6); // 3 events * 10bps * 10k = 30
-  assert.ok(Math.abs(shortCost + 30) < 1e-6); // short receives funding
-});
-
-test("no carry/funding config => zero cost", () => {
-  assert.equal(
-    financingCost({ side: "long", notional: 10_000, fromMs: 0, toMs: YEAR, costs: {} }),
-    0
-  );
-  assert.equal(
-    financingCost({ side: "long", notional: 10_000, fromMs: 0, toMs: YEAR, costs: null }),
-    0
-  );
-});
-```
-
-- [ ] **Step 2: Run to verify it fails**
-
-Run: `node --test test/engine/financing.test.js`
-Expected: FAIL — `financingCost`/`fundingEvents` not exported.
-
-- [ ] **Step 3: Add to src/engine/execution.js**
-
-Append to `src/engine/execution.js`:
-
-```js
-const MS_PER_YEAR = 365 * 24 * 60 * 60 * 1000;
-
-/**
- * Count funding boundaries in the half-open interval (fromMs, toMs], given a
- * funding `intervalMs` cadence anchored at `anchorMs`.
- */
-export function fundingEvents(fromMs, toMs, intervalMs, anchorMs = 0) {
-  if (!(intervalMs > 0) || toMs <= fromMs) return 0;
-  const firstK = Math.floor((fromMs - anchorMs) / intervalMs) + 1;
-  const lastK = Math.floor((toMs - anchorMs) / intervalMs);
-  return Math.max(0, lastK - firstK + 1);
-}
-
-/**
- * Time-based financing cost for holding `notional` from `fromMs` to `toMs`.
- * Positive return = cost to the position (subtract from PnL).
- *
- * costs.carry  = { longAnnualBps, shortAnnualBps }  annualized borrow/margin
- * costs.funding = { rateBps, intervalMs, anchorMs } perp funding per interval;
- *                 longs pay when rateBps > 0, shorts receive (and vice versa).
- */
-export function financingCost({ side, notional, fromMs, toMs, costs }) {
-  const model = costs || {};
-  const absNotional = Math.abs(notional);
-  let cost = 0;
-
-  if (model.carry) {
-    const annualBps =
-      side === "long" ? (model.carry.longAnnualBps ?? 0) : (model.carry.shortAnnualBps ?? 0);
-    const years = Math.max(0, toMs - fromMs) / MS_PER_YEAR;
-    cost += absNotional * (annualBps / 10000) * years;
-  }
-
-  const funding = model.funding;
-  if (funding && funding.intervalMs > 0 && Number.isFinite(funding.rateBps)) {
-    const count = fundingEvents(fromMs, toMs, funding.intervalMs, funding.anchorMs ?? 0);
-    const perEvent = absNotional * (funding.rateBps / 10000);
-    cost += (side === "long" ? 1 : -1) * perEvent * count;
-  }
-
-  return cost;
-}
-```
-
-- [ ] **Step 4: Run to verify it passes**
-
-Run: `node --test test/engine/financing.test.js`
-Expected: PASS (5 tests).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/engine/execution.js test/engine/financing.test.js
-git commit -m "feat: add financingCost (carry + funding) helper
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-### Task 2: Deduct financing in the candle engine
-
-**Files:**
-
-- Modify: `src/engine/backtest.js`
-- Test: `test/financingIntegration.test.js`
-
-- [ ] **Step 1: Write the failing test**
-
-```js
-// test/financingIntegration.test.js
-import test from "node:test";
-import assert from "node:assert/strict";
-import { backtest } from "../src/index.js";
-
-// Daily candles, flat price so gross PnL is ~0; carry should make the long lose.
-function flatCandles(n = 30) {
-  const start = Date.UTC(2025, 0, 2, 14, 30, 0);
-  return Array.from({ length: n }, (_, i) => ({
-    time: start + i * 86_400_000,
-    open: 100,
-    high: 100.5,
-    low: 99.5,
-    close: 100,
-    volume: 1000,
-  }));
-}
-
-test("overnight carry reduces a long's realized PnL vs no-carry", () => {
-  const candles = flatCandles();
-  const opts = {
-    candles,
-    interval: "1d",
-    warmupBars: 1,
-    flattenAtClose: false,
-    scaleOutAtR: 0,
-    signal({ index, bar, openPosition }) {
-      if (openPosition || index !== 1) return null;
-      return { side: "long", entry: bar.close, stop: bar.close - 2, rr: 50, _maxBarsInTrade: 20 };
-    },
-  };
-  const noCarry = backtest(opts);
-  const withCarry = backtest({
-    ...opts,
-    costs: { carry: { longAnnualBps: 1000, shortAnnualBps: 1000 } },
-  });
-  assert.ok(withCarry.metrics.totalPnL < noCarry.metrics.totalPnL);
-  // the closed leg records its financing
-  const leg = withCarry.positions[0];
-  assert.ok(leg.exit.financing > 0);
-});
-```
-
-- [ ] **Step 2: Run to verify it fails**
-
-Run: `node --test test/financingIntegration.test.js`
-Expected: FAIL — PnL unchanged (financing not deducted) and `leg.exit.financing`
-is undefined.
-
-- [ ] **Step 3: Import financingCost in backtest.js**
-
-In `src/engine/backtest.js`, the existing import from `./execution.js` lists
-`applyFill, clampStop, ...`. Add `financingCost` to that import list:
-
-```js
-import {
-  applyFill,
-  clampStop,
-  touchedLimit,
-  ocoExitCheck,
-  isEODBar,
-  roundStep,
-  estimateBarMs,
-  dayKeyUTC,
-  dayKeyET,
-  financingCost,
-} from "./execution.js";
-```
-
-- [ ] **Step 4: Deduct financing inside closeLeg**
-
-In `backtest.js`'s `closeLeg`, find:
-
-```js
-const grossPnl = (exitPx - entryFill) * direction * qty;
-const entryFeePortion = (openPos.entryFeeTotal || 0) * (qty / openPos.initSize);
-const pnl = grossPnl - entryFeePortion - exitFeeTotal;
-```
-
-Replace with:
-
-```js
-const grossPnl = (exitPx - entryFill) * direction * qty;
-const entryFeePortion = (openPos.entryFeeTotal || 0) * (qty / openPos.initSize);
-const financing = financingCost({
-  side: openPos.side,
-  notional: entryFill * qty,
-  fromMs: openPos.openTime,
-  toMs: time,
-  costs,
-});
-const pnl = grossPnl - entryFeePortion - exitFeeTotal - financing;
-```
-
-- [ ] **Step 5: Record financing on the leg**
-
-In the same `closeLeg`, find the `record` object's `exit` block:
-
-```js
-      exit: {
-        price: exitPx,
-        time,
-        reason,
-        pnl,
-        exitATR: openPos._lastATR ?? undefined,
-      },
-```
-
-Replace with:
-
-```js
-      exit: {
-        price: exitPx,
-        time,
-        reason,
-        pnl,
-        financing,
-        exitATR: openPos._lastATR ?? undefined,
-      },
-```
-
-- [ ] **Step 6: Run test + suite**
-
-Run: `node --test test/financingIntegration.test.js`
-Expected: PASS.
-
-Run: `node --test`
-Expected: PASS — default `costs` (no carry/funding) yields `financing === 0`, so
-all existing tests are unaffected.
-
-- [ ] **Step 7: Commit**
-
-```bash
-git add src/engine/backtest.js test/financingIntegration.test.js
-git commit -m "feat: deduct overnight/funding carry in candle backtest
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-### Task 3: Same deduction in portfolio runner + tick engine
-
-**Files:**
-
-- Modify: `src/engine/barSystemRunner.js`
-- Modify: `src/engine/backtestTicks.js`
-- Test: `test/financingIntegration.test.js` (append portfolio + tick cases)
-
-- [ ] **Step 1: Append the failing tests**
-
-```js
-// append to test/financingIntegration.test.js
-import { backtestPortfolio, backtestTicks } from "../src/index.js";
-
-test("portfolio runner deducts carry", () => {
-  const start = Date.UTC(2025, 0, 2, 14, 30, 0);
-  const candles = Array.from({ length: 30 }, (_, i) => ({
-    time: start + i * 86_400_000,
-    open: 100,
-    high: 100.5,
-    low: 99.5,
-    close: 100,
-    volume: 1000,
-  }));
-  const signal = ({ index, bar, openPosition }) =>
-    !openPosition && index === 1
-      ? { side: "long", entry: bar.close, stop: bar.close - 2, rr: 50, _maxBarsInTrade: 20 }
-      : null;
-  const base = { equity: 10_000, systems: [{ symbol: "X", candles, signal }] };
-  const noCarry = backtestPortfolio({ ...base });
-  const withCarry = backtestPortfolio({
-    equity: 10_000,
-    costs: { carry: { longAnnualBps: 1000, shortAnnualBps: 1000 } },
-    systems: [
-      {
-        symbol: "X",
-        candles,
-        signal,
-        costs: { carry: { longAnnualBps: 1000, shortAnnualBps: 1000 } },
-      },
-    ],
-  });
-  assert.ok(withCarry.metrics.totalPnL <= noCarry.metrics.totalPnL);
-});
-
-test("tick engine deducts carry", () => {
-  const start = Date.UTC(2025, 0, 2, 14, 30, 0);
-  const ticks = Array.from({ length: 500 }, (_, i) => ({
-    time: start + i * 60_000,
-    bid: 100,
-    ask: 100.02,
-  }));
-  const signal = ({ index, bar, openPosition }) =>
-    !openPosition && index === 1
-      ? { side: "long", entry: bar.close, stop: bar.close - 0.5, rr: 100 }
-      : null;
-  const withCarry = backtestTicks({
-    ticks,
-    signal,
-    costs: { carry: { longAnnualBps: 5000, shortAnnualBps: 5000 } },
-  });
-  assert.equal(typeof withCarry.metrics.totalPnL, "number");
-  if (withCarry.positions.length) assert.ok(withCarry.positions[0].exit.financing >= 0);
-});
-```
-
-Note: `backtestPortfolio` must thread `system.costs` into each runner's options.
-Verify it already does (the runner reads `this.options.costs`). If portfolio does
-not forward per-system `costs`, add that mapping where it constructs each
-`BarSystemRunner`.
-
-- [ ] **Step 2: Run to verify it fails**
-
-Run: `node --test test/financingIntegration.test.js`
-Expected: FAIL — `financing` not deducted in runner/tick engines.
-
-- [ ] **Step 3: Edit barSystemRunner.js closeLeg**
-
-Add `financingCost` to the `./execution.js` import list in
-`src/engine/barSystemRunner.js`, then in its `closeLeg` find:
-
-```js
-const grossPnl = (exitPx - entryFill) * direction * qty;
-const entryFeePortion = (openPos.entryFeeTotal || 0) * (qty / openPos.initSize);
-const pnl = grossPnl - entryFeePortion - exitFeeTotal;
-```
-
-Replace with:
-
-```js
-const grossPnl = (exitPx - entryFill) * direction * qty;
-const entryFeePortion = (openPos.entryFeeTotal || 0) * (qty / openPos.initSize);
-const financing = financingCost({
-  side: openPos.side,
-  notional: entryFill * qty,
-  fromMs: openPos.openTime,
-  toMs: time,
-  costs: this.options.costs,
-});
-const pnl = grossPnl - entryFeePortion - exitFeeTotal - financing;
-```
-
-And add `financing,` to that method's `record.exit` object (same edit shape as
-Task 2 Step 5).
-
-- [ ] **Step 4: Edit backtestTicks.js closePosition**
-
-Add `financingCost` to the `./execution.js` import in `src/engine/backtestTicks.js`,
-then in `closePosition` find:
-
-```js
-const grossPnl = (price - open.entryFill) * direction * open.size;
-const pnl = grossPnl - (open.entryFeeTotal || 0) - feeTotal;
-```
-
-Replace with:
-
-```js
-const grossPnl = (price - open.entryFill) * direction * open.size;
-const financing = financingCost({
-  side: open.side,
-  notional: open.entryFill * open.size,
-  fromMs: open.openTime,
-  toMs: tick.time,
-  costs,
-});
-const pnl = grossPnl - (open.entryFeeTotal || 0) - feeTotal - financing;
-```
-
-Then in the `trade` object's `exit` block in the same function, add `financing,`:
-
-```js
-      exit: {
-        price,
-        time: tick.time,
-        reason,
-        pnl,
-        financing,
-      },
-```
-
-- [ ] **Step 5: Run test + full suite**
-
-Run: `node --test test/financingIntegration.test.js`
-Expected: PASS.
-
-Run: `node --test`
-Expected: PASS.
-
-- [ ] **Step 6: Lint + commit**
-
-```bash
-npm run lint
-git add src/engine/barSystemRunner.js src/engine/backtestTicks.js test/financingIntegration.test.js
-git commit -m "feat: deduct carry in portfolio and tick engines
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-### Task 4: Docs
-
-**Files:**
-
-- Modify: `docs/backtest-engine.md` and `README.md`
-
-- [ ] **Step 1: Document the cost-model additions**
-
-In the execution/cost-modeling section, add:
-
-````markdown
-### Financing & funding (time-based costs)
-
-In addition to per-fill slippage/spread/commission, the cost model can charge
-the cost of _holding_ a position:
-
-```js
-costs: {
-  carry: {
-    longAnnualBps: 600,   // margin/borrow on a long, annualized bps
-    shortAnnualBps: 300,  // borrow on a short, annualized bps
-  },
-  funding: {
-    rateBps: 1,                 // per-interval perp funding (bps of notional)
-    intervalMs: 8 * 60 * 60e3,  // 8h funding cadence
-    anchorMs: 0,                // funding timestamp alignment
-  },
-}
-```
-
-- **Carry** accrues continuously: `notional * (annualBps/10000) * yearsHeld`.
-- **Funding** charges at each interval boundary crossed while the position is
-  open. Longs pay when `rateBps > 0`; shorts receive (and vice versa).
-- Each closed leg pays carry on its own quantity for its own hold time, and the
-  amount is reported on `position.exit.financing`.
-````
-
-- [ ] **Step 2: Update the README costs note**
-
-Under "Execution and cost modeling", add a one-line mention of `costs.carry` and
-`costs.funding` for perps/shorts, pointing to the docs section above.
-
-- [ ] **Step 3: Format, test, commit**
-
-```bash
-npm run format:check && npm test
-git add docs/backtest-engine.md README.md
-git commit -m "docs: document carry and funding cost model
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-## Self-review checklist
-
-- [ ] Default behavior unchanged: with no `costs.carry`/`costs.funding`, `financingCost` returns 0 and every existing test stays green. ✔ (Task 1 Step 1 last case)
-- [ ] Carry charged per leg on the leg's own qty and hold window (correct under scale-outs). ✔ (Tasks 2, 3)
-- [ ] Funding sign is correct: long pays positive rate, short receives. ✔ (Task 1 Step 1)
-- [ ] `position.exit.financing` is surfaced in all three engines for transparency. ✔
-- [ ] Portfolio forwards per-system `costs` to each runner (verified in Task 3 Step 1 note). ✔