@alphafox/cli 0.3.13 → 0.3.14

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

@@ -0,0 +1,60 @@
+import type { EngineBacktestAttribution } from "./result-attribution";
+export declare const ENGINE_BACKTEST_ACTIVITY_SCHEMA_VERSION: 1;
+export declare const ENGINE_BACKTEST_ACTIVITY_MAX_UTF8_BYTES: number;
+export declare const ENGINE_BACKTEST_ACTIVITY_MAX_FILLED_ORDERS = 2000;
+export declare function utf8ByteLength(value: string): number;
+export interface EngineBacktestOrder {
+    readonly clientOrderId: string;
+    readonly orderId: string;
+    readonly symbol: string;
+    readonly side: string;
+    readonly positionSide?: string;
+    readonly type: string;
+    readonly status: string;
+    readonly reduceOnly: boolean;
+    readonly price: number;
+    readonly contractAmount: number;
+    readonly filledQuantity: number;
+    readonly fee: number;
+    readonly timestamp: string;
+    readonly message?: string;
+    readonly executionReason?: "liquidation";
+}
+export interface EngineBacktestPosition {
+    readonly symbol: string;
+    readonly side: string;
+    readonly contracts: number;
+    readonly entryPrice: number;
+    readonly markPrice: number;
+    readonly unrealizedPnl: number;
+    readonly leverage: number;
+}
+export interface EngineBacktestAccountAdjustment {
+    readonly type: string;
+    readonly amount: number;
+    readonly timestamp: string;
+}
+export interface EngineBacktestActivity {
+    readonly schemaVersion: 1;
+    readonly attribution: EngineBacktestAttribution;
+    readonly openPositions: readonly EngineBacktestPosition[];
+    readonly accountAdjustments: readonly EngineBacktestAccountAdjustment[];
+    readonly filledOrders: readonly EngineBacktestOrder[];
+    readonly filledOrderTotal: number;
+    readonly truncated: boolean;
+}
+export declare function readActivityOrders(value: unknown): EngineBacktestOrder[];
+export declare function readActivityPositions(value: unknown): EngineBacktestPosition[];
+export declare function readActivityAdjustments(value: unknown): EngineBacktestAccountAdjustment[];
+export declare function selectFilledOrderTail(orders: readonly EngineBacktestOrder[], limit?: number): {
+    readonly filledOrders: EngineBacktestOrder[];
+    readonly filledOrderTotal: number;
+    readonly truncated: boolean;
+};
+export declare function buildEngineBacktestActivityFromCompleted(input: {
+    readonly attribution: EngineBacktestAttribution;
+    readonly orders: readonly EngineBacktestOrder[];
+    readonly openPositions: readonly EngineBacktestPosition[];
+    readonly accountAdjustments?: readonly EngineBacktestAccountAdjustment[];
+    readonly maxFilledOrders?: number;
+}): EngineBacktestActivity;

package/dist/engine-backtest/activity.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENGINE_BACKTEST_ACTIVITY_MAX_FILLED_ORDERS = exports.ENGINE_BACKTEST_ACTIVITY_MAX_UTF8_BYTES = exports.ENGINE_BACKTEST_ACTIVITY_SCHEMA_VERSION = void 0;
+exports.utf8ByteLength = utf8ByteLength;
+exports.readActivityOrders = readActivityOrders;
+exports.readActivityPositions = readActivityPositions;
+exports.readActivityAdjustments = readActivityAdjustments;
+exports.selectFilledOrderTail = selectFilledOrderTail;
+exports.buildEngineBacktestActivityFromCompleted = buildEngineBacktestActivityFromCompleted;
+const errors_1 = require("./errors");
+exports.ENGINE_BACKTEST_ACTIVITY_SCHEMA_VERSION = 1;
+exports.ENGINE_BACKTEST_ACTIVITY_MAX_UTF8_BYTES = 1024 * 1024;
+exports.ENGINE_BACKTEST_ACTIVITY_MAX_FILLED_ORDERS = 2_000;
+function utf8ByteLength(value) {
+    return new TextEncoder().encode(value).length;
+}
+function readActivityOrders(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        throw invalidActivityField("orders", "must be an array");
+    }
+    return value.map((item, index) => readOrder(item, index));
+}
+function readActivityPositions(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        throw invalidActivityField("openPositions", "must be an array");
+    }
+    return value.map((item, index) => readPosition(item, index));
+}
+function readActivityAdjustments(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        throw invalidActivityField("accountAdjustments", "must be an array");
+    }
+    return value.map((item, index) => readAdjustment(item, index));
+}
+function selectFilledOrderTail(orders, limit = exports.ENGINE_BACKTEST_ACTIVITY_MAX_FILLED_ORDERS) {
+    const filled = orders
+        .map((order, index) => ({ order, index }))
+        .filter((entry) => entry.order.filledQuantity > 0)
+        .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);
+    const filledOrderTotal = filled.length;
+    const truncated = filledOrderTotal > limit;
+    return {
+        filledOrders: truncated ? filled.slice(-limit) : [...filled],
+        filledOrderTotal,
+        truncated,
+    };
+}
+function buildEngineBacktestActivityFromCompleted(input) {
+    const countCap = input.maxFilledOrders ?? exports.ENGINE_BACKTEST_ACTIVITY_MAX_FILLED_ORDERS;
+    const tail = selectFilledOrderTail(input.orders, countCap);
+    return fitActivityToUtf8Budget({
+        schemaVersion: exports.ENGINE_BACKTEST_ACTIVITY_SCHEMA_VERSION,
+        attribution: {
+            ...input.attribution,
+            symbols: [...input.attribution.symbols],
+        },
+        openPositions: [...input.openPositions],
+        accountAdjustments: [...(input.accountAdjustments ?? [])],
+        filledOrders: tail.filledOrders.map(toPersistedFilledOrder),
+        filledOrderTotal: tail.filledOrderTotal,
+        truncated: tail.truncated,
+    });
+}
+function fitActivityToUtf8Budget(activity) {
+    if (activityUtf8ByteLength(activity) <= exports.ENGINE_BACKTEST_ACTIVITY_MAX_UTF8_BYTES) {
+        return activity;
+    }
+    let low = 0;
+    let high = activity.filledOrders.length;
+    let fitted = withFilledOrderTail(activity, 0);
+    while (low <= high) {
+        const mid = Math.floor((low + high) / 2);
+        const candidate = withFilledOrderTail(activity, mid);
+        if (activityUtf8ByteLength(candidate) <= exports.ENGINE_BACKTEST_ACTIVITY_MAX_UTF8_BYTES) {
+            fitted = candidate;
+            low = mid + 1;
+        }
+        else {
+            high = mid - 1;
+        }
+    }
+    if (activityUtf8ByteLength(fitted) > exports.ENGINE_BACKTEST_ACTIVITY_MAX_UTF8_BYTES) {
+        throw new errors_1.EngineBacktestError({
+            type: "runtime",
+            subtype: "activity_too_large",
+            message: `Activity exceeds ${exports.ENGINE_BACKTEST_ACTIVITY_MAX_UTF8_BYTES} UTF-8 bytes.`,
+        });
+    }
+    return fitted;
+}
+function withFilledOrderTail(activity, keepCount) {
+    const filledOrders = keepCount <= 0 ? [] : activity.filledOrders.slice(-keepCount);
+    return {
+        ...activity,
+        filledOrders,
+        truncated: activity.filledOrderTotal > filledOrders.length,
+    };
+}
+function activityUtf8ByteLength(activity) {
+    return utf8ByteLength(JSON.stringify(activity));
+}
+function toPersistedFilledOrder(order) {
+    return {
+        clientOrderId: order.clientOrderId,
+        orderId: order.orderId,
+        symbol: order.symbol,
+        side: order.side,
+        ...(order.positionSide ? { positionSide: order.positionSide } : {}),
+        type: order.type,
+        status: order.status,
+        reduceOnly: order.reduceOnly,
+        price: order.price,
+        contractAmount: order.contractAmount,
+        filledQuantity: order.filledQuantity,
+        fee: order.fee,
+        timestamp: order.timestamp,
+        ...(order.message?.trim() ? { message: order.message } : {}),
+        ...(order.executionReason === "liquidation"
+            ? { executionReason: "liquidation" }
+            : {}),
+    };
+}
+function readOrder(value, index) {
+    const record = asRecord(value, `orders[${index}]`);
+    const executionReason = optionalString(record.executionReason);
+    return {
+        clientOrderId: requiredString(record.clientOrderId, `orders[${index}].clientOrderId`),
+        orderId: requiredString(record.orderId, `orders[${index}].orderId`),
+        symbol: requiredString(record.symbol, `orders[${index}].symbol`),
+        side: requiredString(record.side, `orders[${index}].side`),
+        ...(optionalString(record.positionSide)
+            ? { positionSide: optionalString(record.positionSide) }
+            : {}),
+        type: requiredString(record.type, `orders[${index}].type`),
+        status: requiredString(record.status, `orders[${index}].status`),
+        reduceOnly: requiredBoolean(record.reduceOnly, `orders[${index}].reduceOnly`),
+        price: requiredFinite(record.price, `orders[${index}].price`),
+        contractAmount: requiredFinite(record.contractAmount, `orders[${index}].contractAmount`),
+        filledQuantity: requiredFinite(record.filledQuantity, `orders[${index}].filledQuantity`),
+        fee: requiredFinite(record.fee, `orders[${index}].fee`),
+        timestamp: requiredString(record.timestamp, `orders[${index}].timestamp`),
+        ...(optionalString(record.message)
+            ? { message: optionalString(record.message) }
+            : {}),
+        ...(executionReason === "liquidation"
+            ? { executionReason: "liquidation" }
+            : {}),
+    };
+}
+function readPosition(value, index) {
+    const record = asRecord(value, `openPositions[${index}]`);
+    return {
+        symbol: requiredString(record.symbol, `openPositions[${index}].symbol`),
+        side: requiredString(record.side, `openPositions[${index}].side`),
+        contracts: requiredFinite(record.contracts, `openPositions[${index}].contracts`),
+        entryPrice: requiredFinite(record.entryPrice, `openPositions[${index}].entryPrice`),
+        markPrice: requiredFinite(record.markPrice, `openPositions[${index}].markPrice`),
+        unrealizedPnl: requiredFinite(record.unrealizedPnl, `openPositions[${index}].unrealizedPnl`),
+        leverage: requiredFinite(record.leverage, `openPositions[${index}].leverage`),
+    };
+}
+function readAdjustment(value, index) {
+    const record = asRecord(value, `accountAdjustments[${index}]`);
+    return {
+        type: requiredString(record.type, `accountAdjustments[${index}].type`),
+        amount: requiredFinite(record.amount, `accountAdjustments[${index}].amount`),
+        timestamp: requiredString(record.timestamp, `accountAdjustments[${index}].timestamp`),
+    };
+}
+function asRecord(value, path) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw invalidActivityField(path, "must be an object");
+    }
+    return value;
+}
+function requiredString(value, path) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw invalidActivityField(path, "must be a non-empty string");
+    }
+    return value;
+}
+function optionalString(value) {
+    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+function requiredBoolean(value, path) {
+    if (typeof value !== "boolean") {
+        throw invalidActivityField(path, "must be a boolean");
+    }
+    return value;
+}
+function requiredFinite(value, path) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw invalidActivityField(path, "must be a finite number");
+    }
+    return value;
+}
+function invalidActivityField(path, reason) {
+    return new errors_1.EngineBacktestError({
+        type: "runtime",
+        subtype: "persist_invalid_activity",
+        message: `Cannot persist activity ${path}: ${reason}`,
+    });
+}

package/dist/engine-backtest/dca-first-order-amount-compat.d.ts

@@ -0,0 +1,7 @@
+/**
+ * WASM runtimes older than the firstOrderAmount rename still size DCA
+ * entries from initialMarginPercent / fixedInitialNotional and default to
+ * 2% when those keys are missing. Mirror the active mode onto the legacy
+ * keys so both runtimes honor the user's first-order size.
+ */
+export declare function projectDcaFirstOrderAmountForLegacyRuntime(config: unknown): unknown;

package/dist/engine-backtest/dca-first-order-amount-compat.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectDcaFirstOrderAmountForLegacyRuntime = projectDcaFirstOrderAmountForLegacyRuntime;
+const DECISION_LOGIC_KEYS = [
+    "decisionLogic",
+    "longDecisionLogic",
+    "shortDecisionLogic",
+];
+const FIRST_ORDER_AMOUNT_TYPE_FIXED = "fixedAmount";
+/**
+ * WASM runtimes older than the firstOrderAmount rename still size DCA
+ * entries from initialMarginPercent / fixedInitialNotional and default to
+ * 2% when those keys are missing. Mirror the active mode onto the legacy
+ * keys so both runtimes honor the user's first-order size.
+ */
+function projectDcaFirstOrderAmountForLegacyRuntime(config) {
+    const record = asRecord(config);
+    if (!record) {
+        return config;
+    }
+    const strategy = asRecord(record.strategy);
+    if (!strategy) {
+        return config;
+    }
+    let changed = false;
+    const nextStrategy = { ...strategy };
+    for (const key of DECISION_LOGIC_KEYS) {
+        const logic = asRecord(strategy[key]);
+        const params = logic ? asRecord(logic.params) : null;
+        if (!logic || !params) {
+            continue;
+        }
+        const projected = projectDecisionLogicParams(params);
+        if (projected === params) {
+            continue;
+        }
+        nextStrategy[key] = { ...logic, params: projected };
+        changed = true;
+    }
+    if (!changed) {
+        return config;
+    }
+    return { ...record, strategy: nextStrategy };
+}
+function projectDecisionLogicParams(params) {
+    const amount = toFiniteNumber(params.firstOrderAmount);
+    if (amount === undefined || amount <= 0) {
+        return params;
+    }
+    const isFixed = params.firstOrderAmountType === FIRST_ORDER_AMOUNT_TYPE_FIXED;
+    const next = { ...params };
+    if (isFixed) {
+        next.fixedInitialNotional = amount;
+        delete next.initialMarginPercent;
+    }
+    else {
+        next.initialMarginPercent = amount;
+        delete next.fixedInitialNotional;
+    }
+    return next;
+}
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function toFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? value
+        : undefined;
+}

package/dist/engine-backtest/load-config.d.ts

@@ -1,4 +1,8 @@
-export declare function loadConfigValue(raw: string, options?: {
+type LoadConfigOptions = {
     readonly cwd?: string;
     readonly readFile?: (path: string) => string;
-}): unknown;
+};
+export declare function loadConfigValue(raw: string, options?: LoadConfigOptions): unknown;
+export declare function loadEngineBacktestConfig(raw: string, options?: LoadConfigOptions): unknown;
+export declare function assertEngineBacktestConfig(value: unknown): void;
+export {};

package/dist/engine-backtest/load-config.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadConfigValue = loadConfigValue;
+exports.loadEngineBacktestConfig = loadEngineBacktestConfig;
+exports.assertEngineBacktestConfig = assertEngineBacktestConfig;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const errors_1 = require("./errors");
@@ -42,3 +44,24 @@ function loadConfigValue(raw, options = {}) {
         });
     }
 }
+function loadEngineBacktestConfig(raw, options = {}) {
+    const value = loadConfigValue(raw, options);
+    assertEngineBacktestConfig(value);
+    return value;
+}
+function assertEngineBacktestConfig(value) {
+    if (!isPlainObject(value) || !isPlainObject(value.config)) {
+        return;
+    }
+    throw new errors_1.EngineBacktestError({
+        type: "usage",
+        subtype: "validate_config_envelope",
+        message: "--config looks like a validate_config HTTP body; engine-backtest needs the inner trader config",
+        hint: "Pass { common, strategy }. Extract the `config` field; do not send { configSchemaVersion, config }.",
+        status: 400,
+        details: { keys: Object.keys(value) },
+    });
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}

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

@@ -25,6 +25,9 @@ export declare function buildCreateRunRequest(input: {
     readonly engineVersion: string;
     readonly equityCurve?: unknown;
     readonly coverageIssues?: readonly TapeCoverageIssue[];
+    readonly orders?: unknown;
+    readonly openPositions?: unknown;
+    readonly accountAdjustments?: unknown;
 }): CreateRunRequestBody;
 /**
  * Experiment detail URL. Locale prefix (`/zh`, `/en`) is optional — web

package/dist/engine-backtest/persist.js

@@ -12,9 +12,11 @@ exports.sweepsPath = sweepsPath;
 exports.buildSweepBaseSnapshot = buildSweepBaseSnapshot;
 exports.buildCreateSweepRequest = buildCreateSweepRequest;
 exports.assertSweepCreateRequestSize = assertSweepCreateRequestSize;
+const activity_1 = require("./activity");
+const coverage_notice_1 = require("./coverage-notice");
 const errors_1 = require("./errors");
+const result_attribution_1 = require("./result-attribution");
 const return_curve_1 = require("./return-curve");
-const coverage_notice_1 = require("./coverage-notice");
 /** Aligned with `@alphafoxai/backtest-runner` DEFAULT_EXECUTION_MODEL. */
 exports.DEFAULT_EXECUTION_MODEL = {
     pricePath: "ohlc_path_4",
@@ -84,6 +86,24 @@ function buildCreateRunRequest(input) {
         initialEquity: snapshot.initialEquity,
         equityCurve: input.equityCurve,
     });
+    const orders = (0, activity_1.readActivityOrders)(input.orders);
+    const openPositions = (0, activity_1.readActivityPositions)(input.openPositions);
+    const accountAdjustments = (0, activity_1.readActivityAdjustments)(input.accountAdjustments);
+    const activity = (0, activity_1.buildEngineBacktestActivityFromCompleted)({
+        attribution: (0, result_attribution_1.attributeEngineBacktestResult)({
+            result: {
+                metrics: input.metrics,
+                orders,
+                openPositions,
+                accountAdjustments,
+            },
+            markets: scenario.tape.markets,
+            symbols,
+        }),
+        orders,
+        openPositions,
+        accountAdjustments,
+    });
     return {
         clientRunId: input.clientRunId,
         snapshot,
@@ -91,6 +111,7 @@ function buildCreateRunRequest(input) {
         engineVersion,
         configSchemaVersion: snapshot.configSchemaVersion,
         ...(returnCurve ? { returnCurve } : {}),
+        activity,
     };
 }
 /**

package/dist/engine-backtest/prepared-tape.d.ts

@@ -0,0 +1,10 @@
+import type { BacktestClientLike, EngineBacktestResult, EngineBacktestTapeInput, EnginePreparedTape } from "./types";
+/** Matches Web `DEFAULT_TAPE_SERIES_CONCURRENCY`. */
+export declare const ENGINE_BACKTEST_TAPE_SERIES_CONCURRENCY = 8;
+export declare function cloneTapeBuffers(sourceBuffers: Readonly<Record<string, ArrayBuffer>>): Record<string, ArrayBuffer>;
+export declare function requirePreparedTapeClient(client: BacktestClientLike): void;
+export declare function prepareWorkerTape(client: BacktestClientLike, tape: EngineBacktestTapeInput, buffers: Readonly<Record<string, ArrayBuffer>>): Promise<EnginePreparedTape>;
+export declare function releaseWorkerTape(client: BacktestClientLike, handle: string | undefined): Promise<void>;
+export declare function requireCompletedPreparedRun(result: EngineBacktestResult): EngineBacktestResult;
+export declare function throwIfPreparedTapeErrors(errors: EngineBacktestResult["errors"] | undefined, details?: unknown): void;
+export declare function mapPreparedTapeError(error: unknown): never;

package/dist/engine-backtest/prepared-tape.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENGINE_BACKTEST_TAPE_SERIES_CONCURRENCY = void 0;
+exports.cloneTapeBuffers = cloneTapeBuffers;
+exports.requirePreparedTapeClient = requirePreparedTapeClient;
+exports.prepareWorkerTape = prepareWorkerTape;
+exports.releaseWorkerTape = releaseWorkerTape;
+exports.requireCompletedPreparedRun = requireCompletedPreparedRun;
+exports.throwIfPreparedTapeErrors = throwIfPreparedTapeErrors;
+exports.mapPreparedTapeError = mapPreparedTapeError;
+const errors_1 = require("./errors");
+/** Matches Web `DEFAULT_TAPE_SERIES_CONCURRENCY`. */
+exports.ENGINE_BACKTEST_TAPE_SERIES_CONCURRENCY = 8;
+const PREPARED_TAPE_METHODS = [
+    "prepareTape",
+    "runPreparedBacktest",
+    "runPreparedBacktestBatch",
+    "releaseTape",
+];
+const PREPARED_TAPE_ERROR_CODES = new Set([
+    "prepared_tape_not_found",
+    "prepared_tape_mismatch",
+]);
+function cloneTapeBuffers(sourceBuffers) {
+    return Object.fromEntries(Object.entries(sourceBuffers).map(([key, buffer]) => [key, buffer.slice(0)]));
+}
+function requirePreparedTapeClient(client) {
+    for (const name of PREPARED_TAPE_METHODS) {
+        if (typeof client[name] !== "function") {
+            throw new errors_1.EngineBacktestError({
+                type: "runtime",
+                subtype: "prepared_tape_unavailable",
+                message: `Backtest runtime is missing ${name}; one-shot runBacktest is not used.`,
+                hint: "Use an Engine WASM host that exports prepareTape, runPreparedBacktest, runPreparedBacktestBatch, and releaseTape.",
+                details: { missing: name },
+            });
+        }
+    }
+}
+async function prepareWorkerTape(client, tape, buffers) {
+    requirePreparedTapeClient(client);
+    const prepared = await client.prepareTape(tape, cloneTapeBuffers(buffers));
+    const failure = preparedTapeFailure(prepared);
+    if (failure) {
+        throw preparedTapeError(failure.code, failure.message, prepared);
+    }
+    if (!prepared ||
+        typeof prepared.handle !== "string" ||
+        prepared.handle.trim() === "") {
+        throw new errors_1.EngineBacktestError({
+            type: "runtime",
+            subtype: "prepared_tape_unavailable",
+            message: "prepareTape did not return a worker-local handle.",
+        });
+    }
+    return prepared;
+}
+async function releaseWorkerTape(client, handle) {
+    if (!handle)
+        return;
+    try {
+        await client.releaseTape(handle);
+    }
+    catch (error) {
+        if (preparedTapeCodeFromUnknown(error) === "prepared_tape_not_found") {
+            return;
+        }
+        throw mapPreparedTapeError(error);
+    }
+}
+function requireCompletedPreparedRun(result) {
+    throwIfPreparedTapeErrors(result.errors, result);
+    if (result.status === "failed") {
+        throw new errors_1.EngineBacktestError({
+            type: "runtime",
+            subtype: "backtest_failed",
+            message: "runPreparedBacktest returned status=failed",
+            details: { errors: result.errors, runId: result.runId },
+        });
+    }
+    return result;
+}
+function throwIfPreparedTapeErrors(errors, details) {
+    const failure = preparedTapeFailure({ errors });
+    if (!failure)
+        return;
+    throw preparedTapeError(failure.code, failure.message, details);
+}
+function mapPreparedTapeError(error) {
+    if (error instanceof errors_1.EngineBacktestError)
+        throw error;
+    const code = preparedTapeCodeFromUnknown(error);
+    if (code) {
+        throw preparedTapeError(code, error instanceof Error ? error.message : String(error), error);
+    }
+    throw error;
+}
+function preparedTapeFailure(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const record = value;
+    const code = preparedTapeCodeFromErrors(record.errors);
+    if (!code)
+        return undefined;
+    return {
+        code,
+        message: record.errors?.[0]?.message?.trim() || code,
+    };
+}
+function preparedTapeCodeFromErrors(errors) {
+    const code = errors?.[0]?.code;
+    return typeof code === "string" && PREPARED_TAPE_ERROR_CODES.has(code)
+        ? code
+        : undefined;
+}
+function preparedTapeCodeFromUnknown(error) {
+    if (error instanceof errors_1.EngineBacktestError && error.subtype) {
+        return PREPARED_TAPE_ERROR_CODES.has(error.subtype)
+            ? error.subtype
+            : undefined;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    for (const code of PREPARED_TAPE_ERROR_CODES) {
+        if (message.includes(code))
+            return code;
+    }
+    return undefined;
+}
+function preparedTapeError(code, message, details) {
+    return new errors_1.EngineBacktestError({
+        type: "runtime",
+        subtype: code,
+        message,
+        details,
+    });
+}

package/dist/engine-backtest/result-attribution.d.ts

@@ -0,0 +1,35 @@
+import type { EngineBacktestAccountAdjustment, EngineBacktestOrder, EngineBacktestPosition } from "./activity";
+import type { EngineBacktestMetrics } from "./types";
+export interface EngineBacktestSymbolAttribution {
+    readonly symbol: string;
+    readonly realizedPnl: number;
+    readonly liquidationRealizedPnl: number;
+    readonly unrealizedPnl: number;
+    readonly feesPaid: number;
+    readonly netPnl: number;
+    readonly orderCount: number;
+    readonly filledOrderCount: number;
+    readonly canceledOrderCount: number;
+    readonly tradeCount: number;
+    readonly winningTrades: number;
+    readonly losingTrades: number;
+    readonly winRatePct: number;
+}
+export interface EngineBacktestAttribution {
+    readonly symbols: readonly EngineBacktestSymbolAttribution[];
+    readonly attributedNetPnl: number;
+    readonly accountAdjustmentPnl: number;
+    readonly residualPnl: number;
+    readonly reconciliationTolerance: number;
+    readonly reconciled: boolean;
+}
+export declare function attributeEngineBacktestResult(input: {
+    readonly result: {
+        readonly metrics: Pick<EngineBacktestMetrics, "netPnl">;
+        readonly orders: readonly EngineBacktestOrder[];
+        readonly openPositions: readonly EngineBacktestPosition[];
+        readonly accountAdjustments?: readonly EngineBacktestAccountAdjustment[];
+    };
+    readonly markets: Readonly<Record<string, unknown>>;
+    readonly symbols?: readonly string[];
+}): EngineBacktestAttribution;