suaveplan/openspec/archive/2026-05-24-game-server-enhanced-anti-cheat-lag/proposal.md

Wave C-2 — game-server enhanced: anti-cheat + interest management + lag compensation

Why

The @suaveplan/game-server package's Wave A–B foundation (core / engine / state / network / matchmaking / performance) is in place. The next layer — the enhanced/ family — adds server-authoritative safeguards and broadcast-scope optimisations needed for any open-world multiplayer game.

Wave C-2 ships the three foundational enhanced/ modules that are entirely self-contained from a dependency standpoint and underpin the rest of the enhanced/ tree (anti-cheat consumed by leaderboard/persistence; interest management by state-sync; lag compensation by replay/state-sync):

• enhanced/anti-cheat/anti-cheat-validator/ — server-authoritative move / action validator with movement, rate-limit, and custom-action rules; player-violation history; punishment escalation FSM.
• enhanced/interest-management/interest-manager/ — area-of-interest manager: circular/rectangular/custom zones, per-player view-distance culling, priority-weighted entity visibility, visibility-change deltas.
• enhanced/lag-compensation/lag-compensator/ — server-side state-rewind + RTT-aware hit validation: per-entity bounded snapshot ring buffer, per-player RTT statistics (avg/min/max/jitter), interpolated state lookups, clamped compensation.

What Changes

Add three feature modules under packages/gaming/games/game-server/src/enhanced/, each as a self-contained 5-files-per-feature directory:

• anti-cheat/anti-cheat-validator/{anti-cheat-validator.ts,.test.ts,.types.ts,.md,index.ts}
• interest-management/interest-manager/{interest-manager.ts,.test.ts,.types.ts,.md,index.ts}
• lag-compensation/lag-compensator/{lag-compensator.ts,.test.ts,.types.ts,.md,index.ts}

Behaviour shift versus the upstream main implementation:

• Inject Clock (and where ids are minted, IdGenerator) from @suaveplan/types rather than reading Date.now/Math.random directly.
• Replace ad-hoc Logger dependency + EventEmitter inheritance with a pluggable listener registry (no @suaveplan/events runtime dep) and OTel metrics for observability.
• Throw GameServerError via the package-wide GAME_SERVER_CODES registry on invalid input or out-of-bounds operations instead of silently returning sentinel values.
• Validate all caller-supplied configuration with Zod at the boundary.

Extend GAME_SERVER_CODES with the following new codes (appended, no re-order):

• CHEAT_DETECTED
• INVALID_VALIDATION_RULE
• INVALID_ANTI_CHEAT_CONFIG
• INTEREST_REGION_INVALID
• INVALID_INTEREST_CONFIG
• INTEREST_PLAYER_NOT_REGISTERED
• LAG_COMPENSATION_HISTORY_EXCEEDED
• INVALID_LAG_COMPENSATION_CONFIG
• LAG_COMPENSATION_ENTITY_NOT_TRACKED

Extend package.json exports map additively with subpath exports for the three new feature modules.

Impact

• Affected specs: game-server (new requirements for enhanced anti-cheat, interest management, lag compensation).
• Affected code: packages/gaming/games/game-server/src/enhanced/** (new), packages/gaming/games/game-server/src/errors/game-server-error.ts (new codes appended), packages/gaming/games/game-server/package.json (additive subpath exports), packages/gaming/games/game-server/src/index.ts (re-exports for the three new modules).
• Out of scope: all other enhanced/* subtrees (leaderboard, persistence, replay, tournament, service-discovery, state-sync, timing) — owned by Wave C-3/C-4. The orchestrator src/index.ts is updated only to add the three Wave C-2 re-exports.