Skip to content

Architecture ​

Substrat is one decomposition seen two ways: a stack of layers (what the code is) and a request path across isolated databases (how it runs). Both pictures are below.

The three layers ​

Everything hangs off one split — humans and hard guarantees below the line, AI velocity above it. Every band is a real, shipping package.

Verticals

Everything a user touches — the businesses themselves.

own vocabulary · screens · pricing · roles

Handlebarbike workshopKallkällacoffee shopMeridianHRManyfoldheadless CMS
the line
Above ↑ AI velocity — mistakes are cosmetic (a wrong screen)↓ Below humans + runtime guarantees — mistakes are catastrophic (a tenant leak)

composes engines in-scope, same transaction

Engines

Headless domain machinery that owns invariants. Star topology — they talk to the kernel, never to each other.

own invariants · versioned · never forked

workorderone state machine · append-only time + materialbookingresource × interval × capacity · one allocation, no locksinvoicingconsumes billable events · immutable once exportedprotocolchecklists + signed docs · freeze → immutable, hashedinviteshashed identifier · accept-required · non-enumerablenotificationspreferences + delivery records · email via platform intentassistantthread record + run lease + exact-input approval · host integration pending

↓ ctx (sql · check · emit · link)  ·  events + audit ↑

Kernel

The substrate. Everything true of every B2B SaaS — and nothing true of any one.

owns no domain entities

IdentityNested tenancyPermissions + grantsEvents / audit spineMigrationsGDPR machineryEmail intentsJobsBilling entitlementsModule systemAttachment contractsApp shell
Every operation runs insidectx.sqlctx.checkctx.emitctx.link

No customer table, no work-order table. It offers attachment contracts that bind to opaque (entityType, entityId) refs the vertical defines.

same kernel semantics on any ground — one contract-test suite gates them all

Adapters

Scope hosts — the interchangeable ground the kernel is seated on.

swappable · escrowable · self-hostable

adapter-sqlitedev · CI · self-host / escrowadapter-cloudflareproduction · Durable-Object per scopeadapter-emailnotification transport · CF Email + mock

Connectors

The outside world, at the edges. React to events on the spine — host code, never module code.

no fetch inside a module — ever

Scrive eSignsignatures-requested → BankID signing → recorded back…moreone port per capability

The four rules that hold it together

  1. 1Kernel owns no domain entities. It provides the spine; verticals define what the entities mean.
  2. 2Star topology. Engines cooperate through fat events and opaque refs — never by importing each other. N contracts, not N².
  3. 3Enforced at runtime. Guarantees are defaults of the substrate, not config a builder — human or AI — can get wrong.
  4. 4No forking. If a vertical ever needs to fork an engine, the engine drew its line wrong.

Topology ​

your codeVerticalTypeScript · often AI-built@substrat-run/kernel API onlykernelScope hostgetScope(principal, tenant, scope)holding a stub is the authorizationone isolation domainScope · branch #1its own database + ACLserialized — one op at a timeone isolation domainScope · branch #240its own database + ACLserialized — one op at a timeevents, kernel-stampedkernel-ownedEvent spineaudit · reporting · integrations
The same shape on every adapter — one SQLite file per scope locally, one Durable Object per scope in production. Nothing above the stub can widen its own reach.

The invariants this picture encodes:

  • The only data path from vertical code to operational data is the scope stub. Holding a stub is the authorization to talk to that scope — and the scope still re-validates every call against its own ACL.
  • A live subscription sends permission-filtered invalidation hints, not entity payloads. The client fetches changed data through its declared read operation, with that operation's checks. See Reads & live updates.
  • Events are emitted below the API surface. Vertical code cannot emit on another scope's behalf, suppress an audit event, or edit its envelope.
  • Ambient tenancy. After obtaining a stub, vertical code never passes tenant or scope IDs again — context rides inside the stub and the operation context. There is no ID parameter to get wrong.

The scope: unit of isolation and consistency ​

A scope is one isolation domain — a housing association, a branch office, a client company, a brand. Each scope has:

  • its own database (one SQLite file locally; a SQLite-backed Durable Object on the Cloudflare adapter),
  • strict serialization — one operation at a time, run to completion. No interleaved read-modify-writes, no lost updates, no need for row locking in module code,
  • a structured-clone boundary — inputs and results are cloned even in-process, so code can never share mutable state with a scope.

Operations run inside the scope's execution domain: one hop to reach the scope, then local, synchronous SQL. This is what makes engine invariants enforceable — the handler sees sql, emit, and check; the caller sees only invoke().

See Tenants & scopes and Operations & the scope host.

Contracts first, adapters below ​

Every boundary-crossing data shape is a Zod schema in @substrat-run/contracts — the reviewed artifact is the runtime validator ("parse, don't trust"). The kernel's behavioral seams are pure TypeScript interfaces in @substrat-run/kernel that import no platform APIs.

Platform specifics live only in adapters:

AdapterBackingUse
@substrat-run/adapter-sqliteone SQLite file per scope, per-scope actorlocal dev, CI, self-host
@substrat-run/adapter-cloudflareSQLite-backed Durable Object per scope + a durable control-plane DOproduction

The rule is testable and non-negotiable: a module's contract tests must pass unchanged on both adapters — and they do: the shared conformance suite runs green on the pure-SQLite adapter in Node and on the Cloudflare adapter in real workerd against Durable Objects. Neither is a mock; both implement the same semantics (serialization, clone boundary, fail-closed addressing, stamped envelopes). This is what makes local development deterministic, CI cloud-free, and the self-host/escrow story literally true — and it's how a vertical moves from laptop to Cloudflare with no code change.

The hosted runtime ​

The topology above is adapter-neutral. Here is what it becomes on the Cloudflare adapter — the production shape. The one thing to hold onto: every box is a Durable Object with its own SQLite. There is no shared cluster; a tenant's data sits in its own isolated database, and the router's only job is to find the right door.

How a request travels

response · metered at the routerBrowseracme.ticket0.substrat.runthe requestcloudflare edgeRouterOne per environment.Finds the door; cannot open it.kernel onlyhostname → nodedurable objectControl-plane DOThe directory.One per environment.kernel onlydispatch · asserts the node + ROUTER_SECRETworker · one per versionThe vertical workerYour pushed bundle. No public route, no state between requests.Kernel hostgetScope() · permission gate · meteringVertical HTTProutes, error envelope, session → principalConnector codethe only place fetch() is allowed to existsession → principalgetScope() · invoke()durable objectIdentity DOOne per tenant.Users, sessions, the owner seat.kernel onlydurable objectScope DOIts own SQLite. One operation at a time.Vertical operations — ctx.check(), then ctx.sqlEngine functions — the same transactionKernel spine — events, outbox, links, migrations
One bundle, two execution environments. The worker is trusted with addressing and never with data; the scope holds the data and cannot reach the network.
1

Browser hits a hostname edge

A tenant, a vertical, and a surface — all encoded in the name.

acme.ticket0.substrat.run
2

The router resolves the door kernel worker · 1 per env

One kernel-owned worker in front of every vertical. Its only binding is the control plane — it reads the directory to turn hostname → (tenant, scope, vertical, surface). It finds the door; it cannot open a scope even by mistake.

reads → Control-plane DB
3

Header handshake, then dispatch compute

Every client x-substrat-* header is stripped; the router asserts the resolved node plus a shared secret, then dispatches to the vertical worker. The vertical has no public route — the router is the only way in.

4

Vertical worker resolves who you are compute

The vertical worker holds no state between requests. It resolves your session to a principal in the tenant’s own identity database.

reads → Identity DB (this tenant)
5

Open the scope, run the operation compute

Gate the scope’s lifecycle & tenancy, then invoke() runs the operation inside the scope’s own SQLite, in one transaction — permission check first, mutation emits an event, the outbox drains to consumers and connectors. Roll back on any throw.

reads + writes → Scope DB (this scope)
6

Response travels back up edge

Back through the router, the one place that knows the tenant — so it meters the request there, one datapoint per call.

The three databases

Directory

Control-plane DB

one per environment
  • Tenant registry & scope lifecycle
  • Roles, tenant grants, entitlements
  • Hostnames, verticals & versions
  • Connections (ciphertext only)
  • The admin audit log

Knows which door — never what’s behind it. A single singleton DO.

Application / auth

Identity DB

one per tenant
  • Users, sessions, credentials
  • Its own auth engine, own SQLite
  • The login → principal map
  • The owner seat, set at provision

Separate DO, separate storage — one tenant’s users can’t leak to another.

Business data

Scope DB

one per scope
  • The vertical’s entities & kernel spine
  • Events, outbox, entity links
  • Applied migrations
  • Scope-level grants & permissions

Where ctx.sql runs — one transaction per operation.

How the databases get created

The trick: a Durable Object’s database springs into existence the first time you address it by id. There is no CREATE DATABASE and no migration server — provisioning is just addressing a new DO and letting it build itself.

1

Write the directory row. The coordinator records the new scope in the control plane — the door now exists, gated by the tenant.

2

Address the Scope DO. The moment it’s named, its SQLite is born. A lazy migration builds the kernel spine and runs the vertical’s own module migrations in order — a PITR bookmark taken before each pass.

3

Project permissions in. The tenant’s current roles and grants are copied into the fresh scope so it can decide access from its own storage — then the migration frontier is recorded back to the directory.

4

Identity DB, likewise. The tenant’s Identity DO is created on first address — tables on construction, the owner seat set at provision, waiting to be claimed by the first login.

Why the shared control plane isn’t a shared blast radius

A normal vertical runs “CP-less” on the hot path: it decides permissions from the scope’s own storage and trusts the node the router asserted — the shared control plane is off the request path entirely. It still owns provisioning and the audit spine, but a request serving one tenant never touches another tenant’s data, or the shared directory, to answer.

The result: the same kernel guarantees, a per-tenant database, and a shared control plane whose failure can’t read or corrupt a running scope. Isolation is the default, not a configuration you can forget.

Modules: how everything joins ​

Engines and verticals join a host the same way — as modules. A module registration bundles:

  • a manifest — self-describing metadata: permissions (with human-readable descriptions), events emitted and consumed, migrations, attachment targets, entity relations, an entitlement key, and optional UI contributions;
  • migrations — plain SQL, journaled per module, applied lazily per scope inside the scope's serialization domain;
  • operations — named handlers ('workorder/create') invoked through scope stubs;
  • event consumers — handlers for event types other modules emit;
  • schedules — recurring work, fired by the deployment's own sweeper under a system actor rather than by a cron the module holds.

An authored operation that declares a permission must still call ctx.check. The host records a finding when such a handler completes without checking; strict test runs can refuse that completion. The declaration alone does not grant access.

A vertical increasingly does not write most of that. It declares its entities, operations and permissions once in the model, and the manifest's entity fragments, permission list, event list and DDL are derived from that declaration — with CI failing on drift between the declaration and what is checked in.

See Modules & the manifest.

Some effects are not the scope's to make: giving someone a tenant-wide role writes directory state, outside any one scope's transaction. A module asks for those with an event, committed with its own write, and an executor effects them out of band, as host code that holds the authority module code never does. It runs inline after the commit, with the outbox as its retry backstop, and can refuse a request outright. The kernel ships one such executor, for membership: it assigns the role an accepted invite names, or takes it away on a removal, only within the authority of whoever asked. See the connector seam.

Calling another vertical: the peer door ​

Start with Cross-vertical communication to choose between a synchronous call, a queued request and an event import. It diagrams the transaction and permission boundaries. The declarations and runnable local example follow here.

Two verticals of one tenant sometimes need each other's operations. A board-room app reads customers from a CRM, for example. Neither call is a person acting, so there is no user token to carry, and an API key pasted into the other app's settings would be a second enforcement system beside the kernel. Instead, the platform says which app is calling:

  • The target declares its peers. The peers entry in its module manifest names the calling vertical, the operations it may invoke and the permissions it holds while doing so. Those are granted as vertical:<slug> at provisioning and listed in PERMISSIONS.md, so widening what another app may do is a reviewed permission diff. See peers.
  • The caller acts as itself, recorded as { vertical, scope }: the calling app and the instance that called. Checks inside the operation are ordinary, no person comes along, and the caller holds no credential of its own.
  • Same tenant only. The target is found by slug, as the tenant's one primary, active instance of that vertical. It is never found by hostname or in another tenant, it is never a preview, and it is never guessed when a tenant runs two instances.
  • Revocation takes effect on the next call. A tenant can switch a peer off on a scope. That removes everything the peer held there, and no re-provision gives it back. The switch is recorded outside the scope too, so a restore or a point-in-time rewind to before it does not let the peer back in, and a peer whose only access comes from a tenant-wide grant can be switched off as well. A caller that has been suspended or uninstalled is refused on its next call. The scope also limits a peer to the keys in the running declaration, so narrowing or removing that declaration takes effect on the next call even if an older grant row remains.

Writing one ​

The target declares who may call it, in its module manifest. The keys are derived from the operations each peer may invoke, so the two halves cannot drift apart:

ts
// spec/model.ts — the CRM's own operations, as any model-first vertical declares them
export const crmOperations = defineOperations(crmEntities, CRM_PERMISSIONS)({
  'customer/list': { summary: 'List customers', permission: 'customer:read', /* … */ },
  'customer/get': { summary: 'One customer', permission: 'customer:read', /* … */ },
  'customer/delete': { summary: 'Delete a customer', permission: 'customer:manage', /* … */ },
});

// src/manifest.ts
export const crmManifest = moduleManifest.parse({
  id: '@acme/crm',
  // … the rest of the manifest
  ...peersDeclaredBy(crmOperations, {
    // The board-room app may list and read customers. `customer:read` is read off those
    // two operations; `customer:manage` is not, so deleting stays out of reach.
    'acme/board-room': ['customer/list', 'customer/get'],
  }),
});

That lands in the CRM's PERMISSIONS.md, so widening what another app may do is a reviewed permission diff rather than a quiet edit.

The caller declares the verticals it calls, in its package.json — the same place outbound names the third-party hosts it may reach:

json
{ "substrat": { "slug": "acme/board-room", "calls": ["acme/crm"] } }

Then it calls, with no address, no token and no allowlist entry of its own:

ts
import { peerClient } from '@substrat-run/vertical-host';

const { items } = await peerClient('acme/crm').invoke<{ items: { id: string; name: string }[] }>(
  'customer/list', { limit: 50 },
);

Module code — an operation, a consumer, a schedule — takes the other leg, because it runs inside the scope's Durable Object where there is no network at all. It enqueues the call and the platform delivers it, at-least-once:

ts
import { PEER_INVOKE_KIND } from '@substrat-run/contracts';

const requestId = ctx.requestPlatform({
  kind: PEER_INVOKE_KIND,
  payload: { vertical: 'acme/crm', operation: 'customer/list', input: { limit: 50 } },
});

The request ID is an enqueue receipt, not the operation result. The drain uses it as the idempotency key; inspect the platform request for delivery status.

Both hosted legs are gated by the same calls declaration, and the caller on both is the scope the platform found the work in — never anything the request or the payload said.

If a team runs multiple live instances of a target vertical, a team admin chooses the target on the calling app's page. The choice belongs to that caller instance: another instance of the same caller has its own choice. Clearing it restores the ambiguous refusal. A suspended bound target refuses while suspended and works again after it is restored. An archived or deleted bound target remains an unavailable choice until the admin clears or changes it; the platform never substitutes another instance. A queued peer-invoke names the vertical, and resolves its target when the drain executes it. A binding changed after enqueue therefore changes where that queued call goes. Archiving invalidates a choice durably; unarchiving the same target does not reactivate that choice until the admin binds it again.

The refusals, and what each means ​

What you seeWhat happened
this app declares it calls X, and you do not run oneThe tenant has no instance of the target. Not an error — the ordinary state of a fresh install.
403 naming substrat.callsThe caller did not declare this target. Add it and push.
403 naming the peer's slugThe target's peers does not name this caller, or names it without the operation.
403 "switched off"A tenant pulled the kill switch on this peer. Only restoring it gives access back.
409 "runs N instances … bind the instance first"The tenant runs two live instances of the target. Choose one on the calling app's page.
409 "bound instance … unavailable"The explicit choice no longer names a live target. Restore a suspended target, or clear or change the choice.
403 from a previewA preview never makes peer calls. Run the two locally against the pure host instead.

A complete local example ​

This Node harness runs two verticals in one tenant. It declares a read operation, derives the peer's permissions from that operation, makes a call, cuts access off, and restores it. There are no migrations or persisted domain rows: the CRM returns one fixed example customer.

In an ESM project using the packages from this release, install the dependencies:

sh
npm install @substrat-run/contracts @substrat-run/kernel @substrat-run/adapter-sqlite
npm install --save-dev tsx

Save the following as peer-example.mts, then run npx tsx peer-example.mts:

ts
import assert from 'node:assert/strict';
import { mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import {
  z, defineEntities, defineOperations, errorCodeOf, manifestOperations, moduleManifest,
  peersDeclaredBy, permissionKey, platformActorId, scopeId, tenantId,
} from '@substrat-run/contracts';
import { assertAllowed, operationsFor, ulid } from '@substrat-run/kernel';
import { SqliteScopeHost } from '@substrat-run/adapter-sqlite';
import { createLocalVerticalBroker } from '@substrat-run/adapter-sqlite/vertical-broker';

const operations = defineOperations(defineEntities({}), ['customer:read'] as const)({
  'customer/list': {
    summary: 'List customers',
    permission: 'customer:read',
    input: z.object({ limit: z.number().int().min(1).max(50) }),
    output: z.object({ items: z.array(z.object({ id: z.string(), name: z.string() })) }),
  },
});
const manifest = moduleManifest.parse({
  id: '@acme/crm', version: '1.0.0', kernelContract: '^0.0.1',
  entitlementKey: 'crm', attachmentTargets: [],
  migrations: { journalDir: './migrations', compatibleFrom: '1.0.0' },
  ...manifestOperations(operations, { permissions: { 'customer:read': 'Read customers' } }),
  ...peersDeclaredBy(operations, { 'acme/board-room': ['customer/list'] }),
});
const dir = mkdtempSync(join(tmpdir(), 'substrat-peer-example-'));
const crm = new SqliteScopeHost({ dir: join(dir, 'crm') });
const board = new SqliteScopeHost({ dir: join(dir, 'board') });
const staff = platformActorId.parse(ulid());
const tenant = tenantId.parse(ulid());
const crmScope = scopeId.parse(ulid());
const boardScope = scopeId.parse(ulid());

try {
  crm.registerModule({
    manifest, migrations: [],
    ...operationsFor(operations)({
      'customer/list': async (ctx) => {
        assertAllowed(await ctx.check(permissionKey.parse('customer:read')));
        return { items: [{ id: 'example', name: 'Example company' }] };
      },
    }),
  });
  for (const host of [crm, board]) {
    await host.admin.createTenant(staff, { id: tenant, slug: 'example', name: 'Example' });
  }
  await crm.admin.grantEntitlement(staff, tenant, 'crm');
  await crm.provisionScope(staff, { tenantId: tenant, scopeId: crmScope, vertical: 'acme/crm' });
  await board.provisionScope(staff, { tenantId: tenant, scopeId: boardScope, vertical: 'acme/board-room' });
  await crm.admin.activateScope(staff, tenant, crmScope);
  await board.admin.activateScope(staff, tenant, boardScope);

  const broker = createLocalVerticalBroker({ 'acme/crm': crm, 'acme/board-room': board });
  const caller = broker.clientFor({ vertical: 'acme/board-room', tenantId: tenant, scopeId: boardScope });
  const read = () => caller.invoke('acme/crm', 'customer/list', { limit: 50 });
  const expected = { items: [{ id: 'example', name: 'Example company' }] };
  assert.deepEqual(await read(), expected);

  const peer = { vertical: 'acme/board-room', node: { tenantId: tenant, scopeId: crmScope } };
  await crm.admin.revokeFromPeer(staff, { ...peer, reason: 'Exercise the switch' });
  await assert.rejects(read, (error: unknown) => errorCodeOf(error) === 'forbidden');
  await crm.admin.restoreToPeer(staff, { ...peer, reason: 'Exercise complete' });
  assert.deepEqual(await read(), expected);
  console.log('Peer call, refusal, and restore passed.');
} finally {
  await crm.close();
  await board.close();
  rmSync(dir, { recursive: true, force: true });
}

The broker belongs only in a Node harness or test. It verifies the caller's live primary scope and uses the target's real peer door; it does not exercise hosted substrat.calls enforcement, egress, or service bindings. Never import it into module or Worker code.

Seeing and changing access ​

After installation, the dashboard app page shows App-to-app access: declared outgoing targets and incoming peers. A target that is not installed is neutral. For an incoming peer, Cut off and Let back in require a reason; the status shows who switched access off, when, and why. The console's scope page offers the same controls in Peers. A failed status read is unknown, never permission to call. Re-provisioning does not restore access.

Hosted rollout (platform operators) ​

Deploy the router with apps/router/src/index.ts as its entry module; it exports the public fetch handler and the named PeerCalls entrypoint. Then deploy the egress worker with this service binding in apps/vertical-egress/wrangler.jsonc:

json
{ "binding": "PEER_CALLS", "service": "substrat-router", "entrypoint": "PeerCalls" }

The test environment binds substrat-router-test instead. Both declarations are checked in. Update the control plane for peer delegation and async delivery, and redeploy participating verticals with the peer routes and declarations from this release. Use the existing platform secret configuration. A missing PEER_CALLS binding fails closed with a refusal naming the binding and config file; it never falls through to an outbound fetch. An old target without the status/switch routes requires a redeploy. These are deployment steps, not actions an app author performs by adding substrat.calls.

Composition: star topology ​

Engines talk to the kernel, never to each other. No engine imports or calls a sibling. Composition happens through three kernel-mediated channels:

  1. Opaque refs — attachment contracts bind to (entityType, entityId) without knowing what the entity is.
  2. Events — an engine reacts to another's schema-versioned events. A contract, not a call: the invoicing engine consumes workorder.completed andcommerce.order-placed — events from two different domains — without importing a single type from either producer.
  3. Vertical-owned orchestration — synchronous flows that need two engines are wired in the vertical, where the glue is visible and editable.

This keeps compatibility at N kernel contracts instead of N² engine pairs, and keeps each engine independently versioned. The corollary test: if two engines need chatty synchronous communication, they are one engine drawn wrong — which is why "work orders + time reporting" is one engine, not two.

Between verticals: exports and imports ​

The same rule holds one level up. Two verticals of one tenant, such as a CRM and a board-room app, each in its own scope with its own audience, integrate by event. Neither reaches into the other's data. Each side declares its half:

  • The producer exports what may leave: events.exports, each type with the permission a receiver must hold. An emitted type that is not exported never leaves its scope.
  • The consumer imports what it takes, and names the vertical it comes from: events.consumes: [{ from, type, schemaVersion }]. Its handlers go under imports in its module registration.

Delivery is a pull on a watermark the consumer keeps. The platform reads the producer's outbox after that watermark, inside the producer's scope and through the producer's own code, then hands the batch to the consumer. The consumer runs each handler in its own transaction together with its delivery record, which makes delivery at-least-once with one effect per event per module. It then moves the watermark, last, in its own database. As a result:

  • A consumer installed after the producer receives the exported history.

  • Restoring the consumer re-delivers whatever the restore undid.

  • Same tenant only. The platform resolves each end as the tenant's one primary instance of that vertical. It never resolves by hostname or across tenants. A preview or a fork is never either end.

  • Identity is the peer door. The receiver must hold the export's key, as vertical:<slug>, in the producer's scope. The producer enters the consumer's scope as itself, { vertical, scope }, and its handlers' checks are real. A peer switched off on either side pauses the edge: nothing is read, the watermark holds, and nothing is lost when the peer is switched back on.

  • Only events classified piiClass: 'none' cross. Erasing a subject cannot reach what another vertical derived from a payload, so personal data travels by a governed call instead. A classified event is withheld: the consumer is told it was sent, and never receives its content.

  • Loops are cut. An event's cause chain may cross at most 8 vertical boundaries.

  • Every edge is visible. Each platform sweep reports every edge as delivered, idle, paused or unresolved. A paused or unresolved edge also writes a sweep-run record with the reason.

The hosted transport, router kick, replay/skip controls, edge-health view and exported-schema checks are implemented. A routed response can trigger delivery within seconds; events from schedules, peer calls and imports wait for the sweep. A replay deliberately runs handlers again. A promote dropping or re-versioning an export a running consumer uses requires acknowledgement. Individual bindScopeVersion changes do not yet have that export-break gate.

The event resolver still requires unique primary instances at both ends. The caller-instance binding used by peer calls does not select an event-stream target. Chapter 7's worked example follows both paths, their permissions and their failure behavior with diagrams.

Language: TypeScript end-to-end ​

Verticals are TypeScript regardless of what the kernel is written in — React UIs, prompt-to-app tools, and coding agents all emit it. Keeping the kernel in TypeScript means one source of truth at the most important interface in the system: "invalid states unrepresentable" materializes directly at the SDK boundary (branded ID types, discriminated unions, literal types) rather than through generated bindings.

Types erase at runtime, so they are never the enforcement: every trust boundary validates at runtime with the same Zod schemas, and the guarantees that matter are structural — the scope boundary, capability stubs, kernel-side stamping — not type-level. Types are ergonomics, especially for agents; the enforcement doesn't depend on the compiler.