xytara 1.27.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`

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.

package/SERVICE_CONTRACT.md

@@ -12,10 +12,25 @@ Core routes:
 - `GET /v1/catalog/task?ref=<task_ref_or_alias>`
 - `GET /v1/catalog/workflows`
 - `GET /v1/catalog/workflow?ref=<workflow_ref_or_alias>`
+- `GET /v1/credit-packs`
+- `GET /v1/credit-packs/summary`
+- `GET /v1/credit-pack?ref=<pack_id>`
+- `GET /v1/account-auth/spend-credentials`
+- `POST /v1/account-auth/spend-credentials`
+- `GET /v1/account-auth/spend-credentials/:credential_id`
+- `POST /v1/account-auth/spend-credentials/:credential_id/revoke`
 - `POST /v1/payment-quotes`
 - `POST /v1/commands/execute`
 - `POST /x402/commands/execute`
 
+Operational note:
+
+- for production acceptance, `POST /x402/commands/execute` and `POST /x402/mcp/tools/invoke` should normally run with `XYTARA_PAYMENT_VERIFICATION_MODE=local_signed` or a stronger verifier mode
+- accepted payments then flow into payment-ledger, treasury-summary, rail-summary, and reconciliation surfaces
+- the default first-party settlement posture is now `bsv_teranode`, and `x402` challenge quotes carry native BSV/Teranode settlement hints when that default path is in use
+- in production, `POST /v1/credit-bridge/grants` should normally require `authorization: Bearer <token>` backed by `XYTARA_CREDIT_BRIDGE_BEARER_TOKEN`
+- in production, spend-credential issuance/revoke should normally require `authorization: Bearer <token>` backed by `XYTARA_ACCOUNT_AUTH_BEARER_TOKEN`
+
 Named first-class lanes:
 
 - `POST /v1/trust/handoffs/emit`
@@ -50,6 +65,10 @@ Named first-class lanes:
 - `POST /v1/coordination-center/zones-dashboard-pack`
 - `POST /v1/mcp/tools/invoke`
 - `POST /x402/mcp/tools/invoke`
+- `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`
 
 Lifecycle and operator routes:
 
@@ -98,6 +117,26 @@ Lifecycle and operator routes:
 - `POST /v1/economics/allocations/reverse`
 - `POST /v1/economics/rails/credits/preview`
 - `POST /v1/economics/rails/credits/apply`
+- `POST /v1/economics/metering/preview`
+- `POST /v1/economics/handoff-bundles/economic-consequence`
+- `POST /v1/economics/rails/credits/preview-spend`
+- `POST /v1/economics/rails/credits/consume`
+- `GET /v1/credit-bridge/grants`
+- `POST /v1/credit-bridge/grants`
+- `GET /v1/credit-bridge/grants/:grant_id`
+- `GET /v1/checkout/purchase-intents`
+- `POST /v1/checkout/purchase-intents`
+- `GET /v1/checkout/purchase-intents/:purchase_intent_id`
+- `GET /v1/checkout/purchase-intents/:purchase_intent_id/sessions`
+- `POST /v1/checkout/purchase-intents/:purchase_intent_id/session`
+- `GET /v1/checkout/purchase-intents/:purchase_intent_id/refunds`
+- `POST /v1/checkout/purchase-intents/:purchase_intent_id/refund-request`
+- `GET /v1/checkout/sessions/:checkout_session_id`
+- `POST /v1/checkout/events/normalize`
+- `GET /v1/checkout/events/:event_id`
+- `POST /v1/runtime-bridge/dispatch`
+- `GET /v1/runtime-bridge/dispatches`
+- `GET /v1/runtime-bridge/dispatches/:request_id`
 - `POST /v1/economics/receipt-ledger/validate`
 - `POST /v1/economics/interpretation-handoff`
 - `POST /v1/economics/markets/preview`
@@ -108,6 +147,16 @@ Lifecycle and operator routes:
 - `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/credit-balance`
+- `GET /v1/economics/accounts/:account_id/metering-summary`
+- `GET /v1/economics/accounts/:account_id/usage-meters`
+- `GET /v1/economics/accounts/:account_id/usage-meters/:usage_meter_id`
+- `GET /v1/economics/accounts/:account_id/entitlements`
+- `GET /v1/economics/accounts/:account_id/entitlements/summary`
+- `GET /v1/economics/accounts/:account_id/entitlements/replenishment-summary`
+- `GET /v1/economics/accounts/:account_id/entitlements/:entitlement_id`
+- `GET /v1/economics/accounts/:account_id/entitlements/:entitlement_id/replenishment-view`
+- `POST /v1/economics/accounts/:account_id/entitlements/:entitlement_id/replenishment-preference`
 - `GET /v1/economics/accounts/:account_id/operator-view`
 - `GET /v1/economics/accounts/:account_id/operator-dashboard`
 - `GET /v1/economics/accounts/:account_id/treasury-summary`
@@ -117,6 +166,8 @@ Lifecycle and operator routes:
 - `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/policy-pack`
+- `GET /v1/economics/accounts/:account_id/agents/:agent_id/policy-view`
 - `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`
@@ -154,11 +205,89 @@ 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
+3. spend credits first when the caller chooses the reusable-balance path
+4. otherwise pay or receive payment challenge
+5. execute
+6. deliver
+7. inspect
+8. prove or reference proof-compatible facts
+
+Credit-first execution should use:
+
+1. fund an account through credit issuance or hosted checkout
+2. inspect `GET /v1/economics/accounts/:account_id/credit-balance`
+3. default to `open_spend`: if the funded caller can pay, the runtime should spend and execute without extra policy ceremony
+4. call `POST /v1/commands/execute` with `payment_preference: "credits_first"`
+5. optionally include `agent_id` and/or `budget_id` only when runtime spend should stay inside explicit policy bounds
+6. treat agent and budget controls as optional bounded-spend posture, not as the default burden on every caller
+7. consume credits on successful execution
+8. receive `402 insufficient_credits` plus a quote when the balance is not enough
+9. receive a bounded policy failure when agent or budget controls deny the spend
+10. fall back to direct payment or top up credits without changing the execution surface
+
+Deterministic usage metering should use:
+
+1. preview the expected unit profile through `POST /v1/economics/metering/preview`
+2. let successful credit spend create a linked usage-meter record automatically
+3. inspect account-level metering state through `GET /v1/economics/accounts/:account_id/metering-summary`
+4. inspect concrete meter records through `GET /v1/economics/accounts/:account_id/usage-meters`
+5. expect reconciliation and operator-export surfaces to expose the same metering trail for audit and operator review
+6. export the same deterministic consequence as a canonical cross-repo handoff bundle through `POST /v1/economics/handoff-bundles/economic-consequence`
+7. expect `POST /v1/transaction-center/result-packages/export` and result-package continuation run/prepare surfaces to auto-carry that same canonical bundle whenever credit-first execution produced the linked usage meter and credit spend
+
+External top-up and pack issuance should use:
+
+1. verify the human-facing purchase outside the runtime
+2. issue a bounded grant through `POST /v1/credit-bridge/grants`
+3. inspect grants through `GET /v1/credit-bridge/grants`
+4. rely on the same account credit balance and credit-first execution path afterward
+
+When using pack-backed issuance:
+
+- `pack_id` should reference a real public credit pack from `GET /v1/credit-packs`
+- unknown pack ids should fail cleanly
+- pack-backed grants may derive default units and nominal amount from the referenced public pack
+
+Delegated spend should use:
+
+1. issue a narrow spend credential for the target account
+2. optionally bind it to an `agent_id` and/or `budget_id`
+3. optionally bind it to a `pack_id` or `entitlement_id` when value should stay inside one pool
+4. call the normal execution surface with `authorization: Bearer <spend_credential>`
+5. use `payment_preference: "credits_first"` for the repeat-use path
+6. revoke the credential without affecting account ownership or payout posture
+
+The first human-facing hosted path now follows:
+
+1. create purchase intent
+2. create checkout session
+3. receive normalized payment status
+4. issue credits or execution entitlement
+5. converge into the runtime spine
+
+Direct single-task hosted execution should use:
+
+1. hosted checkout purchase intent
+2. normalized `paid` event
+3. runtime bridge dispatch
+4. normal transaction, receipt, treasury, and proof follow-through
+
+Hosted checkout payout posture should use:
+
+1. refund request enters review
+2. operator review updates refund state
+3. approval is explicit
+4. completion is manual and bounded
+
+Provider or customer refund-shaped signals may be recorded, but they should not become autonomous payout authority inside the public stack.
+
+Operator-shell posture should now also expose hosted checkout visibility:
+
+- purchase intent counts
+- runtime bridge dispatch counts
+- refund review queue counts
+
+so the human payment path remains operationally visible without introducing a second control plane.
 
 This loop is exercised through:
 

package/START_HERE.md

@@ -40,6 +40,8 @@ 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)
+- [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)
 - [TERMINOLOGY.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/TERMINOLOGY.md)
 
 ## 5. If You Are Building Adapters