docs: document game ping-pong slice

Author: MikelCalvo

README.md

@@ -16,6 +16,7 @@ Current scope of the project:
 - A deterministic single-character `MOVE` round-trip wired through the current bootstrap runtime.
 - A deterministic selected-character `SYNC_POSITION` reconciliation path wired through the current bootstrap runtime.
 - A tolerant `CLIENT_VERSION` metadata path accepted during `LOADING` before `ENTERGAME`.
+- A tolerant `PONG` control path accepted in `GAME` for server-driven ping probes.
 - Character deletion on the selection surface with deterministic success/failure responses.
 - A first visible-world bootstrap that inserts the selected character into the game world after `ENTERGAME`.
 - A first self-only `CHARACTER_UPDATE` refresh emitted immediately after the visible-world insert.
@@ -117,6 +118,7 @@ Legend:
 - `spec/protocol/select-world-entry.md`
 - `spec/protocol/character-delete-selection.md`
 - `spec/protocol/client-version-loading.md`
+- `spec/protocol/game-ping-pong.md`
 - `spec/protocol/visible-world-bootstrap.md`
 - `spec/protocol/character-update-bootstrap.md`
 - `spec/protocol/player-point-change-bootstrap.md`
@@ -207,6 +209,7 @@ What exists today:
 - bootstrap movement updates character coordinates and persists them across fresh auth/game sessions
 - empty-account bootstrap flow can select empire before first character creation, and that choice persists across fresh auth/game sessions
 - tolerant `CLIENT_VERSION` acceptance in `LOADING` with no phase transition and no server response
+- tolerant `PONG` acceptance in `GAME` with no phase transition and no server response
 - the selected character is inserted into the visible world after `ENTERGAME` via minimal `CHARACTER_ADD` + `CHAR_ADDITIONAL_INFO` + `CHARACTER_UPDATE` + `PLAYER_POINT_CHANGE`
 
 What still does not exist yet:

docs/plans/2026-04-18-game-ping-pong.md

@@ -0,0 +1,69 @@
+# Game Ping/Pong Slice Implementation Plan
+
+> For Hermes: use test-driven-development. Keep slices tiny and push one commit at a time.
+
+Goal: freeze the first minimal control-plane `PING`/`PONG` behavior for a session that is already in `GAME`, so a future server-side ping probe can receive a valid client `PONG` without desynchronizing the world session.
+
+Architecture: extend the control codec with explicit `PING` encode and `PONG` decode helpers, teach the `GAME` flow to accept `PONG` as a phase-stable no-op, then document the narrowed scope in protocol docs.
+
+Tech stack: Go 1.26, existing `internal/proto/control`, `internal/game`, and protocol docs.
+
+---
+
+## Task 1: Freeze `PING`/`PONG` codec helpers
+Objective: make the control codec symmetric for the minimal server-driven ping path.
+
+Files:
+- Modify: `internal/proto/control/control.go`
+- Modify: `internal/proto/control/control_test.go`
+
+Steps:
+1. Write failing tests for:
+   - `PING` encode against the frozen fixture
+   - `PONG` decode for a header-only frame
+2. Run: `go test ./internal/proto/control`
+3. Implement the smallest codec changes to pass.
+4. Re-run: `go test ./internal/proto/control`
+5. Commit: `feat: add game ping-pong control support`
+
+## Task 2: Accept `PONG` in `GAME`
+Objective: allow the live game session to tolerate the automatic client reply path.
+
+Files:
+- Modify: `internal/game/flow.go`
+- Modify: `internal/game/flow_test.go`
+
+Steps:
+1. Write a failing test proving `PONG` is accepted in `GAME`.
+2. Run: `go test ./internal/game`
+3. Implement the smallest game-phase branch to decode and ignore `PONG`.
+4. Re-run: `go test ./internal/game`
+5. Keep the session in `GAME` and emit no server frames.
+
+## Task 3: Update docs
+Objective: record the phase-stable in-world control path.
+
+Files:
+- Modify: `README.md`
+- Modify: `spec/protocol/README.md`
+- Modify: `spec/protocol/boot-path.md`
+- Modify: `spec/protocol/packet-matrix.md`
+- Modify: `spec/protocol/session-phases.md`
+- Create: `spec/protocol/game-ping-pong.md`
+
+Steps:
+1. Document the packet layouts and the no-response `PONG` behavior.
+2. Note that the current slice does not yet add a periodic ping scheduler.
+3. Run: `go test ./... && go vet ./...`
+4. Commit: `docs: document game ping-pong slice`
+
+## Verification
+- `go test ./internal/proto/control ./internal/game`
+- `go test ./...`
+- `go vet ./...`
+
+## Scope guardrails
+- Do not add a timer loop or heartbeat scheduler in this slice.
+- Do not introduce disconnect policy for missed replies yet.
+- Do not broaden the slice into movement, chat, or warp work.
+- Do not invent extra `PONG` payload fields.

spec/protocol/README.md

@@ -12,6 +12,7 @@ The repository targets TMP4-era client compatibility, but the protocol contract
 - `select-world-entry.md` — minimal selection, loading, and enter-game packet choreography
 - `character-delete-selection.md` — deterministic character deletion in `SELECT`
 - `client-version-loading.md` — tolerant `CLIENT_VERSION` metadata path during `LOADING`
+- `game-ping-pong.md` — minimal control-plane `PING`/`PONG` behavior once the session is in `GAME`
 - `character-update-bootstrap.md` — first self-only state refresh after entering `GAME`
 - `player-point-change-bootstrap.md` — first self-only point refresh after entering `GAME`
 - `sync-position-bootstrap.md` — first self-only sync-position reconciliation after entering `GAME`

spec/protocol/boot-path.md

@@ -141,6 +141,7 @@ This document depends on:
 - `spec/protocol/packet-matrix.md`
 - `spec/protocol/character-delete-selection.md`
 - `spec/protocol/client-version-loading.md`
+- `spec/protocol/game-ping-pong.md`
 - `spec/protocol/character-update-bootstrap.md`
 - `spec/protocol/player-point-change-bootstrap.md`
 - `spec/protocol/sync-position-bootstrap.md`

spec/protocol/game-ping-pong.md

@@ -0,0 +1,89 @@
+# Game Ping/Pong Control Path
+
+This document freezes the first minimal control-plane `PING`/`PONG` behavior relevant once a session is already in `GAME`.
+
+The goal of this slice is deliberately narrow:
+- preserve the `PING` packet layout as server-owned control data
+- accept a header-only client `PONG` while the session is in `GAME`
+- keep the session in `GAME`
+- emit no server response when `PONG` is received
+
+This slice does not yet add a periodic ping scheduler.
+It only freezes the packet codec and the accepted reply path.
+
+## Covered packets
+
+- `PING`
+- `PONG`
+
+## Envelope
+
+The packets use the project-wide CG/GC frame envelope:
+
+- `header` — `uint16`, little-endian
+- `length` — `uint16`, little-endian, total frame size including the 4-byte envelope
+- `payload` — packet-specific bytes
+
+See `frame-layout.md` for the envelope contract.
+
+## `PING`
+
+Direction:
+- server -> client
+
+Header:
+- `0x0007`
+
+Payload layout:
+- `server_time` — `uint32`, little-endian
+
+Frame length:
+- `8` bytes total (`4 + 4`)
+
+Notes:
+- `server_time` is control-plane compatibility data.
+- The first implementation only freezes the codec; it does not schedule periodic probes yet.
+
+## `PONG`
+
+Direction:
+- client -> server
+
+Header:
+- `0x0006`
+
+Payload layout:
+- none
+
+Frame length:
+- `4` bytes total (`4 + 0`)
+
+Notes:
+- `PONG` is a header-only control reply.
+- The first implementation accepts it in `GAME` as a no-op.
+
+## Working flow
+
+The current server-owned behavior is:
+
+1. the session is already in `GAME`
+2. the server may emit `PING(server_time)`
+3. the client may reply with `PONG`
+4. the server accepts `PONG`
+5. the server emits no response packet
+6. the session remains in `GAME`
+
+## Slice scope
+
+This slice freezes:
+- `PING` encode support
+- `PONG` decode support
+- tolerant `PONG` acceptance in `GAME`
+- no-response behavior for `PONG`
+- phase-stable handling in the live game session
+
+It does not yet freeze:
+- periodic ping cadence
+- timeout or disconnect policy
+- server-time synchronization semantics beyond the carried `server_time` field
+- acceptance of `PONG` outside the currently documented phases

spec/protocol/packet-matrix.md

@@ -12,8 +12,8 @@ Status values:
 
 | Name | Direction | Header | Phase | Status | Notes |
 | --- | --- | --- | --- | --- | --- |
-| `PONG` | client -> server | `0x0006` | handshake/control | documented | response to server ping |
-| `PING` | server -> client | `0x0007` | handshake/control | documented | includes `server_time` |
+| `PONG` | client -> server | `0x0006` | handshake/game control | documented | accepted as a header-only reply to server `PING`; phase-stable in `HANDSHAKE` and `GAME` |
+| `PING` | server -> client | `0x0007` | handshake/game control | documented | carries `server_time`; current slice freezes the codec and the matching `PONG` reply path |
 | `PHASE` | server -> client | `0x0008` | control | documented | phase transition control packet |
 | `KEY_RESPONSE` | client -> server | `0x000A` | handshake | documented | cryptographic response path |
 | `KEY_CHALLENGE` | server -> client | `0x000B` | handshake | documented | challenge + server key material |

spec/protocol/session-phases.md

@@ -111,6 +111,7 @@ Initial milestone scope:
 Typical traffic in this phase:
 - move
 - sync position
+- control-plane `PING`/`PONG` that should not disturb the live phase
 - minimal world updates
 
 ## 6. `CLOSE`
@@ -165,6 +166,7 @@ A packet decoder may still parse them, but the session layer must not process th
 ### `GAME`
 - a character is bound to the connection
 - movement is allowed
+- control-plane `PONG` may be accepted here without changing phase
 - later milestones may enable additional systems here
 
 ## Notes for implementation