xytara 3.1.16 → 3.2.0

package/lib/pricing_optimization_contract.js

@@ -1,775 +0,0 @@
-"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
-};
-
-const PRICING_EXPERIMENT_REJECTION_CODES = [
-  "pricing_sample_too_sparse",
-  "experiment_not_registered",
-  "experiment_not_allowed_now",
-  "operator_approval_missing",
-  "baseline_metrics_missing",
-  "rollback_trigger_thresholds_missing",
-  "public_checkout_copy_review_missing",
-  "post_experiment_review_window_missing",
-  "target_surface_mismatch"
-];
-
-const PRICING_EXPERIMENT_LAUNCH_REQUIREMENTS = [
-  "operator_approval_recorded",
-  "sample_maturity_is_mature_live_signals",
-  "baseline_metrics_recorded_before_change",
-  "rollback_trigger_thresholds_recorded",
-  "public_checkout_copy_reviewed_for_accuracy",
-  "post_experiment_review_window_defined"
-];
-
-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 buildPricingExperimentPlan(state) {
-  const revenueSignals = buildRevenueSignalSummary(state);
-  const decisionGuardrail = buildPricingDecisionGuardrail(state);
-  const quoteCohorts = buildQuoteCohorts(state);
-  const sampleMaturity = revenueSignals.sample_maturity;
-  const experimentReady = decisionGuardrail.allow_price_change;
-  const candidateExperiments = [
-    {
-      experiment_id: "starter_api_pack_entry_price_test",
-      target_surface: "hosted_checkout_starter_api_pack",
-      hypothesis: "starter_entry_conversion_can_improve_without_degrading_refund_or_grant_success_rates",
-      required_segments: [
-        "first_purchase",
-        "hosted_checkout",
-        "starter_api_pack"
-      ],
-      primary_metrics: [
-        "checkout_paid_rate",
-        "external_credit_grant_success_rate",
-        "execution_completion_rate"
-      ],
-      rollback_triggers: [
-        "refund_or_chargeback_rate_increases",
-        "grant_failure_rate_increases",
-        "execution_completion_rate_decreases"
-      ],
-      allowed_now: experimentReady
-    },
-    {
-      experiment_id: "utility_minimum_floor_test",
-      target_surface: "utility_pricing_band_minimum_charge_floor",
-      hypothesis: "utility_quote_abandonment_can_be_reduced_without_training_users_to_expect_free_execution",
-      required_segments: [
-        "pricing_band.utility",
-        "quote_created",
-        "quote_accepted_or_expired"
-      ],
-      primary_metrics: [
-        "quote_conversion_rate",
-        "quote_abandonment_rate",
-        "revenue_capture_rate"
-      ],
-      rollback_triggers: [
-        "revenue_capture_rate_decreases",
-        "support_or_refund_signal_increases",
-        "paid_execution_quality_decreases"
-      ],
-      allowed_now: experimentReady
-    },
-    {
-      experiment_id: "trust_critical_premium_review",
-      target_surface: "trust_critical_premium_multiplier",
-      hypothesis: "high_consequence_work_may_support_higher_margin_when_conversion_is_already_strong",
-      required_segments: [
-        "pricing_band.trust_critical",
-        "converted_quotes",
-        "completed_transactions"
-      ],
-      primary_metrics: [
-        "trust_critical_conversion_rate",
-        "completed_paid_execution_count",
-        "refund_or_dispute_rate"
-      ],
-      rollback_triggers: [
-        "trust_critical_conversion_rate_decreases",
-        "refund_or_dispute_rate_increases",
-        "operator_quality_review_fails"
-      ],
-      allowed_now: experimentReady
-    }
-  ];
-  return {
-    experiment_plan_version: "xytara-pricing-experiment-plan-v1",
-    sample_maturity: sampleMaturity,
-    experiment_state: experimentReady ? "operator_reviewed_experiments_allowed" : "blocked_collect_more_live_data",
-    allow_experiment_launch: experimentReady,
-    required_minimum_live_sample: {
-      quote_count: 100,
-      payment_ledger_count: 20,
-      execution_transaction_count: 20,
-      refund_monitoring_required: true
-    },
-    current_evidence: {
-      counts: revenueSignals.counts,
-      rates: revenueSignals.rates,
-      pricing_band_cohorts: quoteCohorts.by_pricing_band
-    },
-    candidate_experiments: candidateExperiments,
-    launch_requirements: PRICING_EXPERIMENT_LAUNCH_REQUIREMENTS.slice(),
-    deterministic_rejection_codes: PRICING_EXPERIMENT_REJECTION_CODES.slice(),
-    launch_request_template: {
-      experiment_id: "starter_api_pack_entry_price_test",
-      target_surface: "hosted_checkout_starter_api_pack",
-      operator_approval_ref: "ops.pricing.approval.<date>",
-      baseline_metrics_ref: "ops.pricing.baseline.<date>",
-      rollback_trigger_thresholds: {
-        refund_or_chargeback_rate_increases: "operator_defined_threshold",
-        grant_failure_rate_increases: "operator_defined_threshold",
-        execution_completion_rate_decreases: "operator_defined_threshold"
-      },
-      public_checkout_copy_review_ref: "ops.pricing.copy_review.<date>",
-      post_experiment_review_window_days: 14
-    },
-    blocked_actions: experimentReady
-      ? []
-      : [
-          "start_price_ab_test_from_sparse_signals",
-          "change_public_package_prices_without_operator_approval",
-          "change_minimum_floors_without_baseline_metrics",
-          "change_auto_topup_thresholds_without_repeat_usage_data"
-        ],
-    allowed_actions: experimentReady
-      ? [
-          "prepare_small_operator_reviewed_price_experiment",
-          "record_baseline_and_rollback_thresholds",
-          "run_one_surface_at_a_time"
-        ]
-      : [
-          "collect_more_live_quote_payment_execution_and_refund_data",
-          "review_cohort_instrumentation",
-          "keep_current_public_prices_and_thresholds"
-        ],
-    boundary: "pricing_experiments_are_operator_reviewed_and_data_gated_not_automatic_price_changes"
-  };
-}
-
-function validatePricingExperimentLaunchRequest(plan, request) {
-  const pricingPlan = plan || {};
-  const launchRequest = request || {};
-  const candidates = Array.isArray(pricingPlan.candidate_experiments)
-    ? pricingPlan.candidate_experiments
-    : [];
-  const experimentId = launchRequest.experiment_id ? String(launchRequest.experiment_id) : "";
-  const candidate = candidates.find((entry) => entry && entry.experiment_id === experimentId) || null;
-  const rollbackThresholds = launchRequest.rollback_trigger_thresholds || {};
-  const missingRollbackThreshold = candidate
-    ? (Array.isArray(candidate.rollback_triggers) ? candidate.rollback_triggers : [])
-        .some((trigger) => !rollbackThresholds || !rollbackThresholds[trigger])
-    : true;
-  const reviewWindowDays = Number(launchRequest.post_experiment_review_window_days || 0);
-  const rejectionCodes = [];
-
-  if (pricingPlan.allow_experiment_launch !== true || pricingPlan.sample_maturity !== "mature_live_signals") {
-    rejectionCodes.push("pricing_sample_too_sparse");
-  }
-  if (!candidate) {
-    rejectionCodes.push("experiment_not_registered");
-  } else {
-    if (candidate.allowed_now !== true) rejectionCodes.push("experiment_not_allowed_now");
-    if (launchRequest.target_surface && launchRequest.target_surface !== candidate.target_surface) {
-      rejectionCodes.push("target_surface_mismatch");
-    }
-  }
-  if (!launchRequest.operator_approval_ref) rejectionCodes.push("operator_approval_missing");
-  if (!launchRequest.baseline_metrics_ref) rejectionCodes.push("baseline_metrics_missing");
-  if (missingRollbackThreshold) rejectionCodes.push("rollback_trigger_thresholds_missing");
-  if (!launchRequest.public_checkout_copy_review_ref) rejectionCodes.push("public_checkout_copy_review_missing");
-  if (!Number.isFinite(reviewWindowDays) || reviewWindowDays < 1) {
-    rejectionCodes.push("post_experiment_review_window_missing");
-  }
-
-  return {
-    validation_version: "xytara-pricing-experiment-launch-validation-v1",
-    launch_allowed: rejectionCodes.length === 0,
-    experiment_id: experimentId || null,
-    sample_maturity: pricingPlan.sample_maturity || null,
-    rejection_codes: Array.from(new Set(rejectionCodes)),
-    required_requirements: PRICING_EXPERIMENT_LAUNCH_REQUIREMENTS.slice(),
-    boundary: "pricing_launch_validation_requires_mature_samples_operator_approval_baseline_metrics_and_rollback_thresholds"
-  };
-}
-
-function summarizePricingExperimentPlan(state) {
-  const plan = buildPricingExperimentPlan(state);
-  return {
-    product: "xytara",
-    category: "machine-commerce-pricing-experiment-plan-summary",
-    summary_version: "xytara-pricing-experiment-plan-summary-v1",
-    sample_maturity: plan.sample_maturity,
-    experiment_state: plan.experiment_state,
-    allow_experiment_launch: plan.allow_experiment_launch,
-    candidate_experiment_count: plan.candidate_experiments.length,
-    blocked_action_count: plan.blocked_actions.length,
-    launch_requirement_count: plan.launch_requirements.length,
-    deterministic_rejection_code_count: plan.deterministic_rejection_codes.length,
-    boundary: plan.boundary
-  };
-}
-
-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);
-  const pricingExperimentPlan = buildPricingExperimentPlan(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,
-    pricing_experiment_plan: pricingExperimentPlan,
-    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",
-      experiment_plan_ref: "/v1/pricing-optimization/experiment-plan",
-      experiment_plan_summary_ref: "/v1/pricing-optimization/experiment-plan/summary"
-    }
-  };
-}
-
-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,
-    candidate_experiment_count: pack.pricing_experiment_plan.candidate_experiments.length,
-    allow_experiment_launch: pack.pricing_experiment_plan.allow_experiment_launch,
-    linked_surfaces: pack.supported_surfaces
-  };
-}
-
-module.exports = {
-  buildPricingOptimizationPack,
-  summarizePricingOptimizationPack,
-  buildQuoteAbandonmentSummary,
-  buildQuoteCohorts,
-  buildRevenueSignalSummary,
-  buildPricingDecisionGuardrail,
-  buildOptimizationRecommendations,
-  buildPricingExperimentPlan,
-  summarizePricingExperimentPlan,
-  validatePricingExperimentLaunchRequest
-};