The kernel and its engines
The kernel finds, checks, wires and starts the contexts. It owns everything that is about the platform, the language or the framework. A context owns only its business.
Who owns what
The split is the design (REASONED). Routes, tools, flags, events and the contract test ran in the proofs (MEASURED).
| Thing | The kernel | The context |
|---|---|---|
| Finding and wiring | generated at build time; no scanning at run time | one register function |
| Names | adds the context's name in front | writes the short name |
| URLs, MCP tools | mounts, guards, merges OpenAPI | controllers, models, tools |
| Dependencies | owns dependency.yaml, clients, secrets check | says uses: [db.main], gets its slice |
| Auth | checks the token, makes the principal | policies.yaml: which role may do what |
| Settings | layering, schema check, secrets | its own keys, defaults, schema |
| Data | connection, migration runner, outbox | models, repository, migrations |
| Feature flags | the engine; makes <ctx>.enabled itself | flags.yaml (required) |
| Marketing | the port, the sync to the engine | segments.yaml (only if useful) |
| Analytics | the port; refuses an undeclared event | events.yaml (only if useful) |
| Feedback, customer support | the port; tags the context | nothing |
| Observability | telemetry, the signal port | contract, alerts, runbooks |
| Shared outputs | metric list, flag list, URL map, tool list, policy list, docs index, config schema | none |
| Tests | one contract test over every context | unit, integration, SIT, smoke |
What each context must give the kernel
The design, as built in the proofs. FROM CODE
context.yaml: a random id, its owner, what itneeds, what ituses.register: hands over routes, tools, jobs, event handlers and the contract it provides.flags.yaml,policies.yamland its settings schema.- Optional: segments, events, migrations.
What it gets: one object, nothing global
Routes, tools, jobs, events, signals, settings, database and cache slices, flags, segments, analytics, feedback, support, policies, clock, ids, and a typed client for each context it needs. A name outside its own prefix is refused.
The blind-spot table (generated)
You asked to see the blind spots. This is printed on every build. A missing flags.yaml fails the build. An empty optional cell only shows.
| Context | Flags | Segments | Events |
|---|---|---|---|
| billing | 2 | 1 | 1 |
| orders | 2 | none | 1 |
- Feedback and customer support need no column: the kernel tags every context by itself.
MEASURED in the proofs (this is the Flutter proof's table, reshaped).
The engines: in the kernel, and still shared services
- In the kernel (your model): the definitions, the port, the clients, the generators and the blind-spot table.
- Behind it (decided earlier in the corpus): the running engine, one shared service. Flags are the exception: they are evaluated inside the app, with no server.
- Billing is not an engine. A context that needs it says
needs: [billing.v1], like any other context.
Several hosts, one set of contexts
api, worker, cron, migrate and MCP start from the same folders. Each still deploys as its own module.
What one context writes for the engines
# contexts/invoice/flags.yaml (required; the kernel adds invoice.enabled)flags:newcheckout: { type: bool, default: false, client: true, owner: payments, expires: 2027-03-01 }# contexts/invoice/segments.yaml (optional; code decides who is in it)segments:activepayer: { description: paid in the last 30 days, consent: marketing.email }# contexts/invoice/events.yaml (optional; an undeclared event is refused)events:paid: { props: { amountcents: int, currency: string } }
| Engine | The context's part | How you know which context it is |
|---|---|---|
| Flags | flags.yaml | key invoice.newcheckout |
| Marketing | segments.yaml | segment invoice.activepayer |
| Analytics | events.yaml | event invoice.paid |
| Feedback | nothing | the kernel stamps invoice from the caller or screen |
| Customer support | nothing | the same stamp |
- Switch a context off: set
invoice.enabledto false. Its URLs, MCP tools and jobs go away. MEASURED in all four. - A context another one needs cannot be switched off silently: the kernel refuses with a clear message. MEASURED in .NET; decided for all four.
- "Dynamically register" is done at build time: the kernel finds the folders and generates plain calls. It is as hands-free as scanning, with no surprise at start. MEASURED in all four.
Who calls whom
Animation, 4 steps. Starts with: box orders; box billing; box kernel; box flags "flags, in the app"; box engines "analytics, support, feedback". Connected: orders -> kernel, billing -> kernel, kernel -> flags, kernel -> engines. Families, one colour each: ctx "contexts" (orders, billing); k "kernel" (kernel, flags); svc "shared services" (engines). 1. Each context hands over what it has: routes, tools, jobs, flags and events. orders -> kernel: register billing -> kernel: register 2. The kernel makes each context's switch and answers flags inside the app. kernel -> flags: orders.enabled 3. A context tracks an event by its short name. orders -> kernel: track placed 4. The kernel adds the context and passes it to whichever engine is plugged in. kernel -> engines: orders.placed