# Protocol Snapshots

Canonical JSON fixtures for the Oppi client-server protocol and pi SDK events.

## Files

| File | Description | Source of truth |
|------|-------------|-----------------|
| `server-messages.json` | All 33 `ServerMessage` shapes the iOS client must handle | Generated by `server/tests/protocol-snapshots.test.ts` |
| `pi-events.json` | All 31 pi SDK `AgentSessionEvent` shapes | Hand-maintained reference (used to test `translatePiEvent` in `session-protocol.ts`) |

## How they're used

- **`server-messages.json`** is generated from test code and validated against `server/src/types.ts`. The iOS app's `ServerMessage.swift` decoder is tested against these fixtures to ensure both sides agree on the wire format.
- **`pi-events.json`** documents the upstream pi SDK event shapes that the server translates into `ServerMessage` types.

## Updating

Run `npm test` in `server/` — the protocol snapshot test regenerates `server-messages.json` if the types change. If the snapshot drifts, the test fails until you update the fixture.

For `pi-events.json`, update manually when the pi SDK adds new event types.