xytara 3.1.16 → 3.2.0

package/FINAL_CONTRACT.md

@@ -1,498 +0,0 @@
-# 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.
-
-That means:
-
-- prior SDK and service experiments are design history, not public obligations
-- useful capability should be preserved where it strengthens the final product
-- older 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 Across Earlier Product Iterations
-
-From earlier product iterations, 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 implementation labels and temporary 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/PARTNER_READY_PATH.md

@@ -1,71 +0,0 @@
-# xytara Partner-Ready Path
-
-Use this path when you want to evaluate `xytara` as an external runtime and commerce integration surface without relying on private project history.
-
-## What this path is for
-
-This is the shortest partner-facing route for teams that need to:
-
-- evaluate the runtime contract quickly
-- decide whether the reusable credits and direct-pay posture fit their product
-- understand how a neutral third-party adapter reaches reviewable maturity
-- leave with one concrete demo path, one contract path, and one promotion path
-
-## Recommended reading order
-
-1. Read `START_HERE.md`.
-2. Read `CARRIED_HANDOFF_DEMO.md`.
-3. Read `ADAPTER_PARTNER_PATH.md`.
-4. Read `adapters/THIRD_PARTY_SUBMISSION_PROCESS.md`.
-5. Read `SUPABASE_RUNTIME_STATE_SETUP.md` if your deployment does not have persistent disk.
-
-## Recommended first commands
-
-Run these from a cloned `xytara` repository:
-
-```bash
-node examples/quickstart.js
-npm run verify:adapters
-npm run verify:examples
-npm run verify:release-candidate
-node scripts/registry_cli.js review-bundle --file adapters/examples/minimal-third-party-execution.submission-bundle.json
-node scripts/registry_cli.js promotion-readiness --integration partner.execution.minimal_echo
-```
-
-## Recommended first surfaces
-
-- `/v1/release-center/summary`
-- `/v1/adapter-pack/summary`
-- `/v1/adapter-promotion/summary`
-- `/v1/integrations/promotion-readiness`
-- `/v1/runtime/durability`
-
-## First success standard
-
-First success is not "become production default immediately."
-
-First success is:
-
-1. run one end-to-end machine path
-2. understand the default commerce posture
-3. produce one reviewable integration artifact bundle
-4. see promotion blockers as explicit data
-5. understand the proof-side handoff into `xoonya`
-
-## Production readiness rule
-
-If you depend on grants, entitlements, or usage meters surviving restart, do not leave runtime durability implicit.
-
-Use one of these:
-
-- persistent disk plus `XYTARA_STATE_FILE`
-- Supabase-backed state via `SUPABASE_RUNTIME_STATE_SETUP.md`
-
-## Hand-off rule
-
-If an outside team leaves this path with only four references, they should be these:
-
-- `START_HERE.md`
-- `CARRIED_HANDOFF_DEMO.md`
-- `ADAPTER_PARTNER_PATH.md`
-- `adapters/THIRD_PARTY_SUBMISSION_PROCESS.md`

package/PUBLIC_DEMO_SCRIPT.md

@@ -1,78 +0,0 @@
-# xytara Public Demo Script
-
-Use this script when you need a short external-facing walkthrough of `xytara` that does not depend on private project history.
-
-## Goal
-
-Show the runtime side of the public stack in one compact flow:
-
-1. package is live
-2. runtime path is understandable
-3. partner posture is explicit
-4. proof-side continuation exists
-
-## Recommended order
-
-### 1. Release posture
-
-Run:
-
-```bash
-xytara-release --center --summary
-xytara-release --candidate --summary
-```
-
-Or inspect:
-
-- `/v1/release-center/summary`
-- `/v1/release-candidate/summary`
-
-### 2. Runtime durability posture
-
-Inspect:
-
-- `/v1/runtime/durability`
-
-Key sentence to say out loud:
-
-`xytara` treats durability as visible operational posture, not a hidden implementation detail.
-
-### 3. Public runtime walkthrough
-
-Run:
-
-```bash
-node examples/partner_launch_walkthrough.js
-```
-
-Then, if you want the broader package tour:
-
-```bash
-node examples/quickstart.js
-```
-
-### 4. Partner adoption path
-
-Open:
-
-- `PARTNER_READY_PATH.md`
-- `ADAPTER_PARTNER_PATH.md`
-
-Key sentence to say out loud:
-
-Outside teams can reach a reviewable adapter posture without private exceptions.
-
-### 5. Proof continuation
-
-Open:
-
-- `CARRIED_HANDOFF_DEMO.md`
-- `WHY_XYTARA_XOONYA.md`
-
-Key sentence to say out loud:
-
-`xytara` finishes the transaction-side path and hands cleanly into `xoonya` for proof-native completion.
-
-## Good ending line
-
-`xytara` is the public machine-commerce runtime: discover, fund, execute, inspect, and carry forward into proof.