@fabricorg/platform-host 7.0.0 → 7.1.1

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { ActorType, ActionId, ActionStatus, AgentActionRoute, AgentActionRiskTier, MutationFootprint, ExecutionPrincipal, GovernanceRuntimeEvidence, PolicyOutcome, AssetEventEnvelope, ExecutionAttestation, ExternalReconciliation, PolicyObligation, PolicyObligationStatus, ModuleRegistry, ActionDefinition, AdapterImplementation, FabricRuntimeServices, AgentActionPolicyEvaluator, MutationGovernanceResolver, RuntimePolicyDefinition } from '@fabricorg/platform';
+import { ActorType, ActionId, ActionStatus, EvidencePacketReference, AgentActionRoute, AgentActionRiskTier, MutationFootprint, ExecutionPrincipal, GovernanceRuntimeEvidence, PolicyOutcome, AssetEventEnvelope, ExecutionAttestation, ExternalReconciliation, PolicyObligation, PolicyObligationStatus, ModuleRegistry, ActionDefinition, AdapterImplementation, FabricRuntimeServices, AgentActionPolicyEvaluator, MutationGovernanceResolver, RuntimePolicyDefinition } from '@fabricorg/platform';
 import { AssemblyLockfile } from '@fabricorg/assembly';
 
 /** Version of the vendor-neutral health/readiness contract. */
@@ -185,6 +185,20 @@ declare class IdempotencyConflictError extends Error {
     readonly code: "IDEMPOTENCY_CONFLICT";
     constructor(conflict: IdempotencyConflict);
 }
+type ExternalCompletionRefusal = "still_executing" | "not_found" | "not_awaiting" | "immediate_contract" | "reference_mismatch" | "provider_mismatch" | "invalid_completion" | "result_invalid";
+/**
+ * Why a completion was not applied, typed so a webhook handler can answer
+ * the external system correctly: `retryable` means the invocation is still
+ * being finalized and the same callback will be accepted once it parks, so
+ * answer with something the sender retries; anything else is permanent and
+ * a retry will get the same refusal.
+ */
+declare class ExternalCompletionError extends Error {
+    readonly refusal: ExternalCompletionRefusal;
+    readonly code: "EXTERNAL_COMPLETION_REFUSED";
+    constructor(refusal: ExternalCompletionRefusal, message: string);
+    get retryable(): boolean;
+}
 interface PendingAssetEvent {
     eventType: string;
     subjectType: string;
@@ -216,6 +230,14 @@ interface ActionInvocationRecord {
     authorizationReconciliation?: AuthorizationReconciliationOutcome;
     /** Durable evidence when an adapter returned an ambiguous outcome requiring reconciliation. */
     adapterReconciliation?: AdapterReconciliationOutcome;
+    /**
+     * A handoff the host is waiting on. While present the invocation is
+     * `running` without a lease: it is not stuck, it is somebody else's turn,
+     * and the recovery worker must not re-execute it.
+     */
+    pendingCompletion?: PendingExternalCompletion;
+    /** The completion an external system delivered, kept so a repeat is recognised and a contradiction is caught. */
+    externalCompletion?: RecordedExternalCompletion;
     /** Opaque, non-secret reference used to revalidate delegated execution authority. */
     authorizationBindingId?: string;
     attemptCount: number;
@@ -290,6 +312,57 @@ interface ExternalReconciliationRecord extends ExternalReconciliation {
     tenantId: string;
     spaceId: string;
 }
+interface PendingExternalCompletion {
+    provider: string;
+    adapterType: string;
+    operation: string;
+    adapterInvocationId: string;
+    externalReference: string;
+    acceptedAt: Date;
+    /** Past this instant the host moves the invocation to reconciliation. */
+    dueAt?: Date;
+    /**
+     * Set when the invocation finished executing and parked. A handoff is
+     * recorded before the remaining steps run, so until this is set a
+     * completion has nothing settled to settle into; it is asked to retry.
+     */
+    parkedAt?: Date;
+}
+/**
+ * What an external system reports when it finishes work the host accepted.
+ *
+ * Matched to the invocation by `externalReference`, never by guesswork: a
+ * completion that names a reference the invocation is not waiting on is
+ * refused, because completing the wrong invocation is worse than dropping a
+ * callback.
+ */
+interface ExternalCompletion {
+    externalReference: string;
+    outcome: "completed" | "failed";
+    /** Merged over the handler's result on completion. */
+    result?: Record<string, unknown>;
+    error?: string;
+    provider?: string;
+    evidenceReferences?: EvidencePacketReference[];
+    observedAt: Date | string;
+}
+interface RecordedExternalCompletion extends ExternalCompletion {
+    recordedAt: Date;
+    /**
+     * Canonical digest of provider, reference, outcome, result, error, and
+     * evidence. A repeat with the same digest is the same news; a repeat with
+     * the same outcome and a different digest is changed evidence, and is a
+     * contradiction like a flipped outcome. Observation time is left out,
+     * since a redelivery legitimately carries a new one.
+     */
+    digest: string;
+}
+interface ReconcileOverdueCompletionsInput {
+    tenantId?: string;
+    spaceId?: string;
+    limit?: number;
+    now?: Date;
+}
 type AdapterInvocationStatus = "running" | "succeeded" | "failed" | "ambiguous";
 interface AdapterReconciliationOutcome {
     kind: "adapter_outcome_ambiguous";
@@ -330,7 +403,7 @@ 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>;
-    updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation">>): Promise<void>;
+    updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: ActionInvocationPatch): Promise<void>;
     appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
     createAdapterInvocation(record: AdapterInvocationRecord): Promise<void>;
     getAdapterInvocation(id: string): Promise<AdapterInvocationRecord | undefined>;
@@ -364,7 +437,7 @@ interface PlatformHostMutationTransaction<TDb> {
     nextEventSequence(tenantId: string, spaceId: string): Promise<number>;
     listEvents(tenantId: string, spaceId: string): Promise<AssetEventEnvelope[]>;
     getEntityState?(tenantId: string, spaceId: string, entityType: string, entityId: string): Promise<string | undefined>;
-    updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation">>): Promise<void>;
+    updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: ActionInvocationPatch): Promise<void>;
     updateLeasedActionInvocation?(input: UpdateLeasedActionInvocationInput): Promise<boolean>;
 }
 type OutboxStatus = "pending" | "published" | "dead_letter";
@@ -496,6 +569,12 @@ interface ListActionInvocationsInput {
     spaceId?: string;
     statuses?: readonly ActionStatus[];
     updatedBefore?: Date;
+    /** Only invocations holding a pending external completion. */
+    awaitingCompletion?: boolean;
+    /** Only pending completions due at or before this instant. Implies `awaitingCompletion`. */
+    completionDueBefore?: Date;
+    /** Only invocations no worker holds a lease on. */
+    unleased?: boolean;
     limit?: number;
 }
 interface ClaimActionInvocationsInput {
@@ -506,7 +585,20 @@ interface ClaimActionInvocationsInput {
     spaceId?: string;
     now?: Date;
 }
-type ActionInvocationPatch = Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation">>;
+/**
+ * What the host writes back to an invocation.
+ *
+ * Store obligations for `pendingCompletion`, which a custom store must honour
+ * or the recovery worker will re-run an external handoff:
+ * - a patch that sets `pendingCompletion` together with `status: "running"`
+ *   parks the invocation and must clear its lease;
+ * - a patch that sets `pendingCompletion` without a status records the handoff
+ *   and must leave the lease alone;
+ * - a patch with `pendingCompletion: undefined` clears it;
+ * - `claimActionInvocations` must never claim a running invocation without a
+ *   lease, which is what a parked invocation is.
+ */
+type ActionInvocationPatch = Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation" | "pendingCompletion" | "externalCompletion">>;
 interface UpdateLeasedActionInvocationInput {
     id: string;
     tenantId: string;
@@ -609,6 +701,8 @@ interface SubmitActionResult {
     error?: string;
     reconciliation?: AuthorizationReconciliationOutcome;
     adapterReconciliation?: AdapterReconciliationOutcome;
+    /** Present while the invocation waits for an external system to complete it. */
+    pendingCompletion?: PendingExternalCompletion;
     /** Mirrors the action's declared consistency so a caller knows whether the result is settled. */
     consistency?: "authoritative-now" | "provisional-until-reconciled";
     hitlRoute?: AgentActionRoute;
@@ -621,6 +715,8 @@ interface ExecuteActionResult {
     error?: string;
     reconciliation?: AuthorizationReconciliationOutcome;
     adapterReconciliation?: AdapterReconciliationOutcome;
+    /** Present while the invocation waits for an external system to complete it. */
+    pendingCompletion?: PendingExternalCompletion;
     /** Mirrors the action's declared consistency so a caller knows whether the result is settled. */
     consistency?: "authoritative-now" | "provisional-until-reconciled";
     hitlRoute?: AgentActionRoute;
@@ -645,6 +741,12 @@ interface PlatformActionWorkerOptions<TDb> {
     signal?: AbortSignal;
     onError?: (error: unknown, invocation?: ActionInvocationRecord) => void;
     telemetry?: PlatformHostTelemetry;
+    /**
+     * Sweep overdue external handoffs each cycle. Defaults to on. Turn it off
+     * for a store without the governance seam, where the sweep would refuse
+     * on every cycle, and run the sweep elsewhere.
+     */
+    sweepOverdueCompletions?: boolean;
 }
 interface PlatformActionWorkerCycleResult {
     claimed: number;
@@ -746,6 +848,20 @@ interface GovernedActionHost {
     resumeApprovedInvocation(actionInvocationId: string, tenantId: string, spaceId: string, decision: ActionApprovalDecision): Promise<ExecuteActionResult>;
     recordExecutionAttestation(actionInvocationId: string, tenantId: string, spaceId: string, attestation: ExecutionAttestation): Promise<void>;
     recordExternalReconciliation(actionInvocationId: string, tenantId: string, spaceId: string, reconciliation: ExternalReconciliation): Promise<void>;
+    /**
+     * Complete an invocation an adapter handed off, by the reference the
+     * external system was given. Idempotent for a repeated identical
+     * completion; a contradictory one moves the invocation to reconciliation.
+     */
+    completeExternalInvocation(actionInvocationId: string, tenantId: string, spaceId: string, completion: ExternalCompletion): Promise<ExecuteActionResult>;
+    /**
+     * Move handoffs past their deadline to `reconciliation_required`, so a
+     * callback that never comes is a finding and not a silent wait. The
+     * pending handoff is kept, so a late completion can still land.
+     */
+    reconcileOverdueCompletions(input?: ReconcileOverdueCompletionsInput): Promise<{
+        overdue: string[];
+    }>;
 }
 
 declare function createGovernedActionHost<TDb>(options: PlatformHostOptions<TDb>): GovernedActionHost;
@@ -772,7 +888,7 @@ declare class MemoryPlatformHostStore<TDb> implements RecoverablePlatformHostSto
     private runTransactionWithEvents;
     createActionInvocation(input: CreateActionInvocationInput): Promise<ActionInvocationRecord>;
     getActionInvocation(id: string, tenantId: string, spaceId: string): Promise<ActionInvocationRecord | undefined>;
-    updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation">>): Promise<void>;
+    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>;
     appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
@@ -884,7 +1000,7 @@ declare class PostgresPlatformHostStore<TDb> implements RecoverablePlatformHostS
     transaction<TResult>(run: (db: TDb) => Promise<TResult>): Promise<TResult>;
     createActionInvocation(input: CreateActionInvocationInput): Promise<ActionInvocationRecord>;
     getActionInvocation(id: string, tenantId: string, spaceId: string): Promise<ActionInvocationRecord | undefined>;
-    updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation">>): Promise<void>;
+    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>;
     appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
@@ -1051,4 +1167,4 @@ interface CreateDurableSagaParentLifecycleOptions<TDb> {
  */
 declare function createDurableSagaParentLifecycle<TDb>(options: CreateDurableSagaParentLifecycleOptions<TDb>): HostSagaParentLifecycle;
 
-export { type ActionApprovalDecision, type ActionAuthorizationInput, type ActionExecutionAuthorizationInput, type ActionExecutionReason, type ActionInvocationPatch, type ActionInvocationRecord, type AdapterInvocationRecord, type AdapterInvocationStatus, type AdapterReconciliationOutcome, type ApprovalDecisionTransitionResult, type ApprovalPlatformHostStore, type AtomicMutationPlatformHostStore, type AuthorizationBinding, type AuthorizationGoverningMoment, type AuthorizationReconciliationOutcome, type BeginApprovalDecisionInput, type ClaimActionInvocationsInput, type ClaimOutboxInput, type CreateActionInvocationInput, type CreateDurableSagaParentLifecycleOptions, type DispatchActionInput, type DispatchActionResult, type EnterpriseEventEnvelope, type EnterpriseEventPublisher, type EventPayloadClassification, type ExecuteActionResult, type ExecuteInvocationOptions, type ExecutionAttestationRecord, type ExternalReconciliationRecord, type GovernancePlatformHostStore, type GovernedActionHost, type HitlDecisionEvidence, type HostCompensationRecord, type HostSagaParentApprovalInput, type HostSagaParentCancellationInput, type HostSagaParentCompletionInput, type HostSagaParentFailureInput, type HostSagaParentLifecycle, type HostSagaParentProgressInput, type HostSagaParentProgressRecord, type IdempotencyConflict, IdempotencyConflictError, type InvocationProvenance, type InvocationSource, type KnownActionExecutionReason, type ListActionInvocationsInput, MemoryPlatformHostStore, type MemoryPlatformHostTransactionProvider, type NamespacedAttributes, type OutboxEventMetadata, type OutboxPlatformHostStore, type OutboxRecord, type OutboxRelayOptions, type OutboxRelayResult, type OutboxStatus, PARAMETER_DIGEST_ALGORITHM, PLATFORM_HOST_CONTRACT_VERSION, PLATFORM_HOST_HEALTH_CONTRACT_VERSION, PLATFORM_HOST_METRIC_NAMES, type PendingAssetEvent, type PersistedActionApprovalDecision, type PlatformActionDispatcher, type PlatformActionWorkerCycleResult, type PlatformActionWorkerOptions, type PlatformHostAuthorization, type PlatformHostHealthCounts, type PlatformHostHealthOptions, type PlatformHostHealthQuery, type PlatformHostHealthSnapshot, type PlatformHostHealthStatus, type PlatformHostHealthStore, type PlatformHostLifecycleTelemetry, type PlatformHostMetricName, type PlatformHostMetricTelemetry, type PlatformHostMetricType, type PlatformHostMutationTransaction, type PlatformHostOptions, type PlatformHostReadinessReason, type PlatformHostSqlClient, type PlatformHostSqlResult, type PlatformHostStore, type PlatformHostTelemetry, type PlatformHostTelemetryAttribute, type PlatformHostTelemetryEventName, type PlatformHostTelemetryHook, type PlatformHostTelemetryInput, type PlatformHostTelemetryRecord, type PlatformHostWorkerHealthInput, type PolicyEvaluationRecord, type PolicyObligationRecord, type PostgresMigration, PostgresPlatformHostStore, type PostgresPlatformHostTransactionContext, type PostgresPlatformHostTransactionProvider, type RecoverablePlatformHostStore, type RenewActionInvocationLeaseInput, type SubmitActionInput, type SubmitActionResult, type UpdateLeasedActionInvocationInput, applyPostgresMigrations, canonicalJson, cloneOutboxRecord, createDurableSagaParentLifecycle, createGovernedActionHost, createStoreBackedActionDispatcher, digestParameters, emitPlatformHostTelemetry, getPlatformHostHealthSnapshot, runOutboxRelayCycle, runPlatformActionWorker, runPlatformActionWorkerCycle, toEnterpriseEventEnvelope };
+export { type ActionApprovalDecision, type ActionAuthorizationInput, type ActionExecutionAuthorizationInput, type ActionExecutionReason, type ActionInvocationPatch, type ActionInvocationRecord, type AdapterInvocationRecord, type AdapterInvocationStatus, type AdapterReconciliationOutcome, type ApprovalDecisionTransitionResult, type ApprovalPlatformHostStore, type AtomicMutationPlatformHostStore, type AuthorizationBinding, type AuthorizationGoverningMoment, type AuthorizationReconciliationOutcome, type BeginApprovalDecisionInput, type ClaimActionInvocationsInput, type ClaimOutboxInput, type CreateActionInvocationInput, type CreateDurableSagaParentLifecycleOptions, type DispatchActionInput, type DispatchActionResult, type EnterpriseEventEnvelope, type EnterpriseEventPublisher, type EventPayloadClassification, type ExecuteActionResult, type ExecuteInvocationOptions, type ExecutionAttestationRecord, type ExternalCompletion, ExternalCompletionError, type ExternalCompletionRefusal, type ExternalReconciliationRecord, type GovernancePlatformHostStore, type GovernedActionHost, type HitlDecisionEvidence, type HostCompensationRecord, type HostSagaParentApprovalInput, type HostSagaParentCancellationInput, type HostSagaParentCompletionInput, type HostSagaParentFailureInput, type HostSagaParentLifecycle, type HostSagaParentProgressInput, type HostSagaParentProgressRecord, type IdempotencyConflict, IdempotencyConflictError, type InvocationProvenance, type InvocationSource, type KnownActionExecutionReason, type ListActionInvocationsInput, MemoryPlatformHostStore, type MemoryPlatformHostTransactionProvider, type NamespacedAttributes, type OutboxEventMetadata, type OutboxPlatformHostStore, type OutboxRecord, type OutboxRelayOptions, type OutboxRelayResult, type OutboxStatus, PARAMETER_DIGEST_ALGORITHM, PLATFORM_HOST_CONTRACT_VERSION, PLATFORM_HOST_HEALTH_CONTRACT_VERSION, PLATFORM_HOST_METRIC_NAMES, type PendingAssetEvent, type PendingExternalCompletion, type PersistedActionApprovalDecision, type PlatformActionDispatcher, type PlatformActionWorkerCycleResult, type PlatformActionWorkerOptions, type PlatformHostAuthorization, type PlatformHostHealthCounts, type PlatformHostHealthOptions, type PlatformHostHealthQuery, type PlatformHostHealthSnapshot, type PlatformHostHealthStatus, type PlatformHostHealthStore, type PlatformHostLifecycleTelemetry, type PlatformHostMetricName, type PlatformHostMetricTelemetry, type PlatformHostMetricType, type PlatformHostMutationTransaction, type PlatformHostOptions, type PlatformHostReadinessReason, type PlatformHostSqlClient, type PlatformHostSqlResult, type PlatformHostStore, type PlatformHostTelemetry, type PlatformHostTelemetryAttribute, type PlatformHostTelemetryEventName, type PlatformHostTelemetryHook, type PlatformHostTelemetryInput, type PlatformHostTelemetryRecord, type PlatformHostWorkerHealthInput, type PolicyEvaluationRecord, type PolicyObligationRecord, type PostgresMigration, PostgresPlatformHostStore, type PostgresPlatformHostTransactionContext, type PostgresPlatformHostTransactionProvider, type ReconcileOverdueCompletionsInput, type RecordedExternalCompletion, type RecoverablePlatformHostStore, type RenewActionInvocationLeaseInput, type SubmitActionInput, type SubmitActionResult, type UpdateLeasedActionInvocationInput, applyPostgresMigrations, canonicalJson, cloneOutboxRecord, createDurableSagaParentLifecycle, createGovernedActionHost, createStoreBackedActionDispatcher, digestParameters, emitPlatformHostTelemetry, getPlatformHostHealthSnapshot, runOutboxRelayCycle, runPlatformActionWorker, runPlatformActionWorkerCycle, toEnterpriseEventEnvelope };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ActorType, ActionId, ActionStatus, AgentActionRoute, AgentActionRiskTier, MutationFootprint, ExecutionPrincipal, GovernanceRuntimeEvidence, PolicyOutcome, AssetEventEnvelope, ExecutionAttestation, ExternalReconciliation, PolicyObligation, PolicyObligationStatus, ModuleRegistry, ActionDefinition, AdapterImplementation, FabricRuntimeServices, AgentActionPolicyEvaluator, MutationGovernanceResolver, RuntimePolicyDefinition } from '@fabricorg/platform';
+import { ActorType, ActionId, ActionStatus, EvidencePacketReference, AgentActionRoute, AgentActionRiskTier, MutationFootprint, ExecutionPrincipal, GovernanceRuntimeEvidence, PolicyOutcome, AssetEventEnvelope, ExecutionAttestation, ExternalReconciliation, PolicyObligation, PolicyObligationStatus, ModuleRegistry, ActionDefinition, AdapterImplementation, FabricRuntimeServices, AgentActionPolicyEvaluator, MutationGovernanceResolver, RuntimePolicyDefinition } from '@fabricorg/platform';
 import { AssemblyLockfile } from '@fabricorg/assembly';
 
 /** Version of the vendor-neutral health/readiness contract. */
@@ -185,6 +185,20 @@ declare class IdempotencyConflictError extends Error {
     readonly code: "IDEMPOTENCY_CONFLICT";
     constructor(conflict: IdempotencyConflict);
 }
+type ExternalCompletionRefusal = "still_executing" | "not_found" | "not_awaiting" | "immediate_contract" | "reference_mismatch" | "provider_mismatch" | "invalid_completion" | "result_invalid";
+/**
+ * Why a completion was not applied, typed so a webhook handler can answer
+ * the external system correctly: `retryable` means the invocation is still
+ * being finalized and the same callback will be accepted once it parks, so
+ * answer with something the sender retries; anything else is permanent and
+ * a retry will get the same refusal.
+ */
+declare class ExternalCompletionError extends Error {
+    readonly refusal: ExternalCompletionRefusal;
+    readonly code: "EXTERNAL_COMPLETION_REFUSED";
+    constructor(refusal: ExternalCompletionRefusal, message: string);
+    get retryable(): boolean;
+}
 interface PendingAssetEvent {
     eventType: string;
     subjectType: string;
@@ -216,6 +230,14 @@ interface ActionInvocationRecord {
     authorizationReconciliation?: AuthorizationReconciliationOutcome;
     /** Durable evidence when an adapter returned an ambiguous outcome requiring reconciliation. */
     adapterReconciliation?: AdapterReconciliationOutcome;
+    /**
+     * A handoff the host is waiting on. While present the invocation is
+     * `running` without a lease: it is not stuck, it is somebody else's turn,
+     * and the recovery worker must not re-execute it.
+     */
+    pendingCompletion?: PendingExternalCompletion;
+    /** The completion an external system delivered, kept so a repeat is recognised and a contradiction is caught. */
+    externalCompletion?: RecordedExternalCompletion;
     /** Opaque, non-secret reference used to revalidate delegated execution authority. */
     authorizationBindingId?: string;
     attemptCount: number;
@@ -290,6 +312,57 @@ interface ExternalReconciliationRecord extends ExternalReconciliation {
     tenantId: string;
     spaceId: string;
 }
+interface PendingExternalCompletion {
+    provider: string;
+    adapterType: string;
+    operation: string;
+    adapterInvocationId: string;
+    externalReference: string;
+    acceptedAt: Date;
+    /** Past this instant the host moves the invocation to reconciliation. */
+    dueAt?: Date;
+    /**
+     * Set when the invocation finished executing and parked. A handoff is
+     * recorded before the remaining steps run, so until this is set a
+     * completion has nothing settled to settle into; it is asked to retry.
+     */
+    parkedAt?: Date;
+}
+/**
+ * What an external system reports when it finishes work the host accepted.
+ *
+ * Matched to the invocation by `externalReference`, never by guesswork: a
+ * completion that names a reference the invocation is not waiting on is
+ * refused, because completing the wrong invocation is worse than dropping a
+ * callback.
+ */
+interface ExternalCompletion {
+    externalReference: string;
+    outcome: "completed" | "failed";
+    /** Merged over the handler's result on completion. */
+    result?: Record<string, unknown>;
+    error?: string;
+    provider?: string;
+    evidenceReferences?: EvidencePacketReference[];
+    observedAt: Date | string;
+}
+interface RecordedExternalCompletion extends ExternalCompletion {
+    recordedAt: Date;
+    /**
+     * Canonical digest of provider, reference, outcome, result, error, and
+     * evidence. A repeat with the same digest is the same news; a repeat with
+     * the same outcome and a different digest is changed evidence, and is a
+     * contradiction like a flipped outcome. Observation time is left out,
+     * since a redelivery legitimately carries a new one.
+     */
+    digest: string;
+}
+interface ReconcileOverdueCompletionsInput {
+    tenantId?: string;
+    spaceId?: string;
+    limit?: number;
+    now?: Date;
+}
 type AdapterInvocationStatus = "running" | "succeeded" | "failed" | "ambiguous";
 interface AdapterReconciliationOutcome {
     kind: "adapter_outcome_ambiguous";
@@ -330,7 +403,7 @@ 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>;
-    updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation">>): Promise<void>;
+    updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: ActionInvocationPatch): Promise<void>;
     appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
     createAdapterInvocation(record: AdapterInvocationRecord): Promise<void>;
     getAdapterInvocation(id: string): Promise<AdapterInvocationRecord | undefined>;
@@ -364,7 +437,7 @@ interface PlatformHostMutationTransaction<TDb> {
     nextEventSequence(tenantId: string, spaceId: string): Promise<number>;
     listEvents(tenantId: string, spaceId: string): Promise<AssetEventEnvelope[]>;
     getEntityState?(tenantId: string, spaceId: string, entityType: string, entityId: string): Promise<string | undefined>;
-    updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation">>): Promise<void>;
+    updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: ActionInvocationPatch): Promise<void>;
     updateLeasedActionInvocation?(input: UpdateLeasedActionInvocationInput): Promise<boolean>;
 }
 type OutboxStatus = "pending" | "published" | "dead_letter";
@@ -496,6 +569,12 @@ interface ListActionInvocationsInput {
     spaceId?: string;
     statuses?: readonly ActionStatus[];
     updatedBefore?: Date;
+    /** Only invocations holding a pending external completion. */
+    awaitingCompletion?: boolean;
+    /** Only pending completions due at or before this instant. Implies `awaitingCompletion`. */
+    completionDueBefore?: Date;
+    /** Only invocations no worker holds a lease on. */
+    unleased?: boolean;
     limit?: number;
 }
 interface ClaimActionInvocationsInput {
@@ -506,7 +585,20 @@ interface ClaimActionInvocationsInput {
     spaceId?: string;
     now?: Date;
 }
-type ActionInvocationPatch = Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation">>;
+/**
+ * What the host writes back to an invocation.
+ *
+ * Store obligations for `pendingCompletion`, which a custom store must honour
+ * or the recovery worker will re-run an external handoff:
+ * - a patch that sets `pendingCompletion` together with `status: "running"`
+ *   parks the invocation and must clear its lease;
+ * - a patch that sets `pendingCompletion` without a status records the handoff
+ *   and must leave the lease alone;
+ * - a patch with `pendingCompletion: undefined` clears it;
+ * - `claimActionInvocations` must never claim a running invocation without a
+ *   lease, which is what a parked invocation is.
+ */
+type ActionInvocationPatch = Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation" | "pendingCompletion" | "externalCompletion">>;
 interface UpdateLeasedActionInvocationInput {
     id: string;
     tenantId: string;
@@ -609,6 +701,8 @@ interface SubmitActionResult {
     error?: string;
     reconciliation?: AuthorizationReconciliationOutcome;
     adapterReconciliation?: AdapterReconciliationOutcome;
+    /** Present while the invocation waits for an external system to complete it. */
+    pendingCompletion?: PendingExternalCompletion;
     /** Mirrors the action's declared consistency so a caller knows whether the result is settled. */
     consistency?: "authoritative-now" | "provisional-until-reconciled";
     hitlRoute?: AgentActionRoute;
@@ -621,6 +715,8 @@ interface ExecuteActionResult {
     error?: string;
     reconciliation?: AuthorizationReconciliationOutcome;
     adapterReconciliation?: AdapterReconciliationOutcome;
+    /** Present while the invocation waits for an external system to complete it. */
+    pendingCompletion?: PendingExternalCompletion;
     /** Mirrors the action's declared consistency so a caller knows whether the result is settled. */
     consistency?: "authoritative-now" | "provisional-until-reconciled";
     hitlRoute?: AgentActionRoute;
@@ -645,6 +741,12 @@ interface PlatformActionWorkerOptions<TDb> {
     signal?: AbortSignal;
     onError?: (error: unknown, invocation?: ActionInvocationRecord) => void;
     telemetry?: PlatformHostTelemetry;
+    /**
+     * Sweep overdue external handoffs each cycle. Defaults to on. Turn it off
+     * for a store without the governance seam, where the sweep would refuse
+     * on every cycle, and run the sweep elsewhere.
+     */
+    sweepOverdueCompletions?: boolean;
 }
 interface PlatformActionWorkerCycleResult {
     claimed: number;
@@ -746,6 +848,20 @@ interface GovernedActionHost {
     resumeApprovedInvocation(actionInvocationId: string, tenantId: string, spaceId: string, decision: ActionApprovalDecision): Promise<ExecuteActionResult>;
     recordExecutionAttestation(actionInvocationId: string, tenantId: string, spaceId: string, attestation: ExecutionAttestation): Promise<void>;
     recordExternalReconciliation(actionInvocationId: string, tenantId: string, spaceId: string, reconciliation: ExternalReconciliation): Promise<void>;
+    /**
+     * Complete an invocation an adapter handed off, by the reference the
+     * external system was given. Idempotent for a repeated identical
+     * completion; a contradictory one moves the invocation to reconciliation.
+     */
+    completeExternalInvocation(actionInvocationId: string, tenantId: string, spaceId: string, completion: ExternalCompletion): Promise<ExecuteActionResult>;
+    /**
+     * Move handoffs past their deadline to `reconciliation_required`, so a
+     * callback that never comes is a finding and not a silent wait. The
+     * pending handoff is kept, so a late completion can still land.
+     */
+    reconcileOverdueCompletions(input?: ReconcileOverdueCompletionsInput): Promise<{
+        overdue: string[];
+    }>;
 }
 
 declare function createGovernedActionHost<TDb>(options: PlatformHostOptions<TDb>): GovernedActionHost;
@@ -772,7 +888,7 @@ declare class MemoryPlatformHostStore<TDb> implements RecoverablePlatformHostSto
     private runTransactionWithEvents;
     createActionInvocation(input: CreateActionInvocationInput): Promise<ActionInvocationRecord>;
     getActionInvocation(id: string, tenantId: string, spaceId: string): Promise<ActionInvocationRecord | undefined>;
-    updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation">>): Promise<void>;
+    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>;
     appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
@@ -884,7 +1000,7 @@ declare class PostgresPlatformHostStore<TDb> implements RecoverablePlatformHostS
     transaction<TResult>(run: (db: TDb) => Promise<TResult>): Promise<TResult>;
     createActionInvocation(input: CreateActionInvocationInput): Promise<ActionInvocationRecord>;
     getActionInvocation(id: string, tenantId: string, spaceId: string): Promise<ActionInvocationRecord | undefined>;
-    updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation">>): Promise<void>;
+    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>;
     appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
@@ -1051,4 +1167,4 @@ interface CreateDurableSagaParentLifecycleOptions<TDb> {
  */
 declare function createDurableSagaParentLifecycle<TDb>(options: CreateDurableSagaParentLifecycleOptions<TDb>): HostSagaParentLifecycle;
 
-export { type ActionApprovalDecision, type ActionAuthorizationInput, type ActionExecutionAuthorizationInput, type ActionExecutionReason, type ActionInvocationPatch, type ActionInvocationRecord, type AdapterInvocationRecord, type AdapterInvocationStatus, type AdapterReconciliationOutcome, type ApprovalDecisionTransitionResult, type ApprovalPlatformHostStore, type AtomicMutationPlatformHostStore, type AuthorizationBinding, type AuthorizationGoverningMoment, type AuthorizationReconciliationOutcome, type BeginApprovalDecisionInput, type ClaimActionInvocationsInput, type ClaimOutboxInput, type CreateActionInvocationInput, type CreateDurableSagaParentLifecycleOptions, type DispatchActionInput, type DispatchActionResult, type EnterpriseEventEnvelope, type EnterpriseEventPublisher, type EventPayloadClassification, type ExecuteActionResult, type ExecuteInvocationOptions, type ExecutionAttestationRecord, type ExternalReconciliationRecord, type GovernancePlatformHostStore, type GovernedActionHost, type HitlDecisionEvidence, type HostCompensationRecord, type HostSagaParentApprovalInput, type HostSagaParentCancellationInput, type HostSagaParentCompletionInput, type HostSagaParentFailureInput, type HostSagaParentLifecycle, type HostSagaParentProgressInput, type HostSagaParentProgressRecord, type IdempotencyConflict, IdempotencyConflictError, type InvocationProvenance, type InvocationSource, type KnownActionExecutionReason, type ListActionInvocationsInput, MemoryPlatformHostStore, type MemoryPlatformHostTransactionProvider, type NamespacedAttributes, type OutboxEventMetadata, type OutboxPlatformHostStore, type OutboxRecord, type OutboxRelayOptions, type OutboxRelayResult, type OutboxStatus, PARAMETER_DIGEST_ALGORITHM, PLATFORM_HOST_CONTRACT_VERSION, PLATFORM_HOST_HEALTH_CONTRACT_VERSION, PLATFORM_HOST_METRIC_NAMES, type PendingAssetEvent, type PersistedActionApprovalDecision, type PlatformActionDispatcher, type PlatformActionWorkerCycleResult, type PlatformActionWorkerOptions, type PlatformHostAuthorization, type PlatformHostHealthCounts, type PlatformHostHealthOptions, type PlatformHostHealthQuery, type PlatformHostHealthSnapshot, type PlatformHostHealthStatus, type PlatformHostHealthStore, type PlatformHostLifecycleTelemetry, type PlatformHostMetricName, type PlatformHostMetricTelemetry, type PlatformHostMetricType, type PlatformHostMutationTransaction, type PlatformHostOptions, type PlatformHostReadinessReason, type PlatformHostSqlClient, type PlatformHostSqlResult, type PlatformHostStore, type PlatformHostTelemetry, type PlatformHostTelemetryAttribute, type PlatformHostTelemetryEventName, type PlatformHostTelemetryHook, type PlatformHostTelemetryInput, type PlatformHostTelemetryRecord, type PlatformHostWorkerHealthInput, type PolicyEvaluationRecord, type PolicyObligationRecord, type PostgresMigration, PostgresPlatformHostStore, type PostgresPlatformHostTransactionContext, type PostgresPlatformHostTransactionProvider, type RecoverablePlatformHostStore, type RenewActionInvocationLeaseInput, type SubmitActionInput, type SubmitActionResult, type UpdateLeasedActionInvocationInput, applyPostgresMigrations, canonicalJson, cloneOutboxRecord, createDurableSagaParentLifecycle, createGovernedActionHost, createStoreBackedActionDispatcher, digestParameters, emitPlatformHostTelemetry, getPlatformHostHealthSnapshot, runOutboxRelayCycle, runPlatformActionWorker, runPlatformActionWorkerCycle, toEnterpriseEventEnvelope };
+export { type ActionApprovalDecision, type ActionAuthorizationInput, type ActionExecutionAuthorizationInput, type ActionExecutionReason, type ActionInvocationPatch, type ActionInvocationRecord, type AdapterInvocationRecord, type AdapterInvocationStatus, type AdapterReconciliationOutcome, type ApprovalDecisionTransitionResult, type ApprovalPlatformHostStore, type AtomicMutationPlatformHostStore, type AuthorizationBinding, type AuthorizationGoverningMoment, type AuthorizationReconciliationOutcome, type BeginApprovalDecisionInput, type ClaimActionInvocationsInput, type ClaimOutboxInput, type CreateActionInvocationInput, type CreateDurableSagaParentLifecycleOptions, type DispatchActionInput, type DispatchActionResult, type EnterpriseEventEnvelope, type EnterpriseEventPublisher, type EventPayloadClassification, type ExecuteActionResult, type ExecuteInvocationOptions, type ExecutionAttestationRecord, type ExternalCompletion, ExternalCompletionError, type ExternalCompletionRefusal, type ExternalReconciliationRecord, type GovernancePlatformHostStore, type GovernedActionHost, type HitlDecisionEvidence, type HostCompensationRecord, type HostSagaParentApprovalInput, type HostSagaParentCancellationInput, type HostSagaParentCompletionInput, type HostSagaParentFailureInput, type HostSagaParentLifecycle, type HostSagaParentProgressInput, type HostSagaParentProgressRecord, type IdempotencyConflict, IdempotencyConflictError, type InvocationProvenance, type InvocationSource, type KnownActionExecutionReason, type ListActionInvocationsInput, MemoryPlatformHostStore, type MemoryPlatformHostTransactionProvider, type NamespacedAttributes, type OutboxEventMetadata, type OutboxPlatformHostStore, type OutboxRecord, type OutboxRelayOptions, type OutboxRelayResult, type OutboxStatus, PARAMETER_DIGEST_ALGORITHM, PLATFORM_HOST_CONTRACT_VERSION, PLATFORM_HOST_HEALTH_CONTRACT_VERSION, PLATFORM_HOST_METRIC_NAMES, type PendingAssetEvent, type PendingExternalCompletion, type PersistedActionApprovalDecision, type PlatformActionDispatcher, type PlatformActionWorkerCycleResult, type PlatformActionWorkerOptions, type PlatformHostAuthorization, type PlatformHostHealthCounts, type PlatformHostHealthOptions, type PlatformHostHealthQuery, type PlatformHostHealthSnapshot, type PlatformHostHealthStatus, type PlatformHostHealthStore, type PlatformHostLifecycleTelemetry, type PlatformHostMetricName, type PlatformHostMetricTelemetry, type PlatformHostMetricType, type PlatformHostMutationTransaction, type PlatformHostOptions, type PlatformHostReadinessReason, type PlatformHostSqlClient, type PlatformHostSqlResult, type PlatformHostStore, type PlatformHostTelemetry, type PlatformHostTelemetryAttribute, type PlatformHostTelemetryEventName, type PlatformHostTelemetryHook, type PlatformHostTelemetryInput, type PlatformHostTelemetryRecord, type PlatformHostWorkerHealthInput, type PolicyEvaluationRecord, type PolicyObligationRecord, type PostgresMigration, PostgresPlatformHostStore, type PostgresPlatformHostTransactionContext, type PostgresPlatformHostTransactionProvider, type ReconcileOverdueCompletionsInput, type RecordedExternalCompletion, type RecoverablePlatformHostStore, type RenewActionInvocationLeaseInput, type SubmitActionInput, type SubmitActionResult, type UpdateLeasedActionInvocationInput, applyPostgresMigrations, canonicalJson, cloneOutboxRecord, createDurableSagaParentLifecycle, createGovernedActionHost, createStoreBackedActionDispatcher, digestParameters, emitPlatformHostTelemetry, getPlatformHostHealthSnapshot, runOutboxRelayCycle, runPlatformActionWorker, runPlatformActionWorkerCycle, toEnterpriseEventEnvelope };