1  # ADR-0010 — Phase 2 Session Actor Core
 2  
 3  Date: 2026-05-07
 4  
 5  Status: Accepted
 6  
 7  ## Context
 8  
 9  Lightspeed needed a Phase 2 session actor module that models live session ownership and runtime behavior before HTTP/WebSocket transport adapters are introduced.
10  
11  Phase 1 established deterministic ISA simulation, but it did not expose a typed session inbox/outbox contract or crash/restart and heartbeat semantics for one live session.
12  
13  ## Decision
14  
15  Adopt `lightspeed/agent/session` as the Phase 2 actor core:
16  
17  - typed inbox events wrapped in owner-scoped `InboxMessage`
18  - typed outbox messages for patches and telemetry
19  - explicit reconnect policy (`Rehydrate` / `Remount`)
20  - crash, restart, shutdown, and heartbeat timeout behavior
21  - ack-based pending patch removal
22  - per-session telemetry labels for operational traces
23  
24  This ADR implements RFC-0009.
25  
26  ## Consequences
27  
28  Easier:
29  
30  - one module now models one live session with clear state transitions
31  - tests can validate crash/restart and timeout paths without transport
32  - phase boundary to transport adapters is cleaner (inbox/outbox contract exists)
33  
34  Harder:
35  
36  - owner identity is currently a string, not a BEAM pid type
37  - future transport/actor integration must preserve these semantics
38  
39  ## Alternatives considered
40  
41  - postpone session actor until transport phase
42  - implement actor semantics only inside tests
43  - use a generic map state without typed inbox/outbox unions