suaveplan/openspec/archive/2026-05-05-network-plugin-session/tasks.md

Tasks — network-plugin-session

Blocked on: network-core, network-plugin-topology.

1. Scaffold

• 1.1 packages/network/network-plugin-session/ with package.json (@suaveplan/network-plugin-session@0.0.0), tsconfig.json, vitest.config.ts, README.md.
• 1.2 Workspace deps: @suaveplan/network, @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/fsm, @suaveplan/governance (or inline election), @suaveplan/timing, @opentelemetry/api, zod.
• 1.3 sideEffects: false.

2. Types

• 2.1 src/types/session.types.ts — Session, SessionId, SessionConfig, SessionRules, SessionState.
• 2.2 src/types/tree.types.ts — SessionTree, SessionNode, SessionPath.
• 2.3 src/types/message.types.ts — SessionMessage, SessionScope, SessionEnvelope.
• 2.4 src/types/transition.types.ts — SessionTransition, TransitionType, SessionSnapshot.
• 2.5 src/error-codes.ts — defineCodes("NET_SESSION", [...]).

3. Session tree

• 3.1 src/tree/session-tree.ts — SessionTree maintains parent/child relationships.
• 3.2 Root session is created automatically when plugin starts.
• 3.3 createSession(parentId, config), destroySession(sessionId).
• 3.4 getSessionPath(sessionId) returns ancestor chain.
• 3.5 Prevents cycles.

4. Session manager

• 4.1 src/session/session-manager.ts — SessionManager.
• 4.2 join(sessionId, peerId) — adds peer to session, removes from previous leaf.
• 4.3 leave(sessionId, peerId) — removes peer, moves to parent session.
• 4.4 move(peerId, fromSessionId, toSessionId) — atomic leave + join with snapshot.
• 4.5 Emits session:joined, session:left, session:moved on NetworkBus.

5. Session router

• 5.1 src/router/session-router.ts — SessionRouter.
• 5.2 Intercepts send(targetId, envelope) from NetworkNode.
• 5.3 If envelope has sessionId header, delivers only to peers in that session or its descendants.
• 5.4 If envelope has scope: 'parent', delivers only to parent session host.
• 5.5 If envelope has scope: 'broadcast', delivers to all peers in session branch.
• 5.6 If no session scope, defaults to peer's current leaf session.

6. Session host election

• 6.1 src/election/session-host-election.ts — SessionHostElection.
• 6.2 Uses same scoring as governance (latency, uptime, reputation) but scoped to session peers.
• 6.3 Election triggered on host leave or periodic health check.
• 6.4 Emits session:host-changed on bus.

7. Session transition manager

• 7.1 src/transition/session-transition-manager.ts — SessionTransitionManager.
• 7.2 On join: requests state snapshot from session host, applies it locally.
• 7.3 On leave: emits session:peer-left so host can clean up peer state.
• 7.4 On move: creates forwarding tunnel from old host to new host for in-flight messages.
• 7.5 Uses @suaveplan/fsm for transition states: idle → requesting → syncing → active → leaving → complete.

8. Parent state bridge

• 8.1 src/bridge/parent-state-bridge.ts — ParentStateBridge.
• 8.2 Configurable read-only keys replicated from parent to child sessions.
• 8.3 Examples: worldTime, weather, globalEvent.
• 8.4 Child session peers receive parent state updates but cannot send to parent.

9. Session capacity enforcer

• 9.1 src/capacity/session-capacity-enforcer.ts — SessionCapacityEnforcer.
• 9.2 Rejects join when peers.length >= capacity.
• 9.3 Emits session:capacity-exceeded on bus.
• 9.4 Optional: triggers session:split-requested when capacity exceeded and parent allows splitting.

10. Session registry

• 10.1 src/registry/session-registry.ts — SessionRegistry.
• 10.2 Tracks all sessions: id, hostId, peerCount, capacity, depth.
• 10.3 Syncs to NetworkBus for mesh-wide discovery.
• 10.4 Consumed by assignment engine for placing new peers.

11. Plugin wrapper

• 11.1 src/plugin/session-plugin.ts — SessionPlugin implements NetworkPlugin.
• 11.2 Installs session manager, router, election, transition, bridge, capacity, registry on install().
• 11.3 Intercepts NetworkNode.send() to inject session routing.

12. Spec

• 12.1 Update openspec/specs/network-session/spec.md with NET-SESS-01 through NET-SESS-12.

13. Conformance tests

• 13.1 src/session/session.spec-conformance.test.ts — create, destroy, join, leave, move.
• 13.2 src/router/router.spec-conformance.test.ts — scope filtering, upward routing, broadcast.
• 13.3 src/election/election.spec-conformance.test.ts — per-session host, independence from mesh host.
• 13.4 src/transition/transition.spec-conformance.test.ts — snapshot transfer, forwarding tunnel.
• 13.5 src/capacity/capacity.spec-conformance.test.ts — enforcement, rejection, split.
• 13.6 src/bridge/bridge.spec-conformance.test.ts — parent state replication, read-only.
• 13.7 src/registry/session-registry.spec-conformance.test.ts — tree tracking, peer counts.
• 13.8 src/error-codes.spec-conformance.test.ts — frozen registry.

14. Verify

• 14.1 bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-session green.
• 14.2 bunx turbo test:coverage --filter=@suaveplan/network-plugin-session 100/100/100/100.
• 14.3 bun scripts/openspec-conformance.ts @suaveplan/network-plugin-session PASS.

---

Audit Note (2026-05-05)

Status: SHIPPED — every section delivered at full quality (100/100/100/100 coverage, 100% docs, openspec-conformance PASS, 90 tests across 11 files). One scope adjustment from the original spec:

• The CYCLE_DETECTED error code is omitted because the public createSession API rejects duplicate ids (SESSION_ALREADY_EXISTS) and missing parents (PARENT_NOT_FOUND) before any cycle-forming assignment can land. The remaining six NET_SESSION codes cover every reachable failure path.

The shipped surface (SessionTree, SessionManager, SessionRouter, SessionHostElection, SessionTransitionManager, ParentStateBridge, SessionCapacityEnforcer, SessionRegistry, SessionPlugin) covers NET-SESS-01 through NET-SESS-12 from the network-session spec.