{
  "openapi": "3.1.0",
  "info": {
    "title": "Alpha Results",
    "description": "The Alpha Results API is the canonical outcome ledger: result records with provenance and evidence, append-only mastery and XP ledgers, gate passes, effective-dated student state, and computed as-of grade positions including MAP effective grade. Progress and transcript reads are computed over the ledgers rather than stored materializations. Policy values such as the mastery cutoff come from curriculum policy rows at read time. Its projection surface is the OneRoster gradebook service.",
    "version": "1.0"
  },
  "tags": [
    {
      "name": "AI Grading Audit",
      "description": "AI-grading audit trail row: which provider/model/prompt graded a result or component, with human-override provenance and a supersedes self-ref for regrades."
    },
    {
      "name": "Content Effectiveness",
      "description": "Results-owned content-effectiveness rollup. One row per (tenant, contentId) carries validated_by_count / failed_by_count / last_recomputed_at. The Results surface recomputes after settled resultContentEvidence; Content exposes GET /content-item/{id}/effectiveness as a read-only command and never creates or writes this table. contentId is a hook-validated loose ref — no DB FK into content, killing the content↔results cycle."
    },
    {
      "name": "Export Batch (receipt)",
      "description": "Bulk-export receipt. Returns a JSON downloadRef plus per-entity counts; clients fetch bytes out-of-band. Data freshness is the managed updatedAt plus this receipt's createdAt — no separate freshness machinery. Table is results_export_batch to avoid colliding with oneroster's export_batch table name."
    },
    {
      "name": "Gate Pass",
      "description": "Effective-dated gate-pass state per (student, subject, gateContentId): written by the import door when a mastery-gate attempt clears the curriculum-policy cutoff. Failed attempts live in masteryLedger only — a gatePass row exists only for passes (or a later revocation period). gateContentId is a hook-validated loose content ref."
    },
    {
      "name": "Gradebook Category",
      "description": "Alpha pass-through+rename projection over the oneroster category master: title→name, lifecycle/metadata cut."
    },
    {
      "name": "Gradebook Line Item",
      "description": "Alpha rename projection over the OneRoster lineItem master: one stored gradebook surface (the union master), with no results-owned duplicate. The import door's sourceShape=gradebook path writes through this projection's inverse map. Legacy metadata bag and OneRoster status are cut from the Alpha surface."
    },
    {
      "name": "Gradebook Result",
      "description": "Alpha projection over the oneroster result master: rename score→scoreValue, valueMap the spaced OneRoster scoreStatus vocabulary to the typed snake_case enum, pass through comment. The gradebook-kind outcome lives HERE (the projection); the broader multi-source outcome ledger is the native resultRecord."
    },
    {
      "name": "Gradebook Score Scale",
      "description": "Alpha rename projection over the oneroster scoreScale master. Named gradebookScoreScale so the projection view name does not collide with the oneroster score_scale master table in the shared database."
    },
    {
      "name": "Gradebook Score Scale Value",
      "description": "Alpha rename projection over the oneroster scoreScaleValue child master (the scoreScale child rows: value labels with numeric bounds)."
    },
    {
      "name": "Import Batch (receipt)",
      "description": "Import-door receipt (receipt-is-an-entity). POST /imports is the command (idempotency required — same key with a different raw-body hash is a 422); the receipt row carries accepted/rejected counts, the materialized-per-entity map, quarantine payloads (payload + violated constraint + reason — never coerced), reconciliation diagnostics, and the reconciliationUrl. Table is results_import_batch; the entity name stays importBatch."
    },
    {
      "name": "MAP Effective Grade",
      "description": "The ONLY MAP entity results keeps: a computed student-RIT × nweamap:ritToGradeReference join stamped at import time. Natural 4-col key (studentId, subjectId, canonicalTermId, normsSet) + tenant leg. rit50Grade/rit90Grade come from the imported nweamap reference; effectiveGrade uses the shared alpha-rules effective-grade calculator. Raw/typed per-student MAP facts are nweamap's — the import door routes sourceShape=map rows there and materializes only this join here."
    },
    {
      "name": "Mastery Ledger",
      "description": "The durable, append-only mastery ledger: each row is an attempted mastery-gate fact with a supersededBy pointer — never updated, never deleted. Failed and passed attempts both append; gatePass effective-dated state is refreshed when an attempt clears the curriculum-policy cutoff. gateContentId is a hook-validated loose content ref, not a database foreign key. Curriculum policy is read at runtime (not a compile-time import)."
    },
    {
      "name": "Report Card Entry",
      "description": "Effective-dated report-card line per (student, subject, term): the term-scoped surfaced grade snapshot, amendable within its period, history preserved by the effective-dated primitive."
    },
    {
      "name": "Result Content Evidence",
      "description": "Per-result content-effectiveness signal: results supplies the evidence rows and owns the derived content_effectiveness rollup. Content reads that rollup via a computed GET and never writes it. contentId is a hook-validated loose ref — no database foreign key in either direction, avoiding a content↔results cycle."
    },
    {
      "name": "Result KC Evidence",
      "description": "Per-result knowledge-component evidence: the typed signal a result contributes to a KC. kcId is a loose runtime ref toward curriculum's knowledgeComponent (curriculum is a runtime transaction read seam, not a compile-time import)."
    },
    {
      "name": "Result Record",
      "description": "The canonical multi-source outcome fact — the union point where every producer's result lands. resultKind is the governed two-door enum: the public POST accepts only the native kinds; adapter-owned kinds {map, mastery_gate, mastery_visibility, gradebook} enter ONLY through POST /imports, enforced by the PublicDoorResultKind validation. subjectId is the canonical 6-value report/MAP enum set at write time; display aliases fold ONLY in the import hook. contentId is a hook-validated loose ref to content:contentItem — no DB FK. Also anchors the four Ed-Fi-backed transcript computed reads."
    },
    {
      "name": "Result Source Evidence",
      "description": "Provenance row per imported producer fact: which upstream table/key produced a resultRecord, with the raw payload hash (the import door hashes the raw body, never the normalized item) and optionally the canonical payload hash. Written only by the import door; read-only on the API."
    },
    {
      "name": "Source Adapter",
      "description": "One named producer/adapter registered against the import door. Every resultRecord and every import receipt carries a sourceAdapterId FK into this registry."
    },
    {
      "name": "Student KC State",
      "description": "Effective-dated per-student knowledge-component mastery state. One row is one effective period [beginDate, endDate) of a student×KC state; the table is the history, and an exclusion constraint guarantees non-overlap. Primary key is a server uuid; the natural subject is the effective-dated subjectKey (studentId, kcId). kcId is a loose curriculum ref resolved at runtime."
    },
    {
      "name": "Student Track State",
      "description": "Effective-dated per-student track placement: the current track level/segment per (student, track) with placement evidence, refreshed by the import door when a passing mastery gate moves the HMG-derived position. trackId/currentTrackLevelId are loose curriculum refs (runtime transaction seam)."
    },
    {
      "name": "Test Result Component",
      "description": "Question/section anatomy of a result: a typed tree under a resultRecord — test → section → part → question — with parent self-ref. componentRole is a typed enum; contentId is a hook-validated loose ref toward content."
    },
    {
      "name": "XP Ledger",
      "description": "The immutable XP award ledger. XP is computed from the raw per-attempt grain in the import door — never ingested as a pre-computed rollup. Awards may be negative via reversal rows (reversalOfXpAwardId); append-only: no update/delete op, immutableFields on every column. subjectId uses the 7-value xpSubject enum — fastmath persists as itself, never folded to math at XP time. Also anchors the three progress computed reads (course/grade-level progress + next-task), whose derivations consume the curriculum course structure via the runtime transaction seam."
    }
  ],
  "paths": {
    "/results/v1/ai-grading-audit": {
      "get": {
        "operationId": "listAiGradingAudit",
        "summary": "List AI grading audit rows",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "AI Grading Audit"
        ],
        "parameters": [
          {
            "name": "resultRecordId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "resultRecordId",
              "operator": "eq"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AiGradingAudit"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createAiGradingAudit",
        "summary": "Append an audit row",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "AI Grading Audit"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAiGradingAuditRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AiGradingAudit"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/ai-grading-audit/{aiGradingAuditId}": {
      "get": {
        "operationId": "getAiGradingAudit",
        "summary": "Get one audit row",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "AI Grading Audit"
        ],
        "parameters": [
          {
            "name": "aiGradingAuditId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AiGradingAudit"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (ai_grading_audit_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/content-effectiveness": {
      "get": {
        "operationId": "listContentEffectiveness",
        "summary": "List content-effectiveness rollups",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Content Effectiveness"
        ],
        "parameters": [
          {
            "name": "contentId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "contentId",
              "operator": "eq"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ContentEffectiveness"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/content-effectiveness/{contentId}": {
      "get": {
        "operationId": "getContentEffectiveness",
        "summary": "Get one content-effectiveness rollup",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Content Effectiveness"
        ],
        "parameters": [
          {
            "name": "contentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentEffectiveness"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (content_effectiveness_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/exports": {
      "get": {
        "operationId": "listExportBatches",
        "summary": "List export receipts",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Export Batch (receipt)"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ExportBatch"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "exportResults",
        "summary": "Bulk export of results-owned entities",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Export Batch (receipt)"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "The idempotency key (max 128 chars). Optional — when present, the call is replay-protected; a completed replay returns the stored response at 200 with idempotency-replayed: true.",
            "schema": {
              "type": "string",
              "maxLength": 128
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "entities": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Entity names to export; omitted = all results-owned entities."
                  },
                  "studentId": {
                    "type": "string"
                  },
                  "subject": {
                    "type": "string",
                    "enum": [
                      "math",
                      "reading",
                      "language",
                      "science",
                      "vocabulary",
                      "writing"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK (idempotent replay — the stored first response; idempotency-replayed: true).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExportBatch"
                }
              }
            },
            "headers": {
              "idempotency-replayed": {
                "description": "true when this response is a stored idempotent replay (the hook did not run).",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ]
                }
              }
            }
          },
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExportBatch"
                }
              }
            },
            "headers": {
              "idempotency-replayed": {
                "description": "true when this response is a stored idempotent replay (the hook did not run).",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict — an operation with this Idempotency-Key is already in progress (60s lock).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Entity — this Idempotency-Key was already used with a different request body.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "428": {
            "description": "Precondition Required — this operation requires the Idempotency-Key header.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/exports/{exportId}": {
      "get": {
        "operationId": "getExportBatch",
        "summary": "Get one export receipt",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Export Batch (receipt)"
        ],
        "parameters": [
          {
            "name": "exportId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExportBatch"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (export_batch_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/gate-passes": {
      "get": {
        "operationId": "listGatePasses",
        "summary": "List gate passes (?asOf= narrows)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Gate Pass"
        ],
        "parameters": [
          {
            "name": "studentId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "studentId",
              "operator": "eq"
            }
          },
          {
            "name": "subject",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "math",
                "reading",
                "language",
                "science",
                "vocabulary",
                "writing"
              ]
            },
            "x-filter": {
              "column": "subjectId",
              "operator": "eq"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "asOf",
            "in": "query",
            "required": false,
            "description": "Return only rows whose effective period covers this date: beginDate <= asOf and (endDate is null or asOf < endDate). Absent, the full history is returned.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/GatePass"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createGatePass",
        "summary": "Open a gate pass period (system/import surface)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Gate Pass"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateGatePassRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatePass"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Problem (gate_pass_overlap).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/gate-passes/{id}": {
      "get": {
        "operationId": "getGatePass",
        "summary": "Get one gate pass period",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Gate Pass"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "asOf",
            "in": "query",
            "required": false,
            "description": "Return only rows whose effective period covers this date: beginDate <= asOf and (endDate is null or asOf < endDate). Absent, the full history is returned.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatePass"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (gate_pass_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateGatePass",
        "summary": "Amend a period (e.g. revoke)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Gate Pass"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateGatePassRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatePass"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (gate_pass_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Problem (gate_pass_overlap).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/gradebook-categories": {
      "get": {
        "operationId": "listGradebookCategories",
        "summary": "List gradebook categories",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Gradebook Category"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/GradebookCategory"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createGradebookCategory",
        "summary": "Write-through create against the oneroster master",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Gradebook Category"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateGradebookCategoryRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GradebookCategory"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/gradebook-categories/{sourcedId}": {
      "get": {
        "operationId": "getGradebookCategory",
        "summary": "Get one category",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Gradebook Category"
        ],
        "parameters": [
          {
            "name": "sourcedId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GradebookCategory"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (gradebook_category_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/gradebook-line-items": {
      "get": {
        "operationId": "listGradebookLineItems",
        "summary": "List gradebook line items (Alpha reshape of the oneroster master)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Gradebook Line Item"
        ],
        "parameters": [
          {
            "name": "classId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "classId",
              "operator": "eq"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/GradebookLineItem"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createGradebookLineItem",
        "summary": "Write-through create against the oneroster master (inverse map)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Gradebook Line Item"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateGradebookLineItemRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GradebookLineItem"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/gradebook-line-items/{sourcedId}": {
      "get": {
        "operationId": "getGradebookLineItem",
        "summary": "Get one line item",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Gradebook Line Item"
        ],
        "parameters": [
          {
            "name": "sourcedId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GradebookLineItem"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (gradebook_line_item_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/gradebook-results": {
      "get": {
        "operationId": "listGradebookResults",
        "summary": "List gradebook results",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Gradebook Result"
        ],
        "parameters": [
          {
            "name": "studentId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "studentId",
              "operator": "eq"
            }
          },
          {
            "name": "lineItemId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "lineItemId",
              "operator": "eq"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/GradebookResult"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createGradebookResult",
        "summary": "Write-through create against the oneroster master (inverse map + forward valueMap)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Gradebook Result"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateGradebookResultRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GradebookResult"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/gradebook-results/{sourcedId}": {
      "get": {
        "operationId": "getGradebookResult",
        "summary": "Get one gradebook result",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Gradebook Result"
        ],
        "parameters": [
          {
            "name": "sourcedId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GradebookResult"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (gradebook_result_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/gradebook-score-scales": {
      "get": {
        "operationId": "listGradebookScoreScales",
        "summary": "List score scales",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Gradebook Score Scale"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/GradebookScoreScale"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createGradebookScoreScale",
        "summary": "Write-through create against the oneroster master",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Gradebook Score Scale"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateGradebookScoreScaleRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GradebookScoreScale"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/gradebook-score-scales/{sourcedId}": {
      "get": {
        "operationId": "getGradebookScoreScale",
        "summary": "Get one score scale",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Gradebook Score Scale"
        ],
        "parameters": [
          {
            "name": "sourcedId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GradebookScoreScale"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (gradebook_score_scale_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/gradebook-score-scale-values": {
      "get": {
        "operationId": "listGradebookScoreScaleValues",
        "summary": "List score scale values",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Gradebook Score Scale Value"
        ],
        "parameters": [
          {
            "name": "scoreScaleId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "scoreScaleId",
              "operator": "eq"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/GradebookScoreScaleValue"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createGradebookScoreScaleValue",
        "summary": "Write-through create against the oneroster master",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Gradebook Score Scale Value"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateGradebookScoreScaleValueRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GradebookScoreScaleValue"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/gradebook-score-scale-values/{sourcedId}": {
      "get": {
        "operationId": "getGradebookScoreScaleValue",
        "summary": "Get one score scale value",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Gradebook Score Scale Value"
        ],
        "parameters": [
          {
            "name": "sourcedId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GradebookScoreScaleValue"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (gradebook_score_scale_value_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/imports": {
      "get": {
        "operationId": "listImportBatches",
        "summary": "List import receipts",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Import Batch (receipt)"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ImportBatch"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "importResults",
        "summary": "THE 260616 adapter door — the normalizer fan-out",
        "description": "Per row: fold display subject aliases and result-kind aliases (write-time canonicalization lives here); classify the producer row kind; resolve OneRoster student identity; quarantine unknown subject/grade/student rows (never coerced); apply the curriculum-policy mastery cutoff and stamp masteryCutoffPolicyRef; compute XP from the raw grain into xpLedger; append masteryLedger/gatePass and refresh studentTrackState; write mapEffectiveGrade for the MAP shape (raw MAP facts remain nweamap-owned); emit source evidence with raw-body hashes; write the receipt. One transaction.\n\n> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Import Batch (receipt)"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "The idempotency key (max 128 chars). REQUIRED — absent returns 428. A completed replay returns the stored response at 200 with idempotency-replayed: true.",
            "schema": {
              "type": "string",
              "maxLength": 128
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "sourceShape": {
                    "type": "string",
                    "enum": [
                      "timeback_assessment_result",
                      "nwea_map_assessment_result"
                    ]
                  },
                  "sourceAdapterId": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "producerBatchId": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 256
                  },
                  "dryRun": {
                    "type": "boolean",
                    "default": false
                  },
                  "records": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    },
                    "minItems": 1,
                    "description": "Raw producer rows — the hook normalizes; the raw row is hashed and preserved in evidence/quarantine."
                  }
                },
                "required": [
                  "sourceShape",
                  "sourceAdapterId",
                  "producerBatchId",
                  "records"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK (idempotent replay — the stored first response; idempotency-replayed: true).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ImportBatch"
                }
              }
            },
            "headers": {
              "idempotency-replayed": {
                "description": "true when this response is a stored idempotent replay (the hook did not run).",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ]
                }
              }
            }
          },
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ImportBatch"
                }
              }
            },
            "headers": {
              "idempotency-replayed": {
                "description": "true when this response is a stored idempotent replay (the hook did not run).",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict — an operation with this Idempotency-Key is already in progress (60s lock).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Entity — this Idempotency-Key was already used with a different request body.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "428": {
            "description": "Precondition Required — this operation requires the Idempotency-Key header.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/imports/{importId}": {
      "get": {
        "operationId": "getImportBatch",
        "summary": "Get one import receipt (the command's status endpoint)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Import Batch (receipt)"
        ],
        "parameters": [
          {
            "name": "importId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ImportBatch"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (import_batch_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/map-effective-grades": {
      "get": {
        "operationId": "listMapEffectiveGrades",
        "summary": "List computed MAP effective grades",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "MAP Effective Grade"
        ],
        "parameters": [
          {
            "name": "studentId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "studentId",
              "operator": "eq"
            }
          },
          {
            "name": "subject",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "math",
                "reading",
                "language",
                "science",
                "vocabulary",
                "writing"
              ]
            },
            "x-filter": {
              "column": "subjectId",
              "operator": "eq"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MapEffectiveGrade"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createMapEffectiveGrade",
        "summary": "Upsert surface for the import door's computed join (system/import)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "MAP Effective Grade"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateMapEffectiveGradeRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MapEffectiveGrade"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/mastery-ledger": {
      "get": {
        "operationId": "listMasteryLedger",
        "summary": "List mastery ledger rows (append-only history)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Mastery Ledger"
        ],
        "parameters": [
          {
            "name": "studentId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "studentId",
              "operator": "eq"
            }
          },
          {
            "name": "subject",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "math",
                "reading",
                "language",
                "science",
                "vocabulary",
                "writing"
              ]
            },
            "x-filter": {
              "column": "subjectId",
              "operator": "eq"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MasteryLedger"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createMasteryLedgerEntry",
        "summary": "Append a ledger row (system/import surface — the door is the canonical writer)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Mastery Ledger"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateMasteryLedgerRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MasteryLedger"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/mastery-ledger/{masteryLedgerId}": {
      "get": {
        "operationId": "getMasteryLedgerEntry",
        "summary": "Get one ledger row",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Mastery Ledger"
        ],
        "parameters": [
          {
            "name": "masteryLedgerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MasteryLedger"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (mastery_ledger_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/students/{studentId}/highest-mastered-grade": {
      "get": {
        "operationId": "getHighestMasteredGrade",
        "summary": "HMG as-of — max passing integer grade from the ledger (computed, NOT stored)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Mastery Ledger"
        ],
        "parameters": [
          {
            "name": "studentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "subject",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "math",
                "reading",
                "language",
                "science",
                "vocabulary",
                "writing"
              ]
            }
          },
          {
            "name": "asOfDate",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "studentId": {
                      "type": "string"
                    },
                    "subjectId": {
                      "type": "string"
                    },
                    "asOfDate": {
                      "type": "string",
                      "format": "date"
                    },
                    "highestMasteredGrade": {
                      "type": "integer",
                      "nullable": true
                    },
                    "sourceMasteryLedgerIds": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "masteryCutoffPolicyRef": {
                      "type": "string",
                      "nullable": true
                    },
                    "computedAt": {
                      "type": "string",
                      "nullable": true
                    },
                    "nullReason": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": [
                    "studentId",
                    "subjectId",
                    "asOfDate",
                    "highestMasteredGrade",
                    "sourceMasteryLedgerIds"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/students/{studentId}/working-grade": {
      "get": {
        "operationId": "getWorkingGrade",
        "summary": "Working grade — the 5-case HMG+1 resolver over the ledger (shared/alpha-rules)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Mastery Ledger"
        ],
        "parameters": [
          {
            "name": "studentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "subject",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "math",
                "reading",
                "language",
                "science",
                "vocabulary",
                "writing"
              ]
            }
          },
          {
            "name": "asOfDate",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "enrolledGrade",
            "in": "query",
            "required": false,
            "description": "Roster/age grade input to the resolver. Age grade is P&O-owned; callers supply it — results never computes roster grade.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "studentId": {
                      "type": "string"
                    },
                    "subjectId": {
                      "type": "string"
                    },
                    "asOfDate": {
                      "type": "string",
                      "format": "date"
                    },
                    "workingGrade": {
                      "type": "number",
                      "nullable": true
                    },
                    "workingGradeCase": {
                      "type": "string",
                      "enum": [
                        "agree",
                        "high",
                        "low",
                        "hmg",
                        "enr",
                        "missing"
                      ]
                    },
                    "enrolledGrade": {
                      "type": "number",
                      "nullable": true
                    },
                    "highestMasteredGrade": {
                      "type": "integer",
                      "nullable": true
                    },
                    "color": {
                      "type": "string",
                      "nullable": true
                    },
                    "displayTag": {
                      "type": "string",
                      "nullable": true
                    },
                    "formulaVersion": {
                      "type": "string"
                    },
                    "nullReason": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": [
                    "studentId",
                    "subjectId",
                    "asOfDate",
                    "workingGrade",
                    "workingGradeCase",
                    "formulaVersion"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/students/{studentId}/advancement": {
      "get": {
        "operationId": "getAdvancement",
        "summary": "Advancement = max(0, workingGrade − syStartWorkingGrade) (computed)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Mastery Ledger"
        ],
        "parameters": [
          {
            "name": "studentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "subject",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "math",
                "reading",
                "language",
                "science",
                "vocabulary",
                "writing"
              ]
            }
          },
          {
            "name": "asOfDate",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "enrolledGrade",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "syStartWorkingGrade",
            "in": "query",
            "required": false,
            "description": "School-year-start working grade baseline; defaults to the current working grade (advancement 0).",
            "schema": {
              "type": "number"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "studentId": {
                      "type": "string"
                    },
                    "subjectId": {
                      "type": "string"
                    },
                    "asOfDate": {
                      "type": "string",
                      "format": "date"
                    },
                    "currentWorkingGrade": {
                      "type": "number",
                      "nullable": true
                    },
                    "syStartWorkingGrade": {
                      "type": "number",
                      "nullable": true
                    },
                    "advancementValue": {
                      "type": "number",
                      "nullable": true
                    },
                    "formulaVersion": {
                      "type": "string",
                      "nullable": true
                    },
                    "nullReason": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": [
                    "studentId",
                    "subjectId",
                    "asOfDate",
                    "currentWorkingGrade",
                    "advancementValue"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/report-card": {
      "get": {
        "operationId": "listReportCardEntries",
        "summary": "List report card entries (?asOf= narrows)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Report Card Entry"
        ],
        "parameters": [
          {
            "name": "studentId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "studentId",
              "operator": "eq"
            }
          },
          {
            "name": "canonicalTermId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "canonicalTermId",
              "operator": "eq"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "asOf",
            "in": "query",
            "required": false,
            "description": "Return only rows whose effective period covers this date: beginDate <= asOf and (endDate is null or asOf < endDate). Absent, the full history is returned.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ReportCardEntry"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createReportCardEntry",
        "summary": "Open a report card entry period",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Report Card Entry"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateReportCardEntryRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportCardEntry"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Problem (report_card_entry_overlap).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/report-card/{id}": {
      "get": {
        "operationId": "getReportCardEntry",
        "summary": "Get one report card entry",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Report Card Entry"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "asOf",
            "in": "query",
            "required": false,
            "description": "Return only rows whose effective period covers this date: beginDate <= asOf and (endDate is null or asOf < endDate). Absent, the full history is returned.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportCardEntry"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (report_card_entry_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateReportCardEntry",
        "summary": "Amend an entry",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Report Card Entry"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateReportCardEntryRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportCardEntry"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (report_card_entry_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Problem (report_card_entry_overlap).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/result-content-evidence": {
      "get": {
        "operationId": "listResultContentEvidence",
        "summary": "List content evidence rows",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Result Content Evidence"
        ],
        "parameters": [
          {
            "name": "resultRecordId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "resultRecordId",
              "operator": "eq"
            }
          },
          {
            "name": "contentId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "contentId",
              "operator": "eq"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ResultContentEvidence"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/result-content-evidence/{resultContentEvidenceId}": {
      "get": {
        "operationId": "getResultContentEvidence",
        "summary": "Get one content evidence row",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Result Content Evidence"
        ],
        "parameters": [
          {
            "name": "resultContentEvidenceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResultContentEvidence"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (result_content_evidence_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/result-kc-evidence": {
      "get": {
        "operationId": "listResultKcEvidence",
        "summary": "List KC evidence rows",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Result KC Evidence"
        ],
        "parameters": [
          {
            "name": "resultRecordId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "resultRecordId",
              "operator": "eq"
            }
          },
          {
            "name": "kcId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "kcId",
              "operator": "eq"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ResultKcEvidence"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/result-kc-evidence/{resultKcEvidenceId}": {
      "get": {
        "operationId": "getResultKcEvidence",
        "summary": "Get one KC evidence row",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Result KC Evidence"
        ],
        "parameters": [
          {
            "name": "resultKcEvidenceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResultKcEvidence"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (result_kc_evidence_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/result-records": {
      "get": {
        "operationId": "listResultRecords",
        "summary": "List result records (canonical subjects only — aliases are a 400)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Result Record"
        ],
        "parameters": [
          {
            "name": "studentId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "studentId",
              "operator": "eq"
            }
          },
          {
            "name": "subject",
            "in": "query",
            "description": "Canonical subject only — ?subject=Mathematics is a 400.",
            "schema": {
              "type": "string",
              "enum": [
                "math",
                "reading",
                "language",
                "science",
                "vocabulary",
                "writing"
              ]
            },
            "x-filter": {
              "column": "subjectId",
              "operator": "eq"
            }
          },
          {
            "name": "resultKind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "self_paced",
                "external_assessment",
                "learning_app_outcome",
                "legacy_assessment",
                "question_result",
                "map",
                "mastery_gate",
                "mastery_visibility",
                "gradebook"
              ]
            },
            "x-filter": {
              "column": "resultKind",
              "operator": "eq"
            }
          },
          {
            "name": "canonicalTermId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "canonicalTermId",
              "operator": "eq"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ResultRecord"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createResultRecord",
        "summary": "Create a result record (public kinds only — the enforcement half of 260616)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Result Record"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "The idempotency key (max 128 chars). Optional — when present, the call is replay-protected; a completed replay returns the stored response at 200 with idempotency-replayed: true.",
            "schema": {
              "type": "string",
              "maxLength": 128
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateResultRecordRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK (idempotent replay — the stored first response; idempotency-replayed: true).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResultRecord"
                }
              }
            },
            "headers": {
              "idempotency-replayed": {
                "description": "true when this response is a stored idempotent replay (the hook did not run).",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ]
                }
              },
              "ETag": {
                "description": "The resource's current entity-tag (RFC 9110, quoted). Send it back in If-Match on the next write (optimistic concurrency).",
                "schema": {
                  "type": "string"
                }
              },
              "Location": {
                "description": "URI of the created resource (detail route). Persisted on the idempotency row and re-served on replay.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResultRecord"
                }
              }
            },
            "headers": {
              "idempotency-replayed": {
                "description": "true when this response is a stored idempotent replay (the hook did not run).",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ]
                }
              },
              "ETag": {
                "description": "The resource's current entity-tag (RFC 9110, quoted). Send it back in If-Match on the next write (optimistic concurrency).",
                "schema": {
                  "type": "string"
                }
              },
              "Location": {
                "description": "URI of the created resource (detail route). Persisted on the idempotency row and re-served on replay.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict — an operation with this Idempotency-Key is already in progress (60s lock).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Entity — this Idempotency-Key was already used with a different request body.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "428": {
            "description": "Precondition Required — this operation requires the Idempotency-Key header.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/result-records/{resultRecordId}": {
      "get": {
        "operationId": "getResultRecord",
        "summary": "Get one result record",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Result Record"
        ],
        "parameters": [
          {
            "name": "resultRecordId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResultRecord"
                }
              }
            },
            "headers": {
              "ETag": {
                "description": "The resource's current entity-tag (RFC 9110, quoted). Send it back in If-Match on the next write (optimistic concurrency).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (result_record_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateResultRecord",
        "summary": "Amend a result record (If-Match optimistic concurrency)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Result Record"
        ],
        "parameters": [
          {
            "name": "resultRecordId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "description": "The resource's current ETag (from the last GET/write response), quoted per RFC 9110. REQUIRED — absent returns 428; a stale ETag returns 412 (refetch and retry). Send `*` to overwrite unconditionally.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateResultRecordRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResultRecord"
                }
              }
            },
            "headers": {
              "ETag": {
                "description": "The resource's current entity-tag (RFC 9110, quoted). Send it back in If-Match on the next write (optimistic concurrency).",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (result_record_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "Precondition Failed — the If-Match ETag is stale (the resource was modified); refetch and retry.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "428": {
            "description": "Precondition Required — this write requires the If-Match header (send the resource's ETag).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/response-evaluations": {
      "post": {
        "operationId": "createResponseEvaluation",
        "summary": "Grade one embedded-question response against the Content/QTI answer key",
        "description": "Stateless synchronous grade: the renderer submits evidence only; the server reads the Content-owned answer key and grades with the answer_key_grading semantic. Persists nothing; never returns the answer key. No gradable answer key row → 422 results:not_gradable.\n\n> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Result Record"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "contentId": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 256,
                    "description": "The Content item whose QTI answer key grades this response (hook-validated loose ref)."
                  },
                  "responseValue": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "array",
                        "items": {
                          "oneOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "number"
                            }
                          ]
                        }
                      }
                    ],
                    "description": "The submitted response: a string or an array of strings/numbers (QTI single vs multiple/ordered cardinality). Non-emptiness is hook-validated."
                  },
                  "responseIdentifier": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 256,
                    "description": "QTI responseIdentifier when the item declares more than one response slot."
                  },
                  "firstAttempt": {
                    "type": "boolean",
                    "description": "Renderer-declared first-attempt flag (evidence, echoed back — grading ignores it)."
                  },
                  "attemptOrdinal": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Renderer-declared attempt ordinal (evidence, echoed back)."
                  }
                },
                "required": [
                  "contentId",
                  "responseValue"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resultKind": {
                      "type": "string",
                      "description": "Always question_result for a successful response evaluation."
                    },
                    "contentId": {
                      "type": "string"
                    },
                    "responseIdentifier": {
                      "type": "string",
                      "nullable": true
                    },
                    "responseValue": {
                      "oneOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "array",
                          "items": {
                            "oneOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "number"
                              }
                            ]
                          }
                        }
                      ],
                      "description": "The submitted response echoed back (never the correct values)."
                    },
                    "isCorrect": {
                      "type": "boolean"
                    },
                    "score": {
                      "type": "number"
                    },
                    "maxScore": {
                      "type": "number"
                    },
                    "firstAttempt": {
                      "type": "boolean",
                      "nullable": true
                    },
                    "attemptOrdinal": {
                      "type": "integer",
                      "nullable": true
                    },
                    "scoringSource": {
                      "type": "string",
                      "description": "Always content_qti_answer_key."
                    },
                    "gradedBy": {
                      "type": "string",
                      "description": "Always results."
                    },
                    "gradedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": [
                    "resultKind",
                    "contentId",
                    "responseValue",
                    "isCorrect",
                    "score",
                    "maxScore",
                    "scoringSource",
                    "gradedBy",
                    "gradedAt"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/academic-records": {
      "get": {
        "operationId": "getAcademicRecords",
        "summary": "Ed-Fi-backed academic-record computed read (NOT a stored table)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Result Record"
        ],
        "parameters": [
          {
            "name": "studentId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "schoolYear",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": [
                    "data",
                    "nextCursor"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/course-transcripts": {
      "get": {
        "operationId": "getCourseTranscripts",
        "summary": "Ed-Fi-backed course-transcript computed read",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Result Record"
        ],
        "parameters": [
          {
            "name": "studentId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "schoolYear",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": [
                    "data",
                    "nextCursor"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/course-grades": {
      "get": {
        "operationId": "getCourseGrades",
        "summary": "Ed-Fi-backed grading-period grade computed read",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Result Record"
        ],
        "parameters": [
          {
            "name": "studentId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "schoolYear",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": [
                    "data",
                    "nextCursor"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/transcript-results": {
      "get": {
        "operationId": "getTranscriptResults",
        "summary": "Joined transcript+grade computed read",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Result Record"
        ],
        "parameters": [
          {
            "name": "studentId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": [
                    "data",
                    "nextCursor"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/result-source-evidence": {
      "get": {
        "operationId": "listResultSourceEvidence",
        "summary": "List source evidence rows",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Result Source Evidence"
        ],
        "parameters": [
          {
            "name": "resultRecordId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "resultRecordId",
              "operator": "eq"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ResultSourceEvidence"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/result-source-evidence/{sourceEvidenceId}": {
      "get": {
        "operationId": "getResultSourceEvidence",
        "summary": "Get one source evidence row",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Result Source Evidence"
        ],
        "parameters": [
          {
            "name": "sourceEvidenceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResultSourceEvidence"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (source_evidence_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/source-adapters": {
      "get": {
        "operationId": "listSourceAdapters",
        "summary": "List registered source adapters",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Source Adapter"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SourceAdapter"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createSourceAdapter",
        "summary": "Register a source adapter",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Source Adapter"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSourceAdapterRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceAdapter"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/source-adapters/{sourceAdapterId}": {
      "get": {
        "operationId": "getSourceAdapter",
        "summary": "Get one source adapter",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Source Adapter"
        ],
        "parameters": [
          {
            "name": "sourceAdapterId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceAdapter"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (source_adapter_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateSourceAdapter",
        "summary": "Amend a source adapter (activate/deactivate)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Source Adapter"
        ],
        "parameters": [
          {
            "name": "sourceAdapterId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateSourceAdapterRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceAdapter"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (source_adapter_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/kc-states": {
      "get": {
        "operationId": "listStudentKcStates",
        "summary": "List KC state periods (?asOf= narrows to the covering period)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Student KC State"
        ],
        "parameters": [
          {
            "name": "studentId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "studentId",
              "operator": "eq"
            }
          },
          {
            "name": "kcId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "kcId",
              "operator": "eq"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "asOf",
            "in": "query",
            "required": false,
            "description": "Return only rows whose effective period covers this date: beginDate <= asOf and (endDate is null or asOf < endDate). Absent, the full history is returned.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/StudentKcState"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createStudentKcState",
        "summary": "Open a KC state period",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Student KC State"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateStudentKcStateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StudentKcState"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Problem (student_kc_state_overlap).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/kc-states/{id}": {
      "get": {
        "operationId": "getStudentKcState",
        "summary": "Get one KC state period",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Student KC State"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "asOf",
            "in": "query",
            "required": false,
            "description": "Return only rows whose effective period covers this date: beginDate <= asOf and (endDate is null or asOf < endDate). Absent, the full history is returned.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StudentKcState"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (student_kc_state_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateStudentKcState",
        "summary": "Amend a period (e.g. close the open period)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Student KC State"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateStudentKcStateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StudentKcState"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (student_kc_state_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Problem (student_kc_state_overlap).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/track-states": {
      "get": {
        "operationId": "listStudentTrackStates",
        "summary": "List track state periods (?asOf= narrows)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Student Track State"
        ],
        "parameters": [
          {
            "name": "studentId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "studentId",
              "operator": "eq"
            }
          },
          {
            "name": "trackId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "trackId",
              "operator": "eq"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "asOf",
            "in": "query",
            "required": false,
            "description": "Return only rows whose effective period covers this date: beginDate <= asOf and (endDate is null or asOf < endDate). Absent, the full history is returned.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/StudentTrackState"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createStudentTrackState",
        "summary": "Open a track state period",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Student Track State"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateStudentTrackStateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StudentTrackState"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Problem (student_track_state_overlap).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/track-states/{id}": {
      "get": {
        "operationId": "getStudentTrackState",
        "summary": "Get one track state period",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Student Track State"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "asOf",
            "in": "query",
            "required": false,
            "description": "Return only rows whose effective period covers this date: beginDate <= asOf and (endDate is null or asOf < endDate). Absent, the full history is returned.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StudentTrackState"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (student_track_state_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateStudentTrackState",
        "summary": "Amend a period",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Student Track State"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateStudentTrackStateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StudentTrackState"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (student_track_state_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Problem (student_track_state_overlap).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/test-result-components": {
      "get": {
        "operationId": "listTestResultComponents",
        "summary": "List test result components",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Test Result Component"
        ],
        "parameters": [
          {
            "name": "resultRecordId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "resultRecordId",
              "operator": "eq"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TestResultComponent"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createTestResultComponent",
        "summary": "Create a component",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Test Result Component"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTestResultComponentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestResultComponent"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/test-result-components/{testResultComponentId}": {
      "get": {
        "operationId": "getTestResultComponent",
        "summary": "Get one component",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "Test Result Component"
        ],
        "parameters": [
          {
            "name": "testResultComponentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestResultComponent"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (test_result_component_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/xp-ledger": {
      "get": {
        "operationId": "listXpLedger",
        "summary": "List XP awards",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "XP Ledger"
        ],
        "parameters": [
          {
            "name": "studentId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "column": "studentId",
              "operator": "eq"
            }
          },
          {
            "name": "subject",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "math",
                "reading",
                "language",
                "science",
                "vocabulary",
                "writing",
                "fastmath"
              ]
            },
            "x-filter": {
              "column": "subjectId",
              "operator": "eq"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items to return on this page (clamped server-side).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "nextCursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/XpLedger"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when this is the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createXpAward",
        "summary": "Append an XP award (system/import surface — the door computes awards)",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "XP Ledger"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateXpLedgerRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/XpLedger"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/xp-ledger/{xpAwardId}": {
      "get": {
        "operationId": "getXpAward",
        "summary": "Get one XP award",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "XP Ledger"
        ],
        "parameters": [
          {
            "name": "xpAwardId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/XpLedger"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Problem (xp_award_not_found).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/component-xp-awards": {
      "post": {
        "operationId": "createComponentXpAward",
        "summary": "Award component XP from first-attempt accuracy evidence",
        "description": "Awards component XP on evidence rails: expected XP is read from curriculum.course_component_extension (the owning rail — never the request); first-attempt accuracy rolls up results' own question_result rows; multipliers come from the curriculum alpha.policy.xp_award_formula row (fail-loud 422 when absent). Writes result_record, result_source_evidence, and xp_ledger with deterministic ids in one transaction and returns the award receipt.\n\n> **Auth required:** a verified bearer token is required.",
        "tags": [
          "XP Ledger"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "The idempotency key (max 128 chars). REQUIRED — absent returns 428. A completed replay returns the stored response at 200 with idempotency-replayed: true.",
            "schema": {
              "type": "string",
              "maxLength": 128
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "studentId": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 256,
                    "description": "OneRoster student identity — verified against oneroster.user, never fabricated."
                  },
                  "componentId": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 256,
                    "description": "The gated Curriculum component (curriculum.course_component_extension leaf) whose expected_xp is awarded."
                  },
                  "componentType": {
                    "type": "string",
                    "maxLength": 128,
                    "description": "Component-type keyword for the mastery threshold (assessment/test/quiz, video, article/reading; default lesson)."
                  },
                  "subjectId": {
                    "type": "string",
                    "enum": [
                      "math",
                      "reading",
                      "language",
                      "science",
                      "vocabulary",
                      "writing",
                      "fastmath"
                    ],
                    "description": "xpSubject 7-value enum; falls back to the component's subject when omitted."
                  },
                  "happenedAtFrom": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Optional evidence-window lower bound (inclusive) on the question_result occurred_on."
                  },
                  "happenedAtTo": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Optional evidence-window upper bound (inclusive) on the question_result occurred_on."
                  },
                  "declaredQuestionCount": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1000,
                    "description": "Declared embedded-question denominator (skipped declared questions count incorrect)."
                  },
                  "declaredQuestionIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 256
                    },
                    "description": "Declared embedded question content ids — the evidence match set."
                  }
                },
                "required": [
                  "studentId",
                  "componentId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK (idempotent replay — the stored first response; idempotency-replayed: true).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "awardId": {
                      "type": "string",
                      "description": "The deterministic xp_ledger award id."
                    },
                    "status": {
                      "type": "string",
                      "description": "accepted, or replayed when the durable award row already existed with different values (the receipt always reflects the stored row)."
                    },
                    "accuracyRollup": {
                      "type": "object",
                      "description": "correctCount, denominator, accuracyPercent, thresholdPercent, declaredQuestionCount, attemptedFirstAttemptCount."
                    },
                    "materializedIds": {
                      "type": "object",
                      "description": "resultRecord / resultSourceEvidence / xpLedger deterministic ids."
                    },
                    "expectedXp": {
                      "type": "number",
                      "description": "The Curriculum-owned expected XP the multiplier applied to."
                    },
                    "awardedXp": {
                      "type": "number"
                    },
                    "calculationPolicyRef": {
                      "type": "string",
                      "description": "alpha.policy.xp_award_formula:<version from the policy row>."
                    }
                  },
                  "required": [
                    "awardId",
                    "status",
                    "accuracyRollup",
                    "materializedIds",
                    "awardedXp",
                    "calculationPolicyRef"
                  ]
                }
              }
            },
            "headers": {
              "idempotency-replayed": {
                "description": "true when this response is a stored idempotent replay (the hook did not run).",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ]
                }
              }
            }
          },
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "awardId": {
                      "type": "string",
                      "description": "The deterministic xp_ledger award id."
                    },
                    "status": {
                      "type": "string",
                      "description": "accepted, or replayed when the durable award row already existed with different values (the receipt always reflects the stored row)."
                    },
                    "accuracyRollup": {
                      "type": "object",
                      "description": "correctCount, denominator, accuracyPercent, thresholdPercent, declaredQuestionCount, attemptedFirstAttemptCount."
                    },
                    "materializedIds": {
                      "type": "object",
                      "description": "resultRecord / resultSourceEvidence / xpLedger deterministic ids."
                    },
                    "expectedXp": {
                      "type": "number",
                      "description": "The Curriculum-owned expected XP the multiplier applied to."
                    },
                    "awardedXp": {
                      "type": "number"
                    },
                    "calculationPolicyRef": {
                      "type": "string",
                      "description": "alpha.policy.xp_award_formula:<version from the policy row>."
                    }
                  },
                  "required": [
                    "awardId",
                    "status",
                    "accuracyRollup",
                    "materializedIds",
                    "awardedXp",
                    "calculationPolicyRef"
                  ]
                }
              }
            },
            "headers": {
              "idempotency-replayed": {
                "description": "true when this response is a stored idempotent replay (the hook did not run).",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict — an operation with this Idempotency-Key is already in progress (60s lock).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Entity — this Idempotency-Key was already used with a different request body.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "428": {
            "description": "Precondition Required — this operation requires the Idempotency-Key header.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/students/{studentId}/course-progress": {
      "get": {
        "operationId": "getStudentCourseProgress",
        "summary": "Course progress — XP-remaining-first derivation",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "XP Ledger"
        ],
        "parameters": [
          {
            "name": "studentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "subject",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "math",
                "reading",
                "language",
                "science",
                "vocabulary",
                "writing"
              ]
            }
          },
          {
            "name": "asOfDate",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "studentId": {
                      "type": "string"
                    },
                    "asOfDate": {
                      "type": "string",
                      "nullable": true
                    },
                    "courses": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "nullReason": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": [
                    "studentId",
                    "courses"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/students/{studentId}/grade-level-progress": {
      "get": {
        "operationId": "getGradeLevelProgress",
        "summary": "Grade-level progress — MAIN-course average only",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "XP Ledger"
        ],
        "parameters": [
          {
            "name": "studentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "subject",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "math",
                "reading",
                "language",
                "science",
                "vocabulary",
                "writing"
              ]
            }
          },
          {
            "name": "asOfDate",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "studentId": {
                      "type": "string"
                    },
                    "gradeLevelProgress": {
                      "type": "number",
                      "nullable": true
                    },
                    "nullReason": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": [
                    "studentId"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/results/v1/next-task": {
      "get": {
        "operationId": "getNextTask",
        "summary": "The typed next-task ref Results selects — apps render, never rank",
        "description": "> **Auth required:** a verified bearer token is required.",
        "tags": [
          "XP Ledger"
        ],
        "parameters": [
          {
            "name": "studentId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "subject",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "math",
                "reading",
                "language",
                "science",
                "vocabulary",
                "writing"
              ]
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "studentId": {
                      "type": "string"
                    },
                    "task": {
                      "type": "object",
                      "nullable": true
                    },
                    "nullReason": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": [
                    "studentId"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Not Found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AiGradingAudit": {
        "type": "object",
        "properties": {
          "aiGradingAuditId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Natural id of this audit row."
          },
          "resultRecordId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "FK to the owning result record.",
            "x-references": "resultRecord.resultRecordId",
            "x-onDelete": "restrict"
          },
          "testResultComponentId": {
            "type": "string",
            "maxLength": 128,
            "description": "Natural id of this component row.",
            "x-references": "testResultComponent.testResultComponentId",
            "x-onDelete": "restrict"
          },
          "gradingStage": {
            "type": "string",
            "enum": [
              "initial",
              "regrade",
              "appeal",
              "human_override"
            ],
            "description": "Which grading pass this row records."
          },
          "gradingStatus": {
            "type": "string",
            "enum": [
              "pending",
              "completed",
              "failed",
              "overridden"
            ],
            "description": "Outcome status of the grading pass."
          },
          "aiProvider": {
            "type": "string",
            "maxLength": 128,
            "description": "AI provider that graded (e.g. openai)."
          },
          "aiModel": {
            "type": "string",
            "maxLength": 128,
            "description": "Model name used to grade."
          },
          "modelVersion": {
            "type": "string",
            "maxLength": 128,
            "description": "Model version stamp."
          },
          "promptHash": {
            "type": "string",
            "maxLength": 128,
            "description": "sha256 of the grading prompt (provenance)."
          },
          "rubricVersion": {
            "type": "string",
            "maxLength": 128,
            "description": "Rubric version applied."
          },
          "humanOverrideBy": {
            "type": "string",
            "maxLength": 256,
            "description": "Who overrode the AI grade (audit)."
          },
          "humanOverrideReason": {
            "type": "string",
            "maxLength": 1024,
            "description": "Why the AI grade was overridden."
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the event occurred (producer clock)."
          },
          "supersedesAiGradingAuditId": {
            "type": "string",
            "maxLength": 128,
            "description": "Self-ref to the audit row this one supersedes (regrade chain).",
            "x-references": "aiGradingAudit.aiGradingAuditId",
            "x-onDelete": "restrict"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "aiGradingAuditId",
          "resultRecordId",
          "gradingStage",
          "gradingStatus",
          "updatedAt"
        ]
      },
      "ContentEffectiveness": {
        "type": "object",
        "properties": {
          "contentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Content item id (hook-validated loose ref toward content)."
          },
          "validatedByCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Count of settled results that validated against this content item.",
            "default": 0
          },
          "failedByCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Count of settled results that failed against this content item.",
            "default": 0
          },
          "lastRecomputedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the Results surface last recomputed this rollup from evidence. Null when never recomputed."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "contentId",
          "validatedByCount",
          "failedByCount",
          "updatedAt"
        ]
      },
      "ExportBatch": {
        "type": "object",
        "properties": {
          "exportId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Natural id of this export receipt."
          },
          "status": {
            "type": "string",
            "enum": [
              "completed"
            ],
            "description": "Receipt status."
          },
          "scope": {
            "type": "object",
            "description": "What was exported: { entities: [...], studentId?, subject?, since? }."
          },
          "entityCounts": {
            "type": "object",
            "description": "Per-entity exported row counts."
          },
          "downloadRef": {
            "type": "string",
            "maxLength": 512,
            "description": "JSON download reference; clients fetch export bytes out-of-band."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed row-creation timestamp (RFC 3339). Read-only — never accepted on create or update."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "exportId",
          "status",
          "scope",
          "createdAt",
          "updatedAt"
        ]
      },
      "GatePass": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Server-generated unique identifier for this effective-dated period row.",
            "readOnly": true
          },
          "studentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster student identity (tenant-carrying composite FK).",
            "x-references": "oneroster:user.sourcedId",
            "x-onDelete": "restrict"
          },
          "subjectId": {
            "type": "string",
            "enum": [
              "math",
              "reading",
              "language",
              "science",
              "vocabulary",
              "writing"
            ],
            "description": "Canonical subject id, set at write time."
          },
          "gateContentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Gate content ref (hook-validated loose ref)."
          },
          "resultRecordId": {
            "type": "string",
            "maxLength": 128,
            "description": "FK to the owning result record.",
            "x-references": "resultRecord.resultRecordId",
            "x-onDelete": "restrict"
          },
          "gateStatus": {
            "type": "string",
            "enum": [
              "passed",
              "revoked"
            ],
            "description": "Pass state for the period."
          },
          "passedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the gate was passed."
          },
          "nextEligibleAt": {
            "type": "string",
            "format": "date-time",
            "description": "Retake-cooldown eligibility instant (policy-derived)."
          },
          "attemptCount": {
            "type": "integer",
            "minimum": 1,
            "description": "Attempts observed in the period."
          },
          "policyVersion": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Provenance: the mastery-gate policy ref applied at pass time."
          },
          "beginDate": {
            "type": "string",
            "format": "date",
            "description": "Period start (effective-dated from bound; required)."
          },
          "endDate": {
            "type": "string",
            "format": "date",
            "description": "Period end, EXCLUSIVE (half-open); NULL = open current period."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "studentId",
          "subjectId",
          "gateContentId",
          "gateStatus",
          "passedAt",
          "attemptCount",
          "policyVersion",
          "beginDate",
          "updatedAt"
        ]
      },
      "GradebookCategory": {
        "type": "object",
        "properties": {
          "sourcedId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster natural key (pass-through — PK leg)."
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "The human-readable title of the category."
          },
          "dateLastModified": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "sourcedId",
          "name",
          "dateLastModified"
        ]
      },
      "GradebookLineItem": {
        "type": "object",
        "properties": {
          "sourcedId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster natural key (pass-through — PK leg)."
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "The human-readable title of the line item."
          },
          "description": {
            "type": "string",
            "maxLength": 2048,
            "description": "A description of the line item."
          },
          "classId": {
            "type": "string",
            "maxLength": 256,
            "description": "The sourcedId of the class this line item belongs to."
          },
          "categoryId": {
            "type": "string",
            "maxLength": 256,
            "description": "The sourcedId of the category this line item belongs to."
          },
          "assignDate": {
            "type": "string",
            "format": "date",
            "description": "The date this line item was assigned."
          },
          "dueDate": {
            "type": "string",
            "format": "date",
            "description": "The date this line item is due."
          },
          "resultValueMin": {
            "type": "number",
            "description": "The minimum possible score for results on this line item."
          },
          "resultValueMax": {
            "type": "number",
            "description": "The maximum possible score for results on this line item."
          },
          "dateLastModified": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "sourcedId",
          "title",
          "classId",
          "categoryId",
          "assignDate",
          "dueDate",
          "dateLastModified"
        ]
      },
      "GradebookResult": {
        "type": "object",
        "properties": {
          "sourcedId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster natural key (pass-through — PK leg)."
          },
          "lineItemId": {
            "type": "string",
            "maxLength": 256,
            "description": "The sourcedId of the line item this result is for."
          },
          "studentId": {
            "type": "string",
            "maxLength": 256,
            "description": "The sourcedId of the student user who received this result."
          },
          "scoreValue": {
            "type": "number",
            "description": "The numeric score value."
          },
          "scoreStatus": {
            "type": "string",
            "enum": [
              "fully_graded",
              "partially_graded",
              "not_submitted",
              "submitted",
              "exempt"
            ],
            "description": "Typed snake_case enum over the OneRoster spaced vocabulary (two-way valueMap)."
          },
          "comment": {
            "type": "string",
            "maxLength": 2048,
            "description": "Teacher comment on this result."
          },
          "dateLastModified": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "sourcedId",
          "lineItemId",
          "studentId",
          "dateLastModified"
        ]
      },
      "GradebookScoreScale": {
        "type": "object",
        "properties": {
          "sourcedId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster natural key (pass-through — PK leg)."
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "The human-readable title of the score scale."
          },
          "dateLastModified": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "sourcedId",
          "name",
          "dateLastModified"
        ]
      },
      "GradebookScoreScaleValue": {
        "type": "object",
        "properties": {
          "sourcedId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster natural key (pass-through — PK leg)."
          },
          "scoreScaleId": {
            "type": "string",
            "maxLength": 256,
            "description": "The sourcedId of the parent score scale."
          },
          "value": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "The display value (e.g. A, B+, Pass)."
          },
          "lowerBound": {
            "type": "number",
            "description": "The lower bound of the numeric range for this value."
          },
          "upperBound": {
            "type": "number",
            "description": "The upper bound of the numeric range for this value."
          },
          "dateLastModified": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "sourcedId",
          "scoreScaleId",
          "value",
          "dateLastModified"
        ]
      },
      "ImportBatch": {
        "type": "object",
        "properties": {
          "importId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Natural id of this import receipt."
          },
          "sourceAdapterId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "FK to the registered source adapter.",
            "x-references": "sourceAdapter.sourceAdapterId",
            "x-onDelete": "restrict"
          },
          "sourceShape": {
            "type": "string",
            "enum": [
              "timeback_assessment_result",
              "nwea_map_assessment_result"
            ],
            "description": "Pluggable source-generic adapter dispatch; demonstration adapters cover the supported producer shapes."
          },
          "producerBatchId": {
            "type": "string",
            "maxLength": 256,
            "description": "The producer's batch identifier."
          },
          "dryRun": {
            "type": "boolean",
            "description": "Dry-run batches validate + count but materialize nothing.",
            "default": false
          },
          "status": {
            "type": "string",
            "enum": [
              "accepted",
              "partially_accepted",
              "rejected",
              "dry_run"
            ],
            "description": "Receipt status."
          },
          "acceptedCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Rows accepted and materialized."
          },
          "rejectedCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Rows quarantined/rejected."
          },
          "materializedCounts": {
            "type": "object",
            "description": "Per-entity materialization counts (e.g. { resultRecord: 3, xpLedger: 2 })."
          },
          "quarantine": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Quarantined rows: raw payload + violated constraint + reason."
          },
          "diagnostics": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Reconciliation diagnostics (match/mismatch per metric)."
          },
          "reconciliationUrl": {
            "type": "string",
            "maxLength": 512,
            "description": "Where the closed-loop reconciliation for this batch is served."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed row-creation timestamp (RFC 3339). Read-only — never accepted on create or update."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "importId",
          "sourceAdapterId",
          "sourceShape",
          "status",
          "acceptedCount",
          "rejectedCount",
          "createdAt",
          "updatedAt"
        ]
      },
      "MapEffectiveGrade": {
        "type": "object",
        "properties": {
          "studentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster student identity (tenant-carrying composite FK).",
            "x-references": "oneroster:user.sourcedId",
            "x-onDelete": "restrict"
          },
          "subjectId": {
            "type": "string",
            "enum": [
              "math",
              "reading",
              "language",
              "science",
              "vocabulary",
              "writing"
            ],
            "description": "Canonical subject id, set at write time."
          },
          "canonicalTermId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Canonical academic term id."
          },
          "normsSet": {
            "type": "string",
            "enum": [
              "2020",
              "2025"
            ],
            "description": "NWEA norms edition."
          },
          "rit": {
            "type": "number",
            "description": "The observed RIT score."
          },
          "rit50Grade": {
            "type": "number",
            "description": "Grade position at the 50th percentile (from the nweamap reference)."
          },
          "rit90Grade": {
            "type": "number",
            "description": "Grade position at the 90th percentile (from the nweamap reference)."
          },
          "effectiveGrade": {
            "type": "integer",
            "minimum": -1,
            "maximum": 13,
            "description": "Effective instructional grade from the shared alpha-rules calculator."
          },
          "calculatorVersion": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Version stamp of the effective-grade calculator (provenance)."
          },
          "sourceRef": {
            "type": "string",
            "maxLength": 512,
            "description": "Reference-data source URI."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "studentId",
          "subjectId",
          "canonicalTermId",
          "normsSet",
          "rit",
          "effectiveGrade",
          "calculatorVersion",
          "updatedAt"
        ]
      },
      "MasteryLedger": {
        "type": "object",
        "properties": {
          "masteryLedgerId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Natural id of this ledger row."
          },
          "studentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster student identity (tenant-carrying composite FK).",
            "x-references": "oneroster:user.sourcedId",
            "x-onDelete": "restrict"
          },
          "subjectId": {
            "type": "string",
            "enum": [
              "math",
              "reading",
              "language",
              "science",
              "vocabulary",
              "writing"
            ],
            "description": "Canonical subject id, set at write time."
          },
          "resultRecordId": {
            "type": "string",
            "maxLength": 128,
            "description": "FK to the owning result record.",
            "x-references": "resultRecord.resultRecordId",
            "x-onDelete": "restrict"
          },
          "gateContentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Hook-validated loose ref toward content — NOT a DB FK."
          },
          "trackId": {
            "type": "string",
            "maxLength": 256,
            "description": "Loose curriculum track ref."
          },
          "trackLevelId": {
            "type": "string",
            "maxLength": 256,
            "description": "Curriculum track level ref (loose runtime ref)."
          },
          "gradeLevel": {
            "type": "integer",
            "minimum": -1,
            "maximum": 13,
            "description": "Typed integer grade position (PreK=-1, K=0, 1..13)."
          },
          "scorePercent": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Score as a percentage (0-100)."
          },
          "masteryCutoffPolicyRef": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Provenance stamp: alpha.policy.mastery_cutoff:<policyVersion> read from curriculum at write time."
          },
          "passedMasteryGate": {
            "type": "boolean",
            "description": "Whether scorePercent met the policy cutoff at write time."
          },
          "attemptedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the gate was attempted."
          },
          "effectiveDate": {
            "type": "string",
            "format": "date",
            "description": "The ledger fact's effective date (as-of reads key on it)."
          },
          "supersededByMasteryLedgerId": {
            "type": "string",
            "maxLength": 128,
            "description": "Self-ref to the superseding ledger row (append-only corrections).",
            "x-references": "masteryLedger.masteryLedgerId",
            "x-onDelete": "restrict"
          },
          "sourceEvidenceRefs": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Producer evidence pointers (jsonb)."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "masteryLedgerId",
          "studentId",
          "subjectId",
          "gateContentId",
          "gradeLevel",
          "scorePercent",
          "masteryCutoffPolicyRef",
          "passedMasteryGate",
          "attemptedAt",
          "effectiveDate",
          "updatedAt"
        ]
      },
      "ReportCardEntry": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Server-generated unique identifier for this effective-dated period row.",
            "readOnly": true
          },
          "studentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster student identity (tenant-carrying composite FK).",
            "x-references": "oneroster:user.sourcedId",
            "x-onDelete": "restrict"
          },
          "subjectId": {
            "type": "string",
            "enum": [
              "math",
              "reading",
              "language",
              "science",
              "vocabulary",
              "writing"
            ],
            "description": "Canonical subject id, set at write time."
          },
          "canonicalTermId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Canonical academic term id."
          },
          "gradeLabel": {
            "type": "string",
            "maxLength": 64,
            "description": "Surfaced letter/label grade."
          },
          "scorePercent": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Score as a percentage (0-100)."
          },
          "workingGradeSnapshot": {
            "type": "number",
            "description": "Working grade snapshot at entry time (derivation lives in the computed read)."
          },
          "comments": {
            "type": "string",
            "maxLength": 4096,
            "description": "Free-text report-card comments."
          },
          "beginDate": {
            "type": "string",
            "format": "date",
            "description": "Period start (effective-dated from bound; required)."
          },
          "endDate": {
            "type": "string",
            "format": "date",
            "description": "Period end, EXCLUSIVE (half-open); NULL = open current period."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "studentId",
          "subjectId",
          "canonicalTermId",
          "beginDate",
          "updatedAt"
        ]
      },
      "ResultContentEvidence": {
        "type": "object",
        "properties": {
          "resultContentEvidenceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Natural id of this content evidence row."
          },
          "resultRecordId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "FK to the owning result record.",
            "x-references": "resultRecord.resultRecordId",
            "x-onDelete": "restrict"
          },
          "contentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Content ref (hook-validated loose ref toward content)."
          },
          "validationOutcome": {
            "type": "string",
            "enum": [
              "validated",
              "failed"
            ],
            "description": "Whether the content validated against this result."
          },
          "evidenceWeight": {
            "type": "number",
            "minimum": 0,
            "description": "Relative weight of this evidence signal."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "resultContentEvidenceId",
          "resultRecordId",
          "contentId",
          "validationOutcome",
          "updatedAt"
        ]
      },
      "ResultKcEvidence": {
        "type": "object",
        "properties": {
          "resultKcEvidenceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Natural id of this KC evidence row."
          },
          "resultRecordId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "FK to the owning result record.",
            "x-references": "resultRecord.resultRecordId",
            "x-onDelete": "restrict"
          },
          "kcId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Loose curriculum KC ref."
          },
          "evidenceKind": {
            "type": "string",
            "enum": [
              "correct_answer",
              "incorrect_answer",
              "mastery_gate",
              "observation"
            ],
            "description": "Typed evidence classification."
          },
          "scorePercent": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Score as a percentage (0-100)."
          },
          "evidenceWeight": {
            "type": "number",
            "minimum": 0,
            "description": "Relative weight of this evidence signal."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "resultKcEvidenceId",
          "resultRecordId",
          "kcId",
          "evidenceKind",
          "updatedAt"
        ]
      },
      "ResultRecord": {
        "type": "object",
        "properties": {
          "resultRecordId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "FK to the owning result record."
          },
          "studentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster student identity (tenant-carrying composite FK).",
            "x-references": "oneroster:user.sourcedId",
            "x-onDelete": "restrict"
          },
          "studentEmail": {
            "type": "string",
            "maxLength": 320,
            "description": "Producer-supplied student email (quasi-identifying)."
          },
          "sourceSourcedId": {
            "type": "string",
            "maxLength": 256,
            "description": "Producer-side sourcedId of the outcome, when it has one."
          },
          "resultKind": {
            "type": "string",
            "enum": [
              "self_paced",
              "external_assessment",
              "learning_app_outcome",
              "legacy_assessment",
              "question_result",
              "map",
              "mastery_gate",
              "mastery_visibility",
              "gradebook"
            ],
            "description": "Governed enum, two partitions. Public kinds are writable via POST /result-records; adapter-owned kinds only via the import door."
          },
          "outcomeStatus": {
            "type": "string",
            "enum": [
              "fully_graded",
              "partially_graded",
              "submitted",
              "not_submitted",
              "exempt",
              "deleted"
            ],
            "description": "Typed outcome status vocabulary, normalized and typed at write time.",
            "default": "fully_graded"
          },
          "sourceKind": {
            "type": "string",
            "maxLength": 128,
            "description": "Producer-shape classification stamped by the door."
          },
          "gradebookLineItemId": {
            "type": "string",
            "maxLength": 256,
            "description": "FK to the OneRoster gradebook line item.",
            "x-references": "oneroster:lineItem.sourcedId",
            "x-onDelete": "restrict"
          },
          "contentId": {
            "type": "string",
            "maxLength": 256,
            "description": "Hook-validated loose ref to content:contentItem — NOT a DB FK."
          },
          "testFamilyId": {
            "type": "string",
            "maxLength": 256,
            "description": "Assessment family/series identifier."
          },
          "subjectId": {
            "type": "string",
            "enum": [
              "math",
              "reading",
              "language",
              "science",
              "vocabulary",
              "writing"
            ],
            "description": "Canonical 6-value report subject; set at write time, aliases rejected."
          },
          "canonicalTermId": {
            "type": "string",
            "maxLength": 128,
            "description": "Canonical academic term id."
          },
          "occurredOn": {
            "type": "string",
            "format": "date",
            "description": "The date the outcome occurred (date grain)."
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the event occurred (producer clock)."
          },
          "score": {
            "type": "number",
            "description": "Raw score value."
          },
          "scorePercent": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Score as a percentage (0-100)."
          },
          "textScore": {
            "type": "string",
            "maxLength": 256,
            "description": "Text score when the scale is non-numeric."
          },
          "masteryCutoffMet": {
            "type": "boolean",
            "description": "Whether scorePercent met the curriculum-policy mastery cutoff at write time (never an inline 89.5)."
          },
          "isCorrect": {
            "type": "boolean",
            "description": "Whether the response was correct."
          },
          "canonicalResponse": {
            "type": "object",
            "description": "Producer canonical response payload (jsonb)."
          },
          "sourceAdapterId": {
            "type": "string",
            "maxLength": 128,
            "description": "FK to the registered source adapter.",
            "x-references": "sourceAdapter.sourceAdapterId",
            "x-onDelete": "restrict"
          },
          "producerResultId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "The producer's own result identifier."
          },
          "supersededByResultRecordId": {
            "type": "string",
            "maxLength": 128,
            "description": "Self-ref to the superseding record.",
            "x-references": "resultRecord.resultRecordId",
            "x-onDelete": "restrict"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "resultRecordId",
          "studentId",
          "resultKind",
          "subjectId",
          "occurredOn",
          "sourceAdapterId",
          "producerResultId",
          "updatedAt"
        ]
      },
      "ResultSourceEvidence": {
        "type": "object",
        "properties": {
          "sourceEvidenceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Natural id of this evidence row."
          },
          "resultRecordId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "FK to the owning result record.",
            "x-references": "resultRecord.resultRecordId",
            "x-onDelete": "restrict"
          },
          "sourceAdapterId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "FK to the registered source adapter.",
            "x-references": "sourceAdapter.sourceAdapterId",
            "x-onDelete": "restrict"
          },
          "upstreamTable": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Upstream producer table/collection name."
          },
          "upstreamKey": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "Upstream row key within the producer table."
          },
          "producerResultId": {
            "type": "string",
            "maxLength": 256,
            "description": "The producer's own result identifier."
          },
          "rawPayloadHash": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "sha256:<hex> of the raw producer row."
          },
          "canonicalPayloadHash": {
            "type": "string",
            "maxLength": 128,
            "description": "sha256 of the canonicalized payload, when the adapter writes one."
          },
          "rawPayload": {
            "type": "object",
            "description": "The raw producer row (jsonb) for reconciliation."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "sourceEvidenceId",
          "resultRecordId",
          "sourceAdapterId",
          "upstreamTable",
          "upstreamKey",
          "rawPayloadHash",
          "updatedAt"
        ]
      },
      "SourceAdapter": {
        "type": "object",
        "properties": {
          "sourceAdapterId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Natural adapter id (e.g. adapter-timeback-prod)."
          },
          "adapterKind": {
            "type": "string",
            "enum": [
              "qti_scorer",
              "nwea_map",
              "migration",
              "learning_app",
              "manual"
            ],
            "description": "Typed adapter classification."
          },
          "displayName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Human-readable adapter name."
          },
          "writesCanonicalResponse": {
            "type": "boolean",
            "description": "Whether this producer supplies canonicalResponse payloads.",
            "default": false
          },
          "active": {
            "type": "boolean",
            "description": "Whether the adapter may currently write.",
            "default": true
          },
          "lastSuccessAt": {
            "type": "string",
            "format": "date-time",
            "description": "Set by the import door on each accepted batch."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "sourceAdapterId",
          "adapterKind",
          "displayName",
          "updatedAt"
        ]
      },
      "StudentKcState": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Server-generated unique identifier for this effective-dated period row.",
            "readOnly": true
          },
          "studentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster student identity (tenant-carrying composite FK).",
            "x-references": "oneroster:user.sourcedId",
            "x-onDelete": "restrict"
          },
          "kcId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Knowledge-component ref (loose curriculum ref)."
          },
          "subjectId": {
            "type": "string",
            "enum": [
              "math",
              "reading",
              "language",
              "science",
              "vocabulary",
              "writing"
            ],
            "description": "Canonical subject id, set at write time."
          },
          "masteryStatus": {
            "type": "string",
            "enum": [
              "not_started",
              "in_progress",
              "mastered",
              "regressed"
            ],
            "description": "Typed KC mastery status for the period."
          },
          "scorePercent": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Score as a percentage (0-100)."
          },
          "attemptCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Attempts observed in the period."
          },
          "lastResultRecordId": {
            "type": "string",
            "maxLength": 128,
            "description": "FK to the most recent contributing result record.",
            "x-references": "resultRecord.resultRecordId",
            "x-onDelete": "restrict"
          },
          "beginDate": {
            "type": "string",
            "format": "date",
            "description": "Period start (effective-dated from bound; required)."
          },
          "endDate": {
            "type": "string",
            "format": "date",
            "description": "Exclusive; NULL = open current period."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "studentId",
          "kcId",
          "masteryStatus",
          "beginDate",
          "updatedAt"
        ]
      },
      "StudentTrackState": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Server-generated unique identifier for this effective-dated period row.",
            "readOnly": true
          },
          "studentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster student identity (tenant-carrying composite FK).",
            "x-references": "oneroster:user.sourcedId",
            "x-onDelete": "restrict"
          },
          "subjectId": {
            "type": "string",
            "enum": [
              "math",
              "reading",
              "language",
              "science",
              "vocabulary",
              "writing"
            ],
            "description": "Canonical subject id, set at write time."
          },
          "trackId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Curriculum track ref (loose runtime ref)."
          },
          "currentTrackLevelId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Current curriculum track level (loose ref)."
          },
          "currentSegmentId": {
            "type": "string",
            "maxLength": 256,
            "description": "Current segment within the track level (loose ref)."
          },
          "placementEvidence": {
            "type": "object",
            "description": "Method + evidence refs for the placement (working-grade case, ledger ids, policy version)."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "switched",
              "completed"
            ],
            "description": "Receipt status."
          },
          "switchedToTrackId": {
            "type": "string",
            "maxLength": 256,
            "description": "Track switched to, when status=switched."
          },
          "effectiveAt": {
            "type": "string",
            "format": "date-time",
            "description": "Instant the placement took effect."
          },
          "beginDate": {
            "type": "string",
            "format": "date",
            "description": "Period start (effective-dated from bound; required)."
          },
          "endDate": {
            "type": "string",
            "format": "date",
            "description": "Period end, EXCLUSIVE (half-open); NULL = open current period."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "studentId",
          "subjectId",
          "trackId",
          "currentTrackLevelId",
          "status",
          "beginDate",
          "updatedAt"
        ]
      },
      "TestResultComponent": {
        "type": "object",
        "properties": {
          "testResultComponentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Natural id of this component row."
          },
          "resultRecordId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "FK to the owning result record.",
            "x-references": "resultRecord.resultRecordId",
            "x-onDelete": "restrict"
          },
          "parentTestResultComponentId": {
            "type": "string",
            "maxLength": 128,
            "description": "Self-ref to the parent component (test > section > part > question).",
            "x-references": "testResultComponent.testResultComponentId",
            "x-onDelete": "restrict"
          },
          "componentRole": {
            "type": "string",
            "enum": [
              "test",
              "section",
              "part",
              "question"
            ],
            "description": "Typed component role in the result anatomy."
          },
          "sequenceIndex": {
            "type": "integer",
            "minimum": 0,
            "description": "Zero-based ordering within the parent component."
          },
          "contentId": {
            "type": "string",
            "maxLength": 256,
            "description": "Content ref (hook-validated loose ref toward content)."
          },
          "responseValue": {
            "type": "string",
            "maxLength": 4096,
            "description": "The learner's raw response value."
          },
          "isCorrect": {
            "type": "boolean",
            "description": "Whether the response was correct."
          },
          "scorePercent": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Score as a percentage (0-100)."
          },
          "rubricScore": {
            "type": "number",
            "description": "Rubric-scaled score where applicable."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "testResultComponentId",
          "resultRecordId",
          "componentRole",
          "updatedAt"
        ]
      },
      "XpLedger": {
        "type": "object",
        "properties": {
          "xpAwardId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Natural id of this XP award."
          },
          "studentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster student identity (tenant-carrying composite FK).",
            "x-references": "oneroster:user.sourcedId",
            "x-onDelete": "restrict"
          },
          "resultRecordId": {
            "type": "string",
            "maxLength": 128,
            "description": "FK to the owning result record.",
            "x-references": "resultRecord.resultRecordId",
            "x-onDelete": "restrict"
          },
          "contentId": {
            "type": "string",
            "maxLength": 256,
            "description": "Hook-validated loose ref toward content."
          },
          "subjectId": {
            "type": "string",
            "enum": [
              "math",
              "reading",
              "language",
              "science",
              "vocabulary",
              "writing",
              "fastmath"
            ],
            "description": "xpSubject 7-value enum — fastmath is first-class here."
          },
          "expectedXpRef": {
            "type": "object",
            "description": "Provenance of the expected-XP input: { expectedXp, source: source_expected_xp|source_xp|adapter_default, policyRef }."
          },
          "awardedXp": {
            "type": "number",
            "description": "± XP (negative for reversal/insincere)."
          },
          "awardReason": {
            "type": "string",
            "enum": [
              "verified_attempt",
              "reversal",
              "insincere_effort",
              "adjustment"
            ],
            "description": "Typed award reason."
          },
          "calculationPolicyRef": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Curriculum policy provenance (alpha.policy.xp_award:<version>) — never an inline formula constant."
          },
          "sourceEvidenceRefs": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Producer evidence pointers (jsonb)."
          },
          "occurredOn": {
            "type": "string",
            "format": "date",
            "description": "The date the outcome occurred (date grain)."
          },
          "reversalOfXpAwardId": {
            "type": "string",
            "maxLength": 128,
            "description": "Self-ref to the award this row reverses.",
            "x-references": "xpLedger.xpAwardId",
            "x-onDelete": "restrict"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update."
          }
        },
        "required": [
          "xpAwardId",
          "studentId",
          "subjectId",
          "awardedXp",
          "awardReason",
          "calculationPolicyRef",
          "occurredOn",
          "updatedAt"
        ]
      },
      "CreateAiGradingAuditRequest": {
        "type": "object",
        "description": "Create-AiGradingAudit request body (readOnly/server-managed fields excluded).",
        "required": [
          "aiGradingAuditId",
          "resultRecordId",
          "gradingStage",
          "gradingStatus"
        ],
        "additionalProperties": false,
        "properties": {
          "aiGradingAuditId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Natural id of this audit row."
          },
          "resultRecordId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "FK to the owning result record.",
            "x-references": "resultRecord.resultRecordId",
            "x-onDelete": "restrict"
          },
          "testResultComponentId": {
            "type": "string",
            "maxLength": 128,
            "description": "Natural id of this component row.",
            "x-references": "testResultComponent.testResultComponentId",
            "x-onDelete": "restrict"
          },
          "gradingStage": {
            "type": "string",
            "enum": [
              "initial",
              "regrade",
              "appeal",
              "human_override"
            ],
            "description": "Which grading pass this row records."
          },
          "gradingStatus": {
            "type": "string",
            "enum": [
              "pending",
              "completed",
              "failed",
              "overridden"
            ],
            "description": "Outcome status of the grading pass."
          },
          "aiProvider": {
            "type": "string",
            "maxLength": 128,
            "description": "AI provider that graded (e.g. openai)."
          },
          "aiModel": {
            "type": "string",
            "maxLength": 128,
            "description": "Model name used to grade."
          },
          "modelVersion": {
            "type": "string",
            "maxLength": 128,
            "description": "Model version stamp."
          },
          "promptHash": {
            "type": "string",
            "maxLength": 128,
            "description": "sha256 of the grading prompt (provenance)."
          },
          "rubricVersion": {
            "type": "string",
            "maxLength": 128,
            "description": "Rubric version applied."
          },
          "humanOverrideBy": {
            "type": "string",
            "maxLength": 256,
            "description": "Who overrode the AI grade (audit)."
          },
          "humanOverrideReason": {
            "type": "string",
            "maxLength": 1024,
            "description": "Why the AI grade was overridden."
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the event occurred (producer clock)."
          },
          "supersedesAiGradingAuditId": {
            "type": "string",
            "maxLength": 128,
            "description": "Self-ref to the audit row this one supersedes (regrade chain).",
            "x-references": "aiGradingAudit.aiGradingAuditId",
            "x-onDelete": "restrict"
          }
        }
      },
      "CreateGatePassRequest": {
        "type": "object",
        "description": "Create-GatePass request body (readOnly/server-managed fields excluded).",
        "required": [
          "studentId",
          "subjectId",
          "gateContentId",
          "gateStatus",
          "passedAt",
          "attemptCount",
          "policyVersion",
          "beginDate"
        ],
        "additionalProperties": false,
        "properties": {
          "studentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster student identity (tenant-carrying composite FK).",
            "x-references": "oneroster:user.sourcedId",
            "x-onDelete": "restrict"
          },
          "subjectId": {
            "type": "string",
            "enum": [
              "math",
              "reading",
              "language",
              "science",
              "vocabulary",
              "writing"
            ],
            "description": "Canonical subject id, set at write time."
          },
          "gateContentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Gate content ref (hook-validated loose ref)."
          },
          "resultRecordId": {
            "type": "string",
            "maxLength": 128,
            "description": "FK to the owning result record.",
            "x-references": "resultRecord.resultRecordId",
            "x-onDelete": "restrict"
          },
          "gateStatus": {
            "type": "string",
            "enum": [
              "passed",
              "revoked"
            ],
            "description": "Pass state for the period."
          },
          "passedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the gate was passed."
          },
          "nextEligibleAt": {
            "type": "string",
            "format": "date-time",
            "description": "Retake-cooldown eligibility instant (policy-derived)."
          },
          "attemptCount": {
            "type": "integer",
            "minimum": 1,
            "description": "Attempts observed in the period."
          },
          "policyVersion": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Provenance: the mastery-gate policy ref applied at pass time."
          },
          "beginDate": {
            "type": "string",
            "format": "date",
            "description": "Period start (effective-dated from bound; required)."
          },
          "endDate": {
            "type": "string",
            "format": "date",
            "description": "Period end, EXCLUSIVE (half-open); NULL = open current period."
          }
        }
      },
      "UpdateGatePassRequest": {
        "type": "object",
        "description": "Update-GatePass request body (partial — all fields optional; readOnly + immutable fields excluded; null clears a nullable column).",
        "additionalProperties": false,
        "properties": {
          "resultRecordId": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128,
            "description": "FK to the owning result record.",
            "x-references": "resultRecord.resultRecordId",
            "x-onDelete": "restrict"
          },
          "gateStatus": {
            "type": "string",
            "enum": [
              "passed",
              "revoked"
            ],
            "description": "Pass state for the period."
          },
          "passedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the gate was passed."
          },
          "nextEligibleAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Retake-cooldown eligibility instant (policy-derived)."
          },
          "attemptCount": {
            "type": "integer",
            "minimum": 1,
            "description": "Attempts observed in the period."
          },
          "policyVersion": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Provenance: the mastery-gate policy ref applied at pass time."
          },
          "beginDate": {
            "type": "string",
            "format": "date",
            "description": "Period start (effective-dated from bound; required)."
          },
          "endDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Period end, EXCLUSIVE (half-open); NULL = open current period."
          }
        }
      },
      "CreateGradebookCategoryRequest": {
        "type": "object",
        "description": "Create-GradebookCategory request body (readOnly/server-managed fields excluded).",
        "required": [
          "sourcedId",
          "name"
        ],
        "additionalProperties": false,
        "properties": {
          "sourcedId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster natural key (pass-through — PK leg)."
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "The human-readable title of the category."
          }
        }
      },
      "CreateGradebookLineItemRequest": {
        "type": "object",
        "description": "Create-GradebookLineItem request body (readOnly/server-managed fields excluded).",
        "required": [
          "sourcedId",
          "title",
          "classId",
          "categoryId",
          "assignDate",
          "dueDate"
        ],
        "additionalProperties": false,
        "properties": {
          "sourcedId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster natural key (pass-through — PK leg)."
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "The human-readable title of the line item."
          },
          "description": {
            "type": "string",
            "maxLength": 2048,
            "description": "A description of the line item."
          },
          "classId": {
            "type": "string",
            "maxLength": 256,
            "description": "The sourcedId of the class this line item belongs to."
          },
          "categoryId": {
            "type": "string",
            "maxLength": 256,
            "description": "The sourcedId of the category this line item belongs to."
          },
          "assignDate": {
            "type": "string",
            "format": "date",
            "description": "The date this line item was assigned."
          },
          "dueDate": {
            "type": "string",
            "format": "date",
            "description": "The date this line item is due."
          },
          "resultValueMin": {
            "type": "number",
            "description": "The minimum possible score for results on this line item."
          },
          "resultValueMax": {
            "type": "number",
            "description": "The maximum possible score for results on this line item."
          }
        }
      },
      "CreateGradebookResultRequest": {
        "type": "object",
        "description": "Create-GradebookResult request body (readOnly/server-managed fields excluded).",
        "required": [
          "sourcedId",
          "lineItemId",
          "studentId"
        ],
        "additionalProperties": false,
        "properties": {
          "sourcedId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster natural key (pass-through — PK leg)."
          },
          "lineItemId": {
            "type": "string",
            "maxLength": 256,
            "description": "The sourcedId of the line item this result is for."
          },
          "studentId": {
            "type": "string",
            "maxLength": 256,
            "description": "The sourcedId of the student user who received this result."
          },
          "scoreValue": {
            "type": "number",
            "description": "The numeric score value."
          },
          "scoreStatus": {
            "type": "string",
            "enum": [
              "fully_graded",
              "partially_graded",
              "not_submitted",
              "submitted",
              "exempt"
            ],
            "description": "Typed snake_case enum over the OneRoster spaced vocabulary (two-way valueMap)."
          },
          "comment": {
            "type": "string",
            "maxLength": 2048,
            "description": "Teacher comment on this result."
          }
        }
      },
      "CreateGradebookScoreScaleRequest": {
        "type": "object",
        "description": "Create-GradebookScoreScale request body (readOnly/server-managed fields excluded).",
        "required": [
          "sourcedId",
          "name"
        ],
        "additionalProperties": false,
        "properties": {
          "sourcedId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster natural key (pass-through — PK leg)."
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "The human-readable title of the score scale."
          }
        }
      },
      "CreateGradebookScoreScaleValueRequest": {
        "type": "object",
        "description": "Create-GradebookScoreScaleValue request body (readOnly/server-managed fields excluded).",
        "required": [
          "sourcedId",
          "scoreScaleId",
          "value"
        ],
        "additionalProperties": false,
        "properties": {
          "sourcedId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster natural key (pass-through — PK leg)."
          },
          "scoreScaleId": {
            "type": "string",
            "maxLength": 256,
            "description": "The sourcedId of the parent score scale."
          },
          "value": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "The display value (e.g. A, B+, Pass)."
          },
          "lowerBound": {
            "type": "number",
            "description": "The lower bound of the numeric range for this value."
          },
          "upperBound": {
            "type": "number",
            "description": "The upper bound of the numeric range for this value."
          }
        }
      },
      "CreateMapEffectiveGradeRequest": {
        "type": "object",
        "description": "Create-MapEffectiveGrade request body (readOnly/server-managed fields excluded).",
        "required": [
          "studentId",
          "subjectId",
          "canonicalTermId",
          "normsSet",
          "rit",
          "effectiveGrade",
          "calculatorVersion"
        ],
        "additionalProperties": false,
        "properties": {
          "studentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster student identity (tenant-carrying composite FK).",
            "x-references": "oneroster:user.sourcedId",
            "x-onDelete": "restrict"
          },
          "subjectId": {
            "type": "string",
            "enum": [
              "math",
              "reading",
              "language",
              "science",
              "vocabulary",
              "writing"
            ],
            "description": "Canonical subject id, set at write time."
          },
          "canonicalTermId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Canonical academic term id."
          },
          "normsSet": {
            "type": "string",
            "enum": [
              "2020",
              "2025"
            ],
            "description": "NWEA norms edition."
          },
          "rit": {
            "type": "number",
            "description": "The observed RIT score."
          },
          "rit50Grade": {
            "type": "number",
            "description": "Grade position at the 50th percentile (from the nweamap reference)."
          },
          "rit90Grade": {
            "type": "number",
            "description": "Grade position at the 90th percentile (from the nweamap reference)."
          },
          "effectiveGrade": {
            "type": "integer",
            "minimum": -1,
            "maximum": 13,
            "description": "Effective instructional grade from the shared alpha-rules calculator."
          },
          "calculatorVersion": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Version stamp of the effective-grade calculator (provenance)."
          },
          "sourceRef": {
            "type": "string",
            "maxLength": 512,
            "description": "Reference-data source URI."
          }
        }
      },
      "CreateMasteryLedgerRequest": {
        "type": "object",
        "description": "Create-MasteryLedger request body (readOnly/server-managed fields excluded).",
        "required": [
          "masteryLedgerId",
          "studentId",
          "subjectId",
          "gateContentId",
          "gradeLevel",
          "scorePercent",
          "masteryCutoffPolicyRef",
          "passedMasteryGate",
          "attemptedAt",
          "effectiveDate"
        ],
        "additionalProperties": false,
        "properties": {
          "masteryLedgerId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Natural id of this ledger row."
          },
          "studentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster student identity (tenant-carrying composite FK).",
            "x-references": "oneroster:user.sourcedId",
            "x-onDelete": "restrict"
          },
          "subjectId": {
            "type": "string",
            "enum": [
              "math",
              "reading",
              "language",
              "science",
              "vocabulary",
              "writing"
            ],
            "description": "Canonical subject id, set at write time."
          },
          "resultRecordId": {
            "type": "string",
            "maxLength": 128,
            "description": "FK to the owning result record.",
            "x-references": "resultRecord.resultRecordId",
            "x-onDelete": "restrict"
          },
          "gateContentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Hook-validated loose ref toward content — NOT a DB FK."
          },
          "trackId": {
            "type": "string",
            "maxLength": 256,
            "description": "Loose curriculum track ref."
          },
          "trackLevelId": {
            "type": "string",
            "maxLength": 256,
            "description": "Curriculum track level ref (loose runtime ref)."
          },
          "gradeLevel": {
            "type": "integer",
            "minimum": -1,
            "maximum": 13,
            "description": "Typed integer grade position (PreK=-1, K=0, 1..13)."
          },
          "scorePercent": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Score as a percentage (0-100)."
          },
          "masteryCutoffPolicyRef": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Provenance stamp: alpha.policy.mastery_cutoff:<policyVersion> read from curriculum at write time."
          },
          "passedMasteryGate": {
            "type": "boolean",
            "description": "Whether scorePercent met the policy cutoff at write time."
          },
          "attemptedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the gate was attempted."
          },
          "effectiveDate": {
            "type": "string",
            "format": "date",
            "description": "The ledger fact's effective date (as-of reads key on it)."
          },
          "supersededByMasteryLedgerId": {
            "type": "string",
            "maxLength": 128,
            "description": "Self-ref to the superseding ledger row (append-only corrections).",
            "x-references": "masteryLedger.masteryLedgerId",
            "x-onDelete": "restrict"
          },
          "sourceEvidenceRefs": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Producer evidence pointers (jsonb)."
          }
        }
      },
      "CreateReportCardEntryRequest": {
        "type": "object",
        "description": "Create-ReportCardEntry request body (readOnly/server-managed fields excluded).",
        "required": [
          "studentId",
          "subjectId",
          "canonicalTermId",
          "beginDate"
        ],
        "additionalProperties": false,
        "properties": {
          "studentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster student identity (tenant-carrying composite FK).",
            "x-references": "oneroster:user.sourcedId",
            "x-onDelete": "restrict"
          },
          "subjectId": {
            "type": "string",
            "enum": [
              "math",
              "reading",
              "language",
              "science",
              "vocabulary",
              "writing"
            ],
            "description": "Canonical subject id, set at write time."
          },
          "canonicalTermId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Canonical academic term id."
          },
          "gradeLabel": {
            "type": "string",
            "maxLength": 64,
            "description": "Surfaced letter/label grade."
          },
          "scorePercent": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Score as a percentage (0-100)."
          },
          "workingGradeSnapshot": {
            "type": "number",
            "description": "Working grade snapshot at entry time (derivation lives in the computed read)."
          },
          "comments": {
            "type": "string",
            "maxLength": 4096,
            "description": "Free-text report-card comments."
          },
          "beginDate": {
            "type": "string",
            "format": "date",
            "description": "Period start (effective-dated from bound; required)."
          },
          "endDate": {
            "type": "string",
            "format": "date",
            "description": "Period end, EXCLUSIVE (half-open); NULL = open current period."
          }
        }
      },
      "UpdateReportCardEntryRequest": {
        "type": "object",
        "description": "Update-ReportCardEntry request body (partial — all fields optional; readOnly + immutable fields excluded; null clears a nullable column).",
        "additionalProperties": false,
        "properties": {
          "gradeLabel": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 64,
            "description": "Surfaced letter/label grade."
          },
          "scorePercent": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 100,
            "description": "Score as a percentage (0-100)."
          },
          "workingGradeSnapshot": {
            "type": [
              "number",
              "null"
            ],
            "description": "Working grade snapshot at entry time (derivation lives in the computed read)."
          },
          "comments": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 4096,
            "description": "Free-text report-card comments."
          },
          "beginDate": {
            "type": "string",
            "format": "date",
            "description": "Period start (effective-dated from bound; required)."
          },
          "endDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Period end, EXCLUSIVE (half-open); NULL = open current period."
          }
        }
      },
      "CreateResultRecordRequest": {
        "type": "object",
        "description": "Create-ResultRecord request body (readOnly/server-managed fields excluded).",
        "required": [
          "resultRecordId",
          "studentId",
          "resultKind",
          "subjectId",
          "occurredOn",
          "sourceAdapterId",
          "producerResultId"
        ],
        "additionalProperties": false,
        "properties": {
          "resultRecordId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "FK to the owning result record."
          },
          "studentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster student identity (tenant-carrying composite FK).",
            "x-references": "oneroster:user.sourcedId",
            "x-onDelete": "restrict"
          },
          "studentEmail": {
            "type": "string",
            "maxLength": 320,
            "description": "Producer-supplied student email (quasi-identifying)."
          },
          "sourceSourcedId": {
            "type": "string",
            "maxLength": 256,
            "description": "Producer-side sourcedId of the outcome, when it has one."
          },
          "resultKind": {
            "type": "string",
            "enum": [
              "self_paced",
              "external_assessment",
              "learning_app_outcome",
              "legacy_assessment",
              "question_result",
              "map",
              "mastery_gate",
              "mastery_visibility",
              "gradebook"
            ],
            "description": "Governed enum, two partitions. Public kinds are writable via POST /result-records; adapter-owned kinds only via the import door."
          },
          "outcomeStatus": {
            "type": "string",
            "enum": [
              "fully_graded",
              "partially_graded",
              "submitted",
              "not_submitted",
              "exempt",
              "deleted"
            ],
            "description": "Typed outcome status vocabulary, normalized and typed at write time.",
            "default": "fully_graded"
          },
          "sourceKind": {
            "type": "string",
            "maxLength": 128,
            "description": "Producer-shape classification stamped by the door."
          },
          "gradebookLineItemId": {
            "type": "string",
            "maxLength": 256,
            "description": "FK to the OneRoster gradebook line item.",
            "x-references": "oneroster:lineItem.sourcedId",
            "x-onDelete": "restrict"
          },
          "contentId": {
            "type": "string",
            "maxLength": 256,
            "description": "Hook-validated loose ref to content:contentItem — NOT a DB FK."
          },
          "testFamilyId": {
            "type": "string",
            "maxLength": 256,
            "description": "Assessment family/series identifier."
          },
          "subjectId": {
            "type": "string",
            "enum": [
              "math",
              "reading",
              "language",
              "science",
              "vocabulary",
              "writing"
            ],
            "description": "Canonical 6-value report subject; set at write time, aliases rejected."
          },
          "canonicalTermId": {
            "type": "string",
            "maxLength": 128,
            "description": "Canonical academic term id."
          },
          "occurredOn": {
            "type": "string",
            "format": "date",
            "description": "The date the outcome occurred (date grain)."
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the event occurred (producer clock)."
          },
          "score": {
            "type": "number",
            "description": "Raw score value."
          },
          "scorePercent": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Score as a percentage (0-100)."
          },
          "textScore": {
            "type": "string",
            "maxLength": 256,
            "description": "Text score when the scale is non-numeric."
          },
          "masteryCutoffMet": {
            "type": "boolean",
            "description": "Whether scorePercent met the curriculum-policy mastery cutoff at write time (never an inline 89.5)."
          },
          "isCorrect": {
            "type": "boolean",
            "description": "Whether the response was correct."
          },
          "canonicalResponse": {
            "type": "object",
            "description": "Producer canonical response payload (jsonb)."
          },
          "sourceAdapterId": {
            "type": "string",
            "maxLength": 128,
            "description": "FK to the registered source adapter.",
            "x-references": "sourceAdapter.sourceAdapterId",
            "x-onDelete": "restrict"
          },
          "producerResultId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "The producer's own result identifier."
          },
          "supersededByResultRecordId": {
            "type": "string",
            "maxLength": 128,
            "description": "Self-ref to the superseding record.",
            "x-references": "resultRecord.resultRecordId",
            "x-onDelete": "restrict"
          }
        }
      },
      "UpdateResultRecordRequest": {
        "type": "object",
        "description": "Update-ResultRecord request body (partial — all fields optional; readOnly + immutable fields excluded; null clears a nullable column).",
        "additionalProperties": false,
        "properties": {
          "studentEmail": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 320,
            "description": "Producer-supplied student email (quasi-identifying)."
          },
          "sourceSourcedId": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 256,
            "description": "Producer-side sourcedId of the outcome, when it has one."
          },
          "outcomeStatus": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "fully_graded",
              "partially_graded",
              "submitted",
              "not_submitted",
              "exempt",
              "deleted",
              null
            ],
            "description": "Typed outcome status vocabulary, normalized and typed at write time.",
            "default": "fully_graded"
          },
          "sourceKind": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128,
            "description": "Producer-shape classification stamped by the door."
          },
          "gradebookLineItemId": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 256,
            "description": "FK to the OneRoster gradebook line item.",
            "x-references": "oneroster:lineItem.sourcedId",
            "x-onDelete": "restrict"
          },
          "contentId": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 256,
            "description": "Hook-validated loose ref to content:contentItem — NOT a DB FK."
          },
          "testFamilyId": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 256,
            "description": "Assessment family/series identifier."
          },
          "subjectId": {
            "type": "string",
            "enum": [
              "math",
              "reading",
              "language",
              "science",
              "vocabulary",
              "writing"
            ],
            "description": "Canonical 6-value report subject; set at write time, aliases rejected."
          },
          "canonicalTermId": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128,
            "description": "Canonical academic term id."
          },
          "occurredOn": {
            "type": "string",
            "format": "date",
            "description": "The date the outcome occurred (date grain)."
          },
          "occurredAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the event occurred (producer clock)."
          },
          "score": {
            "type": [
              "number",
              "null"
            ],
            "description": "Raw score value."
          },
          "scorePercent": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 100,
            "description": "Score as a percentage (0-100)."
          },
          "textScore": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 256,
            "description": "Text score when the scale is non-numeric."
          },
          "masteryCutoffMet": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether scorePercent met the curriculum-policy mastery cutoff at write time (never an inline 89.5)."
          },
          "isCorrect": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether the response was correct."
          },
          "canonicalResponse": {
            "type": [
              "object",
              "null"
            ],
            "description": "Producer canonical response payload (jsonb)."
          },
          "supersededByResultRecordId": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128,
            "description": "Self-ref to the superseding record.",
            "x-references": "resultRecord.resultRecordId",
            "x-onDelete": "restrict"
          }
        }
      },
      "CreateSourceAdapterRequest": {
        "type": "object",
        "description": "Create-SourceAdapter request body (readOnly/server-managed fields excluded).",
        "required": [
          "sourceAdapterId",
          "adapterKind",
          "displayName"
        ],
        "additionalProperties": false,
        "properties": {
          "sourceAdapterId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Natural adapter id (e.g. adapter-timeback-prod)."
          },
          "adapterKind": {
            "type": "string",
            "enum": [
              "qti_scorer",
              "nwea_map",
              "migration",
              "learning_app",
              "manual"
            ],
            "description": "Typed adapter classification."
          },
          "displayName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Human-readable adapter name."
          },
          "writesCanonicalResponse": {
            "type": "boolean",
            "description": "Whether this producer supplies canonicalResponse payloads.",
            "default": false
          },
          "active": {
            "type": "boolean",
            "description": "Whether the adapter may currently write.",
            "default": true
          },
          "lastSuccessAt": {
            "type": "string",
            "format": "date-time",
            "description": "Set by the import door on each accepted batch."
          }
        }
      },
      "UpdateSourceAdapterRequest": {
        "type": "object",
        "description": "Update-SourceAdapter request body (partial — all fields optional; readOnly + immutable fields excluded; null clears a nullable column).",
        "additionalProperties": false,
        "properties": {
          "adapterKind": {
            "type": "string",
            "enum": [
              "qti_scorer",
              "nwea_map",
              "migration",
              "learning_app",
              "manual"
            ],
            "description": "Typed adapter classification."
          },
          "displayName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Human-readable adapter name."
          },
          "writesCanonicalResponse": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether this producer supplies canonicalResponse payloads.",
            "default": false
          },
          "active": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether the adapter may currently write.",
            "default": true
          },
          "lastSuccessAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Set by the import door on each accepted batch."
          }
        }
      },
      "CreateStudentKcStateRequest": {
        "type": "object",
        "description": "Create-StudentKcState request body (readOnly/server-managed fields excluded).",
        "required": [
          "studentId",
          "kcId",
          "masteryStatus",
          "beginDate"
        ],
        "additionalProperties": false,
        "properties": {
          "studentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster student identity (tenant-carrying composite FK).",
            "x-references": "oneroster:user.sourcedId",
            "x-onDelete": "restrict"
          },
          "kcId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Knowledge-component ref (loose curriculum ref)."
          },
          "subjectId": {
            "type": "string",
            "enum": [
              "math",
              "reading",
              "language",
              "science",
              "vocabulary",
              "writing"
            ],
            "description": "Canonical subject id, set at write time."
          },
          "masteryStatus": {
            "type": "string",
            "enum": [
              "not_started",
              "in_progress",
              "mastered",
              "regressed"
            ],
            "description": "Typed KC mastery status for the period."
          },
          "scorePercent": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Score as a percentage (0-100)."
          },
          "attemptCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Attempts observed in the period."
          },
          "lastResultRecordId": {
            "type": "string",
            "maxLength": 128,
            "description": "FK to the most recent contributing result record.",
            "x-references": "resultRecord.resultRecordId",
            "x-onDelete": "restrict"
          },
          "beginDate": {
            "type": "string",
            "format": "date",
            "description": "Period start (effective-dated from bound; required)."
          },
          "endDate": {
            "type": "string",
            "format": "date",
            "description": "Exclusive; NULL = open current period."
          }
        }
      },
      "UpdateStudentKcStateRequest": {
        "type": "object",
        "description": "Update-StudentKcState request body (partial — all fields optional; readOnly + immutable fields excluded; null clears a nullable column).",
        "additionalProperties": false,
        "properties": {
          "subjectId": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "math",
              "reading",
              "language",
              "science",
              "vocabulary",
              "writing",
              null
            ],
            "description": "Canonical subject id, set at write time."
          },
          "masteryStatus": {
            "type": "string",
            "enum": [
              "not_started",
              "in_progress",
              "mastered",
              "regressed"
            ],
            "description": "Typed KC mastery status for the period."
          },
          "scorePercent": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 100,
            "description": "Score as a percentage (0-100)."
          },
          "attemptCount": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "description": "Attempts observed in the period."
          },
          "lastResultRecordId": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128,
            "description": "FK to the most recent contributing result record.",
            "x-references": "resultRecord.resultRecordId",
            "x-onDelete": "restrict"
          },
          "beginDate": {
            "type": "string",
            "format": "date",
            "description": "Period start (effective-dated from bound; required)."
          },
          "endDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Exclusive; NULL = open current period."
          }
        }
      },
      "CreateStudentTrackStateRequest": {
        "type": "object",
        "description": "Create-StudentTrackState request body (readOnly/server-managed fields excluded).",
        "required": [
          "studentId",
          "subjectId",
          "trackId",
          "currentTrackLevelId",
          "status",
          "beginDate"
        ],
        "additionalProperties": false,
        "properties": {
          "studentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster student identity (tenant-carrying composite FK).",
            "x-references": "oneroster:user.sourcedId",
            "x-onDelete": "restrict"
          },
          "subjectId": {
            "type": "string",
            "enum": [
              "math",
              "reading",
              "language",
              "science",
              "vocabulary",
              "writing"
            ],
            "description": "Canonical subject id, set at write time."
          },
          "trackId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Curriculum track ref (loose runtime ref)."
          },
          "currentTrackLevelId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Current curriculum track level (loose ref)."
          },
          "currentSegmentId": {
            "type": "string",
            "maxLength": 256,
            "description": "Current segment within the track level (loose ref)."
          },
          "placementEvidence": {
            "type": "object",
            "description": "Method + evidence refs for the placement (working-grade case, ledger ids, policy version)."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "switched",
              "completed"
            ],
            "description": "Receipt status."
          },
          "switchedToTrackId": {
            "type": "string",
            "maxLength": 256,
            "description": "Track switched to, when status=switched."
          },
          "effectiveAt": {
            "type": "string",
            "format": "date-time",
            "description": "Instant the placement took effect."
          },
          "beginDate": {
            "type": "string",
            "format": "date",
            "description": "Period start (effective-dated from bound; required)."
          },
          "endDate": {
            "type": "string",
            "format": "date",
            "description": "Period end, EXCLUSIVE (half-open); NULL = open current period."
          }
        }
      },
      "UpdateStudentTrackStateRequest": {
        "type": "object",
        "description": "Update-StudentTrackState request body (partial — all fields optional; readOnly + immutable fields excluded; null clears a nullable column).",
        "additionalProperties": false,
        "properties": {
          "subjectId": {
            "type": "string",
            "enum": [
              "math",
              "reading",
              "language",
              "science",
              "vocabulary",
              "writing"
            ],
            "description": "Canonical subject id, set at write time."
          },
          "currentTrackLevelId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Current curriculum track level (loose ref)."
          },
          "currentSegmentId": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 256,
            "description": "Current segment within the track level (loose ref)."
          },
          "placementEvidence": {
            "type": [
              "object",
              "null"
            ],
            "description": "Method + evidence refs for the placement (working-grade case, ledger ids, policy version)."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "switched",
              "completed"
            ],
            "description": "Receipt status."
          },
          "switchedToTrackId": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 256,
            "description": "Track switched to, when status=switched."
          },
          "effectiveAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Instant the placement took effect."
          },
          "beginDate": {
            "type": "string",
            "format": "date",
            "description": "Period start (effective-dated from bound; required)."
          },
          "endDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Period end, EXCLUSIVE (half-open); NULL = open current period."
          }
        }
      },
      "CreateTestResultComponentRequest": {
        "type": "object",
        "description": "Create-TestResultComponent request body (readOnly/server-managed fields excluded).",
        "required": [
          "testResultComponentId",
          "resultRecordId",
          "componentRole"
        ],
        "additionalProperties": false,
        "properties": {
          "testResultComponentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Natural id of this component row."
          },
          "resultRecordId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "FK to the owning result record.",
            "x-references": "resultRecord.resultRecordId",
            "x-onDelete": "restrict"
          },
          "parentTestResultComponentId": {
            "type": "string",
            "maxLength": 128,
            "description": "Self-ref to the parent component (test > section > part > question).",
            "x-references": "testResultComponent.testResultComponentId",
            "x-onDelete": "restrict"
          },
          "componentRole": {
            "type": "string",
            "enum": [
              "test",
              "section",
              "part",
              "question"
            ],
            "description": "Typed component role in the result anatomy."
          },
          "sequenceIndex": {
            "type": "integer",
            "minimum": 0,
            "description": "Zero-based ordering within the parent component."
          },
          "contentId": {
            "type": "string",
            "maxLength": 256,
            "description": "Content ref (hook-validated loose ref toward content)."
          },
          "responseValue": {
            "type": "string",
            "maxLength": 4096,
            "description": "The learner's raw response value."
          },
          "isCorrect": {
            "type": "boolean",
            "description": "Whether the response was correct."
          },
          "scorePercent": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Score as a percentage (0-100)."
          },
          "rubricScore": {
            "type": "number",
            "description": "Rubric-scaled score where applicable."
          }
        }
      },
      "CreateXpLedgerRequest": {
        "type": "object",
        "description": "Create-XpLedger request body (readOnly/server-managed fields excluded).",
        "required": [
          "xpAwardId",
          "studentId",
          "subjectId",
          "awardedXp",
          "awardReason",
          "calculationPolicyRef",
          "occurredOn"
        ],
        "additionalProperties": false,
        "properties": {
          "xpAwardId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Natural id of this XP award."
          },
          "studentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "OneRoster student identity (tenant-carrying composite FK).",
            "x-references": "oneroster:user.sourcedId",
            "x-onDelete": "restrict"
          },
          "resultRecordId": {
            "type": "string",
            "maxLength": 128,
            "description": "FK to the owning result record.",
            "x-references": "resultRecord.resultRecordId",
            "x-onDelete": "restrict"
          },
          "contentId": {
            "type": "string",
            "maxLength": 256,
            "description": "Hook-validated loose ref toward content."
          },
          "subjectId": {
            "type": "string",
            "enum": [
              "math",
              "reading",
              "language",
              "science",
              "vocabulary",
              "writing",
              "fastmath"
            ],
            "description": "xpSubject 7-value enum — fastmath is first-class here."
          },
          "expectedXpRef": {
            "type": "object",
            "description": "Provenance of the expected-XP input: { expectedXp, source: source_expected_xp|source_xp|adapter_default, policyRef }."
          },
          "awardedXp": {
            "type": "number",
            "description": "± XP (negative for reversal/insincere)."
          },
          "awardReason": {
            "type": "string",
            "enum": [
              "verified_attempt",
              "reversal",
              "insincere_effort",
              "adjustment"
            ],
            "description": "Typed award reason."
          },
          "calculationPolicyRef": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Curriculum policy provenance (alpha.policy.xp_award:<version>) — never an inline formula constant."
          },
          "sourceEvidenceRefs": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Producer evidence pointers (jsonb)."
          },
          "occurredOn": {
            "type": "string",
            "format": "date",
            "description": "The date the outcome occurred (date grain)."
          },
          "reversalOfXpAwardId": {
            "type": "string",
            "maxLength": 128,
            "description": "Self-ref to the award this row reverses.",
            "x-references": "xpLedger.xpAwardId",
            "x-onDelete": "restrict"
          }
        }
      },
      "Problem": {
        "type": "object",
        "description": "RFC 7807 problem details.",
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "A URI identifying the problem type."
          },
          "title": {
            "type": "string",
            "description": "A short, human-readable summary of the problem."
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status code."
          },
          "detail": {
            "type": "string",
            "description": "A human-readable explanation specific to this occurrence."
          },
          "instance": {
            "type": "string",
            "format": "uri",
            "description": "A URI identifying this occurrence."
          }
        },
        "required": [
          "title",
          "status"
        ]
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "servers": [
    {
      "url": "https://alpha.platform4.alphaschool.dev"
    }
  ]
}