@fabricorg/platform-host 8.1.2 → 8.3.0

package/dist/index.d.cts

@@ -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
@@ -241,6 +249,31 @@ export interface PendingAssetEvent {
   payload: unknown;
   eventSchemaVersion?: number;
 }
+/** JSON preparation committed with the handler before adapter execution. */
+export interface FinalizationCheckpoint {
+  protocol: "atomic-after-adapters-v1";
+  actionVersion: number;
+  steps: {
+    adapterType: string;
+    operation: string;
+  }[];
+  params: import("@fabricorg/platform").FinalizationJson;
+  handlerData: import("@fabricorg/platform").FinalizationRecord;
+  handlerEvents: (Omit<PendingAssetEvent, "payload"> & {
+    payload: import("@fabricorg/platform").FinalizationJson;
+  })[];
+  result: import("@fabricorg/platform").FinalizationRecord;
+  stateTransition?: Omit<PendingAssetEvent, "payload"> & {
+    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;
   tenantId: string;
@@ -259,12 +292,16 @@ 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;
   authorizationReconciliation?: AuthorizationReconciliationOutcome;
   /** Durable evidence when an adapter returned an ambiguous outcome requiring reconciliation. */
   adapterReconciliation?: AdapterReconciliationOutcome;
+  /** Durable normalized preparation; absent for invocations prepared by older Hosts. */
+  finalizationCheckpoint?: FinalizationCheckpoint;
   /**
    * Transition Host validated for an idempotent after_adapters action, saved
    * after handler/result/event validation inside a mutation transaction, or before
@@ -289,6 +326,8 @@ export interface ActionInvocationRecord {
   authorizationBindingId?: string;
   /** Worker claims including the first; approval acceptance sets a minimum of 1. */
   attemptCount: number;
+  /** Latest claim durably deferred in pre-effect governance; permits only the immediately next claim. */
+  deferredBeforeEffectAttempt?: number;
   leaseOwner?: string;
   leaseExpiresAt?: Date;
   /** Monotonic claim generation used to reject writes from expired workers. */
@@ -456,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;
@@ -514,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>;
@@ -645,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";
@@ -954,7 +1124,7 @@ export interface ClaimActionInvocationsInput {
  * - `claimActionInvocations` must never claim a running invocation without a
  *   lease, which is what a parked invocation is.
  */
-export type ActionInvocationPatch = Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation" | "pendingStateTransition" | "pendingCompletion" | "externalCompletion">>;
+export type ActionInvocationPatch = Partial<Pick<ActionInvocationRecord, "finalizationCheckpoint" | "deferredBeforeEffectAttempt" | "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation" | "pendingStateTransition" | "pendingCompletion" | "externalCompletion">>;
 export interface UpdateLeasedActionInvocationInput {
   id: string;
   tenantId: string;
@@ -990,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.
@@ -1131,6 +1301,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;
@@ -1144,6 +1322,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 {
@@ -1179,10 +1389,12 @@ export interface PlatformHostOptions<TDb> {
   adapterCircuitBreakers?: AdapterCircuitBreakerProvider;
   /**
    * Positive integer attempt cap for RetryableExecutionError during governance,
-   * before policy-evaluation persistence (default 5). A leased, idempotent action
-   * below the cap is left running for worker reclaim after lease expiry.
-   * Inline execution, approval resume, exhausted attempts, and non-idempotent
-   * actions fail. Policy persistence, obligation listing/resolution/persistence, state-machine checks,
+   * before policy-evaluation persistence (default 5). A leased action below the cap
+   * is left running for worker reclaim after lease expiry. Non-idempotent actions
+   * require a lease-fenced pre-effect deferral marker for the current claim; only
+   * the immediately next claim may proceed using that marker. Inline execution,
+   * approval resume, exhausted attempts, and marker-write failures are not retried.
+   * Policy persistence, obligation listing/resolution/persistence, state-machine checks,
    * the handler transaction, handlers, adapters, and finalization are excluded;
    * their failure/reconciliation/recovery semantics apply, subject to recoveryMaxAttempts.
    */
@@ -1294,6 +1506,12 @@ export interface PlatformHostOptions<TDb> {
   extractEvents?: (data: Record<string, unknown>) => PendingAssetEvent[];
   /** Handler-result fields consumed by extractEvents and omitted from the durable result. */
   eventResultFields?: readonly string[];
+  /**
+   * Optional name registry for hook-returned events from action.finalize.
+   * Checks eventType and subjectType membership; it does not validate handler events,
+   * eventSchemaVersion compatibility, or payload schemas.
+   */
+  eventContracts?: import("@fabricorg/platform").EventContractRegistry;
   redactAdapterInput?: (actionId: ActionId, adapterType: string, operation: string, input: Record<string, unknown>) => Record<string, unknown>;
   /**
    * Redact successful adapter output before row/event persistence and attestation extraction.
@@ -1330,13 +1548,18 @@ export interface PlatformHostOptions<TDb> {
   /** Vendor-neutral lifecycle and metric sink. Telemetry is best effort. */
   telemetry?: PlatformHostTelemetry;
   /**
-   * Epoch-millis deadline delivered to every adapter execution context.
-   * When omitted, no deadline is set and adapters receive no AbortSignal.
+   * Duration in milliseconds, measured before the step enters adapter retry execution.
+   * A step deadlineMs overrides this duration. When this is omitted or zero and
+   * the step has no deadlineMs, no deadline or AbortSignal is delivered.
    */
   adapterDeadlineMs?: number;
 }
 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>;
@@ -1383,9 +1606,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;
@@ -1397,6 +1621,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
@@ -1408,7 +1633,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>;
@@ -1472,6 +1700,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
@@ -1539,16 +1821,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>;
@@ -1599,6 +1885,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;
@@ -1732,6 +2078,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;
@@ -1769,7 +2137,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 {
@@ -1782,15 +2150,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. */