suaveplan/openspec/archive/2026-05-24-game-server-performance/tasks.md

Tasks: Wave B-5b game-server performance

0. Pre-flight

• pwd && git worktree list && git status — confirm isolated worktree.
• Confirm worktree HEAD is descended from genesis tip.
• Read CLAUDE.md, openspec/AGENTS.md, existing src/core, src/errors, src/types.
• Read upstream reference: /mnt/s/web/suaveplan/packages/universal/game-server/src/performance/{ObjectPool,SessionPool,NetworkTierAdapter}.ts.

1. Error registry

• Append six performance codes to GAME_SERVER_CODES (POOL_EXHAUSTED, POOL_DISPOSED, RELEASE_FOREIGN_OBJECT, INVALID_POOL_CONFIG, INVALID_TIER_CONFIG, UNKNOWN_TIER).
• Extend game-server-error.test.ts with assertions on the new codes.
• Update game-server-error.md to enumerate the new codes.

2. object-pool

• object-pool.types.ts — ObjectPoolConfig, PoolStats, Zod numeric config schema.
• object-pool.ts — generic typed pool with acquire/release/withObject/getStats/clear/dispose, two OTel counters, typed-error boundary, pre-allocation gate.
• object-pool.test.ts — 100% coverage incl. cap rejection + foreign-release rejection + dispose lockout.
• object-pool.md — six sections, ≥200 words.
• index.ts barrel.

3. session-pool

• session-pool.types.ts — PooledSession, PooledSessionData, SessionPoolConfig.
• session-pool.ts — typed wrapper over ObjectPool with acquireSession/releaseSession/withSession, injectable Clock, default session-type configurable.
• session-pool.test.ts — 100% coverage incl. reset path + injected clock + auto-release on throw.
• session-pool.md — six sections, ≥200 words.
• index.ts barrel.

4. network-tier-adapter

• network-tier-adapter.types.ts — NetworkTier, NodeCapabilities, LoadBalancingRecommendation, NetworkTierAdapterStats, Zod schemas, listener typedef.
• network-tier-adapter.ts — registerNodeCapabilities/getTierForNodeType/getTierByIndex/ getOptimalTier/getLoadBalancingRecommendations/ validateTierCapacity/getMaxChildren/getStats/clear, one OTel counter, typed-error boundary, optional onCapabilityUpdated listener.
• network-tier-adapter.test.ts — 100% coverage incl. invalid tier list + duplicate tier index + score-bucket fallbacks.
• network-tier-adapter.md — six sections, ≥200 words.
• index.ts barrel.

5. Wiring

• Re-export every public surface from src/index.ts.
• Add subpath exports to package.json for each module.

6. Verification

• bunx turbo lint typecheck test --filter=@suaveplan/game-server green.
• bunx turbo test:coverage --filter=@suaveplan/game-server = 100/100/100/100.
• grep -rnE "from ['\"](vitest|bun:test)['\"]" packages/gaming/games/game-server/src/ → zero output.
• grep -rn "biome-ignore|TODO|FIXME|XXX" packages/gaming/games/game-server/src/performance → zero output.
• All source files ≤300 lines; all test files ≤500 lines.
• bun run docs:check reports 100% coverage.