desic-okx-agent 0.2.1 → 0.3.1

package/dist/strategy/optimize.js

@@ -0,0 +1,113 @@
+import { RuntimeError } from "../core/errors.js";
+import { ONE_MINUTE_MS } from "../bars/types.js";
+import { MINIMUM_ANNUALIZATION_DAYS } from "./constants.js";
+/**
+ * Share of the window used to search. The rest is held back.
+ *
+ * Splitting is the whole point of the exercise rather than a refinement: the
+ * best parameters over any window are partly fitted to its noise, so a figure
+ * measured on the same bars that chose them is not evidence. 7:3 keeps enough
+ * bars to search over while leaving a segment long enough to disagree.
+ */
+export const TRAIN_FRACTION = 0.7;
+/**
+ * Smallest segment worth evaluating, in bars.
+ *
+ * A one-day validation segment produces a return that a single trade decides,
+ * and ranking on that is ranking on coincidence.
+ */
+export const MINIMUM_SEGMENT_BARS = 1_440;
+/**
+ * Splits an evaluation window into a training and a validation segment.
+ *
+ * The two are contiguous and disjoint: the validation segment begins on the
+ * minute after the training segment ends. Overlapping them by even one bar would
+ * let a candidate be credited for a bar it was chosen on.
+ */
+export function splitWindow(evaluationStart, evaluationEnd) {
+    if (evaluationEnd <= evaluationStart) {
+        throw new RuntimeError("VALIDATION", "The optimization window must end after it starts");
+    }
+    const totalBars = Math.floor((evaluationEnd - evaluationStart) / ONE_MINUTE_MS) + 1;
+    const trainBars = Math.floor(totalBars * TRAIN_FRACTION);
+    const validationBars = totalBars - trainBars;
+    if (trainBars < MINIMUM_SEGMENT_BARS || validationBars < MINIMUM_SEGMENT_BARS) {
+        const days = ((MINIMUM_SEGMENT_BARS / TRAIN_FRACTION) * ONE_MINUTE_MS) / 86_400_000;
+        throw new RuntimeError("VALIDATION", `A ${TRAIN_FRACTION * 100}/${Math.round((1 - TRAIN_FRACTION) * 100)} split of ${totalBars} bars leaves segments below the ${MINIMUM_SEGMENT_BARS}-bar minimum. Use a window of at least ${Math.ceil(days)} days.`, false, { totalBars, trainBars, validationBars, minimumBars: MINIMUM_SEGMENT_BARS });
+    }
+    const trainEnd = evaluationStart + (trainBars - 1) * ONE_MINUTE_MS;
+    return {
+        trainStart: evaluationStart,
+        trainEnd,
+        validationStart: trainEnd + ONE_MINUTE_MS,
+        validationEnd: evaluationEnd,
+        trainBars,
+        validationBars
+    };
+}
+/**
+ * Scores one candidate from its validation-segment metrics.
+ *
+ * Calmar is the intended measure, but it divides an annualized return by
+ * drawdown, and the engine withholds annualized figures below
+ * `MINIMUM_ANNUALIZATION_DAYS` because extrapolating a short window produces
+ * five-digit percentages that read as precision and carry none. Rather than fall
+ * back silently, the basis used travels with the score and is printed beside the
+ * table: a column headed "calmar" that is sometimes a different quantity is worse
+ * than an honest label.
+ *
+ * Every basis keeps the sign of the return, so a losing candidate can never
+ * outrank a profitable one through a small denominator.
+ */
+export function rankCandidate(metrics) {
+    if (!metrics)
+        return { score: Number.NEGATIVE_INFINITY, basis: "return" };
+    const calmar = numeric(metrics.calmar);
+    if (calmar !== null && metrics.annualizationReliable === true) {
+        return { score: calmar, basis: "calmar" };
+    }
+    const returnPct = numeric(metrics.returnPct) ?? 0;
+    const drawdownPct = numeric(metrics.maxDrawdownPct) ?? 0;
+    // A run that never drew down has no risk measure to divide by. Ranking it by
+    // return alone is the honest reading, and it is labelled as such.
+    if (drawdownPct <= 0)
+        return { score: returnPct, basis: "return" };
+    return { score: returnPct / drawdownPct, basis: "return_over_drawdown" };
+}
+/** Message-bundle-free description of a basis, for the report footer. */
+export function describeRankBasis(basis, validationDays) {
+    switch (basis) {
+        case "calmar":
+            return "ranked by validation Calmar (annualized return / max drawdown)";
+        case "return_over_drawdown":
+            return `ranked by validation return / max drawdown; Calmar needs ${MINIMUM_ANNUALIZATION_DAYS}+ days and this segment is ${validationDays.toFixed(1)}`;
+        default:
+            return "ranked by validation return; no candidate drew down, so there is no risk denominator";
+    }
+}
+export function verdictFor(train, validation) {
+    if (!train || !validation)
+        return "failed";
+    const trainReturn = numeric(train.returnPct) ?? 0;
+    const validationReturn = numeric(validation.returnPct) ?? 0;
+    if (trainReturn > 0 && validationReturn <= 0)
+        return "overfit";
+    if (validationReturn <= 0)
+        return "weak";
+    // Keeping less than a third of the training edge is decay worth flagging even
+    // though the sign held.
+    if (trainReturn > 0 && validationReturn < trainReturn / 3)
+        return "overfit";
+    // Profitable only on the segment it was not chosen on. Nothing was carried
+    // across the split, so there is nothing the split confirmed.
+    if (trainReturn <= 0)
+        return "unexplained";
+    return "holds";
+}
+function numeric(value) {
+    if (value === null || value === undefined)
+        return null;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+//# sourceMappingURL=optimize.js.map

package/dist/strategy/optimize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimize.js","sourceRoot":"","sources":["../../src/strategy/optimize.ts"],"names":[],"mappings":"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"}

package/dist/strategy/parameter-space.d.ts

@@ -0,0 +1,59 @@
+/** One tunable parameter's inclusive range, and the step between candidates. */
+export interface ParameterRange {
+    min: number;
+    max: number;
+    step: number;
+}
+export type ParameterSpace = Record<string, ParameterRange>;
+/**
+ * Ceiling on the full cartesian product.
+ *
+ * A wide space is almost always an accident rather than an intent: three
+ * parameters at ten values each is already a thousand candidates, and every one
+ * of them is simulated twice. Refusing is more useful than starting something
+ * that finishes in hours.
+ */
+export declare const MAX_COMBINATIONS = 5000;
+/** Below two candidates there is nothing to compare. */
+export declare const MIN_COMBINATIONS = 2;
+/** Candidate budget used when a caller does not choose one. */
+export declare const DEFAULT_BUDGET = 100;
+/** Largest budget accepted. Beyond this the wait outgrows the interactive loop. */
+export declare const MAX_BUDGET = 1000;
+/**
+ * Validates a declared space against the parameters the strategy actually reads.
+ *
+ * A range for a parameter the strategy ignores is silently useless: every
+ * candidate behaves identically, and whichever one ranks first is noise
+ * presented as a finding. That is rejected rather than dropped, which is why
+ * this needs the strategy's own parameter defaults to check against.
+ */
+export declare function parseParameterSpace(raw: unknown, strategyParams: Record<string, unknown>): ParameterSpace;
+/**
+ * Every value one parameter takes, inclusive of both bounds.
+ *
+ * Each value is computed from the index rather than by repeated addition, and
+ * rounded, because accumulating a step such as 0.1 drifts into values like
+ * 2.7999999999999996 that then appear verbatim in the report.
+ */
+export declare function valuesOf(range: ParameterRange): number[];
+export declare function countCombinations(space: ParameterSpace): number;
+/** Describes a space in one line, for the run summary and the report header. */
+export declare function describeSpace(space: ParameterSpace): string;
+/** Keys in a fixed order, so candidate indices mean the same thing on a rerun. */
+export declare function sortedKeys(space: ParameterSpace): string[];
+/**
+ * Chooses which combinations to evaluate.
+ *
+ * Deterministic by construction: the seed is derived from the space and the
+ * budget, so the same request always produces the same candidate set. A rerun is
+ * then comparable to the original rather than a fresh lottery — the same reason a
+ * run records a `dataSnapshotId`.
+ *
+ * When the product exceeds the budget this is a Latin hypercube rather than plain
+ * random sampling: each parameter's values are dealt out across the slots and
+ * shuffled independently, so every value of every parameter is evaluated at least
+ * once. Random sampling can leave one untried, and a search that never evaluated
+ * `slowPeriod: 200` cannot report anything about it.
+ */
+export declare function sampleCandidates(space: ParameterSpace, budget: number): Array<Record<string, number>>;

package/dist/strategy/parameter-space.js

@@ -0,0 +1,221 @@
+import { RuntimeError } from "../core/errors.js";
+/**
+ * Ceiling on the full cartesian product.
+ *
+ * A wide space is almost always an accident rather than an intent: three
+ * parameters at ten values each is already a thousand candidates, and every one
+ * of them is simulated twice. Refusing is more useful than starting something
+ * that finishes in hours.
+ */
+export const MAX_COMBINATIONS = 5_000;
+/** Below two candidates there is nothing to compare. */
+export const MIN_COMBINATIONS = 2;
+/** Candidate budget used when a caller does not choose one. */
+export const DEFAULT_BUDGET = 100;
+/** Largest budget accepted. Beyond this the wait outgrows the interactive loop. */
+export const MAX_BUDGET = 1_000;
+/**
+ * Validates a declared space against the parameters the strategy actually reads.
+ *
+ * A range for a parameter the strategy ignores is silently useless: every
+ * candidate behaves identically, and whichever one ranks first is noise
+ * presented as a finding. That is rejected rather than dropped, which is why
+ * this needs the strategy's own parameter defaults to check against.
+ */
+export function parseParameterSpace(raw, strategyParams) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw new RuntimeError("VALIDATION", "A parameter space must be an object of { min, max, step } ranges, keyed by parameter name");
+    }
+    const entries = Object.entries(raw);
+    if (entries.length === 0) {
+        throw new RuntimeError("VALIDATION", "A parameter space needs at least one parameter");
+    }
+    const space = {};
+    for (const [key, value] of entries) {
+        if (!Object.hasOwn(strategyParams, key)) {
+            // An empty baseline is the common case, and "the strategy declares no
+            // parameter" reads as a fault in the strategy when the real cause is a
+            // missing --params file. Name the actual omission.
+            const available = Object.keys(strategyParams).sort();
+            throw new RuntimeError("VALIDATION", available.length === 0
+                ? `No baseline parameters were provided, so '${key}' cannot be tuned. Pass the strategy's own defaults with --params: a space is checked against them, because tuning a key the strategy never reads leaves every candidate identical.`
+                : `The strategy declares no parameter '${key}', so tuning it would change nothing`, false, { available });
+        }
+        const current = strategyParams[key];
+        if (typeof current !== "number" || !Number.isFinite(current)) {
+            throw new RuntimeError("VALIDATION", `Parameter '${key}' is not a finite number, so it has no numeric range to search`);
+        }
+        space[key] = parseRange(key, value);
+    }
+    const total = countCombinations(space);
+    if (total < MIN_COMBINATIONS) {
+        throw new RuntimeError("VALIDATION", `This space yields ${total} candidate, and at least ${MIN_COMBINATIONS} are needed to compare anything`);
+    }
+    if (total > MAX_COMBINATIONS) {
+        throw new RuntimeError("VALIDATION", `This space yields ${total} combinations, above the ${MAX_COMBINATIONS} limit. Narrow a range or widen a step.`, false, { combinations: total, limit: MAX_COMBINATIONS });
+    }
+    return space;
+}
+function parseRange(key, value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new RuntimeError("VALIDATION", `The range for '${key}' must be an object with min, max, and step`);
+    }
+    const record = value;
+    const min = finite(record.min, `${key}.min`);
+    const max = finite(record.max, `${key}.max`);
+    const step = finite(record.step, `${key}.step`);
+    if (step <= 0)
+        throw new RuntimeError("VALIDATION", `${key}.step must be greater than zero`);
+    if (max < min)
+        throw new RuntimeError("VALIDATION", `${key}.max must be at or above ${key}.min`);
+    if (max > min && step > max - min) {
+        throw new RuntimeError("VALIDATION", `${key}.step of ${step} exceeds its ${min}..${max} range, so only one value would ever be tried`);
+    }
+    return { min, max, step };
+}
+function finite(value, label) {
+    // `Number("")` is 0 and `Number(null)` is 0, so both are rejected explicitly:
+    // an omitted bound must not silently become a legitimate zero.
+    if (value === undefined || value === null || value === "") {
+        throw new RuntimeError("VALIDATION", `${label} is required and must be a finite number`);
+    }
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) {
+        throw new RuntimeError("VALIDATION", `${label} must be a finite number`);
+    }
+    return parsed;
+}
+/**
+ * Every value one parameter takes, inclusive of both bounds.
+ *
+ * Each value is computed from the index rather than by repeated addition, and
+ * rounded, because accumulating a step such as 0.1 drifts into values like
+ * 2.7999999999999996 that then appear verbatim in the report.
+ */
+export function valuesOf(range) {
+    const count = Math.floor((range.max - range.min) / range.step + 1e-9);
+    return Array.from({ length: count + 1 }, (_, index) => Number((range.min + index * range.step).toFixed(10)));
+}
+export function countCombinations(space) {
+    return Object.values(space).reduce((total, range) => total * valuesOf(range).length, 1);
+}
+/** Describes a space in one line, for the run summary and the report header. */
+export function describeSpace(space) {
+    return sortedKeys(space)
+        .map((key) => `${key} ${space[key].min}..${space[key].max} step ${space[key].step}`)
+        .join(", ");
+}
+/** Keys in a fixed order, so candidate indices mean the same thing on a rerun. */
+export function sortedKeys(space) {
+    return Object.keys(space).sort();
+}
+/**
+ * Chooses which combinations to evaluate.
+ *
+ * Deterministic by construction: the seed is derived from the space and the
+ * budget, so the same request always produces the same candidate set. A rerun is
+ * then comparable to the original rather than a fresh lottery — the same reason a
+ * run records a `dataSnapshotId`.
+ *
+ * When the product exceeds the budget this is a Latin hypercube rather than plain
+ * random sampling: each parameter's values are dealt out across the slots and
+ * shuffled independently, so every value of every parameter is evaluated at least
+ * once. Random sampling can leave one untried, and a search that never evaluated
+ * `slowPeriod: 200` cannot report anything about it.
+ */
+export function sampleCandidates(space, budget) {
+    if (!Number.isInteger(budget) || budget < MIN_COMBINATIONS) {
+        throw new RuntimeError("VALIDATION", `The candidate budget must be a whole number of at least ${MIN_COMBINATIONS}`);
+    }
+    const keys = sortedKeys(space);
+    const grids = keys.map((key) => valuesOf(space[key]));
+    const total = grids.reduce((product, values) => product * values.length, 1);
+    if (total <= budget) {
+        return Array.from({ length: total }, (_, index) => combinationAt(keys, grids, index));
+    }
+    // Covering every value of the widest parameter takes at least that many
+    // candidates. Below it the guarantee is arithmetically impossible, so the
+    // budget is refused rather than quietly weakened.
+    const widest = Math.max(...grids.map((values) => values.length));
+    if (budget < widest) {
+        const wide = keys[grids.findIndex((values) => values.length === widest)];
+        throw new RuntimeError("VALIDATION", `A budget of ${budget} cannot cover '${wide}', which has ${widest} values. Use a budget of at least ${widest}, or widen that step.`, false, { budget, required: widest, parameter: wide });
+    }
+    const random = seededRandom(`${JSON.stringify(orderedSpace(space, keys))}|${budget}`);
+    // One shuffled column per parameter: value indices dealt round-robin across the
+    // slots, then permuted. Independent shuffles keep the axes from pairing up
+    // diagonally, which would only ever test fast and slow periods in lockstep.
+    const columns = grids.map((values) => {
+        const slots = Array.from({ length: budget }, (_, slot) => slot % values.length);
+        for (let index = slots.length - 1; index > 0; index -= 1) {
+            const swap = Math.floor(random() * (index + 1));
+            [slots[index], slots[swap]] = [slots[swap], slots[index]];
+        }
+        return slots;
+    });
+    const chosen = [];
+    const seen = new Set();
+    const add = (candidate) => {
+        const signature = keys.map((key) => candidate[key]).join("|");
+        // Dropping a duplicate cannot lose coverage: an identical candidate carrying
+        // the same values is already kept.
+        if (seen.has(signature))
+            return;
+        seen.add(signature);
+        chosen.push(candidate);
+    };
+    for (let slot = 0; slot < budget; slot += 1) {
+        const candidate = {};
+        keys.forEach((key, axis) => {
+            candidate[key] = grids[axis][columns[axis][slot]];
+        });
+        add(candidate);
+    }
+    // Collisions leave the budget short. Top up by walking the product with a
+    // stride so the extra candidates spread out instead of clustering at index 0,
+    // then close any remainder in order — both passes stay deterministic.
+    const stride = Math.max(1, Math.floor(total / budget));
+    for (let index = 0; index < total && chosen.length < budget; index += stride) {
+        add(combinationAt(keys, grids, index));
+    }
+    for (let index = 0; index < total && chosen.length < budget; index += 1) {
+        add(combinationAt(keys, grids, index));
+    }
+    return chosen;
+}
+/** Mixed-radix decoding of a flat index into one combination. */
+function combinationAt(keys, grids, index) {
+    const candidate = {};
+    let remainder = index;
+    for (let axis = keys.length - 1; axis >= 0; axis -= 1) {
+        const values = grids[axis];
+        candidate[keys[axis]] = values[remainder % values.length];
+        remainder = Math.floor(remainder / values.length);
+    }
+    return candidate;
+}
+function orderedSpace(space, keys) {
+    return keys.map((key) => [key, space[key]]);
+}
+/**
+ * Small deterministic generator, seeded from text.
+ *
+ * `Math.random` cannot be used here: the candidate set has to be reproducible
+ * from the request alone. FNV-1a then mulberry32, both fixed integer arithmetic,
+ * so the sequence is identical on every platform.
+ */
+function seededRandom(seed) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < seed.length; index += 1) {
+        hash ^= seed.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    let state = hash >>> 0;
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let value = Math.imul(state ^ (state >>> 15), 1 | state);
+        value = (value + Math.imul(value ^ (value >>> 7), 61 | value)) ^ value;
+        return ((value ^ (value >>> 14)) >>> 0) / 4_294_967_296;
+    };
+}
+//# sourceMappingURL=parameter-space.js.map

package/dist/strategy/parameter-space.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parameter-space.js","sourceRoot":"","sources":["../../src/strategy/parameter-space.ts"],"names":[],"mappings":"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"}

package/dist/strategy/python-bridge.d.ts

@@ -0,0 +1,24 @@
+export interface PythonInvocation {
+    interpreter: string;
+    engineRoot: string;
+    request: unknown;
+    timeoutMs?: number;
+    onProgress?: (progress: {
+        done: number;
+        total: number;
+        pct: number;
+    }) => void;
+    signal?: AbortSignal;
+}
+export interface PythonResponse {
+    ok: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Runs one strategy request in a short-lived Python process.
+ *
+ * `-I` is deliberate: it ignores PYTHONPATH, the user site directory, and other
+ * ambient configuration, so a run cannot be redirected by the environment.
+ * `-u` keeps progress lines flowing instead of sitting in a pipe buffer.
+ */
+export declare function invokePython(invocation: PythonInvocation): Promise<PythonResponse>;

package/dist/strategy/python-bridge.js

@@ -0,0 +1,114 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { RuntimeError } from "../core/errors.js";
+/** stdout is a single JSON object; a larger reply means something is wrong. */
+const MAX_STDOUT_BYTES = 64 * 1024 * 1024;
+const MAX_STDERR_BYTES = 1 * 1024 * 1024;
+/**
+ * Runs one strategy request in a short-lived Python process.
+ *
+ * `-I` is deliberate: it ignores PYTHONPATH, the user site directory, and other
+ * ambient configuration, so a run cannot be redirected by the environment.
+ * `-u` keeps progress lines flowing instead of sitting in a pipe buffer.
+ */
+export async function invokePython(invocation) {
+    const { interpreter, engineRoot, request, onProgress, signal } = invocation;
+    const timeoutMs = invocation.timeoutMs ?? 30 * 60_000;
+    const entry = path.join(engineRoot, "main.py");
+    return new Promise((resolve, reject) => {
+        const child = spawn(interpreter, ["-I", "-u", entry], {
+            stdio: ["pipe", "pipe", "pipe"],
+            // A strategy has no business reading the repository it was launched from.
+            cwd: engineRoot
+        });
+        const stdout = [];
+        let stdoutBytes = 0;
+        let stderrText = "";
+        let stderrBuffer = "";
+        let settled = false;
+        let timedOut = false;
+        const finish = (error, value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            if (error)
+                reject(error);
+            else
+                resolve(value);
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, timeoutMs);
+        const onAbort = () => {
+            child.kill("SIGKILL");
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        child.stdout.on("data", (chunk) => {
+            stdoutBytes += chunk.length;
+            if (stdoutBytes > MAX_STDOUT_BYTES) {
+                child.kill("SIGKILL");
+                finish(new RuntimeError("INTERNAL", "The strategy engine produced an oversized response"));
+                return;
+            }
+            stdout.push(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderrBuffer += chunk.toString("utf8");
+            const lines = stderrBuffer.split("\n");
+            stderrBuffer = lines.pop() ?? "";
+            for (const line of lines) {
+                if (line.startsWith("PROGRESS ")) {
+                    try {
+                        const parsed = JSON.parse(line.slice("PROGRESS ".length));
+                        onProgress?.({
+                            done: Number(parsed.done ?? 0),
+                            total: Number(parsed.total ?? 0),
+                            pct: Number(parsed.pct ?? 0)
+                        });
+                    }
+                    catch {
+                        // A malformed progress line is diagnostic noise, not a failure.
+                    }
+                    continue;
+                }
+                // Keep stderr: discarding it makes an unexpected exit undiagnosable.
+                if (stderrText.length < MAX_STDERR_BYTES)
+                    stderrText += `${line}\n`;
+            }
+        });
+        child.on("error", (error) => {
+            finish(new RuntimeError("CAPABILITY_UNAVAILABLE", `Could not start the Python strategy engine (${interpreter}): ${error.message}`));
+        });
+        child.on("close", (code, killSignal) => {
+            if (timedOut) {
+                finish(new RuntimeError("INTERNAL", `The strategy engine exceeded its ${timeoutMs}ms time limit`));
+                return;
+            }
+            if (signal?.aborted) {
+                finish(new RuntimeError("INTERNAL", "The strategy run was cancelled"));
+                return;
+            }
+            const text = Buffer.concat(stdout).toString("utf8").trim();
+            if (!text) {
+                const detail = stderrText.trim() || `exit code ${code}${killSignal ? ` (${killSignal})` : ""}`;
+                finish(new RuntimeError("INTERNAL", `The strategy engine produced no output: ${detail}`));
+                return;
+            }
+            try {
+                finish(null, JSON.parse(text));
+            }
+            catch {
+                finish(new RuntimeError("INTERNAL", `The strategy engine returned invalid JSON: ${text.slice(0, 200)}`));
+            }
+        });
+        child.stdin.on("error", () => {
+            // The close handler reports the real cause; a broken pipe here is a
+            // symptom of the child having already exited.
+        });
+        child.stdin.end(JSON.stringify(request));
+    });
+}
+//# sourceMappingURL=python-bridge.js.map

package/dist/strategy/python-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-bridge.js","sourceRoot":"","sources":["../../src/strategy/python-bridge.ts"],"names":[],"mappings":"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"}

package/dist/strategy/schema.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Storage for queued and completed strategy runs.
+ *
+ * The equity curve is stored as chunked binary float64 blocks rather than JSON rows.
+ * Every value round-trips bit-for-bit, which decimal JSON text does not guarantee, and
+ * a measured 344k-point curve is 2.4 MB here against roughly 40 MB as JSON objects.
+ *
+ * `codec` names the layout of each chunk's payload. It is read rather than inferred so
+ * that chunks written by an earlier build keep decoding correctly — see `series-codec.ts`.
+ */
+export declare const STRATEGY_SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS strategy_runs (\n  id TEXT PRIMARY KEY,\n  kind TEXT NOT NULL,\n  status TEXT NOT NULL,\n  strategy_name TEXT NOT NULL,\n  strategy_hash TEXT NOT NULL,\n  strategy_source TEXT NOT NULL,\n  inst_id TEXT NOT NULL,\n  request_json TEXT NOT NULL,\n  data_snapshot_id TEXT,\n  bar_count INTEGER NOT NULL DEFAULT 0,\n  preload_bars INTEGER NOT NULL DEFAULT 0,\n  progress_pct REAL NOT NULL DEFAULT 0,\n  eta_ms INTEGER,\n  metrics_json TEXT,\n  -- The assumptions the run actually used. Stored per run because settings can\n  -- change between runs, and a report that cannot say what it assumed is not\n  -- comparable to any other report.\n  assumptions_json TEXT,\n  error TEXT,\n  created_at INTEGER NOT NULL,\n  started_at INTEGER,\n  finished_at INTEGER\n);\n\nCREATE INDEX IF NOT EXISTS idx_strategy_runs_created\n  ON strategy_runs(created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_strategy_runs_status\n  ON strategy_runs(status, created_at DESC);\n\nCREATE TABLE IF NOT EXISTS strategy_run_series (\n  run_id TEXT NOT NULL,\n  chunk_index INTEGER NOT NULL,\n  from_point INTEGER NOT NULL,\n  to_point INTEGER NOT NULL,\n  start_ms INTEGER NOT NULL,\n  step_ms INTEGER NOT NULL,\n  payload BLOB NOT NULL,\n  codec TEXT NOT NULL DEFAULT 'f64x4',\n  PRIMARY KEY(run_id, chunk_index)\n) WITHOUT ROWID;\n\nCREATE TABLE IF NOT EXISTS strategy_run_trades (\n  run_id TEXT NOT NULL,\n  seq INTEGER NOT NULL,\n  trade_json TEXT NOT NULL,\n  PRIMARY KEY(run_id, seq)\n) WITHOUT ROWID;\n\nCREATE TABLE IF NOT EXISTS strategy_run_actions (\n  run_id TEXT NOT NULL,\n  seq INTEGER NOT NULL,\n  action_json TEXT NOT NULL,\n  PRIMARY KEY(run_id, seq)\n) WITHOUT ROWID;\n\n-- One row per evaluated parameter combination of an optimize run.\n--\n-- Training and validation metrics are stored separately rather than merged into\n-- one figure. The gap between them is the finding: a candidate that earned its\n-- ranking and one that memorized the training segment are indistinguishable from\n-- a single number.\nCREATE TABLE IF NOT EXISTS strategy_optimization_candidates (\n  run_id TEXT NOT NULL,\n  candidate_index INTEGER NOT NULL,\n  params_json TEXT NOT NULL,\n  status TEXT NOT NULL,\n  train_metrics_json TEXT,\n  validation_metrics_json TEXT,\n  -- Validation-segment score. Null while queued, and for a candidate that failed.\n  rank_score REAL,\n  -- Which formula produced rank_score, because it is not always Calmar.\n  rank_basis TEXT,\n  verdict TEXT,\n  error TEXT,\n  PRIMARY KEY(run_id, candidate_index)\n) WITHOUT ROWID;\n\n-- Ranking reads this in score order, so it is indexed rather than sorted per read.\nCREATE INDEX IF NOT EXISTS idx_optimization_rank\n  ON strategy_optimization_candidates(run_id, rank_score DESC);\n";