@superbuilders/primer-tives 1.1.3 → 1.2.0

package/README.md

@@ -6,107 +6,91 @@ TypeScript SDK for the Primer adaptive learning engine.
 bun add @superbuilders/primer-tives
 ```
 
-Dependency note: `@superbuilders/errors` is installed automatically and is used for `errors.try()` / `errors.is()`.
+`@superbuilders/errors` is installed automatically. The SDK throws sentinel-wrapped errors and the recommended consumer pattern uses `errors.try` / `errors.is` / `errors.wrap` from that library.
 
-## Entrypoints
+## Subpaths
 
-| Import | Runs on | Use for |
-|---|---|---|
-| `@superbuilders/primer-tives/server` | your backend | `POST /api/v0/students`, `PATCH /api/v0/students/:id/hints`, `POST /api/v0/auth/exchange`, `POST /api/v0/auth/exchange/timeback` |
-| `@superbuilders/primer-tives/client` | the browser | `POST /api/v0/advance` |
-| `@superbuilders/primer-tives/contracts` | either side | shared interaction/submission types, Zod schemas, optional submission validator |
-| `@superbuilders/primer-tives/errors` | either side | every error sentinel |
-| `@superbuilders/primer-tives` (root) | either side | convenience re-export of `/contracts` + `/errors` |
+Every symbol is exported from exactly one subpath. Import from the subpath that owns the thing you need.
 
-`/server` and `/client` are not on the root — pick the side of the wire you are on and import from its subpath. `/contracts` and `/errors` are wire-neutral and safe on either side.
-
-## Supported student flows
-
-Primer intentionally supports **two** backend-authenticated student flows.
-
-### 1. Primer-native / manual students
-
-Use this when **your system** owns the learner identity.
-
-1. Call `createStudent()` once to mint a stable Primer `studentId`.
-2. Persist that `studentId` in your own database alongside your user record.
-3. **Before the student's first session**, call `setStudentHints(studentId, { gradeLevel })` at least once. Native students are created hint-less, and the first `/advance` call fails without a `gradeLevel` on record.
-4. At each session start, call `exchangeStudentForAccessToken(studentId)`.
-5. Hand the returned `accessToken` to the browser SDK.
-
-### 2. Live-authoritative Timeback students
-
-Use this when **Timeback / OneRoster** remains the live authority for each login.
-
-1. At each session start, call `exchangeTimebackStudentForAccessToken(sourcedId)`.
-2. Primer verifies the learner against Timeback on **every call**.
-3. Primer resolves or provisions the frontend-owned Primer student row behind the scenes.
-4. The call returns both the stable Primer `studentId` and a short-lived `accessToken`.
-5. Hand the returned `accessToken` to the browser SDK.
-
-Persisting the returned `studentId` is fine if you want a stable local foreign key. Session startup for this flow still begins from `sourcedId`, and the returned `accessToken` is the session credential you pass to the browser SDK.
+| Subpath | What it owns |
+|---|---|
+| `@superbuilders/primer-tives/server` | `createPrimerServer` and the four `PrimerServer` methods, the config and return types |
+| `@superbuilders/primer-tives/client` | `create` (browser SDK), the `PrimerState` discriminated union, every `*State` interface, the PCI render props |
+| `@superbuilders/primer-tives/contracts` | wire-shape types (`RendererInteraction`, `RendererSubmission`, `ContentInline`, PCI base types, review types), Zod schemas, the optional submission validator |
+| `@superbuilders/primer-tives/errors` | every error sentinel (`Err…`) |
+| `@superbuilders/primer-tives/logger` | the `PrimerLogger` interface, accepted by both server and client config |
+| `@superbuilders/primer-tives/grade-level` | `GradeLevel` type and the `GRADE_LEVELS` constant |
+| `@superbuilders/primer-tives/subject` | `Subject`, `SubjectScope`, the `SUBJECTS` constant |
 
 ## End-to-end examples
 
-### Native/manual flow
+### Native/manual student flow
 
 ```ts
-// ── your backend ─────────────────────────────────────────────────────
 import * as errors from "@superbuilders/errors"
+import * as logger from "@superbuilders/slog"
+import { createPrimerServer } from "@superbuilders/primer-tives/server"
 import {
-  createPrimerServer,
   ErrBadRequest,
   ErrConflict,
   ErrInvalidSecretKey,
   ErrStudentNotFound
-} from "@superbuilders/primer-tives/server"
+} from "@superbuilders/primer-tives/errors"
 
 const primer = createPrimerServer({
   origin: "https://sb-primer.vercel.app",
-  secretKey: process.env.PRIMER_DEMO_SECRET_KEY!,
-  logger: console
+  secretKey: process.env.PRIMER_DEMO_SECRET_KEY ?? "",
+  logger
 })
 
 // One time per user.
 const createResult = await errors.try(primer.createStudent())
 if (createResult.error) {
   if (errors.is(createResult.error, ErrInvalidSecretKey)) {
-    throw new Error("Primer secret key is invalid")
+    logger.error("primer secret key invalid", { error: createResult.error })
+    throw errors.wrap(createResult.error, "primer client init")
   }
   if (errors.is(createResult.error, ErrConflict)) {
-    throw new Error("This Primer frontend is not provisioned with routable content")
+    logger.error("primer frontend not provisioned", { error: createResult.error })
+    throw errors.wrap(createResult.error, "primer frontend provisioning")
   }
-  throw createResult.error
+  logger.error("primer create student failed", { error: createResult.error })
+  throw errors.wrap(createResult.error, "primer create student")
 }
 const studentId = createResult.data
-// persist `studentId` alongside your own user record
+// persist `studentId` alongside your own user record.
 
 // Required before the first session for native students.
-const hintsResult = await errors.try(
-  primer.setStudentHints(studentId, { gradeLevel: "3" })
-)
+const hintsResult = await errors.try(primer.setStudentHints(studentId, { gradeLevel: "3" }))
 if (hintsResult.error) {
   if (errors.is(hintsResult.error, ErrStudentNotFound)) {
-    throw new Error("Stored Primer student id no longer exists on this frontend")
+    logger.error("primer student id not found on this frontend", {
+      studentId,
+      error: hintsResult.error
+    })
+    throw errors.wrap(hintsResult.error, "primer set hints")
   }
   if (errors.is(hintsResult.error, ErrBadRequest)) {
-    throw new Error("Invalid hint payload (e.g. unsupported gradeLevel)")
+    logger.error("primer hint payload rejected", { error: hintsResult.error })
+    throw errors.wrap(hintsResult.error, "primer set hints")
   }
-  throw hintsResult.error
+  logger.error("primer set hints failed", { error: hintsResult.error })
+  throw errors.wrap(hintsResult.error, "primer set hints")
 }
 
 // Every session start.
-const tokenResult = await errors.try(
-  primer.exchangeStudentForAccessToken(studentId)
-)
+const tokenResult = await errors.try(primer.exchangeStudentForAccessToken(studentId))
 if (tokenResult.error) {
   if (errors.is(tokenResult.error, ErrInvalidSecretKey)) {
-    throw new Error("Primer secret key is invalid")
+    logger.error("primer secret key invalid", { error: tokenResult.error })
+    throw errors.wrap(tokenResult.error, "primer token exchange")
   }
   if (errors.is(tokenResult.error, ErrStudentNotFound)) {
-    throw new Error("Stored Primer student id no longer exists on this frontend")
+    logger.error("primer student id stale", { studentId, error: tokenResult.error })
+    throw errors.wrap(tokenResult.error, "primer token exchange")
   }
-  throw tokenResult.error
+  logger.error("primer token exchange failed", { error: tokenResult.error })
+  throw errors.wrap(tokenResult.error, "primer token exchange")
 }
 
 const { accessToken, expiresInSeconds } = tokenResult.data
@@ -115,58 +99,62 @@ const { accessToken, expiresInSeconds } = tokenResult.data
 ### Live-authoritative Timeback flow
 
 ```ts
-// ── your backend ─────────────────────────────────────────────────────
 import * as errors from "@superbuilders/errors"
+import * as logger from "@superbuilders/slog"
+import { createPrimerServer } from "@superbuilders/primer-tives/server"
 import {
-  createPrimerServer,
   ErrConflict,
   ErrInvalidSecretKey,
   ErrStudentNotFound,
   ErrTimebackUnavailable,
   ErrUnsupportedGrade
-} from "@superbuilders/primer-tives/server"
+} from "@superbuilders/primer-tives/errors"
 
 const primer = createPrimerServer({
   origin: "https://sb-primer.vercel.app",
-  secretKey: process.env.PRIMER_DEMO_SECRET_KEY!,
-  logger: console
+  secretKey: process.env.PRIMER_DEMO_SECRET_KEY ?? "",
+  logger
 })
 
 const sessionResult = await errors.try(
-  primer.exchangeTimebackStudentForAccessToken("student-123")
+  primer.exchangeTimebackStudentForAccessToken(sourcedId)
 )
 if (sessionResult.error) {
   if (errors.is(sessionResult.error, ErrInvalidSecretKey)) {
-    throw new Error("Primer secret key is invalid")
+    logger.error("primer secret key invalid", { error: sessionResult.error })
+    throw errors.wrap(sessionResult.error, "primer timeback exchange")
   }
   if (errors.is(sessionResult.error, ErrStudentNotFound)) {
-    throw new Error("Timeback sourcedId was not found upstream")
+    logger.error("timeback sourcedId not found upstream", {
+      sourcedId,
+      error: sessionResult.error
+    })
+    throw errors.wrap(sessionResult.error, "primer timeback exchange")
   }
   if (errors.is(sessionResult.error, ErrUnsupportedGrade)) {
-    throw new Error("Timeback returned a grade Primer does not support")
+    logger.error("timeback grade outside supported range", { error: sessionResult.error })
+    throw errors.wrap(sessionResult.error, "primer timeback exchange")
   }
   if (errors.is(sessionResult.error, ErrConflict)) {
-    throw new Error("This Primer frontend is not provisioned with routable content")
+    logger.error("primer frontend not provisioned for routing", { error: sessionResult.error })
+    throw errors.wrap(sessionResult.error, "primer timeback exchange")
   }
   if (errors.is(sessionResult.error, ErrTimebackUnavailable)) {
-    throw new Error("Timeback is temporarily unavailable")
+    logger.error("timeback authority temporarily unavailable", { error: sessionResult.error })
+    throw errors.wrap(sessionResult.error, "primer timeback exchange")
   }
-  throw sessionResult.error
+  logger.error("primer timeback exchange failed", { error: sessionResult.error })
+  throw errors.wrap(sessionResult.error, "primer timeback exchange")
 }
 
 const { studentId, accessToken, expiresInSeconds } = sessionResult.data
-// persist `studentId` if you want a stable Primer foreign key
-// use `accessToken` for this session only
 ```
 
 ### Browser flow
 
 ```ts
-// ── your frontend ────────────────────────────────────────────────────
-import {
-  create,
-  type PrimerState
-} from "@superbuilders/primer-tives/client"
+import { create } from "@superbuilders/primer-tives/client"
+import type { PrimerState } from "@superbuilders/primer-tives/client"
 
 const client = create({
   accessToken,
@@ -196,10 +184,9 @@ while (state.phase !== "completed" && state.phase !== "fatal") {
     case "errored":
       if (state.retriable) {
         state = await state.retry()
-      } else {
-        throw state.error
+        break
       }
-      break
+      throw state.error
   }
 }
 ```
@@ -209,29 +196,17 @@ while (state.phase !== "completed" && state.phase !== "fatal") {
 # `/server`
 
 ```ts
-import {
-  createPrimerServer,
-  type PrimerServer,
-  type PrimerServerConfig,
-  type SessionToken,
-  type TimebackSession,
-  type PlacementHints,
-  type PlacementHintsResult,
-  type GradeLevel,
-  GRADE_LEVELS,
-  type PrimerLogger,
-  ErrBadRequest,
-  ErrConflict,
-  ErrExternalAuthorityRequired,
-  ErrInvalidSecretKey,
-  ErrJsonParse,
-  ErrNetwork,
-  ErrServerError,
-  ErrStudentNotFound,
-  ErrTimebackUnavailable,
-  ErrTimeout,
-  ErrUnsupportedGrade
+import { createPrimerServer } from "@superbuilders/primer-tives/server"
+import type {
+  PrimerServer,
+  PrimerServerConfig,
+  SessionToken,
+  TimebackSession,
+  PlacementHints,
+  PlacementHintsResult
 } from "@superbuilders/primer-tives/server"
+import type { PrimerLogger } from "@superbuilders/primer-tives/logger"
+import { GRADE_LEVELS, type GradeLevel } from "@superbuilders/primer-tives/grade-level"
 ```
 
 ## `createPrimerServer(config)`
@@ -242,13 +217,13 @@ interface PrimerServerConfig {
   readonly secretKey: string               // your sk_… key
   readonly fetch?: typeof globalThis.fetch // override (tests, proxies, instrumentation)
   readonly abort?: AbortController         // wired into every request signal
-  readonly logger: PrimerLogger            // required debug/info/warn/error logger (console works)
+  readonly logger: PrimerLogger            // required debug/info/warn/error logger
 }
 
 function createPrimerServer(config: PrimerServerConfig): PrimerServer
 ```
 
-Returns a `PrimerServer` with exactly **four** methods:
+Returns a `PrimerServer` with exactly four methods:
 
 ```ts
 interface PrimerServer {
@@ -261,213 +236,113 @@ interface PrimerServer {
 
 ## Method reference
 
-### `createStudent(): Promise<string>`
-
-Provision a new **frontend-owned Primer student** and return its stable `studentId`.
-
-Use this only for the native/manual flow.
-
-```ts
-const studentId = await primer.createStudent()
-```
+### `createStudent()`
 
-Notes:
+Provision a new frontend-owned Primer student and return its stable `studentId`. Use only for the native/manual flow.
 
-- Call this when your system is the source of truth for learner identity.
-- Persist the returned `studentId` in your own database.
-- **Before the first session**, call `setStudentHints(studentId, { gradeLevel })`. Native students are created without a `gradeLevel`, and `/advance` requires one.
-- Use that stored `studentId` with `exchangeStudentForAccessToken(studentId)` at each session start.
-- `logger` is required. Pass any object implementing `debug/info/warn/error`; `console` is acceptable for basic integrations.
+Persist the returned `studentId` in your own database. Before the student's first session, call `setStudentHints(studentId, { gradeLevel })`.
 
-### `setStudentHints(studentId, hints): Promise<PlacementHintsResult>`
+### `setStudentHints(studentId, hints)`
 
 Partial upsert of a native/manual student's placement-routing hints. Omitted fields are left untouched; the server returns the persisted state after upsert.
 
 ```ts
-const { gradeLevel } = await primer.setStudentHints(studentId, {
-  gradeLevel: "3"
-})
+const { gradeLevel } = await primer.setStudentHints(studentId, { gradeLevel: "3" })
 ```
 
-- **Required** for native/manual students before their first session. Without a `gradeLevel` on record, the first `/advance` call fails server-side.
-- `gradeLevel` is the only hint today; future hint kinds (raw context, interests, etc.) will appear as additional optional fields on `PlacementHints`.
-- Safe to call repeatedly — each call is a partial upsert.
+- Required for native/manual students before their first session. If the browser calls `/advance` without a `gradeLevel` on record, the server returns HTTP 412 `needs_hints` and the SDK surfaces it as `ErrNeedsHints` on a `fatal` state.
+- Safe to call repeatedly. Each call is a partial upsert.
 - Not needed for Timeback-linked students: `exchangeTimebackStudentForAccessToken` syncs the grade level from the authority on every call.
-- Throws `ErrStudentNotFound` if `studentId` is unknown; `ErrBadRequest` if the payload fails validation (e.g., unsupported `gradeLevel`).
-
-### `exchangeStudentForAccessToken(studentId): Promise<SessionToken>`
-
-Mint a short-lived access token for an existing **native/manual** Primer student.
+- Throws `ErrStudentNotFound` if `studentId` is unknown; `ErrBadRequest` if the payload fails validation (e.g. unsupported `gradeLevel`).
 
-```ts
-const { accessToken, expiresInSeconds } =
-  await primer.exchangeStudentForAccessToken(studentId)
-```
+### `exchangeStudentForAccessToken(studentId)`
 
-Call this at **every session start**.
+Mint a short-lived access token for an existing native/manual Primer student. Call at every session start.
 
-Important:
+If `studentId` belongs to a Timeback-linked student, throws `ErrExternalAuthorityRequired`. Tokens are short-lived (typically 15 minutes).
 
-- This is for **native/manual** students only.
-- If `studentId` belongs to a Timeback-linked student, the method throws `ErrExternalAuthorityRequired`.
-- Tokens are short-lived (typically 15 minutes).
+### `exchangeTimebackStudentForAccessToken(sourcedId)`
 
-### `exchangeTimebackStudentForAccessToken(sourcedId): Promise<TimebackSession>`
+Live Timeback session start. Verifies the learner against Timeback on every call, resolves or provisions the corresponding Primer student row, and returns the stable `studentId`, the short-lived `accessToken`, and `expiresInSeconds`.
 
-Perform a **live-authoritative Timeback session start**.
-
-Primer verifies the learner against Timeback on every call, then resolves or provisions the corresponding frontend-owned Primer student and returns:
-
-- the stable Primer `studentId`
-- a short-lived `accessToken`
-- `expiresInSeconds`
-
-```ts
-const { studentId, accessToken, expiresInSeconds } =
-  await primer.exchangeTimebackStudentForAccessToken(sourcedId)
-```
-
-Use this at **every Timeback session start**.
-
-Operational rule:
-
-- Call this at every Timeback session start.
-- Persist `studentId` if you need a stable Primer foreign key in your own system.
-- Use the returned `accessToken` for the active browser session.
+Use at every Timeback session start. Persist `studentId` if you need a stable Primer foreign key.
 
 ## Return types
 
-### `SessionToken`
-
 ```ts
 interface SessionToken {
   readonly accessToken: string
   readonly expiresInSeconds: number
 }
-```
 
-### `TimebackSession`
-
-```ts
 interface TimebackSession {
   readonly studentId: string
   readonly accessToken: string
   readonly expiresInSeconds: number
 }
-```
-
-### `PlacementHints`
 
-```ts
 interface PlacementHints {
   readonly gradeLevel?: GradeLevel
 }
-```
-
-Partial shape: pass only the fields you want to set. Today the only hint is `gradeLevel` (the learner's current grade). Re-export `GRADE_LEVELS` enumerates the supported values.
 
-### `PlacementHintsResult`
-
-```ts
 interface PlacementHintsResult {
   readonly studentId: string
   readonly gradeLevel: GradeLevel | null
 }
 ```
 
-The persisted state after upsert. `gradeLevel` is `null` only on native students who have never had one set.
-
-## Error sentinels (`/server`)
-
-All `/server` methods throw sentinel-wrapped `Error`s. Use `errors.try()` and `errors.is()` from `@superbuilders/errors`.
-
-| Sentinel | Raised when |
-|---|---|
-| `ErrInvalidSecretKey` | HTTP 401 — missing, malformed, or unknown `sk_` |
-| `ErrStudentNotFound` | HTTP 404 — native `studentId` unknown on this frontend, or Timeback `sourcedId` unknown upstream |
-| `ErrUnsupportedGrade` | HTTP 400 — Timeback returned a grade outside Primer's supported range |
-| `ErrTimebackUnavailable` | HTTP 502 — Timeback OneRoster endpoint failed during live exchange |
-| `ErrExternalAuthorityRequired` | HTTP 409 — attempted native/manual exchange for a Timeback-linked student |
-| `ErrConflict` | HTTP 409 — frontend is not provisioned for routing/content |
-| `ErrBadRequest` | HTTP 400 — validation failure |
-| `ErrServerError` | HTTP 5xx |
-| `ErrJsonParse` | Success response body was not valid JSON or had the wrong shape |
-| `ErrNetwork` | fetch() rejected (DNS, connection, TLS, etc.) |
-| `ErrTimeout` | fetch() aborted (your `AbortController` or `TimeoutError`) |
-
-### Recommended error-handling pattern
-
-```ts
-import * as errors from "@superbuilders/errors"
-import {
-  createPrimerServer,
-  ErrExternalAuthorityRequired,
-  ErrInvalidSecretKey,
-  ErrStudentNotFound
-} from "@superbuilders/primer-tives/server"
-
-const primer = createPrimerServer({
-  origin: "https://sb-primer.vercel.app",
-  secretKey: process.env.PRIMER_DEMO_SECRET_KEY!,
-  logger: console
-})
-
-const result = await errors.try(
-  primer.exchangeStudentForAccessToken(studentId)
-)
-if (result.error) {
-  if (errors.is(result.error, ErrInvalidSecretKey)) {
-    // rotate or fix your sk_
-  }
-  if (errors.is(result.error, ErrStudentNotFound)) {
-    // your stored studentId is stale or wrong for this frontend
-  }
-  if (errors.is(result.error, ErrExternalAuthorityRequired)) {
-    // this student must authenticate through live Timeback exchange
-  }
-  throw result.error
-}
-
-const { accessToken } = result.data
-```
+`gradeLevel` in `PlacementHintsResult` is `null` only on native students who have never had one set.
 
 ## Rules of the road
 
-- **Native/manual flow:** `createStudent()` once, then `exchangeStudentForAccessToken(studentId)` every session.
-- **Timeback flow:** `exchangeTimebackStudentForAccessToken(sourcedId)` every session.
-- **Student ids are stable identifiers, not browser credentials.** Always hand the browser a fresh `accessToken` from your backend.
-- **Server-only secrets.** Keep `secretKey` on your backend; never ship it to the browser.
-- **Explicit subpaths only.** Import from `/server` or `/client`, never a package root.
+- Native/manual flow: `createStudent()` once, then `exchangeStudentForAccessToken(studentId)` every session.
+- Timeback flow: `exchangeTimebackStudentForAccessToken(sourcedId)` every session.
+- Student ids are stable identifiers, not browser credentials. Always hand the browser a fresh `accessToken` from your backend.
+- Server-only secrets: keep `secretKey` on your backend; never ship it to the browser.
 
 ---
 
 # `/client`
 
 ```ts
-import {
-  create,
-  type Client,
-  type Config,
-  type PrimerState,
-  type PrimerLogger,
-  type Subject,
-  type SubjectScope,
-  SUBJECTS,
-  ErrRateLimited,
-  // …sentinels + every state/interaction/content/PCI type
+import { create } from "@superbuilders/primer-tives/client"
+import type {
+  Client,
+  Config,
+  PrimerState,
+  ObservationState,
+  InteractionState,
+  ChoiceState,
+  TextEntryState,
+  ExtendedTextState,
+  ExtendedTextSingleState,
+  ExtendedTextMultipleState,
+  OrderState,
+  MatchState,
+  PciInteractionState,
+  FeedbackState,
+  CompletedState,
+  ErroredState,
+  FatalState,
+  NonSerializable,
+  PciPendingRenderProps,
+  PciSubmittedRenderProps,
+  PciRenderProps
 } from "@superbuilders/primer-tives/client"
 ```
 
+The `/client` subpath owns the **runtime state machine** only. Wire-shape types (`RendererInteraction`, `RendererSubmission`, `ContentInline`, PCI base types, review types) come from `/contracts`.
+
 ## `create(config)`
 
 ```ts
 function create<const Pcis extends PciId>(config: Config<Pcis>): Client<Pcis>
 
 interface Config<Pcis extends PciId = PciId> {
-  readonly accessToken: string                 // JWS from /server
-  readonly supportedPcis: readonly Pcis[]      // PCI URNs this renderer handles ([] if none)
-  readonly origin: string                      // same origin you gave /server
-  readonly subject: SubjectScope               // "math" | "vocabulary" | "science" | "all"
+  readonly accessToken: string
+  readonly supportedPcis: readonly Pcis[]
+  readonly origin: string
+  readonly subject: SubjectScope
   readonly fetch?: typeof globalThis.fetch
   readonly abort?: AbortController
   readonly logger?: PrimerLogger
@@ -478,46 +353,23 @@ interface Client<Pcis extends PciId = PciId> {
 }
 ```
 
-`create()` does a cheap structural check on the token (must start with `eyJ` and contain two dots) and throws `ErrMalformedAccessToken` if the shape is wrong. Signature verification happens on the server.
-
-### `subject` scope
-
-| Value | Behavior |
-|---|---|
-| `"math"` / `"vocabulary"` / `"science"` | Restrict drill selection to courses of that subject |
-| `"all"` | No filter; drills from any subject the frontend is bound to |
-
-Per-session. To switch subjects, construct a new client. Student placements are isolated per subject — a student with an in-progress math placement resumes it on a math-scoped reconnect, a new vocabulary-scoped client bootstraps a fresh vocabulary placement, and neither disturbs the other. Curriculum routing is not affected by `subject`.
+`create()` does a structural check on the token (must start with `eyJ` and contain two dots) and throws `ErrMalformedAccessToken` if the shape is wrong. Signature verification happens on the server.
 
 ## `PrimerState` — the state machine
 
-`start()` returns a `PrimerState` union. Each phase has its own shape and action methods.
-
 ```ts
 type PrimerState =
-  | ObservationState                // advance()
-  | InteractionState                // submit…() / timeout()
-  | FeedbackState                   // advance()
-  | CompletedState                  // terminal
-  | ErroredState                    // retry() — retriable:boolean
-  | FatalState                      // terminal
+  | ObservationState     // .advance()
+  | InteractionState     // .submit…() / .timeout()
+  | FeedbackState        // .advance()
+  | CompletedState       // terminal
+  | ErroredState         // .retry() — .retriable: boolean
+  | FatalState           // terminal
 ```
 
-### `observation`
+### Interaction action methods
 
-Server wants you to show a stimulus and the student to indicate they're done reading.
-
-```ts
-interface ObservationState {
-  readonly phase: "observation"
-  readonly stimulus: RendererStimulus | null
-  advance(): Promise<PrimerState>
-}
-```
-
-### `interaction`
-
-Server wants an answer. `InteractionState` is a discriminated union over `kind`:
+`InteractionState` is a discriminated union over `kind`:
 
 | `kind` | method |
 |---|---|
@@ -529,31 +381,31 @@ Server wants an answer. `InteractionState` is a discriminated union over `kind`:
 | `match` | `submitMatch(pairs: MatchPair[])` |
 | `portable-custom` | `submit(value: PciValue<K>)` |
 
-All six shapes also expose `timeout(): Promise<PrimerState>`.
+Every `InteractionState` shape also exposes `timeout(): Promise<PrimerState>`.
 
-### `feedback`
+`MatchPair`, `PciValue<K>` come from `/contracts`.
 
-Server has graded the submission and returned feedback content.
+### `FeedbackState`
 
 ```ts
-interface FeedbackState {
+interface FeedbackState extends NonSerializable {
   readonly phase: "feedback"
   readonly stimulus: RendererStimulus | null
   readonly interaction: RendererInteraction
   readonly submission: RendererSubmission
   readonly isCorrect: boolean
-  readonly feedbackContent: ContentInline[]   // server-provided, localized feedback
-  readonly review: InteractionReview | null   // correct answers etc., if available
+  readonly feedbackContent: ContentInline[]
+  readonly review: InteractionReview | null
   advance(): Promise<PrimerState>
 }
 ```
 
-### `errored`
+`RendererStimulus`, `RendererInteraction`, `RendererSubmission`, `ContentInline`, `InteractionReview` all come from `/contracts`.
 
-Transport or validation failure that might be recoverable.
+### `ErroredState`
 
 ```ts
-interface ErroredState {
+interface ErroredState extends NonSerializable {
   readonly phase: "errored"
   readonly error: Error                       // sentinel-wrapped
   readonly retriable: boolean
@@ -561,109 +413,238 @@ interface ErroredState {
 }
 ```
 
-### `fatal`
+`errored.retriable === false` for client-validation errors (e.g. wrapped `ErrInvalidSubmission`) and for non-recoverable transports. Those must be fixed, not retried.
+
+### `FatalState`
 
-Unrecoverable failure (bad request, invalid token, expired token, unsupported PCI, forbidden).
+Unrecoverable failure (bad request, invalid token, expired token, unsupported PCI, forbidden):
 
 ```ts
-interface FatalState {
+interface FatalState extends NonSerializable {
   readonly phase: "fatal"
   readonly error: Error
   readonly retriable: false
 }
 ```
 
-### `completed`
+## PCI render props
 
-Terminal. Session is done.
+Only the renderer-side render props live here. PCI base types (`PciId`, `PciProps`, `PciValue`, `PciRegistry`, `PciUrn`, plus the per-PCI `*Props`/`*Submission` interfaces) come from `/contracts`.
 
 ```ts
-interface CompletedState {
-  readonly phase: "completed"
+type PciPendingRenderProps<K extends PciId> = {
+  mode: "pending"
+  properties: PciProps<K>
+  onValueChange: (value: PciValue<K> | null) => void
 }
+
+type PciSubmittedRenderProps<K extends PciId> = {
+  mode: "submitted"
+  properties: PciProps<K>
+  submission: PciValue<K>
+  review: Extract<InteractionReview<K>, { type: "portable-custom"; pciId: K }> | null
+}
+
+type PciRenderProps<K extends PciId> = PciPendingRenderProps<K> | PciSubmittedRenderProps<K>
 ```
 
-## Content format
+## Behavioral notes
+
+- `start()` is idempotent — calling it twice returns the same promise.
+- A returning student resumes wherever the server last placed them. No client-side cursor management.
+- `PrimerState` holds real closures (action methods, pending-promise caches). Don't serialize it; don't store it across reloads. Call `start()` again on boot.
+- `Config.supportedPcis` is a `const` generic; only those URNs flow through `PciInteractionState` at the type level. Mismatch at runtime is a `fatal` with `ErrUnsupportedPci`.
+
+---
+
+# `/contracts`
+
+Wire-shape types, Zod schemas, review types, and an optional submission validator. Safe to import from either side of the wire — backend code lives here too.
 
 ```ts
-type ContentSpan =
-  | { type: "text"; value: string }
-  | { type: "italic"; value: string }
+import {
+  ChoiceSubmissionSchema,
+  TextEntrySubmissionSchema,
+  ExtendedTextSubmissionSchema,
+  OrderSubmissionSchema,
+  MatchSubmissionSchema,
+  MatchPairSchema,
+  DivisionRemainderPciSubmissionSchema,
+  FractionAdditionPciSubmissionSchema,
+  RendererSubmissionSchema,
+  validateSubmissionForInteraction,
+  submissionValidationMessage,
+  blocksToPlainText,
+  inlinesToPlainText
+} from "@superbuilders/primer-tives/contracts"
 
-type ContentInline =
-  | ContentSpan
-  | { type: "latex"; value: string }
+import type {
+  // interaction & submission shapes
+  RendererInteraction,
+  RendererSubmission,
+  StandardRendererInteraction,
+  PciInteraction,
+  PciSubmission,
+  // stimulus shapes
+  RendererStimulus,
+  BodyStimulus,
+  ImageStimulus,
+  // choice shapes
+  RendererChoice,
+  RendererMatchChoice,
+  MatchPair,
+  // content
+  ContentBlock,
+  ContentInline,
+  ContentSpan,
+  // PCI base
+  PciId,
+  PciUrn,
+  PciRegistry,
+  PciProps,
+  PciValue,
+  DivisionRemainderProps,
+  DivisionRemainderSubmission,
+  FractionAdditionProps,
+  FractionAdditionSubmission,
+  // review (server emits these, client consumes)
+  InteractionReview,
+  ChoiceReview,
+  TextEntryReview,
+  ExtendedTextReview,
+  OrderReview,
+  MatchReview,
+  PciReview,
+  ReviewRecordField,
+  ReviewRecordFieldBaseType,
+  ReviewScalarValue,
+  // validation result
+  SubmissionValidationResult,
+  SubmissionValidationSuccess,
+  SubmissionValidationFailure
+} from "@superbuilders/primer-tives/contracts"
+```
+
+## Schemas
+
+Every `RendererSubmission` variant has a Zod schema; `RendererSubmissionSchema` is the discriminated union over all of them and is the canonical `safeParse`-able wire shape.
+
+```ts
+import * as errors from "@superbuilders/errors"
+import * as logger from "@superbuilders/slog"
+import { RendererSubmissionSchema } from "@superbuilders/primer-tives/contracts"
 
-type ContentBlock = { type: "paragraph"; children: ContentInline[] }
+const result = RendererSubmissionSchema.safeParse(unknownPayload)
+if (!result.success) {
+  logger.error("submission payload failed schema parse", { issues: result.error.issues })
+  throw errors.wrap(result.error, "renderer submission parse")
+}
+const submission = result.data
 ```
 
-All three inline variants share the uniform `{ type, value: string }` shape. `ContentSpan` covers HTML-ish rich-text formatting. `latex` is for inline math expressions (render via Temml).
+## `validateSubmissionForInteraction(interaction, submission)`
 
-Helpers:
+Optional semantic validator. Checks a submission against the interaction it claims to answer (cardinality bounds, identifier membership, duplicate rules, PCI payload shape).
 
 ```ts
-inlinesToPlainText(nodes: ContentInline[]): string
-blocksToPlainText(blocks: ContentBlock[]): string
+function validateSubmissionForInteraction(
+  interaction: RendererInteraction,
+  submission: RendererSubmission
+): SubmissionValidationResult
+
+type SubmissionValidationResult =
+  | { ok: true;  value: RendererSubmission }
+  | { ok: false; issues: readonly string[] }
 ```
 
-## PCI system (Portable Custom Interactions)
+`submissionValidationMessage(failure)` joins `failure.issues` with `"; "` for a single string.
 
 ```ts
-type PciUrn = "urn:primer:pci:division-remainder" | "urn:primer:pci:fraction-addition"
+import * as errors from "@superbuilders/errors"
+import * as logger from "@superbuilders/slog"
+import {
+  submissionValidationMessage,
+  validateSubmissionForInteraction
+} from "@superbuilders/primer-tives/contracts"
+import { ErrInvalidSubmission } from "@superbuilders/primer-tives/errors"
 
-type PciRegistry = {
-  "urn:primer:pci:division-remainder": {
-    props: DivisionRemainderProps
-    value: DivisionRemainderSubmission
-  }
-  "urn:primer:pci:fraction-addition": {
-    props: FractionAdditionProps
-    value: FractionAdditionSubmission
-  }
+const validation = validateSubmissionForInteraction(interaction, submission)
+if (!validation.ok) {
+  logger.warn("submission rejected by contract validation", { issues: validation.issues })
+  throw errors.wrap(ErrInvalidSubmission, submissionValidationMessage(validation))
 }
-
-type PciId = keyof PciRegistry
-type PciProps<K extends PciId> = PciRegistry[K]["props"]
-type PciValue<K extends PciId> = PciRegistry[K]["value"]
 ```
 
-Declare the PCI URNs your renderer can handle via `Config.supportedPcis`. Frames requiring an unsupported PCI resolve to `fatal` with `ErrUnsupportedPci`.
+Validation is **optional at every layer**. The Primer server grades submissions independently and is the only correctness boundary that matters. The browser SDK's built-in interaction state machines call this validator on your behalf before each submit; if you bypass those state machines and write to the wire yourself, you decide whether to validate.
 
-### Renderer props
+---
 
-```ts
-type PciPendingRenderProps<K extends PciId> = {
-  mode: "pending"
-  properties: PciProps<K>
-  onValueChange: (value: PciValue<K> | null) => void
-}
+# `/errors`
 
-type PciSubmittedRenderProps<K extends PciId> = {
-  mode: "submitted"
-  properties: PciProps<K>
-  submission: PciValue<K>
-  review: Extract<InteractionReview<K>, { type: "portable-custom"; pciId: K }> | null
-}
+Every sentinel `Err…` value used by the SDK lives here and only here. Use `errors.is()` from `@superbuilders/errors` to type-check against them.
 
-type PciRenderProps<K extends PciId> = PciPendingRenderProps<K> | PciSubmittedRenderProps<K>
-```
+```ts
+import {
+  // shared (server + client transport)
+  ErrBadRequest,
+  ErrConflict,
+  ErrJsonParse,
+  ErrNetwork,
+  ErrServerError,
+  ErrTimeout,
+  // /server-thrown
+  ErrInvalidSecretKey,
+  ErrStudentNotFound,
+  ErrUnsupportedGrade,
+  ErrTimebackUnavailable,
+  ErrExternalAuthorityRequired,
+  // /client surfaced as `errored`
+  ErrServiceUnavailable,
+  ErrRateLimited,
+  ErrInvalidSubmission,
+  // /client surfaced as `fatal`
+  ErrInvalidAccessToken,
+  ErrTokenExpired,
+  ErrForbidden,
+  ErrNotFound,
+  ErrNeedsHints,
+  ErrUnsupportedPci,
+  // /client thrown directly by `create()`
+  ErrMalformedAccessToken,
+  ErrNotSerializable
+} from "@superbuilders/primer-tives/errors"
+```
+
+## Server-side method failures
 
-## Error sentinels (`/client`)
+| Sentinel | Raised when |
+|---|---|
+| `ErrInvalidSecretKey` | HTTP 401 — missing, malformed, or unknown `sk_` |
+| `ErrStudentNotFound` | HTTP 404 — native `studentId` unknown on this frontend, or Timeback `sourcedId` unknown upstream |
+| `ErrUnsupportedGrade` | HTTP 400 — Timeback returned a grade outside Primer's supported range |
+| `ErrTimebackUnavailable` | HTTP 502 — Timeback OneRoster endpoint failed during live exchange |
+| `ErrExternalAuthorityRequired` | HTTP 409 — attempted native/manual exchange for a Timeback-linked student |
+| `ErrConflict` | HTTP 409 — frontend not provisioned for routing/content |
+| `ErrBadRequest` | HTTP 400 — validation failure |
+| `ErrServerError` | HTTP 5xx |
+| `ErrJsonParse` | response body was not valid JSON or had the wrong shape |
+| `ErrNetwork` | `fetch()` rejected (DNS, connection, TLS, etc.) |
+| `ErrTimeout` | `fetch()` aborted |
 
-### Surfaced as `errored`
+## Client `errored.error`
 
 | Sentinel | Raised when |
 |---|---|
-| `ErrNetwork` | fetch() rejected |
-| `ErrTimeout` | fetch() aborted |
+| `ErrNetwork` | `fetch()` rejected |
+| `ErrTimeout` | `fetch()` aborted |
 | `ErrServerError` | HTTP 5xx |
 | `ErrServiceUnavailable` | HTTP 502/503/504 |
 | `ErrRateLimited` | HTTP 429 |
 | `ErrConflict` | HTTP 409 |
-| `ErrJsonParse` | Success response body wasn't valid JSON |
+| `ErrJsonParse` | success body wasn't valid JSON |
 | `ErrInvalidSubmission` | client-side validation rejected the submission |
 
-### Surfaced as `fatal`
+## Client `fatal.error`
 
 | Sentinel | Raised when |
 |---|---|
@@ -672,18 +653,59 @@ type PciRenderProps<K extends PciId> = PciPendingRenderProps<K> | PciSubmittedRe
 | `ErrTokenExpired` | HTTP 401 with token-expired detail |
 | `ErrForbidden` | HTTP 403 |
 | `ErrNotFound` | HTTP 404 |
+| `ErrNeedsHints` | HTTP 412 — the student has no `gradeLevel` on record; backend must call `setStudentHints` and mint a fresh access token |
 | `ErrUnsupportedPci` | HTTP 422 or a frame asks for a PCI not in `supportedPcis` |
 
-### Thrown directly by `create()`
+## Thrown directly by `create()`
 
 | Sentinel | Raised when |
 |---|---|
 | `ErrMalformedAccessToken` | token doesn't start with `eyJ` or lacks two dots |
 | `ErrNotSerializable` | you called `JSON.stringify()` on a live `PrimerState` (don't) |
 
-## Logger interface
+## Recommended consumer pattern
+
+Per `@superbuilders/errors`: log every error before throwing, wrap external errors with terse Go-style context, never bare `throw new Error(...)`.
+
+```ts
+import * as errors from "@superbuilders/errors"
+import * as logger from "@superbuilders/slog"
+import {
+  ErrExternalAuthorityRequired,
+  ErrInvalidSecretKey,
+  ErrStudentNotFound
+} from "@superbuilders/primer-tives/errors"
+
+const tokenResult = await errors.try(primer.exchangeStudentForAccessToken(studentId))
+if (tokenResult.error) {
+  if (errors.is(tokenResult.error, ErrInvalidSecretKey)) {
+    logger.error("primer secret key invalid", { error: tokenResult.error })
+    throw errors.wrap(tokenResult.error, "primer token exchange")
+  }
+  if (errors.is(tokenResult.error, ErrStudentNotFound)) {
+    logger.error("primer student id stale", { studentId, error: tokenResult.error })
+    throw errors.wrap(tokenResult.error, "primer token exchange")
+  }
+  if (errors.is(tokenResult.error, ErrExternalAuthorityRequired)) {
+    logger.error("primer student requires timeback exchange", {
+      studentId,
+      error: tokenResult.error
+    })
+    throw errors.wrap(tokenResult.error, "primer token exchange")
+  }
+  logger.error("primer token exchange failed", { error: tokenResult.error })
+  throw errors.wrap(tokenResult.error, "primer token exchange")
+}
+const { accessToken } = tokenResult.data
+```
+
+---
+
+# `/logger`
 
 ```ts
+import type { PrimerLogger } from "@superbuilders/primer-tives/logger"
+
 interface PrimerLogger {
   debug(message: string, attributes?: Record<string, unknown>): void
   info(message: string, attributes?: Record<string, unknown>): void
@@ -692,80 +714,40 @@ interface PrimerLogger {
 }
 ```
 
-Same shape on both sides. Plug in your slog/pino/console adapter.
-
-## Behavioral notes
-
-- **`start()` is idempotent.** Calling it twice returns the same promise.
-- **Retry semantics.** `errored.retry()` re-runs the same intent. `errored.retriable === false` for client-validation errors (e.g. `ErrInvalidSubmission`) — those must be fixed, not retried.
-- **Session resumption.** A returning student resumes wherever the server last placed them. No client-side cursor management.
-- **Live state.** `PrimerState` holds real closures (action methods, pending-promise caches). Don't serialize it; don't store it across reloads. Call `start()` again on boot.
-- **PCI type safety.** `Config.supportedPcis` is a `const` generic; only those URNs flow through `PciInteractionState`/`PciSubmission` at the type level. Mismatch at runtime is a `fatal` with `ErrUnsupportedPci`.
+Required by `PrimerServerConfig`, optional on `Config` (the client config). `@superbuilders/slog` matches this shape directly — `import * as logger from "@superbuilders/slog"` and pass `logger`.
 
 ---
 
-# `/contracts`
-
-Wire-shape types, Zod schemas, and an optional submission validator. Safe to import from either side of the wire.
+# `/grade-level`
 
 ```ts
-import {
-  // schemas
-  ChoiceSubmissionSchema,
-  TextEntrySubmissionSchema,
-  ExtendedTextSubmissionSchema,
-  OrderSubmissionSchema,
-  MatchSubmissionSchema,
-  MatchPairSchema,
-  DivisionRemainderPciSubmissionSchema,
-  FractionAdditionPciSubmissionSchema,
-  RendererSubmissionSchema,
-  // validator
-  validateSubmissionForInteraction,
-  submissionValidationMessage,
-  // types
-  type RendererInteraction,
-  type RendererSubmission,
-  type StandardRendererInteraction,
-  type PciInteraction,
-  type PciSubmission,
-  type BodyStimulus,
-  type ImageStimulus,
-  type MatchPair,
-  type RendererChoice,
-  type RendererMatchChoice,
-  type RendererStimulus,
-  type SubmissionValidationResult,
-  type SubmissionValidationSuccess,
-  type SubmissionValidationFailure
-} from "@superbuilders/primer-tives/contracts"
-```
-
-## Schemas
-
-Every `RendererSubmission` variant has a Zod schema; `RendererSubmissionSchema` is the discriminated union over all of them and is the canonical `safeParse`-able wire shape.
+import { GRADE_LEVELS } from "@superbuilders/primer-tives/grade-level"
+import type { GradeLevel } from "@superbuilders/primer-tives/grade-level"
 
-```ts
-const result = RendererSubmissionSchema.safeParse(unknownPayload)
-if (!result.success) { /* … */ }
-const submission = result.data    // typed as RendererSubmission
+const GRADE_LEVELS = ["K", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12"] as const
+type GradeLevel = (typeof GRADE_LEVELS)[number]
 ```
 
-## `validateSubmissionForInteraction(interaction, submission)`
+Used as the `gradeLevel` field on `PlacementHints` / `PlacementHintsResult`.
 
-Optional semantic validator. Checks a submission against the interaction it claims to answer (cardinality bounds, identifier membership, duplicate rules, PCI payload shape).
+---
+
+# `/subject`
 
 ```ts
-function validateSubmissionForInteraction(
-  interaction: RendererInteraction,
-  submission: RendererSubmission
-): SubmissionValidationResult
+import { SUBJECTS } from "@superbuilders/primer-tives/subject"
+import type { Subject, SubjectScope } from "@superbuilders/primer-tives/subject"
 
-type SubmissionValidationResult =
-  | { ok: true;  value: RendererSubmission }
-  | { ok: false; issues: readonly string[] }
+const SUBJECTS = ["math", "vocabulary", "science"] as const
+type Subject = (typeof SUBJECTS)[number]
+type SubjectScope = Subject | "all"
 ```
 
-`submissionValidationMessage(failure)` joins `failure.issues` with `"; "` for cases where you want a single string.
+Used as the `subject` field on the client `Config`.
 
-Validation is **optional at every layer.** The Primer server grades submissions independently and is the only correctness boundary that matters. The browser SDK's built-in interaction state machines call this validator on your behalf before each submit; if you bypass those state machines and write to the wire yourself, you decide whether to validate.
+| Value | Behavior |
+|---|---|
+| `"math"` / `"vocabulary"` / `"science"` | restrict drill selection to courses of that subject |
+| `"all"` | no filter; drills from any subject the frontend is bound to |
+
+Per-session. To switch subjects, construct a new client. Student placements are isolated per subject — a student with an in-progress math placement resumes it on a math-scoped reconnect, a new vocabulary-scoped client bootstraps a fresh vocabulary placement, and neither disturbs the other. Curriculum routing is not affected by `subject`.