1  # ADR-0014 — Phase 6 Developer Ergonomics Layer
 2  
 3  Date: 2026-05-07
 4  
 5  Status: Accepted
 6  
 7  ## Context
 8  
 9  Lightspeed had stable runtime pieces through Phase 5 but application code still required manual low-level plumbing for routes, form payload parsing, typed event decoding, and command construction.
10  
11  Phase 6 roadmap goals require ergonomic APIs that remain explicit and type-directed.
12  
13  ## Decision
14  
15  Adopt a small public ergonomics layer with four modules:
16  
17  - `lightspeed/component/helpers`
18  - `lightspeed/router`
19  - `lightspeed/form`
20  - `lightspeed/event`
21  
22  Also add CRUD-focused example documentation under `examples/crud`.
23  
24  Key properties of this decision:
25  
26  1. Preserve runtime/transport boundaries by keeping helpers purely application-facing.
27  2. Keep decoders explicit and result-based rather than implicit coercion.
28  3. Reuse existing ISA instructions instead of adding new runtime opcodes.
29  4. Capture generator CLI direction in a dedicated RFC without binding implementation now.
30  
31  This ADR implements RFC-0013 and records acceptance of RFC-0014 as forward direction.
32  
33  ## Consequences
34  
35  Easier:
36  
37  - new application code can define routes, typed events, and forms without reading internals
38  - command construction is less repetitive and more consistent
39  - errors become explicit and type-directed at the API boundary
40  
41  Harder:
42  
43  - additional public modules expand compatibility surface
44  - route/form/event helper APIs will need migration discipline as protocol/client evolve
45  
46  ## Alternatives considered
47  
48  - keep ergonomics out of scope until after production hardening
49  - expose only a router API and defer form/event helpers
50  - build macro-style APIs instead of explicit helper modules