Assign once. Deliver in QTI. Keep every learning fact upstream.

Architecture certification

This is a thin orchestration API, not a second SIS, assessment runtime, or gradebook. Every public operation has an owner, an authoritative read path, a retry contract, and a failure mode that exposes the responsible dependency.

Disposition of the blocking downstream findings

Decision authority is explicit: architecture pins the customer contract; immutable deployment receipts decide release readiness. Absence of an approved callable mastery-engine input is recorded honestly and cannot erase the promised adaptive branch or be disguised as successful integration.

System boundary and ownership

End-to-end flow

AcmeTest            AlphaTest admin        OneRoster     mastery_engine       QTI          Results
   | POST /administrations |                  |                 |              |              |
   |----------------------->| verify test ---->|              |              |                 |
   |                        | resolve target ->|              |              |                 |
   |                        | fixed: create QTI session -------------------->|                 |
   |                        | adaptive: start each candidate ->| create native offer --------->|
   | 202 + administration   |                  |              |              |                 |
   |<-----------------------|                  |              |              |                 |
   | POST /.../candidates/{candidateId}/launch                 |              |                 |
   |----------------------->| enforce launch window; return QTI ref -------->|                 |
   | GET /administrations/{id}?include=candidates             |              |                 |
   |----------------------->| read session/runtime state ------------------->|                 |
   | 200 composed status + launch eligibility                  |              |                 |
   |<-----------------------|                  |              |              |                 |
   | launch QTI player with native deliverySessionRef ---------------------->|                 |
   | POST /.../advance      | adaptive only: token + If-Match ->| read QTI; next offer -------->|
   |                        | read each bound candidate runtime ------------>|                 |
   | authoritative state   |                  |              |              |                 |
   |<-----------------------|                  |              |              |                 |
   | POST /close            | read outcomeState.SCORE ---------------------->|                 |
   |                        | write typed result_record --------------------------------------->|
   |                        | exact ?qtiAttemptId= read-back --------------------------------->|
   | 202 closing; GET → scored |                  |              |              |                 |

Creation is asynchronous for a reason

Resolving a class and provisioning N candidate attempts crosses multiple upstreams. POST therefore returns 202 Accepted once validation, the tenant-scoped orchestration record, candidate bindings, and idempotency receipt are durable. The administration progresses from provisioning to scheduled, or provisioning_with_errors while successful candidates remain usable. POST /{id}/provision resumes only failed candidates with their original child keys.

Public HTTP contract

All routes are JSON under /v1. IDs are opaque. Times are RFC 3339 UTC instants. Platform3-native references remain first-class fields.

Creation shape: class target

{
  "test": { "qtiTestId": "qti_test_…", "contentTestSpecId": "test_spec_…", "testKind": "mastery_gate" },
  "target": { "type": "class", "oneRosterSourcedId": "class_…" },
  "window": { "opensAt": "2026-08-20T13:00:00Z", "closesAt": "2026-08-22T21:00:00Z" },
  "timing": { "timeLimitSeconds": 5400 },
  "retakes": { "maxAttempts": 3, "parallelFormRotation": "different_form_required" },
  "accommodations": {
    "default": { "timeMultiplier": 1 },
    "candidateOverrides": []
  }
}

Creation shape: explicit candidate-list target

{
  "test": { "qtiTestId": "qti_test_…", "contentTestSpecId": "test_spec_…", "testKind": "formative" },
  "target": {
    "type": "candidate_list",
    "oneRosterCandidateSourcedIds": ["user_01…", "user_02…"]
  },
  "window": { "opensAt": "2026-08-20T13:00:00Z", "closesAt": "2026-08-22T21:00:00Z" },
  "timing": { "timeLimitSeconds": 1800 },
  "retakes": { "maxAttempts": 1, "parallelFormRotation": "not_required" },
  "accommodations": { "default": { "timeMultiplier": 1 }, "candidateOverrides": [] }
}

Creation shape: adaptive diagnostic

{
  "test": { "contentTestSpecId": "test_spec_…", "testKind": "adaptive_diagnostic" },
  "target": { "type": "class", "oneRosterSourcedId": "class_…" },
  "adaptiveConfig": {
    "selectionPolicyId": "policy_…",
    "scaleCalibrationId": "calibration_…",
    "testBankId": "test_bank_…",
    "bankOperationId": "bank_operation_…",
    "runMode": "production_learner",
    "resultsStudentBindings": [
      { "candidateSourcedId": "user_01…", "resultsStudentId": "student_01…" },
      { "candidateSourcedId": "user_02…", "resultsStudentId": "student_02…" }
    ]
  },
  "window": { "opensAt": "2026-08-20T13:00:00Z", "closesAt": "2026-08-22T21:00:00Z" },
  "retakes": { "maxAttempts": 2, "parallelFormRotation": "not_applicable" }
}

Administration supplies mastery_engine's exact seven production fields per candidate: the five immutable request pins above, testSpecId from test.contentTestSpecId, runMode, and that candidate's caller-supplied resultsStudentId. It resolves the target live, requires the binding set to match the resolved candidates exactly, and validates each Results reference in the same tenant before persisting anything. It never infers one identity from the other.

Response invariants

• testKind recognizes and SHIPs mastery_gate, adaptive_diagnostic, and formative through one resource. Adaptive validation failures use 422 adaptive-capability-required; attempted owner failures use 424 mastery-engine-unavailable. The removed adaptive-administration-contract-unavailable code is historical and must not appear in implementation.
• Each composed candidate has a OneRoster sourcedId, authoritative QTI state, attemptNumber, and launch eligibility. The raw deliverySessionRef appears only in a successful launch response. After verified close, the candidate includes its upstream resultRecordRef.
• AlphaTest never returns a locally computed score. A missing Results record is explicit reconciliation state, not score: null pretending completion.
• Every response includes requestId; dependency failures identify a stable dependency code without leaking upstream credentials or bodies.

Close request and receipt

POST /v1/administrations/adm_123/close
Authorization: Bearer <platform-jwt>
Idempotency-Key: close-adm-123

{}

202 Accepted
{
  "id": "adm_123",
  "status": "closing",
  "close": { "submittedAttempts": 24, "verifiedResults": 0, "failed": 0 },
  "requestId": "req_..."
}

Close first rejects with 409 close-not-ready when any launched candidate remains in_progress or has no submitted attempt. During closing, deterministic child keys derived from tenant, administration, and QTI attempt make every Results create retry-safe. A retry resumes incomplete candidates; it never creates a second result record. A candidate is verified only when GET /alpha/results/v1/result-records?qtiAttemptId=... resolves exactly one record carrying the same administration_id and complete QTI/Content reference set. QTI or Results failures leave close_failed reconciliation metadata and are retried with the same key; the administration cannot read scored prematurely.

Lifecycle and state authority

Retake selection

The retake endpoint is valid only while the administration is open, the prior attempt is submitted, scored, completed, or has typed adaptive-continuation-expired, and maxAttempts is not exhausted; all other combinations return 409 administration-state-conflict or 409 retake-policy-exhausted. Fixed mastery gates exclude used forms and choose the least-used eligible parallel form with a stable hash tie-breaker. Adaptive diagnostics never reuse a continuation: attempt N+1 calls mastery_engine start with the original immutable configuration, the same validated Results binding, and a fresh deterministic child key.

Security, tenancy, and privacy

• API-fronted datastore model: Supabase service-role credentials remain server-side. Browsers never receive an anon or service-role database key.
• Authentication: verify HS256 bearer JWTs using PLATFORM_JWT_SIGNING_SECRET; require sub, role, tenantId, iat, and exp.
• Authorization: the required standard claims are accepted: a published server-side role mapping grants a maximum permission set, and an optional scope claim may only narrow it. School/class claims further narrow target access. A caller cannot widen access by supplying either a scope or X-Timeback-Tenant.
• Tenant routing: the verified JWT tenantId is authoritative. If X-Timeback-Tenant is present it must exactly match, otherwise 403 tenant-mismatch.
• Query invariant: every local select, update, join, idempotency lookup, and unique constraint begins with tenant ID. Upstream calls carry only the verified tenant context.
• Sensitive references: candidate/session composition requires administrations:read_sensitive; list responses omit delivery-session references.
• Adaptive tokens: continuation JWEs are opaque server-to-server credentials encrypted by mastery_engine. Administration stores the ciphertext, ETag, and expiry only in the candidate-attempt binding, never returns the token to browsers, never logs it, and cannot decrypt or index its claims.
• Deletion and retention: administrations are audit glue and are not publicly deleted in v1. Policy metadata is retained seven years by default; idempotency bodies 24 hours; operational logs 30 days with no response bodies or learner PII.

Upstream reality contract

Production base is https://platform3-andymontgomery-9773s-projects.vercel.app. Concrete adapter paths must be verified against each upstream’s published contract before implementation; they are not guessed here. Deployment uses configured UPSTREAM_* URLs and fails capability checks rather than substituting local fixtures.

Adaptive candidate orchestration release contract

This table composes the approved mastery-engine contract with Administration's now-pinned cross-module rules. Every row is part of the SHIP API contract. The evidence column is the separate production-activation gate.

Important Technical Decisions

Every consequential API axis is pinned SHIP or DEFERRED, including deliberate non-decisions. Each anchor is stable; active decisions are mirrored in commitments.json, while superseded ITDs remain here as audit history.

Requirement and decision traceability

External references studied

• Google General AIPs — numbered, stable, status-bearing decisions across resource, method, field, state, authorization, error, retry, and compatibility axes; the named customer-eval benchmark.
• Microsoft Azure REST API Guidelines — resource modeling, repeatability, long-running operations, client clarity.
• Stripe idempotent requests — concrete safe-retry benchmark.
• 1EdTech OneRoster 1.2 — sourcedId roster ownership, REST exchange, filter/sort model.
• 1EdTech QTI 3 specification set — delivery/scoring interoperability, adaptive and accommodations context.