@alphafox/cli 0.3.2 → 0.3.4

package/dist/engine-backtest/sweep-kernel/caps.d.ts

@@ -0,0 +1,26 @@
+import type { SweepSubscriptionTier } from "./types";
+/** Free tier max simultaneous sweep parameters. */
+export declare const FREE_MAX_SWEEP_PARAMS = 5;
+/** Free combination cap (downsample above this). */
+export declare const FREE_MAX_SWEEP_COMBINATIONS = 125;
+/** Pro / Pro Max combination cap. */
+export declare const PRO_MAX_SWEEP_COMBINATIONS = 2000;
+/** Free tier is forced to serial execution. */
+export declare const SWEEP_SERIAL_CONCURRENCY = 1;
+/** Pro default worker count for parameter search. */
+export declare const DEFAULT_SWEEP_CONCURRENCY = 2;
+/** Hard cap on simultaneous sweep workers. */
+export declare const MAX_SWEEP_CONCURRENCY = 8;
+export declare const SWEEP_CONCURRENCY_OPTIONS: readonly [1, 2, 3, 4, 5, 6, 7, 8];
+export type SweepConcurrency = (typeof SWEEP_CONCURRENCY_OPTIONS)[number];
+/**
+ * Free users always run serially. Pro / Pro Max may pick 1…MAX, defaulting to
+ * {@link DEFAULT_SWEEP_CONCURRENCY} when the requested value is invalid.
+ */
+export declare function resolveSweepConcurrency(input: {
+    readonly subscriptionTier: SweepSubscriptionTier | undefined;
+    readonly requested: number;
+}): SweepConcurrency;
+/** null = unlimited param count (Pro / Pro Max). */
+export declare function resolveMaxSweepParams(subscriptionTier: SweepSubscriptionTier | undefined): number | null;
+export declare function resolveMaxSweepCombinations(subscriptionTier: SweepSubscriptionTier | undefined): number;

package/dist/engine-backtest/sweep-kernel/caps.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SWEEP_CONCURRENCY_OPTIONS = exports.MAX_SWEEP_CONCURRENCY = exports.DEFAULT_SWEEP_CONCURRENCY = exports.SWEEP_SERIAL_CONCURRENCY = exports.PRO_MAX_SWEEP_COMBINATIONS = exports.FREE_MAX_SWEEP_COMBINATIONS = exports.FREE_MAX_SWEEP_PARAMS = void 0;
+exports.resolveSweepConcurrency = resolveSweepConcurrency;
+exports.resolveMaxSweepParams = resolveMaxSweepParams;
+exports.resolveMaxSweepCombinations = resolveMaxSweepCombinations;
+/** Free tier max simultaneous sweep parameters. */
+exports.FREE_MAX_SWEEP_PARAMS = 5;
+/** Free combination cap (downsample above this). */
+exports.FREE_MAX_SWEEP_COMBINATIONS = 125;
+/** Pro / Pro Max combination cap. */
+exports.PRO_MAX_SWEEP_COMBINATIONS = 2000;
+/** Free tier is forced to serial execution. */
+exports.SWEEP_SERIAL_CONCURRENCY = 1;
+/** Pro default worker count for parameter search. */
+exports.DEFAULT_SWEEP_CONCURRENCY = 2;
+/** Hard cap on simultaneous sweep workers. */
+exports.MAX_SWEEP_CONCURRENCY = 8;
+exports.SWEEP_CONCURRENCY_OPTIONS = [
+    1, 2, 3, 4, 5, 6, 7, 8,
+];
+function isProTier(subscriptionTier) {
+    return subscriptionTier === "pro" || subscriptionTier === "pro_max";
+}
+/**
+ * Free users always run serially. Pro / Pro Max may pick 1…MAX, defaulting to
+ * {@link DEFAULT_SWEEP_CONCURRENCY} when the requested value is invalid.
+ */
+function resolveSweepConcurrency(input) {
+    if (!isProTier(input.subscriptionTier)) {
+        return exports.SWEEP_SERIAL_CONCURRENCY;
+    }
+    if (Number.isInteger(input.requested) &&
+        input.requested >= exports.SWEEP_SERIAL_CONCURRENCY &&
+        input.requested <= exports.MAX_SWEEP_CONCURRENCY) {
+        return input.requested;
+    }
+    return exports.DEFAULT_SWEEP_CONCURRENCY;
+}
+/** null = unlimited param count (Pro / Pro Max). */
+function resolveMaxSweepParams(subscriptionTier) {
+    return isProTier(subscriptionTier) ? null : exports.FREE_MAX_SWEEP_PARAMS;
+}
+function resolveMaxSweepCombinations(subscriptionTier) {
+    return isProTier(subscriptionTier)
+        ? exports.PRO_MAX_SWEEP_COMBINATIONS
+        : exports.FREE_MAX_SWEEP_COMBINATIONS;
+}

package/dist/engine-backtest/sweep-kernel/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Pure Sweep domain kernel shared with alphafox-web.
+ * Copied from alphafox-web/features/engine-backtest/domain/sweep-kernel.
+ * Keep this folder and the matching tests/sweep-kernel.*.test.ts aligned
+ * with the Web copy. No DOM, IndexedDB, React, or WASM host dependencies.
+ */
+export { DEFAULT_SWEEP_CONCURRENCY, FREE_MAX_SWEEP_COMBINATIONS, FREE_MAX_SWEEP_PARAMS, MAX_SWEEP_CONCURRENCY, PRO_MAX_SWEEP_COMBINATIONS, resolveMaxSweepCombinations, resolveMaxSweepParams, resolveSweepConcurrency, SWEEP_CONCURRENCY_OPTIONS, SWEEP_SERIAL_CONCURRENCY, type SweepConcurrency, } from "./caps";
+export { applySweepCoordinate, buildSweepAxisValues, estimateFastSweepCombinationCount, planSweep, planSweepFastRefinement, } from "./plan";
+export { analyzeSweepIsland, extractSweepMetrics, resolveIslandRiskLevel, selectBestNonLiquidatedPoint, } from "./results";
+export { createSweepSessionState, reduceSweepSession, } from "./session";
+export type { SweepCloudSaveState, SweepExecutionState, SweepSessionEvent, SweepSessionState, } from "./session";
+export type { IslandAnalysis, IslandCounterexample, IslandRiskLevel, IslandWarning, ScoredSweepPoint, SweepMetricPoint, SweepMetricsSource, SweepPoint, SweepPointMetrics, } from "./results";
+export type { SweepAxisInput, SweepAxisWindow, SweepConfigRecord, SweepCoordinate, SweepPlan, SweepPlanAxis, SweepSearchMode, SweepSubscriptionTier, } from "./types";

package/dist/engine-backtest/sweep-kernel/index.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reduceSweepSession = exports.createSweepSessionState = exports.selectBestNonLiquidatedPoint = exports.resolveIslandRiskLevel = exports.extractSweepMetrics = exports.analyzeSweepIsland = exports.planSweepFastRefinement = exports.planSweep = exports.estimateFastSweepCombinationCount = exports.buildSweepAxisValues = exports.applySweepCoordinate = exports.SWEEP_SERIAL_CONCURRENCY = exports.SWEEP_CONCURRENCY_OPTIONS = exports.resolveSweepConcurrency = exports.resolveMaxSweepParams = exports.resolveMaxSweepCombinations = exports.PRO_MAX_SWEEP_COMBINATIONS = exports.MAX_SWEEP_CONCURRENCY = exports.FREE_MAX_SWEEP_PARAMS = exports.FREE_MAX_SWEEP_COMBINATIONS = exports.DEFAULT_SWEEP_CONCURRENCY = void 0;
+/**
+ * Pure Sweep domain kernel shared with alphafox-web.
+ * Copied from alphafox-web/features/engine-backtest/domain/sweep-kernel.
+ * Keep this folder and the matching tests/sweep-kernel.*.test.ts aligned
+ * with the Web copy. No DOM, IndexedDB, React, or WASM host dependencies.
+ */
+var caps_1 = require("./caps");
+Object.defineProperty(exports, "DEFAULT_SWEEP_CONCURRENCY", { enumerable: true, get: function () { return caps_1.DEFAULT_SWEEP_CONCURRENCY; } });
+Object.defineProperty(exports, "FREE_MAX_SWEEP_COMBINATIONS", { enumerable: true, get: function () { return caps_1.FREE_MAX_SWEEP_COMBINATIONS; } });
+Object.defineProperty(exports, "FREE_MAX_SWEEP_PARAMS", { enumerable: true, get: function () { return caps_1.FREE_MAX_SWEEP_PARAMS; } });
+Object.defineProperty(exports, "MAX_SWEEP_CONCURRENCY", { enumerable: true, get: function () { return caps_1.MAX_SWEEP_CONCURRENCY; } });
+Object.defineProperty(exports, "PRO_MAX_SWEEP_COMBINATIONS", { enumerable: true, get: function () { return caps_1.PRO_MAX_SWEEP_COMBINATIONS; } });
+Object.defineProperty(exports, "resolveMaxSweepCombinations", { enumerable: true, get: function () { return caps_1.resolveMaxSweepCombinations; } });
+Object.defineProperty(exports, "resolveMaxSweepParams", { enumerable: true, get: function () { return caps_1.resolveMaxSweepParams; } });
+Object.defineProperty(exports, "resolveSweepConcurrency", { enumerable: true, get: function () { return caps_1.resolveSweepConcurrency; } });
+Object.defineProperty(exports, "SWEEP_CONCURRENCY_OPTIONS", { enumerable: true, get: function () { return caps_1.SWEEP_CONCURRENCY_OPTIONS; } });
+Object.defineProperty(exports, "SWEEP_SERIAL_CONCURRENCY", { enumerable: true, get: function () { return caps_1.SWEEP_SERIAL_CONCURRENCY; } });
+var plan_1 = require("./plan");
+Object.defineProperty(exports, "applySweepCoordinate", { enumerable: true, get: function () { return plan_1.applySweepCoordinate; } });
+Object.defineProperty(exports, "buildSweepAxisValues", { enumerable: true, get: function () { return plan_1.buildSweepAxisValues; } });
+Object.defineProperty(exports, "estimateFastSweepCombinationCount", { enumerable: true, get: function () { return plan_1.estimateFastSweepCombinationCount; } });
+Object.defineProperty(exports, "planSweep", { enumerable: true, get: function () { return plan_1.planSweep; } });
+Object.defineProperty(exports, "planSweepFastRefinement", { enumerable: true, get: function () { return plan_1.planSweepFastRefinement; } });
+var results_1 = require("./results");
+Object.defineProperty(exports, "analyzeSweepIsland", { enumerable: true, get: function () { return results_1.analyzeSweepIsland; } });
+Object.defineProperty(exports, "extractSweepMetrics", { enumerable: true, get: function () { return results_1.extractSweepMetrics; } });
+Object.defineProperty(exports, "resolveIslandRiskLevel", { enumerable: true, get: function () { return results_1.resolveIslandRiskLevel; } });
+Object.defineProperty(exports, "selectBestNonLiquidatedPoint", { enumerable: true, get: function () { return results_1.selectBestNonLiquidatedPoint; } });
+var session_1 = require("./session");
+Object.defineProperty(exports, "createSweepSessionState", { enumerable: true, get: function () { return session_1.createSweepSessionState; } });
+Object.defineProperty(exports, "reduceSweepSession", { enumerable: true, get: function () { return session_1.reduceSweepSession; } });

package/dist/engine-backtest/sweep-kernel/plan.d.ts

@@ -0,0 +1,22 @@
+import type { SweepAxisInput, SweepConfigRecord, SweepCoordinate, SweepPlan, SweepSearchMode, SweepSubscriptionTier } from "./types";
+export declare function buildSweepAxisValues(axis: SweepAxisInput): number[];
+export declare function planSweep(input: {
+    readonly axes: readonly SweepAxisInput[];
+    readonly searchMode?: SweepSearchMode;
+    readonly subscriptionTier?: SweepSubscriptionTier;
+    readonly maxCombinations?: number;
+}): SweepPlan;
+/**
+ * Build the second-stage local Cartesian grid around the best coarse point.
+ * Keeping a complete grid preserves the per-axis robustness slices used by the
+ * result analyzer, unlike sparse Latin-hypercube sampling.
+ */
+export declare function planSweepFastRefinement(input: {
+    readonly coarsePlan: SweepPlan;
+    readonly standardPlan: SweepPlan;
+    readonly center: SweepCoordinate;
+}): SweepCoordinate[];
+export declare function estimateFastSweepCombinationCount(coarsePlan: SweepPlan, standardPlan: SweepPlan): number;
+export declare function applySweepCoordinate(config: SweepConfigRecord, axes: readonly {
+    readonly path: readonly string[];
+}[], coordinate: SweepCoordinate): SweepConfigRecord;

package/dist/engine-backtest/sweep-kernel/plan.js

@@ -0,0 +1,320 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSweepAxisValues = buildSweepAxisValues;
+exports.planSweep = planSweep;
+exports.planSweepFastRefinement = planSweepFastRefinement;
+exports.estimateFastSweepCombinationCount = estimateFastSweepCombinationCount;
+exports.applySweepCoordinate = applySweepCoordinate;
+const caps_1 = require("./caps");
+const MAX_RANGE_POINTS = 21;
+const NEIGHBORHOOD_STEPS = 3;
+const FAST_SWEEP_AXIS_POINTS = 3;
+const EPSILON = 1e-9;
+function buildSweepAxisValues(axis) {
+    if (axis.values) {
+        return normalizeExplicitValues(axis, axis.values);
+    }
+    const window = axis.window ?? defaultNeighborhoodWindow(axis);
+    return buildWindowValues(axis, window);
+}
+function planSweep(input) {
+    const searchMode = input.searchMode ?? "standard";
+    const maxParams = (0, caps_1.resolveMaxSweepParams)(input.subscriptionTier);
+    const selectedAxes = maxParams === null ? [...input.axes] : input.axes.slice(0, maxParams);
+    const rawAxes = selectedAxes.map((axis) => ({
+        path: axis.path,
+        current: axis.current,
+        values: buildSweepAxisValues(axis),
+    }));
+    if (rawAxes.length === 0 ||
+        rawAxes.some((axis) => axis.values.length === 0)) {
+        return {
+            axes: rawAxes,
+            coordinates: [],
+            requestedCombinationCount: 0,
+            sampled: false,
+        };
+    }
+    const requestedCombinationCount = product(rawAxes.map((axis) => axis.values.length));
+    const combinationCap = input.maxCombinations ??
+        (0, caps_1.resolveMaxSweepCombinations)(input.subscriptionTier);
+    const targetSizes = rawAxes.map((axis) => axis.values.length);
+    if (searchMode === "fast" && rawAxes.length > 1) {
+        for (let index = 0; index < targetSizes.length; index += 1) {
+            targetSizes[index] = Math.min(targetSizes[index] ?? FAST_SWEEP_AXIS_POINTS, FAST_SWEEP_AXIS_POINTS);
+        }
+    }
+    else {
+        while (product(targetSizes) > combinationCap) {
+            const axisIndex = targetSizes.reduce((largestIndex, size, index) => size > (targetSizes[largestIndex] ?? 0) ? index : largestIndex, 0);
+            targetSizes[axisIndex] = Math.max(2, (targetSizes[axisIndex] ?? 2) - 1);
+        }
+    }
+    const axes = rawAxes.map((axis, index) => ({
+        path: axis.path,
+        current: axis.current,
+        values: downsample(axis.values, targetSizes[index] ?? axis.values.length, axis.current),
+    }));
+    return {
+        axes,
+        coordinates: cartesianCoordinates(axes.map((axis) => axis.values)),
+        requestedCombinationCount,
+        sampled: requestedCombinationCount > product(targetSizes),
+    };
+}
+/**
+ * Build the second-stage local Cartesian grid around the best coarse point.
+ * Keeping a complete grid preserves the per-axis robustness slices used by the
+ * result analyzer, unlike sparse Latin-hypercube sampling.
+ */
+function planSweepFastRefinement(input) {
+    if (input.coarsePlan.axes.length <= 1 ||
+        input.coarsePlan.axes.length !== input.standardPlan.axes.length ||
+        input.center.values.length !== input.standardPlan.axes.length) {
+        return [];
+    }
+    const localAxes = input.standardPlan.axes.map((axis, index) => localWindow(axis.values, input.center.values[index] ?? axis.current));
+    if (localAxes.some((values) => values.length === 0)) {
+        return [];
+    }
+    const coarseKeys = new Set(input.coarsePlan.coordinates.map(coordinateKey));
+    return cartesianCoordinates(localAxes).filter((coordinate) => !coarseKeys.has(coordinateKey(coordinate)));
+}
+function estimateFastSweepCombinationCount(coarsePlan, standardPlan) {
+    if (coarsePlan.axes.length <= 1) {
+        return coarsePlan.coordinates.length;
+    }
+    const largestRefinement = coarsePlan.coordinates.reduce((largest, center) => Math.max(largest, planSweepFastRefinement({
+        coarsePlan,
+        standardPlan,
+        center,
+    }).length), 0);
+    return coarsePlan.coordinates.length + largestRefinement;
+}
+function applySweepCoordinate(config, axes, coordinate) {
+    return axes.reduce((nextConfig, axis, index) => setValueAtPath(nextConfig, axis.path, coordinate.values[index] ?? getValueAtPath(nextConfig, axis.path)), config);
+}
+function defaultNeighborhoodWindow(axis) {
+    const step = resolveStep(axis);
+    return {
+        min: axis.current - NEIGHBORHOOD_STEPS * step,
+        max: axis.current + NEIGHBORHOOD_STEPS * step,
+        step,
+    };
+}
+function resolveStep(axis) {
+    if (axis.window && axis.window.step > 0) {
+        return axis.window.step;
+    }
+    const span = axis.min !== undefined && axis.max !== undefined && axis.max > axis.min
+        ? (axis.max - axis.min) / (MAX_RANGE_POINTS - 1)
+        : Math.abs(axis.current) > 0
+            ? Math.abs(axis.current) * 0.1
+            : 1;
+    if (axis.isInteger) {
+        return Math.max(1, Math.round(span));
+    }
+    const rounded = Number(span.toPrecision(2));
+    return rounded > 0 ? rounded : 0.1;
+}
+function normalizeExplicitValues(axis, values) {
+    return [
+        ...new Set(values
+            .filter((value) => Number.isFinite(value))
+            .map((value) => roundValue(value, axis.isInteger))
+            .filter((value) => (!axis.isInteger || Number.isInteger(value)) &&
+            isWithinBounds(value, axis))),
+    ].sort((left, right) => left - right);
+}
+function buildWindowValues(axis, window) {
+    const step = window.step;
+    if (!(step > 0) || !Number.isFinite(step)) {
+        return [];
+    }
+    let min = window.min;
+    let max = window.max;
+    if (min > max) {
+        [min, max] = [max, min];
+    }
+    const raw = [];
+    const maxPoints = MAX_RANGE_POINTS * 20;
+    for (let value = min, guard = 0; value <= max + EPSILON && guard < maxPoints; value += step, guard += 1) {
+        raw.push(roundValue(value, axis.isInteger));
+    }
+    const current = roundValue(axis.current, axis.isInteger);
+    if (isWithinDraftWindow(current, min, max)) {
+        raw.push(current);
+    }
+    const unique = [
+        ...new Set(raw
+            .map((value) => clamp(value, axis.min, axis.max))
+            .filter((value) => Number.isFinite(value) &&
+            (!axis.isInteger || Number.isInteger(value)) &&
+            isWithinDraftWindow(value, min, max) &&
+            isWithinBounds(value, axis))),
+    ].sort((left, right) => left - right);
+    return unique.length > MAX_RANGE_POINTS
+        ? downsample(unique, MAX_RANGE_POINTS, axis.current)
+        : unique;
+}
+function roundValue(value, isInteger) {
+    return isInteger ? Math.round(value) : Number(value.toFixed(6));
+}
+function clamp(value, min, max) {
+    let next = value;
+    if (min !== undefined) {
+        next = Math.max(min, next);
+    }
+    if (max !== undefined) {
+        next = Math.min(max, next);
+    }
+    return next;
+}
+function isWithinDraftWindow(value, min, max) {
+    return value + EPSILON >= min && value - EPSILON <= max;
+}
+function isWithinBounds(value, axis) {
+    if (axis.min !== undefined &&
+        (axis.minExclusive ? value <= axis.min : value < axis.min)) {
+        return false;
+    }
+    if (axis.max !== undefined &&
+        (axis.maxExclusive ? value >= axis.max : value > axis.max)) {
+        return false;
+    }
+    return true;
+}
+function downsample(values, limit, keep) {
+    if (values.length <= limit) {
+        return [...values];
+    }
+    const safeLimit = Math.max(2, Math.min(limit, values.length));
+    const selectedIndices = new Set();
+    for (let slot = 0; slot < safeLimit; slot += 1) {
+        selectedIndices.add(Math.round((slot * (values.length - 1)) / (safeLimit - 1)));
+    }
+    const keepIndex = values.indexOf(keep);
+    if (keepIndex >= 0 && !selectedIndices.has(keepIndex)) {
+        const replaceable = [...selectedIndices]
+            .filter((index) => index !== 0 && index !== values.length - 1)
+            .sort((left, right) => Math.abs(left - keepIndex) - Math.abs(right - keepIndex))[0];
+        if (replaceable !== undefined) {
+            selectedIndices.delete(replaceable);
+        }
+        selectedIndices.add(keepIndex);
+    }
+    for (let index = 0; selectedIndices.size < safeLimit; index += 1) {
+        selectedIndices.add(index);
+    }
+    return [...selectedIndices]
+        .sort((left, right) => left - right)
+        .slice(0, safeLimit)
+        .map((index) => values[index]);
+}
+function cartesianCoordinates(axes) {
+    return axes.reduce((coordinates, values) => coordinates.flatMap((coordinate) => values.map((value) => ({
+        values: [...coordinate.values, value],
+    }))), [{ values: [] }]);
+}
+function localWindow(values, center) {
+    if (values.length <= FAST_SWEEP_AXIS_POINTS) {
+        return [...values];
+    }
+    const exactIndex = values.indexOf(center);
+    const centerIndex = exactIndex >= 0
+        ? exactIndex
+        : values.reduce((nearest, value, index) => Math.abs(value - center) <
+            Math.abs((values[nearest] ?? center) - center)
+            ? index
+            : nearest, 0);
+    const start = Math.max(0, Math.min(centerIndex - 1, values.length - FAST_SWEEP_AXIS_POINTS));
+    return values.slice(start, start + FAST_SWEEP_AXIS_POINTS);
+}
+function coordinateKey(coordinate) {
+    return coordinate.values.join("\u0000");
+}
+function product(values) {
+    return values.reduce((total, value) => total * value, 1);
+}
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseArrayIndex(segment) {
+    if (!/^\d+$/.test(segment)) {
+        return null;
+    }
+    const index = Number(segment);
+    return Number.isInteger(index) && index >= 0 ? index : null;
+}
+function getValueAtPath(root, path) {
+    let current = root;
+    for (const segment of path) {
+        if (Array.isArray(current)) {
+            const index = parseArrayIndex(segment);
+            if (index === null) {
+                return undefined;
+            }
+            current = current[index];
+            continue;
+        }
+        if (!isPlainRecord(current)) {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+function containerForPathTail(existing, nextSegment) {
+    if (Array.isArray(existing) || isPlainRecord(existing)) {
+        return existing;
+    }
+    return parseArrayIndex(nextSegment ?? "") !== null ? [] : {};
+}
+function setValueAtPathNode(root, path, value) {
+    if (path.length === 0) {
+        return value;
+    }
+    const [head, ...tail] = path;
+    if (!head) {
+        throw new Error("Sweep config path segment must not be empty.");
+    }
+    if (Array.isArray(root)) {
+        const index = parseArrayIndex(head);
+        if (index === null) {
+            throw new Error(`Expected array index path segment, got "${head}".`);
+        }
+        const next = root.slice();
+        if (tail.length === 0) {
+            while (next.length <= index) {
+                next.push(null);
+            }
+            next[index] = value;
+            return next;
+        }
+        const child = containerForPathTail(next[index], tail[0]);
+        while (next.length <= index) {
+            next.push(null);
+        }
+        next[index] = setValueAtPathNode(child, tail, value);
+        return next;
+    }
+    if (!isPlainRecord(root)) {
+        return setValueAtPathNode(containerForPathTail(undefined, head), path, value);
+    }
+    const nextRoot = { ...root };
+    if (tail.length === 0) {
+        nextRoot[head] = value;
+        return nextRoot;
+    }
+    nextRoot[head] = setValueAtPathNode(containerForPathTail(nextRoot[head], tail[0]), tail, value);
+    return nextRoot;
+}
+function setValueAtPath(root, path, value) {
+    if (path.length === 0) {
+        if (!isPlainRecord(value)) {
+            throw new Error("Root config must be an object.");
+        }
+        return value;
+    }
+    return setValueAtPathNode(root, path, value);
+}

package/dist/engine-backtest/sweep-kernel/results.d.ts

@@ -0,0 +1,72 @@
+import type { SweepCoordinate } from "./types";
+export interface SweepPointMetrics {
+    readonly returnPct: number;
+    readonly maxDrawdownPct: number;
+    readonly sharpeRatio: number;
+    readonly winRatePct: number;
+    readonly maxLeverage?: number;
+    readonly liquidationCount: number;
+    readonly netPnl: number;
+    readonly finalEquity: number;
+    readonly tradeCount: number;
+}
+export interface SweepMetricsSource {
+    readonly returnPct: number;
+    readonly maxDrawdownPct: number;
+    readonly sharpeRatio: number;
+    readonly winRatePct: number;
+    readonly maxLeverage?: number;
+    readonly liquidationCount?: number;
+    readonly liquidated?: boolean;
+    readonly netPnl: number;
+    readonly finalEquity: number;
+    readonly tradeCount: number;
+}
+export interface SweepPoint {
+    readonly coordinate: SweepCoordinate;
+    readonly status: "ok" | "failed";
+    readonly metrics?: SweepPointMetrics;
+    readonly error?: string;
+}
+export type IslandRiskLevel = "low" | "low_medium" | "medium" | "high";
+export interface SweepMetricPoint {
+    readonly value: number;
+    readonly returnPct: number;
+    readonly maxDrawdownPct: number;
+    readonly liquidationCount: number;
+}
+export interface ScoredSweepPoint extends SweepMetricPoint {
+    readonly isCenter: boolean;
+    readonly islandScore: number;
+    readonly riskLevel: IslandRiskLevel;
+}
+export interface IslandCounterexample {
+    readonly counterValue: number;
+    readonly centerReturnPct: number;
+    readonly counterReturnPct: number;
+    readonly centerLiquidationCount: number;
+    readonly counterLiquidationCount: number;
+}
+export interface IslandWarning {
+    readonly centerValue: number;
+    readonly islandScore: number;
+    readonly riskLevel: IslandRiskLevel;
+    readonly counterexamples: readonly IslandCounterexample[];
+}
+export interface IslandAnalysis {
+    readonly points: readonly ScoredSweepPoint[];
+    readonly warning: IslandWarning | null;
+    readonly overallScore: number;
+    readonly overallRiskLevel: IslandRiskLevel;
+}
+export declare function extractSweepMetrics(source: SweepMetricsSource): SweepPointMetrics;
+export declare function selectBestNonLiquidatedPoint(points: readonly SweepPoint[]): {
+    readonly coordinate: SweepCoordinate;
+    readonly returnPct: number;
+} | null;
+export declare function resolveIslandRiskLevel(score: number): IslandRiskLevel;
+/**
+ * Score each swept point by how sharply it deviates from its neighbors, then
+ * flag the point closest to `centerValue` when it sits on a fragile island.
+ */
+export declare function analyzeSweepIsland(points: readonly SweepMetricPoint[], centerValue: number): IslandAnalysis;