xoonya 1.27.0 → 2.0.0

package/README.md

@@ -37,6 +37,15 @@ The intended production-facing proof path is now:
 
 The rest of this README explains the broader route ladder, but the public starting posture should now be understandable from that one proof-side path.
 
+For explicit runtime-economics carry, the bridge now also accepts a canonical `handoff_bundle` wrapper from `xytara` so the economic consequence seam stays contract-shaped across the two repos instead of being reassembled ad hoc by callers.
+
+That same carried bundle can now also ride inside the normal result-package handoff path:
+
+- if `xytara` sends `handoff_bundle.economic_consequence_handoff_bundle`
+- `xoonya` will validate it through the existing bounded bridge logic
+- normal result-package review and run surfaces will expose compact economic-conformance review data automatically
+- direct-pay or non-metered handoffs remain unaffected
+
 The package and service now also expose a default proof center surface so the intended proof-native path is easy to inspect directly:
 
 - canonical event bundle v1
@@ -118,6 +127,7 @@ The package quickstart demonstrates:
 - proof bundle construction
 - proof bundle verification
 - transaction proof-handoff follow-through
+- proof-side bridge carry for explicit economic consequence review when runtime economics need proof-adjacent preservation
 
 ## Service Quickstart
 
@@ -179,6 +189,8 @@ Primary proof-model routes:
 - `POST /v1/proof-center/bridge/receipt-wrap`
 - `POST /v1/proof-center/bridge/validator-verify`
 - `POST /v1/proof-center/bridge/receipt-ledger-handoff`
+- `POST /v1/proof-center/bridge/economic-handoff`
+- `POST /v1/proof-center/bridge/economic-conformance-pack`
 - `POST /v1/proof-center/bridge/operator-review-pack`
 - `POST /v1/proof-center/bridge/compatibility-pack`
 - `POST /v1/proof-center/bridge/workflow-pack`

package/SERVICE_CONTRACT.md

@@ -33,6 +33,8 @@ Primary proof-model routes:
 - `POST /v1/proof-center/bridge/receipt-wrap`
 - `POST /v1/proof-center/bridge/validator-verify`
 - `POST /v1/proof-center/bridge/receipt-ledger-handoff`
+- `POST /v1/proof-center/bridge/economic-handoff`
+- `POST /v1/proof-center/bridge/economic-conformance-pack`
 - `POST /v1/proof-center/bridge/operator-review-pack`
 - `POST /v1/proof-center/bridge/compatibility-pack`
 - `POST /v1/proof-center/bridge/workflow-pack`
@@ -81,6 +83,20 @@ The constitutional proof loop for `xoonya` is:
 4. build proof bundle
 5. verify proof bundle
 
+Bridge-side economic carry should use:
+
+1. pass deterministic runtime economics through `POST /v1/proof-center/bridge/economic-handoff`
+2. prefer the canonical `handoff_bundle` wrapper emitted by `xytara`
+3. review the preserved usage-meter and credit-spend consequence through `POST /v1/proof-center/bridge/economic-conformance-pack`
+4. keep proof itself minimal while preserving the economic handoff as a bounded bridge/export surface
+
+Normal result-package handoff should also accept carried economics when present:
+
+1. send the normal result-package `handoff_bundle`
+2. include `handoff_bundle.economic_consequence_handoff_bundle` when the transaction-side path was credit-backed and metered
+3. expect `POST /v1/proof-center/result-package-handoff/run` and review-summary surfaces to expose compact economic-conformance review data automatically
+4. omit that bundle entirely on direct-pay or non-metered paths without changing proof intake behavior
+
 This loop is exercised through:
 
 - package verification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xoonya",
-  "version": "1.27.0",
+  "version": "2.0.0",
   "description": "Deterministic proof SDK for canonical events, receipts, proof bundles, and verification.",
   "main": "index.js",
   "type": "commonjs",

package/proof_sdk.js

@@ -1048,6 +1048,7 @@ function canonicalizeInteractionResultPackageHandoff(input) {
   const seamLayers = normalizeStringArray(handoff.seam_layers, "handoff_bundle.seam_layers") || [];
   const deliveryCount = Number.isFinite(Number(handoff.delivery_count)) ? Number(handoff.delivery_count) : 0;
   const paymentLedgerCount = Number.isFinite(Number(handoff.payment_ledger_count)) ? Number(handoff.payment_ledger_count) : 0;
+  const economicCarry = extractEconomicConsequenceCarry(handoff);
   return {
     result_package_ref: resultPackageRef,
     source_ref: sourceRef,
@@ -1062,7 +1063,39 @@ function canonicalizeInteractionResultPackageHandoff(input) {
     task_refs: taskRefs,
     delivery_count: deliveryCount,
     payment_ledger_count: paymentLedgerCount,
-    seam_layers: seamLayers
+    seam_layers: seamLayers,
+    economic_consequence_handoff_bundle: economicCarry.handoff_bundle,
+    economic_consequence_review: economicCarry.review
+  };
+}
+
+function extractEconomicConsequenceCarry(handoff) {
+  const bundle = handoff && handoff.economic_consequence_handoff_bundle && typeof handoff.economic_consequence_handoff_bundle === "object" && !Array.isArray(handoff.economic_consequence_handoff_bundle)
+    ? handoff.economic_consequence_handoff_bundle
+    : null;
+  if (!bundle) {
+    return {
+      handoff_bundle: null,
+      review: null
+    };
+  }
+  const conformance = buildEconomicConsequenceConformancePack({
+    handoff_bundle: bundle
+  });
+  return {
+    handoff_bundle: bundle,
+    review: {
+      detected: true,
+      conformance_pack_ref: conformance.conformance_pack_ref,
+      account_ref: conformance.deterministic_consequence.account_ref,
+      usage_meter_ref: conformance.deterministic_consequence.usage_meter_ref,
+      credit_spend_ref: conformance.deterministic_consequence.credit_spend_ref,
+      usage_units: conformance.deterministic_consequence.usage_units,
+      pricing_band: conformance.deterministic_consequence.pricing_band,
+      meter_profile_ref: conformance.deterministic_consequence.meter_profile_ref,
+      next_surface: conformance.next_surface,
+      review_summary_surface: conformance.review_summary_surface
+    }
   };
 }
 
@@ -1130,7 +1163,10 @@ function buildInteractionResultPackageHandoffEvent(input) {
     task_refs: handoff.task_refs,
     delivery_count: handoff.delivery_count,
     payment_ledger_count: handoff.payment_ledger_count,
-    seam_layers: handoff.seam_layers
+    seam_layers: handoff.seam_layers,
+    economic_consequence_ref: handoff.economic_consequence_review
+      ? handoff.economic_consequence_review.conformance_pack_ref
+      : null
   });
   return canonicalizeEvent({
     version: CANONICAL_EVENT_BUNDLE_VERSION,
@@ -1187,7 +1223,10 @@ function runInteractionSpineProofHandoff(input) {
       handoff_kind: "interaction_spine_proof_handoff",
       source_ref: handoff.source_ref,
       committed_ref: handoff.committed_ref || null,
-      precommit_pack_ref: handoff.precommit_pack_ref || null
+      precommit_pack_ref: handoff.precommit_pack_ref || null,
+      economic_consequence_ref: handoff.economic_consequence_review
+        ? handoff.economic_consequence_review.conformance_pack_ref
+        : null
     }
   });
   return {
@@ -1198,6 +1237,7 @@ function runInteractionSpineProofHandoff(input) {
     receipt,
     proof_bundle: proofBundle,
     bundle_verification: verifyProofBundle(proofBundle),
+    economic_consequence_review: handoff.economic_consequence_review || null,
     recommended_loop: "default.proof.bundle.loop"
   };
 }
@@ -1218,7 +1258,10 @@ function runInteractionResultPackageHandoff(input) {
       result_package_ref: handoff.result_package_ref,
       source_ref: handoff.source_ref,
       committed_ref: handoff.committed_ref || null,
-      precommit_pack_ref: handoff.precommit_pack_ref || null
+      precommit_pack_ref: handoff.precommit_pack_ref || null,
+      economic_consequence_ref: handoff.economic_consequence_review
+        ? handoff.economic_consequence_review.conformance_pack_ref
+        : null
     }
   });
   return {
@@ -1229,6 +1272,7 @@ function runInteractionResultPackageHandoff(input) {
     receipt,
     proof_bundle: proofBundle,
     bundle_verification: verifyProofBundle(proofBundle),
+    economic_consequence_review: handoff.economic_consequence_review || null,
     recommended_loop: "default.proof.bundle.loop"
   };
 }
@@ -1292,6 +1336,9 @@ function summarizeInteractionResultPackageHandoff(bundle) {
     precommit_pack_ref: handoff.precommit_pack_ref || null,
     seam_layer_count: Array.isArray(handoff.seam_layers) ? handoff.seam_layers.length : 0,
     task_ref_count: Array.isArray(handoff.task_refs) ? handoff.task_refs.length : 0,
+    economic_consequence_ready: Boolean(handoff.economic_consequence_review),
+    usage_meter_ref: handoff.economic_consequence_review ? handoff.economic_consequence_review.usage_meter_ref : null,
+    credit_spend_ref: handoff.economic_consequence_review ? handoff.economic_consequence_review.credit_spend_ref : null,
     proof_bundle_version: proofBundle.version || null,
     emitted_receipt_id: receipt.receipt_id || null,
     bundle_valid: verification.valid === true,
@@ -1328,7 +1375,8 @@ function reviewInteractionResultPackageHandoff(input) {
         economic_state: {
           payment_protocol: handoff.payment_protocol || null,
           settlement_mode: handoff.settlement_mode || null,
-          treasury_destination_id: handoff.treasury_destination_id || null
+          treasury_destination_id: handoff.treasury_destination_id || null,
+          economic_consequence_review: handoff.economic_consequence_review || null
         },
         proof_handoff: {
           source_ref: handoff.source_ref || null,
@@ -1339,6 +1387,7 @@ function reviewInteractionResultPackageHandoff(input) {
       run_ready: Boolean(handoff.transaction_id && handoff.receipt_id && handoff.proof_ref),
       next_surface: "/v1/proof-center/result-package-handoff/run"
     },
+    economic_consequence_review: handoff.economic_consequence_review || null,
     recommended_loop: "default.proof.bundle.loop",
     next_surface: "/v1/proof-center/result-package-handoff/run"
   };
@@ -1359,7 +1408,11 @@ function summarizeReviewedInteractionResultPackageHandoff(input) {
     review_ref: durability.review_ref || null,
     run_ready: durability.run_ready === true,
     next_surface: durability.next_surface || review.next_surface || null,
-    preserved_seam_layer_count: Number(proofHandoff.seam_layer_count || 0)
+    preserved_seam_layer_count: Number(proofHandoff.seam_layer_count || 0),
+    economic_consequence_ready: Boolean(review.economic_consequence_review),
+    usage_meter_ref: review.economic_consequence_review ? review.economic_consequence_review.usage_meter_ref : null,
+    credit_spend_ref: review.economic_consequence_review ? review.economic_consequence_review.credit_spend_ref : null,
+    economic_consequence_review: review.economic_consequence_review || null
   };
 }
 
@@ -1991,6 +2044,8 @@ function buildBridgeCenter() {
     receipt_wrap_surface: "/v1/proof-center/bridge/receipt-wrap",
     validator_verify_surface: "/v1/proof-center/bridge/validator-verify",
     receipt_ledger_handoff_surface: "/v1/proof-center/bridge/receipt-ledger-handoff",
+    economic_handoff_surface: "/v1/proof-center/bridge/economic-handoff",
+    economic_conformance_pack_surface: "/v1/proof-center/bridge/economic-conformance-pack",
     operator_review_pack_surface: "/v1/proof-center/bridge/operator-review-pack",
     compatibility_pack_surface: "/v1/proof-center/bridge/compatibility-pack",
     supported_profiles: [
@@ -2002,6 +2057,8 @@ function buildBridgeCenter() {
       "receipt_wrap",
       "validator_compatible_verification",
       "receipt_ledger_handoff",
+      "economic_consequence_handoff",
+      "economic_consequence_conformance",
       "operator_review_packaging",
       "compatibility_packaging",
       "profile_carry"
@@ -2016,6 +2073,7 @@ function summarizeBridgeCenter() {
     capability_count: center.supported_capabilities.length,
     profile_count: center.supported_profiles.length,
     receipt_ledger_handoff_surface: center.receipt_ledger_handoff_surface,
+    economic_handoff_surface: center.economic_handoff_surface,
     operator_review_pack_surface: center.operator_review_pack_surface
   };
 }
@@ -2066,6 +2124,14 @@ function summarizeBridgeValidatorVerify(input) {
   };
 }
 
+function unwrapEconomicBridgeInput(input) {
+  const body = normalizeBridgeInput(input);
+  if (body.handoff_bundle && typeof body.handoff_bundle === "object" && !Array.isArray(body.handoff_bundle)) {
+    return body.handoff_bundle;
+  }
+  return body;
+}
+
 function buildReceiptLedgerBridgeHandoff(input) {
   const body = normalizeBridgeInput(input);
   const receiptRef = normalizeString(body.receipt_ref);
@@ -2146,6 +2212,84 @@ function buildReceiptLedgerBridgeHandoff(input) {
   };
 }
 
+function buildEconomicConsequenceBridgeHandoff(input) {
+  const body = unwrapEconomicBridgeInput(input);
+  const accountRef = normalizeString(body.account_ref);
+  const usageMeterRef = normalizeString(body.usage_meter_ref);
+  const meterProfileRef = normalizeString(body.meter_profile_ref);
+  const creditSpendRef = normalizeString(body.credit_spend_ref);
+  const usageMeter = body.usage_meter && typeof body.usage_meter === "object" && !Array.isArray(body.usage_meter)
+    ? body.usage_meter
+    : null;
+  const creditSpend = body.credit_spend && typeof body.credit_spend === "object" && !Array.isArray(body.credit_spend)
+    ? body.credit_spend
+    : null;
+  if (!accountRef) throw new Error("account_ref_required");
+  if (!usageMeterRef) throw new Error("usage_meter_ref_required");
+  if (!meterProfileRef) throw new Error("meter_profile_ref_required");
+  if (!creditSpendRef) throw new Error("credit_spend_ref_required");
+  if (!usageMeter) throw new Error("usage_meter_required");
+  if (!creditSpend) throw new Error("credit_spend_required");
+  if (usageMeter.account_id && normalizeString(usageMeter.account_id) !== accountRef) throw new Error("usage_meter_account_mismatch");
+  if (creditSpend.account_id && normalizeString(creditSpend.account_id) !== accountRef) throw new Error("credit_spend_account_mismatch");
+  if (usageMeter.credit_spend_id && normalizeString(usageMeter.credit_spend_id) !== creditSpendRef) throw new Error("usage_meter_credit_spend_mismatch");
+  if (creditSpend.credit_spend_id && normalizeString(creditSpend.credit_spend_id) !== creditSpendRef) throw new Error("credit_spend_ref_mismatch");
+  if (usageMeter.units != null && creditSpend.units != null && Number(usageMeter.units) !== Number(creditSpend.units)) {
+    throw new Error("usage_meter_units_mismatch");
+  }
+  const handoff = {
+    mode: "xoonya-economic-consequence-handoff-v1",
+    generated_at_iso: new Date().toISOString(),
+    economics_context: {
+      target_system: "xytara",
+      account_ref: accountRef,
+      usage_meter_ref: usageMeterRef,
+      usage_meter_hash: canonicalJsonSha256Hex(usageMeter),
+      usage_meter: usageMeter,
+      meter_profile_ref: meterProfileRef,
+      credit_spend_ref: creditSpendRef,
+      credit_spend_hash: canonicalJsonSha256Hex(creditSpend),
+      credit_spend: creditSpend
+    }
+  };
+  return {
+    ok: true,
+    handoff_ref: buildBridgeRef("bridge.economic-consequence-handoff", handoff),
+    handoff,
+    next_surface: "/v1/proof-center/governance/interpretation-validate",
+    review_summary_surface: "/v1/proof-center/result-package-handoff/review/summary"
+  };
+}
+
+function buildEconomicConsequenceConformancePack(input) {
+  const handoffBundle = buildEconomicConsequenceBridgeHandoff(input);
+  const economicsContext = handoffBundle.handoff.economics_context;
+  return {
+    ok: true,
+    conformance_pack_ref: buildBridgeRef("bridge.economic-conformance-pack", {
+      usage_meter_ref: economicsContext.usage_meter_ref,
+      credit_spend_ref: economicsContext.credit_spend_ref,
+      account_ref: economicsContext.account_ref
+    }),
+    deterministic_consequence: {
+      account_ref: economicsContext.account_ref,
+      usage_meter_ref: economicsContext.usage_meter_ref,
+      credit_spend_ref: economicsContext.credit_spend_ref,
+      usage_units: Number(economicsContext.usage_meter.units || 0),
+      pricing_band: normalizeString(economicsContext.usage_meter.pricing_band || null) || null,
+      meter_profile_ref: economicsContext.meter_profile_ref
+    },
+    preserved_routes: [
+      "/v1/proof-center/bridge/economic-handoff",
+      "/v1/proof-center/bridge/economic-conformance-pack",
+      "/v1/proof-center/governance/interpretation-validate",
+      "/v1/proof-center/result-package-handoff/review/summary"
+    ],
+    next_surface: "/v1/proof-center/governance/interpretation-validate",
+    review_summary_surface: "/v1/proof-center/result-package-handoff/review/summary"
+  };
+}
+
 function buildBridgeOperatorReviewPack(input) {
   const body = normalizeBridgeInput(input);
   const sourceRef = normalizeString(body.source_ref || body.receipt_ref || "proof-bridge.source");
@@ -2160,12 +2304,15 @@ function buildBridgeOperatorReviewPack(input) {
     included_sections: [
       "bridge_summary",
       "validator_verification",
+      "economic_consequence_review",
       "profile_carry",
       "governance_review_link",
       "proof_run_link"
     ],
     bridge_summary_surface: "/v1/proof-center/bridge/summary",
     validator_verify_surface: "/v1/proof-center/bridge/validator-verify",
+    economic_handoff_surface: "/v1/proof-center/bridge/economic-handoff",
+    economic_conformance_pack_surface: "/v1/proof-center/bridge/economic-conformance-pack",
     compatibility_pack_surface: "/v1/proof-center/bridge/compatibility-pack",
     governance_review_link_surface: "/v1/proof-center/governance/review-link",
     proof_run_surface: "/v1/proof-center/result-package-handoff/run"
@@ -2250,6 +2397,7 @@ function buildBridgeWorkflowPack(input) {
     workflow_steps: [
       "receipt_wrap_or_receive",
       "validator_verify",
+      "economic_consequence_handoff",
       "inspect_profile_support",
       "review_operator_pack",
       "handoff_or_run"
@@ -2273,7 +2421,9 @@ function buildBridgeAdminPack(input) {
     operator_refs: {
       workflow_pack_ref: workflowPack.workflow_pack_ref,
       operator_review_pack_ref: workflowPack.refs.operator_review_pack_ref,
-      compatibility_pack_ref: workflowPack.refs.compatibility_pack_ref
+      compatibility_pack_ref: workflowPack.refs.compatibility_pack_ref,
+      economic_handoff_surface: "/v1/proof-center/bridge/economic-handoff",
+      economic_conformance_pack_surface: "/v1/proof-center/bridge/economic-conformance-pack"
     },
     governance_refs: {
       governance_dashboard_surface: "/v1/proof-center/governance/dashboard",
@@ -2678,6 +2828,8 @@ module.exports = {
   buildBridgeReceiptWrap,
   summarizeBridgeValidatorVerify,
   buildReceiptLedgerBridgeHandoff,
+  buildEconomicConsequenceBridgeHandoff,
+  buildEconomicConsequenceConformancePack,
   buildBridgeOperatorReviewPack,
   buildBridgeCompatibilityPack,
   buildBridgeProfileSupport,

package/server.js

@@ -894,6 +894,28 @@ async function routeRequest(req, res) {
     return;
   }
 
+  if (req.method === 'POST' && url.pathname === '/v1/proof-center/bridge/economic-handoff') {
+    try {
+      const body = await readJsonBody(req);
+      const result = proofSdk.buildEconomicConsequenceBridgeHandoff(body);
+      sendJson(res, 200, result);
+    } catch (error) {
+      sendJson(res, 400, { ok: false, reason: error.message });
+    }
+    return;
+  }
+
+  if (req.method === 'POST' && url.pathname === '/v1/proof-center/bridge/economic-conformance-pack') {
+    try {
+      const body = await readJsonBody(req);
+      const result = proofSdk.buildEconomicConsequenceConformancePack(body);
+      sendJson(res, 200, result);
+    } catch (error) {
+      sendJson(res, 400, { ok: false, reason: error.message });
+    }
+    return;
+  }
+
   if (req.method === 'POST' && url.pathname === '/v1/proof-center/bridge/operator-review-pack') {
     try {
       const body = await readJsonBody(req);