xytara 3.1.13 → 3.1.15

package/lib/runtime_state_store.js

@@ -1,369 +1,495 @@
-"use strict";
-
-const fs = require("fs");
-const path = require("path");
-
-function normalizeFilePath(filePath) {
-  const raw = typeof filePath === "string" ? filePath.trim() : "";
-  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;
-}
-
-// Top-level state keys that are PROCESS-LOCAL transient scratch, not durable facts, and
-// must never be snapshotted: persisting them risks restoring a stale entry that briefly
-// misbehaves after a restart. Kept out of the snapshot entirely (no write, no restore).
-const TRANSIENT_STATE_KEYS = new Set(["inFlightPaymentAuthorizations"]);
-
-function stateForSnapshot(state) {
-  if (!state || typeof state !== "object" || Array.isArray(state)) return state;
-  const snapshotSource = {};
-  for (const [key, value] of Object.entries(state)) {
-    if (TRANSIENT_STATE_KEYS.has(key)) continue;
-    snapshotSource[key] = value;
-  }
-  return snapshotSource;
-}
-
-function serializeValue(value) {
-  if (value instanceof Map) {
-    return {
-      __runtime_state_kind: "Map",
-      value: Array.from(value.entries()).map(([key, entry]) => [key, serializeValue(entry)])
-    };
-  }
-  if (value instanceof Set) {
-    return {
-      __runtime_state_kind: "Set",
-      value: Array.from(value.values()).map((entry) => serializeValue(entry))
-    };
-  }
-  if (Array.isArray(value)) {
-    return value.map((entry) => serializeValue(entry));
-  }
-  if (value && typeof value === "object") {
-    return Object.fromEntries(
-      Object.entries(value).map(([key, entry]) => [key, serializeValue(entry)])
-    );
-  }
-  return value;
-}
-
-function deserializeValue(value) {
-  if (Array.isArray(value)) {
-    return value.map((entry) => deserializeValue(entry));
-  }
-  if (!value || typeof value !== "object") {
-    return value;
-  }
-  if (value.__runtime_state_kind === "Map" && Array.isArray(value.value)) {
-    return new Map(value.value.map((entry) => [entry[0], deserializeValue(entry[1])]));
-  }
-  if (value.__runtime_state_kind === "Set" && Array.isArray(value.value)) {
-    return new Set(value.value.map((entry) => deserializeValue(entry)));
-  }
-  return Object.fromEntries(
-    Object.entries(value).map(([key, entry]) => [key, deserializeValue(entry)])
-  );
-}
-
-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 storageMode !== "memory";
-  }
-
-  function markDirty() {
-    if (!enabled()) return;
-    dirty = true;
-  }
-
-  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(stateForSnapshot(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(stateForSnapshot(state));
-      const snapshot = {
-        persisted_at_iso: persistedAtIso,
-        state: serializedSnapshot
-      };
-      fs.writeFileSync(tempPath, JSON.stringify(snapshot, null, 2), "utf8");
-      fs.renameSync(tempPath, filePath);
-      dirty = false;
-      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;
-      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;
-    }
-  }
-
-  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);
-    const applied = applyRestoredState(state, restored);
-    dirty = false;
-    lastPersistedAtIso = parsed && parsed.persisted_at_iso ? String(parsed.persisted_at_iso) : null;
-    lastFlushSucceeded = true;
-    lastError = null;
-    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 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: 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,
-      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(() => {
-      Promise.resolve(flush(state)).catch((error) => {
-        console.error("runtime state snapshot flush failed", error);
-      });
-    }, intervalMs);
-    if (typeof timer.unref === "function") timer.unref();
-  }
-
-  async function stop(state) {
-    if (timer) {
-      clearInterval(timer);
-      timer = null;
-    }
-    try {
-      await flush(state);
-    } catch (error) {
-      console.error("runtime state snapshot final flush failed", error);
-    }
-  }
-
-  return {
-    enabled,
-    storageMode,
-    filePath,
-    intervalMs,
-    inspect,
-    load,
-    markDirty,
-    flush,
-    start,
-    stop
-  };
-}
-
-module.exports = {
-  createRuntimeStateStore
-};
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+
+function normalizeFilePath(filePath) {
+  const raw = typeof filePath === "string" ? filePath.trim() : "";
+  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;
+}
+
+// Top-level state keys that are PROCESS-LOCAL transient scratch, not durable facts, and
+// must never be snapshotted: persisting them risks restoring a stale entry that briefly
+// misbehaves after a restart. Kept out of the snapshot entirely (no write, no restore).
+const TRANSIENT_STATE_KEYS = new Set(["inFlightPaymentAuthorizations"]);
+
+function stateForSnapshot(state) {
+  if (!state || typeof state !== "object" || Array.isArray(state)) return state;
+  const snapshotSource = {};
+  for (const [key, value] of Object.entries(state)) {
+    if (TRANSIENT_STATE_KEYS.has(key)) continue;
+    snapshotSource[key] = value;
+  }
+  return snapshotSource;
+}
+
+function serializeValue(value) {
+  if (value instanceof Map) {
+    return {
+      __runtime_state_kind: "Map",
+      value: Array.from(value.entries()).map(([key, entry]) => [key, serializeValue(entry)])
+    };
+  }
+  if (value instanceof Set) {
+    return {
+      __runtime_state_kind: "Set",
+      value: Array.from(value.values()).map((entry) => serializeValue(entry))
+    };
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => serializeValue(entry));
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, serializeValue(entry)])
+    );
+  }
+  return value;
+}
+
+function deserializeValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => deserializeValue(entry));
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  if (value.__runtime_state_kind === "Map" && Array.isArray(value.value)) {
+    return new Map(value.value.map((entry) => [entry[0], deserializeValue(entry[1])]));
+  }
+  if (value.__runtime_state_kind === "Set" && Array.isArray(value.value)) {
+    return new Set(value.value.map((entry) => deserializeValue(entry)));
+  }
+  return Object.fromEntries(
+    Object.entries(value).map(([key, entry]) => [key, deserializeValue(entry)])
+  );
+}
+
+function createRuntimeStateStore(config = {}) {
+  const filePath = normalizeFilePath(config.filePath);
+  const directoryPath = filePath ? path.dirname(filePath) : "";
+  const intervalMs = Math.max(1000, Number.parseInt(String(config.intervalMs || 15000), 10) || 15000);
+  // Rolling history (Supabase mode): every historyIntervalMs, the snapshot is ALSO written to one of
+  // historySlots rotating rows (`<stateKey>::history::<n>`) in the same table, so a bad write or a
+  // logical clobber of the main row can be rolled back. 0 disables. Off-site copies are separate
+  // (see scripts/state_backup_offsite.js).
+  const historyIntervalMs = config.historyIntervalMs === undefined || config.historyIntervalMs === null || config.historyIntervalMs === ""
+    ? 3600000
+    : Math.max(0, Number(config.historyIntervalMs) || 0);
+  const historySlots = Math.max(1, Math.min(168, Number.parseInt(String(config.historySlots || 24), 10) || 24));
+  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 supabaseTimeoutMs = Math.max(1000, Number.parseInt(String(config.supabaseTimeoutMs || process.env.XYTARA_SUPABASE_TIMEOUT_MS || 10000), 10) || 10000);
+  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";
+  // WRITE GUARD: nothing is written until the durable snapshot has been read successfully (a
+  // restore, or a confirmed "no snapshot yet"). If the boot-time load fails (e.g. the backend
+  // times out), the process runs on empty state — and writing that would OVERWRITE the good
+  // snapshot. Instead flushes are refused and the load is retried; on success the snapshot is
+  // merged under whatever happened since boot, and only then do writes resume.
+  // Content digest of the last snapshot actually persisted: an unchanged snapshot is never rewritten.
+  let lastPersistedDigest = null;
+  let skippedUnchangedWrites = 0;
+  let lastHistoryAtMs = 0;
+  let lastHistorySlot = null;
+  let lastHistoryError = null;
+  let restoreConfirmed = false;
+  let restoreAttempts = 0;
+  let lastRestoreAttemptAtIso = null;
+  let restoreMergedAfterBoot = false;
+
+  function enabled() {
+    return storageMode !== "memory";
+  }
+
+  // Merge a restored snapshot UNDER the live in-memory state (used only when a restore succeeds
+  // after the process already started on empty state): collections are unioned with live entries
+  // winning; scalars/objects take the restored (durable) value.
+  function mergeRestoredState(state, restored) {
+    if (!restored || typeof restored !== "object" || !state) return false;
+    for (const key of Object.keys(state)) {
+      if (!Object.prototype.hasOwnProperty.call(restored, key)) continue;
+      const live = state[key];
+      const durable = restored[key];
+      if (live instanceof Map && durable instanceof Map) {
+        state[key] = new Map([...durable, ...live]);
+      } else if (live instanceof Set && durable instanceof Set) {
+        state[key] = new Set([...durable, ...live]);
+      } else if (Array.isArray(live) && Array.isArray(durable)) {
+        const seen = new Set(durable.map((entry) => JSON.stringify(entry)));
+        state[key] = durable.concat(live.filter((entry) => !seen.has(JSON.stringify(entry))));
+      } else {
+        state[key] = durable;
+      }
+    }
+    return true;
+  }
+
+  function markDirty() {
+    if (!enabled()) return;
+    dirty = true;
+  }
+
+  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 = {}) {
+    // Bounded: a hung Supabase must never stall boot (the server waits for the restore before it
+    // listens) or a flush. A timeout is just a failed attempt; the write guard handles the rest.
+    const response = await fetch(`${supabaseUrl}${pathname}`, {
+      signal: options.signal || AbortSignal.timeout(supabaseTimeoutMs),
+      ...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, snapshotJson) {
+    lastPersistedAtIso = persistedAtIso;
+    lastFlushSucceeded = true;
+    lastError = null;
+    snapshotExists = true;
+    snapshotUpdatedAtIso = persistedAtIso;
+    snapshotSizeBytes = Buffer.byteLength(snapshotJson, "utf8");
+  }
+
+  function digestOf(json) {
+    return crypto.createHash("sha256").update(json, "utf8").digest("hex");
+  }
+
+  function upsertRowBody(key, snapshotJson, persistedAtIso) {
+    return `[{"state_key":${JSON.stringify(key)},"snapshot":${snapshotJson},"persisted_at_iso":${JSON.stringify(persistedAtIso)}}]`;
+  }
+
+  async function upsertSupabaseRow(key, snapshotJson, persistedAtIso) {
+    await fetchSupabase(`/rest/v1/${encodeURIComponent(supabaseTable)}?on_conflict=state_key`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        prefer: "resolution=merge-duplicates,return=minimal"
+      },
+      body: upsertRowBody(key, snapshotJson, persistedAtIso)
+    });
+  }
+
+  // Best-effort rolling history copy; never fails the main flush.
+  async function maybeWriteHistory(snapshotJson, persistedAtIso) {
+    if (historyIntervalMs <= 0) return;
+    const nowMs = Date.parse(persistedAtIso);
+    if (lastHistoryAtMs && nowMs - lastHistoryAtMs < historyIntervalMs) return;
+    const slot = Math.floor(nowMs / historyIntervalMs) % historySlots;
+    try {
+      await upsertSupabaseRow(`${stateKey}::history::${slot}`, snapshotJson, persistedAtIso);
+      lastHistoryAtMs = nowMs;
+      lastHistorySlot = slot;
+      lastHistoryError = null;
+    } catch (error) {
+      lastHistoryError = error;
+    }
+  }
+
+  async function flushSupabase(state) {
+    if (!dirty || !state) return false;
+    const persistedAtIso = new Date().toISOString();
+    const snapshotJson = JSON.stringify(serializeValue(stateForSnapshot(state)));
+    const digest = digestOf(snapshotJson);
+    if (digest === lastPersistedDigest) {
+      // Nothing changed since the last successful write (e.g. a read-only POST): skip the rewrite.
+      dirty = false;
+      skippedUnchangedWrites += 1;
+      return false;
+    }
+    try {
+      await upsertSupabaseRow(stateKey, snapshotJson, persistedAtIso);
+      remoteTableReady = true;
+      dirty = false;
+      lastPersistedDigest = digest;
+      updateSuccessSnapshotMetadata(persistedAtIso, snapshotJson);
+      await maybeWriteHistory(snapshotJson, persistedAtIso);
+      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(stateForSnapshot(state));
+      const snapshotJson = JSON.stringify(serializedSnapshot);
+      const digest = digestOf(snapshotJson);
+      if (digest === lastPersistedDigest) {
+        dirty = false;
+        skippedUnchangedWrites += 1;
+        return false;
+      }
+      const snapshot = {
+        persisted_at_iso: persistedAtIso,
+        state: serializedSnapshot
+      };
+      fs.writeFileSync(tempPath, JSON.stringify(snapshot, null, 2), "utf8");
+      fs.renameSync(tempPath, filePath);
+      dirty = false;
+      lastPersistedDigest = digest;
+      updateSuccessSnapshotMetadata(persistedAtIso, snapshotJson);
+      return true;
+    } catch (error) {
+      lastFlushSucceeded = false;
+      lastError = error;
+      throw error;
+    }
+  }
+
+  async function flush(state) {
+    if (!enabled() || !dirty || !state) return false;
+    if (!restoreConfirmed) return false; // never overwrite a snapshot we have not read yet
+    if (storageMode === "supabase") {
+      return flushSupabase(state);
+    }
+    if (storageMode === "file") {
+      return flushFile(state);
+    }
+    return false;
+  }
+
+  async function loadSupabase(state, options = {}) {
+    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 = Boolean(options.merge && dirty);
+        lastFlushSucceeded = true;
+        lastError = null;
+        snapshotExists = false;
+        return false;
+      }
+      const restored = deserializeValue(row.snapshot);
+      const applied = options.merge ? mergeRestoredState(state, restored) : applyRestoredState(state, restored);
+      // After a late merge the live state now holds snapshot + post-boot changes: persist it.
+      dirty = Boolean(options.merge);
+      lastPersistedAtIso = row.persisted_at_iso ? String(row.persisted_at_iso) : null;
+      lastFlushSucceeded = true;
+      lastError = null;
+      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;
+    }
+  }
+
+  async function loadFile(state, options = {}) {
+    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);
+    const applied = options.merge ? mergeRestoredState(state, restored) : applyRestoredState(state, restored);
+    dirty = Boolean(options.merge);
+    lastPersistedAtIso = parsed && parsed.persisted_at_iso ? String(parsed.persisted_at_iso) : null;
+    lastFlushSucceeded = true;
+    lastError = null;
+    snapshotExists = applied;
+    snapshotUpdatedAtIso = parsed && parsed.persisted_at_iso ? String(parsed.persisted_at_iso) : null;
+    snapshotSizeBytes = Buffer.byteLength(raw, "utf8");
+    return applied;
+  }
+
+  // options.merge: the process already ran on empty state, so merge the snapshot under the live
+  // state instead of replacing it. Any successful read (restore OR confirmed-empty) unlocks writes;
+  // a failed read leaves writes locked and the error propagates to the caller.
+  async function load(state, options = {}) {
+    if (!enabled() || !state) return false;
+    restoreAttempts += 1;
+    lastRestoreAttemptAtIso = new Date().toISOString();
+    let result = false;
+    if (storageMode === "supabase") {
+      result = await loadSupabase(state, options);
+    } else if (storageMode === "file") {
+      result = await loadFile(state, options);
+    }
+    restoreConfirmed = true;
+    if (options.merge) restoreMergedAfterBoot = true;
+    return result;
+  }
+
+  function restoreConfirmedState() {
+    return restoreConfirmed;
+  }
+
+  function inspect() {
+    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: 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,
+      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,
+      skipped_unchanged_writes: skippedUnchangedWrites,
+      history_interval_ms: storageMode === "supabase" ? historyIntervalMs : null,
+      history_slots: storageMode === "supabase" ? historySlots : null,
+      last_history_at_iso: lastHistoryAtMs ? new Date(lastHistoryAtMs).toISOString() : null,
+      last_history_slot: lastHistorySlot,
+      last_history_error: lastHistoryError ? lastHistoryError.message : null,
+      restore_confirmed: restoreConfirmed,
+      writes_locked_until_restore: enabled() && !restoreConfirmed,
+      restore_attempts: restoreAttempts,
+      last_restore_attempt_at_iso: lastRestoreAttemptAtIso,
+      restore_merged_after_boot: restoreMergedAfterBoot
+    };
+  }
+
+  // onRestored(restored): optional callback when a deferred restore finally succeeds.
+  function start(state, onRestored) {
+    if (!enabled() || timer) return;
+    let busy = false;
+    timer = setInterval(() => {
+      if (busy) return;
+      busy = true;
+      const step = restoreConfirmed
+        ? Promise.resolve(flush(state))
+        : Promise.resolve(load(state, { merge: true })).then((restored) => {
+            console.log("xytara runtime state restore succeeded after boot; writes unlocked");
+            if (typeof onRestored === "function") onRestored(restored);
+          });
+      step.catch((error) => {
+        console.error(restoreConfirmed ? "runtime state snapshot flush failed" : "runtime state restore retry failed (writes stay locked)", error && error.message ? error.message : error);
+      }).finally(() => { busy = false; });
+    }, intervalMs);
+    if (typeof timer.unref === "function") timer.unref();
+  }
+
+  async function stop(state) {
+    if (timer) {
+      clearInterval(timer);
+      timer = null;
+    }
+    try {
+      await flush(state);
+    } catch (error) {
+      console.error("runtime state snapshot final flush failed", error);
+    }
+  }
+
+  return {
+    enabled,
+    storageMode,
+    filePath,
+    intervalMs,
+    inspect,
+    load,
+    restoreConfirmed: restoreConfirmedState,
+    markDirty,
+    flush,
+    start,
+    stop
+  };
+}
+
+module.exports = {
+  createRuntimeStateStore
+};