@qtsurfer/sdk 0.7.1 → 0.8.0

package/dist/index.js

@@ -5,20 +5,8 @@ import { client as apiClient } from "@qtsurfer/api-client";
 import {
   cancelBacktest,
   executeBacktest,
-  getBacktestResult,
-  getPrepareStatus,
-  compileStrategy as apiCompileStrategy,
-  prepareBacktest
+  getBacktestResult
 } from "@qtsurfer/api-client";
-import {
-  ExponentialBackoff,
-  TaskCancelledError,
-  TimeoutStrategy,
-  handleWhenResult,
-  retry,
-  timeout,
-  wrap
-} from "cockatiel";
 
 // src/errors.ts
 var QTSError = class extends Error {
@@ -75,27 +63,27 @@ var QTSAuthError = class extends QTSError {
   }
 };
 
-// src/workflows/backtest.ts
-var TICKER = "ticker";
+// src/internal/polling.ts
+import {
+  ExponentialBackoff,
+  TaskCancelledError,
+  TimeoutStrategy,
+  handleWhenResult,
+  retry,
+  timeout,
+  wrap
+} from "cockatiel";
 function normalizeStatus(raw) {
   const value = typeof raw === "string" ? raw.toLowerCase() : "";
   if (value === "completed") return "completed";
+  if (value === "partial") return "completed";
   if (value === "failed") return "failed";
   if (value === "aborted" || value === "cancelled" || value === "canceled") {
     return "aborted";
   }
   return "in-progress";
 }
-async function backtest(req, opts = {}) {
-  const policy = buildStagePolicy(opts);
-  opts.onProgress?.({ stage: "compiling" });
-  const strategyId = await compileStrategy(req.strategy, opts);
-  opts.onProgress?.({ stage: "preparing" });
-  const prepareJobId = await prepareData(req, policy, opts);
-  opts.onProgress?.({ stage: "executing" });
-  return executeStrategy(req, prepareJobId, strategyId, policy, opts);
-}
-function buildStagePolicy(opts) {
+function buildStagePolicy(opts, defaultPollMs, defaultMaxPollMs) {
   const retryPolicy = retry(
     handleWhenResult((r) => {
       const status = r?.status;
@@ -104,17 +92,44 @@ function buildStagePolicy(opts) {
     {
       maxAttempts: Number.MAX_SAFE_INTEGER,
       backoff: new ExponentialBackoff({
-        initialDelay: opts.pollIntervalMs ?? 500,
-        maxDelay: opts.maxPollIntervalMs ?? 5e3
+        initialDelay: opts.pollIntervalMs ?? defaultPollMs,
+        maxDelay: opts.maxPollIntervalMs ?? defaultMaxPollMs
       })
     }
   );
   return opts.timeoutMs ? wrap(timeout(opts.timeoutMs, TimeoutStrategy.Cooperative), retryPolicy) : retryPolicy;
 }
-async function compileStrategy(source, opts) {
+async function runStage(policy, fetchFn, run = {}) {
+  try {
+    return await policy.execute(async (ctx) => {
+      if (run.signal?.aborted) throw new QTSCanceledError("Workflow aborted");
+      const result = await fetchFn(ctx);
+      run.onEachAttempt?.(result);
+      if (run.signal?.aborted) throw new QTSCanceledError("Workflow aborted");
+      return result;
+    }, run.signal);
+  } catch (err) {
+    if (err instanceof QTSCanceledError) throw err;
+    if (err instanceof TaskCancelledError) {
+      if (run.signal?.aborted) throw new QTSCanceledError("Workflow aborted", err);
+      throw new QTSTimeoutError(`Stage exceeded ${run.timeoutMs}ms`, err);
+    }
+    if (run.signal?.aborted) throw new QTSCanceledError("Workflow aborted", err);
+    throw err;
+  }
+}
+
+// src/internal/preparation.ts
+import {
+  getPrepareStatus,
+  compileStrategy as apiCompileStrategy,
+  prepareBacktest
+} from "@qtsurfer/api-client";
+var TICKER = "ticker";
+async function compileStrategySource(source, signal) {
   const { data, error, response } = await apiCompileStrategy({
     body: source,
-    ...opts.signal ? { signal: opts.signal } : {}
+    ...signal ? { signal } : {}
   });
   if (error) {
     if (response?.status === 429) {
@@ -130,30 +145,31 @@ async function compileStrategy(source, opts) {
   }
   return data.strategyId;
 }
-async function prepareData(req, policy, opts) {
+async function prepareDataset(target, policy, run = {}) {
   const { data, error } = await prepareBacktest({
-    path: { exchangeId: req.exchangeId, type: TICKER },
-    body: { instrument: req.instrument, from: req.from, to: req.to },
-    ...opts.signal ? { signal: opts.signal } : {}
+    path: { exchangeId: target.exchangeId, type: TICKER },
+    body: { instrument: target.instrument, from: target.from, to: target.to },
+    ...run.signal ? { signal: run.signal } : {}
   });
   if (error) throw new QTSPreparationError("Prepare submission failed", error);
   if (!data?.jobId) throw new QTSPreparationError("Missing jobId in prepare response");
   const prepareJobId = data.jobId;
   const state = await runStage(
     policy,
-    opts,
     async ({ signal }) => {
       const res = await getPrepareStatus({
-        path: { exchangeId: req.exchangeId, type: TICKER, jobId: prepareJobId },
+        path: { exchangeId: target.exchangeId, type: TICKER, jobId: prepareJobId },
         signal
       });
       if (res.error) throw new QTSPreparationError("Preparation status request failed", res.error);
       if (!res.data) throw new QTSPreparationError("Empty preparation status response");
       return res.data;
     },
-    (r) => {
-      if (r.size > 0) {
-        opts.onProgress?.({ stage: "preparing", percent: r.completed / r.size * 100 });
+    {
+      ...run.signal ? { signal: run.signal } : {},
+      ...run.timeoutMs !== void 0 ? { timeoutMs: run.timeoutMs } : {},
+      onEachAttempt: (r) => {
+        if (r.size > 0) run.onPercent?.(r.completed / r.size * 100);
       }
     }
   );
@@ -164,9 +180,45 @@ async function prepareData(req, policy, opts) {
   if (prepNorm === "aborted") {
     throw new QTSCanceledError("Data preparation aborted");
   }
-  opts.onProgress?.({ stage: "preparing", percent: 100, coverageRatio: state.coverageRatio });
+  run.onPrepared?.(state);
   return prepareJobId;
 }
+
+// src/workflows/backtest.ts
+var DEFAULT_POLL_INTERVAL_MS = 500;
+var DEFAULT_MAX_POLL_INTERVAL_MS = 5e3;
+async function backtest(req, opts = {}) {
+  const policy = buildStagePolicy(opts, DEFAULT_POLL_INTERVAL_MS, DEFAULT_MAX_POLL_INTERVAL_MS);
+  opts.onProgress?.({ stage: "compiling" });
+  const strategyId = await compileStrategySource(req.strategy, opts.signal);
+  opts.onProgress?.({ stage: "preparing" });
+  const prepareJobId = await prepareData(req, policy, opts);
+  opts.onProgress?.({ stage: "executing" });
+  return executeStrategy(req, prepareJobId, strategyId, policy, opts);
+}
+function prepareData(req, policy, opts) {
+  return prepareDataset(
+    {
+      exchangeId: req.exchangeId,
+      instrument: req.instrument,
+      from: req.from,
+      to: req.to
+    },
+    policy,
+    {
+      ...opts.signal ? { signal: opts.signal } : {},
+      ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {},
+      onPercent: (percent) => opts.onProgress?.({ stage: "preparing", percent }),
+      // Surface the backend's coverage ratio for the prepared window (spec 0.98.0) on the
+      // final preparing event, so callers can react to a partially-covered range.
+      onPrepared: (state) => opts.onProgress?.({
+        stage: "preparing",
+        percent: 100,
+        coverageRatio: state.coverageRatio
+      })
+    }
+  );
+}
 async function executeStrategy(req, prepareJobId, strategyId, policy, opts) {
   const { data, error } = await executeBacktest({
     path: { exchangeId: req.exchangeId, type: TICKER },
@@ -183,7 +235,6 @@ async function executeStrategy(req, prepareJobId, strategyId, policy, opts) {
   try {
     const finalResult = await runStage(
       policy,
-      opts,
       async ({ signal }) => {
         const res = await getBacktestResult({
           path: { exchangeId: req.exchangeId, type: TICKER, jobId: executeJobId },
@@ -193,9 +244,13 @@ async function executeStrategy(req, prepareJobId, strategyId, policy, opts) {
         if (!res.data) throw new QTSExecutionError("Empty execution result response");
         return { ...res.data.state, __result: res.data.results };
       },
-      (r) => {
-        if (r.size > 0) {
-          opts.onProgress?.({ stage: "executing", percent: r.completed / r.size * 100 });
+      {
+        ...opts.signal ? { signal: opts.signal } : {},
+        ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {},
+        onEachAttempt: (r) => {
+          if (r.size > 0) {
+            opts.onProgress?.({ stage: "executing", percent: r.completed / r.size * 100 });
+          }
         }
       }
     );
@@ -216,24 +271,43 @@ async function executeStrategy(req, prepareJobId, strategyId, policy, opts) {
     throw err;
   }
 }
-async function runStage(policy, opts, fetchFn, onEachAttempt) {
-  try {
-    return await policy.execute(async (ctx) => {
-      if (opts.signal?.aborted) throw new QTSCanceledError("Workflow aborted");
-      const result = await fetchFn(ctx);
-      onEachAttempt?.(result);
-      if (opts.signal?.aborted) throw new QTSCanceledError("Workflow aborted");
-      return result;
-    }, opts.signal);
-  } catch (err) {
-    if (err instanceof QTSCanceledError) throw err;
-    if (err instanceof TaskCancelledError) {
-      if (opts.signal?.aborted) throw new QTSCanceledError("Workflow aborted", err);
-      throw new QTSTimeoutError(`Stage exceeded ${opts.timeoutMs}ms`, err);
-    }
-    if (opts.signal?.aborted) throw new QTSCanceledError("Workflow aborted", err);
-    throw err;
+
+// src/workflows/catalog.ts
+import {
+  listExchanges as apiListExchanges,
+  listInstruments as apiListInstruments,
+  listSegmentInstruments as apiListSegmentInstruments
+} from "@qtsurfer/api-client";
+
+// src/internal/requestError.ts
+function requestFailed(what, error, status) {
+  const prefix = status === void 0 ? "" : `HTTP ${status} \u2014 `;
+  return new QTSError(`${what} failed: ${prefix}${describe(error)}`, error, status);
+}
+function describe(error) {
+  if (error && typeof error === "object") {
+    const e = error;
+    const code = typeof e.code === "string" || typeof e.code === "number" ? e.code : void 0;
+    const message = typeof e.message === "string" ? e.message : void 0;
+    if (code !== void 0 && message) return `${code}: ${message}`;
+    if (message) return message;
+    if (code !== void 0) return String(code);
   }
+  return String(error);
+}
+
+// src/workflows/catalog.ts
+async function listExchanges() {
+  const { data, error, response } = await apiListExchanges();
+  if (error) throw requestFailed("exchanges call", error, response?.status);
+  if (!data) throw new QTSError("Empty exchanges response");
+  return data;
+}
+async function listInstruments(exchangeId, segment) {
+  const { data, error, response } = segment ? await apiListSegmentInstruments({ path: { exchangeId, segment } }) : await apiListInstruments({ path: { exchangeId } });
+  if (error) throw requestFailed("instruments call", error, response?.status);
+  if (!data) throw new QTSError("Empty instruments response");
+  return data.data;
 }
 
 // src/workflows/downloads.ts
@@ -249,7 +323,7 @@ async function downloadTickers(params) {
   });
   if (error) {
     throw new QTSDownloadError(
-      `tickers download failed: HTTP ${response.status} \u2014 ${describe(error)}`,
+      `tickers download failed: HTTP ${response.status} \u2014 ${describe2(error)}`,
       error,
       response.status
     );
@@ -264,14 +338,14 @@ async function downloadKlines(params) {
   });
   if (error) {
     throw new QTSDownloadError(
-      `klines download failed: HTTP ${response.status} \u2014 ${describe(error)}`,
+      `klines download failed: HTTP ${response.status} \u2014 ${describe2(error)}`,
       error,
       response.status
     );
   }
   return data;
 }
-function describe(error) {
+function describe2(error) {
   if (error && typeof error === "object") {
     const e = error;
     const code = typeof e.code === "string" ? e.code : void 0;
@@ -283,6 +357,206 @@ function describe(error) {
   return String(error);
 }
 
+// src/workflows/strategies.ts
+import {
+  getStrategy as apiGetStrategy,
+  validateStrategy as apiValidateStrategy
+} from "@qtsurfer/api-client";
+async function validateStrategy(strategyId) {
+  const { data, error, response } = await apiValidateStrategy({ path: { strategyId } });
+  if (error) throw requestFailed("strategy validation request", error, response?.status);
+  if (response?.status === 202) return { queued: true, strategyId };
+  if (!data) throw new QTSError("Empty strategy validation response");
+  return { queued: false, strategyId, state: data };
+}
+async function getStrategy(strategyId) {
+  const { data, error, response } = await apiGetStrategy({ path: { strategyId } });
+  if (error) throw requestFailed("strategy lookup", error, response?.status);
+  if (!data) throw new QTSError("Empty strategy response");
+  return data;
+}
+
+// src/workflows/sweep.ts
+import {
+  cancelSweep,
+  executeSweep,
+  getSweepResult,
+  getSweepSensitivity
+} from "@qtsurfer/api-client";
+var DEFAULT_POLL_INTERVAL_MS2 = 2e3;
+var DEFAULT_MAX_POLL_INTERVAL_MS2 = 15e3;
+async function sweep(req, opts = {}) {
+  validateRequest(req);
+  const policy = buildStagePolicy(opts, DEFAULT_POLL_INTERVAL_MS2, DEFAULT_MAX_POLL_INTERVAL_MS2);
+  opts.onProgress?.({ stage: "compiling" });
+  const strategyId = await compileStrategySource(req.strategy, opts.signal);
+  opts.onProgress?.({ stage: "preparing" });
+  const requestId = await prepareData2(req, policy, opts);
+  opts.onProgress?.({ stage: "executing" });
+  const { data, error } = await executeSweep({
+    path: { exchangeId: req.exchangeId, type: TICKER, requestId },
+    body: buildSweepBody(req, strategyId),
+    ...opts.signal ? { signal: opts.signal } : {}
+  });
+  if (error) throw new QTSExecutionError("Sweep submission failed", error);
+  if (!data?.sweepId) throw new QTSExecutionError("Missing sweepId in executeSweep response");
+  return createHandle(req, opts, policy, data, requestId, strategyId);
+}
+function validateRequest(req) {
+  const names = Object.keys(req.params ?? {});
+  if (names.length === 0) {
+    throw new QTSError("sweep: params must hold at least one axis");
+  }
+  for (const name of names) {
+    const axis = req.params[name];
+    if ("values" in axis) {
+      if (axis.values.length === 0) {
+        throw new QTSError(`sweep: axis "${name}" must hold at least one value`);
+      }
+    } else if (!(axis.step > 0)) {
+      throw new QTSError(`sweep: axis "${name}" needs step > 0, got ${axis.step}`);
+    }
+  }
+  const wf = req.walkForward;
+  if (!wf) return;
+  if (wf.folds < 2) {
+    throw new QTSError(`sweep: walkForward.folds must be >= 2, got ${wf.folds}`);
+  }
+  if (wf.inSamplePct !== void 0 && (wf.inSamplePct < 10 || wf.inSamplePct > 90)) {
+    throw new QTSError(
+      `sweep: walkForward.inSamplePct must be within 10..90, got ${wf.inSamplePct}`
+    );
+  }
+}
+function prepareData2(req, policy, opts) {
+  return prepareDataset(
+    {
+      exchangeId: req.exchangeId,
+      instrument: req.instrument,
+      from: req.from,
+      to: req.to
+    },
+    policy,
+    {
+      ...opts.signal ? { signal: opts.signal } : {},
+      ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {},
+      onPercent: (percent) => opts.onProgress?.({ stage: "preparing", percent }),
+      // A thinly covered window is about to be scored once per parameter vector, so the
+      // coverage ratio is worth at least as much here as on a single backtest.
+      onPrepared: (state) => opts.onProgress?.({
+        stage: "preparing",
+        percent: 100,
+        coverageRatio: state.coverageRatio
+      })
+    }
+  );
+}
+function buildSweepBody(req, strategyId) {
+  const spec = { params: req.params };
+  if (req.sampler !== void 0) spec.sampler = req.sampler;
+  if (req.samples !== void 0) spec.samples = req.samples;
+  if (req.seed !== void 0) spec.seed = req.seed;
+  if (req.objective !== void 0) spec.objective = req.objective;
+  const body = { strategyId, sweep: spec };
+  if (req.walkForward) {
+    body.walkForward = {
+      folds: req.walkForward.folds,
+      ...req.walkForward.inSamplePct !== void 0 ? { inSamplePct: req.walkForward.inSamplePct } : {}
+    };
+  }
+  return body;
+}
+function createHandle(req, opts, policy, accepted, requestId, strategyId) {
+  const sweepId = accepted.sweepId;
+  const path = { exchangeId: req.exchangeId, type: TICKER, requestId, sweepId };
+  let state = "executing";
+  const withQuery = viewQuery(opts);
+  const result = (async () => {
+    try {
+      const finalResult = await runStage(
+        policy,
+        async ({ signal: signal2 }) => {
+          const res = await getSweepResult({ path, ...withQuery, signal: signal2 });
+          if (res.error) throw new QTSExecutionError("Sweep result request failed", res.error);
+          if (!res.data) throw new QTSExecutionError("Empty sweep result response");
+          return res.data;
+        },
+        {
+          ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {},
+          onEachAttempt: (r) => {
+            const percent = percentOf(r);
+            opts.onProgress?.({
+              stage: "executing",
+              ...percent !== void 0 ? { percent } : {},
+              snapshot: r.progress
+            });
+          }
+        }
+      );
+      state = normalizeStatus(finalResult.status) === "aborted" ? "canceled" : "completed";
+      return finalResult;
+    } catch (err) {
+      state = err instanceof QTSCanceledError ? "canceled" : "failed";
+      throw err;
+    }
+  })();
+  void result.catch(() => void 0);
+  const { signal } = opts;
+  if (signal) {
+    const requestCancel = () => {
+      if (state === "executing") state = "canceled";
+      void cancelSweep({ path }).catch(() => void 0);
+    };
+    if (signal.aborted) {
+      requestCancel();
+    } else {
+      signal.addEventListener("abort", requestCancel, { once: true });
+      const detach = () => signal.removeEventListener("abort", requestCancel);
+      void result.then(detach, detach);
+    }
+  }
+  return {
+    sweepId,
+    requestId,
+    strategyId,
+    accepted,
+    get state() {
+      return state;
+    },
+    result,
+    results: async (view = {}) => {
+      const res = await getSweepResult({ path, ...viewQuery(view) });
+      if (res.error) {
+        throw requestFailed("sweep results call", res.error, res.response?.status);
+      }
+      if (!res.data) throw new QTSError("Empty sweep result response");
+      return res.data;
+    },
+    sensitivity: async (objective) => {
+      const res = await getSweepSensitivity({
+        path,
+        ...objective !== void 0 ? { query: { objective } } : {}
+      });
+      if (res.error) {
+        throw requestFailed("sweep sensitivity call", res.error, res.response?.status);
+      }
+      if (!res.data) throw new QTSError("Empty sweep sensitivity response");
+      return res.data;
+    }
+  };
+}
+function viewQuery(view) {
+  const query = {};
+  if (view.order !== void 0) query.order = view.order;
+  if (view.ranking !== void 0) query.ranking = view.ranking;
+  return Object.keys(query).length > 0 ? { query } : {};
+}
+function percentOf(result) {
+  const p = result.progress;
+  if (!p || !(p.total > 0)) return void 0;
+  return p.done / p.total * 100;
+}
+
 // src/client.ts
 var QTSurfer = class {
   constructor(options) {
@@ -301,6 +575,47 @@ var QTSurfer = class {
   backtest(req, opts) {
     return backtest(req, opts);
   }
+  /**
+   * 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, opts) {
+    return sweep(req, opts);
+  }
   /**
    * Download one hour of raw tickers for an instrument as a {@link Blob}.
    * Defaults to Lastra; pass `{ format: 'parquet' }` for Parquet.
@@ -312,9 +627,89 @@ var QTSurfer = class {
   klines(args) {
     return downloadKlines(args);
   }
+  /**
+   * 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() {
+    return listExchanges();
+  }
+  /**
+   * 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, segment) {
+    return listInstruments(exchangeId, segment);
+  }
+  /**
+   * 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) {
+    return validateStrategy(strategyId);
+  }
+  /**
+   * 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) {
+    return getStrategy(strategyId);
+  }
   // Future surface:
-  //   strategies: { compile, status, list }
-  //   instruments: { list, get } with TTL cache
+  //   TTL cache for exchanges / instruments
   //   jobs: { cancel, stream, result }
 };
 
@@ -437,6 +832,27 @@ var AuthenticatedClient = class {
   backtest(req, opts) {
     return this.withRefreshOn401(() => backtest(req, opts));
   }
+  /**
+   * 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, opts) {
+    return this.withRefreshOn401(() => sweep(req, opts));
+  }
   /** Download one hour of raw tickers. Refreshes the token once on `401` before retrying. */
   tickers(args) {
     return this.withRefreshOn401(() => downloadTickers(args));
@@ -445,6 +861,41 @@ var AuthenticatedClient = class {
   klines(args) {
     return this.withRefreshOn401(() => downloadKlines(args));
   }
+  /**
+   * List the exchanges the platform serves. Refreshes the token once on `401`
+   * before retrying.
+   */
+  exchanges() {
+    return this.withRefreshOn401(() => listExchanges());
+  }
+  /**
+   * 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, segment) {
+    return this.withRefreshOn401(() => listInstruments(exchangeId, segment));
+  }
+  /**
+   * 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) {
+    return this.withRefreshOn401(() => validateStrategy(strategyId));
+  }
+  /**
+   * 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) {
+    return this.withRefreshOn401(() => getStrategy(strategyId));
+  }
 };
 async function authenticate(apikey, opts = {}) {
   const resolved = apikey ?? readEnvApikey();