xytara 1.26.0 → 2.0.0

package/.env.example

@@ -1,3 +1,23 @@
 XYTARA_HOST=127.0.0.1
 XYTARA_PORT=4320
 XYTARA_BASE_URL=http://127.0.0.1:4320
+XYTARA_PAYMENT_VERIFICATION_MODE=presence
+XYTARA_PAYMENT_MAX_AGE_SECONDS=300
+XYTARA_WALLET_REGISTRY_JSON=[]
+XYTARA_TREASURY_DESTINATION_ID=
+XYTARA_TREASURY_DESTINATION_KIND=
+XYTARA_TREASURY_ACCOUNT_ID=
+XYTARA_TREASURY_EXTERNAL_REF=
+XYTARA_TREASURY_DESTINATIONS_JSON={}
+XYTARA_BSV_TERANODE_NETWORK=mainnet
+XYTARA_BSV_TERANODE_RPC_URL=
+XYTARA_BSV_TERANODE_MODE=opreturn
+XYTARA_BSV_TERANODE_REQUIRED_CONFIRMATIONS=1
+XYTARA_BSV_TERANODE_MERCHANT_ADDRESS=
+XYTARA_BSV_TERANODE_MERCHANT_PAYMAIL=
+XYTARA_BSV_TERANODE_MERCHANT_LABEL=naxytra-runtime
+XYTARA_BSV_TERANODE_USE_METANET=false
+XYTARA_BSV_TERANODE_SATS_PER_USD_CENT=100
+XYTARA_BSV_TERANODE_SETTLEMENT_RUNTIME_MODE=mock
+XYTARA_CREDIT_BRIDGE_BEARER_TOKEN=
+XYTARA_ACCOUNT_AUTH_BEARER_TOKEN=

package/BSV_TERANODE_SETUP.md

@@ -0,0 +1,76 @@
+# BSV Teranode Setup
+
+`xytara` now treats `bsv_teranode` as the native first-party settlement base for the default machine payment path.
+
+Use this guide when you want the public package to emit BSV/Teranode-aware payment and settlement posture instead of only generic treasury bookkeeping.
+
+## What This Gives You
+
+- quotes expose native `bsv_teranode` settlement hints
+- signed payment payloads can carry BSV/Teranode merchant details and settlement reference data
+- accepted payments and resulting receipts preserve BSV/Teranode settlement metadata
+- treasury routing can point directly at a BSV/Teranode merchant address or paymail
+
+This is still a runtime-side settlement contract, not a bundled bank or broadcaster. Real external custody still depends on the BSV/Teranode infrastructure you configure behind it.
+
+## Recommended Environment
+
+```env
+XYTARA_PAYMENT_VERIFICATION_MODE=local_signed
+XYTARA_BSV_TERANODE_NETWORK=mainnet
+XYTARA_BSV_TERANODE_MODE=opreturn
+XYTARA_BSV_TERANODE_REQUIRED_CONFIRMATIONS=1
+XYTARA_BSV_TERANODE_MERCHANT_ADDRESS=
+XYTARA_BSV_TERANODE_MERCHANT_PAYMAIL=
+XYTARA_BSV_TERANODE_MERCHANT_LABEL=naxytra-runtime
+XYTARA_BSV_TERANODE_USE_METANET=false
+XYTARA_BSV_TERANODE_SATS_PER_USD_CENT=100
+XYTARA_BSV_TERANODE_SETTLEMENT_RUNTIME_MODE=mock
+```
+
+Optional:
+
+- `XYTARA_BSV_TERANODE_RPC_URL`
+  - present when you have a Teranode-facing endpoint available and want the runtime to know that the live transport is configured
+
+## Merchant Destination Routing
+
+If you set:
+
+- `XYTARA_BSV_TERANODE_MERCHANT_ADDRESS`
+or
+- `XYTARA_BSV_TERANODE_MERCHANT_PAYMAIL`
+
+then `xytara` can derive a BSV/Teranode treasury destination automatically for `bsv_teranode` settlement quotes.
+
+If you need more explicit destination control, use:
+
+- `XYTARA_TREASURY_DESTINATIONS_JSON`
+
+with a `bsv_teranode` entry.
+
+## Runtime Behavior
+
+For a native `bsv_teranode` quote:
+
+- settlement mode defaults to `bsv_teranode`
+- quote settlement hints include:
+  - rail
+  - network
+  - merchant address or paymail
+  - amount in satoshis
+  - settlement reference
+- signed client payment payloads can carry the same BSV/Teranode hints back to the runtime
+- resulting transactions/receipts preserve BSV/Teranode settlement metadata for later reconciliation and proof follow-through
+
+For live settlement follow-through after payment acceptance, use:
+
+- `GET /v1/settlement/bsv-teranode`
+- `GET /v1/settlement/bsv-teranode/:settlement_id`
+- `POST /v1/settlement/bsv-teranode/:settlement_id/submit`
+- `POST /v1/settlement/bsv-teranode/:settlement_id/refresh`
+
+## Notes
+
+- `bsv_teranode` is the canonical public settlement name
+- Metanet remains optional support infrastructure, not a required dependency

package/README.md

@@ -31,16 +31,125 @@ If you are building adapters, continue with:
 - [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)
 
+If you are wiring the native BSV settlement base, continue with:
+
+- [BSV_TERANODE_SETUP.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/BSV_TERANODE_SETUP.md)
+- [REAL_PAYMENT_SETUP.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/REAL_PAYMENT_SETUP.md)
+
+If you are wiring the first human checkout path, continue with:
+
+- [HUMAN_CHECKOUT_AND_RUNTIME_BRIDGE_PATTERN.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/HUMAN_CHECKOUT_AND_RUNTIME_BRIDGE_PATTERN.md)
+- [RUNTIME_BRIDGE_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/RUNTIME_BRIDGE_CONTRACT.md)
+- [HOSTED_CHECKOUT_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/HOSTED_CHECKOUT_CONTRACT.md)
+- [CHECKOUT_TO_CREDITS_AND_DISPATCH_PLAN.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/CHECKOUT_TO_CREDITS_AND_DISPATCH_PLAN.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
+3. spend existing credits first when the caller prefers the reusable account path
+4. fall back to direct machine payment when credits are not available or not preferred
+5. execute through the default machine path
+6. inspect the transaction-side result and lifecycle state
+7. hand the result into `xoonya`
+8. review and run the proof-side completion path
+
+The machine-facing execution surface now also supports a first-class reusable balance posture:
+
+- set `payment_preference: "credits_first"` on `POST /v1/commands/execute` when the caller wants to spend existing account credits before requesting a fresh payment
+- default spend posture is `open_spend`: if the funded caller can pay, `xytara` should spend and execute without extra runtime ceremony
+- bounded spend posture is optional and only applies when the caller intentionally uses an `agent_id` and/or `budget_id`
+- inspect account credit state with `GET /v1/economics/accounts/:account_id/credit-balance`
+- inspect deterministic usage metering state with `GET /v1/economics/accounts/:account_id/metering-summary`, `GET /v1/economics/accounts/:account_id/usage-meters`, and `GET /v1/economics/accounts/:account_id/usage-meters/:usage_meter_id`
+- expect reconciliation and operator-export surfaces to carry the same metering trail for audit visibility
+- export a canonical cross-repo economic handoff bundle with `POST /v1/economics/handoff-bundles/economic-consequence`
+- expect `POST /v1/transaction-center/result-packages/export` and result-package continuation export/prepare surfaces to auto-carry that same canonical economic bundle whenever the execution path spent credits and produced a deterministic usage meter
+- inspect pack-backed entitlement pools with `GET /v1/economics/accounts/:account_id/entitlements` and `GET /v1/economics/accounts/:account_id/entitlements/summary`
+- inspect low-balance and replenishment posture with `GET /v1/economics/accounts/:account_id/entitlements/replenishment-summary`
+- inspect one pool’s replenishment view with `GET /v1/economics/accounts/:account_id/entitlements/:entitlement_id/replenishment-view`
+- inspect effective account spend posture with `GET /v1/economics/accounts/:account_id/policy-pack`
+- inspect effective agent spend posture with `GET /v1/economics/accounts/:account_id/agents/:agent_id/policy-view`
+- preflight a proposed credit spend with `POST /v1/economics/rails/credits/preview-spend`
+- record explicit bounded credit consumption with `POST /v1/economics/rails/credits/consume`
+- issue externally verified top-up grants with `POST /v1/credit-bridge/grants`
+- inspect externally issued grants with `GET /v1/credit-bridge/grants` and `GET /v1/credit-bridge/grants/:grant_id`
+- discover reusable funding posture through `GET /v1/credit-packs`, `GET /v1/credit-packs/summary`, and `GET /v1/credit-pack?ref=<pack_id>`
+- external grant callers can now fund a named public pack such as `credits.agent`, and `xytara` will validate and record that pack identity directly
+
+The SDK now exposes the same posture directly for agent callers:
+
+- `client.getCreditPackSummary()`
+- `client.getCreditBalance(accountId)`
+- `client.previewUsageMetering({ account_id, task_ref?, workflow_ref?, units? })`
+- `client.getUsageMeteringSummary(accountId)`
+- `client.listUsageMeters(accountId)`
+- `client.getUsageMeter(usageMeterId, accountId?)`
+- `client.exportEconomicConsequenceHandoffBundle({ account_id, usage_meter_id, credit_spend_id, meter_profile_ref? })`
+- `client.listEntitlements(accountId)`
+- `client.getEntitlementSummary(accountId)`
+- `client.getEntitlement(entitlementId, accountId?)`
+- `client.getEntitlementReplenishmentSummary(accountId)`
+- `client.getEntitlementReplenishmentView(entitlementId, accountId?)`
+- `client.updateEntitlementReplenishmentPreference(entitlementId, payload, accountId?)`
+- `client.previewCreditSpend({ account_id, task_ref, units, agent_id?, budget_id? })`
+- `client.getCreditSpendPolicyPack(accountId)`
+- `client.getAgentCreditSpendPolicyView(agentId, accountId?)`
+- `client.executeWithCreditsFirst(payload, options?)`
+
+The runtime now also supports a bounded delegated spend path for repeat-use automation:
+
+- issue a spend credential through `POST /v1/account-auth/spend-credentials`
+- use that credential as `authorization: Bearer <spend_credential>`
+- optionally bind the credential to a `pack_id` or `entitlement_id` when spend should stay inside one value pool
+- execute through the same `credits_first` path without sharing broad operator secrets
+- revoke it through `POST /v1/account-auth/spend-credentials/:credential_id/revoke`
+
+SDK helpers now include:
+
+- `client.createSpendCredential(payload, { bearerToken })`
+- `client.listSpendCredentials(filters?, { bearerToken? })`
+- `client.getSpendCredential(credentialId, { bearerToken? })`
+- `client.revokeSpendCredential(credentialId, payload, { bearerToken })`
+- `client.executeWithSpendCredential(payload, { spendToken })`
+
+This keeps one-off usage and repeat usage on the same public spine:
+
+- direct pay when the caller is using the stack once
+- credit balance when the caller is already funded and wants low-friction repeat execution
+- optional agent and budget controls can still bound that spend without changing the execution surface
+
+It also keeps the human checkout boundary clean:
+
+- an external merchant-facing system can verify a purchase and issue a bounded credit grant into `xytara`
+- `xytara` records the granted value and consumes it during later runtime operations
+- the runtime does not need to absorb provider-specific checkout semantics to support repeat usage
+- in production, `POST /v1/credit-bridge/grants` should normally be protected with `XYTARA_CREDIT_BRIDGE_BEARER_TOKEN`
+
+The first human-facing convenience path now follows a parallel narrow route:
+
+1. create hosted purchase intent
+2. create checkout session
+3. normalize payment success
+4. issue credits or entitlement
+5. dispatch through the runtime bridge when needed
+6. converge back into the same `xytara` and `xoonya` spine
+
+The first direct hosted execution path now also has a public runtime bridge surface:
+
+- `POST /v1/runtime-bridge/dispatch`
+- `GET /v1/runtime-bridge/dispatches`
+- `GET /v1/runtime-bridge/dispatches/:request_id`
+
+The hosted payment side is intentionally asymmetric:
+
+- pay-in should be simple and fast
+- execution and delivery should follow immediately after valid payment
+- refund or reversal requests should enter review first
+- no autonomous payout path should exist outside explicit operator review and completion
+
+The operator shell now also carries hosted checkout visibility so purchase, dispatch, and refund-review load can be monitored from the same public control surface.
 
 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.
 
@@ -98,7 +207,7 @@ The package and service also expose a default transaction center surface so the
 
 - default protocol lane: `mcp`
 - default payment protocol: `x402`
-- default settlement center: built-in chain settlement across the canonical bundled settlement modes
+- default settlement center: built-in chain settlement with `bsv_teranode` as the native default across the canonical bundled settlement modes
 - default treasury landing posture: account treasury destination by settlement mode
 
 That same default center is also reflected in direct helper paths for default MCP usage, so the default path can be previewed or quoted without repeating the full integration-selection story each time.
@@ -560,6 +669,13 @@ Environment example:
 
 - [`.env.example`](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/.env.example)
 
+Production payment note:
+
+- set `XYTARA_PAYMENT_VERIFICATION_MODE=local_signed` to enforce verifiable signed payment acceptance instead of plain header presence
+- provide buyer wallet verification material through `XYTARA_WALLET_REGISTRY_JSON` or `XYTARA_WALLET_REGISTRY_PATH`
+- set `XYTARA_TREASURY_DESTINATION_ID` and related treasury env vars so accepted payments land in your merchant treasury posture instead of the default local account placeholder
+- built-in `x402` is the admission lane; real external payout/custody still depends on the payment rail and treasury destination you configure behind that lane
+
 Primary service routes:
 
 - `GET /health`
@@ -606,6 +722,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`
@@ -636,6 +770,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
 

package/REAL_PAYMENT_SETUP.md

@@ -0,0 +1,101 @@
+# Real Payment Setup
+
+This guide explains how to move `xytara` from local placeholder payment acceptance into a production-usable payment posture.
+
+## What Changed
+
+`xytara` now supports two payment-acceptance modes:
+
+- `presence`
+  - development/demo mode
+  - payment headers are required, but not cryptographically verified
+
+- `local_signed`
+  - production-oriented built-in mode
+  - signed payment payloads are cryptographically verified against a configured wallet registry
+  - quote replay and nonce replay are blocked
+  - accepted payments are routed into your configured merchant treasury destination posture
+
+## Minimum Production-Oriented Configuration
+
+Set these environment variables:
+
+```env
+XYTARA_PAYMENT_VERIFICATION_MODE=local_signed
+XYTARA_PAYMENT_MAX_AGE_SECONDS=300
+XYTARA_WALLET_REGISTRY_JSON=[{"wallet_id":"<wallet-id>","secret":"<shared-secret>","account_id":"<account-id>"}]
+XYTARA_TREASURY_DESTINATION_ID=merchant_treasury_primary
+XYTARA_TREASURY_DESTINATION_KIND=merchant_treasury
+XYTARA_TREASURY_ACCOUNT_ID=merchant-main
+XYTARA_TREASURY_EXTERNAL_REF=merchant-usd-main
+```
+
+You can also load the wallet registry and treasury map from files through:
+
+- `XYTARA_WALLET_REGISTRY_PATH`
+- `XYTARA_TREASURY_DESTINATIONS_PATH`
+
+## What This Gives You
+
+With `local_signed` enabled:
+
+- `POST /x402/commands/execute` challenges for payment
+- the client signs the exact payment payload
+- if the quote is using native `bsv_teranode`, the payment payload can also carry BSV/Teranode merchant and settlement-reference hints
+- the server verifies:
+  - wallet registration
+  - HMAC signature validity
+  - quote id
+  - amount
+  - currency
+  - settlement binding
+  - timestamp freshness
+  - nonce uniqueness
+- accepted payments are recorded into:
+  - `payment-ledger`
+  - `treasury-summary`
+  - `rail-summary`
+  - `reconciliation-report`
+
+## What It Does Not Do By Itself
+
+The built-in path gives you verifiable payment acceptance and merchant treasury routing posture inside `xytara`.
+
+It does not by itself:
+
+- move fiat into a bank account
+- broadcast on-chain settlement
+- replace an external processor or custodian
+
+For actual external custody, connect `xytara` to the real rail you want behind the payment and settlement boundary.
+
+That is where:
+
+- your payment rail integration
+- your settlement integration
+- your merchant treasury destination
+
+become the actual real-world landing point for accepted funds.
+
+## Best Current Public Model
+
+Use the stack like this:
+
+- `x402` route = payment admission lane
+- `local_signed` = real verifiable acceptance posture in the public package
+- `bsv_teranode` = native first-party settlement base when you want the public stack to expose BSV/Teranode-aware payout posture
+- configured treasury destination = merchant-facing landing posture in the runtime
+- external rail / settlement integration = actual custody and payout layer
+
+If you want the native BSV path specifically, continue with [BSV_TERANODE_SETUP.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/BSV_TERANODE_SETUP.md).
+
+## Operator Visibility
+
+After acceptance, inspect:
+
+- `GET /v1/payment-ledger`
+- `GET /v1/economics/accounts/:account_id/treasury-summary`
+- `GET /v1/economics/accounts/:account_id/rail-summary`
+- `GET /v1/reconciliation-report`
+
+These tell you what was accepted, where it was routed in the runtime model, and what still needs reconciliation against the underlying real-world rail.