---
phase: 06.7-network-model-client-trust-fall-trigger
plan: 01
subsystem: protocol
tags: [protocol, zod, colyseus, movement, anim-state]
requires:
  - phase: 06.7
    provides: context and reviewed movement trust-split plan
provides:
  - protocol-owned Direction and anim_state pack/unpack helpers
  - c2s.position_update and c2s.set_sprite_override schemas
  - PlayerState anim_state and sprite_override fields
  - PROTOCOL_VERSION 4 handshake contract
affects: [apps/server, apps/client, packages/protocol]
tech-stack:
  added: []
  patterns: [protocol-owned shared direction helpers, strict zod c2s schemas]
key-files:
  created:
    - packages/protocol/src/anim-state.ts
    - packages/protocol/test/anim-state.test.ts
  modified:
    - packages/protocol/src/index.ts
    - packages/protocol/src/intents.ts
    - packages/protocol/src/state.ts
    - packages/protocol/src/version.ts
    - packages/protocol/test/intents.test.ts
    - packages/protocol/test/state.test.ts
key-decisions:
  - "Direction ownership lives in packages/protocol/src/anim-state.ts; intents.ts imports from it, never the reverse."
  - "position_update monotonic_at_ms is bounded as finite u32 int, not loose nonnegative number."
requirements-completed: [REQ-SRV-03, REQ-CLI-04, REQ-CLI-08]
duration: 20 min
completed: 2026-05-17
---

# Phase 06.7 Plan 01: Protocol Surface Summary

**Protocol v4 movement surface with packed animation state, strict client position updates, sprite override intent, and additive PlayerState fields**

## Performance

- **Duration:** 20 min
- **Started:** 2026-05-17T09:45:00Z
- **Completed:** 2026-05-17T10:05:00Z
- **Tasks:** 3
- **Files modified:** 8

## Accomplishments

- Added `anim-state.ts` as the canonical owner for `Direction`, `FACING_OCTANT`, `OCTANT_FACING`, `packAnimState`, and `unpackAnimState`.
- Added strict `cPositionUpdateSchema` and `cSetSpriteOverrideSchema`, registered both in `c2sSchema`, and exported inferred TS types.
- Added `PlayerState.anim_state` and `PlayerState.sprite_override`, then bumped `PROTOCOL_VERSION` from 3 to 4 with tests.

## Task Commits

1. **Tasks 1-3: Protocol surface, schemas, state fields, tests** - `1ba1fe6` (feat)

**Plan metadata:** this summary commit.

## Files Created/Modified

- `packages/protocol/src/anim-state.ts` - Protocol-owned Direction + packed animation-state helpers.
- `packages/protocol/test/anim-state.test.ts` - Byte-layout, round-trip, and zero import-cycle tests.
- `packages/protocol/src/intents.ts` - `position_update` and `set_sprite_override` schemas plus c2s registration.
- `packages/protocol/src/state.ts` - Colyseus PlayerState fields for `anim_state` and `sprite_override`.
- `packages/protocol/src/version.ts` - PROTOCOL_VERSION 4 history entry and literal.
- `packages/protocol/test/intents.test.ts` - Schema accept/reject and c2s union routing coverage.
- `packages/protocol/test/state.test.ts` - Version and new PlayerState default coverage.

## Decisions Made

- Kept `Direction` in `anim-state.ts` so downstream modules import one way only. This closes codex review concern #5.
- Enforced `monotonic_at_ms` as `.finite().int().min(0).max(0xffffffff)` to match the u32 binary contract. This closes codex review concern #7.

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

- `pnpm trace:check` still fails from pre-existing planning artifact parse/placeholder findings and already-authored 06.7 plan-file examples. The new protocol files' trace tags are valid and the phase requirement rows already show coverage for REQ-SRV-03, REQ-CLI-04, and REQ-CLI-08.

## Verification

- `pnpm -C packages/protocol exec vitest run test/anim-state.test.ts test/intents.test.ts test/state.test.ts` - PASS, 38 tests.
- `pnpm -C packages/protocol typecheck` - PASS.
- Source checks passed for `packAnimState`, `FACING_OCTANT`, `export type Direction`, no `anim-state.ts -> intents.ts` import, barrel export, strict `monotonic_at_ms`, new PlayerState fields, and `PROTOCOL_VERSION = 4`.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

Ready for 06.7-02 and 06.7-03. The server and client can now compile against the protocol v4 movement surface.

## Self-Check: PASSED

- Key created files exist on disk.
- Production commit `1ba1fe6` exists.
- Plan acceptance criteria passed except full `pnpm trace:check`, which is blocked by documented pre-existing planning artifacts outside this plan's code changes.

---
*Phase: 06.7-network-model-client-trust-fall-trigger*
*Completed: 2026-05-17*