xoonya 1.7.0 → 1.9.0

package/README.md

@@ -34,6 +34,12 @@ The current `1.7.0` companion slice adds a lightweight transaction proof-handoff
 - a direct handoff run path that turns transaction-side proof handoff data into a proof-native bundle
 - summary helpers that make the recommended proof follow-through explicit without widening proof scope
 
+The current `1.8.0` companion slice extends that same proof-side carry to richer grouped interaction spine handoffs:
+
+- an interaction-spine handoff center and summary surface
+- a direct interaction-spine handoff run path for composed transaction spines
+- proof-side summaries that preserve both pre-commit and committed-ref context without importing commerce logic
+
 ## Proof Model
 
 The primary proof model is layered:
@@ -122,6 +128,9 @@ Primary proof-model routes:
 - `GET /v1/proof-center/transaction-handoff`
 - `GET /v1/proof-center/transaction-handoff/summary`
 - `POST /v1/proof-center/transaction-handoff/run`
+- `GET /v1/proof-center/result-package-handoff`
+- `GET /v1/proof-center/result-package-handoff/summary`
+- `POST /v1/proof-center/result-package-handoff/run`
 - `POST /v1/events/canonicalize`
 - `POST /v1/events/hash`
 - `POST /v1/receipts/emit`

package/package.json

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

package/proof_sdk.js

@@ -895,6 +895,48 @@ function buildTransactionProofHandoffCenter() {
   };
 }
 
+function buildInteractionSpineProofHandoffCenter() {
+  return {
+    ok: true,
+    brand: "xoonya",
+    product: "interaction spine proof handoff center",
+    supported_source_refs: [
+      "spine.a2a.settlement",
+      "spine.a2c.tooling",
+      "spine.job.commitment"
+    ],
+    required_fields: ["transaction_id", "receipt_id", "proof_ref", "source_ref"],
+    optional_fields: ["task_refs", "delivery_count", "payment_ledger_count", "committed_ref", "precommit_pack_ref"],
+    recommended_loop: "default.proof.bundle.loop"
+  };
+}
+
+function buildInteractionResultPackageHandoffCenter() {
+  return {
+    ok: true,
+    brand: "xoonya",
+    product: "interaction result package handoff center",
+    supported_source_refs: [
+      "result.spine.a2a.settlement",
+      "result.spine.a2c.tooling",
+      "result.spine.job.commitment"
+    ],
+    required_fields: ["result_package_ref", "source_ref", "transaction_id", "receipt_id", "proof_ref"],
+    optional_fields: [
+      "committed_ref",
+      "precommit_pack_ref",
+      "payment_protocol",
+      "settlement_mode",
+      "treasury_destination_id",
+      "task_refs",
+      "delivery_count",
+      "payment_ledger_count",
+      "seam_layers"
+    ],
+    recommended_loop: "default.proof.bundle.loop"
+  };
+}
+
 function summarizeTransactionProofHandoffCenter() {
   const center = buildTransactionProofHandoffCenter();
   return {
@@ -909,6 +951,34 @@ function summarizeTransactionProofHandoffCenter() {
   };
 }
 
+function summarizeInteractionSpineProofHandoffCenter() {
+  const center = buildInteractionSpineProofHandoffCenter();
+  return {
+    ok: true,
+    brand: center.brand,
+    product: center.product,
+    source_ref_count: Array.isArray(center.supported_source_refs) ? center.supported_source_refs.length : 0,
+    supported_source_refs: center.supported_source_refs,
+    required_field_count: Array.isArray(center.required_fields) ? center.required_fields.length : 0,
+    required_fields: center.required_fields,
+    recommended_loop: center.recommended_loop
+  };
+}
+
+function summarizeInteractionResultPackageHandoffCenter() {
+  const center = buildInteractionResultPackageHandoffCenter();
+  return {
+    ok: true,
+    brand: center.brand,
+    product: center.product,
+    source_ref_count: Array.isArray(center.supported_source_refs) ? center.supported_source_refs.length : 0,
+    supported_source_refs: center.supported_source_refs,
+    required_field_count: Array.isArray(center.required_fields) ? center.required_fields.length : 0,
+    required_fields: center.required_fields,
+    recommended_loop: center.recommended_loop
+  };
+}
+
 function canonicalizeTransactionProofHandoff(input) {
   const body = input && typeof input === "object" && !Array.isArray(input) ? input : {};
   const handoff = body.handoff_bundle && typeof body.handoff_bundle === "object" && !Array.isArray(body.handoff_bundle)
@@ -935,6 +1005,67 @@ function canonicalizeTransactionProofHandoff(input) {
   };
 }
 
+function canonicalizeInteractionSpineProofHandoff(input) {
+  const handoff = canonicalizeTransactionProofHandoff(input);
+  const body = input && typeof input === "object" && !Array.isArray(input) ? input : {};
+  const sourceRef = normalizeString(handoff.source_ref);
+  const center = buildInteractionSpineProofHandoffCenter();
+  if (!center.supported_source_refs.includes(sourceRef)) {
+    throw new Error("handoff_bundle.source_ref must be a supported interaction spine ref");
+  }
+  const raw = body.handoff_bundle && typeof body.handoff_bundle === "object" && !Array.isArray(body.handoff_bundle)
+    ? body.handoff_bundle
+    : body;
+  const committedRef = normalizeString(raw.committed_ref);
+  const precommitPackRef = normalizeString(raw.precommit_pack_ref);
+  return {
+    ...handoff,
+    committed_ref: committedRef || null,
+    precommit_pack_ref: precommitPackRef || null
+  };
+}
+
+function canonicalizeInteractionResultPackageHandoff(input) {
+  const body = input && typeof input === "object" && !Array.isArray(input) ? input : {};
+  const handoff = body.handoff_bundle && typeof body.handoff_bundle === "object" && !Array.isArray(body.handoff_bundle)
+    ? body.handoff_bundle
+    : body;
+  const resultPackageRef = normalizeString(handoff.result_package_ref);
+  if (!resultPackageRef) throw new Error("handoff_bundle.result_package_ref required");
+  const center = buildInteractionResultPackageHandoffCenter();
+  if (!center.supported_source_refs.includes(resultPackageRef)) {
+    throw new Error("handoff_bundle.result_package_ref must be a supported interaction result package ref");
+  }
+  const sourceRef = normalizeString(handoff.source_ref);
+  if (!sourceRef) throw new Error("handoff_bundle.source_ref required");
+  const transactionId = normalizeString(handoff.transaction_id);
+  const receiptId = normalizeString(handoff.receipt_id);
+  const proofRef = normalizeString(handoff.proof_ref);
+  if (!transactionId) throw new Error("handoff_bundle.transaction_id required");
+  if (!receiptId) throw new Error("handoff_bundle.receipt_id required");
+  if (!proofRef) throw new Error("handoff_bundle.proof_ref required");
+  const taskRefs = normalizeStringArray(handoff.task_refs, "handoff_bundle.task_refs") || [];
+  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;
+  return {
+    result_package_ref: resultPackageRef,
+    source_ref: sourceRef,
+    transaction_id: transactionId,
+    receipt_id: receiptId,
+    proof_ref: proofRef,
+    committed_ref: normalizeString(handoff.committed_ref) || null,
+    precommit_pack_ref: normalizeString(handoff.precommit_pack_ref) || null,
+    payment_protocol: normalizeString(handoff.payment_protocol) || null,
+    settlement_mode: normalizeString(handoff.settlement_mode) || null,
+    treasury_destination_id: normalizeString(handoff.treasury_destination_id) || null,
+    task_refs: taskRefs,
+    delivery_count: deliveryCount,
+    payment_ledger_count: paymentLedgerCount,
+    seam_layers: seamLayers
+  };
+}
+
 function buildTransactionProofHandoffEvent(input) {
   const handoff = canonicalizeTransactionProofHandoff(input);
   const eventHash = canonicalJsonSha256Hex({
@@ -958,6 +1089,61 @@ function buildTransactionProofHandoffEvent(input) {
   });
 }
 
+function buildInteractionSpineProofHandoffEvent(input) {
+  const handoff = canonicalizeInteractionSpineProofHandoff(input);
+  const eventHash = canonicalJsonSha256Hex({
+    source_ref: handoff.source_ref,
+    transaction_id: handoff.transaction_id,
+    receipt_id: handoff.receipt_id,
+    proof_ref: handoff.proof_ref,
+    task_refs: handoff.task_refs,
+    delivery_count: handoff.delivery_count,
+    payment_ledger_count: handoff.payment_ledger_count,
+    committed_ref: handoff.committed_ref,
+    precommit_pack_ref: handoff.precommit_pack_ref
+  });
+  return canonicalizeEvent({
+    version: CANONICAL_EVENT_BUNDLE_VERSION,
+    domain_id: "xytara.interaction_spine_handoff",
+    sequence: handoff.transaction_id,
+    actor_id: "xytara.interaction_spine",
+    adapter_source: "xytara.spine_handoff",
+    event_type: `${handoff.source_ref}.proof_handoff`,
+    event_hash: eventHash,
+    semantic_slots: handoff
+  });
+}
+
+function buildInteractionResultPackageHandoffEvent(input) {
+  const handoff = canonicalizeInteractionResultPackageHandoff(input);
+  const eventHash = canonicalJsonSha256Hex({
+    result_package_ref: handoff.result_package_ref,
+    source_ref: handoff.source_ref,
+    transaction_id: handoff.transaction_id,
+    receipt_id: handoff.receipt_id,
+    proof_ref: handoff.proof_ref,
+    committed_ref: handoff.committed_ref,
+    precommit_pack_ref: handoff.precommit_pack_ref,
+    payment_protocol: handoff.payment_protocol,
+    settlement_mode: handoff.settlement_mode,
+    treasury_destination_id: handoff.treasury_destination_id,
+    task_refs: handoff.task_refs,
+    delivery_count: handoff.delivery_count,
+    payment_ledger_count: handoff.payment_ledger_count,
+    seam_layers: handoff.seam_layers
+  });
+  return canonicalizeEvent({
+    version: CANONICAL_EVENT_BUNDLE_VERSION,
+    domain_id: "xytara.interaction_result_package_handoff",
+    sequence: handoff.transaction_id,
+    actor_id: "xytara.result_package",
+    adapter_source: "xytara.result_package_handoff",
+    event_type: `${handoff.result_package_ref}.proof_handoff`,
+    event_hash: eventHash,
+    semantic_slots: handoff
+  });
+}
+
 function runTransactionProofHandoff(input) {
   const handoff = canonicalizeTransactionProofHandoff(input);
   const event = buildTransactionProofHandoffEvent(input);
@@ -986,6 +1172,67 @@ function runTransactionProofHandoff(input) {
   };
 }
 
+function runInteractionSpineProofHandoff(input) {
+  const handoff = canonicalizeInteractionSpineProofHandoff(input);
+  const event = buildInteractionSpineProofHandoffEvent(input);
+  const options = input && input.options && typeof input.options === "object" && !Array.isArray(input.options)
+    ? input.options
+    : {};
+  const receipt = emitReceipt(event, options);
+  const proofBundle = buildProofBundle({
+    ceb: event,
+    receipt,
+    evidence_refs: Array.isArray(input && input.evidence_refs) ? input.evidence_refs : [handoff.proof_ref],
+    metadata: {
+      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
+    }
+  });
+  return {
+    ok: true,
+    handoff,
+    canonical_event: event,
+    event_commitment: hashEvent(event),
+    receipt,
+    proof_bundle: proofBundle,
+    bundle_verification: verifyProofBundle(proofBundle),
+    recommended_loop: "default.proof.bundle.loop"
+  };
+}
+
+function runInteractionResultPackageHandoff(input) {
+  const handoff = canonicalizeInteractionResultPackageHandoff(input);
+  const event = buildInteractionResultPackageHandoffEvent(input);
+  const options = input && input.options && typeof input.options === "object" && !Array.isArray(input.options)
+    ? input.options
+    : {};
+  const receipt = emitReceipt(event, options);
+  const proofBundle = buildProofBundle({
+    ceb: event,
+    receipt,
+    evidence_refs: Array.isArray(input && input.evidence_refs) ? input.evidence_refs : [handoff.proof_ref],
+    metadata: {
+      handoff_kind: "interaction_result_package_handoff",
+      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
+    }
+  });
+  return {
+    ok: true,
+    handoff,
+    canonical_event: event,
+    event_commitment: hashEvent(event),
+    receipt,
+    proof_bundle: proofBundle,
+    bundle_verification: verifyProofBundle(proofBundle),
+    recommended_loop: "default.proof.bundle.loop"
+  };
+}
+
 function summarizeTransactionProofHandoff(bundle) {
   const item = bundle && typeof bundle === "object" ? bundle : {};
   const handoff = item.handoff && typeof item.handoff === "object" ? item.handoff : {};
@@ -1006,6 +1253,52 @@ function summarizeTransactionProofHandoff(bundle) {
   };
 }
 
+function summarizeInteractionSpineProofHandoff(bundle) {
+  const item = bundle && typeof bundle === "object" ? bundle : {};
+  const handoff = item.handoff && typeof item.handoff === "object" ? item.handoff : {};
+  const receipt = item.receipt && typeof item.receipt === "object" ? item.receipt : {};
+  const proofBundle = item.proof_bundle && typeof item.proof_bundle === "object" ? item.proof_bundle : {};
+  const verification = item.bundle_verification && typeof item.bundle_verification === "object" ? item.bundle_verification : {};
+  return {
+    ok: item.ok === true,
+    source_ref: handoff.source_ref || null,
+    transaction_id: handoff.transaction_id || null,
+    receipt_id: handoff.receipt_id || null,
+    proof_ref: handoff.proof_ref || null,
+    committed_ref: handoff.committed_ref || null,
+    precommit_pack_ref: handoff.precommit_pack_ref || null,
+    task_ref_count: Array.isArray(handoff.task_refs) ? handoff.task_refs.length : 0,
+    proof_bundle_version: proofBundle.version || null,
+    emitted_receipt_id: receipt.receipt_id || null,
+    bundle_valid: verification.valid === true,
+    recommended_loop: item.recommended_loop || null
+  };
+}
+
+function summarizeInteractionResultPackageHandoff(bundle) {
+  const item = bundle && typeof bundle === "object" ? bundle : {};
+  const handoff = item.handoff && typeof item.handoff === "object" ? item.handoff : {};
+  const receipt = item.receipt && typeof item.receipt === "object" ? item.receipt : {};
+  const proofBundle = item.proof_bundle && typeof item.proof_bundle === "object" ? item.proof_bundle : {};
+  const verification = item.bundle_verification && typeof item.bundle_verification === "object" ? item.bundle_verification : {};
+  return {
+    ok: item.ok === true,
+    result_package_ref: handoff.result_package_ref || null,
+    source_ref: handoff.source_ref || null,
+    transaction_id: handoff.transaction_id || null,
+    receipt_id: handoff.receipt_id || null,
+    proof_ref: handoff.proof_ref || null,
+    committed_ref: handoff.committed_ref || null,
+    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,
+    proof_bundle_version: proofBundle.version || null,
+    emitted_receipt_id: receipt.receipt_id || null,
+    bundle_valid: verification.valid === true,
+    recommended_loop: item.recommended_loop || null
+  };
+}
+
 function runDefaultProofLoop(loopRef, input) {
   const loop = getDefaultProofLoop(loopRef);
   if (!loop) {
@@ -1049,15 +1342,27 @@ module.exports = {
   buildDefaultProofCenter,
   buildDefaultProofLoopCatalog,
   buildDefaultProofLoops,
+  buildInteractionResultPackageHandoffCenter,
+  buildInteractionSpineProofHandoffCenter,
   buildTransactionProofHandoffCenter,
+  buildInteractionResultPackageHandoffEvent,
+  buildInteractionSpineProofHandoffEvent,
   buildTransactionProofHandoffEvent,
+  canonicalizeInteractionResultPackageHandoff,
+  canonicalizeInteractionSpineProofHandoff,
   getDefaultProofLoop,
   canonicalizeTransactionProofHandoff,
   runDefaultProofLoop,
+  runInteractionResultPackageHandoff,
+  runInteractionSpineProofHandoff,
   runTransactionProofHandoff,
   summarizeDefaultProofCenter,
   summarizeDefaultProofLoops,
   summarizeGuidedProofLoopBundle,
+  summarizeInteractionResultPackageHandoff,
+  summarizeInteractionResultPackageHandoffCenter,
+  summarizeInteractionSpineProofHandoff,
+  summarizeInteractionSpineProofHandoffCenter,
   summarizeTransactionProofHandoff,
   summarizeTransactionProofHandoffCenter,
   canonicalizeEvent,

package/server.js

@@ -107,6 +107,26 @@ async function routeRequest(req, res) {
     return;
   }
 
+  if (req.method === 'GET' && url.pathname === '/v1/proof-center/interaction-spine-handoff') {
+    sendJson(res, 200, proofSdk.buildInteractionSpineProofHandoffCenter());
+    return;
+  }
+
+  if (req.method === 'GET' && url.pathname === '/v1/proof-center/interaction-spine-handoff/summary') {
+    sendJson(res, 200, proofSdk.summarizeInteractionSpineProofHandoffCenter());
+    return;
+  }
+
+  if (req.method === 'GET' && url.pathname === '/v1/proof-center/result-package-handoff') {
+    sendJson(res, 200, proofSdk.buildInteractionResultPackageHandoffCenter());
+    return;
+  }
+
+  if (req.method === 'GET' && url.pathname === '/v1/proof-center/result-package-handoff/summary') {
+    sendJson(res, 200, proofSdk.summarizeInteractionResultPackageHandoffCenter());
+    return;
+  }
+
   if (req.method === 'GET' && url.pathname === '/v1/proof-center/default-loop') {
     const loop = proofSdk.getDefaultProofLoop(url.searchParams.get('ref'));
     if (!loop) {
@@ -140,6 +160,28 @@ async function routeRequest(req, res) {
     return;
   }
 
+  if (req.method === 'POST' && url.pathname === '/v1/proof-center/interaction-spine-handoff/run') {
+    try {
+      const body = await readJsonBody(req);
+      const result = proofSdk.runInteractionSpineProofHandoff(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/result-package-handoff/run') {
+    try {
+      const body = await readJsonBody(req);
+      const result = proofSdk.runInteractionResultPackageHandoff(body);
+      sendJson(res, 200, result);
+    } catch (error) {
+      sendJson(res, 400, { ok: false, reason: error.message });
+    }
+    return;
+  }
+
   if (req.method === 'POST' && url.pathname === '/v1/receipts/verify') {
     try {
       const body = await readJsonBody(req);