@fabricorg/platform-host 7.4.0 → 7.5.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { canonicalJson, AdapterRegistry, assertAdapterCircuitBreakerConfig, AdapterCircuitBreakerRegistry, createFabricId, assertGovernanceRuntimeEvidence, FABRIC_GOVERNANCE_CONTRACT_VERSION, assertMutationGovernanceContext, evaluatePolicyDefinitions, aggregatePolicyOutcomes, evaluateStateMachineTransition, executeWithAdapterRetry, isAdapterCircuitOpenError, assertAdapterOutcomeConsistency } from '@fabricorg/platform';
+import { canonicalJson, AdapterRegistry, assertAdapterCircuitBreakerConfig, AdapterCircuitBreakerRegistry, isRetryableExecutionError, createFabricId, assertGovernanceRuntimeEvidence, FABRIC_GOVERNANCE_CONTRACT_VERSION, assertMutationGovernanceContext, evaluatePolicyDefinitions, aggregatePolicyOutcomes, evaluateStateMachineTransition, executeWithAdapterRetry, isAdapterCircuitOpenError, assertAdapterOutcomeConsistency } from '@fabricorg/platform';
 export { canonicalJson } from '@fabricorg/platform';
 import { performance } from 'perf_hooks';
 import { assertAssemblyRuntimeCompatible } from '@fabricorg/assembly';
@@ -308,6 +308,24 @@ function withoutPrivateHostFields(data, eventResultFields) {
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
+var HostError = class extends Error {
+};
+function isRecord(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function tryRedactErrorText(hook, context, message) {
+  if (!hook || message === "") return { success: true, text: message };
+  try {
+    const text = hook(context, message);
+    if (typeof text === "string" && text.length > 0) return { success: true, text };
+  } catch {
+  }
+  return { success: false };
+}
+function redactErrorText(hook, context, message) {
+  const result = tryRedactErrorText(hook, context, message);
+  return result.success ? result.text : "Error text withheld: the error-text redactor failed.";
+}
 function lifecycleId(prefix, invocationId, key) {
   const safeKey = key.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 96);
   return `${prefix}_${invocationId}_${safeKey}`;
@@ -370,7 +388,11 @@ function createExternalCompletionLifecycle(deps) {
       if (completion.provider !== void 0 && recorded.provider !== void 0 && completion.provider !== recorded.provider) {
         throw new ExternalCompletionError("provider_mismatch", `ActionInvocation ${actionInvocationId} was completed by "${recorded.provider}", not "${completion.provider}".`);
       }
-      const incomingDigest = completionDigest(completion, recorded.provider ?? completion.provider);
+      const provider = recorded.provider ?? completion.provider;
+      const rawDigest = completionDigest(completion, provider);
+      if (recorded.digest === rawDigest) return withConsistency(actionResult2(invocation), invocation.actionId);
+      completion = redactCompletion(invocation, completion, provider ?? "external");
+      const incomingDigest = completionDigest(completion, provider);
       if (recorded.digest === incomingDigest) {
         return withConsistency(actionResult2(invocation), invocation.actionId);
       }
@@ -400,8 +422,10 @@ function createExternalCompletionLifecycle(deps) {
     if (completion.provider !== void 0 && completion.provider !== pending.provider) {
       throw new ExternalCompletionError("provider_mismatch", `ActionInvocation ${actionInvocationId} awaits completion from "${pending.provider}", not "${completion.provider}".`);
     }
+    completion = redactCompletion(invocation, completion, completion.provider ?? pending.provider);
     const recordedAt = now();
     const externalCompletion = {
+      // completion has passed the hooks; retain the callback shape for compatibility.
       ...completion,
       provider: completion.provider ?? pending.provider,
       observedAt: completion.observedAt instanceof Date ? completion.observedAt.toISOString() : completion.observedAt,
@@ -422,7 +446,7 @@ function createExternalCompletionLifecycle(deps) {
       await deps.store.updateAdapterInvocation(pending.adapterInvocationId, {
         ...completion.result ? { output: withoutPrivateHostFields(completion.result, eventResultFields) } : {},
         updatedAt: recordedAt
-      });
+      }, { tenantId: invocation.tenantId, spaceId: invocation.spaceId, actionInvocationId: invocation.id });
       await appendEvent(invocation, {
         eventType: "ExternalOperationCompleted",
         ...subject,
@@ -434,7 +458,7 @@ function createExternalCompletionLifecycle(deps) {
       return withConsistency(actionResult2({ ...invocation, ...patch2, result: settles ? merged : invocation.result, ...settles ? { error: void 0 } : {} }), invocation.actionId);
     }
     const error = completion.error ?? `External operation "${pending.externalReference}" failed.`;
-    await deps.store.updateAdapterInvocation(pending.adapterInvocationId, { status: "failed", error, updatedAt: recordedAt });
+    await deps.store.updateAdapterInvocation(pending.adapterInvocationId, { status: "failed", error, updatedAt: recordedAt }, { tenantId: invocation.tenantId, spaceId: invocation.spaceId, actionInvocationId: invocation.id });
     await appendEvent(invocation, {
       eventType: "ExternalOperationFailed",
       ...subject,
@@ -445,6 +469,30 @@ function createExternalCompletionLifecycle(deps) {
     if (settles) emitInvocationStatusTelemetry(invocation, "failed", deps.telemetry, now(), invocation.status);
     return withConsistency(actionResult2({ ...invocation, ...patch }), invocation.actionId);
   }
+  function redactCompletion(invocation, completion, provider) {
+    let result = completion.result;
+    if (result && deps.redactExternalCompletionResult) {
+      try {
+        result = deps.redactExternalCompletionResult(invocation.actionId, provider, result);
+        if (!isRecord(result)) throw new HostError("Completion result redactor must return a non-null, non-array object.");
+      } catch {
+        throw new ExternalCompletionError("redaction_failed", "External completion result withheld: the result redactor failed; nothing was recorded.");
+      }
+    }
+    const error = completion.error == null ? void 0 : tryRedactErrorText(
+      deps.redactErrorText,
+      { actionId: invocation.actionId, source: "external_completion", provider },
+      completion.error
+    );
+    if (error && !error.success) {
+      throw new ExternalCompletionError("redaction_failed", "External completion error withheld: the error-text redactor failed; nothing was recorded.");
+    }
+    return {
+      ...completion,
+      ...completion.result !== void 0 ? { result } : {},
+      ...error?.success ? { error: error.text } : {}
+    };
+  }
   function completionDigest(completion, provider) {
     return createHash("sha256").update(canonicalJson({
       provider: provider ?? null,
@@ -457,7 +505,7 @@ function createExternalCompletionLifecycle(deps) {
   }
   async function recordCompletionReconciliation(invocation, completion, reason) {
     const governanceStore = asGovernanceStore(deps.store);
-    if (!governanceStore) throw new Error("External completion reconciliation requires a governance-capable store.");
+    if (!governanceStore) throw new HostError("External completion reconciliation requires a governance-capable store.");
     const provider = completion.provider ?? invocation.pendingCompletion?.provider ?? invocation.externalCompletion?.provider ?? "external";
     const seed = createHash("sha256").update(`${provider}\0${completion.externalReference}\0${completion.kind ?? "refused"}`).digest("hex").slice(0, 32);
     await governanceStore.appendExternalReconciliation({
@@ -477,10 +525,10 @@ function createExternalCompletionLifecycle(deps) {
   async function reconcileOverdueCompletions(input = {}) {
     const recoverable = deps.store;
     if (!recoverable.listActionInvocations) {
-      throw new Error("Overdue completion reconciliation requires a store that can list invocations.");
+      throw new HostError("Overdue completion reconciliation requires a store that can list invocations.");
     }
     if (!asGovernanceStore(deps.store)) {
-      throw new Error("Overdue completion reconciliation requires a governance-capable store to record its findings.");
+      throw new HostError("Overdue completion reconciliation requires a governance-capable store to record its findings.");
     }
     const current = input.now ?? now();
     const candidates = await recoverable.listActionInvocations({
@@ -855,6 +903,10 @@ var ADMISSION_FAILED = Object.freeze({ kind: "failed" });
 var ADMISSION_TIMED_OUT = Object.freeze({ kind: "timed_out" });
 var ADMISSION_REFUSAL_CODE = /^[a-z][A-Za-z0-9_.:-]{0,127}$/;
 function createGovernedActionHost(options) {
+  const retryableExecutionMaxAttempts = options.retryableExecutionMaxAttempts ?? 5;
+  if (!Number.isInteger(retryableExecutionMaxAttempts) || retryableExecutionMaxAttempts <= 0) {
+    throw new Error("retryableExecutionMaxAttempts must be a positive integer.");
+  }
   if (options.composition) {
     if (!options.registry?.orderedModules) {
       throw new Error("Composition-bound Platform Host requires an explicit module registry.");
@@ -891,6 +943,9 @@ function createGovernedActionHost(options) {
   if (typeof admissionTimeoutMs !== "number" || !Number.isInteger(admissionTimeoutMs) || admissionTimeoutMs < 1 || admissionTimeoutMs > MAX_TIMER_MS) {
     throw new Error(`admissionTimeoutMs must be a whole number of milliseconds from 1 to ${MAX_TIMER_MS}.`);
   }
+  function caughtError(context, error) {
+    return error instanceof HostError ? errorMessage(error) : redactErrorText(options.redactErrorText, context, errorMessage(error));
+  }
   async function submitAction(input) {
     const read = snapshotSubmission(input);
     if (read.executionReason && !["initial", "offline_replay"].includes(read.executionReason)) {
@@ -1188,6 +1243,7 @@ function createGovernedActionHost(options) {
       spaceId,
       attributes: { actionVersion: invocation.actionVersion }
     });
+    let retryableGovernance = true;
     try {
       const parsed = action.schema.safeParse(invocation.parameters);
       if (!parsed.success) {
@@ -1340,6 +1396,7 @@ function createGovernedActionHost(options) {
         mode: "execute",
         now: now()
       });
+      retryableGovernance = false;
       for (const outcome of outcomes) {
         await options.store.appendPolicyEvaluation({
           id: lifecycleId("pol", actionInvocationId, outcome.policyId),
@@ -1383,12 +1440,14 @@ function createGovernedActionHost(options) {
       }
       let data;
       let domainEvents = [];
+      let pendingTransitionEvent;
       try {
         const runHandler = async (db, transaction) => {
           if (options.outbox && !transaction?.appendEventWithOutbox) {
-            throw new Error("Outbox egress requires transactionWithEvents to provide appendEventWithOutbox before handler execution.");
+            throw new HostError("Outbox egress requires transactionWithEvents to provide appendEventWithOutbox before handler execution.");
           }
           const binding = action.stateMachine;
+          let validatedTransition;
           if (binding) {
             const machine = stateMachineResolver(binding.entityType);
             const entityId = binding.getEntityId(parsed.data);
@@ -1418,9 +1477,30 @@ function createGovernedActionHost(options) {
                   db
                 }
               );
-              const replayingAppliedTransition = action.idempotent && currentState === targetState;
+              validatedTransition = { entityId, currentState, targetState, valid: transition.valid };
+              let replayingAppliedTransition = false;
+              if (action.idempotent && currentState === targetState && !transition.valid && entityId) {
+                let source;
+                if (transaction?.getEntityStateSource) {
+                  source = await transaction.getEntityStateSource(tenantId, spaceId, binding.entityType, entityId);
+                } else if (options.store.getEntityStateSource) {
+                  source = await options.store.getEntityStateSource(tenantId, spaceId, binding.entityType, entityId);
+                } else {
+                  const eventStore = options.store;
+                  const listEvents = transaction?.listEvents?.bind(transaction) ?? eventStore.listEvents?.bind(eventStore);
+                  const events2 = listEvents ? await listEvents(tenantId, spaceId) : [];
+                  let latest;
+                  for (const event of events2) {
+                    if (event.tenantId === tenantId && event.spaceId === spaceId && event.subjectType === binding.entityType && event.subjectId === entityId && typeof event.payload?.toState === "string" && (!latest || event.sequence > latest.sequence)) latest = event;
+                  }
+                  if (latest && typeof latest.actionInvocationId === "string") {
+                    source = { state: latest.payload.toState, actionInvocationId: latest.actionInvocationId };
+                  }
+                }
+                replayingAppliedTransition = source?.actionInvocationId === actionInvocationId && source.state === currentState;
+              }
               if (!transition.valid && !replayingAppliedTransition) {
-                throw new Error(transition.error ?? "Invalid state transition");
+                throw transition.error != null ? new Error(transition.error) : new HostError("Invalid state transition");
               }
             }
           }
@@ -1441,14 +1521,14 @@ function createGovernedActionHost(options) {
             parsed.data
           ) : { success: true, data: {} };
           if (!handlerResult.success) {
-            throw new Error(handlerResult.error ?? "Action handler failed");
+            throw handlerResult.error != null ? new Error(handlerResult.error) : new HostError("Action handler failed");
           }
           const handlerData = handlerResult.data ?? {};
           if (action.resultSchema) {
             const publicResult = withoutPrivateHostFields(handlerData, eventResultFields);
             const parsedResult = action.resultSchema.safeParse(publicResult);
             if (!parsedResult.success) {
-              throw new Error(`Action result validation failed at ${parsedResult.error.issues.map((issue) => issue.path.map(String).join(".") || "result").join(", ")}`);
+              throw new HostError(`Action result validation failed at ${parsedResult.error.issues.map((issue) => issue.path.map(String).join(".") || "result").join(", ")}`);
             }
           }
           const events = extractEvents(handlerData);
@@ -1456,7 +1536,7 @@ function createGovernedActionHost(options) {
             (event) => !action.emitsEvents.includes(event.eventType)
           );
           if (undeclaredEvent) {
-            throw new Error(
+            throw new HostError(
               `${action.actionId} emitted undeclared event type ${undeclaredEvent.eventType}`
             );
           }
@@ -1471,7 +1551,29 @@ function createGovernedActionHost(options) {
               );
             }
           }
-          return { data: handlerData, domainEvents: events };
+          let transitionEvent;
+          if (binding && validatedTransition?.valid && validatedTransition.entityId) {
+            const { entityId, currentState, targetState } = validatedTransition;
+            const handlerEmittedTransition = events.some((event) => event.eventType === "StateTransitioned" && event.subjectType === binding.entityType && event.subjectId === entityId);
+            if (!handlerEmittedTransition) {
+              transitionEvent = {
+                eventType: "StateTransitioned",
+                subjectType: binding.entityType,
+                subjectId: entityId,
+                payload: {
+                  entityType: binding.entityType,
+                  entityId,
+                  fromState: currentState,
+                  toState: targetState,
+                  causedByAction: action.actionId
+                }
+              };
+            }
+          }
+          if (transitionEvent && action.eventPhase !== "after_adapters") {
+            await appendEvent(invocation, transitionEvent, "state:transition", 1, transaction);
+          }
+          return { data: handlerData, domainEvents: events, pendingTransitionEvent: transitionEvent };
         };
         const atomicStore = asAtomicMutationStore(options.store);
         const executed = atomicStore ? await atomicStore.transactionWithEvents(
@@ -1479,9 +1581,11 @@ function createGovernedActionHost(options) {
         ) : await options.store.transaction((db) => runHandler(db));
         data = executed.data;
         domainEvents = executed.domainEvents;
+        pendingTransitionEvent = executed.pendingTransitionEvent;
       } catch (error) {
-        return fail2(invocation, "failed", errorMessage(error));
+        return fail2(invocation, "failed", caughtError({ actionId: invocation.actionId, source: "handler" }, error));
       }
+      const adapterInvocationScope = { tenantId: invocation.tenantId, spaceId: invocation.spaceId, actionInvocationId: invocation.id };
       let pendingHandoff = invocation.pendingCompletion;
       for (const [stepIndex, step] of (action.adapterSteps ?? []).entries()) {
         const input = step.getInput(parsed.data, data);
@@ -1489,12 +1593,13 @@ function createGovernedActionHost(options) {
         const adapter = adapters.require(step.adapterType, step.operation);
         const adapterInvocationId = lifecycleId("adp", actionInvocationId, String(stepIndex));
         const previousAdapterInvocation = await options.store.getAdapterInvocation(
-          adapterInvocationId
+          adapterInvocationId,
+          adapterInvocationScope
         );
         if (previousAdapterInvocation?.status === "succeeded") continue;
         if (pendingHandoff?.adapterInvocationId === adapterInvocationId) {
           const subject = options.adapterEventSubject?.(action.actionId, parsed.data, data) ?? { subjectType: "AdapterInvocation", subjectId: adapterInvocationId };
-          await options.store.updateAdapterInvocation(adapterInvocationId, { status: "succeeded", updatedAt: now() });
+          await options.store.updateAdapterInvocation(adapterInvocationId, { status: "succeeded", updatedAt: now() }, adapterInvocationScope);
           await appendEvent(invocation, {
             eventType: "ExternalOperationAccepted",
             subjectType: subject.subjectType,
@@ -1528,9 +1633,7 @@ function createGovernedActionHost(options) {
         const startedAt = now();
         const record = {
           id: adapterInvocationId,
-          actionInvocationId,
-          tenantId,
-          spaceId,
+          ...adapterInvocationScope,
           adapterType: step.adapterType,
           operation: step.operation,
           vendor: adapter.vendor,
@@ -1547,6 +1650,50 @@ function createGovernedActionHost(options) {
           subjectId: adapterEventSubject.subjectId,
           payload: { adapterType: step.adapterType, operation: step.operation }
         }, `adapter:${stepIndex}:started`);
+        async function appendDegradedAdapterEvidence(outputWithheld, message, accepted, output, externalReference) {
+          if (accepted) {
+            await appendEvent(invocation, {
+              eventType: "ExternalOperationAccepted",
+              subjectType: adapterEventSubject.subjectType,
+              subjectId: adapterEventSubject.subjectId,
+              payload: {
+                adapterType: step.adapterType,
+                operation: step.operation,
+                externalReference: accepted.externalReference,
+                ...accepted.dueAt ? { dueAt: accepted.dueAt.toISOString() } : {}
+              }
+            }, `adapter:${stepIndex}:accepted`);
+          }
+          await appendEvent(invocation, {
+            eventType: "AdapterInvocationSucceeded",
+            subjectType: adapterEventSubject.subjectType,
+            subjectId: adapterEventSubject.subjectId,
+            payload: {
+              adapterType: step.adapterType,
+              operation: step.operation,
+              input: recordedInput,
+              ...outputWithheld ? { outputWithheld: true } : { output }
+            }
+          }, `adapter:${stepIndex}:succeeded`);
+          const governanceStore2 = asGovernanceStore(options.store);
+          if (outputWithheld && governanceStore2) {
+            await governanceStore2.appendExternalReconciliation({
+              id: lifecycleId("rec", actionInvocationId, `${adapter.vendor}:${adapterInvocationId}`),
+              actionInvocationId,
+              tenantId,
+              spaceId,
+              status: "pending",
+              provider: adapter.vendor,
+              ...externalReference ?? accepted?.externalReference ? { externalOperationId: externalReference ?? accepted?.externalReference } : {},
+              attempt: 1,
+              reason: message,
+              observedAt: now()
+            });
+          }
+        }
+        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;
         let adapterDeadlineTimer;
         try {
           const adapterController = options.adapterDeadlineMs ? new AbortController() : void 0;
@@ -1554,15 +1701,15 @@ function createGovernedActionHost(options) {
           if (adapterController && deadlineMs) {
             const remaining = deadlineMs - now().getTime();
             if (remaining <= 0) {
-              throw new Error(`Adapter deadline already expired before execution: ${step.adapterType}:${step.operation}`);
+              throw new HostError(`Adapter deadline already expired before execution: ${step.adapterType}:${step.operation}`);
             }
             adapterDeadlineTimer = setTimeout(
-              () => adapterController.abort(new Error("Adapter deadline exceeded")),
+              () => adapterController.abort(new HostError("Adapter deadline exceeded")),
               remaining
             );
             adapterDeadlineTimer.unref?.();
           }
-          const circuitBreaker = circuitBreakers.forAdapter(adapter);
+          const circuitBreaker = circuitBreakers.forAdapter(adapter, { tenantId, spaceId });
           const result2 = await executeWithAdapterRetry({
             ...circuitBreaker ? { circuitBreaker } : {},
             policy: step.retryPolicy ?? adapter.retryPolicy,
@@ -1570,13 +1717,15 @@ function createGovernedActionHost(options) {
             // Every await before the call happens here, before breaker
             // admission, so nothing awaits between admission and the adapter.
             prepareAttempt: async (attempt) => {
+              errorContext = executionErrorContext;
               await options.store.updateAdapterInvocation(adapterInvocationId, {
                 attempt,
                 updatedAt: now()
-              });
+              }, adapterInvocationScope);
             },
-            execute: (attempt, maxAttempts) => {
-              return adapter.execute(input, {
+            execute: async (attempt, maxAttempts) => {
+              errorContext = adapterErrorContext;
+              const adapterResult = await adapter.execute(input, {
                 tenantId,
                 spaceId,
                 actionInvocationId,
@@ -1588,6 +1737,8 @@ function createGovernedActionHost(options) {
                 ...deadlineMs ? { deadlineMs } : {},
                 ...adapterController ? { signal: adapterController.signal } : {}
               });
+              errorContext = executionErrorContext;
+              return adapterResult;
             },
             isSuccessful: (result3) => result3.success,
             getError: (result3) => result3.error,
@@ -1600,19 +1751,23 @@ function createGovernedActionHost(options) {
               return "transient_failure";
             }
           });
+          errorContext = adapterErrorContext;
           assertAdapterOutcomeConsistency(result2);
+          errorContext = executionErrorContext;
           if (!result2.success) {
+            const resultError = result2.error == null ? result2.error : redactErrorText(options.redactErrorText, adapterErrorContext, result2.error);
             const outcome = result2.outcome ?? "transient_failure";
             if (outcome === "ambiguous") {
               const evidence = result2.outcomeEvidence;
-              const message = result2.error ?? "Adapter outcome is ambiguous; external effect may or may not have been applied";
+              const reason = evidence?.reason == null ? resultError : redactErrorText(options.redactErrorText, adapterErrorContext, evidence.reason);
+              const message = resultError ?? "Adapter outcome is ambiguous; external effect may or may not have been applied";
               const adapterReconciliation = {
                 kind: "adapter_outcome_ambiguous",
                 adapterType: step.adapterType,
                 operation: step.operation,
                 vendor: adapter.vendor,
                 adapterInvocationId,
-                ...evidence?.reason ?? result2.error ? { reason: evidence?.reason ?? result2.error } : {},
+                ...evidence?.reason ?? result2.error ? { reason } : {},
                 ...evidence?.externalReference ? { externalReference: evidence.externalReference } : {},
                 message
               };
@@ -1620,7 +1775,7 @@ function createGovernedActionHost(options) {
                 status: "ambiguous",
                 error: message,
                 updatedAt: now()
-              });
+              }, adapterInvocationScope);
               await appendEvent(invocation, {
                 eventType: "AdapterInvocationAmbiguous",
                 subjectType: adapterEventSubject.subjectType,
@@ -1658,24 +1813,52 @@ function createGovernedActionHost(options) {
             }
             await options.store.updateAdapterInvocation(adapterInvocationId, {
               status: "failed",
-              error: result2.error ?? "Adapter failed",
+              error: resultError ?? "Adapter failed",
               updatedAt: now()
-            });
+            }, adapterInvocationScope);
             await appendEvent(invocation, {
               eventType: "AdapterInvocationFailed",
               subjectType: adapterEventSubject.subjectType,
               subjectId: adapterEventSubject.subjectId,
               payload: { adapterType: step.adapterType, operation: step.operation }
             }, `adapter:${stepIndex}:failed`);
-            return fail2(invocation, "failed", result2.error ?? "Adapter failed");
+            return fail2(invocation, "failed", resultError ?? "Adapter failed");
           }
           const resultRecord = result2;
-          const output = isRecord(resultRecord.output) ? resultRecord.output : Object.fromEntries(
+          let output = isRecord(resultRecord.output) ? resultRecord.output : Object.fromEntries(
             Object.entries(resultRecord).filter(
               ([key]) => key !== "success" && key !== "error"
             )
           );
           const handoff = result2.acceptedExternalOperation;
+          if (options.redactAdapterOutput) {
+            try {
+              output = options.redactAdapterOutput(action.actionId, step.adapterType, step.operation, output);
+              if (!isRecord(output)) throw new HostError("Adapter output redactor must return a non-null, non-array object.");
+            } catch {
+              const message = "Adapter output withheld: the output redactor failed after the external effect; reconciliation required.";
+              const reference = typeof handoff?.externalReference === "string" ? handoff.externalReference.trim() : "";
+              const acceptedAt = now();
+              const deadlineMs2 = action.execution?.completionDeadlineMs;
+              const pendingCompletion = pendingHandoff ?? (reference ? {
+                provider: adapter.vendor,
+                adapterType: step.adapterType,
+                operation: step.operation,
+                adapterInvocationId,
+                externalReference: reference,
+                acceptedAt,
+                ...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);
+              } catch {
+                throw new RecoverableFinalizationError(message);
+              }
+              return withConsistency({ actionInvocationId, status: "reconciliation_required", error: message, ...pendingCompletion ? { pendingCompletion } : {} }, action.actionId);
+            }
+          }
           if (handoff) {
             const reference = typeof handoff.externalReference === "string" ? handoff.externalReference.trim() : "";
             if (reference === "") {
@@ -1697,19 +1880,28 @@ 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) {
-              await options.store.updateAdapterInvocation(adapterInvocationId, { status: "succeeded", output, updatedAt: now() });
-              await persistInvocation(invocation, {
-                status: "reconciliation_required",
-                error: refuse,
-                ...pendingHandoff ? {} : { pendingCompletion: accepted }
-              });
+              try {
+                await persistReconciliationVerdict(invocation, {
+                  status: "reconciliation_required",
+                  error: refuse,
+                  ...pendingHandoff ? {} : { pendingCompletion: accepted }
+                });
+                await appendDegradedAdapterEvidence(false, refuse, pendingHandoff ? void 0 : accepted, output);
+              } catch {
+                throw new RecoverableFinalizationError(refuse);
+              }
               let error = refuse;
               try {
                 await externalCompletion.recordCompletionReconciliation(invocation, { externalReference: reference, provider: adapter.vendor }, refuse);
               } catch (logError) {
-                error = `${refuse} Reconciliation log unavailable: ${errorMessage(logError)}`;
+                error = `${refuse} Reconciliation log unavailable: ${caughtError({ actionId: invocation.actionId, source: "execution" }, logError)}`;
                 await options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, { error });
               }
+              try {
+                await options.store.updateAdapterInvocation(adapterInvocationId, { status: "succeeded", output, updatedAt: now() }, adapterInvocationScope);
+              } catch {
+                throw new RecoverableFinalizationError(refuse);
+              }
               return withConsistency({
                 actionInvocationId,
                 status: "reconciliation_required",
@@ -1736,7 +1928,7 @@ function createGovernedActionHost(options) {
             status: "succeeded",
             output,
             updatedAt: now()
-          });
+          }, adapterInvocationScope);
           if (options.extractExecutionAttestation) {
             const attestation = await options.extractExecutionAttestation({
               actionInvocationId,
@@ -1765,12 +1957,13 @@ function createGovernedActionHost(options) {
             }
           }, `adapter:${stepIndex}:succeeded`);
         } catch (error) {
-          const message = errorMessage(error);
+          if (error instanceof RecoverableFinalizationError) throw error;
+          const message = caughtError(isAdapterCircuitOpenError(error) ? adapterErrorContext : errorContext, error);
           await options.store.updateAdapterInvocation(adapterInvocationId, {
             status: "failed",
             error: message,
             updatedAt: now()
-          });
+          }, adapterInvocationScope);
           if (isAdapterCircuitOpenError(error)) {
             await appendEvent(invocation, {
               eventType: "AdapterInvocationFailed",
@@ -1801,7 +1994,7 @@ function createGovernedActionHost(options) {
             try {
               await externalCompletion.recordCompletionReconciliation(invocation, { externalReference: pendingHandoff.externalReference, provider: pendingHandoff.provider, kind: "obligations" }, message);
             } catch (logError) {
-              error = `${message} Reconciliation log unavailable: ${errorMessage(logError)}`;
+              error = `${message} Reconciliation log unavailable: ${caughtError({ actionId: invocation.actionId, source: "execution" }, logError)}`;
               await options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, { error });
             }
             return withConsistency({ actionInvocationId, status: "reconciliation_required", error, pendingCompletion: pendingHandoff }, action.actionId);
@@ -1825,9 +2018,12 @@ function createGovernedActionHost(options) {
                 transaction
               );
             }
+            if (pendingTransitionEvent) {
+              await appendEvent(invocation, pendingTransitionEvent, "state:transition", 1, transaction);
+            }
             if (invocation.leaseOwner && invocation.leaseToken !== void 0) {
               if (!transaction.updateLeasedActionInvocation) {
-                throw new Error("Leased atomic finalization requires transaction-scoped fencing support.");
+                throw new HostError("Leased atomic finalization requires transaction-scoped fencing support.");
               }
               const updated = await transaction.updateLeasedActionInvocation({
                 id: actionInvocationId,
@@ -1860,6 +2056,9 @@ function createGovernedActionHost(options) {
             for (const [index, event] of domainEvents.entries()) {
               await appendEvent(invocation, event, `domain:${index}`, action.version);
             }
+            if (pendingTransitionEvent) {
+              await appendEvent(invocation, pendingTransitionEvent, "state:transition", 1);
+            }
           }
           await persistInvocation(invocation, finalPatch);
         }
@@ -1879,7 +2078,15 @@ function createGovernedActionHost(options) {
       };
     } catch (error) {
       if (error instanceof RecoverableFinalizationError) throw error;
-      return fail2(invocation, "failed", errorMessage(error));
+      if (retryableGovernance && isRetryableExecutionError(error)) {
+        const reason = executionReasonOverride === "approval_resume" ? "approval resume" : !invocation.leaseOwner || invocation.leaseToken === void 0 ? "not leased" : !action.idempotent ? "action not idempotent" : invocation.attemptCount >= retryableExecutionMaxAttempts ? `attempts exhausted (${invocation.attemptCount}/${retryableExecutionMaxAttempts})` : void 0;
+        if (!reason) throw error;
+        return fail2(invocation, "failed", caughtError(
+          { actionId: invocation.actionId, source: "execution" },
+          new Error(`Retryable execution not retried: ${reason}; ${errorMessage(error)}`)
+        ));
+      }
+      return fail2(invocation, "failed", caughtError({ actionId: invocation.actionId, source: "execution" }, error));
     }
   }
   async function resumeApprovedInvocation(actionInvocationId, tenantId, spaceId, decision) {
@@ -1962,9 +2169,9 @@ function createGovernedActionHost(options) {
   }
   async function recordExecutionAttestation(actionInvocationId, tenantId, spaceId, attestation, adapterInvocationId) {
     const governanceStore = asGovernanceStore(options.store);
-    if (!governanceStore) throw new Error("Execution attestations require a governance-capable store.");
+    if (!governanceStore) throw new HostError("Execution attestations require a governance-capable store.");
     const invocation = await options.store.getActionInvocation(actionInvocationId, tenantId, spaceId);
-    if (!invocation) throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
+    if (!invocation) throw new HostError(`ActionInvocation not found: ${actionInvocationId}`);
     const id = lifecycleId("att", actionInvocationId, adapterInvocationId ?? `${attestation.provider}:${attestation.operation}:${attestation.externalOperationId ?? "external"}`);
     await governanceStore.appendExecutionAttestation({
       ...attestation,
@@ -2042,11 +2249,11 @@ function createGovernedActionHost(options) {
         ...traceContext ? { traceContext } : {}
       };
       if (transaction) {
-        if (!transaction.appendEventWithOutbox) throw new Error("Outbox egress requires an atomic transaction with appendEventWithOutbox.");
+        if (!transaction.appendEventWithOutbox) throw new HostError("Outbox egress requires an atomic transaction with appendEventWithOutbox.");
         await transaction.appendEventWithOutbox(envelope, metadata);
       } else {
         const outboxStore = asOutboxStore(options.store);
-        if (!outboxStore) throw new Error("Outbox egress requires an outbox-capable Platform Host store.");
+        if (!outboxStore) throw new HostError("Outbox egress requires an outbox-capable Platform Host store.");
         await outboxStore.appendEventWithOutbox(envelope, metadata);
       }
     } else {
@@ -2063,12 +2270,20 @@ function createGovernedActionHost(options) {
       ...invocation.hitlRiskTier ? { hitlRiskTier: invocation.hitlRiskTier } : {}
     };
   }
+  async function persistReconciliationVerdict(invocation, patch) {
+    try {
+      await persistInvocation(invocation, patch);
+    } catch (error) {
+      if (error instanceof RecoverableFinalizationError) throw error;
+      await persistInvocation(invocation, patch);
+    }
+  }
   async function persistInvocation(invocation, patch) {
     const previousStatus = invocation.status;
     if (invocation.leaseOwner && invocation.leaseToken !== void 0) {
       const recoverable = options.store;
       if (!recoverable.updateLeasedActionInvocation) {
-        throw new Error("Leased execution requires a fencing-capable PlatformHostStore.");
+        throw new HostError("Leased execution requires a fencing-capable PlatformHostStore.");
       }
       const updated = await recoverable.updateLeasedActionInvocation({
         id: invocation.id,
@@ -2093,6 +2308,8 @@ function createGovernedActionHost(options) {
   const externalCompletion = createExternalCompletionLifecycle({
     store: options.store,
     telemetry: options.telemetry,
+    redactErrorText: options.redactErrorText,
+    redactExternalCompletionResult: options.redactExternalCompletionResult,
     eventResultFields,
     now,
     actionResolver,
@@ -2173,9 +2390,6 @@ function initialState(machine) {
 function isTerminal(status) {
   return ["completed", "failed", "blocked_by_policy", "reconciliation_required", "validation_failed"].includes(status);
 }
-function isRecord(value) {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}
 function isAdmissionTime(value) {
   return value instanceof Date && Number.isFinite(value.getTime());
 }
@@ -2478,6 +2692,15 @@ var MemoryPlatformHostStore = class {
         appendEventWithOutbox: (event, metadata) => appendPending(event, metadata),
         nextEventSequence: async (tenantId, spaceId) => (await this.listEvents(tenantId, spaceId)).length + pendingEvents.filter((candidate) => candidate.event.tenantId === tenantId && candidate.event.spaceId === spaceId).length + 1,
         listEvents: async (tenantId, spaceId) => [...await this.listEvents(tenantId, spaceId), ...pendingEvents.map((candidate) => candidate.event).filter((event) => event.tenantId === tenantId && event.spaceId === spaceId)],
+        getEntityStateSource: async (tenantId, spaceId, entityType, entityId) => {
+          let source = await this.getEntityStateSource(tenantId, spaceId, entityType, entityId);
+          for (const { event } of pendingEvents) {
+            if (event.tenantId !== tenantId || event.spaceId !== spaceId || event.subjectType !== entityType || event.subjectId !== entityId) continue;
+            const state = event.payload?.toState;
+            if (typeof state === "string") source = typeof event.actionInvocationId === "string" ? { state, actionInvocationId: event.actionInvocationId } : void 0;
+          }
+          return source;
+        },
         getEntityState: async (tenantId, spaceId, entityType, entityId) => {
           let state = await this.getEntityState(tenantId, spaceId, entityType, entityId);
           for (const pending of pendingEvents) {
@@ -2625,11 +2848,11 @@ var MemoryPlatformHostStore = class {
     if (this.adapterInvocations.some((candidate) => candidate.id === record.id)) return;
     this.adapterInvocations.push(record);
   }
-  async getAdapterInvocation(id) {
-    return this.adapterInvocations.find((candidate) => candidate.id === id);
+  async getAdapterInvocation(id, scope) {
+    return this.adapterInvocations.find((candidate) => candidate.id === id && (scope === void 0 || candidate.tenantId === scope.tenantId && candidate.spaceId === scope.spaceId && candidate.actionInvocationId === scope.actionInvocationId));
   }
-  async updateAdapterInvocation(id, patch) {
-    const record = this.adapterInvocations.find((candidate) => candidate.id === id);
+  async updateAdapterInvocation(id, patch, scope) {
+    const record = this.adapterInvocations.find((candidate) => candidate.id === id && (scope === void 0 || candidate.tenantId === scope.tenantId && candidate.spaceId === scope.spaceId && candidate.actionInvocationId === scope.actionInvocationId));
     if (!record) throw new Error(`AdapterInvocation not found: ${id}`);
     Object.assign(record, patch);
   }
@@ -2734,6 +2957,15 @@ var MemoryPlatformHostStore = class {
   async nextEventSequence(tenantId, spaceId) {
     return this.events.filter((event) => event.tenantId === tenantId && event.spaceId === spaceId).length + 1;
   }
+  async getEntityStateSource(tenantId, spaceId, entityType, entityId) {
+    let source;
+    for (const event of this.events) {
+      if (event.tenantId !== tenantId || event.spaceId !== spaceId || event.subjectType !== entityType || event.subjectId !== entityId) continue;
+      const state = event.payload?.toState;
+      if (typeof state === "string") source = typeof event.actionInvocationId === "string" ? { state, actionInvocationId: event.actionInvocationId } : void 0;
+    }
+    return source;
+  }
   async getEntityState(tenantId, spaceId, entityType, entityId) {
     let state;
     for (const event of this.events) {
@@ -2906,6 +3138,7 @@ var PostgresPlatformHostStore = class _PostgresPlatformHostStore {
           appendEventWithOutbox: (event, metadata) => scoped.appendEventWithOutbox(event, metadata),
           nextEventSequence: (tenantId, spaceId) => scoped.nextEventSequence(tenantId, spaceId),
           listEvents: (tenantId, spaceId) => scoped.listEvents(tenantId, spaceId),
+          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)
@@ -3359,19 +3592,19 @@ var PostgresPlatformHostStore = class _PostgresPlatformHostStore {
       ]
     );
   }
-  async getAdapterInvocation(id) {
+  async getAdapterInvocation(id, scope) {
     const result = await this.sql.query(
-      `SELECT * FROM fabric_platform.adapter_invocations WHERE id=$1`,
-      [id]
+      `SELECT * FROM fabric_platform.adapter_invocations WHERE id=$1${scope ? " AND tenant_id=$2 AND space_id=$3 AND action_invocation_id=$4" : ""}`,
+      [id, ...scope ? [scope.tenantId, scope.spaceId, scope.actionInvocationId] : []]
     );
     return result.rows[0] ? toAdapterRecord(result.rows[0]) : void 0;
   }
-  async updateAdapterInvocation(id, patch) {
+  async updateAdapterInvocation(id, patch, scope) {
     await this.sql.query(
       `UPDATE fabric_platform.adapter_invocations SET
 			 status=COALESCE($2,status), output=COALESCE($3::jsonb,output),
 			 error=CASE WHEN $4::boolean THEN $5 ELSE error END,
-			 attempt=COALESCE($6,attempt), updated_at=COALESCE($7,now()) WHERE id=$1`,
+			 attempt=COALESCE($6,attempt), updated_at=COALESCE($7,now()) WHERE id=$1${scope ? " AND tenant_id=$8 AND space_id=$9 AND action_invocation_id=$10" : ""}`,
       [
         id,
         patch.status ?? null,
@@ -3379,7 +3612,8 @@ var PostgresPlatformHostStore = class _PostgresPlatformHostStore {
         Object.hasOwn(patch, "error"),
         patch.error ?? null,
         patch.attempt ?? null,
-        patch.updatedAt ?? null
+        patch.updatedAt ?? null,
+        ...scope ? [scope.tenantId, scope.spaceId, scope.actionInvocationId] : []
       ]
     );
   }
@@ -3610,6 +3844,16 @@ var PostgresPlatformHostStore = class _PostgresPlatformHostStore {
     );
     return Number(result.rows[0].next_sequence);
   }
+  async getEntityStateSource(tenantId, spaceId, entityType, entityId) {
+    const result = await this.sql.query(
+      `SELECT payload->>'toState' AS state, action_invocation_id FROM fabric_platform.asset_events
+			 WHERE tenant_id=$1 AND space_id=$2 AND subject_type=$3 AND subject_id=$4
+			 AND payload ? 'toState' ORDER BY sequence DESC LIMIT 1`,
+      [tenantId, spaceId, entityType, entityId]
+    );
+    const row = result.rows[0];
+    return typeof row?.state === "string" && typeof row.action_invocation_id === "string" ? { state: row.state, actionInvocationId: row.action_invocation_id } : void 0;
+  }
   async getEntityState(tenantId, spaceId, entityType, entityId) {
     const result = await this.sql.query(
       `SELECT payload->>'toState' AS state FROM fabric_platform.asset_events
@@ -4002,8 +4246,6 @@ function toOutboxRequeueRecord(row, prefix) {
     priorLeaseToken: Number(field("prior_lease_token"))
   };
 }
-
-// src/worker.ts
 var DEFAULT_BATCH_SIZE = 10;
 var DEFAULT_LEASE_DURATION_MS = 5 * 6e4;
 var DEFAULT_POLL_INTERVAL_MS = 1e3;
@@ -4052,6 +4294,7 @@ async function runPlatformActionWorkerCycle(options) {
   let completed = 0;
   let failed = 0;
   let waitingForApproval = 0;
+  let deferred = 0;
   for (const invocation of claimed) {
     const stopHeartbeat = startLeaseHeartbeat(options, invocation, leaseDurationMs);
     try {
@@ -4065,7 +4308,8 @@ async function runPlatformActionWorkerCycle(options) {
       else if (result2.status === "waiting_for_approval") waitingForApproval += 1;
       else failed += 1;
     } catch (error) {
-      failed += 1;
+      if (isRetryableExecutionError(error)) deferred += 1;
+      else failed += 1;
       options.onError?.(error, invocation);
     } finally {
       await stopHeartbeat();
@@ -4075,7 +4319,8 @@ async function runPlatformActionWorkerCycle(options) {
     claimed: claimed.length,
     completed,
     failed,
-    ...waitingForApproval > 0 ? { waitingForApproval } : {}
+    ...waitingForApproval > 0 ? { waitingForApproval } : {},
+    ...deferred > 0 ? { deferred } : {}
   };
   emitWorkerTelemetry(options.telemetry, "worker.cycle.completed", options.workerId, result);
   return result;
@@ -4302,6 +4547,32 @@ function submitInput(subject, scope, idempotencyKey) {
     idempotencyKey
   };
 }
+async function adapterProbe(subject) {
+  await subject.reset?.();
+  if (subject.ours.tenantId === subject.theirs.tenantId) fail("the two scopes must be in different tenants");
+  const suffix = globalThis.crypto.randomUUID();
+  const scope = {
+    tenantId: subject.ours.tenantId,
+    spaceId: `iso-probe-${suffix}`,
+    actionInvocationId: `iso_act_${suffix}`
+  };
+  const id = `iso_adp_${suffix}`;
+  const now = /* @__PURE__ */ new Date();
+  await subject.store.createAdapterInvocation({
+    id,
+    ...scope,
+    adapterType: "iso",
+    operation: "probe",
+    vendor: "iso",
+    status: "running",
+    input: {},
+    output: { probe: true },
+    attempt: 1,
+    createdAt: now,
+    updatedAt: now
+  });
+  return { id, scope };
+}
 function tenantIsolationChecks() {
   return [
     {
@@ -4446,6 +4717,54 @@ function tenantIsolationChecks() {
         if (leaked.length > 0) fail(`a viewer in the other tenant saw ${leaked.length} of our rows`);
         return [theirs.allowed ? "other tenant's viewer sees none of our rows" : "other tenant's viewer is denied"];
       }
+    },
+    {
+      id: "fabric.tenancy.adapter-invocation-read-scoped.v1",
+      async run(subject) {
+        const { id, scope } = await adapterProbe(subject);
+        try {
+          const theirs = { ...scope, tenantId: subject.theirs.tenantId, spaceId: subject.theirs.spaceId };
+          if (await subject.store.getAdapterInvocation(id, { ...scope, tenantId: subject.theirs.tenantId })) fail("an adapter invocation was readable under another tenant's scope");
+          if (await subject.store.getAdapterInvocation(id, theirs)) fail("an adapter invocation was readable under another tenant's scope");
+          if (await subject.store.getAdapterInvocation(id, { ...scope, spaceId: `${scope.spaceId}-other` })) fail("an adapter invocation was readable under another space's scope");
+          if (await subject.store.getAdapterInvocation(id, { ...scope, actionInvocationId: `${scope.actionInvocationId}-other` })) fail("an adapter invocation was readable under another action invocation's scope");
+          const ours = await subject.store.getAdapterInvocation(id, scope);
+          if (!ours || ours.id !== id || ours.tenantId !== scope.tenantId || ours.spaceId !== scope.spaceId || ours.actionInvocationId !== scope.actionInvocationId) fail("our own adapter invocation was not readable under our scope, so the check proves nothing");
+        } finally {
+          await subject.store.updateAdapterInvocation(id, { status: "failed", error: "tenant isolation probe; retired", updatedAt: /* @__PURE__ */ new Date() }, scope);
+        }
+        return ["adapter invocation readable under our scope and invisible outside it"];
+      }
+    },
+    {
+      id: "fabric.tenancy.adapter-invocation-write-scoped.v1",
+      async run(subject) {
+        const { id, scope } = await adapterProbe(subject);
+        const shape = (record) => JSON.stringify({ status: record.status, error: record.error, output: record.output, attempt: record.attempt });
+        try {
+          const before = await subject.store.getAdapterInvocation(id, scope);
+          if (!before) fail("our own adapter invocation was not readable under our scope, so the check proves nothing");
+          const untouched = shape(before);
+          for (const other of [
+            { ...scope, tenantId: subject.theirs.tenantId, spaceId: subject.theirs.spaceId },
+            { ...scope, tenantId: subject.theirs.tenantId },
+            { ...scope, spaceId: `${scope.spaceId}-other` },
+            { ...scope, actionInvocationId: `${scope.actionInvocationId}-other` }
+          ]) {
+            try {
+              await subject.store.updateAdapterInvocation(id, { status: "failed", error: "iso probe", updatedAt: /* @__PURE__ */ new Date() }, other);
+            } catch {
+            }
+            const after = await subject.store.getAdapterInvocation(id, scope);
+            if (!after || shape(after) !== untouched) fail("an adapter invocation changed under another scope");
+          }
+          await subject.store.updateAdapterInvocation(id, { status: "succeeded", updatedAt: /* @__PURE__ */ new Date() }, scope);
+          if ((await subject.store.getAdapterInvocation(id, scope))?.status !== "succeeded") fail("our own adapter invocation was not updated under our scope, so the check proves nothing");
+        } finally {
+          await subject.store.updateAdapterInvocation(id, { status: "failed", error: "tenant isolation probe; retired", updatedAt: /* @__PURE__ */ new Date() }, scope);
+        }
+        return ["adapter invocation untouched outside our scope and writable under ours"];
+      }
     }
   ];
 }