@qtsurfer/api-client 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -44,7 +44,7 @@ type InstrumentListMeta = {
     /**
      * The market segment served in `data`
      */
-    segment: 'spot' | 'futures';
+    segment: "spot" | "futures";
 };
 /**
  * HAL `_links` — segment discovery for the instruments listing
@@ -152,7 +152,7 @@ type Exchange = {
 /**
  * Managed exchange data sources available for backtesting.
  */
-type DataSourceType = 'ticker';
+type DataSourceType = "ticker";
 type PrepareRequest = {
     instrument: Instrument;
     /**
@@ -179,7 +179,7 @@ type PrepareRequest = {
      * labels return `400`.
      *
      */
-    cadence?: '1s' | '5s' | '1m' | '5m' | '15m' | '1h' | '4h' | '1d';
+    cadence?: "1s" | "5s" | "1m" | "5m" | "15m" | "1h" | "4h" | "1d";
 };
 /**
  * Information about a single job
@@ -196,7 +196,7 @@ type JobState = {
      * `PrepareJobState.coverageRatio`, not by polling.
      *
      */
-    status: 'New' | 'Started' | 'Completed' | 'Aborted' | 'Failed';
+    status: "New" | "Started" | "Completed" | "Aborted" | "Failed";
     /**
      * Detailed status information, if available
      */
@@ -270,7 +270,7 @@ type PrepareJobState = JobState & {
          * instrument did not trade that hour. `unknown`: no data to classify by.
          *
          */
-        rationale?: 'pending_conversion' | 'low_activity' | 'unknown';
+        rationale?: "pending_conversion" | "low_activity" | "unknown";
     }>;
 };
 /**
@@ -284,7 +284,7 @@ type SweepAxis = {
     values: Array<number | boolean>;
 };
 type SweepSpecRequest = {
-    sampler?: 'grid' | 'random' | 'lhs';
+    sampler?: "grid" | "random" | "lhs";
     /**
      * Reproducibility seed. If omitted, the server generates one with Java's
      * `L64X128MixRandom` generator and returns the effective value. The range
@@ -296,7 +296,7 @@ type SweepSpecRequest = {
      * Number of samples for `random` and `lhs`; ignored by `grid`.
      */
     samples?: number;
-    objective?: 'sharpe' | 'sortino' | 'pnl' | 'maxdd';
+    objective?: "sharpe" | "sortino" | "pnl" | "maxdd";
     params: {
         [key: string]: SweepAxis;
     };
@@ -306,7 +306,7 @@ type SweepBaseConfig = {
     feeRate?: number;
     buyFeeRate?: number;
     sellFeeRate?: number;
-    feeLeg?: 'RECEIVED' | 'QUOTE' | 'BASE';
+    feeLeg?: "RECEIVED" | "QUOTE" | "BASE";
     percentAmountToLock?: number;
 };
 type ExecuteSweepRequest = {
@@ -325,6 +325,21 @@ type ExecuteSweepRequest = {
      * Trials below this trade count are flagged but remain in the results.
      */
     minTradeFloor?: number;
+    walkForward?: WalkForwardRequest;
+};
+/**
+ * Opt in to walk-forward validation. Present, the sweep runs as F sequential folds and the result gains a `walkForward` section; absent, nothing about the sweep changes. Two requests that differ only in this block are two different sweeps and do not deduplicate against each other.
+ */
+type WalkForwardRequest = {
+    /**
+     * How many sequential optimize-then-score windows to run. Two is the minimum for a reason, and it is structural rather than a tuning choice: parameter drift is measured between consecutive fold winners, and a single fold — one train/test split with no sequence — has no consecutive pair to compare, so it would report the strongest possible stability having measured nothing.
+     * The upper bound is a server setting (12 by default) and is deliberately not pinned here, since a spec that hardcodes a tunable limit lies the day it is raised. Exceeding it, or exceeding the sweep budget once multiplied by the grid size, is a 400.
+     */
+    folds: number;
+    /**
+     * Share of the session each fold spends optimizing; the remainder is where its winner is scored. Lower values leave more data to be scored on and, on short sessions, are also what lets the requested fold count tile the data at all.
+     */
+    inSamplePct?: number;
 };
 type ExecuteSweepAccepted = {
     sweepId: string;
@@ -339,13 +354,51 @@ type ExecuteSweepAccepted = {
      * False when an identical sweep already exists and was not enqueued again.
      */
     queued: boolean;
+    walkForward?: WalkForwardAccepted;
+};
+/**
+ * Echo of the accepted walk-forward configuration, present only when the submit carried one. `inSamplePct` is the resolved value, so a request that omitted it can see what it got.
+ */
+type WalkForwardAccepted = {
+    folds: number;
+    inSamplePct: number;
+    /**
+     * What this sweep actually costs, `folds × (grid size + 1)` — the in-sample runs for every fold plus each fold's one out-of-sample run. Deliberately distinct from the top-level `totalRuns`, which stays the size of the grid that was submitted.
+     */
+    totalRuns: number;
 };
+/**
+ * How far along a sweep is, and — when the sweep is still running — enough to tell a healthy one from a stuck one. The counts partition the shards (or, for a walk-forward sweep, the folds): every unit is either finished, failed, waiting to be retried, or not yet started.
+ */
 type SweepProgress = {
     done: number;
     total: number;
+    /**
+     * Individual runs that executed and aborted. A row-level count: a shard that fails before producing any rows leaves this at 0, which is why `failedShards` exists alongside it.
+     */
     aborted: number;
     shardCount: number;
     pendingShards: number;
+    /**
+     * Shards (or folds) that failed and will not be retried. Distinct from `aborted`: this counts whole units that never reported, not runs that ran badly.
+     */
+    failedShards: number;
+    /**
+     * Units whose last attempt failed on something transient — an I/O error, a worker that died mid-read — and which are queued to be attempted again. Not counted as failures, because they have not failed yet; a sweep with a non-zero value here is still expected to complete.
+     */
+    retrying: number;
+    /**
+     * Units that have not reported anything yet. Covers both work still queued behind other work and work claimed by a worker that stopped before it began, which is why a sweep with a persistent value here and a rising `stalledSeconds` is worth looking at.
+     */
+    notStarted: number;
+    /**
+     * Seconds since anything last advanced. Omitted on a finished sweep, where it would only measure how long ago it finished, and on sweeps submitted before this field existed.
+     */
+    stalledSeconds?: number;
+    /**
+     * Rough seconds remaining, extrapolated from the rate observed so far and assuming nothing else competes for workers. Runs conservative in practice — it has measured 2–5× long when a sweep spent part of its life waiting to be retried, since that wait dilutes the observed rate. **Omitted, never zero, when it cannot be computed**: a sweep with nothing finished yet has no rate to extrapolate from, and a zero would read as "about to finish". Excludes queue wait entirely; `retrying` and `stalledSeconds` are where that shows up.
+     */
+    etaSeconds?: number;
 };
 type SweepRunRow = {
     /**
@@ -356,6 +409,18 @@ type SweepRunRow = {
      * Present only in the `ranked` view.
      */
     rank?: number;
+    /**
+     * The objective of the worst run in this point's immediate neighbourhood — how well the region around it holds up, not how well it scored itself. Present only in the `ranked` view when plateau ranking applied. Always read together with `neighbourCount`.
+     */
+    plateauScore?: number;
+    /**
+     * How many neighbouring parameter points backed the `plateauScore`. Zero means the point had no neighbours in the grid, so its score is unevidenced rather than confirmed — the value alone cannot be distinguished from a genuinely robust one.
+     */
+    neighbourCount?: number;
+    /**
+     * Probability that this run's Sharpe reflects real edge rather than the best draw from however many parameter vectors were tried. Above ~0.95 the result survives the multiple-testing correction; near 0.5 or below it is indistinguishable from the best of a pile of coin flips. Absent on aborted runs, and on sweeps with too few trials to establish any dispersion to deflate against.
+     */
+    deflatedSharpe?: number;
     params: {
         [key: string]: unknown;
     };
@@ -374,11 +439,79 @@ type SweepRunRow = {
     aborted: boolean;
     runtimeMs: number;
 };
+/**
+ * Sensitivity aggregates over a sweep's stored rows. Marginals are always complete; heatmaps may be capped, in which case `heatmapsTruncated` is true.
+ */
+type SweepSensitivity = {
+    sweepId?: string;
+    status?: "RUNNING" | "COMPLETED" | "PARTIAL" | "CANCELLED";
+    objective?: "sharpe" | "sortino" | "pnl" | "maxdd";
+    /**
+     * Rows available when this was computed. Grows while a sweep is still running.
+     */
+    rowsAnalysed?: number;
+    marginals?: Array<SweepMarginal>;
+    heatmaps?: Array<SweepHeatmap>;
+    /**
+     * True when at least one two-parameter surface was left out to stay inside the response budget. Told explicitly because a silently short list would read as "these are all the interactions", which is the wrong thing to conclude from a sensitivity view.
+     */
+    heatmapsTruncated?: boolean;
+};
+/**
+ * One axis, with every other axis collapsed away.
+ */
+type SweepMarginal = {
+    param?: string;
+    points?: Array<SweepMarginalPoint>;
+};
+/**
+ * How the objective behaved at one value of one axis. `best` and `mean` disagreeing is informative rather than noise: a high `best` with a poor `mean` marks a value that only works alongside particular settings of the other axes.
+ */
+type SweepMarginalPoint = {
+    /**
+     * The axis value, as it appears in a run's parameters.
+     */
+    value?: unknown;
+    /**
+     * Non-aborted runs that used this value.
+     */
+    count?: number;
+    best?: number;
+    mean?: number;
+    worst?: number;
+};
+/**
+ * The surface for one pair of axes, with all others collapsed away.
+ */
+type SweepHeatmap = {
+    paramA?: string;
+    paramB?: string;
+    cells?: Array<SweepHeatmapCell>;
+};
+type SweepHeatmapCell = {
+    valueA?: unknown;
+    valueB?: unknown;
+    count?: number;
+    best?: number;
+    mean?: number;
+};
 type ExecuteSweepResult = {
     sweepId: string;
-    status: 'RUNNING' | 'COMPLETED' | 'PARTIAL' | 'CANCELLED';
-    objective: 'sharpe' | 'sortino' | 'pnl' | 'maxdd';
-    order: 'ranked' | 'natural';
+    status: "RUNNING" | "COMPLETED" | "PARTIAL" | "CANCELLED";
+    objective: "sharpe" | "sortino" | "pnl" | "maxdd";
+    order: "ranked" | "natural";
+    /**
+     * Which ordering was actually applied, which is not always the one requested: a sweep with no stored parameter grid cannot be plateau-ranked and falls back to `raw`. Always `raw` when `order=natural`.
+     */
+    ranking?: "plateau" | "raw";
+    /**
+     * Probability of backtest overfitting for the sweep as a whole, by combinatorially symmetric cross-validation: how often the configuration that won in-sample lands below median out-of-sample. Above ~0.5 the sweep is selecting noise, whatever its top row says. Computed once when the last shard finishes, so it is absent while the sweep is still running and on sweeps too small for the statistic to mean anything.
+     */
+    pbo?: number;
+    /**
+     * How many train/test splits the `pbo` figure was averaged over.
+     */
+    pboSplits?: number;
     progress: SweepProgress;
     /**
      * Total result rows currently available.
@@ -389,6 +522,68 @@ type ExecuteSweepResult = {
      */
     truncated: boolean;
     leaderboard: Array<SweepRunRow>;
+    walkForward?: WalkForwardResult;
+};
+/**
+ * Present only on a sweep submitted with `walkForward`, and present from acceptance onward — its presence, not its contents, is what identifies a walk-forward sweep. `completedFolds` is 0 while the first fold is still running.
+ */
+type WalkForwardResult = {
+    /**
+     * Folds requested at submit.
+     */
+    folds: number;
+    /**
+     * Resolved in-sample share each fold optimized on.
+     */
+    inSamplePct?: number;
+    /**
+     * Folds that have finished and reported a winner.
+     */
+    completedFolds: number;
+    /**
+     * Mean normalized lattice distance between consecutive fold winners. Low is good: winners that stay in a tight band fold after fold are evidence the parameter means something, while winners that jump across the grid every time are the sweep re-fitting noise, and that backtest will not survive contact with live data. **Absent is not zero** — the field is omitted whenever the figure could not be computed (fewer than two folds finished, no stored grid to place winners on), because zero is itself a meaningful reading here and a placeholder would be indistinguishable from perfect stability.
+     */
+    paramDrift?: number;
+    /**
+     * One entry per completed fold, oldest first.
+     */
+    results: Array<WalkForwardFold>;
+};
+/**
+ * What one fold concluded. The out-of-sample row is the answer; the in-sample figure is only there to be compared against it, since any grid produces a flattering in-sample winner — that is what optimizing does. The gap between them is the whole reading.
+ */
+type WalkForwardFold = {
+    /**
+     * Position in the walk-forward sequence, oldest first.
+     */
+    foldIx: number;
+    /**
+     * First index of the optimization window, into the prepared session.
+     */
+    inSampleFrom: number;
+    /**
+     * End of the optimization window, exclusive — and where scoring begins.
+     */
+    inSampleTo: number;
+    /**
+     * End of the scoring window, exclusive.
+     */
+    outOfSampleTo: number;
+    /**
+     * The parameter vector that won this fold's optimization window.
+     */
+    params: {
+        [key: string]: unknown;
+    };
+    /**
+     * How that winner scored on the window it was chosen on.
+     */
+    inSampleSharpe: number;
+    outOfSample: SweepRunRow;
+    /**
+     * Vectors this fold evaluated in-sample before picking its winner.
+     */
+    vectorsRun: number;
 };
 /**
  * Response returned by async endpoints (`202 Accepted`). The `jobId` is deterministic for the
@@ -506,7 +701,7 @@ type ResultMap = {
     /**
      * Upload status. Done = signal file is available at signalsUrl. Failed = upload error (see signalsUploadReason). Skipped = no signals emitted.
      */
-    signalsUpload?: 'Done' | 'Failed' | 'Skipped';
+    signalsUpload?: "Done" | "Failed" | "Skipped";
     /**
      * ISO 8601 timestamp of when the upload completed. Only present when signalsUpload is Done.
      */
@@ -560,7 +755,7 @@ type Notice = {
      * `compile-dry-run` is only a lower bound over a bounded synthetic series.
      *
      */
-    provenance?: 'execute' | 'compile-dry-run';
+    provenance?: "execute" | "compile-dry-run";
 };
 /**
  * What is known about a registered strategy: that it compiled, and what validating it found.
@@ -580,7 +775,7 @@ type StrategyState = {
      * * `failed` — it did not; `detail` says how.
      *
      */
-    validation: 'not_validated' | 'pending' | 'passed' | 'failed';
+    validation: "not_validated" | "pending" | "passed" | "failed";
     /**
      * When the live compilation was produced.
      */
@@ -598,7 +793,7 @@ type StrategyState = {
      * re-registering the source fills it in.
      *
      */
-    requiredSources?: Array<'Ticker' | 'KLine' | 'FundingRate'>;
+    requiredSources?: Array<"Ticker" | "KLine" | "FundingRate">;
     /**
      * When the verdict was recorded. Absent until there is one.
      */
@@ -642,7 +837,7 @@ type AuthTokenResponse = {
     /**
      * Always `Bearer`.
      */
-    token_type: 'Bearer';
+    token_type: "Bearer";
     /**
      * Seconds until the JWT expires (typically 3600).
      */
@@ -654,7 +849,7 @@ type AuthTokenResponse = {
     /**
      * Subscription tier this token was issued for. Drives rate limits and feature flags on downstream endpoints.
      */
-    tier: 'free' | 'basic' | 'pro' | 'elite';
+    tier: "free" | "basic" | "pro" | "elite";
 };
 /**
  * Error envelope returned by `POST /auth/token` when the API key is rejected.
@@ -663,7 +858,7 @@ type AuthTokenError = {
     /**
      * Machine-readable error reason.
      */
-    code: 'invalid_apikey' | 'apikey_revoked' | 'apikey_expired';
+    code: "invalid_apikey" | "apikey_revoked" | "apikey_expired";
     /**
      * Human-readable description of the failure.
      */
@@ -673,7 +868,7 @@ type AuthenticateData = {
     body?: never;
     path?: never;
     query?: never;
-    url: '/auth/token';
+    url: "/auth/token";
 };
 type AuthenticateErrors = {
     /**
@@ -697,7 +892,7 @@ type ListExchangesData = {
     body?: never;
     path?: never;
     query?: never;
-    url: '/exchanges';
+    url: "/exchanges";
 };
 type ListExchangesResponses = {
     /**
@@ -715,7 +910,7 @@ type ListInstrumentsData = {
         exchangeId: string;
     };
     query?: never;
-    url: '/exchange/{exchangeId}/instruments';
+    url: "/exchange/{exchangeId}/instruments";
 };
 type ListInstrumentsErrors = {
     /**
@@ -741,10 +936,10 @@ type ListSegmentInstrumentsData = {
         /**
          * Market segment to list instruments for
          */
-        segment: 'spot' | 'futures';
+        segment: "spot" | "futures";
     };
     query?: never;
-    url: '/exchange/{exchangeId}/{segment}/instruments';
+    url: "/exchange/{exchangeId}/{segment}/instruments";
 };
 type ListSegmentInstrumentsErrors = {
     /**
@@ -789,9 +984,9 @@ type DownloadTickersData = {
          * [lastra-convert](https://github.com/QTSurfer/lastra-convert).
          *
          */
-        format?: 'lastra' | 'parquet';
+        format?: "lastra" | "parquet";
     };
-    url: '/exchange/{exchangeId}/tickers/{base}/{quote}';
+    url: "/exchange/{exchangeId}/tickers/{base}/{quote}";
 };
 type DownloadTickersErrors = {
     /**
@@ -847,9 +1042,9 @@ type DownloadKlinesData = {
          * `parquet` returns Parquet via on-the-fly conversion.
          *
          */
-        format?: 'lastra' | 'parquet';
+        format?: "lastra" | "parquet";
     };
-    url: '/exchange/{exchangeId}/klines/{base}/{quote}';
+    url: "/exchange/{exchangeId}/klines/{base}/{quote}";
 };
 type DownloadKlinesErrors = {
     /**
@@ -883,7 +1078,7 @@ type CompileStrategyData = {
     body: string;
     path?: never;
     query?: never;
-    url: '/strategy';
+    url: "/strategy";
 };
 type CompileStrategyErrors = {
     /**
@@ -916,7 +1111,7 @@ type ValidateStrategyData = {
         strategyId: StrategyId;
     };
     query?: never;
-    url: '/strategy/{strategyId}/validate';
+    url: "/strategy/{strategyId}/validate";
 };
 type ValidateStrategyErrors = {
     /**
@@ -937,7 +1132,7 @@ type ValidateStrategyResponses = {
      */
     202: {
         strategyId: StrategyId;
-        validation: 'pending';
+        validation: "pending";
     };
 };
 type ValidateStrategyResponse = ValidateStrategyResponses[keyof ValidateStrategyResponses];
@@ -950,7 +1145,7 @@ type GetStrategyData = {
         strategyId: StrategyId;
     };
     query?: never;
-    url: '/strategy/{strategyId}';
+    url: "/strategy/{strategyId}";
 };
 type GetStrategyErrors = {
     /**
@@ -982,7 +1177,7 @@ type PrepareBacktestData = {
         type: DataSourceType;
     };
     query?: never;
-    url: '/backtest/{exchangeId}/{type}/prepare';
+    url: "/backtest/{exchangeId}/{type}/prepare";
 };
 type PrepareBacktestErrors = {
     /**
@@ -1027,7 +1222,7 @@ type GetPrepareStatusData = {
         jobId: string;
     };
     query?: never;
-    url: '/backtest/{exchangeId}/{type}/prepare/{jobId}';
+    url: "/backtest/{exchangeId}/{type}/prepare/{jobId}";
 };
 type GetPrepareStatusErrors = {
     /**
@@ -1058,7 +1253,7 @@ type ExecuteSweepData = {
         requestId: string;
     };
     query?: never;
-    url: '/backtest/{exchangeId}/{type}/executeSweep/{requestId}';
+    url: "/backtest/{exchangeId}/{type}/executeSweep/{requestId}";
 };
 type ExecuteSweepErrors = {
     /**
@@ -1091,7 +1286,7 @@ type CancelSweepData = {
         sweepId: string;
     };
     query?: never;
-    url: '/backtest/{exchangeId}/{type}/executeSweep/{requestId}/{sweepId}';
+    url: "/backtest/{exchangeId}/{type}/executeSweep/{requestId}/{sweepId}";
 };
 type CancelSweepErrors = {
     /**
@@ -1105,7 +1300,7 @@ type CancelSweepResponses = {
      * Cancellation requested.
      */
     200: {
-        status: 'cancelling';
+        status: "cancelling";
         sweepId: string;
     };
 };
@@ -1119,13 +1314,17 @@ type GetSweepResultData = {
         sweepId: string;
     };
     query?: {
-        objective?: 'sharpe' | 'sortino' | 'pnl' | 'maxdd';
+        objective?: "sharpe" | "sortino" | "pnl" | "maxdd";
         /**
          * `natural` is stable materialisation order; `ranked` is the display view.
          */
-        order?: 'ranked' | 'natural';
+        order?: "ranked" | "natural";
+        /**
+         * How the `ranked` view is ordered. `plateau` prefers points whose neighbourhood also scores well; `raw` uses the objective alone. Ignored when `order=natural`, which is always ordered by `runIx`.
+         */
+        ranking?: "plateau" | "raw";
     };
-    url: '/backtest/{exchangeId}/{type}/executeSweep/{requestId}/{sweepId}';
+    url: "/backtest/{exchangeId}/{type}/executeSweep/{requestId}/{sweepId}";
 };
 type GetSweepResultErrors = {
     /**
@@ -1141,6 +1340,36 @@ type GetSweepResultResponses = {
     200: ExecuteSweepResult;
 };
 type GetSweepResultResponse = GetSweepResultResponses[keyof GetSweepResultResponses];
+type GetSweepSensitivityData = {
+    body?: never;
+    path: {
+        exchangeId: string;
+        type: DataSourceType;
+        requestId: string;
+        sweepId: string;
+    };
+    query?: {
+        /**
+         * Which metric to aggregate. Defaults to the objective the sweep was submitted with.
+         */
+        objective?: "sharpe" | "sortino" | "pnl" | "maxdd";
+    };
+    url: "/backtest/{exchangeId}/{type}/executeSweep/{requestId}/{sweepId}/sensitivity";
+};
+type GetSweepSensitivityErrors = {
+    /**
+     * Sweep not found or expired.
+     */
+    404: ResponseError;
+};
+type GetSweepSensitivityError = GetSweepSensitivityErrors[keyof GetSweepSensitivityErrors];
+type GetSweepSensitivityResponses = {
+    /**
+     * Sensitivity aggregates over the rows available so far.
+     */
+    200: SweepSensitivity;
+};
+type GetSweepSensitivityResponse = GetSweepSensitivityResponses[keyof GetSweepSensitivityResponses];
 type ExecuteBacktestData = {
     /**
      * Execute task parameters
@@ -1169,7 +1398,7 @@ type ExecuteBacktestData = {
         type: DataSourceType;
     };
     query?: never;
-    url: '/backtest/{exchangeId}/{type}/execute';
+    url: "/backtest/{exchangeId}/{type}/execute";
 };
 type ExecuteBacktestErrors = {
     /**
@@ -1204,7 +1433,7 @@ type CancelBacktestData = {
         jobId: string;
     };
     query?: never;
-    url: '/backtest/{exchangeId}/{type}/execute/{jobId}';
+    url: "/backtest/{exchangeId}/{type}/execute/{jobId}";
 };
 type CancelBacktestErrors = {
     /**
@@ -1218,7 +1447,7 @@ type CancelBacktestResponses = {
      * Cancellation request accepted
      */
     200: {
-        status?: 'cancelling';
+        status?: "cancelling";
         jobId?: string;
     };
 };
@@ -1240,7 +1469,7 @@ type GetBacktestResultData = {
         jobId: string;
     };
     query?: never;
-    url: '/backtest/{exchangeId}/{type}/execute/{jobId}';
+    url: "/backtest/{exchangeId}/{type}/execute/{jobId}";
 };
 type GetBacktestResultErrors = {
     /**
@@ -1276,7 +1505,7 @@ type GetBacktestResultResponses = {
 };
 type GetBacktestResultResponse = GetBacktestResultResponses[keyof GetBacktestResultResponses];
 type ClientOptions = {
-    baseUrl: 'https://api.staging.qtsurfer.com/v1' | 'https://api.qtsurfer.com/v1' | (string & {});
+    baseUrl: "https://api.staging.qtsurfer.com/v1" | "https://api.qtsurfer.com/v1" | (string & {});
 };
 
 type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean> = Options$1<TData, ThrowOnError> & {
@@ -1449,6 +1678,17 @@ declare const getPrepareStatus: <ThrowOnError extends boolean = false>(options:
  * The backend expands and executes the matrix internally; clients poll the returned
  * `sweepId` for incremental results.
  *
+ * Supplying `walkForward` runs the sweep in a different mode entirely. Instead of scoring
+ * every parameter vector once over the whole range, the data is split into F sequential
+ * folds; each fold optimizes the full grid on its own window and then scores only its winner
+ * on the window immediately after — data that winner was not chosen on. It answers a harder
+ * question than a leaderboard: not "which parameters won", but "does re-optimizing this
+ * periodically actually work". Omit the block and nothing changes, including the response.
+ *
+ * The cost is the reason it is opt-in rather than always on: F folds × N vectors, so a
+ * 4-fold run over a 500-point grid is 2004 backtests where the plain sweep is 500. The
+ * request is rejected when `folds × totalRuns` exceeds the server's sweep budget.
+ *
  */
 declare const executeSweep: <ThrowOnError extends boolean = false>(options: Options<ExecuteSweepData, ThrowOnError>) => _hey_api_client_fetch.RequestResult<ExecuteSweepAccepted, ResponseError, ThrowOnError>;
 /**
@@ -1465,8 +1705,59 @@ declare const cancelSweep: <ThrowOnError extends boolean = false>(options: Optio
  * display leaderboard. `order=natural` returns every available row, untruncated, ordered by
  * deterministic `runIx`; use that view when materialising durable trial rows.
  *
+ * The `ranked` view is ordered by **plateau score** by default, not by the raw objective. A
+ * plateau score is the objective of the worst run in a parameter point's immediate
+ * neighbourhood, so a point scores well only if the region around it also does — the highest
+ * raw score is frequently a spike that does not survive the parameters moving slightly. Pass
+ * `ranking=raw` for the unadjusted objective order.
+ *
+ * Rows in the `ranked` view carry `plateauScore` and `neighbourCount` when plateau ranking
+ * applied. Read them together: `neighbourCount: 0` means the point had no neighbours to
+ * compare against, so its plateau score is unevidenced rather than confirmed. Sweeps
+ * submitted before plateau ranking existed have no stored parameter grid to rebuild a
+ * neighbourhood from and are always ranked raw; the response's `ranking` field says which
+ * ordering was actually used.
+ *
+ * A sweep submitted with `walkForward` answers in a different shape, and the `walkForward`
+ * field on the response is what tells the two apart — it appears as soon as the sweep is
+ * accepted, before any fold has finished, so it is safe to branch on while polling. There
+ * the leaderboard is one row per completed fold: that fold's winner as it scored
+ * **out-of-sample**, with `runIx` carrying the fold index rather than a grid position. The
+ * in-sample runs behind those winners are not retained — they are an optimization's working
+ * set, and only the winner survives its fold. `ranking` is always `raw` and no plateau, DSR
+ * or PBO figure is reported: the out-of-sample scores are already the honest number, and
+ * layering a certification computed over F observations on top of them would overstate what
+ * was measured.
+ *
  */
 declare const getSweepResult: <ThrowOnError extends boolean = false>(options: Options<GetSweepResultData, ThrowOnError>) => _hey_api_client_fetch.RequestResult<ExecuteSweepResult, ResponseError, ThrowOnError>;
+/**
+ * Get sweep sensitivity surfaces
+ * How the objective moves as each parameter moves — the question a leaderboard cannot answer.
+ * A leaderboard says which point won; a sweep can spend its entire budget on an axis that
+ * never moved the objective at all, and showing only the top rows hides that completely.
+ *
+ * A **marginal** takes one axis and collapses every other one: for each value of that axis,
+ * it aggregates every run that used it, whatever the rest of the parameters were. A flat
+ * marginal means the axis is irrelevant over the range swept. `best`, `mean` and `worst` are
+ * all reported because them disagreeing is itself the signal — a value with a high `best` and
+ * a poor `mean` works only in specific company, which is an interaction between parameters
+ * and would be invisible behind a single number.
+ *
+ * A **heatmap** does the same over a pair of axes, where that interaction becomes visible
+ * directly.
+ *
+ * Served from the sweep's stored rows: no re-run, no engine call, and it works on a sweep
+ * still in flight — the aggregates then describe the runs finished so far. Aborted runs are
+ * excluded throughout, since a run that threw measured nothing and counting it as a bad
+ * outcome would invent evidence against a parameter value that was never really tested.
+ *
+ * This is a separate endpoint rather than extra fields on the result view because the
+ * two-dimensional half is quadratic in the axis count (N axes give N(N-1)/2 surfaces, each
+ * the product of two axes' value counts) and is not wanted on the poll that drives progress.
+ *
+ */
+declare const getSweepSensitivity: <ThrowOnError extends boolean = false>(options: Options<GetSweepSensitivityData, ThrowOnError>) => _hey_api_client_fetch.RequestResult<SweepSensitivity, ResponseError, ThrowOnError>;
 /**
  * Execute a compiled strategy against a prepared dataset
  * Enqueues an execute task that runs the strategy identified by `strategyId` over the data
@@ -1507,4 +1798,4 @@ declare const getBacktestResult: <ThrowOnError extends boolean = false>(options:
 
 declare const client: _hey_api_client_fetch.Client;
 
-export { type AcceptedJob, type AuthTokenError, type AuthTokenResponse, type AuthenticateData, type AuthenticateError, type AuthenticateErrors, type AuthenticateResponse, type AuthenticateResponses, type BacktestJobResult, type CancelBacktestData, type CancelBacktestError, type CancelBacktestErrors, type CancelBacktestResponse, type CancelBacktestResponses, type CancelSweepData, type CancelSweepError, type CancelSweepErrors, type CancelSweepResponse, type CancelSweepResponses, type ClientOptions, type CompileStrategyData, type CompileStrategyError, type CompileStrategyErrors, type CompileStrategyResponse, type CompileStrategyResponses, type CoverageWindow, type DataSourceType, type DownloadKlinesData, type DownloadKlinesError, type DownloadKlinesErrors, type DownloadKlinesResponse, type DownloadKlinesResponses, type DownloadTickersData, type DownloadTickersError, type DownloadTickersErrors, type DownloadTickersResponse, type DownloadTickersResponses, type EquityPoint, type Exchange, type ExecuteBacktestData, type ExecuteBacktestError, type ExecuteBacktestErrors, type ExecuteBacktestResponse, type ExecuteBacktestResponses, type ExecuteSweepAccepted, type ExecuteSweepData, type ExecuteSweepError, type ExecuteSweepErrors, type ExecuteSweepRequest, type ExecuteSweepResponse, type ExecuteSweepResponses, type ExecuteSweepResult, type GetBacktestResultData, type GetBacktestResultError, type GetBacktestResultErrors, type GetBacktestResultResponse, type GetBacktestResultResponses, type GetPrepareStatusData, type GetPrepareStatusError, type GetPrepareStatusErrors, type GetPrepareStatusResponse, type GetPrepareStatusResponses, type GetStrategyData, type GetStrategyError, type GetStrategyErrors, type GetStrategyResponse, type GetStrategyResponses, type GetSweepResultData, type GetSweepResultError, type GetSweepResultErrors, type GetSweepResultResponse, type GetSweepResultResponses, type HalLink, type Instrument, type InstrumentCoverage, type InstrumentDetail, type InstrumentLinks, type InstrumentListMeta, type InstrumentListResponse, type JobState, type ListExchangesData, type ListExchangesResponse, type ListExchangesResponses, type ListInstrumentsData, type ListInstrumentsError, type ListInstrumentsErrors, type ListInstrumentsResponse, type ListInstrumentsResponses, type ListSegmentInstrumentsData, type ListSegmentInstrumentsError, type ListSegmentInstrumentsErrors, type ListSegmentInstrumentsResponse, type ListSegmentInstrumentsResponses, type Notice, type Options, type PrepareBacktestData, type PrepareBacktestError, type PrepareBacktestErrors, type PrepareBacktestResponse, type PrepareBacktestResponses, type PrepareJobState, type PrepareRequest, type ResponseError, type ResultMap, type StrategyId, type StrategyState, type SweepAxis, type SweepBaseConfig, type SweepProgress, type SweepRunRow, type SweepSpecRequest, type ValidateStrategyData, type ValidateStrategyError, type ValidateStrategyErrors, type ValidateStrategyResponse, type ValidateStrategyResponses, authenticate, cancelBacktest, cancelSweep, client, compileStrategy, downloadKlines, downloadTickers, executeBacktest, executeSweep, getBacktestResult, getPrepareStatus, getStrategy, getSweepResult, listExchanges, listInstruments, listSegmentInstruments, prepareBacktest, validateStrategy };
+export { type AcceptedJob, type AuthTokenError, type AuthTokenResponse, type AuthenticateData, type AuthenticateError, type AuthenticateErrors, type AuthenticateResponse, type AuthenticateResponses, type BacktestJobResult, type CancelBacktestData, type CancelBacktestError, type CancelBacktestErrors, type CancelBacktestResponse, type CancelBacktestResponses, type CancelSweepData, type CancelSweepError, type CancelSweepErrors, type CancelSweepResponse, type CancelSweepResponses, type ClientOptions, type CompileStrategyData, type CompileStrategyError, type CompileStrategyErrors, type CompileStrategyResponse, type CompileStrategyResponses, type CoverageWindow, type DataSourceType, type DownloadKlinesData, type DownloadKlinesError, type DownloadKlinesErrors, type DownloadKlinesResponse, type DownloadKlinesResponses, type DownloadTickersData, type DownloadTickersError, type DownloadTickersErrors, type DownloadTickersResponse, type DownloadTickersResponses, type EquityPoint, type Exchange, type ExecuteBacktestData, type ExecuteBacktestError, type ExecuteBacktestErrors, type ExecuteBacktestResponse, type ExecuteBacktestResponses, type ExecuteSweepAccepted, type ExecuteSweepData, type ExecuteSweepError, type ExecuteSweepErrors, type ExecuteSweepRequest, type ExecuteSweepResponse, type ExecuteSweepResponses, type ExecuteSweepResult, type GetBacktestResultData, type GetBacktestResultError, type GetBacktestResultErrors, type GetBacktestResultResponse, type GetBacktestResultResponses, type GetPrepareStatusData, type GetPrepareStatusError, type GetPrepareStatusErrors, type GetPrepareStatusResponse, type GetPrepareStatusResponses, type GetStrategyData, type GetStrategyError, type GetStrategyErrors, type GetStrategyResponse, type GetStrategyResponses, type GetSweepResultData, type GetSweepResultError, type GetSweepResultErrors, type GetSweepResultResponse, type GetSweepResultResponses, type GetSweepSensitivityData, type GetSweepSensitivityError, type GetSweepSensitivityErrors, type GetSweepSensitivityResponse, type GetSweepSensitivityResponses, type HalLink, type Instrument, type InstrumentCoverage, type InstrumentDetail, type InstrumentLinks, type InstrumentListMeta, type InstrumentListResponse, type JobState, type ListExchangesData, type ListExchangesResponse, type ListExchangesResponses, type ListInstrumentsData, type ListInstrumentsError, type ListInstrumentsErrors, type ListInstrumentsResponse, type ListInstrumentsResponses, type ListSegmentInstrumentsData, type ListSegmentInstrumentsError, type ListSegmentInstrumentsErrors, type ListSegmentInstrumentsResponse, type ListSegmentInstrumentsResponses, type Notice, type Options, type PrepareBacktestData, type PrepareBacktestError, type PrepareBacktestErrors, type PrepareBacktestResponse, type PrepareBacktestResponses, type PrepareJobState, type PrepareRequest, type ResponseError, type ResultMap, type StrategyId, type StrategyState, type SweepAxis, type SweepBaseConfig, type SweepHeatmap, type SweepHeatmapCell, type SweepMarginal, type SweepMarginalPoint, type SweepProgress, type SweepRunRow, type SweepSensitivity, type SweepSpecRequest, type ValidateStrategyData, type ValidateStrategyError, type ValidateStrategyErrors, type ValidateStrategyResponse, type ValidateStrategyResponses, type WalkForwardAccepted, type WalkForwardFold, type WalkForwardRequest, type WalkForwardResult, authenticate, cancelBacktest, cancelSweep, client, compileStrategy, downloadKlines, downloadTickers, executeBacktest, executeSweep, getBacktestResult, getPrepareStatus, getStrategy, getSweepResult, getSweepSensitivity, listExchanges, listInstruments, listSegmentInstruments, prepareBacktest, validateStrategy };