@superbuilders/primer-tives 0.4.0 → 0.6.0

package/README.md

@@ -1,8 +1,19 @@
 # @superbuilders/primer-tives
 
-Client SDK for the Primer adaptive learning engine. Drives a state machine over HTTP POST — the client renders frames, the server controls all routing and assessment.
+Client SDK for the Primer adaptive learning engine.
 
-The SDK has no concept of routines, curricula, or backend storage structure. It advances a student through whatever the server decides to serve next.
+> **Breaking change**: Auth is a server-minted Primer JWT access token. `create()` takes `accessToken` (not `publishableKey`), and `client.start()` is parameterless — the student identity lives in the token's `sub` claim. Mint tokens on your backend via `POST /api/v0/auth/exchange` with your `sk_` and either a Primer-minted `student_id` (provider `native`) or a Timeback OneRoster `sourcedId` (provider `timeback`). The exchange body now uses `student_id` in place of the old `sourced_id`.
+
+This package turns the Primer HTTP protocol into a strongly typed, server-driven state machine. Your app renders the current frame, calls the method that is valid for that frame, and the server decides what comes next.
+
+The SDK does **not** know about routines, curricula, storage schemas, or routing rules. It only knows how to:
+
+- start a student session
+- submit answers or timeouts
+- normalize transport failures into sentinel errors plus `retriable` semantics
+- expose the current step as an ergonomic TypeScript union
+- expose interaction-native review data for feedback rendering
+- preserve full type safety for portable custom interactions (PCIs)
 
 ## Install
 
@@ -12,19 +23,41 @@ bun add @superbuilders/primer-tives
 
 Dependency: `@superbuilders/errors` is installed automatically.
 
+## What you get
+
+- **Single entry point**: `create(config)`
+- **Single wire endpoint**: `POST ${origin}/api/v0/advance`
+- **Single runtime model**: `PrimerState`
+- **Six phases/kinds to handle**:
+  - phases: `observation`, `interaction`, `feedback`, `completed`, `errored`, `fatal`
+  - interaction kinds: `choice`, `text-entry`, `extended-text`, `order`, `match`, `portable-custom`
+- **Typed PCI submissions** driven by the `PciRegistry`
+- **Live in-memory state objects** with action methods like `advance()`, `submitChoice()`, `submitOrder()`, `submitMatch()`, `submit()`, `timeout()`, and `retry()`
+
 ## Quick start
 
 ```ts
-import { create, ErrRateLimited } from "@superbuilders/primer-tives"
 import * as errors from "@superbuilders/errors"
-
+import {
+  create,
+  ErrRateLimited,
+  type PrimerState,
+} from "@superbuilders/primer-tives"
+
+// Mint accessToken on your backend via POST /api/v0/auth/exchange
+// (sk_ + { provider, student_id }) then pass it here. Tokens are short-lived
+// (15 min default).
 const client = create({
-  publishableKey: "pk_live_abc123",
+  accessToken: "<primer JWS minted by /auth/exchange>",
   origin: "https://sb-primer.vercel.app",
-  supportedPcis: ["urn:primer:pci:division-remainder"],
+  supportedPcis: [
+    "urn:primer:pci:division-remainder",
+    "urn:primer:pci:fraction-addition",
+  ],
+  subject: "math",
 })
 
-let state = await client.start("student-uuid")
+let state: PrimerState = await client.start()
 
 while (state.phase !== "completed" && state.phase !== "fatal") {
   switch (state.phase) {
@@ -34,32 +67,64 @@ while (state.phase !== "completed" && state.phase !== "fatal") {
       break
 
     case "interaction":
+      renderStimulus(state.stimulus)
+
       switch (state.kind) {
         case "choice":
           state = await state.submitChoice(["option-a"])
           break
+
         case "text-entry":
           state = await state.submitText("42")
           break
+
         case "extended-text":
           if (state.cardinality === "single") {
             state = await state.submitText("answer")
           } else {
-            state = await state.submitTexts(["a", "b"])
+            state = await state.submitTexts(["first", "second"])
           }
           break
+
+        case "order":
+          state = await state.submitOrder(["choice-1", "choice-2", "choice-3"])
+          break
+
+        case "match":
+          state = await state.submitMatch([
+            { source: "left-1", target: "right-2" },
+            { source: "left-2", target: "right-1" },
+          ])
+          break
+
         case "portable-custom":
-          state = await state.submit({ quotient: "3", remainder: "1" })
+          switch (state.pciId) {
+            case "urn:primer:pci:division-remainder":
+              state = await state.submit({ quotient: "3", remainder: "1" })
+              break
+            case "urn:primer:pci:fraction-addition":
+              state = await state.submit({ numerator: "5", denominator: "6" })
+              break
+          }
           break
       }
       break
 
     case "feedback":
-      renderFeedback(state.isCorrect, state.feedbackContent, state.correctAnswer)
+      renderFeedback({
+        correct: state.isCorrect,
+        content: state.feedbackContent,
+        review: state.review,
+        interaction: state.interaction,
+        submission: state.submission,
+      })
       state = await state.advance()
       break
 
     case "errored":
+      if (!state.retriable) {
+        throw state.error
+      }
       if (errors.is(state.error, ErrRateLimited)) {
         await delay(1000)
       }
@@ -69,229 +134,499 @@ while (state.phase !== "completed" && state.phase !== "fatal") {
 }
 ```
 
-Both `state.phase` and `state.kind` are discriminated unions — TypeScript narrows the type in each `case` branch automatically. The outer switch on `phase` is exhaustive over the 6 states (`observation`, `interaction`, `feedback`, `completed`, `errored`, `fatal`). The inner switch on `kind` is exhaustive over the 4 interaction types (`choice`, `text-entry`, `extended-text`, `portable-custom`).
+Both `state.phase` and `state.kind` are discriminated unions, so TypeScript narrows automatically inside each branch.
 
-## Wire protocol
+## Mental model
 
-Every request is a POST to `https://${origin}/api/v0/advance`:
+Primer is **server-authored**.
 
-```
-POST /api/v0/advance
-Header: Authorization: Bearer pk_...
-Body: { studentId, supportedPcis, intent }
-```
+- The client sends an **intent**: advance, submit, or timeout.
+- The server evaluates that intent and returns the next frame.
+- The SDK wraps that frame in a typed state object.
+- Your UI renders the state and calls the next valid method.
 
-The `origin` field is required and must be the full Primer API base URL (e.g., `https://sb-primer.vercel.app`). All requests are made as absolute URLs so the browser sends the `Origin` header for server-side origin validation. The path constant `ADVANCE_PATH` is exported for reference.
-
-The server identifies the student, determines which content to serve based on the frontend's assigned courses, evaluates submissions, and returns the next frame. The client sends:
-
-- `studentId` — who is being advanced
-- `supportedPcis` — which custom interaction types the renderer can handle
-- `intent` — `{ kind: "observation" }`, `{ kind: "interaction", submission: ... }`, or `{ kind: "timeout" }`
-
-Course resolution is entirely server-side. The publishable key identifies the frontend, and the server looks up which courses are assigned to that frontend. The client has no knowledge of courses, subjects, or form factors.
+In other words, your code does not calculate progression locally. The server owns progression; the SDK owns transport, typing, and ergonomics.
 
 ## Configuration
 
 ```ts
 interface Config<Pcis extends PciId = PciId> {
-  readonly publishableKey: string
+  readonly accessToken: string
   readonly supportedPcis: readonly Pcis[]
   readonly origin: string
+  readonly subject: Subject | "all"
   readonly fetch?: typeof globalThis.fetch
   readonly abort?: AbortController
   readonly logger?: PrimerLogger
 }
+
+type Subject = "math" | "vocabulary"
 ```
 
 | Field | Required | Description |
 |---|---|---|
-| `publishableKey` | yes | Must start with `pk_`. Sent as `Authorization: Bearer pk_...` header |
-| `supportedPcis` | yes | PCI URNs the renderer handles. `[]` if none |
-| `origin` | yes | Base URL for the Primer API (e.g., `https://sb-primer.vercel.app`). All requests are cross-origin to ensure the browser sends the Origin header for server-side validation |
-| `fetch` | no | Custom fetch. Defaults to `globalThis.fetch` |
-| `abort` | no | AbortController for cancelling in-flight requests |
-| `logger` | no | Structured logger (`debug`, `info`, `warn`, `error`) |
+| `accessToken` | yes | Primer JWT minted by your backend via `POST /api/v0/auth/exchange`. Sent as `Authorization: Bearer <jwt>`. Short-lived (15 min default). |
+| `supportedPcis` | yes | PCI URNs the renderer can handle. Use `[]` if none |
+| `origin` | yes | Full Primer API base URL, for example `https://sb-primer.vercel.app` |
+| `subject` | yes | Subject scope for this session. `"math"` or `"vocabulary"` restricts drill selection to courses of that subject; `"all"` disables the filter |
+| `fetch` | no | Custom fetch implementation. Defaults to `globalThis.fetch` |
+| `abort` | no | `AbortController` whose `signal` is passed to every request |
+| `logger` | no | Structured logger with `debug`, `info`, `warn`, and `error` methods |
+
+`create()` does a cheap structural check on the token (must start with `eyJ` and contain exactly two dots) and throws `ErrMalformedAccessToken` if the shape is wrong. Signature verification happens on the server.
+
+### What `subject` controls
 
-`create()` validates the key prefix immediately — throws `ErrMalformedPublishableKey` if invalid.
+`subject` is sent on every `/advance` request and narrows the set of drill courses the server can serve:
+
+- `"math"` / `"vocabulary"` — only drills whose `drill_courses.subject` matches are eligible. The bootstrap router, trigger-driven re-routes, and active-frame lookups all respect the scope.
+- `"all"` — no filter; the server treats the session as federated and may serve drills from any subject the frontend is bound to.
+
+The scope is **per-session**. To switch subjects, construct a new client with a different `subject`; you cannot mutate it on an existing client. Student placements are isolated per subject: a student with an in-progress math placement resumes it when a math-scoped client reconnects, and a vocabulary-scoped client will bootstrap a new placement in that subject without disturbing the math one. If a student submits or times out under a scope that does not match their current placement, the server reports no active frame and the client's next observation bootstraps a fresh placement in the declared subject.
+
+Curriculum routing is not affected by `subject` in this release — only drill selection is scoped.
+
+### Credentials
+
+Each integration has one credential pair:
+
+- **`client_id`** — your Primer frontend ID (a UUIDv7). Not currently required in request bodies; it's embedded in the `sk_` record server-side and surfaced as the `tenant_id` claim on minted JWTs.
+- **`client_secret`** — your `sk_` secret key. Sent as `Authorization: Bearer sk_…` on both `/api/v0/students` and `/api/v0/auth/exchange`. Stored only as a SHA-256 hash at rest — the raw value is returned exactly once at generation time.
+
+Never expose `sk_` keys to the browser. Use them only from your backend.
+
+### Minting a student (native provider)
+
+If your integration does not front a Timeback OneRoster tenant, mint a Primer-native student for each of your users and persist the returned `student_id`. Your users exist in your system; Primer just needs a stable UUID to attach session state to.
+
+```sh
+curl -X POST "$ORIGIN/api/v0/students" \
+  -H "Authorization: Bearer $PRIMER_SECRET_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"grade_level":"9"}'
+```
+
+Response:
+
+```json
+{ "student_id": "019d3e6f-5f6d-7000-8000-..." }
+```
+
+- `grade_level` is required. Valid values: `"K"`, `"1"`, `"2"`, …, `"12"`. Primer routes lessons by grade, so it must be set at mint time.
+- The returned `student_id` is owned by the frontend the `sk_` belongs to. Another frontend's `sk_` cannot exchange for it.
+- Store the `student_id` in your own database keyed by your user. It does not change.
+
+### Minting an access token
+
+`POST /api/v0/auth/exchange` takes your `sk_` bearer and a body describing which student you want a token for.
+
+**Native** (you minted the student via `POST /api/v0/students` above):
+
+```sh
+curl -X POST "$ORIGIN/api/v0/auth/exchange" \
+  -H "Authorization: Bearer $PRIMER_SECRET_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"provider":"native","student_id":"<primer-uuid-you-stored>"}'
+```
+
+**Timeback** (`student_id` carries a OneRoster `sourcedId`):
+
+```sh
+curl -X POST "$ORIGIN/api/v0/auth/exchange" \
+  -H "Authorization: Bearer $PRIMER_SECRET_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"provider":"timeback","student_id":"<oneroster-sourced-id>"}'
+```
+
+The request body is `.strict()` — both `provider` and `student_id` are required and the field names are snake_case. A successful response is:
+
+```ts
+{
+  access_token: string,   // HS256 JWS, use as Bearer for /api/v0/advance
+  token_type: "Bearer",
+  expires_in: 900,        // seconds (15 min default)
+  scope: "frame:advance",
+}
+```
+
+Server-side flow:
+
+1. **Authenticate the `sk_`.** SHA-256 the bearer, look up `iam_frontend_secret_keys.key_hash` with `status = 'active'`. The matching `frontend_id` + `key_id` are captured for the token claims.
+2. **Resolve the student.**
+   - `provider: "native"` — join `iam_frontend_students` on `(frontend_id, student_id)`. If no row exists, return `404 student_not_found`. This stops one frontend from minting tokens against another frontend's UUIDs.
+   - `provider: "timeback"` — look up `iam_student_timeback_identities` by `sourced_id`. If a row exists, reuse the linked `iam_students.id`. Otherwise call Timeback OneRoster, map the grade, and insert `iam_students` + `iam_student_timeback_identities` rows in a single transaction. If OneRoster returns 404, return `404 student_not_found`.
+3. **Mint the JWS.** HS256 with claims `{ sub: <iam_students.id>, tenant_id: <frontend_id>, client_id: <key_id>, scope: "frame:advance", iss: "primer", aud: "primer-api", iat, exp, jti }`. Signed but not encrypted — tamper-proof, not opaque.
+
+Error responses:
+
+| Status | Body                         | Cause                                                                 |
+| ------ | ---------------------------- | --------------------------------------------------------------------- |
+| 401    | `invalid_request`            | Missing/malformed `sk_` bearer                                        |
+| 400    | `invalid_request`            | Body failed schema validation                                          |
+| 404    | `student_not_found`          | Native: no junction row. Timeback: OneRoster returned 404.            |
+| 400    | `unsupported_grade`          | Timeback: OneRoster returned a grade we don't route.                  |
+| 502    | `timeback_unavailable`       | Timeback OneRoster / Cognito failure.                                  |
+
+### Local dev (seeded fixtures)
+
+The Primer repo ships a seed script that populates a self-contained dev tenant so SDK integrators can develop against a real `/api/v0/auth/exchange` without any Timeback/OneRoster credentials. The seed is idempotent: every run tears down and re-creates the `Primer Dev` frontend, re-hashes the current `env.PRIMER_SECRET_KEY`, deletes any previous dev students owned by this frontend, and mints a fresh one with a random UUIDv7.
+
+Run the seed:
+
+```sh
+bun db:seed
+```
+
+This invokes `src/db/scripts/seed/index.ts`, which chains:
+
+- `seedFrontend()` — inserts `iam_frontends { name: "Primer Dev" }` and `iam_frontend_secret_keys { key_hash: sha256(env.PRIMER_SECRET_KEY), key_preview, name: "dev-seed", status: "active" }`.
+- `seedTestCourse(frontendId)` — re-inserts `iam_students { id: HARDCODED_USER.studentId }` (stable dev UUID `019d0000-0000-7000-8000-000000000001`) and an `iam_frontend_students { frontend_id, student_id }` native-ownership row, then binds the frontend to the dev curriculum course.
+
+The dev environment is native-first; the seed does **not** create a `iam_student_timeback_identities` row. If you want to exercise the timeback exchange path against the sandbox, hit it with a real OneRoster `sourcedId` (the first call will provision the junction).
+
+Three fixture values a client needs:
+
+| Fixture            | Value                                            | Source                                                                           |
+| ------------------ | ------------------------------------------------ | -------------------------------------------------------------------------------- |
+| Frontend name      | `Primer Dev`                                     | `DEV_FRONTEND_NAME` in `src/db/scripts/seed/constants.ts`                        |
+| Secret key (`sk_`) | whatever `env.PRIMER_SECRET_KEY` is at seed time | hashed at rest; the raw value is unrecoverable after seeding, so keep it in `.env` |
+| Dev student id     | `019d0000-0000-7000-8000-000000000001`           | `HARDCODED_USER.studentId` in `src/lib/auth/hardcoded-user.ts`                   |
+
+Mint a native access token off the seeded student:
+
+```sh
+curl -X POST "$ORIGIN/api/v0/auth/exchange" \
+  -H "Authorization: Bearer $PRIMER_SECRET_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"provider":"native","student_id":"019d0000-0000-7000-8000-000000000001"}'
+```
+
+Expected response:
+
+```json
+{
+  "access_token": "eyJ...",
+  "token_type": "Bearer",
+  "expires_in": 900,
+  "scope": "frame:advance"
+}
+```
+
+Hand `access_token` to `create({ accessToken, origin, supportedPcis })` and you're up. The repo's root `/` page does this automatically — opening it in the browser after `bun db:seed` renders the SDK against the seeded student.
+
+**Integration contract.** The seed script is the contract. As long as it runs cleanly, nothing on the client side has to change when the Primer auth model evolves — drop the DB, re-run `bun db:seed`, and the same `sk_` keeps working. If a future schema change breaks this guarantee, it breaks the seed first; fix the seed and the contract holds.
+
+### Logger interface
+
+```ts
+interface PrimerLogger {
+  debug(message: string, attributes?: Record<string, unknown>): void
+  info(message: string, attributes?: Record<string, unknown>): void
+  warn(message: string, attributes?: Record<string, unknown>): void
+  error(message: string, attributes?: Record<string, unknown>): void
+}
+```
+
+## Wire protocol
+
+Every request is a `POST` to:
+
+```txt
+${origin}/api/v0/advance
+```
+
+The path constant is exported as:
+
+```ts
+const ADVANCE_PATH = "/api/v0/advance"
+```
+
+### Headers
+
+```txt
+Authorization: Bearer <primer jwt>
+Content-Type: application/json
+```
+
+### Request body
+
+```ts
+interface WireRequestBody<Pcis extends PciId = PciId> {
+  supportedPcis: readonly PciId[]
+  intent: WireIntent<Pcis>
+  subject: Subject | "all"
+}
+```
+
+The student identity is **not** in the body. The server reads it from the verified JWT's `sub` claim.
+
+The `subject` field is required on every request and validated server-side. A missing or invalid value is rejected with `400 invalid_request`.
+
+```ts
+type WireIntent<Pcis extends PciId = PciId> =
+  | { kind: "observation" }
+  | { kind: "interaction"; submission: RendererSubmission<Pcis> }
+  | { kind: "timeout" }
+```
+
+### Response outcomes
+
+Conceptually, the server returns one of three outcomes:
+
+```ts
+type WireResult<Pcis extends PciId = PciId> =
+  | {
+      outcome: "advanced"
+      stimulus: RendererStimulus | null
+      interaction: RendererInteraction<Pcis> | null
+    }
+  | {
+      outcome: "submitted"
+      stimulus: RendererStimulus | null
+      interaction: RendererInteraction<Pcis>
+      submission: RendererSubmission<Pcis>
+      isCorrect: boolean
+      feedbackContent: ContentInline[]
+      review: InteractionReview<Pcis> | null
+    }
+  | { outcome: "completed" }
+```
+
+### Important notes
+
+- `origin` must be the **full base URL**. The SDK constructs requests as `${origin}${ADVANCE_PATH}`.
+- `supportedPcis` is sent on every request so the server knows which portable custom interactions the client can render.
+- The client also uses `supportedPcis` as an inbound safety check: if the server returns a PCI frame the client did not advertise support for, the SDK returns a fatal `ErrUnsupportedPci` state.
 
 ## State machine
 
 `PrimerState` is a discriminated union on `phase`:
 
-```
-observation → interaction → feedback → observation → ... → completed
+```txt
+observation -> interaction -> feedback -> observation -> ... -> completed
      |  \          |  \          |  \
-     ↓   ↘         ↓   ↘         ↓   ↘
+     v   \         v   \         v   \
   errored fatal  errored fatal  errored fatal
 
-errored → (retry) → replays failed action
-interaction timeout → same as submit (server evaluates)
+errored -> retry() -> replays exact failed action
+interaction timeout -> same transport path, intent kind "timeout"
 ```
 
-Any action (`advance()`, `submitChoice()`, `timeout()`, etc.) can fail. Transient failures (network, timeout, 5xx) become `errored` with `retry()`. Permanent failures (401, 403, 404) become `fatal` — session is dead, no recovery.
-
-Calling an action twice (e.g., double-clicking `advance()`) returns the same promise — the SDK memoizes in-flight requests internally. No special handling needed.
-
 ### `observation`
 
-Display-only frame. Show the stimulus, call `advance()`.
+Display-only frame. Render `state.stimulus`, then call `advance()`.
 
 ```ts
+state.phase === "observation"
 state.stimulus  // RendererStimulus | null
 state.advance() // Promise<PrimerState>
 ```
 
-Stimulus is a discriminated union on `type`:
-- `BodyStimulus` — `{ type: "body", body: ContentBlock[] }` — text-only
-- `ImageStimulus` — `{ type: "image", description: ContentInline[], src: string }` — image-backed
-- `null` — no stimulus
-
 ### `interaction`
 
-Student must respond. Discriminate on `state.kind`:
+Student must respond. Discriminate on `state.kind`.
 
-| `state.kind` | Submit | Key fields |
-|---|---|---|
-| `"choice"` | `submitChoice(keys: string[])` | `options`, `maxChoices`, `minChoices` |
-| `"text-entry"` | `submitText(value: string)` | — |
-| `"extended-text"` (single) | `submitText(value: string)` | `cardinality: "single"` |
-| `"extended-text"` (multiple) | `submitTexts(values: string[])` | `cardinality: "multiple"`, `maxStrings`, `minStrings` |
-| `"portable-custom"` | `submit(value: PciValue<K>)` | `pciId`, `properties` |
+All interaction states also expose:
 
-All interaction states also have a `timeout()` method that advances the state machine as if the student ran out of time.
+- `state.stimulus`
+- `state.interaction`
+- `timeout()`
 
-All submit and timeout methods return `Promise<PrimerState>`.
+#### Interaction kinds
 
-Every interaction state carries `interaction.prompt` (`ContentInline[]`) and `interaction.type` (the discriminant matching `state.kind`).
+| `state.kind` | Submit method | Key fields |
+|---|---|---|
+| `"choice"` | `submitChoice(selectedKeys: string[])` | `options`, `minChoices`, `maxChoices` |
+| `"text-entry"` | `submitText(value: string)` | `interaction.base`, `interaction.expectedLength?`, `interaction.patternMask?`, `interaction.placeholderText?` |
+| `"extended-text"` + `cardinality: "single"` | `submitText(value: string)` | `interaction.format`, `interaction.expectedLength?`, `interaction.expectedLines?`, `interaction.patternMask?`, `interaction.placeholderText?` |
+| `"extended-text"` + `cardinality: "multiple"` | `submitTexts(values: string[])` | `minStrings`, `maxStrings`, plus the same metadata as single-cardinality extended text |
+| `"order"` | `submitOrder(orderedKeys: string[])` | `choices`, `minChoices`, `maxChoices`, `interaction.shuffle` |
+| `"match"` | `submitMatch(pairs: Array<{ source: string; target: string }>)` | `sourceChoices`, `targetChoices`, `minAssociations`, `maxAssociations`, `interaction.shuffle` |
+| `"portable-custom"` | `submit(value: PciValue<K>)` | `pciId`, `properties` |
 
 ### `feedback`
 
-Server evaluated the submission. Show result, call `advance()`.
+The server has evaluated the submission. Render feedback, then call `advance()`.
 
 ```ts
+state.phase === "feedback"
 state.stimulus         // RendererStimulus | null
-state.interaction      // the original interaction
-state.submission       // the student's submission
+state.interaction      // RendererInteraction<Pcis>
+state.submission       // RendererSubmission<Pcis>
 state.isCorrect        // boolean
 state.feedbackContent  // ContentInline[]
-state.correctAnswer    // RendererCorrectAnswer | null
+state.review           // InteractionReview<Pcis> | null
 state.advance()        // Promise<PrimerState>
 ```
 
-`correctAnswer` carries the canonical correct response, or `null` when unavailable:
+`review` is interaction-native feedback data when available:
 
 ```ts
-type RendererCorrectScalarValue =
-  | { kind: "identifier"; value: string }
-  | { kind: "string"; value: string }
-  | { kind: "integer"; value: number }
-  | { kind: "float"; value: number }
-
-type RendererCorrectAnswer =
-  | { kind: "single"; value: RendererCorrectScalarValue | null }
-  | { kind: "multiple"; values: RendererCorrectScalarValue[] }
+type InteractionReview<Pcis extends PciId = PciId> =
+  | { type: "choice"; correctKeys: string[] }
+  | { type: "text-entry"; correctValue: ReviewScalarValue | null }
+  | { type: "extended-text"; correctValues: ReviewScalarValue[] }
+  | { type: "order"; correctOrder: string[] }
+  | { type: "match"; correctPairs: Array<{ source: string; target: string }> }
   | {
-      kind: "record"
+      type: "portable-custom"
+      pciId: Pcis
       fields: Array<{
         fieldIdentifier: string
-        baseType: "identifier" | "string" | "integer" | "float"
-        value: RendererCorrectScalarValue | null
+        baseType: "identifier" | "string" | "integer" | "float" | "pair"
+        value: ReviewScalarValue | null
       }>
     }
+
+type ReviewScalarValue =
+  | { kind: "identifier"; value: string }
+  | { kind: "string"; value: string }
+  | { kind: "integer"; value: number }
+  | { kind: "float"; value: number }
+  | { kind: "pair"; source: string; target: string }
 ```
 
-For choice interactions, extract correct option identifiers from `kind: "identifier"` scalars. For text-entry, check `kind: "string"` or `kind: "integer"`. For PCI record responses, iterate `fields`. `null` means the server could not determine a correct response.
+Notes:
+
+- `null` means the server did not provide review data.
+- order review preserves ordering directly.
+- match review preserves directional `{ source, target }` pairs directly.
+- PCI review uses record fields and can carry `pair` values without flattening them into strings.
+- `feedback.advance()` uses the same observation intent as `observation.advance()`.
 
 ### `completed`
 
-Session finished. No further actions.
+Session finished successfully. No further actions.
 
 ### `errored`
 
-Transient failure. The request might succeed on retry.
+Recoverable or user-correctable failure.
 
 ```ts
-state.error        // Error sentinel (use errors.is())
-state.failedPhase  // "observation" | "interaction" | "timeout"
-state.retry()      // Promise<PrimerState> — replays exact failed intent
+state.phase === "errored"
+state.error      // Error sentinel
+state.retriable  // boolean
+state.retry()    // Promise<PrimerState>
 ```
 
-Retryable sentinels: `ErrNetwork`, `ErrTimeout`, `ErrRateLimited`, `ErrServerError`, `ErrServiceUnavailable`, `ErrJsonParse`, `ErrConflict`.
+Caller guidance:
+
+- switch on sentinel identity with `errors.is(...)`
+- check `state.retriable` before calling `retry()`
+- non-retriable errored states keep the original sentinel but do not replay the failed action
 
 ### `fatal`
 
-Permanent failure. Session cannot recover. No `retry()`.
+Permanent failure. Session cannot recover.
 
 ```ts
-state.error  // Error sentinel (use errors.is())
+state.phase === "fatal"
+state.error // Error sentinel
 ```
 
-Causes:
-- Invalid publishable key (401 — `ErrInvalidPublishableKey`)
-- Origin not allowed (403 — `ErrForbidden`)
-- Resource not found (404 — `ErrNotFound`)
-- Malformed request (400 — `ErrBadRequest`)
-- Unsupported PCI (422 — `ErrUnsupportedPci`)
+Fatal states can come from:
 
-## Client-side validation
+- malformed request semantics on the server (`400`)
+- missing, invalid, or expired access token (`401`)
+- forbidden (`403`)
+- missing resource (`404`)
+- unsupported PCI (`422`)
+- a successful response that still contains a `portable-custom` frame whose `pciId` is not in `supportedPcis`
+
+## Interaction payloads
+
+```ts
+type PciSubmission<Pcis extends PciId = PciId> = {
+  [K in Pcis]: {
+    type: "portable-custom"
+    pciId: K
+    value: PciValue<K>
+  }
+}[Pcis]
+
+type RendererSubmission<Pcis extends PciId = PciId> =
+  | { type: "choice"; selectedKeys: string[] }
+  | { type: "text-entry"; value: string }
+  | { type: "extended-text"; values: string[] }
+  | { type: "order"; orderedKeys: string[] }
+  | { type: "match"; pairs: Array<{ source: string; target: string }> }
+  | PciSubmission<Pcis>
+```
+
+Notes:
 
-The SDK validates submissions before sending them to the server:
+- single-cardinality extended text is still submitted as `type: "extended-text"` with a one-element `values` array
+- match submissions are directional `{ source, target }` pairs
+- portable custom submissions carry both `pciId` and a typed PCI `value`
 
-**Choice:** rejects fewer than `minChoices`, more than `maxChoices`, duplicates, unknown option identifiers.
+## Client-side validation
 
-**Extended text (multiple):** rejects fewer than `minStrings`, more than `maxStrings`.
+The SDK performs **selective** client-side validation before sending some submissions.
 
-Failed validation returns `errored` (not `fatal`) with `ErrInvalidSubmission`. The original interaction state is still usable — call the submit method again with corrected input. The `retry()` on the errored state replays the same invalid submission and is not useful for validation errors.
+| Interaction kind | Validation performed |
+|---|---|
+| `choice` | min selections, max selections, duplicate keys, unknown option identifiers |
+| `text-entry` | none |
+| `extended-text` + `single` | none |
+| `extended-text` + `multiple` | `minStrings`, `maxStrings` |
+| `order` | min selections, max selections, duplicate keys, unknown choice identifiers |
+| `match` | `minAssociations`, `maxAssociations`, unknown source/target identifiers, and per-choice `matchMin` / `matchMax` caps on both sides |
+| `portable-custom` | no outbound value validation |
+
+If validation fails:
+
+- the submit call resolves to an `errored` state
+- `state.error` will match `ErrInvalidSubmission`
+- `state.retriable` will be `false`
+- the original interaction object is still usable for a corrected resubmission
+- `retry()` returns the same errored state instead of replaying the invalid payload
 
 ## Error sentinels
 
 ```ts
 import * as errors from "@superbuilders/errors"
-import { ErrNetwork, ErrRateLimited } from "@superbuilders/primer-tives"
-
-if (errors.is(state.error, ErrNetwork)) { /* handle */ }
+import {
+  ErrInvalidSubmission,
+  ErrNetwork,
+  ErrRateLimited,
+  ErrUnsupportedPci,
+} from "@superbuilders/primer-tives"
+
+if (errors.is(state.error, ErrNetwork)) {
+  // handle offline / DNS / CORS / fetch failure
+}
 ```
 
-**Retryable** — surface as `errored`, consumer can call `retry()`:
+### Surfaced as `errored`
 
-| Sentinel | Cause |
-|---|---|
-| `ErrNetwork` | Fetch failed (offline, DNS, CORS) |
-| `ErrTimeout` | Request aborted or timed out |
-| `ErrRateLimited` | 429 |
-| `ErrServerError` | 500 or unrecognized 5xx |
-| `ErrServiceUnavailable` | 502/503/504 |
-| `ErrJsonParse` | Response not valid JSON |
-| `ErrConflict` | 409 — server already processed this advance |
-| `ErrInvalidSubmission` | Client-side validation failed |
-
-**Permanent** — surface as `fatal`, session is dead:
-
-| Sentinel | Cause |
+| Sentinel | Meaning | `state.retriable` |
+|---|---|---|
+| `ErrNetwork` | fetch failed before a response was received | `true` |
+| `ErrTimeout` | request was aborted or timed out | `true` |
+| `ErrRateLimited` | `429` | `true` |
+| `ErrServiceUnavailable` | `502`, `503`, or `504` | `true` |
+| `ErrServerError` | any other unhandled HTTP error status | `true` |
+| `ErrJsonParse` | response body was not valid JSON | `true` |
+| `ErrConflict` | `409`, or a local conflicting in-flight action | `true` |
+| `ErrInvalidSubmission` | client-side validation failed | `false` |
+
+### Permanent: surfaced as `fatal`
+
+| Sentinel | Meaning |
 |---|---|
-| `ErrBadRequest` | 400 — malformed request |
-| `ErrInvalidPublishableKey` | 401 — wrong publishable key |
-| `ErrForbidden` | 403 — origin not allowed |
-| `ErrNotFound` | 404 — resource not found |
-| `ErrUnsupportedPci` | 422 — server sent a PCI the client can't handle |
+| `ErrBadRequest` | `400` |
+| `ErrInvalidAccessToken` | `401` with an invalid signature / unknown key / malformed claims |
+| `ErrTokenExpired` | `401` with an `exp` claim in the past |
+| `ErrForbidden` | `403` |
+| `ErrNotFound` | `404` |
+| `ErrUnsupportedPci` | server rejected the request with `422`, or the server returned a PCI frame the client did not advertise in `supportedPcis` |
 
-**Thrown directly** (not wrapped in errored/fatal):
+### Thrown directly
 
-| Sentinel | Cause |
+| Sentinel | Meaning |
 |---|---|
-| `ErrMalformedPublishableKey` | Key doesn't start with `pk_` — thrown by `create()` |
-| `ErrNotSerializable` | Attempted to JSON.stringify PrimerState — thrown by `toJSON()` |
-
-## Submission payloads
-
-```ts
-type RendererSubmission =
-  | { type: "choice"; selectedKeys: string[] }
-  | { type: "text-entry"; value: string }
-  | { type: "extended-text"; values: string[] }
-  | { type: "portable-custom"; pciId: PciId; value: PciValue<PciId> }
-```
+| `ErrMalformedAccessToken` | `create()` received a token whose shape is not a JWS (must start with `eyJ` and contain two dots) |
+| `ErrNotSerializable` | code attempted to serialize a live `PrimerState` |
 
 ## Content format
 
@@ -307,13 +642,44 @@ type ContentInline =
 type ContentBlock = { type: "paragraph"; children: ContentInline[] }
 ```
 
-All three inline variants share the uniform `{ type, value: string }` shape. `ContentSpan` covers HTML-ish rich text formatting. `latex` is for inline math expressions rendered via Temml.
+### Helpers
+
+```ts
+inlinesToPlainText(nodes: ContentInline[]): string
+blocksToPlainText(blocks: ContentBlock[]): string
+```
+
+- `inlinesToPlainText()` strips formatting and concatenates inline values
+- `blocksToPlainText()` flattens block content with newlines between paragraphs
+
+Typical use cases:
+
+- accessibility labels
+- plain-text fallbacks
+- analytics or logging output that should ignore inline formatting
+
+## Stimulus model
+
+```ts
+interface BodyStimulus {
+  type: "body"
+  body: ContentBlock[]
+}
+
+interface ImageStimulus {
+  type: "image"
+  description: ContentInline[]
+  src: string
+}
+
+type RendererStimulus = BodyStimulus | ImageStimulus
+```
 
-`inlinesToPlainText(nodes)` strips inline formatting for accessibility labels. `blocksToPlainText(blocks)` flattens blocks to plain text.
+A frame can also have `stimulus: null`.
 
 ## PCI system
 
-Portable Custom Interactions handle domain-specific input types with full type safety.
+Portable Custom Interactions let Primer serve domain-specific input types while preserving compile-time type safety.
 
 ### Registry
 
@@ -336,31 +702,117 @@ interface PciRegistry {
 ### Type helpers
 
 ```ts
+type PciUrn = `urn:primer:pci:${string}`
 type PciId = keyof PciRegistry & string
-type PciProps<K extends PciId>   // server-provided props
-type PciValue<K extends PciId>   // submission value
+type PciProps<K extends PciId> = PciRegistry[K]["props"]
+type PciValue<K extends PciId> = PciRegistry[K]["value"]
+```
+
+### PCI renderer props
+
+```ts
+type PciRenderProps<K extends PciId> =
+  | {
+      mode: "pending"
+      properties: PciProps<K>
+      onValueChange: (value: PciValue<K> | null) => void
+    }
+  | {
+      mode: "submitted"
+      properties: PciProps<K>
+      submission: PciValue<K>
+      review: Extract<InteractionReview<K>, { type: "portable-custom"; pciId: K }> | null
+    }
 ```
 
 ### Adding a PCI
 
-1. Add entry to `PciRegistry` in `src/pci.ts`
-2. URN format: `urn:primer:pci:<name>`
-3. Include in `supportedPcis` when calling `create()`
-4. Build renderer with `PciRenderProps<"urn:primer:pci:your-pci">`
+1. Add a new entry to `PciRegistry` in `src/pci.ts`
+2. Use the URN format `urn:primer:pci:<name>`
+3. Add that PCI URN to `supportedPcis` when creating the client
+4. Make sure your renderer knows how to render and collect a `PciValue` for that PCI
 
-## Import
+## Import guide
 
 Everything is exported from the package root:
 
 ```ts
-import { create, ADVANCE_PATH } from "@superbuilders/primer-tives"
-import { ErrNetwork, ErrTimeout, ErrUnsupportedPci } from "@superbuilders/primer-tives"
-import { inlinesToPlainText, blocksToPlainText } from "@superbuilders/primer-tives"
-import type { PrimerState, Config, Client, PrimerLogger } from "@superbuilders/primer-tives"
-import type { ContentBlock, ContentInline } from "@superbuilders/primer-tives"
-import type { PciId, PciProps, PciValue, PciRenderProps } from "@superbuilders/primer-tives"
+import {
+  ADVANCE_PATH,
+  ErrConflict,
+  ErrInvalidAccessToken,
+  ErrInvalidSubmission,
+  ErrMalformedAccessToken,
+  ErrNetwork,
+  ErrTimeout,
+  ErrTokenExpired,
+  ErrUnsupportedPci,
+  SUBJECTS,
+  blocksToPlainText,
+  create,
+  inlinesToPlainText,
+} from "@superbuilders/primer-tives"
+
+import type {
+  ChoiceState,
+  Client,
+  Config,
+  ContentBlock,
+  ContentInline,
+  FeedbackState,
+  MatchState,
+  ObservationState,
+  OrderState,
+  PciId,
+  PciProps,
+  PciRenderProps,
+  PciValue,
+  PrimerLogger,
+  PrimerState,
+  RendererInteraction,
+  RendererStimulus,
+  RendererSubmission,
+  Subject,
+  SubjectScope,
+} from "@superbuilders/primer-tives"
 ```
 
-## Non-serializable state
+## Behavioral notes
+
+### States are not serializable
+
+`PrimerState` is live in-memory state that contains closures. Every state object has a poisoned `toJSON()` that throws `ErrNotSerializable`.
+
+Do **not**:
 
-`PrimerState` contains closures. Every state object has a poisoned `toJSON()` that throws `ErrNotSerializable`. Do not persist, stringify, or transfer `PrimerState` — it is ephemeral in-memory state.
+- `JSON.stringify(state)`
+- persist a state object to storage
+- send a state object over the network
+- treat a state object as a durable snapshot
+
+Instead, keep it in memory and render it immediately.
+
+### Repeated actions are deduplicated narrowly
+
+State objects memoize only true re-entry of the same in-flight action.
+
+- calling `advance()` twice on the same observation state returns the same promise
+- calling the same submit method twice with the same payload returns the same promise
+- calling `retry()` twice on the same errored state returns the same promise
+- submit and timeout do **not** alias to each other anymore
+- conflicting in-flight actions surface `ErrConflict` instead of silently reusing the wrong promise
+
+### `start()` is memoized per client instance
+
+A `Client` instance memoizes the first `start()` call and returns the same promise on later calls. In practice, create a fresh client instance per independently managed session.
+
+## Build and publish
+
+The package is built as browser-targeted ESM from `src/index.ts`, emits declaration files, and publishes `dist/` plus this README.
+
+Useful package scripts:
+
+```sh
+bun run build
+bun run typecheck
+```