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

Tasks — game-server enhanced anti-cheat + interest + lag

1. Error codes

• 1.1 Append 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 to GAME_SERVER_CODES.

2. Anti-cheat validator

• 2.1 src/enhanced/anti-cheat/anti-cheat-validator/anti-cheat-validator.types.ts — Zod schemas for AntiCheatConfig, MovementData, ActionData, RateLimitConfig, MovementConfig, PunishmentThresholds; types for Violation, ValidationResult, PlayerViolationHistory, AntiCheatStats, AntiCheatEventMap, ActionValidator, ValidationContext.
• 2.2 anti-cheat-validator.ts — AntiCheatValidator class with injected Clock + IdGenerator, OTel counter + histogram, listener registry. Public surface: registerValidator, validateMovement, validateAction, checkRateLimit, getPlayerHistory, flagPlayer/unflagPlayer, banPlayer/isPlayerBanned, setTick, getStats/resetStats, clearPlayer, dispose, on/off.
• 2.3 anti-cheat-validator.test.ts — full coverage: movement ok / speed-hack / teleport / timing anomaly / vertical-speed cap; rate limit windowing; custom action validator success + failure + throwing; ban-status auto-escalation; auto-flag threshold; stats and disposal.
• 2.4 anti-cheat-validator.md — Purpose / Features / Usage Basic / Usage Advanced / API Reference / Implementation Notes (≥200 words).
• 2.5 index.ts — named re-exports only.

3. Interest manager

• 3.1 interest-manager.types.ts — Zod schema for InterestManagerConfig; types for Vector3, zone discriminated union (CircularZone | RectangularZone | CustomZone), TrackedEntity, PlayerSubscription, EntityVisibility, VisibilityChange, InterestStats, InterestEventMap.
• 3.2 interest-manager.ts — InterestManager class with injected Clock, OTel histogram + counter. Public surface: registerZone, unregisterZone, updateEntity, removeEntity, registerPlayer, updatePlayerPosition, unregisterPlayer, subscribeToZone, unsubscribeFromZone, getVisibleEntities, calculateVisibilityChanges, isInZone, getZonesAtPoint, getZone/getAllZones/getEntity, start/stop, getStats, dispose, on/off. No timer side-effects in constructor.
• 3.3 interest-manager.test.ts — full coverage: zone register / unregister / sweep; entity add/move/remove; player register / view-distance cap; subscribe/unsubscribe; visibility enter/exit deltas; rectangular vs circular vs custom zone containment; stats; dispose.
• 3.4 interest-manager.md.
• 3.5 index.ts.

4. Lag compensator

• 4.1 lag-compensator.types.ts — Zod schema for LagCompensatorConfig; types for PlayerLatency, CompensatedState, HitValidationRequest, HitValidationResult, LagCompensatorStats, LagCompensatorEventMap, StateSnapshot.
• 4.2 lag-compensator.ts — LagCompensator class with injected Clock, bounded ring buffer per entity. Public surface: recordState, updateRtt, getPlayerLatency, getStateAtTime, validateHit, getTrackedEntities, clearEntityHistory, removePlayer, getStats/resetStats, dispose, on/off.
• 4.3 lag-compensator.test.ts — full coverage: state recording + pruning; RTT sample windowing; latency statistics; exact-match / before-only / after-only / interpolated lookups; max-compensation clamp; hit validation valid + invalid + missing-state; events; stats reset; dispose.
• 4.4 lag-compensator.md.
• 4.5 index.ts.

5. Wiring

• 5.1 Add subpath exports for the three new modules to package.json.
• 5.2 Add new module re-exports to src/index.ts (Wave C-2 block).

6. Verification

• 6.1 bunx turbo lint typecheck test --filter=@suaveplan/game-server — green.
• 6.2 bunx turbo test:coverage --filter=@suaveplan/game-server — 100/100/100/100.
• 6.3 No from "vitest" / from "bun:test" in src/.
• 6.4 No biome-ignore / TODO / FIXME / XXX in src/.

7. Archive

• 7.1 Fold the spec delta into openspec/specs/game-server/spec.md and move the change folder to openspec/archive/<yyyy-mm-dd>-game-server-enhanced-anti-cheat-lag/ after merge.