openapi: 3.1.0
info:
  title: Paddock Drill Analysis API
  version: "2.0"
servers:
  - url: https://app.internal
paths:
  /api/drills/{drillId}/runtime:
    get:
      summary: Return client-safe runtime data for local hinting.
      parameters:
        - in: path
          name: drillId
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Client runtime
          content:
            application/json:
              schema:
                type: object
                required: [drillId, clientRuntime]
                properties:
                  drillId: { type: string }
                  clientRuntime:
                    type: object
                    required: [propositionHints]
                    properties:
                      propositionHints:
                        type: array
                        items:
                          type: object
                          required: [propositionId, aliasTexts]
                          properties:
                            propositionId: { type: string }
                            aliasTexts:
                              type: array
                              items: { type: string }
  /api/drills/{drillId}/analyze:
    post:
      summary: Analyze a draft answer and return proposition states backed by evidence.
      parameters:
        - in: path
          name: drillId
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ../schemas/analysis-request.schema.json
      responses:
        "200":
          description: Analysis result
          content:
            application/json:
              schema:
                $ref: ../schemas/analysis-response.schema.json
  /api/drills/{drillId}/submit:
    post:
      summary: Finalize a drill attempt and return the completed rubric plus instructional feedback.
      parameters:
        - in: path
          name: drillId
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: ../schemas/analysis-request.schema.json
                - type: object
                  properties:
                    mode:
                      const: submit
      responses:
        "200":
          description: Finalized result
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ../schemas/analysis-response.schema.json
                  - type: object
                    properties:
                      pedagogy:
                        type: object
                        properties:
                          ruleExplanation: { type: string }
                          formulaScaffold: { type: string }
                          missedPropositionIds:
                            type: array
                            items: { type: string }
