xytara 2.5.0 → 2.6.0

package/lib/payment_verification.js

@@ -2,6 +2,9 @@
 
 const crypto = require("crypto");
 const { loadPaymentConfig } = require("./payment_config");
+const { parseL402Authorization, verifyL402AccessToken } = require("./l402_payment_front");
+const { parseBoltAuthorization, verifyBoltAccessToken } = require("./bolt_payment_front");
+const { parseStripeMppAuthorization, verifyStripeMppAccessToken } = require("./stripe_mpp_payment_front");
 const {
   buildBsvTeranodeSettlementHints,
   extractBsvTeranodePaymentReference,
@@ -44,8 +47,14 @@ function parseInstantPaymentHeaders(headers) {
   };
 }
 
-function parsePayment(headers, requiredHeaders) {
+function parsePayment(headers, requiredHeaders, options) {
   const required = Array.isArray(requiredHeaders) ? requiredHeaders : [];
+  const opts = options || {};
+  if (required.includes("authorization")) {
+    if (opts.authorization_scheme === "mpp" || opts.payment_protocol === "mpp") return parseStripeMppAuthorization(headers);
+    if (opts.authorization_scheme === "bolt" || opts.payment_protocol === "bolt") return parseBoltAuthorization(headers);
+    return parseL402Authorization(headers);
+  }
   if (required.includes("payment-signature")) return parseInstantPaymentHeaders(headers);
   return parseNativePaymentHeaders(headers);
 }
@@ -148,9 +157,20 @@ function verifyPaymentPayloadAgainstQuote(paymentPayload, quote, walletId, maxAg
   return { ok: true, age_seconds: ageSeconds };
 }
 
-function verifyPaymentAcceptance(state, headers, requiredHeaders, quote) {
+function verifyPaymentAcceptance(state, headers, requiredHeaders, quote, options) {
   const config = loadPaymentConfig();
-  const payment = parsePayment(headers || {}, requiredHeaders);
+  const required = Array.isArray(requiredHeaders) ? requiredHeaders : [];
+  const opts = options || {};
+  if (required.includes("authorization")) {
+    if (opts.authorization_scheme === "mpp" || opts.payment_protocol === "mpp") {
+      return verifyStripeMppAccessToken(headers || {}, quote);
+    }
+    if (opts.authorization_scheme === "bolt" || opts.payment_protocol === "bolt") {
+      return verifyBoltAccessToken(headers || {}, quote);
+    }
+    return verifyL402AccessToken(headers || {}, quote);
+  }
+  const payment = parsePayment(headers || {}, requiredHeaders, opts);
   if (config.verification_mode === "presence") {
     return {
       ok: true,

package/lib/pricing_optimization_contract.js

@@ -0,0 +1,556 @@
+"use strict";
+
+const { findTask } = require("../fixtures/catalog");
+const { getCatalog, getCreditPackList } = require("./catalog_contract");
+
+const PRICING_BAND_UNITS = {
+  utility: 1,
+  transactional: 2,
+  decision_support: 3,
+  governed_high_consequence: 5,
+  trust_critical: 8
+};
+
+function normalizeAmount(value) {
+  const amount = Number(value || 0);
+  return Number.isFinite(amount) ? amount : 0;
+}
+
+function collectQuotes(state) {
+  return state && state.quotes instanceof Map ? Array.from(state.quotes.values()) : [];
+}
+
+function valuesFromCollection(collection) {
+  if (!collection) return [];
+  if (collection instanceof Map) return Array.from(collection.values());
+  return Array.isArray(collection) ? collection : [];
+}
+
+function collectCheckoutPurchaseIntents(state) {
+  return valuesFromCollection(state && state.checkoutPurchaseIntents);
+}
+
+function collectCheckoutSessions(state) {
+  return valuesFromCollection(state && state.checkoutSessions);
+}
+
+function collectCheckoutEvents(state) {
+  return valuesFromCollection(state && state.checkoutEvents);
+}
+
+function collectExternalCreditGrants(state) {
+  return valuesFromCollection(state && state.externalCreditGrants);
+}
+
+function collectPaymentLedger(state) {
+  return Array.isArray(state && state.paymentLedger) ? state.paymentLedger : [];
+}
+
+function collectRefunds(state) {
+  return valuesFromCollection(state && state.refunds);
+}
+
+function collectTransactions(state) {
+  return valuesFromCollection(state && state.transactions)
+    .map((entry) => entry && entry.transaction ? entry.transaction : entry)
+    .filter(Boolean);
+}
+
+function resolveQuotePricingBand(quote) {
+  const taskRefs = Array.isArray(quote && quote.task_refs) ? quote.task_refs : [];
+  const observed = new Set();
+  for (const taskRef of taskRefs) {
+    const task = findTask(taskRef);
+    if (task && task.pricing_band) observed.add(task.pricing_band);
+  }
+  if (observed.has("trust_critical")) return "trust_critical";
+  if (observed.has("governed_high_consequence")) return "governed_high_consequence";
+  if (observed.has("decision_support")) return "decision_support";
+  if (observed.has("transactional")) return "transactional";
+  return observed.has("utility") ? "utility" : "utility";
+}
+
+function listTaskPricesByBand() {
+  const catalog = getCatalog();
+  const tasks = Array.isArray(catalog && catalog.tasks) ? catalog.tasks : [];
+  const byBand = new Map();
+  for (const task of tasks) {
+    if (!task || !task.pricing_band || !task.public_launch_price) continue;
+    const amount = normalizeAmount(task.public_launch_price.amount_minor);
+    if (amount <= 0) continue;
+    const band = String(task.pricing_band);
+    const current = byBand.get(band) || [];
+    current.push(amount);
+    byBand.set(band, current);
+  }
+  return byBand;
+}
+
+function buildMinimumChargeFloors() {
+  const byBand = listTaskPricesByBand();
+  return Object.entries(PRICING_BAND_UNITS).map(([pricingBand, usageUnits]) => {
+    const amounts = (byBand.get(pricingBand) || []).slice().sort((left, right) => left - right);
+    const observedMin = amounts.length > 0 ? amounts[0] : usageUnits * 10;
+    return {
+      pricing_band: pricingBand,
+      usage_units: usageUnits,
+      minimum_charge_floor_minor: observedMin,
+      currency: "USD_CENTS",
+      reasoning: "prevent_undercharging_of_runtime_consequence_even_when_quotes_are_small"
+    };
+  });
+}
+
+function buildStarterPricing() {
+  const packs = getCreditPackList();
+  const starter = packs.find((pack) => pack && pack.pack_id === "credits.starter") || null;
+  return {
+    starter_pack_id: starter ? starter.pack_id : "credits.starter",
+    starter_pack_amount_minor: starter ? starter.nominal_amount_minor : 1000,
+    starter_pack_units: starter ? starter.issued_units : 100,
+    recommended_free_boundary: [
+      "auth",
+      "docs",
+      "catalog",
+      "light_preview"
+    ],
+    recommended_paid_entry: [
+      "credit_pack_topup",
+      "quote_then_execute",
+      "low_friction_starter_pack_conversion"
+    ],
+    why_it_matters: "reduce_first-purchase_friction_without_giving_away_execution_and_consequence"
+  };
+}
+
+function buildCreditPackBreakpoints() {
+  return getCreditPackList().map((pack) => ({
+    pack_id: pack.pack_id,
+    category: pack.category,
+    issued_units: pack.issued_units,
+    nominal_amount_minor: pack.nominal_amount_minor,
+    intended_usage_posture: pack.intended_usage_posture,
+    recommended_for: pack.recommended_for
+  }));
+}
+
+function buildConsequencePremiumMultipliers() {
+  return [
+    { posture_id: "standard_runtime", multiplier: 1, recommended_for: "normal_direct_runtime_execution" },
+    { posture_id: "priority_runtime", multiplier: 1.15, recommended_for: "time-sensitive_runtime_execution" },
+    { posture_id: "transactional_consequence", multiplier: 1.2, recommended_for: "settlement_or_commit_bearing_work" },
+    { posture_id: "governed_high_consequence", multiplier: 1.35, recommended_for: "governed_or_multi-step_high_consequence_execution" },
+    { posture_id: "trust_critical", multiplier: 1.5, recommended_for: "trust-critical_authority_identity_or_proof-bearing_execution" }
+  ];
+}
+
+function buildQuoteAbandonmentSummary(state) {
+  const quotes = collectQuotes(state);
+  const statusCounts = quotes.reduce((acc, quote) => {
+    const key = quote && quote.status ? quote.status : "unknown";
+    acc[key] = (acc[key] || 0) + 1;
+    return acc;
+  }, {});
+  const total = quotes.length;
+  const executed = Number(statusCounts.executed || 0);
+  const accepted = Number(statusCounts.accepted || 0);
+  const expired = Number(statusCounts.expired || 0);
+  const quoted = Number(statusCounts.quoted || 0);
+  const converted = executed + accepted;
+  const quotedAmountMinor = quotes.reduce((sum, quote) => sum + normalizeAmount(quote && quote.amount_minor), 0);
+  const convertedAmountMinor = quotes
+    .filter((quote) => quote && (quote.status === "accepted" || quote.status === "executed"))
+    .reduce((sum, quote) => sum + normalizeAmount(quote.amount_minor), 0);
+  const expiredAmountMinor = quotes
+    .filter((quote) => quote && quote.status === "expired")
+    .reduce((sum, quote) => sum + normalizeAmount(quote.amount_minor), 0);
+  return {
+    summary_version: "xytara-quote-abandonment-summary-v2",
+    quote_count: total,
+    status_counts: statusCounts,
+    accepted_or_executed_count: converted,
+    open_quote_count: quoted,
+    expired_quote_count: expired,
+    quoted_amount_minor: quotedAmountMinor,
+    converted_amount_minor: convertedAmountMinor,
+    expired_amount_minor: expiredAmountMinor,
+    conversion_rate: total > 0 ? Number((converted / total).toFixed(4)) : null,
+    abandonment_rate: total > 0 ? Number((expired / total).toFixed(4)) : null,
+    revenue_capture_rate: quotedAmountMinor > 0 ? Number((convertedAmountMinor / quotedAmountMinor).toFixed(4)) : null,
+    note: "true_revenue_optimization_requires_live_quote_acceptance_and_abandonment_data_not_just_static_policy"
+  };
+}
+
+function buildQuoteCohortSummary(state, groupingKey) {
+  const quotes = collectQuotes(state);
+  const groups = new Map();
+  for (const quote of quotes) {
+    const key = groupingKey(quote);
+    const current = groups.get(key) || {
+      cohort_id: key,
+      quote_count: 0,
+      quoted_amount_minor: 0,
+      converted_count: 0,
+      converted_amount_minor: 0,
+      expired_count: 0,
+      expired_amount_minor: 0,
+      open_count: 0
+    };
+    const amount = normalizeAmount(quote && quote.amount_minor);
+    current.quote_count += 1;
+    current.quoted_amount_minor += amount;
+    if (quote && (quote.status === "accepted" || quote.status === "executed")) {
+      current.converted_count += 1;
+      current.converted_amount_minor += amount;
+    } else if (quote && quote.status === "expired") {
+      current.expired_count += 1;
+      current.expired_amount_minor += amount;
+    } else if (quote && quote.status === "quoted") {
+      current.open_count += 1;
+    }
+    groups.set(key, current);
+  }
+  return Array.from(groups.values())
+    .map((entry) => ({
+      ...entry,
+      conversion_rate: entry.quote_count > 0 ? Number((entry.converted_count / entry.quote_count).toFixed(4)) : null,
+      abandonment_rate: entry.quote_count > 0 ? Number((entry.expired_count / entry.quote_count).toFixed(4)) : null,
+      revenue_capture_rate: entry.quoted_amount_minor > 0
+        ? Number((entry.converted_amount_minor / entry.quoted_amount_minor).toFixed(4))
+        : null
+    }))
+    .sort((left, right) => right.quoted_amount_minor - left.quoted_amount_minor || right.quote_count - left.quote_count);
+}
+
+function buildQuoteCohorts(state) {
+  return {
+    by_pricing_band: buildQuoteCohortSummary(state, (quote) => resolveQuotePricingBand(quote)),
+    by_payment_protocol: buildQuoteCohortSummary(state, (quote) => quote && quote.payment_protocol ? quote.payment_protocol : "unknown"),
+    by_settlement_mode: buildQuoteCohortSummary(state, (quote) => quote && quote.settlement_mode ? quote.settlement_mode : "default")
+  };
+}
+
+function determineSampleMaturity(signalCounts) {
+  const counts = signalCounts || {};
+  const quoteCount = Number(counts.quote_count || 0);
+  const checkoutEventCount = Number(counts.checkout_event_count || 0);
+  const paymentLedgerCount = Number(counts.payment_ledger_count || 0);
+  const externalCreditGrantCount = Number(counts.external_credit_grant_count || 0);
+  const executionTransactionCount = Number(counts.execution_transaction_count || 0);
+
+  if (quoteCount >= 100 && paymentLedgerCount >= 20 && executionTransactionCount >= 20) {
+    return "mature_live_signals";
+  }
+  if (
+    quoteCount >= 25
+    && (checkoutEventCount >= 5 || paymentLedgerCount >= 5 || externalCreditGrantCount >= 5)
+    && executionTransactionCount >= 5
+  ) {
+    return "emerging_live_signals";
+  }
+  return "sparse_live_signals";
+}
+
+function postureForSampleMaturity(sampleMaturity) {
+  if (sampleMaturity === "mature_live_signals") return "ready_for_cautious_price_tests";
+  if (sampleMaturity === "emerging_live_signals") return "observe_and_prepare_small_price_tests";
+  return "observe_do_not_optimize_aggressively";
+}
+
+function buildRevenueSignalSummary(state) {
+  const quotes = collectQuotes(state);
+  const checkoutPurchaseIntents = collectCheckoutPurchaseIntents(state);
+  const checkoutSessions = collectCheckoutSessions(state);
+  const checkoutEvents = collectCheckoutEvents(state);
+  const externalCreditGrants = collectExternalCreditGrants(state);
+  const paymentLedger = collectPaymentLedger(state);
+  const refunds = collectRefunds(state);
+  const transactions = collectTransactions(state);
+  const quoteSummary = buildQuoteAbandonmentSummary(state);
+  const paidCheckoutEvents = checkoutEvents.filter((event) => event && event.payment_status === "paid");
+  const refundedCheckoutEvents = checkoutEvents.filter((event) =>
+    event && (event.payment_status === "refunded" || event.payment_status === "chargeback")
+  );
+  const checkoutPaidIntents = checkoutPurchaseIntents.filter((intent) =>
+    intent && (
+      intent.checkout_status === "paid"
+      || intent.customer_status === "credits_issued"
+      || intent.customer_status === "execution_dispatched"
+      || (intent.fulfillment && (intent.fulfillment.credits_issued || intent.fulfillment.execution_authorized))
+    )
+  );
+  const counts = {
+    quote_count: quotes.length,
+    checkout_purchase_intent_count: checkoutPurchaseIntents.length,
+    checkout_session_count: checkoutSessions.length,
+    checkout_event_count: checkoutEvents.length,
+    paid_checkout_event_count: paidCheckoutEvents.length,
+    refunded_checkout_event_count: refundedCheckoutEvents.length,
+    paid_checkout_intent_count: checkoutPaidIntents.length,
+    external_credit_grant_count: externalCreditGrants.length,
+    payment_ledger_count: paymentLedger.length,
+    refund_count: refunds.length,
+    execution_transaction_count: transactions.length
+  };
+  const sampleMaturity = determineSampleMaturity(counts);
+  return {
+    summary_version: "xytara-revenue-signal-summary-v1",
+    sample_maturity: sampleMaturity,
+    pricing_change_posture: postureForSampleMaturity(sampleMaturity),
+    counts,
+    amounts: {
+      quoted_amount_minor: quoteSummary.quoted_amount_minor,
+      converted_quote_amount_minor: quoteSummary.converted_amount_minor,
+      paid_checkout_amount_minor: paidCheckoutEvents.reduce((sum, event) => sum + normalizeAmount(event && event.amount_received_minor), 0),
+      payment_ledger_amount_minor: paymentLedger.reduce((sum, payment) => sum + normalizeAmount(payment && payment.amount_minor), 0),
+      external_credit_grant_amount_minor: externalCreditGrants.reduce((sum, grant) => sum + normalizeAmount(grant && grant.amount_minor), 0),
+      refund_amount_minor: refunds.reduce((sum, refund) => sum + normalizeAmount(refund && refund.amount_minor), 0)
+    },
+    rates: {
+      quote_conversion_rate: quoteSummary.conversion_rate,
+      quote_abandonment_rate: quoteSummary.abandonment_rate,
+      revenue_capture_rate: quoteSummary.revenue_capture_rate,
+      checkout_paid_rate: checkoutPurchaseIntents.length > 0
+        ? Number((checkoutPaidIntents.length / checkoutPurchaseIntents.length).toFixed(4))
+        : null,
+      refund_request_rate: checkoutPurchaseIntents.length > 0
+        ? Number((refunds.length / checkoutPurchaseIntents.length).toFixed(4))
+        : null
+    },
+    required_next_metrics: [
+      "quote_created_and_expired_counts",
+      "hosted_checkout_start_and_paid_counts",
+      "hosted_checkout_api_pack_purchase_counts",
+      "external_credit_grant_success_and_retry_counts",
+      "execution_transaction_completion_counts",
+      "refund_and_chargeback_counts"
+    ],
+    operator_note: sampleMaturity === "sparse_live_signals"
+      ? "live_revenue_signals_are_sparse_so_hold_pricing_thresholds_and_collect_more_evidence"
+      : "live_revenue_signals_are_available_for_careful_operator_review"
+  };
+}
+
+function buildPricingDecisionGuardrail(state) {
+  const revenueSignals = buildRevenueSignalSummary(state);
+  const allowPriceChange = revenueSignals.sample_maturity === "mature_live_signals";
+  return {
+    guardrail_version: "xytara-pricing-decision-guardrail-v1",
+    sample_maturity: revenueSignals.sample_maturity,
+    allow_price_change: allowPriceChange,
+    pricing_change_posture: revenueSignals.pricing_change_posture,
+    required_before_price_change: [
+      "enough_real_quotes_to_measure_conversion_and_abandonment",
+      "enough_hosted_checkout_events_to_measure_pack_purchase_conversion",
+      "enough_external_credit_grants_to_measure_fulfillment_reliability",
+      "enough_execution_transactions_to_measure_paid_usage_quality",
+      "refund_or_chargeback_monitoring_present"
+    ],
+    allowed_actions: allowPriceChange
+      ? [
+          "run_small_operator_reviewed_price_tests",
+          "adjust_auto_topup_thresholds_with_documented_rationale",
+          "review_package_breakpoints_against_live_conversion"
+        ]
+      : [
+          "collect_live_quote_checkout_grant_execution_and_refund_metrics",
+          "keep_current_package_prices_and_thresholds",
+          "improve_instrumentation_and_operator_reporting"
+        ],
+    blocked_actions: allowPriceChange
+      ? []
+      : [
+          "raise_or_lower_public_package_prices_from_sparse_signals",
+          "change_auto_topup_thresholds_without_live_conversion_rationale",
+          "remove_starter_api_pack_or_change_hosted_checkout_gateway_language"
+        ],
+    evidence: {
+      counts: revenueSignals.counts,
+      rates: revenueSignals.rates
+    }
+  };
+}
+
+function buildPackageThresholdRationale(state) {
+  const revenueSignals = buildRevenueSignalSummary(state);
+  return {
+    rationale_version: "xytara-package-threshold-rationale-v1",
+    current_posture: revenueSignals.sample_maturity === "mature_live_signals"
+      ? "eligible_for_operator_reviewed_threshold_tests"
+      : "hold_current_thresholds_until_live_metrics_mature",
+    hosted_checkout_gateway_product_boundary: "public_checkout_sells_api_packs_while_internal_runtime_accounts_consume_credits_and_entitlements",
+    starter_api_pack: {
+      public_package_id: "starter-api",
+      internal_credit_pack_id: "credits.starter",
+      rationale: "keep_the_first_paid_entry_simple_and_compliant_as_an_api_pack_while_mapping_to_internal_machine_runtime_credits",
+      tuning_rule: "do_not_change_until_checkout_conversion_grant_success_execution_completion_and_refund_rates_are_visible"
+    },
+    auto_topup: {
+      current_action: "observe",
+      rationale: "auto_topup_thresholds_should_follow_repeat_usage_and_low_balance_behavior_not_static_launch_assumptions",
+      tuning_rule: "require_live_repeat_purchase_or_low_balance_data_before_threshold_changes"
+    },
+    evidence: {
+      sample_maturity: revenueSignals.sample_maturity,
+      counts: revenueSignals.counts
+    }
+  };
+}
+
+function buildOptimizationRecommendations(state) {
+  const quoteSummary = buildQuoteAbandonmentSummary(state);
+  const cohorts = buildQuoteCohorts(state);
+  const decisionGuardrail = buildPricingDecisionGuardrail(state);
+  const recommendations = [];
+  const utilityBand = cohorts.by_pricing_band.find((entry) => entry.cohort_id === "utility");
+  const trustBand = cohorts.by_pricing_band.find((entry) => entry.cohort_id === "trust_critical");
+  const x402Cohort = cohorts.by_payment_protocol.find((entry) => entry.cohort_id === "x402");
+  const creditCohort = cohorts.by_payment_protocol.find((entry) => entry.cohort_id === "account_credits");
+  const highOpenQuotes = quoteSummary.open_quote_count >= 5;
+
+  if (decisionGuardrail.allow_price_change && utilityBand && utilityBand.abandonment_rate !== null && utilityBand.abandonment_rate > 0.35) {
+    recommendations.push({
+      action_id: "soften_utility_entry_pricing",
+      why: "utility_band_is_showing_meaningful_quote_abandonment",
+      target_surface: "starter_pricing_and_minimum_charge_floors",
+      evidence: utilityBand
+    });
+  }
+  if (decisionGuardrail.allow_price_change && trustBand && trustBand.conversion_rate !== null && trustBand.conversion_rate > 0.7) {
+    recommendations.push({
+      action_id: "review_trust_critical_premium_upward",
+      why: "high-consequence_quotes_are_closing_well_enough_to_support_margin_capture",
+      target_surface: "high_consequence_premium_multipliers",
+      evidence: trustBand
+    });
+  }
+  if (decisionGuardrail.allow_price_change && x402Cohort && creditCohort && x402Cohort.conversion_rate !== null && creditCohort.conversion_rate !== null
+    && x402Cohort.conversion_rate + 0.15 < creditCohort.conversion_rate) {
+    recommendations.push({
+      action_id: "push_repeat_use_toward_credits_after_first_x402_conversion",
+      why: "credits_are_converting_better_than_direct_machine_payment_for_repeat_use",
+      target_surface: "credit_pack_breakpoints_and_runtime_prompts",
+      evidence: {
+        x402: x402Cohort,
+        account_credits: creditCohort
+      }
+    });
+  }
+  if (highOpenQuotes) {
+    recommendations.push({
+      action_id: "review_quote_ttl_and_follow-up",
+      why: "too_many_quotes_are_stalling_without_resolving_to_payment_or_expiry",
+      target_surface: "quote_lifecycle_and_payment_prompts",
+      evidence: {
+        open_quote_count: quoteSummary.open_quote_count,
+        quote_count: quoteSummary.quote_count
+      }
+    });
+  }
+  if (recommendations.length === 0) {
+    recommendations.push({
+      action_id: "continue_live_quote_observation",
+      why: decisionGuardrail.allow_price_change
+        ? "no_price_change_signal_has_cleared_operator_review_thresholds_yet"
+        : "not_enough_live_variance_yet_to_justify_aggressive_pricing_changes",
+      target_surface: "quote_acceptance_and_abandonment_monitoring",
+      evidence: {
+        quote_summary: quoteSummary,
+        decision_guardrail: decisionGuardrail
+      }
+    });
+  }
+  return {
+    recommendation_version: "xytara-pricing-optimization-recommendations-v1",
+    recommendations
+  };
+}
+
+function buildPricingOptimizationPack(state) {
+  const minimumChargeFloors = buildMinimumChargeFloors();
+  const starterPricing = buildStarterPricing();
+  const creditPackBreakpoints = buildCreditPackBreakpoints();
+  const quoteAbandonmentSummary = buildQuoteAbandonmentSummary(state);
+  const quoteCohorts = buildQuoteCohorts(state);
+  const recommendations = buildOptimizationRecommendations(state);
+  const revenueSignalSummary = buildRevenueSignalSummary(state);
+  const pricingDecisionGuardrail = buildPricingDecisionGuardrail(state);
+  const packageThresholdRationale = buildPackageThresholdRationale(state);
+  return {
+    product: "xytara",
+    category: "machine-commerce-pricing-optimization-pack",
+    pack_version: "xytara-pricing-optimization-pack-v3",
+    optimization_posture: "quote_based_pricing_with_credit_conversion_and_consequence_weighting",
+    pricing_change_posture: revenueSignalSummary.pricing_change_posture,
+    live_data_note: revenueSignalSummary.operator_note,
+    why_not_flat_pricing: [
+      "flat_pricing_undercharges_high_consequence_runtime_work",
+      "flat_pricing_overprices_simple_utility_and_entry_paths",
+      "quote_based_pricing_preserves_margin_capture_across_different_runtime_shapes"
+    ],
+    minimum_charge_floors: minimumChargeFloors,
+    pricing_band_review: {
+      pricing_band_units: PRICING_BAND_UNITS,
+      policy_goal: "keep_simple_work_easy_to_try_while_protecting_margin_on_consequence-bearing_runtime"
+    },
+    credit_pack_breakpoints: creditPackBreakpoints,
+    starter_pricing: starterPricing,
+    high_consequence_premium_multipliers: buildConsequencePremiumMultipliers(),
+    quote_abandonment_summary: quoteAbandonmentSummary,
+    quote_conversion_cohorts: quoteCohorts,
+    revenue_signal_summary: revenueSignalSummary,
+    pricing_decision_guardrail: pricingDecisionGuardrail,
+    package_threshold_rationale: packageThresholdRationale,
+    optimization_recommendations: recommendations,
+    data_dependent_tuning: [
+      "conversion_test_starter_pack_pricing",
+      "review_quote_acceptance_and_expiry",
+      "lift_or_lower_minimum_charge_floors_based_on_real_demand",
+      "tighten_or_relax_premium_multipliers_based_on_close_rate_and_margin"
+    ],
+    supported_surfaces: {
+      credit_pack_ref: "/v1/credit-packs",
+      pricing_policy_ref_template: "/v1/economics/accounts/:account_id/pricing-policy-package",
+      quote_policy_ref_template: "/v1/economics/accounts/:account_id/quote-policy-package",
+      payment_quotes_ref: "/v1/payment-quotes",
+      quote_cohorts_ref: "/v1/pricing-optimization/quote-cohorts",
+      recommendations_ref: "/v1/pricing-optimization/recommendations",
+      revenue_signal_summary_ref: "/v1/pricing-optimization/revenue-signal-summary",
+      decision_guardrail_ref: "/v1/pricing-optimization/decision-guardrail"
+    }
+  };
+}
+
+function summarizePricingOptimizationPack(state) {
+  const pack = buildPricingOptimizationPack(state);
+  return {
+    product: "xytara",
+    category: "machine-commerce-pricing-optimization-pack-summary",
+    summary_version: "xytara-pricing-optimization-pack-summary-v3",
+    optimization_posture: pack.optimization_posture,
+    pricing_change_posture: pack.pricing_change_posture,
+    sample_maturity: pack.revenue_signal_summary.sample_maturity,
+    allow_price_change: pack.pricing_decision_guardrail.allow_price_change,
+    floor_count: pack.minimum_charge_floors.length,
+    credit_pack_breakpoint_count: pack.credit_pack_breakpoints.length,
+    premium_multiplier_count: pack.high_consequence_premium_multipliers.length,
+    quote_count: pack.quote_abandonment_summary.quote_count,
+    checkout_event_count: pack.revenue_signal_summary.counts.checkout_event_count,
+    external_credit_grant_count: pack.revenue_signal_summary.counts.external_credit_grant_count,
+    payment_ledger_count: pack.revenue_signal_summary.counts.payment_ledger_count,
+    refund_count: pack.revenue_signal_summary.counts.refund_count,
+    execution_transaction_count: pack.revenue_signal_summary.counts.execution_transaction_count,
+    recommendation_count: pack.optimization_recommendations.recommendations.length,
+    linked_surfaces: pack.supported_surfaces
+  };
+}
+
+module.exports = {
+  buildPricingOptimizationPack,
+  summarizePricingOptimizationPack,
+  buildQuoteAbandonmentSummary,
+  buildQuoteCohorts,
+  buildRevenueSignalSummary,
+  buildPricingDecisionGuardrail,
+  buildOptimizationRecommendations
+};

package/lib/release_history.js

@@ -10,6 +10,21 @@ function buildReleaseHistory() {
     current_version: packageJson.version,
     release_track: "public_release",
     history: [
+      {
+        version: "2.6.0",
+        channel: "public_release",
+        maturity_posture: "expansion_ready",
+        headline: "expansion release with public first-run polish, provider-backed adapter depth, framework reference adapters, and operator observability",
+        milestone_refs: [
+          "public_first_run_quote_and_credits_execution",
+          "provider_backed_mcp_adapter_depth",
+          "langgraph_reference_adapter",
+          "langchain_reference_adapter",
+          "operator_observability_pack",
+          "pricing_telemetry_guardrails",
+          "framework_adapter_verifier_coverage"
+        ]
+      },
       {
         version: "2.5.0",
         channel: "public_release",