@substrat-run/kernel
The kernel's behavioral seams in pure TypeScript. This package imports no platform APIs — Cloudflare specifics live only in adapters, and every adapter must pass the same conformance suite.
pnpm add @substrat-run/kernel @substrat-run/contractsScope host (scope-host.ts)
The adapter seam. Full semantics in Operations & the scope host.
The source is split by concern (#1978), and the connector transport (globalFetch, FetchLike) and the attachment byte helpers live in their own modules; everything below is exported from the package root.
| Export | Kind | Purpose |
|---|---|---|
ScopeHost | interface | getScope, getConnectorScope, getSystemScope (the scheduler's door — a stub whose authority is a module on a timer, #383), getImpersonatedScope (the fourth door: a stub that acts as a principal under a session HostAdmin.beginImpersonation opened and logged first — re-read on every invoke, so an ended or expired session stops working, K-42), provisionScope, registerModule, defineOperation, registeredSchedules / runDueSchedules (the recurring-work seam the platform sweep drives), admin, close |
ScopeStub | interface | the capability — the only way code outside a scope reaches it |
OperationContext | interface | what a handler sees: ambient tenantId/scopeId/principal, sql, now (the operation's instant — the only clock module code may read, stable for the whole invocation), emit, check, search (ids from the declared FTS index), page (one kernel-composed page of a declared entity — filter, sort, keyset cursor and optional total from the operation's paged declaration), entitlement/entitlements (read a held SKU/quota at request time — the gate a CP-less vertical uses), link, grant/revoke (delegation, never elevation), requestPlatform/platformRequests, versionOf (an entity's version — the ULID of the last event about it), atomic (a sub-transaction: the only place an engine error may be caught, because a throw inside discards everything the callback wrote), sealToConnection |
OperationHandler<I, O> | type | (ctx, input) => O | Promise<O> |
ConsumerHandler | type | event consumer; at-least-once, must be idempotent |
ModuleRegistration | interface | manifest + migrations + operations + consumers. operations is a BoundOperations, which only the two binders below produce: the handlers, and the maps the host derives from their declaration and the module never writes by hand — inputs (every invocation is parsed before the guards and the handler, on every path in), concurrency (which entity's version an If-Match on each operation is checked against) and idempotencyOptOuts |
operationsFor(ops)(handlers) | function | binds a module's handlers to its declared operations (#1835): returns { operations }, the handlers and the three derived maps, all from the one declaration. A missing, extra or mistyped handler, or one cast as never / as any, is a compile error at the entry; boundary-lint R11 refuses a cast of the whole map |
undeclaredOperations(reason, handlers) | function | the declared exception: a module with no operation surface to bind to registers its handlers this way, with the reason stated; nothing is parsed for it |
BoundOperations · HandlerMap | types | what the two binders produce — a class with an ES-private brand, so a spread or a copy is not one — and the handler map they take |
assertBoundOperations(moduleId, operations) | function | the adapters' registration check: refuses an operations value the binder did not make |
SqlMigration | interface | { version, sql } — ordered, journaled per module |
ScopedSql, SqlValue | types | synchronous scope-local SQL: query<T>(), exec() |
ExecutorHandler | type | (admin, event) => void — out-of-band host code effecting what a module asked for via an event (K-22). Registered with registerExecutor; receives HostAdmin, never ctx, because it acts with platform authority |
HostAdmin | interface | the audited control-plane surface. Every mutation takes a PlatformActorId and writes an append-only audit row; directory reads take one too and record to the K-24 access log — and a scope read the control plane delegated to the hosted vertical holding the data leaves the same row, through recordDelegatedRead (#1470, below). The capability groups it now spans: permissions & membership (defineRole, listRoles, assignRole, unassignRole, grant, grantToOrg, grantToConnection, grantToSystem — the schedule's system-principal grant (#383), addMember, removeMember, listMembers); organizations (createOrg, listOrgs, getOrg); the vertical + version registry (registerVertical, publishVersion, admitVersion/rejectVersion, promoteVersion, bindScopeVersion, setVerticalListed, verticalServing — push-is-not-live admission, channels, and the stable serving script); the hostname map (bindHostname, setHostnameStatus, setHostnameIssuance, listHostnames, resolveHostname — the router's unlogged per-request read); tenant registry (createTenant, setTenantName, setTenantStatus, listTenants, getTenant, reapTenant); scope directory + lifecycle (listScopes, listScopesReadable — optional: the same rows, naming one that does not read as a scope instead of failing the list, for fleet-wide passes —, getScopeRecord, activateScope, suspendScope/unsuspendScope, archiveScope/unarchiveScope, reapScope, rewindScope); scope introspection (listScopeTables, readScopeTable, queryScope, exportScope — the read-only "Data" window into a scope's own database — plus the eight event readers over the same window, entityHistory (#1353: one record's story, readHistory's answer hoisted to the platform), facetEvents (narrow, group, count — erased payloads counted apart, never folded into a "no value" bucket), eventCause and eventEffects (one event walked backwards to what started it, or forwards to what it set off; the chain ends in a named terminal, never a silent stop), and invocationEvents (#1237: everything one call emitted, siblings with no causal link included, with truncated rather than a quiet cut), lifecycleFlow (#1744: one entity's declared lifecycle replayed over the outbox for the process map — the caller passes the declaration, the scope holds no model), operationSeries (#1750: calls per (entityType, operation) per time bucket over a window of at most seven days — Pulse's business volumes; the caller passes the pairs, the scope holds no model), and deadLetters (#1525: every delivery in the scope that gave up, newest event first — the list the walks reach only one event at a time). All eight are the co-located branch; for a hosted vertical the transport reads them through the vertical's own /internal/* routes instead); the Tier-2 event drain (readUndrainedEvents, markEventsDrained — the two verbs the sweep's outbox drain is made of (#1409), deliberately separate: read, ship through the EventSink, then stamp drained_at only once the sink confirmed durability. readUndrainedEvents selects on drained_at IS NULL; markEventsDrained is what writes the stamp, so a DrainedEvent carries no drainedAt field — it is the envelope plus the three outbox-column facts the envelope cannot hold, operation, version and causedBy (each nullable, the nulls meaning what events sets out). The same phase then runs pruneDrainedEvents: a row drained more than OUTBOX_RETENTION_DAYS (90) ago is deleted once every local consumer of its type has taken it, unless its type is exported to another vertical, it is its entity's or its type's newest event, or its cause chain reaches an imported event; a pass examines at most OUTBOX_PRUNE_SCAN rows from where the last stopped, starts a new lap only in the scope's own UTC hour (up to about four laps a day), and continues a lap a cap stopped on every pass. A scope walk resumed from a bare watermark below the pruned range refuses with WatermarkPruned, so a mirror resyncs; below that range a page's nextCursor is an opaque continuation, honoured until a later prune moves the floor. History reads, and every view over the outbox (facets, lifecycle flow and the process map, operation series, freshness), cover that window, and older history is the lake's: an entity whose earlier events were pruned reads as found mid-life. A consumer added later is never handed rows already pruned. A row an executor refused, or that dead-lettered, is kept for as long as that stays its delivery, by design: it is what a replay reads); entitlements (grantEntitlement, revokeEntitlement, listEntitlements); the connections hub (createConnection, openConnection, listConnections, updateConnectionSecret, revokeConnection, connector-state get/put/list — the integrations credential store; and a vertical's mailed connect links, mintConnectLink, getConnectLink, listConnectLinks, revokeConnectLink, consumeConnectLink, restoreConnectLink — single-use, revocable, keyed by tenant and scope, connections.md §3.5.4); identity (registerIdentityPool, linkIdentity, unlinkIdentity, resolveIdentity, listIdentityTenants, listIdentityMemberships — the same central-only question with each tenant row, the login's principal in it and the link's scope attached, as one read and one access-log row, for a caller that would otherwise ask once per tenant); denials (listDenials, summarizeDenials — a scope's refused permission checks, raw and bucketed per actor and key, K-35; see Denials are recorded) refusals (listRefusals — a scope's refused lifecycle moves and refusing manifest guards, one row per attempt with its kind, the record, the state it was in (none for a guard), the operation, the guard's predicate, the actor and its kind, and the call, #1745; the co-located branch only so far); capabilities (listCapabilities — the operator's read of a scope's link-share and claim-link directory, #1686: records newest first, live unless asked, never a secret and never a hash; beside the platform's two capability verbs mintCapability and revokeCapability, #1672. On the shared control plane revokeCapability reaches a hosted scope in the deployment serving it, over /internal/capabilities/revoke with the admin row kept here (#1686), and the console's Capabilities card fronts it; mintCapability serves only a scope the host holds itself) impersonation (beginImpersonation, endImpersonation, listImpersonations — the record-keeping half of acting as somebody: reason required, read-only unless said otherwise, capped at IMPERSONATION_MAX_MINUTES, admin-logged before the session can be used; the effecting half is ScopeHost.getImpersonatedScope); operational failures (recordOpsFailure, listOpsFailures — what the platform could not complete: a deploy, a restore, a provision, filed with the upstream trace reference so reference = <id> has a queryable home. Deliberately not the audit log: a failure changed nothing. Retention-bounded, so an empty read means "nothing recent", never "nothing ever"); the sweep record (recordSweepRun, listSweepRuns — the durable per-unit record of the three sweep phases that have one, #1255: each live connection swept, failed, or skipped because its provider registered no sweeper (a revoked connection is deliberately not recorded — a skipped row per pass forever would be noise), each schedule run including the ones skipped inside their cadence window (which is what makes a missed run derivable), and each freshness verdict. The other phases — migration reconciliation, the two drains, provision reconcile, the reaps, the event drain — report through PlatformSweepReport only. Telemetry about a machine pass, not audited, and fire-and-forget: a recorder that throws must never sink the pass it is recording); issues (listIssues, setIssueStatus — operational failures grouped by fingerprint into failure classes, most recently seen first, with a staff lifecycle of resolve, ignore or reopen (#1290, #1293). No cursor by design: the grouping is the compression. regressed is ingest's word and the verdict refuses it); findings (listFindings, setFindingStatus, createFindingRule, revokeFindingRule, listFindingRules — the tenant-scoped inbox, #1748: listFindings is keyset-paged (#2198): limit (default 100, at most 500) and a cursor from the last row read, lastSeen descending with id ascending on a tie; a limit or cursor that is not one is refused, never read as the start. A finding seen again mid-walk moves to the front, ahead of the cursor, so a walk never returns one twice; one finding per (tenant, kind, subject), opened on write by the record calls themselves (a tenant's ops failure is a recurring finding on the issue's fingerprint, a failed schedule run an invariant, a stale freshness verdict a drift), counted over that tenant's own occurrences and carrying none of their text. Verdicts are acknowledge, resolve and reopen, keyed on the tenant as well as the id; a resolved finding seen again reopens regressed, naming the version it came back under. Suppressing is a rule — a scope (kind, operation, code, subject) and an expiry of at most FINDING_RULE_MAX_DAYS — under which occurrences are still counted. Every mutation is audited; pruneFindings, the sweep's findings phase, resolves a finding quiet for FINDING_RETENTION_DAYS as stale, audited in the same unit, rather than deleting it); store drivers (recordStoreDriverRelease, getStoreDriverRelease, and, since the release-approval RFC (#2297), approveStoreDriverRelease, revokeStoreDriverRelease, storeDriverApprovals, liveStoreDriverApproval and the revoke walk's cursor storeDriverRevokeWalk / recordStoreDriverRevokeWalk — an approval is a staff record of one release's exact bytes, append-only with at most one live approval per release; each write is audited in the unit that makes it, and the revoke cursor is persisted only under the driver's exclusive hold); wire signing (recordWireAuth, listWireAuth, recordWireWalk — the signing record the uploader writes for each deployment, optional on a host, and read confined to a tenant or { fleet: true }; an absent record reads as unknown, never as ready); model usage (recordModelUsage, listModelUsage, summarizeModelUsage — meter 3's ledger, one line per model call a vertical made through the platform's model host, drained here as a model-usage intent. Idempotent on the intent id, so a retried drain records nothing twice, and retention-bounded by MODEL_USAGE_RETENTION_DAYS; the summary folds with the margin applied at read time and stores nothing, because metering is not billing (D-30)); and the logs (auditLog, accessLog, recordDelegatedRead, markAccessLogDrained, pruneAccessLog). recordDelegatedRead (#1470) is how the control plane leaves the K-24 row for a scope read it delegated to the hosted vertical holding the data — before it, the production path logged only a getScopeRecord entry for those reads, and the sentence above was true of the co-located branch alone. The row is the same shape whichever branch served it: the method comes from the closed delegatedReadMethod set (readScopeTable, listScopeTables, queryScope, listDenials, summarizeDenials, listCapabilities, entityHistory, facetEvents, eventCause, eventEffects, invocationEvents, deadLetters, lifecycleFlow, operationSeries) — plus one second arm, lakeEvents (#1334), for a read the control plane answered from the Tier-2 lake itself, whose scope may be null because one tenant's lake read can span all its scopes — the adapter stamps id and at so a caller can neither backdate a row nor collide one, and a failed write fails the read — returning rows whose disclosure went unrecorded is the thing K-24 exists to prevent |
ProvisionScopeInput | interface | tenant, scope, optional shape + jurisdiction (provisioned via provisionScope(actor, input)) |
globalFetch, FetchLike | const, type | The runtime's fetch, handed on as a value — the one place the FetchLike cast lives (#1291). Host code passes this, never the bare global in any spelling: workerd throws Illegal invocation when a connector calls an unbound fetch as input.fetch(…), and neither Node nor the workers test pool does, so no suite catches it. pnpm lint:bound-fetch refuses the bare global |
deadlineFetch, STREAM_IDLE_TIMEOUT_MS, STREAM_MAX_DURATION_MS | function, const | A connector call's time bounds (#2518): timeoutMs over the call up to the response headers and any buffered read, and, from the first read of a streamed body (ConnectorResponse.body), an idle window (30 s without a non-empty chunk) plus an absolute cap (10 minutes), so a large transfer that keeps flowing is not killed while a stalled or endless one is. All end in a TimeoutError. Both hosts and the shipped connectors wrap their fetch in it |
Permission checker (permission-checker.ts)
The evaluation seam — the model is kernel-owned, the engine is swappable. See Permissions.
| Export | Purpose |
|---|---|
PermissionChecker | check(principal, permission, node, entity?) → Promise<Decision> |
assertAllowed(decision) | throws PermissionDenied unless allowed; the standard first line of an operation. Narrows the type to the proof-carrying allow. |
PermissionDenied | the error class |
denyAllChecker | secure default — denies everything |
UNSAFE_allowAllChecker | test-only; grants everything via a synthetic proof tuple. The name is the warning. |
ulid()
A dependency-free ULID generator — the ID scheme used everywhere (ids in @substrat-run/contracts).
import { ulid } from '@substrat-run/kernel';
const id = ulid(); // '01JZX6ZH2E...'Also importable from @substrat-run/kernel/ulid, which imports nothing at run time.
Subpaths that import nothing
The platform bundles an entry module in front of every deployed vertical (#1893), and the package root would bring @substrat-run/contracts, and zod, with it. So the few things that entry needs have subpaths of their own, each importing nothing at run time:
| Subpath | Exports |
|---|---|
@substrat-run/kernel/invocation-line | invocationLine and the line's types (see Trusting the edges) |
@substrat-run/kernel/ulid | ulid, createUlid, ulidCeiling, ulidFloor, ulidTime |
The other seams
Everything below is in the kernel for the same reason: it is a rule two or more implementations have to agree on, and a second copy of it is a chance for them to disagree. All of it is web-standard only — globalThis.crypto, TextEncoder, URL — because a package that assumed Node would break the portability claim the adapters exist to prove.
Erasure and secrets
| Module | Export | What it is |
|---|---|---|
subject-keys.ts | createSubjectKeys | The mechanism under piiClass. A per-subject data key seals that subject's payloads at the moment a copy is written, so "erase from every copy we hold" becomes "destroy one key". A live scope needs no crypto — Tier 1 is mutable, erasing there is an ordinary redaction. The copies the platform keeps and cannot rewrite are the problem: a reap backup, a stored dump, the Tier-2 event lake. Those are full-fidelity on purpose, which is exactly why a DELETE can never reach one. A tombstone means a destroyed key is never re-minted |
secret-box.ts | webCryptoSecretBox, unconfiguredSecretBox, isSecretBoxConfigured, SecretBoxUnconfiguredError | The symmetric seal/open adapter the connection store rests on. The kernel decides that per-tenant credentials are encrypted at rest and that plaintext never touches the directory; what encrypts is swappable — Web Crypto locally, a Secrets Store binding or an external KMS when hosted. unconfiguredSecretBox refuses to store a credential rather than storing it in the clear |
sealed-box.ts | sealTo, openSealed, generateSealingKeyPair, ConnectionSealingKeyUnavailableError | The asymmetric sibling, answering a question a scope cannot otherwise ask: hand this to a recipient I cannot talk to. Every path out of a hosted scope is a spine row, so a symmetric key minted in-scope would have to travel the same rows as the value it protects. A connection's public half can be projected down, and a public key is enough to write with — so the scope seals, and the connector opens at egress with a private half that never left the directory |
Time, versions and reading the spine
| Module | Export | What it is |
|---|---|---|
clock.ts | frozenClock, manualClock | The test and replay clocks behind ctx.now() — the reason the instant is injected rather than read. frozenClock(at) answers one instant forever; manualClock(start) is a clock a test moves on purpose (read goes in as the host's clock, advance(ms) / set(at) move it), so "the hold has lapsed" is an exact assertion rather than a setTimeout. Shipped from the kernel, not a test package, for the same reason UNSAFE_allowAllChecker is: a vertical's own suite needs it without our tooling. See Testing with a clock |
timeline.ts | readTimeline, readHistory, readScopeTimeline, readScopeHistory, facetEvents, walkEventCause, walkEventEffects, readInvocation, readDeadLetters, TimelineReader, ScopeWalkPage | The sanctioned reads of _substrat_outbox. For one entity: readTimeline is the envelope walk (id, type, when, who), readHistory adds the fat payload, the K-34 authorization, the K-42 impersonation stamp, the emitting operation (the invoke() string; null for a consumer's emit or a pre-column row), the version the emitting code was deployed as (read from the outbox column, never the envelope; null when no version identity was present) , causedBy (#1237: the id of the event whose delivery was in flight when this one was emitted — set for a consumer's or an executor's emit, null when an operation emitted it directly or the row predates the column) and invocationId (#1237: the call the event belongs to, which is what readInvocation groups on — null when no call carried one: a seed, an internal call, or a row written before the column) — null payload after a shred is a supported answer. For the scope: readScopeTimeline / readScopeHistory (#1582) are the same two walks with the entity unpinned — everything since a watermark, each entry carrying the entity it was about, optionally narrowed by entityType; the cursor is the event id (unique and monotonic per scope, so a page boundary inside one operation's burst drops nothing), a mirror keeps the last applied id rather than nextCursor (null once caught up), and because the walk returns events about every entity the caller's check in front of it must be a scope-wide one; facetEvents (#1404) narrows by type and window, groups by one envelope column or one payload field and counts, with erased payloads counted in their own total rather than folded into a "no value" bucket, and — for a payload field — only events whose pii_class is exactly 'none' grouped, every other one counted in withheldPersonal (#1762); walkEventCause (#1445) follows causedBy backwards from one event and ends in a named terminal — operation is a complete chain, unrecorded a truncated one, depth, missing and cycle the ways the walk gave up — so a fragment is never presented as the whole story; walkEventEffects (#1455) is the mirror, forwards: the consumers an event reached and what they emitted in turn, a tree of recorded steps with real timestamps rather than a timing waterfall; readInvocation (#1237) reads by the call instead of by cause — every event one invocation emitted, oldest first, including what its consumers emitted in the same tail, so two events an operation raised side by side (invisible to both walks) come back together, with truncated saying the call did more than is shown; readDeadLetters (#1525) lists every delivery that gave up — error set and no retry due, since a retrying row carries an error too — joined to its event's type, entity, time and call, newest event first and keyset-paged on the (event, consumer) pair so an event that failed on several consumers is not split by a page boundary. All build a SELECT and nothing else, and none checks permission: the caller's assertAllowed comes first, on the line above. The per-entity reads and the scope walks page like an HTTP list (ListPage in, Page out) |
refusals.ts | REFUSALS_TABLE_DDL, REFUSALS_INDEX (the two literals the adapters interpolate), REFUSALS_REBUILD, refusalsAdmitGuards, refusalInsert, refusalOf, markGuardRefusal, RefusalRow, RefusedGuard (refusedTransitionOf is @substrat-run/contracts's) | Refused transitions and refusing guards, recorded (#1745). assertTransition carries the refused move on its thrown error under a registered symbol (never in the problem document, so the HTTP response is unchanged); both adapters' runGuards call markGuardRefusal on a predicate's throw, which marks a conflict (and only a conflict) with the predicate, the operation, the problem's reason and any record the predicate named. Both adapters record either in _substrat_refusals on the operation's failure path, after the rollback and as a write of its own, exactly where a K-35 denial is recorded. The table is this one shared fragment, so self-host and production cannot differ, and lint:spine-ddl resolves it. A store created before guard rows (from_state NOT NULL, no guard / reason) is rebuilt on wake by REFUSALS_REBUILD, inside the adapter's transaction and detected by refusalsAdmitGuards off sqlite_master.sql, the #1288 shape. Rows hold keys and vocabulary only, never a message, input or guard config. Only a refusal that failed its operation is recorded: one a vertical caught inside ctx.atomic and recovered from is the vertical's business |
scope-copy.ts | COPY_ORIGIN_DDL, capabilitiesForLoad, settleCopiedWork, emittedHere | What a copy of a scope leaves behind (#1686). A load into a scope other than the one the dump came from (a fork, a snapshot, a preview, one scope's backup restored onto another) is a copy, and a load back into its own scope is a return. On a copy the capability tables load empty, pending intents and running job runs settle failed and executor retries turn terminal, each "not carried", and _substrat_copy_origin records the source and the highest event id the copy brought in. emittedHere() is the predicate consumer dispatch, executor dispatch and the Tier-2 drain carry, so only events the copy emitted itself become work. Both loaders re-seed the event-id floor from the loaded outbox (#1335), which is what keeps the copy's own events above that mark. A return changes nothing; an unknown source counts as a copy |
refusal-query.ts | refusalListQuery, mapRefusalRow, RefusalDbRow | The SELECT behind HostAdmin.listRefusals (#1745), shared by both adapters the way denial-query.ts is: newest first, bounded, narrowed by kind, record, actor, operation, call and a half-open window. The decode is tolerant on the denial log's rules (#1636), derives the actor's kind from its stored shape, and reads the problem code from the row, falling back to the kind's (invalid_transition) on a row written before the column |
lifecycle-flow.ts | readLifecycleFlow | The process map's data (#1744): one entity type's events walked in (entity_id, id) order over the outbox's entity index, replaying the declared lifecycle the caller passes. A state comes from the event's payload when it carries the lifecycle field and is classed pii_class = 'none', and otherwise from the declared edge out of the state the replay had the entity in — counted apart as inferred, since that half holds only while the code agrees with the model. The previous state decides what an event means: the same operation can be an edge out of one state and merely allowed in another. Answers per-edge counts (declared edges nobody took at 0, undeclared moves kept apart, and the kind of actor behind each). A move first visible on a later event — the payload shows a new state under an operation that is no edge for it, while the declaration has one — is filed as seenLate against the declared pair with no operation, rather than blamed on the operation that reported it; a count there says the edge's operation emits nothing about the entity it moves. It also answers refused: the window's transition refusals from _substrat_refusals (a guard row has no state to draw from), grouped by (state, attempted state, operation), with the actor kinds. Optional in the result, because a vertical on an older version answers without it, and absent means "not reported", never "none". Beyond the edges it answers, instances per state as of until, median and p90 time in state over stays that ended in the window, the longest-stuck instances, the funnel from the initial state and lifecycle totals. History before the window is replayed and not counted; nothing after until is read. Bounded at LIFECYCLE_FLOW_EVENT_BUDGET events, past which it answers complete: false rather than a smaller answer. Checks no permission, like the timeline reads |
operation-series.ts | readOperationSeries | Business volumes per time bucket (#1750): calls per (entityType, operation) the caller names, counted as distinct (entity, invocation) pairs so a call that emitted several events about one record is one move. One aggregate statement over a window of at most seven days, seeking a closed range of the primary key, [ulidFloor(since), ulidFloor(until + OPERATION_SERIES_ID_SLACK_MS)) — an event id never carries a time before its own occurred_at, and the one-minute slack admits an id the mint held a little ahead of it, while occurred_at stays the exact filter — with the pairs bound as one JSON array, so 64 of them stay under the Durable Object's 100 parameters. Buckets are anchored on since. Which pairs are worth counting is the dashboard's lifecycleMovesOf: an operation whose every appearance in a declared lifecycle is an edge into one state, so each of its calls is that move. Checks no permission, like the timeline reads |
entity-version.ts | entityVersionQuery, entityVersionOf, assertIfMatch, OUTBOX_ENTITY_INDEX | What ctx.versionOf and the If-Match check are made of: an entity's version is the ULID of the last outbox row about it — no version column anywhere. Both adapters run the one query here so they cannot answer differently; assertIfMatch turns a stale tag into precondition_failed |
idempotency.ts | IDEMPOTENCY_DDL, assertIdempotencyKey, idempotencyLookupQuery, replayFor, idempotencyRecordStatement, idempotencyPruneStatement | The remembering half of Idempotency-Key: the _substrat_idempotency spine table, the lookup that decides replay from reuse by fingerprint, and the prune that keeps it a cache rather than an archive. The wire half — header names, key validity, the fingerprint — is in @substrat-run/contracts |
impersonation.ts | IMPERSONATION_DDL, newImpersonationSession, assertSessionUsable, assertImpersonationWrites, impersonationStampOf, ImpersonationRefused, … | The session record behind beginImpersonation / getImpersonatedScope (K-42): the directory's _substrat_impersonations table, the check every invoke re-runs (not ended, not expired, same tenant and scope), the refusal a read-only session gives the effecting verbs, and the { session, actor } stamp the outbox, the denial log and the platform-intent journal all carry |
Trusting the edges
| Module | Export | What it is |
|---|---|---|
read-only-sql.ts | assertReadOnlyQuery | The textual gate in front of the scope SQL console. readScopeTable is safe by construction; a console taking user SQL is not, so read-only-ness is enforced per statement in two layers — this shared scan (both adapters, same rejections, so a query that runs in dev runs in prod) and an adapter-authoritative backstop behind it. The scan reads bare tokens outside comments, string literals and quoted identifiers, so a ; inside a string never trips it |
async-invocation-log.ts | asyncLinePass, asyncInvocationId, consoleInvocationLineSink, ASYNC_LINES_PER_PASS, AsyncUnit | The scope host's line for async work (#1901): one per consumer delivery (a module consumer, an executor, an imported event's handler) and per schedule run, built by the request line's own invocationLine, plus kind: 'consumer' | 'schedule' — a request's line has no kind, and absent reads as request. A consumer's line carries eventType, eventId, attempt and an outcome (delivered, retrying, dead-lettered, inert, routed); a schedule's, dueAt and latenessMs. Ids, names and the thrown error's errorCode only — never a payload or an error's text. A unit in a call's tail logs under the call's id; one outside any call under an id minted for it, which its ctx.log lines share. A pass writes at most ASYNC_LINES_PER_PASS (100) lines, then one suppressed line counting the rest per <kind>:<outcome>. Both adapters write it; the SQLite host's invocationLineSink redirects it. It ships inside the vertical's adapter, so a vertical writes these lines after it upgrades and pushes, not on a platform deploy |
invocation-line.ts | invocationLine, InvocationLogLine, OutputFieldsReport, AsyncInvocationKind, AsyncOutcome | The grammar of the one structured log line written per invocation: its fields, their defaults and their order, in one place. Two writers build through it — the request line, written by invocationLog / withInvocationLog in @substrat-run/vertical-host and stamped with the tenant and scope the router asserted, and the async line above — so a field added to one is added to both. A published contract: the read proxy filters on these key names, so fields are added and never renamed. Also importable from @substrat-run/kernel/invocation-line, which imports nothing at run time, because the platform's entry bundles it in front of every vertical (#1893) |
Fleet arithmetic
These are pure functions over the directory projection, deliberately shared so two callers can never disagree about what a number means.
| Module | Export | What it is |
|---|---|---|
platform-sweep.ts | runPlatformSweep, startPlatformSweeper, EventSink, AccessLogSink, PlatformSweepOptions, PlatformSweepReport | One pass of every scheduled thing the platform does, in a fixed order: migration reconciliation first (§5.3, #49), then drain retryable effects, drain pending platform intents, re-run the provision hook on every primary scope (isPrimaryScope: no forkedFrom and not kind: 'preview') whose running version is not the one its provision receipt names — a null receipt counts as behind, since a scope provisioned before the receipt existed has no evidence either way (#1172). The running version (runningVersionOf) is the one the vertical's stable serving script serves, for a scope on that script, and the bound version otherwise: a listed vertical's promote re-serves every install in place without moving their pointers, and this is what reaches them (#1653). At most provisionReconcileBatch (default 50) per pass, from a random start in the behind set so persistent failures cannot starve the rest. An install is also behind when its retirements did not finish for the version it runs (#2185), and the window is shared: installs whose receipt is behind take most of it, installs behind on their retirements alone are owed a quarter (at least one slot), and a slot one class does not need goes to the other; a vertical that answers 501 is counted unsupported, not failed, run each vertical's declared schedules (#383), judge each module's declared freshness expectations (#1272), reap expired snapshots and previews, reap long-archived scopes, reap lapsed tenants, reconcile connectors (each live connection through its provider's sweeper, after the landing step grants and binds it from the landings its vertical's running version declares — a landing declared on-request is left unbound by that step, for the scope to bind itself, #2732), drain each scope's domain events to Tier 2 through the EventSink (#1413), and the staff access log through the AccessLogSink last, pruning what shipped. Between those the pass also walks the cross-vertical edges (#1705), prunes telemetry (#1632) and findings (#1748), samples the storage gauge (#1524), sweeps orphaned attachments (#2314), rolls up the day's request counts (#2501) and takes the day's meter snapshot (#2501); each is off when its option is unset and reports null then. Migration goes first because a drain wakes a scope and wake migrates lazily — running it later would count every failed scope twice — and a scope whose migration failed this pass is skipped by the five phases that would run its code (both drains, provision reconcile, schedules, freshness), since a fail-closed scope would only re-throw the same error; the reaps, the connector pass and the event drain are not keyed on that set. The two sinks are injected, and absent a sink nothing drains — a self-host with none configured is a supported posture, it just keeps everything. recordSweepRun is likewise optional: when it is set, the connector, schedule and freshness phases write one _substrat_sweep_runs row per unit (#1255, the recorded subset the HostAdmin row above spells out); the pass returns a PlatformSweepReport per phase whether or not it is. The phases read the directory through HostAdmin.listScopesReadable when the host has it, so a directory row that does not read as a scope is stepped over by every phase and named once per pass in errors as scope-row (at most twenty); the default tenant reap alone reads strictly, since it clears the tenant's directory afterwards. It holds no timer: a node deployment calls startPlatformSweeper, a Cloudflare one arms a sweeper DO's alarm |
scope-identity.ts | isPrimaryScope, isPrimaryScopeRow, runningVersionOf, INERT_SCOPE_REASON, ServingPointer | The two questions the sweep, both adapters and every door that runs an effect ask the same way: whether a scope is the real install (isPrimaryScope: no forkedFrom, not kind: 'preview'), and which version's code runs on it (runningVersionOf: the serving script's version for a scope on it, the bound version otherwise). A non-primary scope's queued effects settle with INERT_SCOPE_REASON instead of running (#2005). |
migration-progress.ts | migrationProgress | What "487/500 migrated, 13 pending, 0 failed" means, computed once for both the sweep's report and the ops view. It reads the directory projection against the registered frontier — no scope is woken to answer a fleet question |
meters.ts | foldMeterReading | What counts as billable. Every adapter has the same three directory tables and could each write the same GROUP BY; they must not, because the billable rule is a commercial definition and two copies in two dialects is how the two fleets end up quoting different numbers for the same month |
model-usage.ts | foldModelUsage, MODEL_USAGE_RETENTION_DAYS | Meter 3's number, defined once for exactly the reason foldMeterReading is. Adapters list the lines in a window; this folds them, per (tenant, vertical, model) and in total: list price summed with addDecimal — an adapter summing in SQL would float the money — the platform's margin applied at read time rather than stored (D-30: meter, don't bill), and a call the rate card could not price counted as unpriced beside the money rather than folded in as $0, so an unpriced model reads as a gap in pricing instead of a free call |
scope-record.ts | resolveScopeRecord, readableScopes | The directory row provisionScope writes, with every optional resolved and the slug and vertical parsed (a vertical is a verticalSlug or null) — in the kernel so the two adapters cannot default differently. readableScopes maps directory rows the way HostAdmin.listScopesReadable answers: a row that does not read as a Scope is named by its ids and failed field names instead of failing the list |
Guarantees adapters must uphold
Any ScopeHost implementation must provide — verified by @substrat-run/contract-tests:
- Strict serialization per scope — one operation at a time, to completion.
- Structured-clone boundary — inputs/results cloned both directions, even in-process.
- Kernel-stamped events — id, timestamp, tenant, scope, actor stamped below the API surface.
- Fail-closed addressing — mismatched
(tenantId, scopeId)throws, never resolves elsewhere. - PII invariant at emit — PII-classed events without
subjectIdare rejected. - An entity's version is the last event's ULID —
versionOfmoves on every event about the entity, never moves for an event about another, and survives a shred: the payload is erased and the envelope kept, so an erased entity can still refuse a stale write. There is no version column anywhere, and deliberately not going to be one.