@wibly/internal-protocol 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# `@wibly/internal-protocol` — Changelog
+
+## 0.1.1 — 2026-05-30
+
+Initial public npm release. Internal runtime dependency of `@wibly/sdk` —
+not a supported direct import surface for game bundles.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@wibly/internal-protocol",
+  "version": "0.1.1",
+  "description": "Wibly @wibly/internal-protocol",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wibly/wibly"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@wibly/internal-shared": "0.1.1",
+    "zod": "^3.25.76"
+  },
+  "peerDependencies": {}
+}

package/src/__snapshots__/wire-format.test.ts.snap

@@ -0,0 +1,23 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`wire-format byte snapshots > encodes the ack fixture to its locked wire form 1`] = `"{"protocolVersion":1,"kind":"ack","seq":3,"id":"msg_ackFixture_00000000000000","ts":1736000000400,"payload":{"sessionId":"ses_V1StGXR8_Z5jdHi6B_myT","ackSeq":5}}"`;
+
+exports[`wire-format byte snapshots > encodes the emit fixture to its locked wire form 1`] = `"{"protocolVersion":1,"kind":"emit","seq":2,"id":"msg_emitFixture_0000000000000","ts":1736000000300,"payload":{"sessionId":"ses_V1StGXR8_Z5jdHi6B_myT","eventType":"host.riff","data":{"text":"while you all type..."}}}"`;
+
+exports[`wire-format byte snapshots > encodes the error fixture to its locked wire form 1`] = `"{"protocolVersion":1,"kind":"error","seq":4,"id":"msg_errorFixture_00000000000","ts":1736000004000,"payload":{"code":"invalid_request","message":"submit not allowed in current phase","causeMessageId":"msg_submitFixture_00000000000"}}"`;
+
+exports[`wire-format byte snapshots > encodes the event fixture to its locked wire form 1`] = `"{"protocolVersion":1,"kind":"event","seq":2,"id":"msg_eventFixture_00000000000","ts":1736000002000,"payload":{"sessionId":"ses_V1StGXR8_Z5jdHi6B_myT","eventType":"phase.opened","data":{"phaseId":"guess"}}}"`;
+
+exports[`wire-format byte snapshots > encodes the lifecycle fixture to its locked wire form 1`] = `"{"protocolVersion":1,"kind":"lifecycle","seq":3,"id":"msg_lifecycleFixture_0000000","ts":1736000003000,"payload":{"sessionId":"ses_V1StGXR8_Z5jdHi6B_myT","transition":"session.opened","detail":{"hostPlayerId":"plr_host"}}}"`;
+
+exports[`wire-format byte snapshots > encodes the ping fixture to its locked wire form 1`] = `"{"protocolVersion":1,"kind":"ping","seq":4,"id":"msg_pingFixture_0000000000000","ts":1736000000500,"payload":{"sessionId":"ses_V1StGXR8_Z5jdHi6B_myT"}}"`;
+
+exports[`wire-format byte snapshots > encodes the pong fixture to its locked wire form 1`] = `"{"protocolVersion":1,"kind":"pong","seq":5,"id":"msg_pongFixture_000000000000","ts":1736000005000,"payload":{"echoTs":1736000004900}}"`;
+
+exports[`wire-format byte snapshots > encodes the snapshot fixture to its locked wire form 1`] = `"{"protocolVersion":1,"kind":"snapshot","seq":0,"id":"msg_snapshotFixture_0000000","ts":1736000000000,"payload":{"sessionId":"ses_V1StGXR8_Z5jdHi6B_myT","phaseId":"lobby","state":{"round":0,"scores":{}},"baseSeq":0}}"`;
+
+exports[`wire-format byte snapshots > encodes the state_diff fixture to its locked wire form 1`] = `"{"protocolVersion":1,"kind":"state_diff","seq":1,"id":"msg_stateDiffFixture_000000","ts":1736000001000,"payload":{"sessionId":"ses_V1StGXR8_Z5jdHi6B_myT","fromSeq":0,"toSeq":1,"patches":[{"op":"replace","path":"/round","value":1},{"op":"add","path":"/scores/p1","value":0}]}}"`;
+
+exports[`wire-format byte snapshots > encodes the submit fixture to its locked wire form 1`] = `"{"protocolVersion":1,"kind":"submit","seq":1,"id":"msg_submitFixture_00000000000","ts":1736000000200,"payload":{"sessionId":"ses_V1StGXR8_Z5jdHi6B_myT","phaseId":"guess","inputType":"guess","data":{"guess":"lemon"}}}"`;
+
+exports[`wire-format byte snapshots > encodes the subscribe fixture to its locked wire form 1`] = `"{"protocolVersion":1,"kind":"subscribe","seq":0,"id":"msg_subscribeFixture_000000","ts":1736000000100,"payload":{"sessionId":"ses_V1StGXR8_Z5jdHi6B_myT","resumeFromSeq":12}}"`;

package/src/codec.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, it } from 'vitest';
+
+import { decode, encode } from './codec.js';
+import {
+  fixtures,
+  snapshotFixture,
+  subscribeFixture,
+} from './fixtures.js';
+import { MESSAGE_KINDS } from './messages.js';
+import { PROTOCOL_VERSION } from './version.js';
+
+describe('encode / decode — round-trip every kind losslessly', () => {
+  for (const kind of MESSAGE_KINDS) {
+    it(`round-trips the ${kind} fixture`, () => {
+      const fixture = fixtures[kind];
+      const wire = encode(fixture);
+      const decoded = decode(wire);
+      expect(decoded.ok).toBe(true);
+      if (decoded.ok) {
+        expect(decoded.value).toEqual(fixture);
+      }
+    });
+  }
+});
+
+describe('decode — categorised failures', () => {
+  it('returns invalid_json for non-JSON input', () => {
+    const result = decode('this is not json');
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe('invalid_json');
+      if (result.error.kind === 'invalid_json') {
+        expect(typeof result.error.cause).toBe('string');
+      }
+    }
+  });
+
+  it('returns invalid_envelope when protocolVersion is missing', () => {
+    const wire = JSON.stringify({
+      kind: 'ping',
+      seq: 0,
+      id: 'msg_abcdefghijklmnopqrstu',
+      ts: 0,
+      payload: { sessionId: 'ses_abc' },
+    });
+    const result = decode(wire);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe('invalid_envelope');
+    }
+  });
+
+  it('returns invalid_envelope when seq is the wrong type', () => {
+    const fixture = fixtures.ping;
+    const wire = JSON.stringify({ ...fixture, seq: 'not a number' });
+    const result = decode(wire);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe('invalid_envelope');
+    }
+  });
+
+  it('returns invalid_envelope when id is missing the msg_ prefix', () => {
+    const fixture = fixtures.ping;
+    const wire = JSON.stringify({ ...fixture, id: 'not-prefixed' });
+    const result = decode(wire);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe('invalid_envelope');
+    }
+  });
+
+  it('returns version_mismatch when protocolVersion is the wrong number', () => {
+    const fixture = fixtures.ping;
+    const wire = JSON.stringify({ ...fixture, protocolVersion: 999 });
+    const result = decode(wire);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe('version_mismatch');
+      if (result.error.kind === 'version_mismatch') {
+        expect(result.error.supported).toBe(PROTOCOL_VERSION);
+        expect(result.error.received).toBe(999);
+      }
+    }
+  });
+
+  it('returns invalid_envelope when protocolVersion is the wrong type (e.g. string)', () => {
+    // protocolVersion must be a number per the envelope shape; "1" is a
+    // string and fails envelope validation BEFORE the version-literal
+    // check. Documenting the order so callers know what to expect.
+    const fixture = fixtures.ping;
+    const wire = JSON.stringify({ ...fixture, protocolVersion: '1' });
+    const result = decode(wire);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe('invalid_envelope');
+    }
+  });
+
+  it('returns unknown_kind when kind is a string but not in the catalogue', () => {
+    const fixture = fixtures.ping;
+    const wire = JSON.stringify({ ...fixture, kind: 'snapshott' });
+    const result = decode(wire);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe('unknown_kind');
+      if (result.error.kind === 'unknown_kind') {
+        expect(result.error.received).toBe('snapshott');
+      }
+    }
+  });
+
+  it('returns invalid_payload when the kind is known but the payload is wrong', () => {
+    const wire = JSON.stringify({
+      ...snapshotFixture,
+      payload: {
+        sessionId: snapshotFixture.payload.sessionId,
+        phaseId: snapshotFixture.payload.phaseId,
+        state: snapshotFixture.payload.state,
+        // baseSeq omitted on purpose
+      },
+    });
+    const result = decode(wire);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe('invalid_payload');
+      if (result.error.kind === 'invalid_payload') {
+        expect(result.error.messageKind).toBe('snapshot');
+        expect(result.error.issues.length).toBeGreaterThan(0);
+      }
+    }
+  });
+
+  it('returns invalid_payload when the payload sessionId has the wrong prefix', () => {
+    const wire = JSON.stringify({
+      ...subscribeFixture,
+      payload: { ...subscribeFixture.payload, sessionId: 'tnt_wrong' },
+    });
+    const result = decode(wire);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe('invalid_payload');
+      if (result.error.kind === 'invalid_payload') {
+        expect(result.error.messageKind).toBe('subscribe');
+      }
+    }
+  });
+});
+
+describe('encode — produces deterministic JSON', () => {
+  it('encodes the snapshot fixture identically across calls', () => {
+    expect(encode(snapshotFixture)).toEqual(encode(snapshotFixture));
+  });
+
+  it('produces parseable JSON for every kind', () => {
+    for (const kind of MESSAGE_KINDS) {
+      const wire = encode(fixtures[kind]);
+      expect(() => JSON.parse(wire)).not.toThrow();
+    }
+  });
+});
+
+describe('version-mismatch error shape', () => {
+  it('lets the client surface a "please refresh" prompt with both versions', () => {
+    const wire = JSON.stringify({
+      ...snapshotFixture,
+      protocolVersion: PROTOCOL_VERSION + 7,
+    });
+    const result = decode(wire);
+    if (result.ok || result.error.kind !== 'version_mismatch') {
+      throw new Error('expected version_mismatch error');
+    }
+    // The acceptance criterion: both supported and received are present.
+    expect(result.error.supported).toBe(PROTOCOL_VERSION);
+    expect(result.error.received).toBe(PROTOCOL_VERSION + 7);
+  });
+});

package/src/codec.ts

@@ -0,0 +1,140 @@
+/**
+ * Wire codec for protocol messages.
+ *
+ * - `encode(msg)` — turns a typed `Message` into a JSON string. Pure;
+ *   never throws (all inputs are already typed).
+ * - `decode(raw)` — turns a JSON string into a `Result<Message,
+ *   ProtocolError>`. Categorises failures so the caller can render the
+ *   right surface (a version mismatch is a "please refresh" banner, an
+ *   invalid payload is a logged drop, etc.). Per Vibecode Dev Plan §4.3,
+ *   never throws across the boundary.
+ *
+ * MVP uses JSON for legibility and AI tool compatibility. A binary codec
+ * (CBOR / MessagePack) is a Phase 2 optimisation — the encode/decode
+ * surface stays the same, only the body changes.
+ */
+
+import { err, ok, type Result } from '@wibly/internal-shared';
+import type { ZodIssue } from 'zod';
+import { z } from 'zod';
+
+import {
+  MessageSchema,
+  isMessageKind,
+  type Message,
+  type MessageKind,
+} from './messages.js';
+import { PROTOCOL_VERSION, type ProtocolVersion } from './version.js';
+
+/**
+ * Categorised decode failure. Each variant carries enough information for
+ * the caller to render the right surface and log structured context.
+ *
+ * - `invalid_json`     — `JSON.parse` threw. The frame is unrecoverable.
+ * - `version_mismatch` — `protocolVersion` was present but didn't equal
+ *                        `PROTOCOL_VERSION`. Carries `supported` and
+ *                        `received` so the client can render a
+ *                        "please refresh" surface (Acceptance §1077).
+ * - `invalid_envelope` — Envelope shape is wrong (missing required
+ *                        field, wrong type on a top-level field). Caller
+ *                        should drop the frame and log.
+ * - `unknown_kind`     — `kind` was a string but not in the catalogue.
+ *                        Likely a forward-compat artifact (newer peer).
+ * - `invalid_payload`  — Envelope was fine and `kind` was known, but the
+ *                        payload didn't match the per-kind schema.
+ */
+export type ProtocolError =
+  | { readonly kind: 'invalid_json'; readonly cause: string }
+  | {
+      readonly kind: 'version_mismatch';
+      readonly supported: ProtocolVersion;
+      readonly received: unknown;
+    }
+  | {
+      readonly kind: 'invalid_envelope';
+      readonly issues: readonly ZodIssue[];
+    }
+  | { readonly kind: 'unknown_kind'; readonly received: string }
+  | {
+      readonly kind: 'invalid_payload';
+      readonly messageKind: MessageKind;
+      readonly issues: readonly ZodIssue[];
+    };
+
+/**
+ * Envelope-shape pre-check. We use this to peel off the version /
+ * envelope / unknown-kind error categories *before* running the full
+ * discriminated-union parse — the union's failure mode is "no member
+ * matched" which collapses every category into one opaque issue list.
+ *
+ * `payload` is `unknown` here on purpose; the payload Zod check happens
+ * downstream once the kind is known.
+ */
+const EnvelopeShapeSchema = z.object({
+  protocolVersion: z.number().int(),
+  kind: z.string().min(1),
+  seq: z.number().int().nonnegative(),
+  id: z.string().regex(/^msg_[A-Za-z0-9_-]+$/),
+  ts: z.number().int(),
+  payload: z.unknown(),
+});
+
+/** Encode a typed message to its wire form. Pure JSON for MVP. */
+export const encode = (msg: Message): string => JSON.stringify(msg);
+
+/**
+ * Decode a wire-form string. Returns a `Result` so the caller branches
+ * explicitly on failure category. Never throws.
+ *
+ * Decoding order (matters for error categorisation):
+ *
+ *   1. JSON parse           → `invalid_json`
+ *   2. Envelope shape       → `invalid_envelope`
+ *   3. Version literal      → `version_mismatch`
+ *   4. Kind in catalogue    → `unknown_kind`
+ *   5. Full payload parse   → `invalid_payload`
+ *
+ * Order is deliberate: a frame missing `protocolVersion` is "envelope
+ * malformed" (we can't even tell what version it claims); a frame with a
+ * present-but-wrong `protocolVersion` is "we're talking different
+ * languages" (the right surface is a refresh prompt, not a bug log).
+ */
+export const decode = (raw: string): Result<Message, ProtocolError> => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch (e) {
+    return err({
+      kind: 'invalid_json',
+      cause: e instanceof Error ? e.message : String(e),
+    });
+  }
+
+  const envelope = EnvelopeShapeSchema.safeParse(parsed);
+  if (!envelope.success) {
+    return err({ kind: 'invalid_envelope', issues: envelope.error.issues });
+  }
+
+  if (envelope.data.protocolVersion !== PROTOCOL_VERSION) {
+    return err({
+      kind: 'version_mismatch',
+      supported: PROTOCOL_VERSION,
+      received: envelope.data.protocolVersion,
+    });
+  }
+
+  if (!isMessageKind(envelope.data.kind)) {
+    return err({ kind: 'unknown_kind', received: envelope.data.kind });
+  }
+
+  const message = MessageSchema.safeParse(parsed);
+  if (!message.success) {
+    return err({
+      kind: 'invalid_payload',
+      messageKind: envelope.data.kind,
+      issues: message.error.issues,
+    });
+  }
+
+  return ok(message.data);
+};

package/src/fixtures.ts

@@ -0,0 +1,194 @@
+/**
+ * Canonical message fixtures used by the codec, round-trip, and
+ * wire-format snapshot tests. One fixture per message kind, with
+ * deterministic ids / seqs / timestamps so the snapshot files lock the
+ * exact bytes a downstream peer will receive.
+ *
+ * Keep these honest examples — anything weird ("does an empty array
+ * work?", "what about a 64-bit int?") goes into a dedicated test, not
+ * the canonical fixture set.
+ *
+ * Test-only — never imported by runtime code.
+ */
+
+import { PROTOCOL_VERSION } from './version.js';
+import type {
+  AckMessage,
+  EmitMessage,
+  ErrorMessage,
+  EventMessage,
+  LifecycleMessage,
+  Message,
+  MessageKind,
+  PingMessage,
+  PongMessage,
+  SnapshotMessage,
+  StateDiffMessage,
+  SubmitMessage,
+  SubscribeMessage,
+} from './messages.js';
+
+const SESSION_ID = 'ses_V1StGXR8_Z5jdHi6B_myT';
+const FIXED_TS = 1_736_000_000_000;
+
+export const snapshotFixture: SnapshotMessage = {
+  protocolVersion: PROTOCOL_VERSION,
+  kind: 'snapshot',
+  seq: 0,
+  id: 'msg_snapshotFixture_0000000',
+  ts: FIXED_TS,
+  payload: {
+    sessionId: SESSION_ID,
+    phaseId: 'lobby',
+    state: { round: 0, scores: {} },
+    baseSeq: 0,
+  },
+};
+
+export const stateDiffFixture: StateDiffMessage = {
+  protocolVersion: PROTOCOL_VERSION,
+  kind: 'state_diff',
+  seq: 1,
+  id: 'msg_stateDiffFixture_000000',
+  ts: FIXED_TS + 1_000,
+  payload: {
+    sessionId: SESSION_ID,
+    fromSeq: 0,
+    toSeq: 1,
+    patches: [
+      { op: 'replace', path: '/round', value: 1 },
+      { op: 'add', path: '/scores/p1', value: 0 },
+    ],
+  },
+};
+
+export const eventFixture: EventMessage = {
+  protocolVersion: PROTOCOL_VERSION,
+  kind: 'event',
+  seq: 2,
+  id: 'msg_eventFixture_00000000000',
+  ts: FIXED_TS + 2_000,
+  payload: {
+    sessionId: SESSION_ID,
+    eventType: 'phase.opened',
+    data: { phaseId: 'guess' },
+  },
+};
+
+export const lifecycleFixture: LifecycleMessage = {
+  protocolVersion: PROTOCOL_VERSION,
+  kind: 'lifecycle',
+  seq: 3,
+  id: 'msg_lifecycleFixture_0000000',
+  ts: FIXED_TS + 3_000,
+  payload: {
+    sessionId: SESSION_ID,
+    transition: 'session.opened',
+    detail: { hostPlayerId: 'plr_host' },
+  },
+};
+
+export const errorFixture: ErrorMessage = {
+  protocolVersion: PROTOCOL_VERSION,
+  kind: 'error',
+  seq: 4,
+  id: 'msg_errorFixture_00000000000',
+  ts: FIXED_TS + 4_000,
+  payload: {
+    code: 'invalid_request',
+    message: 'submit not allowed in current phase',
+    causeMessageId: 'msg_submitFixture_00000000000',
+  },
+};
+
+export const pongFixture: PongMessage = {
+  protocolVersion: PROTOCOL_VERSION,
+  kind: 'pong',
+  seq: 5,
+  id: 'msg_pongFixture_000000000000',
+  ts: FIXED_TS + 5_000,
+  payload: {
+    echoTs: FIXED_TS + 4_900,
+  },
+};
+
+export const subscribeFixture: SubscribeMessage = {
+  protocolVersion: PROTOCOL_VERSION,
+  kind: 'subscribe',
+  seq: 0,
+  id: 'msg_subscribeFixture_000000',
+  ts: FIXED_TS + 100,
+  payload: {
+    sessionId: SESSION_ID,
+    resumeFromSeq: 12,
+  },
+};
+
+export const submitFixture: SubmitMessage = {
+  protocolVersion: PROTOCOL_VERSION,
+  kind: 'submit',
+  seq: 1,
+  id: 'msg_submitFixture_00000000000',
+  ts: FIXED_TS + 200,
+  payload: {
+    sessionId: SESSION_ID,
+    phaseId: 'guess',
+    inputType: 'guess',
+    data: { guess: 'lemon' },
+  },
+};
+
+export const emitFixture: EmitMessage = {
+  protocolVersion: PROTOCOL_VERSION,
+  kind: 'emit',
+  seq: 2,
+  id: 'msg_emitFixture_0000000000000',
+  ts: FIXED_TS + 300,
+  payload: {
+    sessionId: SESSION_ID,
+    eventType: 'host.riff',
+    data: { text: 'while you all type...' },
+  },
+};
+
+export const ackFixture: AckMessage = {
+  protocolVersion: PROTOCOL_VERSION,
+  kind: 'ack',
+  seq: 3,
+  id: 'msg_ackFixture_00000000000000',
+  ts: FIXED_TS + 400,
+  payload: {
+    sessionId: SESSION_ID,
+    ackSeq: 5,
+  },
+};
+
+export const pingFixture: PingMessage = {
+  protocolVersion: PROTOCOL_VERSION,
+  kind: 'ping',
+  seq: 4,
+  id: 'msg_pingFixture_0000000000000',
+  ts: FIXED_TS + 500,
+  payload: {
+    sessionId: SESSION_ID,
+  },
+};
+
+/**
+ * One fixture per `MessageKind`, keyed by kind so tests can iterate
+ * exhaustively. The compile-time check below would fail if a new kind
+ * is added to the union without a matching fixture entry.
+ */
+export const fixtures: Readonly<Record<MessageKind, Message>> = {
+  snapshot: snapshotFixture,
+  state_diff: stateDiffFixture,
+  event: eventFixture,
+  lifecycle: lifecycleFixture,
+  error: errorFixture,
+  pong: pongFixture,
+  subscribe: subscribeFixture,
+  submit: submitFixture,
+  emit: emitFixture,
+  ack: ackFixture,
+  ping: pingFixture,
+};

package/src/index.ts

@@ -0,0 +1,108 @@
+/**
+ * `@platform/protocol` — wire-protocol types, schemas, and codec shared
+ * between the Runtime (`services/runtime`) and the clients (the SDK in
+ * `packages/sdk` plus the Host / Player web shells).
+ *
+ * Per Vibecode Dev Plan §4.6 — every WebSocket message is encoded /
+ * decoded with the codecs in this package; no inline schemas anywhere
+ * else. The protocol package is the single source of truth.
+ *
+ * Built in chunk B0; see `docs/chunks/B0.md` for the close note.
+ */
+
+export { PROTOCOL_VERSION, type ProtocolVersion } from './version.js';
+
+export {
+  // Primitives
+  SessionIdSchema,
+  type SessionId,
+  MessageIdSchema,
+  type MessageId,
+  JsonPatchOpSchema,
+  type JsonPatchOp,
+  // Per-kind payload schemas
+  SnapshotPayloadSchema,
+  type SnapshotPayload,
+  StateDiffPayloadSchema,
+  type StateDiffPayload,
+  EventPayloadSchema,
+  type EventPayload,
+  LifecyclePayloadSchema,
+  type LifecyclePayload,
+  ErrorPayloadSchema,
+  type ErrorPayload,
+  PongPayloadSchema,
+  type PongPayload,
+  SubscribePayloadSchema,
+  type SubscribePayload,
+  SubmitPayloadSchema,
+  type SubmitPayload,
+  EmitPayloadSchema,
+  type EmitPayload,
+  AckPayloadSchema,
+  type AckPayload,
+  PingPayloadSchema,
+  type PingPayload,
+  // Per-kind message schemas
+  SnapshotMessageSchema,
+  type SnapshotMessage,
+  StateDiffMessageSchema,
+  type StateDiffMessage,
+  EventMessageSchema,
+  type EventMessage,
+  LifecycleMessageSchema,
+  type LifecycleMessage,
+  ErrorMessageSchema,
+  type ErrorMessage,
+  PongMessageSchema,
+  type PongMessage,
+  SubscribeMessageSchema,
+  type SubscribeMessage,
+  SubmitMessageSchema,
+  type SubmitMessage,
+  EmitMessageSchema,
+  type EmitMessage,
+  AckMessageSchema,
+  type AckMessage,
+  PingMessageSchema,
+  type PingMessage,
+  // Direction-grouped + universal schemas
+  ServerMessageSchema,
+  type ServerMessage,
+  ClientMessageSchema,
+  type ClientMessage,
+  MessageSchema,
+  type Message,
+  // Kind catalogues + guards
+  SERVER_MESSAGE_KINDS,
+  CLIENT_MESSAGE_KINDS,
+  MESSAGE_KINDS,
+  type ServerMessageKind,
+  type ClientMessageKind,
+  type MessageKind,
+  isMessageKind,
+  isServerMessageKind,
+  isClientMessageKind,
+} from './messages.js';
+
+export {
+  encode,
+  decode,
+  type ProtocolError,
+} from './codec.js';
+
+export {
+  type SessionState,
+  type HostState,
+  type PlayerState,
+  type TeamState,
+  type StateSlices,
+} from './state-shape.js';
+
+export {
+  type ActorKind,
+  type InputSet,
+  type CollectionRule,
+  type Transition,
+  type Phase,
+} from './phase.js';

package/src/messages.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  errorFixture,
+  fixtures,
+  snapshotFixture,
+  stateDiffFixture,
+  subscribeFixture,
+} from './fixtures.js';
+import {
+  CLIENT_MESSAGE_KINDS,
+  ClientMessageSchema,
+  isClientMessageKind,
+  isMessageKind,
+  isServerMessageKind,
+  MESSAGE_KINDS,
+  MessageSchema,
+  SERVER_MESSAGE_KINDS,
+  ServerMessageSchema,
+  type MessageKind,
+} from './messages.js';
+
+describe('MessageSchema — every kind has a fixture', () => {
+  it('the catalogue and the fixture map are exactly aligned', () => {
+    expect(Object.keys(fixtures).sort()).toEqual([...MESSAGE_KINDS].sort());
+  });
+});
+
+describe('MessageSchema — every fixture parses', () => {
+  for (const kind of MESSAGE_KINDS) {
+    it(`accepts the ${kind} fixture`, () => {
+      const fixture = fixtures[kind];
+      const parsed = MessageSchema.safeParse(fixture);
+      expect(parsed.success).toBe(true);
+      if (parsed.success) {
+        expect(parsed.data).toEqual(fixture);
+      }
+    });
+  }
+});
+
+describe('ServerMessageSchema / ClientMessageSchema partition the union', () => {
+  for (const kind of SERVER_MESSAGE_KINDS) {
+    it(`server schema accepts the ${kind} fixture`, () => {
+      expect(ServerMessageSchema.safeParse(fixtures[kind]).success).toBe(true);
+    });
+    it(`client schema rejects the ${kind} fixture`, () => {
+      expect(ClientMessageSchema.safeParse(fixtures[kind]).success).toBe(false);
+    });
+  }
+  for (const kind of CLIENT_MESSAGE_KINDS) {
+    it(`client schema accepts the ${kind} fixture`, () => {
+      expect(ClientMessageSchema.safeParse(fixtures[kind]).success).toBe(true);
+    });
+    it(`server schema rejects the ${kind} fixture`, () => {
+      expect(ServerMessageSchema.safeParse(fixtures[kind]).success).toBe(false);
+    });
+  }
+});
+
+describe('kind guards', () => {
+  it('isMessageKind accepts every catalogue entry', () => {
+    for (const kind of MESSAGE_KINDS) {
+      expect(isMessageKind(kind)).toBe(true);
+    }
+  });
+
+  it('isMessageKind rejects strings outside the catalogue', () => {
+    expect(isMessageKind('snapshott')).toBe(false);
+    expect(isMessageKind('')).toBe(false);
+    expect(isMessageKind('SNAPSHOT')).toBe(false);
+  });
+
+  it('isServerMessageKind / isClientMessageKind partition the catalogue', () => {
+    for (const kind of MESSAGE_KINDS) {
+      const server = isServerMessageKind(kind);
+      const client = isClientMessageKind(kind);
+      expect(server || client).toBe(true);
+      expect(server && client).toBe(false);
+    }
+  });
+});
+
+describe('envelope shape — required fields', () => {
+  it.each([['protocolVersion'], ['kind'], ['seq'], ['id'], ['ts'], ['payload']])(
+    'rejects messages missing %s',
+    (missingField) => {
+      const broken: Record<string, unknown> = { ...snapshotFixture };
+      delete broken[missingField];
+      const result = MessageSchema.safeParse(broken);
+      expect(result.success).toBe(false);
+    },
+  );
+
+  it('rejects negative seq', () => {
+    const broken = { ...snapshotFixture, seq: -1 };
+    expect(MessageSchema.safeParse(broken).success).toBe(false);
+  });
+
+  it('rejects non-integer seq', () => {
+    const broken = { ...snapshotFixture, seq: 1.5 };
+    expect(MessageSchema.safeParse(broken).success).toBe(false);
+  });
+
+  it('rejects an id without the msg_ prefix', () => {
+    const broken = { ...snapshotFixture, id: 'not-prefixed' };
+    expect(MessageSchema.safeParse(broken).success).toBe(false);
+  });
+
+  it('rejects a sessionId without the ses_ prefix', () => {
+    const broken = {
+      ...snapshotFixture,
+      payload: {
+        ...snapshotFixture.payload,
+        sessionId: 'tnt_wrong_prefix_id_value',
+      },
+    };
+    expect(MessageSchema.safeParse(broken).success).toBe(false);
+  });
+});
+
+describe('per-kind payload shape — happy path is in fixtures; sad paths here', () => {
+  it('snapshot rejects a missing baseSeq', () => {
+    const broken = {
+      ...snapshotFixture,
+      payload: {
+        sessionId: snapshotFixture.payload.sessionId,
+        phaseId: snapshotFixture.payload.phaseId,
+        state: snapshotFixture.payload.state,
+      },
+    };
+    expect(MessageSchema.safeParse(broken).success).toBe(false);
+  });
+
+  it('state_diff rejects an out-of-order patch op (unknown kind)', () => {
+    const broken = {
+      ...stateDiffFixture,
+      payload: {
+        ...stateDiffFixture.payload,
+        patches: [{ op: 'test', path: '/round', value: 1 }],
+      },
+    };
+    expect(MessageSchema.safeParse(broken).success).toBe(false);
+  });
+
+  it('error rejects an empty message string', () => {
+    const broken = {
+      ...errorFixture,
+      payload: { ...errorFixture.payload, message: '' },
+    };
+    expect(MessageSchema.safeParse(broken).success).toBe(false);
+  });
+
+  it('subscribe accepts an absent resumeFromSeq', () => {
+    const slim = {
+      ...subscribeFixture,
+      payload: { sessionId: subscribeFixture.payload.sessionId },
+    };
+    expect(MessageSchema.safeParse(slim).success).toBe(true);
+  });
+});
+
+describe('catalogues are exhaustive at compile time', () => {
+  // Smoke: switch over MessageKind narrows; if a kind is added to the
+  // union without an arm here, this test stops compiling. Doubles as a
+  // runtime sanity check.
+  it('fixtures cover every MessageKind via exhaustive switch', () => {
+    const seen = new Set<MessageKind>();
+    for (const kind of MESSAGE_KINDS) {
+      switch (kind) {
+        case 'snapshot':
+        case 'state_diff':
+        case 'event':
+        case 'lifecycle':
+        case 'error':
+        case 'pong':
+        case 'subscribe':
+        case 'submit':
+        case 'emit':
+        case 'ack':
+        case 'ping':
+          seen.add(kind);
+          break;
+        default: {
+          const exhaustive: never = kind;
+          throw new Error(`unhandled kind: ${exhaustive as string}`);
+        }
+      }
+    }
+    expect(seen.size).toBe(MESSAGE_KINDS.length);
+  });
+});

package/src/messages.ts

@@ -0,0 +1,347 @@
+/**
+ * Wire-protocol message schemas.
+ *
+ * Every WebSocket frame between the Runtime and a connected client is a
+ * single envelope of this shape:
+ *
+ *     { protocolVersion, kind, seq, id, ts, payload }
+ *
+ * - `protocolVersion`  — literal `PROTOCOL_VERSION` (see ./version.ts).
+ * - `kind`             — discriminant; one of `MESSAGE_KINDS`.
+ * - `seq`              — monotonic per session. Server-assigned on
+ *                        server→client frames; client-assigned (per-tab,
+ *                        per-session) on client→server frames so the
+ *                        server can detect dropped frames + dedupe.
+ * - `id`               — stable `msg_…` id (per-message, per-direction).
+ *                        Used as the idempotency key on `submit`/`emit`.
+ * - `ts`               — unix milliseconds. Server time on server→client,
+ *                        client time on client→server.
+ * - `payload`          — typed by `kind`. See per-kind schemas below.
+ *
+ * Add new kinds in the chunk that needs them. Per the chunk-B0 trap,
+ * keep payloads minimal — extra metadata fields land with the chunk that
+ * actually consumes them.
+ */
+
+import { z } from 'zod';
+
+import { PROTOCOL_VERSION } from './version.js';
+
+// -----------------------------------------------------------------------------
+// Shared primitives
+// -----------------------------------------------------------------------------
+
+/**
+ * Session id. Format is `ses_<nanoid>` per the prefixed-id convention from
+ * `@platform/shared/id`. The protocol validates the prefix only; the full
+ * id format is enforced at the Runtime boundary.
+ */
+export const SessionIdSchema = z
+  .string()
+  .regex(/^ses_[A-Za-z0-9_-]+$/, 'must be a ses_ prefixed nanoid');
+export type SessionId = z.infer<typeof SessionIdSchema>;
+
+/**
+ * Message id. Format is `msg_<nanoid>` per `newId('msg')` from
+ * `@platform/shared/id`.
+ */
+export const MessageIdSchema = z
+  .string()
+  .regex(/^msg_[A-Za-z0-9_-]+$/, 'must be a msg_ prefixed nanoid');
+export type MessageId = z.infer<typeof MessageIdSchema>;
+
+/**
+ * JSON-Patch operation subset (RFC 6902 minus `test` — the protocol
+ * doesn't need conditional patches). Used inside `state_diff` payloads.
+ */
+export const JsonPatchOpSchema = z.discriminatedUnion('op', [
+  z.object({ op: z.literal('add'), path: z.string(), value: z.unknown() }),
+  z.object({ op: z.literal('remove'), path: z.string() }),
+  z.object({ op: z.literal('replace'), path: z.string(), value: z.unknown() }),
+  z.object({ op: z.literal('move'), path: z.string(), from: z.string() }),
+  z.object({ op: z.literal('copy'), path: z.string(), from: z.string() }),
+]);
+export type JsonPatchOp = z.infer<typeof JsonPatchOpSchema>;
+
+// -----------------------------------------------------------------------------
+// Server → client payloads
+// -----------------------------------------------------------------------------
+
+/**
+ * Full state load. Sent on initial subscribe and on resume when the
+ * client's `resumeFromSeq` is older than the server can satisfy with
+ * incremental diffs.
+ *
+ * `state` is the per-recipient projection of the session's state slices —
+ * see `./state-shape.ts`. It's `unknown` at the protocol layer because
+ * the shape is described by the Experience manifest (chunk B1).
+ *
+ * `baseSeq` is the seq the next `state_diff` will start `fromSeq`-equal
+ * to. It lets the client tie subsequent diffs to this snapshot without
+ * a separate handshake.
+ */
+export const SnapshotPayloadSchema = z.object({
+  sessionId: SessionIdSchema,
+  phaseId: z.string().min(1),
+  state: z.unknown(),
+  baseSeq: z.number().int().nonnegative(),
+});
+
+/**
+ * Incremental state update. `fromSeq` must equal the receiver's current
+ * applied seq; `toSeq` is the new applied seq after the patches land.
+ * Out-of-order or skipped diffs trigger a resync (server resends
+ * `snapshot`).
+ */
+export const StateDiffPayloadSchema = z.object({
+  sessionId: SessionIdSchema,
+  fromSeq: z.number().int().nonnegative(),
+  toSeq: z.number().int().nonnegative(),
+  patches: z.array(JsonPatchOpSchema),
+});
+
+/**
+ * Server-emitted event. Distinct from `state_diff`: events are
+ * fire-and-forget signals (animation cues, system messages, opportunity
+ * announcements) that don't mutate persistent state.
+ */
+export const EventPayloadSchema = z.object({
+  sessionId: SessionIdSchema,
+  eventType: z.string().min(1),
+  data: z.unknown(),
+});
+
+/**
+ * Lifecycle transition (session opened / closed, phase entered / exited,
+ * host reclaimed, etc.). `transition` is a namespaced string so future
+ * lifecycle verbs land without a schema bump.
+ */
+export const LifecyclePayloadSchema = z.object({
+  sessionId: SessionIdSchema,
+  transition: z.string().min(1),
+  detail: z.unknown(),
+});
+
+/**
+ * Server-emitted error. `code` is the structured category; `message` is
+ * operator-readable. `causeMessageId` ties the error to the client frame
+ * that triggered it (when applicable).
+ */
+export const ErrorPayloadSchema = z.object({
+  code: z.string().min(1),
+  message: z.string().min(1),
+  causeMessageId: MessageIdSchema.optional(),
+});
+
+/**
+ * Heartbeat response. `echoTs` is the client's `ping` envelope `ts` so
+ * the client can compute round-trip latency.
+ */
+export const PongPayloadSchema = z.object({
+  echoTs: z.number().int(),
+});
+
+// -----------------------------------------------------------------------------
+// Client → server payloads
+// -----------------------------------------------------------------------------
+
+/**
+ * Subscribe to a session. `resumeFromSeq` is the last seq the client has
+ * fully applied; the server replies with `state_diff`s when it can
+ * satisfy from buffer, otherwise a fresh `snapshot`.
+ */
+export const SubscribePayloadSchema = z.object({
+  sessionId: SessionIdSchema,
+  resumeFromSeq: z.number().int().nonnegative().optional(),
+});
+
+/**
+ * Active input — the workhorse for turn-based collection. The Runtime
+ * gates on the current phase's `InputSet`; submissions for the wrong
+ * phase / input type get rejected with a structured `error` frame.
+ *
+ * `id` (envelope-level) is the idempotency key — duplicates are deduped
+ * server-side per Vibecode Dev Plan §4.6.
+ */
+export const SubmitPayloadSchema = z.object({
+  sessionId: SessionIdSchema,
+  phaseId: z.string().min(1),
+  inputType: z.string().min(1),
+  data: z.unknown(),
+});
+
+/**
+ * Non-Active emission (host riff while players type, the "Yellow"
+ * pattern in Platform Spec §1.2). Idempotency rules match `submit`.
+ */
+export const EmitPayloadSchema = z.object({
+  sessionId: SessionIdSchema,
+  eventType: z.string().min(1),
+  data: z.unknown(),
+});
+
+/**
+ * Acknowledge a server message by its `seq`. Lets the server prune its
+ * outgoing buffer once every recipient has acked.
+ */
+export const AckPayloadSchema = z.object({
+  sessionId: SessionIdSchema,
+  ackSeq: z.number().int().nonnegative(),
+});
+
+/**
+ * Heartbeat. Carries `sessionId` so the server can route in a
+ * multi-session connection (Phase 2 — MVP is one session per socket).
+ */
+export const PingPayloadSchema = z.object({
+  sessionId: SessionIdSchema,
+});
+
+// -----------------------------------------------------------------------------
+// Kind catalogue
+// -----------------------------------------------------------------------------
+
+/**
+ * Reserved for Phase 2 — P-bundles. The Runtime emits `bundle_snapshot` on
+ * bundle subscribe, `bundle_diff` on bundle state mutation, and
+ * `bundle_event` on cross-session bundle events. Adding them to the union
+ * is a Phase-2 chunk; the codec round-trip tests expand at the same time.
+ *
+ * @deferred Phase 2 — P-bundles
+ *
+ *   'bundle_snapshot',
+ *   'bundle_diff',
+ *   'bundle_event',
+ */
+
+export const SERVER_MESSAGE_KINDS = [
+  'snapshot',
+  'state_diff',
+  'event',
+  'lifecycle',
+  'error',
+  'pong',
+] as const;
+
+export const CLIENT_MESSAGE_KINDS = [
+  'subscribe',
+  'submit',
+  'emit',
+  'ack',
+  'ping',
+] as const;
+
+export const MESSAGE_KINDS = [
+  ...SERVER_MESSAGE_KINDS,
+  ...CLIENT_MESSAGE_KINDS,
+] as const;
+
+export type ServerMessageKind = (typeof SERVER_MESSAGE_KINDS)[number];
+export type ClientMessageKind = (typeof CLIENT_MESSAGE_KINDS)[number];
+export type MessageKind = ServerMessageKind | ClientMessageKind;
+
+const SERVER_KIND_SET: ReadonlySet<string> = new Set(SERVER_MESSAGE_KINDS);
+const CLIENT_KIND_SET: ReadonlySet<string> = new Set(CLIENT_MESSAGE_KINDS);
+const KIND_SET: ReadonlySet<string> = new Set(MESSAGE_KINDS);
+
+export const isMessageKind = (k: string): k is MessageKind => KIND_SET.has(k);
+export const isServerMessageKind = (k: string): k is ServerMessageKind =>
+  SERVER_KIND_SET.has(k);
+export const isClientMessageKind = (k: string): k is ClientMessageKind =>
+  CLIENT_KIND_SET.has(k);
+
+// -----------------------------------------------------------------------------
+// Envelope + discriminated union
+// -----------------------------------------------------------------------------
+
+const envelopeFields = {
+  protocolVersion: z.literal(PROTOCOL_VERSION),
+  seq: z.number().int().nonnegative(),
+  id: MessageIdSchema,
+  ts: z.number().int(),
+} as const;
+
+const message = <K extends MessageKind, P extends z.ZodTypeAny>(
+  kind: K,
+  payload: P,
+) =>
+  z.object({
+    ...envelopeFields,
+    kind: z.literal(kind),
+    payload,
+  });
+
+export const SnapshotMessageSchema = message('snapshot', SnapshotPayloadSchema);
+export const StateDiffMessageSchema = message('state_diff', StateDiffPayloadSchema);
+export const EventMessageSchema = message('event', EventPayloadSchema);
+export const LifecycleMessageSchema = message('lifecycle', LifecyclePayloadSchema);
+export const ErrorMessageSchema = message('error', ErrorPayloadSchema);
+export const PongMessageSchema = message('pong', PongPayloadSchema);
+export const SubscribeMessageSchema = message('subscribe', SubscribePayloadSchema);
+export const SubmitMessageSchema = message('submit', SubmitPayloadSchema);
+export const EmitMessageSchema = message('emit', EmitPayloadSchema);
+export const AckMessageSchema = message('ack', AckPayloadSchema);
+export const PingMessageSchema = message('ping', PingPayloadSchema);
+
+export const ServerMessageSchema = z.discriminatedUnion('kind', [
+  SnapshotMessageSchema,
+  StateDiffMessageSchema,
+  EventMessageSchema,
+  LifecycleMessageSchema,
+  ErrorMessageSchema,
+  PongMessageSchema,
+]);
+
+export const ClientMessageSchema = z.discriminatedUnion('kind', [
+  SubscribeMessageSchema,
+  SubmitMessageSchema,
+  EmitMessageSchema,
+  AckMessageSchema,
+  PingMessageSchema,
+]);
+
+export const MessageSchema = z.discriminatedUnion('kind', [
+  SnapshotMessageSchema,
+  StateDiffMessageSchema,
+  EventMessageSchema,
+  LifecycleMessageSchema,
+  ErrorMessageSchema,
+  PongMessageSchema,
+  SubscribeMessageSchema,
+  SubmitMessageSchema,
+  EmitMessageSchema,
+  AckMessageSchema,
+  PingMessageSchema,
+]);
+
+// -----------------------------------------------------------------------------
+// Inferred types (use the OUTPUT type via z.infer per §4.1 / chunk A1)
+// -----------------------------------------------------------------------------
+
+export type SnapshotMessage = z.infer<typeof SnapshotMessageSchema>;
+export type StateDiffMessage = z.infer<typeof StateDiffMessageSchema>;
+export type EventMessage = z.infer<typeof EventMessageSchema>;
+export type LifecycleMessage = z.infer<typeof LifecycleMessageSchema>;
+export type ErrorMessage = z.infer<typeof ErrorMessageSchema>;
+export type PongMessage = z.infer<typeof PongMessageSchema>;
+export type SubscribeMessage = z.infer<typeof SubscribeMessageSchema>;
+export type SubmitMessage = z.infer<typeof SubmitMessageSchema>;
+export type EmitMessage = z.infer<typeof EmitMessageSchema>;
+export type AckMessage = z.infer<typeof AckMessageSchema>;
+export type PingMessage = z.infer<typeof PingMessageSchema>;
+
+export type ServerMessage = z.infer<typeof ServerMessageSchema>;
+export type ClientMessage = z.infer<typeof ClientMessageSchema>;
+export type Message = z.infer<typeof MessageSchema>;
+
+export type SnapshotPayload = z.infer<typeof SnapshotPayloadSchema>;
+export type StateDiffPayload = z.infer<typeof StateDiffPayloadSchema>;
+export type EventPayload = z.infer<typeof EventPayloadSchema>;
+export type LifecyclePayload = z.infer<typeof LifecyclePayloadSchema>;
+export type ErrorPayload = z.infer<typeof ErrorPayloadSchema>;
+export type PongPayload = z.infer<typeof PongPayloadSchema>;
+export type SubscribePayload = z.infer<typeof SubscribePayloadSchema>;
+export type SubmitPayload = z.infer<typeof SubmitPayloadSchema>;
+export type EmitPayload = z.infer<typeof EmitPayloadSchema>;
+export type AckPayload = z.infer<typeof AckPayloadSchema>;
+export type PingPayload = z.infer<typeof PingPayloadSchema>;

package/src/phase.ts

@@ -0,0 +1,55 @@
+/**
+ * Workflow primitives per Platform Spec §3.9.1.
+ *
+ * Every Experience is a state machine of `Phase`s. Each phase declares an
+ * `InputSet` (whose inputs are accepted) and a `CollectionRule` (when the
+ * phase ends), plus zero or more `Transition`s out. The Runtime owns the
+ * authoritative phase pointer; clients cannot drive transitions
+ * (Invariant §1.2 — turn-based by default).
+ *
+ * Per the chunk-B0 trap ("keep messages minimal — add fields when a chunk
+ * needs them"), these types are deliberately narrow. The manifest schema
+ * in chunk B1 layers Zod validation, structural checks, and any
+ * additional manifest-time fields on top.
+ */
+
+export type ActorKind = 'host' | 'player' | 'team';
+
+export type InputSet = {
+  /** Which actor classes may produce input during this phase. */
+  readonly actors: ReadonlyArray<ActorKind>;
+  /**
+   * Manifest-defined input identifier (e.g. 'guess', 'vote', 'free_text').
+   * The Runtime validates against the manifest's per-input Zod schema; the
+   * protocol carries it as an opaque string.
+   */
+  readonly inputType: string;
+};
+
+/**
+ * When the phase ends. Discriminated on `kind` so the Runtime can branch
+ * exhaustively. Add new variants in the chunk that needs them.
+ */
+export type CollectionRule =
+  | { readonly kind: 'all_respond' }
+  | { readonly kind: 'first_respond'; readonly count: number }
+  | { readonly kind: 'timeout'; readonly ms: number }
+  | { readonly kind: 'manual' };
+
+/**
+ * One outgoing edge from a phase. The Runtime evaluates transitions in
+ * declaration order on collection-rule fire; the first matching transition
+ * is taken. Conditions are manifest-level; the protocol just carries the
+ * tag.
+ */
+export type Transition = {
+  readonly to: string;
+  readonly when?: string;
+};
+
+export type Phase = {
+  readonly id: string;
+  readonly inputSet: InputSet;
+  readonly collectionRule: CollectionRule;
+  readonly transitions: ReadonlyArray<Transition>;
+};

package/src/state-shape.ts

@@ -0,0 +1,54 @@
+/**
+ * Generic state-slice types per Platform Spec §2.4.4.
+ *
+ * The Runtime maintains a session's authoritative state on the server and
+ * pushes it to clients as a `snapshot` on subscribe / reconnect, then as
+ * incremental `state_diff` patches between snapshots. The slices below are
+ * the *shapes* the protocol carries; the *content* is described by the
+ * Experience manifest's `stateSchema` (chunk B1) and is opaque at the
+ * protocol layer — hence the type parameters default to `unknown`.
+ *
+ * Visibility model:
+ *
+ * - `SessionState`  — global, visible to host + every player.
+ * - `HostState`     — host-only.
+ * - `PlayerState`   — split into `public` (visible to all) and `private`
+ *                     (visible only to that player). Per Platform Spec
+ *                     §2.4.4 — the public/private split is the workhorse
+ *                     for hidden information in turn-based games.
+ * - `TeamState`     — visible to members of one team.
+ *
+ * Actor-specific slices are optional: a snapshot delivered to a player
+ * carries `session` + `player` + (their) `team`; a snapshot delivered to
+ * the host carries `session` + `host` + every team. The Runtime composes
+ * the per-recipient projection; the protocol just transports it.
+ */
+
+export type SessionState<T = unknown> = T;
+
+export type HostState<T = unknown> = T;
+
+export type PlayerState<TPublic = unknown, TPrivate = unknown> = {
+  readonly public: TPublic;
+  readonly private: TPrivate;
+};
+
+export type TeamState<T = unknown> = T;
+
+/**
+ * Composite shape carried inside the `snapshot` payload's `state` field.
+ * Each slice is optional so the Runtime can omit slices the recipient is
+ * not entitled to see.
+ */
+export type StateSlices<
+  TSession = unknown,
+  THost = unknown,
+  TPlayerPublic = unknown,
+  TPlayerPrivate = unknown,
+  TTeam = unknown,
+> = {
+  readonly session: SessionState<TSession>;
+  readonly host?: HostState<THost>;
+  readonly player?: PlayerState<TPlayerPublic, TPlayerPrivate>;
+  readonly team?: TeamState<TTeam>;
+};

package/src/version.ts

@@ -0,0 +1,11 @@
+/**
+ * The wire-protocol version. Bumped when an incompatible envelope or
+ * payload change ships. Servers and clients refuse to talk to a peer
+ * advertising a different version (see `decode` in `./codec.ts` →
+ * `version_mismatch`).
+ *
+ * MVP starts at version 1; subsequent bumps land in their own chunk.
+ */
+export const PROTOCOL_VERSION = 1 as const;
+
+export type ProtocolVersion = typeof PROTOCOL_VERSION;

package/src/wire-format.test.ts

@@ -0,0 +1,30 @@
+/**
+ * Wire-format snapshot tests.
+ *
+ * Per Vibecode Dev Plan §4.7.5 — snapshot tests are appropriate for
+ * stable wire formats (anything where a non-meaningful change really
+ * IS a contract break). This file holds one snapshot per `MessageKind`
+ * locking the exact JSON-string bytes a downstream peer would receive.
+ *
+ * If a fixture change is expected (e.g. a new optional field), update
+ * the fixture AND regenerate this file's snapshot in the same commit:
+ *   `pnpm --filter @platform/protocol test -- -u`
+ *
+ * If a snapshot diff is *un*expected, the contract is breaking and the
+ * change needs a `PROTOCOL_VERSION` bump. (See `./version.ts`.)
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { encode } from './codec.js';
+import { fixtures } from './fixtures.js';
+import { MESSAGE_KINDS } from './messages.js';
+
+describe('wire-format byte snapshots', () => {
+  for (const kind of MESSAGE_KINDS) {
+    it(`encodes the ${kind} fixture to its locked wire form`, () => {
+      const wire = encode(fixtures[kind]);
+      expect(wire).toMatchSnapshot();
+    });
+  }
+});