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

Tasks — game-server-engine-sessions (Wave B-2, re-dispatch)

0. Pre-flight (non-negotiable)

• 0.1 git status clean in worktree, git worktree list accounted for.
• 0.2 Worktree at .claude/worktrees/agent-ae5779d2ba388beff — isolated branch built on current genesis HEAD (71a33ed).
• 0.3 Manifest count unchanged — no new packages added, only modules inside @suaveplan/game-server.

1. Spec authoring

• 1.1 Read upstream SessionNode.ts, SessionTree.ts, SessionStore.ts, PlayerManager.ts, SessionLifecycle.ts.
• 1.2 Read existing Wave A core/interfaces/i-session-manager and i-player-manager.
• 1.3 Read existing openspec/changes/game-server-engine-core proposal as template.
• 1.4 Drafted proposal.md.
• 1.5 Filled ## Source mapping table; FSM-shape requirement listed in the "no source line" table with justification.
• 1.6 Drafted specs/game-server/spec.md.
• 1.7 Every requirement carries **Verified by:** line.

2. Implementation

• 2.1 Extend GAME_SERVER_CODES with session + player codes (11 new).
• 2.2 Extend observability/otel.ts with sessionLifecycleCounter, sessionDwellHistogram, playerLifecycleCounter.
• 2.3 Implement src/engine/session-node/session-node.ts — internal mutable graph node.
• 2.4 Implement src/engine/session-tree/session-tree.ts — graph manager with Zod boundary.
• 2.5 Implement src/engine/session-store/session-store.ts — ISessionManager impl with pluggable persistence.
• 2.6 Implement src/engine/session-lifecycle/session-lifecycle.ts — per-session FSM.
• 2.7 Implement src/engine/player-manager/player-manager.ts — IPlayerManager impl.
• 2.8 Add subpath exports to package.json for all five new feature dirs.

3. Tests

• 3.1 session-node.test.ts — 15 scenarios covering tree walks + persistence round-trip.
• 3.2 session-tree.test.ts — 25 scenarios covering CRUD, integrity audit, restore seam.
• 3.3 session-store.test.ts — ISessionManager conformance harness + persist/restore + orphan handling.
• 3.4 session-lifecycle.test.ts — 15 scenarios covering FSM transitions, history, OTel emission.
• 3.5 player-manager.test.ts — IPlayerManager conformance + heartbeat monitor + reconnection + grace eviction.
• 3.6 Every it(...) carries { timeout: 5000 }.

4. Documentation

• 4.1 Sibling .md for every implementation .ts (6 docs: session-node, session-tree, session-store, session-lifecycle, player-manager, plus extended otel.md).
• 4.2 otel.md updated with new instruments.

5. Pre-archive verification (the 5-gate triple)

• 5.1 bun run lint — Biome 0 errors / 0 warnings.
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/game-server — green (395 tests).
• 5.3 bunx turbo test:coverage --filter=@suaveplan/game-server — 100/100/100/100 (1542/1542 stmts, 574/574 branches, 360/360 funcs, 1491/1491 lines).
• 5.4 bun scripts/openspec-conformance.ts @suaveplan/game-server — to be run by archive step.
• 5.5 bunx turbo build --filter=@suaveplan/game-server — to be run by archive step (orchestrator merges before build run).

6. Pre-archive 7-row checklist (AGENTS.md §13)

• 6.1 Generics threaded; conformance harnesses pass for both interfaces.
• 6.2 Zod schemas wired at SessionData, SessionStoreOptions, PlayerManagerOptions boundaries.
• 6.3 Every new error code thrown by at least one production path and asserted in a test.
• 6.4 Lifecycle path tested both for ok and error outcomes.
• 6.5 OTel instruments emitted from production paths and asserted with the in-memory MeterProvider polyfill.
• 6.6 Reconnection grace window + heartbeat monitor self-rescheduling tested.
• 6.7 No retroactive tick — every box reflects work done in this change.

7. Archive

• 7.1 Fold spec delta into openspec/specs/game-server/spec.md — handled by orchestrator post-merge.
• 7.2 Move folder to archive — handled by orchestrator post-merge.
• 7.3 Refresh MANIFEST.md if package set changed (it did not — additive modules only).