xoonya 1.5.0 → 1.7.0

package/README.md

@@ -20,6 +20,20 @@ The package and service now also expose a default proof center surface so the in
 - compact compatibility helpers preserved, but not treated as the public conceptual center
 - proof remains settlement-agnostic and workflow-agnostic by default
 
+The current `1.6.0` companion slice adds guided default proof loops on top of that proof center:
+
+- default proof-loop catalog and detail routes
+- a direct proof-loop run route for the canonical proof-native path
+- package helpers that build, verify, and summarize the proof bundle boundary in one step
+
+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
+
 ## Proof Model
 
 The primary proof model is layered:
@@ -72,6 +86,7 @@ The package quickstart demonstrates:
 - canonical receipt emission
 - proof bundle construction
 - proof bundle verification
+- transaction proof-handoff follow-through
 
 ## Service Quickstart
 
@@ -98,6 +113,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.5.0",
+  "version": "1.7.0",
   "description": "Deterministic proof SDK for canonical events, receipts, proof bundles, and verification.",
   "main": "index.js",
   "type": "commonjs",

package/proof_sdk.js

@@ -793,9 +793,273 @@ function summarizeDefaultProofCenter() {
   };
 }
 
+function buildDefaultProofLoops() {
+  const center = buildDefaultProofCenter();
+  return [
+    {
+      loop_ref: "default.proof.bundle.loop",
+      title: "Default Proof Bundle Loop",
+      description: "Canonicalize an event, emit a receipt, build a proof bundle, and verify it in one proof-native path.",
+      stage_count: 5,
+      stages: ["canonicalize", "hash", "emit_receipt", "build_bundle", "verify_bundle"],
+      event_version: center.proof_model.event_version,
+      receipt_version: center.proof_model.receipt_version,
+      proof_bundle_version: center.proof_model.proof_bundle_version
+    },
+    {
+      loop_ref: "default.proof.receipt.loop",
+      title: "Default Proof Receipt Loop",
+      description: "Canonicalize an event, emit a receipt, and verify the resulting proof-native receipt path.",
+      stage_count: 4,
+      stages: ["canonicalize", "hash", "emit_receipt", "verify_receipt"],
+      event_version: center.proof_model.event_version,
+      receipt_version: center.proof_model.receipt_version,
+      proof_bundle_version: center.proof_model.proof_bundle_version
+    }
+  ];
+}
+
+function buildDefaultProofLoopCatalog() {
+  const center = buildDefaultProofCenter();
+  const loops = buildDefaultProofLoops();
+  return {
+    ok: true,
+    brand: center.brand,
+    product: "default proof loops",
+    event_version: center.proof_model.event_version,
+    receipt_version: center.proof_model.receipt_version,
+    proof_bundle_version: center.proof_model.proof_bundle_version,
+    loop_count: loops.length,
+    loops
+  };
+}
+
+function summarizeDefaultProofLoops() {
+  const catalog = buildDefaultProofLoopCatalog();
+  return {
+    ok: true,
+    brand: catalog.brand,
+    product: catalog.product,
+    event_version: catalog.event_version,
+    receipt_version: catalog.receipt_version,
+    proof_bundle_version: catalog.proof_bundle_version,
+    loop_count: catalog.loop_count,
+    loop_refs: catalog.loops.map((entry) => entry && entry.loop_ref).filter(Boolean),
+    loops: catalog.loops
+  };
+}
+
+function getDefaultProofLoop(ref) {
+  const normalized = String(ref || "").trim();
+  if (!normalized) return null;
+  return buildDefaultProofLoops().find((entry) => entry && entry.loop_ref === normalized) || null;
+}
+
+function summarizeGuidedProofLoopBundle(bundle) {
+  const item = bundle || {};
+  const loop = item.loop || {};
+  const canonicalEvent = item.canonical_event || {};
+  const receipt = item.receipt || {};
+  const proofBundle = item.proof_bundle || {};
+  const verification = item.bundle_verification || {};
+  const receiptVerification = item.receipt_verification || {};
+  return {
+    ok: item.ok === true,
+    loop_ref: loop.loop_ref || null,
+    stage_count: Number(loop.stage_count || 0),
+    event_version: canonicalEvent.version || null,
+    receipt_version: receipt.version || null,
+    proof_bundle_version: proofBundle.version || null,
+    receipt_id: receipt.receipt_id || null,
+    event_commitment: receipt.event_commitment || null,
+    bundle_valid: verification.valid === true,
+    receipt_valid: receiptVerification.valid === true
+  };
+}
+
+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 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 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 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 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 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 runDefaultProofLoop(loopRef, input) {
+  const loop = getDefaultProofLoop(loopRef);
+  if (!loop) {
+    throw new Error("default_proof_loop_not_found");
+  }
+  const body = input && typeof input === "object" && !Array.isArray(input) ? input : {};
+  const event = canonicalizeEvent(body.event || body.ceb);
+  const receiptOptions = body.options && typeof body.options === "object" && !Array.isArray(body.options)
+    ? body.options
+    : {};
+  const receipt = emitReceipt(event, receiptOptions);
+  const bundle = buildProofBundle({
+    ceb: event,
+    receipt,
+    anchors: Array.isArray(body.anchors) ? body.anchors : undefined,
+    attestations: Array.isArray(body.attestations) ? body.attestations : undefined,
+    evidence_refs: Array.isArray(body.evidence_refs) ? body.evidence_refs : undefined,
+    batch_refs: Array.isArray(body.batch_refs) ? body.batch_refs : undefined,
+    metadata: body.metadata && typeof body.metadata === "object" && !Array.isArray(body.metadata) ? body.metadata : undefined
+  });
+  const bundleVerification = verifyProofBundle(bundle);
+  const receiptVerification = receipt.compatibility && receipt.compatibility.legacy_receipt
+    ? verifyReceipt(
+        receipt.compatibility.legacy_receipt.opreturn_hex,
+        Buffer.from(canonicalize(event), "utf8")
+      )
+    : { valid: true, reason: null, version: CANONICAL_RECEIPT_VERSION };
+  return {
+    ok: true,
+    loop,
+    canonical_event: event,
+    event_commitment: hashEvent(event),
+    receipt,
+    receipt_verification: receiptVerification,
+    proof_bundle: bundle,
+    bundle_verification: bundleVerification
+  };
+}
+
 module.exports = {
   buildDefaultProofCenter,
+  buildDefaultProofLoopCatalog,
+  buildDefaultProofLoops,
+  buildTransactionProofHandoffCenter,
+  buildTransactionProofHandoffEvent,
+  getDefaultProofLoop,
+  canonicalizeTransactionProofHandoff,
+  runDefaultProofLoop,
+  runTransactionProofHandoff,
   summarizeDefaultProofCenter,
+  summarizeDefaultProofLoops,
+  summarizeGuidedProofLoopBundle,
+  summarizeTransactionProofHandoff,
+  summarizeTransactionProofHandoffCenter,
   canonicalizeEvent,
   hashEvent,
   emitReceipt,

package/server.js

@@ -87,6 +87,59 @@ async function routeRequest(req, res) {
     return;
   }
 
+  if (req.method === 'GET' && url.pathname === '/v1/proof-center/default-loops') {
+    sendJson(res, 200, proofSdk.buildDefaultProofLoopCatalog());
+    return;
+  }
+
+  if (req.method === 'GET' && url.pathname === '/v1/proof-center/default-loops/summary') {
+    sendJson(res, 200, proofSdk.summarizeDefaultProofLoops());
+    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/default-loop') {
+    const loop = proofSdk.getDefaultProofLoop(url.searchParams.get('ref'));
+    if (!loop) {
+      sendJson(res, 404, { ok: false, error: 'default_proof_loop_not_found' });
+      return;
+    }
+    sendJson(res, 200, { ok: true, loop });
+    return;
+  }
+
+  if (req.method === 'POST' && url.pathname === '/v1/proof-center/default-loops/run') {
+    try {
+      const body = await readJsonBody(req);
+      const loopRef = String(body.loop_ref || '').trim();
+      const result = proofSdk.runDefaultProofLoop(loopRef, body);
+      sendJson(res, 200, result);
+    } catch (error) {
+      sendJson(res, error.message === 'default_proof_loop_not_found' ? 404 : 400, { ok: false, reason: error.message });
+    }
+    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/receipts/verify') {
     try {
       const body = await readJsonBody(req);