@qtsurfer/api-client 0.10.0 → 0.12.0

package/src/generated/schemas.gen.ts

@@ -269,10 +269,36 @@ export const DataSourceTypeSchema = {
 
 export const PrepareRequestSchema = {
   type: "object",
-  required: ["instrument", "from", "to"],
+  description: `Two shapes, chosen by the \`exchangeId\` path segment. Against a managed exchange,
+\`instrument\` is required and \`datasetId\`/\`datasetVersionId\` are ignored. Against the
+reserved \`exchangeId: user\`, send \`datasetId\` instead of \`instrument\` — \`instrument\` is
+ignored there, since it comes from the dataset itself.
+`,
+  required: ["from", "to"],
   properties: {
     instrument: {
-      $ref: "#/components/schemas/Instrument",
+      allOf: [
+        {
+          $ref: "#/components/schemas/Instrument",
+        },
+      ],
+      description: `Required unless \`exchangeId\` is the reserved value \`user\`, in which case send
+\`datasetId\` instead.
+`,
+    },
+    datasetId: {
+      type: "string",
+      description: `Only for \`exchangeId: user\`: the id of a dataset created via \`POST /datasets\`, in place
+of \`instrument\`. Ignored against a managed exchange.
+`,
+      example: "ds_3f9a1c2e7b0d4a5f",
+    },
+    datasetVersionId: {
+      type: "string",
+      description: `Only for \`exchangeId: user\`, and optional even then: pins a specific past version of
+the dataset instead of its current one. Defaults to the dataset's current version.
+`,
+      example: "dsv_8e2b4f19c6a03d7e",
     },
     from: {
       type: "string",
@@ -300,7 +326,23 @@ 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", "5m", "15m", "1h", "4h", "1d"],
+      enum: [
+        "1s",
+        "5s",
+        "1m",
+        "3m",
+        "5m",
+        "15m",
+        "30m",
+        "1h",
+        "2h",
+        "4h",
+        "8h",
+        "12h",
+        "1d",
+        "1w",
+        "1q",
+      ],
       default: "1s",
     },
   },
@@ -363,12 +405,19 @@ is always terminal (\`Completed\`) — decide from
 } as const;
 
 export const PrepareJobStateSchema = {
-  description: `State of a single-instrument prepare job — the \`JobState\` shape plus a per-hour
-data-coverage summary. A single-instrument prepare is always terminal
-(\`status: Completed\`): the client decides what to do from \`coverageRatio\` (e.g.
-execute if it is at or above a chosen threshold) rather than polling for missing
-hours that may never arrive — a missing hour for one instrument usually means low
-activity, not missing data.
+  description: `State of a single-instrument prepare job — the \`JobState\` shape plus a coverage summary.
+A single-instrument prepare is always terminal (\`status: Completed\`): the client decides
+what to do from \`coverageRatio\` (e.g. execute if it is at or above a chosen threshold)
+rather than polling for missing hours that may never arrive — a missing hour for one
+instrument usually means low activity, not missing data.
+
+**Two coverage shapes, by exchange vs. dataset.** Against a managed exchange, coverage is
+walked hour by hour: \`totalHours\`/\`hoursWithData\`/\`hoursWithoutData\`. Against a
+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.
 `,
   allOf: [
     {
@@ -396,25 +445,54 @@ activity, not missing data.
           format: "double",
           minimum: 0,
           maximum: 1,
-          description: `\`hoursWithData / totalHours\` in \`[0,1]\` (\`1.0\` when \`totalHours\` is 0) — the
-fraction of hours in the requested range that have served data.
+          description: `Against a managed exchange: \`hoursWithData / totalHours\` in \`[0,1]\` (\`1.0\` when
+\`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.
 `,
           example: 0.994,
         },
         totalHours: {
           type: "integer",
-          description: "Number of whole hours in the requested prepare range.",
+          description: `Number of whole hours in the requested prepare range. Managed exchanges only —
+absent for a dataset-backed prepare.
+`,
           example: 168,
         },
         hoursWithData: {
           type: "integer",
-          description: "Number of hours in the range that have data.",
+          description: `Number of hours in the range that have data. Managed exchanges only — absent for
+a dataset-backed prepare.
+`,
           example: 167,
         },
+        cadence: {
+          type: "string",
+          description: `The dataset version's own discovered cadence (e.g. \`1m\`, \`1h\`). 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.
+`,
+          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.
+`,
+          example: 0,
+        },
         hoursWithoutData: {
           type: "array",
-          description:
-            "One entry per hour in the range that has no data, with a rationale.",
+          description: `One entry per hour in the range that has no data, with a rationale. Managed
+exchanges only — absent for a dataset-backed prepare.
+`,
           items: {
             type: "object",
             properties: {
@@ -627,9 +705,76 @@ export const ExecuteSweepRequestSchema = {
     walkForward: {
       $ref: "#/components/schemas/WalkForwardRequest",
     },
+    equityCurve: {
+      $ref: "#/components/schemas/EquityCurveRequest",
+    },
   },
 } as const;
 
+export const EquityCurveOptionsSchema = {
+  type: "object",
+  description:
+    "Requested equity-curve transform, applied server-side in a fixed pipeline order: `resample` (point count) then `differential` (encoding) then `outMode` (JSON shape) — each stage assumes the previous one already ran. A server-side size guard can still force a smaller/deflated shape above its thresholds regardless of what is requested here — see `EquityCurveMeta` for what actually happened.",
+  properties: {
+    resample: {
+      type: "integer",
+      minimum: 2,
+      description:
+        "Downsample to at most this many points (extrema-preserving — the global max/min and the exact first/last point are always kept). Omit for no downsampling.",
+    },
+    differential: {
+      type: "boolean",
+      default: false,
+      description:
+        "Delta-encode both fields from the second (post-resample) point onward.",
+    },
+    outMode: {
+      allOf: [
+        {
+          $ref: "#/components/schemas/EquityCurveOutMode",
+        },
+      ],
+      default: "ARRAY",
+      description: "Requested JSON shape.",
+    },
+  },
+} as const;
+
+export const EquityCurveRequestSchema = {
+  allOf: [
+    {
+      $ref: "#/components/schemas/EquityCurveOptions",
+    },
+    {
+      type: "object",
+      properties: {
+        mode: {
+          type: "string",
+          enum: ["auto", "topN", "topPct", "none"],
+          default: "auto",
+          description:
+            "Which trials keep their per-point equity curve. `auto` retains curves only while the accumulated size stays within server limits; `topN`/`topPct` retain curves for the best-ranked trials explicitly; `none` retains no curves.",
+        },
+        n: {
+          type: "integer",
+          minimum: 1,
+          description: "Trial count to retain when mode is topN.",
+        },
+        maxPct: {
+          type: "number",
+          format: "double",
+          exclusiveMinimum: 0,
+          maximum: 100,
+          description:
+            "Top percentage of trials to retain when mode is topPct.",
+        },
+      },
+    },
+  ],
+  description:
+    "Selection (`mode`/`n`/`maxPct`) plus the transform preference (`resample`/`differential`/`outMode`) applied by `GET .../equityCurve` whenever ITS OWN query params are absent, for a curve this sweep retained. The transform half never affects retention or `sweepId` — a caller can always override it per-request at read time regardless of what was submitted here.",
+} as const;
+
 export const WalkForwardRequestSchema = {
   type: "object",
   description:
@@ -871,6 +1016,15 @@ export const SweepRunRowSchema = {
       type: "integer",
       format: "int64",
     },
+    equityCurve: {
+      allOf: [
+        {
+          $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.",
+    },
   },
 } as const;
 
@@ -1008,6 +1162,7 @@ export const ExecuteSweepResultSchema = {
     "leaderboardSize",
     "truncated",
     "leaderboard",
+    "state",
   ],
   properties: {
     sweepId: {
@@ -1016,6 +1171,8 @@ export const ExecuteSweepResultSchema = {
     status: {
       type: "string",
       enum: ["RUNNING", "COMPLETED", "PARTIAL", "CANCELLED"],
+      description:
+        "The sweep's own status vocabulary — not the same set `state.status` below uses. See `state` for why.",
     },
     objective: {
       type: "string",
@@ -1070,6 +1227,17 @@ First failure wins and later ones are not recorded, so on a sweep where several
     walkForward: {
       $ref: "#/components/schemas/WalkForwardResult",
     },
+    state: {
+      allOf: [
+        {
+          $ref: "#/components/schemas/JobState",
+        },
+      ],
+      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.`,
+    },
   },
 } as const;
 
@@ -1311,26 +1479,36 @@ reading: a run that produced no trades often did so for a reason stated here.
       example: 8.75,
     },
     equityCurve: {
-      type: "array",
-      description:
-        "Equity curve over the backtest. Element 0 is an anchor at the backtest `from` with `initialCapital`; the remaining points are one sample per emitted yield, in order. Use it to plot the strategy's running equity without re-deriving it from the yield history.",
-      items: {
-        $ref: "#/components/schemas/EquityPoint",
-      },
-      example: [
-        {
-          timestamp: 1700000000000,
-          equity: 100,
-        },
-        {
-          timestamp: 1700000060000,
-          equity: 110.5,
-        },
+      allOf: [
         {
-          timestamp: 1700000120000,
-          equity: 90.25,
+          $ref: "#/components/schemas/EquityCurveResult",
         },
       ],
+      description:
+        "Equity curve over the backtest. `points[0]` (or `timestamps[0]`/`equities[0]` in `SHORT` mode) is an anchor at the backtest `from` with `initialCapital`; the remaining points are one sample per emitted yield, in order. Use it to plot the strategy's running equity without re-deriving it from the yield history. Always inline for a plain backtest today — never a pointer (`url`); that shape exists only for a sweep row's top-N winners.",
+      example: {
+        points: [
+          {
+            timestamp: 1700000000000,
+            equity: 100,
+          },
+          {
+            timestamp: 1700000060000,
+            equity: 110.5,
+          },
+          {
+            timestamp: 1700000120000,
+            equity: 90.25,
+          },
+        ],
+        meta: {
+          inputPointCount: 3,
+          outputPointCount: 3,
+          resampled: false,
+          differential: false,
+          outMode: "ARRAY",
+        },
+      },
     },
     signalCount: {
       type: "integer",
@@ -1397,6 +1575,104 @@ export const EquityPointSchema = {
   },
 } as const;
 
+export const EquityCurveOutModeSchema = {
+  type: "string",
+  enum: ["ARRAY", "SHORT"],
+  description:
+    "JSON shape for an equity curve's points. `ARRAY` is `[{timestamp, equity}, ...]`; `SHORT` is `{timestamps: [...], equities: [...]}` (parallel arrays, no repeated key text). The one schema shared by every place `outMode` appears, request or response, so the two cannot drift to different value sets.",
+} as const;
+
+export const EquityCurveMetaSchema = {
+  type: "object",
+  description:
+    "What the transform pipeline actually did, computed from the observed outcome — never a copy of what was requested. Lets a caller detect a forced or no-op transform (e.g. a `resample` ceiling already above the curve's size is a legal no-op, reported honestly as `resampled: false`).",
+  required: [
+    "inputPointCount",
+    "outputPointCount",
+    "resampled",
+    "differential",
+    "outMode",
+  ],
+  properties: {
+    inputPointCount: {
+      type: "integer",
+      description: "Size of the curve the transform pipeline received.",
+      example: 100000,
+    },
+    outputPointCount: {
+      type: "integer",
+      description:
+        "Size after the full pipeline (resample, then differential, then outMode).",
+      example: 100,
+    },
+    resampled: {
+      type: "boolean",
+      description:
+        "True only if the resample stage actually changed the point count.",
+    },
+    differential: {
+      type: "boolean",
+      description:
+        "True only if delta-encoding actually ran. Requesting it on a curve of 0 or 1 points has nothing to encode, so it does not run even if asked.",
+    },
+    outMode: {
+      allOf: [
+        {
+          $ref: "#/components/schemas/EquityCurveOutMode",
+        },
+      ],
+      description:
+        "The actual JSON shape served. Present even when the points themselves are not (a pointer curve, `EquityCurveResult.url`) — a caller resolving that URL separately still needs to know how to parse what it gets back before fetching it. May override an explicit request above a server-side size threshold; this field, not the request, is the source of truth for what shape actually came back.",
+      example: "ARRAY",
+    },
+  },
+} as const;
+
+export const EquityCurveResultSchema = {
+  type: "object",
+  description:
+    "An equity curve, shaped per `meta.outMode`: `points` when `ARRAY`, `timestamps` + `equities` (parallel arrays) when `SHORT`. Used identically wherever a curve is returned — a plain backtest's inline `equityCurve` and a sweep row's `equityCurve` are the same type. `url` is present *instead of* any points when the curve is served by pointer rather than inline (a sweep row's top-N winners only): `GET` it separately to fetch this exact same shape with the points populated.",
+  required: ["meta"],
+  properties: {
+    meta: {
+      $ref: "#/components/schemas/EquityCurveMeta",
+    },
+    points: {
+      type: "array",
+      description:
+        "Present when `meta.outMode` is `ARRAY` and the curve is inline (not a pointer).",
+      items: {
+        $ref: "#/components/schemas/EquityPoint",
+      },
+    },
+    timestamps: {
+      type: "array",
+      description:
+        "Present when `meta.outMode` is `SHORT` and the curve is inline (not a pointer).",
+      items: {
+        type: "integer",
+        format: "int64",
+      },
+    },
+    equities: {
+      type: "array",
+      description:
+        "Present when `meta.outMode` is `SHORT` and the curve is inline (not a pointer), parallel to `timestamps` (same index, same point).",
+      items: {
+        type: "number",
+        format: "double",
+      },
+    },
+    url: {
+      type: "string",
+      description:
+        "Present only for a sweep row's pointer curve. `GET` this to fetch the curve itself, in this exact `{points|timestamps+equities, meta}` shape — `meta` there is the real, possibly size-guarded outcome; this outer `meta` is a raw, untransformed preview from the moment the sweep selected this trial's curve, and the two can legitimately differ.",
+      example:
+        "/v1/backtest/binance/ticker/executeSweep/req-1/swp_test/runs/3/equityCurve",
+    },
+  },
+} as const;
+
 export const strategyIdSchema = {
   description: `Unique identifier for a compiled strategy, derived from the source itself: the same code
 always yields the same id, for every caller, whatever its formatting. See
@@ -1406,6 +1682,68 @@ always yields the same id, for every caller, whatever its formatting. See
   example: "6bsh31ikwkuivhtgcoa6s4",
 } as const;
 
+export const DeclaredPropertySchema = {
+  type: "object",
+  description: `One property name \`POST /strategy\` could establish without constructing the strategy —
+either declared with \`@StrategyProperty\` on the compiled source, or one of the small set of
+base properties every strategy carries (\`amnt\`, \`enabled\`, \`multiEntry\`, ...).
+
+**Best-effort, not exhaustive.** A property registered through an attached risk/backtest
+config needs a live instance to discover and is not listed here. Use this to catch a typo'd
+sweep key before submitting, not as the definitive list of what a sweep will accept — a
+name absent from this list may still be valid.
+`,
+  required: ["name"],
+  properties: {
+    name: {
+      type: "string",
+      description:
+        "The key a sweep or execute param map uses for this property.",
+      example: "rsi.period",
+    },
+    description: {
+      type: "string",
+      description: "Human-readable label, as declared.",
+      example: "RSI period",
+    },
+    defaultValue: {
+      type: "string",
+      description: `The declared default, as a string, if one was given. Absent, not null, when none was
+declared.
+`,
+      example: "14",
+    },
+    reflected: {
+      type: "boolean",
+      description: `Whether a value for this key is injected into the strategy's field (\`true\`) or only
+available through the property map (\`false\`).
+`,
+      example: true,
+    },
+    min: {
+      type: "number",
+      format: "double",
+      description:
+        "Suggested sweep/range minimum, if declared. Advisory only, never validated.",
+      example: 2,
+    },
+    max: {
+      type: "number",
+      format: "double",
+      description:
+        "Suggested sweep/range maximum, if declared. Advisory only, never validated.",
+      example: 50,
+    },
+    step: {
+      type: "number",
+      format: "double",
+      description:
+        "Suggested sweep/range step, if declared. Advisory only, never validated.",
+      example: 1,
+    },
+  },
+} as const;
+
 export const NoticeSchema = {
   type: "object",
   description: `A diagnostic the engine raised while the strategy ran. Advisory: it describes something worth
@@ -1584,6 +1922,244 @@ the strategy — the check has not run. Stop waiting and re-request it later.
   },
 } as const;
 
+export const DatasetSchema = {
+  type: "object",
+  description: `A dataset's own metadata — not its data. \`currentVersionId\` is what a prepare against
+\`exchangeId: user\` reads by default; see \`DatasetVersion\` for what a version carries.
+
+\`from\`/\`to\`/\`cadence\` mirror that current version's own discovered range and cadence, so
+you don't need a second call to \`GET /datasets/{datasetId}/uploads/{uploadId}\` just to see
+what a dataset covers. Absent until a version exists.
+`,
+  required: ["datasetId", "name", "type", "instrument", "createdAt"],
+  properties: {
+    datasetId: {
+      type: "string",
+      description: "Opaque id, returned by `POST /datasets`.",
+      example: "ds_3f9a1c2e7b0d4a5f",
+    },
+    name: {
+      type: "string",
+      description: "Unique among your datasets.",
+      example: "My BTC ticks",
+    },
+    type: {
+      type: "string",
+      enum: ["ticker"],
+      description: "Always `ticker` in v1.",
+      example: "ticker",
+    },
+    instrument: {
+      $ref: "#/components/schemas/Instrument",
+    },
+    createdAt: {
+      type: "string",
+      format: "date-time",
+      description: "When the dataset was created.",
+      example: "2026-08-20T09:00:00Z",
+    },
+    currentVersionId: {
+      type: "string",
+      description: `The id of the most recently finalized, successfully ingested version. Absent until at
+least one upload has finished ingesting.
+`,
+      example: "dsv_8e2b4f19c6a03d7e",
+    },
+    updatedAt: {
+      type: "string",
+      format: "date-time",
+      description:
+        "When `currentVersionId` last changed. Absent until it has a value.",
+      example: "2026-08-20T09:04:12Z",
+    },
+    from: {
+      type: "string",
+      format: "date-time",
+      description: `Start of \`currentVersionId\`'s own data range, as discovered at ingest time. Absent
+until a version exists.
+`,
+      example: "2026-03-01T00:00:00Z",
+    },
+    to: {
+      type: "string",
+      format: "date-time",
+      description: `End of \`currentVersionId\`'s own data range, as discovered at ingest time. Absent until
+a version exists.
+`,
+      example: "2026-03-08T00:00:00Z",
+    },
+    cadence: {
+      type: "string",
+      description: `\`currentVersionId\`'s own discovered bar cadence (e.g. \`1s\`, \`1m\`, \`1h\`). Absent until a
+version exists.
+`,
+      example: "1m",
+    },
+  },
+} as const;
+
+export const DatasetWithLinksSchema = {
+  description:
+    "A `Dataset` plus a self link. Returned by `GET /datasets/{datasetId}`.",
+  allOf: [
+    {
+      $ref: "#/components/schemas/Dataset",
+    },
+    {
+      type: "object",
+      properties: {
+        _links: {
+          type: "object",
+          properties: {
+            self: {
+              type: "object",
+              properties: {
+                href: {
+                  type: "string",
+                  example: "/v1/datasets/ds_3f9a1c2e7b0d4a5f",
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  ],
+} as const;
+
+export const DatasetCreatedSchema = {
+  description: `A \`Dataset\` plus the first upload session — the presigned URL to PUT the file to.
+`,
+  allOf: [
+    {
+      $ref: "#/components/schemas/Dataset",
+    },
+    {
+      type: "object",
+      required: ["uploadId", "upload"],
+      properties: {
+        uploadId: {
+          type: "string",
+          description: `Identifies this upload session. Pass to
+\`POST /datasets/{datasetId}/uploads/{uploadId}/finalize\` once the PUT completes.
+`,
+          example: "up_1a2b3c4d5e6f7a8b",
+        },
+        upload: {
+          type: "object",
+          required: ["url", "expiresInMinutes"],
+          properties: {
+            url: {
+              type: "string",
+              description: `Presigned URL. \`PUT\` the raw CSV file here directly — no \`Authorization\`
+header, no other API credentials.
+`,
+              example:
+                "https://storage.qtsurfer.com/00000000-.../uploads/up_1a2b3c4d5e6f7a8b/raw.csv?X-Amz-...",
+            },
+            expiresInMinutes: {
+              type: "integer",
+              description: "How long `url` stays valid.",
+              example: 15,
+            },
+          },
+        },
+      },
+    },
+  ],
+} as const;
+
+export const DatasetVersionSchema = {
+  type: "object",
+  description: `One successfully ingested upload. Cadence and timestamp unit are discovered from the file,
+not declared by the caller.
+`,
+  required: ["datasetId"],
+  properties: {
+    datasetId: {
+      type: "string",
+      example: "ds_3f9a1c2e7b0d4a5f",
+    },
+    id: {
+      type: "string",
+      description:
+        "The version id. Pass as `datasetVersionId` on `POST .../prepare` to pin it.",
+      example: "dsv_8e2b4f19c6a03d7e",
+    },
+    bytes: {
+      type: "integer",
+      description: "Size of the uploaded file.",
+      example: 4831022,
+    },
+    rows: {
+      type: "integer",
+      description: "Number of data rows.",
+      example: 86400,
+    },
+    cadence: {
+      type: "string",
+      description: "The discovered bar cadence (e.g. `1s`, `1m`, `1h`).",
+      example: "1s",
+    },
+    timestampUnit: {
+      type: "string",
+      enum: ["iso", "s", "ms", "us"],
+      description: `The unit the \`timestamp\` column was uploaded in — ISO-8601, or the epoch band its
+numeric values fell in (seconds, millis, or micros).
+`,
+      example: "iso",
+    },
+    gaps: {
+      type: "integer",
+      description: "Number of gaps at the discovered cadence.",
+      example: 0,
+    },
+    largestGapSteps: {
+      type: "integer",
+      description: "The largest gap, in units of the discovered cadence step.",
+      example: 0,
+    },
+  },
+} as const;
+
+export const DatasetUploadStateSchema = {
+  type: "object",
+  description: `Progress of one upload, from staged through ingest. Postgres-backed 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}\`.
+`,
+  required: ["uploadId", "status"],
+  properties: {
+    uploadId: {
+      type: "string",
+      example: "up_1a2b3c4d5e6f7a8b",
+    },
+    status: {
+      type: "string",
+      enum: ["uploading", "ingesting", "ready", "failed"],
+      description: `* \`uploading\` — the file was PUT to the presigned URL, but \`finalize\` has not been
+  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).
+`,
+      example: "ready",
+    },
+    jobId: {
+      type: "string",
+      description: "The ingest job id, while `status` is `ingesting`.",
+    },
+    version: {
+      allOf: [
+        {
+          $ref: "#/components/schemas/DatasetVersion",
+        },
+      ],
+      description: "Present when `status` is `ready` or `failed`.",
+    },
+  },
+} as const;
+
 export const AuthTokenResponseSchema = {
   type: "object",
   required: ["access_token", "token_type", "expires_in", "tier"],