hapi/shared/fixtures/README.md

# Golden protocol fixtures

Machine-generated conformance fixtures for the HAPI client protocol. The
**web implementation is the source of truth**: every `expected*` value in
every file is produced by running the real web implementation over
hand-authored wire inputs, then applying the normative projection each suite
documents below. Native clients (iOS `HapiProtocol`, Android
`:core:protocol`) port the same logic and must reproduce the expectations
from the inputs exactly.

Three suites:

| Suite | Pins | Web source of truth |
|-------|------|---------------------|
| `chat/` | message decode/render pipeline (normalize → reduce → group) | `web/src/chat/` |
| `sse/` | `session-updated` versioned-patch application | `applySessionDetailPatch` in `web/src/lib/sessionPatch.ts` |
| `pagination/` | message window: paging cursors, epoch resets, optimistic sends, trims | `web/src/lib/message-window-store.ts` + `web/src/lib/messages.ts` |

Never edit the JSON by hand — edit the case definitions in
`web/scripts/fixtures/` (`cases/`, `sse/cases.ts`, `pagination/cases.ts`) and
regenerate.

## Layout

```
shared/fixtures/
├── VERSION                  # current fixtureVersion (single integer + \n)
├── chat/<name>.json         # one fixture per case
├── sse/<name>.json
├── pagination/<name>.json
├── catalogs/modes.json      # reference tables (see Catalogs below)
└── README.md
```

## How to consume (all suites)

- **iOS** (`ios/`, SPM test target): resolve the repo checkout from the test
  file's own location and load every `<suite>/*.json`, e.g.
  `URL(fileURLWithPath: #filePath)` → walk up to the package root →
  `../../shared/fixtures`. Decode the inputs, run the ported implementation,
  project, and compare against the stored expectations.
- **Android** (`android/`, `:core:protocol` JVM tests): pass the directory via
  Gradle — `tasks.withType<Test> { systemProperty("hapi.fixtures.dir",
  rootDir.resolve("../shared/fixtures")) }` — and read it with
  `System.getProperty("hapi.fixtures.dir")` in the test.
- Iterate **all** files in a suite directory (fail on zero files) so newly
  added fixtures are picked up without native-side changes.

### Acceptance bar

Exact match on the normative projection: serialize your computed output and
the fixture's stored expectation to **canonical JSON** (recursively sorted
object keys; numbers as JSON numbers; no `undefined`/absent-key differences)
and compare for equality. Field order in the files is already canonical
(sorted keys, 4-space indent, LF, trailing newline), so a key-sorted
structural deep-compare is equivalent.

### fixtureVersion policy

`fixtureVersion` (mirrored in `VERSION`, shared by all suites) is bumped when
a document schema or a normative projection changes shape. Native suites must
**fail loudly when the on-disk version is newer than the version they
support** (do not silently skip), and should tolerate older versions only if
they explicitly implement them. Additive new fixture *files* and new wire
cases do not bump the version.

---

# Chat suite (`chat/`)

Runs the real web pipeline (`normalizeDecryptedMessage` → `reduceChatBlocks`
→ `buildVisibleChatBlocks`) over wire messages, then projects.

## Document schema (`fixtureVersion: 1`)

```jsonc
{
    "fixtureVersion": 1,
    "name": "claude-assistant-text",        // equals the file name
    "description": "…",
    "input": {
        "messages": [ /* DecryptedMessage[] exactly as GET /sessions/:id/messages returns them */ ],
        "agentState": null,                 // session.agentState (permission requests) or null
        "options": { "hasMoreMessages": false }  // older history exists beyond `messages`
    },
    "expected": {
        "blocks": [ /* projected ChatBlock[] (pre tool-grouping) */ ],
        "hasReadyEvent": false,
        "latestUsage": null,                // or { inputTokens, outputTokens, contextSize, contextWindow }
        "visibleBlocks": [ /* projected blocks after tool-grouping */ ]
    }
}
```

Per fixture, the acceptance comparison covers `blocks`, `hasReadyEvent`,
`latestUsage`, and `visibleBlocks`.

## Normative field contract

The projection keeps **structure + semantics** and drops web-presentation and
advisory detail. Whatever is absent below is intentionally NOT part of the
contract — natives may derive their own equivalents but must not expect it in
fixtures. Implementation: `web/scripts/fixtures/projection.ts` (keep in sync
with this list).

Optional fields are present only when they carry a value; `invokedAt` is
omitted when null. `localId` is always present (nullable) on the block kinds
that carry it.

### Every block

`kind`, `id`, `createdAt`, `invokedAt?`

### Per kind

| kind | normative fields |
|------|------------------|
| `user-text` | `localId`, `text`, `attachments?` — each `{ id, filename, mimeType, size, path }` |
| `agent-text` | `localId`, `text` |
| `agent-reasoning` | `localId`, `text` |
| `cli-output` | `localId`, `text`, `source` (`'user' \| 'assistant'`) |
| `codex-review` | `localId`, `review` (verbatim normalized review object) |
| `generated-image` | `localId`, `imageId`, `fileName`, `mimeType` |
| `agent-event` | `event` — the normalized AgentEvent object verbatim (`type` + typed payload fields) |
| `tool-call` | `localId`, `tool`, `children?` (recursively projected; omitted when empty) |
| `tool-group` (visibleBlocks only) | `firstToolId`, `lastToolId`, `tools` (projected `tool-call` blocks in order; membership + order + count) |

### `tool` object

`{ id, name, state, input?, result?, permission? }`

- `state`: `'pending' | 'running' | 'completed' | 'error'`
- `input`: verbatim wire value (may be `null` when only the result was seen)
- `result`: verbatim wire value, present once a result/progress landed —
  including hub truncation markers (`…[hapi: truncated N chars]…`) byte-for-byte
- `permission?`: `{ status, mode?, decision?, allowedTools?, answers?, reason? }`
  — `status`: `'pending' | 'approved' | 'denied' | 'canceled'`

### Top level

- `hasReadyEvent`: boolean (a `ready` event is consumed, never a block)
- `latestUsage`: `null` or `{ inputTokens, outputTokens, contextSize, contextWindow }`
  (`contextWindow` nullable; `contextSize` already folds cache tokens in)

### Dropped (web-presentation / advisory — not in fixtures)

Block level: `meta`, `usage` (per-block), `model`, `durationMs`, `status`
(optimistic-send state), `originalText`, `streamId`, `uuid`/`parentUUID`,
`agentTimestamp`. Tool level: `createdAt`/`startedAt`/`completedAt`/
`execStartedAt`/`execCompletedAt` (timing), `description`, `nativeTitle`,
`nativeKind`, `progress`. Permission level: `id`, `date`, `createdAt`,
`completedAt`. Attachments: `previewUrl`. Generated image: `source`.
Tool group: `defaultOpen`, `historyState`, `needsOlderHistory`,
`activityTitle`, `presentationMode`, `summary`. Top level: `latestGoal`,
`latestUsage.cacheCreation`/`cacheRead`/`model`/`timestamp`.

---

# SSE session-patch suite (`sse/`)

Pins the versioned-patch algorithm for `session-updated` events carrying a
`SessionPatch` (contract: `docs/api/client-contract/sse.md`, "Versioned patch
algorithm"). Expectations are computed by the real web fold —
`applySessionDetailPatch` in `web/src/lib/sessionPatch.ts`.

## Document schema (`fixtureVersion: 1`)

```jsonc
{
    "fixtureVersion": 1,
    "name": "metadata-newer-version-applied",   // equals the file name
    "description": "…",
    "initialSession": { /* full Session as cached before the first patch */ },
    "patches": [ /* SessionPatch payloads in arrival order */ ],
    "expectedPatchResults": [ "applied" | "unchanged", … ],  // aligned with patches
    "expectedSession": { /* Session after folding all patches */ }
}
```

## Replay contract

Fold over `patches` in order:

```
next = applySessionDetailPatch(session, patch)   // your port
results[i] = next == null ? "unchanged" : "applied"
session = next ?? session
```

Compare `results` against `expectedPatchResults` and the final session
against `expectedSession` (canonical-JSON equality). `unchanged` is
normative: it means the call reported "nothing changed — keep the previous
object identity" (version-gated wrapper, sub-minute `activeAt` keep-alive,
no-op assignment). A port that applies a stale wrapper, or that treats a
keep-alive as a change, fails on the verdict even when the final session
happens to match.

Both inputs are stored **schema-normalized**: `initialSession` is the parse
output of `SessionSchema` and every patch is the parse output of the strict
`SessionPatchSchema` (zod defaults applied, e.g. `TodoItem.priority`), so
consumers decode the JSON verbatim — no schema re-run needed. The generator
validates every authored patch against the wire schema, and the web
self-check re-validates on every test run, so fixtures cannot drift from
`shared/src/schemas.ts`.

Behavior deliberately pinned (see the individual descriptions):

- versioned wrappers (`metadata`/`agentState`/`todos`/`teamState`) apply only
  when `version` is **strictly greater** than the cached watermark; equal and
  older versions are dropped regardless of value; absent `todosUpdatedAt`/
  `teamStateUpdatedAt` watermarks count as 0
- `teamState` wrapper with `value: null` clears the field (absent in
  `expectedSession`) and still stores the watermark
- `updatedAt` is max-monotonic; an older `updatedAt` alone is `unchanged`
- flat fields are last-write-wins; a `serviceTier` key explicitly present as
  `null` clears it
- `activeTurnStartedAt` is **not applied** by the patch path (web behavior:
  no assignment branch) — a patch carrying only it is `unchanged`
- a patch whose only effective change is an `activeAt` delta < 60s is
  `unchanged` and the cached `activeAt` does **not** move
- `scratchlistUpdatedAt` is a refetch trigger only: `unchanged`, no session
  mutation

---

# Pagination suite (`pagination/`)

Pins the message-window store: paging requests it must issue, epoch-reset
handling, optimistic-send reconciliation, queued-row lifecycle, and window
trimming (contract: `docs/api/client-contract/pagination.md`). Expectations
are recorded from the real web store (`web/src/lib/message-window-store.ts`)
driven by a scripted ApiClient.

## Document schema (`fixtureVersion: 1`)

```jsonc
{
    "fixtureVersion": 1,
    "name": "older-page-epoch-mismatch-resets",   // equals the file name
    "description": "…",
    "ops": [ /* operation script, in order; see below */ ],
    "expectedState": { /* final window projection, see below */ }
}
```

## Operations

Replay each op strictly sequentially against your ported store. Ops that hit
the server carry `responses` — the scripted `GET /messages` replies, consumed
FIFO — and the machine-recorded `expectedRequests`: the exact query objects
the web store sent (`limit` only for a latest page; `beforeAt`+`beforeSeq`+
`limit` for older pages; `afterAt`+`afterSeq`+`untilAt`+`untilSeq`+`epoch`+
`limit` for tail catch-up, where `untilAt`/`untilSeq` are `null` on the first
loop request). Your port must issue the same requests in the same order and
consume every scripted response.

| `op` | Store operation (web name) | Notes |
|------|----------------------------|-------|
| `sync-tail` | `syncTailMessages` | Full tail sync; latest page when no usable cursor, else the after-cursor loop. |
| `fetch-older` | `fetchOlderMessages` | One older page. `expectedOutcome` is `{kind:'applied', hasMore, addedRenderableCount}` or `{kind:'stopped', reason}`. On an epoch mismatch the store runs an internal tail sync — its request/response belong to this same op and the outcome is `stopped`/`epoch-reset`. |
| `sse-messages` | `ingestIncomingMessages` | SSE `message-received` delivery (also advances the newest cursor when an epoch is cached — even past rows the pipeline hides). |
| `append-optimistic` | `appendOptimisticMessage` | Local optimistic row (`id === localId`). Does **not** advance the newest cursor. |
| `update-status` | `updateMessageStatus` | Client send-state transition by `localId`. |
| `messages-consumed` | `markMessagesConsumed` | SSE event: stamp `invokedAt`, flip status to `sent` (skip `failed`), re-sort by position; never advances the newest cursor. |
| `message-cancelled` | `removeOptimisticMessage` | SSE event / optimistic DELETE removal; matches `localId` **or** `id`; idempotent. |
| `cancel-invoked` | remove + append | DELETE answered `{"status":"invoked"}`: remove by `localId`, then ingest the returned `message` with client status `sent` (the harness adds the status). |
| `set-view-mode` | `setMessageViewMode` | `tail` re-entry trims to the visible window and, after a history overflow, forces a latest reset. |
| `queued-state` | reconcile round trip | Collect candidates (user rows with `invokedAt === null`, pinned in `expectedCandidates`, window order), apply `invoked` entries like `messages-consumed`, then drop candidates in neither `queuedLocalIds` nor `invoked`. |

## `expectedState` projection (normative)

```jsonc
{
    "messages": [ { "id", "localId", "seq", "createdAt",
                    "invokedAt"?,     // wire tri-state: absent / null / number
                    "scheduledAt"?,   // wire tri-state
                    "status"?,        // client send state when present
                    "queued": bool,   // user row ∧ invokedAt === null ∧ status ≠ 'failed'
                    "optimistic": bool } ],   // localId ∧ id === localId
    "hasMore": bool,                  // older history exists (server flag ∨ trim)
    "epoch": number | null,
    "viewMode": "tail" | "history",
    "olderCursor": { "at", "seq" } | null,   // next before-request position
    "newestCursor": { "at", "seq" } | null   // next after-request position
}
```

`messages` order is normative (position order: `at = invokedAt ?? createdAt`,
ties by `seq`). The cursors are the store's compound paging positions (web
internals `oldestPosition*` / `newestPosition*`); everything else that is
web-internal (render/version counters, notification throttling, persistence)
is intentionally NOT part of the contract.

Determinism notes: the web store's only wall-clock reads gate notification
throttling and never touch this projection, so no time injection is needed —
replays are exact. Fixtures keep every position pair distinct (no `(at, seq)`
ties), so the web's id tie-break (`localeCompare`) never decides an order;
native ports should still break full ties with an ASCII id comparison.

---

# Catalogs

`catalogs/` holds reference tables generated from `shared/src` modules (not
from the chat pipeline) by the same generator, with the same canonical
serialization and drift gate. Never edit them by hand.

- **`catalogs/modes.json`** — generated from `shared/src/modes.ts`
  (`web/scripts/fixtures/modesCatalog.ts` imports the module directly, like
  the chat pipeline):
  - `permissionModesByFlavor`: for every `AGENT_FLAVORS` entry, the permission
    modes offered for that flavor **in offer order**, each as
    `{ mode, label, tone }` (`tone`: `'neutral' | 'info' | 'warning' |
    'danger'`). An empty array means the flavor exposes no runtime permission
    switching (e.g. `pi`).
  - `codexCollaborationModes`: the codex-only collaboration axis as
    `{ mode, label }` pairs.

  Natives port this table (mode ids, order, labels, tones) and should compare
  their port against the file in tests the same way as the chat fixtures:
  canonical-JSON equality.

---

# Regeneration & drift gate

```bash
bun run gen:fixtures        # from the repo root (runs web/scripts/generate-fixtures.ts)
```

Output is byte-deterministic (canonical serialization), so `git status` after
a regeneration is the drift signal: when `web/src/chat/**`,
`web/src/lib/sessionPatch.ts`, `web/src/lib/message-window-store.ts` or
`web/src/lib/messages.ts` change behavior, regenerated fixtures differ, the
diff gets committed, and the native conformance suites go red until the ports
catch up. The web-side self-checks (all in `bun run test:web`) re-run every
stored input against the live implementation and fail on any divergence from
the stored expectations or from canonical serialization:

- `web/src/chat/fixtures.test.ts` — chat suite (also rebuilds
  `catalogs/modes.json` from `shared/src/modes.ts` and compares)
- `web/src/lib/sessionPatch.fixtures.test.ts` — sse suite
- `web/src/lib/message-window-store.fixtures.test.ts` — pagination suite