@fabricorg/platform-host 8.4.0 → 8.6.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, StagedInvocationRequest, canonicalJson } from "@fabricorg/platform";
+import { ActionDefinition, ActionId, ActionStatus, ActorType, AdapterCircuitBreakerProvider, AdapterImplementation, AgentActionPolicyContext, AgentActionPolicyDecision, 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. */
@@ -183,7 +183,7 @@ export interface IdempotencyConflict {
   code: "IDEMPOTENCY_CONFLICT";
   idempotencyKey: string;
   existingInvocationId: string;
-  reasons: Array<"actor" | "authority_binding" | "action_version" | "parameters">;
+  reasons: Array<"actor" | "authority_binding" | "action_version" | "parameters" | "agent_proposal">;
 }
 export declare class IdempotencyConflictError extends Error {
   readonly conflict: IdempotencyConflict;
@@ -251,7 +251,7 @@ export interface PendingAssetEvent {
 }
 /** JSON preparation committed with the handler before adapter execution. */
 export interface FinalizationCheckpoint {
-  protocol: "atomic-after-adapters-v1";
+  protocol: "atomic-after-adapters-v1" | "atomic-after-adapters-v2";
   actionVersion: number;
   steps: {
     adapterType: string;
@@ -259,6 +259,8 @@ export interface FinalizationCheckpoint {
   }[];
   params: import("@fabricorg/platform").FinalizationJson;
   handlerData: import("@fabricorg/platform").FinalizationRecord;
+  /** Private adapter input preparation; retained until settlement, including reconciliation. */
+  adapterPreparation?: import("@fabricorg/platform").FinalizationRecord;
   handlerEvents: (Omit<PendingAssetEvent, "payload"> & {
     payload: import("@fabricorg/platform").FinalizationJson;
   })[];
@@ -274,7 +276,21 @@ export interface StagedInvocationOrigin {
   parentInvocationId: string;
   stageKey: string;
 }
+export interface AgentProposal {
+  confidence?: number;
+  riskTier?: AgentActionRiskTier;
+  agentSessionId?: string;
+  agentRunId?: string;
+  reason?: string;
+  evidence?: ApprovalEvidence;
+}
+export interface HostHitlEvaluatorContext extends AgentActionPolicyContext {
+  actionInvocationId: string;
+  /** The durable (post-redaction) invocation record as read before evaluation. */
+  invocation: Readonly<ActionInvocationRecord>;
+}
 export interface ActionInvocationRecord {
+  readonly agentProposal?: AgentProposal;
   id: string;
   tenantId: string;
   spaceId: string;
@@ -337,6 +353,11 @@ export interface ActionInvocationRecord {
   hitlReason?: string;
   hitlPolicyVersion?: string;
   approvalDecision?: PersistedActionApprovalDecision;
+  approvalExpiresAt?: Date;
+  approvalExpiry?: {
+    expiresAt: Date;
+    expiredAt: Date;
+  };
   mutationFootprint?: MutationFootprint;
   executionPrincipal?: ExecutionPrincipal;
   runtimeEvidence?: GovernanceRuntimeEvidence;
@@ -359,14 +380,50 @@ export interface AuthorizationReconciliationOutcome {
   provenance?: Omit<InvocationProvenance, "traceAttributes">;
   message: string;
 }
+export interface HostHitlDecision extends AgentActionPolicyDecision {
+  /** Absolute approval deadline; a valid Date, including a deadline already due. */
+  approvalExpiresAt?: Date;
+}
 export interface HitlDecisionEvidence {
+  approvalExpiresAt?: Date;
   route: AgentActionRoute;
   riskTier: AgentActionRiskTier;
   reason: string;
   policyVersion?: string;
   evaluatedAt: Date;
 }
+export type ApprovalEvidenceValue = null | boolean | number | string | ApprovalEvidenceValue[] | {
+  [key: string]: ApprovalEvidenceValue;
+};
+export type ApprovalEvidence = {
+  [key: string]: ApprovalEvidenceValue;
+};
+/** Maximum serialized UTF-8 evidence size. */
+export declare const MAX_APPROVAL_EVIDENCE_BYTES: number;
+export declare const APPROVAL_REQUESTED_EVENT: "ApprovalRequested";
+export declare const APPROVAL_DECIDED_EVENT: "ApprovalDecided";
+export declare const APPROVAL_EXPIRED_EVENT: "ApprovalExpired";
+export interface ApprovalRequestedPayload {
+  route: AgentActionRoute;
+  riskTier: AgentActionRiskTier;
+  reason: string;
+  expiresAt?: string;
+}
+export interface ApprovalDecidedPayload {
+  approved: boolean;
+  approverId: string;
+  approverType: ActorType;
+  reason?: string;
+  decidedAt: string;
+  evidencePresent: boolean;
+}
+export interface ApprovalExpiredPayload {
+  expiresAt: string;
+  expiredAt: string;
+}
 export interface ActionApprovalDecision {
+  /** Verification references only; credentials and tokens must not be included. */
+  evidence?: ApprovalEvidence;
   approved: boolean;
   approverId: string;
   approverType: ActorType;
@@ -625,6 +682,8 @@ export interface PlatformHostStore<TDb> {
  * back when `run` throws.
  */
 export interface PlatformHostMutationTransaction<TDb> {
+  /** Conditional SQL approval write on the transaction connection; lifecycle events are appended by the caller in this unit of work. */
+  beginApprovalDecision?(input: Omit<BeginApprovalDecisionInput, "lifecycleEvent">): Promise<ApprovalDecisionTransitionResult>;
   readonly db: TDb;
   /**
    * Read and lock an invocation until this transaction completes.
@@ -1059,7 +1118,34 @@ export interface OutboxRequeueAuthorizationInput {
 export interface AtomicMutationPlatformHostStore<TDb> extends PlatformHostStore<TDb> {
   transactionWithEvents<TResult>(run: (transaction: PlatformHostMutationTransaction<TDb>) => Promise<TResult>): Promise<TResult>;
 }
+export interface ApprovalLifecycleEvent {
+  event: AssetEventEnvelope;
+  metadata: OutboxEventMetadata;
+}
+/** Called within the transition transaction. Must be pure and return audit-safe data. Sequence is assigned by the store. */
+export type ApprovalLifecycleEventFactory = (invocation: ActionInvocationRecord, kind: "requested" | "decided" | "expired") => ApprovalLifecycleEvent;
+export interface ExpireDueApprovalsInput {
+  tenantId?: string;
+  spaceId?: string;
+  now?: Date;
+  limit?: number;
+}
+export interface ExpireDueApprovalsStoreInput extends ExpireDueApprovalsInput {
+  now: Date;
+  lifecycleEvent?: ApprovalLifecycleEventFactory;
+}
+export interface ParkApprovalInput {
+  approvalExpiresAt?: Date;
+  actionInvocationId: string;
+  tenantId: string;
+  spaceId: string;
+  now: Date;
+  leaseOwner?: string;
+  leaseToken?: number;
+  lifecycleEvent?: ApprovalLifecycleEventFactory;
+}
 export interface BeginApprovalDecisionInput {
+  lifecycleEvent?: ApprovalLifecycleEventFactory;
   actionInvocationId: string;
   tenantId: string;
   spaceId: string;
@@ -1074,7 +1160,37 @@ export interface ApprovalDecisionTransitionResult {
 }
 /** Optional store capability required only when agent HITL or approval resume is used. */
 export interface ApprovalPlatformHostStore<TDb> extends PlatformHostStore<TDb> {
+  /** True only when approval transitions and lifecycle outbox events share a transaction. */
+  readonly transactionalApprovalLifecycle?: boolean;
+  /**
+   * Conditionally park an executable invocation only with its matching lease owner/generation
+   * (when leased) and no prior approval decision. Persist the deadline supplied in input.
+   * Serialize with beginApprovalDecision and expireDueApprovals so each waiting row settles
+   * exactly once across concurrent decisions and sweeps; losing transitions report applied: false.
+   * When lifecycleEvent is supplied, its event/outbox writes and the state change must commit
+   * in the same atomic unit of work, or roll back together.
+   */
+  parkApproval?(input: ParkApprovalInput): Promise<ApprovalDecisionTransitionResult>;
+  /**
+   * Atomically claim and expire scoped waiting rows whose input.now >= approvalExpiresAt.
+   * Set failed with approvalExpiry and no approvalDecision. Each waiting row must settle
+   * exactly once across concurrent sweeps and beginApprovalDecision calls; return only rows
+   * this sweep settled (competing decision transitions report applied: false).
+   * When lifecycleEvent is supplied, the events/outbox writes and state changes must commit
+   * in the same atomic unit of work, or roll back together.
+   */
+  expireDueApprovals?(input: ExpireDueApprovalsStoreInput): Promise<ActionInvocationRecord[]>;
   recordHitlDecision(actionInvocationId: string, tenantId: string, spaceId: string, decision: HitlDecisionEvidence): Promise<ActionInvocationRecord>;
+  /**
+   * Atomically decide a waiting row, comparing the stored deadline with input.now inside
+   * the serialized transition. A decision at or after that deadline (input.now >=
+   * approvalExpiresAt) must never be applied: expire the row to failed with approvalExpiry
+   * and no approvalDecision instead. The caller's decision.decidedAt does not extend it.
+   * Each waiting row must settle exactly once across concurrent decisions and expiry sweeps;
+   * a losing transition reports applied: false. With lifecycleEvent, the selected decided
+   * or expired event/outbox writes and state change must commit in the same atomic unit
+   * of work, or roll back together. Required when implementing parkApproval/expireDueApprovals.
+   */
   beginApprovalDecision(input: BeginApprovalDecisionInput): Promise<ApprovalDecisionTransitionResult>;
 }
 /** Optional durable capabilities used when external-governance enrichment is configured. */
@@ -1124,7 +1240,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, "finalizationCheckpoint" | "deferredBeforeEffectAttempt" | "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation" | "pendingStateTransition" | "pendingCompletion" | "externalCompletion">>;
+export type ActionInvocationPatch = Partial<Pick<ActionInvocationRecord, "approvalExpiresAt" | "approvalExpiry" | "approvalDecision" | "leaseOwner" | "leaseExpiresAt" | "leaseToken" | "attemptCount" | "finalizationCheckpoint" | "deferredBeforeEffectAttempt" | "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation" | "pendingStateTransition" | "pendingCompletion" | "externalCompletion">>;
 export interface UpdateLeasedActionInvocationInput {
   id: string;
   tenantId: string;
@@ -1233,9 +1349,12 @@ export interface PlatformActionDispatcher {
  * `provenance` and `authorizationBinding` are also read once there and
  * replaced by Host's own copies. For any other action Host uses those three
  * as the caller's objects, read where and as often as before (README,
- * "Submission snapshot").
+ * "Submission snapshot"). `agentProposal` is read once and deeply copied before
+ * the first await for all actions, independently of `admitSubmission`.
  */
 export interface SubmitActionInput {
+  /** Read once and deeply copied before the first await, regardless of admission. */
+  agentProposal?: AgentProposal;
   actionId: ActionId;
   parameters: Record<string, unknown>;
   tenantId: string;
@@ -1322,6 +1441,8 @@ export interface PlatformActionWorkerCycleResult {
   failed: number;
   /** Present when claimed agent work was durably parked instead of failing. */
   waitingForApproval?: number;
+  /** Due approval waits settled to failed during this cycle; present when positive. */
+  expiredApprovals?: number;
   /**
    * Present only when > 0: claimed invocations whose execution threw a
    * RetryableExecutionError (counted by error type, not by where it was thrown).
@@ -1446,7 +1567,11 @@ export interface PlatformHostOptions<TDb> {
     shouldPublish?(event: AssetEventEnvelope): boolean;
   };
   /** Optional vertical-owned evaluator. When absent, agent behavior is unchanged. */
-  hitlEvaluator?: AgentActionPolicyEvaluator;
+  hitlEvaluator?: (context: HostHitlEvaluatorContext) => HostHitlDecision | Promise<HostHitlDecision>;
+  /** Positive integer milliseconds, used when the evaluator supplies no absolute deadline. */
+  approvalDefaultTtlMs?: number;
+  /** Atomic approval lifecycle events and outbox writes; defaults to false. */
+  approvalLifecycleEvents?: boolean;
   /** Durable evaluator/ruleset version recorded with every HITL decision. */
   hitlPolicyVersion?: string;
   /** Optional portable resolver; provider-specific implementations belong in integration packages. */
@@ -1499,6 +1624,8 @@ export interface PlatformHostOptions<TDb> {
    * copy, after the check admitted the submission.
    */
   redactActionParameters?: (actionId: ActionId, parameters: Record<string, unknown>) => Record<string, unknown>;
+  /** Runs beside parameter redaction; output is validated and copied before persistence. */
+  redactAgentProposal?: (actionId: ActionId, proposal: AgentProposal) => AgentProposal;
   /**
    * The bound on an action's `admitSubmission` check. An answer that
    * settles this many milliseconds or more after the check was called,
@@ -1560,7 +1687,15 @@ export interface PlatformHostOptions<TDb> {
    */
   adapterDeadlineMs?: number;
 }
+export interface ApprovalExpiryHost {
+  expireDueApprovals(input?: ExpireDueApprovalsInput): Promise<{
+    expired: string[];
+  }>;
+}
 export interface GovernedActionHost {
+  expireDueApprovals?(input?: ExpireDueApprovalsInput): Promise<{
+    expired: string[];
+  }>;
   submitAction(input: SubmitActionInput): Promise<SubmitActionResult>;
   /** Whether this Host's registry contains an action with a non-empty staged-descendant allowlist. */
   readonly hasStagedInvocationActions?: boolean;
@@ -1605,7 +1740,7 @@ export interface OutboxRequeueHost {
 }
 //#endregion
 //#region src/host.d.ts
-export declare function createGovernedActionHost<TDb>(options: PlatformHostOptions<TDb>): GovernedActionHost & OutboxRequeueHost;
+export declare function createGovernedActionHost<TDb>(options: PlatformHostOptions<TDb>): GovernedActionHost & OutboxRequeueHost & ApprovalExpiryHost;
 //#endregion
 //#region src/memory-store.d.ts
 export interface MemoryPlatformHostTransactionProvider<TDb> {
@@ -1615,6 +1750,8 @@ export interface MemoryPlatformHostTransactionProvider<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 transactionalApprovalLifecycle: boolean;
+  private readonly approvalTransactionProvider;
   readonly transactionalStagedInvocations: boolean;
   transactionWithEvents?: <TResult>(run: (transaction: PlatformHostMutationTransaction<TDb>) => Promise<TResult>) => Promise<TResult>;
   private adapterCommit;
@@ -1645,7 +1782,10 @@ export declare class MemoryPlatformHostStore<TDb> implements RecoverablePlatform
   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>;
+  private runApprovalTransaction;
+  parkApproval(input: ParkApprovalInput): Promise<ApprovalDecisionTransitionResult>;
   beginApprovalDecision(input: BeginApprovalDecisionInput): Promise<ApprovalDecisionTransitionResult>;
+  expireDueApprovals(input: ExpireDueApprovalsStoreInput): Promise<ActionInvocationRecord[]>;
   appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
   recordMutationGovernance(actionInvocationId: string, tenantId: string, spaceId: string, context: Pick<ActionInvocationRecord, "mutationFootprint" | "executionPrincipal"> & {
     footprint: NonNullable<ActionInvocationRecord["mutationFootprint"]>;
@@ -1832,6 +1972,7 @@ export declare class PostgresPlatformHostStore<TDb> implements RecoverablePlatfo
   private readonly sql;
   readonly transactionWithEvents?: AtomicMutationPlatformHostStore<TDb>["transactionWithEvents"];
   readonly transactionalOutbox: boolean;
+  readonly transactionalApprovalLifecycle: boolean;
   readonly transactionalStagedInvocations: boolean;
   constructor(db: TDb, sql: PlatformHostSqlClient, transactionProvider?: PostgresPlatformHostTransactionProvider<TDb>);
   ensureSchema(): Promise<void>;
@@ -1843,6 +1984,8 @@ export declare class PostgresPlatformHostStore<TDb> implements RecoverablePlatfo
   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>;
+  parkApproval(input: ParkApprovalInput): Promise<ApprovalDecisionTransitionResult>;
+  expireDueApprovals(input: ExpireDueApprovalsStoreInput): Promise<ActionInvocationRecord[]>;
   beginApprovalDecision(input: BeginApprovalDecisionInput): Promise<ApprovalDecisionTransitionResult>;
   appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
   recordMutationGovernance(actionInvocationId: string, tenantId: string, spaceId: string, context: {

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, StagedInvocationRequest, canonicalJson } from "@fabricorg/platform";
+import { ActionDefinition, ActionId, ActionStatus, ActorType, AdapterCircuitBreakerProvider, AdapterImplementation, AgentActionPolicyContext, AgentActionPolicyDecision, 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. */
@@ -183,7 +183,7 @@ export interface IdempotencyConflict {
   code: "IDEMPOTENCY_CONFLICT";
   idempotencyKey: string;
   existingInvocationId: string;
-  reasons: Array<"actor" | "authority_binding" | "action_version" | "parameters">;
+  reasons: Array<"actor" | "authority_binding" | "action_version" | "parameters" | "agent_proposal">;
 }
 export declare class IdempotencyConflictError extends Error {
   readonly conflict: IdempotencyConflict;
@@ -251,7 +251,7 @@ export interface PendingAssetEvent {
 }
 /** JSON preparation committed with the handler before adapter execution. */
 export interface FinalizationCheckpoint {
-  protocol: "atomic-after-adapters-v1";
+  protocol: "atomic-after-adapters-v1" | "atomic-after-adapters-v2";
   actionVersion: number;
   steps: {
     adapterType: string;
@@ -259,6 +259,8 @@ export interface FinalizationCheckpoint {
   }[];
   params: import("@fabricorg/platform").FinalizationJson;
   handlerData: import("@fabricorg/platform").FinalizationRecord;
+  /** Private adapter input preparation; retained until settlement, including reconciliation. */
+  adapterPreparation?: import("@fabricorg/platform").FinalizationRecord;
   handlerEvents: (Omit<PendingAssetEvent, "payload"> & {
     payload: import("@fabricorg/platform").FinalizationJson;
   })[];
@@ -274,7 +276,21 @@ export interface StagedInvocationOrigin {
   parentInvocationId: string;
   stageKey: string;
 }
+export interface AgentProposal {
+  confidence?: number;
+  riskTier?: AgentActionRiskTier;
+  agentSessionId?: string;
+  agentRunId?: string;
+  reason?: string;
+  evidence?: ApprovalEvidence;
+}
+export interface HostHitlEvaluatorContext extends AgentActionPolicyContext {
+  actionInvocationId: string;
+  /** The durable (post-redaction) invocation record as read before evaluation. */
+  invocation: Readonly<ActionInvocationRecord>;
+}
 export interface ActionInvocationRecord {
+  readonly agentProposal?: AgentProposal;
   id: string;
   tenantId: string;
   spaceId: string;
@@ -337,6 +353,11 @@ export interface ActionInvocationRecord {
   hitlReason?: string;
   hitlPolicyVersion?: string;
   approvalDecision?: PersistedActionApprovalDecision;
+  approvalExpiresAt?: Date;
+  approvalExpiry?: {
+    expiresAt: Date;
+    expiredAt: Date;
+  };
   mutationFootprint?: MutationFootprint;
   executionPrincipal?: ExecutionPrincipal;
   runtimeEvidence?: GovernanceRuntimeEvidence;
@@ -359,14 +380,50 @@ export interface AuthorizationReconciliationOutcome {
   provenance?: Omit<InvocationProvenance, "traceAttributes">;
   message: string;
 }
+export interface HostHitlDecision extends AgentActionPolicyDecision {
+  /** Absolute approval deadline; a valid Date, including a deadline already due. */
+  approvalExpiresAt?: Date;
+}
 export interface HitlDecisionEvidence {
+  approvalExpiresAt?: Date;
   route: AgentActionRoute;
   riskTier: AgentActionRiskTier;
   reason: string;
   policyVersion?: string;
   evaluatedAt: Date;
 }
+export type ApprovalEvidenceValue = null | boolean | number | string | ApprovalEvidenceValue[] | {
+  [key: string]: ApprovalEvidenceValue;
+};
+export type ApprovalEvidence = {
+  [key: string]: ApprovalEvidenceValue;
+};
+/** Maximum serialized UTF-8 evidence size. */
+export declare const MAX_APPROVAL_EVIDENCE_BYTES: number;
+export declare const APPROVAL_REQUESTED_EVENT: "ApprovalRequested";
+export declare const APPROVAL_DECIDED_EVENT: "ApprovalDecided";
+export declare const APPROVAL_EXPIRED_EVENT: "ApprovalExpired";
+export interface ApprovalRequestedPayload {
+  route: AgentActionRoute;
+  riskTier: AgentActionRiskTier;
+  reason: string;
+  expiresAt?: string;
+}
+export interface ApprovalDecidedPayload {
+  approved: boolean;
+  approverId: string;
+  approverType: ActorType;
+  reason?: string;
+  decidedAt: string;
+  evidencePresent: boolean;
+}
+export interface ApprovalExpiredPayload {
+  expiresAt: string;
+  expiredAt: string;
+}
 export interface ActionApprovalDecision {
+  /** Verification references only; credentials and tokens must not be included. */
+  evidence?: ApprovalEvidence;
   approved: boolean;
   approverId: string;
   approverType: ActorType;
@@ -625,6 +682,8 @@ export interface PlatformHostStore<TDb> {
  * back when `run` throws.
  */
 export interface PlatformHostMutationTransaction<TDb> {
+  /** Conditional SQL approval write on the transaction connection; lifecycle events are appended by the caller in this unit of work. */
+  beginApprovalDecision?(input: Omit<BeginApprovalDecisionInput, "lifecycleEvent">): Promise<ApprovalDecisionTransitionResult>;
   readonly db: TDb;
   /**
    * Read and lock an invocation until this transaction completes.
@@ -1059,7 +1118,34 @@ export interface OutboxRequeueAuthorizationInput {
 export interface AtomicMutationPlatformHostStore<TDb> extends PlatformHostStore<TDb> {
   transactionWithEvents<TResult>(run: (transaction: PlatformHostMutationTransaction<TDb>) => Promise<TResult>): Promise<TResult>;
 }
+export interface ApprovalLifecycleEvent {
+  event: AssetEventEnvelope;
+  metadata: OutboxEventMetadata;
+}
+/** Called within the transition transaction. Must be pure and return audit-safe data. Sequence is assigned by the store. */
+export type ApprovalLifecycleEventFactory = (invocation: ActionInvocationRecord, kind: "requested" | "decided" | "expired") => ApprovalLifecycleEvent;
+export interface ExpireDueApprovalsInput {
+  tenantId?: string;
+  spaceId?: string;
+  now?: Date;
+  limit?: number;
+}
+export interface ExpireDueApprovalsStoreInput extends ExpireDueApprovalsInput {
+  now: Date;
+  lifecycleEvent?: ApprovalLifecycleEventFactory;
+}
+export interface ParkApprovalInput {
+  approvalExpiresAt?: Date;
+  actionInvocationId: string;
+  tenantId: string;
+  spaceId: string;
+  now: Date;
+  leaseOwner?: string;
+  leaseToken?: number;
+  lifecycleEvent?: ApprovalLifecycleEventFactory;
+}
 export interface BeginApprovalDecisionInput {
+  lifecycleEvent?: ApprovalLifecycleEventFactory;
   actionInvocationId: string;
   tenantId: string;
   spaceId: string;
@@ -1074,7 +1160,37 @@ export interface ApprovalDecisionTransitionResult {
 }
 /** Optional store capability required only when agent HITL or approval resume is used. */
 export interface ApprovalPlatformHostStore<TDb> extends PlatformHostStore<TDb> {
+  /** True only when approval transitions and lifecycle outbox events share a transaction. */
+  readonly transactionalApprovalLifecycle?: boolean;
+  /**
+   * Conditionally park an executable invocation only with its matching lease owner/generation
+   * (when leased) and no prior approval decision. Persist the deadline supplied in input.
+   * Serialize with beginApprovalDecision and expireDueApprovals so each waiting row settles
+   * exactly once across concurrent decisions and sweeps; losing transitions report applied: false.
+   * When lifecycleEvent is supplied, its event/outbox writes and the state change must commit
+   * in the same atomic unit of work, or roll back together.
+   */
+  parkApproval?(input: ParkApprovalInput): Promise<ApprovalDecisionTransitionResult>;
+  /**
+   * Atomically claim and expire scoped waiting rows whose input.now >= approvalExpiresAt.
+   * Set failed with approvalExpiry and no approvalDecision. Each waiting row must settle
+   * exactly once across concurrent sweeps and beginApprovalDecision calls; return only rows
+   * this sweep settled (competing decision transitions report applied: false).
+   * When lifecycleEvent is supplied, the events/outbox writes and state changes must commit
+   * in the same atomic unit of work, or roll back together.
+   */
+  expireDueApprovals?(input: ExpireDueApprovalsStoreInput): Promise<ActionInvocationRecord[]>;
   recordHitlDecision(actionInvocationId: string, tenantId: string, spaceId: string, decision: HitlDecisionEvidence): Promise<ActionInvocationRecord>;
+  /**
+   * Atomically decide a waiting row, comparing the stored deadline with input.now inside
+   * the serialized transition. A decision at or after that deadline (input.now >=
+   * approvalExpiresAt) must never be applied: expire the row to failed with approvalExpiry
+   * and no approvalDecision instead. The caller's decision.decidedAt does not extend it.
+   * Each waiting row must settle exactly once across concurrent decisions and expiry sweeps;
+   * a losing transition reports applied: false. With lifecycleEvent, the selected decided
+   * or expired event/outbox writes and state change must commit in the same atomic unit
+   * of work, or roll back together. Required when implementing parkApproval/expireDueApprovals.
+   */
   beginApprovalDecision(input: BeginApprovalDecisionInput): Promise<ApprovalDecisionTransitionResult>;
 }
 /** Optional durable capabilities used when external-governance enrichment is configured. */
@@ -1124,7 +1240,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, "finalizationCheckpoint" | "deferredBeforeEffectAttempt" | "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation" | "pendingStateTransition" | "pendingCompletion" | "externalCompletion">>;
+export type ActionInvocationPatch = Partial<Pick<ActionInvocationRecord, "approvalExpiresAt" | "approvalExpiry" | "approvalDecision" | "leaseOwner" | "leaseExpiresAt" | "leaseToken" | "attemptCount" | "finalizationCheckpoint" | "deferredBeforeEffectAttempt" | "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation" | "pendingStateTransition" | "pendingCompletion" | "externalCompletion">>;
 export interface UpdateLeasedActionInvocationInput {
   id: string;
   tenantId: string;
@@ -1233,9 +1349,12 @@ export interface PlatformActionDispatcher {
  * `provenance` and `authorizationBinding` are also read once there and
  * replaced by Host's own copies. For any other action Host uses those three
  * as the caller's objects, read where and as often as before (README,
- * "Submission snapshot").
+ * "Submission snapshot"). `agentProposal` is read once and deeply copied before
+ * the first await for all actions, independently of `admitSubmission`.
  */
 export interface SubmitActionInput {
+  /** Read once and deeply copied before the first await, regardless of admission. */
+  agentProposal?: AgentProposal;
   actionId: ActionId;
   parameters: Record<string, unknown>;
   tenantId: string;
@@ -1322,6 +1441,8 @@ export interface PlatformActionWorkerCycleResult {
   failed: number;
   /** Present when claimed agent work was durably parked instead of failing. */
   waitingForApproval?: number;
+  /** Due approval waits settled to failed during this cycle; present when positive. */
+  expiredApprovals?: number;
   /**
    * Present only when > 0: claimed invocations whose execution threw a
    * RetryableExecutionError (counted by error type, not by where it was thrown).
@@ -1446,7 +1567,11 @@ export interface PlatformHostOptions<TDb> {
     shouldPublish?(event: AssetEventEnvelope): boolean;
   };
   /** Optional vertical-owned evaluator. When absent, agent behavior is unchanged. */
-  hitlEvaluator?: AgentActionPolicyEvaluator;
+  hitlEvaluator?: (context: HostHitlEvaluatorContext) => HostHitlDecision | Promise<HostHitlDecision>;
+  /** Positive integer milliseconds, used when the evaluator supplies no absolute deadline. */
+  approvalDefaultTtlMs?: number;
+  /** Atomic approval lifecycle events and outbox writes; defaults to false. */
+  approvalLifecycleEvents?: boolean;
   /** Durable evaluator/ruleset version recorded with every HITL decision. */
   hitlPolicyVersion?: string;
   /** Optional portable resolver; provider-specific implementations belong in integration packages. */
@@ -1499,6 +1624,8 @@ export interface PlatformHostOptions<TDb> {
    * copy, after the check admitted the submission.
    */
   redactActionParameters?: (actionId: ActionId, parameters: Record<string, unknown>) => Record<string, unknown>;
+  /** Runs beside parameter redaction; output is validated and copied before persistence. */
+  redactAgentProposal?: (actionId: ActionId, proposal: AgentProposal) => AgentProposal;
   /**
    * The bound on an action's `admitSubmission` check. An answer that
    * settles this many milliseconds or more after the check was called,
@@ -1560,7 +1687,15 @@ export interface PlatformHostOptions<TDb> {
    */
   adapterDeadlineMs?: number;
 }
+export interface ApprovalExpiryHost {
+  expireDueApprovals(input?: ExpireDueApprovalsInput): Promise<{
+    expired: string[];
+  }>;
+}
 export interface GovernedActionHost {
+  expireDueApprovals?(input?: ExpireDueApprovalsInput): Promise<{
+    expired: string[];
+  }>;
   submitAction(input: SubmitActionInput): Promise<SubmitActionResult>;
   /** Whether this Host's registry contains an action with a non-empty staged-descendant allowlist. */
   readonly hasStagedInvocationActions?: boolean;
@@ -1605,7 +1740,7 @@ export interface OutboxRequeueHost {
 }
 //#endregion
 //#region src/host.d.ts
-export declare function createGovernedActionHost<TDb>(options: PlatformHostOptions<TDb>): GovernedActionHost & OutboxRequeueHost;
+export declare function createGovernedActionHost<TDb>(options: PlatformHostOptions<TDb>): GovernedActionHost & OutboxRequeueHost & ApprovalExpiryHost;
 //#endregion
 //#region src/memory-store.d.ts
 export interface MemoryPlatformHostTransactionProvider<TDb> {
@@ -1615,6 +1750,8 @@ export interface MemoryPlatformHostTransactionProvider<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 transactionalApprovalLifecycle: boolean;
+  private readonly approvalTransactionProvider;
   readonly transactionalStagedInvocations: boolean;
   transactionWithEvents?: <TResult>(run: (transaction: PlatformHostMutationTransaction<TDb>) => Promise<TResult>) => Promise<TResult>;
   private adapterCommit;
@@ -1645,7 +1782,10 @@ export declare class MemoryPlatformHostStore<TDb> implements RecoverablePlatform
   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>;
+  private runApprovalTransaction;
+  parkApproval(input: ParkApprovalInput): Promise<ApprovalDecisionTransitionResult>;
   beginApprovalDecision(input: BeginApprovalDecisionInput): Promise<ApprovalDecisionTransitionResult>;
+  expireDueApprovals(input: ExpireDueApprovalsStoreInput): Promise<ActionInvocationRecord[]>;
   appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
   recordMutationGovernance(actionInvocationId: string, tenantId: string, spaceId: string, context: Pick<ActionInvocationRecord, "mutationFootprint" | "executionPrincipal"> & {
     footprint: NonNullable<ActionInvocationRecord["mutationFootprint"]>;
@@ -1832,6 +1972,7 @@ export declare class PostgresPlatformHostStore<TDb> implements RecoverablePlatfo
   private readonly sql;
   readonly transactionWithEvents?: AtomicMutationPlatformHostStore<TDb>["transactionWithEvents"];
   readonly transactionalOutbox: boolean;
+  readonly transactionalApprovalLifecycle: boolean;
   readonly transactionalStagedInvocations: boolean;
   constructor(db: TDb, sql: PlatformHostSqlClient, transactionProvider?: PostgresPlatformHostTransactionProvider<TDb>);
   ensureSchema(): Promise<void>;
@@ -1843,6 +1984,8 @@ export declare class PostgresPlatformHostStore<TDb> implements RecoverablePlatfo
   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>;
+  parkApproval(input: ParkApprovalInput): Promise<ApprovalDecisionTransitionResult>;
+  expireDueApprovals(input: ExpireDueApprovalsStoreInput): Promise<ActionInvocationRecord[]>;
   beginApprovalDecision(input: BeginApprovalDecisionInput): Promise<ApprovalDecisionTransitionResult>;
   appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
   recordMutationGovernance(actionInvocationId: string, tenantId: string, spaceId: string, context: {