holosphere 2.0.0-alpha10 → 2.0.0-alpha11

package/dist/{index-DJXftyvB.js → index-D-jZhliX.js}

@@ -421,12 +421,12 @@ async function createPersistentStorage(namespace, options = {}) {
   const isBrowser = typeof window !== "undefined" && typeof window.indexedDB !== "undefined";
   typeof process !== "undefined" && process.versions && void 0;
   if (isBrowser) {
-    const { IndexedDBStorage } = await import("./indexeddb-storage-BFt6hMeF.js");
+    const { IndexedDBStorage } = await import("./indexeddb-storage-5eiUNsHC.js");
     const storage = new IndexedDBStorage();
     await storage.init(namespace);
     return storage;
   } else {
-    const { MemoryStorage } = await import("./memory-storage-C9HuoL2E.js");
+    const { MemoryStorage } = await import("./memory-storage-CI-gfmuG.js");
     const storage = new MemoryStorage();
     await storage.init(namespace);
     return storage;
@@ -710,6 +710,22 @@ class NostrClient {
       return null;
     }
   }
+  /**
+   * Get event from LRU cache by d-tag path (for local-first reads).
+   * This is always up-to-date because writes update the LRU cache synchronously,
+   * unlike persistent storage which uses batched writes.
+   * @param {string} path - The d-tag path
+   * @param {number} [kind=30000] - Event kind
+   * @returns {Object|null} The cached event or null
+   */
+  getCachedByPath(path, kind2 = 3e4) {
+    const dTagKey = `d:${kind2}:${path}`;
+    const cached = this._eventCache.get(dTagKey);
+    if (cached && cached.events && cached.events[0]) {
+      return cached.events[0];
+    }
+    return null;
+  }
   /**
    * Get all events from persistent storage matching a prefix
    * @param {string} prefix - The path prefix to match
@@ -3996,7 +4012,7 @@ class GunDBBackend extends StorageBackend {
   }
 }
 const name = "holosphere";
-const version$1 = "2.0.0-alpha8";
+const version$1 = "2.0.0-alpha11";
 const description = "Holonic geospatial communication infrastructure combining H3 hexagonal indexing with distributed P2P storage";
 const type = "module";
 const bin = {
@@ -4779,6 +4795,24 @@ async function nostrPut(client, path, data, kind2 = 3e4) {
 async function nostrGet(client, path, kind2 = 3e4, options = {}) {
   const timeout = options.timeout !== void 0 ? options.timeout : 3e4;
   const authors = options.authors || [client.publicKey];
+  if (!options.skipCache && client.getCachedByPath) {
+    const cachedEvent = client.getCachedByPath(path, kind2);
+    if (cachedEvent && cachedEvent.content) {
+      if (authors.includes(cachedEvent.pubkey)) {
+        try {
+          const data = JSON.parse(cachedEvent.content);
+          if (!data || data._deleted) {
+            return null;
+          }
+          if (options.includeAuthor) {
+            data._author = cachedEvent.pubkey;
+          }
+          return data;
+        } catch (error) {
+        }
+      }
+    }
+  }
   if (!options.skipPersistent && client.persistentGet) {
     const persistedEvent = await client.persistentGet(path);
     if (persistedEvent && persistedEvent.content) {
@@ -4997,9 +5031,6 @@ async function nostrDelete(client, path, kind2 = 3e4) {
     } catch (e) {
     }
   }
-  if (client.clearCache) {
-    client.clearCache(path);
-  }
   const coordinate = `${kind2}:${client.publicKey}:${path}`;
   const deletionEvent = {
     kind: 5,
@@ -5018,6 +5049,7 @@ async function nostrDelete(client, path, kind2 = 3e4) {
   }
   return result;
 }
+const DELETE_RATE_LIMIT_MS = 100;
 async function nostrDeleteAll(client, pathPrefix, kind2 = 3e4) {
   const filter = {
     kinds: [kind2],
@@ -5053,7 +5085,8 @@ async function nostrDeleteAll(client, pathPrefix, kind2 = 3e4) {
     return { success: true, count: 0, results: [] };
   }
   const tombstoneResults = [];
-  for (const event of matching) {
+  for (let i = 0; i < matching.length; i++) {
+    const event = matching[i];
     const dTag = event.tags.find((t) => t[0] === "d")[1];
     try {
       const tombstone = {
@@ -5068,8 +5101,8 @@ async function nostrDeleteAll(client, pathPrefix, kind2 = 3e4) {
         } catch (e) {
         }
       }
-      if (client.clearCache) {
-        client.clearCache(dTag);
+      if (i < matching.length - 1 && DELETE_RATE_LIMIT_MS > 0) {
+        await new Promise((resolve) => setTimeout(resolve, DELETE_RATE_LIMIT_MS));
       }
     } catch (error) {
       console.error(`Failed to delete item ${dTag}:`, error);
@@ -5945,7 +5978,7 @@ const sha256 = sha256$1;
 let secp256k1 = null;
 async function loadCrypto() {
   if (!secp256k1) {
-    const module2 = await import("./secp256k1-CreY7Pcl.js");
+    const module2 = await import("./secp256k1-CEwJNcfV.js");
     secp256k1 = module2.secp256k1;
   }
   return secp256k1;
@@ -6610,7 +6643,9 @@ async function addActiveHologram(client, appname, sourceHolon, lensName, dataId,
     sourceData._meta.activeHolograms.push({
       targetHolon,
       created: now,
-      lastUpdated: now
+      lastUpdated: now,
+      platforms: {}
+      // Platform-specific data (e.g., telegram: { messageId: 123 })
     });
   }
   return write(client, sourcePath, sourceData);
@@ -6651,6 +6686,66 @@ async function removeActiveHologram(client, appname, sourceHolon, lensName, data
   }
   return false;
 }
+async function updateActiveHologramPlatform(client, appname, sourceHolon, lensName, dataId, targetHolon, platform, platformData) {
+  let currentAppname = appname;
+  let currentHolon = sourceHolon;
+  let currentLens = lensName;
+  let currentDataId = dataId;
+  let sourcePath = buildPath(currentAppname, currentHolon, currentLens, currentDataId);
+  let sourceData = await read(client, sourcePath);
+  if (!sourceData) {
+    console.warn(`Source data not found at ${sourcePath}`);
+    return false;
+  }
+  let depth = 0;
+  const maxDepth = 10;
+  while (sourceData.hologram === true && sourceData.target && depth < maxDepth) {
+    depth++;
+    currentAppname = sourceData.target.appname || currentAppname;
+    currentHolon = sourceData.target.holonId;
+    currentLens = sourceData.target.lensName || currentLens;
+    currentDataId = sourceData.target.dataId || currentDataId;
+    sourcePath = buildPath(currentAppname, currentHolon, currentLens, currentDataId);
+    sourceData = await read(client, sourcePath);
+    if (!sourceData) {
+      console.warn(`Real source data not found at ${sourcePath}`);
+      return false;
+    }
+  }
+  if (!sourceData._meta || !Array.isArray(sourceData._meta.activeHolograms)) {
+    console.warn(`No activeHolograms found for ${sourcePath}`);
+    return false;
+  }
+  const hologramEntry = sourceData._meta.activeHolograms.find(
+    (h) => h.targetHolon === targetHolon
+  );
+  if (!hologramEntry) {
+    console.warn(`No hologram entry found for target ${targetHolon}`);
+    return false;
+  }
+  if (!hologramEntry.platforms) {
+    hologramEntry.platforms = {};
+  }
+  hologramEntry.platforms[platform] = {
+    ...hologramEntry.platforms[platform],
+    ...platformData,
+    lastUpdated: Date.now()
+  };
+  hologramEntry.lastUpdated = Date.now();
+  return write(client, sourcePath, sourceData);
+}
+async function getActiveHolograms(client, appname, sourceHolon, lensName, dataId, platform = null) {
+  const sourcePath = buildPath(appname, sourceHolon, lensName, dataId);
+  const sourceData = await read(client, sourcePath);
+  if (!sourceData?._meta?.activeHolograms) {
+    return [];
+  }
+  let holograms = sourceData._meta.activeHolograms;
+  if (platform) {
+    holograms = holograms.filter((h) => h.platforms?.[platform]);
+  }
+  return holograms;
+}
 async function refreshActiveHolograms(client, appname, sourceHolon, lensName, dataId, sourceData = null) {
   if (!sourceData) {
     const sourcePath = buildPath(appname, sourceHolon, lensName, dataId);
@@ -6867,6 +6962,7 @@ const hologram = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProp
   cleanupCircularHologramsByIds,
   createHologram,
   deleteHologram,
+  getActiveHolograms,
   getHologramSource,
   isHologram,
   isResolvedHologram,
@@ -6875,6 +6971,7 @@ const hologram = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProp
   removeActiveHologram,
   resolveHologram,
   setupFederation,
+  updateActiveHologramPlatform,
   updateHologramOverrides,
   wouldCreateCircularHologram
 }, Symbol.toStringTag, { value: "Module" }));
@@ -17661,7 +17758,7 @@ class ChainManager {
    */
   async _loadEthers() {
     if (!this.ethers) {
-      const ethersModule = await import("./index-DeZ1xz_s.js");
+      const ethersModule = await import("./index-Bl6rM1NW.js");
       this.ethers = ethersModule;
     }
     return this.ethers;
@@ -26452,7 +26549,7 @@ class ContractDeployer {
    */
   async _loadEthers() {
     if (!this.ethers) {
-      this.ethers = await import("./index-DeZ1xz_s.js");
+      this.ethers = await import("./index-Bl6rM1NW.js");
     }
     return this.ethers;
   }
@@ -26838,7 +26935,7 @@ class ContractOperations {
    */
   async _loadEthers() {
     if (!this.ethers) {
-      this.ethers = await import("./index-DeZ1xz_s.js");
+      this.ethers = await import("./index-Bl6rM1NW.js");
     }
     return this.ethers;
   }
@@ -38194,6 +38291,9 @@ class HoloSphereBase extends HoloSphere$1 {
     this.schemas = /* @__PURE__ */ new Map();
     this._cache = /* @__PURE__ */ new Map();
     this.subscriptionRegistry = new SubscriptionRegistry();
+    this._writeCache = /* @__PURE__ */ new Map();
+    this._pendingWrites = /* @__PURE__ */ new Map();
+    this._deleteCache = /* @__PURE__ */ new Set();
     this._ai = null;
     const openaiKey = config.openaiKey || this._getEnv("OPENAI_API_KEY");
     if (openaiKey) {
@@ -38325,6 +38425,8 @@ class HoloSphereBase extends HoloSphere$1 {
   // === Data Operations ===
   /**
    * Writes data to a specific holon and lens.
+   * By default, write is optimistic (non-blocking) - returns immediately after caching locally.
+   * Data is synced to relays in the background.
    *
    * @param {string} holonId - H3 cell ID for the holon
    * @param {string} lensName - Name of the lens (data category)
@@ -38335,15 +38437,18 @@ class HoloSphereBase extends HoloSphere$1 {
    * @param {boolean} [options.strict] - Override schema strict mode
    * @param {boolean} [options.autoPropagate=true] - Whether to propagate to federated holons
    * @param {Object} [options.propagationOptions] - Options for propagation
-   * @returns {Promise<boolean>} True if write succeeded
+   * @param {boolean} [options.blocking=false] - If true, wait for relay confirmation before returning
+   * @returns {Promise<boolean>} True if write succeeded (or queued for optimistic writes)
    * @throws {ValidationError} If holonId, lensName, or data is invalid
    * @throws {AuthorizationError} If capability token is invalid
    */
   async write(holonId, lensName, data, options = {}) {
-    if (!holonId || typeof holonId !== "string") {
+    if (holonId != null) holonId = String(holonId);
+    if (lensName != null) lensName = String(lensName);
+    if (!holonId) {
       throw new ValidationError$1("ValidationError: holonId must be a non-empty string");
     }
-    if (!lensName || typeof lensName !== "string") {
+    if (!lensName) {
       throw new ValidationError$1("ValidationError: lensName must be a non-empty string");
     }
     if (!data || typeof data !== "object") {
@@ -38358,82 +38463,148 @@ class HoloSphereBase extends HoloSphere$1 {
     }
     if (!data.id) {
       data.id = `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    } else {
+      data.id = String(data.id);
     }
+    if (!data._meta) data._meta = {};
+    data._meta.createdAt = data._meta.createdAt || Date.now();
+    data._meta.updatedAt = Date.now();
     const path = buildPath(this.config.appName, holonId, lensName, data.id);
-    this._log("DEBUG", "write", { holonId, lensName, dataId: data.id, path });
-    const existingData = await read(this.client, path);
-    if (existingData && existingData.hologram === true && existingData.target) {
-      const hologramStructureFields = ["hologram", "soul", "target", "id", "_meta"];
-      const localOverrideFields = Object.keys(existingData).filter((k) => !hologramStructureFields.includes(k));
-      const localData = { ...existingData };
-      const sourceUpdates = {};
-      for (const [key, value] of Object.entries(data)) {
-        if (hologramStructureFields.includes(key) || key === "_hologram") continue;
-        if (localOverrideFields.includes(key)) {
-          localData[key] = value;
-        } else {
-          sourceUpdates[key] = value;
-        }
-      }
-      if (Object.keys(sourceUpdates).length > 0 && options.validate !== false && this.schemas.has(lensName)) {
-        const sourcePath = buildPath(
-          existingData.target.appname || this.config.appName,
-          existingData.target.holonId,
-          existingData.target.lensName,
-          existingData.target.dataId
-        );
-        const currentSourceData = await read(this.client, sourcePath);
-        const mergedSourceData = { ...currentSourceData, ...sourceUpdates };
-        const schemaObj = this.schemas.get(lensName);
-        const strict = options.strict !== void 0 ? options.strict : schemaObj.strict;
-        if (schemaObj.schema && typeof schemaObj.schema === "object" && !schemaObj.schema.$ref) {
-          validate(mergedSourceData, schemaObj.schema, lensName, strict);
-        }
-      }
-      const startTime2 = Date.now();
-      await write(this.client, path, localData);
-      if (Object.keys(sourceUpdates).length > 0) {
-        const sourcePath = buildPath(
-          existingData.target.appname || this.config.appName,
-          existingData.target.holonId,
-          existingData.target.lensName,
-          existingData.target.dataId
-        );
-        await update(this.client, sourcePath, sourceUpdates);
-        await refreshActiveHolograms(
-          this.client,
-          existingData.target.appname || this.config.appName,
-          existingData.target.holonId,
-          existingData.target.lensName,
-          existingData.target.dataId
-        );
+    this._log("DEBUG", "write", { holonId, lensName, dataId: data.id, path, blocking: !!options.blocking });
+    if (options.validate !== false && this.schemas.has(lensName)) {
+      const schemaObj = this.schemas.get(lensName);
+      const strict = options.strict !== void 0 ? options.strict : schemaObj.strict;
+      if (schemaObj.schema && typeof schemaObj.schema === "object" && !schemaObj.schema.$ref) {
+        validate(data, schemaObj.schema, lensName, strict);
       }
-      const endTime2 = Date.now();
+    }
+    this._writeCache.set(path, { data: { ...data }, timestamp: Date.now() });
+    this._deleteCache.delete(path);
+    this._log("DEBUG", "📝 CACHE WRITE", {
+      path,
+      dataId: data.id,
+      cacheSize: this._writeCache.size,
+      mode: options.blocking ? "blocking" : "optimistic"
+    });
+    const syncPromise = this._syncWriteToRelay(holonId, lensName, data, path, options);
+    if (options.blocking) {
+      this._log("DEBUG", "⏳ BLOCKING: Waiting for relay confirmation", { path });
+      return syncPromise;
+    }
+    this._log("DEBUG", "⚡ OPTIMISTIC: Returning immediately, sync in background", { path });
+    return true;
+  }
+  /**
+   * Syncs a write operation to the relay in the background.
+   * Handles hologram writes, propagation, and error logging.
+   *
+   * @private
+   * @param {string} holonId - Holon ID
+   * @param {string} lensName - Lens name
+   * @param {Object} data - Data to write
+   * @param {string} path - Storage path
+   * @param {Object} options - Write options
+   * @returns {Promise<boolean>} True if write succeeded
+   */
+  async _syncWriteToRelay(holonId, lensName, data, path, options) {
+    const startTime = Date.now();
+    this._log("DEBUG", "🔄 RELAY SYNC START", {
+      path,
+      dataId: data.id,
+      relays: this.client?.relays?.map((r) => r.url) || ["local-only"]
+    });
+    try {
+      const existingData = await read(this.client, path);
+      if (existingData && existingData.hologram === true && existingData.target) {
+        this._log("DEBUG", "🔗 Syncing hologram write", { path, target: existingData.target });
+        return this._syncHologramWrite(existingData, data, path, lensName, options);
+      }
+      await write(this.client, path, data);
+      const endTime = Date.now();
+      const duration = endTime - startTime;
       this._metrics.writes++;
       if (!this._metrics.totalWriteTime) this._metrics.totalWriteTime = 0;
-      this._metrics.totalWriteTime += endTime2 - startTime2;
+      this._metrics.totalWriteTime += duration;
+      this._log("DEBUG", "✅ RELAY SYNC SUCCESS", {
+        path,
+        dataId: data.id,
+        duration: `${duration}ms`,
+        totalWrites: this._metrics.writes
+      });
+      const { autoPropagate = true } = options;
+      if (autoPropagate && !data.hologram) {
+        this._log("DEBUG", "📤 Starting propagation", { path });
+        this.propagate(holonId, lensName, data, options.propagationOptions || {}).catch((err) => this._log("WARN", "⚠️ Propagation failed", { path, error: err.message }));
+      }
       return true;
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      this._log("ERROR", "❌ RELAY SYNC FAILED", {
+        path,
+        dataId: data.id,
+        duration: `${duration}ms`,
+        error: error.message,
+        stack: error.stack?.split("\n")[1]?.trim()
+      });
+      this._log("WARN", "💾 Data retained in write cache for retry", { path, cacheSize: this._writeCache.size });
+      return false;
     }
-    if (!data._meta) data._meta = {};
-    data._meta.createdAt = data._meta.createdAt || Date.now();
-    data._meta.updatedAt = Date.now();
-    if (options.validate !== false && this.schemas.has(lensName)) {
+  }
+  /**
+   * Handles hologram write synchronization.
+   *
+   * @private
+   */
+  async _syncHologramWrite(existingData, data, path, lensName, options) {
+    const hologramStructureFields = ["hologram", "soul", "target", "id", "_meta"];
+    const localOverrideFields = Object.keys(existingData).filter((k) => !hologramStructureFields.includes(k));
+    const localData = { ...existingData };
+    const sourceUpdates = {};
+    for (const [key, value] of Object.entries(data)) {
+      if (hologramStructureFields.includes(key) || key === "_hologram") continue;
+      if (localOverrideFields.includes(key)) {
+        localData[key] = value;
+      } else {
+        sourceUpdates[key] = value;
+      }
+    }
+    if (Object.keys(sourceUpdates).length > 0 && options.validate !== false && this.schemas.has(lensName)) {
+      const sourcePath = buildPath(
+        existingData.target.appname || this.config.appName,
+        existingData.target.holonId,
+        existingData.target.lensName,
+        existingData.target.dataId
+      );
+      const currentSourceData = await read(this.client, sourcePath);
+      const mergedSourceData = { ...currentSourceData, ...sourceUpdates };
       const schemaObj = this.schemas.get(lensName);
       const strict = options.strict !== void 0 ? options.strict : schemaObj.strict;
       if (schemaObj.schema && typeof schemaObj.schema === "object" && !schemaObj.schema.$ref) {
-        validate(data, schemaObj.schema, lensName, strict);
+        validate(mergedSourceData, schemaObj.schema, lensName, strict);
       }
     }
     const startTime = Date.now();
-    await write(this.client, path, data);
+    await write(this.client, path, localData);
+    if (Object.keys(sourceUpdates).length > 0) {
+      const sourcePath = buildPath(
+        existingData.target.appname || this.config.appName,
+        existingData.target.holonId,
+        existingData.target.lensName,
+        existingData.target.dataId
+      );
+      await update(this.client, sourcePath, sourceUpdates);
+      await refreshActiveHolograms(
+        this.client,
+        existingData.target.appname || this.config.appName,
+        existingData.target.holonId,
+        existingData.target.lensName,
+        existingData.target.dataId
+      );
+    }
     const endTime = Date.now();
     this._metrics.writes++;
     if (!this._metrics.totalWriteTime) this._metrics.totalWriteTime = 0;
     this._metrics.totalWriteTime += endTime - startTime;
-    const { autoPropagate = true } = options;
-    if (autoPropagate && !data.hologram) {
-      await this.propagate(holonId, lensName, data, options.propagationOptions || {});
-    }
     return true;
   }
   /**
@@ -38537,10 +38708,13 @@ class HoloSphereBase extends HoloSphere$1 {
    * @throws {AuthorizationError} If capability token is invalid
    */
   async read(holonId, lensName, dataId = null, options = {}) {
-    if (!holonId || typeof holonId !== "string") {
+    if (holonId != null) holonId = String(holonId);
+    if (lensName != null) lensName = String(lensName);
+    if (dataId != null) dataId = String(dataId);
+    if (!holonId) {
       throw new ValidationError$1("ValidationError: holonId must be a non-empty string");
     }
-    if (!lensName || typeof lensName !== "string") {
+    if (!lensName) {
       throw new ValidationError$1("ValidationError: lensName must be a non-empty string");
     }
     const capToken = options.capabilityToken || options.capability;
@@ -38554,13 +38728,40 @@ class HoloSphereBase extends HoloSphere$1 {
     let result;
     if (dataId) {
       const path = buildPath(this.config.appName, holonId, lensName, dataId);
-      this._log("DEBUG", "read", { holonId, lensName, dataId, path });
-      result = await read(this.client, path);
-      this._log("DEBUG", "read result", { found: !!result, isHologram: result?.hologram === true });
+      if (this._deleteCache.has(path)) {
+        this._log("DEBUG", "🗑️ CACHE READ: Deleted item", {
+          path,
+          source: "delete-cache",
+          deleteCacheSize: this._deleteCache.size
+        });
+        result = null;
+      } else {
+        const cached = this._writeCache.get(path);
+        if (cached) {
+          const cacheAge = Date.now() - cached.timestamp;
+          this._log("DEBUG", "⚡ CACHE HIT: Write cache", {
+            path,
+            source: "write-cache",
+            cacheAge: `${cacheAge}ms`,
+            writeCacheSize: this._writeCache.size
+          });
+          result = cached.data;
+        } else {
+          this._log("DEBUG", "📖 CACHE MISS: Reading from storage", { path });
+          result = await read(this.client, path);
+          this._log("DEBUG", "💾 STORAGE READ", {
+            path,
+            source: "storage",
+            found: !!result,
+            isHologram: result?.hologram === true
+          });
+        }
+      }
     } else {
       const path = buildPath(this.config.appName, holonId, lensName);
       this._log("DEBUG", "readAll", { holonId, lensName, path });
-      result = await readAll(this.client, path);
+      const storageResult = await readAll(this.client, path);
+      result = this._mergeWithWriteCache(storageResult, path);
       this._log("DEBUG", "readAll result", { count: Array.isArray(result) ? result.length : 0 });
     }
     const { resolveHolograms = true } = options;
@@ -38574,8 +38775,39 @@ class HoloSphereBase extends HoloSphere$1 {
     this._metrics.totalReadTime += endTime - startTime;
     return result;
   }
+  /**
+   * Merges storage results with write cache for readAll operations.
+   * Cached writes take precedence over storage data.
+   * Deleted items are filtered out.
+   *
+   * @private
+   * @param {Array} storageResult - Results from storage
+   * @param {string} pathPrefix - Path prefix for filtering cache
+   * @returns {Array} Merged results
+   */
+  _mergeWithWriteCache(storageResult, pathPrefix) {
+    const results = Array.isArray(storageResult) ? [...storageResult] : [];
+    const resultMap = new Map(results.map((item) => [item.id, item]));
+    for (const [cachedPath, cached] of this._writeCache.entries()) {
+      if (cachedPath.startsWith(pathPrefix + "/")) {
+        const cachedData = cached.data;
+        if (cachedData.id) {
+          resultMap.set(cachedData.id, cachedData);
+        }
+      }
+    }
+    for (const deletedPath of this._deleteCache) {
+      if (deletedPath.startsWith(pathPrefix + "/")) {
+        const dataId = deletedPath.split("/").pop();
+        resultMap.delete(dataId);
+      }
+    }
+    return Array.from(resultMap.values());
+  }
   /**
    * Updates existing data in a specific holon and lens.
+   * By default, update is optimistic (non-blocking) - returns immediately after caching merged data.
+   * Data is synced to relays in the background.
    *
    * @param {string} holonId - H3 cell ID for the holon
    * @param {string} lensName - Name of the lens (data category)
@@ -38585,6 +38817,7 @@ class HoloSphereBase extends HoloSphere$1 {
    * @param {string} [options.capabilityToken] - Capability token for authorization
    * @param {boolean} [options.validate=true] - Whether to validate against schema
    * @param {boolean} [options.strict] - Override schema strict mode
+   * @param {boolean} [options.blocking=false] - If true, wait for relay confirmation before returning
    * @returns {Promise<boolean>} True if update succeeded, false if data not found
    * @throws {ValidationError} If holonId, lensName, dataId, or updates is invalid
    * @throws {AuthorizationError} If capability token is invalid
@@ -38610,11 +38843,16 @@ class HoloSphereBase extends HoloSphere$1 {
       }
     }
     const path = buildPath(this.config.appName, holonId, lensName, dataId);
-    const existingData = await read(this.client, path);
+    const cached = this._writeCache.get(path);
+    const existingData = cached ? cached.data : await read(this.client, path);
+    const dataSource = cached ? "write-cache" : "storage";
     if (!existingData) {
+      this._log("DEBUG", "✏️ UPDATE: Data not found", { path, dataId });
       return false;
     }
+    this._log("DEBUG", "✏️ UPDATE: Found data", { path, dataId, source: dataSource });
     if (existingData.hologram === true && existingData.target) {
+      this._log("DEBUG", "🔗 Updating hologram", { path });
       return this.write(holonId, lensName, { ...existingData, ...updates, id: dataId }, options);
     }
     const mergedData = { ...existingData, ...updates };
@@ -38627,44 +38865,104 @@ class HoloSphereBase extends HoloSphere$1 {
         validate(mergedData, schemaObj.schema, lensName, strict);
       }
     }
-    const startTime = Date.now();
-    await write(this.client, path, mergedData);
-    const endTime = Date.now();
-    this._metrics.writes++;
-    if (!this._metrics.totalWriteTime) this._metrics.totalWriteTime = 0;
-    this._metrics.totalWriteTime += endTime - startTime;
-    if (existingData._meta && existingData._meta.activeHolograms) {
-      await refreshActiveHolograms(this.client, this.config.appName, holonId, lensName, dataId);
+    this._writeCache.set(path, { data: { ...mergedData }, timestamp: Date.now() });
+    this._deleteCache.delete(path);
+    this._log("DEBUG", "✏️ CACHE UPDATE", {
+      path,
+      dataId,
+      updatedFields: Object.keys(updates),
+      cacheSize: this._writeCache.size,
+      mode: options.blocking ? "blocking" : "optimistic"
+    });
+    const syncPromise = this._syncUpdateToRelay(holonId, lensName, dataId, mergedData, existingData, path);
+    if (options.blocking) {
+      this._log("DEBUG", "⏳ BLOCKING: Waiting for update confirmation", { path });
+      return syncPromise;
     }
     return true;
   }
+  /**
+   * Syncs an update operation to the relay in the background.
+   *
+   * @private
+   */
+  async _syncUpdateToRelay(holonId, lensName, dataId, mergedData, existingData, path) {
+    const startTime = Date.now();
+    this._log("DEBUG", "🔄 UPDATE SYNC START", {
+      path,
+      dataId,
+      relays: this.client?.relays?.map((r) => r.url) || ["local-only"]
+    });
+    try {
+      await write(this.client, path, mergedData);
+      const duration = Date.now() - startTime;
+      this._metrics.writes++;
+      if (!this._metrics.totalWriteTime) this._metrics.totalWriteTime = 0;
+      this._metrics.totalWriteTime += duration;
+      this._log("DEBUG", "✅ UPDATE SYNC SUCCESS", {
+        path,
+        dataId,
+        duration: `${duration}ms`,
+        totalWrites: this._metrics.writes
+      });
+      if (existingData._meta && existingData._meta.activeHolograms) {
+        this._log("DEBUG", "🔗 Refreshing active holograms", { path });
+        refreshActiveHolograms(this.client, this.config.appName, holonId, lensName, dataId).catch((err) => this._log("WARN", "⚠️ Hologram refresh failed", { path, error: err.message }));
+      }
+      return true;
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      this._log("ERROR", "❌ UPDATE SYNC FAILED", {
+        path,
+        dataId,
+        duration: `${duration}ms`,
+        error: error.message,
+        stack: error.stack?.split("\n")[1]?.trim()
+      });
+      this._log("WARN", "💾 Data retained in write cache for retry", { path, cacheSize: this._writeCache.size });
+      return false;
+    }
+  }
   /**
    * Deletes data from a specific holon and lens.
+   * By default, delete is optimistic (non-blocking) - returns immediately after cache invalidation.
    *
    * @param {string} holonId - H3 cell ID for the holon
    * @param {string} lensName - Name of the lens (data category)
    * @param {string} dataId - ID of the data to delete
    * @param {Object} [options={}] - Delete options
    * @param {string} [options.capabilityToken] - Capability token for authorization
+   * @param {boolean} [options.blocking=false] - If true, wait for relay confirmation before returning
    * @returns {Promise<boolean>} True if deletion succeeded, false if data not found
    * @throws {ValidationError} If holonId, lensName, or dataId is invalid
    * @throws {AuthorizationError} If not owner and no valid capability token
    */
   async delete(holonId, lensName, dataId, options = {}) {
-    if (!holonId || typeof holonId !== "string") {
+    if (holonId != null) holonId = String(holonId);
+    if (lensName != null) lensName = String(lensName);
+    if (dataId != null) dataId = String(dataId);
+    if (!holonId) {
       throw new ValidationError$1("ValidationError: holonId must be a non-empty string");
     }
-    if (!lensName || typeof lensName !== "string") {
+    if (!lensName) {
       throw new ValidationError$1("ValidationError: lensName must be a non-empty string");
     }
-    if (!dataId || typeof dataId !== "string") {
+    if (!dataId) {
       throw new ValidationError$1("ValidationError: dataId must be a non-empty string");
     }
     const path = buildPath(this.config.appName, holonId, lensName, dataId);
-    const existingData = await read(this.client, path);
+    const cached = this._writeCache.get(path);
+    let existingData = cached ? cached.data : null;
+    let dataSource = cached ? "write-cache" : null;
     if (!existingData) {
+      existingData = await read(this.client, path);
+      dataSource = existingData ? "storage" : null;
+    }
+    if (!existingData) {
+      this._log("DEBUG", "🗑️ DELETE: Data not found", { path });
       return false;
     }
+    this._log("DEBUG", "🗑️ DELETE: Found data", { path, source: dataSource });
     const dataOwner = existingData.owner || existingData._creator;
     const isOwner = !dataOwner || dataOwner === this.client.publicKey;
     const capToken = options.capabilityToken || options.capability;
@@ -38682,11 +38980,49 @@ class HoloSphereBase extends HoloSphere$1 {
         throw new AuthorizationError("AuthorizationError: Invalid capability token for delete operation", "delete");
       }
     }
+    this._writeCache.delete(path);
+    this._deleteCache.add(path);
+    this._log("DEBUG", "🗑️ CACHE DELETE", {
+      path,
+      dataId,
+      deleteCacheSize: this._deleteCache.size,
+      writeCacheSize: this._writeCache.size,
+      mode: options.blocking ? "blocking" : "optimistic"
+    });
     if (existingData.hologram === true) {
+      this._log("DEBUG", "🔗 Deleting hologram", { path });
       return this.deleteHologram(holonId, lensName, dataId, options);
     }
-    await deleteData(this.client, path);
-    this._metrics.deletes++;
+    const startTime = Date.now();
+    this._log("DEBUG", "🔄 DELETE SYNC START", { path, dataId });
+    const deletePromise = deleteData(this.client, path).then(() => {
+      const duration = Date.now() - startTime;
+      this._metrics.deletes++;
+      this._deleteCache.delete(path);
+      this._log("DEBUG", "✅ DELETE SYNC SUCCESS", {
+        path,
+        dataId,
+        duration: `${duration}ms`,
+        totalDeletes: this._metrics.deletes,
+        deleteCacheSize: this._deleteCache.size
+      });
+      return true;
+    }).catch((error) => {
+      const duration = Date.now() - startTime;
+      this._log("ERROR", "❌ DELETE SYNC FAILED", {
+        path,
+        dataId,
+        duration: `${duration}ms`,
+        error: error.message
+      });
+      this._log("WARN", "💾 Path retained in delete cache", { path, deleteCacheSize: this._deleteCache.size });
+      return false;
+    });
+    if (options.blocking) {
+      this._log("DEBUG", "⏳ BLOCKING: Waiting for delete confirmation", { path });
+      return deletePromise;
+    }
+    this._log("DEBUG", "⚡ OPTIMISTIC: Returning immediately, delete sync in background", { path });
     return true;
   }
   // === Global Tables ===
@@ -38698,6 +39034,8 @@ class HoloSphereBase extends HoloSphere$1 {
    * @returns {Promise<boolean>} True if write succeeded
    */
   async writeGlobal(table, data) {
+    if (table != null) table = String(table);
+    if (data?.id != null) data.id = String(data.id);
     return writeGlobal(this.client, this.config.appName, table, data);
   }
   /**
@@ -38708,6 +39046,8 @@ class HoloSphereBase extends HoloSphere$1 {
    * @returns {Promise<Object|Array|null>} Data object, array of objects, or null
    */
   async readGlobal(table, key = null) {
+    if (table != null) table = String(table);
+    if (key != null) key = String(key);
     return readGlobal(this.client, this.config.appName, table, key);
   }
   /**
@@ -38719,6 +39059,8 @@ class HoloSphereBase extends HoloSphere$1 {
    * @returns {Promise<boolean>} True if update succeeded
    */
   async updateGlobal(table, key, updates) {
+    if (table != null) table = String(table);
+    if (key != null) key = String(key);
     return updateGlobal(this.client, this.config.appName, table, key, updates);
   }
   /**
@@ -38729,6 +39071,8 @@ class HoloSphereBase extends HoloSphere$1 {
    * @returns {Promise<boolean>} True if deletion succeeded
    */
   async deleteGlobal(table, key) {
+    if (table != null) table = String(table);
+    if (key != null) key = String(key);
     return deleteGlobal(this.client, this.config.appName, table, key);
   }
   /**
@@ -38738,6 +39082,7 @@ class HoloSphereBase extends HoloSphere$1 {
    * @returns {Promise<Array>} Array of all data objects in the table
    */
   async getAllGlobal(table) {
+    if (table != null) table = String(table);
     return getAllGlobal(this.client, this.config.appName, table);
   }
   /**
@@ -38747,6 +39092,7 @@ class HoloSphereBase extends HoloSphere$1 {
    * @returns {Promise<boolean>} True if deletion succeeded
    */
   async deleteAllGlobal(table) {
+    if (table != null) table = String(table);
     return deleteAllGlobal(this.client, this.config.appName, table);
   }
   // === Batch Operations ===
@@ -38768,6 +39114,8 @@ class HoloSphereBase extends HoloSphere$1 {
    * @returns {Promise<boolean>} True if deletion succeeded
    */
   async deleteAll(holonId, lensName) {
+    if (holonId != null) holonId = String(holonId);
+    if (lensName != null) lensName = String(lensName);
     const path = buildPath(this.config.appName, holonId, lensName);
     return deleteAll(this.client, path);
   }
@@ -39075,6 +39423,49 @@ class HoloSphereBase extends HoloSphere$1 {
   getHologramSource(data) {
     return getHologramSource(data);
   }
+  /**
+   * Updates platform-specific data for an active hologram entry.
+   * Used by platform clients (Telegram, Discord, etc.) to store their message IDs.
+   *
+   * @param {string} sourceHolon - Source holon ID where the original data lives
+   * @param {string} lensName - Lens name (e.g., 'quests', 'events')
+   * @param {string} dataId - Data ID
+   * @param {string} targetHolon - Target holon ID where the hologram exists
+   * @param {string} platform - Platform name (e.g., 'telegram', 'discord')
+   * @param {Object} platformData - Platform-specific data (e.g., { messageId: 123 })
+   * @returns {Promise<boolean>} Success indicator
+   */
+  async updateHologramPlatform(sourceHolon, lensName, dataId, targetHolon, platform, platformData) {
+    return updateActiveHologramPlatform(
+      this.client,
+      this.config.appName,
+      sourceHolon,
+      lensName,
+      dataId,
+      targetHolon,
+      platform,
+      platformData
+    );
+  }
+  /**
+   * Gets active holograms for a data item, optionally filtered by platform.
+   *
+   * @param {string} sourceHolon - Source holon ID
+   * @param {string} lensName - Lens name
+   * @param {string} dataId - Data ID
+   * @param {string} [platform] - Optional platform filter (e.g., 'telegram')
+   * @returns {Promise<Array>} Array of hologram entries with platform data
+   */
+  async getActiveHolograms(sourceHolon, lensName, dataId, platform = null) {
+    return getActiveHolograms(
+      this.client,
+      this.config.appName,
+      sourceHolon,
+      lensName,
+      dataId,
+      platform
+    );
+  }
   /**
    * Cleans up circular hologram references in a holon.
    *
@@ -39518,6 +39909,48 @@ class HoloSphereBase extends HoloSphere$1 {
       avgWriteTime: writes > 0 ? totalWriteTime / writes : 0
     };
   }
+  /**
+   * Returns the current status of optimistic caches for debugging.
+   * Useful for understanding what data is pending sync or marked as deleted.
+   *
+   * @returns {Object} Cache status object
+   * @returns {number} return.writeCacheSize - Number of items in write cache (pending sync)
+   * @returns {number} return.deleteCacheSize - Number of items in delete cache (pending delete sync)
+   * @returns {Array<Object>} return.writeCacheEntries - Array of write cache entries with path and age
+   * @returns {Array<string>} return.deleteCachePaths - Array of paths marked as deleted
+   */
+  getCacheStatus() {
+    const now = Date.now();
+    const writeCacheEntries = [];
+    for (const [path, entry] of this._writeCache.entries()) {
+      writeCacheEntries.push({
+        path,
+        dataId: entry.data?.id,
+        age: `${now - entry.timestamp}ms`,
+        timestamp: new Date(entry.timestamp).toISOString()
+      });
+    }
+    return {
+      writeCacheSize: this._writeCache.size,
+      deleteCacheSize: this._deleteCache.size,
+      writeCacheEntries,
+      deleteCachePaths: Array.from(this._deleteCache)
+    };
+  }
+  /**
+   * Clears the optimistic caches. Useful for testing or resetting state.
+   * Warning: This may cause inconsistencies if there are pending syncs.
+   */
+  clearCaches() {
+    const writeSize = this._writeCache.size;
+    const deleteSize = this._deleteCache.size;
+    this._writeCache.clear();
+    this._deleteCache.clear();
+    this._log("WARN", "🧹 CACHES CLEARED", {
+      writeCacheCleared: writeSize,
+      deleteCacheCleared: deleteSize
+    });
+  }
   // === Aliases ===
   /**
    * Alias for {@link HoloSphereBase#write}.
@@ -39838,4 +40271,4 @@ export {
   exists as y,
   bytes as z
 };
-//# sourceMappingURL=index-DJXftyvB.js.map
+//# sourceMappingURL=index-D-jZhliX.js.map