xytara 2.5.0 → 2.6.0

package/lib/network_transport.js

@@ -0,0 +1,110 @@
+"use strict";
+
+const dns = require("dns");
+let Agent = null;
+try {
+  ({ Agent } = require("undici"));
+} catch (_) {
+  Agent = null;
+}
+
+const dispatcherCache = new Map();
+let configuredDnsResultOrder = null;
+
+function normalizeString(value, fallback = "") {
+  const raw = typeof value === "string" ? value.trim() : "";
+  return raw || fallback;
+}
+
+function normalizeFamily(value) {
+  const normalized = normalizeString(value).toLowerCase();
+  if (!normalized || normalized === "auto" || normalized === "any" || normalized === "0") return null;
+  if (normalized === "4" || normalized === "ipv4") return 4;
+  if (normalized === "6" || normalized === "ipv6") return 6;
+  return null;
+}
+
+function normalizeDnsResultOrder(value) {
+  const normalized = normalizeString(value).toLowerCase();
+  if (!normalized) return "verbatim";
+  if (normalized === "ipv4first" || normalized === "ipv6first" || normalized === "verbatim") return normalized;
+  return "verbatim";
+}
+
+function loadNetworkTransportConfig() {
+  const globalFamily = normalizeFamily(process.env.XYTARA_NETWORK_PREFERRED_IP_FAMILY);
+  const dnsResultOrder = normalizeDnsResultOrder(process.env.XYTARA_NETWORK_DNS_RESULT_ORDER);
+  return {
+    dns_result_order: dnsResultOrder,
+    global_family: globalFamily,
+    external_execution_family: normalizeFamily(process.env.XYTARA_EXTERNAL_EXECUTION_IP_FAMILY) || globalFamily,
+    callback_family: normalizeFamily(process.env.XYTARA_CALLBACK_IP_FAMILY) || globalFamily,
+    settlement_family: normalizeFamily(process.env.XYTARA_SETTLEMENT_IP_FAMILY) || globalFamily
+  };
+}
+
+function ensureDnsResultOrderConfigured(config) {
+  const effective = config && config.dns_result_order ? config.dns_result_order : "verbatim";
+  if (configuredDnsResultOrder === effective) return;
+  dns.setDefaultResultOrder(effective);
+  configuredDnsResultOrder = effective;
+}
+
+function getDispatcherForFamily(family) {
+  if (!Agent) return null;
+  if (!family) return null;
+  const key = String(family);
+  if (dispatcherCache.has(key)) return dispatcherCache.get(key);
+  const dispatcher = new Agent({
+    connect: {
+      family
+    }
+  });
+  dispatcherCache.set(key, dispatcher);
+  return dispatcher;
+}
+
+function buildFetchOptionsForPurpose(purpose, baseOptions = {}) {
+  const config = loadNetworkTransportConfig();
+  ensureDnsResultOrderConfigured(config);
+  const purposeKey = normalizeString(purpose, "external_execution");
+  const family = purposeKey === "callback"
+    ? config.callback_family
+    : purposeKey === "settlement"
+      ? config.settlement_family
+      : config.external_execution_family;
+  const dispatcher = getDispatcherForFamily(family);
+  return dispatcher
+    ? { ...baseOptions, dispatcher }
+    : { ...baseOptions };
+}
+
+function buildNetworkTransportSummary() {
+  const config = loadNetworkTransportConfig();
+  ensureDnsResultOrderConfigured(config);
+  const classify = (family) => family === 4 ? "ipv4" : family === 6 ? "ipv6" : "auto";
+  return {
+    ok: true,
+    category: "machine-commerce-network-transport-summary",
+    summary_version: "xytara-network-transport-summary-v1",
+    dns_result_order: config.dns_result_order,
+    preferred_families: {
+      global: classify(config.global_family),
+      external_execution: classify(config.external_execution_family),
+      callback_delivery: classify(config.callback_family),
+      settlement_transport: classify(config.settlement_family)
+    },
+    posture: "dual-stack_capable_with_operator-selectable_ip_family_preferences",
+    linked_surfaces: {
+      external_execution_ref: "/v1/capability-registry/execution-truth",
+      callback_security_ref: "/v1/checkout/events/security",
+      settlement_readiness_ref: "/v1/settlement/bsv-teranode/readiness"
+    }
+  };
+}
+
+module.exports = {
+  buildFetchOptionsForPurpose,
+  buildNetworkTransportSummary,
+  loadNetworkTransportConfig
+};

package/lib/operator_intelligence.js

@@ -1,7 +1,103 @@
 "use strict";
 
+const { summarizeActivityLedger } = require("./activity_audit_contract");
 const { buildEconomicsIntelligenceSummary } = require("./commerce_economics");
 const { buildPartnerIntelligencePack } = require("./partner_intelligence");
+const { buildRevenueSignalSummary } = require("./pricing_optimization_contract");
+
+function valuesFromCollection(collection) {
+  if (!collection) return [];
+  if (collection instanceof Map) return Array.from(collection.values());
+  return Array.isArray(collection) ? collection : [];
+}
+
+function unwrapTransaction(entry) {
+  if (entry && entry.transaction) return entry.transaction;
+  return entry || null;
+}
+
+function countBy(values, selector) {
+  return values.reduce((acc, value) => {
+    const key = selector(value) || "unknown";
+    acc[key] = (acc[key] || 0) + 1;
+    return acc;
+  }, {});
+}
+
+function countAdapterFailures(transactions) {
+  return transactions.filter((transaction) => {
+    const execution = transaction && transaction.execution;
+    const results = execution && execution.results_by_task_id && typeof execution.results_by_task_id === "object"
+      ? Object.values(execution.results_by_task_id)
+      : [];
+    return transaction && transaction.status === "failed"
+      || execution && execution.status === "failed"
+      || results.some((result) => result && (
+        result.status === "failed"
+        || result.invocation_status === "provider_failed"
+        || result.provider_status === "failed"
+      ));
+  }).length;
+}
+
+function latestIso(values, fieldNames) {
+  const timestamps = values
+    .flatMap((value) => fieldNames.map((fieldName) => value && value[fieldName]).filter(Boolean))
+    .map((value) => Date.parse(value))
+    .filter((value) => Number.isFinite(value))
+    .sort((left, right) => right - left);
+  return timestamps.length ? new Date(timestamps[0]).toISOString() : null;
+}
+
+function buildAttentionQueue({ counts, revenueSignals }) {
+  const queue = [];
+  if (counts.adapter_failure_count > 0) {
+    queue.push({
+      lane: "adapter_execution",
+      priority: "high",
+      action: "inspect_adapter_failures",
+      surface_ref: "/v1/runtime-bridge/dispatches",
+      reason: "provider-backed execution reported failed adapter outcomes"
+    });
+  }
+  if (counts.failed_settlement_count > 0 || counts.pending_settlement_count > 0) {
+    queue.push({
+      lane: "settlement",
+      priority: counts.failed_settlement_count > 0 ? "high" : "medium",
+      action: "inspect_native_settlement_records",
+      surface_ref: "/v1/settlement/bsv-teranode",
+      reason: "settlement records are failed or waiting for submission/finality"
+    });
+  }
+  if (counts.payment_count > counts.delivery_count) {
+    queue.push({
+      lane: "delivery",
+      priority: "medium",
+      action: "compare_payment_ledger_to_deliveries",
+      surface_ref: "/v1/deliveries",
+      reason: "payment count is higher than delivery count"
+    });
+  }
+  if (revenueSignals.sample_maturity === "sparse_live_signals") {
+    queue.push({
+      lane: "pricing_telemetry",
+      priority: "low",
+      action: "continue_collecting_live_quote_and_execution_metrics",
+      surface_ref: "/v1/pricing-optimization/revenue-signal-summary",
+      reason: "pricing recommendations should stay conservative while live samples are sparse"
+    });
+  }
+  if (queue.length === 0) {
+    queue.push({
+      lane: "operator_posture",
+      priority: "low",
+      action: "continue_current_observability_cadence",
+      surface_ref: "/v1/operator-observability/summary",
+      reason: "no immediate operator attention item crossed the current thresholds"
+    });
+  }
+  return queue;
+}
 
 function buildOperatorIntelligencePack(state, input) {
   const payload = input && typeof input === "object" && !Array.isArray(input) ? input : {};
@@ -84,7 +180,125 @@ function summarizeOperatorIntelligencePack(state, input) {
   };
 }
 
+function buildOperatorObservabilityPack(state, input) {
+  const payload = input && typeof input === "object" && !Array.isArray(input) ? input : {};
+  const accountId = String(payload.account_id || "").trim() || null;
+  const quotes = valuesFromCollection(state && state.quotes).filter((quote) => !accountId || quote.account_id === accountId);
+  const transactions = valuesFromCollection(state && state.transactions)
+    .map(unwrapTransaction)
+    .filter(Boolean)
+    .filter((transaction) => !accountId || transaction.account_id === accountId);
+  const receipts = valuesFromCollection(state && state.receipts)
+    .map((entry) => entry && entry.receipt ? entry.receipt : entry)
+    .filter(Boolean)
+    .filter((receipt) => !accountId || receipt.account_id === accountId);
+  const deliveries = valuesFromCollection(state && state.deliveries).filter((delivery) => !accountId || delivery.account_id === accountId);
+  const payments = (Array.isArray(state && state.paymentLedger) ? state.paymentLedger : [])
+    .filter((payment) => !accountId || payment.account_id === accountId);
+  const externalCreditGrants = valuesFromCollection(state && state.externalCreditGrants)
+    .filter((grant) => !accountId || grant.account_id === accountId);
+  const settlements = valuesFromCollection(state && state.bsvSettlementRecords)
+    .filter((settlement) => !accountId || settlement.account_id === accountId);
+  const activitySummary = summarizeActivityLedger(state, { account_id: accountId });
+  const revenueSignals = buildRevenueSignalSummary(state);
+  const failedSettlementCount = settlements.filter((settlement) => settlement && settlement.status === "failed").length;
+  const pendingSettlementCount = settlements.filter((settlement) => settlement && (
+    settlement.status === "ready_for_submission"
+    || settlement.finality_status === "pending_submission"
+    || settlement.finality_status === "pending_confirmation"
+  )).length;
+  const counts = {
+    quote_count: quotes.length,
+    transaction_count: transactions.length,
+    receipt_count: receipts.length,
+    payment_count: payments.length,
+    delivery_count: deliveries.length,
+    external_credit_grant_count: externalCreditGrants.length,
+    settlement_count: settlements.length,
+    finalized_settlement_count: settlements.filter((settlement) => settlement && settlement.finality_status === "finalized").length,
+    pending_settlement_count: pendingSettlementCount,
+    failed_settlement_count: failedSettlementCount,
+    adapter_failure_count: countAdapterFailures(transactions)
+  };
+  const attentionQueue = buildAttentionQueue({ counts, revenueSignals });
+  return {
+    ok: true,
+    product: "xytara",
+    category: "machine-commerce-operator-observability-pack",
+    pack_version: "xytara-operator-observability-pack-v1",
+    posture: "read_only_operator_visibility_across_money_execution_delivery_settlement_and_pricing",
+    account_scope: accountId || "all_accounts",
+    operator_state: attentionQueue.some((entry) => entry.priority === "high")
+      ? "attention_required"
+      : attentionQueue.some((entry) => entry.priority === "medium")
+        ? "watch"
+        : "steady",
+    counts,
+    status_counts: {
+      quotes: countBy(quotes, (quote) => quote && quote.status),
+      transactions: countBy(transactions, (transaction) => transaction && transaction.status),
+      deliveries: countBy(deliveries, (delivery) => delivery && delivery.status),
+      payments: countBy(payments, (payment) => payment && payment.status || payment && payment.payment && payment.payment.status),
+      settlements: countBy(settlements, (settlement) => settlement && settlement.status),
+      settlement_finality: countBy(settlements, (settlement) => settlement && settlement.finality_status)
+    },
+    latest_activity: {
+      quote_at_iso: latestIso(quotes, ["created_at_iso", "executed_at_iso", "payment_recorded_at_iso"]),
+      transaction_at_iso: latestIso(transactions, ["completed_at_iso", "created_at_iso"]),
+      payment_at_iso: latestIso(payments, ["recorded_at_iso"]),
+      delivery_at_iso: latestIso(deliveries, ["delivered_at_iso", "created_at_iso"]),
+      grant_at_iso: latestIso(externalCreditGrants, ["created_at_iso", "granted_at_iso", "recorded_at_iso"]),
+      settlement_at_iso: latestIso(settlements, ["finalized_at_iso", "confirmed_at_iso", "submitted_at_iso", "created_at_iso"])
+    },
+    activity_summary: activitySummary,
+    pricing_telemetry_summary: {
+      sample_maturity: revenueSignals.sample_maturity,
+      pricing_change_posture: revenueSignals.pricing_change_posture,
+      quote_conversion_rate: revenueSignals.rates.quote_conversion_rate,
+      quote_abandonment_rate: revenueSignals.rates.quote_abandonment_rate,
+      revenue_capture_rate: revenueSignals.rates.revenue_capture_rate
+    },
+    attention_queue: attentionQueue,
+    linked_surfaces: {
+      activity_ledger_ref: "/v1/activity-ledger",
+      payment_ledger_ref: "/v1/payment-ledger",
+      reconciliation_report_ref: "/v1/reconciliation-report",
+      deliveries_ref: "/v1/deliveries",
+      settlement_ref: "/v1/settlement/bsv-teranode",
+      adapter_depth_ref: "/v1/adapter-depth/summary",
+      pricing_revenue_signal_ref: "/v1/pricing-optimization/revenue-signal-summary",
+      operator_intelligence_ref: "/v1/operator-intelligence"
+    },
+    boundary: "read_only_operator_visibility_no_fund_movement_no_settlement_submission_no_secret_material"
+  };
+}
+
+function summarizeOperatorObservabilityPack(state, input) {
+  const pack = buildOperatorObservabilityPack(state, input);
+  return {
+    ok: true,
+    product: pack.product,
+    category: "machine-commerce-operator-observability-pack-summary",
+    summary_version: "xytara-operator-observability-pack-summary-v1",
+    account_scope: pack.account_scope,
+    operator_state: pack.operator_state,
+    quote_count: pack.counts.quote_count,
+    payment_count: pack.counts.payment_count,
+    transaction_count: pack.counts.transaction_count,
+    delivery_count: pack.counts.delivery_count,
+    external_credit_grant_count: pack.counts.external_credit_grant_count,
+    settlement_count: pack.counts.settlement_count,
+    pending_settlement_count: pack.counts.pending_settlement_count,
+    adapter_failure_count: pack.counts.adapter_failure_count,
+    pricing_sample_maturity: pack.pricing_telemetry_summary.sample_maturity,
+    attention_item_count: pack.attention_queue.length,
+    linked_surfaces: pack.linked_surfaces
+  };
+}
+
 module.exports = {
   buildOperatorIntelligencePack,
-  summarizeOperatorIntelligencePack
+  summarizeOperatorIntelligencePack,
+  buildOperatorObservabilityPack,
+  summarizeOperatorObservabilityPack
 };

package/lib/payment_config.js

@@ -59,14 +59,64 @@ function loadTreasuryDestinationMap() {
     process.env.XYTARA_TREASURY_DESTINATIONS_PATH,
     {}
   );
-  return raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+  const input = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+  const normalized = {};
+  for (const [settlementMode, entry] of Object.entries(input)) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+    normalized[normalizeSettlementMode(settlementMode)] = {
+      destination_id: typeof entry.destination_id === "string" && entry.destination_id.trim()
+        ? entry.destination_id.trim()
+        : null,
+      destination_kind: typeof entry.destination_kind === "string" && entry.destination_kind.trim()
+        ? entry.destination_kind.trim()
+        : null,
+      account_id: typeof entry.account_id === "string" && entry.account_id.trim()
+        ? entry.account_id.trim()
+        : null,
+      external_ref: typeof entry.external_ref === "string" && entry.external_ref.trim()
+        ? entry.external_ref.trim()
+        : null,
+      custody_ref: typeof entry.custody_ref === "string" && entry.custody_ref.trim()
+        ? entry.custody_ref.trim()
+        : null,
+      reporting_ref: typeof entry.reporting_ref === "string" && entry.reporting_ref.trim()
+        ? entry.reporting_ref.trim()
+        : null,
+      wallet_ref: typeof entry.wallet_ref === "string" && entry.wallet_ref.trim()
+        ? entry.wallet_ref.trim()
+        : null,
+      provider_ref: typeof entry.provider_ref === "string" && entry.provider_ref.trim()
+        ? entry.provider_ref.trim()
+        : null,
+      network: typeof entry.network === "string" && entry.network.trim()
+        ? entry.network.trim()
+        : null,
+      chain_id: typeof entry.chain_id === "string" && entry.chain_id.trim()
+        ? entry.chain_id.trim()
+        : null,
+      asset_symbol: typeof entry.asset_symbol === "string" && entry.asset_symbol.trim()
+        ? entry.asset_symbol.trim()
+        : null,
+      policy_scope: typeof entry.policy_scope === "string" && entry.policy_scope.trim()
+        ? entry.policy_scope.trim()
+        : null,
+      storage_class: typeof entry.storage_class === "string" && entry.storage_class.trim()
+        ? entry.storage_class.trim()
+        : null,
+      enabled: entry.enabled !== false,
+      accept_inbound: entry.accept_inbound !== false
+    };
+  }
+  return normalized;
 }
 
 function loadPaymentConfig() {
-  const verificationMode = String(process.env.XYTARA_PAYMENT_VERIFICATION_MODE || "presence").trim() || "presence";
+  const verificationModeInput = String(process.env.XYTARA_PAYMENT_VERIFICATION_MODE || "presence").trim() || "presence";
+  const verificationMode = verificationModeInput === "signed" ? "local_signed" : verificationModeInput;
   const maxAgeSeconds = Number(process.env.XYTARA_PAYMENT_MAX_AGE_SECONDS || 300);
   return {
     verification_mode: verificationMode,
+    verification_mode_input: verificationModeInput,
     payment_max_age_seconds: Number.isFinite(maxAgeSeconds) && maxAgeSeconds > 0 ? maxAgeSeconds : 300,
     wallet_registry: loadWalletRegistry(),
     treasury_destination_id: String(process.env.XYTARA_TREASURY_DESTINATION_ID || "").trim() || null,
@@ -104,7 +154,34 @@ function buildConfiguredTreasuryDestination(accountId, settlementMode) {
     external_ref:
       (mapEntry && typeof mapEntry.external_ref === "string" && mapEntry.external_ref.trim())
       || config.treasury_external_ref
-      || null
+      || null,
+    custody_ref: mapEntry && typeof mapEntry.custody_ref === "string" && mapEntry.custody_ref.trim()
+      ? mapEntry.custody_ref.trim()
+      : null,
+    reporting_ref: mapEntry && typeof mapEntry.reporting_ref === "string" && mapEntry.reporting_ref.trim()
+      ? mapEntry.reporting_ref.trim()
+      : null,
+    wallet_ref: mapEntry && typeof mapEntry.wallet_ref === "string" && mapEntry.wallet_ref.trim()
+      ? mapEntry.wallet_ref.trim()
+      : null,
+    provider_ref: mapEntry && typeof mapEntry.provider_ref === "string" && mapEntry.provider_ref.trim()
+      ? mapEntry.provider_ref.trim()
+      : null,
+    network: mapEntry && typeof mapEntry.network === "string" && mapEntry.network.trim()
+      ? mapEntry.network.trim()
+      : null,
+    chain_id: mapEntry && typeof mapEntry.chain_id === "string" && mapEntry.chain_id.trim()
+      ? mapEntry.chain_id.trim()
+      : null,
+    asset_symbol: mapEntry && typeof mapEntry.asset_symbol === "string" && mapEntry.asset_symbol.trim()
+      ? mapEntry.asset_symbol.trim()
+      : null,
+    policy_scope: mapEntry && typeof mapEntry.policy_scope === "string" && mapEntry.policy_scope.trim()
+      ? mapEntry.policy_scope.trim()
+      : null,
+    storage_class: mapEntry && typeof mapEntry.storage_class === "string" && mapEntry.storage_class.trim()
+      ? mapEntry.storage_class.trim()
+      : null
   };
 }
 

package/lib/payment_front_registry.js

@@ -0,0 +1,53 @@
+"use strict";
+
+const { summarizeX402LanePack } = require("./x402_lane_contract");
+const { summarizeStripeMppLanePack } = require("./stripe_mpp_lane_contract");
+const { summarizeL402LanePack } = require("./l402_lane_contract");
+const { summarizeBoltLanePack } = require("./bolt_lane_contract");
+
+function buildPaymentFrontRegistryPack() {
+  return {
+    product: "xytara",
+    category: "machine-commerce-payment-front-registry-pack",
+    pack_version: "xytara-payment-front-registry-pack-v1",
+    posture: "multiple_payment_fronts_one_runtime_core",
+    fronts: {
+      x402: summarizeX402LanePack(),
+      hosted_checkout: summarizeStripeMppLanePack(),
+      l402: summarizeL402LanePack(),
+      bolt_utxo_spv: summarizeBoltLanePack(),
+      account_credits: {
+        product: "xytara",
+        category: "machine-commerce-account-credits-front",
+        summary_version: "xytara-account-credits-front-summary-v1",
+        posture: "repeat_use_spend_surface"
+      }
+    },
+    operator_rule: "add payment fronts where they improve adoption or economics, but keep execution/governance/proof semantics centralized",
+    linked_surfaces: {
+      payment_protocols_ref: "/v1/payment-protocols",
+      payment_protocol_strategy_ref: "/v1/payment-protocols/strategy",
+      x402_ref: "/v1/x402",
+      stripe_mpp_ref: "/v1/stripe-mpp",
+      l402_ref: "/v1/l402",
+      bolt_ref: "/v1/bolt"
+    }
+  };
+}
+
+function summarizePaymentFrontRegistryPack() {
+  const pack = buildPaymentFrontRegistryPack();
+  return {
+    product: pack.product,
+    category: pack.category,
+    summary_version: "xytara-payment-front-registry-pack-summary-v1",
+    posture: pack.posture,
+    front_count: Object.keys(pack.fronts).length,
+    linked_surfaces: pack.linked_surfaces
+  };
+}
+
+module.exports = {
+  buildPaymentFrontRegistryPack,
+  summarizePaymentFrontRegistryPack
+};

package/lib/payment_protocol_contract.js

@@ -0,0 +1,165 @@
+"use strict";
+
+function buildPaymentProtocolPack() {
+  return {
+    product: "xytara",
+    category: "machine-commerce-payment-protocol-pack",
+    pack_version: "xytara-payment-protocol-pack-v1",
+    lane_state: "default_machine_payment_plus_credit_and_adapter_expansion",
+    default_protocol: "x402",
+    current_native_payment_paths: [
+      {
+        protocol_id: "x402",
+        state: "first_party_default",
+        why_it_exists: "default machine-native quote -> challenge -> pay -> execute handshake"
+      },
+      {
+        protocol_id: "account_credits",
+        state: "first_party_repeat_use",
+        why_it_exists: "best repeat-use path for agents and operators that should not re-negotiate every call"
+      },
+      {
+        protocol_id: "stripe_mpp",
+        state: "first_party_human_checkout_lane",
+        why_it_exists: "human checkout, top-up, and hosted payment entry without making human checkout the center of the stack"
+      }
+    ],
+    adapter_ready_external_fronts: [
+      {
+        protocol_id: "l402",
+        state: "adapter_ready_current",
+        why_it_matters: "lightning-native service payment can matter for agents that want highly permissionless micropayment access"
+      },
+      {
+        protocol_id: "utxo_spv_payment_fronts",
+        state: "adapter_ready_current",
+        why_it_matters: "native UTXO verification and SPV-style settlement proofs can matter where facilitator dependence is undesirable"
+      },
+      {
+        protocol_id: "circle_nanopayments",
+        state: "adapter_ready_next",
+        why_it_matters: "high-frequency stable-value collection can complement machine-native pricing and credit replenishment"
+      },
+      {
+        protocol_id: "circle_cctp",
+        state: "adapter_ready_next",
+        why_it_matters: "stable-value treasury mobility can expand settlement reach without redefining runtime execution"
+      },
+      {
+        protocol_id: "future_payment_front_protocols",
+        state: "adapter_front_only",
+        why_it_matters: "similar future negotiation and payment protocols should be absorbed by the payment front instead of hardwiring brand-specific ideology into the runtime"
+      }
+    ],
+    charging_boundary: {
+      keep_free: [
+        "auth",
+        "discovery",
+        "docs",
+        "catalog_inspection",
+        "contract_views",
+        "release_and_start_paths",
+        "lightweight_preview_and_readiness_surfaces"
+      ],
+      keep_paid: [
+        "execution",
+        "quoted_runtime_work",
+        "credit_consumption",
+        "settlement_bearing_operations",
+        "resource_consuming_runtime_consequence",
+        "high_consequence_or_governed_machine_actions"
+      ],
+      principle: "do_not_charge_before_value_is_felt_but_do_not_give_runtime_consequence_away_for_free"
+    },
+    supported_surfaces: {
+      x402_lane_ref: "/v1/x402",
+      stripe_mpp_lane_ref: "/v1/stripe-mpp",
+      l402_lane_ref: "/v1/l402",
+      bolt_lane_ref: "/v1/bolt",
+      payment_front_registry_ref: "/v1/payment-fronts",
+      stablecoin_lane_ref: "/v1/stablecoins",
+      pricing_optimization_ref: "/v1/pricing-optimization",
+      treasury_destinations_ref: "/v1/treasury-destinations"
+    }
+  };
+}
+
+function buildPaymentProtocolStrategyPack() {
+  const pack = buildPaymentProtocolPack();
+  return {
+    product: "xytara",
+    category: "machine-commerce-payment-protocol-strategy-pack",
+    pack_version: "xytara-payment-protocol-strategy-pack-v1",
+    primary_protocol_thesis: {
+      machine_native_default: "x402",
+      repeat_use_default: "account_credits",
+      human_procurement_default: "hosted_checkout",
+      strategy_rule: "keep the commerce core protocol-agnostic while using the least-friction lane that fits the actor and operating constraint"
+    },
+    protocol_roles: [
+      {
+        protocol_id: "x402",
+        role: "machine_native_http_payment",
+        why_now: "strong fit for agent-call monetization, quote-to-pay flows, and interoperable HTTP-native machine commerce"
+      },
+      {
+        protocol_id: "account_credits",
+        role: "repeat_use_and_metered_runtime_spend",
+        why_now: "best fit for repeated agent use where renegotiating payment every call adds friction"
+      },
+      {
+        protocol_id: "hosted_checkout",
+        role: "human_checkout_and_procurement_entry",
+        why_now: "best fit for public SaaS sales, enterprise procurement, and external fiat money-in lanes"
+      },
+      {
+        protocol_id: "l402_or_other_permissionless_fronts",
+        role: "permissionless_adapter_payment_front",
+        why_now: "worth supporting through adapter fronts now when customers strongly value lower dependency or Lightning-native / UTXO-native settlement"
+      }
+    ],
+    commercialization_rules: [
+      "Use x402 as the primary self-serve machine paywall.",
+      "Use credits as the primary repeat-use spend posture after first conversion.",
+      "Use hosted checkout for humans and enterprise buyers, then convert that funding into internal authorization or credits.",
+      "Treat future permissionless fronts as adapter lanes into the same execution, proof, and governance core rather than as a fork of the product."
+    ],
+    operator_decisions: {
+      launch_primary_machine_lane: "x402",
+      launch_primary_human_lane: "hosted_checkout",
+      launch_repeat_use_lane: "account_credits",
+      current_optional_permissionless_lanes: ["l402", "utxo_spv_payment_fronts"]
+    },
+    linked_surfaces: {
+      payment_protocols_ref: "/v1/payment-protocols",
+      x402_lane_ref: "/v1/x402",
+      hosted_checkout_lane_ref: "/v1/stripe-mpp",
+      l402_lane_ref: "/v1/l402",
+      bolt_lane_ref: "/v1/bolt",
+      payment_front_registry_ref: "/v1/payment-fronts",
+      commercialization_summary_ref: "/v1/capability-registry/commercialization-summary",
+      execution_truth_ref: "/v1/capability-registry/execution-truth"
+    }
+  };
+}
+
+function summarizePaymentProtocolPack() {
+  const pack = buildPaymentProtocolPack();
+  return {
+    product: "xytara",
+    category: "machine-commerce-payment-protocol-pack-summary",
+    summary_version: "xytara-payment-protocol-pack-summary-v1",
+    default_protocol: pack.default_protocol,
+    current_path_count: pack.current_native_payment_paths.length,
+    adapter_ready_external_front_count: pack.adapter_ready_external_fronts.length,
+    free_boundary_count: pack.charging_boundary.keep_free.length,
+    paid_boundary_count: pack.charging_boundary.keep_paid.length,
+    linked_surfaces: pack.supported_surfaces
+  };
+}
+
+module.exports = {
+  buildPaymentProtocolPack,
+  buildPaymentProtocolStrategyPack,
+  summarizePaymentProtocolPack
+};