backtest-audit-kit 0.1.0__py3-none-any.whl

auditkit/__init__.py

@@ -0,0 +1,16 @@
+"""auditkit — a tiny, dependency-free toolkit for auditing backtests.
+
+The toolkit answers one question: *is this strategy real, or did the backtest
+lie to you?*  It ships four independent checkers:
+
+* ``auditkit.checks.lookahead``   — AST-based look-ahead / future-function lint.
+* ``auditkit.checks.invariants``  — ledger invariants (equity identity, wd_cum, monotonic counters).
+* ``auditkit.checks.mutants``     — mutation testing: which bugs would your tests *not* catch?
+* ``auditkit.checks.fees``        — fee / funding / slippage accounting checks.
+
+Everything is pure standard library (Python 3.9+).  No pandas, no numpy,
+no network access.
+"""
+
+__version__ = "0.1.0"
+__all__ = ["checks"]

auditkit/checks/__init__.py

@@ -0,0 +1,5 @@
+"""Checkers bundled with auditkit."""
+
+from . import fees, invariants, lookahead, mutants
+
+__all__ = ["lookahead", "invariants", "mutants", "fees"]

auditkit/checks/fees.py

@@ -0,0 +1,184 @@
+"""Fee / funding / slippage accounting.
+
+Costs are where optimistic backtests hide.  Three failure modes dominate:
+
+* **one-sided fees** — the engine charges the entry fee but forgets the exit
+  (or vice-versa), so every trade is quietly cheaper than reality;
+* **funding charged once** — a perp position held for ``k`` bars should pay
+  funding ``k`` times, but the engine deducts a single period;
+* **double-counted slippage** — slippage is applied to both the raw fill *and*
+  the already-slippaged price, charging it twice per fill.
+
+Each trade is a ``dict``::
+
+    {
+      "id": "t1",
+      "entry_notional": 10_000.0,
+      "exit_notional": 10_000.0,   # optional, defaults to entry_notional
+      "holding_bars": 8,
+      "fee_paid": 10.0,            # total round-trip fee actually charged
+      "funding_paid": 8.0,         # total funding actually charged
+      "slippage_paid": 4.0,        # total slippage cost actually charged
+    }
+
+Rates are in **basis points** (1 bp = 0.01%).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional, Sequence
+
+__all__ = ["FeeIssue", "check_trades", "check_trade", "DEFAULT_RATES"]
+
+BPS = 10_000.0
+DEFAULT_RATES = {
+    "fee_bps": 5.0,            # per side (taker)
+    "funding_bps_per_bar": 1.0,
+    "slippage_bps": 2.0,       # per fill
+}
+REL_TOL = 0.05  # 5% tolerance on each estimate
+
+
+@dataclass(frozen=True)
+class FeeIssue:
+    rule: str
+    trade_id: object
+    message: str
+    expected: Optional[float] = None
+    actual: Optional[float] = None
+
+    def as_dict(self) -> dict:
+        return {
+            "rule": self.rule,
+            "trade_id": self.trade_id,
+            "message": self.message,
+            "expected": self.expected,
+            "actual": self.actual,
+        }
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        return f"[{self.rule}] trade={self.trade_id}: {self.message}"
+
+
+def _f(trade: dict, key: str, default: float = 0.0) -> float:
+    val = trade.get(key, default)
+    try:
+        return float(val)
+    except (TypeError, ValueError):
+        return default
+
+
+def _outside(actual: float, expected: float, rel_tol: float) -> Optional[str]:
+    """Return ``"low"``, ``"high"``, or ``None`` relative to ``expected``."""
+    if expected <= 0:
+        return "high" if actual > 1e-9 else None
+    ratio = actual / expected
+    if ratio < 1 - rel_tol:
+        return "low"
+    if ratio > 1 + rel_tol:
+        return "high"
+    return None
+
+
+def check_trade(
+    trade: dict,
+    fee_bps: float = DEFAULT_RATES["fee_bps"],
+    funding_bps_per_bar: float = DEFAULT_RATES["funding_bps_per_bar"],
+    slippage_bps: float = DEFAULT_RATES["slippage_bps"],
+    rel_tol: float = REL_TOL,
+) -> List[FeeIssue]:
+    issues: List[FeeIssue] = []
+    tid = trade.get("id", "?")
+    entry = _f(trade, "entry_notional")
+    exit_n = _f(trade, "exit_notional", entry) or entry
+    bars = int(_f(trade, "holding_bars", 1)) or 1
+
+    # --- round-trip fees (both sides) ------------------------------------- #
+    expected_fee = (entry + exit_n) * fee_bps / BPS
+    actual_fee = _f(trade, "fee_paid", float("nan"))
+    if actual_fee == actual_fee:  # not NaN -> provided
+        side = _outside(actual_fee, expected_fee, rel_tol)
+        if side == "low":
+            issues.append(
+                FeeIssue(
+                    "ONE_SIDED_FEE",
+                    tid,
+                    f"fee {actual_fee:.4f} < round-trip expectation "
+                    f"{expected_fee:.4f} (entry+exit) -- likely only one side charged",
+                    expected_fee,
+                    actual_fee,
+                )
+            )
+        elif side == "high":
+            issues.append(
+                FeeIssue(
+                    "FEE_OVERCHARGE",
+                    tid,
+                    f"fee {actual_fee:.4f} > round-trip expectation {expected_fee:.4f}",
+                    expected_fee,
+                    actual_fee,
+                )
+            )
+
+    # --- funding per bar -------------------------------------------------- #
+    expected_funding = entry * funding_bps_per_bar / BPS * bars
+    actual_funding = _f(trade, "funding_paid", float("nan"))
+    if actual_funding == actual_funding and bars > 1:
+        side = _outside(actual_funding, expected_funding, rel_tol)
+        if side == "low":
+            issues.append(
+                FeeIssue(
+                    "FUNDING_ONCE",
+                    tid,
+                    f"funding {actual_funding:.4f} for {bars} bars < "
+                    f"{expected_funding:.4f} -- charged once, not per bar",
+                    expected_funding,
+                    actual_funding,
+                )
+            )
+        elif side == "high":
+            issues.append(
+                FeeIssue(
+                    "FUNDING_OVERCHARGE",
+                    tid,
+                    f"funding {actual_funding:.4f} > {expected_funding:.4f} "
+                    f"for {bars} bars",
+                    expected_funding,
+                    actual_funding,
+                )
+            )
+
+    # --- slippage once per fill (round trip = two fills) ------------------ #
+    expected_slip = (entry + exit_n) * slippage_bps / BPS
+    actual_slip = _f(trade, "slippage_paid", float("nan"))
+    if actual_slip == actual_slip:
+        side = _outside(actual_slip, expected_slip, rel_tol)
+        if side == "high":
+            issues.append(
+                FeeIssue(
+                    "SLIPPAGE_MULTIPLE",
+                    tid,
+                    f"slippage {actual_slip:.4f} > one-pass expectation "
+                    f"{expected_slip:.4f} -- slippage looks double-counted",
+                    expected_slip,
+                    actual_slip,
+                )
+            )
+
+    return issues
+
+
+def check_trades(
+    trades: Sequence[dict],
+    fee_bps: float = DEFAULT_RATES["fee_bps"],
+    funding_bps_per_bar: float = DEFAULT_RATES["funding_bps_per_bar"],
+    slippage_bps: float = DEFAULT_RATES["slippage_bps"],
+    rel_tol: float = REL_TOL,
+) -> List[FeeIssue]:
+    out: List[FeeIssue] = []
+    for trade in trades:
+        out.extend(
+            check_trade(trade, fee_bps, funding_bps_per_bar, slippage_bps, rel_tol)
+        )
+    return out

auditkit/checks/invariants.py

@@ -0,0 +1,183 @@
+"""Ledger invariants.
+
+A backtest is an accounting system; accounting systems have invariants.  When a
+result looks impossible it is usually because one of these was violated
+somewhere in the loop, and the bug silently reshaped the equity curve.
+
+The checker consumes a ``ledger``: an ordered list of per-step ``dict`` records.
+Only the keys you provide are checked; the canonical ones are:
+
+===============  ==========================================================
+key              meaning
+===============  ==========================================================
+``step``/``bar`` optional step label (used in messages)
+``cap``          total equity (cash + market value of open positions)
+``cash``         free cash (excludes position value)
+``positions``    ``{symbol: market_value}``
+``wd``           amount withdrawn on this step (default ``0``)
+``wd_cum``       cumulative withdrawals to date
+``bust``         ``True`` if this step returned via the liquidation path
+``trades``       counter, must be non-decreasing (also ``n_events``, ``bars``,
+                 ``fills``)
+===============  ==========================================================
+
+Rules
+-----
+``EQUITY_IDENTITY``    ``cap == cash + sum(positions.values())`` within tolerance.
+``NEGATIVE_BALANCE``   ``cap`` / ``cash`` / ``equity`` never below zero.
+``NEGATIVE_POSITION``  no negative position values.
+``WD_MONOTONIC``       ``wd_cum`` is non-decreasing.
+``WD_ACCRUAL``         withdrawing ``wd`` must grow ``wd_cum`` by exactly ``wd``.
+``BUST_WD_CARRY``      the liquidation/bust path must *carry* ``wd_cum`` forward,
+                       not reset it (the bug that erased history in case 2/3).
+``COUNTER_MONOTONIC``  counters never decrease.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Iterable, List, Optional, Sequence
+
+__all__ = ["Violation", "check_ledger", "DEFAULT_COUNTERS", "DEFAULT_TOL"]
+
+DEFAULT_TOL = 1e-6
+DEFAULT_COUNTERS: Sequence[str] = ("trades", "n_events", "bars", "fills")
+_BALANCE_KEYS = ("cap", "cash", "equity")
+
+
+@dataclass(frozen=True)
+class Violation:
+    rule: str
+    step: object
+    message: str
+
+    def as_dict(self) -> dict:
+        return {"rule": self.rule, "step": self.step, "message": self.message}
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        return f"[{self.rule}] step={self.step}: {self.message}"
+
+
+def _num(rec: dict, key: str, default: float = 0.0) -> float:
+    val = rec.get(key, default)
+    if val is None:
+        return default
+    try:
+        return float(val)
+    except (TypeError, ValueError):
+        return default
+
+
+def _step(rec: dict, fallback: int) -> object:
+    return rec.get("step", rec.get("bar", fallback))
+
+
+def check_ledger(
+    ledger: Sequence[dict],
+    tol: float = DEFAULT_TOL,
+    counters: Iterable[str] = DEFAULT_COUNTERS,
+) -> List[Violation]:
+    """Run every invariant over ``ledger`` and return all violations found."""
+    violations: List[Violation] = []
+    counters = tuple(counters)
+    prev: Optional[dict] = None
+
+    for idx, rec in enumerate(ledger):
+        step = _step(rec, idx)
+
+        # --- equity identity -------------------------------------------- #
+        if "cap" in rec and "cash" in rec:
+            pos = rec.get("positions") or {}
+            pos_value = sum(_num({"v": v}, "v") for v in pos.values())
+            diff = _num(rec, "cap") - (_num(rec, "cash") + pos_value)
+            if abs(diff) > tol:
+                violations.append(
+                    Violation(
+                        "EQUITY_IDENTITY",
+                        step,
+                        f"cap={_num(rec, 'cap'):.6f} but cash+positions="
+                        f"{_num(rec, 'cash') + pos_value:.6f} (diff {diff:+.6f})",
+                    )
+                )
+
+        # --- non-negative balances -------------------------------------- #
+        for key in _BALANCE_KEYS:
+            if key in rec and _num(rec, key) < -tol:
+                violations.append(
+                    Violation("NEGATIVE_BALANCE", step, f"{key}={_num(rec, key):.6f} < 0")
+                )
+        for sym, val in (rec.get("positions") or {}).items():
+            if _num({"v": val}, "v") < -tol:
+                violations.append(
+                    Violation(
+                        "NEGATIVE_POSITION", step, f"position {sym}={val} < 0"
+                    )
+                )
+
+        if prev is not None:
+            # --- wd_cum ----------------------------------------------- #
+            if "wd_cum" in rec and "wd_cum" in prev:
+                wd_cum, prev_wd_cum = _num(rec, "wd_cum"), _num(prev, "wd_cum")
+                if wd_cum < prev_wd_cum - tol:
+                    violations.append(
+                        Violation(
+                            "WD_MONOTONIC",
+                            step,
+                            f"wd_cum decreased {prev_wd_cum:.6f} -> {wd_cum:.6f}",
+                        )
+                    )
+                wd = _num(rec, "wd", 0.0)
+                if wd > tol:
+                    grew = wd_cum - prev_wd_cum
+                    if abs(grew - wd) > tol:
+                        violations.append(
+                            Violation(
+                                "WD_ACCRUAL",
+                                step,
+                                f"withdrew {wd:.6f} but wd_cum grew {grew:+.6f}",
+                            )
+                        )
+
+            # --- bust must carry wd_cum ------------------------------- #
+            if rec.get("bust"):
+                if "wd_cum" in prev and _num(prev, "wd_cum") > tol:
+                    if "wd_cum" not in rec:
+                        violations.append(
+                            Violation(
+                                "BUST_WD_CARRY",
+                                step,
+                                "bust path returned cap without wd_cum "
+                                f"(prev wd_cum={_num(prev, 'wd_cum'):.6f})",
+                            )
+                        )
+                    elif _num(rec, "wd_cum") < _num(prev, "wd_cum") - tol:
+                        violations.append(
+                            Violation(
+                                "BUST_WD_CARRY",
+                                step,
+                                "bust path dropped wd_cum "
+                                f"{_num(prev, 'wd_cum'):.6f} -> {_num(rec, 'wd_cum'):.6f}",
+                            )
+                        )
+
+            # --- counters --------------------------------------------- #
+            for c in counters:
+                if c in rec and c in prev and _num(rec, c) < _num(prev, c) - tol:
+                    violations.append(
+                        Violation(
+                            "COUNTER_MONOTONIC",
+                            step,
+                            f"{c} decreased {_num(prev, c):g} -> {_num(rec, c):g}",
+                        )
+                    )
+
+        prev = rec
+
+    return violations
+
+
+def violations_by_rule(violations: Sequence[Violation]) -> Dict[str, int]:
+    out: Dict[str, int] = {}
+    for v in violations:
+        out[v.rule] = out.get(v.rule, 0) + 1
+    return out

auditkit/checks/lookahead.py

@@ -0,0 +1,252 @@
+"""Look-ahead / future-function detection.
+
+A *look-ahead* (a.k.a. future leak) is code that lets a strategy decision on
+bar ``i`` see information that only exists on bars ``i+1...``.  In a backtest
+this silently inflates results, and it is the single most common reason a
+"profitable" strategy dies in production.
+
+This module is a *heuristic linter*, not a proof engine.  It parses source with
+``ast`` and flags three shapes that are strongly correlated with future leaks:
+
+``NEGATIVE_SHIFT``
+    ``series.shift(-1)`` / ``pct_change(-1)`` / ``diff(-1)`` — pulls the next
+    value into the current row.  Positive shifts read the past and are fine.
+
+``FUTURE_SLICE`` / ``FUTURE_INDEX``
+    ``data[i + 1:]`` (open-ended future slice) or ``data[i + 1]`` (direct read
+    of the next bar), where the lower bound is an anchor plus a positive
+    constant.
+
+``FUTURE_WINDOW_LOOP``
+    ``for j in range(ei + 1, min(ei + 1 + TO, n)):`` — a forward window scan.
+    When such a loop is *nested inside* another bar loop it is the classic
+    "decide the exit on the entry bar" bug and is reported ``HIGH``.  A
+    stand-alone forward loop is reported ``MEDIUM`` for manual review, because
+    a correctly written simulation pass also walks forward (see note below).
+
+Design note / honest limitation
+-------------------------------
+Statics cannot tell a *simulation* pass from a *decision* leak.  The fixed
+version of case 1 avoids the ambiguity entirely by evaluating the exit **only
+on the current bar** while the backtest advances, so it produces zero findings.
+If you do keep a separate forward simulation pass, expect a ``MEDIUM`` finding;
+that is intentional and means "a human should confirm this pass cannot feed
+back into the entry decision".
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional, Sequence
+
+__all__ = [
+    "Finding",
+    "LookaheadDetector",
+    "detect",
+    "detect_file",
+    "format_findings",
+    "SEVERITY_ORDER",
+]
+
+SEVERITY_ORDER = {"LOW": 1, "MEDIUM": 2, "HIGH": 3}
+
+#: Methods that reach into the future when called with a negative argument.
+FUTURE_METHODS = frozenset({"shift", "pct_change", "diff"})
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One suspicious construct found in the source."""
+
+    rule: str
+    severity: str
+    lineno: int
+    message: str
+    snippet: str = ""
+
+    def as_dict(self) -> dict:
+        return {
+            "rule": self.rule,
+            "severity": self.severity,
+            "lineno": self.lineno,
+            "message": self.message,
+            "snippet": self.snippet,
+        }
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        return f"[{self.severity}] {self.rule} L{self.lineno}: {self.message}"
+
+
+# --------------------------------------------------------------------------- #
+# small AST helpers
+# --------------------------------------------------------------------------- #
+def _is_int_const(node: ast.AST) -> bool:
+    return (
+        isinstance(node, ast.Constant)
+        and isinstance(node.value, int)
+        and not isinstance(node.value, bool)
+    )
+
+
+def _is_positive_int(node: ast.AST) -> bool:
+    return _is_int_const(node) and node.value > 0  # type: ignore[attr-defined]
+
+
+def _is_negative_int(node: ast.AST) -> bool:
+    if _is_int_const(node) and node.value < 0:  # type: ignore[attr-defined]
+        return True
+    if isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.USub):
+        return _is_positive_int(node.operand)
+    return False
+
+
+def _adds_positive_int(node: ast.AST) -> bool:
+    """True iff ``node`` looks like ``<anchor> + k`` with ``k`` a positive int.
+
+    A bare constant is *not* a match, so ``range(1, n)`` stays clean.
+    """
+    if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Add):
+        return _is_positive_int(node.right) or _is_positive_int(node.left)
+    return False
+
+
+def _is_range_call(node: ast.AST) -> bool:
+    return (
+        isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Name)
+        and node.func.id == "range"
+    )
+
+
+def _call_name(node: ast.Call) -> Optional[str]:
+    fn = node.func
+    if isinstance(fn, ast.Attribute):
+        return fn.attr
+    if isinstance(fn, ast.Name):
+        return fn.id
+    return None
+
+
+# --------------------------------------------------------------------------- #
+# visitor
+# --------------------------------------------------------------------------- #
+class LookaheadDetector(ast.NodeVisitor):
+    """Walk a parsed module and collect :class:`Finding` objects."""
+
+    def __init__(self) -> None:
+        self.findings: List[Finding] = []
+        self._loop_depth = 0  # number of enclosing ``for ... in range(...)`` loops
+
+    # -- loops -------------------------------------------------------------- #
+    def visit_For(self, node: ast.For) -> None:  # noqa: N802 (ast API)
+        if _is_range_call(node.iter):
+            self._check_range(node, node.iter)  # type: ignore[arg-type]
+            self._loop_depth += 1
+            self.generic_visit(node)
+            self._loop_depth -= 1
+        else:
+            self.generic_visit(node)
+
+    def _check_range(self, loop: ast.For, call: ast.Call) -> None:
+        if len(call.args) < 2:
+            return
+        start = call.args[0]
+        if not _adds_positive_int(start):
+            return
+        severity = "HIGH" if self._loop_depth >= 1 else "MEDIUM"
+        target = _target_name(loop.target)
+        self.findings.append(
+            Finding(
+                rule="FUTURE_WINDOW_LOOP",
+                severity=severity,
+                lineno=loop.lineno,
+                message=(
+                    f"forward window scan `range({ast.unparse(start)}, ...)` over "
+                    f"`{target}` starts strictly after an anchor; "
+                    + (
+                        "nested inside another bar loop -> looks like the exit is "
+                        "decided on the entry bar"
+                        if severity == "HIGH"
+                        else "stand-alone forward pass -- confirm it cannot feed the entry decision"
+                    )
+                ),
+                snippet=ast.unparse(call),
+            )
+        )
+
+    # -- calls -------------------------------------------------------------- #
+    def visit_Call(self, node: ast.Call) -> None:  # noqa: N802
+        name = _call_name(node)
+        if name in FUTURE_METHODS and node.args and _is_negative_int(node.args[0]):
+            self.findings.append(
+                Finding(
+                    rule="NEGATIVE_SHIFT",
+                    severity="HIGH",
+                    lineno=node.lineno,
+                    message=(
+                        f"`{name}({ast.unparse(node.args[0])})` reads the future "
+                        "(positive lag reads the past)"
+                    ),
+                    snippet=ast.unparse(node),
+                )
+            )
+        self.generic_visit(node)
+
+    # -- indexing ----------------------------------------------------------- #
+    def visit_Subscript(self, node: ast.Subscript) -> None:  # noqa: N802
+        sl = node.slice
+        if isinstance(sl, ast.Slice):
+            if sl.lower is not None and _adds_positive_int(sl.lower):
+                self.findings.append(
+                    Finding(
+                        rule="FUTURE_SLICE",
+                        severity="HIGH" if self._loop_depth >= 1 else "MEDIUM",
+                        lineno=node.lineno,
+                        message=(
+                            "slice lower bound is an anchor plus a positive "
+                            "constant -> the slice reaches into the future"
+                        ),
+                        snippet=ast.unparse(node),
+                    )
+                )
+        elif _adds_positive_int(sl):
+            self.findings.append(
+                Finding(
+                    rule="FUTURE_INDEX",
+                    severity="MEDIUM",
+                    lineno=node.lineno,
+                    message="direct index of the next bar (anchor + positive constant)",
+                    snippet=ast.unparse(node),
+                )
+            )
+        self.generic_visit(node)
+
+
+def _target_name(target: ast.AST) -> str:
+    if isinstance(target, ast.Name):
+        return target.id
+    return ast.unparse(target)
+
+
+# --------------------------------------------------------------------------- #
+# public API
+# --------------------------------------------------------------------------- #
+def detect(source: str, filename: str = "<string>") -> List[Finding]:
+    """Return all findings for ``source``, sorted by line number."""
+    tree = ast.parse(source, filename=filename)
+    visitor = LookaheadDetector()
+    visitor.visit(tree)
+    return sorted(visitor.findings, key=lambda f: (f.lineno, f.rule))
+
+
+def detect_file(path: str | Path) -> List[Finding]:
+    p = Path(path)
+    return detect(p.read_text(encoding="utf-8"), filename=str(p))
+
+
+def format_findings(findings: Sequence[Finding]) -> str:
+    if not findings:
+        return "clean: no look-ahead patterns detected"
+    return "\n".join(str(f) for f in findings)

auditkit/checks/mutants.py

@@ -0,0 +1,317 @@
+"""Mutation testing: which bugs would your tests *not* catch?
+
+Your backtest engine has a test suite.  It passes.  That proves very little:
+tests pass on code that is wrong in a way the tests never probe.  Mutation
+testing measures that gap mechanically.
+
+For a target function we generate *mutants* — single, small, semantically real
+changes (flip a comparator, off-by-one a constant, swap non-commutative
+operands, delete a fee/commission term).  Each mutant is executed against your
+suite.  If the suite still passes, the mutant **survived** — that mutation is a
+coverage blind spot, and the same blind spot will happily hide a real bug.
+
+Public API
+----------
+``generate_mutants(source)`` -> ``list[Mutant]``
+``run_mutation_tests(source, test_suite)`` -> ``MutationResult``
+
+A ``test_suite`` is a callable ``(namespace: dict) -> None`` where
+``namespace`` is the module-level globals of the (mutated) target module.  It
+should raise (e.g. ``assert``) when the behaviour is wrong, and return quietly
+otherwise.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+from typing import Callable, Dict, Iterable, List, Optional, Tuple
+
+__all__ = [
+    "Mutant",
+    "MutationResult",
+    "generate_mutants",
+    "run_mutation_tests",
+    "DEFAULT_KINDS",
+    "COMPARE_FLIP",
+    "FEE_WORDS",
+]
+
+DEFAULT_KINDS = ("compare", "offbyone", "swap", "delete_fee")
+
+COMPARE_FLIP = {
+    ast.Lt: ast.LtE,
+    ast.LtE: ast.Lt,
+    ast.Gt: ast.GtE,
+    ast.GtE: ast.Gt,
+    ast.Eq: ast.NotEq,
+    ast.NotEq: ast.Eq,
+}
+
+#: Only non-commutative operators are worth swapping (``a+b == b+a``).
+SWAP_OPS = (ast.Sub, ast.Div)
+
+FEE_WORDS = ("fee", "commission", "funding", "slip", "borrow", "cost")
+
+TestSuite = Callable[[Dict[str, object]], None]
+
+
+@dataclass(frozen=True)
+class Mutant:
+    id: str
+    kind: str
+    description: str
+    source: str
+
+
+@dataclass
+class MutationResult:
+    total: int
+    killed: int
+    survived: List[Mutant]
+    score: float
+    details: List[Tuple[str, str, str]] = field(default_factory=list)
+
+    @property
+    def survivors(self) -> List[Mutant]:
+        return self.survived
+
+    def report(self) -> str:
+        lines = [
+            f"mutants generated : {self.total}",
+            f"killed            : {self.killed}",
+            f"survived          : {len(self.survived)}",
+            f"mutation score    : {self.score * 100:.1f}%",
+        ]
+        if self.survived:
+            lines.append("blind spots (surviving mutants):")
+            for m in self.survived:
+                lines.append(f"  - [{m.id}] {m.description}")
+        return "\n".join(lines)
+
+
+# --------------------------------------------------------------------------- #
+# source-level mutation
+# --------------------------------------------------------------------------- #
+def _walk_deterministic(tree: ast.AST) -> List[ast.AST]:
+    return list(ast.walk(tree))
+
+
+def _apply_nth(source: str, predicate, mutate, index: int) -> str:
+    """Re-parse ``source``, mutate the ``index``-th node matching ``predicate``."""
+    tree = ast.parse(source)
+    seen = 0
+    for node in _walk_deterministic(tree):
+        if predicate(node):
+            if seen == index:
+                mutate(node)
+                ast.fix_missing_locations(tree)
+                return ast.unparse(tree)
+            seen += 1
+    raise IndexError(f"no node #{index} matched predicate")
+
+
+def _compare_pred(node: ast.AST) -> bool:
+    return (
+        isinstance(node, ast.Compare)
+        and len(node.ops) == 1
+        and type(node.ops[0]) in COMPARE_FLIP
+    )
+
+
+def _offbyone_pred(node: ast.AST) -> bool:
+    return (
+        isinstance(node, ast.Constant)
+        and isinstance(node.value, int)
+        and not isinstance(node.value, bool)
+    )
+
+
+def _swap_pred(node: ast.AST) -> bool:
+    return isinstance(node, ast.BinOp) and isinstance(node.op, SWAP_OPS)
+
+
+def _stmt_has_fee_word(stmt: ast.stmt) -> bool:
+    for node in ast.walk(stmt):
+        name = None
+        if isinstance(node, ast.Name):
+            name = node.id
+        elif isinstance(node, ast.Attribute):
+            name = node.attr
+        if name and any(w in name.lower() for w in FEE_WORDS):
+            return True
+    return False
+
+
+def _fee_stmts(tree: ast.AST) -> List[ast.stmt]:
+    """Statements that directly live in a function/module body and mention a fee.
+
+    Entire function/class definitions are never candidates -- deleting a whole
+    function is not a realistic "forgot the fee" edit.
+    """
+    out: List[ast.stmt] = []
+    for node in _walk_deterministic(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Module)):
+            for stmt in node.body:
+                if isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                    continue
+                if _stmt_has_fee_word(stmt):
+                    out.append(stmt)
+    return out
+
+
+def _delete_nth_fee_stmt(source: str, index: int) -> str:
+    tree = ast.parse(source)
+    targets = _fee_stmts(tree)
+    if index >= len(targets):
+        raise IndexError("no such fee statement")
+    fingerprint = ast.unparse(targets[index])
+
+    class _Deleter(ast.NodeTransformer):
+        def __init__(self) -> None:
+            self.done = False
+
+        def generic_visit(self, node: ast.AST) -> ast.AST:
+            if not self.done:
+                for attr in ("body", "orelse", "finalbody"):
+                    body = getattr(node, attr, None)
+                    if isinstance(body, list):
+                        for i, stmt in enumerate(body):
+                            if isinstance(stmt, ast.stmt) and ast.unparse(stmt) == fingerprint:
+                                del body[i]
+                                self.done = True
+                                break
+            return super().generic_visit(node)
+
+    _Deleter().visit(tree)
+    ast.fix_missing_locations(tree)
+    return ast.unparse(tree)
+
+
+def generate_mutants(
+    source: str, kinds: Optional[Iterable[str]] = None
+) -> List[Mutant]:
+    """Generate first-order mutants for ``source``."""
+    kinds = tuple(kinds) if kinds is not None else DEFAULT_KINDS
+    kindset = set(kinds)
+    base = ast.parse(source)
+    mutants: List[Mutant] = []
+
+    if "compare" in kindset:
+        for i, node in enumerate(
+            [n for n in _walk_deterministic(base) if _compare_pred(n)]
+        ):
+            old, new = type(node.ops[0]), COMPARE_FLIP[type(node.ops[0])]
+            mid = f"cmp{i}"
+
+            def _mutate(n, old=old, new=new):
+                n.ops[0] = new()
+
+            mutants.append(
+                Mutant(
+                    mid,
+                    "compare",
+                    f"flip `{old.__name__}` -> `{new.__name__}` at L{node.lineno}",
+                    _apply_nth(source, _compare_pred, _mutate, i),
+                )
+            )
+
+    if "offbyone" in kindset:
+        for i, node in enumerate(
+            [n for n in _walk_deterministic(base) if _offbyone_pred(n)]
+        ):
+            for delta, tag in ((1, "up"), (-1, "down")):
+                mid = f"ob{tag}{i}"
+
+                def _mutate(n, delta=delta):
+                    n.value = n.value + delta
+
+                mutants.append(
+                    Mutant(
+                        mid,
+                        "offbyone",
+                        f"constant {node.value} -> {node.value + delta} at L{node.lineno}",
+                        _apply_nth(source, _offbyone_pred, _mutate, i),
+                    )
+                )
+
+    if "swap" in kindset:
+        for i, node in enumerate(
+            [n for n in _walk_deterministic(base) if _swap_pred(n)]
+        ):
+            mid = f"swap{i}"
+
+            def _mutate(n):
+                n.left, n.right = n.right, n.left
+
+            mutants.append(
+                Mutant(
+                    mid,
+                    "swap",
+                    f"swap operands of `{type(node.op).__name__}` at L{node.lineno}",
+                    _apply_nth(source, _swap_pred, _mutate, i),
+                )
+            )
+
+    if "delete_fee" in kindset:
+        for i, stmt in enumerate(_fee_stmts(base)):
+            mid = f"delfee{i}"
+            mutants.append(
+                Mutant(
+                    mid,
+                    "delete_fee",
+                    f"delete fee/cost statement `{ast.unparse(stmt)}` at L{stmt.lineno}",
+                    _delete_nth_fee_stmt(source, i),
+                )
+            )
+
+    # de-duplicate identical sources (e.g. equivalent flips)
+    seen: set = set()
+    unique: List[Mutant] = []
+    for m in mutants:
+        if m.source in seen:
+            continue
+        seen.add(m.source)
+        unique.append(m)
+    return unique
+
+
+# --------------------------------------------------------------------------- #
+# execution
+# --------------------------------------------------------------------------- #
+def run_mutation_tests(
+    source: str,
+    test_suite: TestSuite,
+    name: str = "target",
+    kinds: Optional[Iterable[str]] = None,
+) -> MutationResult:
+    """Run ``test_suite`` against every mutant of ``source``."""
+    mutants = generate_mutants(source, kinds)
+    survived: List[Mutant] = []
+    details: List[Tuple[str, str, str]] = []
+    killed = 0
+
+    for mutant in mutants:
+        try:
+            namespace: Dict[str, object] = {
+                "__name__": f"auditkit_mutant_{mutant.id}",
+                "__builtins__": __builtins__,
+            }
+            exec(compile(mutant.source, f"<{name}:{mutant.id}>", "exec"), namespace)
+        except Exception as exc:  # mutant does not even import -> killed
+            killed += 1
+            details.append((mutant.id, "killed", f"load failed: {exc!r}"))
+            continue
+
+        try:
+            test_suite(namespace)
+        except Exception as exc:
+            killed += 1
+            details.append((mutant.id, "killed", f"{type(exc).__name__}: {exc}"))
+        else:
+            survived.append(mutant)
+            details.append((mutant.id, "survived", mutant.description))
+
+    total = len(mutants)
+    score = killed / total if total else 1.0
+    return MutationResult(total, killed, survived, score, details)

backtest_audit_kit-0.1.0.dist-info/METADATA

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: backtest-audit-kit
+Version: 0.1.0
+Summary: Audit a backtest: look-ahead lint, ledger invariants, mutation coverage, cost checks. Pure standard library.
+Author: rytjy
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rytjy/backtest-audit-kit
+Project-URL: Repository, https://github.com/rytjy/backtest-audit-kit
+Keywords: backtesting,lookahead-bias,audit,trading,quant,mutation-testing,invariants,backtest-overfitting
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# backtest-audit-kit
+
+**"I verify whether your strategy is real — or whether the backtest lied to you."**
+
+A tiny, dependency-free toolkit that audits a backtest the way an accountant
+audits a ledger and a QA engineer audits a test suite. It does not sell you
+returns; it finds the four ways a backtest most often lies.
+
+> **回测审计 / 策略代码复核服务** — 一页说明与联系方式 → **[PORTFOLIO.md](PORTFOLIO.md)**
+> **Backtest audits · strategy-code review** — one-page overview → **[PORTFOLIO.md](PORTFOLIO.md)**
+
+---
+
+## English
+
+**What it is.** A pure standard-library (Python 3.9+) kit of four independent
+checkers for a trading backtest:
+
+| Checker | Question it answers |
+|---|---|
+| `checks/lookahead.py` | Does any decision on bar `i` see bars `i+1...`? (AST-based future-function lint) |
+| `checks/invariants.py` | Does the ledger obey accounting invariants? (equity identity, `wd_cum` carry, monotonic counters, non-negative balances) |
+| `checks/mutants.py` | Which bugs would your test suite *not* catch? (mutation testing; survivors = coverage blind spots) |
+| `checks/fees.py` | Are fees two-sided, funding charged per bar, and slippage counted once per fill? |
+
+**Who it is for.** Quant developers, prop-desk researchers, and anyone who has
+ever shipped a strategy that looked great in a notebook and died in
+production. If you are reviewing someone else's backtest — or your own — this
+gives you a checklist, reproduction scripts, and before/after numbers instead
+of opinions.
+
+**What I deliver.** ① A ranked findings list plus a runnable reproduction
+script for each problem. ② A minimal fix patch. ③ A before/after reconciliation
+of the headline numbers (win rate, net PnL, multiple, MDD, t-stat).
+
+**Sample cases** (full write-ups in `cases/`):
+
+1. **Look-ahead** — the exit scan ran on the entry bar, so every signal knew
+   its outcome. Fixed: 91 trades / 90.1% / **+$214.37** → 26 trades / 65.4% /
+   **-$0.12**; a tick-level re-run gives 27 trades / 66.7% / **+$0.37**. The
+   leak was worth **≈ $214** of imaginary PnL — the whole profit.
+2. **Withdrawal accounting** — the bust path dropped `wd_cum`, so any strategy
+   with withdrawals was systematically understated. Fixed: same 2024–26 config
+   **7.82x → 215.27x** (a ≈ 27x gap; withdrawal rules "double-keep-half" vs
+   "double-keep-100" differ by ~27x).
+3. **Drawdown metric** — the circuit-breaker reset the running peak, so the
+   "reported MDD" was only the local drawdown. Investor-view raw drawdown
+   **99.7%** vs reported **53.1%** — a **46 pp** gap. Conclusion: MDD must be
+   written twice (breaker-local *and* raw).
+   (*Bonus case 4:* 5-minute bar clustering inflated `n` ~11x and turned
+   t = 15.60 into t = 1.75 after a 24h cooldown.)
+4. **Cost omission** (`cases/case5_cost_omission.md`) — a high-turnover 50x
+   book charged **no** fee, funding or slippage; its take-profit needed only a
+   **+0.08%** move while one round trip costs **0.09%** (the venue's real 4.5 bps
+   taker), so the target sat below the toll and every win is a net loss. At the
+   venue rate the omitted cost ran **~5.4x the starting capital** and **~17.8x the
+   reported profit**.
+
+**Install.**
+
+```bash
+pip install backtest-audit-kit
+```
+
+**Use it in code** (four checkers, pure standard library):
+
+```python
+from auditkit.checks import lookahead
+findings = lookahead.detect_file("strategy.py")   # future-data lint
+print(lookahead.format_findings(findings))
+```
+
+**How to run.**
+
+```bash
+cd portfolio/backtest-audit-kit
+python3 -m unittest discover tests      # stdlib only, no install
+# or, if you have pytest:
+python3 -m pytest tests/ -q
+python3 examples/run_demo.py            # see all four checkers in action
+```
+
+**Honesty note.** The look-ahead checker is a heuristic linter, not a proof
+engine: it flags the *shapes* that leak, and a stand-alone forward-simulation
+pass is reported `MEDIUM` for human review rather than being declared safe.
+Mutation testing reports blind spots; it never claims your strategy is
+profitable. No checker here predicts returns.
+
+---
+
+## 中文
+
+**是什么。** 一个纯 Python 标准库（3.9+）实现的回测审计工具包，四个互相独立
+的检查器：
+
+| 检查器 | 回答的问题 |
+|---|---|
+| `checks/lookahead.py` | 在 bar `i` 上的决策，是否读到了 `i+1...` 的数据？（基于 AST 的前视/未来函数检测） |
+| `checks/invariants.py` | 账本是否满足会计不变量？（权益恒等式、`wd_cum` 结转、计数器单调、余额非负） |
+| `checks/mutants.py` | 你的测试套件**抓不到**哪些 bug？（变异测试；存活的变异体 = 覆盖盲区） |
+| `checks/fees.py` | 手续费是否双边计、资金费是否逐 bar 计、滑点是否每笔只算一次？ |
+
+**给谁用。** 量化开发者、自营研究岗、以及任何"回测很美、实盘就死"过的
+人。带看别人的回测（或自己的）时，它给你的是**问题清单 + 复现脚本 + 修复前后
+的数字**，而不是一句"我觉得不太行"。
+
+**交付物承诺。** ① 按严重度排序的问题清单，每个问题配一个可运行的复现脚本。
+② 最小修复补丁。③ 修复前后的对账数字（胜率 / 净利 / 倍数 / 回撤 / t 值）。
+
+**案例摘要**（完整写在 `cases/`）：
+
+1. **前视 bug** —— 出场扫描写在开仓 bar 的循环内，每个信号都提前知道结果。
+   修复后：91 笔 / 90.1% / **+$214.37** → 26 笔 / 65.4% / **-$0.12**；tick 级
+   复跑得 27 笔 / 66.7% / **+$0.37**。这个泄漏值 **约 $214 的虚假收益**，
+   即全部利润。
+2. **提现会计 bug** —— 爆仓返程丢了 `wd_cum`，导致所有带提现的策略历史收益被
+   系统性低估。修复后：同一配置 2024–26 **7.82x → 215.27x**（相差约 27 倍；
+   提现规则"翻 2 留 1"与"翻 200 留 100"之间也差约 27 倍）。
+3. **回撤口径 bug** —— 熔断触发时把 peak 重置为 cap，"报告 MDD"只是每段熔断
+   后的局部回撤。投资者口径的原始回撤 **99.7%** vs 报告 **53.1%**，**差 46
+   个百分点**。结论：MDD 必须双写（熔断口径 + 原始口径）。
+   （**附赠案例 4**：一段暴跌连打十几根 5min bar 让样本量虚增约 11 倍，t 值从
+   15.60 在 24h 冷却去重后掉到 1.75。）
+4. **成本漏算**（`cases/case5_cost_omission.md`）—— 一个高换手 50x 账本**完全没算**手续费/资金费/滑点；止盈只需价格动 **+0.08%**，而一趟往返 **0.09%**（场馆真实 4.5bps taker）⇒ 目标在成本之下，每笔赢单净亏。按场馆真实费率，漏掉的成本约 **5.4× 本金**、**17.8× 账面收益**。
+
+**怎么跑。**
+
+```bash
+cd portfolio/backtest-audit-kit
+python3 -m unittest discover tests      # 只用标准库，无需安装
+# 若装了 pytest：
+python3 -m pytest tests/ -q
+python3 examples/run_demo.py            # 四个检查器全跑一遍
+```
+
+**诚实声明。** 前视检查器是启发式 linter，不是证明器：它抓的是会泄漏的**代码
+形态**，独立的"向前模拟"循环会被标为 `MEDIUM` 交人工复核，而不是被判安全。
+变异测试只报告覆盖盲区，从不声称你的策略赚钱。本工具包不预测任何收益。
+
+---
+
+## Also in this account · 另见
+
+- [`outpost/`](./outpost/) — 一个"只放能跑、能查、能被否证的东西"的据点：
+  单文件表格整理工具（零依赖、离线自检 14 项）+ 一份**被自己推翻**的回测（做空山寨无 edge）
+  + 一次"两条腿都断了"的数据源修复。不写客户名、不写"我能做什么"。

backtest_audit_kit-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+auditkit/__init__.py,sha256=Z13wkb6SMQZBgqtx_wRTKEm-vWuMZ_M8vDFWZ5edVK0,708
+auditkit/checks/__init__.py,sha256=AZigLxdMbxcwLCZmJKrVODEgzHR6nQvfVbjyPm_vRV0,148
+auditkit/checks/fees.py,sha256=hiOJoFg0BLxWwe54KlwnuruV5WaK1Q8UwNhx5c5EI_s,6261
+auditkit/checks/invariants.py,sha256=FdDooxn0yVhgtalNYYdc9lzqq5hHKRPPP0AM1-dTz4I,7204
+auditkit/checks/lookahead.py,sha256=mwFrP5x6vjsbN5hsczaSelZ4BDXKsJdIgIivPBj0OrQ,9185
+auditkit/checks/mutants.py,sha256=eh3rKrEI0Cb3439VB9x5O26tnvnqReAMz-5Z-dabfLI,10188
+backtest_audit_kit-0.1.0.dist-info/licenses/LICENSE,sha256=rOsDuKcMp6cQ1ShvEiEmEMh_QK-tTgFdHBTB5bEIqYY,1062
+backtest_audit_kit-0.1.0.dist-info/METADATA,sha256=VTc3pyWGqedT-bOZU3KeMA49hhFYXWrSh1PDPgMkMZc,8550
+backtest_audit_kit-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+backtest_audit_kit-0.1.0.dist-info/top_level.txt,sha256=kQBTO9qJ9E8TUvF_DHOn19QTe_3B8AcCxlLR-TzBKx8,9
+backtest_audit_kit-0.1.0.dist-info/RECORD,,

backtest_audit_kit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

backtest_audit_kit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rytjy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

backtest_audit_kit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+auditkit