Skip to content

Operations & the scope host ​

The scope-host contract is the heart of the kernel: module code registers operations; callers reach a scope only through a capability stub. The operation handler runs inside the scope's execution domain, which is what makes invariants enforceable — the handler sees sql, emit, check, and link; the caller sees only invoke().

The contract ​

ts
interface ScopeHost {
  getScope(principal: PrincipalId, tenantId: TenantId, scopeId: ScopeId): Promise<ScopeStub>;
  provisionScope(actor: PlatformActorId, input: ProvisionScopeInput): Promise<void>;
  registerModule(registration: ModuleRegistration): void;
  // Out-of-band effects a module asks for but cannot perform — see
  // /concepts/events#the-connector-seam
  registerExecutor(id: string, eventType: string, handler: ExecutorHandler): void;
  defineOperation<I, O>(name: string, handler: OperationHandler<I, O>): void;
  readonly admin: HostAdmin; // control plane: roles/grants, tenant registry,
                             // scope lifecycle, entitlements, audit log
  close(): Promise<void>;
}

interface ScopeStub {
  readonly tenantId: TenantId;
  readonly scopeId: ScopeId;
  invoke<O, I>(operation: string, input?: I, options?: InvokeOptions): Promise<O>;
}

Operation names are module-namespaced: 'workorder/create', 'invoicing/export'.

This is a teaching subset. The live ScopeHost has since grown a per-tenant relational store (provisionTenantStore / openTenantStore), scope import/restore/snapshot (importScope, restoreScope, snapshotScope), connector methods, and a scheduler seam (getSystemScope opens a stub whose authority is a module on a timer, and registeredSchedules / runDueSchedules let the platform sweep run a vertical's recurring work) — surfaces the rest of these docs introduce where they belong.

getSystemScope(moduleId, tenantId, scopeId) is the mirror of getConnectorScope: a door for a non-human caller. Where a connection's stub stamps { connection } on its events, a system stub stamps { system: moduleId } and checks against system:<moduleId> grants — so a scheduled operation is attributable to the schedule, and ctx.check stays its one gate.

Two more doors follow the same shape. getCapabilityScope acts as a capability that someone exchanged a shared link for (Sharing by link). getVerticalScope acts as another app of the same tenant, which the platform identified (the peer door). Each stamps its caller on what it emits, and ctx.check stays the one gate. deliverToPeer is the consumer half of cross-vertical events: it applies a batch another app exported, entering through the peer door.

What the harness around a call can observe ​

getScope takes a fourth argument, ScopeStubOptions, for the HTTP layer around an operation rather than for the module. Its observers fire only after an invoke commits:

  • onPlatformRequests(count, scopeId) fires when the operation enqueued platform intents, naming the scope they went into.
  • onExportedEvents(count) fires when the operation, or an in-scope consumer in its tail, committed an event of a type this deployment exports to another app.

A hosted vertical turns each into a response header. The router reads it and asks the platform to act on that scope now, instead of at the next sweep. kickFlags (from @substrat-run/vertical-host) wires both with one call:

ts
return host.getScope(principal, tenantId, scopeId, {
  ...kickFlags((name, value) => c.header(name, value)),
});

A vertical that leaves this out still works, and waits for the sweep. The flags carry no authority: the router strips every inbound x-substrat-* header, so only a response can raise one. The intent flag's value names the scope the intents went into, since a worker serving several scopes under one hostname picks the scope per request. The platform always drains the routed scope, and drains the named scope as well when both are live installs (active, not a preview or a fork) in the same tenant under the same vertical. The header holds one scope, so when one request writes intents into several scopes that are not the routed one, only the last is drained at once and the sweep picks up the rest. The exports flag always acts on the routed scope.

Preconditions travel per invocation, not in the input ​

invoke's third argument carries facts about the request, never about the domain. A handler's declared input is what the operation means; threading a retry token or an entity tag through it would make every in-process caller state something it does not have. mountOperations reads these off headers — a test, a seed or a schedule omits them entirely.

ts
interface InvokeOptions {
  readonly ifMatch?: string;                                   // the caller's `If-Match`
  readonly onEntityVersion?: (version: string | null) => void; // the `ETag` to hand back
  readonly idempotencyKey?: string;                            // the caller's `Idempotency-Key`
  readonly onIdempotentReplay?: () => void;                    // sets `Idempotency-Replayed`
}

One bag rather than a parameter per concern, because the two are one precondition pass at one point in the invoke — before the guards, inside the transaction.

  • ifMatch is the version the caller believes it is writing over, verbatim from the header (quoted, and possibly a list). onEntityVersion is called after a guarded operation commits, with the entity's version as the caller's own write left it — read after the handler and inside the same transaction, because a client that echoed back the tag it sent would loop on its own stale value. Neither runs for an operation that declares no concurrency, and neither runs for one that rolled back.
  • idempotencyKey has nothing to declare: it is honoured on every unsafe operation, since a retried write creating a second entity is a hazard on all of them. A first request under a key runs and its return value is recorded inside the operation's own transaction; a second under the same key and the same input returns that recording without running the handler, and onIdempotentReplay fires when it does. A key names one request, so the same key with a different input is refused rather than answered — serving the first request's response to a second one is a lie the caller would act on.

An option the operation cannot honour is refused, not ignored — and refused before the invocation takes its turn, in both directions:

  • ifMatch sent to an operation that declares no concurrency. Nothing would have been compared, and a caller who believes its write is protected while it is not is the single failure this mechanism exists to prevent. Silence is how that belief survives.
  • idempotencyKey sent to an operation that declared idempotency: false. Its response is deliberately never recorded, so the retry would do the work a second time — while the caller reads its 200 as proof that retrying was safe.

The HTTP half of both — the headers, the 412, the replay window — is §7 and §7b of API design.

What a handler sees ​

ts
interface OperationContext {
  readonly tenantId: TenantId;      // ambient — from the stub, not from the caller
  readonly scopeId: ScopeId;
  readonly principal: PrincipalId;
  readonly sql: ScopedSql;          // synchronous, scope-local SQL
  now(): Instant;                   // the operation's instant — the only clock
  readonly log: ModuleLog;          // debug / info / warn / error (template, fields)
  readonly requestId: string | null; // the request (or delivery, or run) this call belongs to
  emit(event: DomainEventInput): void;
  check(permission: PermissionKey, entity?: EntityRef): Promise<Decision>;
  search(entityType: string, term: string, options?: SearchOptions): SearchHit[];
  page<T>(entityType: string, params: PageParams): Page<T> | CountedPage<T>;
  versionOf(entity: EntityRef): EntityVersion | null;
  entitlement(key: string): Promise<EntitlementView | null>;
  entitlements(): Promise<EntitlementView[]>;
  link(child: EntityRef, parent: EntityRef): void;
  grant(principal: PrincipalId, permission: PermissionKey, entity: EntityRef): Promise<void>;
  revoke(principal: PrincipalId, permission: PermissionKey, entity: EntityRef): Promise<void>;
  canAssign(roleKey: string): Promise<Coverage>;
  readonly capabilities: CapabilityVerbs;   // mint / revoke / list
  requestPlatform(request: PlatformRequestInput): PlatformRequestId;
  platformRequests(filter?: PlatformRequestFilter): PlatformRequestEntry[];  // narrow: isUndecodablePlatformRequest
  sealToConnection(provider: string, plaintext: string): Promise<SealedSecret>;
  atomic<T>(fn: () => T | Promise<T>): Promise<T>;
}
  • sql queries the scope's own database — synchronously, because the data is local to the execution domain. One network hop to reach the scope, then local queries.
  • now is the operation's instant, and the only clock module code may read — new Date() and Date.now() are boundary-lint R6 violations, the same class of ban as node:*. It is stable for the whole invocation: every call returns the same value, so two rows written in one transaction cannot disagree about when they were written, and an event carries the same instant as the row it describes. The host injects it (clock on the host options), which is what makes elapsed time assertable — see Testing with a clock.
  • log writes one structured line per call. The host stamps what it knows (tenant, scope, operation, invocation id, and whether a person, a connector, a schedule, a shared link or another app is running the code), and your code supplies only a template and its fields: ctx.log.warn('reply to {ticketId} bounced: {reason}', { ticketId, reason }). Keep the template a constant. Every line from one call site then shares it, so the lines can be grouped into patterns and filtered by operation — the purpose of the template, which the dashboard's log reads are still to pick up. A template built from values makes each line its own pattern. A call never throws: oversized values are trimmed, a non-primitive field is stringified, and a capability secret minted in the same call is withheld. It is not transactional, so a line is kept even when the operation later rolls back — those are usually the lines you want.
  • requestId is the id the platform minted for the request this call belongs to: the response's x-substrat-request-id, the id on every ctx.log line and event the call emits, and the request the dashboard opens for it. Put it in your own error messages so a person can quote it. A consumer gets its delivery's id and a schedule run gets its run's; it is null only for an in-process call such as a test or a seed. Opaque — read it only to repeat it.
  • emit validates the event input and stamps the envelope kernel-side (id, timestamp, tenant, scope, actor). See Events & audit.
  • check asks the permission checker about the ambient principal at the ambient node, optionally narrowed to one entity. See Permissions.
  • search returns entity ids from the FTS index the kernel derived from the manifest's searchables — a module never writes a MATCH of its own. An entity type nobody declared searchable throws NotSearchable rather than returning nothing.
  • page reads one page of a declared entity: the kernel composes the WHERE from the operation's declared filterable columns, the ORDER BY from the caller's choice among sortable, the keyset cursor, the LIMIT, and — when the declaration asks for one — the total over the same WHERE. It reads the indexes it also provisioned. Rows come back wrapped; mapPage re-shapes the entries and keeps the cursor. An undeclared sort or filter throws (SortNotDeclared, FilterNotDeclared), never silently applies nothing. See Lists are pages, not dumps.
  • versionOf is an entity's version — the ULID of the last event about it, read from the outbox; there is no version column. A state move (archive, unarchive, trash, restore) is the one event that leaves it where it was: it changes no content. It is what a read-modify-write's If-Match is checked against, and it survives a shred, so an erased entity can still refuse a stale write. The caller's side of that comparison is InvokeOptions.ifMatch; the transport's side is A read-modify-write says what it is writing over.
  • entitlement / entitlements read the tenant's currently-held entitlements at request time — the sanctioned way a hosted vertical gates a feature or enforces its own quota without a control-plane binding. entitlement(key) returns the live EntitlementView (key, plan, quota, expiresAt) or null when the tenant does not hold the key; expiry is applied at read, so a non-null result is always live. The kernel enforces presence + expiry; the vertical decides what quota means. On a hosted vertical this reads a scope-local projection. See The platform layer.
  • link records a child→parent relation tuple (e.g. work order → facility) used by the permission evaluator's entity-edge rule. The relation must be declared in a registered module's entityRelations. Idempotent.
  • grant / revoke narrow a permission the caller already holds onto one entity — how an app expresses user-initiated sharing. Non-escalating by construction: entity is required, so module code can never write a scope- or tenant-wide grant, and the caller's own decision on that entity is re-checked first. Delegation, never elevation. Transactional with the operation, like its rows and its events. Without it, an app where a person shares their own record would need a membership table consulted by hand in every handler — the forgotten-WHERE-clause failure this platform exists to remove.
  • canAssign is the bound on handing out a role: the caller may assign (or remove) a role only if it already holds every permission that role carries here. It is not the permission check. The operation still opens with its own ctx.check, then asks this. Host code outside any operation asks the same thing of the host for a principal it names: host.canAssign(tenantId, scopeId, principal, roleKey), one answer by construction.
  • capabilities mints authority carried by a secret rather than held by a principal ("anyone with this link may read this folder until Friday"). The rule is grant's: narrowed onto one entity, from keys the caller holds, and re-checked every time the capability acts. See Sharing by link.
  • requestPlatform / platformRequests enqueue a durable platform intent and read back what the platform did with it — the sandbox-clean way to ask for a privileged action, with no upward call and no credential in vertical code.
  • sealToConnection seals a value to a connection's public key so it can ride on an event that a connector opens at egress. The scope never holds the private half; the consumer still needs no cross-module read, it just cannot read that one field. It takes a provider name ('scrive'), never a connection id — connection identity is the host's business, and an engine that learned it would be naming infrastructure it is not allowed to see. It fails closed and legibly: no projected key for that provider throws, rather than emitting a request that silently reaches nobody. Await it before ctx.emit, which is what lets emit stay synchronous.
  • atomic runs a callback as a sub-transaction inside the operation's own. A throw inside discards everything the callback wrote — rows, events, links, grants, platform intents — while the operation's other writes survive, and it still commits once. This is the only place module code may catch an engine error: an engine call composed inside your transaction has no boundary of its own, so a bare catch would commit its partial writes. boundary-lint R7 rejects the unprotected form. A succeeded atomic is still provisional — if the operation later throws, its writes go too — and sub-transactions nest but must not interleave.

Testing with a clock ​

Anything whose behaviour is a function of elapsed time — an absence request going stale, a metering period rolling, a cart hold lapsing — is untestable against the wall clock: the interesting branch never runs inside a 40 ms test. The usual workarounds are to sleep (slow and flaky) or to shrink the window to zero, which proves that an already-expired thing is expired and nothing about expiry.

The host takes a clock, so a suite can move time on purpose:

ts
import { manualClock } from '@substrat-run/kernel';

const clock = manualClock('2026-03-02T09:00:00.000Z');
const host = new SqliteScopeHost({ dir, clock: clock.read });

await guest.invoke('shop/add-to-cart', { cartId, variantId, qty: 1 });

clock.advance(14 * 60_000);   // inside the 15-minute hold — still reserved
await expect(otto.invoke('shop/add-to-cart', { … })).rejects.toThrow(/out of stock/);

clock.advance(2 * 60_000);    // past it — the unit is sellable again
await otto.invoke('shop/add-to-cart', { … });

No real time passes. frozenClock(at) is the simpler form when a test only needs one fixed instant. Both come from @substrat-run/kernel, so a vertical's own suite gets them without depending on our test tooling.

Timestamps are stored as ISO 8601 text. ctx.now() returns an Instant — an ISO string with an offset — and that is what goes in the column (created_at TEXT NOT NULL). Text sorts and compares correctly, reads correctly in a .sqlite file someone opens by hand, and needs no per-table convention about seconds versus milliseconds. Epoch integers appear in this repo only inside a third-party schema that defines its own storage (Better Auth's tables in demos/auth-server), which is that library's contract, not ours.

Contract semantics — what every adapter guarantees ​

These are the semantics the conformance suite verifies, so you can rely on them regardless of which adapter is underneath:

Strict serialization per scope ​

One operation at a time, to completion. Ten concurrent read-await-write increments land on exactly ten. Module code never needs locks, transactions-for-concurrency, or retry loops against its own scope.

Structured-clone boundary ​

Inputs and results are cloned on every stub call, both directions — even in-process. Mutating an input object after invoke(), or mutating a returned result, can never affect scope state. Code cannot share mutable state with a scope, so "it worked locally because we shared memory" bugs are impossible by construction.

Fail-closed addressing ​

getScope validates (tenantId, scopeId) against the directory. A mismatched pair throws; it never resolves to another tenant's scope. The same fail-closed path also gates lifecycle status: a suspended or deleting tenant, or a suspended or archived scope, fails getScope — which is how suspend and archive actually contain. Operations are gated once more at invoke: a module whose entitlementKey the tenant does not hold does not resolve.

Kernel-stamped events ​

The event envelope's origin fields are not parameters. See Events & audit.

A signed platform call is accepted once ​

Each scope keeps the nonces of the signed platform calls it accepted, so the same call sent again is refused. That record belongs to the store, not to the scope's data: a dump, a copy or a restore never carries it, and module code never sees it.

In-scope functions vs registered operations ​

Engines expose their logic at two altitudes:

  • Registered operations ('workorder/create') — the default bindings, each starting with its own permission check. Invoke these through a stub.
  • In-scope functions (plain exports like createWorkOrder(ctx, input)) — composable building blocks a vertical's own operation can call in the same transaction, when it needs to wrap engine behavior with domain logic (pricing, extra validation). The caller is then responsible for the permission check.

This is how a vertical customizes without forking: write your own operation, call the engine's in-scope functions, keep everything inside one serialized, audited execution.

ts
host.defineOperation('acme/create-priced-workorder', async (ctx, input) => {
  assertAllowed(await ctx.check(PERM.create));
  const order = createWorkOrder(ctx, toEngineInput(input)); // engine function
  ctx.sql.exec('INSERT INTO acme_pricing ...');             // vertical's own table
  return order;
});

SQL limits on ctx.sql ​

A scope's database is a Durable Object's SQLite when deployed and better-sqlite3 locally, and the Durable Object's build sets four limits far below stock SQLite's. Left alone, a statement over one would run in every local test and fail on the first deployed call, so the node adapter enforces the first three of these on ctx.sql and refuses with the Durable Object's own message. Your suite sees what production sees for them, and the fourth needs one line in your own test setup to see the same thing. The LIKE/GLOB pattern limit is not enforced by the adapter itself: node's SQLite allows 50 000 bytes, and enforcing it there would replace SQLite's like() on every connection in production — a JavaScript call per row and no LIKE prefix index for self-hosters. Instead, @substrat-run/adapter-sqlite/testing is the same patch as an opt-in test-only helper: add it to your vitest.config.ts's setupFiles (on by default in a scaffold from npm create substrat) and your suite refuses a pattern a Durable Object would too:

ts
// vitest.config.ts
export default defineConfig({ test: { setupFiles: ['@substrat-run/adapter-sqlite/testing'] } });

Bound the pattern yourself either way (below) — the helper catches a regression, it does not fix one. If your own suite typechecks against the subpath, it needs @types/better-sqlite3 as a (dev)dependency too — the scaffold from npm create substrat already carries it.

LimitValueThe refusal
Terms in one compound SELECT (UNION, UNION ALL, INTERSECT, EXCEPT)5too many terms in compound SELECT
Bound parameters in one statement100too many SQL variables at offset N (variable number must be between ?1 and ?100 for ?101)
Statement length100 000 bytes (UTF-8, the whole string)statement too long
LIKE / GLOB pattern length50 bytes (UTF-8), not adapter-enforced — opt in with @substrat-run/adapter-sqlite/testingLIKE or GLOB pattern too complex

These are measured against a real Durable Object, not read from documentation (packages/adapter-cloudflare/test/do-sql-limits.test.ts), and exported as DO_SQL_LIMITS from @substrat-run/kernel. How they are counted:

  • Compound terms are the operands of one chain. A subquery, a CTE body and a view body each count their own, so SELECT … FROM (five terms) UNION ALL … is fine. A multi-row VALUES list is not a compound: five thousand rows ran.

  • Bound parameters are the highest parameter number, not the number written: :a + :a is one, ?100 is a hundred. A dynamic IN (${ids.map(() => '?')}) is a hundred members at most, less whatever else the statement binds — and it passes every test whose fixture has a handful of rows. Pass a list of unknown length as one JSON array instead: inList from @substrat-run/contracts binds it and reads it back with json_each, which has no such limit:

    ts
    import { inList } from '@substrat-run/contracts';
    
    const list = inList(ids); // { sql: '(SELECT value FROM json_each(?))', params: ['["…","…"]'] }
    ctx.sql.query(`SELECT * FROM acme_items WHERE owner = ? AND id IN ${list.sql}`, [owner, ...list.params]);

    json_each is SQLite's own JSON1 table-valued function and runs the same on both adapters — better-sqlite3 on the node host and the Durable Object's SQLite when hosted — so there is no adapter-specific reason to avoid it. An empty list matches nothing (a hand-built IN () is a syntax error). Pass the values in the column's own type: a json_each value carries no affinity, so a numeric column converts a numeric string (inList(['123']) matches 123), but a TEXT column never matches a number — inList([1]) matches neither '1' nor the '1.0' a bound 1 would. Pass a TEXT column's values as strings (ids.map(String)), or cast the comparison (CAST(col AS INTEGER) IN ${list.sql}). boundary-lint rule R12 refuses the hand-built placeholder list in module code and points here; a list whose length is fixed and short opts out in a boundary-lint-allow R12 … boundary-lint-end R12 block. On the node adapter the refusal names inList after the Durable Object's own words.

  • Statement length is the whole string handed to ctx.sql, so a multi-statement string counts once.

  • LIKE is a pattern built from input: a search term becomes %term% plus an escape per wildcard. Bound the term in bytes, or match with instr(lower(col), lower(?)).

Only your module's ctx.sql is judged. The platform's own statements are the platform's responsibility, and they already run on a real Durable Object in this repository's suites. A vertical's tenant relational store (a declared tenantStoreNeed, D1 when hosted) is a different database with its own limits and is not covered here.

Event consumers ​

A module can subscribe to event types (declared in its manifest under events.consumes). Consumers run as ordinary in-scope operations under a system actor, with at-least-once delivery tracked in a kernel delivery journal — so handlers must be idempotent. Ordering is guaranteed only within one (scope, module) pair.

The invoicing engine is the reference example: it consumes workorder.completed and rebuilds its own state from the event payload alone.

A consumer can also take events from another app of the same tenant. It declares consumes: [{ from, type, schemaVersion }], and its handlers go under the registration's imports, never consumers. Delivery keeps the same at-least-once journal, and the watermark lives in the consumer's own store. See Between verticals: exports and imports.