xytara 3.1.0 → 3.1.2

package/FINAL_CONTRACT.md

@@ -1,498 +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.
-
-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.
+# 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.