xytara 3.1.16 → 3.2.0

package/lib/commerce_bridge.js

@@ -1,274 +0,0 @@
-"use strict";
-
-// Generic external-commerce bridge — the name-neutral server-side contract an upstream
-// fiat SaaS front calls after a confirmed payment. Two jobs:
-//   1. /v1/commerce/grants         -> mint internal units for a confirmed purchase
-//      (reuses the proven external-credit-grant primitive; idempotent per upstream event
-//      so a payment-webhook retry never double-mints).
-//   2. /v1/commerce/prepare-execution -> issue a time-boxed DELEGATED-SPEND CREDENTIAL
-//      (the identity bridge) so the paying customer's agent can spend those units here,
-//      gated on sufficient balance.
-//   3. /v1/commerce/state          -> read-only unit balance for an account.
-//
-// This module names no upstream brand and the upstream names nothing here — the only
-// things crossing the seam are opaque refs + units. Routes are gated by the commerce-
-// bridge bearer (verifyCommerceBridgeAccess in server.js).
-
-const { createExternalCreditGrant } = require("./external_credit_bridge");
-const { createAuthorityBinding } = require("./account_auth");
-const { normalizeAgentPublicKey } = require("./agent_identity");
-const { buildCreditBalanceSummary, consumeAccountCredits } = require("./commerce_economics");
-const { findCreditPack } = require("../fixtures/catalog");
-
-function normalizeString(value, fallback = null) {
-  const s = typeof value === "string" ? value.trim() : "";
-  return s || fallback;
-}
-function ensureObject(value) {
-  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
-
-function loadCommercePackMap() {
-  const raw = String(process.env.XYTARA_COMMERCE_PACK_MAP_JSON || "").trim();
-  if (!raw) return {};
-  try {
-    const parsed = JSON.parse(raw);
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
-  } catch (_) {
-    return {};
-  }
-}
-
-// How many internal units a package/plan grants: explicit pack map first
-// (packageRef/planRef -> units), then a catalog credit pack's issued_units.
-function resolveCommerceUnits(packageRef, planRef) {
-  const map = loadCommercePackMap();
-  const key = packageRef || planRef;
-  if (key && Object.prototype.hasOwnProperty.call(map, key)) {
-    const n = Number(map[key]);
-    if (Number.isFinite(n) && n > 0) return { units: n, pack_id: key };
-  }
-  const pack = key ? findCreditPack(key) : null;
-  if (pack && Number.isFinite(Number(pack.issued_units)) && Number(pack.issued_units) > 0) {
-    return { units: Number(pack.issued_units), pack_id: pack.pack_id };
-  }
-  return { units: null, pack_id: key || null };
-}
-
-function availableUnits(state, accountId) {
-  const summary = buildCreditBalanceSummary(state, accountId);
-  if (!summary) return 0;
-  if (typeof summary.available_units === "number") return summary.available_units;
-  if (summary.balance && typeof summary.balance.available_units === "number") return summary.balance.available_units;
-  if (summary.lifecycle_totals && typeof summary.lifecycle_totals.available_units === "number") return summary.lifecycle_totals.available_units;
-  return 0;
-}
-
-// POST /v1/commerce/grants
-function grantCommerceAllocation(state, body) {
-  const b = ensureObject(body);
-  const accountRef = normalizeString(b.accountRef);
-  if (!accountRef) return { http_status: 400, body: { ok: false, reason: "account_ref_required" } };
-  // Require a single stable, globally-unique dedup anchor (the upstream event id). No
-  // fallback chain: an ambiguous anchor could either double-mint (retry omits eventRef)
-  // or wrongly dedup a distinct purchase whose ref collides with a prior eventRef.
-  const eventRef = normalizeString(b.eventRef);
-  if (!eventRef) return { http_status: 400, body: { ok: false, reason: "event_ref_required" } };
-  const { units, pack_id } = resolveCommerceUnits(normalizeString(b.packageRef), normalizeString(b.planRef));
-  if (!Number.isFinite(units) || units <= 0) {
-    return { http_status: 422, body: { ok: false, reason: "unknown_package", detail: "no unit mapping for the package/plan; set XYTARA_COMMERCE_PACK_MAP_JSON" } };
-  }
-  // Both the grant_id and the idempotency_key are account-namespaced so a shared eventRef
-  // across two accounts (upstreams whose event ids are per-account sequences) cannot
-  // collide on grant_id (checked first by createExternalCreditGrant) and under-mint one.
-  const dedupeAnchor = `${accountRef}:${eventRef}`;
-  const idempotencyKey = `commerce_grant:${dedupeAnchor}`;
-  const grant = createExternalCreditGrant(state, {
-    grant_id: `commerce_grant_${dedupeAnchor}`,
-    idempotency_key: idempotencyKey,
-    account_id: accountRef,
-    // units is explicit; do NOT pass pack_id (createExternalCreditGrant validates pack_id
-    // against the catalog and the package ref is an upstream key, not a catalog pack).
-    units,
-    source: "commerce_bridge",
-    rail_kind: "commerce_bridge",
-    reason: "commerce_grant",
-    provider_reference: normalizeString(b.providerRef),
-    purchase_reference: normalizeString(b.purchaseRef),
-    metadata: {
-      order_type: normalizeString(b.orderType),
-      checkout_surface: ensureObject(b.metadata).checkoutSurface || "public_checkout",
-      package_ref: pack_id || null,
-      event_ref: eventRef
-    }
-  });
-  if (grant && grant.ok === false) {
-    return { http_status: 422, body: { ok: false, reason: grant.reason || "commerce_grant_failed" } };
-  }
-  // Response fields mirror what the upstream client reads (camelCase) + snake aliases.
-  return {
-    http_status: 200,
-    body: {
-      ok: true,
-      status: "granted",
-      grantId: grant.grant_id,
-      grant_id: grant.grant_id,
-      accountRef,
-      account_ref: accountRef,
-      hiddenAccountRef: accountRef,
-      hidden_account_ref: accountRef,
-      units,
-      unitsGranted: units,
-      entitlementRef: grant.entitlement_id || null,
-      economicRef: grant.entitlement_id || null
-    }
-  };
-}
-
-// POST /v1/commerce/prepare-execution
-function prepareCommerceExecution(state, body) {
-  const b = ensureObject(body);
-  const accountRef = normalizeString(b.accountRef);
-  if (!accountRef) return { http_status: 400, body: { ok: false, reason: "account_ref_required" } };
-  const featureRef = normalizeString(b.featureRef);
-  const quotedUnits = Number.isFinite(Number(b.quotedUnits)) ? Number(b.quotedUnits) : 0;
-  const delegatedSpend = ensureObject(b.delegatedSpend);
-  const available = availableUnits(state, accountRef);
-
-  const refuse = (decision, extra) => ({
-    http_status: 200,
-    body: Object.assign({
-      ok: true,
-      authorized: false,
-      authorityMode: "delegated_spend_credential",
-      authorityDecision: decision,
-      spendAuthorityRef: null,
-      spendAuthorityToken: null,
-      validUntil: null,
-      delegatedSpendAccepted: false,
-      availableUnits: available,
-      quotedUnits,
-      capabilitySummary: []
-    }, extra || {})
-  });
-
-  // A bounded authorization requires a positive quote — the credential is capped to it.
-  if (!(quotedUnits > 0)) return refuse("quoted_units_required");
-  // Economic gate: only authorize when the account can cover the quote.
-  if (available < quotedUnits) return refuse("insufficient_units");
-
-  // Optional cryptographic agent-key binding. If an upstream intends identity binding
-  // but sends an unparseable key, REFUSE rather than silently downgrade to bearer-only
-  // (createSpendCredential would otherwise drop the key and still authorize).
-  const agentPublicKey = normalizeString(delegatedSpend.agent_public_key || delegatedSpend.agentPublicKey, null);
-  if (agentPublicKey && !normalizeAgentPublicKey(agentPublicKey)) {
-    return refuse("invalid_agent_key");
-  }
-
-  const ttlMs = Math.max(60000, Number(process.env.XYTARA_COMMERCE_PREP_TTL_MS || 900000) || 900000);
-  const validUntil = new Date(Date.now() + ttlMs).toISOString();
-
-  // Issue a BOUND delegated-spend credential via an authority binding: each spend action
-  // is capped at quotedUnits (max_commit/reserve/reversal), so the token can never commit
-  // more than the quote in one action and cannot drain the whole balance. Total spend is
-  // additionally hard-capped by the account balance at commit time. (Without a binding the
-  // credential is open_spend and the quote is not enforced.)
-  const binding = createAuthorityBinding(state, {
-    account_id: accountRef,
-    scope: "runtime_spend",
-    labels: [featureRef, "commerce_prepared"].filter(Boolean),
-    expires_at_iso: validUntil,
-    issued_by: "commerce_bridge",
-    // Constrain to spend/commit only — this credential is for executing paid work, not
-    // for driving reserve/release/reverse lifecycle actions.
-    authority_scope: ["runtime.execute"],
-    allowed_consequence_families: ["commit"],
-    max_commit_units: quotedUnits,
-    max_reserve_units: quotedUnits,
-    max_reversal_units: quotedUnits,
-    ...(agentPublicKey ? { agent_public_key: agentPublicKey } : {})
-  });
-  const credentialView = (binding && binding.spend_credential) || {};
-
-  return {
-    http_status: 200,
-    body: {
-      ok: true,
-      authorized: true,
-      authorityMode: "delegated_spend_credential",
-      authorityDecision: "authorized",
-      // The binding is the authority ref; its credential's bearer token is what the
-      // paying customer's agent presents to spend here. Opaque upstream.
-      spendAuthorityRef: binding.binding_id,
-      spendAuthorityToken: credentialView.bearer_token || null,
-      credentialRef: binding.credential_id || null,
-      identityBound: Boolean(credentialView.agent_key_ref),
-      boundUnits: quotedUnits,
-      proofMode: "credential_issued",
-      proofRef: binding.binding_id,
-      economicRef: binding.credential_id || null,
-      validUntil,
-      delegatedSpendAccepted: Boolean(b.delegatedSpend),
-      availableUnits: available,
-      quotedUnits,
-      capabilitySummary: [featureRef].filter(Boolean)
-    }
-  };
-}
-
-// POST /v1/commerce/settle
-// Server-side settlement for the trusted upstream seam: burn units against an account
-// after it has executed the paid work. The commerce bearer IS the authority here (this is
-// not a delegated-agent path), so there is no per-action bound — the account balance is
-// the hard cap (consumeAccountCredits refuses an overdraw). Returns the raw consume
-// result so an upstream caller reads the same credit_spend/usage_meter shape as the
-// direct consume route.
-function settleCommerceConsumption(state, body) {
-  const b = ensureObject(body);
-  const accountRef = normalizeString(b.accountRef || b.account_id);
-  if (!accountRef) return { http_status: 400, body: { ok: false, reason: "account_ref_required" } };
-  const units = Number(b.units);
-  if (!Number.isFinite(units) || units <= 0) {
-    return { http_status: 400, body: { ok: false, reason: "units_required" } };
-  }
-  const result = consumeAccountCredits(state, {
-    account_id: accountRef,
-    units,
-    task_ref: normalizeString(b.taskRef || b.task_ref),
-    workflow_ref: normalizeString(b.workflowRef || b.workflow_ref),
-    transaction_id: normalizeString(b.transactionRef || b.transaction_id),
-    quote_id: normalizeString(b.quoteRef || b.quote_id),
-    pack_id: normalizeString(b.packId || b.pack_id),
-    reason: normalizeString(b.reason, "commerce_settle")
-  });
-  if (result && result.ok === false) {
-    const http_status = result.reason === "insufficient_credits" ? 409 : 403;
-    return { http_status, body: result };
-  }
-  return { http_status: 200, body: result };
-}
-
-// GET /v1/commerce/state
-function inspectCommerceState(state, query) {
-  const accountRef = normalizeString(query && (query.accountRef || query.account_ref));
-  if (!accountRef) return { http_status: 400, body: { ok: false, reason: "account_ref_required" } };
-  const available = availableUnits(state, accountRef);
-  return {
-    http_status: 200,
-    body: {
-      ok: true,
-      accountRef,
-      account_ref: accountRef,
-      availableUnits: available,
-      available_units: available
-    }
-  };
-}
-
-module.exports = {
-  grantCommerceAllocation,
-  prepareCommerceExecution,
-  settleCommerceConsumption,
-  inspectCommerceState,
-  resolveCommerceUnits
-};

package/lib/commerce_cases.js

@@ -1,399 +0,0 @@
-"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
-};