xytara 3.1.0 → 3.1.2

package/SERVICE_CONTRACT.md

@@ -1,419 +1,419 @@
-# xytara Service Contract
-
-This file freezes the public service contract for `xytara`.
-
-## Public Routes
-
-Core routes:
-
-- `GET /health`
-- `GET /openapi.json`
-- `GET /v1/openapi`
-- `GET /v1/openapi/summary`
-- `GET /asyncapi.json`
-- `GET /v1/asyncapi`
-- `GET /v1/asyncapi/summary`
-- `GET /cloudevents.json`
-- `GET /v1/cloudevents`
-- `GET /v1/cloudevents/summary`
-- `GET /v1/auth-profiles`
-- `GET /v1/auth-profiles/summary`
-- `GET /v1/identity-interop`
-- `GET /v1/identity-interop/summary`
-- `GET /v1/providers`
-- `GET /v1/providers/summary`
-- `GET /v1/frameworks`
-- `GET /v1/frameworks/summary`
-- `GET /v1/protocols`
-- `GET /v1/protocols/summary`
-- `GET /v1/integration-matrix`
-- `GET /v1/integration-matrix/summary`
-- `GET /v1/mcp`
-- `GET /v1/mcp/summary`
-- `GET /v1/mcp/tools`
-- `GET /v1/a2a`
-- `GET /v1/a2a/summary`
-- `GET /v1/a2c`
-- `GET /v1/a2c/summary`
-- `GET /v1/x402`
-- `GET /v1/x402/summary`
-- `GET /v1/payment-protocols`
-- `GET /v1/payment-protocols/summary`
-- `GET /v1/settlement`
-- `GET /v1/settlement/summary`
-- `GET /v1/stripe-mpp`
-- `GET /v1/stripe-mpp/summary`
-- `GET /v1/stablecoins`
-- `GET /v1/stablecoins/summary`
-- `GET /v1/major-rails`
-- `GET /v1/major-rails/summary`
-- `GET /v1/treasury`
-- `GET /v1/treasury/summary`
-- `GET /v1/pricing-optimization`
-- `GET /v1/pricing-optimization/summary`
-- `GET /v1/pricing-optimization/quote-abandonment-summary`
-- `GET /v1/pricing-optimization/quote-cohorts`
-- `GET /v1/pricing-optimization/recommendations`
-- `GET /v1/activity-ledger`
-- `GET /v1/activity-ledger/summary`
-- `GET /v1/operator-observability`
-- `GET /v1/operator-observability/summary`
-- `GET /v1/business-cockpit`
-- `GET /v1/business-cockpit/summary`
-- `GET /business-cockpit`
-- `GET /v1/treasury-destinations`
-- `GET /v1/treasury-destinations/summary`
-- `GET /v1/treasury-destinations/operator-pack`
-- `GET /v1/treasury-destinations/operator-pack/summary`
-- `POST /v1/treasury-destinations/validate-preview`
-- `GET /v1/treasury-egress-policy`
-- `GET /v1/treasury-egress-policy/summary`
-- `GET /v1/erc8004`
-- `GET /v1/erc8004/summary`
-- `GET /v1/event-systems`
-- `GET /v1/event-systems/summary`
-- `GET /v1/telemetry`
-- `GET /v1/telemetry/summary`
-- `GET /v1/provenance`
-- `GET /v1/provenance/summary`
-- `GET /v1/artifact-distribution`
-- `GET /v1/artifact-distribution/summary`
-- `GET /v1/shared-signals`
-- `GET /v1/shared-signals/summary`
-- `GET /v1/feature-control`
-- `GET /v1/feature-control/summary`
-- `GET /v1/adapter-certification`
-- `GET /v1/adapter-certification/summary`
-- `GET /v1/adapter-certification/:front_id`
-- `GET /v1/trust-portability-boundary`
-- `GET /v1/trust-portability-boundary/summary`
-- `GET /v1/trust-portability-boundary/:axis_id`
-- `GET /v1/signed-audit-provenance`
-- `GET /v1/signed-audit-provenance/summary`
-- `GET /v1/signed-audit-provenance/:surface_id`
-- `GET /v1/catalog`
-- `GET /v1/catalog/summary`
-- `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/integrations`
-- `GET /v1/integrations/summary`
-- `GET /v1/integrations/classes`
-- `GET /v1/integrations/protocols`
-- `GET /v1/integrations/settlement-modes`
-- `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
-- `GET /v1/identity-interop` exposes how native authority and machine identity map to `JWT`, `DID/VC`, and `SD-JWT VC` interop lanes without replacing the native runtime authority model
-- `GET /v1/x402` exposes the first-class quote -> challenge -> pay -> execute lane for paid machine execution
-- `GET /v1/payment-protocols` makes the charging boundary explicit: keep auth, discovery, docs, catalog, and lightweight preview free while keeping execution, credit consumption, and consequence-bearing runtime work paid
-- `GET /v1/settlement` exposes the settlement family map across native BSV/Teranode, EVM/Base/USDC, and the major-rails family
-- `GET /v1/stripe-mpp` exposes the hosted-checkout and external-funding entry lane without making provider-specific checkout semantics the center of the stack
-- `GET /v1/stablecoins` exposes the current USDC/Base runtime family and marks Circle Nanopayments/CCTP as adapter-ready extensions instead of pretending they are already core first-party rails
-- `GET /v1/major-rails` exposes Solana plus the Antelope/Proton XPR/Metal family as one practical non-default settlement lane
-- `GET /v1/treasury` exposes the treasury-connectivity posture and the internal reserve doctrine of BSV/Teranode plus DAI/USDC, with Monero retained only as an optional hidden privacy reserve
-- `GET /v1/pricing-optimization` exposes minimum charge floors, starter pricing posture, credit-pack breakpoints, high-consequence premium multipliers, and quote abandonment visibility so revenue posture is reviewable instead of implicit
-- `GET /v1/pricing-optimization/quote-cohorts` and `GET /v1/pricing-optimization/recommendations` expose how quote conversion and abandonment behave by pricing band, payment protocol, and settlement mode so monetization tuning can be data-shaped rather than guessed
-- `GET /v1/activity-ledger` exposes one operator-grade ledger across quote, payment, settlement, delivery, dispute, refund, credit-grant, bridge, and integration-admission activity so operators can answer who did what, paid what, received what, and through which route
-- `GET /v1/operator-observability` exposes a protected read-only pack across activity, payment, delivery, settlement, adapter failure, credit-grant, and pricing telemetry posture without moving funds or submitting settlements
-- `GET /v1/business-cockpit` and `GET /business-cockpit` expose one protected operator analytics surface that bundles release posture, treasury landing truth, runtime activity, settlement readiness, and linked proof-facing health into a single private JSON or HTML cockpit
-- `GET /v1/treasury-destinations` is public-readiness only: it shows which rails are operationally configured without exposing actual landing references
-- `GET /v1/treasury-destinations/operator-pack` is the operator-only custody surface and is where real destination references belong
-- `POST /v1/treasury-destinations/validate-preview` lets operators preview per-rail custody readiness before they claim a rail as operational
-- `GET /v1/treasury-egress-policy` makes the treasury black-hole posture explicit: funds can come in easily through configured rails, but treasury release remains blocked until manual operator review with explicit reason and signoff
-- when `XYTARA_ACCOUNT_AUTH_BEARER_TOKEN` is configured, `GET /v1/activity-ledger`, `GET /v1/operator-observability`, `GET /v1/business-cockpit`, `GET /v1/business-cockpit/summary`, `GET /business-cockpit`, `GET /v1/treasury-destinations/operator-pack`, `POST /v1/treasury-destinations/validate-preview`, and `GET /v1/treasury-egress-policy` require that bearer token
-- `GET /v1/providers` exposes the OpenAI Codex and Claude/MCP family as first-class provider entry lanes
-- `GET /v1/frameworks` exposes LangGraph, LangChain, AutoGen, and Semantic Kernel as the primary runtime framework lanes, with CrewAI and LlamaIndex surfaced as registry-backed framework breadth
-- `GET /v1/protocols` exposes the canonical protocol and transport family across MCP, A2A, A2C, ACP, gRPC, Kafka, NATS, MQTT, ROS2, and webhook-event-bus posture
-- `GET /v1/integration-matrix` exposes the canonical public view across providers, frameworks, protocols, payments, settlement families, and registry-backed integrations
-- `GET /v1/telemetry` exposes the OpenTelemetry-aligned observability posture across runtime traces, metrics, logs, and event carry
-- `GET /v1/provenance` exposes the SLSA-aligned release and execution provenance posture for runtime trust and adoption
-- `GET /v1/artifact-distribution` exposes OCI-style artifact distribution posture for adapters, submission bundles, registry snapshots, and release artifacts
-- `GET /v1/shared-signals` exposes OpenID Shared Signals and CAEP-aligned risk and identity event exchange posture without replacing native runtime decisions
-- `GET /v1/feature-control` exposes OpenFeature/OFREP-aligned rollout and policy portability posture across pricing, authority, identity, trust, and release gates
-- `GET /v1/adapter-certification` exposes the front-specific adapter certification contract and its machine-readable compatibility states
-- `GET /v1/trust-portability-boundary` exposes the bounded trust portability contract for identity, delegation, delivery, and settlement-linked followthrough
-- `GET /v1/signed-audit-provenance` exposes the signed audit and provenance surface map for selected evidence-bearing runtime and release lanes
-- 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
-- the default machine-payment lane remains `x402`, while credits and `stripe_mpp` provide repeat-use and human-funding paths, and future protocol expansion should normally enter through the payment front rather than replacing the default machine lane
-- quote-based pricing is intentionally preferred over flat pricing because it protects margin on high-consequence work without overpricing small utility flows, but quote abandonment and conversion should still be monitored through the pricing-optimization layer
-- production acceptance on `bsv_teranode`, `evm`, `base`, `usdc`, `dai`, or `monero` should only be claimed once the corresponding treasury destination is explicitly configured and visible through `GET /v1/treasury-destinations`, with real custody details limited to `GET /v1/treasury-destinations/operator-pack`
-- 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`
-- `POST /v1/trust/handoffs/validate`
-- `POST /v1/execution-receipts/handoffs/emit`
-- `POST /v1/execution-receipts/handoffs/validate`
-- `POST /v1/receipt-ledger/handoffs/emit`
-- `POST /v1/receipt-ledger/handoffs/validate`
-- `POST /v1/admission/preview`
-- `POST /v1/runtime/emit`
-- `POST /v1/runtime/anchor`
-- `POST /v1/runtime/emit-anchor`
-- `POST /v1/registry/register`
-- `POST /v1/anchoring/submit`
-- `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`
-- `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:
-
-- `GET /v1/payment-quotes`
-- `GET /v1/payment-quotes/:quote_id`
-- `GET /v1/governed-transactions`
-- `GET /v1/governed-transactions/:transaction_id`
-- `GET /v1/receipts`
-- `GET /v1/receipts/:receipt_id`
-- `GET /v1/payment-ledger`
-- `GET /v1/payment-ledger/:payment_id`
-- `GET /v1/deliveries`
-- `GET /v1/deliveries/:delivery_id`
-- `GET /v1/disputes`
-- `POST /v1/disputes`
-- `GET /v1/disputes/:dispute_id`
-- `POST /v1/disputes/:dispute_id/actions`
-- `GET /v1/refunds`
-- `POST /v1/refunds`
-- `GET /v1/refunds/:refund_id`
-- `POST /v1/refunds/:refund_id/actions`
-- `POST /v1/remediation-tickets`
-- `GET /v1/remediation-tickets`
-- `GET /v1/remediation-tickets/:ticket_id`
-- `POST /v1/remediation-tickets/:ticket_id/actions`
-- `GET /v1/reconciliation-report`
-- `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/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`
-- `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/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`
-- `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/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`
-- `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`
-
-## Error-Shape Expectations
-
-Primary error posture:
-
-- malformed or invalid requests return `400`
-- payment-required flows return `402`
-- expired quotes return `409`
-- missing routes return `404`
-- unexpected server failures return `500`
-
-Expected top-level error shapes:
-
-- generic failure:
-  - `{ "ok": false, "reason": "<message>" }`
-- payment challenge:
-  - `{ "ok": false, "payment_required": { ... } }`
-- expired quote:
-  - `{ "ok": false, "reason": "quote_expired", "quote": { ... } }`
-- not found:
-  - `{ "ok": false, "reason": "not_found", "path": "<path>" }`
-
-Named resource-view responses may return resource-specific missing reasons such as `quote_not_found` or `delivery_not_found`, but the top-level failure posture should remain predictable.
-
-## Final-Loop Verification
-
-The constitutional commerce loop for `xytara` is:
-
-1. discover
-2. quote
-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 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 hosted purchase 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 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 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 verification
-- adapter verification
-- quickstart verification
-- service verification
+# xytara Service Contract
+
+This file freezes the public service contract for `xytara`.
+
+## Public Routes
+
+Core routes:
+
+- `GET /health`
+- `GET /openapi.json`
+- `GET /v1/openapi`
+- `GET /v1/openapi/summary`
+- `GET /asyncapi.json`
+- `GET /v1/asyncapi`
+- `GET /v1/asyncapi/summary`
+- `GET /cloudevents.json`
+- `GET /v1/cloudevents`
+- `GET /v1/cloudevents/summary`
+- `GET /v1/auth-profiles`
+- `GET /v1/auth-profiles/summary`
+- `GET /v1/identity-interop`
+- `GET /v1/identity-interop/summary`
+- `GET /v1/providers`
+- `GET /v1/providers/summary`
+- `GET /v1/frameworks`
+- `GET /v1/frameworks/summary`
+- `GET /v1/protocols`
+- `GET /v1/protocols/summary`
+- `GET /v1/integration-matrix`
+- `GET /v1/integration-matrix/summary`
+- `GET /v1/mcp`
+- `GET /v1/mcp/summary`
+- `GET /v1/mcp/tools`
+- `GET /v1/a2a`
+- `GET /v1/a2a/summary`
+- `GET /v1/a2c`
+- `GET /v1/a2c/summary`
+- `GET /v1/x402`
+- `GET /v1/x402/summary`
+- `GET /v1/payment-protocols`
+- `GET /v1/payment-protocols/summary`
+- `GET /v1/settlement`
+- `GET /v1/settlement/summary`
+- `GET /v1/stripe-mpp`
+- `GET /v1/stripe-mpp/summary`
+- `GET /v1/stablecoins`
+- `GET /v1/stablecoins/summary`
+- `GET /v1/major-rails`
+- `GET /v1/major-rails/summary`
+- `GET /v1/treasury`
+- `GET /v1/treasury/summary`
+- `GET /v1/pricing-optimization`
+- `GET /v1/pricing-optimization/summary`
+- `GET /v1/pricing-optimization/quote-abandonment-summary`
+- `GET /v1/pricing-optimization/quote-cohorts`
+- `GET /v1/pricing-optimization/recommendations`
+- `GET /v1/activity-ledger`
+- `GET /v1/activity-ledger/summary`
+- `GET /v1/operator-observability`
+- `GET /v1/operator-observability/summary`
+- `GET /v1/business-cockpit`
+- `GET /v1/business-cockpit/summary`
+- `GET /business-cockpit`
+- `GET /v1/treasury-destinations`
+- `GET /v1/treasury-destinations/summary`
+- `GET /v1/treasury-destinations/operator-pack`
+- `GET /v1/treasury-destinations/operator-pack/summary`
+- `POST /v1/treasury-destinations/validate-preview`
+- `GET /v1/treasury-egress-policy`
+- `GET /v1/treasury-egress-policy/summary`
+- `GET /v1/erc8004`
+- `GET /v1/erc8004/summary`
+- `GET /v1/event-systems`
+- `GET /v1/event-systems/summary`
+- `GET /v1/telemetry`
+- `GET /v1/telemetry/summary`
+- `GET /v1/provenance`
+- `GET /v1/provenance/summary`
+- `GET /v1/artifact-distribution`
+- `GET /v1/artifact-distribution/summary`
+- `GET /v1/shared-signals`
+- `GET /v1/shared-signals/summary`
+- `GET /v1/feature-control`
+- `GET /v1/feature-control/summary`
+- `GET /v1/adapter-certification`
+- `GET /v1/adapter-certification/summary`
+- `GET /v1/adapter-certification/:front_id`
+- `GET /v1/trust-portability-boundary`
+- `GET /v1/trust-portability-boundary/summary`
+- `GET /v1/trust-portability-boundary/:axis_id`
+- `GET /v1/signed-audit-provenance`
+- `GET /v1/signed-audit-provenance/summary`
+- `GET /v1/signed-audit-provenance/:surface_id`
+- `GET /v1/catalog`
+- `GET /v1/catalog/summary`
+- `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/integrations`
+- `GET /v1/integrations/summary`
+- `GET /v1/integrations/classes`
+- `GET /v1/integrations/protocols`
+- `GET /v1/integrations/settlement-modes`
+- `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
+- `GET /v1/identity-interop` exposes how native authority and machine identity map to `JWT`, `DID/VC`, and `SD-JWT VC` interop lanes without replacing the native runtime authority model
+- `GET /v1/x402` exposes the first-class quote -> challenge -> pay -> execute lane for paid machine execution
+- `GET /v1/payment-protocols` makes the charging boundary explicit: keep auth, discovery, docs, catalog, and lightweight preview free while keeping execution, credit consumption, and consequence-bearing runtime work paid
+- `GET /v1/settlement` exposes the settlement family map across native BSV/Teranode, EVM/Base/USDC, and the major-rails family
+- `GET /v1/stripe-mpp` exposes the hosted-checkout and external-funding entry lane without making provider-specific checkout semantics the center of the stack
+- `GET /v1/stablecoins` exposes the current USDC/Base runtime family and marks Circle Nanopayments/CCTP as adapter-ready extensions instead of pretending they are already core first-party rails
+- `GET /v1/major-rails` exposes Solana plus the Antelope/Proton XPR/Metal family as one practical non-default settlement lane
+- `GET /v1/treasury` exposes the treasury-connectivity posture and the internal reserve doctrine of BSV/Teranode plus DAI/USDC, with Monero retained only as an optional hidden privacy reserve
+- `GET /v1/pricing-optimization` exposes minimum charge floors, starter pricing posture, credit-pack breakpoints, high-consequence premium multipliers, and quote abandonment visibility so revenue posture is reviewable instead of implicit
+- `GET /v1/pricing-optimization/quote-cohorts` and `GET /v1/pricing-optimization/recommendations` expose how quote conversion and abandonment behave by pricing band, payment protocol, and settlement mode so monetization tuning can be data-shaped rather than guessed
+- `GET /v1/activity-ledger` exposes one operator-grade ledger across quote, payment, settlement, delivery, dispute, refund, credit-grant, bridge, and integration-admission activity so operators can answer who did what, paid what, received what, and through which route
+- `GET /v1/operator-observability` exposes a protected read-only pack across activity, payment, delivery, settlement, adapter failure, credit-grant, and pricing telemetry posture without moving funds or submitting settlements
+- `GET /v1/business-cockpit` and `GET /business-cockpit` expose one protected operator analytics surface that bundles release posture, treasury landing truth, runtime activity, settlement readiness, and linked proof-facing health into a single private JSON or HTML cockpit
+- `GET /v1/treasury-destinations` is public-readiness only: it shows which rails are operationally configured without exposing actual landing references
+- `GET /v1/treasury-destinations/operator-pack` is the operator-only custody surface and is where real destination references belong
+- `POST /v1/treasury-destinations/validate-preview` lets operators preview per-rail custody readiness before they claim a rail as operational
+- `GET /v1/treasury-egress-policy` makes the treasury black-hole posture explicit: funds can come in easily through configured rails, but treasury release remains blocked until manual operator review with explicit reason and signoff
+- when `XYTARA_ACCOUNT_AUTH_BEARER_TOKEN` is configured, `GET /v1/activity-ledger`, `GET /v1/operator-observability`, `GET /v1/business-cockpit`, `GET /v1/business-cockpit/summary`, `GET /business-cockpit`, `GET /v1/treasury-destinations/operator-pack`, `POST /v1/treasury-destinations/validate-preview`, and `GET /v1/treasury-egress-policy` require that bearer token
+- `GET /v1/providers` exposes the OpenAI Codex and Claude/MCP family as first-class provider entry lanes
+- `GET /v1/frameworks` exposes LangGraph, LangChain, AutoGen, and Semantic Kernel as the primary runtime framework lanes, with CrewAI and LlamaIndex surfaced as registry-backed framework breadth
+- `GET /v1/protocols` exposes the canonical protocol and transport family across MCP, A2A, A2C, ACP, gRPC, Kafka, NATS, MQTT, ROS2, and webhook-event-bus posture
+- `GET /v1/integration-matrix` exposes the canonical public view across providers, frameworks, protocols, payments, settlement families, and registry-backed integrations
+- `GET /v1/telemetry` exposes the OpenTelemetry-aligned observability posture across runtime traces, metrics, logs, and event carry
+- `GET /v1/provenance` exposes the SLSA-aligned release and execution provenance posture for runtime trust and adoption
+- `GET /v1/artifact-distribution` exposes OCI-style artifact distribution posture for adapters, submission bundles, registry snapshots, and release artifacts
+- `GET /v1/shared-signals` exposes OpenID Shared Signals and CAEP-aligned risk and identity event exchange posture without replacing native runtime decisions
+- `GET /v1/feature-control` exposes OpenFeature/OFREP-aligned rollout and policy portability posture across pricing, authority, identity, trust, and release gates
+- `GET /v1/adapter-certification` exposes the front-specific adapter certification contract and its machine-readable compatibility states
+- `GET /v1/trust-portability-boundary` exposes the bounded trust portability contract for identity, delegation, delivery, and settlement-linked followthrough
+- `GET /v1/signed-audit-provenance` exposes the signed audit and provenance surface map for selected evidence-bearing runtime and release lanes
+- 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
+- the default machine-payment lane remains `x402`, while credits and `stripe_mpp` provide repeat-use and human-funding paths, and future protocol expansion should normally enter through the payment front rather than replacing the default machine lane
+- quote-based pricing is intentionally preferred over flat pricing because it protects margin on high-consequence work without overpricing small utility flows, but quote abandonment and conversion should still be monitored through the pricing-optimization layer
+- production acceptance on `bsv_teranode`, `evm`, `base`, `usdc`, `dai`, or `monero` should only be claimed once the corresponding treasury destination is explicitly configured and visible through `GET /v1/treasury-destinations`, with real custody details limited to `GET /v1/treasury-destinations/operator-pack`
+- 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`
+- `POST /v1/trust/handoffs/validate`
+- `POST /v1/execution-receipts/handoffs/emit`
+- `POST /v1/execution-receipts/handoffs/validate`
+- `POST /v1/receipt-ledger/handoffs/emit`
+- `POST /v1/receipt-ledger/handoffs/validate`
+- `POST /v1/admission/preview`
+- `POST /v1/runtime/emit`
+- `POST /v1/runtime/anchor`
+- `POST /v1/runtime/emit-anchor`
+- `POST /v1/registry/register`
+- `POST /v1/anchoring/submit`
+- `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`
+- `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:
+
+- `GET /v1/payment-quotes`
+- `GET /v1/payment-quotes/:quote_id`
+- `GET /v1/governed-transactions`
+- `GET /v1/governed-transactions/:transaction_id`
+- `GET /v1/receipts`
+- `GET /v1/receipts/:receipt_id`
+- `GET /v1/payment-ledger`
+- `GET /v1/payment-ledger/:payment_id`
+- `GET /v1/deliveries`
+- `GET /v1/deliveries/:delivery_id`
+- `GET /v1/disputes`
+- `POST /v1/disputes`
+- `GET /v1/disputes/:dispute_id`
+- `POST /v1/disputes/:dispute_id/actions`
+- `GET /v1/refunds`
+- `POST /v1/refunds`
+- `GET /v1/refunds/:refund_id`
+- `POST /v1/refunds/:refund_id/actions`
+- `POST /v1/remediation-tickets`
+- `GET /v1/remediation-tickets`
+- `GET /v1/remediation-tickets/:ticket_id`
+- `POST /v1/remediation-tickets/:ticket_id/actions`
+- `GET /v1/reconciliation-report`
+- `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/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`
+- `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/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`
+- `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/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`
+- `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`
+
+## Error-Shape Expectations
+
+Primary error posture:
+
+- malformed or invalid requests return `400`
+- payment-required flows return `402`
+- expired quotes return `409`
+- missing routes return `404`
+- unexpected server failures return `500`
+
+Expected top-level error shapes:
+
+- generic failure:
+  - `{ "ok": false, "reason": "<message>" }`
+- payment challenge:
+  - `{ "ok": false, "payment_required": { ... } }`
+- expired quote:
+  - `{ "ok": false, "reason": "quote_expired", "quote": { ... } }`
+- not found:
+  - `{ "ok": false, "reason": "not_found", "path": "<path>" }`
+
+Named resource-view responses may return resource-specific missing reasons such as `quote_not_found` or `delivery_not_found`, but the top-level failure posture should remain predictable.
+
+## Final-Loop Verification
+
+The constitutional commerce loop for `xytara` is:
+
+1. discover
+2. quote
+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 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 hosted purchase 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 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 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 verification
+- adapter verification
+- quickstart verification
+- service verification