xytara 2.6.0 → 2.8.0

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
 };

package/lib/release_history.js

@@ -10,6 +10,31 @@ function buildReleaseHistory() {
     current_version: packageJson.version,
     release_track: "public_release",
     history: [
+      {
+        version: "2.8.0",
+        channel: "public_release",
+        maturity_posture: "release_boundary_hardened",
+        headline: "release-boundary hardening with provider promotion evidence gates, pricing experiment guardrails, treasury public-claim safety, and read-only operator observability boundaries",
+        milestone_refs: [
+          "framework_provider_promotion_evidence_gate",
+          "pricing_experiment_plan_gate",
+          "pricing_experiment_launch_gate",
+          "treasury_public_claim_boundary",
+          "operator_observability_read_only_boundary"
+        ]
+      },
+      {
+        version: "2.7.0",
+        channel: "public_release",
+        maturity_posture: "expansion_closeout",
+        headline: "expansion-closeout release with package-hardening, clean-consumer release smoke testing, and disciplined adapter claim boundaries",
+        milestone_refs: [
+          "npm_packaged_verification_scripts",
+          "release_candidate_packaging_guard",
+          "clean_consumer_release_smoke",
+          "expansion_closeout_claim_boundaries"
+        ]
+      },
       {
         version: "2.6.0",
         channel: "public_release",

package/lib/treasury_destinations_contract.js

@@ -177,6 +177,30 @@ const RAIL_PROFILES = [
   }
 ];
 
+const TREASURY_PUBLIC_BOUNDARY_REJECTION_CODES = [
+  "public_custody_destination_leak",
+  "public_external_ref_leak",
+  "public_custody_ref_leak",
+  "public_reporting_ref_leak",
+  "public_wallet_ref_leak",
+  "public_provider_ref_leak",
+  "internal_rail_public_claimed",
+  "readiness_only_rail_public_claimed",
+  "claim_boundary_mismatch",
+  "unsupported_live_claim_rail",
+  "operator_visibility_rule_missing"
+];
+
+const SENSITIVE_PUBLIC_DESTINATION_FIELDS = [
+  "external_ref",
+  "custody_ref",
+  "reporting_ref",
+  "wallet_ref",
+  "provider_ref",
+  "merchant_address",
+  "merchant_paymail"
+];
+
 function classifyDestinationSource(profile, paymentConfig) {
   const settlementMode = profile.settlement_mode;
   const mapEntry = paymentConfig.treasury_destinations_by_settlement_mode[settlementMode];
@@ -432,6 +456,7 @@ function buildOperatorTreasuryDestinationsPack() {
       ? "claim_only_the_rails_with_real_configured_destinations_as_live_landing_paths"
       : "no_multi-rail_operational_claims_until_real_destinations_exist",
     custody_visibility_rule: "do_not_expose_real_external_refs_or_custody_refs_on_public_surfaces",
+    deterministic_rejection_codes: TREASURY_PUBLIC_BOUNDARY_REJECTION_CODES.slice(),
     config_examples: Object.fromEntries(RAIL_PROFILES.map((profile) => [profile.settlement_mode, profile.config_template]))
   };
 }
@@ -458,6 +483,7 @@ function buildTreasuryDestinationsPack() {
     operator_rule: operatorPack.operator_rule,
     claim_discipline_rule: "unsupported_or_unconfigured_rails_may_be_listed_as_architecture_but_not_as_live_landing_paths",
     privacy_rule: "public_surfaces_must_not_expose_real_treasury_landing_refs_or_custody_provider_refs",
+    deterministic_rejection_codes: TREASURY_PUBLIC_BOUNDARY_REJECTION_CODES.slice(),
     config_examples: operatorPack.config_examples
   };
 }
@@ -475,6 +501,7 @@ function summarizeTreasuryDestinationsPack() {
     readiness_only_profile_count: pack.readiness_summary.readiness_only_profile_count,
     reporting_gap_count: pack.readiness_summary.reporting_gap_count,
     internal_only_profile_count: pack.profiles.filter((entry) => entry.compliance_posture === "internal_only_policy_gated").length,
+    deterministic_rejection_code_count: pack.deterministic_rejection_codes.length,
     public_claim_boundary: pack.public_claim_boundary,
     linked_surfaces: pack.supported_surfaces
   };
@@ -493,6 +520,7 @@ function summarizeOperatorTreasuryDestinationsPack() {
     readiness_only_profile_count: pack.readiness_summary.readiness_only_profile_count,
     reporting_gap_count: pack.readiness_summary.reporting_gap_count,
     internal_only_profile_count: pack.profiles.filter((entry) => entry.compliance_posture === "internal_only_policy_gated").length,
+    deterministic_rejection_code_count: pack.deterministic_rejection_codes.length,
     public_claim_boundary: pack.public_claim_boundary,
     linked_surfaces: pack.supported_surfaces
   };
@@ -534,10 +562,80 @@ function buildTreasuryDestinationValidationPreview(input) {
   }
 }
 
+function arraysEqual(left, right) {
+  const leftSorted = (Array.isArray(left) ? left : []).slice().sort();
+  const rightSorted = (Array.isArray(right) ? right : []).slice().sort();
+  return leftSorted.length === rightSorted.length && leftSorted.every((entry, index) => entry === rightSorted[index]);
+}
+
+function validateTreasuryDestinationPublicBoundary(packInput) {
+  const pack = packInput || buildTreasuryDestinationsPack();
+  const profiles = Array.isArray(pack.profiles) ? pack.profiles : [];
+  const boundary = pack.public_claim_boundary || {};
+  const rejectionCodes = [];
+  const liveClaimableRails = profiles.filter((entry) => entry && entry.public_claim_allowed).map((entry) => entry.rail_id);
+  const internalOnlyRails = profiles
+    .filter((entry) => entry && entry.compliance_posture === "internal_only_policy_gated")
+    .map((entry) => entry.rail_id);
+  const readinessOnlyRails = profiles
+    .filter((entry) => entry && !entry.public_claim_allowed && entry.compliance_posture !== "internal_only_policy_gated")
+    .map((entry) => entry.rail_id);
+
+  for (const profile of profiles) {
+    if (!profile) continue;
+    if (profile.custody_destination != null) {
+      rejectionCodes.push("public_custody_destination_leak");
+    }
+    const visibility = profile.destination_visibility || {};
+    for (const fieldName of SENSITIVE_PUBLIC_DESTINATION_FIELDS) {
+      if (visibility[fieldName] != null) {
+        rejectionCodes.push(`public_${fieldName}_leak`);
+      }
+      if (profile[fieldName] != null) {
+        rejectionCodes.push(`public_${fieldName}_leak`);
+      }
+    }
+    if (profile.compliance_posture === "internal_only_policy_gated" && profile.public_claim_allowed === true) {
+      rejectionCodes.push("internal_rail_public_claimed");
+    }
+    if (boundary.readiness_only_rails && boundary.readiness_only_rails.includes(profile.rail_id) && profile.public_claim_allowed === true) {
+      rejectionCodes.push("readiness_only_rail_public_claimed");
+    }
+  }
+
+  const boundaryLiveRails = Array.isArray(boundary.live_claimable_rails) ? boundary.live_claimable_rails : [];
+  const boundaryReadinessRails = Array.isArray(boundary.readiness_only_rails) ? boundary.readiness_only_rails : [];
+  const boundaryInternalRails = Array.isArray(boundary.internal_only_rails) ? boundary.internal_only_rails : [];
+  if (
+    !arraysEqual(liveClaimableRails, boundaryLiveRails)
+    || !arraysEqual(readinessOnlyRails, boundaryReadinessRails)
+    || !arraysEqual(internalOnlyRails, boundaryInternalRails)
+  ) {
+    rejectionCodes.push("claim_boundary_mismatch");
+  }
+  if (boundaryLiveRails.some((railId) => !profiles.some((entry) => entry && entry.rail_id === railId && entry.public_claim_allowed === true))) {
+    rejectionCodes.push("unsupported_live_claim_rail");
+  }
+  if (pack.category === "machine-commerce-operator-treasury-destinations-pack"
+    && pack.custody_visibility_rule !== "do_not_expose_real_external_refs_or_custody_refs_on_public_surfaces") {
+    rejectionCodes.push("operator_visibility_rule_missing");
+  }
+
+  return {
+    validation_version: "xytara-treasury-public-boundary-validation-v1",
+    public_boundary_valid: rejectionCodes.length === 0,
+    rejection_codes: Array.from(new Set(rejectionCodes)),
+    deterministic_rejection_codes: TREASURY_PUBLIC_BOUNDARY_REJECTION_CODES.slice(),
+    public_claim_boundary: boundary,
+    boundary: "public_treasury_surfaces_must_not_expose_landing_or_custody_refs_and_must_match_claim_allowed_state"
+  };
+}
+
 module.exports = {
   buildOperatorTreasuryDestinationsPack,
   summarizeOperatorTreasuryDestinationsPack,
   buildTreasuryDestinationsPack,
   summarizeTreasuryDestinationsPack,
-  buildTreasuryDestinationValidationPreview
+  buildTreasuryDestinationValidationPreview,
+  validateTreasuryDestinationPublicBoundary
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xytara",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "Agent-commerce runtime for quote, pay, execute, deliver, meter, and integrate.",
   "main": "index.js",
   "bin": {
@@ -35,6 +35,7 @@
     "client.js",
     "server.js",
     "bin/",
+    "scripts/",
     "fixtures/",
     "integrations/",
     "lib/",
@@ -71,12 +72,16 @@
     "verify:package": "node scripts/verify_all.js",
     "verify:integrations": "node scripts/verify_integrations.js",
     "verify:adapters": "node scripts/verify_adapters.js",
+    "verify:framework-provider-promotion": "node scripts/verify_framework_provider_promotion.js",
+    "verify:operator-observability-boundary": "node scripts/verify_operator_observability_boundary.js",
+    "verify:pricing-experiment-plan": "node scripts/verify_pricing_experiment_plan.js",
+    "verify:treasury-public-boundary": "node scripts/verify_treasury_public_boundary.js",
     "verify:tooling": "node scripts/verify_tooling.js",
     "verify:examples": "node scripts/verify_examples.js",
     "verify:service": "node scripts/verify_service.js",
     "verify:release-candidate": "node scripts/verify_release_candidate.js",
     "verify:production-readiness": "node scripts/verify_production_readiness.js",
-    "verify:all": "node scripts/verify_all.js && node scripts/verify_integrations.js && node scripts/verify_adapters.js && node scripts/verify_tooling.js && node scripts/verify_examples.js && node scripts/verify_service.js",
+    "verify:all": "node scripts/verify_all.js && node scripts/verify_integrations.js && node scripts/verify_adapters.js && node scripts/verify_framework_provider_promotion.js && node scripts/verify_operator_observability_boundary.js && node scripts/verify_pricing_experiment_plan.js && node scripts/verify_treasury_public_boundary.js && node scripts/verify_tooling.js && node scripts/verify_examples.js && node scripts/verify_service.js",
     "prepublishOnly": "npm run verify:release-candidate"
   }
 }

package/scripts/generate_treasury_destinations.js

@@ -0,0 +1,195 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline/promises");
+const { stdin: input, stdout: output } = require("process");
+
+const TEMPLATE_PATH = path.resolve(__dirname, "..", "TREASURY_DESTINATIONS.production.template.json");
+const DEFAULT_OUTPUT_PATH = path.resolve(__dirname, "..", "TREASURY_DESTINATIONS.production.json");
+
+const RAIL_ORDER = [
+  "bsv_teranode",
+  "evm",
+  "base",
+  "usdc",
+  "dai",
+  "solana_payment",
+  "xpr_payment",
+  "antelope_payment",
+  "monero"
+];
+
+const RAIL_HELP = {
+  bsv_teranode: "BSV treasury receive address or paymail.",
+  evm: "Ethereum mainnet treasury receive address.",
+  base: "Base treasury receive address.",
+  usdc: "USDC treasury receive address on the chain you actually use.",
+  dai: "DAI treasury receive address on the chain you actually use.",
+  solana_payment: "Solana treasury receive address.",
+  xpr_payment: "Proton/XPR treasury account or address.",
+  antelope_payment: "Antelope treasury account or address.",
+  monero: "Monero treasury receive address. Keep this internal-only unless truly needed."
+};
+
+function loadTemplate() {
+  return JSON.parse(fs.readFileSync(TEMPLATE_PATH, "utf8"));
+}
+
+function parseArgs(argv) {
+  const args = { outputPath: DEFAULT_OUTPUT_PATH };
+  for (let i = 0; i < argv.length; i += 1) {
+    const part = argv[i];
+    if (part === "--output" && argv[i + 1]) {
+      args.outputPath = path.resolve(process.cwd(), argv[i + 1]);
+      i += 1;
+    } else if (part === "--include-monero") {
+      args.includeMonero = true;
+    }
+  }
+  return args;
+}
+
+function slugFromRail(rail) {
+  return String(rail || "").replace(/_payment$/, "").replace(/[^a-z0-9]+/gi, "_").replace(/^_+|_+$/g, "").toLowerCase();
+}
+
+function defaultRef(prefix, rail, suffix = "primary") {
+  return `${prefix}.${slugFromRail(rail)}.${suffix}`;
+}
+
+function defaultStorageClassForRail(rail) {
+  if (rail === "bsv_teranode") return "cold_primary";
+  if (rail === "monero") return "isolated_policy_gated";
+  return "warm_operational";
+}
+
+function defaultProviderRefForRail(rail) {
+  if (rail === "bsv_teranode") return "";
+  if (rail === "usdc" || rail === "dai") return "";
+  return defaultRef("rpc", rail);
+}
+
+function defaultWalletRefForRail(rail) {
+  if (rail === "bsv_teranode") return "";
+  if (rail === "monero") return "";
+  return defaultRef("wallet", rail);
+}
+
+function defaultReportingRefForRail(rail) {
+  if (rail === "monero") return "ledger.monero.internal";
+  return defaultRef("ledger", rail);
+}
+
+function defaultCustodyRefForRail(rail) {
+  if (rail === "monero") return "vault.monero.policy_gated";
+  return defaultRef("vault", rail);
+}
+
+function validateLikelyAddress(rail, value) {
+  if (!value) return null;
+  if (rail === "evm" || rail === "base" || rail === "usdc" || rail === "dai") {
+    return /^0x[a-fA-F0-9]{40}$/.test(value) ? null : "Expected a 0x-prefixed 20-byte EVM address.";
+  }
+  if (rail === "solana_payment") {
+    return /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(value) ? null : "Expected a likely Solana base58 address.";
+  }
+  return null;
+}
+
+async function ask(rl, prompt, fallback = "") {
+  const suffix = fallback ? ` [${fallback}]` : "";
+  const answer = (await rl.question(`${prompt}${suffix}: `)).trim();
+  return answer || fallback;
+}
+
+async function askYesNo(rl, prompt, fallback = true) {
+  const hint = fallback ? "Y/n" : "y/N";
+  const answer = (await rl.question(`${prompt} [${hint}]: `)).trim().toLowerCase();
+  if (!answer) return fallback;
+  return answer === "y" || answer === "yes";
+}
+
+function pruneEmptyStrings(entry) {
+  return Object.fromEntries(
+    Object.entries(entry).filter(([, value]) => value !== "")
+  );
+}
+
+async function buildRailEntry(rl, rail, templateEntry, args) {
+  if (rail === "monero" && !args.includeMonero) {
+    const wantsMonero = await askYesNo(rl, "Include Monero in this treasury file?", false);
+    if (!wantsMonero) return templateEntry;
+  }
+
+  output.write(`\n[${rail}] ${RAIL_HELP[rail] || ""}\n`);
+  const shouldConfigure = await askYesNo(rl, `Configure ${rail} now?`, rail !== "monero");
+  if (!shouldConfigure) return templateEntry;
+
+  const entry = { ...templateEntry };
+  const externalRef = await ask(rl, "external_ref", entry.external_ref || "");
+  const validationMessage = validateLikelyAddress(rail, externalRef);
+  if (validationMessage) {
+    output.write(`  Warning: ${validationMessage}\n`);
+  }
+  entry.external_ref = externalRef;
+
+  if (entry.destination_id) {
+    entry.destination_id = await ask(rl, "destination_id", entry.destination_id);
+  }
+  if (entry.destination_kind) {
+    entry.destination_kind = await ask(rl, "destination_kind", entry.destination_kind);
+  }
+  if (Object.prototype.hasOwnProperty.call(entry, "network")) {
+    entry.network = await ask(rl, "network", entry.network || "mainnet");
+  }
+  if (Object.prototype.hasOwnProperty.call(entry, "chain_id")) {
+    entry.chain_id = await ask(rl, "chain_id", entry.chain_id || "");
+  }
+  if (Object.prototype.hasOwnProperty.call(entry, "asset_symbol")) {
+    entry.asset_symbol = await ask(rl, "asset_symbol", entry.asset_symbol || "");
+  }
+  if (Object.prototype.hasOwnProperty.call(entry, "policy_scope")) {
+    entry.policy_scope = await ask(rl, "policy_scope", entry.policy_scope || "internal_optional_privacy_reserve");
+  }
+
+  entry.custody_ref = await ask(rl, "custody_ref", defaultCustodyRefForRail(rail));
+  entry.reporting_ref = await ask(rl, "reporting_ref", defaultReportingRefForRail(rail));
+
+  if (Object.prototype.hasOwnProperty.call(entry, "wallet_ref")) {
+    entry.wallet_ref = await ask(rl, "wallet_ref", defaultWalletRefForRail(rail));
+  }
+  if (Object.prototype.hasOwnProperty.call(entry, "provider_ref")) {
+    entry.provider_ref = await ask(rl, "provider_ref", defaultProviderRefForRail(rail));
+  }
+
+  entry.storage_class = await ask(rl, "storage_class", defaultStorageClassForRail(rail));
+  return pruneEmptyStrings(entry);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const template = loadTemplate();
+  const rl = readline.createInterface({ input, output });
+
+  output.write("xytara treasury destination generator\n");
+  output.write("This script does not create wallets or keys. It builds TREASURY_DESTINATIONS.production.json from the receive destinations you already control.\n");
+  output.write(`Template: ${TEMPLATE_PATH}\n`);
+  output.write(`Output:   ${args.outputPath}\n`);
+
+  const result = {};
+  for (const rail of RAIL_ORDER) {
+    result[rail] = await buildRailEntry(rl, rail, template[rail], args);
+  }
+
+  await rl.close();
+
+  fs.writeFileSync(args.outputPath, `${JSON.stringify(result, null, 2)}\n`, "utf8");
+  output.write(`\nWrote ${args.outputPath}\n`);
+  output.write("Upload this file to Render Secret Files, then set XYTARA_TREASURY_DESTINATIONS_PATH=./TREASURY_DESTINATIONS.production.json\n");
+}
+
+main().catch((error) => {
+  console.error(error && error.stack ? error.stack : error);
+  process.exitCode = 1;
+});