xytara 1.24.0 → 1.26.0

package/FINAL_CONTRACT.md

@@ -0,0 +1,498 @@
+# xytara Final Contract
+
+## Purpose
+
+`xytara` is the machine transaction and execution layer.
+
+It exists to let agents, developers, and systems:
+
+- discover machine capabilities
+- quote work before execution
+- pay through one or more supported payment paths
+- execute tasks and workflows
+- receive deliverables
+- inspect lifecycle state
+- integrate third-party adapters
+- emit proof through `xoonya`
+
+`xytara` is not the proof foundation itself.
+It consumes and emits proof-compatible facts, but its primary job is machine commerce and execution.
+
+## Public Release Stance
+
+This product is being prepared as a first public release from private lineage.
+
+That means:
+
+- prior internal SDK and service shapes are design history, not public obligations
+- useful capability should be preserved where it strengthens the final product
+- historical private helper sprawl does not automatically define the public contract
+
+The public baseline should therefore be chosen for product quality, clarity, extensibility, and end-to-end usefulness, not for backward compatibility with prior private repos.
+
+## Product Boundary
+
+`xytara` owns:
+
+- task catalog
+- workflow catalog
+- quote generation
+- pricing logic
+- payment negotiation
+- payment rail adapters
+- execution adapters
+- settlement adapters
+- delivery and result surfaces
+- lifecycle inspection
+- operator visibility
+- adapter manifests and adapter onboarding surfaces
+
+`xytara` does not own:
+
+- base proof semantics
+- base receipt semantics
+- proof canonicalization rules
+- base proof bundle semantics
+
+Those belong to `xoonya`.
+
+## Core Doctrine
+
+`xytara` is the hot-state, machine-transaction layer.
+
+Its doctrine is:
+
+- discover
+- quote
+- pay
+- execute
+- deliver
+- inspect
+- prove
+
+The commerce layer may evolve quickly.
+Its proof boundary must remain strict.
+
+## Required Product Capabilities
+
+### 1. Discovery
+
+The system must expose machine-discoverable catalogs of:
+
+- tasks
+- workflows
+- settlement profiles
+- planning facets
+- operational list and summary surfaces
+
+Discovery must support:
+
+- raw row access
+- summary access
+- value-list access where useful
+- filterable query paths
+
+### 2. Quote Before Execution
+
+Every payable execution path must support quote or price discovery before irreversible work begins.
+
+The quote system must support:
+
+- single-task quotes
+- workflow/task-set quotes
+- preview flows where execution outcome is not yet committed
+- dynamic and static pricing models
+
+### 3. Payment Paths
+
+The commerce layer must support multiple payment modes.
+
+At minimum, the architecture must permit:
+
+- machine-native pay-per-use negotiation
+- human-friendly billing / credits
+- settlement-aware downstream accounting
+
+The public contract must stay payment-rail-neutral.
+
+### 4. Execution
+
+The system must support:
+
+- direct task execution
+- workflow execution
+- synchronous result flows
+- asynchronous result flows
+- waited result flows
+- lifecycle inspection after execution
+
+### 5. Delivery
+
+Execution outputs must be representable as deliverables.
+
+The delivery contract must support:
+
+- inline outputs
+- artifact references
+- linked records
+- monitor snapshots
+- activity snapshots
+
+### 6. Lifecycle and Operator Surfaces
+
+The system must expose lifecycle and operator-facing surfaces for:
+
+- quotes
+- transactions
+- receipts
+- payments / ledger records
+- deliveries
+- disputes
+- refunds
+- remediation tickets
+- reports
+
+The operator layer must provide:
+
+- summaries
+- counts and aggregates
+- status views
+- open issue views
+- execution exception views
+- dashboard views
+- drill-down record retrieval
+
+### 7. Adapter Extensibility
+
+The commerce layer must be intentionally extensible by third parties.
+
+This is a first-class product requirement.
+
+## Required Separation Boundaries
+
+### 1. Execution vs Proof
+
+Execution describes what happened and produces externally consequential event facts.
+
+Proof commits to those facts.
+
+`xytara` must not redefine proof semantics.
+
+### 2. Commerce vs Settlement Rail
+
+The commerce layer negotiates and coordinates payment and execution.
+
+Settlement rails are plugged in as adapters.
+
+The public commerce contract must not collapse into one rail’s worldview.
+
+### 3. Commerce vs Governance
+
+The commerce layer may enforce configured rules and policies needed for execution and transaction processing.
+
+But it should not become an all-purpose political governance system.
+
+### 4. Hot State vs Cold Truth
+
+Hot operational state belongs in commerce.
+
+Cold portable truth belongs in proof.
+
+The commerce layer may reference proof artifacts and emit them, but must not absorb their base semantics.
+
+## Public Commerce Model
+
+The public commerce contract should center on the following abstractions.
+
+### A. Task
+
+A task is the smallest directly executable commercial capability.
+
+Every public task should have:
+
+- stable reference
+- summary representation
+- pricing representation
+- schema/template representation where applicable
+- execution mode
+- adapter identity
+- capability metadata
+
+### B. Workflow
+
+A workflow is a composed machine capability built from one or more tasks.
+
+Every public workflow should have:
+
+- stable reference
+- summary representation
+- pricing representation
+- task composition metadata
+- execution and failure posture metadata
+
+### C. Quote
+
+A quote is the priced and versioned commercial offer for a machine action.
+
+Quotes may be:
+
+- previews
+- execution quotes
+- workflow quotes
+- batch quotes
+
+### D. Result / Deliverable
+
+A result is the execution outcome.
+
+A deliverable is the artifact or structured output accessible to the caller or downstream systems.
+
+### E. Lifecycle Record
+
+Lifecycle records track operational state across the quote -> execution -> delivery -> issue/remediation path.
+
+## Required Adapter Classes
+
+The final public system must support explicit adapter classes.
+
+### 1. Execution Adapter
+
+Wraps an execution backend or runtime capability.
+
+Responsibilities:
+
+- execute supported task(s)
+- surface deterministic input/output contracts
+- expose capability metadata
+- produce proof-compatible event facts
+
+### 2. Settlement Adapter
+
+Handles external settlement or anchoring coordination where needed.
+
+Responsibilities:
+
+- accept settlement targets
+- expose external references
+- support verification-ready references back into lifecycle state
+
+### 3. Payment Rail Adapter
+
+Handles a payment negotiation and payment confirmation path.
+
+Responsibilities:
+
+- advertise payment capability
+- perform negotiation / payment admission logic
+- produce settlement/payment references usable by lifecycle systems
+
+### 4. Agent Protocol Adapter
+
+Wraps agent-facing invocation or integration protocols.
+
+Examples:
+
+- MCP-style consumption
+- other machine-callable protocol surfaces
+
+Responsibilities:
+
+- expose discovery and invocation in a machine-native way
+- preserve underlying quote/pay/execute semantics
+
+### 5. Identity / Registry Adapter
+
+Handles external identity, trust, registry, or discovery linkage where needed.
+
+Responsibilities:
+
+- surface references, identities, and compatibility metadata
+- remain additive, not redefining the commerce core
+
+## Third-Party Adapter Contract
+
+Third-party adapter support is a product surface, not a private implementation detail.
+
+The final system must include:
+
+- stable adapter interfaces
+- manifest schema
+- capability metadata schema
+- certification harness
+- compatibility/version rules
+- example adapters
+- adapter authoring docs
+
+### Third-party adapter lifecycle
+
+1. Implement adapter interface
+2. Publish adapter manifest
+3. Pass certification harness
+4. Register into catalog or adapter registry
+5. Promote from staging to production
+
+### Required adapter properties
+
+Every adapter must define:
+
+- adapter identity
+- adapter version
+- adapter class
+- supported capabilities
+- failure semantics
+- timeout behavior
+- idempotency behavior
+- health contract
+- proof hook behavior
+
+## Payment Model
+
+The system must support multiple commercial modes without collapsing into one payment ideology.
+
+### Publicly acceptable modes
+
+- pay-per-use machine negotiation
+- credits / usage units
+- human-facing billing / invoicing / top-up style models
+- batch or workflow pricing
+
+### Rule
+
+No public commerce contract should require a single chain, single stablecoin, or single card processor to remain valid.
+
+## Pricing Model
+
+The system must support:
+
+- fixed pricing
+- dynamic pricing
+- pricing basis metadata
+- pricing band metadata
+- pricing currency metadata
+- bundle/workflow pricing
+
+The first production release should keep pricing explainable and stable enough for trust.
+
+More advanced adaptive pricing may be layered later, but it must not make the catalog unintelligible.
+
+## Settlement Model
+
+Settlement is distinct from execution.
+
+### Rule
+
+Execution success and settlement finality may be related, but they are not identical concepts.
+
+The commerce system must preserve explicit separation between:
+
+- task execution
+- result production
+- settlement/anchoring/finality reference
+
+## Operator Model
+
+The operator layer is a required product surface.
+
+### Required outcomes
+
+Operators must be able to:
+
+- inspect active operational issues
+- inspect execution exceptions
+- view top-level dashboard state
+- drill into affected records
+- retrieve status and aggregate summaries
+
+This may begin as API and CLI surfaces before a full UI is finished.
+
+## Public Entry Surfaces
+
+The final public commerce product should support:
+
+- package / SDK surface
+- service API surface
+- CLI surface
+- machine-tool surface
+
+### One-line use principle
+
+The public product story must support the practical flow:
+
+run command -> see catalog -> define task(s) -> get quote(s) -> pay -> receive deliverable(s) -> verify proof
+
+This is not just an example.
+It is part of the product contract.
+
+## Proof Relationship
+
+The commerce layer must emit facts and receipts in a way compatible with `xoonya`.
+
+### Rule
+
+Commerce may:
+
+- emit proof-compatible canonical event facts
+- emit receipts via proof integration
+- expose proof references in results and lifecycle records
+
+Commerce may not:
+
+- redefine proof semantics
+- redefine receipt validity
+- turn commerce metadata into the base proof contract
+
+## Versioning Strategy
+
+Commerce versioning should distinguish between:
+
+- core product contract changes
+- adapter API changes
+- catalog/schema changes
+- optional helper additions
+
+Breaking changes to adapter contracts and commerce contract surfaces must be explicit.
+
+## Conformance Requirements
+
+The final commerce product must maintain conformance across:
+
+- discovery surfaces
+- quote/pay/execute paths
+- batch paths
+- lifecycle inspection
+- operator summaries
+- proof integration
+- adapter certification
+
+## What Must Survive From Internal Lineages
+
+From the internal stack, the following semantic wins should survive:
+
+- clean separation of execution and proof
+- clean separation of execution and settlement
+- batching and ordering as explicit concerns
+- adapter-first design
+- neutral commerce over multiple rails
+- proof-backed lifecycle state
+- operator-grade visibility
+
+Historical internal labels and names should not survive publicly.
+
+## Final Product Position
+
+`xytara` should become:
+
+- the machine transaction layer
+- the machine execution layer
+- the machine delivery layer
+- the operator-visible machine commerce layer
+
+It should be:
+
+- protocol-agnostic
+- rail-flexible
+- adapter-extensible
+- machine-native
+- proof-backed
+
+That is the correct public role for the final commerce product.

package/README.md

@@ -16,6 +16,34 @@ It exists to let agents, developers, and systems:
 
 This repo is the hot-state commerce layer. It does not define base proof semantics. It references and emits proof-compatible facts, while `xoonya` owns canonical proof.
 
+## Start Here
+
+If you are new to the public stack, use this order:
+
+1. read [START_HERE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/START_HERE.md)
+2. run `node examples/quickstart.js`
+3. run `npm run verify:all`
+4. use [FINAL_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/FINAL_CONTRACT.md) and [SERVICE_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/SERVICE_CONTRACT.md) as the durable public contract
+
+If you are building adapters, continue with:
+
+- [adapters/AUTHORING_GUIDE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/adapters/AUTHORING_GUIDE.md)
+- [adapters/ONBOARDING_POSTURE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/adapters/ONBOARDING_POSTURE.md)
+- [adapters/THIRD_PARTY_SUBMISSION_PROCESS.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/adapters/THIRD_PARTY_SUBMISSION_PROCESS.md)
+
+## Production Path
+
+The intended production-facing default path is now:
+
+1. discover a capability
+2. preview or quote the transaction path
+3. execute through the default machine path
+4. inspect the transaction-side result and lifecycle state
+5. hand the result into `xoonya`
+6. review and run the proof-side completion path
+
+The rest of this README explains the full surface area and milestone trail, but the public starting posture should now be understandable from that one default path.
+
 ## Commerce Loop
 
 The public product loop is:
@@ -244,6 +272,24 @@ The current `1.24.0` line starts turning that adapter-integrable operating path
 
 This is intended to make the transaction-side continuation path easier to use as the obvious first public adapter path instead of only a path that is integrable with a little extra coordination.
 
+The current `1.25.0` line starts turning that adapter-ready default path into a clearer adapter-complete default path:
+
+- complete-default-path summaries on top of the default operating-path path
+- compact complete-default-path bundles for direct adapter-facing complete-path posture
+- default complete-default-path summaries for the next proof-side complete-default-path run posture
+- clearer complete-default-path ids and stable complete-path carry
+
+This is intended to make the transaction-side continuation path easier to adopt as the complete public default path an outside builder can use without needing private interpretation.
+
+The current `1.26.0` line finalizes that public shape into a cleaner production-ready package:
+
+- a publishable [START_HERE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/START_HERE.md) onboarding path
+- clearer top-level README entry points for the default production flow
+- publishable contract and terminology docs carried in the package tarball
+- naming cleanup that keeps the public story anchored to `xytara` and `xoonya`
+
+This is intended to make the public transaction-side package feel like a finished production-facing product instead of a strong stack that still assumes milestone-history context.
+
 ## Package Surface
 
 The SDK is broad, but it stays organized into a few repeatable families instead of one-off surfaces.

package/SERVICE_CONTRACT.md

@@ -0,0 +1,105 @@
+# xytara Service Contract
+
+This file freezes the public service contract for `xytara`.
+
+## Public Routes
+
+Core routes:
+
+- `GET /health`
+- `GET /v1/catalog`
+- `GET /v1/catalog/summary`
+- `GET /v1/catalog/task?ref=<task_ref_or_alias>`
+- `GET /v1/catalog/workflows`
+- `GET /v1/catalog/workflow?ref=<workflow_ref_or_alias>`
+- `POST /v1/payment-quotes`
+- `POST /v1/commands/execute`
+- `POST /x402/commands/execute`
+
+Named first-class lanes:
+
+- `POST /v1/trust/handoffs/emit`
+- `POST /v1/trust/handoffs/validate`
+- `POST /v1/execution-receipts/handoffs/emit`
+- `POST /v1/execution-receipts/handoffs/validate`
+- `POST /v1/receipt-ledger/handoffs/emit`
+- `POST /v1/receipt-ledger/handoffs/validate`
+- `POST /v1/admission/preview`
+- `POST /v1/runtime/emit`
+- `POST /v1/runtime/anchor`
+- `POST /v1/runtime/emit-anchor`
+- `POST /v1/registry/register`
+- `POST /v1/anchoring/submit`
+- `POST /v1/mcp/tools/invoke`
+- `POST /x402/mcp/tools/invoke`
+
+Lifecycle and operator routes:
+
+- `GET /v1/payment-quotes`
+- `GET /v1/payment-quotes/:quote_id`
+- `GET /v1/governed-transactions`
+- `GET /v1/governed-transactions/:transaction_id`
+- `GET /v1/receipts`
+- `GET /v1/receipts/:receipt_id`
+- `GET /v1/payment-ledger`
+- `GET /v1/payment-ledger/:payment_id`
+- `GET /v1/deliveries`
+- `GET /v1/deliveries/:delivery_id`
+- `GET /v1/disputes`
+- `POST /v1/disputes`
+- `GET /v1/disputes/:dispute_id`
+- `POST /v1/disputes/:dispute_id/actions`
+- `GET /v1/refunds`
+- `POST /v1/refunds`
+- `GET /v1/refunds/:refund_id`
+- `POST /v1/refunds/:refund_id/actions`
+- `POST /v1/remediation-tickets`
+- `GET /v1/remediation-tickets`
+- `GET /v1/remediation-tickets/:ticket_id`
+- `POST /v1/remediation-tickets/:ticket_id/actions`
+- `GET /v1/reconciliation-report`
+- `GET /v1/operator-export-pack`
+- `GET /v1/operations/dashboard`
+- `GET /v1/operations/attention-records`
+
+## Error-Shape Expectations
+
+Primary error posture:
+
+- malformed or invalid requests return `400`
+- payment-required flows return `402`
+- expired quotes return `409`
+- missing routes return `404`
+- unexpected server failures return `500`
+
+Expected top-level error shapes:
+
+- generic failure:
+  - `{ "ok": false, "reason": "<message>" }`
+- payment challenge:
+  - `{ "ok": false, "payment_required": { ... } }`
+- expired quote:
+  - `{ "ok": false, "reason": "quote_expired", "quote": { ... } }`
+- not found:
+  - `{ "ok": false, "reason": "not_found", "path": "<path>" }`
+
+Named resource-view responses may return resource-specific missing reasons such as `quote_not_found` or `delivery_not_found`, but the top-level failure posture should remain predictable.
+
+## Final-Loop Verification
+
+The constitutional commerce loop for `xytara` is:
+
+1. discover
+2. quote
+3. pay or receive payment challenge
+4. execute
+5. deliver
+6. inspect
+7. prove or reference proof-compatible facts
+
+This loop is exercised through:
+
+- package verification
+- adapter verification
+- quickstart verification
+- service verification

package/START_HERE.md

@@ -0,0 +1,61 @@
+# xytara Start Here
+
+This is the shortest reliable path for understanding and using the public `xytara` package in production-facing order.
+
+## 1. Understand The Role
+
+`xytara` is the transaction-side half of the public stack.
+
+Its job is to let a caller:
+
+1. discover a machine capability
+2. quote or preview the path
+3. execute through the default transaction flow
+4. inspect result and lifecycle state
+5. hand the result into `xoonya` for proof-native completion
+
+## 2. Run The Fastest Real Example
+
+Run:
+
+```bash
+node examples/quickstart.js
+```
+
+This is the fastest way to see the intended package story end-to-end.
+
+## 3. Verify The Whole Package
+
+Run:
+
+```bash
+npm run verify:all
+```
+
+This is the production-confidence check for the published package surface.
+
+## 4. Read The Durable Contract
+
+For long-term product understanding, read:
+
+- [FINAL_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/FINAL_CONTRACT.md)
+- [SERVICE_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/SERVICE_CONTRACT.md)
+- [TERMINOLOGY.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/TERMINOLOGY.md)
+
+## 5. If You Are Building Adapters
+
+Continue with:
+
+- [adapters/AUTHORING_GUIDE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/adapters/AUTHORING_GUIDE.md)
+- [adapters/ONBOARDING_POSTURE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/adapters/ONBOARDING_POSTURE.md)
+- [adapters/THIRD_PARTY_SUBMISSION_PROCESS.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/adapters/THIRD_PARTY_SUBMISSION_PROCESS.md)
+
+## 6. Production Reading Rule
+
+If you only remember one thing, remember this:
+
+The main public path is no longer "read every milestone layer."
+
+It is:
+
+discover -> preview/quote -> execute -> inspect -> hand off to `xoonya`

package/TERMINOLOGY.md

@@ -0,0 +1,50 @@
+# xytara Terminology
+
+This file freezes the public terminology used by `xytara`.
+
+The goal is:
+
+- one public name for the repo
+- one stable commerce vocabulary
+- no private-lineage naming leakage
+
+## Public Name
+
+- repo name: `xytara`
+- package name: `xytara`
+- service name: `xytara`
+
+Use `xytara` only for this repo and its public commerce identity.
+
+## Preferred Commerce Terms
+
+Use these terms consistently:
+
+- `catalog`
+- `task`
+- `workflow`
+- `task set`
+- `quote`
+- `payment`
+- `execute`
+- `deliver`
+- `inspect`
+- `operator`
+- `adapter`
+- `settlement profile`
+- `lifecycle`
+
+## Cross-Repo Reference Rule
+
+If this repo needs to mention the other repo, use generic wording:
+
+- `the proof repo`
+- `the proof layer`
+
+Do not brand the other repo inside this repo's core public copy.
+
+## Naming Rule
+
+This repo should read like a self-contained public commerce product with an explicit proof boundary.
+
+If wording does not strengthen that outcome, keep it generic.

package/index.js

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

package/lib/commerce_client.js

@@ -4968,6 +4968,54 @@ class CommerceClient {
     });
   }
 
+  async prepareInteractionResultPackageCompleteDefaultPathSummary(continuationRef, body, options) {
+    const opts = options || {};
+    return this.runNamedTaskRoute("/v1/transaction-center/result-package-continuations/prepare/complete-default-path-summary", {
+      command: opts.command || String(continuationRef || "").trim() || "result.package.continuation.complete.default.path.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 prepareInteractionResultPackageCompleteDefaultPathBundle(continuationRef, body, options) {
+    const opts = options || {};
+    return this.runNamedTaskRoute("/v1/transaction-center/result-package-continuations/prepare/complete-default-path-bundle", {
+      command: opts.command || String(continuationRef || "").trim() || "result.package.continuation.complete.default.path.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 prepareInteractionResultPackageCompleteDefaultPathDefaultSummary(continuationRef, body, options) {
+    const opts = options || {};
+    return this.runNamedTaskRoute("/v1/transaction-center/result-package-continuations/prepare/complete-default-path-default-summary", {
+      command: opts.command || String(continuationRef || "").trim() || "result.package.continuation.complete.default.path.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 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.24.0",
+  "version": "1.26.0",
   "description": "Machine commerce SDK for discovery, quoting, execution, lifecycle inspection, and adapters.",
   "main": "index.js",
   "type": "commonjs",
@@ -39,6 +39,10 @@
     "adapters/",
     ".env.example",
     "README.md",
+    "START_HERE.md",
+    "FINAL_CONTRACT.md",
+    "SERVICE_CONTRACT.md",
+    "TERMINOLOGY.md",
     "LICENSE",
     "NOTICE"
   ],

package/server.js

@@ -1880,6 +1880,58 @@ function buildPreparedContinuationDefaultOperatingPathRunSummary(portableHandoff
   };
 }
 
+function buildPreparedContinuationAdapterCompleteDefaultPathSummary(portableHandoff, continuation) {
+  const operatingPath = buildPreparedContinuationDefaultOperatingPathRunSummary(portableHandoff, continuation);
+  return {
+    ok: operatingPath.ok === true,
+    default_operating_path_ref: operatingPath.default_operating_path_ref || null,
+    complete_default_path_ref: operatingPath.default_operating_path_ref
+      ? `complete.${operatingPath.default_operating_path_ref}`
+      : null,
+    complete_default_path_ids: Array.isArray(operatingPath.stable_default_operating_path_ids)
+      ? operatingPath.stable_default_operating_path_ids
+      : [],
+    complete_default_path_carry: operatingPath.default_operating_path_carry || {},
+    adapter_complete_by_default: operatingPath.operating_path_ready_by_default === true,
+    next_surface: "/v1/proof-center/result-package-handoff/review/complete-default-path"
+  };
+}
+
+function buildPreparedContinuationAdapterCompleteDefaultPathBundle(portableHandoff, continuation) {
+  const handoff = portableHandoff && typeof portableHandoff === "object" ? portableHandoff : {};
+  const summary = buildPreparedContinuationAdapterCompleteDefaultPathSummary(portableHandoff, continuation);
+  return {
+    ok: true,
+    complete_default_path_summary: summary,
+    complete_default_path_template: {
+      ok: true,
+      complete_default_path_ref: summary.complete_default_path_ref || null,
+      target_surface: "/v1/proof-center/result-package-handoff/review/complete-default-path",
+      request_template: {
+        handoff_bundle: handoff
+      },
+      stable_boundary_ids: Array.isArray(summary.complete_default_path_ids) ? summary.complete_default_path_ids : []
+    }
+  };
+}
+
+function buildPreparedContinuationDefaultCompletePathRunSummary(portableHandoff, continuation) {
+  const completePath = buildPreparedContinuationAdapterCompleteDefaultPathSummary(portableHandoff, continuation);
+  return {
+    ok: completePath.ok === true,
+    complete_default_path_ref: completePath.complete_default_path_ref || null,
+    default_complete_default_path_ref: completePath.complete_default_path_ref
+      ? `default.${completePath.complete_default_path_ref}`
+      : null,
+    stable_default_complete_default_path_ids: Array.isArray(completePath.complete_default_path_ids)
+      ? completePath.complete_default_path_ids
+      : [],
+    default_complete_default_path_carry: completePath.complete_default_path_carry || {},
+    complete_default_path_ready: completePath.adapter_complete_by_default === true,
+    next_surface: "/v1/proof-center/result-package-handoff/review/complete-default-path-run"
+  };
+}
+
 function buildInteractionResultPackageContinuationRequestTemplate(portableHandoff, continuation) {
   const handoff = portableHandoff && typeof portableHandoff === "object" ? portableHandoff : {};
   return {
@@ -3970,6 +4022,99 @@ async function routeRequest(req, res) {
     return;
   }
 
+  if (req.method === "POST" && url.pathname === "/v1/transaction-center/result-package-continuations/prepare/complete-default-path-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, buildPreparedContinuationAdapterCompleteDefaultPathSummary(portableHandoff, continuation));
+    return;
+  }
+
+  if (req.method === "POST" && url.pathname === "/v1/transaction-center/result-package-continuations/prepare/complete-default-path-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, buildPreparedContinuationAdapterCompleteDefaultPathBundle(portableHandoff, continuation));
+    return;
+  }
+
+  if (req.method === "POST" && url.pathname === "/v1/transaction-center/result-package-continuations/prepare/complete-default-path-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, buildPreparedContinuationDefaultCompletePathRunSummary(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();