@substrat-run/kernel 0.114.0 → 0.117.0

package/dist/scope-host.d.ts

@@ -1,8 +1,11 @@
-import type { AdminAction, ListPage, Connection, ConnectionFilter, ConnectionId, ConnectionGrant, ConnectionGrantRecord, ConnectionSecret, CreateConnectionInput, OpenConnection, ProjectedConnectionGrant, ProjectedConnectionKey, AccessLogEntry, DelegatedReadRecord, BindHostnameInput, AdminLogEntry, OpsFailureEntry, SweepRunEntry, SweepRunKind, SweepRunOutcome, ModelUsageEntry, ModelUsageSummary, CapabilityGrant, CreateTenantInput, Decision, Instant, DomainEvent, DomainEventInput, PlatformRequestInput, PlatformRequestId, PlatformRequest, PlatformRequestFilter, PlatformRequestStatus, PlatformRequestFailure, EntitlementGrant, EntitlementGrantInput, EntitlementView, MeterReading, EntityRef, IdentityLink, IdentityPool, Jurisdiction, ModuleId, ModuleManifest, ScheduleSpec, SystemGrant, CreateOrgInput, Node, Org, OrgId, OrgMembership, PermissionKey, PlatformActorId, ChannelName, ChannelHistoryEntry, DnsRecord, HostnameBinding, HostnameStatus, PromotionAcknowledgement, PublishVersionInput, RegisterVerticalInput, VerticalServingState, RouteTarget, DirectoryDump, PrincipalId, ResolvedIdentity, RoleAssignment, RoleDefinition, QueryScopeInput, ReadScopeTableInput, Scope, ScopeDump, SubjectShredReceipt, ScopeQueryResult, ScopeId, ScopeStatus, ScopeTable, DenialFilter, DenialSummary, PermissionDenial, Coverage, BeginImpersonationInput, ImpersonationFilter, ImpersonationSession, ImpersonationSessionId, ScopeTablePage, StorageShape, Tenant, TenantId, TenantRole, TenantStoreHandle, AttachmentRecord, BlobStoreHandle, Visibility, Vertical, VerticalChannel, VerticalVersion, TenantStatus, Page, CountedPage, FreshnessSpec, DrainedEvent, EntityHistoryInput, EventFacetInput, EventCauseInput, EventEffectsInput, EffectsTree, InvocationEventsInput, InvocationEvents, DeadLettersInput, DeadLetter, CauseChain, EventFacetResult, HistoryEntry, ErrorCode, PlatformRequestFailureOrigin, IssueEntry, IssueStatus, IssueStatusInput } from '@substrat-run/contracts';
+import type { AdminAction, BecomeCapabilityInput, CapabilityExchange, CapabilityId, MintedCapability, ListPage, Connection, ConnectionFilter, ConnectionId, ConnectionGrant, ConnectionGrantRecord, ConnectionSecret, CreateConnectionInput, OpenConnection, ProjectedConnectionGrant, ProjectedConnectionKey, AccessLogEntry, DelegatedReadRecord, BindHostnameInput, AdminLogEntry, OpsFailureEntry, SweepRunEntry, SweepRunKind, SweepRunOutcome, ModelUsageEntry, ModelUsageSummary, CapabilityGrant, CreateTenantInput, Decision, Instant, DomainEvent, DomainEventInput, PlatformRequestInput, PlatformRequestId, PlatformRequest, PlatformRequestFilter, PlatformRequestStatus, PlatformRequestFailure, EntitlementGrant, EntitlementGrantInput, EntitlementView, MeterReading, EntityRef, IdentityLink, IdentityPool, Jurisdiction, ModuleId, ModuleManifest, ScheduleSpec, SystemGrant, SystemSwitch, SystemSwitchResult, CreateOrgInput, Node, Org, OrgId, OrgMembership, PermissionKey, PlatformActorId, ChannelName, ChannelHistoryEntry, DnsRecord, HostnameBinding, HostnameStatus, PromotionAcknowledgement, PublishVersionInput, RegisterVerticalInput, VerticalServingState, RouteTarget, DirectoryDump, IdentityMembership, PrincipalId, ResolvedIdentity, RoleAssignment, RoleDefinition, QueryScopeInput, ReadScopeTableInput, Scope, ScopeDump, SubjectShredReceipt, ScopeQueryResult, ScopeId, ScopeStatus, ScopeTable, DenialFilter, DenialSummary, PermissionDenial, Coverage, BeginImpersonationInput, ImpersonationFilter, ImpersonationSession, ImpersonationSessionId, ScopeTablePage, StorageShape, Tenant, TenantId, TenantRole, TenantStoreHandle, AttachmentRecord, BlobStoreHandle, Visibility, Vertical, VerticalChannel, VerticalVersion, TenantStatus, Page, CountedPage, FreshnessSpec, EntityHistoryInput, EventFacetInput, EventCauseInput, EventEffectsInput, EffectsTree, InvocationEventsInput, InvocationEvents, DeadLettersInput, DeadLetter, CauseChain, EventFacetResult, HistoryEntry, ErrorCode, PlatformRequestFailureOrigin, IssueEntry, IssueStatus, IssueStatusInput } from '@substrat-run/contracts';
+import type { CapabilityVerbs } from './capability.js';
 import type { ModelUsageFilter, ModelUsageInput, ModelUsageWindow } from './model-usage.js';
 import type { SealedSecret } from './secret-box.js';
 import type { SearchHit, SearchOptions } from './search-index.js';
 import type { EntityVersion } from './entity-version.js';
+import type { UndrainedEvents } from './outbox-event.js';
+import type { JobDriveReport, JobHandler, JobRun, JobRunFilter, StartJobRunInput } from './job-run.js';
 /**
  * What a caller asks a paged read for (#811).
  *
@@ -152,7 +155,11 @@ export interface OperationContext {
      * one to an untrusted caller does its own `assertAllowed` first.
      */
     versionOf(entity: EntityRef): EntityVersion | null;
-    /** Node-level check; pass `entity` for per-entity checks (portal access, §4.2 rule 3). */
+    /**
+     * Node-level check; pass `entity` for per-entity checks (portal access, §4.2 rule 3).
+     * A `permission` that is not a key (a cast past the brand) throws `internal` rather
+     * than returning a denial, and records none (#1642, `assertPermissionKey`).
+     */
     check(permission: PermissionKey, entity?: EntityRef): Promise<Decision>;
     /**
      * Find entities of one type by what a person typed (#827) — the read a picker
@@ -326,6 +333,41 @@ export interface OperationContext {
      * permission problem.
      */
     canAssign(roleKey: string): Promise<Coverage>;
+    /**
+     * Capabilities (#1672) — authority carried by a SECRET rather than held by a principal:
+     * "anyone with this link may read this folder until Friday".
+     *
+     * `mint` narrows authority the CALLER holds onto one entity (and what lies beneath it
+     * through declared parent edges), specific keys, an optional operation allowlist, an
+     * optional expiry and use limit, and returns the secret once. Whoever later exchanges
+     * that secret (`ScopeHost.exchangeCapability`) acts as `{ capability: <id> }` — resolved
+     * by the checker against the capability's own row, stamped on every event it emits,
+     * refused into the denial log like any other actor.
+     *
+     * Non-escalating on EVERY use, not only at mint: each key is re-checked here on the
+     * entity with this operation's own check (`ctx.grant`'s predicate), and the checker
+     * re-checks the minter every time the capability acts — so revoking the minter's access
+     * ends what their links can do. Only a principal may mint or revoke; a capability,
+     * connection or schedule cannot delegate.
+     *
+     * ```ts
+     * assertAllowed(await ctx.check('folder:share', folderRef));
+     * const { secret } = await ctx.capabilities.mint({
+     *   entity: folderRef,
+     *   permissions: ['folder:read'],
+     *   expiresAt: input.expiresAt,
+     * });
+     * return { link: `${origin}/#share=${secret}` }; // a FRAGMENT: never sent to a server
+     * ```
+     *
+     * The kernel stores only the secret's hash, and an idempotency recording withholds the
+     * secret. Beyond that, a TRIPWIRE: while this invocation runs, `ctx.emit`,
+     * `ctx.requestPlatform` and `ctx.sql` refuse any record that carries the secret verbatim,
+     * which catches a module persisting it by accident. It is not a boundary against a module
+     * that means to leak it (`assertNoSecret` says why). Transactional with the operation,
+     * like `ctx.grant`.
+     */
+    readonly capabilities: CapabilityVerbs;
     /**
      * Run `fn` as a SUB-TRANSACTION of this operation (#770,
      * docs/architecture/sub-transactions.md) — the boundary that makes catching an
@@ -632,11 +674,23 @@ export interface FreshnessReport {
  * What `runDueSchedules` did for one scope in one pass (#383). A schedule inside its
  * cadence window is `skipped`; a due one is `fired` (its operation ran) or `failed`
  * (the operation threw — recorded, never allowed to stop the others).
+ *
+ * A module switched off on the scope (#1666, `revokeFromSystem`) reports every schedule
+ * `skipped` with `switchedOff: true`, due or not: nothing ran, and that was decided, so
+ * it is neither a failure nor an absence. `skipped` rather than a new outcome because
+ * the durable sweep record parses outcomes on the platform side, and a vertical newer
+ * than its control plane must not emit a value that refuses the whole batch.
  */
 export interface ScheduleRunReport {
     fired: number;
     skipped: number;
     failed: number;
+    /**
+     * The module is switched off on this scope (#1666) — every `skipped` above is that,
+     * not a cadence window. Optional and absent otherwise, so a stored or pre-widening
+     * report stays valid.
+     */
+    switchedOff?: true;
     /** Per-schedule failures on this scope: the operation name and the error. */
     errors: {
         operation: string;
@@ -1232,10 +1286,75 @@ export interface HostAdmin {
      * reason: one grant mechanism, tuples tombstoned on revoke (K-21), visible to the
      * permission diff. It is what makes `ctx.check` resolve for a schedule — the gate
      * stays `ctx.check`, not a bypass. Projected at scope provisioning from the
-     * module's declared `schedules[].permissions`; a per-tenant "scheduling off" is a
-     * revoke of this grant, nothing more.
+     * module's declared `schedules[].permissions`.
+     *
+     * **Refused while the module's schedule kill switch is off on that scope** (#1666),
+     * with `conflict`: restore is the lever; a grant is not. A grant that went through would
+     * hand the module's system authority back to a job run or a `getSystemScope` invoke
+     * while its schedules stayed off. Only `restoreToSystem` turns the switch back on.
+     * (A TENANT-level grant — `node.scopeId` null — is not checked: the switch lives in each
+     * scope's storage and the directory cannot see it. Nothing in the platform writes one.)
      */
     grantToSystem(actor: PlatformActorId, grant: SystemGrant): Promise<void>;
+    /**
+     * The schedule kill switch (#1666): turn ONE module's scheduled work off on ONE scope.
+     *
+     * Module-wide on the scope, by design — see `systemSwitch` for why a per-permission or
+     * per-schedule switch is either inexpressible or noisy. It tombstones every live
+     * `system:<module>` grant the scope holds (K-21) and makes the scope's OFF marker live
+     * (`system-switch.ts`). While it is off:
+     *
+     * - `runDueSchedules` fires nothing for the module and reports each schedule `skipped`
+     *   with `switchedOff: true` — never `failed`, so a switched-off scope makes no noise,
+     *   and its cadence clock is untouched, so a due schedule fires on the first pass after
+     *   `restoreToSystem`;
+     * - anything acting with the module's system authority is denied by its own
+     *   `ctx.check` — a resumable job run (#1577) fails its step, a `getSystemScope` invoke
+     *   is refused;
+     * - and nothing can hand that authority back: `grantToSystem` refuses, and a reconcile
+     *   seats no `system:` grant for the module, not even one a newer version declares.
+     *   `restoreToSystem` is the only way back.
+     *
+     * **Audited first, on every attempt**: an intent row (with the `reason`) before anything
+     * moves, then an outcome row (`applied`, `refused`, or `failed`), paired by the
+     * `operationId` the call answers with. A repeat — including the retry after a crash
+     * between the move and its outcome row — answers `changed: false` and is audited all the
+     * same. The scope's storage and the admin log are separate stores, so the pair is not
+     * atomic: this order fails toward "an intent with no outcome", never toward "a switch
+     * that moved with no row".
+     *
+     * Throws `not_found` when the scope holds no `system:<module>` grant at all — a typo in
+     * an emergency must not answer "done". On a host that delegates to the deployment
+     * serving the scope, the write happens THERE and the audit rows HERE.
+     */
+    revokeFromSystem(actor: PlatformActorId, input: SystemSwitch): Promise<SystemSwitchResult>;
+    /**
+     * The inverse of `revokeFromSystem` (#1666), and the ONLY way to turn a switched-off
+     * module's schedules back on: tombstones the OFF marker and restores exactly the grants
+     * the OFF took — a grant revoked independently before the switch was pulled stays
+     * revoked, so ON never widens the system principal. Same shape, same `reason`, same
+     * audit-first rows, same idempotence and `not_found`.
+     */
+    restoreToSystem(actor: PlatformActorId, input: SystemSwitch): Promise<SystemSwitchResult>;
+    /**
+     * Mint a `become` capability on a scope (#1672): whoever exchanges its secret yields
+     * `input.principal` rather than a session — the shape an owner claim link and a member
+     * invite are, so both can move onto this primitive later. The secret is returned once;
+     * the scope keeps its hash. Expiry and a use limit are required.
+     *
+     * Platform-only in this first cut, deliberately: `become` is impersonation by another
+     * name, and the bound on who may mint one from module code is designed with the claim
+     * and invite migrations. Audited in the admin log (never the secret, never its hash).
+     * Refuses an unknown or inactive scope, as `getScope` does.
+     */
+    mintCapability(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId, input: BecomeCapabilityInput): Promise<MintedCapability>;
+    /**
+     * Revoke any capability on a scope (#1672) — the operator's lever for a leaked link, and
+     * how a re-minted claim link retires the last one. Takes effect on the next check, for
+     * every session it handed out. Idempotent; `not_found` for a capability the scope does
+     * not hold. Audited in the admin log.
+     */
+    revokeCapability(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId, capabilityId: CapabilityId): Promise<void>;
     grantToOrg(actor: PlatformActorId, orgId: OrgId, permission: PermissionKey, node: Node, entity?: EntityRef): Promise<void>;
     addMember(actor: PlatformActorId, tenantId: TenantId, principal: PrincipalId, orgId: OrgId): Promise<void>;
     /**
@@ -1489,6 +1608,15 @@ export interface HostAdmin {
         takenAt: string;
         pending: string[];
     }[]>;
+    /**
+     * The size in bytes of a CO-LOCATED scope's database (#1524): `SqlStorage.databaseSize`
+     * on a Durable Object, `page_count × page_size` on SQLite. It covers the scope database
+     * only. Attachment blobs, per-tenant D1 stores and the lake are elsewhere and are not
+     * counted. It wakes the scope, so the one caller is an on-demand storage reading, never
+     * a sweep. For a dispatch vertical the route reads it through the vertical's
+     * `/internal/database-size` instead, and this is the co-located fallback. Access-logged.
+     */
+    scopeDatabaseSize(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId): Promise<number>;
     /**
      * #286's backout: PITR-rewind a scope to a pre-migration bookmark — schema AND
      * data, discarding every write since. Audited (destructive by design). The scope
@@ -1664,8 +1792,14 @@ export interface HostAdmin {
      * repeat is harmless — the lake is keyed by event id and every consumer in this
      * platform is already required-idempotent. At-least-once is the only one of the
      * two that cannot silently lose exact history, which is the point of the tier.
+     *
+     * A row that does not decode is SKIPPED (#1636): never returned, so no sink receives an
+     * event built from stand-ins, and never stamped, so the stamp stays exact. The read steps
+     * past it so the rows behind it still ship, and says what it stepped over in the answer's
+     * optional `skipped` — absent on a clean read, so every caller that reads an array reads
+     * the one it always did. See `readUndrainedOutbox` for the bound, and for the cost.
      */
-    readUndrainedEvents(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId, limit?: number): Promise<DrainedEvent[]>;
+    readUndrainedEvents(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId, limit?: number): Promise<UndrainedEvents>;
     /**
      * Stamp `drained_at` on events the sink accepted (#1334). Idempotent: marking a
      * row already marked changes nothing, so a retry after a partial ship is safe.
@@ -1710,9 +1844,17 @@ export interface HostAdmin {
      *
      * A cutoff in the FUTURE is refused here, at the boundary, not only by the control-plane
      * route: this is a public verb and in-process callers never pass that door.
+     *
+     * `countOnly` (#1545) answers the same question read-only: how many rows the window holds,
+     * with nothing reopened and no receipt written — a count egresses nothing, so there is no
+     * second egress for K-24 to record, and an intent row for a mutation that never happens is
+     * a claim about the tenant's data that is not true. It is UNBOUNDED, unlike the reopen:
+     * an aggregate materialises no rows, so it answers for the whole window in one call rather
+     * than a batch of it. Absent, the verb reopens exactly as it always has.
      */
     redrainEvents(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId, input: {
         drainedBefore: string;
+        countOnly?: boolean;
     }): Promise<number>;
     /**
      * Facet a CO-LOCATED scope's outbox (#1239) — narrow, group, count. For a
@@ -2214,6 +2356,19 @@ export interface HostAdmin {
      * because asking at all is a category error the caller should see.
      */
     listIdentityTenants(actor: PlatformActorId, provider: string, externalId: string): Promise<TenantId[]>;
+    /**
+     * `listIdentityTenants`, with what a caller does next already attached: each tenant
+     * row (status included), the login's principal in it, and the scope the link was
+     * made in. One read and ONE access-log row, where composing the same answer out of
+     * `listIdentityTenants` + a `getTenant`/`resolveIdentity` per tenant is 2N+ reads and
+     * as many log rows — on a hosted directory each of those is a round trip, and a
+     * request that resolves its caller this way pays them before it does any work.
+     *
+     * Same safety condition as `listIdentityTenants`, for the same reason: **central
+     * pools only**, and it throws on a tenant-bound or unregistered pool. Ordered by
+     * tenant id. Non-active tenants are returned, not filtered — see `IdentityMembership`.
+     */
+    listIdentityMemberships(actor: PlatformActorId, provider: string, externalId: string): Promise<IdentityMembership[]>;
     /**
      * Every identity link in one tenant — the projection read (#406). This is what the
      * platform gathers (authoritatively, never from a caller's body) to deliver a
@@ -2629,6 +2784,36 @@ export declare const OPS_FAILURE_RETENTION_DAYS = 90;
  * for the same reason: the table stays bounded even where no scheduled pass runs.
  */
 export declare const SWEEP_RUN_RETENTION_DAYS = 14;
+/**
+ * The drained batch's dedupe key on the directory's `_substrat_sweep_runs` (#1232), as
+ * both adapters build it: `recordSweepRun` is an `INSERT OR IGNORE` against this index,
+ * which is what makes a replayed drain write nothing twice.
+ *
+ * `kind` is in it since #1572, and that is the fix rather than a tidy-up. Every entry of
+ * one drained batch shares its `request_id`, and `unit` is built from two namespaces that
+ * nothing keeps apart — `<scopeId>:<operation>` for a schedule, `<scopeId>:<eventType>`
+ * for a freshness verdict — while `scheduleSpec.operation` is `z.string().min(1)`. A
+ * schedule named exactly like an event type its scope expects freshness on collided on
+ * `(request_id, unit)`, and the ignore-on-conflict write discarded the second row with no
+ * error anywhere. Both rows are signals by their absence (a stopped evaluator, a missed
+ * run), so losing one read as the very thing it was meant to rule out. It is #1288's
+ * collision, in the record table beside the state table.
+ *
+ * Shared rather than spelled in each adapter because a directory that predates it
+ * re-creates it (`ensureSweepRunsIntentKind`, in both), and `lint:spine-ddl` sees only
+ * the created copy. One definition keeps the re-created shape and the created shape the
+ * same shape; the gate then holds each adapter's DDL to including it.
+ */
+export declare const SWEEP_RUNS_INTENT_INDEX = "CREATE UNIQUE INDEX IF NOT EXISTS _substrat_sweep_runs_intent ON _substrat_sweep_runs (request_id, kind, unit);";
+/**
+ * Whether a directory's `_substrat_sweep_runs_intent` already has `kind` among its
+ * columns, read off the index's `sql` in `sqlite_master` — which DO SQLite serves and
+ * `PRAGMA` does not, so both adapters detect by one strategy. `false` means the index
+ * must be DROPPED and created again: `CREATE … IF NOT EXISTS` matches on the name alone,
+ * so on every existing directory the old `(request_id, unit)` index would otherwise
+ * stand for good, while a fresh one — and any test that starts from one — gets the new.
+ */
+export declare function sweepRunsIntentHasKind(indexSql: string): boolean;
 /**
  * How long an issue row outlives its last occurrence (#1233). Deliberately longer
  * than the 90-day evidence beneath it: an issue is the compressed memory of a
@@ -2669,10 +2854,12 @@ export interface SweepRunInput {
     at?: string | null;
     /**
      * The platform-intent id a drained batch arrived under — the dedupe key. The
-     * adapters enforce UNIQUE (requestId, unit) with an ignore-on-conflict write,
-     * so a replayed drain (a settle that failed in transport, a partial batch
-     * re-run) writes nothing twice. Unset (the direct sweep path) dedupes nothing:
-     * NULLs are distinct under the unique index, exactly as intended.
+     * adapters enforce UNIQUE (requestId, kind, unit) with an ignore-on-conflict
+     * write (`SWEEP_RUNS_INTENT_INDEX`), so a replayed drain (a settle that failed in
+     * transport, a partial batch re-run) writes nothing twice — while a schedule and
+     * a freshness entry of one batch that derive the same unit are two rows (#1572).
+     * Unset (the direct sweep path) dedupes nothing: NULLs are distinct under the
+     * unique index, exactly as intended.
      */
     requestId?: string | null;
 }
@@ -3040,6 +3227,43 @@ export interface ScopeHost {
      * so the type holds, but it is **not a person**.
      */
     getSystemScope(moduleId: ModuleId, tenantId: TenantId, scopeId: ScopeId): Promise<ScopeStub>;
+    /**
+     * Trade a capability's SECRET for what it grants (#1672) — one counted use.
+     *
+     * `act`: a session token to present to `getCapabilityScope`, valid until the earlier of
+     * `CAPABILITY_SESSION_TTL_MS` and the capability's own expiry. The harness sets it as an
+     * HttpOnly cookie, so the secret itself is presented exactly once and never lives in
+     * browser history or a `Referer` (`@substrat-run/vertical-host`'s
+     * `mountCapabilityExchange`). `become`: the principal the holder becomes, for the
+     * harness's identity directory to bind.
+     *
+     * `null` for an unknown, expired, revoked or used-up secret — one answer, so a probe
+     * learns nothing. The use is atomic: a single-use secret exchanged twice at once admits
+     * one. The exchange is on the spine as `capability.exercised`, actor `{ capability }`.
+     * Same fail-closed (tenant, scope) and lifecycle gate as `getScope`.
+     *
+     * `options.mode` names the only kind the caller can handle; a secret of the other kind
+     * answers `null` WITHOUT taking a use — so a claim link pasted into a share-link route is
+     * refused rather than spent.
+     */
+    exchangeCapability(tenantId: TenantId, scopeId: ScopeId, secret: string, options?: {
+        mode?: 'act' | 'become';
+    }): Promise<CapabilityExchange | null>;
+    /**
+     * A scope stub whose authority is a CAPABILITY (#1672) — the fifth door, beside the
+     * principal, connection, system and impersonation ones, and a door rather than a flag for
+     * the reason each of those is: what differs is the authority.
+     *
+     * The session is re-resolved on EVERY invoke, inside the operation's transaction: a
+     * revoked or expired capability, or an expired session, is refused `unauthenticated`
+     * before the handler runs, and an operation outside the capability's allowlist is
+     * refused `forbidden`. Neither is a K-35 denial — no key was checked. Inside, the
+     * operation is ordinary: `ctx.check` resolves the capability's grant (its entity subtree,
+     * its keys, its minter's authority now), refusals ARE recorded with actor
+     * `{ capability }`, and so is every event it emits. `ctx.principal` carries the
+     * capability id so the type holds; it is **not a person**.
+     */
+    getCapabilityScope(sessionToken: string, tenantId: TenantId, scopeId: ScopeId, options?: ScopeStubOptions): Promise<ScopeStub>;
     /**
      * The recurring-work declarations of every module registered on this host (#383)
      * — each module's id, the vertical it belongs to, and its `schedules`. Sync like
@@ -3110,6 +3334,84 @@ export interface ScopeHost {
      * nothing is due.
      */
     drainDue(tenantId: TenantId, scopeId: ScopeId): Promise<ExecutorDrainReport>;
+    /**
+     * Register a JOB — long, resumable work (#1577). Host code, like
+     * `registerExecutor`, and for the same reason: a walk of an external system
+     * holds credentials and makes network calls, which module code may not.
+     *
+     * `moduleId` and `name` are two thirds of the coalescing key; the third is the
+     * `instance` a run names. The handler is the body of ONE PASS — see `JobHandler`
+     * and this driver's contract in `job-run.ts`. `retry` is the DEFAULT policy for
+     * the job's steps; a step may pass its own.
+     *
+     * The fourth driver, and a SIBLING of the three that already exist rather than a
+     * widening of any of them. An executor retries one delivery whole; a schedule
+     * fires one operation that must finish; the platform sweep does a pass of
+     * maintenance. None of them can stop halfway through an hour and carry on.
+     */
+    registerJob(moduleId: ModuleId, name: string, handler: JobHandler, retry?: ExecutorRetryPolicy): void;
+    /**
+     * Start a run, or JOIN the one already in flight for the same
+     * `(module, job, instance)` — the coalescing half of the driver.
+     *
+     * A start against a live key returns THAT run: its id, its cursor, its counters.
+     * Not a second row, and not a refusal — asking for a re-index while one is
+     * running is a reasonable thing to do, and the useful answer is the walk that is
+     * already happening. Coalescing is the driver's decision, never a unique index:
+     * a run whose worker was evicted is still `running` and MUST be restartable, so
+     * the constraint cannot be "one row ever" (which is what `_substrat_sweep_runs`
+     * legitimately carries, being a receipt rather than a cursor).
+     *
+     * The payload is held to the queue-safety rule at this boundary and refused with
+     * the offending path named, the way an operation's input failure already is: ids
+     * and configuration, never bytes, class instances or functions.
+     *
+     * Fleet maintenance, no actor — the same class as `drainDue`. What the run may DO
+     * is decided inside it, by an ordinary `ctx.check` against `system:<moduleId>`.
+     */
+    startJobRun(tenantId: TenantId, scopeId: ScopeId, input: StartJobRunInput): Promise<JobRun>;
+    /**
+     * Advance every DUE run on this scope — the driver proper, the resumable sibling
+     * of `drainDue`.
+     *
+     * One pass per run by default: a pass does a bounded chunk, commits a cursor, and
+     * the next call resumes from it, so an hour-long walk is never one call anybody
+     * has to keep alive. `maxPasses` raises that for a caller with a budget; `limit`
+     * caps how many runs one call picks up.
+     *
+     * A step that exhausts its retries fails ITS run and is reported — never thrown,
+     * so one bad run cannot stop the ones behind it. Idempotent and safe when nothing
+     * is due. A run whose job this host does not register is left untouched: it may
+     * belong to another deployment, and failing it would destroy a resumable run
+     * because the wrong process looked at it.
+     *
+     * Deliberately NOT gated on the module's `system:<moduleId>` grant the way
+     * `runDueSchedules` is. A schedule is started by the platform and the grant is
+     * the switch that says whether it should be; a run was started explicitly, and a
+     * grant gate here would STALL it silently rather than refuse it. The authority it
+     * exercises is checked where it is used, inside the operations its steps invoke.
+     *
+     * **One driver per scope at a time**, and that is a bound the caller holds, not one
+     * this enforces — there is no lease. Coalescing stops duplicate RUNS; two concurrent
+     * calls of THIS would advance the same run together. Every topology the driver is
+     * built for gives a scope one tick (the platform sweep does one call per scope, a
+     * scope DO's alarm fires for its own), so the bound holds by construction; the full
+     * argument, and what an overlap would actually cost, is in `job-run.ts`.
+     */
+    runDueJobs(tenantId: TenantId, scopeId: ScopeId, options?: {
+        maxPasses?: number;
+        limit?: number;
+    }): Promise<JobDriveReport>;
+    /**
+     * The scope's run records, newest first — "the outcome has to be legible to an
+     * operator afterwards", as a read rather than as a promise.
+     *
+     * Every run, in whatever state it settled, with the cursor it reached, the
+     * counters it accumulated and the error that stopped it. Fleet maintenance, no
+     * actor — the same class as `listPlatformRequestHistory`, which it is shaped
+     * after for the same reason: a record nobody can read is not evidence.
+     */
+    jobRuns(tenantId: TenantId, scopeId: ScopeId, filter?: JobRunFilter): Promise<JobRun[]>;
     /**
      * Execute ONE connector delivery with this host's directory, credentials and egress —
      * the platform half of #574 phase 3. A CP-less host routes each connector delivery
@@ -3191,10 +3493,143 @@ export interface ScopeHost {
         /** WHO refused (#841). Omitted by a caller too old to attribute — stored as NULL. */
         failure?: PlatformRequestFailure | null;
     }): Promise<void>;
+    /**
+     * Live reads (#938) — a subscription to this scope's change feed, or absent.
+     *
+     * **Optional on the contract, and that is the whole design.** A live read needs a
+     * transport that can hold a connection open for longer than a request, and only one
+     * host has one: on Cloudflare a scope IS a Durable Object, which the runtime keeps
+     * addressable between requests and can hand a `WebSocketPair` to. The pure host is a
+     * function call inside somebody else's process — there is no connection for it to
+     * hold and nothing to wake when an event lands — so `SqliteScopeHost` declares
+     * `liveReads?: never`, the `clock?: never` precedent (`CloudflareScopeHostOptions`)
+     * applied in the other direction: there, the hosted adapter refuses an option it
+     * cannot honour; here, the pure adapter refuses a surface it cannot honour. A
+     * mistaken `host.liveReads!.subscribe(…)` against SQLite is a compile error rather
+     * than a promise that never resolves.
+     *
+     * What this costs, stated rather than hidden, exactly as the clock seam states it:
+     * live-read behaviour is held to its tests on the Cloudflare host ONLY. There is no
+     * contract suite for it, because a contract suite is a claim that both adapters
+     * answer the same way, and on this one they deliberately do not.
+     *
+     * A caller therefore asks rather than assumes:
+     *
+     * ```ts
+     * const live = host.liveReads;
+     * if (!live) return new Response('live reads are not available here', { status: 501 });
+     * return live.subscribe({ tenantId, scopeId, principal, request });
+     * ```
+     */
+    readonly liveReads?: LiveReadSurface;
     /** Bare operation registration (tests, glue). Names are module-namespaced: 'workorder/create'. */
     defineOperation<I, O>(name: string, handler: OperationHandler<I, O>): void;
     close(): Promise<void>;
 }
+/**
+ * The live-read surface (#938): one `Upgrade` in, one long-lived subscription out.
+ *
+ * **What crosses it is an invalidation, never a payload.** A frame names the event
+ * type and the `(entityType, entityId)` it was about, and the client re-reads that
+ * entity through the ordinary operation it already calls. That is what keeps the
+ * change feed from quietly becoming a second, ungoverned read API: every field a
+ * subscriber ever sees came back through the declared read surface, with that read's
+ * own permission check, its own field-level omissions and its own PII handling.
+ *
+ * **Every frame is filtered per subscriber, after the commit and after the check.**
+ * The host offers each committed event to each subscriber and delivers it only if
+ * that subscriber passes the entity type's declared `liveTargets.readPermission` ON
+ * THAT ENTITY — the same walk `ctx.check(key, entityRef)` makes, through the same
+ * evaluator, so an entity-narrowed grant decides a push exactly as it decides a read.
+ * An entity type no module declared reaches nobody. Knowing that a row exists and
+ * changed at 14:02 is information about that row, so "the body was empty" is not a
+ * defence: the filter runs whether or not there is a payload to withhold.
+ *
+ * **Generic over the runtime's request and response, because the kernel names
+ * neither.** This package has one dependency and no DOM or workers lib
+ * (`docs/architecture/dependency-policy.md`), which is why `FetchLike` above describes
+ * a `fetch` structurally rather than importing one. The same rule applies here, and it
+ * is load-bearing in the other direction too: what a caller gets back must be the
+ * runtime's OWN response object, because a Worker's handler has to return one. A
+ * structural stand-in would describe it correctly and still not be returnable. So the
+ * type travels through instead of being restated — `CloudflareScopeHost` binds it to
+ * the real `Request`/`Response`, and code holding the bare contract gets `unknown` back
+ * and narrows at its own mount point, where it knows which host it is on.
+ */
+export interface LiveReadSurface<Req extends LiveUpgradeRequest = LiveUpgradeRequest, Res = unknown> {
+    /**
+     * Accept a WebSocket `Upgrade` and subscribe the principal to the scope's changes.
+     *
+     * The caller is the vertical, and it has already done the one thing this surface
+     * cannot do for itself: resolved WHO is asking. The principal is an authenticated
+     * fact the vertical's session carries, exactly as it is for an `invoke` — this
+     * surface trusts it the same way and no further, which is why every frame is still
+     * checked against it individually rather than a subscription being authorized once.
+     *
+     * Returns the 101 to hand back to the client, or a refusal to return as-is: a
+     * request that is not an upgrade gets 426, and one arriving over a hop that cannot
+     * carry a socket gets a refusal naming that, so the client can fall back to polling
+     * KNOWINGLY. Neither is thrown, because both are answers to a client rather than
+     * faults of the caller.
+     */
+    subscribe(input: {
+        tenantId: TenantId;
+        scopeId: ScopeId;
+        /** WHO is subscribing — resolved by the vertical from its own session, never by the client. */
+        principal: PrincipalId;
+        /** The upgrade request as it arrived, carried whole so the host reads its own headers. */
+        request: Req;
+    }): Promise<Res>;
+}
+/**
+ * The only thing this surface needs of an incoming request: its headers.
+ *
+ * Narrow on purpose. A live-read door reads `Upgrade` to know what is being asked for
+ * and `cf-connecting-o2o` to know whether this hop can carry it, and nothing else — it
+ * does not route on the path, read the body, or care about the method. Describing
+ * exactly that much is what lets a test drive the door with a two-line object instead
+ * of constructing a runtime request.
+ */
+export interface LiveUpgradeRequest {
+    readonly headers: {
+        get(name: string): string | null;
+    };
+}
+/**
+ * One frame on a live read (#938) — the wire shape, so both ends name it once.
+ *
+ * Deliberately not the outbox envelope. An envelope carries the payload, the
+ * authorization chain, the impersonation stamp and the PII class, and none of those
+ * belong on a channel whose contract is "re-read it yourself". What a subscriber
+ * needs in order to act is what is here: which entity changed, and what happened to it.
+ */
+export interface LiveChange {
+    /** Always `'change'` today; a field rather than an assumption, so a second kind can be added. */
+    readonly kind: 'change';
+    /**
+     * The event id — a ULID, so frames sort and a repeat is recognisable.
+     *
+     * **Not a gap detector, and a client must not use it as one.** ULIDs are ordered but
+     * not contiguous, so "the next id is not the one after this" says nothing on its own.
+     * More to the point, gaps here are the NORMAL case and the deliberate one: the
+     * permission filter withholds every event this subscriber may not read, so the ids it
+     * receives are a sparse subset of what the scope emitted, by design. A client
+     * inferring missed updates from the spacing would be reading someone else's
+     * entitlements as its own packet loss.
+     *
+     * What it is good for: ordering frames that arrive out of order, and discarding one
+     * it has already acted on. Detecting a genuinely missed update would need an
+     * authorized contiguous cursor — a per-subscriber sequence, counted after the filter —
+     * which this protocol does not have and should not grow by accident.
+     */
+    readonly id: string;
+    /** The emitted event type, e.g. `'ticket0/message-posted'`. */
+    readonly type: string;
+    readonly entityType: string;
+    readonly entityId: string;
+    /** When the event was emitted (ISO 8601), i.e. the emitting operation's instant. */
+    readonly at: string;
+}
 /**
  * Refuse a cutoff in the future — at the HostAdmin boundary, not only at the HTTP door.
  *