@fabricorg/platform-host 7.5.0 → 7.6.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @fabricorg/platform-host
 
+## 7.6.0
+
+### Minor Changes
+
+- 74295fd: Add optional `updateAdapterInvocation` and `appendExternalReconciliation` members to `PlatformHostMutationTransaction` (issue #71). The adapter update retains the store method's tenant/space/invocation scope semantics. Memory transactions buffer these writes and undo ledger writes if commit fails; PostgreSQL delegates them to the transaction-bound scoped store.
+
+  Host uses these members for withheld-output and refused-handoff finalization. Evidence events and the adapter's succeeded marker precede the fenced terminal verdict inside the transaction. Withheld-output governance reconciliation shares that transaction when applicable. Leased atomic finalization also requires transaction-scoped `updateLeasedActionInvocation`; missing required members select the verdict-first fallback before evidence writes. Host retries the whole transaction once on a non-lease error, then selects the verdict-first fallback if the retry also fails with a non-lease error. Lease loss on either attempt raises `RecoverableFinalizationError` without fallback. Status telemetry fires after an atomic commit or through fallback verdict persistence. Refused-handoff completion reconciliation logging and its tolerated-failure error update remain after commit. Event IDs, payloads, returned results, and pending-completion selection are unchanged.
+
+  **Release note: failure semantics (issue #71).** When atomic finalization succeeds on a store with the required transaction members, the degraded verdict and its evidence commit together. A rolled-back atomic attempt leaves the invocation and adapter row `running` until the retry or fallback commits. Repeated non-lease transaction failures select the verdict-first fallback so the invocation can reach terminal `reconciliation_required` even when atomic evidence cannot be written. If the fallback evidence write also fails, Host throws `RecoverableFinalizationError` after the verdict commits, retaining the prior terminal-verdict/evidence-gap behavior. Lease loss or failure to persist the fallback verdict can still leave the invocation reclaimable; the adapter then re-runs under its `adapterInvocationId` idempotency key, as after a crash immediately following the adapter return. Previously a terminal verdict could remain with missing evidence and a running adapter row. Non-atomic stores and transactions lacking the required members keep the old verdict-first order and its evidence gap. Custom stores must implement the new transaction members in the same transaction to get the atomic behavior. Finalization failures retain `RecoverableFinalizationError`; adapters still need idempotency or a stable idempotency key.
+
+  A store wrapper that spreads a built-in transaction object (`...transaction`) inherits the new members: Host commits these writes through the inner transaction rather than through the wrapper's store-level overrides of `updateAdapterInvocation` or `appendExternalReconciliation`.
+
+  A successful COMMIT with a lost acknowledgement can cause the leased retry to report lease loss (`RecoverableFinalizationError`) even though the stored state is complete, as with the previous verdict retry.
+
+- 5d93521: Add `ReconciliationRequiredError` and `isReconciliationRequiredError` to Platform's root and policies exports (issue #70). The error accepts a message and optional cause; its stable name and `EXECUTION_RECONCILIATION_REQUIRED` code support recognition across package copies.
+
+  Host honours this signal at the handler-transaction catch, including a store wrapper detecting that its own recovery receipt no longer matches the action's declared events or result schema before handing it back. Wrappers cannot tell which Host transaction they wrap: the same API also serves finalization and external completion. Translate only conditions the store detects itself, not Host internal errors matched by message text; those errors have no public stable code or message contract. Put non-sensitive operator detail in the message because `cause` is not stored. It redacts the message, persists terminal `reconciliation_required`, and returns consistency and HITL metadata. The existing status telemetry fires through persistence. Re-execution returns the terminal record without running the handler; adapters do not run after this signal. Atomic `transactionWithEvents` stores roll back the attempt's domain writes, domain events, and `StateTransitioned` together. On the `transaction`-only fallback, Host appends events directly and the built-in stores do not roll back: domain writes and any events already appended during the attempt stay persisted beside the `reconciliation_required` record, as they already do beside `failed`. A custom fallback transaction may roll back domain writes, but Host does not make event appends atomic with those writes.
+
+  **Release note: failure semantics (issue #70).** Previously these handler-transaction throws recorded terminal `failed`. Opting into `ReconciliationRequiredError` now requests an operator decision where a domain effect may already have committed. Ordinary handler errors, pre-handler governance/validation, state guards, adapters, and finalization retain their existing failure or recovery semantics. `after_adapters` finalization still uses `RecoverableFinalizationError`. Workers continue counting returned reconciliation results as `failed`. No new event is introduced. Host's Platform peer remains `workspace:^` so published packages require the Platform release containing the runtime exports.
+
+- 73d5f98: Preserve the validated transition for idempotent `after_adapters` actions in the optional durable invocation field `pendingStateTransition` (issue #69). Host saves the entity type, entity ID, original state, and target. With a mutation transaction, it writes through transaction-scoped `updateActionInvocation` after the handler succeeds and result/events validate, just before the callback returns. This avoids holding the invocation row lock during the handler while keeping the evidence atomic with domain writes. Without a mutation transaction, Host writes before the handler. Non-idempotent actions do not write the field. The saved transition is retained as evidence after completion. Memory and PostgreSQL stores persist it through invocation patches; PostgreSQL supports both ordinary and leased updates.
+
+  **Release note: recovery semantics (issue #69).** A recovered replay admitted by the same-invocation state shortcut can emit the original `StateTransitioned` after adapters when the saved entity type, entity ID, and target match the current binding and state. It uses the saved `fromState`, the existing payload shape, and the stable `state:transition` event ID; built-in event and outbox stores deduplicate that ID. A handler-supplied transition for the same subject still suppresses Host emission. Custom stores must persist and reload `pendingStateTransition`, including through transaction-scoped `updateActionInvocation`, to get this behavior. Invocations started before upgrading have no saved transition and get no re-emitted event. Missing or mismatched evidence preserves replay acceptance without fabricating a prior state. PostgreSQL `ensureSchema()` adds the `pending_state_transition jsonb` column through additive migration 7, preserving the checksums of earlier migrations. `before_adapters` continues to record the transition with the handler's events and does not write this field.
+
 ## 7.5.0
 
 ### Minor Changes

package/README.md

@@ -80,6 +80,46 @@ handlers, adapters, and finalization retain their existing failure/reconciliatio
 A retryable obligation-resolver error fails terminally with the policy evidence from that attempt.
 Preview evaluation does not enter this execution catch.
 
+**Handler transaction reconciliation.** A handler or store transaction wrapper can throw
+`ReconciliationRequiredError(message, { cause })` from `@fabricorg/platform` (also exported from
+`@fabricorg/platform/policies`) when a domain effect may already have committed and an operator
+must decide how to proceed. For example, a recovery-receipt store can check its own stored result
+against the action's current declared events and result schema before handing that result back.
+If its own check detects an incompatible receipt from an earlier attempt, it can throw this signal.
+Put non-sensitive operator detail in the message: Host stores the redacted message, not `cause`.
+The cross-copy predicate
+`isReconciliationRequiredError` recognises the stable name and `EXECUTION_RECONCILIATION_REQUIRED`
+code as well as local instances.
+
+A `transactionWithEvents` wrapper cannot tell which Host transaction it is wrapping from the public
+callback contract: Host also uses this API for `after_adapters` finalization and external completion.
+Translate only a condition the store detects itself while recovering its own receipt, and let other
+errors propagate unchanged. Do not match Host's internal validation-error messages; those errors
+have no public stable code or message contract.
+
+Host honours the signal only at the handler-transaction catch, covering `transactionWithEvents`
+and the fallback `transaction`. It redacts the message with `redactErrorText` using `source: "handler"`,
+records terminal `reconciliation_required`, and returns the error with the action's consistency and
+persisted HITL route/risk tier. Status persistence emits the existing reconciliation telemetry.
+Re-execution returns the terminal record without running the handler. Workers retain their existing
+counting: a returned reconciliation result increments `failed`, not `completed` or `deferred`.
+
+Atomic `transactionWithEvents` stores roll back the attempt's domain writes, domain events, and
+Host's `StateTransitioned` together when the transaction throws. On the `transaction`-only fallback,
+Host appends events directly. The built-in stores simply run the callback without rollback: domain
+writes and any events Host appended during the attempt stay persisted beside the
+`reconciliation_required` record, as they already do beside `failed`. A custom fallback transaction
+may roll back its domain writes, but Host does not make its event appends atomic with those writes.
+Host does not run adapters after this signal or add a new lifecycle event for it. Effects or evidence
+committed by earlier attempts are not undone.
+
+The signal does not change failures in pre-handler governance or validation, state-transition guard
+exceptions, adapters, or finalization. Governance and adapter throws retain their existing `failed`
+paths. State guards still fail closed. `after_adapters` finalization failures still escape as
+`RecoverableFinalizationError` for recovery; other finalization throws retain their existing failure
+path. An ordinary handler error still records `failed`. This signal requests an operator decision,
+not an automatic retry or a claim that the current transaction committed.
+
 New rows bind that key to the action version, actor/authority binding, and a versioned canonical
 parameter digest. Host 3 defaults to `enforce`, which throws `IdempotencyConflictError`; configure
 `idempotency.conflictMode` as `audit-only` for a preflight soak. Legacy null-digest rows skip only the
@@ -210,6 +250,9 @@ in action parameters or workflow history.
 Production stores can implement `AtomicMutationPlatformHostStore.transactionWithEvents`. The
 transaction-scoped `db`, event sequence, event append, event listing, and invocation update methods
 must all use the same database transaction.
+The optional transaction-scoped `updateAdapterInvocation` and `appendExternalReconciliation`
+operations extend this unit of work to degraded adapter finalization, as described under redaction
+below.
 
 `PostgresPlatformHostStore` enables this capability when constructed with a
 `PostgresPlatformHostTransactionProvider`. The application owns that narrow binder because only the
@@ -314,22 +357,43 @@ failures refuse with non-retryable `redaction_failed` before writes, allowing a
 callback after the redactor is repaired.
 
 If `redactAdapterOutput` throws or returns null, an array, or a non-object value, the external effect
-has already happened. Host persists the `reconciliation_required` verdict before the adapter row.
-It retries an idempotent verdict write once after a store error; a lost lease is not retried. After
-the verdict is durable, Host emits the retained handoff's `ExternalOperationAccepted`, emits
-`AdapterInvocationSucceeded` with redacted input and `outputWithheld: true` without output, appends
-fixed-text reconciliation evidence when the store supports it, and marks the adapter `succeeded`.
-The events use the normal step deduplication keys. A first accepted reference is retained as
-`pendingCompletion`, so its callback can still land as evidence. References come from the original
-adapter result. Refused handoffs also persist their verdict before evidence and the adapter marker.
-
-Once the reconciliation verdict is durable, direct execution returns it and recovery excludes it.
-A later evidence or adapter-marker write failure does not change it to completed or failed; Host
-throws `RecoverableFinalizationError`. The verdict, evidence and marker are separate writes, so an
-evidence-write failure can leave a partial audit trail. If both verdict-write attempts fail, the
-adapter can run again on recovery, the same exposure as a crash mid-step. Adapters behind these paths
-should be idempotent or carry a stable idempotency key. A lost lease can also prevent this branch
-from establishing its own durable verdict; these are not atomic guarantees.
+has already happened. Host withholds output and records a `reconciliation_required` verdict. Its
+safe evidence includes the retained handoff's `ExternalOperationAccepted`,
+`AdapterInvocationSucceeded` with redacted input and `outputWithheld: true` without output, and
+fixed-text reconciliation evidence when the store supports governance. The events use the normal
+step deduplication keys. A first accepted reference is retained as `pendingCompletion`, so its
+callback can still land as evidence. References come from the original adapter result.
+
+For withheld output and refused handoffs (immediate completion or a second handoff), Host uses
+`transactionWithEvents` when the transaction supplies `updateAdapterInvocation`,
+`updateLeasedActionInvocation` for a leased invocation, and `appendExternalReconciliation` for
+withheld output on a governance-capable store. These optional members must
+share the event/verdict transaction; the adapter update must enforce the store method's supplied
+tenant, space, and invocation scope. Both built-in stores provide them when configured with a
+transaction provider. Custom stores must implement them to get this atomic behavior.
+
+When atomic finalization succeeds, evidence events, any withheld-output reconciliation entry, the adapter's `succeeded`
+marker, and the terminal `reconciliation_required` verdict commit together. Host writes evidence and
+the marker before the fenced verdict, which releases the lease, then emits status telemetry after
+commit. It retries the whole transaction once on a non-lease error. If the retry also fails with a
+non-lease error, Host selects the verdict-first fallback described below. Lease loss is not retried
+or converted to fallback; it raises `RecoverableFinalizationError`. Atomic rollback leaves the
+invocation and adapter row `running` until a retry or fallback commits. If lease loss or an unavailable
+fallback verdict prevents finalization, the invocation remains reclaimable and the adapter can run
+again under the same `adapterInvocationId` idempotency key. Adapters should be idempotent or carry
+that stable idempotency key.
+
+Without the required transaction members, or after two non-lease transaction failures, Host keeps
+the verdict-first order: the `reconciliation_required` verdict precedes evidence and the adapter marker. It retries the verdict
+write once, except on lease loss. A later evidence or marker failure raises
+`RecoverableFinalizationError` after the verdict commits and can leave a terminal verdict with missing
+evidence, including when the same deterministic failure affects the transaction and fallback. If both verdict-write attempts fail, the adapter can run again on recovery,
+the same exposure as a crash mid-step; adapters should be idempotent or carry a stable idempotency key.
+Direct execution returns a durable terminal verdict and recovery excludes it through terminal-status
+checks. Refused-handoff completion reconciliation logging stays after finalization. After atomic
+finalization, a failed log write leaves the committed verdict and adapter marker intact if the
+unfenced invocation-error update succeeds. If that error update also fails, the existing adapter-error
+catch can mark the adapter and invocation `failed`.
 
 `extractExecutionAttestation` receives the redacted output, so an extractor that needs a stripped
 field can fail after the external effect, following the existing extractor-failure behavior.
@@ -540,13 +604,30 @@ can filter it. It does not need an `emitsEvents` declaration from the action.
 For `before_adapters`, the transition is appended with the handler's domain events. For
 `after_adapters`, it is deferred to finalization after required adapter steps succeed or
 accept a parked external handoff, immediately after domain events. Adapter failure withholds
-both domain events and the transition, leaving Host's recorded entity state unchanged by that
-invocation even though handler writes may have committed. With `transactionWithEvents`, the
+both domain events and the transition, leaving the built-in stores' ledger-derived entity state
+unchanged by that invocation even though handler writes may have committed. Custom stores that
+read domain rows can already observe the target state at this point. With `transactionWithEvents`, the
 transition shares the transaction used for domain events in the selected phase; otherwise it
 follows the same legacy non-atomic boundary as domain events.
 
-Invalid transitions, failed handlers, replay-only acceptance in the target state, and bindings
-without a non-empty entity ID or target do not produce a Host transition fact. If the handler
+For idempotent `after_adapters` actions, Host saves `pendingStateTransition` on the invocation.
+It contains `{ entityType, entityId, fromState, toState }` from the validated transition.
+Custom stores must persist and return this optional invocation-record field through
+`updateActionInvocation`, including the transaction-scoped method. With a mutation transaction,
+Host writes the field after the handler succeeds and result/events validate, just before returning
+from the transaction callback. This keeps the invocation row lock out of the handler run while the
+saved transition commits or rolls back with the domain writes. The `transaction`-only fallback saves
+it separately before the handler. Non-idempotent actions do not write this field. It is retained as
+evidence after completion. PostgreSQL `ensureSchema()` adds `pending_state_transition jsonb`.
+
+On an admitted same-invocation replay, Host uses the saved `fromState` when the saved entity type,
+entity ID, and target match the current binding and state. The fact follows the usual event phase
+and stable `state:transition` ID, so built-in stores deduplicate an already appended event.
+Invocations started before upgrading, or stores that omit this evidence, retain replay acceptance
+without a re-emitted transition. Mismatched evidence also suppresses replay emission.
+
+Invalid transitions, failed handlers, replay acceptance without matching saved evidence, and
+bindings without a non-empty entity ID or target do not produce a Host transition fact. If the handler
 returns its own `StateTransitioned` with the bound entity's subject type and ID, Host suppresses
 its generated fact in either event phase. Applications using that workaround should remove it
 to use Host emission.

package/dist/index.cjs

@@ -1448,6 +1448,8 @@ function createGovernedActionHost(options) {
             throw new HostError("Outbox egress requires transactionWithEvents to provide appendEventWithOutbox before handler execution.");
           }
           const binding = action.stateMachine;
+          let replayedTransition;
+          let pendingStateTransition;
           let validatedTransition;
           if (binding) {
             const machine = stateMachineResolver(binding.entityType);
@@ -1500,6 +1502,21 @@ function createGovernedActionHost(options) {
                 }
                 replayingAppliedTransition = source?.actionInvocationId === actionInvocationId && source.state === currentState;
               }
+              const pending = invocation.pendingStateTransition;
+              if (replayingAppliedTransition && pending && pending.entityType === binding.entityType && pending.entityId === entityId && pending.toState === currentState) {
+                replayedTransition = pending;
+              }
+              if (action.idempotent && transition.valid && entityId && action.eventPhase === "after_adapters") {
+                pendingStateTransition = {
+                  entityType: binding.entityType,
+                  entityId,
+                  fromState: currentState,
+                  toState: targetState
+                };
+                if (!transaction) {
+                  await options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, { pendingStateTransition });
+                }
+              }
               if (!transition.valid && !replayingAppliedTransition) {
                 throw transition.error != null ? new Error(transition.error) : new HostError("Invalid state transition");
               }
@@ -1553,7 +1570,7 @@ function createGovernedActionHost(options) {
             }
           }
           let transitionEvent;
-          if (binding && validatedTransition?.valid && validatedTransition.entityId) {
+          if (binding && validatedTransition?.entityId && (validatedTransition.valid || replayedTransition)) {
             const { entityId, currentState, targetState } = validatedTransition;
             const handlerEmittedTransition = events.some((event) => event.eventType === "StateTransitioned" && event.subjectType === binding.entityType && event.subjectId === entityId);
             if (!handlerEmittedTransition) {
@@ -1564,7 +1581,7 @@ function createGovernedActionHost(options) {
                 payload: {
                   entityType: binding.entityType,
                   entityId,
-                  fromState: currentState,
+                  fromState: replayedTransition?.fromState ?? currentState,
                   toState: targetState,
                   causedByAction: action.actionId
                 }
@@ -1574,6 +1591,9 @@ function createGovernedActionHost(options) {
           if (transitionEvent && action.eventPhase !== "after_adapters") {
             await appendEvent(invocation, transitionEvent, "state:transition", 1, transaction);
           }
+          if (transaction && pendingStateTransition) {
+            await transaction.updateActionInvocation(actionInvocationId, tenantId, spaceId, { pendingStateTransition });
+          }
           return { data: handlerData, domainEvents: events, pendingTransitionEvent: transitionEvent };
         };
         const atomicStore = asAtomicMutationStore(options.store);
@@ -1584,6 +1604,17 @@ function createGovernedActionHost(options) {
         domainEvents = executed.domainEvents;
         pendingTransitionEvent = executed.pendingTransitionEvent;
       } catch (error) {
+        if (platform.isReconciliationRequiredError(error)) {
+          const message = caughtError({ actionId: invocation.actionId, source: "handler" }, error);
+          await persistInvocation(invocation, { status: "reconciliation_required", error: message });
+          return withConsistency({
+            actionInvocationId,
+            status: "reconciliation_required",
+            error: message,
+            ...invocation.hitlRoute ? { hitlRoute: invocation.hitlRoute } : {},
+            ...invocation.hitlRiskTier ? { hitlRiskTier: invocation.hitlRiskTier } : {}
+          }, action.actionId);
+        }
         return fail2(invocation, "failed", caughtError({ actionId: invocation.actionId, source: "handler" }, error));
       }
       const adapterInvocationScope = { tenantId: invocation.tenantId, spaceId: invocation.spaceId, actionInvocationId: invocation.id };
@@ -1651,7 +1682,7 @@ function createGovernedActionHost(options) {
           subjectId: adapterEventSubject.subjectId,
           payload: { adapterType: step.adapterType, operation: step.operation }
         }, `adapter:${stepIndex}:started`);
-        async function appendDegradedAdapterEvidence(outputWithheld, message, accepted, output, externalReference) {
+        async function appendDegradedAdapterEvidence(outputWithheld, message, accepted, output, externalReference, transaction) {
           if (accepted) {
             await appendEvent(invocation, {
               eventType: "ExternalOperationAccepted",
@@ -1663,7 +1694,7 @@ function createGovernedActionHost(options) {
                 externalReference: accepted.externalReference,
                 ...accepted.dueAt ? { dueAt: accepted.dueAt.toISOString() } : {}
               }
-            }, `adapter:${stepIndex}:accepted`);
+            }, `adapter:${stepIndex}:accepted`, 1, transaction);
           }
           await appendEvent(invocation, {
             eventType: "AdapterInvocationSucceeded",
@@ -1675,10 +1706,10 @@ function createGovernedActionHost(options) {
               input: recordedInput,
               ...outputWithheld ? { outputWithheld: true } : { output }
             }
-          }, `adapter:${stepIndex}:succeeded`);
+          }, `adapter:${stepIndex}:succeeded`, 1, transaction);
           const governanceStore2 = asGovernanceStore(options.store);
           if (outputWithheld && governanceStore2) {
-            await governanceStore2.appendExternalReconciliation({
+            await (transaction ?? governanceStore2).appendExternalReconciliation({
               id: lifecycleId("rec", actionInvocationId, `${adapter.vendor}:${adapterInvocationId}`),
               actionInvocationId,
               tenantId,
@@ -1692,6 +1723,52 @@ function createGovernedActionHost(options) {
             });
           }
         }
+        async function finalizeDegradedAdapterAtomically(patch, outputWithheld, message, accepted, output, externalReference) {
+          const atomicStore = asAtomicMutationStore(options.store);
+          if (!atomicStore) return false;
+          const needsReconciliation = outputWithheld && !!asGovernanceStore(options.store);
+          const previousStatus = invocation.status;
+          const finalize = () => atomicStore.transactionWithEvents(async (transaction) => {
+            if (!transaction.updateAdapterInvocation || needsReconciliation && !transaction.appendExternalReconciliation || invocation.leaseOwner && invocation.leaseToken !== void 0 && !transaction.updateLeasedActionInvocation) return false;
+            await appendDegradedAdapterEvidence(outputWithheld, message, accepted, output, externalReference, transaction);
+            await transaction.updateAdapterInvocation(adapterInvocationId, {
+              status: "succeeded",
+              ...outputWithheld ? {} : { output },
+              updatedAt: now()
+            }, adapterInvocationScope);
+            if (invocation.leaseOwner && invocation.leaseToken !== void 0) {
+              if (!transaction.updateLeasedActionInvocation) {
+                throw new HostError("Leased atomic finalization requires transaction-scoped fencing support.");
+              }
+              const updated = await transaction.updateLeasedActionInvocation({
+                id: actionInvocationId,
+                tenantId,
+                spaceId,
+                workerId: invocation.leaseOwner,
+                leaseToken: invocation.leaseToken,
+                patch
+              });
+              if (!updated) throw new RecoverableFinalizationError(`Invocation lease lost: ${actionInvocationId}`);
+            } else {
+              await transaction.updateActionInvocation(actionInvocationId, tenantId, spaceId, patch);
+            }
+            return true;
+          });
+          let committed;
+          try {
+            committed = await finalize();
+          } catch (error) {
+            if (error instanceof RecoverableFinalizationError) throw error;
+            try {
+              committed = await finalize();
+            } catch (retryError) {
+              if (retryError instanceof RecoverableFinalizationError) throw retryError;
+              return false;
+            }
+          }
+          if (committed) emitInvocationStatusTelemetry(invocation, patch.status, options.telemetry, now(), previousStatus);
+          return committed;
+        }
         const adapterErrorContext = { actionId: action.actionId, source: "adapter", adapterType: step.adapterType, operation: step.operation, provider: adapter.vendor };
         const executionErrorContext = { actionId: action.actionId, source: "execution" };
         let errorContext = executionErrorContext;
@@ -1851,9 +1928,13 @@ function createGovernedActionHost(options) {
                 ...deadlineMs2 ? { dueAt: new Date(acceptedAt.getTime() + deadlineMs2) } : {}
               } : void 0);
               try {
-                await persistReconciliationVerdict(invocation, { status: "reconciliation_required", error: message, ...pendingCompletion ? { pendingCompletion } : {} });
-                await appendDegradedAdapterEvidence(true, message, pendingCompletion?.adapterInvocationId === adapterInvocationId ? pendingCompletion : void 0, void 0, reference || void 0);
-                await options.store.updateAdapterInvocation(adapterInvocationId, { status: "succeeded", updatedAt: now() }, adapterInvocationScope);
+                const patch = { status: "reconciliation_required", error: message, ...pendingCompletion ? { pendingCompletion } : {} };
+                const accepted = pendingCompletion?.adapterInvocationId === adapterInvocationId ? pendingCompletion : void 0;
+                if (!await finalizeDegradedAdapterAtomically(patch, true, message, accepted, void 0, reference || void 0)) {
+                  await persistReconciliationVerdict(invocation, patch);
+                  await appendDegradedAdapterEvidence(true, message, accepted, void 0, reference || void 0);
+                  await options.store.updateAdapterInvocation(adapterInvocationId, { status: "succeeded", updatedAt: now() }, adapterInvocationScope);
+                }
               } catch {
                 throw new RecoverableFinalizationError(message);
               }
@@ -1881,13 +1962,18 @@ function createGovernedActionHost(options) {
             const completion = action.execution?.completion ?? "immediate";
             const refuse = completion === "immediate" ? `Adapter ${step.adapterType}:${step.operation} handed off external operation "${reference}" but ${action.actionId} declares immediate completion; the external effect may be in flight.` : pendingHandoff ? `Adapter ${step.adapterType}:${step.operation} handed off a second external operation "${reference}" while "${pendingHandoff.externalReference}" is already pending; one invocation waits on one completion.` : void 0;
             if (refuse) {
+              let adapterFinalizedAtomically;
               try {
-                await persistReconciliationVerdict(invocation, {
+                const patch = {
                   status: "reconciliation_required",
                   error: refuse,
                   ...pendingHandoff ? {} : { pendingCompletion: accepted }
-                });
-                await appendDegradedAdapterEvidence(false, refuse, pendingHandoff ? void 0 : accepted, output);
+                };
+                adapterFinalizedAtomically = await finalizeDegradedAdapterAtomically(patch, false, refuse, pendingHandoff ? void 0 : accepted, output);
+                if (!adapterFinalizedAtomically) {
+                  await persistReconciliationVerdict(invocation, patch);
+                  await appendDegradedAdapterEvidence(false, refuse, pendingHandoff ? void 0 : accepted, output);
+                }
               } catch {
                 throw new RecoverableFinalizationError(refuse);
               }
@@ -1899,7 +1985,7 @@ function createGovernedActionHost(options) {
                 await options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, { error });
               }
               try {
-                await options.store.updateAdapterInvocation(adapterInvocationId, { status: "succeeded", output, updatedAt: now() }, adapterInvocationScope);
+                if (!adapterFinalizedAtomically) await options.store.updateAdapterInvocation(adapterInvocationId, { status: "succeeded", output, updatedAt: now() }, adapterInvocationScope);
               } catch {
                 throw new RecoverableFinalizationError(refuse);
               }
@@ -2673,11 +2759,14 @@ var MemoryPlatformHostStore = class {
     await previous;
     let domainSnapshot;
     let snapshotCreated = false;
+    const undoLedgerWrites = [];
     try {
       domainSnapshot = transactionProvider.snapshot(this.db);
       snapshotCreated = true;
       const pendingEvents = [];
       const pendingUpdates = [];
+      const pendingAdapterUpdates = [];
+      const pendingReconciliations = [];
       const appendPending = async (event, metadata) => {
         if (this.events.some((candidate) => candidate.id === event.id) || pendingEvents.some((candidate) => candidate.event.id === event.id)) return;
         pendingEvents.push({ event, ...metadata ? { metadata } : {} });
@@ -2712,26 +2801,62 @@ var MemoryPlatformHostStore = class {
           }
           return state;
         },
+        updateAdapterInvocation: async (id, patch, scope) => {
+          if (!await this.getAdapterInvocation(id, scope)) throw new Error(`AdapterInvocation not found: ${id}`);
+          pendingAdapterUpdates.push([id, patch, scope]);
+        },
+        appendExternalReconciliation: async (record) => {
+          pendingReconciliations.push(record);
+        },
         updateActionInvocation: async (id, tenantId, spaceId, patch) => {
-          pendingUpdates.push({ id, tenantId, spaceId, patch });
+          pendingUpdates.push({ id, tenantId, spaceId, patch: copyInvocationPatch(patch) });
         },
         updateLeasedActionInvocation: async (input) => {
           const record = await this.getActionInvocation(input.id, input.tenantId, input.spaceId);
           if (!record || record.status !== "running" || record.leaseOwner !== input.workerId || record.leaseToken !== input.leaseToken) return false;
-          pendingUpdates.push({ id: input.id, tenantId: input.tenantId, spaceId: input.spaceId, patch: input.patch });
+          pendingUpdates.push({ id: input.id, tenantId: input.tenantId, spaceId: input.spaceId, patch: copyInvocationPatch(input.patch) });
           return true;
         }
       });
       for (const update of pendingUpdates) {
         if (!await this.getActionInvocation(update.id, update.tenantId, update.spaceId)) throw new Error(`ActionInvocation not found: ${update.id}`);
       }
+      const rememberRecord = (record) => {
+        const before = { ...record };
+        undoLedgerWrites.push(() => {
+          for (const key of Object.keys(record)) Reflect.deleteProperty(record, key);
+          Object.assign(record, before);
+        });
+      };
+      const rememberAppend = (rows, id) => {
+        if (!rows.some((row) => row.id === id)) undoLedgerWrites.push(() => {
+          const index = rows.findIndex((row) => row.id === id);
+          if (index !== -1) rows.splice(index, 1);
+        });
+      };
       for (const pending of pendingEvents) {
+        rememberAppend(this.events, pending.event.id);
+        rememberAppend(this.outbox, pending.event.id);
         if (pending.metadata) await this.appendEventWithOutbox(pending.event, pending.metadata);
         else await this.appendEvent(pending.event);
       }
-      for (const update of pendingUpdates) await this.updateActionInvocation(update.id, update.tenantId, update.spaceId, update.patch);
+      for (const record of pendingReconciliations) {
+        rememberAppend(this.externalReconciliations, record.id);
+        await this.appendExternalReconciliation(record);
+      }
+      for (const [id, patch, scope] of pendingAdapterUpdates) {
+        const record = await this.getAdapterInvocation(id, scope);
+        if (!record) throw new Error(`AdapterInvocation not found: ${id}`);
+        rememberRecord(record);
+        await this.updateAdapterInvocation(id, patch, scope);
+      }
+      for (const update of pendingUpdates) {
+        rememberRecord(await this.getActionInvocation(update.id, update.tenantId, update.spaceId));
+        await this.updateActionInvocation(update.id, update.tenantId, update.spaceId, update.patch);
+      }
       return result;
     } catch (error) {
+      for (const undo of undoLedgerWrites.reverse()) undo();
       if (snapshotCreated) transactionProvider.restore(this.db, domainSnapshot);
       throw error;
     } finally {
@@ -2759,6 +2884,10 @@ var MemoryPlatformHostStore = class {
     const record = await this.getActionInvocation(id, tenantId, spaceId);
     if (!record) throw new Error(`ActionInvocation not found: ${id}`);
     Object.assign(record, patch, { updatedAt: /* @__PURE__ */ new Date() });
+    if (Object.hasOwn(patch, "pendingStateTransition")) {
+      if (patch.pendingStateTransition) record.pendingStateTransition = { ...patch.pendingStateTransition };
+      else delete record.pendingStateTransition;
+    }
     if (Object.hasOwn(patch, "pendingCompletion") && patch.pendingCompletion === void 0) delete record.pendingCompletion;
     if (Object.hasOwn(patch, "externalCompletion") && patch.externalCompletion === void 0) delete record.externalCompletion;
     if (Object.hasOwn(patch, "error") && patch.error === void 0) delete record.error;
@@ -3046,6 +3175,9 @@ function cloneOutboxRequeue(requeue) {
     priorAvailableAt: new Date(requeue.priorAvailableAt)
   };
 }
+function copyInvocationPatch(patch) {
+  return { ...patch, ...patch.pendingStateTransition ? { pendingStateTransition: { ...patch.pendingStateTransition } } : {} };
+}
 async function applyPostgresMigrations(client, migrations) {
   const ordered = validateMigrations(migrations);
   const statements = ordered.map((migration) => migrationStatement(migration));
@@ -3142,7 +3274,9 @@ var PostgresPlatformHostStore = class _PostgresPlatformHostStore {
           getEntityStateSource: (tenantId, spaceId, entityType, entityId) => scoped.getEntityStateSource(tenantId, spaceId, entityType, entityId),
           getEntityState: (tenantId, spaceId, entityType, entityId) => scoped.getEntityState(tenantId, spaceId, entityType, entityId),
           updateActionInvocation: (id, tenantId, spaceId, patch) => scoped.updateActionInvocation(id, tenantId, spaceId, patch),
-          updateLeasedActionInvocation: (input) => scoped.updateLeasedActionInvocation(input)
+          updateLeasedActionInvocation: (input) => scoped.updateLeasedActionInvocation(input),
+          updateAdapterInvocation: (id, patch, scope) => scoped.updateAdapterInvocation(id, patch, scope),
+          appendExternalReconciliation: (record) => scoped.appendExternalReconciliation(record)
         });
       });
     }
@@ -3325,6 +3459,13 @@ var PostgresPlatformHostStore = class _PostgresPlatformHostStore {
 				ALTER TABLE fabric_platform.action_invocations
 					ADD COLUMN admitted_at timestamptz;
 			`
+    }, {
+      version: 7,
+      name: "pending_state_transition",
+      sql: `
+				ALTER TABLE fabric_platform.action_invocations
+					ADD COLUMN IF NOT EXISTS pending_state_transition jsonb;
+			`
     }]);
   }
   async transaction(run) {
@@ -3405,6 +3546,7 @@ var PostgresPlatformHostStore = class _PostgresPlatformHostStore {
 			 pending_completion=CASE WHEN $12::boolean THEN $13::jsonb ELSE pending_completion END,
 			 completion_due_at=CASE WHEN $12::boolean THEN ($13::jsonb->>'dueAt')::timestamptz ELSE completion_due_at END,
 			 external_completion=CASE WHEN $14::boolean THEN $15::jsonb ELSE external_completion END,
+			 pending_state_transition=CASE WHEN $16::boolean THEN $17::jsonb ELSE pending_state_transition END,
 			 lease_owner=CASE WHEN ($13::jsonb IS NOT NULL AND $4='running') OR $4 IN ('waiting_for_approval','completed','failed','blocked_by_policy','reconciliation_required','validation_failed')
 			                  THEN NULL ELSE lease_owner END,
 			 lease_expires_at=CASE WHEN ($13::jsonb IS NOT NULL AND $4='running') OR $4 IN ('waiting_for_approval','completed','failed','blocked_by_policy','reconciliation_required','validation_failed')
@@ -3426,7 +3568,9 @@ var PostgresPlatformHostStore = class _PostgresPlatformHostStore {
         Object.hasOwn(patch, "pendingCompletion"),
         patch.pendingCompletion ? JSON.stringify(patch.pendingCompletion) : null,
         Object.hasOwn(patch, "externalCompletion"),
-        patch.externalCompletion ? JSON.stringify(patch.externalCompletion) : null
+        patch.externalCompletion ? JSON.stringify(patch.externalCompletion) : null,
+        Object.hasOwn(patch, "pendingStateTransition"),
+        patch.pendingStateTransition ? JSON.stringify(patch.pendingStateTransition) : null
       ]
     );
   }
@@ -3978,6 +4122,7 @@ var PostgresPlatformHostStore = class _PostgresPlatformHostStore {
 			 pending_completion=CASE WHEN $14::boolean THEN $15::jsonb ELSE pending_completion END,
 			 completion_due_at=CASE WHEN $14::boolean THEN ($15::jsonb->>'dueAt')::timestamptz ELSE completion_due_at END,
 			 external_completion=CASE WHEN $16::boolean THEN $17::jsonb ELSE external_completion END,
+			 pending_state_transition=CASE WHEN $18::boolean THEN $19::jsonb ELSE pending_state_transition END,
 			 lease_owner=CASE WHEN ($15::jsonb IS NOT NULL AND $6='running') OR $6 IN ('waiting_for_approval','completed','failed','blocked_by_policy','reconciliation_required','validation_failed')
 			                  THEN NULL ELSE lease_owner END,
 			 lease_expires_at=CASE WHEN ($15::jsonb IS NOT NULL AND $6='running') OR $6 IN ('waiting_for_approval','completed','failed','blocked_by_policy','reconciliation_required','validation_failed')
@@ -4003,7 +4148,9 @@ var PostgresPlatformHostStore = class _PostgresPlatformHostStore {
         Object.hasOwn(patch, "pendingCompletion"),
         patch.pendingCompletion ? JSON.stringify(patch.pendingCompletion) : null,
         Object.hasOwn(patch, "externalCompletion"),
-        patch.externalCompletion ? JSON.stringify(patch.externalCompletion) : null
+        patch.externalCompletion ? JSON.stringify(patch.externalCompletion) : null,
+        Object.hasOwn(patch, "pendingStateTransition"),
+        patch.pendingStateTransition ? JSON.stringify(patch.pendingStateTransition) : null
       ]
     );
     return result.rows.length === 1;
@@ -4102,6 +4249,7 @@ function toActionRecord(row) {
     ...row.execution_reason ? { executionReason: String(row.execution_reason) } : {},
     ...row.authorization_reconciliation ? { authorizationReconciliation: row.authorization_reconciliation } : {},
     ...row.adapter_reconciliation ? { adapterReconciliation: row.adapter_reconciliation } : {},
+    ...row.pending_state_transition ? { pendingStateTransition: row.pending_state_transition } : {},
     ...row.pending_completion ? { pendingCompletion: toPendingCompletion(row.pending_completion) } : {},
     ...row.external_completion ? { externalCompletion: toExternalCompletion(row.external_completion) } : {},
     ...row.authorization_binding_id ? { authorizationBindingId: String(row.authorization_binding_id) } : {},