@fabricorg/platform-host 7.1.1 → 7.2.0

package/dist/index.cjs

@@ -284,6 +284,221 @@ function isPromiseLike(value) {
   );
 }
 
+// src/host-internals.ts
+function asAtomicMutationStore(store) {
+  const candidate = store;
+  return typeof candidate.transactionWithEvents === "function" ? store : void 0;
+}
+function asGovernanceStore(store) {
+  const candidate = store;
+  return typeof candidate.recordMutationGovernance === "function" && typeof candidate.appendPolicyObligations === "function" && typeof candidate.appendExecutionAttestation === "function" ? store : void 0;
+}
+function withoutPrivateHostFields(data, eventResultFields) {
+  return Object.fromEntries(
+    Object.entries(data).filter(([key]) => !eventResultFields.includes(key))
+  );
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function lifecycleId(prefix, invocationId, key) {
+  const safeKey = key.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 96);
+  return `${prefix}_${invocationId}_${safeKey}`;
+}
+function emitInvocationStatusTelemetry(invocation, status, telemetry, occurredAt, previousStatus) {
+  if (!status) return;
+  const event = status === "completed" ? { name: "invocation.completed", metricName: PLATFORM_HOST_METRIC_NAMES.invocationCompleted } : status === "blocked_by_policy" ? { name: "invocation.policy_blocked", metricName: PLATFORM_HOST_METRIC_NAMES.invocationPolicyBlocked } : status === "validation_failed" ? { name: "invocation.validation_failed", metricName: PLATFORM_HOST_METRIC_NAMES.invocationValidationFailed } : status === "waiting_for_approval" ? { name: "invocation.approval_waited", metricName: PLATFORM_HOST_METRIC_NAMES.invocationApprovalWaited } : status === "reconciliation_required" ? { name: "invocation.reconciliation_required", metricName: PLATFORM_HOST_METRIC_NAMES.invocationReconciliationRequired } : status === "failed" ? { name: "invocation.failed", metricName: PLATFORM_HOST_METRIC_NAMES.invocationFailed } : void 0;
+  if (!event) return;
+  emitPlatformHostTelemetry(telemetry, {
+    kind: "event",
+    name: event.name,
+    metricName: event.metricName,
+    occurredAt,
+    tenantId: invocation.tenantId,
+    spaceId: invocation.spaceId,
+    attributes: {
+      ...invocation.actionId ? { actionId: invocation.actionId } : {},
+      ...invocation.actionVersion !== void 0 ? { actionVersion: invocation.actionVersion } : {},
+      ...previousStatus ? { fromStatus: previousStatus } : {}
+    }
+  });
+}
+
+// src/external-completion.ts
+function createExternalCompletionLifecycle(deps) {
+  const { now, actionResolver, appendEvent, persistInvocation, actionResult: actionResult2, withConsistency, eventResultFields } = deps;
+  async function completeExternalInvocation(actionInvocationId, tenantId, spaceId, completion) {
+    if (typeof completion.externalReference !== "string" || completion.externalReference.trim() === "") {
+      throw new ExternalCompletionError("invalid_completion", "External completion must name the external reference it completes.");
+    }
+    if (completion.outcome !== "completed" && completion.outcome !== "failed") {
+      throw new ExternalCompletionError("invalid_completion", `External completion outcome must be "completed" or "failed", received "${String(completion.outcome)}".`);
+    }
+    const atomicStore = asAtomicMutationStore(deps.store);
+    if (atomicStore) {
+      return atomicStore.transactionWithEvents(async (transaction) => {
+        const read2 = transaction.getActionInvocationForUpdate ? await transaction.getActionInvocationForUpdate(actionInvocationId, tenantId, spaceId) : await deps.store.getActionInvocation(actionInvocationId, tenantId, spaceId);
+        return settleExternalCompletion(read2, actionInvocationId, completion, {
+          update: (patch) => transaction.updateActionInvocation(actionInvocationId, tenantId, spaceId, patch),
+          transaction
+        });
+      });
+    }
+    const read = await deps.store.getActionInvocation(actionInvocationId, tenantId, spaceId);
+    return settleExternalCompletion(read, actionInvocationId, completion, {
+      update: (patch) => deps.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, patch)
+    });
+  }
+  async function settleExternalCompletion(invocation, actionInvocationId, completion, writer) {
+    if (!invocation) throw new ExternalCompletionError("not_found", `ActionInvocation not found: ${actionInvocationId}`);
+    const recorded = invocation.externalCompletion;
+    const stillExecuting = !recorded && (invocation.status === "pending" || invocation.status === "running" && (invocation.leaseOwner !== void 0 || invocation.pendingCompletion?.parkedAt === void 0));
+    if (stillExecuting) {
+      throw new ExternalCompletionError("still_executing", `ActionInvocation ${actionInvocationId} is still executing; retry the completion after it parks.`);
+    }
+    if (recorded) {
+      if (recorded.externalReference !== completion.externalReference) {
+        throw new ExternalCompletionError("reference_mismatch", `ActionInvocation ${actionInvocationId} was completed by "${recorded.externalReference}", not "${completion.externalReference}".`);
+      }
+      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);
+      if (recorded.digest === incomingDigest) {
+        return withConsistency(actionResult2(invocation), invocation.actionId);
+      }
+      const message = recorded.outcome === completion.outcome ? `External operation "${completion.externalReference}" reported ${completion.outcome} again with different evidence.` : `External operation "${completion.externalReference}" reported ${completion.outcome} after reporting ${recorded.outcome}.`;
+      await recordCompletionReconciliation(invocation, { ...completion, kind: `contradicted:${incomingDigest.slice(0, 16)}` }, message);
+      await appendEvent(invocation, {
+        eventType: "ExternalOperationContradicted",
+        subjectType: "AdapterInvocation",
+        subjectId: invocation.pendingCompletion?.adapterInvocationId ?? actionInvocationId,
+        payload: { externalReference: completion.externalReference, recorded: recorded.outcome, reported: completion.outcome }
+      }, `external:${completion.externalReference}:contradicted:${completion.outcome}`, 1, writer.transaction);
+      await writer.update({ status: "reconciliation_required", error: message });
+      emitInvocationStatusTelemetry(invocation, "reconciliation_required", deps.telemetry, now(), invocation.status);
+      return withConsistency(actionResult2({ ...invocation, status: "reconciliation_required", error: message }), invocation.actionId);
+    }
+    const pending = invocation.pendingCompletion;
+    if (!pending) {
+      const action = actionResolver(invocation.actionId);
+      if ((action?.execution?.completion ?? "immediate") === "immediate") {
+        throw new ExternalCompletionError("immediate_contract", `Action ${invocation.actionId} declares immediate completion; nothing external completes it.`);
+      }
+      throw new ExternalCompletionError("not_awaiting", `ActionInvocation ${actionInvocationId} is not awaiting an external completion.`);
+    }
+    if (pending.externalReference !== completion.externalReference) {
+      throw new ExternalCompletionError("reference_mismatch", `ActionInvocation ${actionInvocationId} awaits "${pending.externalReference}", not "${completion.externalReference}".`);
+    }
+    if (completion.provider !== void 0 && completion.provider !== pending.provider) {
+      throw new ExternalCompletionError("provider_mismatch", `ActionInvocation ${actionInvocationId} awaits completion from "${pending.provider}", not "${completion.provider}".`);
+    }
+    const recordedAt = now();
+    const externalCompletion = {
+      ...completion,
+      provider: completion.provider ?? pending.provider,
+      observedAt: completion.observedAt instanceof Date ? completion.observedAt.toISOString() : completion.observedAt,
+      recordedAt,
+      digest: completionDigest(completion, completion.provider ?? pending.provider)
+    };
+    const subject = { subjectType: "AdapterInvocation", subjectId: pending.adapterInvocationId };
+    const settles = invocation.status === "running" && pending.parkedAt !== void 0 || invocation.status === "reconciliation_required" && invocation.error?.includes("did not complete by") === true;
+    if (completion.outcome === "completed") {
+      const action = actionResolver(invocation.actionId);
+      const merged = withoutPrivateHostFields({ ...invocation.result, ...completion.result ?? {} }, eventResultFields);
+      if (action?.resultSchema) {
+        const parsedResult = action.resultSchema.safeParse(merged);
+        if (!parsedResult.success) {
+          throw new ExternalCompletionError("result_invalid", `External completion result validation failed at ${parsedResult.error.issues.map((issue) => issue.path.map(String).join(".") || "result").join(", ")}`);
+        }
+      }
+      await deps.store.updateAdapterInvocation(pending.adapterInvocationId, {
+        ...completion.result ? { output: withoutPrivateHostFields(completion.result, eventResultFields) } : {},
+        updatedAt: recordedAt
+      });
+      await appendEvent(invocation, {
+        eventType: "ExternalOperationCompleted",
+        ...subject,
+        payload: { externalReference: pending.externalReference, provider: pending.provider, ...completion.result ? { result: withoutPrivateHostFields(completion.result, eventResultFields) } : {} }
+      }, `external:${pending.adapterInvocationId}:completed`, 1, writer.transaction);
+      const patch2 = settles ? { status: "completed", result: merged, externalCompletion, pendingCompletion: void 0, error: void 0 } : { externalCompletion, pendingCompletion: void 0 };
+      await writer.update(patch2);
+      if (settles) emitInvocationStatusTelemetry(invocation, "completed", deps.telemetry, now(), invocation.status);
+      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 appendEvent(invocation, {
+      eventType: "ExternalOperationFailed",
+      ...subject,
+      payload: { externalReference: pending.externalReference, provider: pending.provider, error }
+    }, `external:${pending.adapterInvocationId}:failed`, 1, writer.transaction);
+    const patch = settles ? { status: "failed", error, externalCompletion, pendingCompletion: void 0 } : { externalCompletion, pendingCompletion: void 0 };
+    await writer.update(patch);
+    if (settles) emitInvocationStatusTelemetry(invocation, "failed", deps.telemetry, now(), invocation.status);
+    return withConsistency(actionResult2({ ...invocation, ...patch }), invocation.actionId);
+  }
+  function completionDigest(completion, provider) {
+    return crypto.createHash("sha256").update(canonicalJson({
+      provider: provider ?? null,
+      externalReference: completion.externalReference,
+      outcome: completion.outcome,
+      result: completion.result ?? null,
+      error: completion.error ?? null,
+      evidenceReferences: completion.evidenceReferences ?? null
+    })).digest("hex");
+  }
+  async function recordCompletionReconciliation(invocation, completion, reason) {
+    const governanceStore = asGovernanceStore(deps.store);
+    if (!governanceStore) throw new Error("External completion reconciliation requires a governance-capable store.");
+    const provider = completion.provider ?? invocation.pendingCompletion?.provider ?? invocation.externalCompletion?.provider ?? "external";
+    const seed = crypto.createHash("sha256").update(`${provider}\0${completion.externalReference}\0${completion.kind ?? "refused"}`).digest("hex").slice(0, 32);
+    await governanceStore.appendExternalReconciliation({
+      id: lifecycleId("rec", invocation.id, `ext:${seed}`),
+      actionInvocationId: invocation.id,
+      tenantId: invocation.tenantId,
+      spaceId: invocation.spaceId,
+      status: "pending",
+      provider,
+      externalOperationId: completion.externalReference,
+      attempt: 1,
+      reason,
+      ...completion.evidenceReferences ? { evidenceReferences: completion.evidenceReferences } : {},
+      observedAt: now()
+    });
+  }
+  async function reconcileOverdueCompletions(input = {}) {
+    const recoverable = deps.store;
+    if (!recoverable.listActionInvocations) {
+      throw new Error("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.");
+    }
+    const current = input.now ?? now();
+    const candidates = await recoverable.listActionInvocations({
+      statuses: ["running"],
+      completionDueBefore: current,
+      unleased: true,
+      ...input.tenantId ? { tenantId: input.tenantId } : {},
+      ...input.spaceId ? { spaceId: input.spaceId } : {},
+      limit: Math.max(1, Math.min(input.limit ?? 100, 1e3))
+    });
+    const overdue = [];
+    for (const invocation of candidates) {
+      const pending = invocation.pendingCompletion;
+      if (!pending?.dueAt || pending.dueAt.getTime() > current.getTime()) continue;
+      if (invocation.leaseOwner) continue;
+      const message = `External operation "${pending.externalReference}" from ${pending.provider} did not complete by ${pending.dueAt.toISOString()}.`;
+      await recordCompletionReconciliation(invocation, { externalReference: pending.externalReference, provider: pending.provider, kind: "overdue" }, message);
+      await persistInvocation(invocation, { status: "reconciliation_required", error: message });
+      overdue.push(invocation.id);
+    }
+    return { overdue };
+  }
+  return { completeExternalInvocation, reconcileOverdueCompletions, recordCompletionReconciliation };
+}
+
 // src/host.ts
 var DEFAULT_EXTRACT_EVENTS = (data) => {
   const value = data._events;
@@ -500,24 +715,24 @@ function createGovernedActionHost(options) {
     }
     const action = actionResolver(invocation.actionId);
     if (!action) {
-      return fail(invocation, "failed", `Unknown action: ${invocation.actionId}`);
+      return fail2(invocation, "failed", `Unknown action: ${invocation.actionId}`);
     }
     if (action.kind === "saga") {
-      return fail(
+      return fail2(
         invocation,
         "failed",
         `Saga action ${invocation.actionId} requires a durable PlatformActionDispatcher and cannot execute as an atomic Host action.`
       );
     }
     if (resumingRunningInvocation && invocation.attemptCount === 0 && !invocation.leaseOwner && !action.idempotent) {
-      return fail(
+      return fail2(
         invocation,
         "failed",
         `Interrupted inline action ${invocation.actionId} is not declared idempotent; manual reconciliation is required.`
       );
     }
     if (invocation.attemptCount > 1 && !action.idempotent) {
-      return fail(
+      return fail2(
         invocation,
         "failed",
         `Interrupted action ${invocation.actionId} is not declared idempotent; manual reconciliation is required.`
@@ -541,12 +756,12 @@ function createGovernedActionHost(options) {
       const parsed = action.schema.safeParse(invocation.parameters);
       if (!parsed.success) {
         const message = parsed.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
-        return fail(invocation, "validation_failed", message);
+        return fail2(invocation, "validation_failed", message);
       }
       if (options.resolveMutationGovernance && !invocation.mutationFootprint) {
         const governanceStore2 = asGovernanceStore(options.store);
         if (!governanceStore2) {
-          return fail(invocation, "failed", "The configured mutation-governance resolver requires a governance-capable store.");
+          return fail2(invocation, "failed", "The configured mutation-governance resolver requires a governance-capable store.");
         }
         const context = await options.resolveMutationGovernance({
           actionInvocationId,
@@ -564,7 +779,7 @@ function createGovernedActionHost(options) {
         const hitlParameters = isRecord(parsed.data) ? parsed.data : invocation.parameters;
         const approvalStore = asApprovalStore(options.store);
         if (!approvalStore) {
-          return fail(
+          return fail2(
             invocation,
             "failed",
             "The configured HITL evaluator requires a store with approval persistence support."
@@ -595,7 +810,7 @@ function createGovernedActionHost(options) {
           );
         }
         if (invocation.hitlRoute === "rejected") {
-          return fail(
+          return fail2(
             invocation,
             "failed",
             `HITL rejected: ${invocation.hitlReason ?? "no reason provided"}`
@@ -614,7 +829,7 @@ function createGovernedActionHost(options) {
       const authorizationInput = toAuthorizationInput(action, invocation);
       const executionReason = executionReasonOverride ?? (invocation.attemptCount > 1 || resumingRunningInvocation && invocation.attemptCount === 0 ? "recovery" : invocation.executionReason ?? "initial");
       if (!await options.authorization.checkEntitlement(authorizationInput)) {
-        return fail(
+        return fail2(
           invocation,
           "failed",
           `Module "${action.namespace}" is no longer enabled for tenant ${tenantId}`
@@ -654,7 +869,7 @@ function createGovernedActionHost(options) {
       }) : await options.authorization.authorize(authorizationInput);
       if (!executionAuthorized) {
         if (!action.execution) {
-          return fail(invocation, "failed", `Actor ${invocation.actorId} is not authorized to execute action ${action.actionId}`);
+          return fail2(invocation, "failed", `Actor ${invocation.actorId} is not authorized to execute action ${action.actionId}`);
         }
         const reconciliation = {
           kind: "authorization_denied",
@@ -704,12 +919,12 @@ function createGovernedActionHost(options) {
           subjectId: actionInvocationId,
           payload: { actionId: action.actionId, policyId: aggregate.policyId, reason }
         }, `compliance:${aggregate.policyId}`);
-        return fail(invocation, "blocked_by_policy", reason);
+        return fail2(invocation, "blocked_by_policy", reason);
       }
       if (options.resolvePolicyObligations) {
         const governanceStore2 = asGovernanceStore(options.store);
         if (!governanceStore2) {
-          return fail(invocation, "failed", "Policy obligations require a governance-capable store.");
+          return fail2(invocation, "failed", "Policy obligations require a governance-capable store.");
         }
         const existing = await governanceStore2.listPolicyObligations(actionInvocationId, tenantId, spaceId);
         if (existing.length === 0) {
@@ -824,7 +1039,7 @@ function createGovernedActionHost(options) {
         data = executed.data;
         domainEvents = executed.domainEvents;
       } catch (error) {
-        return fail(invocation, "failed", errorMessage(error));
+        return fail2(invocation, "failed", errorMessage(error));
       }
       let pendingHandoff = invocation.pendingCompletion;
       for (const [stepIndex, step] of (action.adapterSteps ?? []).entries()) {
@@ -1004,7 +1219,7 @@ function createGovernedActionHost(options) {
               subjectId: adapterEventSubject.subjectId,
               payload: { adapterType: step.adapterType, operation: step.operation }
             }, `adapter:${stepIndex}:failed`);
-            return fail(invocation, "failed", result2.error ?? "Adapter failed");
+            return fail2(invocation, "failed", result2.error ?? "Adapter failed");
           }
           const resultRecord = result2;
           const output = isRecord(resultRecord.output) ? resultRecord.output : Object.fromEntries(
@@ -1042,7 +1257,7 @@ function createGovernedActionHost(options) {
               });
               let error = refuse;
               try {
-                await recordCompletionReconciliation(invocation, { externalReference: reference, provider: adapter.vendor }, refuse);
+                await externalCompletion.recordCompletionReconciliation(invocation, { externalReference: reference, provider: adapter.vendor }, refuse);
               } catch (logError) {
                 error = `${refuse} Reconciliation log unavailable: ${errorMessage(logError)}`;
                 await options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, { error });
@@ -1108,7 +1323,7 @@ function createGovernedActionHost(options) {
             error: message,
             updatedAt: now()
           });
-          return fail(invocation, "failed", message);
+          return fail2(invocation, "failed", message);
         } finally {
           if (adapterDeadlineTimer) clearTimeout(adapterDeadlineTimer);
         }
@@ -1123,14 +1338,14 @@ function createGovernedActionHost(options) {
             await persistInvocation(invocation, { status: "reconciliation_required", error: message });
             let error = message;
             try {
-              await recordCompletionReconciliation(invocation, { externalReference: pendingHandoff.externalReference, provider: pendingHandoff.provider, kind: "obligations" }, message);
+              await externalCompletion.recordCompletionReconciliation(invocation, { externalReference: pendingHandoff.externalReference, provider: pendingHandoff.provider, kind: "obligations" }, message);
             } catch (logError) {
               error = `${message} Reconciliation log unavailable: ${errorMessage(logError)}`;
               await options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, { error });
             }
             return withConsistency({ actionInvocationId, status: "reconciliation_required", error, pendingCompletion: pendingHandoff }, action.actionId);
           }
-          return fail(invocation, "failed", message);
+          return fail2(invocation, "failed", message);
         }
       }
       const result = withoutPrivateHostFields(data, eventResultFields);
@@ -1203,7 +1418,7 @@ function createGovernedActionHost(options) {
       };
     } catch (error) {
       if (error instanceof RecoverableFinalizationError) throw error;
-      return fail(invocation, "failed", errorMessage(error));
+      return fail2(invocation, "failed", errorMessage(error));
     }
   }
   async function resumeApprovedInvocation(actionInvocationId, tenantId, spaceId, decision) {
@@ -1222,7 +1437,7 @@ function createGovernedActionHost(options) {
       };
     }
     const action = actionResolver(invocation.actionId);
-    if (!action) return fail(invocation, "failed", `Unknown action: ${invocation.actionId}`);
+    if (!action) return fail2(invocation, "failed", `Unknown action: ${invocation.actionId}`);
     const approvalAuthorizationInput = toAuthorizationInput(action, {
       tenantId,
       spaceId,
@@ -1316,175 +1531,6 @@ function createGovernedActionHost(options) {
       spaceId
     });
   }
-  async function completeExternalInvocation(actionInvocationId, tenantId, spaceId, completion) {
-    if (typeof completion.externalReference !== "string" || completion.externalReference.trim() === "") {
-      throw new ExternalCompletionError("invalid_completion", "External completion must name the external reference it completes.");
-    }
-    if (completion.outcome !== "completed" && completion.outcome !== "failed") {
-      throw new ExternalCompletionError("invalid_completion", `External completion outcome must be "completed" or "failed", received "${String(completion.outcome)}".`);
-    }
-    const atomicStore = asAtomicMutationStore(options.store);
-    if (atomicStore) {
-      return atomicStore.transactionWithEvents(async (transaction) => {
-        const read2 = transaction.getActionInvocationForUpdate ? await transaction.getActionInvocationForUpdate(actionInvocationId, tenantId, spaceId) : await options.store.getActionInvocation(actionInvocationId, tenantId, spaceId);
-        return settleExternalCompletion(read2, actionInvocationId, completion, {
-          update: (patch) => transaction.updateActionInvocation(actionInvocationId, tenantId, spaceId, patch),
-          transaction
-        });
-      });
-    }
-    const read = await options.store.getActionInvocation(actionInvocationId, tenantId, spaceId);
-    return settleExternalCompletion(read, actionInvocationId, completion, {
-      update: (patch) => options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, patch)
-    });
-  }
-  async function settleExternalCompletion(invocation, actionInvocationId, completion, writer) {
-    if (!invocation) throw new ExternalCompletionError("not_found", `ActionInvocation not found: ${actionInvocationId}`);
-    const recorded = invocation.externalCompletion;
-    const stillExecuting = !recorded && (invocation.status === "pending" || invocation.status === "running" && (invocation.leaseOwner !== void 0 || invocation.pendingCompletion?.parkedAt === void 0));
-    if (stillExecuting) {
-      throw new ExternalCompletionError("still_executing", `ActionInvocation ${actionInvocationId} is still executing; retry the completion after it parks.`);
-    }
-    if (recorded) {
-      if (recorded.externalReference !== completion.externalReference) {
-        throw new ExternalCompletionError("reference_mismatch", `ActionInvocation ${actionInvocationId} was completed by "${recorded.externalReference}", not "${completion.externalReference}".`);
-      }
-      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);
-      if (recorded.digest === incomingDigest) {
-        return withConsistency(actionResult(invocation), invocation.actionId);
-      }
-      const message = recorded.outcome === completion.outcome ? `External operation "${completion.externalReference}" reported ${completion.outcome} again with different evidence.` : `External operation "${completion.externalReference}" reported ${completion.outcome} after reporting ${recorded.outcome}.`;
-      await recordCompletionReconciliation(invocation, { ...completion, kind: `contradicted:${incomingDigest.slice(0, 16)}` }, message);
-      await appendEvent(invocation, {
-        eventType: "ExternalOperationContradicted",
-        subjectType: "AdapterInvocation",
-        subjectId: invocation.pendingCompletion?.adapterInvocationId ?? actionInvocationId,
-        payload: { externalReference: completion.externalReference, recorded: recorded.outcome, reported: completion.outcome }
-      }, `external:${completion.externalReference}:contradicted:${completion.outcome}`, 1, writer.transaction);
-      await writer.update({ status: "reconciliation_required", error: message });
-      emitInvocationStatusTelemetry(invocation, "reconciliation_required", options.telemetry, now(), invocation.status);
-      return withConsistency(actionResult({ ...invocation, status: "reconciliation_required", error: message }), invocation.actionId);
-    }
-    const pending = invocation.pendingCompletion;
-    if (!pending) {
-      const action = actionResolver(invocation.actionId);
-      if ((action?.execution?.completion ?? "immediate") === "immediate") {
-        throw new ExternalCompletionError("immediate_contract", `Action ${invocation.actionId} declares immediate completion; nothing external completes it.`);
-      }
-      throw new ExternalCompletionError("not_awaiting", `ActionInvocation ${actionInvocationId} is not awaiting an external completion.`);
-    }
-    if (pending.externalReference !== completion.externalReference) {
-      throw new ExternalCompletionError("reference_mismatch", `ActionInvocation ${actionInvocationId} awaits "${pending.externalReference}", not "${completion.externalReference}".`);
-    }
-    if (completion.provider !== void 0 && completion.provider !== pending.provider) {
-      throw new ExternalCompletionError("provider_mismatch", `ActionInvocation ${actionInvocationId} awaits completion from "${pending.provider}", not "${completion.provider}".`);
-    }
-    const recordedAt = now();
-    const externalCompletion = {
-      ...completion,
-      provider: completion.provider ?? pending.provider,
-      observedAt: completion.observedAt instanceof Date ? completion.observedAt.toISOString() : completion.observedAt,
-      recordedAt,
-      digest: completionDigest(completion, completion.provider ?? pending.provider)
-    };
-    const subject = { subjectType: "AdapterInvocation", subjectId: pending.adapterInvocationId };
-    const settles = invocation.status === "running" && pending.parkedAt !== void 0 || invocation.status === "reconciliation_required" && invocation.error?.includes("did not complete by") === true;
-    if (completion.outcome === "completed") {
-      const action = actionResolver(invocation.actionId);
-      const merged = withoutPrivateHostFields({ ...invocation.result, ...completion.result ?? {} }, eventResultFields);
-      if (action?.resultSchema) {
-        const parsedResult = action.resultSchema.safeParse(merged);
-        if (!parsedResult.success) {
-          throw new ExternalCompletionError("result_invalid", `External completion result validation failed at ${parsedResult.error.issues.map((issue) => issue.path.map(String).join(".") || "result").join(", ")}`);
-        }
-      }
-      await options.store.updateAdapterInvocation(pending.adapterInvocationId, {
-        ...completion.result ? { output: withoutPrivateHostFields(completion.result, eventResultFields) } : {},
-        updatedAt: recordedAt
-      });
-      await appendEvent(invocation, {
-        eventType: "ExternalOperationCompleted",
-        ...subject,
-        payload: { externalReference: pending.externalReference, provider: pending.provider, ...completion.result ? { result: withoutPrivateHostFields(completion.result, eventResultFields) } : {} }
-      }, `external:${pending.adapterInvocationId}:completed`, 1, writer.transaction);
-      const patch2 = settles ? { status: "completed", result: merged, externalCompletion, pendingCompletion: void 0, error: void 0 } : { externalCompletion, pendingCompletion: void 0 };
-      await writer.update(patch2);
-      if (settles) emitInvocationStatusTelemetry(invocation, "completed", options.telemetry, now(), invocation.status);
-      return withConsistency(actionResult({ ...invocation, ...patch2, result: settles ? merged : invocation.result, ...settles ? { error: void 0 } : {} }), invocation.actionId);
-    }
-    const error = completion.error ?? `External operation "${pending.externalReference}" failed.`;
-    await options.store.updateAdapterInvocation(pending.adapterInvocationId, { status: "failed", error, updatedAt: recordedAt });
-    await appendEvent(invocation, {
-      eventType: "ExternalOperationFailed",
-      ...subject,
-      payload: { externalReference: pending.externalReference, provider: pending.provider, error }
-    }, `external:${pending.adapterInvocationId}:failed`, 1, writer.transaction);
-    const patch = settles ? { status: "failed", error, externalCompletion, pendingCompletion: void 0 } : { externalCompletion, pendingCompletion: void 0 };
-    await writer.update(patch);
-    if (settles) emitInvocationStatusTelemetry(invocation, "failed", options.telemetry, now(), invocation.status);
-    return withConsistency(actionResult({ ...invocation, ...patch }), invocation.actionId);
-  }
-  function completionDigest(completion, provider) {
-    return crypto.createHash("sha256").update(canonicalJson({
-      provider: provider ?? null,
-      externalReference: completion.externalReference,
-      outcome: completion.outcome,
-      result: completion.result ?? null,
-      error: completion.error ?? null,
-      evidenceReferences: completion.evidenceReferences ?? null
-    })).digest("hex");
-  }
-  async function recordCompletionReconciliation(invocation, completion, reason) {
-    const governanceStore = asGovernanceStore(options.store);
-    if (!governanceStore) throw new Error("External completion reconciliation requires a governance-capable store.");
-    const provider = completion.provider ?? invocation.pendingCompletion?.provider ?? invocation.externalCompletion?.provider ?? "external";
-    const seed = crypto.createHash("sha256").update(`${provider}\0${completion.externalReference}\0${completion.kind ?? "refused"}`).digest("hex").slice(0, 32);
-    await governanceStore.appendExternalReconciliation({
-      id: lifecycleId("rec", invocation.id, `ext:${seed}`),
-      actionInvocationId: invocation.id,
-      tenantId: invocation.tenantId,
-      spaceId: invocation.spaceId,
-      status: "pending",
-      provider,
-      externalOperationId: completion.externalReference,
-      attempt: 1,
-      reason,
-      ...completion.evidenceReferences ? { evidenceReferences: completion.evidenceReferences } : {},
-      observedAt: now()
-    });
-  }
-  async function reconcileOverdueCompletions(input = {}) {
-    const recoverable = options.store;
-    if (!recoverable.listActionInvocations) {
-      throw new Error("Overdue completion reconciliation requires a store that can list invocations.");
-    }
-    if (!asGovernanceStore(options.store)) {
-      throw new Error("Overdue completion reconciliation requires a governance-capable store to record its findings.");
-    }
-    const current = input.now ?? now();
-    const candidates = await recoverable.listActionInvocations({
-      statuses: ["running"],
-      completionDueBefore: current,
-      unleased: true,
-      ...input.tenantId ? { tenantId: input.tenantId } : {},
-      ...input.spaceId ? { spaceId: input.spaceId } : {},
-      limit: Math.max(1, Math.min(input.limit ?? 100, 1e3))
-    });
-    const overdue = [];
-    for (const invocation of candidates) {
-      const pending = invocation.pendingCompletion;
-      if (!pending?.dueAt || pending.dueAt.getTime() > current.getTime()) continue;
-      if (invocation.leaseOwner) continue;
-      const message = `External operation "${pending.externalReference}" from ${pending.provider} did not complete by ${pending.dueAt.toISOString()}.`;
-      await recordCompletionReconciliation(invocation, { externalReference: pending.externalReference, provider: pending.provider, kind: "overdue" }, message);
-      await persistInvocation(invocation, { status: "reconciliation_required", error: message });
-      overdue.push(invocation.id);
-    }
-    return { overdue };
-  }
   function declaredConsistency(actionId) {
     return actionResolver(actionId)?.execution?.consistency;
   }
@@ -1544,7 +1590,7 @@ function createGovernedActionHost(options) {
       await (transaction ?? options.store).appendEvent(envelope);
     }
   }
-  async function fail(invocation, status, error) {
+  async function fail2(invocation, status, error) {
     await persistInvocation(invocation, { status, error });
     return {
       actionInvocationId: invocation.id,
@@ -1581,7 +1627,26 @@ function createGovernedActionHost(options) {
     );
     emitInvocationStatusTelemetry(invocation, patch.status, options.telemetry, now(), previousStatus);
   }
-  return { submitAction, executeInvocation, resumeApprovedInvocation, recordExecutionAttestation, recordExternalReconciliation, completeExternalInvocation, reconcileOverdueCompletions };
+  const externalCompletion = createExternalCompletionLifecycle({
+    store: options.store,
+    telemetry: options.telemetry,
+    eventResultFields,
+    now,
+    actionResolver,
+    appendEvent,
+    persistInvocation,
+    actionResult,
+    withConsistency
+  });
+  return {
+    submitAction,
+    executeInvocation,
+    resumeApprovedInvocation,
+    recordExecutionAttestation,
+    recordExternalReconciliation,
+    completeExternalInvocation: externalCompletion.completeExternalInvocation,
+    reconcileOverdueCompletions: externalCompletion.reconcileOverdueCompletions
+  };
 }
 function actionResult(invocation) {
   return {
@@ -1600,18 +1665,10 @@ function asApprovalStore(store) {
   const candidate = store;
   return typeof candidate.recordHitlDecision === "function" && typeof candidate.beginApprovalDecision === "function" ? store : void 0;
 }
-function asAtomicMutationStore(store) {
-  const candidate = store;
-  return typeof candidate.transactionWithEvents === "function" ? store : void 0;
-}
 function asOutboxStore(store) {
   const candidate = store;
   return typeof candidate.appendEventWithOutbox === "function" && typeof candidate.claimOutbox === "function" ? store : void 0;
 }
-function asGovernanceStore(store) {
-  const candidate = store;
-  return typeof candidate.recordMutationGovernance === "function" && typeof candidate.appendPolicyObligations === "function" && typeof candidate.appendExecutionAttestation === "function" ? store : void 0;
-}
 function numberValue(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
@@ -1647,39 +1704,9 @@ function initialState(machine) {
 function isTerminal(status) {
   return ["completed", "failed", "blocked_by_policy", "reconciliation_required", "validation_failed"].includes(status);
 }
-function emitInvocationStatusTelemetry(invocation, status, telemetry, occurredAt, previousStatus) {
-  if (!status) return;
-  const event = status === "completed" ? { name: "invocation.completed", metricName: PLATFORM_HOST_METRIC_NAMES.invocationCompleted } : status === "blocked_by_policy" ? { name: "invocation.policy_blocked", metricName: PLATFORM_HOST_METRIC_NAMES.invocationPolicyBlocked } : status === "validation_failed" ? { name: "invocation.validation_failed", metricName: PLATFORM_HOST_METRIC_NAMES.invocationValidationFailed } : status === "waiting_for_approval" ? { name: "invocation.approval_waited", metricName: PLATFORM_HOST_METRIC_NAMES.invocationApprovalWaited } : status === "reconciliation_required" ? { name: "invocation.reconciliation_required", metricName: PLATFORM_HOST_METRIC_NAMES.invocationReconciliationRequired } : status === "failed" ? { name: "invocation.failed", metricName: PLATFORM_HOST_METRIC_NAMES.invocationFailed } : void 0;
-  if (!event) return;
-  emitPlatformHostTelemetry(telemetry, {
-    kind: "event",
-    name: event.name,
-    metricName: event.metricName,
-    occurredAt,
-    tenantId: invocation.tenantId,
-    spaceId: invocation.spaceId,
-    attributes: {
-      ...invocation.actionId ? { actionId: invocation.actionId } : {},
-      ...invocation.actionVersion !== void 0 ? { actionVersion: invocation.actionVersion } : {},
-      ...previousStatus ? { fromStatus: previousStatus } : {}
-    }
-  });
-}
-function withoutPrivateHostFields(data, eventResultFields) {
-  return Object.fromEntries(
-    Object.entries(data).filter(([key]) => !eventResultFields.includes(key))
-  );
-}
-function errorMessage(error) {
-  return error instanceof Error ? error.message : String(error);
-}
 function isRecord(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
-function lifecycleId(prefix, invocationId, key) {
-  const safeKey = key.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 96);
-  return `${prefix}_${invocationId}_${safeKey}`;
-}
 function validateAuthorizationBinding(input, parameterDigest, authorityMoment, currentTime = /* @__PURE__ */ new Date()) {
   const binding = input.authorizationBinding;
   if (binding.id !== input.authorizationBindingId && input.authorizationBindingId) throw new Error("Authorization binding ID does not match authorizationBindingId.");
@@ -3537,6 +3564,181 @@ function createDurableSagaParentLifecycle(options) {
   };
 }
 
+// src/tenant-isolation.ts
+function fail(message) {
+  throw new Error(message);
+}
+function submitInput(subject, scope, idempotencyKey) {
+  return {
+    actionId: subject.actionId,
+    parameters: subject.parameters ?? {},
+    tenantId: scope.tenantId,
+    spaceId: scope.spaceId,
+    actorId: scope.actorId,
+    actorType: scope.actorType,
+    idempotencyKey
+  };
+}
+function tenantIsolationChecks() {
+  return [
+    {
+      id: "fabric.tenancy.invocation-scoped-read.v1",
+      async run(subject) {
+        await subject.reset?.();
+        if (subject.ours.tenantId === subject.theirs.tenantId) fail("the two scopes must be in different tenants");
+        const ours = await subject.host.submitAction(submitInput(subject, subject.ours, "iso:read"));
+        const crossRead = await subject.store.getActionInvocation(ours.actionInvocationId, subject.theirs.tenantId, subject.theirs.spaceId);
+        if (crossRead !== void 0) fail("an invocation was readable under another tenant's scope");
+        const shape = (record) => JSON.stringify({ status: record?.status, result: record?.result, error: record?.error, attemptCount: record?.attemptCount, updatedAt: record?.updatedAt });
+        const before = await subject.store.getActionInvocation(ours.actionInvocationId, subject.ours.tenantId, subject.ours.spaceId);
+        if (!before) fail("our own invocation was not readable under our scope, so the check proves nothing");
+        const untouched = shape(before);
+        let crossExecute;
+        try {
+          crossExecute = await subject.host.executeInvocation(ours.actionInvocationId, subject.theirs.tenantId, subject.theirs.spaceId);
+        } catch {
+          crossExecute = void 0;
+        }
+        if (crossExecute !== void 0) fail("an invocation was executable under another tenant's scope");
+        const after = await subject.store.getActionInvocation(ours.actionInvocationId, subject.ours.tenantId, subject.ours.spaceId);
+        if (untouched !== shape(after)) fail("an execution attempted under another tenant's scope changed our invocation");
+        return ["invocation readable under our scope, invisible and untouched under the other tenant's"];
+      }
+    },
+    {
+      id: "fabric.tenancy.idempotency-key-scoped.v1",
+      async run(subject) {
+        await subject.reset?.();
+        const ours = await subject.host.submitAction(submitInput(subject, subject.ours, "iso:shared-key"));
+        const again = await subject.host.submitAction(submitInput(subject, subject.ours, "iso:shared-key"));
+        if (ours.actionInvocationId !== again.actionInvocationId) fail("the same idempotency key in one tenant produced two invocations, so the key is not doing anything and the check proves nothing");
+        const theirs = await subject.host.submitAction(submitInput(subject, subject.theirs, "iso:shared-key"));
+        if (ours.actionInvocationId === theirs.actionInvocationId) fail("the same idempotency key in two tenants resolved to one invocation");
+        return ["one idempotency key: one invocation within a tenant, two across tenants"];
+      }
+    },
+    {
+      id: "fabric.tenancy.events-scoped.v1",
+      async run(subject) {
+        await subject.reset?.();
+        const ours = await subject.host.submitAction(submitInput(subject, subject.ours, "iso:events"));
+        const theirEvents = await subject.store.listEvents(subject.theirs.tenantId, subject.theirs.spaceId);
+        const leaked = theirEvents.filter((event) => event.tenantId === subject.ours.tenantId || event.actionInvocationId === ours.actionInvocationId);
+        if (leaked.length > 0) fail(`${leaked.length} of our events appeared in the other tenant's stream`);
+        const ourEvents = await subject.store.listEvents(subject.ours.tenantId, subject.ours.spaceId);
+        if (!ourEvents.some((event) => event.actionInvocationId === ours.actionInvocationId)) fail("our own stream does not carry the event we just caused, so the check proves nothing");
+        if (ourEvents.some((event) => event.tenantId !== subject.ours.tenantId)) fail("another tenant's event appeared in our stream");
+        return ["event streams carry their own tenant's events and only those"];
+      }
+    },
+    {
+      id: "fabric.tenancy.worker-claim-scoped.v1",
+      async run(subject) {
+        await subject.reset?.();
+        const probeSpace = `iso-probe-${Date.now()}`;
+        const created = await subject.store.createActionInvocation({
+          id: `iso_pending_${Date.now()}`,
+          tenantId: subject.ours.tenantId,
+          spaceId: probeSpace,
+          actionId: subject.actionId,
+          actionVersion: 1,
+          actorId: subject.ours.actorId,
+          actorType: subject.ours.actorType,
+          status: "pending",
+          parameters: subject.parameters ?? {},
+          result: {},
+          correlationId: `iso-corr-${Date.now()}`
+        });
+        try {
+          const theirs = await subject.store.claimActionInvocations({
+            workerId: "iso-worker",
+            leaseDurationMs: 1e3,
+            limit: 1e3,
+            tenantId: subject.theirs.tenantId,
+            spaceId: probeSpace
+          });
+          if (theirs.some((row) => row.id === created.id)) fail("a worker scoped to another tenant claimed our pending invocation");
+          const ours = await subject.store.claimActionInvocations({
+            workerId: "iso-worker",
+            leaseDurationMs: 1e3,
+            limit: 1e3,
+            tenantId: subject.ours.tenantId,
+            spaceId: probeSpace
+          });
+          if (!ours.some((row) => row.id === created.id)) fail("a worker scoped to our own tenant did not claim our pending invocation, so the check proves nothing");
+        } finally {
+          await subject.store.updateActionInvocation(created.id, subject.ours.tenantId, probeSpace, {
+            status: "failed",
+            error: "tenant isolation probe; never executed"
+          });
+        }
+        return ["tenant-scoped claim takes our work and leaves other tenants' alone"];
+      }
+    },
+    {
+      id: "fabric.tenancy.completion-scoped.v1",
+      async run(subject) {
+        await subject.reset?.();
+        const ours = await subject.host.submitAction(submitInput(subject, subject.ours, "iso:complete"));
+        let outcome;
+        try {
+          await subject.host.completeExternalInvocation(ours.actionInvocationId, subject.theirs.tenantId, subject.theirs.spaceId, {
+            externalReference: "iso-ref",
+            outcome: "completed",
+            observedAt: (/* @__PURE__ */ new Date()).toISOString()
+          });
+          outcome = "accepted";
+        } catch (error) {
+          const refusal = error.refusal;
+          outcome = refusal ?? "threw";
+        }
+        if (outcome !== "not_found") fail(`a completion under another tenant's scope was ${outcome}; it must be refused as not_found`);
+        let mine;
+        try {
+          await subject.host.completeExternalInvocation(ours.actionInvocationId, subject.ours.tenantId, subject.ours.spaceId, {
+            externalReference: "iso-ref",
+            outcome: "completed",
+            observedAt: (/* @__PURE__ */ new Date()).toISOString()
+          });
+          mine = "accepted";
+        } catch (error) {
+          mine = error.refusal ?? "threw";
+        }
+        if (mine === "not_found") fail("a completion under our own scope was refused as not_found, so the check proves nothing");
+        return ["completion under the other tenant's scope refused as not_found; found under ours"];
+      }
+    },
+    {
+      id: "fabric.tenancy.projection-scoped.v1",
+      async run(subject) {
+        if (!subject.read) return ["skipped: subject lends no read"];
+        await subject.reset?.();
+        await subject.host.submitAction(submitInput(subject, subject.ours, "iso:projection"));
+        const ours = await subject.read(subject.ours);
+        const theirs = await subject.read(subject.theirs);
+        if (!ours.allowed) fail("our own viewer was denied the read");
+        if (ours.rows.length === 0) fail("our own viewer saw nothing, so the check proves nothing");
+        if (ours.rows.some((row) => row?.tenantId !== subject.ours.tenantId)) fail("our own viewer saw rows that are not ours, or rows carrying no tenant");
+        const leaked = theirs.allowed ? theirs.rows.filter((row) => row?.tenantId === subject.ours.tenantId) : [];
+        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"];
+      }
+    }
+  ];
+}
+async function runTenantIsolationChecks(subject) {
+  const checks = [];
+  for (const check of tenantIsolationChecks()) {
+    try {
+      const evidence = await check.run(subject);
+      checks.push({ id: check.id, status: evidence[0]?.startsWith("skipped") ? "skipped" : "passed", evidence });
+    } catch (error) {
+      checks.push({ id: check.id, status: "failed", evidence: [], error: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  return { passed: checks.every((check) => check.status !== "failed"), checks };
+}
+
 exports.ExternalCompletionError = ExternalCompletionError;
 exports.IdempotencyConflictError = IdempotencyConflictError;
 exports.MemoryPlatformHostStore = MemoryPlatformHostStore;
@@ -3557,6 +3759,8 @@ exports.getPlatformHostHealthSnapshot = getPlatformHostHealthSnapshot;
 exports.runOutboxRelayCycle = runOutboxRelayCycle;
 exports.runPlatformActionWorker = runPlatformActionWorker;
 exports.runPlatformActionWorkerCycle = runPlatformActionWorkerCycle;
+exports.runTenantIsolationChecks = runTenantIsolationChecks;
+exports.tenantIsolationChecks = tenantIsolationChecks;
 exports.toEnterpriseEventEnvelope = toEnterpriseEventEnvelope;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map