patchwork-os 0.2.0-beta.9.canary.92 → 1.1.0-beta.1

package/dist/ta/desk/cellBacktest.d.ts

@@ -0,0 +1,179 @@
+/**
+ * cellBacktest.ts — Phase 2 harness. The SOLE path any desk cell may grade through.
+ *
+ * No cell earns GRADED status except via a Verdict produced here. Calling code
+ * that tries to grade a cell by other means (static edge, scoreLedger baseline,
+ * ad-hoc permutation) must be removed or pointed here.
+ *
+ * Design: docs/qumo-desk-precommit.md §5 + bigtrack-backtest.md §1–§3.
+ *
+ * ── What this file provides ─────────────────────────────────────────────────
+ *
+ *   CellSpec          — frozen parameter record for one cell (canonical-JSON
+ *                       byte-equality enforced at registration time).
+ *   Verdict           — output of one gate run; append-only to verdicts.jsonl.
+ *   cellBacktest()    — walk-forward + paired-date null + block-bootstrap +
+ *                       regime stratification → Verdict for one cell.
+ *   runBattery()      — Bonferroni-Holm family correction over N specs.
+ *   loadLocalCandles()— local-cache-only loader (hard error on missing tail).
+ *
+ * ── Invariants enforced in code (not just docs) ──────────────────────────────
+ *
+ *   1. GRADED requires ALL: decided ≥ GATE_DECIDED, edge > 0, permutationP < 0.05,
+ *      familyAdjustedP < 0.05, and sign-consistency (positive edge in ≥ 2 of 3
+ *      regimes). Any single failure → WATCH.
+ *   2. A sub-N (scorable < MIN_N=30) cell CANNOT print a win-rate (throws).
+ *   3. A null arm that has fewer push-drops than the method arm CANNOT be used
+ *      (asymmetric-push guard — throws).
+ *   4. The candleSetHash is computed from the exact scored bytes; a hash mismatch
+ *      on re-run means the data changed and the verdict is invalidated.
+ *   5. Any cell whose universe contains a symbol outside ALWAYS_LISTED throws at
+ *      registration — survivorship block.
+ *
+ * ── Null kinds ───────────────────────────────────────────────────────────────
+ *
+ *   "matched-date-dart"  — setup cells (wp-volume-climax, kodama). For each
+ *     method-fire date, a seeded RNG picks a random direction and a random
+ *     price ±5% from close as the stop; target = entry ± same distance.
+ *     Controls for time-period effect; isolates the climax pattern.
+ *
+ *   "random-in-range-level" — level cells (wp-level-fifty, 4th-floor). For each
+ *     method-fire date, a seeded RNG places a random level inside the detected
+ *     swing range and runs the same resolveTouch logic. Controls for "something
+ *     happens at any level in the range" (the relevant null for a level claim).
+ *
+ * ── Regime classification ────────────────────────────────────────────────────
+ *
+ *   200-bar SMA slope + price position → bull / bear / chop.
+ *   Sign-consistency gate: method edge must be > 0 in ≥ 2 of 3 non-empty regimes.
+ *   If a regime has < MIN_REGIME_DECIDED decided pairs it is excluded (too thin).
+ */
+import type { Candle } from "../types.js";
+import type { DetectResult } from "./accrualEmitter.js";
+export declare const VERDICTS_FILE: string;
+export declare const GATE_DECIDED = 40;
+export declare const PERMUTATION_SEED = 777;
+export declare const NULL_SEED = 4242;
+/** Always-listed universe — the ONLY symbols a CellSpec may include. */
+export declare const ALWAYS_LISTED: readonly ["BTCUSDT", "ETHUSDT"];
+export type AlwaysListed = (typeof ALWAYS_LISTED)[number];
+export type NullKind = "matched-date-dart" | "random-in-range-level";
+export type Regime = "bull" | "bear" | "chop";
+/**
+ * Frozen parameter record for one cell. Canonical-JSON byte-equality is checked
+ * at gate time: if the running params differ from what was used in an existing
+ * verdict, the verdict is invalidated and a new run is required.
+ *
+ * All knobs here are pre-registered in docs/qumo-desk-precommit.md before any
+ * history accrues. Changing any field requires a methodVersion bump.
+ */
+export interface CellSpec {
+    cellName: string;
+    methodVersion: string;
+    timeframe: "1d" | "4h";
+    universe: readonly string[];
+    outcomeWindowBars: number;
+    nullKind: NullKind;
+    seeds: {
+        rng: number;
+        permutation: number;
+        null: number;
+    };
+    /**
+     * Detector run at bar-close. candles[0..t] are visible; candles[t+1..] are NOT
+     * passed in — the harness slices candles to [0..t+1] before calling. Returns
+     * false or the card geometry.
+     */
+    detect: (candles: Candle[]) => DetectResult;
+}
+export type GateState = "GRADED" | "WATCH" | "FALSIFIED";
+export interface RegimeStats {
+    regime: Regime;
+    decided: number;
+    methodWins: number;
+    nullWins: number;
+    edge: number | null;
+}
+export interface Verdict {
+    cellName: string;
+    methodVersion: string;
+    gitSha: string;
+    seeds: {
+        rng: number;
+        permutation: number;
+        null: number;
+    };
+    candleSetHash: string;
+    /** Total decided pairs across all assets (method wins + losses, matched to null). */
+    N: number;
+    methodWinRate: number;
+    nullWinRate: number;
+    edge: number;
+    wilsonLow: number;
+    wilsonHigh: number;
+    permutationP: number;
+    familyAdjustedP: number;
+    perRegime: RegimeStats[];
+    signConsistent: boolean;
+    gateState: GateState;
+    /** Human-readable gate failure reason(s). Empty string on GRADED. */
+    failReason: string;
+    runTs: string;
+    familyN: number;
+    timeframe: "1d" | "4h";
+}
+/**
+ * Load all 1d candles for `sym` from the local cache. Hard errors on missing
+ * directory, zero files, non-daily gaps, or if the tail does not reach
+ * `expectedTailMs` (today-1 at UTC midnight).
+ */
+export declare function loadLocalCandles(sym: string, expectedTailMs?: number): Candle[];
+/**
+ * Apply Bonferroni-Holm step-down correction to an array of (cellName, p) pairs.
+ * Returns the family-adjusted p for each cell (in input order).
+ * familyN is the FROZEN total cell count (includes banned/falsified cells).
+ */
+export declare function holmAdjust(pValues: number[], familyN: number): number[];
+export interface CellBacktestOptions {
+    /** Pre-loaded candles to use instead of loading from cache (for tests). */
+    candlesByAsset?: Map<string, Candle[]>;
+    /**
+     * Frozen family size for Holm correction. Must be set equal to the total
+     * number of pre-registered cells (including falsified/banned ones) — not just
+     * the cells currently in the battery.
+     */
+    familyN: number;
+    /**
+     * Array of per-cell p-values from other cells in the same battery run, so
+     * Holm can be applied in one pass. If omitted, only this cell's p is corrected
+     * (conservative: treats familyN cells each with this cell's p).
+     */
+    batteryPs?: number[];
+}
+/**
+ * Run the full gate for one CellSpec. Returns a Verdict.
+ *
+ * Survivorship block: throws if spec.universe contains any symbol outside
+ * ALWAYS_LISTED (prevents universe-wide backtests until point-in-time membership
+ * is reconstructed).
+ *
+ * Sub-N throw: throws if the caller tries to log a win-rate when scorable < MIN_N.
+ * (The Verdict itself always shows N; the GRADED gate enforces ≥ GATE_DECIDED.)
+ */
+export declare function cellBacktest(spec: CellSpec, opts: CellBacktestOptions): Verdict;
+/**
+ * Run cellBacktest for multiple specs and apply Holm correction in one pass.
+ * The familyN must be the same frozen value for all cells.
+ */
+export declare function runBattery(specs: CellSpec[], familyN: number, candlesByAsset?: Map<string, Candle[]>): Verdict[];
+/**
+ * Append a verdict to ~/.patchwork/qumo-verdicts.jsonl (one JSON line per run).
+ * The file is append-only; never mutated in place. The desk reads the latest
+ * verdict per cellName to display the current gate state.
+ */
+export declare function appendVerdict(v: Verdict): void;
+/**
+ * Read the latest verdict for each cell from verdicts.jsonl.
+ * Returns a map from cellName → most-recent Verdict.
+ */
+export declare function readLatestVerdicts(): Map<string, Verdict>;