@qtsurfer/api-client 0.6.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
@@ -409,7 +604,7 @@ type BacktestJobResult = {
     state: JobState;
 };
 /**
- * Execution result map. Always includes core fields (hostName, iops, strategyId, instrument). Yield metrics (pnlTotal, pnlTotalPercent, totalTrades, winRate, equityCurve, etc.) are present when the strategy emitted at least one trade. When signal storage is enabled, includes signal fields described below.
+ * Execution result map. Always includes core fields (hostName, iops, strategyId, instrument). Yield metrics (pnlTotal, pnlTotalPercent, totalTrades, winRate, equityCurve, etc.) are present when the strategy emitted at least one trade. When signal storage is enabled, includes signal fields described below. `notices` carries what the run had to say about itself, and is absent when it had nothing.
  */
 type ResultMap = {
     /**
@@ -421,13 +616,36 @@ type ResultMap = {
      */
     iops?: number;
     /**
-     * Identifier of the compiled strategy that produced this result
+     * **Not the `strategyId` you compiled with** — this is the execution context id,
+     * `strategy:<user>:<strategyId>`. The compiled strategy's id is the last `:`-separated
+     * segment; that, not this whole string, is what `GET /strategy/{strategyId}` takes.
+     *
+     * Take the segment after the last `:` rather than counting from the front: the shape has
+     * changed once already and callers that indexed a fixed position broke on it.
+     *
      */
     strategyId: string;
     /**
      * The instrument (currency pair) that was backtested
      */
     instrument: string;
+    /**
+     * Diagnostics the engine raised over this run, each with `provenance: execute`.
+     *
+     * **Absent means nothing was raised.** This is the one surface where silence is a real
+     * answer: the run happened, over your data, start to finish, and the engine found nothing
+     * worth saying. That is not true of the compile path, where an empty list only means a
+     * short synthetic series reached nothing — see `GET /strategy/{strategyId}`.
+     *
+     * Notices are raised on failed and aborted runs too, and those are the ones most worth
+     * reading: a run that produced no trades often did so for a reason stated here.
+     *
+     */
+    notices?: Array<Notice>;
+    /**
+     * How many notices were dropped past the cap of 50. Absent when none were. A large value usually means one fault repeating per instrument or per parameter vector rather than 50 distinct problems.
+     */
+    noticesTruncated?: number;
     /**
      * Total profit and loss in the output currency
      */
@@ -483,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.
      */
@@ -507,9 +725,110 @@ type EquityPoint = {
     equity: number;
 };
 /**
- * Unique identifier for a compiled strategy
+ * Unique identifier for a compiled strategy, derived from the source itself: the same code
+ * always yields the same id, for every caller, whatever its formatting. See
+ * `POST /strategy` for exactly which rewrites preserve it and which do not.
+ *
  */
 type StrategyId = string;
+/**
+ * A diagnostic the engine raised while the strategy ran. Advisory: it describes something worth
+ * knowing about how the strategy is wired, not necessarily an error.
+ *
+ */
+type Notice = {
+    /**
+     * Severity as the engine classified it.
+     */
+    level: string;
+    /**
+     * Stable identifier for the kind of finding; safe to match on.
+     */
+    code: string;
+    /**
+     * Human-readable explanation.
+     */
+    message: string;
+    /**
+     * Where it came from, which matters because the two silences differ: an empty list from a
+     * real run (`execute`) is a clean bill of health, while an empty list from
+     * `compile-dry-run` is only a lower bound over a bounded synthetic series.
+     *
+     */
+    provenance?: "execute" | "compile-dry-run";
+};
+/**
+ * What is known about a registered strategy: that it compiled, and what validating it found.
+ *
+ * **`validation: passed` does not mean the strategy is correct.** It means the class loaded and
+ * survived the first event of a short synthetic run — a floor, not a guarantee. When
+ * `dryRunIncomplete` is true it is a lower floor still, because the run did not finish.
+ *
+ */
+type StrategyState = {
+    strategyId: StrategyId;
+    /**
+     * * `not_validated` — registered, never checked. `POST /strategy/{strategyId}/validate`
+     * checks it.
+     * * `pending` — a check was asked for and has not answered yet.
+     * * `passed` — the class loaded and survived its first event.
+     * * `failed` — it did not; `detail` says how.
+     *
+     */
+    validation: "not_validated" | "pending" | "passed" | "failed";
+    /**
+     * When the live compilation was produced.
+     */
+    compiledAt?: string;
+    /**
+     * The market data a strategy needs, read off the compiled class rather than off anything
+     * you sent — `TickerStrategy`, `KlineStrategy` and `FundingRateStrategy` each declare one,
+     * and a `MultiSourceStrategy` declares a set.
+     *
+     * **Absent is not "needs nothing".** A strategy always needs market data, so an absent
+     * field never means an empty requirement — it means the platform could not establish the
+     * answer without constructing your strategy, which it will not do to fill in a field.
+     * That happens for a `MultiSourceStrategy`, for a class that overrides
+     * `getMarketDataSource()`, and for anything registered before this field existed;
+     * re-registering the source fills it in.
+     *
+     */
+    requiredSources?: Array<"Ticker" | "KLine" | "FundingRate">;
+    /**
+     * When the verdict was recorded. Absent until there is one.
+     */
+    validatedAt?: string;
+    /**
+     * Why validation failed, or why a queued check has not reported. Present on `failed`, and
+     * alongside `validationStalled`.
+     *
+     */
+    detail?: string;
+    /**
+     * What the run surfaced. An empty or absent list is not a clean bill of health when
+     * `dryRunIncomplete` is true — see that field.
+     *
+     */
+    notices?: Array<Notice>;
+    /**
+     * How many notices were dropped past the cap. Absent when none were.
+     */
+    noticesTruncated?: number;
+    /**
+     * The check did not finish its budget — it ran out of time, was refused because the
+     * platform was already holding too many unfinishable runs, or hit a failure attributable to
+     * the synthetic instrument rather than to your strategy. The verdict stands as far as it
+     * went; it simply reached less than a full run would.
+     *
+     */
+    dryRunIncomplete?: boolean;
+    /**
+     * A queued check has not reported for far longer than one takes. Nothing is disproved about
+     * the strategy — the check has not run. Stop waiting and re-request it later.
+     *
+     */
+    validationStalled?: boolean;
+};
 type AuthTokenResponse = {
     /**
      * Short-lived HS256 JWT. Send as `Authorization: Bearer <token>` on all other endpoints.
@@ -518,7 +837,7 @@ type AuthTokenResponse = {
     /**
      * Always `Bearer`.
      */
-    token_type: 'Bearer';
+    token_type: "Bearer";
     /**
      * Seconds until the JWT expires (typically 3600).
      */
@@ -530,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.
@@ -539,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.
      */
@@ -549,7 +868,7 @@ type AuthenticateData = {
     body?: never;
     path?: never;
     query?: never;
-    url: '/auth/token';
+    url: "/auth/token";
 };
 type AuthenticateErrors = {
     /**
@@ -573,7 +892,7 @@ type ListExchangesData = {
     body?: never;
     path?: never;
     query?: never;
-    url: '/exchanges';
+    url: "/exchanges";
 };
 type ListExchangesResponses = {
     /**
@@ -591,7 +910,7 @@ type ListInstrumentsData = {
         exchangeId: string;
     };
     query?: never;
-    url: '/exchange/{exchangeId}/instruments';
+    url: "/exchange/{exchangeId}/instruments";
 };
 type ListInstrumentsErrors = {
     /**
@@ -617,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 = {
     /**
@@ -665,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 = {
     /**
@@ -723,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 = {
     /**
@@ -757,70 +1076,89 @@ type CompileStrategyData = {
      * Raw strategy Java source code
      */
     body: string;
-    headers?: {
-        /**
-         * When `true`, compile asynchronously and return `202` with a `jobId`.
-         */
-        'X-Compile-Async'?: boolean;
-    };
     path?: never;
     query?: never;
-    url: '/strategy';
+    url: "/strategy";
 };
 type CompileStrategyErrors = {
     /**
-     * Invalid strategy (compilation error)
+     * The source is not valid Java; the message carries the compiler diagnostics. Nothing is
+     * registered, so there is no id to look up afterwards.
+     *
      */
     400: ResponseError;
+    /**
+     * Too many compilations in flight. Retry later.
+     */
+    429: ResponseError;
 };
 type CompileStrategyError = CompileStrategyErrors[keyof CompileStrategyErrors];
 type CompileStrategyResponses = {
     /**
-     * Strategy compiled successfully (sync mode)
+     * Compiled and registered
      */
     200: {
         strategyId: StrategyId;
     };
+};
+type CompileStrategyResponse = CompileStrategyResponses[keyof CompileStrategyResponses];
+type ValidateStrategyData = {
+    body?: never;
+    path: {
+        /**
+         * The id returned by `POST /strategy`
+         */
+        strategyId: StrategyId;
+    };
+    query?: never;
+    url: "/strategy/{strategyId}/validate";
+};
+type ValidateStrategyErrors = {
     /**
-     * Compile task accepted (async mode — set `X-Compile-Async: true`)
+     * No such registered strategy for this user
      */
-    202: AcceptedJob;
+    404: ResponseError;
 };
-type CompileStrategyResponse = CompileStrategyResponses[keyof CompileStrategyResponses];
+type ValidateStrategyError = ValidateStrategyErrors[keyof ValidateStrategyErrors];
+type ValidateStrategyResponses = {
+    /**
+     * Already validated; the recorded verdict, unchanged
+     */
+    200: StrategyState;
+    /**
+     * Validation queued. Not a terminal outcome — poll `GET /strategy/{strategyId}` until
+     * `validation` leaves `pending`.
+     *
+     */
+    202: {
+        strategyId: StrategyId;
+        validation: "pending";
+    };
+};
+type ValidateStrategyResponse = ValidateStrategyResponses[keyof ValidateStrategyResponses];
 type GetStrategyData = {
     body?: never;
     path: {
         /**
-         * The id returned by `POST /strategy` (sync) or the `jobId` returned in async mode
+         * The id returned by `POST /strategy`
          */
-        strategyId: string;
+        strategyId: StrategyId;
     };
     query?: never;
-    url: '/strategy/{strategyId}';
+    url: "/strategy/{strategyId}";
 };
 type GetStrategyErrors = {
     /**
-     * Strategy compile job not found
+     * No such registered strategy for this user
      */
     404: ResponseError;
 };
 type GetStrategyError = GetStrategyErrors[keyof GetStrategyErrors];
 type GetStrategyResponses = {
     /**
-     * Strategy compile state
+     * Strategy state
      */
-    200: {
-        /**
-         * Compile job id (only set in async mode)
-         */
-        jobId?: string;
-        status: 'New' | 'Started' | 'Completed' | 'Aborted' | 'Failed';
-        strategyId?: StrategyId;
-        /**
-         * Compilation error messages when `status` is `Failed`
-         */
-        statusDetail?: string | null;
-    };
+    200: StrategyState;
 };
 type GetStrategyResponse = GetStrategyResponses[keyof GetStrategyResponses];
 type PrepareBacktestData = {
@@ -839,7 +1177,7 @@ type PrepareBacktestData = {
         type: DataSourceType;
     };
     query?: never;
-    url: '/backtest/{exchangeId}/{type}/prepare';
+    url: "/backtest/{exchangeId}/{type}/prepare";
 };
 type PrepareBacktestErrors = {
     /**
@@ -884,7 +1222,7 @@ type GetPrepareStatusData = {
         jobId: string;
     };
     query?: never;
-    url: '/backtest/{exchangeId}/{type}/prepare/{jobId}';
+    url: "/backtest/{exchangeId}/{type}/prepare/{jobId}";
 };
 type GetPrepareStatusErrors = {
     /**
@@ -915,7 +1253,7 @@ type ExecuteSweepData = {
         requestId: string;
     };
     query?: never;
-    url: '/backtest/{exchangeId}/{type}/executeSweep/{requestId}';
+    url: "/backtest/{exchangeId}/{type}/executeSweep/{requestId}";
 };
 type ExecuteSweepErrors = {
     /**
@@ -948,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 = {
     /**
@@ -962,7 +1300,7 @@ type CancelSweepResponses = {
      * Cancellation requested.
      */
     200: {
-        status: 'cancelling';
+        status: "cancelling";
         sweepId: string;
     };
 };
@@ -976,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 = {
     /**
@@ -998,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
@@ -1026,7 +1398,7 @@ type ExecuteBacktestData = {
         type: DataSourceType;
     };
     query?: never;
-    url: '/backtest/{exchangeId}/{type}/execute';
+    url: "/backtest/{exchangeId}/{type}/execute";
 };
 type ExecuteBacktestErrors = {
     /**
@@ -1061,7 +1433,7 @@ type CancelBacktestData = {
         jobId: string;
     };
     query?: never;
-    url: '/backtest/{exchangeId}/{type}/execute/{jobId}';
+    url: "/backtest/{exchangeId}/{type}/execute/{jobId}";
 };
 type CancelBacktestErrors = {
     /**
@@ -1075,7 +1447,7 @@ type CancelBacktestResponses = {
      * Cancellation request accepted
      */
     200: {
-        status?: 'cancelling';
+        status?: "cancelling";
         jobId?: string;
     };
 };
@@ -1097,7 +1469,7 @@ type GetBacktestResultData = {
         jobId: string;
     };
     query?: never;
-    url: '/backtest/{exchangeId}/{type}/execute/{jobId}';
+    url: "/backtest/{exchangeId}/{type}/execute/{jobId}";
 };
 type GetBacktestResultErrors = {
     /**
@@ -1133,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> & {
@@ -1231,29 +1603,58 @@ declare const downloadTickers: <ThrowOnError extends boolean = false>(options: O
  */
 declare const downloadKlines: <ThrowOnError extends boolean = false>(options: Options<DownloadKlinesData, ThrowOnError>) => _hey_api_client_fetch.RequestResult<Blob | File, ResponseError, ThrowOnError>;
 /**
- * Compile a strategy from source code
- * Submits raw strategy source for compilation. By default the call is synchronous and returns
- * the `strategyId` once compilation succeeds. Set the header `X-Compile-Async: true` to enqueue
- * the compile task and return immediately with a `jobId` — poll
- * `GET /strategy/{strategyId}` to check status.
+ * Compile and register a strategy
+ * Compiles raw strategy source and registers it, returning its `strategyId`.
+ *
+ * **This answers one question: is the source valid Java.** It compiles, registers, and hands
+ * back the id — nothing more. Whether the class can actually run is
+ * `POST /strategy/{strategyId}/validate`, and everything known about a strategy, validation
+ * included, is read from `GET /strategy/{strategyId}`. One place to ask, so there is no second
+ * answer to keep in step.
+ *
+ * The `strategyId` is derived from what the code *means*, not from how it is written. Adding a
+ * comment, inserting a blank line, re-indenting, reordering imports, or moving a method around
+ * all return the **same** id — you have not created a second strategy. Renaming a variable,
+ * changing an identifier's case, reordering fields, or reordering statements inside a method
+ * return a **different** one.
  *
- * The `strategyId` is deterministic: the same source for the same user always produces the
- * same id.
+ * Two rules follow, and they are worth designing around:
+ *
+ * - re-submitting a strategy you have only reformatted is free, and gives you back the id you
+ * already had, along with any validation already recorded against it;
+ * - the id says nothing about *behaviour*. Two sources that compute the same thing by
+ * different means are two strategies, because deciding otherwise would mean deciding program
+ * equivalence.
  *
  */
-declare const compileStrategy: <ThrowOnError extends boolean = false>(options: Options<CompileStrategyData, ThrowOnError>) => _hey_api_client_fetch.RequestResult<CompileStrategyResponse, ResponseError, ThrowOnError>;
+declare const compileStrategy: <ThrowOnError extends boolean = false>(options: Options<CompileStrategyData, ThrowOnError>) => _hey_api_client_fetch.RequestResult<{
+    strategyId: StrategyId;
+}, ResponseError, ThrowOnError>;
 /**
- * Get a strategy by id, including its compile status
- * Polls the status of a strategy compilation. Useful when the strategy was submitted with
- * `X-Compile-Async: true`. Returns the resolved `strategyId` once compilation completes.
+ * Check that a registered strategy can actually run
+ * Instantiates the compiled class and drives it through a bounded synthetic series, so a wiring
+ * fault surfaces here instead of at your first backtest. The verdict — pass or fail, plus any
+ * engine notices — is recorded and served from `GET /strategy/{strategyId}`.
+ *
+ * **Idempotent.** If a verdict already exists for the current compilation it comes straight
+ * back with `200` and nothing is queued. Otherwise the check is queued and this returns `202`;
+ * poll `GET /strategy/{strategyId}` until `validation` is `passed` or `failed`.
+ *
+ * Recompiling supersedes a verdict, which makes this callable again — the old answer described
+ * bytecode that is no longer what would run.
  *
  */
-declare const getStrategy: <ThrowOnError extends boolean = false>(options: Options<GetStrategyData, ThrowOnError>) => _hey_api_client_fetch.RequestResult<{
-    jobId?: string;
-    status: "New" | "Started" | "Completed" | "Aborted" | "Failed";
-    strategyId?: StrategyId;
-    statusDetail?: string | null;
-}, ResponseError, ThrowOnError>;
+declare const validateStrategy: <ThrowOnError extends boolean = false>(options: Options<ValidateStrategyData, ThrowOnError>) => _hey_api_client_fetch.RequestResult<ValidateStrategyResponse, ResponseError, ThrowOnError>;
+/**
+ * Get a strategy by id, including its validation state
+ * Reports that the strategy is registered — implied by a `200` at all — and what validating it
+ * found.
+ *
+ * A `404` means one thing: no such registered strategy for this user. It is never a stale or
+ * expired answer; registration and verdict are stored durably, not cached.
+ *
+ */
+declare const getStrategy: <ThrowOnError extends boolean = false>(options: Options<GetStrategyData, ThrowOnError>) => _hey_api_client_fetch.RequestResult<StrategyState, ResponseError, ThrowOnError>;
 /**
  * Prepare backtest data
  * Enqueues a prepare task over the requested date range. Returns immediately with a `jobId`;
@@ -1277,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>;
 /**
@@ -1293,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
@@ -1335,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 Options, type PrepareBacktestData, type PrepareBacktestError, type PrepareBacktestErrors, type PrepareBacktestResponse, type PrepareBacktestResponses, type PrepareJobState, type PrepareRequest, type ResponseError, type ResultMap, type StrategyId, type SweepAxis, type SweepBaseConfig, type SweepProgress, type SweepRunRow, type SweepSpecRequest, authenticate, cancelBacktest, cancelSweep, client, compileStrategy, downloadKlines, downloadTickers, executeBacktest, executeSweep, getBacktestResult, getPrepareStatus, getStrategy, getSweepResult, listExchanges, listInstruments, listSegmentInstruments, prepareBacktest };
+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 };