@substrat-run/kernel 0.138.0 → 0.140.0

package/dist/scope-host.d.ts

@@ -1,12 +1,18 @@
 import type { ModuleLog } from './module-log.js';
 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 { 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, 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';
@@ -32,6 +38,16 @@ 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'>;
+    /**
+     * 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).
@@ -82,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.
@@ -201,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
@@ -257,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
@@ -326,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;
     /**
@@ -338,7 +379,17 @@ 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
+     *   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.
@@ -354,6 +405,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.
@@ -738,9 +839,7 @@ export type ConsumerHandler = (ctx: OperationContext, event: DomainEvent) => voi
 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.
+ * or taken away and, when `orgId` is given (#2047), the org joined or left in the same unit.
  */
 export type MembershipChange = {
     tenantId: TenantId;
@@ -753,6 +852,15 @@ export type MembershipChange = {
      * 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. */
@@ -761,9 +869,10 @@ export type MembershipChange = {
     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.
+ * 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;
@@ -777,6 +886,12 @@ export type MembershipChangeResult = {
 } | {
     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
@@ -795,8 +910,11 @@ export type MembershipChangeResult = {
  * 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 (#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
@@ -1409,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
@@ -1485,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).
@@ -1509,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).
@@ -1540,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
@@ -1776,7 +1969,14 @@ 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
@@ -1787,6 +1987,11 @@ export interface HostAdmin {
      * 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.
@@ -2214,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
@@ -2858,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>;
     /**
@@ -2869,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.
@@ -3058,6 +3308,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
@@ -3125,6 +3411,35 @@ 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>;
+    /** 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.
@@ -3583,6 +3898,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;
@@ -3763,8 +4084,24 @@ 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.
+     *
+     * 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;
+    }): 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
@@ -4190,6 +4527,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
@@ -4442,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.
@@ -4495,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
@@ -4551,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;
+        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.
+         */
+        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;
 /**
@@ -4586,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?
  *
@@ -4646,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`.
  */