xytara 1.12.0 → 1.14.0

package/README.md

@@ -139,10 +139,21 @@ The current `1.10.0` line starts building on that by exposing reusable continuat
 - continuation summaries that make the default transaction-to-proof bridge explicit instead of inferred
 - prepared continuation artifacts that classify the preserved execution, economic, and proof-facing context that survives into proof-native follow-through
 - extension-seam summaries that distinguish stable carry from future adapter-ready boundary points on that durable path
+- reusable-default summaries that expose the stable prepared artifact as a clearer default follow-through pattern
+- reusable-default template surfaces that package that same default path into a direct proof-side review request
 - extension-template surfaces that turn the durable transaction-side artifact into a reusable proof-side extension-review request
 
 This is intended to make the public stack easier to compose after grouped execution, not just easier to inspect.
 
+The current `1.14.0` line starts hardening that reusable path into a clearer public composition contract:
+
+- prepared-artifact composition-contract summaries
+- composition-contract template surfaces for proof-side contract review
+- compact composition-contract bundles for direct transaction-side contract reuse
+- clearer public contract ids across the reusable-default continuation path
+
+This is intended to make the transaction-side continuation path easier to treat as a stable public contract instead of only a strong reusable default.
+
 ## Package Surface
 
 The SDK is broad, but it stays organized into a few repeatable families instead of one-off surfaces.

package/index.js

@@ -40,7 +40,7 @@ const {
 } = require("./integrations/registry");
 
 const COMMERCE_SDK_NAME = "xytara";
-const COMMERCE_SDK_VERSION = "1.12.0";
+const COMMERCE_SDK_VERSION = "1.14.0";
 const COMMERCE_API_VERSION = "v1";
 
 function createClient(options) {

package/lib/commerce_client.js

@@ -1175,14 +1175,30 @@ function summarizeInteractionResultPackageContinuationPreparationPayload(payload
   const extensionTemplate = item.extension_template && typeof item.extension_template === "object"
     ? item.extension_template
     : {};
+  const reusableDefault = item.reusable_default_summary && typeof item.reusable_default_summary === "object"
+    ? item.reusable_default_summary
+    : {};
+  const reusableDefaultTemplate = item.reusable_default_template && typeof item.reusable_default_template === "object"
+    ? item.reusable_default_template
+    : {};
+  const compositionContract = item.composition_contract_summary && typeof item.composition_contract_summary === "object"
+    ? item.composition_contract_summary
+    : {};
+  const compositionContractTemplate = item.composition_contract_template && typeof item.composition_contract_template === "object"
+    ? item.composition_contract_template
+    : {};
   return {
     ok: item.ok === true,
     continuation_ref: continuation ? continuation.continuation_ref : null,
     result_package_ref: continuation ? continuation.result_package_ref : null,
     prepared_artifact_ref: artifact.prepared_artifact_ref || null,
     extension_seam_ref: extension.extension_seam_ref || null,
+    reusable_default_ref: reusableDefault.reusable_default_ref || null,
     target_surface: template.target_surface || null,
     review_surface: template.review_surface || null,
+    default_review_surface: reusableDefault.default_followthrough && reusableDefault.default_followthrough.review_surface
+      ? reusableDefault.default_followthrough.review_surface
+      : null,
     continuation_ready: continuation ? continuation.continuation_ready === true : false,
     evidence_ref_count: Array.isArray(template.request_template && template.request_template.evidence_refs)
       ? template.request_template.evidence_refs.length
@@ -1193,7 +1209,12 @@ function summarizeInteractionResultPackageContinuationPreparationPayload(payload
       artifact.preserved_context.proof_handoff.seam_layer_count || 0
     ),
     proof_ready: artifact.durable_path && artifact.durable_path.proof_ready === true,
+    reusable_by_default: reusableDefault.default_followthrough && reusableDefault.default_followthrough.reusable_by_default === true,
+    composition_contract_ref: compositionContract.composition_contract_ref || null,
+    contract_ready: compositionContract.contract_ready === true,
     future_adapter_hook_count: Number(extension.future_adapter_hook_count || 0),
+    reusable_default_target_surface: reusableDefaultTemplate.target_surface || null,
+    composition_contract_target_surface: compositionContractTemplate.target_surface || null,
     extension_target_surface: extensionTemplate.target_surface || null
   };
 }
@@ -4346,6 +4367,86 @@ class CommerceClient {
     });
   }
 
+  async prepareInteractionResultPackageReusableDefaultSummary(continuationRef, body, options) {
+    const opts = options || {};
+    return this.runNamedTaskRoute("/v1/transaction-center/result-package-continuations/prepare/default-summary", {
+      command: opts.command || String(continuationRef || "").trim() || "result.package.continuation.default.summary",
+      continuation_ref: String(continuationRef || "").trim(),
+      body: body || {},
+      callback_url: opts.callbackUrl || null,
+      settlement_mode: opts.settlementMode || null,
+      payment_protocol: opts.paymentProtocol || null,
+      protocol: opts.protocol || null,
+      integration_id: opts.integrationId || null,
+      integration_ids: Array.isArray(opts.integrationIds) ? opts.integrationIds : [],
+      integration_context: opts.integrationContext || null
+    });
+  }
+
+  async prepareInteractionResultPackageReusableDefaultTemplate(continuationRef, body, options) {
+    const opts = options || {};
+    return this.runNamedTaskRoute("/v1/transaction-center/result-package-continuations/prepare/default-template", {
+      command: opts.command || String(continuationRef || "").trim() || "result.package.continuation.default.template",
+      continuation_ref: String(continuationRef || "").trim(),
+      body: body || {},
+      callback_url: opts.callbackUrl || null,
+      settlement_mode: opts.settlementMode || null,
+      payment_protocol: opts.paymentProtocol || null,
+      protocol: opts.protocol || null,
+      integration_id: opts.integrationId || null,
+      integration_ids: Array.isArray(opts.integrationIds) ? opts.integrationIds : [],
+      integration_context: opts.integrationContext || null
+    });
+  }
+
+  async prepareInteractionResultPackageCompositionContractSummary(continuationRef, body, options) {
+    const opts = options || {};
+    return this.runNamedTaskRoute("/v1/transaction-center/result-package-continuations/prepare/contract-summary", {
+      command: opts.command || String(continuationRef || "").trim() || "result.package.continuation.contract.summary",
+      continuation_ref: String(continuationRef || "").trim(),
+      body: body || {},
+      callback_url: opts.callbackUrl || null,
+      settlement_mode: opts.settlementMode || null,
+      payment_protocol: opts.paymentProtocol || null,
+      protocol: opts.protocol || null,
+      integration_id: opts.integrationId || null,
+      integration_ids: Array.isArray(opts.integrationIds) ? opts.integrationIds : [],
+      integration_context: opts.integrationContext || null
+    });
+  }
+
+  async prepareInteractionResultPackageCompositionContractBundle(continuationRef, body, options) {
+    const opts = options || {};
+    return this.runNamedTaskRoute("/v1/transaction-center/result-package-continuations/prepare/contract-bundle", {
+      command: opts.command || String(continuationRef || "").trim() || "result.package.continuation.contract.bundle",
+      continuation_ref: String(continuationRef || "").trim(),
+      body: body || {},
+      callback_url: opts.callbackUrl || null,
+      settlement_mode: opts.settlementMode || null,
+      payment_protocol: opts.paymentProtocol || null,
+      protocol: opts.protocol || null,
+      integration_id: opts.integrationId || null,
+      integration_ids: Array.isArray(opts.integrationIds) ? opts.integrationIds : [],
+      integration_context: opts.integrationContext || null
+    });
+  }
+
+  async prepareInteractionResultPackageCompositionContractTemplate(continuationRef, body, options) {
+    const opts = options || {};
+    return this.runNamedTaskRoute("/v1/transaction-center/result-package-continuations/prepare/contract-template", {
+      command: opts.command || String(continuationRef || "").trim() || "result.package.continuation.contract.template",
+      continuation_ref: String(continuationRef || "").trim(),
+      body: body || {},
+      callback_url: opts.callbackUrl || null,
+      settlement_mode: opts.settlementMode || null,
+      payment_protocol: opts.paymentProtocol || null,
+      protocol: opts.protocol || null,
+      integration_id: opts.integrationId || null,
+      integration_ids: Array.isArray(opts.integrationIds) ? opts.integrationIds : [],
+      integration_context: opts.integrationContext || null
+    });
+  }
+
   async runNamedTaskRoute(path, payload) {
     if (!this.apiKey || !this.walletId || !this.walletSecret) {
       throw new Error("named task routes require apiKey, walletId, and walletSecret");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xytara",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "Machine commerce SDK for discovery, quoting, execution, lifecycle inspection, and adapters.",
   "main": "index.js",
   "type": "commonjs",

package/server.js

@@ -1219,6 +1219,126 @@ function buildPreparedContinuationExtensionTemplate(portableHandoff, continuatio
   };
 }
 
+function buildPreparedContinuationReusableDefaultSummary(portableHandoff, continuation) {
+  const handoff = portableHandoff && typeof portableHandoff === "object" ? portableHandoff : {};
+  const seamLayers = Array.isArray(handoff.seam_layers) ? handoff.seam_layers : [];
+  const taskRefs = Array.isArray(handoff.task_refs) ? handoff.task_refs : [];
+  return {
+    ok: true,
+    reusable_default_ref: continuation && continuation.continuation_ref
+      ? `default.${continuation.continuation_ref}`
+      : null,
+    continuation_ref: continuation && continuation.continuation_ref ? continuation.continuation_ref : null,
+    prepared_artifact_ref: continuation && continuation.continuation_ref
+      ? `prepared.${continuation.continuation_ref}`
+      : null,
+    stable_default_carry: {
+      execution_context: {
+        committed_ref: handoff.committed_ref || null,
+        task_ref_count: taskRefs.length
+      },
+      economic_context: {
+        payment_protocol: handoff.payment_protocol || null,
+        settlement_mode: handoff.settlement_mode || null,
+        treasury_destination_id: handoff.treasury_destination_id || null
+      },
+      proof_context: {
+        source_ref: handoff.source_ref || null,
+        seam_layer_count: seamLayers.length
+      }
+    },
+    default_followthrough: {
+      review_surface: "/v1/proof-center/result-package-handoff/review/default-continuation",
+      review_summary_surface: "/v1/proof-center/result-package-handoff/review/summary",
+      run_surface: "/v1/proof-center/result-package-handoff/run",
+      reusable_by_default: Boolean(handoff.result_package_ref && handoff.transaction_id && handoff.receipt_id && handoff.proof_ref)
+    }
+  };
+}
+
+function buildPreparedContinuationReusableDefaultTemplate(portableHandoff, continuation) {
+  const handoff = portableHandoff && typeof portableHandoff === "object" ? portableHandoff : {};
+  const summary = buildPreparedContinuationReusableDefaultSummary(portableHandoff, continuation);
+  return {
+    ok: true,
+    reusable_default_ref: summary.reusable_default_ref || null,
+    target_surface: "/v1/proof-center/result-package-handoff/review/default-continuation",
+    request_template: {
+      handoff_bundle: handoff
+    },
+    stable_boundary_ids: [
+      "prepared_artifact_default",
+      "review_default_continuation",
+      "proof_run"
+    ]
+  };
+}
+
+function buildPreparedContinuationCompositionContractSummary(portableHandoff, continuation) {
+  const handoff = portableHandoff && typeof portableHandoff === "object" ? portableHandoff : {};
+  const reusableDefault = buildPreparedContinuationReusableDefaultSummary(portableHandoff, continuation);
+  const seamLayers = Array.isArray(handoff.seam_layers) ? handoff.seam_layers : [];
+  return {
+    ok: true,
+    composition_contract_ref: continuation && continuation.continuation_ref
+      ? `contract.${continuation.continuation_ref}`
+      : null,
+    reusable_default_ref: reusableDefault.reusable_default_ref || null,
+    public_contract_ids: [
+      "prepared_artifact",
+      "reusable_default_review",
+      "proof_run"
+    ],
+    contract_carry: {
+      execution_context: {
+        committed_ref: handoff.committed_ref || null,
+        stable: Boolean(handoff.committed_ref)
+      },
+      economic_context: {
+        payment_protocol: handoff.payment_protocol || null,
+        settlement_mode: handoff.settlement_mode || null,
+        treasury_destination_id: handoff.treasury_destination_id || null
+      },
+      proof_context: {
+        source_ref: handoff.source_ref || null,
+        seam_layer_count: seamLayers.length
+      }
+    },
+    helper_only_summary_ids: [
+      "extension_seam_summary",
+      "portable_handoff_summary"
+    ],
+    contract_ready: reusableDefault.default_followthrough && reusableDefault.default_followthrough.reusable_by_default === true,
+    next_surface: "/v1/proof-center/result-package-handoff/review/contract-summary"
+  };
+}
+
+function buildPreparedContinuationCompositionContractTemplate(portableHandoff, continuation) {
+  const handoff = portableHandoff && typeof portableHandoff === "object" ? portableHandoff : {};
+  const summary = buildPreparedContinuationCompositionContractSummary(portableHandoff, continuation);
+  return {
+    ok: true,
+    composition_contract_ref: summary.composition_contract_ref || null,
+    target_surface: "/v1/proof-center/result-package-handoff/review/contract-summary",
+    request_template: {
+      handoff_bundle: handoff
+    },
+    stable_boundary_ids: [
+      "prepared_artifact_contract",
+      "review_contract_summary",
+      "proof_run"
+    ]
+  };
+}
+
+function buildPreparedContinuationCompositionContractBundle(portableHandoff, continuation) {
+  return {
+    ok: true,
+    composition_contract_summary: buildPreparedContinuationCompositionContractSummary(portableHandoff, continuation),
+    composition_contract_template: buildPreparedContinuationCompositionContractTemplate(portableHandoff, continuation)
+  };
+}
+
 function buildInteractionResultPackageContinuationRequestTemplate(portableHandoff, continuation) {
   const handoff = portableHandoff && typeof portableHandoff === "object" ? portableHandoff : {};
   return {
@@ -2175,6 +2295,9 @@ async function routeRequest(req, res) {
         continuation_summary: buildInteractionResultPackageContinuationSummary(portableHandoff, continuation),
         prepared_artifact_summary: buildPreparedContinuationArtifactSummary(portableHandoff, continuation),
         extension_seam_summary: buildPreparedContinuationExtensionSeamSummary(portableHandoff, continuation),
+        reusable_default_summary: buildPreparedContinuationReusableDefaultSummary(portableHandoff, continuation),
+        reusable_default_template: buildPreparedContinuationReusableDefaultTemplate(portableHandoff, continuation),
+        ...buildPreparedContinuationCompositionContractBundle(portableHandoff, continuation),
         extension_template: buildPreparedContinuationExtensionTemplate(portableHandoff, continuation),
         proof_request_template: buildInteractionResultPackageContinuationRequestTemplate(portableHandoff, continuation)
       });
@@ -2211,11 +2334,169 @@ async function routeRequest(req, res) {
     sendJson(res, 200, {
       ...buildPreparedContinuationArtifactCompactSummary(portableHandoff, continuation),
       extension_seam_summary: buildPreparedContinuationExtensionSeamSummary(portableHandoff, continuation),
+      reusable_default_summary: buildPreparedContinuationReusableDefaultSummary(portableHandoff, continuation),
+      reusable_default_template: buildPreparedContinuationReusableDefaultTemplate(portableHandoff, continuation),
+      ...buildPreparedContinuationCompositionContractBundle(portableHandoff, continuation),
       extension_template: buildPreparedContinuationExtensionTemplate(portableHandoff, continuation)
     });
     return;
   }
 
+  if (req.method === "POST" && url.pathname === "/v1/transaction-center/result-package-continuations/prepare/default-summary") {
+    const body = await readJsonBody(req);
+    const continuationRef = String(body && body.continuation_ref || "").trim();
+    const continuation = getInteractionResultPackageContinuation(continuationRef);
+    if (!continuation) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const resultPackage = getInteractionResultPackage(continuation.result_package_ref);
+    if (!resultPackage) {
+      sendJson(res, 404, { ok: false, error: "result_package_not_found" });
+      return;
+    }
+    const payload = buildInteractionSpinePathRunPayload({
+      ...(body && typeof body === "object" && !Array.isArray(body) ? body : {}),
+      spine_path_ref: resultPackage.source_ref
+    });
+    if (!payload) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const result = executeCommandRequest(state, payload, req.headers);
+    if (result.status !== 200) {
+      sendJson(res, result.status, result.payload);
+      return;
+    }
+    const portableHandoff = buildInteractionResultPackagePortableHandoff(result.payload, resultPackage);
+    sendJson(res, 200, buildPreparedContinuationReusableDefaultSummary(portableHandoff, continuation));
+    return;
+  }
+
+  if (req.method === "POST" && url.pathname === "/v1/transaction-center/result-package-continuations/prepare/contract-summary") {
+    const body = await readJsonBody(req);
+    const continuationRef = String(body && body.continuation_ref || "").trim();
+    const continuation = getInteractionResultPackageContinuation(continuationRef);
+    if (!continuation) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const resultPackage = getInteractionResultPackage(continuation.result_package_ref);
+    if (!resultPackage) {
+      sendJson(res, 404, { ok: false, error: "result_package_not_found" });
+      return;
+    }
+    const payload = buildInteractionSpinePathRunPayload({
+      ...(body && typeof body === "object" && !Array.isArray(body) ? body : {}),
+      spine_path_ref: resultPackage.source_ref
+    });
+    if (!payload) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const result = executeCommandRequest(state, payload, req.headers);
+    if (result.status !== 200) {
+      sendJson(res, result.status, result.payload);
+      return;
+    }
+    const portableHandoff = buildInteractionResultPackagePortableHandoff(result.payload, resultPackage);
+    sendJson(res, 200, buildPreparedContinuationCompositionContractSummary(portableHandoff, continuation));
+    return;
+  }
+
+  if (req.method === "POST" && url.pathname === "/v1/transaction-center/result-package-continuations/prepare/contract-bundle") {
+    const body = await readJsonBody(req);
+    const continuationRef = String(body && body.continuation_ref || "").trim();
+    const continuation = getInteractionResultPackageContinuation(continuationRef);
+    if (!continuation) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const resultPackage = getInteractionResultPackage(continuation.result_package_ref);
+    if (!resultPackage) {
+      sendJson(res, 404, { ok: false, error: "result_package_not_found" });
+      return;
+    }
+    const payload = buildInteractionSpinePathRunPayload({
+      ...(body && typeof body === "object" && !Array.isArray(body) ? body : {}),
+      spine_path_ref: resultPackage.source_ref
+    });
+    if (!payload) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const result = executeCommandRequest(state, payload, req.headers);
+    if (result.status !== 200) {
+      sendJson(res, result.status, result.payload);
+      return;
+    }
+    const portableHandoff = buildInteractionResultPackagePortableHandoff(result.payload, resultPackage);
+    sendJson(res, 200, buildPreparedContinuationCompositionContractBundle(portableHandoff, continuation));
+    return;
+  }
+
+  if (req.method === "POST" && url.pathname === "/v1/transaction-center/result-package-continuations/prepare/contract-template") {
+    const body = await readJsonBody(req);
+    const continuationRef = String(body && body.continuation_ref || "").trim();
+    const continuation = getInteractionResultPackageContinuation(continuationRef);
+    if (!continuation) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const resultPackage = getInteractionResultPackage(continuation.result_package_ref);
+    if (!resultPackage) {
+      sendJson(res, 404, { ok: false, error: "result_package_not_found" });
+      return;
+    }
+    const payload = buildInteractionSpinePathRunPayload({
+      ...(body && typeof body === "object" && !Array.isArray(body) ? body : {}),
+      spine_path_ref: resultPackage.source_ref
+    });
+    if (!payload) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const result = executeCommandRequest(state, payload, req.headers);
+    if (result.status !== 200) {
+      sendJson(res, result.status, result.payload);
+      return;
+    }
+    const portableHandoff = buildInteractionResultPackagePortableHandoff(result.payload, resultPackage);
+    sendJson(res, 200, buildPreparedContinuationCompositionContractTemplate(portableHandoff, continuation));
+    return;
+  }
+
+  if (req.method === "POST" && url.pathname === "/v1/transaction-center/result-package-continuations/prepare/default-template") {
+    const body = await readJsonBody(req);
+    const continuationRef = String(body && body.continuation_ref || "").trim();
+    const continuation = getInteractionResultPackageContinuation(continuationRef);
+    if (!continuation) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const resultPackage = getInteractionResultPackage(continuation.result_package_ref);
+    if (!resultPackage) {
+      sendJson(res, 404, { ok: false, error: "result_package_not_found" });
+      return;
+    }
+    const payload = buildInteractionSpinePathRunPayload({
+      ...(body && typeof body === "object" && !Array.isArray(body) ? body : {}),
+      spine_path_ref: resultPackage.source_ref
+    });
+    if (!payload) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const result = executeCommandRequest(state, payload, req.headers);
+    if (result.status !== 200) {
+      sendJson(res, result.status, result.payload);
+      return;
+    }
+    const portableHandoff = buildInteractionResultPackagePortableHandoff(result.payload, resultPackage);
+    sendJson(res, 200, buildPreparedContinuationReusableDefaultTemplate(portableHandoff, continuation));
+    return;
+  }
+
   if (req.method === "POST" && url.pathname === "/v1/transaction-center/result-package-continuations/prepare/extension-template") {
     const body = await readJsonBody(req);
     const continuationRef = String(body && body.continuation_ref || "").trim();