Decide first, plug in later
No: you do not need multi-region, Logto or the shared services figured out before this design. They are slots. You do need 4 shapes on day 0, and they cost little now.
The proof: swap each one, see if any context changes
Two contexts and a kernel in Bun. Each swap is its own git branch. MEASURED
| Swap | Files changed in contexts | Files changed outside | Tests |
|---|---|---|---|
| auth: one issuer to a forked one, real signed tokens | 0 | 4 | 41 pass |
| billing: in the app to a second process over HTTP | 0 | 2 | 39 pass |
| one database to two regions | 0 | 9 | 43 pass |
| flags: a file to OpenFeature | 0 | 7 | 39 pass |
| all four at once | 0 | 18 | 51 pass |
The other way round: what hurts if it is left out
A context was written without each shape, then the swap was tried. MEASURED
| Shape left out | What broke later | Fix inside the context | Day 0? |
|---|---|---|---|
| the caller's scope reaches the repository | wrong region: not found | 5 files, 20 lines | yes |
| the caller makes the id (UUIDv7) | ids clash across regions | in the same 5 files | yes |
| contracts are plain data | broke over HTTP | 3 files, 3 lines | yes |
| a write carries a request id | a retry charged twice | 2 files, 16 lines and a column | yes |
| the principal is neutral | a raw token field was empty | 1 file, 1 line | no |
| a caller expects "unavailable" | said "declined" instead | 1 file, 4 lines | no |
| flags see the caller | no per-user rollout | 1 file, 3 lines | no |
- These are small in one context. They are painful when 25 contexts each need them. REASONED.
- Also day 0, in the kernel: the test harness talks to contexts as a cluster would. Without it 6 tests failed when billing moved out of the app. MEASURED
- Two more day-0 rules cost nothing: across contexts a link is an id, and every owned table has its owner column. REASONED.
Each of the five you named
| Topic | Before the module system? | What lands later |
|---|---|---|
| Multi-region | no | a kernel database adapter and values |
| Logto and auth | no | an issuer behind the auth port |
| Shared services (billing and the rest) | no | the same contract, over HTTP |
| Docs framework | yes for workspace, by your ruling | none: it must be settled first |
| Observability (obs) | no; the signal port is needed in the language bases | each context's contract |
- Multi-region still has one open hole here: a job that works across all owners has no home region. Nothing in the design says where it runs. REASONED, NOT TESTED.
- Limit of the proof: Bun only, with two fake regions, a local issuer and an in-memory flag provider. No real Postgres, Logto or regions with lag.
A swap, seen from a context
Animation, 3 steps. Starts with: box orders "orders: 0 files change"; box kernel "kernel port"; box a "today"; box b "later". Connected: orders -> kernel, kernel -> a, kernel -> b. Families, one colour each: ctx "context" (orders); k "kernel" (kernel); out "behind it" (a, b). 1. The context only knows the port. orders -> kernel: call 2. Today the port uses one issuer, one database and billing in the app. kernel -> a: today 3. Later it uses the fork, two regions and billing over HTTP. The context is untouched. kernel -> b: later