xytara 2.0.0 → 2.1.0

package/.env.example

@@ -21,3 +21,5 @@ 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=
+XYTARA_STATE_SNAPSHOT_INTERVAL_MS=5000

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/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/PUBLISH_PLAN.md

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

package/README.md

@@ -36,7 +36,7 @@ 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 +120,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 +153,55 @@ 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/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 --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 +638,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 +730,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 +810,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 +829,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 +875,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 +896,17 @@ 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
 
 ## Verification
 

package/RELEASE_CHECKLIST.md

@@ -0,0 +1,10 @@
+# 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. Redeploy the service and verify:
+   - `/v1/release-center/summary`
+   - `/v1/announcement-pack/summary`
+   - `/v1/outreach-proof/summary`
+4. Run the first public proof path.
+5. Only then publish the npm package.

package/RELEASE_NOTES.md

@@ -0,0 +1,19 @@
+# xytara 2.1.0 Release Notes
+
+`xytara` 2.1.0 is the public machine-commerce release-candidate 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`
+
+Recommended first checks:
+
+1. `npm install xytara`
+2. `xytara-release --candidate --summary`
+3. `npm run verify:release-candidate`
+4. inspect `/v1/release-candidate/summary` on the deployed service

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/bin/xytara-release.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+"use strict";
+
+const {
+  buildReleasePack,
+  summarizeReleasePack,
+  buildComparisonPack,
+  summarizeComparisonPack,
+  buildAdoptionPack,
+  summarizeAdoptionPack,
+  buildScenarioPack,
+  summarizeScenarioPack,
+  buildLaunchPack,
+  summarizeLaunchPack
+} = require("../lib/release_pack");
+const {
+  buildReleaseManifest,
+  summarizeReleaseManifest,
+  buildLaunchNotes,
+  summarizeLaunchNotes
+} = require("../lib/release_manifest");
+const {
+  buildReleaseCenter,
+  summarizeReleaseCenter
+} = require("../lib/release_center");
+const {
+  buildReleaseHistory,
+  summarizeReleaseHistory
+} = require("../lib/release_history");
+const {
+  buildPublishPlan,
+  summarizePublishPlan
+} = require("../lib/publish_plan");
+const {
+  buildEcosystemEntryPack,
+  summarizeEcosystemEntryPack
+} = require("../lib/ecosystem_entry");
+const {
+  buildLaunchNarrativePack,
+  summarizeLaunchNarrativePack
+} = require("../lib/launch_narrative");
+const {
+  buildOutreachProofPack,
+  summarizeOutreachProofPack
+} = require("../lib/outreach_proof");
+const {
+  buildAnnouncementPack,
+  summarizeAnnouncementPack
+} = require("../lib/announcement_pack");
+const {
+  buildReleaseCandidatePack,
+  summarizeReleaseCandidatePack
+} = require("../lib/release_candidate");
+
+function printUsage() {
+  process.stderr.write(
+    [
+      "Usage:",
+      "  xytara-release [--summary] [--comparison] [--adoption] [--scenarios] [--launch] [--manifest] [--notes] [--center] [--history] [--publish-plan] [--ecosystem] [--narrative] [--outreach-proof] [--announcement] [--candidate] [--pretty]",
+      "",
+      "Options:",
+      "  --summary   Emit the compact release-pack summary",
+      "  --comparison   Emit the launch comparison pack",
+      "  --adoption   Emit the machine-world adoption pack",
+      "  --scenarios   Emit the first-run scenario pack",
+      "  --launch   Emit the compact launch/operator pack",
+      "  --manifest   Emit the release manifest",
+      "  --notes   Emit the release notes artifact",
+      "  --center   Emit the canonical release center artifact",
+      "  --history   Emit the release history artifact",
+      "  --publish-plan   Emit the publish-day command artifact",
+      "  --ecosystem   Emit the ecosystem entry artifact",
+      "  --narrative   Emit the launch narrative artifact",
+      "  --outreach-proof   Emit the outreach proof artifact",
+      "  --announcement   Emit the announcement artifact",
+      "  --candidate   Emit the release candidate artifact",
+      "  --pretty    Pretty-print JSON output"
+    ].join("\n")
+  );
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    printUsage();
+    process.stderr.write("\n");
+    process.exit(0);
+  }
+
+  const summary = args.includes("--summary");
+  const comparison = args.includes("--comparison");
+  const adoption = args.includes("--adoption");
+  const scenarios = args.includes("--scenarios");
+  const launch = args.includes("--launch");
+  const manifest = args.includes("--manifest");
+  const notes = args.includes("--notes");
+  const center = args.includes("--center");
+  const history = args.includes("--history");
+  const publishPlan = args.includes("--publish-plan");
+  const ecosystem = args.includes("--ecosystem");
+  const narrative = args.includes("--narrative");
+  const outreachProof = args.includes("--outreach-proof");
+  const announcement = args.includes("--announcement");
+  const candidate = args.includes("--candidate");
+  const pretty = args.includes("--pretty") || summary;
+  let payload;
+  if (comparison && summary) {
+    payload = summarizeComparisonPack();
+  } else if (comparison) {
+    payload = buildComparisonPack();
+  } else if (adoption && summary) {
+    payload = summarizeAdoptionPack();
+  } else if (adoption) {
+    payload = buildAdoptionPack();
+  } else if (scenarios && summary) {
+    payload = summarizeScenarioPack();
+  } else if (scenarios) {
+    payload = buildScenarioPack();
+  } else if (launch && summary) {
+    payload = summarizeLaunchPack();
+  } else if (launch) {
+    payload = buildLaunchPack();
+  } else if (manifest && summary) {
+    payload = summarizeReleaseManifest();
+  } else if (manifest) {
+    payload = buildReleaseManifest();
+  } else if (notes && summary) {
+    payload = summarizeLaunchNotes();
+  } else if (notes) {
+    payload = buildLaunchNotes();
+  } else if (center && summary) {
+    payload = summarizeReleaseCenter();
+  } else if (center) {
+    payload = buildReleaseCenter();
+  } else if (history && summary) {
+    payload = summarizeReleaseHistory();
+  } else if (history) {
+    payload = buildReleaseHistory();
+  } else if (publishPlan && summary) {
+    payload = summarizePublishPlan();
+  } else if (publishPlan) {
+    payload = buildPublishPlan();
+  } else if (ecosystem && summary) {
+    payload = summarizeEcosystemEntryPack();
+  } else if (ecosystem) {
+    payload = buildEcosystemEntryPack();
+  } else if (narrative && summary) {
+    payload = summarizeLaunchNarrativePack();
+  } else if (narrative) {
+    payload = buildLaunchNarrativePack();
+  } else if (outreachProof && summary) {
+    payload = summarizeOutreachProofPack();
+  } else if (outreachProof) {
+    payload = buildOutreachProofPack();
+  } else if (announcement && summary) {
+    payload = summarizeAnnouncementPack();
+  } else if (announcement) {
+    payload = buildAnnouncementPack();
+  } else if (candidate && summary) {
+    payload = summarizeReleaseCandidatePack();
+  } else if (candidate) {
+    payload = buildReleaseCandidatePack();
+  } else {
+    payload = summary ? summarizeReleasePack() : buildReleasePack();
+  }
+  process.stdout.write(JSON.stringify(payload, null, pretty ? 2 : 0));
+}
+
+main();