xytara 2.5.0 → 2.6.0

package/lib/checkout_event_security.js

@@ -0,0 +1,142 @@
+"use strict";
+
+const crypto = require("crypto");
+
+function normalizeString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function parseBoolean(value, fallback) {
+  const normalized = normalizeString(value).toLowerCase();
+  if (!normalized) return fallback;
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+  return fallback;
+}
+
+function safeEqualHex(left, right) {
+  const leftNormalized = normalizeString(left).toLowerCase();
+  const rightNormalized = normalizeString(right).toLowerCase();
+  if (!leftNormalized || !rightNormalized || leftNormalized.length !== rightNormalized.length) return false;
+  try {
+    return crypto.timingSafeEqual(Buffer.from(leftNormalized, "hex"), Buffer.from(rightNormalized, "hex"));
+  } catch (_error) {
+    return false;
+  }
+}
+
+function loadCheckoutEventSecurityConfig() {
+  const secret = normalizeString(process.env.XYTARA_CHECKOUT_WEBHOOK_SECRET || process.env.XYTARA_HOSTED_CHECKOUT_WEBHOOK_SECRET);
+  const verificationRequired = parseBoolean(
+    process.env.XYTARA_CHECKOUT_WEBHOOK_VERIFICATION_REQUIRED,
+    secret.length > 0
+  );
+  const maxAgeSeconds = Math.max(30, Number(process.env.XYTARA_CHECKOUT_WEBHOOK_MAX_AGE_SECONDS || 300) || 300);
+  return {
+    secret: secret || null,
+    verification_required: verificationRequired,
+    max_age_seconds: maxAgeSeconds,
+    signature_header: "x-xytara-checkout-signature",
+    timestamp_header: "x-xytara-checkout-timestamp",
+    signature_mode: "hmac_sha256_timestamped"
+  };
+}
+
+function buildCheckoutEventSecuritySummary() {
+  const config = loadCheckoutEventSecurityConfig();
+  const blockers = [];
+  if (config.verification_required && !config.secret) blockers.push("checkout_webhook_secret_missing");
+  return {
+    ok: true,
+    category: "machine-commerce-checkout-event-security-summary",
+    summary_version: "xytara-checkout-event-security-summary-v1",
+    verification_required: config.verification_required,
+    secret_configured: Boolean(config.secret),
+    max_age_seconds: config.max_age_seconds,
+    signature_header: config.signature_header,
+    timestamp_header: config.timestamp_header,
+    signature_mode: config.signature_mode,
+    ready: blockers.length === 0,
+    blockers,
+    operator_guidance: config.verification_required
+      ? "sign checkout event payloads with the configured webhook secret before forwarding them into xytara"
+      : "configure XYTARA_CHECKOUT_WEBHOOK_SECRET and keep verification required when hosted checkout is live"
+  };
+}
+
+function buildCheckoutEventSignature(rawBody, secret, timestamp) {
+  return crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
+}
+
+function verifyCheckoutEventRequest(headers, rawBody) {
+  const config = loadCheckoutEventSecurityConfig();
+  const headerMap = headers && typeof headers === "object" ? headers : {};
+  const signature = normalizeString(headerMap[config.signature_header]);
+  const timestamp = normalizeString(headerMap[config.timestamp_header]);
+
+  if (!config.verification_required && !config.secret) {
+    return {
+      ok: true,
+      verification_mode: "verification_not_required",
+      signature_mode: config.signature_mode
+    };
+  }
+
+  if (!config.secret) {
+    return {
+      ok: false,
+      reason: "checkout_webhook_secret_missing"
+    };
+  }
+
+  if (!signature) {
+    return {
+      ok: false,
+      reason: "checkout_webhook_signature_missing"
+    };
+  }
+
+  if (!timestamp) {
+    return {
+      ok: false,
+      reason: "checkout_webhook_timestamp_missing"
+    };
+  }
+
+  const timestampMs = Date.parse(timestamp);
+  if (!Number.isFinite(timestampMs)) {
+    return {
+      ok: false,
+      reason: "checkout_webhook_timestamp_invalid"
+    };
+  }
+
+  const ageSeconds = Math.abs(Date.now() - timestampMs) / 1000;
+  if (ageSeconds > config.max_age_seconds) {
+    return {
+      ok: false,
+      reason: "checkout_webhook_timestamp_expired"
+    };
+  }
+
+  const expected = buildCheckoutEventSignature(rawBody, config.secret, timestamp);
+  if (!safeEqualHex(expected, signature)) {
+    return {
+      ok: false,
+      reason: "checkout_webhook_signature_invalid"
+    };
+  }
+
+  return {
+    ok: true,
+    verification_mode: "timestamped_hmac",
+    signature_mode: config.signature_mode
+  };
+}
+
+module.exports = {
+  buildCheckoutEventSecuritySummary,
+  buildCheckoutEventSignature,
+  loadCheckoutEventSecurityConfig,
+  verifyCheckoutEventRequest
+};

package/lib/command_flow.js

@@ -5,10 +5,11 @@ const {
   createQuote,
   hydrateQuoteStates
 } = require("./commerce_runtime");
-const { consumeAccountCredits, buildUsageMeterPreview } = require("./commerce_economics");
+const { consumeAccountCredits, buildUsageMeterPreview, previewCreditSpend } = require("./commerce_economics");
 const { resolveSpendCredential, evaluateAuthorityBindingAction } = require("./account_auth");
 const { validateIntegrationSelection } = require("../integrations/dispatch");
 const { markPaymentAccepted, verifyPaymentAcceptance } = require("./payment_verification");
+const { executeExternalTarget, resolveExecutionTarget } = require("./external_execution_runtime");
 
 function hasPaymentHeaders(headers, requiredHeaders) {
   return requiredHeaders.every((headerName) => headers[headerName]);
@@ -22,7 +23,84 @@ function parseBearerToken(headers) {
   return match ? match[1].trim() : null;
 }
 
-function executeCommandRequest(state, payload, headers, options) {
+function buildCreditCommitPayload(payload, quote, requiredUnits) {
+  return {
+    account_id: quote.account_id,
+    agent_id: payload.agent_id || null,
+    budget_id: payload.budget_id || null,
+    pack_id: payload.pack_id || null,
+    entitlement_id: payload.entitlement_id || null,
+    quote_id: quote.quote_id,
+    task_ref: payload.task_ref || null,
+    workflow_ref: payload.workflow_ref || null,
+    units: requiredUnits,
+    reason: "credit_first_execution"
+  };
+}
+
+function buildCreditRejectionResponse(creditDecision, quote) {
+  const failureReason = creditDecision && creditDecision.credit_spend_preview
+    ? creditDecision.credit_spend_preview.failure_reason
+    : null;
+  const reason = failureReason
+    || (creditDecision && creditDecision.policy_guard && creditDecision.policy_guard.reason)
+    || (creditDecision && creditDecision.entitlement_guard && creditDecision.entitlement_guard.reason)
+    || (creditDecision && creditDecision.reason)
+    || "credit_spend_not_allowed";
+
+  if (reason === "insufficient_credits") {
+    const preview = creditDecision && creditDecision.credit_spend_preview ? creditDecision.credit_spend_preview : {};
+    return {
+      status: 402,
+      payload: {
+        ok: false,
+        reason: "insufficient_credits",
+        insufficient_credits: {
+          account_id: quote.account_id,
+          required_units: preview.required_units,
+          available_units: preview.available_units,
+          recommended_next_surfaces: {
+            credits_topup: "/v1/checkout/purchase-intents",
+            direct_payment: "/v1/payment-quotes"
+          }
+        },
+        quote
+      }
+    };
+  }
+
+  return {
+    status: 403,
+    payload: {
+      ok: false,
+      reason,
+      account_id: quote.account_id,
+      policy_guard: creditDecision && creditDecision.policy_guard ? creditDecision.policy_guard : null,
+      entitlement_guard: creditDecision && creditDecision.entitlement_guard ? creditDecision.entitlement_guard : null,
+      quote
+    }
+  };
+}
+
+async function buildExternalExecutionOptions(payload, quote, authorizationContext) {
+  const executionTarget = resolveExecutionTarget(payload, quote);
+  if (!executionTarget) return {};
+  const execution = await executeExternalTarget(executionTarget, payload, quote, authorizationContext);
+  if (!execution || !execution.ok) {
+    return {
+      error: execution || {
+        ok: false,
+        status: 502,
+        reason: "external_execution_failed"
+      }
+    };
+  }
+  return {
+    externalExecution: execution
+  };
+}
+
+async function executeCommandRequest(state, payload, headers, options) {
   const opts = options || {};
   const requiredHeaders = Array.isArray(opts.requiredHeaders) && opts.requiredHeaders.length > 0
     ? opts.requiredHeaders
@@ -72,10 +150,12 @@ function executeCommandRequest(state, payload, headers, options) {
     }
     const quote = createQuote(state, payload);
     if (prefersCredits) {
-      const meteringPreview = buildUsageMeterPreview(state, {
+      const creditPayload = {
         ...payload,
+        account_id: quote.account_id,
         quoted_units: Number.isFinite(Number(payload.quoted_units)) ? Number(payload.quoted_units) : undefined
-      });
+      };
+      const meteringPreview = buildUsageMeterPreview(state, creditPayload);
       const requiredUnits = meteringPreview.usage_units;
       if (delegatedSpend.ok && delegatedSpend.binding) {
         const authorityDecision = evaluateAuthorityBindingAction(delegatedSpend.binding, "delegated_credit_spend", requiredUnits);
@@ -96,42 +176,65 @@ function executeCommandRequest(state, payload, headers, options) {
           };
         }
       }
-      const creditSpend = consumeAccountCredits(state, {
-        account_id: quote.account_id,
-        agent_id: payload.agent_id || null,
-        budget_id: payload.budget_id || null,
-        pack_id: payload.pack_id || null,
-        entitlement_id: payload.entitlement_id || null,
-        quote_id: quote.quote_id,
-        task_ref: payload.task_ref || null,
-        workflow_ref: payload.workflow_ref || null,
-        units: requiredUnits,
-        reason: "credit_first_execution"
-      });
+
+      const creditDecision = previewCreditSpend(state, creditPayload);
+      if (!creditDecision.ok || !creditDecision.credit_spend_preview || creditDecision.credit_spend_preview.executable_now !== true) {
+        return buildCreditRejectionResponse(creditDecision, quote);
+      }
+
+      const preCommitAuthorizationContext = delegatedSpend.ok
+        ? delegatedSpend.authorization_context
+        : {
+            ok: true,
+            verification_mode: "account_credits",
+            wallet_id: quote.account_id,
+            age_seconds: 0,
+            payment_payload: {
+              credit_spend_status: "precommit"
+            }
+          };
+      const externalExecutionOptions = await buildExternalExecutionOptions(payload, quote, preCommitAuthorizationContext);
+      if (externalExecutionOptions.error) {
+        return {
+          status: externalExecutionOptions.error.status || 502,
+          payload: {
+            ok: false,
+            reason: externalExecutionOptions.error.reason || "external_execution_failed",
+            details: externalExecutionOptions.error.details || null,
+            credit_spend_status: "not_committed",
+            credit_spend_preview: creditDecision.credit_spend_preview,
+            quote
+          }
+        };
+      }
+
+      const creditSpend = consumeAccountCredits(state, buildCreditCommitPayload(payload, quote, requiredUnits));
       if (creditSpend.ok) {
+        const paymentVerification = {
+          ...(delegatedSpend.ok
+            ? delegatedSpend.authorization_context
+            : {
+                ok: true,
+                verification_mode: "account_credits",
+                wallet_id: quote.account_id,
+                age_seconds: 0,
+                payment_payload: {}
+              }),
+          payment_payload: {
+            ...((delegatedSpend.ok && delegatedSpend.authorization_context && delegatedSpend.authorization_context.payment_payload) || {}),
+            credit_spend_id: creditSpend.credit_spend.credit_spend_id
+          }
+        };
         return {
           status: 200,
           payload: createCommandResult(state, {
             ...payload,
             payment_preference: "credits_first"
           }, quote, {
-            paymentVerification: {
-              ...(delegatedSpend.ok
-                ? delegatedSpend.authorization_context
-                : {
-                    ok: true,
-                    verification_mode: "account_credits",
-                    wallet_id: quote.account_id,
-                    age_seconds: 0,
-                    payment_payload: {}
-                  }),
-              payment_payload: {
-                ...((delegatedSpend.ok && delegatedSpend.authorization_context && delegatedSpend.authorization_context.payment_payload) || {}),
-                credit_spend_id: creditSpend.credit_spend.credit_spend_id
-              }
-            },
+            paymentVerification,
             creditSpend: creditSpend.credit_spend,
-            skipPaymentLedger: true
+            skipPaymentLedger: true,
+            externalExecution: externalExecutionOptions.externalExecution || null
           })
         };
       }
@@ -142,6 +245,7 @@ function executeCommandRequest(state, payload, headers, options) {
             ok: false,
             reason: creditSpend.reason,
             account_id: quote.account_id,
+            provider_execution_completed_but_credit_commit_failed: Boolean(externalExecutionOptions.externalExecution),
             policy_guard: {
               agent_id: creditSpend.agent_id || null,
               budget_id: creditSpend.budget_id || null,
@@ -161,6 +265,7 @@ function executeCommandRequest(state, payload, headers, options) {
         payload: {
           ok: false,
           reason: "insufficient_credits",
+          provider_execution_completed_but_credit_commit_failed: Boolean(externalExecutionOptions.externalExecution),
           insufficient_credits: {
             account_id: quote.account_id,
             required_units: creditSpend.required_units,
@@ -206,7 +311,10 @@ function executeCommandRequest(state, payload, headers, options) {
     };
   }
 
-  const paymentVerification = verifyPaymentAcceptance(state, headers || {}, requiredHeaders, quote);
+  const paymentVerification = verifyPaymentAcceptance(state, headers || {}, requiredHeaders, quote, {
+    payment_protocol: opts.paymentProtocol || (payload && payload.payment_protocol) || null,
+    authorization_scheme: opts.authorizationScheme || null
+  });
   if (!paymentVerification.ok) {
     return {
       status: paymentVerification.status || 403,
@@ -219,16 +327,29 @@ function executeCommandRequest(state, payload, headers, options) {
   }
 
   markPaymentAccepted(state, paymentVerification);
+  const externalExecutionOptions = await buildExternalExecutionOptions(payload, quote, paymentVerification);
+  if (externalExecutionOptions.error) {
+    return {
+      status: externalExecutionOptions.error.status || 502,
+      payload: {
+        ok: false,
+        reason: externalExecutionOptions.error.reason || "external_execution_failed",
+        details: externalExecutionOptions.error.details || null,
+        quote
+      }
+    };
+  }
 
   return {
     status: 200,
     payload: createCommandResult(state, payload, quote, {
-      paymentVerification
+      paymentVerification,
+      externalExecution: externalExecutionOptions.externalExecution || null
     })
   };
 }
 
-function executeAuthorizedCommandRequest(state, payload, authorizationContext) {
+async function executeAuthorizedCommandRequest(state, payload, authorizationContext) {
   const validation = validateIntegrationSelection(payload);
   if (!validation.ok) {
     return {
@@ -258,11 +379,23 @@ function executeAuthorizedCommandRequest(state, payload, authorizationContext) {
       ? authorizationContext.payment_payload
       : null
   };
+  const externalExecutionOptions = await buildExternalExecutionOptions(payload, quote, paymentVerification);
+  if (externalExecutionOptions.error) {
+    return {
+      status: externalExecutionOptions.error.status || 502,
+      payload: {
+        ok: false,
+        reason: externalExecutionOptions.error.reason || "external_execution_failed",
+        details: externalExecutionOptions.error.details || null
+      }
+    };
+  }
 
   return {
     status: 200,
     payload: createCommandResult(state, payload, quote, {
-      paymentVerification
+      paymentVerification,
+      externalExecution: externalExecutionOptions.externalExecution || null
     })
   };
 }

package/lib/commerce_artifacts.js

@@ -67,6 +67,12 @@ function createCommandArtifacts(payload, quote, options) {
   const normalizedBody = payload && payload.body && typeof payload.body === "object" && !Array.isArray(payload.body)
     ? payload.body
     : {};
+  const externalExecution = opts.externalExecution && typeof opts.externalExecution === "object"
+    ? opts.externalExecution
+    : null;
+  const externalResponse = externalExecution && externalExecution.target_response && typeof externalExecution.target_response === "object"
+    ? externalExecution.target_response
+    : null;
   const resultsByTaskId = Object.fromEntries(resultTasks.map((task, index) => [
     task.task_id,
     (() => {
@@ -164,7 +170,17 @@ function createCommandArtifacts(payload, quote, options) {
       if (task.task_ref === "adapter.mcp.invoke") {
         base.adapter_lane = "mcp";
         base.tool_name = normalizedBody.tool_name || null;
-        base.invocation_status = "simulated";
+        base.invocation_status = externalExecution ? "provider_completed" : "simulated";
+      }
+      if (externalExecution) {
+        base.execution_provider = externalExecution.provider || null;
+        base.execution_target_id = externalExecution.target_id || null;
+        if (externalResponse && externalResponse.provider_job_id) base.provider_job_id = externalResponse.provider_job_id;
+        if (externalResponse && externalResponse.output_payload) base.output_payload = externalResponse.output_payload;
+        if (externalResponse && externalResponse.output_ref) base.output_ref = externalResponse.output_ref;
+        base.provider_status = externalResponse && externalResponse.provider_status
+          ? externalResponse.provider_status
+          : "completed";
       }
       return base;
     })()
@@ -263,7 +279,7 @@ function createCommandArtifacts(payload, quote, options) {
     quote_id: quote.quote_id,
     integration_ids: Array.isArray(quote.integration_ids) ? quote.integration_ids : [],
     protocols: Array.isArray(quote.protocols) ? quote.protocols : [],
-    output_ref: `output_${transactionId}`,
+    output_ref: externalResponse && externalResponse.output_ref ? externalResponse.output_ref : `output_${transactionId}`,
     callback_url: payload.callback_url || null,
     capabilities: quote.capabilities,
     adapters: quote.adapters,
@@ -280,7 +296,10 @@ function createCommandArtifacts(payload, quote, options) {
       capability_scopes: capabilityScopes,
       adapters_used: adaptersUsed,
       integration_ids: Array.isArray(quote.execution_integration_ids) ? quote.execution_integration_ids : [],
-      results_by_task_id: resultsByTaskId
+      results_by_task_id: resultsByTaskId,
+      provider: externalExecution ? externalExecution.provider || null : null,
+      provider_target_id: externalExecution ? externalExecution.target_id || null : null,
+      provider_job_id: externalResponse && externalResponse.provider_job_id ? externalResponse.provider_job_id : null
     },
     created_at_iso: startedAt.toISOString(),
     completed_at_iso: deferredCompletion ? null : completedAt.toISOString(),
@@ -304,7 +323,7 @@ function createCommandArtifacts(payload, quote, options) {
       ...defaultPath,
       status: deferredCompletion ? "pending_completion" : "recorded"
     },
-    proof_ref: `proof_${receiptId}`,
+    proof_ref: externalResponse && externalResponse.proof_ref ? externalResponse.proof_ref : `proof_${receiptId}`,
     execution_summary: {
       command: payload.command || "command.execute",
       task_count: resultTasks.length,

package/lib/commerce_checkout.js

@@ -1,7 +1,7 @@
 "use strict";
 
-const { createRefund } = require("./commerce_cases");
-const { applyRailCredits } = require("./commerce_economics");
+const { createRefund, createRemediationTicket } = require("./commerce_cases");
+const { applyRailCredits, buildCreditBalanceSummary, reverseRailCredits } = require("./commerce_economics");
 const { dispatchRuntimeBridgeRequest } = require("./runtime_bridge");
 
 function normalizeString(value, fallback) {
@@ -142,6 +142,90 @@ function getHostedCheckoutEvent(state, eventId) {
   return state.checkoutEvents.get(eventId) || null;
 }
 
+function getRuntimeBridgeDispatchByPurchaseIntent(state, purchaseIntentId) {
+  return Array.from(state.runtimeBridgeDispatches.values()).find((dispatch) =>
+    dispatch && dispatch.purchase_intent_id === purchaseIntentId
+  ) || null;
+}
+
+function createHostedCheckoutRemediationTicket(state, purchaseIntent, event, refund, reasonCode, note) {
+  return createRemediationTicket(state, {
+    transaction_id: null,
+    receipt_id: null,
+    reason_code: reasonCode,
+    action_code: "compensate_or_review",
+    note,
+    actor: { type: "system", role: "hosted_checkout_compensator" },
+    context: {
+      purchase_intent_id: purchaseIntent.purchase_intent_id,
+      refund_id: refund ? refund.refund_id : null,
+      provider_reference: event.provider_reference || null,
+      payment_status: event.payment_status || null,
+      source: "hosted_checkout_compensation"
+    }
+  });
+}
+
+function applyHostedCheckoutCompensation(state, purchaseIntent, event, refund) {
+  const balanceBefore = buildCreditBalanceSummary(state, purchaseIntent.account_id);
+  const currentAvailableUnits = Number(balanceBefore.available_units || 0);
+  const requiredUnits = Number(purchaseIntent.credits_units || 0);
+  const runtimeBridgeDispatch = getRuntimeBridgeDispatchByPurchaseIntent(state, purchaseIntent.purchase_intent_id);
+  const compensation = {
+    compensation_state: "review_required",
+    compensation_path: null,
+    reversal_credit_event_id: null,
+    remediation_ticket_id: null,
+    requires_manual_followup: true,
+    downstream_execution_detected: Boolean(runtimeBridgeDispatch),
+    insufficient_available_units: currentAvailableUnits < requiredUnits
+  };
+
+  if (purchaseIntent.fulfillment && purchaseIntent.fulfillment.credits_issued) {
+    const reversalResult = reverseRailCredits(state, {
+      account_id: purchaseIntent.account_id,
+      purchase_intent_id: purchaseIntent.purchase_intent_id,
+      provider_reference: event.provider_reference,
+      reason: event.payment_status === "chargeback"
+        ? "hosted_checkout_chargeback_compensation"
+        : "hosted_checkout_refund_compensation"
+    });
+    if (reversalResult.ok) {
+      compensation.reversal_credit_event_id = reversalResult.reversal.credit_event_id;
+      compensation.compensation_path = "credit_reversal";
+      compensation.compensation_state = (currentAvailableUnits >= requiredUnits && !runtimeBridgeDispatch)
+        ? "compensated"
+        : "remediation_required";
+      compensation.requires_manual_followup = compensation.compensation_state !== "compensated";
+    } else {
+      compensation.compensation_path = "credit_reversal_failed";
+      compensation.compensation_state = "compensation_failed";
+    }
+  } else if (purchaseIntent.fulfillment && purchaseIntent.fulfillment.execution_authorized) {
+    compensation.compensation_path = "execution_remediation";
+    compensation.compensation_state = "remediation_required";
+  }
+
+  if (compensation.compensation_state !== "compensated") {
+    const note = compensation.downstream_execution_detected
+      ? "Hosted checkout reversal landed after execution dispatch and needs remediation review"
+      : compensation.insufficient_available_units
+        ? "Hosted checkout reversal landed after funded capacity was partially or fully consumed"
+        : "Hosted checkout reversal requires explicit operator review";
+    const ticket = createHostedCheckoutRemediationTicket(
+      state,
+      purchaseIntent,
+      event,
+      refund,
+      event.payment_status === "chargeback" ? "chargeback_compensation_review_required" : "refund_compensation_review_required",
+      note
+    );
+    compensation.remediation_ticket_id = ticket.ticket_id;
+  }
+
+  return compensation;
+}
+
 function listHostedCheckoutRefunds(state, purchaseIntentId) {
   const refunds = Array.from(state.refunds.values()).filter((refund) => refund && refund.purchase_intent_id);
   if (!purchaseIntentId) return refunds;
@@ -162,6 +246,9 @@ function buildHostedCheckoutOperatorSummary(state, accountId) {
     credits_issued_count: purchaseIntents.filter((entry) => entry.fulfillment && entry.fulfillment.credits_issued).length,
     execution_dispatched_count: bridgeDispatches.length,
     refund_review_required_count: purchaseIntents.filter((entry) => entry.customer_status === "refund_review_required" || entry.customer_status === "refund_review_requested").length,
+    auto_compensated_count: purchaseIntents.filter((entry) => entry && entry.compensation && entry.compensation.compensation_state === "compensated").length,
+    compensation_review_required_count: purchaseIntents.filter((entry) => entry && entry.compensation && entry.compensation.compensation_state === "remediation_required").length,
+    compensation_failed_count: purchaseIntents.filter((entry) => entry && entry.compensation && entry.compensation.compensation_state === "compensation_failed").length,
     refund_case_count: refunds.length,
     refund_status_counts: refunds.reduce((acc, refund) => {
       const key = refund && refund.status ? refund.status : "unknown";
@@ -202,7 +289,7 @@ function requestHostedCheckoutRefund(state, purchaseIntentId, body) {
   return refund;
 }
 
-function normalizeHostedCheckoutEvent(state, body) {
+async function normalizeHostedCheckoutEvent(state, body) {
   const payload = ensureObject(body);
   const eventId = normalizeString(payload.event_id, null);
   if (eventId && state.checkoutEvents.has(eventId)) {
@@ -228,6 +315,7 @@ function normalizeHostedCheckoutEvent(state, body) {
       ? Number(payload.amount_received_minor)
       : purchaseIntent.price.amount_minor,
     currency: normalizeString(payload.currency, purchaseIntent.price.currency),
+    security_verification: ensureObject(payload.security_verification),
     timestamp,
     applied_status: "recorded",
     credits_event_id: null,
@@ -263,7 +351,7 @@ function normalizeHostedCheckoutEvent(state, body) {
         credits_issued: true
       };
     } else if (purchaseIntent.purchase_mode === "single_task_execution" || purchaseIntent.entitlement_mode === "execution_authorization") {
-      const bridgeDispatch = dispatchRuntimeBridgeRequest(state, {
+      const bridgeDispatch = await dispatchRuntimeBridgeRequest(state, {
         request_id: `bridge_${purchaseIntent.purchase_intent_id}`,
         account_id: purchaseIntent.account_id,
         capability_id: purchaseIntent.capability_id,
@@ -315,6 +403,48 @@ function normalizeHostedCheckoutEvent(state, body) {
       }
     });
     nextIntent.latest_refund_id = refund.refund_id;
+    const compensation = applyHostedCheckoutCompensation(state, purchaseIntent, event, refund);
+    event.compensation = compensation;
+    nextIntent.compensation = compensation;
+    if (compensation.compensation_state === "compensated") {
+      refund.status = "completed";
+      refund.action_code = "auto_compensated";
+      refund.updated_at_iso = nowIso();
+      refund.history = [
+        ...(Array.isArray(refund.history) ? refund.history : []),
+        {
+          at_iso: refund.updated_at_iso,
+          event: "auto_compensated",
+          note: paymentStatus === "chargeback"
+            ? "Chargeback compensation applied automatically"
+            : "Refund compensation applied automatically",
+          reason_code: refund.reason_code,
+          action_code: "auto_compensated",
+          previous_status: "requested",
+          next_status: "completed",
+          actor: { type: "system", role: "hosted_checkout_compensator" },
+          context: {
+            purchase_intent_id: purchaseIntent.purchase_intent_id,
+            provider_reference: event.provider_reference,
+            reversal_credit_event_id: compensation.reversal_credit_event_id
+          }
+        }
+      ].slice(-20);
+      state.refunds.set(refund.refund_id, refund);
+      nextIntent.customer_status = paymentStatus === "chargeback" ? "chargeback_compensated" : "refund_compensated";
+      event.applied_status = "auto_compensated";
+      if (nextIntent.fulfillment) {
+        nextIntent.fulfillment = {
+          ...nextIntent.fulfillment,
+          credits_issued: false
+        };
+      }
+    } else {
+      nextIntent.customer_status = paymentStatus === "chargeback" ? "chargeback_review_required" : "refund_review_required";
+      event.applied_status = compensation.compensation_state === "compensation_failed"
+        ? "compensation_failed"
+        : "refund_review_required";
+    }
   }
 
   state.checkoutPurchaseIntents.set(purchaseIntentId, nextIntent);