@qtsurfer/api-client 0.14.0 → 0.15.0

package/src/generated/schemas.gen.ts

@@ -18,6 +18,21 @@ export const ResponseErrorSchema = {
   },
 } as const;
 
+export const ScalarStrategyParamValueSchema = {
+  description: "A scalar strategy property value for one execution.",
+  oneOf: [
+    {
+      type: "number",
+    },
+    {
+      type: "string",
+    },
+    {
+      type: "boolean",
+    },
+  ],
+} as const;
+
 export const InstrumentSchema = {
   description: "Exchange instrument identifier (e.g. a currency pair)",
   type: "string",
@@ -320,30 +335,20 @@ the dataset instead of its current one. Defaults to the dataset's current versio
     },
     cadence: {
       type: "string",
-      description: `Output bar cadence for the prepared range. Defaults to the publisher's
-native cadence (\`1s\`); coarser cadences are produced on demand via
-resampling and stored alongside the native blob in cache. Coarser-than-
-source values must be exact multiples of the source cadence — invalid
-labels return \`400\`.
-`,
-      enum: [
-        "1s",
-        "5s",
-        "1m",
-        "3m",
-        "5m",
-        "15m",
-        "30m",
-        "1h",
-        "2h",
-        "4h",
-        "8h",
-        "12h",
-        "1d",
-        "1w",
-        "1q",
-      ],
-      default: "1s",
+      description: `Output bar cadence for the prepared range. Coarser cadences are produced on demand by
+resampling the source and stored alongside the native blob in cache. A target finer
+than the source, or not an exact multiple of it, returns \`400\`. What's accepted, and
+what omitting it means, depends on the source:
+
+* Managed exchange — one of \`1s\`, \`5s\`, \`1m\`, \`3m\`, \`5m\`, \`15m\`, \`30m\`, \`1h\`, \`2h\`,
+  \`4h\`, \`8h\`, \`12h\`, \`1d\`, \`1w\`, \`1q\`; any other label returns \`400\`. Omitted = \`1s\`,
+  the publisher's native cadence.
+* Dataset (\`exchangeId: user\`) — omitted = the dataset version's own discovered
+  \`cadence\` (see \`DatasetVersion.cadence\`), served as-is. Any cadence equal to or
+  coarser than it and an exact multiple of it is accepted, including ones outside the
+  managed-exchange list (e.g. \`15s\`); an \`rt\` dataset can be resampled to any fixed
+  cadence.
+`,
     },
   },
   example: {
@@ -371,7 +376,8 @@ export const JobStateSchema = {
       description: `Current status of the job. Treat \`Completed | Aborted | Failed\` as
 terminal; \`New | Started\` mean keep polling. A single-instrument prepare
 is always terminal (\`Completed\`) — decide from
-\`PrepareJobState.coverageRatio\`, not by polling.
+\`PrepareJobState.coverageRatio\` (or \`dataFrom\`/\`dataTo\` against an \`rt\` dataset,
+which has no ratio), not by polling.
 `,
       enum: ["New", "Started", "Completed", "Aborted", "Failed"],
       example: "Completed",
@@ -418,8 +424,10 @@ walked hour by hour: \`totalHours\`/\`hoursWithData\`/\`hoursWithoutData\`. Agai
 dataset-backed prepare (\`exchangeId: user\`), coverage is reported on the dataset's own
 cadence grid instead — hour-walking a daily dataset would report \`1/24\` and read as
 broken — via \`cadence\`/\`gaps\`/\`largestGapSteps\`; \`totalHours\`/\`hoursWithData\`/
-\`hoursWithoutData\` are absent in that case. \`dataFrom\`/\`dataTo\`/\`coverageRatio\` are present
-either way, computed accordingly.
+\`hoursWithoutData\` are absent in that case. \`dataFrom\`/\`dataTo\` are present either way, and
+\`coverageRatio\` too, computed accordingly — except against a dataset whose \`cadence\` is \`rt\`:
+with no fixed step there is no expected row count to measure against, so \`coverageRatio\`
+is absent and \`gaps\`/\`largestGapSteps\` are \`0\`.
 `,
   allOf: [
     {
@@ -451,7 +459,8 @@ either way, computed accordingly.
 \`totalHours\` is 0), the fraction of hours in the requested range that have served
 data. Against a dataset (\`exchangeId: user\`): \`rows / expectedStepsAtCadence\`
 over the dataset version's own range — echoing what ingest computed once, not
-recomputed against a narrower prepare request.
+recomputed against a narrower prepare request. Absent for an \`rt\` dataset (no
+fixed step, so no expected row count).
 `,
           example: 0.994,
         },
@@ -471,22 +480,23 @@ a dataset-backed prepare.
         },
         cadence: {
           type: "string",
-          description: `The dataset version's own discovered cadence (e.g. \`1m\`, \`1h\`). Only present for a
-dataset-backed prepare (\`exchangeId: user\`).
+          description: `The dataset version's own discovered cadence — a fixed grid (e.g. \`1m\`, \`1h\`) or
+\`rt\` (see \`DatasetVersion.cadence\`). Only present for a dataset-backed prepare
+(\`exchangeId: user\`).
 `,
           example: "1m",
         },
         gaps: {
           type: "integer",
           description: `Number of gaps in the dataset version at its own cadence, as discovered at ingest
-time. Only present for a dataset-backed prepare.
+time. \`0\` for \`rt\`. Only present for a dataset-backed prepare.
 `,
           example: 0,
         },
         largestGapSteps: {
           type: "integer",
-          description: `The largest gap in the dataset version, in units of its own cadence step. Only
-present for a dataset-backed prepare.
+          description: `The largest gap in the dataset version, in units of its own cadence step. \`0\` for
+\`rt\`. Only present for a dataset-backed prepare.
 `,
           example: 0,
         },
@@ -639,7 +649,7 @@ export const SweepBaseConfigSchema = {
       type: "number",
       format: "double",
       exclusiveMinimum: 0,
-      default: 10000,
+      default: 100,
     },
     feeRate: {
       type: "number",
@@ -969,7 +979,7 @@ export const SweepRunRowSchema = {
       minimum: 0,
       maximum: 1,
       description:
-        "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.",
+        "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, on sweeps with too few trials to establish any dispersion to deflate against, on runs with fewer than 3 period returns, and on a degenerate (near-constant) return series — all cases where the underlying statistic isn't meaningfully computable, rather than genuinely zero. A present value is the computed probability, however small.",
     },
     params: {
       type: "object",
@@ -1032,8 +1042,10 @@ export const SweepRunRowSchema = {
           $ref: "#/components/schemas/EquityCurveResult",
         },
       ],
-      description:
-        "Present only when this trial's curve was selected (`equityCurve.mode` was `topN`/`topPct` on the request, and this row ranked among the winners) — absent, not null, otherwise; a run that was never spilled and one that was spilled but not selected look identical here. Always a pointer today (`url` present, no inline points): a sweep's curves live in a spill store, not the response, until fetched separately. `GET` the `url` to fetch the curve itself; its own `meta` there is the real, possibly size-guarded outcome, while this outer `meta` is a raw, untransformed preview from selection time and can differ.",
+      description: `Present whenever this trial actually has a curve — which is any completed run of a sweep that requested curves at all (\`equityCurve.mode\` \`topN\`/\`topPct\`), not only the ranked winners. Absent, not null, when there is genuinely nothing: the run aborted, it made no trades, or the sweep never retained curves (\`mode\` \`auto\`/\`none\`).
+Selection decides how the curve travels, not whether it exists. A row may carry \`url\` alone, or \`url\` together with the points inline.
+**Read \`points\`/\`equities\` to tell whether the curve is inline — never the presence of this object, and never the absence of \`url\`.** Both mislead, and in opposite directions: this object is present on rows that carry only a pointer, and \`url\` stays present alongside an inline curve so a caller can still re-request a different transform. An inline curve is emitted on the materialisation view (\`?order=natural\`), where each row is read once; the ranked view keeps the pointer, being polled.
+When only a pointer is present, \`GET\` the \`url\` for the curve. Its own \`meta\` there is the real, possibly size-guarded outcome. This outer \`meta\` may be a declaration rather than a measurement — for a row whose curve was not promoted, the point count is derived from the trade count (one equity point per closed trade) instead of being read from the store, to keep a polled response from doing per-row work.`,
     },
   },
 } as const;
@@ -1246,7 +1258,8 @@ First failure wins and later ones are not recorded, so on a sweep where several
       description: `The same \`JobState\` shape a single-execute \`BacktestJobResult\` carries — not a sweep-specific lookalike, the actual type, so field names and timestamp formatting match exactly.
 \`state.status\` uses \`JobState\`'s own vocabulary (\`New\`/\`Started\`/\`Completed\`/ \`Aborted\`/\`Failed\`), mapped from the sweep's \`status\` field above rather than copying it: \`PARTIAL\` and \`CANCELLED\` both map to \`Aborted\`, because a sweep's \`PARTIAL\` is already terminal (some shards finished, some failed, nothing more is coming) unlike a single job's non-terminal \`Partial\`, which has no equivalent here at all.
 \`state.completed\` is real ticks processed on a plain sweep. On a \`walkForward\` sweep it is currently always \`0\` — the walk-forward fold runner was not wired to count ticks when this shipped, unlike the plain shard path.
-\`state.size\` is always \`0\` on every path (single execute, plain sweep, walk-forward alike) — nothing populates it anywhere yet. That is a known gap across the whole API, not a sweep-specific omission.`,
+\`state.size\` is an upfront estimate — range x the prepare's target cadence, set before any data is even loaded, not a query against loaded data — on a single execute and a plain sweep alike. A plain sweep's value is the sum of every shard's own \`size\` (each shard's per-run estimate x its own vector slice), the same additive shape \`state.completed\` already used above. \`0\` means the prepare context behind the job predates this field (a job whose prepare ran before the estimate existed) — never a guessed cadence standing in for a real one.
+On a \`walkForward\` sweep, \`state.size\` is still always \`0\`: fold runs were out of scope for the estimate the same way they are for \`state.completed\` above — a fold's \`size\` is simply never set, so the sum stays honest at \`0\` rather than needing a special case.`,
     },
   },
 } as const;
@@ -1525,17 +1538,7 @@ reading: a run that produced no trades often did so for a reason stated here.
     params: {
       type: "object",
       additionalProperties: {
-        oneOf: [
-          {
-            type: "number",
-          },
-          {
-            type: "string",
-          },
-          {
-            type: "boolean",
-          },
-        ],
+        $ref: "#/components/schemas/ScalarStrategyParamValue",
       },
       description:
         "The strategy properties this run was given, echoed back as sent. Absent when the request carried none, so its presence is what distinguishes a parameterised run from one at the declared defaults — a stored result cannot otherwise say which vector produced it, and this endpoint is meant to be called repeatedly over one prepare.",
@@ -1979,8 +1982,11 @@ what a dataset covers. Absent until a version exists.
     },
     type: {
       type: "string",
-      enum: ["ticker"],
-      description: "Always `ticker` in v1.",
+      enum: ["ticker", "klines"],
+      description: `\`ticker\` for an upload or a \`dex\` import with no \`cadence\` requested (native per-trade
+data). \`klines\` for a \`dex\` import that requested a candle \`cadence\` — pre-aggregated
+bars rather than raw ticks. Purely informational; both shapes are read the same way.
+`,
       example: "ticker",
     },
     instrument: {
@@ -2024,8 +2030,8 @@ a version exists.
     },
     cadence: {
       type: "string",
-      description: `\`currentVersionId\`'s own discovered bar cadence (e.g. \`1s\`, \`1m\`, \`1h\`). Absent until a
-version exists.
+      description: `\`currentVersionId\`'s own discovered cadence — a fixed grid (e.g. \`1s\`, \`1m\`, \`1h\`) or
+\`rt\` (see \`DatasetVersion.cadence\`). Absent until a version exists.
 `,
       example: "1m",
     },
@@ -2042,6 +2048,27 @@ export const DatasetWithLinksSchema = {
     {
       type: "object",
       properties: {
+        dataUrl: {
+          type: "string",
+          description: `Presigned GET URL to the current version's stored file — see \`dataFormat\` for
+which format it's actually in. Present only once the current version's status is
+\`ready\`. Long-lived (day-scale, not permanent): a DuckDB-WASM/\`lastra-ts\`-style
+reader issues HTTP range requests against it lazily over an extended viewing
+session, not in one shot like a browser upload.
+`,
+          example:
+            "https://storage.qtsurfer.com/00000000-.../ds_3f9a1c2e7b0d4a5f/dsv_8e2b4f19c6a03d7e/ticker_BTC_USDT_1700000000000_1700086400000_1m.lastra?X-Amz-...",
+        },
+        dataFormat: {
+          type: "string",
+          enum: ["lastra", "parquet"],
+          description: `Which format \`dataUrl\` is actually in — check this rather than assuming it
+matches how you uploaded it. \`lastra\` — our native columnar format — for a CSV (or
+gzip/zip of one) upload, always converted on ingest. \`parquet\` for a parquet
+upload, stored as-is today.
+`,
+          example: "lastra",
+        },
         _links: {
           type: "object",
           properties: {
@@ -2069,8 +2096,9 @@ export const DatasetUploadTargetSchema = {
   properties: {
     url: {
       type: "string",
-      description: `Presigned URL. \`PUT\` the raw CSV file here directly — no \`Authorization\` header,
-no other API credentials.
+      description: `Presigned URL. \`PUT\` the file here directly — the CSV or parquet itself, or a \`.gz\`/\`.zip\` of it
+(see \`createDataset\`'s own description) — no \`Authorization\` header, no other API
+credentials.
 `,
       example:
         "https://storage.qtsurfer.com/uploads/00000000-.../up_1a2b3c4d5e6f7a8b/raw.csv?X-Amz-...",
@@ -2161,7 +2189,8 @@ not declared by the caller.
     },
     bytes: {
       type: "integer",
-      description: "Size of the uploaded file.",
+      description:
+        "Size of the stored file `dataUrl` points at — a converted `lastra` for a CSV/gzip/zip upload, or the parquet file itself, unconverted, for a parquet upload. Not the size of the bytes originally PUT to storage; see `dataFormat`.",
       example: 4831022,
     },
     rows: {
@@ -2171,7 +2200,13 @@ not declared by the caller.
     },
     cadence: {
       type: "string",
-      description: "The discovered bar cadence (e.g. `1s`, `1m`, `1h`).",
+      description: `The cadence discovered from the data's own timestamps. Either a fixed grid — \`1s\`,
+\`5s\`, \`15s\`, \`1m\`, \`5m\`, \`15m\`, \`30m\`, \`1h\`, \`4h\`, \`1d\` — when at least half the
+intervals between consecutive rows fall on that step (small clock jitter tolerated), or
+\`rt\`: native data at the rate it was captured, each row at its own timestamp with no
+fixed step — per-trade on-chain swaps, block-spaced or sub-second ticks, irregular
+intervals. An \`rt\` dataset can be resampled to any fixed cadence at prepare time.
+`,
       example: "1s",
     },
     timestampUnit: {
@@ -2184,20 +2219,42 @@ numeric values fell in (seconds, millis, or micros).
     },
     gaps: {
       type: "integer",
-      description: "Number of gaps at the discovered cadence.",
+      description:
+        "Number of gaps at the discovered cadence. Always `0` for `rt`.",
       example: 0,
     },
     largestGapSteps: {
       type: "integer",
-      description: "The largest gap, in units of the discovered cadence step.",
+      description:
+        "The largest gap, in units of the discovered cadence step. Always `0` for `rt`.",
       example: 0,
     },
+    dataUrl: {
+      type: "string",
+      description: `Presigned GET URL to the stored file — see \`dataFormat\` for which format it's in.
+Present once the version is \`ready\`. Long-lived (day-scale, not permanent): a
+DuckDB-WASM/\`lastra-ts\`-style reader issues HTTP range requests against it lazily over
+an extended viewing session, not in one shot like a browser upload.
+`,
+      example:
+        "https://storage.qtsurfer.com/00000000-.../ds_3f9a1c2e7b0d4a5f/dsv_8e2b4f19c6a03d7e/ticker_BTC_USDT_1700000000000_1700086400000_1m.lastra?X-Amz-...",
+    },
+    dataFormat: {
+      type: "string",
+      enum: ["lastra", "parquet"],
+      description: `Which format \`dataUrl\` is actually in — check this rather than assuming it matches
+how you uploaded it. \`lastra\` — our native columnar format — for a CSV (or gzip/zip
+of one) upload, always converted on ingest. \`parquet\` for a parquet upload, stored
+as-is today.
+`,
+      example: "lastra",
+    },
   },
 } as const;
 
 export const DatasetUploadStateSchema = {
   type: "object",
-  description: `Progress of one upload, from staged through ingest. Postgres-backed once a version exists,
+  description: `Progress of one upload, from staged through ingest. Durably recorded once a version exists,
 so \`ready\`/\`failed\` are permanent answers; \`uploading\`/\`ingesting\` reflect in-flight state
 that can itself age out — see the \`404\` case on \`GET .../uploads/{uploadId}\`.
 `,
@@ -2214,7 +2271,8 @@ that can itself age out — see the \`404\` case on \`GET .../uploads/{uploadId}
   called yet.
 * \`ingesting\` — \`finalize\` was called; the worker is parsing and validating the file.
 * \`ready\` — ingested successfully. \`version\` carries the result.
-* \`failed\` — ingest rejected the file (e.g. bad CSV contract, mixed timestamp units).
+* \`failed\` — ingest rejected the file (e.g. bad CSV contract, mixed timestamp units, a
+  \`.zip\` with no file inside or more than one).
 `,
       example: "ready",
     },
@@ -2222,6 +2280,209 @@ that can itself age out — see the \`404\` case on \`GET .../uploads/{uploadId}
       type: "string",
       description: "The ingest job id, while `status` is `ingesting`.",
     },
+    error: {
+      type: "string",
+      description: `A human-readable reason, present when \`status\` is \`failed\` (e.g. bad CSV contract,
+mixed timestamp units, a \`.zip\` with no file inside or more than one). Durably
+recorded alongside the failure itself, so it stays available however long after the
+fact you poll — not tied to how recently the failure happened.
+`,
+      example: "line 3: column 'close' is not a number: not-a-number",
+    },
+    version: {
+      allOf: [
+        {
+          $ref: "#/components/schemas/DatasetVersion",
+        },
+      ],
+      description: "Present when `status` is `ready` or `failed`.",
+    },
+  },
+} as const;
+
+export const DatasetImportRequestSchema = {
+  type: "object",
+  description: `\`POST /datasets/imports\`'s request body. A common block plus one type-specific block,
+selected by \`type\` — \`dex\` is the only value today.
+`,
+  required: ["name", "instrument", "from", "to", "type"],
+  properties: {
+    name: {
+      type: "string",
+      description: "A name unique among your datasets. `409` if already taken.",
+      example: "weth-usdc-week",
+    },
+    instrument: {
+      $ref: "#/components/schemas/Instrument",
+    },
+    from: {
+      type: "string",
+      format: "date-time",
+      description:
+        "Start of the range to fetch, inclusive. Must be before `to`.",
+      example: "2026-08-01T00:00:00Z",
+    },
+    to: {
+      type: "string",
+      format: "date-time",
+      description: `End of the range to fetch, exclusive. The total span is capped by your tier — a
+request wider than that ceiling is \`400\`, regardless of source type.
+`,
+      example: "2026-08-08T00:00:00Z",
+    },
+    cadence: {
+      type: "string",
+      enum: ["1s", "1m", "5m"],
+      description: `Optional. Omitted/blank keeps native per-trade event cadence — each swap at its own
+timestamp, so the resulting version's \`cadence\` is \`rt\` unless the swaps happen to sit
+on a fixed grid (see \`DatasetVersion.cadence\`). Set to \`1s\`, \`1m\` or
+\`5m\` instead to get pre-aggregated candles at that width rather than raw trades (the
+resulting dataset's \`type\` becomes \`klines\`); any other value is \`400\`. Not every
+network supports every cadence — an unsupported combination fails asynchronously, not
+at request time (see \`DatasetImportState.error\`).
+`,
+    },
+    type: {
+      type: "string",
+      enum: ["dex"],
+      description: "The source to fetch from. `dex` is the only value today.",
+      example: "dex",
+    },
+    dex: {
+      $ref: "#/components/schemas/DatasetImportDexRequest",
+    },
+  },
+} as const;
+
+export const DatasetImportDexRequestSchema = {
+  type: "object",
+  description: `The \`dex\` source's own fields — required when \`type\` is \`dex\`. \`id\`/\`version\` are required
+for a plain (native-cadence) import; both are ignored if the top-level \`cadence\` requested
+pre-aggregated candles instead, since that path needs neither a protocol nor a version
+distinction.
+`,
+  required: ["network", "contract"],
+  properties: {
+    network: {
+      type: "string",
+      enum: ["ethereum", "robinhood"],
+      description: "Which chain the pool/pair lives on.",
+      example: "ethereum",
+    },
+    id: {
+      type: "string",
+      enum: ["uniswap"],
+      description: `Which on-chain DEX protocol \`contract\` implements. Required unless the top-level
+\`cadence\` requested pre-aggregated candles, in which case it's ignored.
+`,
+      example: "uniswap",
+    },
+    version: {
+      type: "string",
+      enum: ["v2", "v3"],
+      description: `Uniswap version the pool/pair contract implements. Required unless the top-level
+\`cadence\` requested pre-aggregated candles, in which case it's ignored.
+`,
+      example: "v3",
+    },
+    contract: {
+      type: "string",
+      description: "The pool (v3) or pair (v2) contract address.",
+      example: "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
+    },
+    factory: {
+      type: "string",
+      description: `The factory that deployed \`contract\`. Optional — when omitted, it is discovered
+on-chain from \`contract\` itself at fetch time. Supply it explicitly only if you
+already know it, or the pool/pair belongs to a factory other than the canonical one
+for \`network\`/\`version\`. Either way, the pool/pair is validated against whichever
+factory is used before anything is fetched — a wrong or unrelated factory fails the
+import rather than silently fetching from the wrong pool. Ignored if the top-level
+\`cadence\` requested pre-aggregated candles.
+`,
+    },
+  },
+  example: {
+    network: "ethereum",
+    id: "uniswap",
+    version: "v3",
+    contract: "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
+  },
+} as const;
+
+export const DatasetImportCreatedSchema = {
+  type: "object",
+  description:
+    "The response to `POST /datasets/imports` — the dataset now exists, and its fetch has started.",
+  required: ["datasetId", "importId", "jobId", "status"],
+  properties: {
+    datasetId: {
+      type: "string",
+      description:
+        "Opaque id of the newly created dataset — same id space as `POST /datasets`.",
+      example: "ds_3f9a1c2e7b0d4a5f",
+    },
+    importId: {
+      type: "string",
+      description: `Identifies this import. Pass to \`GET /datasets/{datasetId}/imports/{importId}\` to poll
+it — there is no separate "finalize" step the way an upload has.
+`,
+      example: "imp_01j9z1x2y3z4a5b6c7d8e9f0g1",
+    },
+    jobId: {
+      type: "string",
+      description: "The fetch/ingest job id.",
+      example:
+        "dataset-import:00000000-.../ds_3f9a1c2e7b0d4a5f:imp_01j9z1x2y3z4a5b6c7d8e9f0g1",
+    },
+    status: {
+      type: "string",
+      enum: ["fetching"],
+      description:
+        "Always `fetching` in this response — the fetch has only just started.",
+      example: "fetching",
+    },
+  },
+} as const;
+
+export const DatasetImportStateSchema = {
+  type: "object",
+  description: `Progress of one import, from fetching through ingest. \`fetching\` is the one status only an
+import ever reports — an upload's file already exists by the time you can poll it; an
+import's doesn't, until this source finishes fetching it.
+`,
+  required: ["importId", "status"],
+  properties: {
+    importId: {
+      type: "string",
+      example: "imp_01j9z1x2y3z4a5b6c7d8e9f0g1",
+    },
+    status: {
+      type: "string",
+      enum: ["fetching", "ingesting", "ready", "failed"],
+      description: `* \`fetching\` — reading from the source; nothing staged yet.
+* \`ingesting\` — fetch complete, staged, and re-entered the same ingest chain an
+  upload uses; the worker is parsing and validating it.
+* \`ready\` — ingested successfully. \`version\` carries the result.
+* \`failed\` — the fetch or the ingest that followed it was rejected. \`error\` names why.
+`,
+      example: "ready",
+    },
+    jobId: {
+      type: "string",
+      description:
+        "The fetch/ingest job id, while `status` is `fetching` or `ingesting`.",
+    },
+    error: {
+      type: "string",
+      description: `A human-readable reason, present when \`status\` is \`failed\` — an unresolvable
+pool/pair, no data in the requested range, a range older than the configured source
+retains, the fetch exceeding your tier's time ceiling, or any of
+\`DatasetUploadState.error\`'s own ingest-side reasons once fetching hands off to it.
+Durably recorded, same as on the upload path.
+`,
+      example: "Import exceeded the tier's 12 minute ceiling",
+    },
     version: {
       allOf: [
         {