Optional: server-side deep inbound schema validation

[eshaffer321]

Parent Issue

Related to #974 (Deep Payload Schemas)

Overview

PR #976 added deep JSON Schemas for PlayerAction, GameEvent, and ClientGameState as contract artifacts for external clients. Server runtime currently validates envelope + action type discriminant only — full semantic validation is handled by the engine validator layer.

This ticket tracks the optional follow-up of adding Ajv-based deep schema validation at the server WebSocket receive boundary, which would catch structurally malformed payloads (wrong field types, missing required fields) before they reach the engine.

Motivation

• Defense in depth: reject obviously malformed payloads early
• Better error messages for external clients (schema error vs cryptic engine error)
• May simplify engine validators that currently re-check structural concerns

Trade-offs

• Adds ~1-2ms latency per inbound message (Ajv compilation is one-time, validation is fast)
• Duplicates some structural checks already in engine validators
• Schema must stay in sync with TypeScript types (already enforced by CI)

Acceptance Criteria

• Inbound action payloads validated against player-action.schema.json via Ajv
• Schema validation errors returned as PROTOCOL_PARSE_ERROR_INVALID_PAYLOAD with descriptive message
• Performance benchmark shows acceptable overhead (<5ms p99)
• Engine validators that only check structure (not game-state) are identified and documented for potential removal

Notes

This is explicitly optional and low priority. The current enforcement scope (envelope + discriminant) is documented and sufficient for correctness — the engine validators catch everything that deep schema validation would catch, plus game-state-dependent rules.