xytara 3.1.0 → 3.1.2

package/lib/first_run_conversion_contract.js

@@ -1,290 +1,290 @@
-"use strict";
-
-const { buildScenarioPack } = require("./release_pack");
-const { summarizeX402LanePack } = require("./x402_lane_contract");
-const { summarizeProviderRuntimeJourneyPack } = require("./provider_runtime_journey_contract");
-const { summarizeMarketLaneTracePack } = require("./market_lane_trace_contract");
-
-function uniqueSorted(values) {
-  return Array.from(new Set((Array.isArray(values) ? values : []).filter(Boolean))).sort();
-}
-
-function buildConversion(entry) {
-  const scenario = entry.scenario || {};
-  const stages = Array.isArray(entry.stages) ? entry.stages : [];
-  return {
-    conversion_id: entry.conversion_id,
-    conversion_label: entry.conversion_label,
-    conversion_posture: entry.conversion_posture,
-    claim_status: "bounded_live",
-    public_first_contact_ready: Boolean(entry.public_first_contact_ready),
-    quote_ready: stages.some((stage) => stage.stage_id === "quote"),
-    revenue_ready: Boolean(entry.revenue_ready),
-    proof_ready: Boolean(entry.proof_ready),
-    operator_inspection_ready: Boolean(entry.operator_inspection_ready),
-    payment_posture: entry.payment_posture,
-    stage_count: stages.length,
-    stages,
-    entrypoint: entry.entrypoint,
-    scenario_ref: scenario.scenario_ref || null,
-    success_signals: Array.isArray(scenario.success_signals) ? scenario.success_signals.slice() : [],
-    supporting_surfaces: uniqueSorted([
-      ...(entry.supporting_surfaces || []),
-      ...(scenario.surfaces || [])
-    ]),
-    claim_boundary: entry.claim_boundary
-  };
-}
-
-function buildFirstRunConversionPack() {
-  const scenarioPack = buildScenarioPack();
-  const scenarios = Array.isArray(scenarioPack.scenarios) ? scenarioPack.scenarios : [];
-  const x402Summary = summarizeX402LanePack();
-  const providerJourneySummary = summarizeProviderRuntimeJourneyPack();
-  const traceSummary = summarizeMarketLaneTracePack();
-
-  const directPayScenario = scenarios.find((entry) => entry && entry.scenario_ref === "scenario.direct_pay.trust_verify") || {};
-  const creditsScenario = scenarios.find((entry) => entry && entry.scenario_ref === "scenario.credits_first.repeat_run") || {};
-  const proofScenario = scenarios.find((entry) => entry && entry.scenario_ref === "scenario.runtime_to_proof.followthrough") || {};
-
-  const conversions = [
-    buildConversion({
-      conversion_id: "direct_x402_paid_proof",
-      conversion_label: "direct x402 paid proof",
-      conversion_posture: "quote_to_direct_pay_execute_and_proof_pickup",
-      public_first_contact_ready: true,
-      revenue_ready: true,
-      proof_ready: true,
-      operator_inspection_ready: true,
-      payment_posture: "direct_x402",
-      entrypoint: "xytara first-run --run-quote --account ACCOUNT_REF --pretty",
-      scenario: directPayScenario,
-      stages: [
-        {
-          stage_index: 1,
-          stage_id: "discover",
-          posture: "inspect_machine_payment_lane",
-          surface_ref: "/v1/x402/summary",
-          expected_outcome: "confirm the default machine-payment lane and bounded x402 posture before quoting"
-        },
-        {
-          stage_index: 2,
-          stage_id: "quote",
-          posture: "secretless_first_contact_quote",
-          surface_ref: "xytara first-run --run-quote --account ACCOUNT_REF --pretty",
-          expected_outcome: "produce a payment-required challenge without spending funds or requiring wallet secrets"
-        },
-        {
-          stage_index: 3,
-          stage_id: "fund",
-          posture: "pay_admission_after_quote",
-          surface_ref: "/x402/commands/execute",
-          expected_outcome: "replay the quoted request through the machine-payment lane with approved payment proof"
-        },
-        {
-          stage_index: 4,
-          stage_id: "execute",
-          posture: "bounded_paid_runtime_execution",
-          surface_ref: "/x402/commands/execute",
-          expected_outcome: "execute the paid runtime call and receive transaction, payment, and delivery continuity"
-        },
-        {
-          stage_index: 5,
-          stage_id: "prove",
-          posture: "result_package_proof_pickup",
-          surface_ref: "https://xoonya.onrender.com/v1/proof-center/result-package-handoff/summary",
-          expected_outcome: "pick up result-package proof followthrough instead of ending at runtime output"
-        },
-        {
-          stage_index: 6,
-          stage_id: "inspect",
-          posture: "operator_and_builder_inspection",
-          surface_ref: "/v1/payment-ledger",
-          expected_outcome: "inspect payment ledger and settlement-linked runtime consequence after the paid call completes"
-        }
-      ],
-      supporting_surfaces: [
-        "/v1/settlement/bsv-teranode",
-        "/v1/transaction-center/result-packages/export-template",
-        "https://xoonya.onrender.com/v1/proof-center/result-package-handoff/review/summary"
-      ],
-      claim_boundary: "claim_direct_x402_first_run_conversion_only_for_the_listed_quote_pay_execute_proof_and_inspection_surfaces_not_as_unbounded_payment_or_custody_control"
-    }),
-    buildConversion({
-      conversion_id: "credits_first_paid_proof",
-      conversion_label: "credits-first paid proof",
-      conversion_posture: "quote_to_credits_execute_and_proof_pickup",
-      public_first_contact_ready: true,
-      revenue_ready: true,
-      proof_ready: true,
-      operator_inspection_ready: true,
-      payment_posture: "credits_first",
-      entrypoint: "xytara first-run --execute-with-credits --account ACCOUNT_REF --pretty",
-      scenario: creditsScenario,
-      stages: [
-        {
-          stage_index: 1,
-          stage_id: "discover",
-          posture: "inspect_repeat_use_path",
-          surface_ref: "/v1/release-pack/scenarios/summary",
-          expected_outcome: "confirm the repeat-use credits-first path before funding or execution"
-        },
-        {
-          stage_index: 2,
-          stage_id: "quote",
-          posture: "secretless_first_contact_quote",
-          surface_ref: "xytara first-run --run-quote --account ACCOUNT_REF --pretty",
-          expected_outcome: "establish pricing and admission posture before switching to funded credits-first execution"
-        },
-        {
-          stage_index: 3,
-          stage_id: "fund",
-          posture: "approved_credit_funding",
-          surface_ref: "/v1/credit-packs/summary",
-          expected_outcome: "fund repeat-use credits through an approved money-in path without changing the public execution surface"
-        },
-        {
-          stage_index: 4,
-          stage_id: "execute",
-          posture: "bounded_credits_first_runtime_execution",
-          surface_ref: "/v1/commands/execute",
-          expected_outcome: "reuse the governed runtime surface with payment_preference=credits_first on a funded account"
-        },
-        {
-          stage_index: 5,
-          stage_id: "prove",
-          posture: "result_package_proof_pickup",
-          surface_ref: "https://xoonya.onrender.com/v1/proof-center/result-package-handoff/review/summary",
-          expected_outcome: "continue the funded execution into proof-side review and handoff verification"
-        },
-        {
-          stage_index: 6,
-          stage_id: "inspect",
-          posture: "repeat_use_account_inspection",
-          surface_ref: "/v1/economics/accounts/:account_id/usage-meters",
-          expected_outcome: "inspect repeat-use spend, usage meters, and entitlement continuity after the funded execution"
-        }
-      ],
-      supporting_surfaces: [
-        "/v1/economics/accounts/:account_id/entitlements",
-        "/v1/economics/accounts/:account_id/credit-balance",
-        "/v1/transaction-center/result-packages/export-template"
-      ],
-      claim_boundary: "claim_credits_first_conversion_only_for_the_listed_funded_account_runtime_and_proof_followthrough_surfaces_not_as_hidden_money_in_or_global_credit_truth"
-    }),
-    buildConversion({
-      conversion_id: "result_package_proof_pickup",
-      conversion_label: "result-package proof pickup",
-      conversion_posture: "runtime_delivery_into_xoonya_review_and_run",
-      public_first_contact_ready: false,
-      revenue_ready: false,
-      proof_ready: true,
-      operator_inspection_ready: true,
-      payment_posture: "carried_from_prior_paid_execution",
-      entrypoint: "POST /v1/transaction-center/result-packages/export",
-      scenario: proofScenario,
-      stages: [
-        {
-          stage_index: 1,
-          stage_id: "discover",
-          posture: "inspect_result_package_followthrough",
-          surface_ref: "/v1/transaction-center/result-packages/summary",
-          expected_outcome: "discover the result-package surface that keeps runtime output proof-ready"
-        },
-        {
-          stage_index: 2,
-          stage_id: "execute",
-          posture: "carry_forward_prior_paid_runtime_result",
-          surface_ref: "/v1/transaction-center/transaction-class-packs/run",
-          expected_outcome: "carry a paid runtime result into the governed result-package export and continuation path"
-        },
-        {
-          stage_index: 3,
-          stage_id: "deliver",
-          posture: "export_portable_handoff_bundle",
-          surface_ref: "/v1/transaction-center/result-packages/export-template",
-          expected_outcome: "export a portable handoff bundle that is ready for proof-side review and run"
-        },
-        {
-          stage_index: 4,
-          stage_id: "prove",
-          posture: "xoonya_review_and_run",
-          surface_ref: "https://xoonya.onrender.com/v1/proof-center/result-package-handoff/run",
-          expected_outcome: "continue the result package into xoonya proof review and deterministic run surfaces"
-        },
-        {
-          stage_index: 5,
-          stage_id: "inspect",
-          posture: "proof_service_and_bridge_inspection",
-          surface_ref: "https://xoonya.onrender.com/v1/proof-center/verification-services/summary",
-          expected_outcome: "inspect the proof-facing service posture that completes the runtime-to-proof conversion path"
-        }
-      ],
-      supporting_surfaces: [
-        "https://xoonya.onrender.com/v1/proof-center/result-package-handoff/summary",
-        "https://xoonya.onrender.com/v1/proof-center/result-package-handoff/review/summary"
-      ],
-      claim_boundary: "claim_result_package_proof_pickup_only_for_the_listed_runtime_export_handoff_review_and_run_surfaces_not_as_generic_external_proof_or_settlement_truth"
-    })
-  ];
-
-  return {
-    ok: true,
-    product: "xytara",
-    category: "machine-commerce-first-run-conversion-pack",
-    pack_version: "xytara-first-run-conversion-pack-v1",
-    posture: "launch_grade_quote_fund_execute_proof_conversion_paths",
-    doctrine: "first_run_conversion_paths_make_public_discovery_revenue_and_proof_followthrough_stories_machine_readable_before_go_to_market_claims",
-    conversion_count: conversions.length,
-    public_first_contact_ready_count: conversions.filter((entry) => entry.public_first_contact_ready).length,
-    revenue_ready_conversion_count: conversions.filter((entry) => entry.revenue_ready).length,
-    proof_ready_conversion_count: conversions.filter((entry) => entry.proof_ready).length,
-    operator_inspection_ready_count: conversions.filter((entry) => entry.operator_inspection_ready).length,
-    stage_total_count: conversions.reduce((total, entry) => total + Number(entry.stage_count || 0), 0),
-    linked_runtime_counts: {
-      x402_first_run_flow_count: Number(x402Summary.first_run_flow_count || 0),
-      provider_runtime_journey_count: Number(providerJourneySummary.journey_count || 0),
-      market_lane_trace_count: Number(traceSummary.market_lane_trace_count || 0)
-    },
-    conversions,
-    linked_surfaces: {
-      x402_lane_summary_ref: "/v1/x402/summary",
-      providers_summary_ref: "/v1/providers/summary",
-      provider_journeys_summary_ref: "/v1/providers/journeys/summary",
-      release_scenarios_summary_ref: "/v1/release-pack/scenarios/summary",
-      result_packages_summary_ref: "/v1/transaction-center/result-packages/summary",
-      result_package_export_template_ref: "/v1/transaction-center/result-packages/export-template",
-      xoonya_result_package_handoff_summary_ref: "https://xoonya.onrender.com/v1/proof-center/result-package-handoff/summary",
-      xoonya_result_package_review_summary_ref: "https://xoonya.onrender.com/v1/proof-center/result-package-handoff/review/summary",
-      xoonya_verification_services_summary_ref: "https://xoonya.onrender.com/v1/proof-center/verification-services/summary"
-    }
-  };
-}
-
-function summarizeFirstRunConversionPack() {
-  const pack = buildFirstRunConversionPack();
-  return {
-    ok: true,
-    product: pack.product,
-    category: "machine-commerce-first-run-conversion-summary",
-    summary_version: "xytara-first-run-conversion-summary-v1",
-    conversion_count: pack.conversion_count,
-    public_first_contact_ready_count: pack.public_first_contact_ready_count,
-    revenue_ready_conversion_count: pack.revenue_ready_conversion_count,
-    proof_ready_conversion_count: pack.proof_ready_conversion_count,
-    operator_inspection_ready_count: pack.operator_inspection_ready_count,
-    stage_total_count: pack.stage_total_count,
-    linked_surfaces: pack.linked_surfaces
-  };
-}
-
-function getFirstRunConversionDetail(conversionId) {
-  const normalized = String(conversionId || "").trim().toLowerCase();
-  return (buildFirstRunConversionPack().conversions || []).find((entry) => entry.conversion_id === normalized) || null;
-}
-
-module.exports = {
-  buildFirstRunConversionPack,
-  summarizeFirstRunConversionPack,
-  getFirstRunConversionDetail
-};
+"use strict";
+
+const { buildScenarioPack } = require("./release_pack");
+const { summarizeX402LanePack } = require("./x402_lane_contract");
+const { summarizeProviderRuntimeJourneyPack } = require("./provider_runtime_journey_contract");
+const { summarizeMarketLaneTracePack } = require("./market_lane_trace_contract");
+
+function uniqueSorted(values) {
+  return Array.from(new Set((Array.isArray(values) ? values : []).filter(Boolean))).sort();
+}
+
+function buildConversion(entry) {
+  const scenario = entry.scenario || {};
+  const stages = Array.isArray(entry.stages) ? entry.stages : [];
+  return {
+    conversion_id: entry.conversion_id,
+    conversion_label: entry.conversion_label,
+    conversion_posture: entry.conversion_posture,
+    claim_status: "bounded_live",
+    public_first_contact_ready: Boolean(entry.public_first_contact_ready),
+    quote_ready: stages.some((stage) => stage.stage_id === "quote"),
+    revenue_ready: Boolean(entry.revenue_ready),
+    proof_ready: Boolean(entry.proof_ready),
+    operator_inspection_ready: Boolean(entry.operator_inspection_ready),
+    payment_posture: entry.payment_posture,
+    stage_count: stages.length,
+    stages,
+    entrypoint: entry.entrypoint,
+    scenario_ref: scenario.scenario_ref || null,
+    success_signals: Array.isArray(scenario.success_signals) ? scenario.success_signals.slice() : [],
+    supporting_surfaces: uniqueSorted([
+      ...(entry.supporting_surfaces || []),
+      ...(scenario.surfaces || [])
+    ]),
+    claim_boundary: entry.claim_boundary
+  };
+}
+
+function buildFirstRunConversionPack() {
+  const scenarioPack = buildScenarioPack();
+  const scenarios = Array.isArray(scenarioPack.scenarios) ? scenarioPack.scenarios : [];
+  const x402Summary = summarizeX402LanePack();
+  const providerJourneySummary = summarizeProviderRuntimeJourneyPack();
+  const traceSummary = summarizeMarketLaneTracePack();
+
+  const directPayScenario = scenarios.find((entry) => entry && entry.scenario_ref === "scenario.direct_pay.trust_verify") || {};
+  const creditsScenario = scenarios.find((entry) => entry && entry.scenario_ref === "scenario.credits_first.repeat_run") || {};
+  const proofScenario = scenarios.find((entry) => entry && entry.scenario_ref === "scenario.runtime_to_proof.followthrough") || {};
+
+  const conversions = [
+    buildConversion({
+      conversion_id: "direct_x402_paid_proof",
+      conversion_label: "direct x402 paid proof",
+      conversion_posture: "quote_to_direct_pay_execute_and_proof_pickup",
+      public_first_contact_ready: true,
+      revenue_ready: true,
+      proof_ready: true,
+      operator_inspection_ready: true,
+      payment_posture: "direct_x402",
+      entrypoint: "xytara first-run --run-quote --account ACCOUNT_REF --pretty",
+      scenario: directPayScenario,
+      stages: [
+        {
+          stage_index: 1,
+          stage_id: "discover",
+          posture: "inspect_machine_payment_lane",
+          surface_ref: "/v1/x402/summary",
+          expected_outcome: "confirm the default machine-payment lane and bounded x402 posture before quoting"
+        },
+        {
+          stage_index: 2,
+          stage_id: "quote",
+          posture: "secretless_first_contact_quote",
+          surface_ref: "xytara first-run --run-quote --account ACCOUNT_REF --pretty",
+          expected_outcome: "produce a payment-required challenge without spending funds or requiring wallet secrets"
+        },
+        {
+          stage_index: 3,
+          stage_id: "fund",
+          posture: "pay_admission_after_quote",
+          surface_ref: "/x402/commands/execute",
+          expected_outcome: "replay the quoted request through the machine-payment lane with approved payment proof"
+        },
+        {
+          stage_index: 4,
+          stage_id: "execute",
+          posture: "bounded_paid_runtime_execution",
+          surface_ref: "/x402/commands/execute",
+          expected_outcome: "execute the paid runtime call and receive transaction, payment, and delivery continuity"
+        },
+        {
+          stage_index: 5,
+          stage_id: "prove",
+          posture: "result_package_proof_pickup",
+          surface_ref: "https://xoonya.onrender.com/v1/proof-center/result-package-handoff/summary",
+          expected_outcome: "pick up result-package proof followthrough instead of ending at runtime output"
+        },
+        {
+          stage_index: 6,
+          stage_id: "inspect",
+          posture: "operator_and_builder_inspection",
+          surface_ref: "/v1/payment-ledger",
+          expected_outcome: "inspect payment ledger and settlement-linked runtime consequence after the paid call completes"
+        }
+      ],
+      supporting_surfaces: [
+        "/v1/settlement/bsv-teranode",
+        "/v1/transaction-center/result-packages/export-template",
+        "https://xoonya.onrender.com/v1/proof-center/result-package-handoff/review/summary"
+      ],
+      claim_boundary: "claim_direct_x402_first_run_conversion_only_for_the_listed_quote_pay_execute_proof_and_inspection_surfaces_not_as_unbounded_payment_or_custody_control"
+    }),
+    buildConversion({
+      conversion_id: "credits_first_paid_proof",
+      conversion_label: "credits-first paid proof",
+      conversion_posture: "quote_to_credits_execute_and_proof_pickup",
+      public_first_contact_ready: true,
+      revenue_ready: true,
+      proof_ready: true,
+      operator_inspection_ready: true,
+      payment_posture: "credits_first",
+      entrypoint: "xytara first-run --execute-with-credits --account ACCOUNT_REF --pretty",
+      scenario: creditsScenario,
+      stages: [
+        {
+          stage_index: 1,
+          stage_id: "discover",
+          posture: "inspect_repeat_use_path",
+          surface_ref: "/v1/release-pack/scenarios/summary",
+          expected_outcome: "confirm the repeat-use credits-first path before funding or execution"
+        },
+        {
+          stage_index: 2,
+          stage_id: "quote",
+          posture: "secretless_first_contact_quote",
+          surface_ref: "xytara first-run --run-quote --account ACCOUNT_REF --pretty",
+          expected_outcome: "establish pricing and admission posture before switching to funded credits-first execution"
+        },
+        {
+          stage_index: 3,
+          stage_id: "fund",
+          posture: "approved_credit_funding",
+          surface_ref: "/v1/credit-packs/summary",
+          expected_outcome: "fund repeat-use credits through an approved money-in path without changing the public execution surface"
+        },
+        {
+          stage_index: 4,
+          stage_id: "execute",
+          posture: "bounded_credits_first_runtime_execution",
+          surface_ref: "/v1/commands/execute",
+          expected_outcome: "reuse the governed runtime surface with payment_preference=credits_first on a funded account"
+        },
+        {
+          stage_index: 5,
+          stage_id: "prove",
+          posture: "result_package_proof_pickup",
+          surface_ref: "https://xoonya.onrender.com/v1/proof-center/result-package-handoff/review/summary",
+          expected_outcome: "continue the funded execution into proof-side review and handoff verification"
+        },
+        {
+          stage_index: 6,
+          stage_id: "inspect",
+          posture: "repeat_use_account_inspection",
+          surface_ref: "/v1/economics/accounts/:account_id/usage-meters",
+          expected_outcome: "inspect repeat-use spend, usage meters, and entitlement continuity after the funded execution"
+        }
+      ],
+      supporting_surfaces: [
+        "/v1/economics/accounts/:account_id/entitlements",
+        "/v1/economics/accounts/:account_id/credit-balance",
+        "/v1/transaction-center/result-packages/export-template"
+      ],
+      claim_boundary: "claim_credits_first_conversion_only_for_the_listed_funded_account_runtime_and_proof_followthrough_surfaces_not_as_hidden_money_in_or_global_credit_truth"
+    }),
+    buildConversion({
+      conversion_id: "result_package_proof_pickup",
+      conversion_label: "result-package proof pickup",
+      conversion_posture: "runtime_delivery_into_xoonya_review_and_run",
+      public_first_contact_ready: false,
+      revenue_ready: false,
+      proof_ready: true,
+      operator_inspection_ready: true,
+      payment_posture: "carried_from_prior_paid_execution",
+      entrypoint: "POST /v1/transaction-center/result-packages/export",
+      scenario: proofScenario,
+      stages: [
+        {
+          stage_index: 1,
+          stage_id: "discover",
+          posture: "inspect_result_package_followthrough",
+          surface_ref: "/v1/transaction-center/result-packages/summary",
+          expected_outcome: "discover the result-package surface that keeps runtime output proof-ready"
+        },
+        {
+          stage_index: 2,
+          stage_id: "execute",
+          posture: "carry_forward_prior_paid_runtime_result",
+          surface_ref: "/v1/transaction-center/transaction-class-packs/run",
+          expected_outcome: "carry a paid runtime result into the governed result-package export and continuation path"
+        },
+        {
+          stage_index: 3,
+          stage_id: "deliver",
+          posture: "export_portable_handoff_bundle",
+          surface_ref: "/v1/transaction-center/result-packages/export-template",
+          expected_outcome: "export a portable handoff bundle that is ready for proof-side review and run"
+        },
+        {
+          stage_index: 4,
+          stage_id: "prove",
+          posture: "xoonya_review_and_run",
+          surface_ref: "https://xoonya.onrender.com/v1/proof-center/result-package-handoff/run",
+          expected_outcome: "continue the result package into xoonya proof review and deterministic run surfaces"
+        },
+        {
+          stage_index: 5,
+          stage_id: "inspect",
+          posture: "proof_service_and_bridge_inspection",
+          surface_ref: "https://xoonya.onrender.com/v1/proof-center/verification-services/summary",
+          expected_outcome: "inspect the proof-facing service posture that completes the runtime-to-proof conversion path"
+        }
+      ],
+      supporting_surfaces: [
+        "https://xoonya.onrender.com/v1/proof-center/result-package-handoff/summary",
+        "https://xoonya.onrender.com/v1/proof-center/result-package-handoff/review/summary"
+      ],
+      claim_boundary: "claim_result_package_proof_pickup_only_for_the_listed_runtime_export_handoff_review_and_run_surfaces_not_as_generic_external_proof_or_settlement_truth"
+    })
+  ];
+
+  return {
+    ok: true,
+    product: "xytara",
+    category: "machine-commerce-first-run-conversion-pack",
+    pack_version: "xytara-first-run-conversion-pack-v1",
+    posture: "launch_grade_quote_fund_execute_proof_conversion_paths",
+    doctrine: "first_run_conversion_paths_make_public_discovery_revenue_and_proof_followthrough_stories_machine_readable_before_go_to_market_claims",
+    conversion_count: conversions.length,
+    public_first_contact_ready_count: conversions.filter((entry) => entry.public_first_contact_ready).length,
+    revenue_ready_conversion_count: conversions.filter((entry) => entry.revenue_ready).length,
+    proof_ready_conversion_count: conversions.filter((entry) => entry.proof_ready).length,
+    operator_inspection_ready_count: conversions.filter((entry) => entry.operator_inspection_ready).length,
+    stage_total_count: conversions.reduce((total, entry) => total + Number(entry.stage_count || 0), 0),
+    linked_runtime_counts: {
+      x402_first_run_flow_count: Number(x402Summary.first_run_flow_count || 0),
+      provider_runtime_journey_count: Number(providerJourneySummary.journey_count || 0),
+      market_lane_trace_count: Number(traceSummary.market_lane_trace_count || 0)
+    },
+    conversions,
+    linked_surfaces: {
+      x402_lane_summary_ref: "/v1/x402/summary",
+      providers_summary_ref: "/v1/providers/summary",
+      provider_journeys_summary_ref: "/v1/providers/journeys/summary",
+      release_scenarios_summary_ref: "/v1/release-pack/scenarios/summary",
+      result_packages_summary_ref: "/v1/transaction-center/result-packages/summary",
+      result_package_export_template_ref: "/v1/transaction-center/result-packages/export-template",
+      xoonya_result_package_handoff_summary_ref: "https://xoonya.onrender.com/v1/proof-center/result-package-handoff/summary",
+      xoonya_result_package_review_summary_ref: "https://xoonya.onrender.com/v1/proof-center/result-package-handoff/review/summary",
+      xoonya_verification_services_summary_ref: "https://xoonya.onrender.com/v1/proof-center/verification-services/summary"
+    }
+  };
+}
+
+function summarizeFirstRunConversionPack() {
+  const pack = buildFirstRunConversionPack();
+  return {
+    ok: true,
+    product: pack.product,
+    category: "machine-commerce-first-run-conversion-summary",
+    summary_version: "xytara-first-run-conversion-summary-v1",
+    conversion_count: pack.conversion_count,
+    public_first_contact_ready_count: pack.public_first_contact_ready_count,
+    revenue_ready_conversion_count: pack.revenue_ready_conversion_count,
+    proof_ready_conversion_count: pack.proof_ready_conversion_count,
+    operator_inspection_ready_count: pack.operator_inspection_ready_count,
+    stage_total_count: pack.stage_total_count,
+    linked_surfaces: pack.linked_surfaces
+  };
+}
+
+function getFirstRunConversionDetail(conversionId) {
+  const normalized = String(conversionId || "").trim().toLowerCase();
+  return (buildFirstRunConversionPack().conversions || []).find((entry) => entry.conversion_id === normalized) || null;
+}
+
+module.exports = {
+  buildFirstRunConversionPack,
+  summarizeFirstRunConversionPack,
+  getFirstRunConversionDetail
+};