One folder, one bounded contextLLM view

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

SwapFiles changed in contextsFiles changed outsideTests
auth: one issuer to a forked one, real signed tokens0441 pass
billing: in the app to a second process over HTTP0239 pass
one database to two regions0943 pass
flags: a file to OpenFeature0739 pass
all four at once01851 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 outWhat broke laterFix inside the contextDay 0?
the caller's scope reaches the repositorywrong region: not found5 files, 20 linesyes
the caller makes the id (UUIDv7)ids clash across regionsin the same 5 filesyes
contracts are plain databroke over HTTP3 files, 3 linesyes
a write carries a request ida retry charged twice2 files, 16 lines and a columnyes
the principal is neutrala raw token field was empty1 file, 1 lineno
a caller expects "unavailable"said "declined" instead1 file, 4 linesno
flags see the callerno per-user rollout1 file, 3 linesno
  • 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

TopicBefore the module system?What lands later
Multi-regionnoa kernel database adapter and values
Logto and authnoan issuer behind the auth port
Shared services (billing and the rest)nothe same contract, over HTTP
Docs frameworkyes for workspace, by your rulingnone: it must be settled first
Observability (obs)no; the signal port is needed in the language baseseach 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

  • context
  • kernel
  • behind it
orders: 0 files changeorders: 0 files changekernel portkernel porttodaytodaylaterlatercall
1The context only knows the port.
1 / 3
All steps (3)