xytara 3.1.16 → 3.2.0

package/SERVICE_CONTRACT.md

@@ -1,419 +0,0 @@
-# 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

package/SUPABASE_RUNTIME_STATE_SETUP.md

@@ -1,61 +0,0 @@
-# xytara Supabase Runtime State Setup
-
-Use this when `xytara` runs on infrastructure without persistent disk, such as a free Render service.
-
-## What This Solves
-
-This keeps runtime economics state durable across restart:
-
-- external credit grants
-- entitlements
-- credit spends
-- usage meters
-- hidden-account economics carry
-
-## 1. Create The Table In Supabase
-
-Run this SQL:
-
-```sql
-create table if not exists public.xytara_runtime_state (
-  state_key text primary key,
-  snapshot jsonb not null,
-  persisted_at_iso timestamptz not null default now()
-);
-```
-
-## 2. Configure xytara
-
-Set these environment variables on the deployed service:
-
-```text
-XYTARA_SUPABASE_URL=https://<project-ref>.supabase.co
-XYTARA_SUPABASE_SERVICE_ROLE_KEY=<service-role-key>
-XYTARA_SUPABASE_STATE_TABLE=xytara_runtime_state
-XYTARA_SUPABASE_STATE_KEY=default
-XYTARA_STATE_SNAPSHOT_INTERVAL_MS=5000
-```
-
-If `XYTARA_SUPABASE_URL` and `XYTARA_SUPABASE_SERVICE_ROLE_KEY` are set, `xytara` will use Supabase-backed runtime persistence instead of local file snapshots.
-
-## 3. Verify Runtime Durability
-
-Inspect:
-
-- `GET /v1/runtime/durability`
-
-Expected direction:
-
-- `storage_mode: "supabase"`
-- `remote_reachable: true`
-- `remote_table_ready: true`
-- `snapshot_exists: true` after the first persisted mutation
-
-## 4. Verify The Real Economics Path
-
-1. issue a hidden-account grant
-2. confirm balance and entitlements exist
-3. restart or redeploy `xytara`
-4. confirm the same hidden account still has balance and entitlements
-5. spend once
-6. confirm usage meter and spend history survive another restart

package/TERMINOLOGY.md

@@ -1,50 +0,0 @@
-# xytara Terminology
-
-This file freezes the public terminology used by `xytara`.
-
-The goal is:
-
-- one public name for the repo
-- one stable commerce vocabulary
-- no private-lineage naming leakage
-
-## Public Name
-
-- repo name: `xytara`
-- package name: `xytara`
-- service name: `xytara`
-
-Use `xytara` only for this repo and its public commerce identity.
-
-## Preferred Commerce Terms
-
-Use these terms consistently:
-
-- `catalog`
-- `task`
-- `workflow`
-- `task set`
-- `quote`
-- `payment`
-- `execute`
-- `deliver`
-- `inspect`
-- `operator`
-- `adapter`
-- `settlement profile`
-- `lifecycle`
-
-## Cross-Repo Reference Rule
-
-If this repo needs to mention the other repo, use generic wording:
-
-- `the proof repo`
-- `the proof layer`
-
-Do not brand the other repo inside this repo's core public copy.
-
-## Naming Rule
-
-This repo should read like a self-contained public commerce product with an explicit proof boundary.
-
-If wording does not strengthen that outcome, keep it generic.

package/WHY_XYTARA_XOONYA.md

@@ -1,63 +0,0 @@
-# Why xytara And xoonya
-
-The public stack is intentionally split into two repos because runtime commerce and canonical proof have different operating constraints.
-
-## xytara
-
-`xytara` owns the transaction-side path:
-
-- discover
-- preview or quote
-- fund or spend
-- execute
-- inspect
-- export carry
-
-It is the right place for:
-
-- payment posture
-- credits and entitlements
-- settlement visibility
-- adapter registration and promotion
-- operator-facing runtime state
-
-## xoonya
-
-`xoonya` owns the proof-side path:
-
-- receive handoff
-- review preserved context
-- emit proof-native completion
-- verify the final bundle
-
-It is the right place for:
-
-- canonical event shape
-- receipts
-- proof bundles
-- narrow proof-adjacent integrations
-- reviewable proof followthrough
-
-## Why the split matters
-
-If commerce and proof are collapsed together, one side usually becomes muddy:
-
-- the runtime becomes too rigid
-- or the proof layer absorbs workflow and settlement semantics it should not own
-
-This split keeps both sides legible:
-
-- `xytara` stays execution and economics aware
-- `xoonya` stays canonical and proof aware
-
-## What builders get
-
-Builders do not need to choose between “commerce first” and “proof first.”
-
-They can:
-
-1. run the machine path in `xytara`
-2. export or carry the result
-3. complete the proof path in `xoonya`
-
-That is the public stack story.

package/XT1_EXECUTION_TRUTH_STANDARD.md

@@ -1,78 +0,0 @@
-# XT1 Execution Truth Standard
-
-Status: active runtime standard
-
-Version: `xt1/v1`
-
-## Purpose
-
-`XT1` is the coined public name for the canonical `xytara` runtime-side execution-truth standard.
-
-It is the `xytara` counterpart to `xoonya`'s `XNYA` native proof primitive.
-
-Where `XNYA` names the compact proof-side commitment family, `XT1` names the hot-state runtime fact spine that exists before proof review and followthrough move into `xoonya`.
-
-## What XT1 Covers
-
-`XT1` freezes the canonical `xytara` object sequence:
-
-1. `quote`
-2. `transaction`
-3. `receipt`
-4. `delivery`
-5. `settlement`
-6. `proof_handoff`
-
-Together these objects form the canonical runtime transcript and fact layer for:
-
-- priced intent
-- payment and authorization
-- execution
-- delivery
-- settlement linkage
-- treasury linkage
-- proof handoff
-
-## Doctrine
-
-`XT1` means:
-
-- `xytara` owns runtime-side execution truth
-- `xytara` emits proof-compatible facts
-- `xytara` does not redefine `xoonya` proof validity
-- execution success, settlement finality, and proof validity remain distinct
-
-## Relationship To Existing Surfaces
-
-`XT1` is not a second competing model.
-
-It is the coined public standard name for the already-frozen `xytara` execution-truth model documented in:
-
-- XYTARA_EXECUTION_TRUTH_MODEL.md
-
-Machine-readable surfaces:
-
-- `GET /v1/xt1`
-- `GET /v1/xt1/summary`
-- `GET /v1/execution-truth`
-- `GET /v1/execution-truth/summary`
-
-The `xt1` routes are the named standard alias.
-
-The `execution-truth` routes remain the descriptive runtime alias.
-
-## Invariants
-
-`XT1` preserves these invariants:
-
-- quote precedes irreversible paid execution
-- transaction is the canonical hot-state execution record
-- receipt is the runtime completion record, not the proof core
-- delivery truth remains first-class and inspectable
-- settlement truth remains linked but distinct from execution success
-- treasury consequence remains reconstructible from runtime artifacts
-- proof handoff remains explicit at the `xytara -> xoonya` boundary
-
-## Public Meaning
-
-For `3.0.0`, `XT1` means the runtime side now has a public, coined, stable standard name rather than only a descriptive contract.