@christtrade/depth 0.12.24 → 0.12.26

package/types/core/strategy-stream.d.ts

@@ -0,0 +1,40 @@
+export type ChunkPlan = {
+    fromNs: bigint;
+    toNs: bigint;
+};
+/** `coveredTo`: how far the source actually got - adapters cap responses and report the cap here, not as an error. */
+export type RangeFetchResult<B> = {
+    bars: B[];
+    coveredTo: bigint | null;
+};
+export type RangeFetch<B> = (opts: {
+    fromNs: bigint;
+    toNs: bigint;
+    barNs: bigint;
+}) => Promise<RangeFetchResult<B>>;
+export declare const DEFAULT_STREAM_DEPTH = 4;
+export declare const DEFAULT_MAX_CONTINUATIONS = 16;
+/**
+ * Chunk boundaries decided up front, not lazily - a request has to fire before
+ * its predecessor answers. `chunkBars` is bars in a chunk, not the width: a
+ * hundred-bar chunk spans ninety-nine periods, ends inclusive.
+ */
+export declare function planChunks(fromNs: bigint, toNs: bigint, barNs: bigint, chunkBars: bigint, maxChunks: number): ChunkPlan[];
+export type StreamOptions<B> = {
+    plan: readonly ChunkPlan[];
+    barNs: bigint;
+    fetch: RangeFetch<B>;
+    /** Pieces, not whole chunks - a two-request chunk arrives as two calls rather than paying to join them. */
+    deliver: (bars: B[], chunkIndex: number) => void;
+    /** False once superseded - checked after every await so a stale walk's late chunks don't reach the new run. */
+    isAlive?: () => boolean;
+    onProgress?: (delivered: number, total: number) => void;
+    depth?: number;
+    maxContinuations?: number;
+};
+/**
+ * Rejects with the first failure *in plan order*, not time order - otherwise a
+ * later failure could skip the bars an earlier, still-outstanding chunk owns,
+ * and a run that quietly drops a year still produces a plausible equity curve.
+ */
+export declare function streamRangeChunks<B>(opts: StreamOptions<B>): Promise<number>;

package/types/core/strategy-sweep.d.ts

@@ -0,0 +1,75 @@
+import type { StrategyStats } from './strategy-runtime';
+/**
+ * One axis of a sweep: a parameter and the values to try for it.
+ *
+ * Explicit `values` for anything discrete (a boolean, a select, a handful of
+ * lengths worth testing). `from`/`to`/`step` for a numeric range, which is what
+ * a ParamDef with min/max/step already describes - so the UI can offer a sweep
+ * over a parameter without the author declaring anything extra.
+ */
+export type SweepAxis = {
+    param: string;
+    values: unknown[];
+} | {
+    param: string;
+    from: number;
+    to: number;
+    step: number;
+};
+export interface SweepSpec {
+    axes: SweepAxis[];
+    /**
+     * Fraction of the run held back from the end as out-of-sample, 0 to 0.9.
+     *
+     * Optional but strongly encouraged, and the reason it is here rather than in
+     * some later "advanced" feature: a sweep is a machine for overfitting. Report
+     * only the best in-sample result and you have found the parameters that best
+     * describe noise you already have. The out-of-sample column is what tells you
+     * whether you found anything at all.
+     */
+    oosFraction?: number;
+}
+/** What one point of the grid produced. */
+export interface SweepResult {
+    /** The parameter values this run used - only the swept ones. */
+    params: Record<string, unknown>;
+    /** Over the whole window. */
+    stats: StrategyStats;
+    /** The leading portion, when a split was requested. */
+    inSample?: StrategyStats;
+    /** The held-back tail. The number that actually means something. */
+    outOfSample?: StrategyStats;
+}
+export declare const MAX_SWEEP_BAR_ITERATIONS = 200000000;
+export declare const MAX_SWEEP_COMBOS = 20000;
+export declare function axisValues(axis: SweepAxis): unknown[];
+/**
+ * The cartesian product of every axis, as parameter patches.
+ *
+ * Ordered so the first axis varies slowest. That makes the result array read as
+ * rows of the first parameter when laid out as a grid, which is what a heatmap
+ * wants without having to sort anything.
+*/
+export declare function expandGrid(axes: SweepAxis[]): Array<Record<string, unknown>>;
+export interface SweepBudget {
+    combos: number;
+    bars: number;
+    iterations: number;
+    ok: boolean;
+    /** Populated when ok is false. Written for a user, not a log. */
+    reason?: string;
+}
+/** Whether a sweep is worth attempting here, and what to say when it is not. */
+export declare function checkSweepBudget(combos: number, bars: number): SweepBudget;
+/**
+ * Where to cut a run into in-sample and out-of-sample halves.
+ *
+ * The tail is held back, never the head: the point is to test on data that comes
+ * *after* what the parameters were chosen on, because that is the only ordering
+ * that resembles trading them.
+ *
+ * Returns null when there is no meaningful split - too few bars, or a fraction
+ * that would leave one side empty. A missing OOS column is honest; a two-bar one
+ * is worse than none.
+ */
+export declare function splitIndex(barCount: number, oosFraction: number | undefined): number | null;

package/types/core/strategy-walkforward.d.ts

@@ -0,0 +1,91 @@
+import type { StrategyStats } from './strategy-runtime';
+export interface WalkForwardSpec {
+    /** How many out-of-sample segments to test. */
+    windows: number;
+    /**
+     * In-sample length as a multiple of out-of-sample length.
+     *
+     * 3 or 4 is conventional: enough history to optimise on, tested against a
+     * meaningful stretch of what followed. At 1 the optimiser sees as much data
+     * as it is judged on, which makes every window statistically thin.
+     */
+    isMultiple: number;
+    /**
+     * Anchored keeps the in-sample start fixed and lets it grow; rolling slides
+     * a fixed-width window.
+     *
+     * Neither is correct in general. Anchored uses more data and assumes the
+     * distant past still applies; rolling adapts to regime change and forgets.
+     * Which one flatters a strategy is itself a finding.
+     */
+    anchored: boolean;
+}
+export interface WalkForwardWindow {
+    index: number;
+    /** Bar indices, half-open: [from, to). */
+    isFrom: number;
+    isTo: number;
+    oosFrom: number;
+    oosTo: number;
+}
+export interface WalkForwardWindowResult {
+    window: WalkForwardWindow;
+    /** What the optimiser chose on the in-sample segment. */
+    params: Record<string, unknown>;
+    inSample: StrategyStats;
+    outOfSample: StrategyStats;
+}
+export interface ParameterStability {
+    param: string;
+    /** The value chosen in each window, in order. */
+    values: number[];
+    distinct: number;
+    /**
+     * Standard deviation over the mean. Scale-free, so a period and a percentage
+     * are comparable.
+     *
+     * Under ~0.15 the windows broadly agree. Over ~0.5 they do not, and a single
+     * "optimal" value quoted from the full-history sweep is a coincidence.
+     */
+    coefficientOfVariation: number;
+}
+/**
+ * Divides a series into overlapping optimise/test windows.
+ *
+ * Anchored keeps every in-sample segment starting at bar zero instead.
+ *
+ * Returns an empty array when the series cannot support the schedule. Refusing
+ * is the honest answer - a walk-forward over 40-bar windows produces numbers
+ * that look like analysis and are noise.
+ */
+export declare function planWalkForward(barCount: number, spec: WalkForwardSpec): WalkForwardWindow[];
+/**
+ * How much of the optimised edge survived on unseen data.
+ *
+ * Per-bar instead of total - anchored windows differ in length and an
+ * unweighted ratio would let the longest in-sample segment dominate.
+ *
+ * 1.0 means out-of-sample matched in-sample. Below ~0.5 is the usual warning
+ * line. Negative means the optimised parameters lost money on what followed,
+ * which is the most useful result a backtest can give you.
+ *
+ * Returns 0 when in-sample made nothing - there is no ratio to a zero
+ * denominator, and reporting Infinity as "infinitely efficient" would be absurd.
+ */
+export declare function walkForwardEfficiency(results: WalkForwardWindowResult[]): number;
+/**
+ * Whether the optimiser kept choosing the same thing.
+ *
+ * Only numeric parameters - the spread of a boolean or a string across windows
+ * has no meaningful coefficient.
+ */
+export declare function parameterStability(results: WalkForwardWindowResult[]): ParameterStability[];
+/**
+ * Picks the best row of a scored grid.
+ *
+ * `higherIsBetter` is false for drawdown-like objectives. Rows whose metric is
+ * not finite are skipped rather than winning: a profit factor of Infinity means
+ * a run with no losing trade, which on a two-trade in-sample window is noise
+ * dressed as perfection.
+ */
+export declare function pickBest<T>(rows: T[], metric: (row: T) => number | undefined, higherIsBetter?: boolean): T | null;

package/types/hooks/useChartData.d.ts

@@ -126,6 +126,8 @@ export interface ChartDataResult {
     seekHorizon: (horizon: bigint, triggerResample?: boolean, hotPath?: boolean, 
     /** Explicit navigation: bring the view along instead of leaving it behind. */
     recenter?: boolean) => void;
+    /** Frames a span of time. Does not move the playhead - see 'chart:goto-range'. */
+    gotoRange: (fromNs: bigint, toNs?: bigint, padding?: number) => void;
     applyHorizon: (horizon: bigint, triggerResample?: boolean, hotPath?: boolean) => void;
     scheduleResample: () => void;
     runIndicatorWorker: (trades: SerialTrade[], barNs: bigint) => void;

package/types/hooks/useChartSubscriptions.d.ts

@@ -45,6 +45,7 @@ export interface UseChartSubscriptionsParams {
     setPluginChartTypes: (types: ChartTypePlugin[]) => void;
     setChartSettings: (updater: ChartSettings | ((prev: ChartSettings) => ChartSettings)) => void;
     resetView: () => void;
+    gotoRange: (fromNs: bigint, toNs?: bigint, padding?: number) => void;
     buildChartTypeActiveCtx: () => ChartTypeActiveContext;
     pushDrawParams: () => void;
     runIndicatorWorker: (trades: SerialTrade[], barNs: bigint) => void;

package/types/interfaces/plugins/IChartPlugin.d.ts

@@ -13,7 +13,7 @@ import type { SerialTrade, PriceHistory } from '../../lib/types';
 import type { FootprintBar } from '../../lib/types/footprint';
 import type { BracketAmendment } from '../../lib/types/trading-types';
 import type { PlaceOrderRequest } from '../../lib/matchingEngine';
-export type PluginType = 'indicator' | 'drawing' | 'chart-type' | 'data-source' | 'extension';
+export type PluginType = 'indicator' | 'drawing' | 'chart-type' | 'data-source' | 'extension' | 'strategy';
 export type Permission = 'data:read' | 'data:write' | 'eventbus:emit' | 'eventbus:intercept' | 'ui:pane' | 'ui:panel' | 'ui:toolbar' | 'ui:context-menu' | 'render:overlay' | 'render:shader' | 'drawing:register' | 'chart-type:register' | 'theme:register' | 'audio' | 'network' | 'storage' | 'intercept' | 'execution:read' | 'execution:write';
 export interface ToolbarItem {
     id: string;
@@ -163,6 +163,18 @@ export interface PluginContext {
     dataLevel: DataLevel;
     horizon: () => number;
     getData(): Readonly<PluginDataSnapshot>;
+    fetchRange(opts: {
+        /** Defaults to the focused symbol. */
+        symbol?: string;
+        fromNs: bigint;
+        toNs: bigint;
+        /** Bar period to fetch at. Defaults to the chart's current timeframe. */
+        barNs?: bigint;
+    }): Promise<{
+        bars: OhlcvBar[];
+        hasMore: boolean;
+        coveredTo: bigint | null;
+    }>;
     /**
      * The bar still being built at the playback horizon, or `null` before any
      * data has arrived.