xytara 2.0.0 → 2.2.0

package/.env.example

@@ -21,3 +21,9 @@ XYTARA_BSV_TERANODE_SATS_PER_USD_CENT=100
 XYTARA_BSV_TERANODE_SETTLEMENT_RUNTIME_MODE=mock
 XYTARA_CREDIT_BRIDGE_BEARER_TOKEN=
 XYTARA_ACCOUNT_AUTH_BEARER_TOKEN=
+XYTARA_STATE_FILE=./var/xytara/runtime-state.json
+XYTARA_STATE_SNAPSHOT_INTERVAL_MS=5000
+XYTARA_SUPABASE_URL=
+XYTARA_SUPABASE_SERVICE_ROLE_KEY=
+XYTARA_SUPABASE_STATE_TABLE=xytara_runtime_state
+XYTARA_SUPABASE_STATE_KEY=default

package/ADAPTER_START_HERE.md

@@ -0,0 +1,56 @@
+# xytara Adapter Start Here
+
+Use this path if you want to build a third-party adapter against public `xytara`.
+
+## Recommended order
+
+1. Read `adapters/AUTHORING_GUIDE.md`.
+2. Read `adapters/ONBOARDING_POSTURE.md`.
+3. Read `adapters/THIRD_PARTY_SUBMISSION_PROCESS.md`.
+4. Run `npm run verify:adapters`.
+5. Validate and review one example bundle:
+   - `node scripts/registry_cli.js validate-bundle --example protocol`
+   - `node scripts/registry_cli.js review-bundle --example protocol`
+6. Inspect promotion posture:
+   - `node scripts/registry_cli.js promotion-readiness --integration partner.protocol.acme_mcp`
+   - `node scripts/registry_cli.js promotion-action-set --integration partner.protocol.acme_mcp`
+7. When you want the explicit staged-to-trusted walkthrough, continue with:
+   - `ADAPTER_PROMOTION_START_HERE.md`
+
+## Fastest copy-and-adapt starter
+
+If you want the shortest third-party starter path, copy these and rename them:
+
+- `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`
+
+## Adapter classes
+
+- `execution_adapter`
+- `payment_rail_adapter`
+- `settlement_adapter`
+- `agent_protocol_adapter`
+- `identity_registry_adapter`
+
+## Artifact stack
+
+Every serious third-party integration should converge on:
+
+1. adapter manifest
+2. registration record
+3. certification pack
+4. submission bundle
+5. submission bundle set when multiple integrations are reviewed together
+6. registry snapshot for normalized review/import posture
+
+## Public review surfaces
+
+- `/v1/integrations/summary`
+- `/v1/integrations/promotion-readiness`
+- `/v1/integrations/promotion-actions`
+- `/v1/integrations/review/submission-bundle`
+- `/v1/integrations/review/submission-bundle-set`
+- `/v1/integrations/review/registry-snapshot`

package/BSV_TERANODE_SETUP.md

@@ -26,12 +26,29 @@ XYTARA_BSV_TERANODE_MERCHANT_LABEL=naxytra-runtime
 XYTARA_BSV_TERANODE_USE_METANET=false
 XYTARA_BSV_TERANODE_SATS_PER_USD_CENT=100
 XYTARA_BSV_TERANODE_SETTLEMENT_RUNTIME_MODE=mock
+XYTARA_BSV_TERANODE_RPC_URL=
+XYTARA_BSV_TERANODE_RPC_API_KEY=
+XYTARA_BSV_TERANODE_RPC_AUTH_HEADER=authorization
+XYTARA_BSV_TERANODE_RPC_AUTH_SCHEME=
+XYTARA_BSV_TERANODE_OBSERVER_URL=
 ```
 
 Optional:
 
+- `XYTARA_BSV_TERANODE_SETTLEMENT_RUNTIME_MODE`
+  - `mock` keeps the old simulated submit/refresh loop
+  - `observe` accepts a payment-provided `txid` and performs real live confirmation refresh
+  - `arc` submits `raw_tx` through ARC and then performs real live confirmation refresh
 - `XYTARA_BSV_TERANODE_RPC_URL`
-  - present when you have a Teranode-facing endpoint available and want the runtime to know that the live transport is configured
+  - use your ARC submit endpoint, for example `https://arc.taal.com/v1/tx`
+- `XYTARA_BSV_TERANODE_RPC_API_KEY`
+  - required when your ARC provider expects authenticated submission
+- `XYTARA_BSV_TERANODE_RPC_AUTH_HEADER`
+  - defaults to `authorization`
+- `XYTARA_BSV_TERANODE_RPC_AUTH_SCHEME`
+  - leave blank for TAAL-style raw API-key auth, or set `Bearer` if your provider expects it
+- `XYTARA_BSV_TERANODE_OBSERVER_URL`
+  - optional transaction observer base; defaults to `https://api.whatsonchain.com/v1/bsv/<network>`
 
 ## Merchant Destination Routing
 
@@ -70,6 +87,18 @@ For live settlement follow-through after payment acceptance, use:
 - `POST /v1/settlement/bsv-teranode/:settlement_id/submit`
 - `POST /v1/settlement/bsv-teranode/:settlement_id/refresh`
 
+If the signed payment payload already carries:
+
+- `bsv_teranode.txid`
+
+then `observe` mode is enough to turn `xytara` into a live confirmation tracker.
+
+If the signed payment payload also carries:
+
+- `bsv_teranode.raw_tx`
+
+then `arc` mode can submit the raw transaction through ARC before refresh.
+
 ## Notes
 
 - `bsv_teranode` is the canonical public settlement name

package/CARRIED_HANDOFF_DEMO.md

@@ -0,0 +1,60 @@
+# xytara Carried Handoff Demo
+
+This is the fastest concrete cross-repo path after the phase program closed.
+
+The goal is simple:
+
+1. export a result-package handoff from `xytara`
+2. review it with `xoonya`
+3. run the proof-side continuation
+
+## 1. Export A Real Handoff Bundle
+
+From the `xytara` repo root, run:
+
+```bash
+node examples/export_carried_handoff.js
+```
+
+This writes:
+
+```text
+examples/generated.carried-handoff.json
+```
+
+The file is already shaped for `xoonya-review`.
+
+## 2. Review It In xoonya
+
+From the `xoonya` repo root, run:
+
+```bash
+xoonya-review --file ../xytara/examples/generated.carried-handoff.json --summary
+```
+
+Or run the packaged example:
+
+```bash
+node examples/review_carried_handoff.js --file ../xytara/examples/generated.carried-handoff.json
+```
+
+## 3. What This Proves
+
+This is the clearest public adoption story now that the phase program is complete:
+
+- `xytara` does discovery, execution, and handoff export
+- `xoonya` does carried review and proof-side followthrough
+- the cross-repo seam is an inspectable bundle, not an undocumented internal jump
+
+## 4. Related Surfaces
+
+Runtime side:
+
+- `POST /v1/transaction-center/result-packages/export`
+- `GET /v1/transaction-center/result-package/export-template`
+
+Proof side:
+
+- `POST /v1/proof-center/result-package-handoff/review/summary`
+- `POST /v1/proof-center/result-package-handoff/run`
+- `xoonya-review --file ./handoff.json --summary`

package/EXAMPLE_PATHS.md

@@ -0,0 +1,53 @@
+# xytara Example Paths
+
+These are the recommended public examples for `xytara`.
+
+## Broad package tour
+
+Run:
+
+```bash
+node examples/quickstart.js
+```
+
+Use this when you want the widest package-level walkthrough.
+
+## Cross-repo carried handoff
+
+Run:
+
+```bash
+node examples/export_carried_handoff.js
+```
+
+Use this when you want the clearest handoff into `xoonya`.
+
+## Partner launch walkthrough
+
+Run:
+
+```bash
+node examples/partner_launch_walkthrough.js
+```
+
+Use this when you want the shortest release and launch oriented runtime story.
+
+## Funded runtime walkthrough
+
+Run:
+
+```bash
+node examples/funded_runtime_walkthrough.js
+```
+
+Use this when you want the reusable-balance posture instead of only the broad quickstart.
+
+## Adapter review walkthrough
+
+Run:
+
+```bash
+node examples/adapter_review_walkthrough.js
+```
+
+Use this when you want the neutral third-party adapter promotion and review path.

package/FINAL_CONTRACT.md

@@ -20,13 +20,13 @@ It consumes and emits proof-compatible facts, but its primary job is machine com
 
 ## Public Release Stance
 
-This product is being prepared as a first public release from private lineage.
+This product is being prepared as a first public release.
 
 That means:
 
-- prior internal SDK and service shapes are design history, not public obligations
+- prior SDK and service experiments are design history, not public obligations
 - useful capability should be preserved where it strengthens the final product
-- historical private helper sprawl does not automatically define the public contract
+- older helper sprawl does not automatically define the public contract
 
 The public baseline should therefore be chosen for product quality, clarity, extensibility, and end-to-end usefulness, not for backward compatibility with prior private repos.
 
@@ -464,9 +464,9 @@ The final commerce product must maintain conformance across:
 - proof integration
 - adapter certification
 
-## What Must Survive From Internal Lineages
+## What Must Survive Across Earlier Product Iterations
 
-From the internal stack, the following semantic wins should survive:
+From earlier product iterations, the following semantic wins should survive:
 
 - clean separation of execution and proof
 - clean separation of execution and settlement
@@ -476,7 +476,7 @@ From the internal stack, the following semantic wins should survive:
 - proof-backed lifecycle state
 - operator-grade visibility
 
-Historical internal labels and names should not survive publicly.
+Historical implementation labels and temporary names should not survive publicly.
 
 ## Final Product Position
 

package/OPERATIONS_RUNBOOK.md

@@ -0,0 +1,65 @@
+# xytara Operations Runbook
+
+Use this runbook for the normal post-program operating posture.
+
+## Daily checks
+
+Run:
+
+```bash
+xytara-release --center --summary
+xytara-release --candidate --summary
+```
+
+Inspect:
+
+- `/v1/release-center/summary`
+- `/v1/release-candidate/summary`
+- `/v1/runtime/durability`
+
+## Runtime durability checks
+
+Healthy durability should show:
+
+- `enabled: true`
+- recoverable posture present
+- no active persistence blocker
+
+If you use hidden-account grants, credits, entitlements, or usage meters, durability is not optional.
+
+## Release confidence checks
+
+Run:
+
+```bash
+npm run verify:examples
+npm run verify:release-candidate
+```
+
+## Partner-facing checks
+
+Keep these ready:
+
+- `PROGRAM_COMPLETE_RELEASE.md`
+- `PARTNER_READY_PATH.md`
+- `PUBLIC_DEMO_SCRIPT.md`
+- `CARRIED_HANDOFF_DEMO.md`
+
+## If durability looks wrong
+
+Check in this order:
+
+1. `/v1/runtime/durability`
+2. persistence configuration
+3. the most recent persisted timestamp
+4. whether the last real grant/write advanced persistence state
+
+## If an external adopter asks “where do I start?”
+
+Point them to:
+
+1. `START_HERE.md`
+2. `PARTNER_READY_PATH.md`
+3. `PUBLIC_DEMO_SCRIPT.md`
+
+Do not send a raw dump of all docs first.

package/OPERATOR_START_HERE.md

@@ -0,0 +1,63 @@
+# xytara Operator Start Here
+
+This is the shortest path for an operator who needs to evaluate `xytara` after the 10-phase program has already closed.
+
+## 1. Confirm Terminal Program State
+
+Run:
+
+```bash
+xytara-release --phases --summary
+xytara-release --phase-10 --summary
+```
+
+Or inspect:
+
+- `GET /v1/phases/summary`
+- `GET /v1/phases/phase-10/gate/summary`
+- `GET /v1/phases/phase-10/completion/summary`
+
+## 2. Confirm Release Posture
+
+Run:
+
+```bash
+xytara-release --center --summary
+xytara-release --candidate --summary
+```
+
+These are the fastest checks for "is the package live, coherent, and publish-shaped?"
+
+## 3. Exercise The Runtime Path
+
+Run:
+
+```bash
+node examples/quickstart.js
+```
+
+This remains the fastest package-level execution story.
+
+## 4. Verify Confidence
+
+Run:
+
+```bash
+npm run verify:all
+npm run verify:release-candidate
+```
+
+For the compact day-two operator path, also read:
+
+- `OPERATIONS_RUNBOOK.md`
+
+## 5. Choose The Next Workstream
+
+After the program is closed, the next useful work is one of:
+
+- productization
+- real partner/internal integration
+- operational hardening
+- launch and release packaging
+
+If you only pick one, pick a real integration and keep the docs/productization work close behind it.

package/PARTNER_READY_PATH.md

@@ -0,0 +1,71 @@
+# xytara Partner-Ready Path
+
+Use this path when you want to evaluate `xytara` as an external runtime and commerce integration surface without relying on private project history.
+
+## What this path is for
+
+This is the shortest partner-facing route for teams that need to:
+
+- evaluate the runtime contract quickly
+- decide whether the reusable credits and direct-pay posture fit their product
+- understand how a neutral third-party adapter reaches reviewable maturity
+- leave with one concrete demo path, one contract path, and one promotion path
+
+## Recommended reading order
+
+1. Read `START_HERE.md`.
+2. Read `CARRIED_HANDOFF_DEMO.md`.
+3. Read `ADAPTER_PARTNER_PATH.md`.
+4. Read `adapters/THIRD_PARTY_SUBMISSION_PROCESS.md`.
+5. Read `SUPABASE_RUNTIME_STATE_SETUP.md` if your deployment does not have persistent disk.
+
+## Recommended first commands
+
+Run these from a cloned `xytara` repository:
+
+```bash
+node examples/quickstart.js
+npm run verify:adapters
+npm run verify:examples
+npm run verify:release-candidate
+node scripts/registry_cli.js review-bundle --file adapters/examples/minimal-third-party-execution.submission-bundle.json
+node scripts/registry_cli.js promotion-readiness --integration partner.execution.minimal_echo
+```
+
+## Recommended first surfaces
+
+- `/v1/release-center/summary`
+- `/v1/adapter-pack/summary`
+- `/v1/adapter-promotion/summary`
+- `/v1/integrations/promotion-readiness`
+- `/v1/runtime/durability`
+
+## First success standard
+
+First success is not "become production default immediately."
+
+First success is:
+
+1. run one end-to-end machine path
+2. understand the default commerce posture
+3. produce one reviewable integration artifact bundle
+4. see promotion blockers as explicit data
+5. understand the proof-side handoff into `xoonya`
+
+## Production readiness rule
+
+If you depend on grants, entitlements, or usage meters surviving restart, do not leave runtime durability implicit.
+
+Use one of these:
+
+- persistent disk plus `XYTARA_STATE_FILE`
+- Supabase-backed state via `SUPABASE_RUNTIME_STATE_SETUP.md`
+
+## Hand-off rule
+
+If an outside team leaves this path with only four references, they should be these:
+
+- `START_HERE.md`
+- `CARRIED_HANDOFF_DEMO.md`
+- `ADAPTER_PARTNER_PATH.md`
+- `adapters/THIRD_PARTY_SUBMISSION_PROCESS.md`

package/PROGRAM_COMPLETE_RELEASE.md

@@ -0,0 +1,63 @@
+# xytara Program-Complete Release
+
+`xytara` is no longer an in-flight phase build. The public 10-phase program is complete, and this repository now represents a release-shaped machine-commerce runtime.
+
+## What is complete
+
+- the full phase program is closed
+- the default runtime path is stable
+- reusable credits and entitlements exist on the public spine
+- cross-repo handoff into `xoonya` is documented and runnable
+- operator and partner-facing docs now exist alongside the package
+- runtime durability is explicit instead of hidden
+- Supabase-backed durability is available when persistent disk is not
+
+## What this release means
+
+This release is the point where `xytara` should be evaluated as a public runtime and commerce surface, not as an unfinished internal roadmap.
+
+The recommended evaluation path is now:
+
+1. read `START_HERE.md`
+2. run `node examples/quickstart.js`
+3. run `node examples/partner_launch_walkthrough.js`
+4. inspect `CARRIED_HANDOFF_DEMO.md`
+5. inspect `PARTNER_READY_PATH.md`
+
+## Public outcome
+
+An external builder should now be able to:
+
+- understand the runtime role quickly
+- run a first machine-commerce path locally
+- inspect release and launch posture through summary surfaces
+- understand partner adapter onboarding without private explanation
+- understand how proof-side followthrough continues into `xoonya`
+
+## Operator outcome
+
+An operator should now be able to:
+
+- inspect runtime durability explicitly
+- verify release-candidate posture quickly
+- onboard generic external builders without writing one-off handoff notes
+- point durability-sensitive adopters to the correct persistence path
+
+## Recommended live checks
+
+- `/v1/release-center/summary`
+- `/v1/release-candidate/summary`
+- `/v1/runtime/durability`
+- `/v1/adapter-partners/summary`
+
+## Release rule
+
+Do not describe this repository as “phase-complete but still basically internal.”
+
+The correct external posture is:
+
+- program complete
+- runtime public
+- partner-ready
+- proof-aware
+- operationally inspectable

package/PROGRAM_STATUS.md

@@ -0,0 +1,57 @@
+# xytara Program Status
+
+`xytara` is no longer in an active milestone-build posture.
+
+The public phase program is complete and the runtime now sits in terminal closeout posture:
+
+- `current_phase: "program_closed"`
+- `completed_phase_count: 10`
+- `active_phase_count: 0`
+- Phase 10 decision: `ready_for_program_closeout`
+
+## What Exists Now
+
+The live package now includes:
+
+- transaction discovery, quoting, execution, and lifecycle inspection
+- release-center and phase-program inspection surfaces
+- production-facing adapter onboarding and third-party registration material
+- multi-rail settlement and continuity surfaces through the full 10-phase program
+- machine-readable closeout state instead of an indefinitely open final phase
+
+## Best Next Work
+
+The highest-value next work is no longer "add more phases."
+
+It is:
+
+1. productization: tighten onboarding, examples, install paths, and first-contact docs
+2. real integrations: wire 1-3 actual partner or internal use cases end to end
+3. operational hardening: improve observability, deployment metadata, and operator audit posture
+4. commercial packaging: prepare demos, launch collateral, and versioned release framing
+
+## Operator Checks
+
+For a quick terminal-state inspection, use:
+
+```bash
+xytara-release --phases --summary
+xytara-release --phase-10 --summary
+xytara-release --center --summary
+```
+
+Or inspect the live HTTP surfaces:
+
+- `GET /v1/phases/summary`
+- `GET /v1/phases/phase-10/completion/summary`
+- `GET /v1/phases/phase-10/gate/summary`
+- `GET /v1/release-center/summary`
+
+## Recommended Reading Order
+
+1. [START_HERE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/START_HERE.md)
+2. [README.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/README.md)
+3. [FINAL_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/FINAL_CONTRACT.md)
+4. [SERVICE_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/SERVICE_CONTRACT.md)
+5. [PROGRAM_STATUS.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/PROGRAM_STATUS.md)
+6. [CARRIED_HANDOFF_DEMO.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/CARRIED_HANDOFF_DEMO.md)

package/PUBLIC_DEMO_SCRIPT.md

@@ -0,0 +1,78 @@
+# xytara Public Demo Script
+
+Use this script when you need a short external-facing walkthrough of `xytara` that does not depend on private project history.
+
+## Goal
+
+Show the runtime side of the public stack in one compact flow:
+
+1. package is live
+2. runtime path is understandable
+3. partner posture is explicit
+4. proof-side continuation exists
+
+## Recommended order
+
+### 1. Release posture
+
+Run:
+
+```bash
+xytara-release --center --summary
+xytara-release --candidate --summary
+```
+
+Or inspect:
+
+- `/v1/release-center/summary`
+- `/v1/release-candidate/summary`
+
+### 2. Runtime durability posture
+
+Inspect:
+
+- `/v1/runtime/durability`
+
+Key sentence to say out loud:
+
+`xytara` treats durability as visible operational posture, not a hidden implementation detail.
+
+### 3. Public runtime walkthrough
+
+Run:
+
+```bash
+node examples/partner_launch_walkthrough.js
+```
+
+Then, if you want the broader package tour:
+
+```bash
+node examples/quickstart.js
+```
+
+### 4. Partner adoption path
+
+Open:
+
+- `PARTNER_READY_PATH.md`
+- `ADAPTER_PARTNER_PATH.md`
+
+Key sentence to say out loud:
+
+Outside teams can reach a reviewable adapter posture without private exceptions.
+
+### 5. Proof continuation
+
+Open:
+
+- `CARRIED_HANDOFF_DEMO.md`
+- `WHY_XYTARA_XOONYA.md`
+
+Key sentence to say out loud:
+
+`xytara` finishes the transaction-side path and hands cleanly into `xoonya` for proof-native completion.
+
+## Good ending line
+
+`xytara` is the public machine-commerce runtime: discover, fund, execute, inspect, and carry forward into proof.

package/PUBLISH_PLAN.md

@@ -0,0 +1,14 @@
+# xytara Publish Plan
+
+1. Run `npm run verify:release-candidate`.
+2. Run `node examples/partner_launch_walkthrough.js`.
+3. Run `npm pack --dry-run --json` and confirm the package contents.
+4. Publish with `npm publish --access public`.
+5. Redeploy the live service surfaces.
+6. Verify:
+   - `/v1/release-candidate/summary`
+   - `/v1/release-center/summary`
+   - `/v1/announcement-pack/summary`
+   - `/v1/outreach-proof/summary`
+   - `/v1/runtime/durability`
+7. Run the first public machine proof path.