---
title: "The kernel and its engines"
description: What the kernel owns and what a context gives it.
source: kernel.dh.md
---
<!-- Made by dh llm from the source; nobody edits this file. -->

# 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
1. `context.yaml`: a random id, its owner, what it `needs`, what it `uses`.
2. `register`: hands over routes, tools, jobs, event handlers and the contract it provides.
3. `flags.yaml`, `policies.yaml` and its settings schema.
4. 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
```yaml
# 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.enabled` to 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
