@substrat-run/kernel 0.139.0 → 0.140.0

package/dist/scope-host.d.ts

@@ -1,15 +1,18 @@
 import type { ModuleLog } from './module-log.js';
 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 { OnBehalfOf, ExportReadInput, ExportedBatch, ImportBatch, ImportedEvent, ImportResult, ImportState, ImportCursorMove, ImportCursorMoved, AdminAction, BecomeCapabilityInput, CapabilityExchange, CapabilityFilter, CapabilityId, CapabilityPage, MintedCapability, ListPage, ConnectLink, ConnectLinkConsume, ConnectLinkFilter, ConnectLinkKey, ConsumeConnectLinkInput, MintConnectLinkInput, Connection, ConnectionFilter, ConnectionId, ConnectionGrant, ConnectionGrantRecord, ConnectionSecret, CreateConnectionInput, OpenConnection, ProjectedConnectionGrant, ProjectedConnectionKey, AccessLogEntry, DelegatedReadRecord, OwnerTransferAudit, MemberChangeAudit, PeerBindingAudit, CopyMarkAudit, BindHostnameInput, AdminLogEntry, OpsFailureEntry, PlatformRequestDrainTotalsEntry, SweepRunEntry, SweepRunKind, SweepRunOutcome, ModelUsageEntry, ModelUsageSummary, CapabilityGrant, CreateTenantInput, Decision, Instant, DomainEvent, DomainEventInput, PlatformRequestInput, PlatformRequestId, PlatformRequest, PlatformRequestFilter, PlatformRequestStatus, PlatformRequestFailure, PlatformOutcomeEvent, EntitlementGrant, EntitlementGrantInput, EntitlementView, MeterReading, EntityRef, IdentityLink, IdentityPool, Jurisdiction, ModuleId, ModuleManifest, ScheduleSpec, SystemGrant, PeerGrantsStatusEntry, SystemGrantsStatusEntry, SystemSwitchRecord, SystemSwitch, SystemSwitchResult, PeerCoverage, PeerSwitch, PeerSwitchResult, VerticalCaller, VerticalResolution, PeerBinding, PeerInstanceResolution, 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, EntityGrantShape } from '@substrat-run/contracts';
 import type { ConnectionUseOutcome } from './connector-calls.js';
 import type { CapabilityVerbs } from './capability.js';
+import type { AuditedOperationRef, AuditedOperationRow } from './audit-outcome.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 { OnSubjectErased } from './module-erasure.js';
 import type { SystemSwitchReassert, SystemSwitchReassertOptions, SystemSwitchRecordFilter } from './system-switch-record.js';
 import type { SearchHit, SearchOptions } from './search-index.js';
+import type { GrantedEntitiesPage } from './grant-scoped-read.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';
@@ -40,6 +43,11 @@ export interface PageParams {
      * archive. Refused for an entity that declares no archive. The bin is `ctx.pageTrashed`.
      */
     readonly view?: Exclude<EntityStateName, 'trashed'>;
+    /**
+     * Also return each row's own cursor, as `rowCursors` (#2073) — asked for by `pageVisible`,
+     * which may stop partway through a page. Off by default, so an ordinary page is unchanged.
+     */
+    readonly rowCursors?: boolean;
 }
 /**
  * The scope-host contract — the adapter seam (§5.1 of the design doc).
@@ -90,6 +98,13 @@ export interface OperationContext {
     readonly tenantId: TenantId;
     readonly scopeId: ScopeId;
     readonly principal: PrincipalId;
+    /** Seal positions for one filtered list under this scope, caller and operation. */
+    pageContinuation(list: string, query: unknown): {
+        /** Read-only and copy walks cannot persist a hidden budget-stop position. */
+        writable?: boolean;
+        open(cursor: string): Promise<string>;
+        seal(position: string, hidden: boolean): Promise<string | null>;
+    };
     readonly sql: ScopedSql;
     /**
      * The operation's instant (#812) — the ONLY clock module code may read.
@@ -209,6 +224,18 @@ export interface OperationContext {
      * than returning a denial, and records none (#1642, `assertPermissionKey`).
      */
     check(permission: PermissionKey, entity?: EntityRef): Promise<Decision>;
+    /**
+     * Page entity ids reachable through this caller's live grants and declared parent edges.
+     * `all` means a node grant makes every entity of this type visible; `incomplete` means
+     * this checker cannot enumerate the path, so callers must use a checked full walk.
+     * An `ids` page is complete only after its cursor becomes null. Ids may repeat across
+     * pages on multiple parent paths: accumulate a Set, and do not treat page lengths as
+     * a count or total. The union of all pages is complete. Every id passes `ctx.check`.
+     */
+    grantedEntities(permission: PermissionKey, entityType: string, options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<GrantedEntitiesPage>;
     /**
      * Find entities of one type by what a person typed (#827) — the read a picker
      * over 40 000 customers needs and `ctx.sql` cannot express without every
@@ -265,9 +292,9 @@ export interface OperationContext {
      *
      * **This does not check permission** — nothing on `ctx` does, and a paged read
      * is not an exception. The operation's own `assertAllowed` still comes first.
-     * A read that filters per ROW after the fact (a portal walk) cannot use this at
-     * all: a page of 20 filtered down to 3 is not a page, and the honest shape is an
-     * over-fetch loop the handler owns.
+     * A read that filters per ROW after the fact (a portal walk) cannot hand this
+     * page on as it is: a page of 20 filtered down to 3 is not a page, and its cursor
+     * may be a refused row's. It walks this read with `pageVisible` instead (#2073).
      *
      * Throws `NotListable` for an entity no operation declared `paged.over` on,
      * `SortNotDeclared` for a `?sort=` outside the vocabulary, and
@@ -334,6 +361,12 @@ export interface OperationContext {
      * revives it and records that as one `entity.linked` spine event, since access resumes.
      *
      * Checks no permission: the operation does, in its own vocabulary.
+     *
+     * A parent in the TRASH (#119) is refused `not_found`: nothing new hangs off a binned
+     * entity, since it is gone from everyone's view until restored. A MISSING parent of a type that
+     * declares trash gets the identical refusal, so the two cannot be told apart. An ARCHIVED parent
+     * is allowed — archived is filed away and still readable, and whether one may still be added to
+     * is the vertical's rule, not the kernel's.
      */
     link(child: EntityRef, parent: EntityRef): void;
     /**
@@ -346,6 +379,9 @@ export interface OperationContext {
      *   move would make the child its own ancestor.
      * - `from` must be a live parent edge of `child`; `conflict` otherwise. Every other
      *   parent a multi-parent entity has is left alone.
+     * - A `to` in the TRASH is refused `not_found`, as `link` refuses one (#119) — the same refusal a
+     *   missing `to` of that type gets. `from` is not: moving a child out from under a binned
+     *   parent is how it is rescued.
      * - `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
@@ -876,9 +912,9 @@ export type MembershipChangeResult = {
  * It receives `HostAdmin`, not `ctx`: it acts with platform authority, which is
  * 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).
+ * joins. That `admin` is bound to this one event, never the host's own (#2055). A handler
+ * that writes for a person attributes from it — `admin.attributed(onBehalfOf)` — which keeps
+ * the event (#2069); a view of the HOST knows nothing of the event.
  *
  * 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
@@ -1491,6 +1527,11 @@ export interface ModuleRegistration<C extends readonly EventContract[] = []> {
      * nothing, and it reads as coverage. A bound operation with no entry is
      * allowed and means what it always meant — nothing was declared to parse.
      *
+     * **It also carries the declared surface (#119).** `operationInputsOf` records, for the frozen
+     * map it returns, every declared operation and the entity each addresses by id. The host DERIVES
+     * its trash refusal from that — nothing else is handed over — and a module with a trashable
+     * entity must pass that map as returned, with every operation it binds declared in it.
+     *
      * Typed structurally rather than as `z.ZodType` so the kernel keeps its single
      * dependency and no zod version is pinned by the scope-host contract. The
      * shape is the whole surface the host uses: throw to refuse, return the value
@@ -1567,6 +1608,15 @@ export interface ModuleRegistration<C extends readonly EventContract[] = []> {
      * contribute the same name.
      */
     predicates?: Record<string, GuardPredicate>;
+    /**
+     * This module's own step in a subject erasure (#2068), for the rows its declared
+     * `erasure: { subjects }` cannot reach — a link the row does not hold itself. Run by
+     * `shredSubject` inside the erasure's one transaction, after the declared entities and
+     * before the key is destroyed; a throw refuses the whole erasure and rolls it back.
+     * Synchronous, idempotent, and handed a `sql` that reaches the module's own tables only
+     * (`module-erasure.ts`). Requires `manifest.erasure`, whose `tables` is that reach.
+     */
+    onSubjectErased?: OnSubjectErased;
 }
 /**
  * Admin surface for enforcement input (design doc §4; control-plane.md §4.4).
@@ -1591,6 +1641,16 @@ export interface ModuleRegistration<C extends readonly EventContract[] = []> {
  * stay sync — they are code-time bookkeeping, not control-plane state.)
  */
 export interface HostAdmin {
+    /**
+     * This same admin, with every row written through it also naming `onBehalfOf` (#977, #2069),
+     * and keeping whatever this one already carries — for the `admin` an executor handler is
+     * handed, the event (`causedBy`). A handler that writes for a person attributes from that
+     * `admin`, so the cause comes along by construction and there is no option to forget.
+     *
+     * Optional so an admin that predates it still satisfies the interface; a caller that finds it
+     * absent writes through the admin it holds, unattributed to a person.
+     */
+    attributed?(onBehalfOf: OnBehalfOf): HostAdmin;
     defineRole(actor: PlatformActorId, tenantId: TenantId, role: RoleDefinition): Promise<void>;
     /**
      * Every role the directory holds, ordered by (tenantId, key).
@@ -1622,6 +1682,57 @@ export interface HostAdmin {
      */
     unassignRole(actor: PlatformActorId, assignment: RoleAssignment): Promise<void>;
     grant(actor: PlatformActorId, grant: CapabilityGrant): Promise<void>;
+    /**
+     * Give a person a vertical's declared entity-grant SHAPE on one entity (#2071): every key in
+     * `permissions`, plus the marker that makes them a holder of the shape, so a key the shape
+     * gains later reaches them at the next {@link reconcileEntityGrantShapes}. What a vertical
+     * calls where it used to `grant` its `ENTITY_GRANTS` keys one at a time. It brings back a key
+     * or marker a revoke tombstoned, as `grant` does, and leaves a live row as it is, expiry
+     * included, as `ctx.grant` does. Audited as `grantEntityShape`.
+     */
+    grantEntityShape(actor: PlatformActorId, grant: {
+        principalId: PrincipalId;
+        node: {
+            tenantId: TenantId;
+            scopeId: ScopeId;
+        };
+        entity: EntityRef;
+        permissions: readonly PermissionKey[];
+        grantedBy: PrincipalId;
+    }): Promise<void>;
+    /**
+     * Top every holder of each declared shape up to the shape as it is now (#2071): a key the
+     * shape gained is granted to each person holding the shape's marker on an entity of that
+     * type. Never a key revoked from that person there (its K-21 tombstone stays). A key merely
+     * dropped from the shape is left in place; a key the shape declares `retired` (#2082) is taken
+     * back from every holder instead, its row tombstoned, once per scope — including a direct grant
+     * of that key to the holder on the same entity, which is the same row. Until it is done on a scope, a
+     * shape that declares a `holder` is also backfilled: each person its holder relationship names
+     * as the owner of an entity (`'self'`, or the vertical's own column) is marked if they hold a
+     * key of the shape there. Never inferred from key sets, so a grant delegated on someone else's
+     * record is never marked. Without a `holder`, there is no backfill.
+     *
+     * Only shapes declared `bootstrap: true` are reconciled — those given with
+     * {@link grantEntityShape} on a person's own record. A SHARING shape, reached through
+     * `ctx.grant` (todo's `list`), is skipped whole: reconciling one would mark every person
+     * something was fully shared with as a holder.
+     *
+     * Bounded: `batch` rows of work (default 500, an integer from 1 to 5000, or `validation_failed`)
+     * per scope transaction, backfill included, repeated until a pass finishes — so it is safe
+     * on a large scope, and finishes on a re-run if interrupted. Each (person, entity) topped up is
+     * an `entity.grants-topped-up` event on the entity, and each one retired keys were taken from an
+     * `entity.grants-retired` event. Audited as `reconcileEntityGrantShapes` when it changed
+     * anything. Returns how many (person, entity) it topped up, and how many it retired keys from.
+     */
+    reconcileEntityGrantShapes(actor: PlatformActorId, node: {
+        tenantId: TenantId;
+        scopeId: ScopeId;
+    }, shapes: readonly EntityGrantShape[], opts?: {
+        batch?: number;
+    }): Promise<{
+        toppedUp: number;
+        retired: number;
+    }>;
     /** Grant to an organization (portal customers); members reach it via membership tuples. */
     /**
      * Grant a permission to a CONNECTION (#97) — how a connector is allowed to
@@ -2308,6 +2419,17 @@ export interface HostAdmin {
      * per-call path, before any staff member is involved.
      */
     resolveVerticalInstance(tenantId: TenantId, vertical: string): Promise<VerticalResolution>;
+    /** Resolve for one caller at execution time. An explicit stale binding refuses without fallback. */
+    resolvePeerInstance(tenantId: TenantId, callerScopeId: ScopeId, vertical: string): Promise<PeerInstanceResolution>;
+    /** Read the caller's explicit choice, if any. Tenant-scoped and recorded as an admin read. */
+    peerBinding(actor: PlatformActorId, tenantId: TenantId, callerScopeId: ScopeId, vertical: string): Promise<PeerBinding | undefined>;
+    /** Every explicit target choice this calling scope currently holds. */
+    peerBindings(actor: PlatformActorId, tenantId: TenantId, callerScopeId: ScopeId): Promise<PeerBinding[]>;
+    /** Bind or clear this caller's target. Both endpoints are checked in the directory at write. */
+    setPeerBinding(actor: PlatformActorId, tenantId: TenantId, callerScopeId: ScopeId, vertical: string, targetScopeId: ScopeId | null): Promise<{
+        changed: boolean;
+        previous: ScopeId | null;
+    }>;
     /**
      * Persist a tenant. Idempotent on the id — re-creating an existing tenant is a
      * no-op, not an error (control-plane.md §4.1). `status` starts `active` and
@@ -2952,8 +3074,11 @@ export interface HostAdmin {
      * the audit metadata — the rotate-side analogue of `createdBy` on create
      * (§3.5.1). Omitted ⇒ the effecting actor stands alone, the platform-driven
      * refresh path.
+     *
+     * `expiresAt`: a date replaces the connection's expiry, `null` clears it (the credential
+     * that had one was replaced by one that has none), and omitted keeps it.
      */
-    updateConnectionSecret(actor: PlatformActorId, id: ConnectionId, secret: ConnectionSecret, expiresAt?: string, opts?: {
+    updateConnectionSecret(actor: PlatformActorId, id: ConnectionId, secret: ConnectionSecret, expiresAt?: string | null, opts?: {
         rotatedBy?: string;
     }): Promise<void>;
     /**
@@ -2963,6 +3088,37 @@ export interface HostAdmin {
      * constraint ignores revoked rows.
      */
     revokeConnection(actor: PlatformActorId, id: ConnectionId): Promise<void>;
+    /**
+     * A vertical's MAILED connect link (connections.md §3.5.4) — the row that makes a consent
+     * round single-use and revocable when it lives days rather than minutes. Beside the
+     * connections because it is their front door: the round it starts ends in
+     * `createConnection` (or a rotation) for the same tenant and scope.
+     *
+     * Every verb below is keyed by (tenant, scope): a link of another scope or tenant is
+     * `undefined` / `unknown`, never a refusal that admits it exists. Expiry is judged against
+     * the host's own clock. Mint, revoke, consume and restore are each audited — metadata
+     * only, though nothing here is secret: the credential does not exist until a round is
+     * consumed, and it never touches this row.
+     */
+    mintConnectLink(actor: PlatformActorId, input: MintConnectLinkInput): Promise<ConnectLink>;
+    getConnectLink(actor: PlatformActorId, key: ConnectLinkKey): Promise<ConnectLink | undefined>;
+    /** Newest first. `outstandingOnly`: outstanding AND unexpired — the links that still open. */
+    listConnectLinks(actor: PlatformActorId, filter: ConnectLinkFilter): Promise<ConnectLink[]>;
+    /**
+     * Outstanding → revoked. Idempotent: a revoked or used link is answered as it stands and
+     * nothing is written. `undefined` when the scope holds no such link.
+     */
+    revokeConnectLink(actor: PlatformActorId, key: ConnectLinkKey): Promise<ConnectLink | undefined>;
+    /**
+     * Outstanding and unexpired → used, recording what the consent attached. Atomic: of two
+     * concurrent consumes exactly one answers `ok`. Otherwise the typed reason.
+     */
+    consumeConnectLink(actor: PlatformActorId, input: ConsumeConnectLinkInput): Promise<ConnectLinkConsume>;
+    /**
+     * Used → outstanding, the best-effort undo after the credential store failed. Only a
+     * used, unexpired link moves; `false` for anything else, a revoked link included.
+     */
+    restoreConnectLink(actor: PlatformActorId, key: ConnectLinkKey): Promise<boolean>;
     /**
      * Open the credential for one (tenant, vertical, provider[, account]) — the
      * connector's read, and the only path in the system that yields plaintext.
@@ -3263,6 +3419,27 @@ export interface HostAdmin {
      * cannot be written.
      */
     recordMemberChange(actor: PlatformActorId, entry: MemberChangeAudit): Promise<void>;
+    /** One intent or outcome of a tenant's peer-instance binding change (#1720). */
+    recordPeerBindingChange(actor: PlatformActorId, entry: PeerBindingAudit): Promise<void>;
+    /**
+     * Close one audited change whose intent has no outcome (#2064): in ONE transaction, read the
+     * intent `intentId` names, and if no outcome row exists for its operation, write an `unknown`
+     * outcome carrying `error` and an ops-failure row (`audit.<action>`, stage `outcome-unknown`)
+     * for the staff digest. Answers `true` when it wrote them, `false` when an outcome was already
+     * there, so concurrent callers settle an operation once. Throws `not_found` for an id that is
+     * not an audited-change intent. See `audit-outcome.ts` for why a later real outcome still wins.
+     */
+    settleUnrecordedOutcome(actor: PlatformActorId, input: {
+        intentId: string;
+        error: string;
+    }): Promise<boolean>;
+    /**
+     * Every admin-log row of the given audited operations (#2064), read through the operation-id
+     * index in bounded batches — one statement per `AUDITED_OPERATIONS_BATCH` ids, never a scan of
+     * the log. Only rows of the exact (action, operation, tenant, scope) asked about are returned.
+     * Reading the audit trail is itself recorded, once per call.
+     */
+    auditedOperations(actor: PlatformActorId, refs: readonly AuditedOperationRef[]): Promise<AuditedOperationRow[]>;
     /**
      * 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.
@@ -3908,10 +4085,19 @@ 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.
+     * A view of the host knows nothing of any event: an executor handler attributes from the
+     * `admin` it is handed instead (`HostAdmin.attributed`), which keeps its `causedBy`.
+     */
+    attributed?(onBehalfOf: OnBehalfOf): ScopeHost;
+    /**
+     * The same view, its rows also naming `options.causedBy` as the event they are the effect
+     * of (K-22, #2055).
+     *
+     * @deprecated since #2069: an executor handler attributes from the `admin` it is handed —
+     * `admin.attributed(onBehalfOf)` — which carries its event by construction. This form needs
+     * the event passed again, and a handler that forgets writes `causedBy` NULL with nothing
+     * failing. It stays because it shipped, and because it is how the membership executor still
+     * attributes on a host whose handed admin predates `HostAdmin.attributed`.
      */
     attributed?(onBehalfOf: OnBehalfOf, options?: {
         causedBy?: string;
@@ -4618,6 +4804,11 @@ export interface ScopeHost {
         lastError?: string | null;
         /** WHO refused (#841). Omitted by a caller too old to attribute — stored as NULL. */
         failure?: PlatformRequestFailure | null;
+        /**
+         * #2102: an outcome event written into the scope with the settle, in its transaction,
+         * and only when this settle moves the row out of `pending` (`settlePlatformRequestIn`).
+         */
+        event?: PlatformOutcomeEvent | null;
     }): Promise<void>;
     /**
      * Live reads (#938) — a subscription to this scope's change feed, or absent.
@@ -4671,10 +4862,12 @@ 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.
+ * A subscription may be narrowed `within` one entity (#1853), which only removes frames.
+ * Two built roots replace the per-row check with one about the ROOT, and their subscribers
+ * are sent bare `LiveNudge` frames that name no entity: `checkedWithin`, whose principal must
+ * pass a stated key on the root at the handshake and again on every pass that has something
+ * to send (#938), and `vouchedWithin`, which the vertical asserts once and nothing re-checks
+ * (#1853). Which to use is on `checkedWithin`.
  *
  * **Generic over the runtime's request and response, because the kernel names
  * neither.** This package has one dependency and no DOM or workers lib
@@ -4727,10 +4920,51 @@ export interface LiveReadSurface<Req extends LiveUpgradeRequest = LiveUpgradeReq
          *   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.
+         * - **A `checkedWithin(…)` value replaces the per-row check with one on the root**
+         *   (#938). The principal must pass the stated key on the root, at the handshake (a
+         *   `403` otherwise) and again on every pass that has a row beneath it to announce,
+         *   so a grant withdrawn, or a root moved out from under it, closes the socket
+         *   instead of nudging it. `LiveNudge` frames only, as for a vouched root.
+         *
+         * **Freshness (Codex #2077 r5).** A decision is reused within a pass only while the
+         * scope has had no write and nothing it holds has reached its `expires_at` since the
+         * decision. It is never reused while the scope reads its permissions from the directory.
+         * Both are checked against the clock immediately before each send. A change that lands
+         * while a check is still being evaluated can let that one frame through. Frames name
+         * nothing the subscriber could not read when checked, and the next frame, pass and poll
+         * see the change: a push is a hint at most one evaluation stale.
+         */
+        within?: EntityRef | VouchedWithin | CheckedWithin;
+        /**
+         * When the credential that proved `principal` stops being valid (ISO 8601), so the
+         * socket never outlives it (#938). Pass the session's or the bearer's expiry
+         * (`AuthSubject.expiresAt`). A handshake at or past it is refused, and the scope closes
+         * the socket (`1008`) on its first pass at or past it, before sending anything on that
+         * pass. Absent: the socket lives until either end closes it, as before.
          */
-        within?: EntityRef | VouchedWithin;
+        expiresAt?: string;
     }): Promise<Res>;
 }
+/**
+ * The close codes a live socket ends with, so a client can tell "try again" from "poll".
+ *
+ * - `1008` (policy): the subscriber may no longer watch what it subscribed to — a
+ *   `checkedWithin` gate refused, or the session that opened it ended. A reconnect meets
+ *   the handshake's own refusal.
+ * - `4429`: this principal already holds `LIVE_SOCKETS_PER_PRINCIPAL` sockets on the scope.
+ *   Not a reason to retry: the client should poll, which it does anyway, and stop asking.
+ */
+export declare const LIVE_CLOSE: {
+    readonly revoked: 1008;
+    readonly tooMany: 4429;
+};
+/**
+ * How many live sockets one principal may hold on one scope (#938). A tab holds one per
+ * feed (the desk's, and one per open conversation in ticket0's portal), and each socket is
+ * work on every post-commit pass, so a principal opening more is a cost on everybody else
+ * writing to the scope. Eight covers several tabs; past it a socket is closed `4429`.
+ */
+export declare const LIVE_SOCKETS_PER_PRINCIPAL = 8;
 /** The brand only `vouchedWithin` can apply — a literal cannot type-check as one. */
 declare const vouchedBrand: unique symbol;
 /**
@@ -4762,6 +4996,50 @@ export declare function vouchedWithin(entity: EntityRef, opts: {
 }): 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;
+/** The brand only `checkedWithin` can apply. */
+declare const checkedBrand: unique symbol;
+/**
+ * A `within` root the PRINCIPAL must be allowed `permission` on, re-checked for as long
+ * as the socket is open (#938). Built only by `checkedWithin`.
+ */
+export interface CheckedWithin {
+    readonly [checkedBrand]: true;
+    readonly entity: EntityRef;
+    readonly permission: PermissionKey;
+}
+/**
+ * Watch `entity` and everything beneath it, for as long as the subscriber may
+ * `permission` on `entity` itself.
+ *
+ * For a subscriber whose grant reaches the ROOT but not each row under it the way a
+ * `liveTargets` key would: ticket0's portal customer holds `conversation:read-own` on
+ * their contact, which reaches the conversation's public thread, while the per-row key
+ * on a message is the staff read. Rooted at an entity whose subtree is exactly what that
+ * key's read returns, the walk is the row filter and the key is the gate.
+ *
+ * The gate is asked at the handshake (`403` if it refuses) and again, once per socket,
+ * on every post-commit pass that has a row beneath the root to announce. A refusal or a
+ * check that throws closes the socket (`1008`) and sends nothing on that pass, so a
+ * revoked grant, a principal who is gone, or a root relinked out of the grant's reach
+ * ends the subscription instead of nudging it, and the client's reconnect meets the
+ * handshake's `403`. A pass with nothing beneath the root asks nothing, so an idle
+ * subscription costs no checks.
+ *
+ * **`checkedWithin` or `vouchedWithin`?** Use `checkedWithin` whenever the subscriber is
+ * a principal with a grant that reaches the root: authority leaves with the grant. Use
+ * `vouchedWithin` only when there is no such grant to ask, as for ticket0's widget
+ * visitor, who holds a session token rather than a principal of their own. A vouched
+ * socket is asserted once, so a token revoked mid-socket keeps receiving content-free
+ * nudges until the socket closes. That is known and accepted for the widget: the nudge
+ * names nothing, and every re-read it causes is checked again.
+ *
+ * Both send `LiveNudge` frames only: the subscriber may not read each row, so it is
+ * never told which one changed. Only rows of a type some module declared in
+ * `liveTargets` are announced, as for every other subscriber.
+ */
+export declare function checkedWithin(entity: EntityRef, permission: string): CheckedWithin;
+/** Was this value built by `checkedWithin`? */
+export declare function isCheckedWithin(value: unknown): value is CheckedWithin;
 /**
  * Is this request asking to be upgraded to a WebSocket?
  *
@@ -4822,12 +5100,13 @@ export interface LiveChange {
     readonly at: string;
 }
 /**
- * What a vouched subscriber is told (#1853): something beneath its root changed, and
- * nothing else.
+ * What a vouched or checked subscriber is told (#1853, #938): 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
+ * No event type and no entity, deliberately. Such a subscriber holds no read on the
+ * entities its frames are about — the vertical vouched for the ROOT, or the principal was
+ * checked on the root alone, 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`.
  */