@fabricorg/platform-host 8.2.0 → 8.4.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ActionDefinition, ActionId, ActionStatus, ActorType, AdapterCircuitBreakerProvider, AdapterImplementation, AgentActionPolicyEvaluator, AgentActionRiskTier, AgentActionRoute, AssetEventEnvelope, EvidencePacketReference, ExecutionAttestation, ExecutionPrincipal, ExternalReconciliation, FabricRuntimeServices, GovernanceRuntimeEvidence, ModuleRegistry, MutationFootprint, MutationGovernanceResolver, PolicyObligation, PolicyObligationStatus, PolicyOutcome, RuntimePolicyDefinition, canonicalJson } from "@fabricorg/platform";
+import { ActionDefinition, ActionId, ActionStatus, ActorType, AdapterCircuitBreakerProvider, AdapterImplementation, AgentActionPolicyEvaluator, AgentActionRiskTier, AgentActionRoute, AssetEventEnvelope, EvidencePacketReference, ExecutionAttestation, ExecutionPrincipal, ExternalReconciliation, FabricRuntimeServices, GovernanceRuntimeEvidence, ModuleRegistry, MutationFootprint, MutationGovernanceResolver, PolicyObligation, PolicyObligationStatus, PolicyOutcome, RuntimePolicyDefinition, StagedInvocationRequest, canonicalJson } from "@fabricorg/platform";
 import { AssemblyLockfile } from "@fabricorg/assembly";
 //#region src/observability.d.ts
 /** Version of the vendor-neutral health/readiness contract. */
@@ -218,6 +218,14 @@ export declare class ActionAdmissionError extends Error {
   /** The check's own code, present only for `refused`. */
   refusalCode?: string | undefined);
 }
+export type SubmissionRefusal = "entitlement" | "authorization";
+/** A definitive authorization-boundary refusal before an invocation is created. */
+export declare class SubmissionRefusalError extends Error {
+  readonly actionId: string;
+  readonly refusal: SubmissionRefusal;
+  readonly code: "ACTION_SUBMISSION_REFUSED";
+  constructor(actionId: string, refusal: SubmissionRefusal, message: string);
+}
 export type ExternalCompletionRefusal = "still_executing" | "not_found" | "not_awaiting" | "immediate_contract" | "reference_mismatch" | "provider_mismatch" | "invalid_completion" | "result_invalid" | "redaction_failed";
 /**
  * Why a completion was not applied, typed so a webhook handler can answer
@@ -259,6 +267,12 @@ export interface FinalizationCheckpoint {
     payload: import("@fabricorg/platform").FinalizationJson;
   };
   skipped: number[];
+  /** Handler requests retained so finalization replay stages the identical batch. */
+  stagedInvocations?: readonly import("@fabricorg/platform").StagedInvocationRequest[];
+}
+export interface StagedInvocationOrigin {
+  parentInvocationId: string;
+  stageKey: string;
 }
 export interface ActionInvocationRecord {
   id: string;
@@ -278,6 +292,8 @@ export interface ActionInvocationRecord {
   parameterDigestAlgorithm?: "fabric-canonical-json-sha256-v1";
   idempotencyActorId?: string;
   idempotencyAuthorizationBindingId?: string;
+  /** Host-only identity for a staged child; public submissions cannot set it. */
+  stagedOrigin?: StagedInvocationOrigin;
   provenance?: Omit<InvocationProvenance, "traceAttributes">;
   authorizationBinding?: AuthorizationBinding;
   executionReason?: ActionExecutionReason;
@@ -479,7 +495,7 @@ export interface AdapterInvocationRecord {
   createdAt: Date;
   updatedAt: Date;
 }
-export interface CreateActionInvocationInput extends Omit<ActionInvocationRecord, "createdAt" | "updatedAt" | "attemptCount" | "leaseOwner" | "leaseExpiresAt" | "leaseToken"> {}
+export interface CreateActionInvocationInput extends Omit<ActionInvocationRecord, "createdAt" | "updatedAt" | "attemptCount" | "leaseOwner" | "leaseExpiresAt" | "leaseToken" | "stagedOrigin"> {}
 /** Scope of an adapter checkpoint within its owning action invocation. */
 export interface AdapterInvocationScope {
   tenantId: string;
@@ -537,6 +553,8 @@ export interface PlatformHostStore<TDb> {
   transaction<TResult>(run: (db: TDb) => Promise<TResult>): Promise<TResult>;
   createActionInvocation(input: CreateActionInvocationInput): Promise<ActionInvocationRecord>;
   getActionInvocation(id: string, tenantId: string, spaceId: string): Promise<ActionInvocationRecord | undefined>;
+  /** Resolve Host-owned staged identity within one tenant and space. */
+  getActionInvocationByStagedOrigin?(tenantId: string, spaceId: string, origin: StagedInvocationOrigin): Promise<ActionInvocationRecord | undefined>;
   updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: ActionInvocationPatch): Promise<void>;
   appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
   createAdapterInvocation(record: AdapterInvocationRecord): Promise<void>;
@@ -668,6 +686,135 @@ export interface PlatformHostMutationTransaction<TDb> {
    * governance evidence cannot share the event/verdict transaction.
    */
   appendExternalReconciliation?: GovernancePlatformHostStore<TDb>["appendExternalReconciliation"];
+  /** Atomically retain an immutable staged batch with the parent mutation. */
+  stageInvocations?(records: readonly StagedInvocationRecord[]): Promise<void>;
+}
+export type StagedInvocationStatus = "pending" | "dispatched" | "rejected" | "dead_lettered" | "cancelled";
+export interface StagedInvocationRecord {
+  id: string;
+  tenantId: string;
+  spaceId: string;
+  parentInvocationId: string;
+  parentActionId: ActionId;
+  key: string;
+  actionId: ActionId;
+  expectedActionVersion: number;
+  parameters: Record<string, unknown>;
+  parameterDigest: string;
+  batchDigest: string;
+  status: StagedInvocationStatus;
+  /**
+   * The child's id, recorded by the first settlement whose attempt knew it.
+   * A settlement without an id leaves an earlier one in place. After a crash
+   * between child creation and settlement it stays absent until a later
+   * attempt finds the child by its staged origin.
+   */
+  childInvocationId?: string;
+  attemptCount: number;
+  availableAt: Date;
+  leaseOwner?: string;
+  leaseExpiresAt?: Date;
+  leaseToken: number;
+  lastError?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+export interface ClaimStagedInvocationsInput {
+  workerId: string;
+  leaseDurationMs: number;
+  limit?: number;
+  tenantId?: string;
+  spaceId?: string;
+  now?: Date;
+}
+export interface CreateStagedActionInvocationInput {
+  stageId: string;
+  workerId: string;
+  leaseToken: number;
+  now?: Date;
+  invocation: CreateActionInvocationInput & {
+    stagedOrigin: StagedInvocationOrigin;
+  };
+}
+export type CreateStagedActionInvocationResult = {
+  kind: "created" | "existing";
+  invocation: ActionInvocationRecord;
+} | {
+  kind: "lease_lost";
+};
+/** Optional durable capability for transactional staging and post-completion dispatch. */
+export interface StagedInvocationPlatformHostStore<TDb> extends PlatformHostStore<TDb> {
+  readonly transactionalStagedInvocations?: boolean;
+  getActionInvocationByStagedOrigin(tenantId: string, spaceId: string, origin: StagedInvocationOrigin): Promise<ActionInvocationRecord | undefined>;
+  /** Return the existing origin or create it only while this exact stage lease is live. */
+  createActionInvocationForStagedLease(input: CreateStagedActionInvocationInput): Promise<CreateStagedActionInvocationResult>;
+  claimStagedInvocations(input: ClaimStagedInvocationsInput): Promise<StagedInvocationRecord[]>;
+  /**
+   * The settlements below are each one compare-and-set on a pending row's
+   * lease owner and token, and release the lease. A settlement that carries
+   * `childInvocationId` records it; one without leaves a recorded id in place.
+   */
+  markStagedInvocationDispatched(input: {
+    id: string;
+    workerId: string;
+    leaseToken: number;
+    childInvocationId: string;
+    now?: Date;
+  }): Promise<boolean>;
+  markStagedInvocationRejected(input: {
+    id: string;
+    workerId: string;
+    leaseToken: number;
+    error: string;
+    now?: Date;
+  }): Promise<boolean>;
+  markStagedInvocationFailed(input: {
+    id: string;
+    workerId: string;
+    leaseToken: number;
+    error: string;
+    availableAt: Date;
+    deadLetter: boolean;
+    childInvocationId?: string;
+    now?: Date;
+  }): Promise<boolean>;
+  renewStagedInvocationLease(input: {
+    id: string;
+    workerId: string;
+    leaseToken: number;
+    leaseDurationMs: number;
+    now?: Date;
+  }): Promise<boolean>;
+  /**
+   * Replace the lease token of a pending row this worker leases with a larger
+   * one and extend the lease, in one compare-and-set on owner, token and an
+   * unexpired lease. Returns the new token, or `undefined` when the lease no
+   * longer matches. Tokens only grow, as with claims, so a later claim never
+   * hands an old token out again. Afterwards the old token fails the
+   * child-creation fence, renewal and every settlement. A store must order
+   * the rotation after any child creation the fence already admitted under
+   * the old token (PostgreSQL: the fence's `FOR SHARE` row lock makes the
+   * rotation wait). Host rotates before the lookup that decides a stage
+   * whose attempt holds no child id.
+   */
+  rotateStagedInvocationLease(input: {
+    id: string;
+    workerId: string;
+    leaseToken: number;
+    leaseDurationMs: number;
+    now?: Date;
+  }): Promise<number | undefined>;
+  cancelStagedInvocationsForFailedParents(input?: {
+    tenantId?: string;
+    spaceId?: string;
+    now?: Date;
+  }): Promise<number>;
+  listStagedInvocations(input: {
+    tenantId: string;
+    spaceId: string;
+    parentInvocationId?: string;
+    statuses?: readonly StagedInvocationStatus[];
+  }): Promise<StagedInvocationRecord[]>;
 }
 export type OutboxStatus = "pending" | "published" | "dead_letter";
 export type EventPayloadClassification = "public" | "internal" | "confidential" | "restricted";
@@ -1013,7 +1160,7 @@ export interface ActionAuthorizationInput {
   actorId: string;
   actorType: ActorType;
 }
-export type KnownActionExecutionReason = "initial" | "approval_resume" | "recovery" | "offline_replay";
+export type KnownActionExecutionReason = "initial" | "approval_resume" | "recovery" | "offline_replay" | "staged_dispatch";
 export type ActionExecutionReason = KnownActionExecutionReason | (string & {});
 /**
  * Trusted execution-boundary authorization input.
@@ -1027,6 +1174,14 @@ export interface ActionExecutionAuthorizationInput extends ActionAuthorizationIn
   invocation: Readonly<ActionInvocationRecord>;
   executionReason: ActionExecutionReason;
 }
+/** Trusted authorization input for deciding a parked approval. */
+export interface ActionApprovalAuthorizationInput extends ActionAuthorizationInput {
+  decision: ActionApprovalDecision;
+  /** The parked invocation being decided. */
+  actionInvocationId: string;
+  /** The durable (post-redaction) invocation record as read before the decision transition. */
+  invocation: Readonly<ActionInvocationRecord>;
+}
 /**
  * Input to `resolvePolicies`. Carries the invocation identity and the
  * schema-parsed durable (post-redaction) parameters so a resolver can choose
@@ -1046,9 +1201,7 @@ export interface PlatformHostAuthorization {
    */
   authorizeExecution?(input: ActionExecutionAuthorizationInput): Promise<boolean>;
   /** Optional distinct authorization boundary for human/system approval decisions. */
-  authorizeApproval?(input: ActionAuthorizationInput & {
-    decision: ActionApprovalDecision;
-  }): Promise<boolean>;
+  authorizeApproval?(input: ActionApprovalAuthorizationInput): Promise<boolean>;
   /**
    * Authorization for `requeueOutboxDeadLetter`. There is no action to fall
    * back to, so when this is absent every requeue is refused as
@@ -1154,6 +1307,14 @@ export interface PlatformActionWorkerOptions<TDb> {
    * on every cycle, and run the sweep elsewhere.
    */
   sweepOverdueCompletions?: boolean;
+  /** Dispatch staged descendants each cycle. Defaults to on when a registered action declares them. */
+  dispatchStagedInvocations?: boolean;
+  stagedInvocationBatchSize?: number;
+  stagedInvocationLeaseDurationMs?: number;
+  stagedInvocationLeaseRenewalIntervalMs?: number;
+  stagedInvocationSubmissionTimeoutMs?: number;
+  stagedInvocationMaxAttempts?: number;
+  stagedInvocationRetryDelayMs?: (attempt: number) => number;
 }
 export interface PlatformActionWorkerCycleResult {
   claimed: number;
@@ -1167,6 +1328,38 @@ export interface PlatformActionWorkerCycleResult {
    * The row stays leased and a later claim retries it; excluded from failed.
    */
   deferred?: number;
+  staged?: StagedInvocationDispatchResult;
+}
+export interface StagedInvocationDispatchInput {
+  workerId: string;
+  limit?: number;
+  leaseDurationMs?: number;
+  leaseRenewalIntervalMs?: number;
+  submissionTimeoutMs?: number;
+  maxAttempts?: number;
+  retryDelayMs?: (attempt: number) => number;
+  tenantId?: string;
+  spaceId?: string;
+  /**
+   * Receives a failed staged-origin lookup and any error that ends one claimed
+   * row's processing early (a store error from renewal, rotation or
+   * settlement). The sweep counts that row as failed and continues.
+   */
+  onError?: (error: unknown) => void;
+}
+/**
+ * Counters for one sweep. Each claimed row is counted once, as dispatched,
+ * rejected or failed. `failed` includes rows settled for retry, rows whose
+ * lease was lost before settlement, and rows whose processing threw;
+ * `deadLettered` counts the subset of `failed` settled as `dead_lettered`.
+ */
+export interface StagedInvocationDispatchResult {
+  claimed: number;
+  dispatched: number;
+  rejected: number;
+  failed: number;
+  deadLettered: number;
+  cancelled: number;
 }
 /** Origin of error text redacted before Host records or returns it. */
 export interface ErrorTextRedactionContext {
@@ -1369,6 +1562,10 @@ export interface PlatformHostOptions<TDb> {
 }
 export interface GovernedActionHost {
   submitAction(input: SubmitActionInput): Promise<SubmitActionResult>;
+  /** Whether this Host's registry contains an action with a non-empty staged-descendant allowlist. */
+  readonly hasStagedInvocationActions?: boolean;
+  /** One bounded lease-fenced sweep of completed parents' staged descendants. */
+  dispatchStagedInvocations?(input: StagedInvocationDispatchInput): Promise<StagedInvocationDispatchResult>;
   executeInvocation(actionInvocationId: string, tenantId: string, spaceId: string, options?: ExecuteInvocationOptions): Promise<ExecuteActionResult>;
   resumeApprovedInvocation(actionInvocationId: string, tenantId: string, spaceId: string, decision: ActionApprovalDecision): Promise<ExecuteActionResult>;
   recordExecutionAttestation(actionInvocationId: string, tenantId: string, spaceId: string, attestation: ExecutionAttestation): Promise<void>;
@@ -1415,9 +1612,10 @@ export interface MemoryPlatformHostTransactionProvider<TDb> {
   snapshot(db: TDb): TDb;
   restore(db: TDb, snapshot: TDb): void;
 }
-export declare class MemoryPlatformHostStore<TDb> implements RecoverablePlatformHostStore<TDb>, ApprovalPlatformHostStore<TDb>, GovernancePlatformHostStore<TDb>, OutboxPlatformHostStore<TDb>, OutboxRequeuePlatformHostStore<TDb> {
+export declare class MemoryPlatformHostStore<TDb> implements RecoverablePlatformHostStore<TDb>, ApprovalPlatformHostStore<TDb>, GovernancePlatformHostStore<TDb>, OutboxPlatformHostStore<TDb>, OutboxRequeuePlatformHostStore<TDb>, StagedInvocationPlatformHostStore<TDb> {
   readonly db: TDb;
   readonly transactionalOutbox: boolean;
+  readonly transactionalStagedInvocations: boolean;
   transactionWithEvents?: <TResult>(run: (transaction: PlatformHostMutationTransaction<TDb>) => Promise<TResult>) => Promise<TResult>;
   private adapterCommit;
   private transactionTail;
@@ -1429,6 +1627,7 @@ export declare class MemoryPlatformHostStore<TDb> implements RecoverablePlatform
   readonly executionAttestations: ExecutionAttestationRecord[];
   readonly externalReconciliations: ExternalReconciliationRecord[];
   readonly outbox: OutboxRecord[];
+  readonly stagedInvocations: StagedInvocationRecord[];
   /**
    * Requeue evidence is append-only audit history, so unlike the ledger
    * arrays above, which tests have always inspected and seeded directly, it
@@ -1440,7 +1639,10 @@ export declare class MemoryPlatformHostStore<TDb> implements RecoverablePlatform
   transaction<TResult>(run: (db: TDb) => Promise<TResult>): Promise<TResult>;
   private runTransactionWithEvents;
   createActionInvocation(input: CreateActionInvocationInput): Promise<ActionInvocationRecord>;
+  createActionInvocationForStagedLease(input: CreateStagedActionInvocationInput): Promise<CreateStagedActionInvocationResult>;
+  private applyStagedBatch;
   getActionInvocation(id: string, tenantId: string, spaceId: string): Promise<ActionInvocationRecord | undefined>;
+  getActionInvocationByStagedOrigin(tenantId: string, spaceId: string, origin: StagedInvocationOrigin): Promise<ActionInvocationRecord | undefined>;
   updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: ActionInvocationPatch): Promise<void>;
   recordHitlDecision(actionInvocationId: string, tenantId: string, spaceId: string, decision: HitlDecisionEvidence): Promise<ActionInvocationRecord>;
   beginApprovalDecision(input: BeginApprovalDecisionInput): Promise<ApprovalDecisionTransitionResult>;
@@ -1504,6 +1706,60 @@ export declare class MemoryPlatformHostStore<TDb> implements RecoverablePlatform
   claimActionInvocations(input: ClaimActionInvocationsInput): Promise<ActionInvocationRecord[]>;
   updateLeasedActionInvocation(input: UpdateLeasedActionInvocationInput): Promise<boolean>;
   renewActionInvocationLease(input: RenewActionInvocationLeaseInput): Promise<boolean>;
+  claimStagedInvocations(input: ClaimStagedInvocationsInput): Promise<StagedInvocationRecord[]>;
+  markStagedInvocationDispatched(input: {
+    id: string;
+    workerId: string;
+    leaseToken: number;
+    childInvocationId: string;
+    now?: Date;
+  }): Promise<boolean>;
+  markStagedInvocationRejected(input: {
+    id: string;
+    workerId: string;
+    leaseToken: number;
+    error: string;
+    now?: Date;
+  }): Promise<boolean>;
+  markStagedInvocationFailed(input: {
+    id: string;
+    workerId: string;
+    leaseToken: number;
+    error: string;
+    availableAt: Date;
+    deadLetter: boolean;
+    childInvocationId?: string;
+    now?: Date;
+  }): Promise<boolean>;
+  renewStagedInvocationLease(input: {
+    id: string;
+    workerId: string;
+    leaseToken: number;
+    leaseDurationMs: number;
+    now?: Date;
+  }): Promise<boolean>;
+  /** Await-free, like the fenced create above, so a create runs wholly before or after it. */
+  rotateStagedInvocationLease(input: {
+    id: string;
+    workerId: string;
+    leaseToken: number;
+    leaseDurationMs: number;
+    now?: Date;
+  }): Promise<number | undefined>;
+  cancelStagedInvocationsForFailedParents(input?: {
+    tenantId?: string;
+    spaceId?: string;
+    now?: Date;
+  }): Promise<number>;
+  listStagedInvocations(input: {
+    tenantId: string;
+    spaceId: string;
+    parentInvocationId?: string;
+    statuses?: readonly StagedInvocationStatus[];
+  }): Promise<StagedInvocationRecord[]>;
+  private leasedStagedInvocation;
+  /** Mirrors PostgreSQL: a missing child id keeps the recorded one; `lastError` is replaced. */
+  private settleStagedInvocation;
   listEvents(tenantId: string, spaceId: string): Promise<AssetEventEnvelope[]>;
 }
 //#endregion
@@ -1571,16 +1827,20 @@ export interface PostgresPlatformHostTransactionProvider<TDb> {
   run<TResult>(run: (context: PostgresPlatformHostTransactionContext<TDb>) => Promise<TResult>): Promise<TResult>;
 }
 /** Durable mutation-pipeline ledger for Databricks Lakebase or standard Postgres. */
-export declare class PostgresPlatformHostStore<TDb> implements RecoverablePlatformHostStore<TDb>, ApprovalPlatformHostStore<TDb>, GovernancePlatformHostStore<TDb>, OutboxPlatformHostStore<TDb>, OutboxRequeuePlatformHostStore<TDb> {
+export declare class PostgresPlatformHostStore<TDb> implements RecoverablePlatformHostStore<TDb>, ApprovalPlatformHostStore<TDb>, GovernancePlatformHostStore<TDb>, OutboxPlatformHostStore<TDb>, OutboxRequeuePlatformHostStore<TDb>, StagedInvocationPlatformHostStore<TDb> {
   readonly db: TDb;
   private readonly sql;
   readonly transactionWithEvents?: AtomicMutationPlatformHostStore<TDb>["transactionWithEvents"];
   readonly transactionalOutbox: boolean;
+  readonly transactionalStagedInvocations: boolean;
   constructor(db: TDb, sql: PlatformHostSqlClient, transactionProvider?: PostgresPlatformHostTransactionProvider<TDb>);
   ensureSchema(): Promise<void>;
   transaction<TResult>(run: (db: TDb) => Promise<TResult>): Promise<TResult>;
   createActionInvocation(input: CreateActionInvocationInput): Promise<ActionInvocationRecord>;
+  createActionInvocationForStagedLease(input: CreateStagedActionInvocationInput): Promise<CreateStagedActionInvocationResult>;
+  stageInvocations(records: readonly StagedInvocationRecord[]): Promise<void>;
   getActionInvocation(id: string, tenantId: string, spaceId: string): Promise<ActionInvocationRecord | undefined>;
+  getActionInvocationByStagedOrigin(tenantId: string, spaceId: string, origin: StagedInvocationOrigin): Promise<ActionInvocationRecord | undefined>;
   updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: ActionInvocationPatch): Promise<void>;
   recordHitlDecision(actionInvocationId: string, tenantId: string, spaceId: string, decision: HitlDecisionEvidence): Promise<ActionInvocationRecord>;
   beginApprovalDecision(input: BeginApprovalDecisionInput): Promise<ApprovalDecisionTransitionResult>;
@@ -1631,6 +1891,66 @@ export declare class PostgresPlatformHostStore<TDb> implements RecoverablePlatfo
     spaceId: string;
     outboxId?: string;
   }): Promise<OutboxRequeueRecord[]>;
+  claimStagedInvocations(input: ClaimStagedInvocationsInput): Promise<StagedInvocationRecord[]>;
+  markStagedInvocationDispatched(input: {
+    id: string;
+    workerId: string;
+    leaseToken: number;
+    childInvocationId: string;
+    now?: Date;
+  }): Promise<boolean>;
+  markStagedInvocationRejected(input: {
+    id: string;
+    workerId: string;
+    leaseToken: number;
+    error: string;
+    now?: Date;
+  }): Promise<boolean>;
+  markStagedInvocationFailed(input: {
+    id: string;
+    workerId: string;
+    leaseToken: number;
+    error: string;
+    availableAt: Date;
+    deadLetter: boolean;
+    childInvocationId?: string;
+    now?: Date;
+  }): Promise<boolean>;
+  renewStagedInvocationLease(input: {
+    id: string;
+    workerId: string;
+    leaseToken: number;
+    leaseDurationMs: number;
+    now?: Date;
+  }): Promise<boolean>;
+  /**
+   * The UPDATE needs a row lock that conflicts with the `FOR SHARE` lock the
+   * fenced child insert takes on this row, so it waits for an in-flight
+   * insert to commit. A fenced insert under the old token that reaches the
+   * row while this rotation is uncommitted waits for it, rechecks the new row
+   * version and inserts nothing (live tests "orders a token rotation after an
+   * in-flight fenced create ..." and "refuses a fenced create under the old
+   * token once a token rotation is ordered before it").
+   */
+  rotateStagedInvocationLease(input: {
+    id: string;
+    workerId: string;
+    leaseToken: number;
+    leaseDurationMs: number;
+    now?: Date;
+  }): Promise<number | undefined>;
+  cancelStagedInvocationsForFailedParents(input?: {
+    tenantId?: string;
+    spaceId?: string;
+    now?: Date;
+  }): Promise<number>;
+  listStagedInvocations(input: {
+    tenantId: string;
+    spaceId: string;
+    parentInvocationId?: string;
+    statuses?: readonly StagedInvocationStatus[];
+  }): Promise<StagedInvocationRecord[]>;
+  private settleStagedInvocation;
   nextEventSequence(tenantId: string, spaceId: string): Promise<number>;
   getEntityStateSource(tenantId: string, spaceId: string, entityType: string, entityId: string): Promise<{
     state: string;
@@ -1764,6 +2084,28 @@ export interface CreateDurableSagaParentLifecycleOptions<TDb> {
  */
 export declare function createDurableSagaParentLifecycle<TDb>(options: CreateDurableSagaParentLifecycleOptions<TDb>): HostSagaParentLifecycle;
 //#endregion
+//#region src/staged-invocations.d.ts
+export declare const MAX_STAGED_INVOCATIONS = 32;
+export declare const MAX_STAGED_INVOCATION_KEY_LENGTH = 128;
+export declare const MAX_STAGED_INVOCATION_BYTES: number;
+export declare const MAX_STAGED_INVOCATION_BATCH_BYTES: number;
+export declare const STAGED_INVOCATION_KEY_PATTERN: RegExp;
+interface PrepareStagedInvocationBatchInput<TDb> {
+  parent: Pick<ActionInvocationRecord, "id" | "tenantId" | "spaceId" | "actionId">;
+  parentAction: ActionDefinition<TDb>;
+  requests: readonly StagedInvocationRequest[];
+  resolveAction(actionId: ActionId): ActionDefinition<TDb> | undefined;
+  redactParameters?(actionId: ActionId, parameters: Record<string, unknown>): Record<string, unknown>;
+  /** Keys whose parameters already passed the redactor into a durable checkpoint. */
+  redactedKeys?: readonly string[];
+  now: Date;
+}
+/** Validate and normalize one immutable batch before its parent transaction commits. */
+export declare function prepareStagedInvocationBatch<TDb>(input: PrepareStagedInvocationBatchInput<TDb>): StagedInvocationRecord[];
+export declare function stagedInvocationRequestIdentity(record: StagedInvocationRecord): string;
+export declare function cloneStagedInvocationRecord(record: StagedInvocationRecord): StagedInvocationRecord;
+export declare function asStagedInvocationStore<TDb>(store: PlatformHostStore<TDb>): StagedInvocationPlatformHostStore<TDb> | undefined;
+//#endregion
 //#region src/tenant-isolation.d.ts
 export interface TenantIsolationScope {
   tenantId: string;
@@ -1801,7 +2143,7 @@ export interface TenantIsolationSubject<TDb = unknown> {
   reset?(): Promise<void> | void;
 }
 export interface TenantIsolationCheck {
-  id: "fabric.tenancy.invocation-scoped-read.v1" | "fabric.tenancy.idempotency-key-scoped.v1" | "fabric.tenancy.events-scoped.v1" | "fabric.tenancy.worker-claim-scoped.v1" | "fabric.tenancy.completion-scoped.v1" | "fabric.tenancy.projection-scoped.v1" | "fabric.tenancy.adapter-invocation-read-scoped.v1" | "fabric.tenancy.adapter-invocation-write-scoped.v1";
+  id: "fabric.tenancy.invocation-scoped-read.v1" | "fabric.tenancy.idempotency-key-scoped.v1" | "fabric.tenancy.events-scoped.v1" | "fabric.tenancy.worker-claim-scoped.v1" | "fabric.tenancy.staged-invocation-scoped.v1" | "fabric.tenancy.completion-scoped.v1" | "fabric.tenancy.projection-scoped.v1" | "fabric.tenancy.adapter-invocation-read-scoped.v1" | "fabric.tenancy.adapter-invocation-write-scoped.v1";
   run(subject: TenantIsolationSubject): Promise<string[]>;
 }
 export interface TenantIsolationResult {
@@ -1814,15 +2156,16 @@ export interface TenantIsolationResult {
   }>;
 }
 /**
- * The suite any deployment of the host must pass before it claims isolation.
+ * The suite a deployment of the host must pass before it claims isolation.
  *
- * Eight checks: an invocation cannot be read, executed, or completed under
+ * Nine checks: an invocation cannot be read, executed, or completed under
  * another tenant's scope; an idempotency key is a tenant's own, so the same
  * key in two tenants is two invocations; a tenant's event stream carries no
  * other tenant's events; a worker scoped to one tenant does not claim another's
- * work; an adapter checkpoint cannot be read or written under another tenant,
- * space, or owning invocation; and, when the subject lends a read, a viewer in
- * the other tenant sees nothing of ours.
+ * work; staged listing and claiming retain tenant and space scope; an adapter
+ * checkpoint cannot be read or written under another tenant, space, or owning
+ * invocation; and, when the subject lends a read, a viewer in the other tenant
+ * sees nothing of ours.
  */
 export declare function tenantIsolationChecks(): readonly TenantIsolationCheck[];
 /** Run every check, returning each result rather than throwing on the first. */