xytara 2.7.0 → 2.8.0

package/RELEASE_NOTES.md

@@ -1,3 +1,15 @@
+# xytara 2.8.0 Release Notes
+
+`xytara` 2.8.0 is the release-boundary hardening line for live-provider promotion discipline, treasury/operator public-claim safety, and pricing experiment guardrails.
+
+Highlights:
+
+- adds framework-provider promotion evidence gates so LangGraph/LangChain style claims stay reference-contract until endpoint, auth, health, latency, failure, and proof-fact evidence exists
+- hardens pricing experiment planning and launch gates so optimization remains sample-maturity and operator-review gated
+- hardens treasury public claim boundaries so public surfaces do not leak landing/custody/provider refs or promote readiness-only/internal rails as live
+- hardens operator observability boundaries so read-only views cannot drift into mutation, settlement submission, fund movement, unsafe attention actions, or secret-bearing control behavior
+- keeps the 2.7.0 clean-consumer packaging and release-smoke posture intact while making expansion claims more defensible
+
 # xytara 2.7.0 Release Notes
 
 `xytara` 2.7.0 is the expansion-closeout release line for package-hardening, clean-consumer release smoke testing, and disciplined adapter/product claim boundaries.

package/index.js

@@ -35,6 +35,14 @@ const {
   buildAdapterPack,
   summarizeAdapterPack
 } = require("./lib/adapter_pack");
+const {
+  buildFrameworkProviderPromotionPack,
+  summarizeFrameworkProviderPromotionPack
+} = require("./lib/framework_provider_promotion");
+const {
+  buildPricingExperimentPlan,
+  summarizePricingExperimentPlan
+} = require("./lib/pricing_optimization_contract");
 const {
   buildPublishPlan,
   summarizePublishPlan
@@ -159,6 +167,10 @@ module.exports = {
   summarizeReleaseHistory,
   buildAdapterPack,
   summarizeAdapterPack,
+  buildFrameworkProviderPromotionPack,
+  summarizeFrameworkProviderPromotionPack,
+  buildPricingExperimentPlan,
+  summarizePricingExperimentPlan,
   buildPublishPlan,
   summarizePublishPlan,
   buildEcosystemEntryPack,

package/lib/framework_provider_promotion.js

@@ -0,0 +1,235 @@
+"use strict";
+
+const packageJson = require("../package.json");
+
+const FRAMEWORK_PROVIDER_CANDIDATES = Object.freeze([
+  Object.freeze({
+    framework_id: "langgraph",
+    adapter_id: "reference.framework.langgraph",
+    task_ref: "framework.langgraph.execute",
+    endpoint_env: "XYTARA_LANGGRAPH_PROVIDER_URL",
+    auth_env: "XYTARA_LANGGRAPH_PROVIDER_TOKEN",
+    health_path_env: "XYTARA_LANGGRAPH_PROVIDER_HEALTH_PATH"
+  }),
+  Object.freeze({
+    framework_id: "langchain",
+    adapter_id: "reference.framework.langchain",
+    task_ref: "framework.langchain.execute",
+    endpoint_env: "XYTARA_LANGCHAIN_PROVIDER_URL",
+    auth_env: "XYTARA_LANGCHAIN_PROVIDER_TOKEN",
+    health_path_env: "XYTARA_LANGCHAIN_PROVIDER_HEALTH_PATH"
+  })
+]);
+
+const FRAMEWORK_PROVIDER_PROMOTION_REQUIREMENTS = Object.freeze([
+  "endpoint_configured",
+  "auth_configured",
+  "health_check_passes",
+  "latency_observed",
+  "failure_behavior_bounded",
+  "proof_fact_shape_preserved",
+  "operator_evidence_recorded"
+]);
+
+const FRAMEWORK_PROVIDER_PROMOTION_REJECTION_CODES = Object.freeze([
+  "framework_not_registered",
+  "candidate_not_live_check_ready",
+  "adapter_id_mismatch",
+  "task_ref_mismatch",
+  "operator_evidence_missing",
+  "auth_boundary_evidence_missing",
+  "health_check_missing",
+  "health_check_failed",
+  "latency_measurement_missing",
+  "latency_budget_exceeded",
+  "failure_behavior_evidence_missing",
+  "proof_fact_shape_evidence_missing",
+  "secret_material_forbidden"
+]);
+
+function normalizeString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function containsSecretMaterial(value) {
+  if (!value || typeof value !== "object") return false;
+  const secretishKey = /(secret|token|credential|password|private[_-]?key|authorization)/i;
+  const secretishValue = /(bearer\s+[a-z0-9._-]{8,}|sk_live_|npm_[a-z0-9]|ghp_[a-z0-9]|xox[baprs]-)/i;
+  const stack = [value];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (!current || typeof current !== "object") continue;
+    for (const [key, entry] of Object.entries(current)) {
+      if (secretishKey.test(String(key))) return true;
+      if (typeof entry === "string" && secretishValue.test(entry)) return true;
+      if (entry && typeof entry === "object") stack.push(entry);
+    }
+  }
+  return false;
+}
+
+function boolFromEnv(value) {
+  const normalized = normalizeString(value).toLowerCase();
+  return ["1", "true", "yes", "on"].includes(normalized);
+}
+
+function summarizeCandidate(candidate, env = process.env) {
+  const endpoint = normalizeString(env[candidate.endpoint_env]);
+  const authToken = normalizeString(env[candidate.auth_env]);
+  const healthPath = normalizeString(env[candidate.health_path_env]) || "/health";
+  const endpointConfigured = Boolean(endpoint);
+  const authConfigured = Boolean(authToken);
+  const liveCheckReady = endpointConfigured && authConfigured;
+  return {
+    framework_id: candidate.framework_id,
+    adapter_id: candidate.adapter_id,
+    task_ref: candidate.task_ref,
+    state: liveCheckReady ? "live_check_ready" : "reference_contract_only",
+    endpoint_configured: endpointConfigured,
+    auth_configured: authConfigured,
+    health_path: healthPath,
+    endpoint_env: candidate.endpoint_env,
+    auth_env: candidate.auth_env,
+    health_path_env: candidate.health_path_env,
+    promotion_evidence_template: {
+      framework_id: candidate.framework_id,
+      adapter_id: candidate.adapter_id,
+      task_ref: candidate.task_ref,
+      operator_evidence_ref: "ops.framework_provider.<framework_id>.<date>",
+      auth_boundary_ref: "ops.framework_provider.auth_boundary.<framework_id>.<date>",
+      health_check: {
+        status_code: 200,
+        health_ok: true
+      },
+      latency_ms: 250,
+      latency_budget_ms: 2000,
+      failure_behavior_ref: "ops.framework_provider.failure_behavior.<framework_id>.<date>",
+      proof_fact_shape_ref: "ops.framework_provider.proof_facts.<framework_id>.<date>"
+    },
+    required_live_evidence: [
+      "real_external_endpoint",
+      "auth_or_access_boundary",
+      "health_check_response",
+      "bounded_latency_measurement",
+      "failure_behavior_observed",
+      "proof_fact_shape_preserved"
+    ],
+    claim_boundary: liveCheckReady
+      ? "may_run_live_promotion_check_but_must_not_claim_provider_live_until_check_evidence_is_recorded"
+      : "reference_adapter_only_no_live_external_provider_claim"
+  };
+}
+
+function buildFrameworkProviderPromotionPack(options = {}) {
+  const env = options.env || process.env;
+  const candidates = FRAMEWORK_PROVIDER_CANDIDATES.map((candidate) => summarizeCandidate(candidate, env));
+  const liveReadyCandidates = candidates.filter((candidate) => candidate.state === "live_check_ready");
+  const requireLive = boolFromEnv(env.XYTARA_FRAMEWORK_PROMOTION_REQUIRE_LIVE);
+  return {
+    ok: true,
+    product: packageJson.name,
+    category: "machine-commerce-framework-provider-promotion-pack",
+    pack_version: "xytara-framework-provider-promotion-pack-v1",
+    posture: "reference_framework_adapters_promote_only_with_external_endpoint_evidence",
+    promotion_state: liveReadyCandidates.length > 0 ? "live_check_ready" : "no_live_provider_evidence_configured",
+    require_live: requireLive,
+    framework_candidate_count: candidates.length,
+    live_check_ready_count: liveReadyCandidates.length,
+    promoted_provider_count: 0,
+    candidates,
+    promotion_requirements: FRAMEWORK_PROVIDER_PROMOTION_REQUIREMENTS.slice(),
+    deterministic_rejection_codes: FRAMEWORK_PROVIDER_PROMOTION_REJECTION_CODES.slice(),
+    strict_boundaries: [
+      "reference_framework_adapters_do_not_equal_live_provider_integrations",
+      "do_not_claim_langgraph_or_langchain_live_provider_without_endpoint_auth_health_and_latency_evidence",
+      "failed_or_missing_live_checks_keep_frameworks_in_reference_contract_state",
+      "live_provider_promotion_does_not_change_adapter_claims_for_unchecked_frameworks"
+    ],
+    linked_surfaces: {
+      framework_lane_ref: "/v1/frameworks",
+      framework_provider_promotion_ref: "/v1/framework-provider-promotion",
+      framework_provider_promotion_summary_ref: "/v1/framework-provider-promotion/summary",
+      adapter_depth_ref: "/v1/adapter-depth/summary",
+      integrations_ref: "/v1/integrations"
+    }
+  };
+}
+
+function validateFrameworkProviderPromotionEvidence(pack, evidence) {
+  const promotionPack = pack || {};
+  const evidencePacket = evidence || {};
+  const candidates = Array.isArray(promotionPack.candidates) ? promotionPack.candidates : [];
+  const frameworkId = normalizeString(evidencePacket.framework_id);
+  const candidate = candidates.find((entry) => entry && entry.framework_id === frameworkId) || null;
+  const healthCheck = evidencePacket.health_check || null;
+  const latencyValue = evidencePacket.latency_ms;
+  const latencyMs = Number(latencyValue);
+  const latencyBudgetMs = Number(evidencePacket.latency_budget_ms || 2000);
+  const rejectionCodes = [];
+
+  if (!candidate) {
+    rejectionCodes.push("framework_not_registered");
+  } else {
+    if (candidate.state !== "live_check_ready" || !candidate.endpoint_configured || !candidate.auth_configured) {
+      rejectionCodes.push("candidate_not_live_check_ready");
+    }
+    if (normalizeString(evidencePacket.adapter_id) && normalizeString(evidencePacket.adapter_id) !== candidate.adapter_id) {
+      rejectionCodes.push("adapter_id_mismatch");
+    }
+    if (normalizeString(evidencePacket.task_ref) && normalizeString(evidencePacket.task_ref) !== candidate.task_ref) {
+      rejectionCodes.push("task_ref_mismatch");
+    }
+  }
+  if (!normalizeString(evidencePacket.operator_evidence_ref)) rejectionCodes.push("operator_evidence_missing");
+  if (!normalizeString(evidencePacket.auth_boundary_ref)) rejectionCodes.push("auth_boundary_evidence_missing");
+  if (!healthCheck || typeof healthCheck !== "object") {
+    rejectionCodes.push("health_check_missing");
+  } else if (healthCheck.health_ok !== true || Number(healthCheck.status_code || 0) < 200 || Number(healthCheck.status_code || 0) >= 300) {
+    rejectionCodes.push("health_check_failed");
+  }
+  if (latencyValue === null || latencyValue === undefined || latencyValue === "" || !Number.isFinite(latencyMs) || latencyMs < 0) {
+    rejectionCodes.push("latency_measurement_missing");
+  } else if (Number.isFinite(latencyBudgetMs) && latencyBudgetMs > 0 && latencyMs > latencyBudgetMs) {
+    rejectionCodes.push("latency_budget_exceeded");
+  }
+  if (!normalizeString(evidencePacket.failure_behavior_ref)) rejectionCodes.push("failure_behavior_evidence_missing");
+  if (!normalizeString(evidencePacket.proof_fact_shape_ref)) rejectionCodes.push("proof_fact_shape_evidence_missing");
+  if (containsSecretMaterial(evidencePacket)) rejectionCodes.push("secret_material_forbidden");
+
+  return {
+    validation_version: "xytara-framework-provider-promotion-evidence-validation-v1",
+    promotion_allowed: rejectionCodes.length === 0,
+    framework_id: frameworkId || null,
+    rejection_codes: Array.from(new Set(rejectionCodes)),
+    required_requirements: FRAMEWORK_PROVIDER_PROMOTION_REQUIREMENTS.slice(),
+    boundary: "framework_provider_promotion_requires_endpoint_auth_health_latency_failure_and_proof_fact_evidence_without_secret_material"
+  };
+}
+
+function summarizeFrameworkProviderPromotionPack(options = {}) {
+  const pack = buildFrameworkProviderPromotionPack(options);
+  return {
+    ok: true,
+    product: pack.product,
+    category: "machine-commerce-framework-provider-promotion-summary",
+    summary_version: "xytara-framework-provider-promotion-summary-v1",
+    posture: pack.posture,
+    promotion_state: pack.promotion_state,
+    require_live: pack.require_live,
+    framework_candidate_count: pack.framework_candidate_count,
+    live_check_ready_count: pack.live_check_ready_count,
+    promoted_provider_count: pack.promoted_provider_count,
+    promotion_requirement_count: pack.promotion_requirements.length,
+    deterministic_rejection_code_count: pack.deterministic_rejection_codes.length,
+    boundary_count: pack.strict_boundaries.length,
+    linked_surfaces: pack.linked_surfaces
+  };
+}
+
+module.exports = {
+  FRAMEWORK_PROVIDER_CANDIDATES,
+  FRAMEWORK_PROVIDER_PROMOTION_REJECTION_CODES,
+  buildFrameworkProviderPromotionPack,
+  summarizeFrameworkProviderPromotionPack,
+  validateFrameworkProviderPromotionEvidence
+};

package/lib/operator_intelligence.js

@@ -5,12 +5,71 @@ const { buildEconomicsIntelligenceSummary } = require("./commerce_economics");
 const { buildPartnerIntelligencePack } = require("./partner_intelligence");
 const { buildRevenueSignalSummary } = require("./pricing_optimization_contract");
 
+const OPERATOR_OBSERVABILITY_REJECTION_CODES = [
+  "boundary_missing",
+  "missing_linked_surface",
+  "mutation_surface_linked",
+  "settlement_submission_surface_linked",
+  "fund_movement_surface_linked",
+  "unsafe_attention_action",
+  "secret_material_forbidden",
+  "count_not_number"
+];
+
+const OPERATOR_OBSERVABILITY_REQUIRED_SURFACES = [
+  "activity_ledger_ref",
+  "payment_ledger_ref",
+  "reconciliation_report_ref",
+  "deliveries_ref",
+  "settlement_ref",
+  "adapter_depth_ref",
+  "pricing_revenue_signal_ref",
+  "operator_intelligence_ref"
+];
+
 function valuesFromCollection(collection) {
   if (!collection) return [];
   if (collection instanceof Map) return Array.from(collection.values());
   return Array.isArray(collection) ? collection : [];
 }
 
+function containsSecretMaterial(value) {
+  if (!value || typeof value !== "object") return false;
+  const secretishKey = /(secret|token|credential|password|private[_-]?key|authorization|api[_-]?key)/i;
+  const secretishValue = /(bearer\s+[a-z0-9._-]{8,}|sk_live_|npm_[a-z0-9]|ghp_[a-z0-9]|xox[baprs]-)/i;
+  const stack = [value];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (!current || typeof current !== "object") continue;
+    for (const [key, entry] of Object.entries(current)) {
+      if (secretishKey.test(String(key))) return true;
+      if (typeof entry === "string" && secretishValue.test(entry)) return true;
+      if (entry && typeof entry === "object") stack.push(entry);
+    }
+  }
+  return false;
+}
+
+function isUnsafeLinkedSurface(value) {
+  const normalized = String(value || "").toLowerCase();
+  return /\/(submit|refund|grant|release|rotate|delete|mutate|write|webhook|checkout)(\/|$)|submission|fund-movement|fund_movement/.test(normalized);
+}
+
+function isSettlementSubmissionSurface(value) {
+  const normalized = String(value || "").toLowerCase();
+  return /settlement.*(submit|submission|broadcast|raw_tx)|\/submit(\/|$)/.test(normalized);
+}
+
+function isFundMovementSurface(value) {
+  const normalized = String(value || "").toLowerCase();
+  return /(fund|treasury|credit).*(release|transfer|withdraw|grant|refund|disburse)|external-credit-grants/.test(normalized);
+}
+
+function isUnsafeAttentionAction(action) {
+  const normalized = String(action || "").toLowerCase();
+  return /^(submit|grant|refund|release|rotate|delete|write|mutate|broadcast|withdraw|transfer|disburse)_/.test(normalized);
+}
+
 function unwrapTransaction(entry) {
   if (entry && entry.transaction) return entry.transaction;
   return entry || null;
@@ -269,10 +328,52 @@ function buildOperatorObservabilityPack(state, input) {
       pricing_revenue_signal_ref: "/v1/pricing-optimization/revenue-signal-summary",
       operator_intelligence_ref: "/v1/operator-intelligence"
     },
+    deterministic_rejection_codes: OPERATOR_OBSERVABILITY_REJECTION_CODES.slice(),
     boundary: "read_only_operator_visibility_no_fund_movement_no_settlement_submission_no_secret_material"
   };
 }
 
+function validateOperatorObservabilityBoundary(packInput) {
+  const pack = packInput || {};
+  const rejectionCodes = [];
+  const linkedSurfaces = pack.linked_surfaces || {};
+  const counts = pack.counts || {};
+  if (pack.boundary !== "read_only_operator_visibility_no_fund_movement_no_settlement_submission_no_secret_material") {
+    rejectionCodes.push("boundary_missing");
+  }
+  for (const surfaceName of OPERATOR_OBSERVABILITY_REQUIRED_SURFACES) {
+    if (!linkedSurfaces[surfaceName]) {
+      rejectionCodes.push("missing_linked_surface");
+    }
+  }
+  for (const surfaceRef of Object.values(linkedSurfaces)) {
+    if (isUnsafeLinkedSurface(surfaceRef)) rejectionCodes.push("mutation_surface_linked");
+    if (isSettlementSubmissionSurface(surfaceRef)) rejectionCodes.push("settlement_submission_surface_linked");
+    if (isFundMovementSurface(surfaceRef)) rejectionCodes.push("fund_movement_surface_linked");
+  }
+  const attentionQueue = Array.isArray(pack.attention_queue) ? pack.attention_queue : [];
+  for (const item of attentionQueue) {
+    if (item && isUnsafeAttentionAction(item.action)) {
+      rejectionCodes.push("unsafe_attention_action");
+    }
+  }
+  for (const [key, value] of Object.entries(counts)) {
+    if (key.endsWith("_count") && typeof value !== "number") {
+      rejectionCodes.push("count_not_number");
+    }
+  }
+  if (containsSecretMaterial(pack)) {
+    rejectionCodes.push("secret_material_forbidden");
+  }
+  return {
+    validation_version: "xytara-operator-observability-boundary-validation-v1",
+    observability_boundary_valid: rejectionCodes.length === 0,
+    rejection_codes: Array.from(new Set(rejectionCodes)),
+    deterministic_rejection_codes: OPERATOR_OBSERVABILITY_REJECTION_CODES.slice(),
+    boundary: "operator_observability_must_remain_read_only_without_secret_material_mutation_links_or_fund_movement_actions"
+  };
+}
+
 function summarizeOperatorObservabilityPack(state, input) {
   const pack = buildOperatorObservabilityPack(state, input);
   return {
@@ -292,6 +393,7 @@ function summarizeOperatorObservabilityPack(state, input) {
     adapter_failure_count: pack.counts.adapter_failure_count,
     pricing_sample_maturity: pack.pricing_telemetry_summary.sample_maturity,
     attention_item_count: pack.attention_queue.length,
+    deterministic_rejection_code_count: pack.deterministic_rejection_codes.length,
     linked_surfaces: pack.linked_surfaces
   };
 }
@@ -300,5 +402,6 @@ module.exports = {
   buildOperatorIntelligencePack,
   summarizeOperatorIntelligencePack,
   buildOperatorObservabilityPack,
-  summarizeOperatorObservabilityPack
+  summarizeOperatorObservabilityPack,
+  validateOperatorObservabilityBoundary
 };

package/lib/pricing_optimization_contract.js

@@ -11,6 +11,27 @@ const PRICING_BAND_UNITS = {
   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;
@@ -466,6 +487,195 @@ function buildOptimizationRecommendations(state) {
   };
 }
 
+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();
@@ -476,6 +686,7 @@ function buildPricingOptimizationPack(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",
@@ -501,6 +712,7 @@ function buildPricingOptimizationPack(state) {
     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",
@@ -516,7 +728,9 @@ function buildPricingOptimizationPack(state) {
       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"
+      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"
     }
   };
 }
@@ -541,6 +755,8 @@ function summarizePricingOptimizationPack(state) {
     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
   };
 }
@@ -552,5 +768,8 @@ module.exports = {
   buildQuoteCohorts,
   buildRevenueSignalSummary,
   buildPricingDecisionGuardrail,
-  buildOptimizationRecommendations
+  buildOptimizationRecommendations,
+  buildPricingExperimentPlan,
+  summarizePricingExperimentPlan,
+  validatePricingExperimentLaunchRequest
 };