1  # Lightspeed Roadmap
  2  
  3  ## Strategy
  4  
  5  Lightspeed should be developed from the protocol inward:
  6  
  7  1. Define lifecycle, protocol, and ISA.
  8  2. Build deterministic runtime tests.
  9  3. Implement a minimal server session actor.
 10  4. Implement a minimal browser client.
 11  5. Integrate with one Gleam HTTP stack.
 12  6. Add ergonomic component APIs.
 13  7. Optimize diffing and patch encoding.
 14  
 15  The main risk is building framework ergonomics before the runtime contract is stable. Do not optimize APIs before lifecycle and protocol invariants are locked.
 16  
 17  ## Phase 0 — Repository constitution
 18  
 19  **Goal:** establish project structure, decision process, and initial vocabulary.
 20  
 21  Deliverables:
 22  
 23  - README
 24  - roadmap
 25  - milestones
 26  - specs directory
 27  - RFC template
 28  - ADR template
 29  - Makefile
 30  - CI workflow
 31  - placeholder Gleam modules
 32  - unit tests for lifecycle and ISA invariants
 33  
 34  Exit criteria:
 35  
 36  - `make ci` is the canonical local verification command.
 37  - every major architectural change has both an RFC and ADR path.
 38  
 39  ## Phase 1 — Core runtime model
 40  
 41  **Goal:** define the minimal live-session model without transport coupling.
 42  
 43  Deliverables:
 44  
 45  - `lightspeed/component`
 46  - `lightspeed/protocol`
 47  - `lightspeed/diff`
 48  - `lightspeed/agent/typestate`
 49  - `lightspeed/agent/isa`
 50  - deterministic test interpreter for ISA programs
 51  - lifecycle transition tests
 52  
 53  Exit criteria:
 54  
 55  - a counter example can be simulated entirely in unit tests.
 56  - illegal lifecycle transitions are impossible through public APIs.
 57  - ISA instructions can be logged and replayed.
 58  
 59  ## Phase 2 — BEAM actor session
 60  
 61  **Goal:** run a live session as a typed BEAM actor.
 62  
 63  Deliverables:
 64  
 65  - session actor module
 66  - typed event inbox
 67  - patch outbox
 68  - crash/restart semantics
 69  - per-session telemetry events
 70  - timeout/heartbeat model
 71  
 72  Exit criteria:
 73  
 74  - one server process owns one live session.
 75  - reconnect can rehydrate or remount based on policy.
 76  - crashes are isolated to the affected session.
 77  
 78  ## Phase 3 — Transport adapters
 79  
 80  **Goal:** connect the runtime to HTTP and WebSocket infrastructure.
 81  
 82  Deliverables:
 83  
 84  - transport behaviour/contract
 85  - WebSocket adapter for one Gleam HTTP stack
 86  - server-rendered initial HTML adapter
 87  - protocol encoder/decoder
 88  - connection authentication hooks
 89  
 90  Exit criteria:
 91  
 92  - browser can mount a live view.
 93  - browser events reach the session actor.
 94  - patches are pushed back and acknowledged.
 95  
 96  ## Phase 4 — Browser runtime
 97  
 98  **Goal:** build the smallest useful client runtime.
 99  
100  Deliverables:
101  
102  - `client/lightspeed.js`
103  - connect/reconnect loop
104  - event delegation
105  - patch application
106  - ack protocol
107  - loading/error states
108  - client-side hooks API draft
109  
110  Exit criteria:
111  
112  - counter example works in a browser.
113  - network disconnect reconnects cleanly.
114  - duplicate patches are idempotent or rejected deterministically.
115  
116  ## Phase 5 — Rendering and diff strategy
117  
118  **Goal:** replace naive full-fragment replacement with stable patches.
119  
120  Deliverables:
121  
122  - HTML fingerprinting strategy
123  - keyed node strategy
124  - patch compression
125  - static/dynamic segment split
126  - server-side diff tests
127  - browser patch conformance tests
128  
129  Exit criteria:
130  
131  - repeated renders of unchanged static regions send no patch payload.
132  - keyed collections avoid unnecessary replacement.
133  - patch stream is versioned.
134  
135  ## Phase 6 — Developer ergonomics
136  
137  **Goal:** make application code feel native to Gleam.
138  
139  Deliverables:
140  
141  - component helpers
142  - router integration layer
143  - form bindings
144  - typed event decoders
145  - examples
146  - generator CLI RFC
147  
148  Exit criteria:
149  
150  - a new developer can build CRUD without reading internals.
151  - errors are actionable and type-directed.
152  
153  ## Phase 7 — Distribution and production hardening
154  
155  **Goal:** make Lightspeed operationally credible.
156  
157  Deliverables:
158  
159  - supervision tree guidance
160  - metrics and tracing
161  - rate limiting hooks
162  - CSRF/session protection
163  - load testing harness
164  - security review
165  - deployment guide
166  
167  Exit criteria:
168  
169  - documented production configuration.
170  - deterministic behaviour under reconnect, crash, slow client, and replay scenarios.