xytara 2.0.0 → 2.2.0

package/README.md

@@ -16,6 +16,8 @@ It exists to let agents, developers, and systems:
 
 This repo is the hot-state commerce layer. It does not define base proof semantics. It references and emits proof-compatible facts, while `xoonya` owns canonical proof.
 
+The 10-phase public program is now complete. `xytara` is in terminal closeout posture rather than active milestone build posture.
+
 ## Start Here
 
 If you are new to the public stack, use this order:
@@ -25,18 +27,51 @@ If you are new to the public stack, use this order:
 3. run `npm run verify:all`
 4. use [FINAL_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/FINAL_CONTRACT.md) and [SERVICE_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/SERVICE_CONTRACT.md) as the durable public contract
 
+If you are evaluating the post-program operating posture, read:
+
+- [PROGRAM_STATUS.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/PROGRAM_STATUS.md)
+- [OPERATOR_START_HERE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/OPERATOR_START_HERE.md)
+- [OPERATIONS_RUNBOOK.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/OPERATIONS_RUNBOOK.md)
+- [PROGRAM_COMPLETE_RELEASE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/PROGRAM_COMPLETE_RELEASE.md)
+- [WHY_XYTARA_XOONYA.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/WHY_XYTARA_XOONYA.md)
+
+If you want one concrete cross-repo adoption story, start with:
+
+- [CARRIED_HANDOFF_DEMO.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/CARRIED_HANDOFF_DEMO.md)
+
+If you want the shortest neutral external-adoption bundle, continue with:
+
+- [PARTNER_READY_PATH.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/PARTNER_READY_PATH.md)
+- [PUBLIC_DEMO_SCRIPT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/PUBLIC_DEMO_SCRIPT.md)
+- [EXAMPLE_PATHS.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/EXAMPLE_PATHS.md)
+- `node examples/partner_launch_walkthrough.js`
+
 If you are building adapters, continue with:
 
+- [ADAPTER_START_HERE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/ADAPTER_START_HERE.md)
+- [ADAPTER_PROMOTION_START_HERE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/ADAPTER_PROMOTION_START_HERE.md)
+- [ADAPTER_PARTNER_PATH.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/ADAPTER_PARTNER_PATH.md)
+- [SOFT_LAUNCH_KIT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/SOFT_LAUNCH_KIT.md)
+- [OUTREACH_START_HERE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/OUTREACH_START_HERE.md)
+- [OUTREACH_MESSAGES.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/OUTREACH_MESSAGES.md)
 - [adapters/AUTHORING_GUIDE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/adapters/AUTHORING_GUIDE.md)
 - [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)
 
+The fastest copy-and-adapt third-party starter now lives under:
+
+- `adapters/examples/minimal-third-party-execution-adapter.manifest.json`
+- `adapters/examples/minimal-third-party-execution-adapter.js`
+- `adapters/examples/minimal-third-party-execution-registration.record.json`
+- `adapters/examples/minimal-third-party-execution.certification-pack.json`
+- `adapters/examples/minimal-third-party-execution.submission-bundle.json`
+
 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:
+If you are wiring external checkout or hosted funding paths, 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)
@@ -120,23 +155,23 @@ This keeps one-off usage and repeat usage on the same public spine:
 - 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:
+It also keeps the external funding 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:
+The first external checkout 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
+5. dispatch through the runtime path 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:
+The first direct hosted execution path now also has a public runtime dispatch surface:
 
 - `POST /v1/runtime-bridge/dispatch`
 - `GET /v1/runtime-bridge/dispatches`
@@ -153,6 +188,82 @@ The operator shell now also carries hosted checkout visibility so purchase, disp
 
 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.
 
+For release-grade adoption posture, inspect:
+
+- `GET /v1/release-pack`
+- `GET /v1/release-pack/summary`
+- `GET /v1/release-pack/comparison`
+- `GET /v1/release-pack/comparison/summary`
+- `GET /v1/release-pack/adoption`
+- `GET /v1/release-pack/adoption/summary`
+- `GET /v1/release-pack/scenarios`
+- `GET /v1/release-pack/scenarios/summary`
+- `GET /v1/release-pack/launch`
+- `GET /v1/release-pack/launch/summary`
+- `GET /v1/release-manifest`
+- `GET /v1/release-manifest/summary`
+- `GET /v1/release-notes`
+- `GET /v1/release-notes/summary`
+- `GET /v1/release-center`
+- `GET /v1/release-center/summary`
+- `GET /v1/release-history`
+- `GET /v1/release-history/summary`
+- `GET /v1/adapter-pack`
+- `GET /v1/adapter-pack/summary`
+- `GET /v1/adapter-promotion`
+- `GET /v1/adapter-promotion/summary`
+- `GET /v1/adapter-partners`
+- `GET /v1/adapter-partners/summary`
+- `GET /v1/soft-launch`
+- `GET /v1/soft-launch/summary`
+- `GET /v1/outreach-copy`
+- `GET /v1/outreach-copy/summary`
+- `GET /v1/outreach-targets`
+- `GET /v1/outreach-targets/summary`
+- `GET /v1/outreach-messages`
+- `GET /v1/outreach-messages/summary`
+- `GET /v1/phases`
+- `GET /v1/phases/summary`
+- `GET /v1/phases/phase-1`
+- `GET /v1/phases/phase-1/summary`
+- `GET /v1/publish-plan`
+- `GET /v1/publish-plan/summary`
+- `GET /v1/ecosystem-entry`
+- `GET /v1/ecosystem-entry/summary`
+- `GET /v1/launch-narrative`
+- `GET /v1/launch-narrative/summary`
+- `GET /v1/outreach-proof`
+- `GET /v1/outreach-proof/summary`
+- `GET /v1/announcement-pack`
+- `GET /v1/announcement-pack/summary`
+- `GET /v1/release-candidate`
+- `GET /v1/release-candidate/summary`
+- `xytara-release --summary`
+- `xytara-release --comparison --summary`
+- `xytara-release --adoption --summary`
+- `xytara-release --scenarios --summary`
+- `xytara-release --launch --summary`
+- `xytara-release --manifest --summary`
+- `xytara-release --notes --summary`
+- `xytara-release --center --summary`
+- `xytara-release --history --summary`
+- `xytara-release --adapters --summary`
+- `xytara-release --adapter-promotion --summary`
+- `xytara-release --adapter-partners --summary`
+- `xytara-release --soft-launch --summary`
+- `xytara-release --outreach-copy --summary`
+- `xytara-release --outreach-targets --summary`
+- `xytara-release --outreach-messages --summary`
+- `xytara-release --phases --summary`
+- `xytara-release --phase-1 --summary`
+- `xytara-release --ecosystem --summary`
+- `xytara-release --narrative --summary`
+- `xytara-release --outreach-proof --summary`
+- `xytara-release --announcement --summary`
+- `xytara-release --candidate --summary`
+
+These surfaces package the current machine-commerce value story, first-contact CLI path, default transaction posture, catalog/task-pack coverage, credit-pack posture, and integration/settlement breadth into one machine-readable launch boundary.
+
 ## Commerce Loop
 
 The public product loop is:
@@ -589,6 +700,12 @@ Run:
 node examples/quickstart.js
 ```
 
+For a direct one-line machine run against a live service, use the bundled CLI:
+
+```bash
+xytara-run --url https://xytara.onrender.com --account acct_demo --command "cli-run" --task trust.verify --body-json '{"subject_id":"subject-1"}' --wallet-id merchant_wallet_main --wallet-secret YOUR_LOCAL_SIGNED_SECRET --txid YOUR_BSV_TXID
+```
+
 The quickstart exercises:
 
 - health and catalog
@@ -675,6 +792,9 @@ Production payment note:
 - 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
+- for native BSV/Teranode live follow-through, set `XYTARA_BSV_TERANODE_SETTLEMENT_RUNTIME_MODE` to `observe` or `arc`
+- use `XYTARA_BSV_TERANODE_RPC_URL` plus optional ARC auth envs when the live runtime needs ARC submission
+- use `XYTARA_BSV_TERANODE_OBSERVER_URL` if you want to override the default live observer base
 
 Primary service routes:
 
@@ -752,6 +872,7 @@ Primary service routes:
 - `GET /v1/receipts/:receipt_id`
 - `GET /v1/payment-ledger`
 - `GET /v1/payment-ledger/:payment_id`
+- `GET /v1/payment-ledger/:payment_id/operator-pack`
 - `GET /v1/deliveries`
 - `GET /v1/deliveries/:delivery_id`
 - `GET /v1/disputes`
@@ -770,6 +891,7 @@ Primary service routes:
 - `GET /v1/operator-export-pack`
 - `GET /v1/operations/dashboard`
 - `GET /v1/operations/attention-records`
+- `GET /v1/runtime/durability`
 - `GET /v1/operator-shell`
 - `GET /v1/operator-shell/summary`
 - `POST /v1/operator-shell/summary`
@@ -815,6 +937,8 @@ Primary service routes:
 - `GET /v1/economics/evidence/receipts/:receipt_ref`
 - `GET /v1/economics/evidence/jobs/:job_id`
 - `GET /v1/economics/integration/jobs/:job_id`
+- `GET /v1/settlement/bsv-teranode/readiness`
+- `GET /v1/settlement/bsv-teranode/:settlement_id/operator-pack`
 
 The Wave C coordination carry-over line adds a bounded coordination center on top of the public transaction spine:
 
@@ -834,9 +958,21 @@ The Wave F shell carry-over line adds a bounded operator shell inside public `xy
 
 - self-serve agent account issuance for the public runtime path
 - a unified operator shell summary across operations, economics, and coordination
+- explicit runtime durability visibility for snapshot-backed recovery posture
+- explicit native BSV/Teranode readiness visibility for merchant identity, transport, and verification posture
 - compact workflow/admin shell exports that point cleanly into proof-side follow-through when needed
 
-This keeps the public product centered on `naxytra` while recovering the useful operator-shell lineage as a built-in `xytara` capability instead of a separate branded surface.
+This keeps the public product centered on `naxytra` while preserving the useful operator-shell capability directly inside `xytara` instead of splitting it into a separate surface.
+
+The durability and native-settlement readiness surfaces are also intended to make the remaining production boundary explicit:
+
+- `/v1/runtime/durability` exposes whether runtime snapshots are enabled, whether a recoverable snapshot exists yet, and any current durability blockers
+- `/v1/settlement/bsv-teranode/readiness` exposes whether merchant identity, transport, verification mode, and runtime mode are production-ready, plus the next manual inputs still required
+- `/v1/payment-ledger/:payment_id/operator-pack` and `/v1/settlement/bsv-teranode/:settlement_id/operator-pack` collapse payment, settlement, treasury, proof, and economic-consequence carry into one operator-facing pack so direct-pay and funded-runtime paths are easier to inspect without stitching raw records together
+
+If you use grants, entitlements, or usage metering in deployed `xytara`, `XYTARA_STATE_FILE` should point at persistent disk rather than ephemeral container storage. Otherwise those economics records will reset across restart.
+
+If your host does not provide persistent disk, use the Supabase-backed runtime state path documented in [SUPABASE_RUNTIME_STATE_SETUP.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/SUPABASE_RUNTIME_STATE_SETUP.md).
 
 ## Verification
 

package/RELEASE_CHECKLIST.md

@@ -0,0 +1,16 @@
+# xytara Release Checklist
+
+1. Run `npm run verify:release-candidate`.
+2. Confirm `npm pack --dry-run --json` includes the public docs and both CLI entrypoints.
+3. Run `node examples/partner_launch_walkthrough.js`.
+3. Redeploy the service and verify:
+   - `/v1/release-center/summary`
+   - `/v1/announcement-pack/summary`
+   - `/v1/outreach-proof/summary`
+   - `/v1/runtime/durability`
+4. Confirm the program-complete docs are packaged:
+   - `PROGRAM_COMPLETE_RELEASE.md`
+   - `WHY_XYTARA_XOONYA.md`
+   - `PARTNER_READY_PATH.md`
+5. Run the first public proof path.
+6. Only then publish the npm package.

package/RELEASE_NOTES.md

@@ -0,0 +1,28 @@
+# xytara 2.2.0 Release Notes
+
+`xytara` 2.2.0 is the public machine-commerce program-complete line.
+
+Highlights:
+
+- direct one-line machine execution with `xytara-run`
+- release, comparison, adoption, scenario, and launch packs over HTTP and CLI
+- release-center, announcement-pack, and release-candidate surfaces for public launch readiness
+- credits-first reusable spend posture
+- native settlement-aware runtime inspection
+- proof-compatible handoff into `xoonya`
+- partner-ready onboarding and launch docs
+- explicit runtime durability posture, including Supabase-backed persistence on hosts without persistent disk
+
+Recommended first checks:
+
+1. `npm install xytara`
+2. `xytara-release --candidate --summary`
+3. `npm run verify:release-candidate`
+4. `node examples/partner_launch_walkthrough.js`
+5. inspect `/v1/release-candidate/summary` and `/v1/runtime/durability` on the deployed service
+
+Recommended first docs:
+
+- `PROGRAM_COMPLETE_RELEASE.md`
+- `WHY_XYTARA_XOONYA.md`
+- `PARTNER_READY_PATH.md`

package/SERVICE_CONTRACT.md

@@ -237,7 +237,7 @@ Deterministic usage metering should use:
 
 External top-up and pack issuance should use:
 
-1. verify the human-facing purchase outside the runtime
+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
@@ -257,7 +257,7 @@ Delegated spend should use:
 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:
+The first hosted purchase path now follows:
 
 1. create purchase intent
 2. create checkout session
@@ -269,7 +269,7 @@ Direct single-task hosted execution should use:
 
 1. hosted checkout purchase intent
 2. normalized `paid` event
-3. runtime bridge dispatch
+3. runtime dispatch
 4. normal transaction, receipt, treasury, and proof follow-through
 
 Hosted checkout payout posture should use:
@@ -284,7 +284,7 @@ Provider or customer refund-shaped signals may be recorded, but they should not
 Operator-shell posture should now also expose hosted checkout visibility:
 
 - purchase intent counts
-- runtime bridge dispatch counts
+- runtime dispatch counts
 - refund review queue counts
 
 so the human payment path remains operationally visible without introducing a second control plane.

package/START_HERE.md

@@ -2,6 +2,8 @@
 
 This is the shortest reliable path for understanding and using the public `xytara` package in production-facing order.
 
+The phase program is now complete, so this file is the right starting point for a closed and release-shaped runtime rather than an in-flight milestone build.
+
 ## 1. Understand The Role
 
 `xytara` is the transaction-side half of the public stack.
@@ -24,6 +26,17 @@ node examples/quickstart.js
 
 This is the fastest way to see the intended package story end-to-end.
 
+If you want the clearest cross-repo adoption path instead of the broad package tour, continue with:
+
+- [CARRIED_HANDOFF_DEMO.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/CARRIED_HANDOFF_DEMO.md)
+
+If you want the shortest neutral external-adoption bundle, continue with:
+
+- [PARTNER_READY_PATH.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/PARTNER_READY_PATH.md)
+- [PUBLIC_DEMO_SCRIPT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/PUBLIC_DEMO_SCRIPT.md)
+- [EXAMPLE_PATHS.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/EXAMPLE_PATHS.md)
+- `node examples/partner_launch_walkthrough.js`
+
 ## 3. Verify The Whole Package
 
 Run:
@@ -40,6 +53,13 @@ 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)
+- [PROGRAM_STATUS.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/PROGRAM_STATUS.md)
+- [OPERATOR_START_HERE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/OPERATOR_START_HERE.md)
+- [OPERATIONS_RUNBOOK.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/OPERATIONS_RUNBOOK.md)
+- [PROGRAM_COMPLETE_RELEASE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/PROGRAM_COMPLETE_RELEASE.md)
+- [WHY_XYTARA_XOONYA.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/WHY_XYTARA_XOONYA.md)
+- [CARRIED_HANDOFF_DEMO.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/CARRIED_HANDOFF_DEMO.md)
+- [PARTNER_READY_PATH.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/PARTNER_READY_PATH.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)
@@ -48,6 +68,7 @@ For long-term product understanding, read:
 
 Continue with:
 
+- [ADAPTER_START_HERE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/ADAPTER_START_HERE.md)
 - [adapters/AUTHORING_GUIDE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/adapters/AUTHORING_GUIDE.md)
 - [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)
@@ -61,3 +82,14 @@ The main public path is no longer "read every milestone layer."
 It is:
 
 discover -> preview/quote -> execute -> inspect -> hand off to `xoonya`
+
+## 7. If You Are Operating The Closed Program
+
+Use:
+
+- [PROGRAM_STATUS.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/PROGRAM_STATUS.md)
+- [OPERATOR_START_HERE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/OPERATOR_START_HERE.md)
+
+If you depend on hidden-account grants, credits, or usage meters in production, set `XYTARA_STATE_FILE` to a path on persistent disk before you trust restart durability.
+
+If your host does not provide persistent disk, use [SUPABASE_RUNTIME_STATE_SETUP.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/SUPABASE_RUNTIME_STATE_SETUP.md) instead.

package/SUPABASE_RUNTIME_STATE_SETUP.md

@@ -0,0 +1,61 @@
+# 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/WHY_XYTARA_XOONYA.md

@@ -0,0 +1,63 @@
+# 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/adapters/examples/minimal-third-party-execution-adapter.js

@@ -0,0 +1,61 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const manifest = JSON.parse(
+  fs.readFileSync(path.resolve(__dirname, "minimal-third-party-execution-adapter.manifest.json"), "utf8")
+);
+
+async function getHealth() {
+  return {
+    status: "ok",
+    readiness: "ready",
+    adapter_id: manifest.adapter_id
+  };
+}
+
+function describeCapabilities() {
+  return {
+    adapter_id: manifest.adapter_id,
+    adapter_class: manifest.adapter_class,
+    capabilities: manifest.capabilities.slice(),
+    execution_modes: Array.isArray(manifest.execution_modes) ? manifest.execution_modes.slice() : []
+  };
+}
+
+async function preview(request) {
+  return {
+    adapter_id: manifest.adapter_id,
+    accepted: true,
+    preview: {
+      task_ref: request && request.task_ref ? request.task_ref : "example.task",
+      mode: "preview",
+      echoed_body: request && request.body ? request.body : {}
+    }
+  };
+}
+
+async function execute(request) {
+  return {
+    adapter_id: manifest.adapter_id,
+    status: "completed",
+    result: {
+      task_ref: request && request.task_ref ? request.task_ref : "example.task",
+      mode: "execute",
+      echoed_body: request && request.body ? request.body : {}
+    },
+    proof_facts: {
+      emits_proof_compatible_facts: manifest.proof_contract.emits_proof_compatible_facts,
+      proof_mode: manifest.proof_contract.proof_mode
+    }
+  };
+}
+
+module.exports = {
+  manifest,
+  getHealth,
+  describeCapabilities,
+  preview,
+  execute
+};

package/adapters/examples/minimal-third-party-execution-adapter.manifest.json

@@ -0,0 +1,79 @@
+{
+  "adapter_id": "partner.execution.minimal_echo",
+  "adapter_class": "execution_adapter",
+  "adapter_version": "0.1.0",
+  "interface_version": "commerce-adapter-interface/v1",
+  "display_name": "Minimal Third-Party Echo Adapter",
+  "description": "Minimal third-party execution adapter starter for external builders copying the public xytara contract.",
+  "capabilities": [
+    "task.execute",
+    "task.preview"
+  ],
+  "compatibility": {
+    "node": ">=18",
+    "commerce_contract": "xytara/v1",
+    "proof_contract": "xoonya/v1"
+  },
+  "health_contract": {
+    "check_kind": "self_reported",
+    "supports_readiness": true
+  },
+  "idempotency_contract": {
+    "strategy": "caller_supplied_key",
+    "scope": "task_execution"
+  },
+  "failure_contract": {
+    "categories": [
+      "invalid_input",
+      "timeout",
+      "upstream_unavailable"
+    ],
+    "retryable_categories": [
+      "timeout",
+      "upstream_unavailable"
+    ]
+  },
+  "proof_contract": {
+    "emits_proof_compatible_facts": true,
+    "proof_mode": "execution_facts_only"
+  },
+  "latency_class": "interactive",
+  "pricing_basis": "per_task",
+  "execution_modes": [
+    "sync"
+  ],
+  "required_secrets": [
+    "MINIMAL_EXECUTION_TOKEN"
+  ],
+  "required_permissions": [
+    "network:outbound"
+  ],
+  "supported_profiles": [
+    "partner"
+  ],
+  "supported_regions": [
+    "global"
+  ],
+  "supported_settlement_modes": [
+    "evm_payment"
+  ],
+  "registration_contract": {
+    "integration_id": "partner.execution.minimal_echo",
+    "integration_maturity": "reference_example",
+    "bundled": false,
+    "default_selection_enabled": false,
+    "selection_priority": 600,
+    "requires_explicit_selection": true
+  },
+  "certification_contract": {
+    "certification_state": "reference_example",
+    "certification_scope": [
+      "contract_shape",
+      "example_behavior"
+    ],
+    "verified_with": [
+      "npm run verify:adapters"
+    ],
+    "last_verified_contract_version": "commerce-adapter-interface/v1"
+  }
+}