@substrat-run/kernel 0.137.0 → 0.139.0

package/dist/scope-host.d.ts

@@ -1,8 +1,12 @@
 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 { ScopeRoleHolder } from './scope-role-admin.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, MemberChangeAudit, 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, FindingEntry, FindingFilter, FindingRuleEntry, FindingRuleInput, FindingStatusInput, DeclaredMigration, CheckSubject } from '@substrat-run/contracts';
 import type { ConnectionUseOutcome } from './connector-calls.js';
 import type { CapabilityVerbs } from './capability.js';
+import { type EntityStateName } from '@substrat-run/contracts';
 import type { ModelUsageFilter, ModelUsageInput, ModelUsageWindow } from './model-usage.js';
+import type { FindingPruneReport } from './findings.js';
 import type { SealedSecret } from './secret-box.js';
 import type { SystemSwitchReassert, SystemSwitchReassertOptions, SystemSwitchRecordFilter } from './system-switch-record.js';
 import type { SearchHit, SearchOptions } from './search-index.js';
@@ -31,6 +35,11 @@ export interface PageParams {
     readonly filters?: Readonly<Record<string, unknown>>;
     /** Also count the filtered set — the declaration's `total`, passed through. */
     readonly total?: boolean;
+    /**
+     * Which rows of an archivable entity (#119): `active` when unset, `archived` to read the
+     * archive. Refused for an entity that declares no archive. The bin is `ctx.pageTrashed`.
+     */
+    readonly view?: Exclude<EntityStateName, 'trashed'>;
 }
 /**
  * The scope-host contract — the adapter seam (§5.1 of the design doc).
@@ -338,6 +347,13 @@ export interface OperationContext {
      * - `from` must be a live parent edge of `child`; `conflict` otherwise. Every other
      *   parent a multi-parent entity has is left alone.
      * - `from` equal to `to` is a no-op: nothing written, nothing emitted.
+     * - A `to` that is ALREADY a live parent of `child` is the way to detach one parent of a
+     *   multi-parent child (#2044): the `from` edge is tombstoned, the live `to` edge stays
+     *   live — no second row, no revive, no `entity.linked` — and `entity.relinked` is still
+     *   emitted. Like every edge `link` or `relink` leaves live, `to` is left PERMANENT: a
+     *   future expiry on it (which only a restored dump can hold) is cleared, silently. The
+     *   child keeps every other parent untouched, expiry included. The contract suite holds
+     *   both adapters to it.
      * - The old edge is tombstoned (K-21), not deleted, and one `entity.relinked` spine event
      *   records the move on the child's timeline, stamped like any event the operation emits.
      * - Transactional with the operation: a relink whose operation throws never happened.
@@ -353,6 +369,56 @@ export interface OperationContext {
      * ```
      */
     relink(child: EntityRef, from: EntityRef, to: EntityRef): void;
+    /**
+     * Archive an entity (#119): hide it from active views and keep it. Only an entity whose
+     * model declares `archive: { permission }` can be archived.
+     *
+     * - **Checks the declared archive key on the entity itself** — unlike `link`, because the
+     *   key is declared beside the entity and an operation archiving under another key is the
+     *   one mistake this exists to make impossible. A denial throws `PermissionDenied`.
+     * - Only an `active` entity: anything else is `conflict` (`reason: 'invalid_transition'`);
+     *   a missing one is `not_found`.
+     * - Stamps `_substrat_archived_at` with the operation's instant and emits one kernel-authored
+     *   `entity.archived`, with the actor and the authorization chain on its envelope.
+     * - Transactional with the operation, like every other write.
+     *
+     * Resolves to the state the entity is now in.
+     */
+    archive(entity: EntityRef): Promise<EntityStateName>;
+    /** Bring an archived entity back to active. Same key, refusals and recording as `archive`. */
+    unarchive(entity: EntityRef): Promise<EntityStateName>;
+    /**
+     * Move an entity to the trash (#119) — a reversible delete. Needs `trash: { permission }`
+     * on the entity, and checks that key on it. An `active` or an `archived` entity may be
+     * trashed; the archive survives the trip, so a `restore` returns it to the archive.
+     * Emits `entity.trashed`.
+     */
+    trash(entity: EntityRef): Promise<EntityStateName>;
+    /**
+     * Take an entity out of the trash, back to the state it was trashed from — `archived` if it
+     * was archived, `active` otherwise. Checks the trash key. Emits `entity.restored`, whose
+     * payload's `to` says which — and so does the value it resolves to.
+     */
+    restore(entity: EntityRef): Promise<EntityStateName>;
+    /**
+     * The state of one archivable/trashable entity — `active`, `archived` or `trashed` — or
+     * `null` when the row does not exist. What a get-by-id reads before deciding what to answer:
+     * the kernel filters the reads it composes, never a handler's own `SELECT`.
+     *
+     * Checks no permission, like every read on `ctx`. Throws `validation_failed` for an entity
+     * type that declares neither.
+     */
+    entityState(entity: EntityRef): EntityStateName | null;
+    /**
+     * One page of the TRASH of a declared entity (#119) — `ctx.page` over the trashed rows,
+     * with the declared trash key checked on EACH row inside the kernel, so a handler cannot
+     * forget it. A row the caller may not see in the bin is left out, which can make a page
+     * short; the walk still ends only at a null `nextCursor`. No `total`: a count over rows the
+     * caller cannot see would disclose them.
+     */
+    pageTrashed<T>(entityType: string, params: Omit<PageParams, 'view' | 'total'>): Promise<Page<T>>;
+    /** `ctx.search` over the trash, the declared trash key checked per hit (#119). */
+    searchTrashed(entityType: string, term: string, options?: Omit<SearchOptions, 'view'>): Promise<SearchHit[]>;
     /**
      * Narrow a permission the CALLER ALREADY HOLDS onto one entity — how an app
      * expresses user-initiated sharing.
@@ -593,6 +659,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 +801,62 @@ 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, when `orgId` is given (#2047), the org joined or left in the same unit.
+ */
+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;
+    /**
+     * The org joined (an add) or left (a removal) beside the role (#2047). Bounded by membership:
+     * the unit applies nothing unless `boundedBy` is a live member of it, read inside the unit
+     * (`liveOrgMembership`). A member holds everything the org confers — its grants in each
+     * scope's own store included — so that is the whole bound, and no scope is read. A join's
+     * membership expires no later than `boundedBy`'s own (`joinedMembershipExpiry`). Absent, the
+     * change is the role alone.
+     */
+    orgId?: OrgId;
+} & ({
+    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), out of the role's
+ * bound, or out of the org's (#2047: `boundedBy` is no live member of it). 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;
+} | {
+    applied: false;
+    unknownOrg: OrgId;
+} | {
+    applied: false;
+    notMember: OrgId;
+};
 /**
  * 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
@@ -740,10 +874,58 @@ export type ImportHandler = (ctx: OperationContext, event: ImportedEvent) => voi
  * consumers must.
  *
  * 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.
+ * precisely what module code must never hold. Admin writes it makes through the `admin`
+ * it is handed are stamped with the causing event's id (`causedBy`), so the split trail
+ * joins. That `admin` is bound to this one event, never the host's own: a handler that
+ * writes through the host instead — `host.attributed(…)` — passes `{ causedBy: event.id }`
+ * itself (#2055).
+ *
+ * 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, 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 type ExecutorHandler = (admin: HostAdmin, event: DomainEvent) => void | Promise<void>;
+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).
  *
@@ -1433,6 +1615,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>;
@@ -1563,6 +1749,22 @@ export interface HostAdmin {
      * `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
@@ -1590,6 +1792,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;
@@ -1652,7 +1858,34 @@ 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>;
+    /**
+     * Make `principal` a member of the org. `opts.expiresAt` (#2047) makes the membership lapse
+     * then, as any expiring tuple does; absent, it never lapses. Re-adding replaces the row,
+     * clearing a tombstone and setting the expiry anew.
+     */
+    addMember(actor: PlatformActorId, tenantId: TenantId, principal: PrincipalId, orgId: OrgId, opts?: {
+        expiresAt?: Instant;
+    }): 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.
+     *
+     * With `orgId` (#2047) the org is joined or left in the same unit, and bounded there too:
+     * `boundedBy` must be a live member of it. An add writes the membership — expiring no later
+     * than `boundedBy`'s own — with an `addMember` audit row; a removal tombstones it, with a
+     * `removeMember` row if it took anything. The role and the org apply together or not at all.
+     *
+     * 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
@@ -1664,6 +1897,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>;
     /**
@@ -2359,6 +2595,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,
@@ -2909,6 +3152,42 @@ export interface HostAdmin {
      * for an unknown fingerprint. Audited with the before/after status diff (K-33).
      */
     setIssueStatus(actor: PlatformActorId, fingerprint: string, status: IssueStatusInput): Promise<IssueEntry | undefined>;
+    /**
+     * Findings (#1748), most recently seen first: the tenant-scoped inbox. `filter.tenantId`
+     * absent is the staff fleet read; every tenant-facing caller passes it, and the HTTP surface
+     * forces it from the principal. Access-logged (K-24). No cursor, for `listIssues`'s reason.
+     */
+    listFindings(actor: PlatformActorId, filter?: FindingFilter): Promise<FindingEntry[]>;
+    /**
+     * A verdict on one of `tenantId`'s findings: acknowledge, resolve, or reopen. Keyed on the
+     * tenant as well as the id, so another tenant's finding reads as unknown (undefined).
+     * Audited with the before/after diff (K-33).
+     */
+    setFindingStatus(actor: PlatformActorId, tenantId: TenantId, id: string, status: FindingStatusInput): Promise<FindingEntry | undefined>;
+    /**
+     * Suppress with a rule: a scope (kind / operation / code / subject) and an expiry of at most
+     * `FINDING_RULE_MAX_DAYS`. The findings it covers now are suppressed at once; later
+     * occurrences it covers are counted but keep their finding suppressed. Audited, naming how
+     * many findings it suppressed.
+     */
+    createFindingRule(actor: PlatformActorId, tenantId: TenantId, input: FindingRuleInput): Promise<{
+        rule: FindingRuleEntry;
+        suppressed: number;
+    }>;
+    /** End one of `tenantId`'s rules now. Undefined for an unknown rule. Audited. */
+    revokeFindingRule(actor: PlatformActorId, tenantId: TenantId, ruleId: string): Promise<FindingRuleEntry | undefined>;
+    /**
+     * The findings retention pass (#1748) — `pruneFindings`: a quiet open or acked finding is
+     * resolved as `stale` with a `resolveStaleFinding` audit row written in the same unit, never
+     * deleted; closed findings and expired rules past the window are deleted, at most `limit` of
+     * each per call. Optional so a host that predates findings degrades the sweep's phase to `null`.
+     */
+    pruneFindings?(actor: PlatformActorId, limit: number): Promise<FindingPruneReport>;
+    /** `tenantId`'s suppress rules, newest first; `active` keeps the unexpired ones. Access-logged. */
+    listFindingRules(actor: PlatformActorId, tenantId: TenantId, filter?: {
+        active?: boolean;
+        limit?: number;
+    }): Promise<FindingRuleEntry[]>;
     /**
      * Meter 3's ledger (#1054): one line per model call a vertical made through the
      * platform's model host, drained here as a `model-usage` intent. Idempotent on the
@@ -2976,6 +3255,14 @@ export interface HostAdmin {
      * cannot be written.
      */
     recordCopyMark(actor: PlatformActorId, entry: CopyMarkAudit): Promise<void>;
+    /**
+     * Record one phase of a dashboard member change (#1150) — an invite, a role move or a removal
+     * on an installed vertical's scope — as `manageScopeMember`. The change runs in the vertical's
+     * deployment, so the control plane writes these around its call: `intent` first (and must not
+     * call if this throws), then the outcome. `recordOwnerTransfer`'s shape. Throws when the row
+     * cannot be written.
+     */
+    recordMemberChange(actor: PlatformActorId, entry: MemberChangeAudit): Promise<void>;
     /**
      * Stamp `drainedAt` on every not-yet-drained access row up to and including
      * `upToId`, marking them shipped to Tier 2. Returns how many rows moved.
@@ -3434,6 +3721,12 @@ export declare function telemetryRetentionStatements(nowMs: number, limit: numbe
     sql: string;
     params: [string, number];
 }[];
+/**
+ * One bounded retention DELETE: at most `LIMIT ?` rows whose `column` is before `?`, oldest
+ * first through the column's own index, `RETURNING 1` so the count is what was deleted. Takes
+ * `(horizon, limit)`. The statement `telemetryRetentionStatements` and `pruneFindings` share.
+ */
+export declare function boundedRetentionDelete(table: string, column: string): string;
 /** Filter for `listIssues` (#1233). Bounded by `limit` only — see the verb's doc. */
 export interface IssueFilter {
     status?: IssueStatus;
@@ -3614,8 +3907,15 @@ export interface ScopeHost {
      *
      * Optional so a host that predates it still satisfies the interface; a transport
      * that finds it absent writes unattributed rows, which is what every row was before.
+     *
+     * `options.causedBy` (#2055) is the event whose effect the view's writes are (K-22): an
+     * executor handler passes its own event's id, because the host stamps nothing ambiently —
+     * a field set around the handler's `await` would also stamp every other admin call the
+     * host served meanwhile. The `admin` a handler is handed already carries it.
      */
-    attributed?(onBehalfOf: OnBehalfOf): ScopeHost;
+    attributed?(onBehalfOf: OnBehalfOf, options?: {
+        causedBy?: string;
+    }): ScopeHost;
     /**
      * Mint a capability stub for a principal. Validates the (tenantId, scopeId)
      * pair against the directory — a mismatched pair fails closed (K-3), it never
@@ -4041,6 +4341,31 @@ export interface ScopeHost {
      * `canAssign`; an unknown role throws `not_found`.
      */
     assignScopeRoleBounded(tenantId: TenantId, scopeId: ScopeId, caller: PrincipalId, assignee: PrincipalId, roleKey: string): Promise<Coverage>;
+    /**
+     * The scope's role roster (#1150): every live scope-level role assignment, one row per
+     * (principal, role) — or one principal's, with `principal`. One scope, addressed by the caller
+     * after its own (tenant, scope) check — K-3 is asserted here too — so it is a read of this
+     * scope, never a walk across scopes.
+     */
+    listScopeRoleHolders(tenantId: TenantId, scopeId: ScopeId, principal?: PrincipalId): Promise<ScopeRoleHolder[]>;
+    /**
+     * Move `principal` from scope role `from` to `to` in ONE scope task (#1150): the caller's
+     * bound is asked over both roles (taking `from` away is bounded like granting it, §5.1
+     * consequence 1), then `from` is tombstoned and `to` granted together. Nothing is written
+     * on a refusal, so nobody is left holding both roles or neither. Throws `not_found` for a
+     * `to` this tenant does not define, and `conflict` when `principal` does not hold `from`.
+     */
+    changeScopeRoleBounded(tenantId: TenantId, scopeId: ScopeId, caller: PrincipalId, principal: PrincipalId, from: string, to: string): Promise<Coverage>;
+    /**
+     * Take every scope role `principal` holds, in ONE scope task (#1150), bounded by the
+     * caller's authority over each (§5.1 consequence 1: you cannot strip what you could not
+     * have granted). A role the tenant no longer defines confers nothing and is taken without a
+     * bound. A refusal writes nothing; `revoked` names what was taken.
+     */
+    revokeScopeRolesBounded(tenantId: TenantId, scopeId: ScopeId, caller: PrincipalId, principal: PrincipalId): Promise<{
+        coverage: Coverage;
+        revoked: string[];
+    }>;
     /**
      * 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
@@ -4140,12 +4465,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.
@@ -4187,12 +4519,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;
@@ -4341,6 +4671,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
@@ -4375,8 +4710,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?
  *
@@ -4436,6 +4821,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.
  *