openapi.yaml

openapi: '3.0.3'
info:
  title: NeuroWealth Backend API
  version: '1.0.0'
  description: |
    NeuroWealth autonomous DeFi portfolio manager backend.

    Authentication: All protected endpoints require a `Bearer <JWT>` token in the
    `Authorization` header, obtained from `POST /api/auth/login`.

servers:
  - url: /api/v1
    description: Versioned API base (alias of /api for current release)
  - url: /api
    description: API base

tags:
  - name: Network
    description: Stellar network fee oracle and congestion (public).
  - name: Analytics
    description: Portfolio performance and risk analytics
  - name: Assistant
    description: |
      Tool-calling conversational assistant (#318). Replaces the rule-based
      NLP parser as the recognition layer for open-ended requests. The model
      never moves money or changes state directly — it may only propose a
      call from a fixed, allowlisted tool registry, and every non-read-only
      tool is dry-run and gated behind an explicit confirmation before it
      executes through the same verified, idempotent, audited service paths
      every other feature uses.
  - name: Agent
    description: Explainable rebalance decisions (#343) — the per-decision rationale ledger.
  - name: Admin
    description: Operational tooling and audit (requires admin-scoped credentials).
  - name: Auth
    description: Authentication and session management
  - name: Portfolio
    description: User portfolio management
  - name: Realtime
    description: |
      Authenticated WebSocket streaming (#316). The handshake below is a real
      HTTP request and is spec'd here so generated clients know how to open it;
      everything after the 101 is the JSON subprotocol described in the
      `WebSocket*` schemas and in docs/WEBSOCKET_STREAMING.md.

# ─── Reusable components ──────────────────────────────────────────────────────
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    # ── Shared primitives ────────────────────────────────────────────────────
    Period:
      type: string
      enum: ['7d', '30d', '90d']
      default: '30d'
      description: Analysis time window. Maximum available history is 90 days.

    InsufficientHistoryFlag:
      type: boolean
      description: |
        True when the available snapshot history is shorter than the requested
        window. Rows/responses with this flag set are excluded from leaderboard
        rankings. Never silently serves a truncated window under the requested label.

    NullableDecimal:
      type: number
      format: double
      nullable: true

    RankedCandidate:
      type: object
      required: [protocol, eligible]
      properties:
        protocol:
          type: string
        apy:
          $ref: '#/components/schemas/NullableDecimal'
        riskScore:
          type: integer
          nullable: true
        eligible:
          type: boolean
        rejectionReason:
          type: string
          nullable: true
          description: null on the chosen protocol; otherwise over_risk_ceiling | risk_score_unknown | lower_apy | lower_target_weight | current_position | etc.

    RebalanceDecision:
      type: object
      properties:
        id:
          type: string
          format: uuid
        correlationId:
          type: string
        batchKey:
          type: string
        fromProtocol:
          type: string
        toProtocol:
          type: string
          nullable: true
        outcome:
          type: string
          enum: [REBALANCED, HELD, BLOCKED]
        blockedReason:
          type: string
          nullable: true
          description: risk_ceiling | below_min_improvement | cost_exceeds_gain | no_candidates
        strategyName:
          type: string
          nullable: true
        strategyIsFollowed:
          type: boolean
        followedStrategyId:
          type: string
          format: uuid
          nullable: true
        thresholds:
          type: object
          properties:
            minimumImprovement:
              type: number
            maxGasPercent:
              type: number
        currentApy:
          $ref: '#/components/schemas/NullableDecimal'
        chosenApy:
          $ref: '#/components/schemas/NullableDecimal'
        rawImprovement:
          $ref: '#/components/schemas/NullableDecimal'
        estCostPercent:
          $ref: '#/components/schemas/NullableDecimal'
        netImprovement:
          $ref: '#/components/schemas/NullableDecimal'
        candidates:
          type: array
          items:
            $ref: '#/components/schemas/RankedCandidate'
        rationale:
          type: string
          nullable: true
        outboxOpId:
          type: string
          format: uuid
          nullable: true
        outboxStatus:
          type: string
          nullable: true
          description: Joined from outbox_ops.status when outboxOpId present.
        heldSince:
          type: string
          format: date-time
          nullable: true
        lastEvaluatedAt:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time

    RebalanceDecisionAdmin:
      allOf:
        - $ref: '#/components/schemas/RebalanceDecision'
        - type: object
          properties:
            affectedUserIds:
              type: array
              items:
                type: string
                format: uuid
            affectedPositions:
              type: integer

    StressScenario:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        description:
          type: string
        shocks:
          type: object
        provenance:
          type: string

    StressResult:
      type: object
      properties:
        scenarioId:
          type: string
        label:
          type: string
        preValueUsd:
          type: number
        postValueUsd:
          type: number
        impactUsd:
          type: number
        impactPct:
          type: number
        perPosition:
          type: array
          items:
            type: object
        modeledRecoveryDays:
          type: integer
          nullable: true
        permanentImpairment:
          type: boolean
        caveat:
          type: string
        asOf:
          type: string
          format: date-time

    # ── Assistant (#318) ─────────────────────────────────────────────────────
    AssistantChatRequest:
      type: object
      required: [message]
      additionalProperties: false
      properties:
        message:
          type: string
          minLength: 1
          maxLength: 2000
        targetUserId:
          type: string
          format: uuid
          description: |
            Act on this linked sub-account instead of the caller's own
            account. Omit (or pass the caller's own id) to act on the
            caller's own account.

    AssistantChatResponse:
      type: object
      required: [reply, usedFallback, pendingConfirmation]
      properties:
        reply:
          type: string
          description: The assistant's reply, ready to display verbatim.
        usedFallback:
          type: boolean
          description: |
            True when the model was unavailable or the token budget was
            exhausted and this reply is a graceful degradation rather than a
            model-generated answer.
        pendingConfirmation:
          type: boolean
          description: |
            True when this reply is a confirmation prompt for a proposed
            action. The caller's next message on the same channel/account
            must be an affirmative or negative reply — it is interpreted as
            the confirmation decision, not a new request.

    # ── Strategy What-If simulation (#344) ────────────────────────────────────
    StrategySimulateRequest:
      type: object
      additionalProperties: false
      properties:
        strategy:
          type: string
          enum: [MAX_YIELD, TARGET_ALLOCATION, GOAL_TRACKING]
          nullable: true
          description: Strategy to simulate. Mutually exclusive with followStrategyId.
        targetAllocations:
          type: object
          additionalProperties:
            type: number
            minimum: 0
            maximum: 100
          description: |
            Protocol name → target weight (%). After config resolution these
            must sum to 100 for TARGET_ALLOCATION, enforced in the service.
        riskCeiling:
          type: integer
          minimum: 0
          maximum: 100
          description: |
            Risk ceiling to simulate. Always clamped to the stricter of the
            caller's own and any applied ceiling.
        followStrategyId:
          type: string
          format: uuid
          nullable: true
          description: |
            Simulate the config of a published strategy to follow. Mutually
            exclusive with the inline strategy/targetAllocations/riskCeiling.
        historyWindowDays:
          type: integer
          minimum: 1
          maximum: 180
          default: 90
          description: Historical replay window; capped at 180 days.
        assumeInitialDeposit:
          type: boolean
          description: |
            When the caller has no active positions, replay a nominal $1000
            instead of zero.

    StrategySimulateResponse:
      type: object
      required: [immediate, historical, simulationToken, asOf, effectiveConfig, dataCaveats, label]
      properties:
        immediate:
          $ref: '#/components/schemas/StrategyImmediateDecision'
        historical:
          $ref: '#/components/schemas/StrategyHistoricalReplay'
        simulationToken:
          type: string
          description: Opaque sha-256 binding the preview to the exact config + window.
        asOf:
          type: string
          format: date-time
        effectiveConfig:
          type: object
          properties:
            strategyName:
              type: string
              enum: [MAX_YIELD, TARGET_ALLOCATION, GOAL_TRACKING]
              nullable: true
            targetAllocations:
              type: object
              additionalProperties:
                type: number
            riskCeiling:
              type: integer
              nullable: true
        dataCaveats:
          type: array
          items:
            type: string
          description: Window-truncation and missing-protocol caveats, never silent.
        label:
          type: string

    StrategyImmediateDecision:
      type: object
      required: [action, targetProtocol, moves, trace, reasoning]
      properties:
        action:
          type: string
          enum: [rebalance, hold, blocked]
        targetProtocol:
          type: string
          nullable: true
        moves:
          type: array
          items:
            type: object
            properties:
              toProtocol:
                type: string
              fraction:
                type: number
        trace:
          type: object
          description: Shape-parity with the persisted DecisionTrace.
        reasoning:
          type: string

    StrategyHistoricalReplay:
      type: object
      required:
        - rebalanceCount
        - turnoverRatio
        - totalFeesPaid
        - endingValue
        - startingValue
        - counterfactualEndingValue
        - finalProtocol
        - timeSeries
        - realizedGainPct
        - counterfactualGainPct
        - dataCaveats
      properties:
        rebalanceCount:
          type: integer
        turnoverRatio:
          type: number
        totalFeesPaid:
          type: string
        endingValue:
          type: string
        startingValue:
          type: string
        counterfactualEndingValue:
          type: string
        finalProtocol:
          type: string
          nullable: true
        timeSeries:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                format: date
              simulatedValue:
                type: string
              counterfactualValue:
                type: string
        realizedGainPct:
          type: number
          nullable: true
        counterfactualGainPct:
          type: number
          nullable: true
        dataCaveats:
          type: array
          items:
            type: string

    # ── Risk metrics ─────────────────────────────────────────────────────────
    RiskMetrics:
      type: object
      description: |
        Computed risk/performance statistics for a portfolio-value series.

        **Null contract**: any metric that is not computable (insufficient samples,
        zero variance, degenerate series) is returned as `null` — never as `0`,
        `Infinity`, or `NaN`.

        **VaR / CVaR estimators**:
        - `varHistorical*` / `cvarHistorical*` — empirical (plain-historical),
          sorts the observed return distribution. Preferred for DeFi portfolios.
        - `varParametric*` — Gaussian assumption (mean + σ). Underestimates tail
          risk for fat-tailed distributions; provided for comparison only.

        All loss magnitudes are **positive numbers** (0.05 = 5% potential loss).
      properties:
        sampleCount:
          type: integer
          description: Number of period-return observations used in all computations.
        annualisedVolatility:
          allOf:
            - $ref: '#/components/schemas/NullableDecimal'
          description: |
            Sample standard deviation of period returns × √(periodsPerYear).
            null if fewer than 2 return observations.
        sortinoRatio:
          allOf:
            - $ref: '#/components/schemas/NullableDecimal'
          description: |
            (Annualised mean return − MAR) / annualised downside deviation.
            null if fewer than 2 observations or downside deviation is 0 (no losses).
        downsideDeviation:
          allOf:
            - $ref: '#/components/schemas/NullableDecimal'
          description: RMS of returns below MAR, annualised. null if no returns.
        maxDrawdown:
          allOf:
            - $ref: '#/components/schemas/NullableDecimal'
          description: |
            Maximum peak-to-trough decline as a positive fraction (0.15 = 15%).
            null if fewer than 2 value points.
        maxDrawdownDuration:
          nullable: true
          type: integer
          description: |
            Number of observation steps from peak to trough in the max drawdown
            episode. null if no drawdown occurred.
        varHistorical95:
          allOf:
            - $ref: '#/components/schemas/NullableDecimal'
          description: Historical VaR at 95% confidence (positive = potential loss).
        varHistorical99:
          allOf:
            - $ref: '#/components/schemas/NullableDecimal'
          description: Historical VaR at 99% confidence.
        varParametric95:
          allOf:
            - $ref: '#/components/schemas/NullableDecimal'
          description: Parametric (Gaussian) VaR at 95% confidence.
        varParametric99:
          allOf:
            - $ref: '#/components/schemas/NullableDecimal'
          description: Parametric (Gaussian) VaR at 99% confidence.
        cvarHistorical95:
          allOf:
            - $ref: '#/components/schemas/NullableDecimal'
          description: Historical CVaR (Expected Shortfall) at 95%.
        cvarHistorical99:
          allOf:
            - $ref: '#/components/schemas/NullableDecimal'
          description: Historical CVaR at 99%.
        beta:
          allOf:
            - $ref: '#/components/schemas/NullableDecimal'
          description: |
            Beta vs an exogenous benchmark series. null when no benchmark is
            provided (benchmark index ingestion is deferred).
        periodsPerYear:
          type: number
          description: |
            Inferred periods-per-year used for annualisation, derived from the
            median inter-observation spacing. Robust to snapshot gaps.
      required:
        - sampleCount
        - periodsPerYear

    PortfolioRiskResponse:
      type: object
      properties:
        userId:
          type: string
          format: uuid
        requestedWindow:
          $ref: '#/components/schemas/Period'
        actualWindowDays:
          type: integer
          description: Days of data actually used (may be shorter than requested).
        insufficientHistory:
          $ref: '#/components/schemas/InsufficientHistoryFlag'
        dataFrom:
          nullable: true
          type: string
          format: date-time
          description: ISO timestamp of the earliest snapshot included.
        dataTo:
          nullable: true
          type: string
          format: date-time
          description: ISO timestamp of the latest snapshot included.
        computedAt:
          type: string
          format: date-time
          description: When these figures were computed (staleness signal).
        source:
          type: string
          enum: ['precomputed', 'live']
          description: Whether the response was served from the precomputed cache.
        metrics:
          allOf:
            - $ref: '#/components/schemas/RiskMetrics'
            - nullable: true
              type: object
          description: null when sampleCount is 0 (entirely un-funded history).
      required:
        - userId
        - requestedWindow
        - actualWindowDays
        - insufficientHistory
        - computedAt
        - source

    RollingVolPoint:
      type: object
      properties:
        timestampMs:
          type: integer
          format: int64
          description: Epoch milliseconds of the last return in this rolling window.
        volatility:
          nullable: true
          type: number
          format: double
          description: Annualised volatility over the window. null if insufficient data.
      required:
        - timestampMs
        - volatility

    DrawdownPoint:
      type: object
      properties:
        timestampMs:
          type: integer
          format: int64
        drawdown:
          type: number
          format: double
          description: Drawdown from the running peak as a positive fraction.
      required:
        - timestampMs
        - drawdown

    TimeseriesResponse:
      type: object
      properties:
        userId:
          type: string
          format: uuid
        requestedWindow:
          $ref: '#/components/schemas/Period'
        insufficientHistory:
          $ref: '#/components/schemas/InsufficientHistoryFlag'
        rollingVolatility:
          type: array
          items:
            $ref: '#/components/schemas/RollingVolPoint'
        drawdown:
          type: array
          items:
            $ref: '#/components/schemas/DrawdownPoint'
        computedAt:
          type: string
          format: date-time
      required:
        - userId
        - requestedWindow
        - insufficientHistory
        - rollingVolatility
        - drawdown
        - computedAt

    ValidationError:
      type: object
      properties:
        error:
          type: string
          example: Validation error
        details:
          type: object
      required:
        - error

    UnauthorizedError:
      type: object
      properties:
        error:
          type: string
          example: Unauthorized
      required:
        - error

    # ── Real-time WebSocket subprotocol (#316) ───────────────────────────────
    #
    # These are not request/response bodies: they are the JSON frames exchanged
    # over the socket opened by `GET /ws`. They live in the spec so client
    # generators and reviewers have one authoritative shape per frame.

    WebSocketTopic:
      type: string
      enum: [portfolio, transactions, agent, alerts, strategies]
      description: |
        Subscription, ordering, and permission unit.

        **Ordering**: within a topic, events arrive in ascending `seq`. Across
        topics there is NO ordering guarantee — all topics share one per-user
        sequence, so use `seq` rather than arrival order. On-chain events
        inherit ProcessedEvent's ledger ordering upstream.

    WebSocketSubscribe:
      type: object
      description: Client → server. Start live delivery for the given topics.
      required: [type, topics]
      additionalProperties: false
      properties:
        type:
          type: string
          enum: [subscribe]
        topics:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/WebSocketTopic'
        coalesce:
          type: boolean
          default: false
          description: |
            Opt into latest-wins coalescing of same-type bursts within a short
            window (WS_COALESCE_WINDOW_MS). Suppressed events remain in the
            durable stream but are NOT redelivered by a later `resume`, because
            `afterSeq` has already moved past them. Off by default.

    WebSocketResume:
      type: object
      description: |
        Client → server. Replay everything after `afterSeq`, then switch to live.
        Send this on every reconnect.
      required: [type, topics, afterSeq]
      additionalProperties: false
      properties:
        type:
          type: string
          enum: [resume]
        topics:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/WebSocketTopic'
        afterSeq:
          type: integer
          minimum: 0
          description: Last `seq` the client durably processed. 0 replays everything retained.
        coalesce:
          type: boolean
          default: false

    WebSocketUnsubscribe:
      type: object
      description: Client → server. Stop delivery for the given topics.
      required: [type, topics]
      additionalProperties: false
      properties:
        type:
          type: string
          enum: [unsubscribe]
        topics:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/WebSocketTopic'

    WebSocketPing:
      type: object
      description: |
        Client → server. Application-level keepalive, answered with `pong`. Only
        needed by clients that cannot observe protocol-level pongs (browsers);
        the server pings every `heartbeatIntervalMs` regardless.
      required: [type]
      additionalProperties: false
      properties:
        type:
          type: string
          enum: [ping]

    WebSocketClientMessage:
      description: |
        Every message a client may send. The receive side is a control channel
        only — v1 is server→client for data. State-changing operations stay on
        the REST surface, which has the validation, idempotency, and audit trail
        a socket does not.
      oneOf:
        - $ref: '#/components/schemas/WebSocketSubscribe'
        - $ref: '#/components/schemas/WebSocketResume'
        - $ref: '#/components/schemas/WebSocketUnsubscribe'
        - $ref: '#/components/schemas/WebSocketPing'

    WebSocketHello:
      type: object
      description: Server → client. First frame after a successful handshake.
      required: [type, actor, topics, currentSeq, heartbeatIntervalMs]
      properties:
        type:
          type: string
          enum: [hello]
        actor:
          type: string
          enum: [self, delegated]
          description: |
            `delegated` when the connection was opened with `?actor=<userId>`
            and an ACTIVE sub-account grant authorised it.
        topics:
          type: array
          description: Topics this connection may subscribe to, derived server-side.
          items:
            $ref: '#/components/schemas/WebSocketTopic'
        currentSeq:
          type: integer
          description: Newest `seq` on the bound stream right now.
        heartbeatIntervalMs:
          type: integer

    WebSocketSubscribed:
      type: object
      description: Server → client. Acknowledges the active subscription set.
      required: [type, topics, currentSeq, coalesce]
      properties:
        type:
          type: string
          enum: [subscribed]
        topics:
          type: array
          items:
            $ref: '#/components/schemas/WebSocketTopic'
        currentSeq:
          type: integer
        coalesce:
          type: boolean

    WebSocketEvent:
      type: object
      description: |
        Server → client. One domain event.

        **Delivery is at-least-once.** A `resume` replays from the durable store
        while live events keep arriving, and the live-switch prefers a duplicate
        over a hole. Dedupe on `seq`, which is monotonic per user.

        **Payloads are allowlisted per event type** by the same discipline as
        REST responses (src/utils/api-formatters.ts). No `userId`, wallet
        address, key, or internal field appears here.
      required: [type, seq, topic, event, payload, emittedAt]
      properties:
        type:
          type: string
          enum: [event]
        seq:
          type: integer
          description: Monotonic per-user sequence number. Track the highest you processed.
        topic:
          $ref: '#/components/schemas/WebSocketTopic'
        event:
          type: string
          description: Domain event type, e.g. `deposit.received`.
          example: deposit.received
        payload:
          type: object
          additionalProperties: true
        emittedAt:
          type: string
          format: date-time

    WebSocketReplay:
      type: object
      description: Server → client. Brackets the replay served for a `resume`.
      required: [type, status, fromSeq, toSeq, count]
      properties:
        type:
          type: string
          enum: [replay]
        status:
          type: string
          enum: [start, end]
        fromSeq:
          type: integer
        toSeq:
          type: integer
        count:
          type: integer

    WebSocketGap:
      type: object
      description: |
        Server → client. The stream could not be served continuously.

        * `retention` — the requested `afterSeq` is older than what is retained,
          or a single replay hit its page limit with history still to come.
        * `backpressure` — the client was too slow; delivery stopped at
          `afterSeq`. Nothing is lost; `resume` from there.
        * `unknown_stream` — the requested `afterSeq` is ahead of the server.

        When `snapshotRequired` is true, replay cannot close the gap: fetch a
        REST snapshot (`/portfolio`, `/transactions`, …) and then `subscribe`.
      required:
        [
          type,
          reason,
          afterSeq,
          currentSeq,
          oldestAvailableSeq,
          snapshotRequired,
        ]
      properties:
        type:
          type: string
          enum: [gap]
        reason:
          type: string
          enum: [retention, backpressure, unknown_stream]
        afterSeq:
          type: integer
          nullable: true
        currentSeq:
          type: integer
        oldestAvailableSeq:
          type: integer
          nullable: true
        snapshotRequired:
          type: boolean

    WebSocketError:
      type: object
      description: |
        Server → client. `forbidden` mirrors REST 403 semantics — a topic the
        connection's grant does not cover. `unauthorized` precedes a close with
        code 4408 when the session is revoked mid-connection.
      required: [type, code, message]
      properties:
        type:
          type: string
          enum: [error]
        code:
          type: string
          enum: [bad_request, forbidden, unauthorized, rate_limited, internal]
        message:
          type: string

    WebSocketDraining:
      type: object
      description: |
        Server → client. Sent before a graceful shutdown closes the socket with
        code 1001. Reconnect after `retryAfterMs` and `resume` from
        `resumeAfterSeq`.
      required: [type, reason, resumeAfterSeq, retryAfterMs]
      properties:
        type:
          type: string
          enum: [draining]
        reason:
          type: string
          enum: [server_shutdown]
        resumeAfterSeq:
          type: integer
        retryAfterMs:
          type: integer

    WebSocketPong:
      type: object
      description: Server → client. Reply to an application-level `ping`.
      required: [type, at]
      properties:
        type:
          type: string
          enum: [pong]
        at:
          type: string
          format: date-time

    WebSocketServerFrame:
      description: Every frame the server may send.
      oneOf:
        - $ref: '#/components/schemas/WebSocketHello'
        - $ref: '#/components/schemas/WebSocketSubscribed'
        - $ref: '#/components/schemas/WebSocketEvent'
        - $ref: '#/components/schemas/WebSocketReplay'
        - $ref: '#/components/schemas/WebSocketGap'
        - $ref: '#/components/schemas/WebSocketError'
        - $ref: '#/components/schemas/WebSocketDraining'
        - $ref: '#/components/schemas/WebSocketPong'

  responses:
    Unauthorized:
      description: Missing or invalid JWT.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'

# ─── Paths ────────────────────────────────────────────────────────────────────
paths:

  # ── Assistant endpoints (#318) ────────────────────────────────────────────────

  /assistant/chat:
    post:
      operationId: assistantChat
      summary: Send a message to the tool-calling assistant
      description: |
        Sends one message to the conversational assistant and returns its
        reply. The assistant may read live account data to ground its answer,
        or propose an action (deposit, withdraw, rebalance, adjust strategy,
        follow/unfollow a marketplace strategy, create a recurring deposit,
        create an alert rule) — action proposals are always previewed
        (dry-run) and returned as a confirmation prompt; the SAME action only
        executes once the caller's next message is an affirmative reply
        (`pendingConfirmation: true` on this response). A negative reply
        cancels it; anything else re-prompts without executing or dropping
        the pending action.

        **Sub-accounts**: pass `targetUserId` to act on a linked child
        account. The caller must hold an ACTIVE `SubAccount` link with the
        permission the specific proposed tool requires (same enforcement as
        `src/middleware/subAccount.ts`); a caller with no link, or the wrong
        permission, gets `403` before the message even reaches the model.

        **Degradation**: if the model is unavailable or the caller's token
        budget is exhausted, this still returns `200` with a graceful reply
        and `usedFallback: true` — never a `5xx` or a hang.
      tags: [Assistant]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistantChatRequest'
            examples:
              read_only:
                summary: Open-ended read request
                value:
                  message: "what's my portfolio worth right now?"
              action_proposal:
                summary: A request that proposes an action
                value:
                  message: "withdraw 50 USDC"
              sub_account:
                summary: Acting on a linked sub-account
                value:
                  message: "what's the balance on my kid's account?"
                  targetUserId: "3f8e1c2a-4b5d-6e7f-8a9b-0c1d2e3f4a5b"
      responses:
        '200':
          description: The assistant's reply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantChatResponse'
              examples:
                grounded_answer:
                  summary: Grounded read-only answer
                  value:
                    reply: "Your portfolio is currently worth 150.00 USDC."
                    usedFallback: false
                    pendingConfirmation: false
                confirmation_prompt:
                  summary: Action proposed — awaiting confirmation
                  value:
                    reply: 'I''d like to: *Withdraw 50 USDC*. Reply "yes" to confirm or "no" to cancel.'
                    usedFallback: false
                    pendingConfirmation: true
                degraded:
                  summary: Model unavailable — graceful fallback
                  value:
                    reply: "I'm having trouble understanding requests like that right now. Please try a specific command (e.g. \"balance\", \"deposit 10\"), or try again shortly."
                    usedFallback: true
                    pendingConfirmation: false
        '400':
          description: Validation failed (empty/oversized message, malformed targetUserId).
        '401':
          description: Missing/invalid bearer token, or no permission on the requested sub-account.

  # ── Strategy What-If simulation (#344) ─────────────────────────────────────

  /strategies/simulate:
    post:
      operationId: simulateStrategy
      summary: Dry-run a hypothetical strategy change (what-if)
      description: |
        Simulates a hypothetical strategy config on the caller's current
        positions and public `ProtocolRate` history without applying it. Pure
        read — **zero side effects** (no outbox/event/log/transaction/DB write).

        Returns two legs:
          * `immediate` — what the agent would do right now (`rebalance` /
            `hold` / `blocked`) plus a `trace` shape-parity with the persisted
            `DecisionTrace`.
          * `historical` — a non-compounding daily replay over retained history,
            side-by-side with a counterfactual "held in the starting protocol"
            leg; rebalances subtract the live `estimateRebalanceCost`.

        Resolution precedence: followed config (current follow or
        `followStrategyId`) → submitted inline config → the caller's own config.
        The effective risk ceiling is always the stricter of the caller's and
        any applied ceiling. `followStrategyId` is mutually exclusive with an
        inline `strategy`/`targetAllocations`/`riskCeiling`.
      tags: [Strategy]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StrategySimulateRequest'
            examples:
              what_if:
                summary: Inline what-if
                value:
                  strategy: MAX_YIELD
                  riskCeiling: 70
                  historyWindowDays: 90
              follow_target:
                summary: Simulate the config of a followed strategy
                value:
                  followStrategyId: cccccccc-cccc-4ccc-8ccc-cccccccccccc
      responses:
        '200':
          description: The what-if preview.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StrategySimulateResponse'
        '400':
          description: SimulationValidationError (weights do not sum to 100, GOAL_TRACKING without an active goal, window over cap, follow/inline conflict).
        '401':
          description: Missing/invalid bearer token.
        '404':
          description: SimulationNotFoundError (unknown owner or unpublished follow target).
        '429':
          description: Rate limited (simulateRateLimiter, 6 req/min).

  # ── Risk endpoints ───────────────────────────────────────────────────────────

  /analytics/risk:
    get:
      operationId: getPortfolioRisk
      summary: Portfolio risk metrics
      description: |
        Returns VaR (95%/99%, historical and parametric), CVaR (95%/99%,
        historical), Sortino ratio, downside deviation, max drawdown (+duration),
        and annualised volatility for the authenticated user's portfolio.

        **Ownership**: `userId` is taken from the JWT payload — you cannot read
        another user's risk data via this endpoint.

        **Retention boundary**: YieldSnapshot rows are hard-deleted after 90 days
        by the snapshotter. Windows longer than the available history are
        relabelled with `insufficientHistory: true` and `actualWindowDays` set to
        the honest available span — never silently truncated.

        **Caching**: If a precomputed row < 1 hour old exists, it is returned
        directly (`source: "precomputed"`). Otherwise a live compute is performed
        (`source: "live"`).

        **Null contract**: metrics that cannot be computed return `null`, never
        `0`, `Infinity`, or `NaN`.
      tags: [Analytics]
      security:
        - bearerAuth: []
      parameters:
        - name: window
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Period'
          description: Analysis time window.
      responses:
        '200':
          description: Risk metrics for the authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortfolioRiskResponse'
              examples:
                sufficient_history:
                  summary: User with 30d of data
                  value:
                    userId: '3f8e1c2a-4b5d-6e7f-8a9b-0c1d2e3f4a5b'
                    requestedWindow: '30d'
                    actualWindowDays: 30
                    insufficientHistory: false
                    dataFrom: '2026-07-21T00:00:00.000Z'
                    dataTo: '2026-08-20T00:00:00.000Z'
                    computedAt: '2026-08-20T12:00:00.000Z'
                    source: 'precomputed'
                    metrics:
                      sampleCount: 720
                      annualisedVolatility: 0.12
                      sortinoRatio: 1.85
                      downsideDeviation: 0.045
                      maxDrawdown: 0.08
                      maxDrawdownDuration: 14
                      varHistorical95: 0.031
                      varHistorical99: 0.065
                      varParametric95: 0.028
                      varParametric99: 0.044
                      cvarHistorical95: 0.052
                      cvarHistorical99: 0.078
                      beta: null
                      periodsPerYear: 8760
                insufficient_history:
                  summary: New user with < 7d data requesting 30d
                  value:
                    userId: '3f8e1c2a-4b5d-6e7f-8a9b-0c1d2e3f4a5b'
                    requestedWindow: '30d'
                    actualWindowDays: 3
                    insufficientHistory: true
                    dataFrom: '2026-08-17T00:00:00.000Z'
                    dataTo: '2026-08-20T00:00:00.000Z'
                    computedAt: '2026-08-20T12:00:00.000Z'
                    source: 'live'
                    metrics: null
        '400':
          description: Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Missing or invalid JWT.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '500':
          description: Internal server error.

  /analytics/risk/timeseries:
    get:
      operationId: getPortfolioRiskTimeseries
      summary: Portfolio risk timeseries (rolling volatility + drawdown)
      description: |
        Returns graph-ready rolling annualised volatility and running-peak
        drawdown series for the authenticated user's portfolio.

        **Ownership**: `userId` is taken from the JWT payload.

        **Null in rolling volatility**: points with fewer observations than
        `rollingWindow` have `volatility: null`.
      tags: [Analytics]
      security:
        - bearerAuth: []
      parameters:
        - name: window
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Period'
        - name: rollingWindow
          in: query
          required: false
          schema:
            type: integer
            minimum: 2
            maximum: 30
            default: 7
          description: Number of observations per rolling volatility window.
      responses:
        '200':
          description: Timeseries data for the authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeseriesResponse'
        '400':
          description: Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Missing or invalid JWT.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '500':
          description: Internal server error.

  # ── Existing analytics endpoints ─────────────────────────────────────────────

  /analytics/correlation:
    get:
      operationId: getPortfolioCorrelation
      summary: Portfolio APY correlation matrix and diversification score
      description: |
        Returns the per-protocol APY correlation matrix and a weighted
        diversification score for the authenticated user's portfolio (#348).

        Correlation is computed from historical quoted APY levels
        (`ProtocolRate.supplyApy`), aligned to common days — it measures how
        synchronously protocols' yields have moved, NOT asset-price correlation,
        and does not model principal loss, depeg, or smart-contract failure. The
        `caveat` field ships with every response.

        `correlation[i][j]` is in [-1, 1]; degenerate (constant) series yield
        `null` rather than 0. The diversification score is 0-100 (higher = more
        diversified), `null` when fewer than 2 protocols have history.
      tags: [Analytics]
      security:
        - bearerAuth: []
      parameters:
        - name: window
          in: query
          required: false
          schema:
            type: string
            enum: [30d, 60d, 90d]
            default: 90d
      responses:
        '200':
          description: Correlation matrix and diversification score.
          content:
            application/json:
              schema:
                type: object
                properties:
                  userId:
                    type: string
                    format: uuid
                  window:
                    type: string
                  computed:
                    type: boolean
                  observationCount:
                    type: integer
                  protocols:
                    type: array
                    items:
                      type: string
                  correlation:
                    type: array
                    items:
                      type: array
                      items:
                        type: number
                        nullable: true
                  averageCorrelation:
                    type: number
                    nullable: true
                  diversificationScore:
                    type: number
                    nullable: true
                  caveat:
                    type: string
        '400':
          description: Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /analytics/factor-exposure:
    get:
      operationId: getFactorExposure
      summary: Rolling beta and market-factor exposure report
      description: |
        Measures how much of the authenticated user's yield movement is
        explained by the DeFi-yield "market factor" versus idiosyncratic
        protocol selection, on a rolling window so exposure can be seen
        changing over time (#352).

        The market is the canonical equal/TVL-weighted average of tracked
        `ProtocolRate` APY series (`src/analytics/benchmark.ts`). Each window
        regresses portfolio daily return on market daily return (OLS): a beta
        of ~1 means "your yield moves with the tracked-protocol market", ~0
        means "independent of it".

        This is YIELD co-movement, NOT price beta, and the market is not a
        traded index — the fixed `caveats[0]` states this on every response.
        Under-sampled (< 14 aligned days) or zero-market-variance windows
        report `null` beta/R², never 0 or NaN. Series are intersected on a
        shared daily grid (never zero-filled); mismatched days are dropped and
        `sampleCount` reflects the intersection.

        Retention is bounded at 90 days and `rollingWindow` must be shorter
        than `window`; a rolling window that leaves fewer than 2 windows
        returns the summary only, with a caveat. `inputHash` (sha256 of the
        sorted input snapshot) lets the report be reproduced deterministically.
      tags: [Analytics]
      security:
        - bearerAuth: []
      parameters:
        - name: window
          in: query
          required: false
          schema:
            type: string
            enum: [30d, 60d, 90d]
            default: 90d
        - name: rollingWindow
          in: query
          required: false
          schema:
            type: string
            enum: [7d, 14d, 30d]
            default: 30d
        - name: weighting
          in: query
          required: false
          schema:
            type: string
            enum: [equal, tvl]
            default: equal
      responses:
        '200':
          description: Rolling beta and market-factor exposure report.
          content:
            application/json:
              schema:
                type: object
                properties:
                  userId:
                    type: string
                    format: uuid
                  window:
                    type: string
                  rollingWindow:
                    type: string
                  weighting:
                    type: string
                    enum: [equal, tvl]
                  actualWindowDays:
                    type: integer
                  insufficientHistory:
                    type: boolean
                  sampleCount:
                    type: integer
                  rolling:
                    type: array
                    items:
                      type: object
                      properties:
                        windowEndMs:
                          type: integer
                        sampleCount:
                          type: integer
                        beta:
                          type: number
                          nullable: true
                        alpha:
                          type: number
                          nullable: true
                        alphaAnnualized:
                          type: number
                          nullable: true
                        rSquared:
                          type: number
                          nullable: true
                        idiosyncraticVolShare:
                          type: number
                          nullable: true
                  summary:
                    type: object
                    nullable: true
                    properties:
                      sampleCount:
                        type: integer
                      beta:
                        type: number
                        nullable: true
                      alpha:
                        type: number
                        nullable: true
                      alphaAnnualized:
                        type: number
                        nullable: true
                      rSquared:
                        type: number
                        nullable: true
                      idiosyncraticVolShare:
                        type: number
                        nullable: true
                  benchmark:
                    type: object
                    properties:
                      weighting:
                        type: string
                        enum: [equal, tvl]
                      universeSize:
                        type: integer
                      tvlFallback:
                        type: boolean
                  caveats:
                    type: array
                    items:
                      type: string
                  inputHash:
                    type: string
                  computedAt:
                    type: string
                    format: date-time
        '400':
          description: Invalid query parameters (e.g. rollingWindow >= window).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /analytics/yield-breakdown:
    get:
      operationId: getYieldBreakdown
      summary: Yield base/incentive composition and effective APY
      description: |
        Returns the base (market) vs incentive (token-reward) split, incentive
        share, and haircuted effective APY for the authenticated user's held
        protocols (all protocols when they hold none) (#349).

        Effective APY = base + incentive × (1 − INCENTIVE_HAIRCUT); protocols
        with no decomposition fall back to the raw quoted supply APY. The
        `caveat` travels with every response, and `effectiveApyEnabled` reports
        whether `USE_EFFECTIVE_APY=true` is gating optimizer/agent consumption.
      tags: [Analytics]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Yield composition per held protocol.
          content:
            application/json:
              schema:
                type: object
                properties:
                  userId:
                    type: string
                    format: uuid
                  effectiveApyEnabled:
                    type: boolean
                  caveat:
                    type: string
                  protocols:
                    type: array
                    items:
                      type: object
                      properties:
                        protocol:
                          type: string
                        asset:
                          type: string
                        network:
                          type: string
                        supplyApy:
                          type: number
                        baseApy:
                          type: number
                          nullable: true
                        incentiveApy:
                          type: number
                          nullable: true
                        incentiveShare:
                          type: number
                          nullable: true
                        effectiveApy:
                          type: number
                        rewardTokens:
                          type: array
                          nullable: true
                          items:
                            type: object
                            properties:
                              symbol:
                                type: string
                              address:
                                type: string
                              apy:
                                type: number
        '401':
          $ref: '#/components/responses/Unauthorized'

  /analytics/apy-history:
    get:
      operationId: getApyHistory
      summary: APY snapshot history
      description: |
        Returns APY snapshots over time for the authenticated user's positions.
        Graph-ready (sorted ascending by date).
      tags: [Analytics]
      security:
        - bearerAuth: []
      parameters:
        - name: period
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Period'
      responses:
        '200':
          description: APY history points.
          content:
            application/json:
              schema:
                type: object
                properties:
                  userId:
                    type: string
                    format: uuid
                  period:
                    $ref: '#/components/schemas/Period'
                  points:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          format: date
                        apy:
                          type: number
                        positionId:
                          type: string
        '401':
          $ref: '#/components/responses/Unauthorized'

  /analytics/user-yield:
    get:
      operationId: getUserYield
      summary: User yield summary
      description: Returns cumulative and period yield earned by the authenticated user.
      tags: [Analytics]
      security:
        - bearerAuth: []
      parameters:
        - name: period
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Period'
      responses:
        '200':
          description: Yield summary.
          content:
            application/json:
              schema:
                type: object
                properties:
                  userId:
                    type: string
                    format: uuid
                  period:
                    $ref: '#/components/schemas/Period'
                  totalYield:
                    type: number
                  periodYield:
                    type: number
                  averageApy:
                    type: number
                  points:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'

  /analytics/user-yield/export:
    get:
      operationId: exportUserYield
      summary: User yield summary (CSV export)
      description: |
        Same data as GET /analytics/user-yield, as a downloadable CSV — one
        row per yield snapshot point, with the period totals repeated on
        every row (#405).
      tags: [Analytics]
      security:
        - bearerAuth: []
      parameters:
        - name: period
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Period'
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [csv]
            default: csv
      responses:
        '200':
          description: CSV file.
          content:
            text/csv:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'

  /analytics/protocol-performance:
    get:
      operationId: getProtocolPerformance
      summary: Protocol APY history
      description: Returns historical APY rates per protocol. Public endpoint (no auth required).
      tags: [Analytics]
      security: []
      parameters:
        - name: period
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Period'
      responses:
        '200':
          description: Protocol APY history grouped by protocol.
          content:
            application/json:
              schema:
                type: object
                properties:
                  period:
                    $ref: '#/components/schemas/Period'
                  protocols:
                    type: array
                    items:
                      type: object

  # ── Agent decisions (#343) ────────────────────────────────────────────────────

  /agent/decisions:
    get:
      operationId: listAgentDecisions
      summary: List own rebalance decisions
      description: |
        Owner-scoped decision listing for the per-decision rationale ledger (#343).
        Visible iff the caller is in `affectedUserIds`; the response is projected
        to that user's view (no sibling `affectedUserIds`, no other user's position
        sizes). The decision is the batch evaluation that the agent loop ran for
        `protocol:strategy:followId` — REBALANCED, HELD, or BLOCKED — with the
        snapshotted thresholds, the APY inputs, the ranked candidates and their
        per-candidate rejection reasons, and — when the decision linked an
        `outboxOpId` — its current outbox `status` so the UI can explain
        “decided to rebalance → on-chain submission failed”.

        **Real-time counterpart**: every new decision row emits `agent.decision_recorded`
        on the same users' streams (seq-ordered, replayable).
      tags: [Agent]
      security:
        - bearerAuth: []
      parameters:
        - name: outcome
          in: query
          required: false
          schema:
            type: string
            enum: [REBALANCED, HELD, BLOCKED]
        - name: fromProtocol
          in: query
          required: false
          schema:
            type: string
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Inclusive lower bound on `createdAt`.
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Inclusive upper bound on `createdAt`.
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
      responses:
        '200':
          description: Paginated decision listing (user-projected).
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: integer
                  limit:
                    type: integer
                  total:
                    type: integer
                  decisions:
                    type: array
                    items:
                      $ref: '#/components/schemas/RebalanceDecision'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /agent/decisions/{id}:
    get:
      operationId: getAgentDecision
      summary: Get one rebalance decision (full trace)
      description: |
        Full trace for a single decision, including the ranked `candidates`.
        Visible iff the caller is in `affectedUserIds`; otherwise 404.
      tags: [Agent]
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Full decision trace (user-projected).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RebalanceDecision'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Decision not found or not visible to caller.

  /admin/agent/decisions:
    get:
      operationId: listAdminAgentDecisions
      summary: Admin — list all rebalance decisions
      description: |
        Unrestricted, admin-scoped decision listing for support/audit.
        Requires `read` admin scope; every call is written to `AdminAuditLog`
        as `LIST_AGENT_DECISIONS`.
      tags: [Admin]
      security:
        - bearerAuth: []
      parameters:
        - name: outcome
          in: query
          required: false
          schema:
            type: string
            enum: [REBALANCED, HELD, BLOCKED]
        - name: fromProtocol
          in: query
          required: false
          schema:
            type: string
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - name: correlationId
          in: query
          required: false
          schema:
            type: string
        - name: batchKey
          in: query
          required: false
          schema:
            type: string
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
      responses:
        '200':
          description: Paginated decision listing (admin — includes affectedUserIds).
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: integer
                  limit:
                    type: integer
                  total:
                    type: integer
                  decisions:
                    type: array
                    items:
                      $ref: '#/components/schemas/RebalanceDecisionAdmin'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Missing or insufficient admin scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'

  # ── Network conditions (#342) ─────────────────────────────────────────────────

  /network/conditions:
    get:
      operationId: getNetworkConditions
      summary: Current network fee and congestion snapshot
      description: |
        Adaptive base-fee oracle snapshot (#342) — recommended base fee (p70),
        aggressive base fee (p95), congestion level with hysteresis, ledger
        capacity usage, plus per-priority ETA bands derived from recent
        outbox latency percentiles. Public, rate-limited.
      tags: [Network]
      security: []
      responses:
        '200':
          description: Fee snapshot + ETA bands.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      recommendedBaseFee:
                        type: integer
                      aggressiveBaseFee:
                        type: integer
                      congestionLevel:
                        type: string
                        enum: [low, elevated, high, severe]
                      ledgerCapacityUsage:
                        type: number
                      sampledAt:
                        type: string
                        format: date-time
                      ttlMs:
                        type: integer
                      stale:
                        type: boolean
                      etaBands:
                        type: object
                        properties:
                          LOW:
                            type: object
                            properties:
                              minSeconds:
                                type: integer
                              maxSeconds:
                                type: integer
                          NORMAL:
                            type: object
                            properties:
                              minSeconds:
                                type: integer
                              maxSeconds:
                                type: integer
                          CRITICAL:
                            type: object
                            properties:
                              minSeconds:
                                type: integer
                              maxSeconds:
                                type: integer

  # ── Stress testing (#351) ─────────────────────────────────────────────────────

  /analytics/stress/scenarios:
    get:
      operationId: getStressScenarios
      summary: List built-in stress scenarios
      tags: [Analytics]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Scenario library.
          content:
            application/json:
              schema:
                type: object
                properties:
                  scenarios:
                    type: array
                    items:
                      $ref: '#/components/schemas/StressScenario'
                  caveat:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'

  /analytics/stress:
    post:
      operationId: runStressTest
      summary: Run scenario stress test on current portfolio
      tags: [Analytics]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                scenarioId:
                  type: string
                  example: stablecoin_depeg_2022
                custom:
                  type: object
                  properties:
                    assetPriceShockPct:
                      type: object
                      additionalProperties:
                        type: number
                    apyShockPct:
                      oneOf:
                        - type: number
                        - type: object
                          additionalProperties:
                            type: number
                    incentiveApyToZero:
                      type: boolean
                    protocolLossPct:
                      type: object
                      additionalProperties:
                        type: number
                    recoveryDays:
                      type: integer
                runAll:
                  type: boolean
                asOf:
                  type: string
                  format: date-time
      responses:
        '200':
          description: Stress result (or ranked runAll).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StressResult'
        '400':
          $ref: '#/components/responses/Unauthorized'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ── Real-time WebSocket stream (#316) ─────────────────────────────────────────

  /ws:
    get:
      operationId: openRealtimeStream
      summary: Open the authenticated real-time event stream
      description: |
        Upgrades to a WebSocket carrying this user's live, sequence-numbered
        event stream. Not a REST endpoint: the only HTTP response a client
        should ever see is a rejection — success is a `101 Switching Protocols`
        followed by the JSON subprotocol below.

        Full client contract, including reconnect policy and worked examples:
        `docs/WEBSOCKET_STREAMING.md`.

        ### Authentication
        The same JWT + live-session check the REST middleware performs, run
        BEFORE the protocol switch — an unauthenticated peer gets a 401 and
        never becomes a WebSocket. There is no anonymous channel.

        Send the token either as `Authorization: Bearer <jwt>` (server-side
        clients) or as the subprotocol pair `Sec-WebSocket-Protocol: bearer,
        <jwt>` (browsers, which cannot set headers on a WebSocket). A `?token=`
        query parameter is deliberately NOT accepted: URLs reach access logs,
        proxy logs, and referrers, and this token is a live session.

        A session revoked while the socket is open closes it with code 4408 —
        the server rechecks the session periodically rather than trusting the
        handshake forever.

        ### Message flow
        1. Server sends `hello` with the topics you may read and `currentSeq`.
        2. Client sends `subscribe` (live from now) or `resume` (replay first).
        3. Server sends `event` frames; each carries a monotonic per-user `seq`.
        4. On reconnect, client sends `resume` with the highest `seq` it
           durably processed. Missed events replay, then live resumes.

        ### Delivery guarantees
        At-least-once, with a duplication window around a reconnect — dedupe on
        `seq`. Within a topic, events are ordered; across topics they are not.

        ### Heartbeat and idle policy
        The server pings every `heartbeatIntervalMs` (default 30s). A connection
        that neither pongs nor sends a frame for `WS_IDLE_TIMEOUT_MS` (default
        90s) is closed with code 4408. Clients that cannot observe protocol
        pongs may send `{"type":"ping"}` instead.

        ### Backpressure
        A slow consumer is never buffered without bound. Past the per-connection
        bound the server stops delivering, sends one `gap` frame with reason
        `backpressure`, and waits for a `resume`. Nothing is lost — the durable
        stream still holds every event.

        ### Limits
        Handshakes are rate-limited per source IP (`429` on the upgrade), client
        messages per connection (`rate_limited` error frame, then close 4429),
        and each user may hold `WS_MAX_CONNECTIONS_PER_USER` sockets per pod.

        ### Close codes
        | Code | Meaning |
        |------|---------|
        | 1000 | Normal closure |
        | 1001 | Server draining (preceded by a `draining` frame) |
        | 4401 | Unauthenticated |
        | 4403 | Actor not permitted |
        | 4408 | Session revoked, or idle timeout |
        | 4429 | Message rate limit exceeded |
      tags: [Realtime]
      security:
        - bearerAuth: []
      parameters:
        - name: actor
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: |
            Bind the connection to a sub-account's stream instead of your own.
            The ACTIVE `SubAccount` grant is verified server-side and its
            permissions decide the readable topics (`VIEW` → portfolio,
            transactions, agent, alerts; `MANAGE_STRATEGY` → strategies).
            Same enforcement as the REST `actingAsUserId` routes; the client's
            opinion about its own scope is never consulted.
        - name: Sec-WebSocket-Protocol
          in: header
          required: false
          schema:
            type: string
            example: bearer, eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
          description: Browser alternative to the Authorization header.
      requestBody:
        required: false
        description: |
          Not an HTTP body — documents the frames the client sends over the
          socket after the upgrade.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebSocketClientMessage'
      responses:
        '101':
          description: |
            Protocol switched. Every subsequent server frame is one of
            `WebSocketServerFrame`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebSocketServerFrame'
        '401':
          description: Missing, malformed, expired, or revoked credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: No ACTIVE sub-account grant for the requested `actor`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '429':
          description: Handshake rate limit, or too many concurrent connections.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'

  # ── Health ────────────────────────────────────────────────────────────────────

  /health/live:
    get:
      operationId: getLiveness
      summary: Liveness probe
      description: Always returns 200 once the process is running.
      tags: [Health]
      security: []
      responses:
        '200':
          description: Process alive.

  /health/ready:
    get:
      operationId: getReadiness
      summary: Readiness probe
      description: Returns 200 only when all background services are healthy.
      tags: [Health]
      security: []
      responses:
        '200':
          description: All services ready.
        '503':
          description: One or more services not ready.