@substrat-run/kernel 0.136.0 → 0.138.0

package/dist/scope-host.d.ts

@@ -1,5 +1,6 @@
 import type { ModuleLog } from './module-log.js';
-import type { OnBehalfOf, ExportReadInput, ExportedBatch, ImportBatch, ImportedEvent, ImportResult, ImportState, ImportCursorMove, ImportCursorMoved, AdminAction, BecomeCapabilityInput, CapabilityExchange, CapabilityFilter, CapabilityId, CapabilityPage, MintedCapability, ListPage, Connection, ConnectionFilter, ConnectionId, ConnectionGrant, ConnectionGrantRecord, ConnectionSecret, CreateConnectionInput, OpenConnection, ProjectedConnectionGrant, ProjectedConnectionKey, AccessLogEntry, DelegatedReadRecord, OwnerTransferAudit, CopyMarkAudit, BindHostnameInput, AdminLogEntry, OpsFailureEntry, PlatformRequestDrainTotalsEntry, 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, PeerGrantsStatusEntry, SystemGrantsStatusEntry, SystemSwitchRecord, SystemSwitch, SystemSwitchResult, PeerCoverage, PeerSwitch, PeerSwitchResult, VerticalCaller, VerticalResolution, CreateOrgInput, Node, Org, OrgId, OrgMembership, PermissionKey, PlatformActorId, ChannelName, ExportBreak, ChannelHistoryEntry, DnsRecord, HostnameBinding, HostnameStatus, PromotionAcknowledgement, BindAcknowledgement, PublishVersionInput, RegisterVerticalInput, VerticalServingState, RouteTarget, DirectoryDump, IdentityMembership, PrincipalId, ResolvedIdentity, RoleAssignment, RoleDefinition, QueryScopeInput, ReadScopeTableInput, Scope, ScopeDump, SubjectShredReceipt, ScopeQueryResult, ScopeId, ScopeStatus, ScopeTable, DenialFilter, DenialSummary, RefusalFilter, RefusalRecord, 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, LifecycleFlowInput, LifecycleFlowResult, CauseChain, EventFacetResult, HistoryEntry, ErrorCode, PlatformRequestFailureOrigin, IssueEntry, IssueStatus, IssueStatusInput, DeclaredMigration, CheckSubject } from '@substrat-run/contracts';
+import type { DeliveryRefusal } from './delivery-refusal.js';
+import type { OnBehalfOf, ExportReadInput, ExportedBatch, ImportBatch, ImportedEvent, ImportResult, ImportState, ImportCursorMove, ImportCursorMoved, AdminAction, BecomeCapabilityInput, CapabilityExchange, CapabilityFilter, CapabilityId, CapabilityPage, MintedCapability, ListPage, Connection, ConnectionFilter, ConnectionId, ConnectionGrant, ConnectionGrantRecord, ConnectionSecret, CreateConnectionInput, OpenConnection, ProjectedConnectionGrant, ProjectedConnectionKey, AccessLogEntry, DelegatedReadRecord, OwnerTransferAudit, CopyMarkAudit, BindHostnameInput, AdminLogEntry, OpsFailureEntry, PlatformRequestDrainTotalsEntry, 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, PeerGrantsStatusEntry, SystemGrantsStatusEntry, SystemSwitchRecord, SystemSwitch, SystemSwitchResult, PeerCoverage, PeerSwitch, PeerSwitchResult, VerticalCaller, VerticalResolution, CreateOrgInput, Node, Org, OrgId, OrgMembership, PermissionKey, PlatformActorId, ChannelName, ExportBreak, ChannelHistoryEntry, DnsRecord, HostnameBinding, HostnameStatus, PromotionAcknowledgement, BindAcknowledgement, PublishVersionInput, RegisterVerticalInput, VerticalServingState, RouteTarget, DirectoryDump, IdentityMembership, PrincipalId, ResolvedIdentity, RoleAssignment, RoleDefinition, QueryScopeInput, ReadScopeTableInput, Scope, ScopeDump, SubjectShredReceipt, ScopeQueryResult, ScopeId, ScopeStatus, ScopeTable, DenialFilter, DenialSummary, RefusalFilter, RefusalRecord, 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, LifecycleFlowInput, LifecycleFlowResult, OperationSeriesInput, OperationSeriesResult, CauseChain, EventFacetResult, HistoryEntry, ErrorCode, PlatformRequestFailureOrigin, IssueEntry, IssueStatus, IssueStatusInput, DeclaredMigration, CheckSubject } from '@substrat-run/contracts';
 import type { ConnectionUseOutcome } from './connector-calls.js';
 import type { CapabilityVerbs } from './capability.js';
 import type { ModelUsageFilter, ModelUsageInput, ModelUsageWindow } from './model-usage.js';
@@ -593,6 +594,18 @@ export interface InvokeOptions {
      * uncapped count, so a reader can tell a short list from a truncated one.
      */
     readonly onEmitted?: (report: EmittedReport) => void;
+    /**
+     * Called after the operation COMMITS and its executors ran inline (#1184), with what each
+     * delivery of this call's events did. The inline path is the common case of K-22 §4.2,
+     * so the request holder is the one who can tell a person their accept was refused rather
+     * than report success for an effect that never happened.
+     *
+     * Every delivery the call's post-commit tail attempted, which can include an earlier
+     * call's retry that came due: a caller picks out its own by `eventType` and `entity`.
+     * Never called for a rolled-back operation, a read-only session or an
+     * idempotent replay. Absent from a host that predates it — read that as "not reported".
+     */
+    readonly onExecutorOutcomes?: (outcomes: readonly ExecutorOutcome[]) => void;
 }
 /** How many of an invocation's own events `onEmitted` names (#1746). `total` is uncapped. */
 export declare const EMITTED_REPORT_CAP = 20;
@@ -723,6 +736,48 @@ export type ConsumerHandler = (ctx: OperationContext, event: DomainEvent) => voi
  * code, and the version you declared is the only one you will be handed.
  */
 export type ImportHandler = (ctx: OperationContext, event: ImportedEvent) => void | Promise<void>;
+/**
+ * One membership change for `HostAdmin.applyMembership` (#1184): a TENANT-level role assigned
+ * or taken away, and nothing else. No org is joined or left — what an org confers lives partly
+ * in each scope's own store, where no directory unit can bound it, so authorizing an org
+ * membership is its own capability.
+ */
+export type MembershipChange = {
+    tenantId: TenantId;
+    principal: PrincipalId;
+    /** The tenant-level role assigned or taken away. */
+    roleKey: string;
+    /**
+     * Whose authority bounds the write (§5.1) — the inviter of an add, the remover of a removal:
+     * the unit applies nothing unless this principal covers every permission `roleKey` carries,
+     * read inside the unit (`tenantCoverage`).
+     */
+    boundedBy: PrincipalId;
+} & ({
+    op: 'add';
+    /** Apply nothing when `principal`'s removal fence stands at or after this instant. */
+    unlessRemovedSince: Instant;
+} | {
+    op: 'remove';
+});
+/**
+ * What the unit did: applied, or why not — fenced by a removal (an add only), or out of the
+ * bound. A removal that applied says whether it took anything (`changed`); one that took
+ * nothing still raised the fence.
+ */
+export type MembershipChangeResult = {
+    applied: true;
+    changed?: boolean;
+} | {
+    applied: false;
+    removedAt: string;
+} | {
+    applied: false;
+    missing: PermissionKey[];
+} | {
+    applied: false;
+    unknownRole: string;
+};
 /**
  * An **executor**: out-of-band host code that effects, outside a scope, what a module
  * asked for inside one (K-22 §4.2; D-18's triage rule — effects on the outside world
@@ -742,8 +797,53 @@ export type ImportHandler = (ctx: OperationContext, event: ImportedEvent) => voi
  * It receives `HostAdmin`, not `ctx`: it acts with platform authority, which is
  * precisely what module code must never hold. Admin writes it makes are stamped with
  * the causing event's id (`causedBy`), so the split trail joins.
+ *
+ * A handler that decides an event must never be effected RETURNS `refuseDelivery(reason)`
+ * (#1184). The delivery is journaled terminal with the reason, never retried. A return
+ * value rather than a thrown error, so module code cannot produce one: the most an
+ * operation can do is throw, and a throw is retried like any other failure.
  */
-export type ExecutorHandler = (admin: HostAdmin, event: DomainEvent) => void | Promise<void>;
+export type ExecutorHandler = (admin: HostAdmin, event: DomainEvent, scope: ExecutorScope) => void | DeliveryRefusal | Promise<void | DeliveryRefusal>;
+/**
+ * The scope an executor's event came from, as the executor may read it (#1184).
+ *
+ * Here rather than through `HostAdmin` or the host, and the pure adapter is why: its
+ * handler runs INSIDE the scope's actor task, and every host read of a scope re-enqueues
+ * on that actor, so `host.canAssign` from a handler waits on the task holding it and never
+ * returns. The adapter builds this to suit where the handler runs, as it builds a
+ * connector's `openAttachment`.
+ *
+ * Reads only, and checks no permission: the caller is host code that already holds
+ * platform authority. Both answer about the event's own (tenant, scope), never another.
+ */
+export interface ExecutorScope {
+    /** One entity's history in this scope — `readHistory`'s answer, oldest first. */
+    history(entity: EntityRef, page?: ListPage): Promise<Page<HistoryEntry>>;
+    /**
+     * May `principal` confer `roleKey` at this scope's node, or at the tenant node
+     * (`level: 'tenant'`)? The K-21 set comparison `ctx.canAssign` answers, narrowing-aware,
+     * over the tenant's projected role. Throws `unknownRoleError` for a role this tenant does
+     * not define.
+     */
+    covers(principal: PrincipalId, roleKey: string, level: 'scope' | 'tenant'): Promise<Coverage>;
+}
+/**
+ * What one executor delivery did inside the call that emitted its event (#1184) — what
+ * `InvokeOptions.onExecutorOutcomes` reports. `refused` is terminal by the handler's own
+ * decision; `dead-lettered` is terminal by exhaustion; `retrying` will be tried again.
+ */
+export interface ExecutorOutcome {
+    readonly executorId: string;
+    readonly eventId: string;
+    readonly eventType: string;
+    /** The event's entity, as `<entityType>:<entityId>` — how a caller finds its own event. */
+    readonly entity: string;
+    readonly outcome: 'delivered' | 'retrying' | 'dead-lettered' | 'refused' | 'inert' | 'routed';
+    /** The refusal reason, or the failure's message. Absent on a delivery. */
+    readonly error?: string;
+}
+/** One delivery's `ExecutorOutcome` — the one builder both adapters report through. */
+export declare function executorOutcomeOf(executorId: string, event: DomainEvent, outcome: ExecutorOutcome['outcome'], error?: unknown): ExecutorOutcome;
 /**
  * How hard the host tries before it gives up on one delivery (#100).
  *
@@ -846,7 +946,8 @@ export interface ScheduleRunReport {
      * 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. A module a PITR rewind holds off until its switch is back in the
-     * scope (#1819, Cloudflare only) reports the same.
+     * scope (#1819, Cloudflare only) reports the same. The system door refuses that module's
+     * other calls too, a job run's among them (#1834).
      */
     switchedOff?: true;
     /**
@@ -1432,6 +1533,10 @@ export interface HostAdmin {
      * role that was never assigned (or already revoked) is a silent no-op. Takes a
      * `PlatformActorId` like every admin mutation — the caller's own authority to do
      * this is decided above the kernel (e.g. the dashboard's manage-members check).
+     *
+     * At the TENANT node it also raises the principal's removal fence (#1184), in the same
+     * unit as the revoke and whether or not anything was held, so a membership-executor add
+     * still on its way for them is refused. The no-op stays unaudited.
      */
     unassignRole(actor: PlatformActorId, assignment: RoleAssignment): Promise<void>;
     grant(actor: PlatformActorId, grant: CapabilityGrant): Promise<void>;
@@ -1471,8 +1576,10 @@ export interface HostAdmin {
      * 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.)
+     * A TENANT-level grant (`node.scopeId` null) is refused the same way while the directory
+     * records the module off on any scope of the tenant (#1743). One that already existed when
+     * a scope was switched off gives the module nothing there: the evaluator denies a
+     * switched-off subject on its scope whatever it holds (#1823).
      */
     grantToSystem(actor: PlatformActorId, grant: SystemGrant): Promise<void>;
     /**
@@ -1489,7 +1596,8 @@ export interface HostAdmin {
      *   `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;
+     *   is refused — including authority from a TENANT-level grant, which OFF cannot
+     *   tombstone: the evaluator reads the marker before any grant (#1823);
      * - 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.
@@ -1502,8 +1610,14 @@ export interface HostAdmin {
      * 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
+     * Throws `not_found` when the module has no authority reaching the scope at all — no
+     * `system:<module>` grant on the scope and no live tenant-level one (#1823) — so a typo in
+     * an emergency does not answer "done". A module whose only authority there is a
+     * tenant-level grant IS switched: OFF writes the marker and tombstones nothing.
+     *
+     * The directory's record of the switch is written BEFORE the scope moves and taken back if
+     * the move throws or holds nothing (#1823), so #1743's tenant-level refusal has no window to
+     * miss. 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>;
@@ -1545,6 +1659,30 @@ export interface HostAdmin {
      * `systemGrantsStatus` reports both side by side (`schedules` and `recorded`).
      */
     listSystemSwitches(actor: PlatformActorId, filter?: SystemSwitchRecordFilter): Promise<SystemSwitchRecord[]>;
+    /**
+     * Which of these modules the tenant holds a live TENANT-level `system:` grant for (#1823).
+     * A module whose only authority on a scope is such a grant has nothing in the scope's
+     * storage, so a switch carried into a deployment (a hosted provision, reconcile or restore)
+     * names these as `tenantHeld`, and the deployment's in-unit OFF holds them too. Order follows
+     * `moduleIds`. Access-logged (K-24), as the fleet read is.
+     */
+    tenantHeldSystemModules(actor: PlatformActorId, tenantId: TenantId, moduleIds: readonly ModuleId[]): Promise<ModuleId[]>;
+    /**
+     * The peer half of a carry (#2029): the peers the directory records OFF on this one scope
+     * (`revokeFromPeer` writes the record, as `revokeFromSystem` writes the module's), and of those
+     * the ones the tenant holds a live tenant-level `vertical:` grant for (#2030). Carried into a
+     * deployment's provision, reconcile or restore beside the modules, so its in-unit OFF puts them
+     * back off too. Empty lists when none is. Access-logged (K-24), as the module reads are.
+     */
+    peerSwitchCarry(actor: PlatformActorId, node: {
+        tenantId: TenantId;
+        scopeId: ScopeId;
+    }): Promise<{
+        switchedOffPeers: string[];
+        tenantHeldPeers: string[];
+        /** #2045: each recorded-off peer's fence (the record's operation id), by slug. */
+        fences: Record<string, string>;
+    }>;
     /**
      * Put the directory's OFF positions back into one scope (#1674), for a scope whose storage
      * lost them: a wipe then re-provision, or a restore of a dump taken before the switch was
@@ -1572,6 +1710,10 @@ export interface HostAdmin {
      * deployment applying it. That move is undone (switched back on) and audited as
      * `staleCarry`, BEFORE the record is read again for the OFF pass. Only a module recorded
      * `on` is ever switched on here.
+     *
+     * Every kind of switch (#2029): after the modules, every peer the record holds `off` on the
+     * scope is switched off again the same way (through `revokeFromPeer`'s switch), audited as
+     * `reassertPeerSwitch`, and answered as an entry naming `vertical` rather than `moduleId`.
      */
     reassertSystemSwitches(actor: PlatformActorId, node: {
         tenantId: TenantId;
@@ -1635,6 +1777,21 @@ export interface HostAdmin {
     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>;
+    /**
+     * One membership change, applied as ONE directory unit (#1184): a single SQLite transaction or
+     * a single synchronous ControlPlaneDO method, with no await inside it. In that unit it
+     * re-evaluates the bound — `boundedBy` must still cover every permission `roleKey` carries,
+     * against the directory as it stands (`tenantCoverage`) — and only then writes. An ADD also
+     * reads `principal`'s removal fence first, then assigns the TENANT-level role and writes its
+     * audit row. A REMOVE unassigns it and raises the fence, as a tenant-level `unassignRole`
+     * does. A removal, a grant, a role redefinition or a demotion lands wholly before the unit
+     * (and governs it) or wholly after it, never between its check and its write.
+     *
+     * The fence is `_substrat_membership_fences`: every tenant-level `unassignRole` and every
+     * `removeMember` raises it for the person, in the same unit as its revoke — a no-op included,
+     * since a removal of someone whose add is still on its way must still win.
+     */
+    applyMembership(actor: PlatformActorId, change: MembershipChange): Promise<MembershipChangeResult>;
     /**
      * Revoke a membership (K-21). **Tombstones, never deletes**: the tuple keeps its
      * row, gains a `revokedAt`, and the permission walk skips it. Deletion would
@@ -1646,6 +1803,9 @@ export interface HostAdmin {
      * no-op, and a no-op is not audited. Re-adding via `addMember` clears the
      * tombstone (they are a member again); the add/revoke history lives in the admin
      * log, which is append-only.
+     *
+     * Raises the principal's removal fence (#1184) in the same unit as the revoke, a no-op
+     * included, so a membership-executor add still on its way for them is refused.
      */
     removeMember(actor: PlatformActorId, tenantId: TenantId, principal: PrincipalId, orgId: OrgId): Promise<void>;
     /**
@@ -2341,6 +2501,13 @@ export interface HostAdmin {
      * Reads only the lifecycle field of unclassified payloads; logged like every read here.
      */
     lifecycleFlow(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId, input: LifecycleFlowInput): Promise<LifecycleFlowResult>;
+    /**
+     * Calls per `(entityType, operation)` per time bucket over the scope's outbox (#1750) —
+     * `readOperationSeries`, hoisted: the business volumes Pulse draws. The caller passes
+     * the pairs (from the running version's declared lifecycles); the scope holds no model.
+     * Reads no payload; logged like every read here.
+     */
+    operationSeries(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId, input: OperationSeriesInput): Promise<OperationSeriesResult>;
     /**
      * One read-only SQL statement against the scope's database — the console the two
      * table-shaped reads deliberately weren't (#219). User SQL DOES reach the DB here,
@@ -3871,6 +4038,12 @@ export interface ScopeHost {
      * one enforcement path, `ctx.check` stays the single gate, no bypass. Events it
      * emits are stamped `{ system: moduleId }`. `ctx.principal` carries the module id
      * so the type holds, but it is **not a person**.
+     *
+     * **It is the one door for that authority** (#1834). A schedule's fire and a job run's
+     * `pass.scope()` both act through it, and so does `getSystemAttachments`. On the hosted adapter it
+     * also refuses (`forbidden`) a module a PITR rewind holds off (#1819), at every call it makes,
+     * not only when it is opened: each call is pinned to the scope instance the door checked, and
+     * a call landing on a restarted one (a rewound scope always is) is checked again first.
      */
     getSystemScope(moduleId: ModuleId, tenantId: TenantId, scopeId: ScopeId): Promise<ScopeStub>;
     /**
@@ -4116,12 +4289,19 @@ export interface ScopeHost {
      * 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.
      *
+     * `options.leaseMs` (#2034) is how long one pass holds its run without reaching a
+     * step boundary, which renews it — default `JOB_LEASE_MS`. Past it, the run is due
+     * again and the next drive takes it over, counting the silent pass as a failed
+     * attempt. A job whose pass may go longer than that between two steps says so here.
+     *
      * 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;
+    registerJob(moduleId: ModuleId, name: string, handler: JobHandler, retry?: ExecutorRetryPolicy, options?: {
+        leaseMs?: number;
+    }): void;
     /**
      * Start a run, or JOIN the one already in flight for the same
      * `(module, job, instance)` — the coalescing half of the driver.
@@ -4163,12 +4343,10 @@ export interface ScopeHost {
      * 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`.
+     * **Overlapping calls are safe** (#2034): each run is CLAIMED before its pass, with a
+     * lease the pass renews at every step boundary, so two calls on one scope never run
+     * one run's handler together. A run whose pass died is taken over once its lease
+     * expires. The full argument is in `job-run.ts`.
      */
     runDueJobs(tenantId: TenantId, scopeId: ScopeId, options?: {
         maxPasses?: number;
@@ -4317,6 +4495,11 @@ export interface ScopeHost {
  * 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.
  *
+ * A subscription may be narrowed `within` one entity (#1853), which only removes frames;
+ * the one exception to the per-principal check is a `within` the vertical built with
+ * `vouchedWithin`, whose subscriber is sent bare `LiveNudge` frames and nothing that
+ * names an entity.
+ *
  * **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
@@ -4351,8 +4534,58 @@ export interface LiveReadSurface<Req extends LiveUpgradeRequest = LiveUpgradeReq
         principal: PrincipalId;
         /** The upgrade request as it arrived, carried whole so the host reads its own headers. */
         request: Req;
+        /**
+         * Narrow the feed to one entity and what hangs beneath it (#1853).
+         *
+         * A frame is then delivered only if its entity IS this one or reaches it upward
+         * through live declared `parent` edges (what `ctx.link` / `ctx.relink` write) — the
+         * walk `ctx.check` makes, rooted here instead of at a grant.
+         *
+         * - **An `EntityRef` narrows and nothing else.** The principal's own per-frame
+         *   `liveTargets` check still runs; `within` is ANDed with it, so it can only take
+         *   frames away. A screen watching one conversation passes it to stop hearing the
+         *   rest of the desk.
+         * - **A `vouchedWithin(…)` value replaces the principal's check.** For a subscriber
+         *   confined by something other than a grant — a widget visitor holding a session
+         *   token the vertical has just redeemed. The vertical asserts access to the root,
+         *   the same trust it already extends in naming `principal`, and the scope's walk is
+         *   the whole filter. Such a subscriber receives `LiveNudge` frames only, which name
+         *   no event type and no entity.
+         */
+        within?: EntityRef | VouchedWithin;
     }): Promise<Res>;
 }
+/** The brand only `vouchedWithin` can apply — a literal cannot type-check as one. */
+declare const vouchedBrand: unique symbol;
+/**
+ * A `within` root the VERTICAL vouches the subscriber may watch, in place of the
+ * principal's own grants (#1853). Built only by `vouchedWithin`.
+ */
+export interface VouchedWithin {
+    readonly [vouchedBrand]: true;
+    readonly entity: EntityRef;
+    /** Why the vertical vouches — what it checked. Required, and kept on the subscription. */
+    readonly because: string;
+}
+/**
+ * Vouch that the subscriber may watch `entity` and everything beneath it, though the
+ * principal it subscribes as holds no read on it.
+ *
+ * The one way to reach the replacing mode, so every use is greppable and none is an
+ * accident: an object literal is refused by the type checker, and anything not built
+ * here is refused by the host at run time (`isVouchedWithin`). Call it only after the
+ * vertical itself has proven access — for ticket0's widget, by redeeming the session
+ * token for the session it names.
+ *
+ * What it costs the subscriber is detail: a vouched feed carries `LiveNudge` frames, so
+ * the scope never tells it which entity changed or how. Root it at an entity whose
+ * subtree holds only what the subscriber may see — the walk is the whole filter.
+ */
+export declare function vouchedWithin(entity: EntityRef, opts: {
+    because: string;
+}): VouchedWithin;
+/** Was this value built by `vouchedWithin`? A host asks before it drops the principal's check. */
+export declare function isVouchedWithin(value: unknown): value is VouchedWithin;
 /**
  * Is this request asking to be upgraded to a WebSocket?
  *
@@ -4412,6 +4645,24 @@ export interface LiveChange {
     /** When the event was emitted (ISO 8601), i.e. the emitting operation's instant. */
     readonly at: string;
 }
+/**
+ * What a vouched subscriber is told (#1853): something beneath its root changed, and
+ * nothing else.
+ *
+ * No event type and no entity, deliberately. A vouched subscriber holds no read on the
+ * entities its frames are about — the vertical vouched for the ROOT, and the scope
+ * cannot know which rows under it the vertical's own read would show. Naming the type
+ * or the id would tell it what it never asked to read. The client re-reads, as it does
+ * on a `LiveChange`.
+ */
+export interface LiveNudge {
+    readonly kind: 'nudge';
+    /** The event id, as on `LiveChange` — for ordering and de-duplication only. */
+    readonly id: string;
+    readonly at: string;
+}
+/** Any frame a live read sends. */
+export type LiveFrame = LiveChange | LiveNudge;
 /**
  * Refuse a cutoff in the future — at the HostAdmin boundary, not only at the HTTP door.
  *