xoonya 1.6.0 → 1.8.0

package/README.md

@@ -28,6 +28,18 @@ The current `1.6.0` companion slice adds guided default proof loops on top of th
 
 This keeps `xoonya` narrow while making the intended proof path easier to inspect alongside the newer guided transaction-loop work in `xytara`.
 
+The current `1.7.0` companion slice adds a lightweight transaction proof-handoff surface:
+
+- a transaction proof-handoff center that states the expected handoff contract
+- 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:
@@ -80,6 +92,7 @@ The package quickstart demonstrates:
 - canonical receipt emission
 - proof bundle construction
 - proof bundle verification
+- transaction proof-handoff follow-through
 
 ## Service Quickstart
 
@@ -106,6 +119,15 @@ Environment example:
 Primary proof-model routes:
 
 - `GET /health`
+- `GET /v1/proof-center`
+- `GET /v1/proof-center/summary`
+- `GET /v1/proof-center/default-loops`
+- `GET /v1/proof-center/default-loops/summary`
+- `GET /v1/proof-center/default-loop`
+- `POST /v1/proof-center/default-loops/run`
+- `GET /v1/proof-center/transaction-handoff`
+- `GET /v1/proof-center/transaction-handoff/summary`
+- `POST /v1/proof-center/transaction-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.6.0",
+  "version": "1.8.0",
   "description": "Deterministic proof SDK for canonical events, receipts, proof bundles, and verification.",
   "main": "index.js",
   "type": "commonjs",

package/proof_sdk.js

@@ -877,6 +877,262 @@ function summarizeGuidedProofLoopBundle(bundle) {
   };
 }
 
+function buildTransactionProofHandoffCenter() {
+  return {
+    ok: true,
+    brand: "xoonya",
+    product: "transaction proof handoff center",
+    supported_source_refs: [
+      "transaction.registry.anchor",
+      "transaction.runtime.consequence",
+      "transaction.trust.receipt",
+      "transaction.admission.settlement",
+      "transaction.job.commitment"
+    ],
+    recommended_loop: "default.proof.bundle.loop",
+    required_fields: ["transaction_id", "receipt_id", "proof_ref"],
+    optional_fields: ["source_ref", "task_refs", "delivery_count", "payment_ledger_count"]
+  };
+}
+
+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 summarizeTransactionProofHandoffCenter() {
+  const center = buildTransactionProofHandoffCenter();
+  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 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 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)
+    ? body.handoff_bundle
+    : body;
+  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 sourceRef = normalizeString(handoff.source_ref || body.source_ref || "transaction.proof_handoff");
+  const taskRefs = normalizeStringArray(handoff.task_refs, "handoff_bundle.task_refs") || [];
+  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 {
+    source_ref: sourceRef,
+    transaction_id: transactionId,
+    receipt_id: receiptId,
+    proof_ref: proofRef,
+    task_refs: taskRefs,
+    delivery_count: deliveryCount,
+    payment_ledger_count: paymentLedgerCount
+  };
+}
+
+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 buildTransactionProofHandoffEvent(input) {
+  const handoff = canonicalizeTransactionProofHandoff(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
+  });
+  return canonicalizeEvent({
+    version: CANONICAL_EVENT_BUNDLE_VERSION,
+    domain_id: "xytara.transaction_handoff",
+    sequence: handoff.transaction_id,
+    actor_id: "xytara.transaction_center",
+    adapter_source: "xytara.proof_handoff",
+    event_type: `${handoff.source_ref}.proof_handoff`,
+    event_hash: eventHash,
+    semantic_slots: handoff
+  });
+}
+
+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 runTransactionProofHandoff(input) {
+  const handoff = canonicalizeTransactionProofHandoff(input);
+  const event = buildTransactionProofHandoffEvent(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: "transaction_proof_handoff",
+      source_ref: handoff.source_ref
+    }
+  });
+  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 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 summarizeTransactionProofHandoff(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,
+    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 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 runDefaultProofLoop(loopRef, input) {
   const loop = getDefaultProofLoop(loopRef);
   if (!loop) {
@@ -920,11 +1176,23 @@ module.exports = {
   buildDefaultProofCenter,
   buildDefaultProofLoopCatalog,
   buildDefaultProofLoops,
+  buildInteractionSpineProofHandoffCenter,
+  buildTransactionProofHandoffCenter,
+  buildInteractionSpineProofHandoffEvent,
+  buildTransactionProofHandoffEvent,
+  canonicalizeInteractionSpineProofHandoff,
   getDefaultProofLoop,
+  canonicalizeTransactionProofHandoff,
   runDefaultProofLoop,
+  runInteractionSpineProofHandoff,
+  runTransactionProofHandoff,
   summarizeDefaultProofCenter,
   summarizeDefaultProofLoops,
   summarizeGuidedProofLoopBundle,
+  summarizeInteractionSpineProofHandoff,
+  summarizeInteractionSpineProofHandoffCenter,
+  summarizeTransactionProofHandoff,
+  summarizeTransactionProofHandoffCenter,
   canonicalizeEvent,
   hashEvent,
   emitReceipt,

package/server.js

@@ -97,6 +97,26 @@ async function routeRequest(req, res) {
     return;
   }
 
+  if (req.method === 'GET' && url.pathname === '/v1/proof-center/transaction-handoff') {
+    sendJson(res, 200, proofSdk.buildTransactionProofHandoffCenter());
+    return;
+  }
+
+  if (req.method === 'GET' && url.pathname === '/v1/proof-center/transaction-handoff/summary') {
+    sendJson(res, 200, proofSdk.summarizeTransactionProofHandoffCenter());
+    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/default-loop') {
     const loop = proofSdk.getDefaultProofLoop(url.searchParams.get('ref'));
     if (!loop) {
@@ -119,6 +139,28 @@ async function routeRequest(req, res) {
     return;
   }
 
+  if (req.method === 'POST' && url.pathname === '/v1/proof-center/transaction-handoff/run') {
+    try {
+      const body = await readJsonBody(req);
+      const result = proofSdk.runTransactionProofHandoff(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/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/receipts/verify') {
     try {
       const body = await readJsonBody(req);