@alphafox/cli 0.3.13 → 0.3.14

package/dist/engine-backtest/result-attribution.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attributeEngineBacktestResult = attributeEngineBacktestResult;
+function attributeEngineBacktestResult(input) {
+    const bySymbol = new Map();
+    const ensure = (symbol) => {
+        const existing = bySymbol.get(symbol);
+        if (existing)
+            return existing;
+        const created = {
+            symbol,
+            realizedPnl: 0,
+            liquidationRealizedPnl: 0,
+            unrealizedPnl: 0,
+            feesPaid: 0,
+            orderCount: 0,
+            filledOrderCount: 0,
+            canceledOrderCount: 0,
+            tradeCount: 0,
+            winningTrades: 0,
+            losingTrades: 0,
+        };
+        bySymbol.set(symbol, created);
+        return created;
+    };
+    input.symbols?.forEach(ensure);
+    const book = new Map();
+    const orders = input.result.orders
+        .map((order, index) => ({ order, index }))
+        .sort((left, right) => {
+        const byTimestamp = Date.parse(left.order.timestamp) - Date.parse(right.order.timestamp);
+        if (byTimestamp !== 0)
+            return byTimestamp;
+        return left.index - right.index;
+    })
+        .map((entry) => entry.order);
+    for (const order of orders) {
+        const attribution = ensure(order.symbol);
+        attribution.orderCount++;
+        if (isCanceled(order.status)) {
+            attribution.canceledOrderCount++;
+            continue;
+        }
+        if (!(order.filledQuantity > 0))
+            continue;
+        attribution.filledOrderCount++;
+        attribution.feesPaid += finiteOrZero(order.fee);
+        const reduction = applyFill(book, order, contractSizeFor(input.markets[order.symbol]));
+        if (reduction === null)
+            continue;
+        attribution.tradeCount++;
+        attribution.realizedPnl += reduction.realizedPnl;
+        if (isLiquidationOrder(order)) {
+            attribution.liquidationRealizedPnl += reduction.realizedPnl;
+        }
+        if (reduction.realizedPnl > 0)
+            attribution.winningTrades++;
+        else if (reduction.realizedPnl < 0)
+            attribution.losingTrades++;
+    }
+    for (const position of input.result.openPositions) {
+        ensure(position.symbol).unrealizedPnl += finiteOrZero(position.unrealizedPnl);
+    }
+    const symbols = [...bySymbol.values()].map((value) => {
+        const netPnl = value.realizedPnl + value.unrealizedPnl - value.feesPaid;
+        return {
+            ...value,
+            netPnl,
+            winRatePct: value.tradeCount > 0
+                ? (value.winningTrades / value.tradeCount) * 100
+                : 0,
+        };
+    });
+    const attributedNetPnl = symbols.reduce((total, symbol) => total + symbol.netPnl, 0);
+    const accountAdjustmentPnl = (input.result.accountAdjustments ?? []).reduce((total, adjustment) => total + finiteOrZero(adjustment.amount), 0);
+    const residualPnl = input.result.metrics.netPnl - attributedNetPnl - accountAdjustmentPnl;
+    const reconciliationTolerance = Math.max(0.01, Math.abs(input.result.metrics.netPnl) * 1e-6);
+    return {
+        symbols,
+        attributedNetPnl,
+        accountAdjustmentPnl,
+        residualPnl,
+        reconciliationTolerance,
+        reconciled: Math.abs(residualPnl) <= reconciliationTolerance,
+    };
+}
+function applyFill(book, order, contractSize) {
+    const side = normalizeOrderSide(order.side);
+    if (!side)
+        return null;
+    const positionSide = resolveAttributionPositionSide({
+        positionSide: order.positionSide,
+        reduceOnly: order.reduceOnly,
+        side,
+    });
+    const isReduce = order.reduceOnly ||
+        (positionSide === "long" && side === "sell") ||
+        (positionSide === "short" && side === "buy");
+    const key = `${order.symbol}\u0000${positionSide}`;
+    const quantity = order.filledQuantity * contractSize;
+    const position = book.get(key);
+    if (!isReduce) {
+        if (!position) {
+            book.set(key, { quantity, entryPrice: order.price });
+            return null;
+        }
+        const total = position.quantity + quantity;
+        if (total > 0) {
+            position.entryPrice =
+                (position.entryPrice * position.quantity + order.price * quantity) /
+                    total;
+        }
+        position.quantity = total;
+        return null;
+    }
+    if (!position || position.quantity <= 0)
+        return null;
+    const closed = Math.min(quantity, position.quantity);
+    const realized = positionSide === "short"
+        ? (position.entryPrice - order.price) * closed
+        : (order.price - position.entryPrice) * closed;
+    position.quantity -= closed;
+    if (position.quantity <= 1e-12)
+        book.delete(key);
+    return { realizedPnl: realized };
+}
+function isLiquidationOrder(order) {
+    if (order.executionReason === "liquidation")
+        return true;
+    return order.message?.trim().toLowerCase() === "liquidation";
+}
+function resolveAttributionPositionSide(input) {
+    const explicit = input.positionSide?.trim().toLowerCase();
+    if (explicit === "long" || explicit === "short")
+        return explicit;
+    if (input.reduceOnly)
+        return input.side === "sell" ? "long" : "short";
+    return input.side === "buy" ? "long" : "short";
+}
+function normalizeOrderSide(value) {
+    const normalized = value.trim().toLowerCase();
+    return normalized === "buy" || normalized === "sell" ? normalized : null;
+}
+function isCanceled(status) {
+    const normalized = status.toLowerCase();
+    return normalized === "canceled" || normalized === "cancelled";
+}
+function contractSizeFor(market) {
+    if (!market || typeof market !== "object")
+        return 1;
+    const size = market.contractSize;
+    return typeof size === "number" && size > 0 ? size : 1;
+}
+function finiteOrZero(value) {
+    return Number.isFinite(value) ? value : 0;
+}

package/dist/engine-backtest/run-command.js

@@ -11,11 +11,13 @@ const client_1 = require("../http/client");
 const store_1 = require("../keychain/store");
 const coverage_notice_1 = require("./coverage-notice");
 const errors_1 = require("./errors");
+const dca_first_order_amount_compat_1 = require("./dca-first-order-amount-compat");
 const load_config_1 = require("./load-config");
 const parse_args_1 = require("./parse-args");
 const sweep_command_1 = require("./sweep-command");
 const persist_1 = require("./persist");
 const paths_1 = require("../cache/paths");
+const prepared_tape_1 = require("./prepared-tape");
 const replay_timeframe_1 = require("./replay-timeframe");
 const resolve_packages_1 = require("./resolve-packages");
 var load_config_2 = require("./load-config");
@@ -193,10 +195,10 @@ async function executeEngineBacktestRun(args, flags, env = process.env, deps = {
     if (needsApi) {
         requireAuth(profile, env, tokensFn);
     }
-    const config = (0, load_config_1.loadConfigValue)(args.configRaw, {
+    const config = (0, dca_first_order_amount_compat_1.projectDcaFirstOrderAmountForLegacyRuntime)((0, load_config_1.loadEngineBacktestConfig)(args.configRaw, {
         cwd: deps.cwd,
         readFile: deps.readFile,
-    });
+    }));
     let experimentId = args.experimentId;
     if (!experimentId && !createExperiment) {
         throw new errors_1.EngineBacktestError({
@@ -319,6 +321,7 @@ async function executeEngineBacktestRun(args, flags, env = process.env, deps = {
                 toMs: args.range.toMs,
                 dataQualityMode: args.dataQualityMode,
                 cacheDir: (0, paths_1.resolveTapeCacheDir)(env),
+                seriesConcurrency: prepared_tape_1.ENGINE_BACKTEST_TAPE_SERIES_CONCURRENCY,
                 onProgress: (progress) => {
                     emitProgress(flags, writeLine, progress.stage || "tape", progress.fraction, progress.detail);
                 },
@@ -350,22 +353,24 @@ async function executeEngineBacktestRun(args, flags, env = process.env, deps = {
             runId,
             definitionId: args.definitionId,
             configSchemaVersion,
-            config: plan.effectiveConfig ?? config,
+            config: (0, dca_first_order_amount_compat_1.projectDcaFirstOrderAmountForLegacyRuntime)(plan.effectiveConfig ?? config),
             subscriptionTier,
             initialEquity: args.initialEquity,
             tape: tapeResult.tape,
             executionModel,
         });
-        const result = await client.runBacktest(scenario, tapeResult.buffers, (fraction) => {
-            emitProgress(flags, writeLine, "wasm", fraction);
-        });
-        if (result.status === "failed") {
-            throw new errors_1.EngineBacktestError({
-                type: "runtime",
-                subtype: "backtest_failed",
-                message: "runBacktest returned status=failed",
-                details: { errors: result.errors, runId: result.runId },
-            });
+        const prepared = await (0, prepared_tape_1.prepareWorkerTape)(client, tapeResult.tape, tapeResult.buffers);
+        let result;
+        try {
+            result = (0, prepared_tape_1.requireCompletedPreparedRun)(await client.runPreparedBacktest(prepared.handle, scenario, (fraction) => {
+                emitProgress(flags, writeLine, "wasm", fraction);
+            }));
+        }
+        catch (error) {
+            throw (0, prepared_tape_1.mapPreparedTapeError)(error);
+        }
+        finally {
+            await (0, prepared_tape_1.releaseWorkerTape)(client, prepared.handle);
         }
         const engineVersion = result.engineVersion?.trim() ||
             (typeof client.version === "function" ? (await client.version()).trim() : "") ||
@@ -406,6 +411,9 @@ async function executeEngineBacktestRun(args, flags, env = process.env, deps = {
                 engineVersion,
                 equityCurve: result.equityCurve,
                 coverageIssues: tapeResult.coverageIssues,
+                orders: result.orders,
+                openPositions: result.openPositions,
+                accountAdjustments: result.accountAdjustments,
             });
             const res = await postJson(api, profile, env, runsPath(experimentId), body, mintId);
             persistedRunId = extractEntityId(res.json);

package/dist/engine-backtest/sweep-command.d.ts

@@ -1,6 +1,6 @@
 import type { EngineBacktestCliFlags, EngineBacktestRunDeps } from "./run-command";
 import type { EngineBacktestSweepArgs, EngineBacktestSweepSuccess } from "./types";
-/** WASM `runBacktestBatch` hard limit. Keep in sync with Engine. */
+/** WASM prepared-batch variant hard limit. Keep in sync with Engine. */
 export declare const MAX_ENGINE_BACKTEST_BATCH_VARIANTS = 256;
 /** Sweep chunk size: below the 256 cap so JSONL can refresh mid-search. */
 export declare const SWEEP_WASM_BATCH_VARIANTS = 32;
@@ -8,6 +8,6 @@ export interface EngineBacktestSweepDeps extends EngineBacktestRunDeps {
     readonly maxVariantsPerBatch?: number;
     readonly now?: () => number;
 }
-export declare function cloneTapeBuffers(sourceBuffers: Readonly<Record<string, ArrayBuffer>>): Record<string, ArrayBuffer>;
+export { cloneTapeBuffers } from "./prepared-tape";
 export declare function splitBatchChunk<T>(chunk: readonly T[], maxVariants?: number): T[][];
 export declare function executeEngineBacktestSweep(args: EngineBacktestSweepArgs, flags: EngineBacktestCliFlags, env?: NodeJS.ProcessEnv, deps?: EngineBacktestSweepDeps): Promise<EngineBacktestSweepSuccess>;

package/dist/engine-backtest/sweep-command.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SWEEP_WASM_BATCH_VARIANTS = exports.MAX_ENGINE_BACKTEST_BATCH_VARIANTS = void 0;
-exports.cloneTapeBuffers = cloneTapeBuffers;
+exports.cloneTapeBuffers = exports.SWEEP_WASM_BATCH_VARIANTS = exports.MAX_ENGINE_BACKTEST_BATCH_VARIANTS = void 0;
 exports.splitBatchChunk = splitBatchChunk;
 exports.executeEngineBacktestSweep = executeEngineBacktestSweep;
 const node_crypto_1 = require("node:crypto");
@@ -11,13 +10,15 @@ const paths_1 = require("../cache/paths");
 const store_1 = require("../keychain/store");
 const coverage_notice_1 = require("./coverage-notice");
 const errors_1 = require("./errors");
+const dca_first_order_amount_compat_1 = require("./dca-first-order-amount-compat");
 const load_config_1 = require("./load-config");
 const parse_axes_1 = require("./parse-axes");
 const persist_1 = require("./persist");
+const prepared_tape_1 = require("./prepared-tape");
 const replay_timeframe_1 = require("./replay-timeframe");
 const resolve_packages_1 = require("./resolve-packages");
 const sweep_kernel_1 = require("./sweep-kernel");
-/** WASM `runBacktestBatch` hard limit. Keep in sync with Engine. */
+/** WASM prepared-batch variant hard limit. Keep in sync with Engine. */
 exports.MAX_ENGINE_BACKTEST_BATCH_VARIANTS = 256;
 /** Sweep chunk size: below the 256 cap so JSONL can refresh mid-search. */
 exports.SWEEP_WASM_BATCH_VARIANTS = 32;
@@ -28,9 +29,8 @@ const SUBSCRIPTION_TIERS = new Set([
     "pro",
     "pro_max",
 ]);
-function cloneTapeBuffers(sourceBuffers) {
-    return Object.fromEntries(Object.entries(sourceBuffers).map(([key, buffer]) => [key, buffer.slice(0)]));
-}
+var prepared_tape_2 = require("./prepared-tape");
+Object.defineProperty(exports, "cloneTapeBuffers", { enumerable: true, get: function () { return prepared_tape_2.cloneTapeBuffers; } });
 function splitBatchChunk(chunk, maxVariants = exports.MAX_ENGINE_BACKTEST_BATCH_VARIANTS) {
     const limit = Math.max(1, Math.floor(maxVariants));
     if (chunk.length <= limit)
@@ -72,7 +72,7 @@ async function executeEngineBacktestSweep(args, flags, env = process.env, deps =
     if (persist) {
         requireAuth(profile, env, tokensFn);
     }
-    const config = asConfigRecord((0, load_config_1.loadConfigValue)(args.configRaw, {
+    const config = asConfigRecord((0, load_config_1.loadEngineBacktestConfig)(args.configRaw, {
         cwd: deps.cwd,
         readFile: deps.readFile,
     }));
@@ -193,6 +193,7 @@ async function executeEngineBacktestSweep(args, flags, env = process.env, deps =
                     toMs: args.range.toMs,
                     dataQualityMode: args.dataQualityMode,
                     cacheDir: (0, paths_1.resolveTapeCacheDir)(env),
+                    seriesConcurrency: prepared_tape_1.ENGINE_BACKTEST_TAPE_SERIES_CONCURRENCY,
                     onProgress: (progress) => {
                         emitProgress(flags, writeLine, progress.stage || "tape", progress.fraction, progress.detail);
                     },
@@ -584,7 +585,7 @@ async function resolveConfigSchemaVersion(client, definitionId, explicit) {
     return version;
 }
 async function planCoordinate(input) {
-    const nextConfig = (0, sweep_kernel_1.applySweepCoordinate)(input.config, input.axes, input.coordinate);
+    const nextConfig = asConfigRecord((0, dca_first_order_amount_compat_1.projectDcaFirstOrderAmountForLegacyRuntime)((0, sweep_kernel_1.applySweepCoordinate)(input.config, input.axes, input.coordinate)));
     try {
         const plan = await input.client.planBacktest({
             definitionId: input.definitionId,
@@ -619,6 +620,52 @@ async function planCoordinate(input) {
         };
     }
 }
+async function runPreparedWorkerBatches(args) {
+    for (const subChunk of splitBatchChunk(args.chunk, args.input.maxVariantsPerBatch)) {
+        const scenarios = subChunk.map((item) => args.input.runner.assembleScenario({
+            runId: args.input.mintId(),
+            definitionId: args.input.definitionId,
+            configSchemaVersion: args.input.configSchemaVersion,
+            config: item.item.config,
+            subscriptionTier: args.input.subscriptionTier,
+            initialEquity: args.input.initialEquity,
+            tape: args.input.tape,
+            executionModel: args.input.executionModel,
+        }));
+        const first = scenarios[0];
+        if (!first)
+            continue;
+        const { tape: _tape, ...baseScenario } = first;
+        const batch = {
+            version: 1,
+            batchId: args.input.mintId(),
+            baseScenario,
+            variants: scenarios.map((scenario) => ({
+                runId: scenario.runId,
+                config: scenario.trader.config,
+            })),
+            tape: args.input.tape,
+        };
+        const result = await args.client.runPreparedBacktestBatch(args.handle, batch);
+        (0, prepared_tape_1.throwIfPreparedTapeErrors)(result.errors, result);
+        if (result.results.length !== subChunk.length) {
+            throw new errors_1.EngineBacktestError({
+                type: "runtime",
+                subtype: "batch_result_count",
+                message: "runPreparedBacktestBatch returned an unexpected result count",
+                details: {
+                    expected: subChunk.length,
+                    actual: result.results.length,
+                },
+            });
+        }
+        subChunk.forEach((entry, index) => {
+            args.completed[entry.index] = readBatchPoint(entry.item.coordinate, result.results[index]);
+        });
+        const finished = args.completed.filter((point) => point !== undefined);
+        args.input.onProgress(finished.length, finished);
+    }
+}
 async function executeSweepBatches(input) {
     if (input.ready.length === 0) {
         return [];
@@ -630,49 +677,21 @@ async function executeSweepBatches(input) {
     });
     await Promise.all(chunks.map(async (chunk, workerIndex) => {
         const client = workers[workerIndex];
-        for (const subChunk of splitBatchChunk(chunk, input.maxVariantsPerBatch)) {
-            const scenarios = subChunk.map((item) => input.runner.assembleScenario({
-                runId: input.mintId(),
-                definitionId: input.definitionId,
-                configSchemaVersion: input.configSchemaVersion,
-                config: item.item.config,
-                subscriptionTier: input.subscriptionTier,
-                initialEquity: input.initialEquity,
-                tape: input.tape,
-                executionModel: input.executionModel,
-            }));
-            const first = scenarios[0];
-            if (!first)
-                continue;
-            const { tape: _tape, ...baseScenario } = first;
-            const batch = {
-                version: 1,
-                batchId: input.mintId(),
-                baseScenario,
-                variants: scenarios.map((scenario) => ({
-                    runId: scenario.runId,
-                    config: scenario.trader.config,
-                })),
-                tape: input.tape,
-            };
-            const result = await client.runBacktestBatch(batch, cloneTapeBuffers(input.buffers));
-            if (result.results.length !== subChunk.length) {
-                throw new errors_1.EngineBacktestError({
-                    type: "runtime",
-                    subtype: "batch_result_count",
-                    message: "runBacktestBatch returned an unexpected result count",
-                    details: {
-                        expected: subChunk.length,
-                        actual: result.results.length,
-                    },
-                });
-            }
-            subChunk.forEach((entry, index) => {
-                const point = result.results[index];
-                completed[entry.index] = readBatchPoint(entry.item.coordinate, point);
+        const prepared = await (0, prepared_tape_1.prepareWorkerTape)(client, input.tape, input.buffers);
+        try {
+            await runPreparedWorkerBatches({
+                client,
+                handle: prepared.handle,
+                chunk,
+                completed,
+                input,
             });
-            const finished = completed.filter((point) => point !== undefined);
-            input.onProgress(finished.length, finished);
+        }
+        catch (error) {
+            (0, prepared_tape_1.mapPreparedTapeError)(error);
+        }
+        finally {
+            await (0, prepared_tape_1.releaseWorkerTape)(client, prepared.handle);
         }
     }));
     return completed.filter((point) => point !== undefined);
@@ -688,7 +707,7 @@ function readBatchPoint(coordinate, point) {
     return {
         coordinate,
         status: "failed",
-        error: point.errors?.[0]?.message ?? "runBacktestBatch variant failed",
+        error: point.errors?.[0]?.message ?? "runPreparedBacktestBatch variant failed",
     };
 }
 function partitionRoundRobin(items, workerCount) {

package/dist/engine-backtest/types.d.ts

@@ -1,3 +1,4 @@
+import type { EngineBacktestActivity } from "./activity";
 export type SubscriptionTier = "free" | "pro" | "pro_max";
 export type DataQualityMode = "strict" | "basic";
 /** New runs default to basic; `--data-quality strict` remains an explicit override. */
@@ -124,6 +125,7 @@ export interface EngineBacktestResult {
     readonly equityCurve?: unknown[];
     readonly orders?: unknown[];
     readonly openPositions?: unknown[];
+    readonly accountAdjustments?: unknown[];
     readonly errors?: Array<{
         code: string;
         message: string;
@@ -222,6 +224,10 @@ export interface TapeLoadResult {
     readonly coverageWarnings: readonly string[];
     readonly coverageIssues: readonly TapeCoverageIssue[];
 }
+export interface EnginePreparedTape {
+    readonly handle: string;
+    readonly fingerprint: string;
+}
 export interface BacktestClientLike {
     init(): Promise<string>;
     version(): Promise<string>;
@@ -237,8 +243,15 @@ export interface BacktestClientLike {
         readonly configSchemaVersion: number;
         readonly config: unknown;
     }): Promise<EngineBacktestPlan | EngineBacktestFailure>;
-    runBacktest(scenario: EngineBacktestScenario, buffers: Record<string, ArrayBuffer>, onProgress?: (fraction: number) => void): Promise<EngineBacktestResult>;
-    runBacktestBatch(batch: EngineBacktestBatchRequest, buffers: Record<string, ArrayBuffer>, onProgress?: (fraction: number) => void): Promise<EngineBacktestBatchResult>;
+    prepareTape(tape: EngineBacktestTapeInput, buffers: Record<string, ArrayBuffer>): Promise<EnginePreparedTape>;
+    runPreparedBacktest(handle: string, scenario: EngineBacktestScenario, onProgress?: (fraction: number) => void): Promise<EngineBacktestResult>;
+    runPreparedBacktestBatch(handle: string, batch: EngineBacktestBatchRequest, onProgress?: (fraction: number) => void): Promise<EngineBacktestBatchResult>;
+    releaseTape(handle: string): Promise<{
+        readonly released: true;
+    }>;
+    /** Legacy one-shot WASM API. CLI host must not call these. */
+    runBacktest?(scenario: EngineBacktestScenario, buffers: Record<string, ArrayBuffer>, onProgress?: (fraction: number) => void): Promise<EngineBacktestResult>;
+    runBacktestBatch?(batch: EngineBacktestBatchRequest, buffers: Record<string, ArrayBuffer>, onProgress?: (fraction: number) => void): Promise<EngineBacktestBatchResult>;
     terminate(): void;
 }
 export interface BacktestWasmModule {
@@ -258,6 +271,7 @@ export interface BacktestRunnerModule {
         readonly toMs: number;
         readonly dataQualityMode?: DataQualityMode;
         readonly cacheDir?: string;
+        readonly seriesConcurrency?: number;
         readonly onProgress?: (progress: TapeLoadProgress) => void;
     }, options?: unknown): Promise<TapeLoadResult>;
     assembleScenario(input: {
@@ -300,6 +314,8 @@ export interface CreateRunRequestBody {
     readonly configSchemaVersion: number;
     /** Compact [[unix_ms, cumulative_return]]; omitted when the local run has no series. */
     readonly returnCurve?: ReadonlyArray<readonly [number, number]>;
+    /** Ledger snapshot + filled-order tail. Omitted only when persist is skipped. */
+    readonly activity?: EngineBacktestActivity;
 }
 export interface EngineBacktestRunSuccess {
     readonly metrics: EngineBacktestMetrics;