xytara 1.25.0 → 1.27.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:
@@ -253,6 +281,15 @@ The current `1.25.0` line starts turning that adapter-ready default path into a
 
 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.
@@ -569,6 +606,24 @@ Primary service routes:
 - `POST /v1/registry/packs/anchor`
 - `POST /v1/anchoring/submit`
 - `POST /v1/anchoring/packs/preview`
+- `GET /v1/coordination-center`
+- `GET /v1/coordination-center/summary`
+- `GET /v1/zones`
+- `GET /v1/zones/compatibility-profiles`
+- `GET /v1/zones/:zoneId/constitution`
+- `POST /v1/coordination-center/interpretation-handoff/validate`
+- `POST /v1/coordination-center/handshake-preview`
+- `POST /v1/coordination-center/cross-zone-preview`
+- `POST /v1/coordination-center/admission-case-projection`
+- `POST /v1/coordination-center/admission-case-bundle`
+- `POST /v1/coordination-center/operator-view`
+- `POST /v1/coordination-center/admin-view`
+- `POST /v1/coordination-center/admission-ops-pack`
+- `POST /v1/coordination-center/admission-workflow-pack`
+- `POST /v1/coordination-center/coordination-pack`
+- `POST /v1/coordination-center/review-link`
+- `GET /v1/coordination-center/zones-dashboard`
+- `POST /v1/coordination-center/zones-dashboard-pack`
 - `POST /v1/mcp/tools/invoke`
 - `GET /v1/payment-quotes`
 - `GET /v1/payment-quotes/:quote_id`
@@ -599,6 +654,73 @@ Primary service routes:
 - `GET /v1/operator-export-pack`
 - `GET /v1/operations/dashboard`
 - `GET /v1/operations/attention-records`
+- `GET /v1/operator-shell`
+- `GET /v1/operator-shell/summary`
+- `POST /v1/operator-shell/summary`
+- `POST /v1/operator-shell/workflow-pack`
+- `POST /v1/operator-shell/admin-pack`
+- `GET /v1/agent-accounts`
+- `POST /v1/agent-accounts`
+- `GET /v1/agent-accounts/:account_id`
+- `POST /v1/economics/budgets`
+- `POST /v1/economics/budgets/:budget_id/status`
+- `POST /v1/economics/agents`
+- `POST /v1/economics/agents/:agent_id/status`
+- `POST /v1/economics/receipts`
+- `POST /v1/economics/receipts/:receipt_id/lifecycle`
+- `POST /v1/economics/receipts/:receipt_id/operator-action`
+- `POST /v1/economics/allocations/mint`
+- `POST /v1/economics/allocations/reverse`
+- `POST /v1/economics/rails/credits/preview`
+- `POST /v1/economics/rails/credits/apply`
+- `POST /v1/economics/receipt-ledger/validate`
+- `POST /v1/economics/interpretation-handoff`
+- `POST /v1/economics/markets/preview`
+- `POST /v1/economics/markets/workflow-pack`
+- `POST /v1/economics/markets/signoff-pack`
+- `POST /v1/economics/markets/coordination-pack`
+- `GET /v1/economics/accounts/:account_id/budgets`
+- `GET /v1/economics/accounts/:account_id/agents`
+- `GET /v1/economics/accounts/:account_id/receipts`
+- `GET /v1/economics/accounts/:account_id`
+- `GET /v1/economics/accounts/:account_id/operator-view`
+- `GET /v1/economics/accounts/:account_id/operator-dashboard`
+- `GET /v1/economics/accounts/:account_id/treasury-summary`
+- `GET /v1/economics/accounts/:account_id/ledger-export`
+- `GET /v1/economics/accounts/:account_id/treasury-drilldown`
+- `GET /v1/economics/accounts/:account_id/reconciliation-pack`
+- `GET /v1/economics/accounts/:account_id/treasury-workflow-pack`
+- `GET /v1/economics/accounts/:account_id/treasury-signoff-pack`
+- `GET /v1/economics/accounts/:account_id/policy-summary`
+- `GET /v1/economics/accounts/:account_id/rail-summary`
+- `GET /v1/economics/accounts/:account_id/rail-workflow-pack`
+- `GET /v1/economics/accounts/:account_id/rail-signoff-pack`
+- `POST /v1/economics/jobs/:job_id/operator-action`
+- `GET /v1/economics/evidence/receipts/:receipt_ref`
+- `GET /v1/economics/evidence/jobs/:job_id`
+- `GET /v1/economics/integration/jobs/:job_id`
+
+The Wave C coordination carry-over line adds a bounded coordination center on top of the public transaction spine:
+
+- zone discovery, compatibility profiles, and constitution lookup
+- interpretation-handoff validation and cross-zone handshake preview
+- cross-zone admission-case projection and portable case-bundle export
+- coordination operator/admin views plus explicit review-linkage into governance and proof follow-through
+- admission ops/workflow packs, coordination packs, and zones dashboard packaging
+
+The Wave D adapter-breadth line broadens the bundled public integration surface as well:
+
+- additional built-in protocol surfaces for `a2a`, `acp`, `mqtt`, `grpc`, `kafka`, `nats`, and `ros2`
+- additional built-in execution-front surfaces for `langchain`, `langgraph`, `semantic_kernel`, `autogen`, `crewai`, and `llamaindex`
+- broader bundled payment and identity breadth through `mpp` and `erc8004`-oriented public integration surfaces
+
+The Wave F shell carry-over line adds a bounded operator shell inside public `xytara`:
+
+- self-serve agent account issuance for the public runtime path
+- a unified operator shell summary across operations, economics, and coordination
+- compact workflow/admin shell exports that point cleanly into proof-side follow-through when needed
+
+This keeps the public product centered on `naxytra` while recovering the useful operator-shell lineage as a built-in `xytara` capability instead of a separate branded surface.
 
 ## Verification