@qtsurfer/api-client 0.6.0 → 0.8.0

package/src/generated/schemas.gen.ts

@@ -1,997 +1,1574 @@
 // This file is auto-generated by @hey-api/openapi-ts
 
 export const ResponseErrorSchema = {
-    description: 'General response error',
-    type: 'object',
-    required: ['code', 'message'],
-    properties: {
-        code: {
-            description: 'Status code',
-            type: 'integer',
-            example: 400
-        },
-        message: {
-            description: 'Error description',
-            type: 'string',
-            example: 'Invalid request'
-        }
-    }
+  description: "General response error",
+  type: "object",
+  required: ["code", "message"],
+  properties: {
+    code: {
+      description: "Status code",
+      type: "integer",
+      example: 400,
+    },
+    message: {
+      description: "Error description",
+      type: "string",
+      example: "Invalid request",
+    },
+  },
 } as const;
 
 export const InstrumentSchema = {
-    description: 'Exchange instrument identifier (e.g. a currency pair)',
-    type: 'string',
-    example: 'BTC/USDT'
+  description: "Exchange instrument identifier (e.g. a currency pair)",
+  type: "string",
+  example: "BTC/USDT",
 } as const;
 
 export const InstrumentListResponseSchema = {
-    description: 'HAL-style response envelope for the instruments listing',
-    type: 'object',
-    required: ['data', 'meta', '_links'],
-    properties: {
-        data: {
-            type: 'array',
-            description: 'The list of instruments for the segment',
-            items: {
-                '$ref': '#/components/schemas/InstrumentDetail'
-            }
-        },
-        meta: {
-            '$ref': '#/components/schemas/InstrumentListMeta'
-        },
-        _links: {
-            '$ref': '#/components/schemas/InstrumentLinks'
-        }
-    }
+  description: "HAL-style response envelope for the instruments listing",
+  type: "object",
+  required: ["data", "meta", "_links"],
+  properties: {
+    data: {
+      type: "array",
+      description: "The list of instruments for the segment",
+      items: {
+        $ref: "#/components/schemas/InstrumentDetail",
+      },
+    },
+    meta: {
+      $ref: "#/components/schemas/InstrumentListMeta",
+    },
+    _links: {
+      $ref: "#/components/schemas/InstrumentLinks",
+    },
+  },
 } as const;
 
 export const InstrumentListMetaSchema = {
-    description: 'Metadata describing the instruments listing',
-    type: 'object',
-    required: ['updatedAt', 'exchange', 'segment'],
-    properties: {
-        updatedAt: {
-            type: 'string',
-            format: 'date-time',
-            description: 'When this listing was last refreshed',
-            example: '2026-07-09T19:09:07Z'
-        },
-        exchange: {
-            type: 'string',
-            description: 'The exchange the instruments belong to',
-            example: 'binance'
-        },
-        segment: {
-            type: 'string',
-            enum: ['spot', 'futures'],
-            description: 'The market segment served in `data`',
-            example: 'spot'
-        }
-    }
+  description: "Metadata describing the instruments listing",
+  type: "object",
+  required: ["updatedAt", "exchange", "segment"],
+  properties: {
+    updatedAt: {
+      type: "string",
+      format: "date-time",
+      description: "When this listing was last refreshed",
+      example: "2026-07-09T19:09:07Z",
+    },
+    exchange: {
+      type: "string",
+      description: "The exchange the instruments belong to",
+      example: "binance",
+    },
+    segment: {
+      type: "string",
+      enum: ["spot", "futures"],
+      description: "The market segment served in `data`",
+      example: "spot",
+    },
+  },
 } as const;
 
 export const InstrumentLinksSchema = {
-    description: 'HAL `_links` — segment discovery for the instruments listing',
-    type: 'object',
-    required: ['self'],
-    properties: {
-        self: {
-            allOf: [
-                {
-                    '$ref': '#/components/schemas/HalLink'
-                }
-            ],
-            description: 'Link to this listing'
+  description: "HAL `_links` — segment discovery for the instruments listing",
+  type: "object",
+  required: ["self"],
+  properties: {
+    self: {
+      allOf: [
+        {
+          $ref: "#/components/schemas/HalLink",
         },
-        spot: {
-            allOf: [
-                {
-                    '$ref': '#/components/schemas/HalLink'
-                }
-            ],
-            description: 'Link to the spot instruments listing. Present when the exchange has a spot segment.'
+      ],
+      description: "Link to this listing",
+    },
+    spot: {
+      allOf: [
+        {
+          $ref: "#/components/schemas/HalLink",
         },
-        futures: {
-            allOf: [
-                {
-                    '$ref': '#/components/schemas/HalLink'
-                }
-            ],
-            description: 'Link to the futures instruments listing. Present only when the exchange has a futures segment.'
-        }
-    }
+      ],
+      description:
+        "Link to the spot instruments listing. Present when the exchange has a spot segment.",
+    },
+    futures: {
+      allOf: [
+        {
+          $ref: "#/components/schemas/HalLink",
+        },
+      ],
+      description:
+        "Link to the futures instruments listing. Present only when the exchange has a futures segment.",
+    },
+  },
 } as const;
 
 export const HalLinkSchema = {
-    description: 'A HAL link object (Hypertext Application Language)',
-    type: 'object',
-    required: ['href'],
-    properties: {
-        href: {
-            type: 'string',
-            format: 'uri-reference',
-            description: 'The link target as an absolute-path URI reference (resolve against the API base). A URI Template (RFC 6570) when `templated` is true.',
-            example: '/v1/exchange/binance/spot/instruments'
-        },
-        templated: {
-            type: 'boolean',
-            description: 'True when `href` is an RFC 6570 URI Template.',
-            example: false
-        }
-    }
+  description: "A HAL link object (Hypertext Application Language)",
+  type: "object",
+  required: ["href"],
+  properties: {
+    href: {
+      type: "string",
+      format: "uri-reference",
+      description:
+        "The link target as an absolute-path URI reference (resolve against the API base). A URI Template (RFC 6570) when `templated` is true.",
+      example: "/v1/exchange/binance/spot/instruments",
+    },
+    templated: {
+      type: "boolean",
+      description: "True when `href` is an RFC 6570 URI Template.",
+      example: false,
+    },
+  },
 } as const;
 
 export const InstrumentDetailSchema = {
-    description: 'Exchange instrument with per-data-type coverage and market info',
-    type: 'object',
-    required: ['id', 'base', 'quote'],
-    properties: {
-        id: {
-            type: 'string',
-            description: 'Instrument identifier (e.g. currency pair)',
-            example: 'BTC/USDT'
-        },
-        base: {
-            type: 'string',
-            description: 'Base currency',
-            example: 'BTC'
-        },
-        quote: {
-            type: 'string',
-            description: 'Quote currency',
-            example: 'USDT'
-        },
-        coverage: {
-            '$ref': '#/components/schemas/InstrumentCoverage'
-        },
-        lastPrice: {
-            type: 'number',
-            format: 'double',
-            description: 'Last traded price',
-            example: 84250.5
-        },
-        volume24h: {
-            type: 'number',
-            format: 'double',
-            description: 'Trading volume in the last 24 hours (in quote currency)',
-            example: 1234567.89
-        }
-    }
+  description:
+    "Exchange instrument with per-data-type coverage and market info",
+  type: "object",
+  required: ["id", "base", "quote"],
+  properties: {
+    id: {
+      type: "string",
+      description: "Instrument identifier (e.g. currency pair)",
+      example: "BTC/USDT",
+    },
+    base: {
+      type: "string",
+      description: "Base currency",
+      example: "BTC",
+    },
+    quote: {
+      type: "string",
+      description: "Quote currency",
+      example: "USDT",
+    },
+    coverage: {
+      $ref: "#/components/schemas/InstrumentCoverage",
+    },
+    lastPrice: {
+      type: "number",
+      format: "double",
+      description: "Last traded price",
+      example: 84250.5,
+    },
+    volume24h: {
+      type: "number",
+      format: "double",
+      description: "Trading volume in the last 24 hours (in quote currency)",
+      example: 1234567.89,
+    },
+  },
 } as const;
 
 export const InstrumentCoverageSchema = {
-    description: 'Time coverage of available data for this instrument, per data type',
-    type: 'object',
-    properties: {
-        tickers: {
-            allOf: [
-                {
-                    '$ref': '#/components/schemas/CoverageWindow'
-                }
-            ],
-            description: 'Coverage of ticker data'
+  description:
+    "Time coverage of available data for this instrument, per data type",
+  type: "object",
+  properties: {
+    tickers: {
+      allOf: [
+        {
+          $ref: "#/components/schemas/CoverageWindow",
         },
-        klines: {
-            allOf: [
-                {
-                    '$ref': '#/components/schemas/CoverageWindow'
-                }
-            ],
-            description: 'Coverage of kline (candlestick) data'
-        }
-    }
+      ],
+      description: "Coverage of ticker data",
+    },
+    klines: {
+      allOf: [
+        {
+          $ref: "#/components/schemas/CoverageWindow",
+        },
+      ],
+      description: "Coverage of kline (candlestick) data",
+    },
+  },
 } as const;
 
 export const CoverageWindowSchema = {
-    description: 'The time range of available data for a single data type',
-    type: 'object',
-    properties: {
-        from: {
-            type: 'string',
-            format: 'date-time',
-            description: 'Earliest timestamp with data available',
-            example: '2026-04-10T21:00:00Z'
-        },
-        to: {
-            type: 'string',
-            format: 'date-time',
-            description: 'Latest timestamp with data available',
-            example: '2026-07-09T20:31:08Z'
-        },
-        inactiveSince: {
-            type: 'string',
-            format: 'date-time',
-            description: 'If the instrument stopped producing this data type (delisted/inactive), the timestamp it went inactive. Optional — omitted while the instrument is active.',
-            example: '2026-06-30T12:00:00Z'
-        }
-    }
+  description: "The time range of available data for a single data type",
+  type: "object",
+  properties: {
+    from: {
+      type: "string",
+      format: "date-time",
+      description: "Earliest timestamp with data available",
+      example: "2026-04-10T21:00:00Z",
+    },
+    to: {
+      type: "string",
+      format: "date-time",
+      description: "Latest timestamp with data available",
+      example: "2026-07-09T20:31:08Z",
+    },
+    inactiveSince: {
+      type: "string",
+      format: "date-time",
+      description:
+        "If the instrument stopped producing this data type (delisted/inactive), the timestamp it went inactive. Optional — omitted while the instrument is active.",
+      example: "2026-06-30T12:00:00Z",
+    },
+  },
 } as const;
 
 export const ExchangeSchema = {
-    description: 'Exchange service provider',
-    type: 'object',
-    required: ['id', 'name'],
-    properties: {
-        id: {
-            description: 'Unique identifier for the exchange',
-            type: 'string',
-            example: 'binance'
-        },
-        name: {
-            description: 'Name of the exchange',
-            type: 'string',
-            example: 'Binance'
-        },
-        description: {
-            description: 'Description of the exchange',
-            type: 'string',
-            example: 'Binance cryptocurrency exchange'
-        }
-    }
+  description: "Exchange service provider",
+  type: "object",
+  required: ["id", "name"],
+  properties: {
+    id: {
+      description: "Unique identifier for the exchange",
+      type: "string",
+      example: "binance",
+    },
+    name: {
+      description: "Name of the exchange",
+      type: "string",
+      example: "Binance",
+    },
+    description: {
+      description: "Description of the exchange",
+      type: "string",
+      example: "Binance cryptocurrency exchange",
+    },
+  },
 } as const;
 
 export const DataSourceTypeSchema = {
-    type: 'string',
-    description: 'Managed exchange data sources available for backtesting.',
-    enum: ['ticker'],
-    example: 'ticker'
+  type: "string",
+  description: "Managed exchange data sources available for backtesting.",
+  enum: ["ticker"],
+  example: "ticker",
 } as const;
 
 export const PrepareRequestSchema = {
-    type: 'object',
-    required: ['instrument', 'from', 'to'],
-    properties: {
-        instrument: {
-            '$ref': '#/components/schemas/Instrument'
-        },
-        from: {
-            type: 'string',
-            description: `Start date for the preparation process. Supports the following formats:
+  type: "object",
+  required: ["instrument", "from", "to"],
+  properties: {
+    instrument: {
+      $ref: "#/components/schemas/Instrument",
+    },
+    from: {
+      type: "string",
+      description: `Start date for the preparation process. Supports the following formats:
 - ISO-8601 (e.g. 2024-12-14T23:59:59Z)
 - ISO DATE (e.g. 2024-12-14)
 - BASIC ISO DATE (e.g., 20241214)
 `,
-            example: '2024-12-13T00:00:00Z'
-        },
-        to: {
-            type: 'string',
-            description: `End date for the preparation process. Supports the following formats:
+      example: "2024-12-13T00:00:00Z",
+    },
+    to: {
+      type: "string",
+      description: `End date for the preparation process. Supports the following formats:
 - ISO-8601 (e.g. 2024-12-14T23:59:59Z)
 - ISO DATE (e.g. 2024-12-14)
 - BASIC ISO DATE (e.g., 20241214)
 `,
-            example: '2024-12-14'
-        },
-        cadence: {
-            type: 'string',
-            description: `Output bar cadence for the prepared range. Defaults to the publisher's
+      example: "2024-12-14",
+    },
+    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', '5m', '15m', '1h', '4h', '1d'],
-            default: '1s'
-        }
+      enum: ["1s", "5s", "1m", "5m", "15m", "1h", "4h", "1d"],
+      default: "1s",
     },
-    example: {
-        instrument: 'BTC/USDT',
-        from: '2024-12-13T00:00:00Z',
-        to: '2024-12-14T00:00:00Z',
-        cadence: '1m'
-    }
+  },
+  example: {
+    instrument: "BTC/USDT",
+    from: "2024-12-13T00:00:00Z",
+    to: "2024-12-14T00:00:00Z",
+    cadence: "1m",
+  },
 } as const;
 
 export const JobStateSchema = {
-    type: 'object',
-    description: 'Information about a single job',
-    required: ['contextId', 'status', 'size', 'completed'],
-    properties: {
-        contextId: {
-            type: 'string',
-            description: 'Opaque context identifier for the job',
-            example: 'ctx_2o8heaioicr0edvx5ybcap'
-        },
-        status: {
-            type: 'string',
-            description: `Current status of the job. Treat \`Completed | Aborted | Failed\` as
+  type: "object",
+  description: "Information about a single job",
+  required: ["contextId", "status", "size", "completed"],
+  properties: {
+    contextId: {
+      type: "string",
+      description: "Opaque context identifier for the job",
+      example: "ctx_2o8heaioicr0edvx5ybcap",
+    },
+    status: {
+      type: "string",
+      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.
 `,
-            enum: ['New', 'Started', 'Completed', 'Aborted', 'Failed'],
-            example: 'Completed'
-        },
-        statusDetail: {
-            type: ['string', 'null'],
-            description: 'Detailed status information, if available',
-            example: 'Job completed with error code 5001'
-        },
-        size: {
-            type: 'integer',
-            description: 'Total size of the data being prepared',
-            example: 100
-        },
-        completed: {
-            type: 'integer',
-            description: 'The amount of data processed so far',
-            example: 50
-        },
-        startTime: {
-            type: ['string', 'null'],
-            format: 'date-time',
-            description: 'Timestamp for when the preparation started',
-            example: '2025-01-04T14:00:00Z'
-        },
-        endTime: {
-            type: ['string', 'null'],
-            format: 'date-time',
-            description: 'Timestamp for when the preparation finished',
-            example: '2025-01-04T14:00:20Z'
-        }
-    }
+      enum: ["New", "Started", "Completed", "Aborted", "Failed"],
+      example: "Completed",
+    },
+    statusDetail: {
+      type: ["string", "null"],
+      description: "Detailed status information, if available",
+      example: "Job completed with error code 5001",
+    },
+    size: {
+      type: "integer",
+      description: "Total size of the data being prepared",
+      example: 100,
+    },
+    completed: {
+      type: "integer",
+      description: "The amount of data processed so far",
+      example: 50,
+    },
+    startTime: {
+      type: ["string", "null"],
+      format: "date-time",
+      description: "Timestamp for when the preparation started",
+      example: "2025-01-04T14:00:00Z",
+    },
+    endTime: {
+      type: ["string", "null"],
+      format: "date-time",
+      description: "Timestamp for when the preparation finished",
+      example: "2025-01-04T14:00:20Z",
+    },
+  },
 } as const;
 
 export const PrepareJobStateSchema = {
-    description: `State of a single-instrument prepare job — the \`JobState\` shape plus a per-hour
+  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.
 `,
-    allOf: [
-        {
-            '$ref': '#/components/schemas/JobState'
-        },
-        {
-            type: 'object',
-            properties: {
-                dataFrom: {
-                    type: ['string', 'null'],
-                    format: 'date-time',
-                    description: 'Start of the available data range for the prepared instrument.',
-                    example: '2026-04-14T13:00:00Z'
-                },
-                dataTo: {
-                    type: ['string', 'null'],
-                    format: 'date-time',
-                    description: 'End of the available data range for the prepared instrument.',
-                    example: '2026-04-14T15:30:05Z'
-                },
-                coverageRatio: {
-                    type: 'number',
-                    format: 'double',
-                    minimum: 0,
-                    maximum: 1,
-                    description: `\`hoursWithData / totalHours\` in \`[0,1]\` (\`1.0\` when \`totalHours\` is 0) — the
+  allOf: [
+    {
+      $ref: "#/components/schemas/JobState",
+    },
+    {
+      type: "object",
+      properties: {
+        dataFrom: {
+          type: ["string", "null"],
+          format: "date-time",
+          description:
+            "Start of the available data range for the prepared instrument.",
+          example: "2026-04-14T13:00:00Z",
+        },
+        dataTo: {
+          type: ["string", "null"],
+          format: "date-time",
+          description:
+            "End of the available data range for the prepared instrument.",
+          example: "2026-04-14T15:30:05Z",
+        },
+        coverageRatio: {
+          type: "number",
+          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.
 `,
-                    example: 0.994
-                },
-                totalHours: {
-                    type: 'integer',
-                    description: 'Number of whole hours in the requested prepare range.',
-                    example: 168
-                },
-                hoursWithData: {
-                    type: 'integer',
-                    description: 'Number of hours in the range that have data.',
-                    example: 167
-                },
-                hoursWithoutData: {
-                    type: 'array',
-                    description: 'One entry per hour in the range that has no data, with a rationale.',
-                    items: {
-                        type: 'object',
-                        properties: {
-                            hour: {
-                                type: 'string',
-                                format: 'date-time',
-                                description: 'The hour (UTC, hour-aligned) that has no data.',
-                                example: '2026-04-14T02:00:00Z'
-                            },
-                            expected: {
-                                type: 'integer',
-                                description: `Expected row count for the hour (currently always 0; reserved for
+          example: 0.994,
+        },
+        totalHours: {
+          type: "integer",
+          description: "Number of whole hours in the requested prepare range.",
+          example: 168,
+        },
+        hoursWithData: {
+          type: "integer",
+          description: "Number of hours in the range that have data.",
+          example: 167,
+        },
+        hoursWithoutData: {
+          type: "array",
+          description:
+            "One entry per hour in the range that has no data, with a rationale.",
+          items: {
+            type: "object",
+            properties: {
+              hour: {
+                type: "string",
+                format: "date-time",
+                description: "The hour (UTC, hour-aligned) that has no data.",
+                example: "2026-04-14T02:00:00Z",
+              },
+              expected: {
+                type: "integer",
+                description: `Expected row count for the hour (currently always 0; reserved for
 future use). The rationale never depends on it.
 `,
-                                example: 0
-                            },
-                            rationale: {
-                                type: 'string',
-                                description: `Why the hour has no data. \`pending_conversion\`: data for this hour is
+                example: 0,
+              },
+              rationale: {
+                type: "string",
+                description: `Why the hour has no data. \`pending_conversion\`: data for this hour is
 still being produced — a re-poll may fill it. \`low_activity\`: the
 instrument did not trade that hour. \`unknown\`: no data to classify by.
 `,
-                                enum: ['pending_conversion', 'low_activity', 'unknown'],
-                                example: 'low_activity'
-                            }
-                        }
-                    }
-                }
-            }
-        }
-    ]
+                enum: ["pending_conversion", "low_activity", "unknown"],
+                example: "low_activity",
+              },
+            },
+          },
+        },
+      },
+    },
+  ],
 } as const;
 
 export const SweepAxisSchema = {
-    description: 'A numeric range or an explicit list of values for one strategy property.',
-    oneOf: [
-        {
-            type: 'object',
-            required: ['from', 'to', 'step'],
-            additionalProperties: false,
-            properties: {
-                from: {
-                    type: 'number',
-                    format: 'double'
-                },
-                to: {
-                    type: 'number',
-                    format: 'double'
-                },
-                step: {
-                    type: 'number',
-                    format: 'double',
-                    exclusiveMinimum: 0
-                }
-            }
+  description:
+    "A numeric range or an explicit list of values for one strategy property.",
+  oneOf: [
+    {
+      type: "object",
+      required: ["from", "to", "step"],
+      additionalProperties: false,
+      properties: {
+        from: {
+          type: "number",
+          format: "double",
         },
-        {
-            type: 'object',
-            required: ['values'],
-            additionalProperties: false,
-            properties: {
-                values: {
-                    type: 'array',
-                    minItems: 1,
-                    items: {
-                        oneOf: [
-                            {
-                                type: 'number'
-                            },
-                            {
-                                type: 'boolean'
-                            }
-                        ]
-                    }
-                }
-            }
-        }
-    ]
+        to: {
+          type: "number",
+          format: "double",
+        },
+        step: {
+          type: "number",
+          format: "double",
+          exclusiveMinimum: 0,
+        },
+      },
+    },
+    {
+      type: "object",
+      required: ["values"],
+      additionalProperties: false,
+      properties: {
+        values: {
+          type: "array",
+          minItems: 1,
+          items: {
+            oneOf: [
+              {
+                type: "number",
+              },
+              {
+                type: "boolean",
+              },
+            ],
+          },
+        },
+      },
+    },
+  ],
 } as const;
 
 export const SweepSpecRequestSchema = {
-    type: 'object',
-    required: ['params'],
-    properties: {
-        sampler: {
-            type: 'string',
-            enum: ['grid', 'random', 'lhs'],
-            default: 'grid'
-        },
-        seed: {
-            type: 'integer',
-            format: 'int64',
-            minimum: -9007199254740991,
-            maximum: 9007199254740991,
-            description: `Reproducibility seed. If omitted, the server generates one with Java's
+  type: "object",
+  required: ["params"],
+  properties: {
+    sampler: {
+      type: "string",
+      enum: ["grid", "random", "lhs"],
+      default: "grid",
+    },
+    seed: {
+      type: "integer",
+      format: "int64",
+      minimum: -9007199254740991,
+      maximum: 9007199254740991,
+      description: `Reproducibility seed. If omitted, the server generates one with Java's
 \`L64X128MixRandom\` generator and returns the effective value. The range
 is limited to JavaScript-safe integers so generated clients can replay it exactly.
-`
-        },
-        samples: {
-            type: 'integer',
-            minimum: 1,
-            description: 'Number of samples for `random` and `lhs`; ignored by `grid`.'
-        },
-        objective: {
-            type: 'string',
-            enum: ['sharpe', 'sortino', 'pnl', 'maxdd'],
-            default: 'sharpe'
-        },
-        params: {
-            type: 'object',
-            minProperties: 1,
-            additionalProperties: {
-                '$ref': '#/components/schemas/SweepAxis'
-            }
-        }
-    },
-    example: {
-        sampler: 'lhs',
-        seed: 487221,
-        samples: 100,
-        objective: 'sharpe',
-        params: {
-            rsiPeriod: {
-                from: 7,
-                to: 28,
-                step: 1
-            },
-            useTrendFilter: {
-                values: [true, false]
-            }
-        }
-    }
+`,
+    },
+    samples: {
+      type: "integer",
+      minimum: 1,
+      description:
+        "Number of samples for `random` and `lhs`; ignored by `grid`.",
+    },
+    objective: {
+      type: "string",
+      enum: ["sharpe", "sortino", "pnl", "maxdd"],
+      default: "sharpe",
+    },
+    params: {
+      type: "object",
+      minProperties: 1,
+      additionalProperties: {
+        $ref: "#/components/schemas/SweepAxis",
+      },
+    },
+  },
+  example: {
+    sampler: "lhs",
+    seed: 487221,
+    samples: 100,
+    objective: "sharpe",
+    params: {
+      rsiPeriod: {
+        from: 7,
+        to: 28,
+        step: 1,
+      },
+      useTrendFilter: {
+        values: [true, false],
+      },
+    },
+  },
 } as const;
 
 export const SweepBaseConfigSchema = {
-    type: 'object',
-    properties: {
-        initialFunding: {
-            type: 'number',
-            format: 'double',
-            exclusiveMinimum: 0,
-            default: 10000
-        },
-        feeRate: {
-            type: 'number',
-            format: 'double',
-            minimum: 0,
-            default: 0.001
-        },
-        buyFeeRate: {
-            type: 'number',
-            format: 'double',
-            minimum: 0
-        },
-        sellFeeRate: {
-            type: 'number',
-            format: 'double',
-            minimum: 0
-        },
-        feeLeg: {
-            type: 'string',
-            enum: ['RECEIVED', 'QUOTE', 'BASE'],
-            default: 'RECEIVED'
-        },
-        percentAmountToLock: {
-            type: 'number',
-            format: 'double',
-            exclusiveMinimum: 0,
-            maximum: 100
-        }
-    }
+  type: "object",
+  properties: {
+    initialFunding: {
+      type: "number",
+      format: "double",
+      exclusiveMinimum: 0,
+      default: 10000,
+    },
+    feeRate: {
+      type: "number",
+      format: "double",
+      minimum: 0,
+      default: 0.001,
+    },
+    buyFeeRate: {
+      type: "number",
+      format: "double",
+      minimum: 0,
+    },
+    sellFeeRate: {
+      type: "number",
+      format: "double",
+      minimum: 0,
+    },
+    feeLeg: {
+      type: "string",
+      enum: ["RECEIVED", "QUOTE", "BASE"],
+      default: "RECEIVED",
+    },
+    percentAmountToLock: {
+      type: "number",
+      format: "double",
+      exclusiveMinimum: 0,
+      maximum: 100,
+    },
+  },
 } as const;
 
 export const ExecuteSweepRequestSchema = {
-    type: 'object',
-    required: ['strategyId', 'sweep'],
-    properties: {
-        strategyId: {
-            '$ref': '#/components/schemas/strategyId'
-        },
-        sweep: {
-            '$ref': '#/components/schemas/SweepSpecRequest'
-        },
-        baseConfig: {
-            '$ref': '#/components/schemas/SweepBaseConfig'
-        },
-        storeSignals: {
-            type: 'boolean',
-            default: false,
-            description: 'Store signals for every trial. Keep false for normal sweeps.'
-        },
-        shards: {
-            type: 'integer',
-            minimum: 0,
-            description: 'Requested horizontal shard count; 0 or omitted selects automatically.',
-            default: 0
-        },
-        minTradeFloor: {
-            type: 'integer',
-            minimum: 0,
-            default: 30,
-            description: 'Trials below this trade count are flagged but remain in the results.'
-        }
-    }
+  type: "object",
+  required: ["strategyId", "sweep"],
+  properties: {
+    strategyId: {
+      $ref: "#/components/schemas/strategyId",
+    },
+    sweep: {
+      $ref: "#/components/schemas/SweepSpecRequest",
+    },
+    baseConfig: {
+      $ref: "#/components/schemas/SweepBaseConfig",
+    },
+    storeSignals: {
+      type: "boolean",
+      default: false,
+      description:
+        "Store signals for every trial. Keep false for normal sweeps.",
+    },
+    shards: {
+      type: "integer",
+      minimum: 0,
+      description:
+        "Requested horizontal shard count; 0 or omitted selects automatically.",
+      default: 0,
+    },
+    minTradeFloor: {
+      type: "integer",
+      minimum: 0,
+      default: 30,
+      description:
+        "Trials below this trade count are flagged but remain in the results.",
+    },
+    walkForward: {
+      $ref: "#/components/schemas/WalkForwardRequest",
+    },
+  },
+} as const;
+
+export const WalkForwardRequestSchema = {
+  type: "object",
+  description:
+    "Opt in to walk-forward validation. Present, the sweep runs as F sequential folds and the result gains a `walkForward` section; absent, nothing about the sweep changes. Two requests that differ only in this block are two different sweeps and do not deduplicate against each other.",
+  required: ["folds"],
+  properties: {
+    folds: {
+      type: "integer",
+      minimum: 2,
+      description: `How many sequential optimize-then-score windows to run. Two is the minimum for a reason, and it is structural rather than a tuning choice: parameter drift is measured between consecutive fold winners, and a single fold — one train/test split with no sequence — has no consecutive pair to compare, so it would report the strongest possible stability having measured nothing.
+The upper bound is a server setting (12 by default) and is deliberately not pinned here, since a spec that hardcodes a tunable limit lies the day it is raised. Exceeding it, or exceeding the sweep budget once multiplied by the grid size, is a 400.`,
+    },
+    inSamplePct: {
+      type: "integer",
+      minimum: 10,
+      maximum: 90,
+      default: 66,
+      description:
+        "Share of the session each fold spends optimizing; the remainder is where its winner is scored. Lower values leave more data to be scored on and, on short sessions, are also what lets the requested fold count tile the data at all.",
+    },
+  },
 } as const;
 
 export const ExecuteSweepAcceptedSchema = {
-    type: 'object',
-    required: ['sweepId', 'requestId', 'totalRuns', 'shards', 'seed', 'queued'],
-    properties: {
-        sweepId: {
-            type: 'string',
-            example: 'swp_95e47a7f0966ce11'
-        },
-        requestId: {
-            type: 'string'
-        },
-        totalRuns: {
-            type: 'integer',
-            minimum: 1
-        },
-        shards: {
-            type: 'integer',
-            minimum: 1
-        },
-        seed: {
-            type: 'integer',
-            format: 'int64',
-            minimum: -9007199254740991,
-            maximum: 9007199254740991,
-            description: 'Effective seed used to expand the sweep.'
-        },
-        queued: {
-            type: 'boolean',
-            description: 'False when an identical sweep already exists and was not enqueued again.'
-        }
-    }
+  type: "object",
+  required: ["sweepId", "requestId", "totalRuns", "shards", "seed", "queued"],
+  properties: {
+    sweepId: {
+      type: "string",
+      example: "swp_95e47a7f0966ce11",
+    },
+    requestId: {
+      type: "string",
+    },
+    totalRuns: {
+      type: "integer",
+      minimum: 1,
+    },
+    shards: {
+      type: "integer",
+      minimum: 1,
+    },
+    seed: {
+      type: "integer",
+      format: "int64",
+      minimum: -9007199254740991,
+      maximum: 9007199254740991,
+      description: "Effective seed used to expand the sweep.",
+    },
+    queued: {
+      type: "boolean",
+      description:
+        "False when an identical sweep already exists and was not enqueued again.",
+    },
+    walkForward: {
+      $ref: "#/components/schemas/WalkForwardAccepted",
+    },
+  },
+} as const;
+
+export const WalkForwardAcceptedSchema = {
+  type: "object",
+  description:
+    "Echo of the accepted walk-forward configuration, present only when the submit carried one. `inSamplePct` is the resolved value, so a request that omitted it can see what it got.",
+  required: ["folds", "inSamplePct", "totalRuns"],
+  properties: {
+    folds: {
+      type: "integer",
+    },
+    inSamplePct: {
+      type: "integer",
+    },
+    totalRuns: {
+      type: "integer",
+      description:
+        "What this sweep actually costs, `folds × (grid size + 1)` — the in-sample runs for every fold plus each fold's one out-of-sample run. Deliberately distinct from the top-level `totalRuns`, which stays the size of the grid that was submitted.",
+    },
+  },
 } as const;
 
 export const SweepProgressSchema = {
-    type: 'object',
-    required: ['done', 'total', 'aborted', 'shardCount', 'pendingShards'],
-    properties: {
-        done: {
-            type: 'integer',
-            format: 'int64'
-        },
-        total: {
-            type: 'integer'
-        },
-        aborted: {
-            type: 'integer',
-            format: 'int64'
-        },
-        shardCount: {
-            type: 'integer'
-        },
-        pendingShards: {
-            type: 'integer'
-        }
-    }
+  type: "object",
+  description:
+    "How far along a sweep is, and — when the sweep is still running — enough to tell a healthy one from a stuck one. The counts partition the shards (or, for a walk-forward sweep, the folds): every unit is either finished, failed, waiting to be retried, or not yet started.",
+  required: [
+    "done",
+    "total",
+    "aborted",
+    "shardCount",
+    "pendingShards",
+    "failedShards",
+    "retrying",
+    "notStarted",
+  ],
+  properties: {
+    done: {
+      type: "integer",
+      format: "int64",
+    },
+    total: {
+      type: "integer",
+    },
+    aborted: {
+      type: "integer",
+      format: "int64",
+      description:
+        "Individual runs that executed and aborted. A row-level count: a shard that fails before producing any rows leaves this at 0, which is why `failedShards` exists alongside it.",
+    },
+    shardCount: {
+      type: "integer",
+    },
+    pendingShards: {
+      type: "integer",
+    },
+    failedShards: {
+      type: "integer",
+      format: "int64",
+      description:
+        "Shards (or folds) that failed and will not be retried. Distinct from `aborted`: this counts whole units that never reported, not runs that ran badly.",
+    },
+    retrying: {
+      type: "integer",
+      description:
+        "Units whose last attempt failed on something transient — an I/O error, a worker that died mid-read — and which are queued to be attempted again. Not counted as failures, because they have not failed yet; a sweep with a non-zero value here is still expected to complete.",
+    },
+    notStarted: {
+      type: "integer",
+      description:
+        "Units that have not reported anything yet. Covers both work still queued behind other work and work claimed by a worker that stopped before it began, which is why a sweep with a persistent value here and a rising `stalledSeconds` is worth looking at.",
+    },
+    stalledSeconds: {
+      type: "integer",
+      format: "int64",
+      description:
+        "Seconds since anything last advanced. Omitted on a finished sweep, where it would only measure how long ago it finished, and on sweeps submitted before this field existed.",
+    },
+    etaSeconds: {
+      type: "integer",
+      format: "int64",
+      description:
+        'Rough seconds remaining, extrapolated from the rate observed so far and assuming nothing else competes for workers. Runs conservative in practice — it has measured 2–5× long when a sweep spent part of its life waiting to be retried, since that wait dilutes the observed rate. **Omitted, never zero, when it cannot be computed**: a sweep with nothing finished yet has no rate to extrapolate from, and a zero would read as "about to finish". Excludes queue wait entirely; `retrying` and `stalledSeconds` are where that shows up.',
+    },
+  },
 } as const;
 
 export const SweepRunRowSchema = {
-    type: 'object',
-    required: ['runIx', 'params', 'sharpe', 'sortino', 'pnl', 'pnlPct', 'cagr', 'maxDdPct', 'trades', 'winRate', 'belowTradeFloor', 'aborted', 'runtimeMs'],
-    properties: {
-        runIx: {
-            type: 'integer',
-            minimum: 0,
-            description: 'Deterministic zero-based expansion index, stable across shards and ranking.'
-        },
-        rank: {
-            type: 'integer',
-            minimum: 1,
-            description: 'Present only in the `ranked` view.'
-        },
-        params: {
-            type: 'object',
-            additionalProperties: true
-        },
-        sharpe: {
-            type: 'number',
-            format: 'double'
-        },
-        sortino: {
-            type: 'number',
-            format: 'double'
-        },
-        pnl: {
-            type: 'number',
-            format: 'double',
-            description: 'Absolute net PnL in the output currency.'
-        },
-        pnlPct: {
-            type: 'number',
-            format: 'double'
-        },
-        cagr: {
-            type: 'number',
-            format: 'double'
-        },
-        maxDdPct: {
-            type: 'number',
-            format: 'double'
-        },
-        trades: {
-            type: 'integer',
-            format: 'int64'
-        },
-        winRate: {
-            type: 'number',
-            format: 'double'
-        },
-        belowTradeFloor: {
-            type: 'boolean'
-        },
-        aborted: {
-            type: 'boolean'
-        },
-        runtimeMs: {
-            type: 'integer',
-            format: 'int64'
-        }
-    }
+  type: "object",
+  required: [
+    "runIx",
+    "params",
+    "sharpe",
+    "sortino",
+    "pnl",
+    "pnlPct",
+    "cagr",
+    "maxDdPct",
+    "trades",
+    "winRate",
+    "belowTradeFloor",
+    "aborted",
+    "runtimeMs",
+  ],
+  properties: {
+    runIx: {
+      type: "integer",
+      minimum: 0,
+      description:
+        "Deterministic zero-based expansion index, stable across shards and ranking.",
+    },
+    rank: {
+      type: "integer",
+      minimum: 1,
+      description: "Present only in the `ranked` view.",
+    },
+    plateauScore: {
+      type: "number",
+      format: "double",
+      description:
+        "The objective of the worst run in this point's immediate neighbourhood — how well the region around it holds up, not how well it scored itself. Present only in the `ranked` view when plateau ranking applied. Always read together with `neighbourCount`.",
+    },
+    neighbourCount: {
+      type: "integer",
+      minimum: 0,
+      description:
+        "How many neighbouring parameter points backed the `plateauScore`. Zero means the point had no neighbours in the grid, so its score is unevidenced rather than confirmed — the value alone cannot be distinguished from a genuinely robust one.",
+    },
+    deflatedSharpe: {
+      type: "number",
+      format: "double",
+      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.",
+    },
+    params: {
+      type: "object",
+      additionalProperties: true,
+    },
+    sharpe: {
+      type: "number",
+      format: "double",
+    },
+    sortino: {
+      type: "number",
+      format: "double",
+    },
+    pnl: {
+      type: "number",
+      format: "double",
+      description: "Absolute net PnL in the output currency.",
+    },
+    pnlPct: {
+      type: "number",
+      format: "double",
+    },
+    cagr: {
+      type: "number",
+      format: "double",
+    },
+    maxDdPct: {
+      type: "number",
+      format: "double",
+    },
+    trades: {
+      type: "integer",
+      format: "int64",
+    },
+    winRate: {
+      type: "number",
+      format: "double",
+    },
+    belowTradeFloor: {
+      type: "boolean",
+    },
+    aborted: {
+      type: "boolean",
+    },
+    runtimeMs: {
+      type: "integer",
+      format: "int64",
+    },
+  },
+} as const;
+
+export const SweepSensitivitySchema = {
+  type: "object",
+  description:
+    "Sensitivity aggregates over a sweep's stored rows. Marginals are always complete; heatmaps may be capped, in which case `heatmapsTruncated` is true.",
+  properties: {
+    sweepId: {
+      type: "string",
+    },
+    status: {
+      type: "string",
+      enum: ["RUNNING", "COMPLETED", "PARTIAL", "CANCELLED"],
+    },
+    objective: {
+      type: "string",
+      enum: ["sharpe", "sortino", "pnl", "maxdd"],
+    },
+    rowsAnalysed: {
+      type: "integer",
+      description:
+        "Rows available when this was computed. Grows while a sweep is still running.",
+    },
+    marginals: {
+      type: "array",
+      items: {
+        $ref: "#/components/schemas/SweepMarginal",
+      },
+    },
+    heatmaps: {
+      type: "array",
+      items: {
+        $ref: "#/components/schemas/SweepHeatmap",
+      },
+    },
+    heatmapsTruncated: {
+      type: "boolean",
+      description:
+        'True when at least one two-parameter surface was left out to stay inside the response budget. Told explicitly because a silently short list would read as "these are all the interactions", which is the wrong thing to conclude from a sensitivity view.',
+    },
+  },
+} as const;
+
+export const SweepMarginalSchema = {
+  type: "object",
+  description: "One axis, with every other axis collapsed away.",
+  properties: {
+    param: {
+      type: "string",
+    },
+    points: {
+      type: "array",
+      items: {
+        $ref: "#/components/schemas/SweepMarginalPoint",
+      },
+    },
+  },
+} as const;
+
+export const SweepMarginalPointSchema = {
+  type: "object",
+  description:
+    "How the objective behaved at one value of one axis. `best` and `mean` disagreeing is informative rather than noise: a high `best` with a poor `mean` marks a value that only works alongside particular settings of the other axes.",
+  properties: {
+    value: {
+      description: "The axis value, as it appears in a run's parameters.",
+    },
+    count: {
+      type: "integer",
+      description: "Non-aborted runs that used this value.",
+    },
+    best: {
+      type: "number",
+      format: "double",
+    },
+    mean: {
+      type: "number",
+      format: "double",
+    },
+    worst: {
+      type: "number",
+      format: "double",
+    },
+  },
+} as const;
+
+export const SweepHeatmapSchema = {
+  type: "object",
+  description:
+    "The surface for one pair of axes, with all others collapsed away.",
+  properties: {
+    paramA: {
+      type: "string",
+    },
+    paramB: {
+      type: "string",
+    },
+    cells: {
+      type: "array",
+      items: {
+        $ref: "#/components/schemas/SweepHeatmapCell",
+      },
+    },
+  },
+} as const;
+
+export const SweepHeatmapCellSchema = {
+  type: "object",
+  properties: {
+    valueA: {},
+    valueB: {},
+    count: {
+      type: "integer",
+    },
+    best: {
+      type: "number",
+      format: "double",
+    },
+    mean: {
+      type: "number",
+      format: "double",
+    },
+  },
 } as const;
 
 export const ExecuteSweepResultSchema = {
-    type: 'object',
-    required: ['sweepId', 'status', 'objective', 'order', 'progress', 'leaderboardSize', 'truncated', 'leaderboard'],
-    properties: {
-        sweepId: {
-            type: 'string'
-        },
-        status: {
-            type: 'string',
-            enum: ['RUNNING', 'COMPLETED', 'PARTIAL', 'CANCELLED']
-        },
-        objective: {
-            type: 'string',
-            enum: ['sharpe', 'sortino', 'pnl', 'maxdd']
-        },
-        order: {
-            type: 'string',
-            enum: ['ranked', 'natural']
-        },
-        progress: {
-            '$ref': '#/components/schemas/SweepProgress'
-        },
-        leaderboardSize: {
-            type: 'integer',
-            description: 'Total result rows currently available.'
-        },
-        truncated: {
-            type: 'boolean',
-            description: 'True only when the ranked view exceeds its display limit.'
-        },
-        leaderboard: {
-            type: 'array',
-            items: {
-                '$ref': '#/components/schemas/SweepRunRow'
-            }
-        }
-    }
+  type: "object",
+  required: [
+    "sweepId",
+    "status",
+    "objective",
+    "order",
+    "progress",
+    "leaderboardSize",
+    "truncated",
+    "leaderboard",
+  ],
+  properties: {
+    sweepId: {
+      type: "string",
+    },
+    status: {
+      type: "string",
+      enum: ["RUNNING", "COMPLETED", "PARTIAL", "CANCELLED"],
+    },
+    objective: {
+      type: "string",
+      enum: ["sharpe", "sortino", "pnl", "maxdd"],
+    },
+    order: {
+      type: "string",
+      enum: ["ranked", "natural"],
+    },
+    ranking: {
+      type: "string",
+      enum: ["plateau", "raw"],
+      description:
+        "Which ordering was actually applied, which is not always the one requested: a sweep with no stored parameter grid cannot be plateau-ranked and falls back to `raw`. Always `raw` when `order=natural`.",
+    },
+    pbo: {
+      type: "number",
+      format: "double",
+      minimum: 0,
+      maximum: 1,
+      description:
+        "Probability of backtest overfitting for the sweep as a whole, by combinatorially symmetric cross-validation: how often the configuration that won in-sample lands below median out-of-sample. Above ~0.5 the sweep is selecting noise, whatever its top row says. Computed once when the last shard finishes, so it is absent while the sweep is still running and on sweeps too small for the statistic to mean anything.",
+    },
+    pboSplits: {
+      type: "integer",
+      description:
+        "How many train/test splits the `pbo` figure was averaged over.",
+    },
+    progress: {
+      $ref: "#/components/schemas/SweepProgress",
+    },
+    leaderboardSize: {
+      type: "integer",
+      description: "Total result rows currently available.",
+    },
+    truncated: {
+      type: "boolean",
+      description: "True only when the ranked view exceeds its display limit.",
+    },
+    leaderboard: {
+      type: "array",
+      items: {
+        $ref: "#/components/schemas/SweepRunRow",
+      },
+    },
+    walkForward: {
+      $ref: "#/components/schemas/WalkForwardResult",
+    },
+  },
+} as const;
+
+export const WalkForwardResultSchema = {
+  type: "object",
+  description:
+    "Present only on a sweep submitted with `walkForward`, and present from acceptance onward — its presence, not its contents, is what identifies a walk-forward sweep. `completedFolds` is 0 while the first fold is still running.",
+  required: ["folds", "completedFolds", "results"],
+  properties: {
+    folds: {
+      type: "integer",
+      description: "Folds requested at submit.",
+    },
+    inSamplePct: {
+      type: "integer",
+      description: "Resolved in-sample share each fold optimized on.",
+    },
+    completedFolds: {
+      type: "integer",
+      description: "Folds that have finished and reported a winner.",
+    },
+    paramDrift: {
+      type: "number",
+      format: "double",
+      minimum: 0,
+      description:
+        "Mean normalized lattice distance between consecutive fold winners. Low is good: winners that stay in a tight band fold after fold are evidence the parameter means something, while winners that jump across the grid every time are the sweep re-fitting noise, and that backtest will not survive contact with live data. **Absent is not zero** — the field is omitted whenever the figure could not be computed (fewer than two folds finished, no stored grid to place winners on), because zero is itself a meaningful reading here and a placeholder would be indistinguishable from perfect stability.",
+    },
+    results: {
+      type: "array",
+      description: "One entry per completed fold, oldest first.",
+      items: {
+        $ref: "#/components/schemas/WalkForwardFold",
+      },
+    },
+  },
+} as const;
+
+export const WalkForwardFoldSchema = {
+  type: "object",
+  description:
+    "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.",
+  required: [
+    "foldIx",
+    "inSampleFrom",
+    "inSampleTo",
+    "outOfSampleTo",
+    "params",
+    "inSampleSharpe",
+    "outOfSample",
+    "vectorsRun",
+  ],
+  properties: {
+    foldIx: {
+      type: "integer",
+      description: "Position in the walk-forward sequence, oldest first.",
+    },
+    inSampleFrom: {
+      type: "integer",
+      description:
+        "First index of the optimization window, into the prepared session.",
+    },
+    inSampleTo: {
+      type: "integer",
+      description:
+        "End of the optimization window, exclusive — and where scoring begins.",
+    },
+    outOfSampleTo: {
+      type: "integer",
+      description: "End of the scoring window, exclusive.",
+    },
+    params: {
+      type: "object",
+      additionalProperties: true,
+      description:
+        "The parameter vector that won this fold's optimization window.",
+    },
+    inSampleSharpe: {
+      type: "number",
+      format: "double",
+      description: "How that winner scored on the window it was chosen on.",
+    },
+    outOfSample: {
+      $ref: "#/components/schemas/SweepRunRow",
+    },
+    vectorsRun: {
+      type: "integer",
+      description:
+        "Vectors this fold evaluated in-sample before picking its winner.",
+    },
+  },
 } as const;
 
 export const AcceptedJobSchema = {
-    type: 'object',
-    description: `Response returned by async endpoints (\`202 Accepted\`). The \`jobId\` is deterministic for the
+  type: "object",
+  description: `Response returned by async endpoints (\`202 Accepted\`). The \`jobId\` is deterministic for the
 same input parameters — repeated calls with identical params return the same id.
 `,
-    required: ['jobId'],
-    properties: {
-        jobId: {
-            type: 'string',
-            description: 'Unique job identifier; use this to poll for completion.',
-            example: '13RBLGQlPnfDjO6wyKSX8i'
-        }
+  required: ["jobId"],
+  properties: {
+    jobId: {
+      type: "string",
+      description: "Unique job identifier; use this to poll for completion.",
+      example: "13RBLGQlPnfDjO6wyKSX8i",
     },
-    example: {
-        jobId: '13RBLGQlPnfDjO6wyKSX8i'
-    }
+  },
+  example: {
+    jobId: "13RBLGQlPnfDjO6wyKSX8i",
+  },
 } as const;
 
 export const BacktestJobResultSchema = {
-    type: 'object',
-    description: 'Backtest job result.',
-    required: ['results', 'state'],
-    properties: {
-        results: {
-            '$ref': '#/components/schemas/ResultMap'
-        },
-        state: {
-            '$ref': '#/components/schemas/JobState'
-        }
-    }
+  type: "object",
+  description: "Backtest job result.",
+  required: ["results", "state"],
+  properties: {
+    results: {
+      $ref: "#/components/schemas/ResultMap",
+    },
+    state: {
+      $ref: "#/components/schemas/JobState",
+    },
+  },
 } as const;
 
 export const ResultMapSchema = {
-    type: 'object',
-    description: 'Execution result map. Always includes core fields (hostName, iops, strategyId, instrument). Yield metrics (pnlTotal, pnlTotalPercent, totalTrades, winRate, equityCurve, etc.) are present when the strategy emitted at least one trade. When signal storage is enabled, includes signal fields described below.',
-    required: ['strategyId', 'instrument'],
-    properties: {
-        hostName: {
-            type: 'string',
-            description: 'Identifier of the worker that executed the strategy. Useful when reporting issues so support can correlate with logs.',
-            example: 'executor10'
-        },
-        iops: {
-            type: 'number',
-            format: 'double',
-            description: 'Instrument operations per second throughput during execution',
-            example: 123956.53
-        },
-        strategyId: {
-            type: 'string',
-            description: 'Identifier of the compiled strategy that produced this result',
-            example: 'strategy:00000000-0000-0000-0000-000000000000:ticker:2iyvtenlzh9dabqtxn7nbv'
-        },
-        instrument: {
-            type: 'string',
-            description: 'The instrument (currency pair) that was backtested',
-            example: 'BTC/USDT'
-        },
-        pnlTotal: {
-            type: 'number',
-            format: 'double',
-            description: 'Total profit and loss in the output currency',
-            example: 42.75
-        },
-        pnlTotalPercent: {
-            type: 'number',
-            format: 'double',
-            description: 'Total PnL as a percentage of the initial capital (`backtestFunding`). Zero when `backtestFunding` is 0.',
-            example: 42.75
-        },
-        totalTrades: {
-            type: 'integer',
-            format: 'int64',
-            description: 'Total number of trades executed by the strategy',
-            example: 156
-        },
-        winRate: {
-            type: 'number',
-            format: 'double',
-            description: 'Percentage of profitable trades (0-100)',
-            example: 58.33
-        },
-        sharpeRatio: {
-            type: 'number',
-            format: 'double',
-            description: 'Risk-adjusted return ratio (mean return / standard deviation of returns)',
-            example: 1.245
-        },
-        sortinoRatio: {
-            type: 'number',
-            format: 'double',
-            description: 'Downside risk-adjusted return ratio (mean return / downside deviation)',
-            example: 1.872
-        },
-        cagr: {
-            type: 'number',
-            format: 'double',
-            description: 'Compound Annual Growth Rate',
-            example: 0.1534
-        },
-        maxDrawdown: {
-            type: 'number',
-            format: 'double',
-            description: 'Maximum absolute drawdown in the output currency',
-            example: 12.5
-        },
-        maxDrawdownPercent: {
-            type: 'number',
-            format: 'double',
-            description: 'Maximum percentage drawdown from peak equity',
-            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
-                },
-                {
-                    timestamp: 1700000120000,
-                    equity: 90.25
-                }
-            ]
-        },
-        signalCount: {
-            type: 'integer',
-            description: 'Number of signals emitted during strategy execution',
-            example: 100000
-        },
-        signalsId: {
-            type: 'string',
-            description: 'Storage key for the signals file. Treat as opaque; use signalsUrl to download.',
-            example: '00000000-0000-0000-0000-000000000000/exec/binance/3vsndwikcuaatjmb83fjtl'
-        },
-        signalsUrl: {
-            type: 'string',
-            format: 'uri',
-            description: "HTTPS URL to download the signals Parquet file. Use signalsUpload to know when it's ready.",
-            example: 'https://storage.qtsurfer.com/00000000-0000-0000-0000-000000000000/exec/binance/3vsndwikcuaatjmb83fjtl.parquet'
+  type: "object",
+  description:
+    "Execution result map. Always includes core fields (hostName, iops, strategyId, instrument). Yield metrics (pnlTotal, pnlTotalPercent, totalTrades, winRate, equityCurve, etc.) are present when the strategy emitted at least one trade. When signal storage is enabled, includes signal fields described below. `notices` carries what the run had to say about itself, and is absent when it had nothing.",
+  required: ["strategyId", "instrument"],
+  properties: {
+    hostName: {
+      type: "string",
+      description:
+        "Identifier of the worker that executed the strategy. Useful when reporting issues so support can correlate with logs.",
+      example: "executor10",
+    },
+    iops: {
+      type: "number",
+      format: "double",
+      description:
+        "Instrument operations per second throughput during execution",
+      example: 123956.53,
+    },
+    strategyId: {
+      type: "string",
+      description: `**Not the \`strategyId\` you compiled with** — this is the execution context id,
+\`strategy:<user>:<strategyId>\`. The compiled strategy's id is the last \`:\`-separated
+segment; that, not this whole string, is what \`GET /strategy/{strategyId}\` takes.
+
+Take the segment after the last \`:\` rather than counting from the front: the shape has
+changed once already and callers that indexed a fixed position broke on it.
+`,
+      example:
+        "strategy:00000000-0000-0000-0000-000000000000:2iyvtenlzh9dabqtxn7nbv",
+    },
+    instrument: {
+      type: "string",
+      description: "The instrument (currency pair) that was backtested",
+      example: "BTC/USDT",
+    },
+    notices: {
+      type: "array",
+      description: `Diagnostics the engine raised over this run, each with \`provenance: execute\`.
+
+**Absent means nothing was raised.** This is the one surface where silence is a real
+answer: the run happened, over your data, start to finish, and the engine found nothing
+worth saying. That is not true of the compile path, where an empty list only means a
+short synthetic series reached nothing — see \`GET /strategy/{strategyId}\`.
+
+Notices are raised on failed and aborted runs too, and those are the ones most worth
+reading: a run that produced no trades often did so for a reason stated here.
+`,
+      items: {
+        $ref: "#/components/schemas/Notice",
+      },
+    },
+    noticesTruncated: {
+      type: "integer",
+      description:
+        "How many notices were dropped past the cap of 50. Absent when none were. A large value usually means one fault repeating per instrument or per parameter vector rather than 50 distinct problems.",
+      example: 3,
+    },
+    pnlTotal: {
+      type: "number",
+      format: "double",
+      description: "Total profit and loss in the output currency",
+      example: 42.75,
+    },
+    pnlTotalPercent: {
+      type: "number",
+      format: "double",
+      description:
+        "Total PnL as a percentage of the initial capital (`backtestFunding`). Zero when `backtestFunding` is 0.",
+      example: 42.75,
+    },
+    totalTrades: {
+      type: "integer",
+      format: "int64",
+      description: "Total number of trades executed by the strategy",
+      example: 156,
+    },
+    winRate: {
+      type: "number",
+      format: "double",
+      description: "Percentage of profitable trades (0-100)",
+      example: 58.33,
+    },
+    sharpeRatio: {
+      type: "number",
+      format: "double",
+      description:
+        "Risk-adjusted return ratio (mean return / standard deviation of returns)",
+      example: 1.245,
+    },
+    sortinoRatio: {
+      type: "number",
+      format: "double",
+      description:
+        "Downside risk-adjusted return ratio (mean return / downside deviation)",
+      example: 1.872,
+    },
+    cagr: {
+      type: "number",
+      format: "double",
+      description: "Compound Annual Growth Rate",
+      example: 0.1534,
+    },
+    maxDrawdown: {
+      type: "number",
+      format: "double",
+      description: "Maximum absolute drawdown in the output currency",
+      example: 12.5,
+    },
+    maxDrawdownPercent: {
+      type: "number",
+      format: "double",
+      description: "Maximum percentage drawdown from peak equity",
+      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,
         },
-        signalsUpload: {
-            type: 'string',
-            enum: ['Done', 'Failed', 'Skipped'],
-            description: 'Upload status. Done = signal file is available at signalsUrl. Failed = upload error (see signalsUploadReason). Skipped = no signals emitted.',
-            example: 'Done'
+        {
+          timestamp: 1700000060000,
+          equity: 110.5,
         },
-        signalsUploadedAt: {
-            type: 'string',
-            format: 'date-time',
-            description: 'ISO 8601 timestamp of when the upload completed. Only present when signalsUpload is Done.',
-            example: '2026-03-18T13:21:48.170Z'
+        {
+          timestamp: 1700000120000,
+          equity: 90.25,
         },
-        signalsUploadReason: {
-            type: 'string',
-            description: 'Human-readable reason when signalsUpload is Failed or Skipped.',
-            example: 'signal file generation failed'
-        }
-    }
+      ],
+    },
+    signalCount: {
+      type: "integer",
+      description: "Number of signals emitted during strategy execution",
+      example: 100000,
+    },
+    signalsId: {
+      type: "string",
+      description:
+        "Storage key for the signals file. Treat as opaque; use signalsUrl to download.",
+      example:
+        "00000000-0000-0000-0000-000000000000/exec/binance/3vsndwikcuaatjmb83fjtl",
+    },
+    signalsUrl: {
+      type: "string",
+      format: "uri",
+      description:
+        "HTTPS URL to download the signals Parquet file. Use signalsUpload to know when it's ready.",
+      example:
+        "https://storage.qtsurfer.com/00000000-0000-0000-0000-000000000000/exec/binance/3vsndwikcuaatjmb83fjtl.parquet",
+    },
+    signalsUpload: {
+      type: "string",
+      enum: ["Done", "Failed", "Skipped"],
+      description:
+        "Upload status. Done = signal file is available at signalsUrl. Failed = upload error (see signalsUploadReason). Skipped = no signals emitted.",
+      example: "Done",
+    },
+    signalsUploadedAt: {
+      type: "string",
+      format: "date-time",
+      description:
+        "ISO 8601 timestamp of when the upload completed. Only present when signalsUpload is Done.",
+      example: "2026-03-18T13:21:48.170Z",
+    },
+    signalsUploadReason: {
+      type: "string",
+      description:
+        "Human-readable reason when signalsUpload is Failed or Skipped.",
+      example: "signal file generation failed",
+    },
+  },
 } as const;
 
 export const EquityPointSchema = {
-    type: 'object',
-    description: 'Single sample of the running equity at a yield event.',
-    required: ['timestamp', 'equity'],
-    properties: {
-        timestamp: {
-            type: 'integer',
-            format: 'int64',
-            description: 'Epoch milliseconds. The first point in an equity curve is anchored at the backtest `from`; subsequent points carry the timestamp of each emitted yield.',
-            example: 1700000000000
-        },
-        equity: {
-            type: 'number',
-            format: 'double',
-            description: 'Running equity at this point (`initialCapital + cumulativePnl`).',
-            example: 110.5
-        }
-    }
+  type: "object",
+  description: "Single sample of the running equity at a yield event.",
+  required: ["timestamp", "equity"],
+  properties: {
+    timestamp: {
+      type: "integer",
+      format: "int64",
+      description:
+        "Epoch milliseconds. The first point in an equity curve is anchored at the backtest `from`; subsequent points carry the timestamp of each emitted yield.",
+      example: 1700000000000,
+    },
+    equity: {
+      type: "number",
+      format: "double",
+      description:
+        "Running equity at this point (`initialCapital + cumulativePnl`).",
+      example: 110.5,
+    },
+  },
 } as const;
 
 export const strategyIdSchema = {
-    description: 'Unique identifier for a compiled strategy',
-    type: 'string',
-    example: '6bsh31ikwkuivhtgcoa6s4'
+  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
+\`POST /strategy\` for exactly which rewrites preserve it and which do not.
+`,
+  type: "string",
+  example: "6bsh31ikwkuivhtgcoa6s4",
+} as const;
+
+export const NoticeSchema = {
+  type: "object",
+  description: `A diagnostic the engine raised while the strategy ran. Advisory: it describes something worth
+knowing about how the strategy is wired, not necessarily an error.
+`,
+  required: ["level", "code", "message"],
+  properties: {
+    level: {
+      type: "string",
+      description: "Severity as the engine classified it.",
+      example: "WARN",
+    },
+    code: {
+      type: "string",
+      description:
+        "Stable identifier for the kind of finding; safe to match on.",
+      example: "indicator.bar-data-on-ticker-path",
+    },
+    message: {
+      type: "string",
+      description: "Human-readable explanation.",
+      example: "Indicator requires bar data but is on the ticker path",
+    },
+    provenance: {
+      type: "string",
+      enum: ["execute", "compile-dry-run"],
+      description: `Where it came from, which matters because the two silences differ: an empty list from a
+real run (\`execute\`) is a clean bill of health, while an empty list from
+\`compile-dry-run\` is only a lower bound over a bounded synthetic series.
+`,
+      example: "compile-dry-run",
+    },
+  },
+} as const;
+
+export const StrategyStateSchema = {
+  type: "object",
+  description: `What is known about a registered strategy: that it compiled, and what validating it found.
+
+**\`validation: passed\` does not mean the strategy is correct.** It means the class loaded and
+survived the first event of a short synthetic run — a floor, not a guarantee. When
+\`dryRunIncomplete\` is true it is a lower floor still, because the run did not finish.
+`,
+  required: ["strategyId", "validation"],
+  properties: {
+    strategyId: {
+      $ref: "#/components/schemas/strategyId",
+    },
+    validation: {
+      type: "string",
+      enum: ["not_validated", "pending", "passed", "failed"],
+      description: `* \`not_validated\` — registered, never checked. \`POST /strategy/{strategyId}/validate\`
+  checks it.
+* \`pending\` — a check was asked for and has not answered yet.
+* \`passed\` — the class loaded and survived its first event.
+* \`failed\` — it did not; \`detail\` says how.
+`,
+      example: "passed",
+    },
+    compiledAt: {
+      type: "string",
+      format: "date-time",
+      description: "When the live compilation was produced.",
+    },
+    requiredSources: {
+      type: "array",
+      description: `The market data a strategy needs, read off the compiled class rather than off anything
+you sent — \`TickerStrategy\`, \`KlineStrategy\` and \`FundingRateStrategy\` each declare one,
+and a \`MultiSourceStrategy\` declares a set.
+
+**Absent is not "needs nothing".** A strategy always needs market data, so an absent
+field never means an empty requirement — it means the platform could not establish the
+answer without constructing your strategy, which it will not do to fill in a field.
+That happens for a \`MultiSourceStrategy\`, for a class that overrides
+\`getMarketDataSource()\`, and for anything registered before this field existed;
+re-registering the source fills it in.
+`,
+      items: {
+        type: "string",
+        enum: ["Ticker", "KLine", "FundingRate"],
+      },
+      example: ["Ticker"],
+    },
+    validatedAt: {
+      type: "string",
+      format: "date-time",
+      description: "When the verdict was recorded. Absent until there is one.",
+    },
+    detail: {
+      type: "string",
+      description: `Why validation failed, or why a queued check has not reported. Present on \`failed\`, and
+alongside \`validationStalled\`.
+`,
+    },
+    notices: {
+      type: "array",
+      description: `What the run surfaced. An empty or absent list is not a clean bill of health when
+\`dryRunIncomplete\` is true — see that field.
+`,
+      items: {
+        $ref: "#/components/schemas/Notice",
+      },
+    },
+    noticesTruncated: {
+      type: "integer",
+      description:
+        "How many notices were dropped past the cap. Absent when none were.",
+      example: 3,
+    },
+    dryRunIncomplete: {
+      type: "boolean",
+      description: `The check did not finish its budget — it ran out of time, was refused because the
+platform was already holding too many unfinishable runs, or hit a failure attributable to
+the synthetic instrument rather than to your strategy. The verdict stands as far as it
+went; it simply reached less than a full run would.
+`,
+    },
+    validationStalled: {
+      type: "boolean",
+      description: `A queued check has not reported for far longer than one takes. Nothing is disproved about
+the strategy — the check has not run. Stop waiting and re-request it later.
+`,
+    },
+  },
+  example: {
+    strategyId: "6bsh31ikwkuivhtgcoa6s4",
+    validation: "passed",
+    compiledAt: "2026-08-04T16:23:04Z",
+    requiredSources: ["Ticker"],
+    validatedAt: "2026-08-04T16:24:11Z",
+    notices: [
+      {
+        level: "WARN",
+        code: "indicator.bar-data-on-ticker-path",
+        message: "Indicator requires bar data but is on the ticker path",
+        provenance: "compile-dry-run",
+      },
+    ],
+  },
 } as const;
 
 export const AuthTokenResponseSchema = {
-    type: 'object',
-    required: ['access_token', 'token_type', 'expires_in', 'tier'],
-    properties: {
-        access_token: {
-            type: 'string',
-            description: 'Short-lived HS256 JWT. Send as `Authorization: Bearer <token>` on all other endpoints.'
-        },
-        token_type: {
-            type: 'string',
-            enum: ['Bearer'],
-            description: 'Always `Bearer`.'
-        },
-        expires_in: {
-            type: 'integer',
-            description: 'Seconds until the JWT expires (typically 3600).',
-            example: 3600
-        },
-        scopes: {
-            type: 'array',
-            description: 'Scopes granted to this token. Reserved for future use; currently always empty.',
-            items: {
-                type: 'string'
-            },
-            example: []
-        },
-        tier: {
-            type: 'string',
-            enum: ['free', 'basic', 'pro', 'elite'],
-            description: 'Subscription tier this token was issued for. Drives rate limits and feature flags on downstream endpoints.',
-            example: 'free'
-        }
-    }
+  type: "object",
+  required: ["access_token", "token_type", "expires_in", "tier"],
+  properties: {
+    access_token: {
+      type: "string",
+      description:
+        "Short-lived HS256 JWT. Send as `Authorization: Bearer <token>` on all other endpoints.",
+    },
+    token_type: {
+      type: "string",
+      enum: ["Bearer"],
+      description: "Always `Bearer`.",
+    },
+    expires_in: {
+      type: "integer",
+      description: "Seconds until the JWT expires (typically 3600).",
+      example: 3600,
+    },
+    scopes: {
+      type: "array",
+      description:
+        "Scopes granted to this token. Reserved for future use; currently always empty.",
+      items: {
+        type: "string",
+      },
+      example: [],
+    },
+    tier: {
+      type: "string",
+      enum: ["free", "basic", "pro", "elite"],
+      description:
+        "Subscription tier this token was issued for. Drives rate limits and feature flags on downstream endpoints.",
+      example: "free",
+    },
+  },
 } as const;
 
 export const AuthTokenErrorSchema = {
-    type: 'object',
-    required: ['code', 'message'],
-    description: 'Error envelope returned by `POST /auth/token` when the API key is rejected.',
-    properties: {
-        code: {
-            type: 'string',
-            enum: ['invalid_apikey', 'apikey_revoked', 'apikey_expired'],
-            description: 'Machine-readable error reason.'
-        },
-        message: {
-            type: 'string',
-            description: 'Human-readable description of the failure.'
-        }
-    }
-} as const;
+  type: "object",
+  required: ["code", "message"],
+  description:
+    "Error envelope returned by `POST /auth/token` when the API key is rejected.",
+  properties: {
+    code: {
+      type: "string",
+      enum: ["invalid_apikey", "apikey_revoked", "apikey_expired"],
+      description: "Machine-readable error reason.",
+    },
+    message: {
+      type: "string",
+      description: "Human-readable description of the failure.",
+    },
+  },
+} as const;