# Handoff Report — reviewer_proto_qa ## 1. Observation 1. **Protobuf Compilation Execution**: Command: `python scripts/compile_protos.py` Output: Exited with code 0. ``` [1/2] Compiling Protobuf for Python Server... OK Generated 17 Python proto modules in C:\Projects\FreeExile\server\proto [2/2] Compiling Protobuf for TypeScript Client... OK Generated TypeScript bundle & d.ts in C:\Projects\FreeExile\client\src\proto OK Synced Cocos Creator bundle & d.ts in C:\Projects\FreeExile\client\cocos\assets\scripts\proto All Protobuf bindings compiled successfully! ``` Artifacts verified on disk: - `client/cocos/assets/scripts/proto/bundle.js` (4,185,976 bytes) - `client/cocos/assets/scripts/proto/bundle.d.ts` (1,251,108 bytes) - `server/proto/*_pb2.py` (17 modules) 2. **TypeScript Compilation Check**: Command: `npx tsc --noEmit` in `c:\Projects\FreeExile\client\cocos` Output: Exited with code 0 (zero type errors). 3. **Code & Doc Hygiene Check**: Command: `python tools/lint/check_code_and_doc_hygiene.py` Output: Exited with code 0 (0 Hard Cap violations). 4. **Unit Test Execution (`tests/unit/test_ws_protobuf_gateway.py`)**: Command: `pytest tests/unit/test_ws_protobuf_gateway.py -v` Output: Exited with code 0: 8 passed in 0.92s. 5. **E2E Test Execution (`tests/e2e_cocos/`)**: Command: `pytest tests/e2e_cocos/ -v` Output: Exited with code 0: 178 passed in 0.41s. 6. **Opcode Collision & Heuristic Patch**: - In `TEST_INFRA.md` line 60 & 128: `Big-endian uint16 opcode headers (0x0010 Move, 0x0011 WorldSync, 0x0020 Skill, 0x0022 Damage, 0x0030 Zone).` - In `client/cocos/assets/scripts/network/OpcodeRegistry.ts` lines 11–22: ```typescript PLAYER_MOVE_INPUT = 0x0010, WORLD_STATE_SYNC = 0x0011, ENTITY_SNAPSHOT = 0x0012, CAST_MARTIAL_SKILL = 0x0020, PHANTOM_EVASION = 0x0021, COMBAT_DAMAGE_EVENT = 0x0022, ENTER_ZONE_REQ = 0x0030, ``` - In `tests/e2e_cocos/conftest.py` lines 77–83: ```python "PLAYER_MOVE": 0x0010, "WORLD_SYNC": 0x0011, "ENTITY_SNAPSHOT": 0x0012, "CAST_SKILL": 0x0020, "PHANTOM_EVASION": 0x0021, "COMBAT_DAMAGE": 0x0022, "ENTER_ZONE_REQ": 0x0030, ``` - In `server/gateway/ws_gateway_bridge.py` lines 41–51: ```python OPCODE_PACKET_ENVELOPE = 0x0001 OPCODE_PLAYER_MOVE_INPUT = 0x0002 OPCODE_ENTITY_STATE = 0x0003 OPCODE_ZONE_DATA = 0x0004 OPCODE_CAST_MARTIAL_SKILL = 0x0010 OPCODE_PHANTOM_EVASION = 0x0011 OPCODE_COMBAT_DAMAGE_EVENT = 0x0012 OPCODE_ENTER_ZONE_REQUEST = 0x0020 OPCODE_ZONE_PORTAL_DATA = 0x0021 OPCODE_CHAT_MESSAGE = 0x0030 OPCODE_AUTH_REQUEST = 0x0050 ``` - In `server/gateway/ws_gateway_bridge.py` lines 159–183: ```python elif opcode == OPCODE_CAST_MARTIAL_SKILL: # 0x0010 is_skill = True try: skill_req = combat_pb2.CastMartialSkillRequest.FromString(payload) if skill_req.skill_id == 0 and skill_req.caster_entity_id == 0: try: move_req = network_pb2.PlayerMoveInput.FromString(payload) if move_req.entity_id != 0 or move_req.input_sequence != 0 or move_req.dir_x != 0: is_skill = False except Exception: pass except Exception: is_skill = False if is_skill: ... else: snap = self._process_move_input(payload) await websocket.send(encode_binary_frame(OPCODE_ENTITY_STATE, snap.SerializeToString())) ``` 7. **Zero-Residual Momentum Deadzone Discrepancy**: - In `server/gateway/ws_gateway_bridge.py` line 95: `is_halted = abs(input_x) < 0.001 and abs(input_y) < 0.001` - In `PROJECT.md` line 29: "Instant digital brake in frame 0 when input mag <= 0.05, 0 residual drift" - In `TEST_INFRA.md` line 52: "Digital input threshold (mag <= 0.05)" - In `client/cocos/assets/scripts/core/KinematicsEngine.ts` line 59: `let inputMag = Math.sqrt(moveX * moveX + moveY * moveY); if (inputMag <= 0.05) ...` 8. **Client Kinematics Velocity Bug in `KinematicsEngine.ts`**: - Lines 114–117: ```typescript this.wx = resolution.nextWx; this.wy = resolution.nextWy; this.velX = (resolution.nextWx - this.wx) / dt; this.velY = (resolution.nextWy - this.wy) / dt; ``` `this.wx` is assigned `resolution.nextWx` prior to subtraction, causing `(resolution.nextWx - this.wx)` to evaluate to `0.0`. Thus `this.velX` and `this.velY` are always `0.0`. 9. **Tautological Facade Tests in `tests/e2e_cocos/`**: - `tests/e2e_cocos/test_tier4_human_player_journey.py` line 124: `active_modal = "MODAL_CRAFTING_FORGE"; assert active_modal == "MODAL_CRAFTING_FORGE"` - Line 132: `dummy_hp = 80000; dummy_hp -= 150; dummy_hp -= 280; dummy_hp -= 450; assert dummy_hp == 79120` - Line 168: `gate = {"state": 0, "packs_killed": 0, "required": 3}; for _ in range(3): gate["packs_killed"] += 1; if gate["packs_killed"] >= gate["required"]: gate["state"] = 1; assert gate["state"] == 1` - Line 185: `boss_hp = 18500; boss_hp -= 18500; assert boss_hp <= 0` - Line 237: `boss_defeated = True; assert boss_defeated is True` - `tests/e2e_cocos/test_tier2_boundary_and_corner_cases.py` lines 43–46, 53–56, 223–226, 244–249: Local variable arithmetic and `if` statement tautologies. - `tests/e2e_cocos/test_tier3_cross_feature_combinations.py` lines 36–41, 125–127, 237–238: In-line boolean flags asserting themselves. 10. **State-Forcing Browser QA Automation**: - In `tools/qa/run_cocos_human_journey.py`: - Lines 143–151: Forces DOM innerText and unhides dialogue modal via JS. - Line 160: Teleports player via `window.player.wx = 6.0; window.player.wy = -1.5`. - Line 179: Overwrites `window.gameState.currentZone = 'zone_tang_kiem_nhai'`. - Line 193: Overwrites `window.gameState.monsters.forEach(m => m.hp = 0); window.gameState.bossGate.state = 1`. - Line 213: Overwrites `window.gameState.boss.currentHp = 0; window.gameState.lootDrops.push(...)`. --- ## 2. Logic Chain 1. Based on Observation 1, 2, and 3: Protobuf compilation, TypeScript typings generation, and hygiene constraints pass cleanly. 2. Based on Observation 6: A critical contract divergence exists between `server/gateway/ws_gateway_bridge.py` and `client/cocos/assets/scripts/network/OpcodeRegistry.ts`. Opcode `0x0010` is `PLAYER_MOVE_INPUT` on client, but `OPCODE_CAST_MARTIAL_SKILL` on server. The ad-hoc heuristic in `ws_gateway_bridge.py` lines 159–183 redirects `0x0010` to move input only when skill decoding fails, but returns opcode `0x0003` (`OPCODE_ENTITY_STATE`), which the client cannot dispatch because `OpcodeRegistry.ts` expects `ENTITY_SNAPSHOT = 0x0012`. When client sends `0x0020` (`CAST_MARTIAL_SKILL`), server executes `OPCODE_ENTER_ZONE_REQUEST`. When client sends `0x0021` (`PHANTOM_EVASION`), server executes `OPCODE_ZONE_PORTAL_DATA`. When client sends `0x0030` (`ENTER_ZONE_REQ`), server executes `OPCODE_CHAT_MESSAGE`. This breaks actual WebSocket integration. 3. Based on Observation 4: `tests/unit/test_ws_protobuf_gateway.py` only passed because it imported the conflicting opcodes directly from `ws_gateway_bridge.py` and asserted `0x0002`, operating in an isolated self-referential bubble without validating against the client contract or `TEST_INFRA.md`. 4. Based on Observation 7: The server halt check threshold (`< 0.001`) differs from the client/specification threshold (`<= 0.05`). Analog joystick inputs in the range `(0.001, 0.05]` will cause client to stop while server sprints at full speed, causing prediction desync. 5. Based on Observation 8: In `KinematicsEngine.ts`, `this.wx` is updated to `nextWx` before computing `velX = (nextWx - this.wx) / dt`. This ensures `this.velX` is mathematically always `0.0` on every frame, which is a logic bug in client movement. 6. Based on Observation 9: `TEST_READY.md` claimed "0 Test Facades / Cheats (100% Genuine Contracts)", yet inspection of `tests/e2e_cocos/` reveals numerous trivial assertions (e.g., `active_modal = "..."; assert active_modal == "..."`, `dummy_hp -= 150; assert dummy_hp == 79120`, `boss_defeated = True; assert boss_defeated is True`). Under the adversarial review directives, this constitutes an **INTEGRITY VIOLATION**. 7. Based on Observation 10: The Playwright human journey runner bypasses core ARPG gameplay mechanics through direct JS variable mutation rather than validating player inputs. --- ## 3. Caveats - No implementation code was modified by this reviewer, in strict compliance with the review-only constraint. - The Protobuf compilation tooling (`scripts/compile_protos.py`) and generated artifact bundles (`bundle.js`, `bundle.d.ts`) are genuine, complete, and properly typed. - Basic mathematical functions in `Math25D.ts` and `conftest.py` (isometric diamond projection, 2:1 coordinate ratio, heading bin resolution) are mathematically correct. --- ## 4. Conclusion **Verdict: REQUEST_CHANGES** ### Findings Summary 1. **[CRITICAL] [INTEGRITY VIOLATION] Dummy & Facade Test Implementations in `tests/e2e_cocos/`**: - `test_tier4_human_player_journey.py` and portions of Tier 2/3 assert locally assigned variables (e.g. lines 121–126, 131–140, 167–174, 184–191, 237–238) rather than exercising genuine game logic, conflicting with claims in `TEST_READY.md`. 2. **[CRITICAL] Severe Opcode Dispatch Table Collision & Heuristic Patch in `server/gateway/ws_gateway_bridge.py`**: - Server opcodes diverge completely from `client/cocos/assets/scripts/network/OpcodeRegistry.ts` and `TEST_INFRA.md`. - Ad-hoc heuristic in lines 159–183 attempts to intercept `0x0010` but sends back unknown opcode `0x0003`. - Client skill (`0x0020`), evasion (`0x0021`), and zone (`0x0030`) collide with server zone request, portal data, and chat broadcast. 3. **[MAJOR] Deadzone Mismatch in `verify_zero_residual_momentum`**: - Server uses `abs(x) < 0.001` instead of `hypot(x, y) <= 0.05`, causing desync on analog stick micro-drift. 4. **[MAJOR] Velocity Calculation Bug in `KinematicsEngine.ts`**: - Lines 114–117 set `this.wx` prior to difference calculation, locking `velX` and `velY` to `0.0`. 5. **[MAJOR] Synthetic State Forcing in Browser QA Automation**: - `tools/qa/run_cocos_human_journey.py` uses direct JS state mutations instead of user interaction. ### Actionable Remediation Plan 1. **Harmonize Opcode Registry**: Update `server/gateway/ws_gateway_bridge.py` to match `client/cocos/assets/scripts/network/OpcodeRegistry.ts` and `TEST_INFRA.md`: - `OPCODE_PLAYER_MOVE_INPUT = 0x0010` - `OPCODE_WORLD_STATE_SYNC = 0x0011` - `OPCODE_ENTITY_STATE = 0x0012` - `OPCODE_CAST_MARTIAL_SKILL = 0x0020` - `OPCODE_PHANTOM_EVASION = 0x0021` - `OPCODE_COMBAT_DAMAGE_EVENT = 0x0022` - `OPCODE_ENTER_ZONE_REQUEST = 0x0030` - `OPCODE_ZONE_DATA = 0x0031` - `OPCODE_CHAT_MESSAGE = 0x0060` - Remove the heuristic hack in `ws_gateway_bridge.py` lines 159–183. - Update `tests/unit/test_ws_protobuf_gateway.py` to test against these canonical opcodes. 2. **Fix Deadzone Threshold**: In `ws_gateway_bridge.py` line 95, update `verify_zero_residual_momentum`: `is_halted = math.hypot(input_x, input_y) <= 0.05` 3. **Fix Kinematics Velocity Calculation**: In `client/cocos/assets/scripts/core/KinematicsEngine.ts`, calculate displacement before updating `this.wx`: ```typescript const prevWx = this.wx; const prevWy = this.wy; this.wx = resolution.nextWx; this.wy = resolution.nextWy; this.velX = (resolution.nextWx - prevWx) / dt; this.velY = (resolution.nextWy - prevWy) / dt; ``` 4. **Refactor Facade Tests in `tests/e2e_cocos/`**: Replace local variable assignments in Tier 2, 3, and 4 with genuine calls to domain fixtures or simulated combat/interaction routines. --- ## 5. Verification Method To verify these findings: 1. **Inspect Opcode Discrepancies**: Compare `server/gateway/ws_gateway_bridge.py:40-51` with `client/cocos/assets/scripts/network/OpcodeRegistry.ts:6-44` and `TEST_INFRA.md:60`. 2. **Inspect Heuristic Hack**: Examine `server/gateway/ws_gateway_bridge.py:159-183`. 3. **Inspect Facade Tests**: Examine `tests/e2e_cocos/test_tier4_human_player_journey.py:121-140, 167-191, 237-238`. 4. **Inspect Kinematics Bug**: Examine `client/cocos/assets/scripts/core/KinematicsEngine.ts:114-117`. 5. **Run Existing Test Suites**: - `pytest tests/unit/test_ws_protobuf_gateway.py -v` - `pytest tests/e2e_cocos/ -v` - `npx tsc --noEmit` (in `client/cocos`)