@christtrade/depth 0.12.25 → 0.12.26

package/types/core/TypedEventBus.d.ts

@@ -95,7 +95,7 @@ export interface ChartEvents {
     'timeframe:change': {
         tf: Timeframe;
     };
-    /** Runtime entitlement change (see `chart.allowTimeframes`). The UI re-reads
+    /** Runtime entitlement change. The UI re-reads
      *  `features` so locks and gates reflect what is allowed now. */
     'features:change': void;
     'timeframe:add-failed': {
@@ -565,11 +565,66 @@ export interface ChartEvents {
          * ParamDef already carries min, max and step.
          */
         paramDefs: Record<string, unknown>;
+        /** Bars this run actually covered - not always what was asked for. `clipped` is false for a run over everything loaded. */
+        range: {
+            fromNs: bigint | null;
+            toNs: bigint | null;
+            bars: number;
+            totalBars: number;
+            clipped: boolean;
+            /** Span the loaded data covers, so a picker can bound itself. */
+            dataFromNs: bigint | null;
+            dataToNs: bigint | null;
+        };
     };
     'plugin:apply-params': {
         id: string;
         params: Record<string, unknown>;
     };
+    'plugin:strategy-range': {
+        id: string;
+        range: {
+            fromNs?: bigint;
+            toNs?: bigint;
+        } | null;
+        /**
+         * Fetch the span instead of clipping to what the chart holds. Opt-in -
+         * clipping is free and covers almost every range, fetching walks the
+         * network a chunk at a time. Requires `fromNs`; no streaming backwards
+         * from an open-ended start.
+         */
+        fetch?: boolean;
+    };
+    'plugin:strategy-run': {
+        id: string;
+        /** `null` clears any bound and runs over everything loaded; omitted keeps the stored bound. */
+        range?: {
+            fromNs?: bigint;
+            toNs?: bigint;
+        } | null;
+        /** As on 'plugin:strategy-range' - go get the span, don't clip. */
+        fetch?: boolean;
+    };
+    'plugin:strategy-mode': {
+        id: string;
+        manual: boolean;
+    };
+    'plugin:strategy-stale': {
+        id: string;
+        name: string;
+        /** Bars arrived since the last run, or 0. */
+        newBars: number;
+        /** Params edited since the last run. Empty when none. */
+        params: Record<string, unknown>;
+    };
+    'plugin:strategy-progress': {
+        id: string;
+        name: string;
+        phase: 'fetching' | 'running' | 'analysing' | 'done' | 'failed';
+        done: number;
+        total: number;
+        error?: string;
+    };
     'plugin:strategy-sweep': {
         id: string;
         grid: Array<Record<string, unknown>>;

package/types/core/index.d.ts

@@ -25,9 +25,11 @@ export type { ChartModelInit, ChartPluginRef, ChartPaneState } from './ChartMode
 export { DrawingStore } from './DrawingStore';
 export type { ChartPlugin, PluginType, Permission, PluginManifest, PluginContext, PluginDataSnapshot, DrawingPlugin, ChartTypePlugin, ChartTypeRenderContext, DataSourcePlugin, IndicatorPlugin, IndicatorRenderContext, } from '../interfaces/plugins';
 export { createScriptedPlugin } from './ScriptedPlugin';
-export { StrategyEngine, DEFAULT_STRATEGY_CONFIG } from './strategy-runtime';
+export { StrategyEngine, DEFAULT_STRATEGY_CONFIG, reconcileIntrabar } from './strategy-runtime';
 export { axisValues, checkSweepBudget, expandGrid, splitIndex, MAX_SWEEP_COMBOS, MAX_SWEEP_BAR_ITERATIONS, } from './strategy-sweep';
 export type { SweepAxis, SweepSpec, SweepResult, SweepBudget } from './strategy-sweep';
+export { clipRange, hasRange, emptyRangeReason } from './strategy-range';
+export type { StrategyRange, ClippedRange } from './strategy-range';
 export { planWalkForward, walkForwardEfficiency, parameterStability, pickBest, } from './strategy-walkforward';
 export type { WalkForwardSpec, WalkForwardWindow, WalkForwardWindowResult, ParameterStability, } from './strategy-walkforward';
 export type { BrokerApi, StrategyEquityPoint, ExitReason, OrderOpts, Side, StrategyBar, StrategyConfig, StrategyOrder, StrategyPosition, StrategyResult, StrategyStats, StrategyTrade, } from './strategy-runtime';

package/types/core/script-runtime.d.ts

@@ -2,8 +2,10 @@ import { STDLIB } from '../lib/indicator-stdlib';
 import { PluginType, DataLevel, Layout, ExitReason, SCRIPT_DSL } from './script-dsl';
 export { STDLIB, SCRIPT_DSL, PluginType, DataLevel, Layout, ExitReason };
 export type { OhlcvBar, DrawCommand } from '../lib/indicator-stdlib';
-export { StrategyEngine, DEFAULT_STRATEGY_CONFIG } from './strategy-runtime';
+export { StrategyEngine, DEFAULT_STRATEGY_CONFIG, reconcileIntrabar } from './strategy-runtime';
 export { axisValues, checkSweepBudget, expandGrid, splitIndex } from './strategy-sweep';
+export { clipRange, hasRange, emptyRangeReason } from './strategy-range';
+export type { StrategyRange, ClippedRange } from './strategy-range';
 export type { SweepAxis, SweepSpec, SweepResult, SweepBudget } from './strategy-sweep';
 export { planWalkForward, walkForwardEfficiency, parameterStability, pickBest, } from './strategy-walkforward';
 export type { WalkForwardSpec, WalkForwardWindow, WalkForwardWindowResult, ParameterStability, } from './strategy-walkforward';

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

@@ -0,0 +1,41 @@
+import type { StrategyBar } from './strategy-runtime';
+/** Inclusive both ends, nanoseconds. An omitted end means "as far as the data goes". */
+export interface StrategyRange {
+    fromNs?: bigint;
+    toNs?: bigint;
+}
+/** Where a range lands in a bar array, plus what it cost. */
+export interface ClippedRange {
+    /** First bar in range. */
+    from: number;
+    /** One past the last bar in range, so `bars.slice(from, to)` is the run. */
+    to: number;
+    /** How many bars the run will see. */
+    count: number;
+    /** How many bars were available before clipping. */
+    total: number;
+    /** Timestamps of the first and last bar actually in range. */
+    firstTs: bigint | null;
+    lastTs: bigint | null;
+    /** Span the whole data set covers, ignoring the range - lets a picker bound itself to what exists. */
+    dataFromNs: bigint | null;
+    dataToNs: bigint | null;
+}
+/**
+ * Resolve a range against a sorted bar array. `toNs` includes the bar that opens
+ * exactly on it. Binary search, not a filter - this runs once per sweep
+ * combination, and a linear scan over a million bars twenty thousand times
+ * turns a sweep into a hang.
+ *
+ * No warmup before `from`: feeding a run bars it isn't allowed to trade is how
+ * an out-of-sample window quietly stops being out of sample.
+ */
+export declare function clipRange(bars: readonly StrategyBar[], range?: StrategyRange): ClippedRange;
+/** True when the range asks for something, rather than being absent or empty. */
+export declare function hasRange(range?: StrategyRange): boolean;
+/**
+ * Why a clipped run has nothing to run over. Spelled out rather than an empty
+ * result, since a strategy with no trades and one given no bars look identical
+ * in a results panel, and only one of those is the user's fault.
+ */
+export declare function emptyRangeReason(clipped: ClippedRange, range?: StrategyRange): string;

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

@@ -28,13 +28,9 @@ export interface StrategyPosition {
     tp?: number;
     tag?: string;
     /**
-     * Best and worst price reached while this position has been open.
-     *
-     * Tracked from the bar the position opened, over that bar's full range. A
-     * market order fills at the open so the whole range is fair; a limit or stop
-     * filling mid-bar makes the entry bar's contribution an upper bound. Every
-     * later bar is exact. Worth knowing before reading MAE as gospel on
-     * one-bar trades.
+     * Best/worst price while open, from the entry bar's full range. Exact for
+     * a market fill; an upper bound for a limit/stop filling mid-bar - don't
+     * read MAE as gospel on a one-bar trade.
      */
     highWatermark: number;
     lowWatermark: number;
@@ -52,10 +48,9 @@ export interface StrategyPosition {
     /** Fills that have gone into this position. Checked against `pyramiding`. */
     entries: number;
     /**
-     * Commission already paid to open the quantity still held. Carried on the
-     * position so the trade log can report a round-trip fee: equity is charged
-     * at entry, but nothing is logged until the exit, and a trade whose pnl
-     * omitted the entry side would not sum to the equity curve.
+     * Commission already paid to open the quantity still held. Carried so the
+     * exit's trade record can report the round-trip fee - otherwise pnl
+     * wouldn't sum to the equity curve.
      */
     entryFees: number;
 }
@@ -84,6 +79,12 @@ export interface StrategyTrade {
     durationNs: bigint;
     tag?: string;
     reason: ExitReason;
+    /**
+     * Stop and target both sat inside the resolving bar, so which came first
+     * was assumed (stop wins) rather than observed. Intrabar data shrinks how
+     * often this happens but never zeroes it.
+     */
+    ambiguousExit?: boolean;
     /** Worst the price went against this position before it closed. */
     maeAbs: number;
     /** Best the price went in favour of it. */
@@ -197,16 +198,26 @@ export interface StrategyStats {
     totalFees: number;
     totalCommission: number;
     /**
-     * What slippage cost, in account currency.
-     *
-     * Not a separate deduction - slippage is already inside every fill price and
-     * so already inside netPnl. This reports what that was worth, so a strategy
-     * that only loses to slippage is distinguishable from one that is simply
-     * wrong. Subtracting it again would double-count it.
+     * What slippage cost, in account currency - already inside netPnl via the
+     * fill prices, reported here rather than deducted again.
      */
     totalSlippage: number;
     /** What the run would have made with no commission at all. */
     grossPnlBeforeCosts: number;
+    /** Chart bars whose fills were resolved against finer intrabar data. */
+    intrabarBars: number;
+    /**
+     * Bars given intrabar data that didn't reconcile with the aggregate and
+     * fell back to it. Non-zero means the finer feed has holes - the run is
+     * still valid, just not the run the intrabar toggle implies.
+     */
+    intrabarFallbacks: number;
+    /**
+     * Exits where stop and target shared a resolving bar and the stop was
+     * assumed first. Compare against `totalTrades` for how much of the result
+     * rests on that assumption.
+     */
+    ambiguousExits: number;
 }
 export interface StrategyConfig {
     initialCapital: number;
@@ -220,19 +231,15 @@ export interface StrategyConfig {
     /** How many entries may stack in the same direction. */
     pyramiding: number;
     /**
-     * Whether an opposite-side order flips an open position or merely closes it.
-     *
-     * True matches how most scripts read: sell() while long means "get out and go
-     * short". False means sell() can only ever flatten, and opening the other way
-     * takes a second, separate order.
+     * Whether an opposite-side order flips a position or just closes it. True
+     * matches how most scripts read: sell() while long means "get out and go
+     * short".
      */
     allowReverse: boolean;
     /**
-     * Smallest tradable quantity increment. Order sizes floor to it.
-     *
-     * 1 for a listed future, where a third of a contract does not exist; spot
-     * venues are the other case entirely, so this comes from the instrument
-     * rather than being assumed.
+     * Smallest tradable quantity increment; order sizes floor to it. 1 for a
+     * listed future, fractional for spot - comes from the instrument, not
+     * assumed.
      */
     qtyStep: number;
 }
@@ -253,6 +260,18 @@ export interface StrategyBar {
     close: number;
     volume: number;
 }
+/**
+ * Do these finer bars actually subdivide this one?
+ *
+ * A feed with a hole in it is worse than none at all - it'd resolve a stop
+ * against a range missing the second price actually traded through. Rejected
+ * whole rather than repaired, since fixing it would mean inventing the
+ * ordering inside the gap.
+ *
+ * @param tolerance Half a tick - two aggregation paths over the same trades
+ * agree to the tick, not the float.
+ */
+export declare function reconcileIntrabar(bar: StrategyBar, sub: readonly StrategyBar[] | undefined, tolerance: number): boolean;
 export interface OrderOpts {
     /** Place a limit instead of a market order. */
     limit?: number;
@@ -293,10 +312,33 @@ export declare class StrategyEngine {
     private closeRequested;
     private barNs;
     private slippagePaid;
+    private usedIntrabar;
+    private intrabarBars;
+    private intrabarFallbacks;
+    private ambiguousExits;
+    private pendingEquity;
+    private equityCount;
+    private firstTs;
+    private lastTs;
+    private lastEquity;
+    private prevEquity;
+    private maxDdAbs;
+    private maxDdPct;
+    private ulcerSum;
+    private retN;
+    private retMean;
+    private retM2;
+    private downSum;
+    private downCount;
+    private curvePhase;
+    private curveStride;
+    private lastFolded;
     constructor(cfg?: Partial<StrategyConfig>);
     setBarNs(ns: bigint): void;
-    beginBar(bar: StrategyBar, index: number): void;
+    beginBar(bar: StrategyBar, index: number, sub?: readonly StrategyBar[]): void;
     endBar(bar: StrategyBar): void;
+    private foldPending;
+    private keepInCurve;
     finish(lastBar: StrategyBar | undefined): void;
     get equity(): number;
     get result(): StrategyResult;
@@ -318,8 +360,6 @@ export declare class StrategyEngine {
     private runYears;
     private cagr;
     private sortino;
-    private barReturns;
-    private peakAt;
     private barsInPositionTotal;
     private sharpe;
 }

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/interfaces/plugins/IChartPlugin.d.ts

@@ -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.