tradelab 1.0.0 → 1.1.0

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

@@ -0,0 +1,535 @@
+# 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). ✔