xytara 2.1.0 → 2.2.0

package/lib/release_history.js

@@ -11,7 +11,7 @@ function buildReleaseHistory() {
     release_track: "public_release",
     history: [
       {
-        version: "2.1.0",
+        version: "2.2.0",
         channel: "public_release",
         maturity_posture: "launch_ready",
         headline: "public machine-commerce release-candidate with release-center, announcement, and candidate rehearsal surfaces",

package/lib/runtime_state_store.js

@@ -8,6 +8,16 @@ function normalizeFilePath(filePath) {
   return raw ? path.resolve(raw) : "";
 }
 
+function normalizeUrl(url) {
+  const raw = typeof url === "string" ? url.trim() : "";
+  return raw ? raw.replace(/\/+$/, "") : "";
+}
+
+function normalizeString(value, fallback = "") {
+  const raw = typeof value === "string" ? value.trim() : "";
+  return raw || fallback;
+}
+
 function serializeValue(value) {
   if (value instanceof Map) {
     return {
@@ -52,15 +62,27 @@ function deserializeValue(value) {
 
 function createRuntimeStateStore(config = {}) {
   const filePath = normalizeFilePath(config.filePath);
+  const directoryPath = filePath ? path.dirname(filePath) : "";
   const intervalMs = Math.max(1000, Number.parseInt(String(config.intervalMs || 5000), 10) || 5000);
+  const supabaseUrl = normalizeUrl(config.supabaseUrl);
+  const supabaseServiceRoleKey = normalizeString(config.supabaseServiceRoleKey);
+  const supabaseTable = normalizeString(config.supabaseTable, "xytara_runtime_state");
+  const stateKey = normalizeString(config.stateKey, "default");
+  const storageMode = supabaseUrl && supabaseServiceRoleKey ? "supabase" : filePath ? "file" : "memory";
   let dirty = false;
   let timer = null;
   let lastPersistedAtIso = null;
   let lastFlushSucceeded = false;
   let lastError = null;
+  let snapshotExists = false;
+  let snapshotUpdatedAtIso = null;
+  let snapshotSizeBytes = 0;
+  let remoteConfigured = storageMode === "supabase";
+  let remoteReachable = storageMode !== "supabase";
+  let remoteTableReady = storageMode !== "supabase";
 
   function enabled() {
-    return Boolean(filePath);
+    return storageMode !== "memory";
   }
 
   function markDirty() {
@@ -68,84 +90,246 @@ function createRuntimeStateStore(config = {}) {
     dirty = true;
   }
 
-  function flush(state) {
-    if (!enabled() || !dirty || !state) return false;
+  function applyRestoredState(state, restored) {
+    if (!restored || typeof restored !== "object" || !state) return false;
+    for (const key of Object.keys(state)) {
+      if (Object.prototype.hasOwnProperty.call(restored, key)) {
+        state[key] = restored[key];
+      }
+    }
+    return true;
+  }
+
+  function inspectFileDirectory() {
+    let exists = false;
+    let writable = false;
+    let error = null;
+    if (storageMode !== "file") {
+      return {
+        exists: false,
+        writable: false,
+        error: null
+      };
+    }
+    try {
+      exists = fs.existsSync(directoryPath);
+      if (exists) {
+        fs.accessSync(directoryPath, fs.constants.W_OK);
+        writable = true;
+      }
+    } catch (issue) {
+      writable = false;
+      error = issue;
+    }
+    return {
+      exists,
+      writable,
+      error
+    };
+  }
+
+  async function fetchSupabase(pathname, options = {}) {
+    const response = await fetch(`${supabaseUrl}${pathname}`, {
+      ...options,
+      headers: {
+        apikey: supabaseServiceRoleKey,
+        authorization: `Bearer ${supabaseServiceRoleKey}`,
+        ...(options.headers || {})
+      }
+    });
+    remoteReachable = true;
+    if (!response.ok) {
+      const text = await response.text();
+      const error = new Error(`supabase_runtime_state_${response.status}: ${text || response.statusText}`);
+      error.status = response.status;
+      throw error;
+    }
+    return response;
+  }
+
+  function updateSuccessSnapshotMetadata(persistedAtIso, serializedSnapshot) {
+    lastPersistedAtIso = persistedAtIso;
+    lastFlushSucceeded = true;
+    lastError = null;
+    snapshotExists = true;
+    snapshotUpdatedAtIso = persistedAtIso;
+    snapshotSizeBytes = Buffer.byteLength(JSON.stringify(serializedSnapshot), "utf8");
+  }
+
+  async function flushSupabase(state) {
+    if (!dirty || !state) return false;
+    const persistedAtIso = new Date().toISOString();
+    const serializedSnapshot = serializeValue(state);
+    const payload = [{
+      state_key: stateKey,
+      snapshot: serializedSnapshot,
+      persisted_at_iso: persistedAtIso
+    }];
+    try {
+      await fetchSupabase(`/rest/v1/${encodeURIComponent(supabaseTable)}?on_conflict=state_key`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          prefer: "resolution=merge-duplicates,return=minimal"
+        },
+        body: JSON.stringify(payload)
+      });
+      remoteTableReady = true;
+      dirty = false;
+      updateSuccessSnapshotMetadata(persistedAtIso, serializedSnapshot);
+      return true;
+    } catch (error) {
+      lastFlushSucceeded = false;
+      lastError = error;
+      remoteReachable = false;
+      remoteTableReady = false;
+      throw error;
+    }
+  }
+
+  function flushFile(state) {
+    if (!dirty || !state) return false;
     try {
       fs.mkdirSync(path.dirname(filePath), { recursive: true });
       const tempPath = `${filePath}.tmp`;
+      const persistedAtIso = new Date().toISOString();
+      const serializedSnapshot = serializeValue(state);
       const snapshot = {
-        persisted_at_iso: new Date().toISOString(),
-        state: serializeValue(state)
+        persisted_at_iso: persistedAtIso,
+        state: serializedSnapshot
       };
       fs.writeFileSync(tempPath, JSON.stringify(snapshot, null, 2), "utf8");
       fs.renameSync(tempPath, filePath);
       dirty = false;
-      lastPersistedAtIso = snapshot.persisted_at_iso;
+      updateSuccessSnapshotMetadata(persistedAtIso, serializedSnapshot);
+      return true;
+    } catch (error) {
+      lastFlushSucceeded = false;
+      lastError = error;
+      throw error;
+    }
+  }
+
+  async function flush(state) {
+    if (!enabled() || !dirty || !state) return false;
+    if (storageMode === "supabase") {
+      return flushSupabase(state);
+    }
+    if (storageMode === "file") {
+      return flushFile(state);
+    }
+    return false;
+  }
+
+  async function loadSupabase(state) {
+    try {
+      const response = await fetchSupabase(
+        `/rest/v1/${encodeURIComponent(supabaseTable)}?state_key=eq.${encodeURIComponent(stateKey)}&select=snapshot,persisted_at_iso&limit=1`
+      );
+      const rows = await response.json();
+      const row = Array.isArray(rows) && rows[0] ? rows[0] : null;
+      remoteTableReady = true;
+      if (!row || !row.snapshot) {
+        dirty = false;
+        lastFlushSucceeded = true;
+        lastError = null;
+        snapshotExists = false;
+        return false;
+      }
+      const restored = deserializeValue(row.snapshot);
+      const applied = applyRestoredState(state, restored);
+      dirty = false;
+      lastPersistedAtIso = row.persisted_at_iso ? String(row.persisted_at_iso) : null;
       lastFlushSucceeded = true;
       lastError = null;
-      return true;
+      snapshotExists = applied;
+      snapshotUpdatedAtIso = lastPersistedAtIso;
+      snapshotSizeBytes = Buffer.byteLength(JSON.stringify(row.snapshot), "utf8");
+      return applied;
     } catch (error) {
       lastFlushSucceeded = false;
       lastError = error;
+      remoteReachable = false;
+      remoteTableReady = false;
       throw error;
     }
   }
 
-  function load(state) {
-    if (!enabled() || !state || !fs.existsSync(filePath)) return false;
+  async function loadFile(state) {
+    if (!state || !fs.existsSync(filePath)) return false;
     const raw = fs.readFileSync(filePath, "utf8");
     const parsed = JSON.parse(raw);
     const restored = deserializeValue(parsed && parsed.state ? parsed.state : parsed);
-    if (!restored || typeof restored !== "object") return false;
-    for (const key of Object.keys(state)) {
-      if (Object.prototype.hasOwnProperty.call(restored, key)) {
-        state[key] = restored[key];
-      }
-    }
+    const applied = applyRestoredState(state, restored);
     dirty = false;
     lastPersistedAtIso = parsed && parsed.persisted_at_iso ? String(parsed.persisted_at_iso) : null;
     lastFlushSucceeded = true;
     lastError = null;
-    return true;
+    snapshotExists = applied;
+    snapshotUpdatedAtIso = parsed && parsed.persisted_at_iso ? String(parsed.persisted_at_iso) : null;
+    snapshotSizeBytes = Buffer.byteLength(raw, "utf8");
+    return applied;
+  }
+
+  async function load(state) {
+    if (!enabled() || !state) return false;
+    if (storageMode === "supabase") {
+      return loadSupabase(state);
+    }
+    if (storageMode === "file") {
+      return loadFile(state);
+    }
+    return false;
   }
 
   function inspect() {
-    const snapshotExists = enabled() && fs.existsSync(filePath);
-    const stats = snapshotExists ? fs.statSync(filePath) : null;
+    const fileDirectory = inspectFileDirectory();
+    const fileStats = storageMode === "file" && snapshotExists && fs.existsSync(filePath)
+      ? fs.statSync(filePath)
+      : null;
     return {
       enabled: enabled(),
+      storage_mode: storageMode,
       file_path: filePath || null,
+      directory_path: directoryPath || null,
       interval_ms: intervalMs,
       dirty,
       timer_active: Boolean(timer),
+      directory_exists: storageMode === "file" ? fileDirectory.exists : false,
+      directory_writable: storageMode === "file" ? fileDirectory.writable : false,
+      directory_error: storageMode === "file" && fileDirectory.error ? fileDirectory.error.message : null,
       snapshot_exists: snapshotExists,
-      snapshot_size_bytes: stats ? stats.size : 0,
-      snapshot_updated_at_iso: stats ? stats.mtime.toISOString() : null,
+      snapshot_size_bytes: fileStats ? fileStats.size : snapshotSizeBytes,
+      snapshot_updated_at_iso: fileStats ? fileStats.mtime.toISOString() : snapshotUpdatedAtIso,
       last_persisted_at_iso: lastPersistedAtIso,
       last_flush_succeeded: lastFlushSucceeded,
-      last_error: lastError ? lastError.message : null
+      last_error: lastError ? lastError.message : null,
+      supabase_url: supabaseUrl || null,
+      supabase_table: storageMode === "supabase" ? supabaseTable : null,
+      supabase_state_key: storageMode === "supabase" ? stateKey : null,
+      remote_configured: remoteConfigured,
+      remote_reachable: remoteReachable,
+      remote_table_ready: remoteTableReady
     };
   }
 
   function start(state) {
     if (!enabled() || timer) return;
     timer = setInterval(() => {
-      try {
-        flush(state);
-      } catch (error) {
+      Promise.resolve(flush(state)).catch((error) => {
         console.error("runtime state snapshot flush failed", error);
-      }
+      });
     }, intervalMs);
     if (typeof timer.unref === "function") timer.unref();
   }
 
-  function stop(state) {
+  async function stop(state) {
     if (timer) {
       clearInterval(timer);
       timer = null;
     }
     try {
-      flush(state);
+      await flush(state);
     } catch (error) {
       console.error("runtime state snapshot final flush failed", error);
     }
@@ -153,6 +337,7 @@ function createRuntimeStateStore(config = {}) {
 
   return {
     enabled,
+    storageMode,
     filePath,
     intervalMs,
     inspect,

package/lib/soft_launch_pack.js

@@ -0,0 +1,78 @@
+"use strict";
+
+const packageJson = require("../package.json");
+
+function buildSoftLaunchPack() {
+  return {
+    ok: true,
+    product: packageJson.name,
+    category: "machine-commerce-soft-launch-pack",
+    message_core: {
+      headline: "governed machine commerce for builders who need paid execution, reusable credits, and proof-aware followthrough",
+      short_pitch: "xytara gives agent builders and tool authors a machine-commerce spine for quote, pay, execute, inspect, and continue into proof without stitching together separate systems.",
+      when_to_lead: [
+        "when an agent or tool needs a paid capability path",
+        "when repeat usage should use funded account balance instead of repeated manual payment",
+        "when execution must stay inspectable and continue cleanly into proof review"
+      ]
+    },
+    first_targets: [
+      {
+        audience_ref: "agent_builder",
+        first_message: "start with one paid machine run and inspect the release center afterward",
+        first_proof_path: "scenario.direct_pay.trust_verify"
+      },
+      {
+        audience_ref: "adapter_author",
+        first_message: "start from the minimal third-party starter and inspect promotion workflow next",
+        first_proof_path: "partner.execution.minimal_echo"
+      },
+      {
+        audience_ref: "tool_or_marketplace_author",
+        first_message: "start with the launch summary and compare xytara against patchwork alternatives",
+        first_proof_path: "scenario.direct_pay.trust_verify"
+      }
+    ],
+    first_artifacts: {
+      release_center: "/v1/release-center/summary",
+      announcement: "/v1/announcement-pack/summary",
+      outreach_proof: "/v1/outreach-proof/summary",
+      adapter_partners: "/v1/adapter-partners/summary",
+      first_cli: "xytara-release --center --summary",
+      first_run_cli: "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"
+    },
+    outreach_sequence: [
+      "send the short pitch and first proof path to a small builder set",
+      "point each audience to the matching first artifact and cli",
+      "watch which first path they actually try",
+      "collect install, wording, and trust-posture confusion",
+      "tighten docs and first-run friction before broader outreach"
+    ],
+    feedback_watchlist: [
+      "install friction",
+      "first-run confusion",
+      "adapter authoring confusion",
+      "promotion trust-model confusion",
+      "difference between direct pay and funded-runtime paths"
+    ]
+  };
+}
+
+function summarizeSoftLaunchPack() {
+  const pack = buildSoftLaunchPack();
+  return {
+    ok: true,
+    product: pack.product,
+    category: pack.category,
+    target_count: pack.first_targets.length,
+    artifact_count: Object.keys(pack.first_artifacts).length,
+    outreach_step_count: pack.outreach_sequence.length,
+    feedback_watch_count: pack.feedback_watchlist.length,
+    first_cli: pack.first_artifacts.first_cli
+  };
+}
+
+module.exports = {
+  buildSoftLaunchPack,
+  summarizeSoftLaunchPack
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xytara",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Machine commerce SDK for discovery, quoting, execution, lifecycle inspection, and adapters.",
   "main": "index.js",
   "bin": {
@@ -47,6 +47,18 @@
     "PUBLISH_PLAN.md",
     ".env.example",
     "README.md",
+    "PROGRAM_STATUS.md",
+    "OPERATOR_START_HERE.md",
+    "OPERATIONS_RUNBOOK.md",
+    "PROGRAM_COMPLETE_RELEASE.md",
+    "WHY_XYTARA_XOONYA.md",
+    "CARRIED_HANDOFF_DEMO.md",
+    "PARTNER_READY_PATH.md",
+    "EXAMPLE_PATHS.md",
+    "PUBLIC_DEMO_SCRIPT.md",
+    "SUPABASE_RUNTIME_STATE_SETUP.md",
+    "ADAPTER_START_HERE.md",
+    "examples/",
     "BSV_TERANODE_SETUP.md",
     "REAL_PAYMENT_SETUP.md",
     "START_HERE.md",