The platform layer
A Substrat vertical is not a SaaS product that happens to share some libraries. It is an application deployed onto a platform — and the platform below it owns tenancy, routing, custom domains, identity, entitlements, and the event history tier. This page is about that layer: what it gives you, what it deliberately does not share, and why the boundary falls where it does.
Status
The platform layer runs in production. Shipping on both adapters: scope provisioning, the directory, the tenant registry, tenant + scope lifecycle transitions (with fail-closed gating), the entitlement gate, and the host admin surface — every mutation of which takes a platform actor and writes an append-only audit log. Since this page was first written the router and custom-domain issuance, the ops console, the builder dashboard, per-PR previews, directory backup/restore, and the platform-owned outbound seams (connections, egress policy, email) have all landed. What is still designed-and-unbuilt is called out where it appears.
One platform, N deployments
Each vertical gets its own kernel-runtime deployment, hosting that vertical's scopes. Different verticals are separate deployments with separate storage namespaces. It's tempting to read that as every vertical re-erects the whole platform. It doesn't — and the split between what's shared and what isn't is the design:
| Shared — the platform owns it | Per-vertical | |
|---|---|---|
| Routing | Resolves hostname → (tenant, scope, vertical, surface), then dispatches | The surfaces a manifest declares |
| Custom domains | Hostname issuance, DNS validation, certificate lifecycle | — |
| Tenancy | Tenant registry, scope directory, provisioning lifecycle | — |
| Identity | Auth callbacks, principal derivation, capability minting, the persona issuer a seeded preview signs in through | — |
| Entitlements | The entitlement store, operation gate and scope-local projection | The entitlementKey each manifest declares; how its plan and quota are used |
| History & analytics | The event spine and its history tier | — |
| Copies | Snapshots, forks, per-PR previews, per-scope PITR, directory backup/restore | — |
| The outside world | Connections and their sealed credentials, the outbound egress seam, the email relay, inbound mail on the platform's receiving subdomain (mail-in) | The declared allowlist, the connectors a manifest requires, and connectors it ships itself |
| Admin | Directory, audit log, access log, ops-failure log; the console and the builder dashboard | — |
| Execution | — | The scope's code: kernel + engines + your modules, and their migrations |
Everything a vertical would hate to rebuild is already shared. The only per-vertical thing is the code that runs inside a scope.
The scope's code is the app binary; the platform beneath it is one platform.
So building a second vertical does not mean standing up a second Substrat. It means shipping a second binary onto the same substrate — new modules, new vocabulary, new screens, against the same tenancy, the same permission model, the same event spine, the same domains machinery.
The platform also implements the deployment and lifecycle machinery for scope stores: separate objects a vertical declares by binding and driver. Their storage is included in full scope dumps, erasure, reaping and the storage meter. Hosted scope stores are not available yet. One driver is registered, graph, and it serves only the verticals its registration names. Store-driver releases have their own rollout and rollback, separate from a vertical's code release, and a release is used only once staff have approved it. None is approved yet, so a hosted push declaring a graph store passes the push check and is refused before anything is uploaded.
Why the deployments don't merge
The obvious follow-up: if the platform is shared anyway, why not run every vertical's modules in one deployment and let entitlements decide which are active per scope?
It's a coherent design — it's how ordinary multi-tenant SaaS works — and it is rejected, for one reason that dominates the others:
- Migrations would be globally ordered across unrelated verticals. Every scope would carry every vertical's modules, and module registration order is a migration-ordering contract. A change to another vertical's migration list would touch your scopes.
- Blast radius would merge. A bad deploy of someone else's module code would take down your scopes.
- Upgrades would go lockstep. A shared binary means every vertical upgrades together — so you could not stay on engine v2 while another vertical moves to v3. Verticals on Substrat are often owned by different companies. Forcing one to upgrade because another shipped is the forced-upgrade treadmill that has degraded every extensible business platform that tried it.
The shared-bundle alternative also trades a structural guarantee for a configuration guarantee — isolation would hold because the entitlement config says so, rather than because nothing is addressable. Substrat consistently refuses that trade: vertical code never gets a raw handle to the storage namespace, it gets a capability stub for one scope, so cross-scope access isn't denied — it's unreachable.
Scope lifecycle
provisioning → active ⇄ suspended, then → archived → reaped
Provisioning is idempotent and journaled, safe to re-run and safe to drive from a reconciliation sweep (Tenants & scopes). Provisioning requires an existing active tenant — a scope can never be orphaned. A provisioned scope serves nothing until it is activated. The rest of the lifecycle is control-plane work; every transition is validated (an illegal one fails closed) and audited:
- Suspend fails
getScopeclosed for that scope; suspending a tenant does the same for every scope under it, without touching their rows. It's how an incident or a non-payment is contained without deleting anything — the same fail-closed path that stops a confused-deputy bug. - Archive stops the scope serving and nothing more: it is a status change, the scope's storage stays where it is, and un-archive returns it to
activewith its data intact. A scope can be archived fromprovisioningtoo — that is how a failed or stuck provision is abandoned — and the archive records the status it left. - Reap is what releases the storage. Only an archived scope can be reaped, by staff, or by the sweep when a deployment opts in with a retention window (
reapArchivedAfterDays; on the hosted control plane,SCOPE_RETENTION_DAYS) and the scope has been archived longer than it. Without a window, an archived scope stays, and stays metered, until someone reaps it. The reap wipes the scope's database, and the directory row stays as a tombstone, with the audit trail and the burned slug. The event history already shipped to the history tier is not touched. Reaped is terminal. - Storage is metered until reap. The storage gauge counts every scope that holds data, archived and suspended ones included, because their bytes are still there. A scope archived straight from
provisioningnever held data and is not counted. - Jurisdiction is immutable. Fixed at provisioning; a scope's execution domain can never relocate. There is no edit affordance because there is no edit.
Asking the platform for something: intents, not calls
A vertical sometimes needs a privileged action it structurally cannot perform: provision a sibling scope (a new Manyfold "site"), send mail, reach a third party. The obvious design is an upward call — the vertical holds a platform credential and invokes the control plane. It is rejected for the same reason the shared bundle above is: a credential in vertical code is a configuration guarantee, and the whole point is that the reach should not exist.
Instead the vertical enqueues an intent into its own scope, and the platform comes and gets it:
// inside an operation, AFTER the vertical's own permission check
const id = ctx.requestPlatform({
kind: 'provision-sibling',
payload: { slug, name, owner: principal },
});- The row lands in this scope's
_substrat_platform_requestsspine table, atomic with the operation — if the handler throws, the intent never happened. - Origin fields (
id,requestedAt,requestedBy) are stamped kernel-side, exactly as an event envelope is. The vertical cannot claim to be someone else. - The platform's drain reads that scope's DO, so it knows the tenant inherently — the tenant is not in the payload and cannot be forged into it.
kindselects the platform-side handler, which validates the payload. To the kernel the payload is opaque, like an event's.- A scope may hold at most
MAX_PENDING_PLATFORM_REQUESTS(32) pending intents; past thatrequestPlatformthrows. A stuck or runaway vertical cannot flood the drain.
Authorization is the vertical's; isolation is the platform's. That split is why the intent is enqueued after the vertical's own ctx.check.
On a hosted request, the vertical flags a newly queued intent in its response, naming the scope the intent went into. The router then asks the control plane to drain in the background. The control plane always drains the scope the router resolved, and drains the named one too when both are live installs (active, not a preview or a fork) of the same tenant and vertical. It re-derives both from the directory, so the flag carries no authority. This usually reduces the wait to seconds without holding up the response. If that notification fails, the durable intent stays queued for the control plane's periodic sweep.
And the outcome comes back. ctx.platformRequests(filter) reads this scope's own intent journal — newest first, filterable by kind and status — returning the same record the platform settled, with its result or lastError. That read exists for one concrete reason: a contract whose signature request settled failed can say so on its own screen, instead of showing a document that appears to be out for signature and is not. The kernel owns every write to the table, so a status is only ever the platform's answer. The one row it did not write is one a restored dump brought in, and such a row may not decode: it is still returned beside every other intent, carrying a decodeError that names the columns that did not, and the drain settles it failed rather than act on what it could not read.
Scheduled work
The platform runs one recurring pass — the platform sweep — that does every unit of scheduled work the system has, in a fixed order: reconciling stragglers' migrations, draining retryable effects and pending platform intents, sampling scope storage for the stored gauge, re-running the provision hook where a scope's bound version has moved past the one it was provisioned against, running each vertical's declared schedules, judging its declared freshness expectations, reaping expired previews and long-archived scopes and lapsed tenants, reconciling connectors, draining each scope's domain events to Tier 2 through the injected EventSink — absent a sink, nothing drains — then pruning outbox rows drained more than 90 days ago (what the prune keeps), and shipping the staff access log last. The full list with what each phase skips is on the platform-sweep.ts row. Three of those phases leave a durable per-unit record that the console and /sweep-runs read — each live connection swept, each schedule run, each freshness verdict — when a deployment configures the recorder; the rest report through the pass's own summary. It is the scheduler's unit of work; it holds no timer of its own. A deployment with a directory drives it: a node server calls startPlatformSweeper at boot, the hosted control plane runs it from a 15-minute cron, and definePlatformSweeperDO is the alarm-driven trigger for a Cloudflare deployment that holds its own directory. A vertical deployed into the dispatch namespace (which does not honour wrangler crons) does not run the platform sweep at all. It runs a scope sweeper (defineScopeSweeperDO, bound as SWEEPER; the uploader supplies one when the vertical declares schedules and exports none). That sweeper is a singleton alarm that walks its own roster of scopes and runs drainDue and the due schedules for each.
Because module operations run in the vertical's own runtime — where its code and its scopes' data live — a vertical's schedules run there, in that vertical's sweeper, not in the control plane (whose scope storage is empty by design). The control plane's pass does the platform-side work instead: it reaches each scope over the vertical's /internal surface to drain its intents, sample its storage, reconcile its provision and reap it. For each vertical that declares schedules, its sweeper enumerates its live scopes and invokes each due operation under a system actor, recording per-scope outcomes and stepping over any failure rather than letting it sink the pass. A schedule fires no more often than its cadence, tracked per scope; a fork or snapshot is skipped, so a test copy never runs real recurring side effects.
Entitlements gate operations and carry plans
Every manifest declares an entitlementKey. The platform holds a set of entitlements per tenant, and checks it when a scope invokes an operation — default-deny, uncached today (a DO-cached variant is an open benchmark).
A module's handlers are registered with the deployment, but an invocation whose tenant lacks its key is refused as not_found before the handler runs. A revoke or expiry therefore takes effect at the operation boundary without redeploying the vertical. A module's own declared schedule, invoked through its system door, is the exception: its system grant is the switch, so background cleanup does not stop when a tenant's entitlement expires.
The flag also carries a plan. An entitlement is not only an on/off SKU: a grant carries a plan (the tier), a quota and an expiresAt, which a vertical reads at request time through ctx.entitlement(key) / ctx.entitlements() to gate features and enforce quota within a module it already holds. Entitlements are an operation gate and a feature/plan surface. The kernel enforces two things itself: presence (the gate above) and expiry, which fails closed at the gate exactly as a revoke would; quota and plan are expression only — the vertical reads the number and enforces its own meaning. For a hosted vertical these are read from a scope-local projection, so gating a feature needs no control-plane binding. It is the same mechanism as the operation gate and, like it, uncached today (a DO-cached variant is the open benchmark).
Why the admin console isn't a vertical
Substrat's admin surface — provisioning scopes, suspending tenants, granting entitlements — runs outside the module system, and this is worth understanding because it's a good test of whether the isolation story is real.
A super-admin, by definition, acts across every tenant. So: could you just build it as a vertical, with the platform as its own tenant?
No — and not because it would be dangerous. Because it would be inert. A vertical's code reaches data through exactly one path: a capability stub for one (tenant, scope) pair that the kernel minted for it. It holds no handle to the storage namespace and no way to name a scope it wasn't invoked for — including, in production, scopes belonging to other verticals' deployments, which it cannot address at all. An admin vertical would sit there with no way to reach the thing it exists to manage. To give it that reach you'd have to build a privileged out-of-band path — which is the control plane, arrived at by a longer road.
This is the isolation guarantee doing its job on its own author. The interesting half: record-keeping about tenants — who they are, which plan, what staff did — is ordinary scope-shaped data, and can perfectly well be a vertical on Substrat like any other. It's acting across tenants that cannot be.
What this means for you
- Don't build tenancy, domains, audit, or identity. They're below you. Verticals that rebuild them are a smell that the kernel drew a line wrong. Authentication in particular is a swappable edge adapter — see authentication & identity.
- Your scopes carry your code only. Your migrations are ordered against your modules and the engines you depend on — never against a stranger's vertical.
- You upgrade on your schedule. Per-vertical deployments exist so that engine versions, migrations, and blast radius stay yours.
- Declare an
entitlementKeyand mean it. It is the unit at which your module is sold, licensed, and switched off.
See Tenants & scopes for the entities and addressing model, and Modules & the manifest for what a deployment is made of.