xytara 3.1.13 → 3.1.14

package/lib/commerce_cases.js

@@ -1,399 +1,399 @@
-"use strict";
-
-const crypto = require("crypto");
-
-function setResultRemediation(state, transactionId, patch) {
-  if (!transactionId || !state.transactions.has(transactionId)) {
-    return;
-  }
-  const current = state.transactions.get(transactionId);
-  const currentTransactionRemediation = current.transaction && current.transaction.remediation && typeof current.transaction.remediation === "object"
-    ? current.transaction.remediation
-    : {};
-  const currentReceiptRemediation = current.receipt && current.receipt.remediation && typeof current.receipt.remediation === "object"
-    ? current.receipt.remediation
-    : {};
-  const nextRemediation = {
-    ...currentTransactionRemediation,
-    ...currentReceiptRemediation,
-    ...(patch || {}),
-    updated_at_iso: new Date().toISOString()
-  };
-  current.transaction.remediation = nextRemediation;
-  current.receipt.remediation = nextRemediation;
-}
-
-function appendHistory(record, event, body, nextStatus) {
-  const timestamp = new Date().toISOString();
-  const actor = body && body.actor && typeof body.actor === "object" ? body.actor : { type: "operator", role: "reviewer" };
-  const context = body && body.context && typeof body.context === "object" ? body.context : null;
-  const previousStatus = record.status || null;
-  return {
-    ...record,
-    status: nextStatus || record.status,
-    updated_at_iso: timestamp,
-    history: [
-      ...(Array.isArray(record.history) ? record.history : []),
-      {
-        at_iso: timestamp,
-        event,
-        note: body && typeof body.note === "string" ? body.note : null,
-        reason_code: body && typeof body.reason_code === "string" ? body.reason_code : record.reason_code || null,
-        action_code: body && typeof body.action_code === "string" ? body.action_code : null,
-        previous_status: previousStatus,
-        next_status: nextStatus || record.status,
-        actor,
-        context
-      }
-    ].slice(-20)
-  };
-}
-
-function createDispute(state, body) {
-  const timestamp = new Date().toISOString();
-  const actor = body && body.actor && typeof body.actor === "object" ? body.actor : { type: "operator", role: "creator" };
-  const context = body && body.context && typeof body.context === "object" ? body.context : null;
-  const dispute = {
-    dispute_id: `dsp_${crypto.randomBytes(6).toString("hex")}`,
-    title: typeof body.title === "string" && body.title.trim() ? body.title.trim() : "Dispute",
-    description: typeof body.description === "string" && body.description.trim() ? body.description.trim() : null,
-    status: "open",
-    transaction_id: body.transaction_id || null,
-    receipt_id: body.receipt_id || null,
-    reason_code: body.reason_code || "other",
-    note: body.note || null,
-    evidence: body && body.evidence && typeof body.evidence === "object" ? body.evidence : {},
-    created_at_iso: timestamp,
-    updated_at_iso: timestamp,
-    created_actor: actor,
-    created_context: context,
-    history: [
-      {
-        at_iso: timestamp,
-        event: "opened",
-        note: body.note || body.description || null,
-        reason_code: body.reason_code || "other",
-        action_code: null,
-        previous_status: null,
-        next_status: "open",
-        actor,
-        context
-      }
-    ]
-  };
-  state.disputes.set(dispute.dispute_id, dispute);
-  setResultRemediation(state, dispute.transaction_id, {
-    status: "under_dispute",
-    reason_code: dispute.reason_code,
-    active_case_type: "dispute",
-    active_case_id: dispute.dispute_id,
-    compensating_action_status: "none"
-  });
-  return dispute;
-}
-
-function createRefund(state, body) {
-  const timestamp = new Date().toISOString();
-  const actor = body && body.actor && typeof body.actor === "object" ? body.actor : { type: "operator", role: "creator" };
-  const context = body && body.context && typeof body.context === "object" ? body.context : null;
-  const refund = {
-    refund_id: `rfd_${crypto.randomBytes(6).toString("hex")}`,
-    status: "requested",
-    transaction_id: body.transaction_id || null,
-    receipt_id: body.receipt_id || null,
-    purchase_intent_id: body.purchase_intent_id || null,
-    reason_code: body.reason_code || "other",
-    note: body.note || null,
-    requested_by: typeof body.requested_by === "string" && body.requested_by.trim() ? body.requested_by.trim() : "operator",
-    created_at_iso: timestamp,
-    updated_at_iso: timestamp,
-    created_actor: actor,
-    created_context: context,
-    history: [
-      {
-        at_iso: timestamp,
-        event: "requested",
-        note: body.note || null,
-        reason_code: body.reason_code || "other",
-        action_code: null,
-        previous_status: null,
-        next_status: "requested",
-        actor,
-        context
-      }
-    ]
-  };
-  state.refunds.set(refund.refund_id, refund);
-  setResultRemediation(state, refund.transaction_id, {
-    status: "remediation_pending",
-    reason_code: refund.reason_code,
-    active_case_type: "refund",
-    active_case_id: refund.refund_id,
-    compensating_action_status: "none"
-  });
-  return refund;
-}
-
-function actOnDispute(state, disputeId, body) {
-  const current = state.disputes.get(disputeId);
-  if (!current) return null;
-  const action = String((body && body.action) || "").trim();
-  const statusByAction = {
-    review: "under_review",
-    escalate: "escalated",
-    reopen: "open",
-    resolve: "resolved",
-    dismiss: "dismissed"
-  };
-  const nextStatus = statusByAction[action] || current.status;
-  const next = appendHistory(current, action || "review", body, nextStatus);
-  if (body && typeof body.resolution_code === "string" && body.resolution_code.trim()) {
-    next.resolution_code = body.resolution_code.trim();
-  }
-  state.disputes.set(disputeId, next);
-  const remediationStatus = next.status === "resolved" || next.status === "dismissed"
-    ? "none"
-    : next.status === "escalated"
-      ? "escalated"
-      : "under_dispute";
-  setResultRemediation(state, next.transaction_id, {
-    status: remediationStatus,
-    reason_code: remediationStatus === "none" ? null : next.reason_code,
-    active_case_type: remediationStatus === "none" ? null : "dispute",
-    active_case_id: remediationStatus === "none" ? null : next.dispute_id,
-    compensating_action_status: remediationStatus === "none" ? null : "none"
-  });
-  return next;
-}
-
-function actOnRefund(state, refundId, body) {
-  const current = state.refunds.get(refundId);
-  if (!current) return null;
-  const action = String((body && body.action) || "").trim();
-  const allowedActionsByStatus = {
-    requested: ["review", "cancel"],
-    under_review: ["approve", "cancel", "fail", "pending_manual"],
-    approved: ["complete", "fail", "pending_manual", "cancel"],
-    pending_manual: ["complete", "fail", "cancel"],
-    failed: [],
-    completed: [],
-    cancelled: []
-  };
-  const allowedActions = allowedActionsByStatus[current.status] || [];
-  if (action && !allowedActions.includes(action)) {
-    return null;
-  }
-  const statusByAction = {
-    review: "under_review",
-    approve: "approved",
-    complete: "completed",
-    cancel: "cancelled",
-    fail: "failed",
-    pending_manual: "pending_manual"
-  };
-  const nextStatus = statusByAction[action] || current.status;
-  const next = appendHistory(current, action || "review", body, nextStatus);
-  if (body && typeof body.action_code === "string" && body.action_code.trim()) {
-    next.action_code = body.action_code.trim();
-  }
-  state.refunds.set(refundId, next);
-  const remediationStatus = next.status === "completed"
-    ? "compensated"
-    : next.status === "cancelled"
-      ? "none"
-    : next.status === "approved"
-      ? "remediation_pending"
-    : next.status === "pending_manual"
-      ? "remediation_pending"
-    : next.status === "failed"
-      ? "compensation_failed"
-      : "remediation_pending";
-  setResultRemediation(state, next.transaction_id, {
-    status: remediationStatus,
-    reason_code: remediationStatus === "none" ? null : next.reason_code,
-    active_case_type: remediationStatus === "compensated" || remediationStatus === "none" ? null : "refund",
-    active_case_id: remediationStatus === "compensated" || remediationStatus === "none" ? null : next.refund_id,
-    compensating_action_status: remediationStatus === "none" ? null : next.status
-  });
-  return next;
-}
-
-function createRemediationTicket(state, body) {
-  const timestamp = new Date().toISOString();
-  const actor = body && body.actor && typeof body.actor === "object" ? body.actor : { type: "operator", role: "creator" };
-  const context = body && body.context && typeof body.context === "object" ? body.context : null;
-  const ticket = {
-    ticket_id: `rmt_${crypto.randomBytes(6).toString("hex")}`,
-    status: "open",
-    transaction_id: body.transaction_id || null,
-    receipt_id: body.receipt_id || null,
-    reason_code: body.reason_code || "other",
-    action_code: body.action_code || "investigate",
-    assigned_owner: typeof body.assigned_owner === "string" && body.assigned_owner.trim() ? body.assigned_owner.trim() : null,
-    note: body.note || null,
-    created_at_iso: timestamp,
-    updated_at_iso: timestamp,
-    created_actor: actor,
-    created_context: context,
-    history: [
-      {
-        at_iso: timestamp,
-        event: "opened",
-        note: body.note || null,
-        reason_code: body.reason_code || "other",
-        action_code: body.action_code || "investigate",
-        previous_status: null,
-        next_status: "open",
-        actor,
-        context
-      }
-    ]
-  };
-  state.remediationTickets.set(ticket.ticket_id, ticket);
-  setResultRemediation(state, ticket.transaction_id, {
-    status: "remediation_pending",
-    reason_code: ticket.reason_code,
-    active_case_type: "remediation_ticket",
-    active_case_id: ticket.ticket_id,
-    compensating_action_status: ticket.action_code
-  });
-  return ticket;
-}
-
-function actOnRemediationTicket(state, ticketId, body) {
-  const current = state.remediationTickets.get(ticketId);
-  if (!current) return null;
-  const action = String((body && body.action) || "").trim();
-  const statusByAction = {
-    acknowledge: "acknowledged",
-    assign: "assigned",
-    escalate: "escalated",
-    resolve: "resolved",
-    clear: "cleared"
-  };
-  const next = appendHistory(current, action || "acknowledge", body, statusByAction[action] || current.status);
-  if (body && body.reason_code) {
-    next.reason_code = body.reason_code;
-  }
-  if (body && body.action_code) {
-    next.action_code = body.action_code;
-  }
-  if (body && typeof body.assigned_owner === "string" && body.assigned_owner.trim()) {
-    next.assigned_owner = body.assigned_owner.trim();
-  }
-  if (body && typeof body.note === "string" && body.note.trim()) {
-    if (next.status === "assigned") {
-      next.assignment_note = body.note.trim();
-    }
-    if (next.status === "cleared") {
-      next.cleared_note = body.note.trim();
-    }
-  }
-  state.remediationTickets.set(ticketId, next);
-  const remediationStatus = next.status === "cleared"
-    ? "none"
-    : next.status === "resolved"
-      ? "none"
-    : next.status === "escalated"
-      ? "escalated"
-      : "remediation_pending";
-  setResultRemediation(state, next.transaction_id, {
-    status: remediationStatus,
-    reason_code: remediationStatus === "none" ? null : next.reason_code,
-    active_case_type: remediationStatus === "none" ? null : "remediation_ticket",
-    active_case_id: remediationStatus === "none" ? null : next.ticket_id,
-    compensating_action_status: remediationStatus === "none" ? null : next.action_code
-  });
-  return next;
-}
-
-function resolveRefundAccountId(state, refund, body) {
-  const explicit = body && typeof body.account_id === "string" && body.account_id.trim() ? body.account_id.trim() : null;
-  if (explicit) return explicit;
-  const txId = refund && refund.transaction_id;
-  if (txId && state.transactions && state.transactions.has(txId)) {
-    const record = state.transactions.get(txId);
-    const fromTx = record && ((record.transaction && record.transaction.account_id) || record.account_id);
-    if (typeof fromTx === "string" && fromTx.trim()) return fromTx.trim();
-  }
-  return null;
-}
-
-// Settle a refund by returning value to the paying account as re-spendable CREDITS.
-// This is deliberately NOT an autonomous outbound transfer: it only MINTS credits into
-// the account's balance (reusing the proven external-credit-grant primitive) and never
-// moves funds out of the treasury. The credited amount is operator-controlled
-// (refund_units, required) rather than auto-derived, and the operation is idempotent per
-// refund (grant_id = refund_credit_<id>), so a refund can never mint twice. The caller
-// (server route) MUST gate this behind the credit-bridge bearer, exactly like direct
-// credit grants, so a refund cannot become an unauthenticated credit-minting bypass.
-function settleRefundAsCredit(state, refundId, body) {
-  const refund = state.refunds.get(refundId);
-  if (!refund) return { ok: false, status: 404, reason: "refund_not_found" };
-  if (refund.credit_grant_id) {
-    return { ok: true, status: 200, already_settled: true, refund, grant_id: refund.credit_grant_id };
-  }
-  const settleableStatuses = new Set(["requested", "under_review", "approved", "pending_manual"]);
-  if (!settleableStatuses.has(refund.status)) {
-    return { ok: false, status: 409, reason: "refund_not_settleable", detail: `refund status is ${refund.status}` };
-  }
-  const units = Number(body && body.refund_units);
-  if (!Number.isFinite(units) || units <= 0) {
-    return { ok: false, status: 400, reason: "refund_units_required", detail: "provide a positive refund_units to return value as credits" };
-  }
-  const accountId = resolveRefundAccountId(state, refund, body);
-  if (!accountId) {
-    return { ok: false, status: 400, reason: "refund_account_unresolved", detail: "provide account_id or link the refund to a known transaction" };
-  }
-  const { createExternalCreditGrant } = require("./external_credit_bridge");
-  const grant = createExternalCreditGrant(state, {
-    grant_id: `refund_credit_${refund.refund_id}`,
-    idempotency_key: `refund_credit_${refund.refund_id}`,
-    account_id: accountId,
-    units,
-    amount_minor: Number.isFinite(Number(body && body.refund_amount_minor)) ? Number(body.refund_amount_minor) : null,
-    currency: body && typeof body.currency === "string" && body.currency.trim() ? body.currency.trim() : null,
-    source: "refund_credit",
-    // Honest ledger labeling: refund-origin credits bucket under their own rail_kind/
-    // reason so rail-summary views never conflate them with external-checkout money-in.
-    rail_kind: "refund_credit_bridge",
-    reason: "refund_credit",
-    metadata: {
-      refund_id: refund.refund_id,
-      transaction_id: refund.transaction_id || null,
-      reason_code: refund.reason_code || null
-    }
-  });
-  if (grant && grant.ok === false) {
-    return { ok: false, status: 422, reason: grant.reason || "refund_credit_failed" };
-  }
-  const next = appendHistory(refund, "settle_credit", body, "completed");
-  next.credit_grant_id = grant.grant_id;
-  next.refunded_units = units;
-  next.refund_settlement = {
-    mode: "credit",
-    grant_id: grant.grant_id,
-    account_id: accountId,
-    units,
-    amount_minor: grant.amount_minor != null ? grant.amount_minor : null
-  };
-  state.refunds.set(refundId, next);
-  setResultRemediation(state, next.transaction_id, {
-    status: "compensated",
-    reason_code: null,
-    active_case_type: null,
-    active_case_id: null,
-    compensating_action_status: "completed"
-  });
-  return { ok: true, status: 200, refund: next, grant_id: grant.grant_id, account_id: accountId, units };
-}
-
-module.exports = {
-  actOnDispute,
-  actOnRefund,
-  actOnRemediationTicket,
-  createDispute,
-  createRefund,
-  createRemediationTicket,
-  settleRefundAsCredit
-};
+"use strict";
+
+const crypto = require("crypto");
+
+function setResultRemediation(state, transactionId, patch) {
+  if (!transactionId || !state.transactions.has(transactionId)) {
+    return;
+  }
+  const current = state.transactions.get(transactionId);
+  const currentTransactionRemediation = current.transaction && current.transaction.remediation && typeof current.transaction.remediation === "object"
+    ? current.transaction.remediation
+    : {};
+  const currentReceiptRemediation = current.receipt && current.receipt.remediation && typeof current.receipt.remediation === "object"
+    ? current.receipt.remediation
+    : {};
+  const nextRemediation = {
+    ...currentTransactionRemediation,
+    ...currentReceiptRemediation,
+    ...(patch || {}),
+    updated_at_iso: new Date().toISOString()
+  };
+  current.transaction.remediation = nextRemediation;
+  current.receipt.remediation = nextRemediation;
+}
+
+function appendHistory(record, event, body, nextStatus) {
+  const timestamp = new Date().toISOString();
+  const actor = body && body.actor && typeof body.actor === "object" ? body.actor : { type: "operator", role: "reviewer" };
+  const context = body && body.context && typeof body.context === "object" ? body.context : null;
+  const previousStatus = record.status || null;
+  return {
+    ...record,
+    status: nextStatus || record.status,
+    updated_at_iso: timestamp,
+    history: [
+      ...(Array.isArray(record.history) ? record.history : []),
+      {
+        at_iso: timestamp,
+        event,
+        note: body && typeof body.note === "string" ? body.note : null,
+        reason_code: body && typeof body.reason_code === "string" ? body.reason_code : record.reason_code || null,
+        action_code: body && typeof body.action_code === "string" ? body.action_code : null,
+        previous_status: previousStatus,
+        next_status: nextStatus || record.status,
+        actor,
+        context
+      }
+    ].slice(-20)
+  };
+}
+
+function createDispute(state, body) {
+  const timestamp = new Date().toISOString();
+  const actor = body && body.actor && typeof body.actor === "object" ? body.actor : { type: "operator", role: "creator" };
+  const context = body && body.context && typeof body.context === "object" ? body.context : null;
+  const dispute = {
+    dispute_id: `dsp_${crypto.randomBytes(6).toString("hex")}`,
+    title: typeof body.title === "string" && body.title.trim() ? body.title.trim() : "Dispute",
+    description: typeof body.description === "string" && body.description.trim() ? body.description.trim() : null,
+    status: "open",
+    transaction_id: body.transaction_id || null,
+    receipt_id: body.receipt_id || null,
+    reason_code: body.reason_code || "other",
+    note: body.note || null,
+    evidence: body && body.evidence && typeof body.evidence === "object" ? body.evidence : {},
+    created_at_iso: timestamp,
+    updated_at_iso: timestamp,
+    created_actor: actor,
+    created_context: context,
+    history: [
+      {
+        at_iso: timestamp,
+        event: "opened",
+        note: body.note || body.description || null,
+        reason_code: body.reason_code || "other",
+        action_code: null,
+        previous_status: null,
+        next_status: "open",
+        actor,
+        context
+      }
+    ]
+  };
+  state.disputes.set(dispute.dispute_id, dispute);
+  setResultRemediation(state, dispute.transaction_id, {
+    status: "under_dispute",
+    reason_code: dispute.reason_code,
+    active_case_type: "dispute",
+    active_case_id: dispute.dispute_id,
+    compensating_action_status: "none"
+  });
+  return dispute;
+}
+
+function createRefund(state, body) {
+  const timestamp = new Date().toISOString();
+  const actor = body && body.actor && typeof body.actor === "object" ? body.actor : { type: "operator", role: "creator" };
+  const context = body && body.context && typeof body.context === "object" ? body.context : null;
+  const refund = {
+    refund_id: `rfd_${crypto.randomBytes(6).toString("hex")}`,
+    status: "requested",
+    transaction_id: body.transaction_id || null,
+    receipt_id: body.receipt_id || null,
+    purchase_intent_id: body.purchase_intent_id || null,
+    reason_code: body.reason_code || "other",
+    note: body.note || null,
+    requested_by: typeof body.requested_by === "string" && body.requested_by.trim() ? body.requested_by.trim() : "operator",
+    created_at_iso: timestamp,
+    updated_at_iso: timestamp,
+    created_actor: actor,
+    created_context: context,
+    history: [
+      {
+        at_iso: timestamp,
+        event: "requested",
+        note: body.note || null,
+        reason_code: body.reason_code || "other",
+        action_code: null,
+        previous_status: null,
+        next_status: "requested",
+        actor,
+        context
+      }
+    ]
+  };
+  state.refunds.set(refund.refund_id, refund);
+  setResultRemediation(state, refund.transaction_id, {
+    status: "remediation_pending",
+    reason_code: refund.reason_code,
+    active_case_type: "refund",
+    active_case_id: refund.refund_id,
+    compensating_action_status: "none"
+  });
+  return refund;
+}
+
+function actOnDispute(state, disputeId, body) {
+  const current = state.disputes.get(disputeId);
+  if (!current) return null;
+  const action = String((body && body.action) || "").trim();
+  const statusByAction = {
+    review: "under_review",
+    escalate: "escalated",
+    reopen: "open",
+    resolve: "resolved",
+    dismiss: "dismissed"
+  };
+  const nextStatus = statusByAction[action] || current.status;
+  const next = appendHistory(current, action || "review", body, nextStatus);
+  if (body && typeof body.resolution_code === "string" && body.resolution_code.trim()) {
+    next.resolution_code = body.resolution_code.trim();
+  }
+  state.disputes.set(disputeId, next);
+  const remediationStatus = next.status === "resolved" || next.status === "dismissed"
+    ? "none"
+    : next.status === "escalated"
+      ? "escalated"
+      : "under_dispute";
+  setResultRemediation(state, next.transaction_id, {
+    status: remediationStatus,
+    reason_code: remediationStatus === "none" ? null : next.reason_code,
+    active_case_type: remediationStatus === "none" ? null : "dispute",
+    active_case_id: remediationStatus === "none" ? null : next.dispute_id,
+    compensating_action_status: remediationStatus === "none" ? null : "none"
+  });
+  return next;
+}
+
+function actOnRefund(state, refundId, body) {
+  const current = state.refunds.get(refundId);
+  if (!current) return null;
+  const action = String((body && body.action) || "").trim();
+  const allowedActionsByStatus = {
+    requested: ["review", "cancel"],
+    under_review: ["approve", "cancel", "fail", "pending_manual"],
+    approved: ["complete", "fail", "pending_manual", "cancel"],
+    pending_manual: ["complete", "fail", "cancel"],
+    failed: [],
+    completed: [],
+    cancelled: []
+  };
+  const allowedActions = allowedActionsByStatus[current.status] || [];
+  if (action && !allowedActions.includes(action)) {
+    return null;
+  }
+  const statusByAction = {
+    review: "under_review",
+    approve: "approved",
+    complete: "completed",
+    cancel: "cancelled",
+    fail: "failed",
+    pending_manual: "pending_manual"
+  };
+  const nextStatus = statusByAction[action] || current.status;
+  const next = appendHistory(current, action || "review", body, nextStatus);
+  if (body && typeof body.action_code === "string" && body.action_code.trim()) {
+    next.action_code = body.action_code.trim();
+  }
+  state.refunds.set(refundId, next);
+  const remediationStatus = next.status === "completed"
+    ? "compensated"
+    : next.status === "cancelled"
+      ? "none"
+    : next.status === "approved"
+      ? "remediation_pending"
+    : next.status === "pending_manual"
+      ? "remediation_pending"
+    : next.status === "failed"
+      ? "compensation_failed"
+      : "remediation_pending";
+  setResultRemediation(state, next.transaction_id, {
+    status: remediationStatus,
+    reason_code: remediationStatus === "none" ? null : next.reason_code,
+    active_case_type: remediationStatus === "compensated" || remediationStatus === "none" ? null : "refund",
+    active_case_id: remediationStatus === "compensated" || remediationStatus === "none" ? null : next.refund_id,
+    compensating_action_status: remediationStatus === "none" ? null : next.status
+  });
+  return next;
+}
+
+function createRemediationTicket(state, body) {
+  const timestamp = new Date().toISOString();
+  const actor = body && body.actor && typeof body.actor === "object" ? body.actor : { type: "operator", role: "creator" };
+  const context = body && body.context && typeof body.context === "object" ? body.context : null;
+  const ticket = {
+    ticket_id: `rmt_${crypto.randomBytes(6).toString("hex")}`,
+    status: "open",
+    transaction_id: body.transaction_id || null,
+    receipt_id: body.receipt_id || null,
+    reason_code: body.reason_code || "other",
+    action_code: body.action_code || "investigate",
+    assigned_owner: typeof body.assigned_owner === "string" && body.assigned_owner.trim() ? body.assigned_owner.trim() : null,
+    note: body.note || null,
+    created_at_iso: timestamp,
+    updated_at_iso: timestamp,
+    created_actor: actor,
+    created_context: context,
+    history: [
+      {
+        at_iso: timestamp,
+        event: "opened",
+        note: body.note || null,
+        reason_code: body.reason_code || "other",
+        action_code: body.action_code || "investigate",
+        previous_status: null,
+        next_status: "open",
+        actor,
+        context
+      }
+    ]
+  };
+  state.remediationTickets.set(ticket.ticket_id, ticket);
+  setResultRemediation(state, ticket.transaction_id, {
+    status: "remediation_pending",
+    reason_code: ticket.reason_code,
+    active_case_type: "remediation_ticket",
+    active_case_id: ticket.ticket_id,
+    compensating_action_status: ticket.action_code
+  });
+  return ticket;
+}
+
+function actOnRemediationTicket(state, ticketId, body) {
+  const current = state.remediationTickets.get(ticketId);
+  if (!current) return null;
+  const action = String((body && body.action) || "").trim();
+  const statusByAction = {
+    acknowledge: "acknowledged",
+    assign: "assigned",
+    escalate: "escalated",
+    resolve: "resolved",
+    clear: "cleared"
+  };
+  const next = appendHistory(current, action || "acknowledge", body, statusByAction[action] || current.status);
+  if (body && body.reason_code) {
+    next.reason_code = body.reason_code;
+  }
+  if (body && body.action_code) {
+    next.action_code = body.action_code;
+  }
+  if (body && typeof body.assigned_owner === "string" && body.assigned_owner.trim()) {
+    next.assigned_owner = body.assigned_owner.trim();
+  }
+  if (body && typeof body.note === "string" && body.note.trim()) {
+    if (next.status === "assigned") {
+      next.assignment_note = body.note.trim();
+    }
+    if (next.status === "cleared") {
+      next.cleared_note = body.note.trim();
+    }
+  }
+  state.remediationTickets.set(ticketId, next);
+  const remediationStatus = next.status === "cleared"
+    ? "none"
+    : next.status === "resolved"
+      ? "none"
+    : next.status === "escalated"
+      ? "escalated"
+      : "remediation_pending";
+  setResultRemediation(state, next.transaction_id, {
+    status: remediationStatus,
+    reason_code: remediationStatus === "none" ? null : next.reason_code,
+    active_case_type: remediationStatus === "none" ? null : "remediation_ticket",
+    active_case_id: remediationStatus === "none" ? null : next.ticket_id,
+    compensating_action_status: remediationStatus === "none" ? null : next.action_code
+  });
+  return next;
+}
+
+function resolveRefundAccountId(state, refund, body) {
+  const explicit = body && typeof body.account_id === "string" && body.account_id.trim() ? body.account_id.trim() : null;
+  if (explicit) return explicit;
+  const txId = refund && refund.transaction_id;
+  if (txId && state.transactions && state.transactions.has(txId)) {
+    const record = state.transactions.get(txId);
+    const fromTx = record && ((record.transaction && record.transaction.account_id) || record.account_id);
+    if (typeof fromTx === "string" && fromTx.trim()) return fromTx.trim();
+  }
+  return null;
+}
+
+// Settle a refund by returning value to the paying account as re-spendable CREDITS.
+// This is deliberately NOT an autonomous outbound transfer: it only MINTS credits into
+// the account's balance (reusing the proven external-credit-grant primitive) and never
+// moves funds out of the treasury. The credited amount is operator-controlled
+// (refund_units, required) rather than auto-derived, and the operation is idempotent per
+// refund (grant_id = refund_credit_<id>), so a refund can never mint twice. The caller
+// (server route) MUST gate this behind the credit-bridge bearer, exactly like direct
+// credit grants, so a refund cannot become an unauthenticated credit-minting bypass.
+function settleRefundAsCredit(state, refundId, body) {
+  const refund = state.refunds.get(refundId);
+  if (!refund) return { ok: false, status: 404, reason: "refund_not_found" };
+  if (refund.credit_grant_id) {
+    return { ok: true, status: 200, already_settled: true, refund, grant_id: refund.credit_grant_id };
+  }
+  const settleableStatuses = new Set(["requested", "under_review", "approved", "pending_manual"]);
+  if (!settleableStatuses.has(refund.status)) {
+    return { ok: false, status: 409, reason: "refund_not_settleable", detail: `refund status is ${refund.status}` };
+  }
+  const units = Number(body && body.refund_units);
+  if (!Number.isFinite(units) || units <= 0) {
+    return { ok: false, status: 400, reason: "refund_units_required", detail: "provide a positive refund_units to return value as credits" };
+  }
+  const accountId = resolveRefundAccountId(state, refund, body);
+  if (!accountId) {
+    return { ok: false, status: 400, reason: "refund_account_unresolved", detail: "provide account_id or link the refund to a known transaction" };
+  }
+  const { createExternalCreditGrant } = require("./external_credit_bridge");
+  const grant = createExternalCreditGrant(state, {
+    grant_id: `refund_credit_${refund.refund_id}`,
+    idempotency_key: `refund_credit_${refund.refund_id}`,
+    account_id: accountId,
+    units,
+    amount_minor: Number.isFinite(Number(body && body.refund_amount_minor)) ? Number(body.refund_amount_minor) : null,
+    currency: body && typeof body.currency === "string" && body.currency.trim() ? body.currency.trim() : null,
+    source: "refund_credit",
+    // Honest ledger labeling: refund-origin credits bucket under their own rail_kind/
+    // reason so rail-summary views never conflate them with external-checkout money-in.
+    rail_kind: "refund_credit_bridge",
+    reason: "refund_credit",
+    metadata: {
+      refund_id: refund.refund_id,
+      transaction_id: refund.transaction_id || null,
+      reason_code: refund.reason_code || null
+    }
+  });
+  if (grant && grant.ok === false) {
+    return { ok: false, status: 422, reason: grant.reason || "refund_credit_failed" };
+  }
+  const next = appendHistory(refund, "settle_credit", body, "completed");
+  next.credit_grant_id = grant.grant_id;
+  next.refunded_units = units;
+  next.refund_settlement = {
+    mode: "credit",
+    grant_id: grant.grant_id,
+    account_id: accountId,
+    units,
+    amount_minor: grant.amount_minor != null ? grant.amount_minor : null
+  };
+  state.refunds.set(refundId, next);
+  setResultRemediation(state, next.transaction_id, {
+    status: "compensated",
+    reason_code: null,
+    active_case_type: null,
+    active_case_id: null,
+    compensating_action_status: "completed"
+  });
+  return { ok: true, status: 200, refund: next, grant_id: grant.grant_id, account_id: accountId, units };
+}
+
+module.exports = {
+  actOnDispute,
+  actOnRefund,
+  actOnRemediationTicket,
+  createDispute,
+  createRefund,
+  createRemediationTicket,
+  settleRefundAsCredit
+};