docs: document client-version loading slice

Author: MikelCalvo

README.md

@@ -15,6 +15,7 @@ Current scope of the project:
 - A stub-compatible binary smoke path that reaches `GAME` with the current public bootstrap flows.
 - 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 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.
 - A first self-only `PLAYER_POINT_CHANGE` refresh emitted immediately after the selected-character update.
@@ -113,6 +114,7 @@ Legend:
 - `spec/protocol/auth-login.md`
 - `spec/protocol/login-selection.md`
 - `spec/protocol/select-world-entry.md`
+- `spec/protocol/client-version-loading.md`
 - `spec/protocol/visible-world-bootstrap.md`
 - `spec/protocol/character-update-bootstrap.md`
 - `spec/protocol/player-point-change-bootstrap.md`
@@ -190,7 +192,7 @@ Current stub bootstrap credentials:
 
 Current minimal runtime path exposed by the shipped binaries:
 - `authd`: `HANDSHAKE -> AUTH -> LOGIN3 -> AUTH_SUCCESS`
-- `gamed`: `HANDSHAKE -> LOGIN -> SELECT -> EMPIRE_SELECT? -> CHARACTER_CREATE? -> CHARACTER_SELECT -> LOADING -> GAME -> CHARACTER_ADD -> CHAR_ADDITIONAL_INFO -> CHARACTER_UPDATE -> PLAYER_POINT_CHANGE -> MOVE/SYNC_POSITION`
+- `gamed`: `HANDSHAKE -> LOGIN -> SELECT -> EMPIRE_SELECT? -> CHARACTER_CREATE? -> CHARACTER_SELECT -> LOADING -> CLIENT_VERSION? -> ENTERGAME -> GAME -> CHARACTER_ADD -> CHAR_ADDITIONAL_INFO -> CHARACTER_UPDATE -> PLAYER_POINT_CHANGE -> MOVE/SYNC_POSITION`
 
 This is still a bootstrap runtime, not full gameplay.
 What exists today:
@@ -201,6 +203,7 @@ What exists today:
 - deterministic selected-character `SYNC_POSITION` reconciliation in `GAME`
 - 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
 - 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-client-version-loading.md

@@ -0,0 +1,87 @@
+# Client-Version Loading Slice Implementation Plan
+
+> For Hermes: use test-driven-development. Keep slices tiny and push one commit at a time.
+
+Goal: accept `CLIENT_VERSION` during `LOADING` as tolerant client metadata so a TMP4 client can send it before `ENTERGAME` without desynchronizing the session.
+
+Architecture: freeze a small control-plane codec for `CLIENT_VERSION`, extend world-entry and boot tests to cover the loading-time no-op path, then document the exact packet layout and phase behavior.
+
+Tech stack: Go 1.26, existing frame/session/control/world-entry packages, current authd/gamed bootstrap runtime.
+
+---
+
+## Task 1: Freeze the `CLIENT_VERSION` packet codec
+Objective: define the fixed-width payload shape and decoding behavior.
+
+Files:
+- Modify: `internal/proto/control/control.go`
+- Modify: `internal/proto/control/control_test.go`
+
+Steps:
+1. Write failing tests for:
+   - `CLIENT_VERSION` encode/decode round-trip
+   - invalid payload length rejection
+2. Run: `go test ./internal/proto/control`
+3. Implement the smallest codec set to pass.
+4. Re-run: `go test ./internal/proto/control`
+5. Commit: `feat: add client-version control codec`
+
+## Task 2: Accept `CLIENT_VERSION` in `LOADING`
+Objective: tolerate the client metadata packet without changing session state.
+
+Files:
+- Modify: `internal/worldentry/flow.go`
+- Modify: `internal/worldentry/flow_test.go`
+
+Steps:
+1. Write failing tests for:
+   - `CLIENT_VERSION` is accepted in `LOADING`
+   - the flow returns no frames
+   - the session remains in `LOADING`
+2. Run: `go test ./internal/worldentry`
+3. Implement the smallest loading-phase branch to pass.
+4. Re-run: `go test ./internal/worldentry`
+5. Commit: `feat: accept client-version during loading`
+
+## Task 3: Cover boot composition
+Objective: prove the composed boot flow and TCP harness tolerate `CLIENT_VERSION` before `ENTERGAME`.
+
+Files:
+- Modify: `internal/boot/flow_test.go`
+- Modify: `internal/boot/flow_socket_test.go`
+
+Steps:
+1. Add failing unit and socket tests that send `CLIENT_VERSION` in `LOADING` before `ENTERGAME`.
+2. Run: `go test ./internal/boot`
+3. Re-run after wiring the world-entry path.
+4. Commit: `test: cover client-version loading path`
+
+## Task 4: Update docs
+Objective: document the tolerated loading-time metadata path.
+
+Files:
+- Modify: `README.md`
+- Modify: `spec/protocol/README.md`
+- Modify: `spec/protocol/boot-path.md`
+- Modify: `spec/protocol/session-phases.md`
+- Modify: `spec/protocol/select-world-entry.md`
+- Modify: `spec/protocol/packet-matrix.md`
+- Create: `spec/protocol/client-version-loading.md`
+
+Steps:
+1. Document packet layout and no-response behavior.
+2. Run: `go test ./... && go vet ./...`
+3. Commit: `docs: document client-version loading slice`
+
+## Verification
+- `go test ./internal/proto/control`
+- `go test ./internal/worldentry`
+- `go test ./internal/boot`
+- `go test ./...`
+- `go vet ./...`
+
+## Scope guardrails
+- Do not enforce version matching yet.
+- Do not persist the metadata yet.
+- Do not add a server reply packet.
+- Do not broaden acceptance outside `LOADING` in this slice.

spec/protocol/README.md

@@ -10,6 +10,7 @@ The repository targets TMP4-era client compatibility, but the protocol contract
 - `auth-login.md` — minimal auth-server credential exchange and login-key issuance
 - `login-selection.md` — minimal login-by-key and selection-surface packet layouts
 - `select-world-entry.md` — minimal selection, loading, and enter-game packet choreography
+- `client-version-loading.md` — tolerant `CLIENT_VERSION` metadata path during `LOADING`
 - `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

@@ -89,9 +89,11 @@ Expected outcomes:
 ## 7. Loading/bootstrap completes
 The server sends the minimum required bootstrap data for the selected character.
 This typically includes the main character and player points, plus any other mandatory world bootstrap packets.
+During this phase the client may also emit `CLIENT_VERSION` metadata before it proceeds to `ENTERGAME`.
 
 Expected outcomes:
 - the client accepts the selected character context
+- the server tolerates `CLIENT_VERSION` in `LOADING` without changing phase
 - the client can issue the enter-game action
 
 ## 8. Enter game succeeds
@@ -137,6 +139,7 @@ This document depends on:
 - `spec/protocol/session-phases.md`
 - `spec/protocol/frame-layout.md`
 - `spec/protocol/packet-matrix.md`
+- `spec/protocol/client-version-loading.md`
 - `spec/protocol/character-update-bootstrap.md`
 - `spec/protocol/player-point-change-bootstrap.md`
 - `spec/protocol/sync-position-bootstrap.md`

spec/protocol/client-version-loading.md

@@ -0,0 +1,79 @@
+# Client-Version Metadata During Loading
+
+This document freezes the first minimal `CLIENT_VERSION` slice for the TMP4 boot path.
+
+The goal of this slice is narrow:
+- accept `CLIENT_VERSION` in `LOADING`
+- decode its fixed-width metadata payload
+- keep the session in `LOADING`
+- emit no server response
+
+This slice is intentionally tolerant.
+It does not yet enforce any version policy.
+
+## Covered packet
+
+- `CLIENT_VERSION`
+
+## Envelope
+
+The packet uses 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.
+
+## `CLIENT_VERSION`
+
+Direction:
+- client -> server
+
+Header:
+- `0x000D`
+
+Payload layout:
+- `executable_name` — fixed `33` bytes (`32 + 1`)
+- `timestamp` — fixed `33` bytes (`32 + 1`)
+
+Frame length:
+- `70` bytes total (`4 + 33 + 33`)
+
+String rules:
+- strings are carried in fixed-width fields
+- a trailing zero byte may terminate the string early
+- unused bytes remain zero-filled
+- the server trims at the first zero byte when decoding
+
+## Working flow
+
+The current server-owned behavior is:
+
+1. the session is already in `LOADING`
+2. the client may send `CLIENT_VERSION`
+3. the server decodes `executable_name` and `timestamp`
+4. the server emits no response packet
+5. the session remains in `LOADING`
+6. the client may still proceed to `ENTERGAME`
+
+## Notes
+
+- This packet is currently treated as metadata only.
+- The first implementation does not persist the values.
+- The first implementation does not reject by filename or timestamp.
+- Version gating can be layered in later once compatibility evidence is stronger.
+
+## Slice scope
+
+This slice freezes:
+- packet identity
+- payload layout
+- tolerant acceptance in `LOADING`
+- no-response behavior
+
+It does not yet freeze:
+- any exact build string policy
+- auth/login-time handling
+- repeated-client-version policy beyond "accept and ignore"
+- logging requirements

spec/protocol/packet-matrix.md

@@ -18,7 +18,7 @@ Status values:
 | `KEY_RESPONSE` | client -> server | `0x000A` | handshake | documented | cryptographic response path |
 | `KEY_CHALLENGE` | server -> client | `0x000B` | handshake | documented | challenge + server key material |
 | `KEY_COMPLETE` | server -> client | `0x000C` | handshake | documented | completes key exchange |
-| `CLIENT_VERSION` | client -> server | `0x000D` | late handshake/loading | planned | exact timing to be locked by tests |
+| `CLIENT_VERSION` | client -> server | `0x000D` | loading | documented | accepted as metadata in `LOADING`; no server response and no phase transition |
 
 ## Authentication and selection surface
 

spec/protocol/select-world-entry.md

@@ -20,6 +20,7 @@ It does not yet freeze the full visible-world packet set.
 - `PLAYER_CREATE_SUCCESS`
 - `PLAYER_CREATE_FAILURE`
 - `CHARACTER_SELECT`
+- `CLIENT_VERSION`
 - `ENTERGAME`
 - `MAIN_CHARACTER`
 - `PLAYER_POINTS`
@@ -52,9 +53,10 @@ The current project-owned selection/world-entry flow is:
    - `PHASE(LOADING)`
    - `MAIN_CHARACTER`
    - `PLAYER_POINTS`
-10. the client sends `ENTERGAME`
-11. the server transitions to `GAME`
-12. the server emits:
+10. the client may send `CLIENT_VERSION` metadata while staying in `LOADING`
+11. the client sends `ENTERGAME`
+12. the server transitions to `GAME`
+13. the server emits:
    - `PHASE(GAME)`
    - `CHARACTER_ADD`
    - `CHAR_ADDITIONAL_INFO`

spec/protocol/session-phases.md

@@ -91,6 +91,7 @@ Purpose:
 Typical traffic in this phase:
 - main character bootstrap packet(s)
 - player points / stats
+- `CLIENT_VERSION` metadata from the client
 - optional time/channel/world bootstrap data
 - enter-game request from the client
 
@@ -157,6 +158,7 @@ A packet decoder may still parse them, but the session layer must not process th
 ### `LOADING`
 - a concrete character choice already exists
 - world bootstrap is in progress
+- `CLIENT_VERSION` metadata may be accepted here without changing phase
 - arbitrary in-world actions are still invalid
 
 ### `GAME`