@fabricorg/platform-host 7.1.0 → 7.1.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @fabricorg/platform-host
 
+## 7.1.2
+
+### Patch Changes
+
+- 07e3c65: The external-completion lifecycle moves out of the host into its own internal module, with the helpers it shares with the host in another. No behaviour changes; the public surface is unchanged and every test passes as before.
+
+## 7.1.1
+
+### Patch Changes
+
+- 91f7d7e: A repeated completion was judged identical by outcome alone, so a second `completed` callback carrying a different result was absorbed as a replay and its evidence discarded. A recorded completion now carries a canonical digest of provider, reference, outcome, result, error, and evidence, with observation time left out because a redelivery carries a new one. A repeat with the same digest is absorbed; the same outcome with a different digest is a contradiction and is handled as one: reconciliation, the first outcome kept, the second logged, `ExternalOperationContradicted` emitted.
+
 ## 7.1.0
 
 ### Minor Changes

package/README.md

@@ -265,7 +265,9 @@ await host.completeExternalInvocation(actionInvocationId, tenantId, spaceId, {
 ```
 
 Matching is by reference: a completion naming a reference the invocation is not waiting on is
-refused. A repeated identical completion is absorbed. A contradictory one moves the invocation to
+refused. A repeated identical completion is absorbed, identity being a digest of provider,
+reference, outcome, result, error, and evidence. A contradictory one, a flipped outcome or the same
+outcome with different evidence, moves the invocation to
 `reconciliation_required`, keeps the first outcome on record, logs the second, and emits
 `ExternalOperationContradicted`. Under an atomic store the read and write happen under one lock. The
 callback's result is validated against the action's result schema and stripped of private fields.

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;
@@ -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 });
@@ -1123,7 +1338,7 @@ 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 });
@@ -1316,163 +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}".`);
-      }
-      if (recorded.outcome === completion.outcome) {
-        return withConsistency(actionResult(invocation), invocation.actionId);
-      }
-      const message = `External operation "${completion.externalReference}" reported ${completion.outcome} after reporting ${recorded.outcome}.`;
-      await recordCompletionReconciliation(invocation, { ...completion, kind: `contradicted:${completion.outcome}` }, 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
-    };
-    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);
-  }
-  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;
   }
@@ -1569,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 {
@@ -1588,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;
 }
@@ -1635,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.");