@qtsurfer/sdk 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ResultMap, AuthTokenResponse } from '@qtsurfer/api-client';
+import { ResultMap, Exchange as Exchange$1, InstrumentDetail as InstrumentDetail$1, StrategyState as StrategyState$1, SweepProgress as SweepProgress$1, ExecuteSweepAccepted, ExecuteSweepResult, SweepSensitivity as SweepSensitivity$1, SweepHeatmap as SweepHeatmap$1, SweepHeatmapCell as SweepHeatmapCell$1, SweepMarginal as SweepMarginal$1, SweepMarginalPoint as SweepMarginalPoint$1, SweepRunRow as SweepRunRow$1, WalkForwardFold as WalkForwardFold$1, WalkForwardResult as WalkForwardResult$1, AuthTokenResponse } from '@qtsurfer/api-client';
 
 interface BacktestRequest {
     /** Strategy source code (Java) */
@@ -48,9 +48,619 @@ interface BacktestOptions {
     timeoutMs?: number;
 }
 
+/**
+ * One exchange the platform serves. Alias for api-client's `Exchange`:
+ * `id` (what every other call takes as `exchangeId`), `name`, and an
+ * optional `description`.
+ */
+type Exchange = Exchange$1;
+/**
+ * One instrument on an exchange. Alias for api-client's `InstrumentDetail`:
+ * `id` / `base` / `quote`, plus optional `coverage` (the date windows for
+ * which tickers and klines actually exist, per data type), `lastPrice` and
+ * `volume24h`.
+ *
+ * `coverage` is what tells you whether a backtest range is downloadable at
+ * all; it is optional, and absent means the platform did not report one, not
+ * that there is no data.
+ */
+type InstrumentDetail = InstrumentDetail$1;
+/**
+ * A market segment of an exchange. `'spot'` is the default segment served
+ * when {@link QTSurfer.instruments} is called without one.
+ */
+type InstrumentSegment = 'spot' | 'futures';
+
 /** Wire format for hourly tickers/klines downloads. */
 type DownloadFormat = 'lastra' | 'parquet';
 
+/**
+ * Everything the platform records about a registered strategy. Alias for
+ * api-client's `StrategyState`.
+ *
+ * `validation` is the verdict and is one of:
+ *
+ * - `'not_validated'` — registered, never checked.
+ * - `'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.
+ *
+ * **`'passed'` is a floor, not a guarantee.** It means the compiled class
+ * could be instantiated and got through the first event of a short synthetic
+ * run — not the caller's instrument, not the caller's window, and not the
+ * rest of the run. It says nothing about whether the strategy is correct,
+ * profitable, or safe to run at scale. `dryRunIncomplete` marks a check that
+ * ran out of its budget, which makes a `'passed'` verdict a lower floor
+ * still, and makes an empty `notices` list no longer a clean bill of health.
+ *
+ * A verdict describes the bytecode that existed when it was recorded:
+ * `compiledAt` newer than `validatedAt` means the strategy was recompiled
+ * afterwards and the verdict no longer describes what would run.
+ */
+type StrategyState = StrategyState$1;
+/**
+ * Outcome of {@link QTSurfer.validateStrategy} — the SDK's rendering of the
+ * two answers that operation has, which the response body alone cannot tell
+ * apart.
+ *
+ * - `queued: false` — a verdict already existed for the current compilation
+ *   and comes back in `state` unchanged; nothing new was queued. This is
+ *   **not** the same as "terminal": a check queued by an earlier call can
+ *   still be running, so read `state.validation` rather than treating
+ *   `queued: false` as "there is an answer".
+ * - `queued: true` — a check was just queued. Nothing is known yet; poll
+ *   {@link QTSurfer.strategy} until `validation` leaves `'pending'`.
+ */
+type StrategyValidation = {
+    queued: false;
+    strategyId: string;
+    state: StrategyState;
+} | {
+    queued: true;
+    strategyId: string;
+    state?: undefined;
+};
+
+/**
+ * The metric a sweep optimizes, and the one its leaderboard and its
+ * sensitivity surfaces are read against.
+ *
+ * One vocabulary throughout: the objective a {@link SweepRequest} is submitted
+ * with is the objective the leaderboard is ranked by, and the one
+ * {@link Sweep.sensitivity} aggregates unless a different one is asked for.
+ *
+ * - `'sharpe'` — risk-adjusted return; the platform default when a request names none.
+ * - `'sortino'` — downside-risk-adjusted return.
+ * - `'pnl'` — absolute net profit and loss.
+ * - `'maxdd'` — maximum drawdown.
+ */
+type SweepObjective = 'sharpe' | 'sortino' | 'pnl' | 'maxdd';
+/**
+ * How the parameter grid is turned into the list of vectors that actually run.
+ *
+ * - `'grid'` — every combination of every axis value. The platform default;
+ *   cost is the product of the axis sizes.
+ * - `'random'` — uniformly random draws from the grid, capped at
+ *   {@link SweepRequest.samples}.
+ * - `'lhs'` — Latin hypercube draws, which spread the sample more evenly than
+ *   uniform random.
+ *
+ * `samples` is required by `'random'` and `'lhs'` and ignored by `'grid'`.
+ */
+type SweepSampler = 'grid' | 'random' | 'lhs';
+/**
+ * How the ranked leaderboard is ordered.
+ *
+ * The **platform default is `'plateau'`**, so the order a sweep answers with is
+ * *not* raw objective order unless you ask for it. A plateau score is the
+ * objective of the worst run in a point's immediate neighbourhood, so a point
+ * only ranks well when the region around it does too — which exists because
+ * the highest raw score is very often a spike that does not survive the
+ * parameters moving slightly.
+ *
+ * **What you request is not always what you get.** Read `ranking` on the
+ * result to find out which ordering was actually applied: a sweep with no
+ * stored parameter grid has no neighbourhood to score against and falls back
+ * to `'raw'`, and a walk-forward sweep is always `'raw'` because its
+ * leaderboard is one out-of-sample row per fold rather than a grid.
+ *
+ * This applies to the ranked view only. Alongside `order: 'natural'` it is
+ * **ignored** — that view is always ordered by `runIx`.
+ */
+type SweepRanking = 'plateau' | 'raw';
+/**
+ * Which view of a sweep's rows to read: the display leaderboard, or every row
+ * in a stable order.
+ *
+ * - `'ranked'` — the platform default. Sorted, and capped at a display limit;
+ *   `truncated` on the result is `true` when the cap actually bit, in which
+ *   case rows exist that this view does not carry. This is the view
+ *   {@link SweepRanking} applies to.
+ * - `'natural'` — every available row, untruncated, in deterministic `runIx`
+ *   order. The view to read when materialising durable trial rows rather than
+ *   showing a top-N, and the only way to reach rows the ranked view dropped —
+ *   {@link Sweep.results} reads it off an existing sweep without re-running it.
+ *   {@link SweepRanking} is **ignored** here and the response reports `'raw'`;
+ *   rank, plateau score and neighbour count belong to the ranked view and are
+ *   not part of this one.
+ */
+type SweepOrder = 'ranked' | 'natural';
+/**
+ * Sweep lifecycle as observed by the SDK, readable off {@link Sweep.state}.
+ *
+ * - `'executing'` — submitted and being polled.
+ * - `'completed'` — finished. The platform's own status may still be `'PARTIAL'`.
+ * - `'failed'` — the poll itself failed: transport, HTTP, or a stage timeout.
+ * - `'canceled'` — the sweep was aborted and the platform reported it cancelled.
+ */
+type SweepState = 'executing' | 'completed' | 'failed' | 'canceled';
+/**
+ * One strategy property and the values a sweep should try for it: either a
+ * numeric range walked in fixed steps, or an explicit list.
+ *
+ * ```ts
+ * const params: Record<string, ParamAxis> = {
+ *   rsiPeriod: { from: 7, to: 28, step: 1 },
+ *   useTrendFilter: { values: [true, false] },
+ * };
+ * ```
+ *
+ * The two shapes are mutually exclusive on the wire, and mixing them is a
+ * request the platform rejects rather than reconciles. A list entry is a number
+ * or a boolean — the axis of a boolean flag is `{ values: [true, false] }`, not
+ * a range.
+ */
+type ParamAxis = {
+    /** First value. */
+    from: number;
+    /** Last value the walk may reach. */
+    to: number;
+    /** Increment; must be greater than zero. */
+    step: number;
+} | {
+    /** The values to try; at least one. */
+    values: Array<number | boolean>;
+};
+/**
+ * Opt a sweep into walk-forward validation.
+ *
+ * Attaching this changes what the sweep does, not just how much of it runs.
+ * Instead of scoring every parameter vector once over the whole range, the data
+ * is cut into sequential folds; each fold optimizes the whole grid on its own
+ * window and then scores only its winner on the window immediately after — data
+ * that winner was never chosen on. The question it answers is not "which
+ * parameters won" but "does re-optimizing this periodically actually work".
+ *
+ * Omit it and nothing about the sweep changes, including the shape of the
+ * response.
+ *
+ * **It costs folds × grid.** Four folds over a 500-point grid is roughly 2000
+ * backtests where the plain sweep is 500, which is why it is opt-in. The
+ * platform rejects the request outright when that product exceeds its sweep
+ * budget.
+ *
+ * **It is a different sweep, not a variant of one.** Two requests that differ
+ * only in this block do not deduplicate against each other.
+ *
+ * The answer arrives as `walkForward` on the {@link SweepResult} — see
+ * {@link Sweep.result} for how to read it.
+ */
+interface SweepWalkForward {
+    /**
+     * How many sequential optimize-then-score windows to run. Two is the floor
+     * and the reason is structural rather than a tuning preference: parameter
+     * drift is measured between consecutive fold winners, and a single fold has
+     * no consecutive pair, so it would report the strongest possible stability
+     * having measured nothing. The ceiling is a platform setting; exceeding it is
+     * rejected.
+     */
+    folds: number;
+    /**
+     * Share of each fold's window spent optimizing, the rest being where its
+     * winner is scored. Omit to take the platform default. Lower values leave
+     * more data to score on and, on short sessions, are what let the requested
+     * fold count tile the data at all. Must be within 10..90.
+     */
+    inSamplePct?: number;
+}
+/**
+ * What the platform answered when it accepted the sweep, exactly as it sent it
+ * — see {@link Sweep.accepted} for the three fields that make it worth reading
+ * before any result exists.
+ */
+type SweepAccepted = ExecuteSweepAccepted;
+/**
+ * A sweep snapshot: status, progress, and the rows available for the selected
+ * view. Resolved by {@link Sweep.result}, which is also where the semantics of
+ * every field are documented.
+ */
+type SweepResult = ExecuteSweepResult;
+/**
+ * The platform's own progress record for a running sweep, carried on
+ * {@link SweepProgressEvent.snapshot}. Distinct from the event that wraps it:
+ * this is what the server reported, the event is what the SDK emitted.
+ *
+ * Two of its fields are easy to add together by mistake. `aborted` counts
+ * individual runs that executed and aborted — a row-level count. `failedShards`
+ * counts whole units of work (shards, or folds on a walk-forward sweep) that
+ * failed and will not be retried, having never reported anything. A shard that
+ * dies before producing a single row leaves `aborted` at zero, which is exactly
+ * why the second count exists; **summing them double-counts nothing and
+ * describes nothing**.
+ *
+ * `retrying` is not a failure count either — those units failed on something
+ * transient and are queued to be attempted again, so a sweep with a non-zero
+ * value there is still expected to finish.
+ *
+ * `etaSeconds` is **omitted, never zero** when it cannot be computed: a sweep
+ * with nothing finished has no observed rate to extrapolate from, and a zero
+ * would read as "about to finish". When present it runs conservative — it
+ * excludes queue wait entirely, and a sweep that spent part of its life being
+ * retried will have diluted the rate it is derived from.
+ */
+type SweepProgress = SweepProgress$1;
+/** One trial on a sweep's leaderboard. See {@link Sweep.result} for how to read it. */
+type SweepRunRow = SweepRunRow$1;
+/**
+ * Sensitivity aggregates over a sweep's stored rows, returned by
+ * {@link Sweep.sensitivity}. Marginals are always complete; the pair surfaces
+ * may be capped, in which case `heatmapsTruncated` is `true`.
+ */
+type SweepSensitivity = SweepSensitivity$1;
+/** One axis, with every other axis collapsed away. */
+type SweepMarginal = SweepMarginal$1;
+/** How the objective behaved at one value of one axis. */
+type SweepMarginalPoint = SweepMarginalPoint$1;
+/** The surface for one pair of axes, with all others collapsed away. */
+type SweepHeatmap = SweepHeatmap$1;
+/** One cell of a {@link SweepHeatmap}. */
+type SweepHeatmapCell = SweepHeatmapCell$1;
+/**
+ * The walk-forward section of a {@link SweepResult}, present exactly when the
+ * sweep was submitted with {@link SweepWalkForward}.
+ *
+ * **`paramDrift` absent is not zero.** The field is omitted whenever the figure
+ * could not be computed — fewer than two folds finished, or no stored grid to
+ * place the winners on — and zero is itself a meaningful reading there (winners
+ * that never moved), so a placeholder would be indistinguishable from perfect
+ * stability.
+ */
+type WalkForwardResult = WalkForwardResult$1;
+/**
+ * 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 = WalkForwardFold$1;
+/**
+ * A parameter sweep over one instrument and one window: the same strategy run
+ * once per parameter vector, scored and ranked against a single objective.
+ *
+ * ```ts
+ * const request: SweepRequest = {
+ *   strategy: source,
+ *   exchangeId: 'binance',
+ *   instrument: 'BTC/USDT',
+ *   from: '2026-01-01T00:00:00Z',
+ *   to: '2026-02-01T00:00:00Z',
+ *   params: {
+ *     rsiPeriod: { from: 7, to: 28, step: 1 },
+ *     useTrendFilter: { values: [true, false] },
+ *   },
+ *   objective: 'sharpe',
+ * };
+ * ```
+ */
+interface SweepRequest {
+    /** Strategy source code (Java), compiled once and reused by every trial. */
+    strategy: string;
+    /** Exchange id, e.g. `binance`. */
+    exchangeId: string;
+    /** Instrument symbol, e.g. `BTC/USDT`. */
+    instrument: string;
+    /** Range start (ISO-8601, ISO DATE, or BASIC ISO DATE). */
+    from: string;
+    /** Range end (same formats as `from`; must be later than `from`). */
+    to: string;
+    /** The grid: one {@link ParamAxis} per strategy property to vary. At least one. */
+    params: Record<string, ParamAxis>;
+    /**
+     * How the grid becomes the list of vectors actually run. Omit to keep the
+     * platform default, the full cross product.
+     */
+    sampler?: SweepSampler;
+    /**
+     * How many vectors to draw for `'random'` and `'lhs'`; ignored by `'grid'`.
+     */
+    samples?: number;
+    /**
+     * Reproducibility seed. Omit to let the platform generate one and report it
+     * back on {@link Sweep.accepted}, so a randomly sampled sweep can be replayed
+     * exactly by submitting the same seed again.
+     */
+    seed?: number;
+    /**
+     * The metric to optimize and rank by; omit to keep the platform default
+     * (`'sharpe'`). It is also what {@link Sweep.sensitivity} aggregates unless
+     * told otherwise.
+     */
+    objective?: SweepObjective;
+    /**
+     * Opt into walk-forward validation, which changes both what runs and the
+     * shape of the answer. Omit to run an ordinary sweep.
+     */
+    walkForward?: SweepWalkForward;
+}
+/**
+ * Emitted at stage transitions and after each poll of a running sweep.
+ *
+ * The `snapshot` is where the detail lives — see {@link SweepProgress}, whose
+ * counts measure different things and must not be added together.
+ */
+interface SweepProgressEvent {
+    /** Current workflow stage. */
+    stage: BacktestStage;
+    /**
+     * 0-100, computed from the runs finished out of the runs expected (`done` /
+     * `total` on the snapshot, both run-level counts — not the shard counts,
+     * which partition units of work rather than runs). Absent on stage
+     * transitions before the first poll.
+     */
+    percent?: number;
+    /**
+     * Fraction (0-1) of the requested window that actually holds data, as
+     * reported once preparation completes. Present only on the final `preparing`
+     * event. Worth reading on a sweep in particular: a thinly covered window is
+     * about to be scored once per parameter vector.
+     */
+    coverageRatio?: number;
+    /**
+     * The platform's progress record for the sweep. Present only on `executing`
+     * events.
+     */
+    snapshot?: SweepProgress;
+}
+/** Tuning knobs for a {@link QTSurfer.sweep} invocation. */
+interface SweepOptions {
+    /**
+     * Ask the platform to stop the sweep between parameter vectors.
+     *
+     * **Aborting does not reject {@link Sweep.result}** — it resolves with
+     * whatever was scored before the stop. That is a deliberate divergence from
+     * `backtest()`, which rejects with `QTSCanceledError` when its run is
+     * aborted; see {@link Sweep.result} for why. Aborting *before* the platform
+     * has accepted the sweep — during compile, prepare or submission — rejects
+     * the {@link QTSurfer.sweep} call itself with `QTSCanceledError`, since there
+     * is no sweep yet and so no rows to keep.
+     */
+    signal?: AbortSignal;
+    /** Called on stage transitions and after each poll with updated progress. */
+    onProgress?: (p: SweepProgressEvent) => void;
+    /**
+     * Initial interval between polls. Default 2000ms, backed off up to
+     * `maxPollIntervalMs`. Longer than a single backtest's, because a sweep is
+     * many backtests and its leaderboard changes on the timescale of shards
+     * finishing rather than ticks.
+     */
+    pollIntervalMs?: number;
+    /** Upper bound for exponential backoff. Default 15000ms. */
+    maxPollIntervalMs?: number;
+    /**
+     * Per-stage timeout. Default none. A sweep is many backtests, so the execute
+     * stage legitimately outlasts anything a single run would take.
+     */
+    timeoutMs?: number;
+    /**
+     * How to order the leaderboard the poll reads. Omit to send no preference and
+     * take the platform default, which is `'plateau'` — so leaving this unset
+     * does **not** give you raw objective order. What was actually applied is
+     * reported on the result. **Ignored entirely when `order` is `'natural'`**,
+     * which is always ordered by `runIx`; the platform accepts both and answers
+     * with the ordering it applied.
+     */
+    ranking?: SweepRanking;
+    /**
+     * Which view of the rows the background poll reads. Omit to take the platform
+     * default, `'ranked'` — the sorted, display-capped leaderboard. `'natural'`
+     * returns every available row untruncated.
+     *
+     * This only decides what {@link Sweep.result} resolves with. Reading the same
+     * sweep another way afterwards — to reach the rows a `truncated` ranked view
+     * dropped, say — is {@link Sweep.results}, which re-reads rather than
+     * re-running.
+     */
+    order?: SweepOrder;
+}
+/**
+ * Handle for a running parameter sweep, returned by {@link QTSurfer.sweep} once
+ * the platform has accepted it. The leaderboard keeps being polled in the
+ * background.
+ */
+interface Sweep {
+    /** Server-side sweep identifier. */
+    readonly sweepId: string;
+    /**
+     * The prepared dataset every trial ran against — the prepare jobId the
+     * workflow resolved before submitting, which is also what addresses this
+     * sweep on the wire.
+     *
+     * This is the value the workflow prepared with, not the acceptance echo of
+     * it. {@link Sweep.accepted} carries the echo, unmodified, for anyone who
+     * wants to compare the two.
+     */
+    readonly requestId: string;
+    /** The compiled strategy every trial shares. */
+    readonly strategyId: string;
+    /**
+     * What acceptance already answered, before a single trial has run, exactly as
+     * the platform sent it.
+     *
+     * Three of its fields are the reason this is exposed rather than folded away:
+     *
+     * - `seed` — the effective seed, generated platform-side when the request
+     *   omitted one. Submitting it again is what makes a randomly sampled sweep
+     *   replayable.
+     * - `queued` — `false` means an identical sweep already existed and nothing
+     *   new was enqueued. The handle is still valid and still resolves; it is
+     *   just reading a sweep this call did not start.
+     * - `walkForward` — present exactly when this is a walk-forward sweep. It is
+     *   the discriminator, and it is available here immediately, so code watching
+     *   progress can branch on the answer's shape without waiting for
+     *   {@link Sweep.result}.
+     */
+    readonly accepted: SweepAccepted;
+    /**
+     * Local snapshot of the sweep lifecycle; reading it does not contact the
+     * server.
+     */
+    readonly state: SweepState;
+    /**
+     * Resolves with the final leaderboard once the sweep stops advancing.
+     *
+     * **This resolves on every terminal status, cancellation included** —
+     * `'COMPLETED'`, `'PARTIAL'` and `'CANCELLED'` all hand back the result
+     * rather than raising. That is a deliberate divergence from `backtest()`,
+     * which rejects with `QTSCanceledError` when its run is aborted: cancelling a
+     * sweep is documented as leaving completed rows readable, and throwing them
+     * away would lose the only reason to cancel a sweep late rather than early.
+     * Read `status` to find out which of the three you got. The promise rejects
+     * only for transport failures, HTTP errors, and stage timeouts.
+     *
+     * `'PARTIAL'` means at least one unit of work died and its runs are simply
+     * missing. There is no failed status for a sweep as a whole, so a sweep whose
+     * every shard died is `'PARTIAL'` with an empty leaderboard — check
+     * `leaderboardSize` before reading anything into a top row.
+     *
+     * ### Reading the leaderboard
+     *
+     * **The default order is not the raw objective order.** It is plateau order,
+     * and `ranking` on the result says which was actually applied — not always
+     * the one requested, because a sweep with no stored parameter grid cannot be
+     * plateau-ranked and falls back to raw. See {@link SweepRanking}.
+     *
+     * **The default view is capped.** When `truncated` is `true`, rows exist that
+     * the leaderboard does not carry — `leaderboardSize` counts what is
+     * available. {@link Sweep.results} with `order: 'natural'` is what returns
+     * all of them, in `runIx` order and with no ranking applied. That is a
+     * re-read of this same sweep, not a second one.
+     *
+     * **`plateauScore` and `neighbourCount` are read together.** A neighbour
+     * count of `0` means the point had no neighbours in the grid to compare
+     * against, so its plateau score is unevidenced rather than confirmed — on its
+     * own it is indistinguishable from a genuinely robust one.
+     *
+     * **`deflatedSharpe`** is the probability that a row's Sharpe reflects real
+     * edge rather than the best draw from however many vectors were tried. Around
+     * 0.95 and up it survives the multiple-testing correction; near 0.5 or below
+     * it is not distinguishable from the best of a pile of coin flips. It is
+     * absent on aborted runs, and on sweeps with too few trials to establish any
+     * dispersion to deflate against.
+     *
+     * **`pbo`** is the probability of backtest overfitting for the sweep as a
+     * whole: how often the configuration that won in-sample lands below median
+     * out-of-sample. Above roughly 0.5 the sweep is selecting noise, and that
+     * verdict is about the search, not about any one row — a high value
+     * discredits the top row however good it looks. It is computed once the last
+     * unit of work finishes, so it is absent while the sweep is still running and
+     * on sweeps too small for the statistic to mean anything.
+     *
+     * ### A walk-forward sweep answers in a different shape
+     *
+     * `walkForward` is the discriminator, and it appears as soon as the sweep is
+     * accepted — before any fold has finished — so it is safe to branch on while
+     * polling (it is also on {@link Sweep.accepted}). When it is present, 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
+     * position in the grid**. No plateau score, deflated Sharpe or PBO figure is
+     * reported for one — the out-of-sample numbers are already the honest
+     * measurement. See {@link WalkForwardResult} for why an absent `paramDrift`
+     * is not a zero.
+     *
+     * ### An empty leaderboard is not always an empty answer
+     *
+     * A sweep can finish having scored nothing, because every shard failed before
+     * producing a row. When that happens `failReason` carries the cause reported
+     * by the *first* shard to fail — typically something the whole grid would have
+     * hit, such as a strategy that could not be loaded. Read it before concluding
+     * that a sweep with no rows simply found nothing: those are different
+     * outcomes and the leaderboard alone cannot tell them apart. Only the first
+     * failure is recorded, so where several shards failed for different reasons
+     * this names one of them rather than summarising all — pair it with
+     * `progress.failedShards` for the count.
+     */
+    readonly result: Promise<SweepResult>;
+    /**
+     * Re-read this sweep's rows under a different view.
+     *
+     * **This is a read, not a re-run.** It compiles nothing, prepares nothing and
+     * submits nothing: the same sweep is asked for its rows again with different
+     * query parameters, so no second sweep is created and nothing is enqueued.
+     * The view a {@link SweepOptions} chose applies to the background poll behind
+     * {@link Sweep.result}; this is how to look at the same sweep another way
+     * afterwards.
+     *
+     * **It is the route to rows the ranked view dropped.** When `truncated` is
+     * `true` on a result, rows exist that the leaderboard does not carry;
+     * `order: 'natural'` returns every available row untruncated, in
+     * deterministic `runIx` order.
+     *
+     * **`ranking` is ignored when `order` is `'natural'`** — that view is always
+     * ordered by `runIx`, and the response reports `'raw'`. The platform accepts
+     * both rather than rejecting the pair, and answers with the ordering it
+     * actually applied.
+     *
+     * Readable while the sweep is still running, in which case it returns the
+     * rows finished so far — exactly like {@link Sweep.sensitivity}. Like every
+     * handle-scoped call, it does not take part in an
+     * {@link AuthenticatedClient}'s refresh-on-401 policy.
+     *
+     * @param view which view to read; an absent property takes the platform
+     * default (`order: 'ranked'`, `ranking: 'plateau'`)
+     * @throws QTSError on any non-2xx response, with the HTTP status on `status`.
+     */
+    results(view?: {
+        order?: SweepOrder;
+        ranking?: SweepRanking;
+    }): Promise<SweepResult>;
+    /**
+     * 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 whole budget on an axis that never moved the objective at all,
+     * and the top rows hide 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 did not matter over the
+     * range swept. `best`, `mean` and `worst` are all reported because them
+     * disagreeing is the signal — a value with a high best and a poor mean only
+     * works in specific company, which is an interaction, and a single number
+     * would hide it. A *heatmap* does the same over a pair of axes, where that
+     * interaction is visible directly.
+     *
+     * **Check `heatmapsTruncated`.** Marginals are always complete; the pair
+     * surfaces are quadratic in the axis count and may be capped to stay inside
+     * the response budget. When the flag is `true`, at least one pair was left
+     * out, so the list you have is not the full set of interactions. This method
+     * hands back the whole {@link SweepSensitivity} rather than just its surfaces
+     * precisely so that flag cannot be lost on the way out.
+     *
+     * Readable while the sweep is still running, in which case the aggregates
+     * describe the runs finished so far and `rowsAnalysed` says how many that
+     * was. Aborted runs are excluded throughout: 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.
+     *
+     * Like every handle-scoped call, this does not take part in an
+     * {@link AuthenticatedClient}'s refresh-on-401 policy.
+     *
+     * @param objective which metric to aggregate; omit to use the objective the
+     * sweep was submitted with
+     * @throws QTSError on any non-2xx response, with the HTTP status on `status`.
+     */
+    sensitivity(objective?: SweepObjective): Promise<SweepSensitivity>;
+}
+
 /** Configuration for {@link QTSurfer}. */
 interface QTSurferOptions {
     /** Base URL of the QTSurfer API, e.g. `https://api.qtsurfer.com/v1`. */
@@ -79,7 +689,9 @@ interface DownloadHourArgs {
 }
 /**
  * Thin, stateless wrapper over `@qtsurfer/api-client` that exposes the SDK's
- * workflow methods (`backtest`, `tickers`, `klines`). Constructing an
+ * workflow methods (`backtest`, `sweep`, `tickers`, `klines`), the platform catalog
+ * (`exchanges`, `instruments`) and the strategy surface (`validateStrategy`,
+ * `strategy`). Constructing an
  * instance reconfigures the underlying api-client singleton, so avoid
  * holding two `QTSurfer`s with different `baseUrl`s or tokens alive in the
  * same process — they will race. Prefer the `authenticate()` helper over
@@ -94,6 +706,45 @@ declare class QTSurfer {
      * stage-by-stage error and retry semantics.
      */
     backtest(req: BacktestRequest, opts?: BacktestOptions): Promise<BacktestResult>;
+    /**
+     * Run the full compile → prepare → executeSweep pipeline and resolve once the
+     * platform has accepted the sweep, handing back a {@link Sweep} that keeps
+     * polling the leaderboard in the background.
+     *
+     * The whole sweep is one call because the execute-sweep endpoint is addressed
+     * by the id of an already-prepared dataset: exposing the stages separately
+     * would hand dataset lifecycle to the caller and buy nothing. Preparing is
+     * idempotent, so sweeping the same window twice prepares it once.
+     *
+     * The returned promise rejects with {@link QTSStrategyCompileError} if
+     * compilation fails, {@link QTSPreparationError} if data preparation fails,
+     * {@link QTSExecutionError} if the platform rejects the sweep — an expanded
+     * grid over the server limit, or a walk-forward request whose fold count
+     * multiplies past the sweep budget, both answer `400` — {@link QTSTimeoutError}
+     * if a stage exceeds `timeoutMs`, or {@link QTSCanceledError} if the caller's
+     * signal fires before the sweep is accepted. A plain {@link QTSError} means
+     * the request itself is malformed (an empty grid, a non-positive `step`, a
+     * walk-forward block with fewer than two folds) and never reached the network.
+     *
+     * What the sweep *found* arrives through {@link Sweep.result}, which is also
+     * where the semantics of the leaderboard are documented. Acceptance already
+     * answers three things worth reading before any result exists — the effective
+     * seed, whether this submission enqueued anything, and whether this is a
+     * walk-forward sweep — see {@link Sweep.accepted}.
+     *
+     * ```ts
+     * const handle = await qts.sweep({
+     *   strategy: source,
+     *   exchangeId: 'binance',
+     *   instrument: 'BTC/USDT',
+     *   from: '2026-01-01T00:00:00Z',
+     *   to: '2026-02-01T00:00:00Z',
+     *   params: { rsiPeriod: { from: 7, to: 28, step: 1 } },
+     * });
+     * const leaderboard = await handle.result;
+     * ```
+     */
+    sweep(req: SweepRequest, opts?: SweepOptions): Promise<Sweep>;
     /**
      * Download one hour of raw tickers for an instrument as a {@link Blob}.
      * Defaults to Lastra; pass `{ format: 'parquet' }` for Parquet.
@@ -101,14 +752,89 @@ declare class QTSurfer {
     tickers(args: DownloadHourArgs): Promise<Blob>;
     /** Download one hour of klines for an instrument as a {@link Blob}. */
     klines(args: DownloadHourArgs): Promise<Blob>;
+    /**
+     * List the exchanges the platform serves. Each `id` is what every other
+     * method takes as `exchangeId`.
+     *
+     * @throws QTSError on any non-2xx response, with the HTTP status on
+     * `status`.
+     */
+    exchanges(): Promise<Exchange[]>;
+    /**
+     * List an exchange's instruments, each with the per-data-type `coverage`
+     * that says which date windows are actually downloadable.
+     *
+     * Omitting `segment` asks for the exchange's **default** segment, which is
+     * `'spot'` today. The API answers with a HAL envelope that this method
+     * unwraps to the instrument array, so the envelope's `meta.segment`,
+     * `meta.updatedAt` and segment-discovery `_links` do not reach you: if you
+     * need certainty about which segment you are looking at, pass `segment`
+     * explicitly rather than relying on the default.
+     *
+     * @param exchangeId exchange identifier, e.g. `binance`
+     * @throws QTSError on any non-2xx response, with the HTTP status on
+     * `status`.
+     */
+    instruments(exchangeId: string, segment?: InstrumentSegment): Promise<InstrumentDetail[]>;
+    /**
+     * Ask the platform to check that a registered strategy can actually run:
+     * it instantiates the compiled class and drives it through a bounded
+     * synthetic series, so a wiring fault surfaces here instead of at the first
+     * backtest.
+     *
+     * **Idempotent, and two-outcome.** `queued: false` means a verdict already
+     * existed for the current compilation and came back unchanged in `state` —
+     * nothing was queued. `queued: true` means a check was just started, and is
+     * **not** terminal: poll {@link QTSurfer.strategy} until `validation`
+     * leaves `'pending'`. The discriminant reports whether work was *started*,
+     * not whether a verdict *exists*, because a `queued: false` answer can
+     * itself carry `validation: 'pending'` from a check an earlier call queued;
+     * `state.validation` is what tells you that.
+     *
+     * **Poll with a deadline of your own.** `'pending'` is not guaranteed to
+     * resolve — a queued check can go unreported for far longer than one takes,
+     * which the platform eventually flags as `validationStalled`. Nothing about
+     * the strategy is disproved when that happens, but a caller that waits for
+     * a terminal verdict without a timeout can wait forever. This SDK ships no
+     * polling helper for that reason: the timeout is the caller's policy.
+     *
+     * Whatever the verdict, it is a floor rather than a guarantee — see
+     * {@link StrategyState}.
+     *
+     * @param strategyId the id returned when the strategy was compiled
+     * @throws QTSError on any non-2xx response; a `404` (carried on `status`)
+     * means no such registered strategy for this caller.
+     */
+    validateStrategy(strategyId: string): Promise<StrategyValidation>;
+    /**
+     * Read everything the platform records about a strategy: whether it is
+     * registered at all, its validation verdict, the market data its compiled
+     * class requires, and any engine notices the check raised. This is what to
+     * poll after {@link QTSurfer.validateStrategy} returns `queued: true`, and
+     * the only place a verdict is read from.
+     *
+     * Check `compiledAt` against `validatedAt` before trusting a verdict: the
+     * strategy may have been recompiled since it was recorded, in which case
+     * the verdict describes bytecode that is no longer what would run.
+     * See {@link StrategyState} for why even a fresh `'passed'` is a floor
+     * rather than a guarantee.
+     *
+     * @param strategyId the id returned when the strategy was compiled
+     * @throws QTSError on any non-2xx response. A `404` (carried on `status`)
+     * means exactly one thing — no such registered strategy for this caller.
+     * It is never a stale or expired answer.
+     */
+    strategy(strategyId: string): Promise<StrategyState>;
 }
 
 /**
  * Base class for every error the SDK throws. Catch this to handle all SDK
  * failures generically, or catch a specific subclass below to tell which
  * stage failed. `status` is only set when the throw site had an HTTP status
- * to attach — today that is just {@link QTSDownloadError}; the workflow-stage
- * errors carry `cause` instead and encode retryability in their message.
+ * to attach: {@link QTSDownloadError} always carries one, and so does the
+ * plain `QTSError` thrown by the single-request calls (`exchanges`,
+ * `instruments`, `validateStrategy`, `strategy`). The workflow-stage errors
+ * carry `cause` instead and encode retryability in their message.
  */
 declare class QTSError extends Error {
     readonly cause?: unknown | undefined;
@@ -259,21 +985,68 @@ declare class AuthenticatedClient {
      * triggering a refresh.
      */
     backtest(req: BacktestRequest, opts?: BacktestOptions): Promise<BacktestResult>;
+    /**
+     * Run the full compile → prepare → executeSweep pipeline and resolve once the
+     * platform has accepted the sweep, handing back a {@link Sweep} that keeps
+     * polling the leaderboard in the background. See {@link QTSurfer.sweep} for
+     * why the sweep is one call rather than composable stages, and
+     * {@link Sweep.result} for how to read what it found.
+     *
+     * The currently cached token is sent (minting one first if none is cached),
+     * but as with `backtest()` a `401` here is **not** auto-retried: the
+     * underlying stage errors carry no HTTP status, so a token that expires
+     * mid-pipeline surfaces as `QTSPreparationError`/`QTSExecutionError` rather
+     * than triggering a refresh.
+     *
+     * The background leaderboard poll and {@link Sweep.sensitivity} sit outside
+     * the policy for a second, independent reason: both run after this promise
+     * has already resolved, so a token that expires while a sweep is in flight
+     * surfaces on {@link Sweep.result} whatever the stage errors carry.
+     */
+    sweep(req: SweepRequest, opts?: SweepOptions): Promise<Sweep>;
     /** Download one hour of raw tickers. Refreshes the token once on `401` before retrying. */
     tickers(args: DownloadHourArgs): Promise<Blob>;
     /** Download one hour of klines. Refreshes the token once on `401` before retrying. */
     klines(args: DownloadHourArgs): Promise<Blob>;
+    /**
+     * List the exchanges the platform serves. Refreshes the token once on `401`
+     * before retrying.
+     */
+    exchanges(): Promise<Exchange[]>;
+    /**
+     * List an exchange's instruments, optionally for a specific segment.
+     * Refreshes the token once on `401` before retrying. See
+     * {@link QTSurfer.instruments} for what the unwrapped HAL envelope leaves
+     * out.
+     */
+    instruments(exchangeId: string, segment?: InstrumentSegment): Promise<InstrumentDetail[]>;
+    /**
+     * Ask the platform to check that a registered strategy can actually run.
+     * Refreshes the token once on `401` before retrying. Two-outcome — see
+     * {@link QTSurfer.validateStrategy}; `queued: true` is not terminal and
+     * must be followed by polling {@link AuthenticatedClient.strategy} under a
+     * deadline of your own.
+     */
+    validateStrategy(strategyId: string): Promise<StrategyValidation>;
+    /**
+     * Read a strategy's recorded state, including its validation verdict.
+     * Refreshes the token once on `401` before retrying. See
+     * {@link StrategyState} for why a `'passed'` verdict is a floor rather than
+     * a guarantee.
+     */
+    strategy(strategyId: string): Promise<StrategyState>;
 }
 /**
  * Exchange a long-lived API key for an authenticated session.
  *
  * If `apikey` is omitted, the SDK reads `QTSURFER_APIKEY` from the
  * environment. The returned {@link AuthenticatedClient} caches the JWT,
- * refreshes it on 401, and exposes the same workflow surface as
- * `QTSurfer` (`backtest`, `tickers`, `klines`).
+ * refreshes it on 401, and exposes the same surface as `QTSurfer`
+ * (`backtest`, `sweep`, `tickers`, `klines`, `exchanges`, `instruments`,
+ * `validateStrategy`, `strategy`).
  *
  * @throws {QTSAuthError} if no apikey is supplied or available in env.
  */
 declare function authenticate(apikey?: string, opts?: AuthOptions): Promise<AuthenticatedClient>;
 
-export { type AuthOptions, AuthenticatedClient, type BacktestOptions, type BacktestProgress, type BacktestRequest, type BacktestResult, type BacktestStage, type DownloadFormat, type DownloadHourArgs, InMemoryTokenStore, QTSAuthError, QTSCanceledError, QTSDownloadError, QTSError, QTSExecutionError, QTSPreparationError, QTSStrategyCompileError, QTSTimeoutError, QTSurfer, type QTSurferOptions, type TokenStore, authenticate };
+export { type AuthOptions, AuthenticatedClient, type BacktestOptions, type BacktestProgress, type BacktestRequest, type BacktestResult, type BacktestStage, type DownloadFormat, type DownloadHourArgs, type Exchange, InMemoryTokenStore, type InstrumentDetail, type InstrumentSegment, type ParamAxis, QTSAuthError, QTSCanceledError, QTSDownloadError, QTSError, QTSExecutionError, QTSPreparationError, QTSStrategyCompileError, QTSTimeoutError, QTSurfer, type QTSurferOptions, type StrategyState, type StrategyValidation, type Sweep, type SweepAccepted, type SweepHeatmap, type SweepHeatmapCell, type SweepMarginal, type SweepMarginalPoint, type SweepObjective, type SweepOptions, type SweepOrder, type SweepProgress, type SweepProgressEvent, type SweepRanking, type SweepRequest, type SweepResult, type SweepRunRow, type SweepSampler, type SweepSensitivity, type SweepState, type SweepWalkForward, type TokenStore, type WalkForwardFold, type WalkForwardResult, authenticate };