1  # Developer Guide
 2  
 3  ## Development loop
 4  
 5  ```sh
 6  make setup
 7  make fmt
 8  make test
 9  make docs
10  ```
11  
12  Before opening a pull request:
13  
14  ```sh
15  make ci
16  ```
17  
18  ## Design workflow
19  
20  For every code change, create both:
21  
22  - an RFC for proposal, design, and impact analysis
23  - an ADR for the accepted architectural decision and consequences
24  
25  Write the RFC first, then the ADR once the decision is accepted.
26  
27  RFCs must cover at least one of these areas when relevant:
28  
29  - public API
30  - wire protocol
31  - ISA
32  - lifecycle
33  - browser runtime
34  - security model
35  - compatibility guarantees
36  
37  PRs must link the RFC and ADR.
38  
39  ## Module rules
40  
41  - `lightspeed/component` is application-facing.
42  - `lightspeed/component/helpers` provides app-facing command helpers.
43  - `lightspeed/protocol` is the wire-facing model.
44  - `lightspeed/agent/isa` is the runtime instruction vocabulary.
45  - `lightspeed/agent/typestate` owns lifecycle transitions.
46  - `lightspeed/transport` must not know component internals.
47  - `lightspeed/diff` must not know transport internals.
48  - `lightspeed/router` resolves paths and emits mount/render ISA sequences.
49  - `lightspeed/event` and `lightspeed/form` own typed payload decoding.
50  - `lightspeed/ops/*` provides production hardening helpers and guidance models.
51  
52  ## Testing rules
53  
54  Every new instruction needs:
55  
56  - opcode test
57  - classification test
58  - protocol encoding/decoding test once encoders exist
59  - simulation test once the test interpreter exists
60  
61  Every lifecycle transition needs:
62  
63  - compile-visible function signature
64  - unit test for exposed state label
65  - doc example showing valid usage
66  
67  ## Naming
68  
69  Use conservative names until the concept stabilizes.
70  
71  Preferred vocabulary:
72  
73  - session
74  - lifecycle
75  - instruction
76  - frame
77  - patch
78  - transport
79  - component
80  - command
81  - effect
82  - agent
83  
84  Avoid overloading Phoenix names unless the behaviour is intentionally equivalent.