holosphere 1.3.0-alpha5 → 1.3.0-alpha8

package/content.js

@@ -13,6 +13,24 @@
  */
 const READ_TIMEOUT_MS = 8000;
 
+/**
+ * Default deadline (ms) for the put-path's Gun ack callback. Gun fires the
+ * ack only after the local commit + at least one peer ack chain — with no
+ * reachable peer (cold start, offline, partitioned mesh) it never fires
+ * and the consumer's `await holosphere.put(...)` hangs forever. UIs
+ * worked around this by racing every `put` against their own timeout;
+ * owning the deadline here makes every consumer local-first by default.
+ *
+ * On timeout the returned promise resolves with a `queued: true` sentinel
+ * (see `put` return shape) — Gun keeps the write in its local queue and
+ * the ack callback's side effects (subscriber notification, hologram
+ * cascade, federation propagation) run later when a peer reappears.
+ *
+ * Pick `WRITE_TIMEOUT_MS = 0` (or pass `{ timeout: 0 }`) to opt out of
+ * the fallback and keep the historical "wait for ack" behaviour.
+ */
+const WRITE_TIMEOUT_MS = 5000;
+
 /**
  * `.once()` wrapped in a deadline. Resolves with the value when Gun fires
  * back, or `null` after `timeoutMs` if it hasn't. Pass `timeoutMs <= 0` to
@@ -20,18 +38,69 @@ const READ_TIMEOUT_MS = 8000;
  *
  * The first responder wins — both branches are idempotent so a late
  * `.once()` callback after timeout is harmlessly ignored.
+ *
+ * Pass `{ awaitNetwork: true }` for cold reads that MUST reach the network —
+ * notably cross-holon hologram soul resolution. Gun's `.once()` fires
+ * synchronously with whatever is in the local graph and never re-fires; for a
+ * node we never subscribed to (another holon's lens), that first value is
+ * `undefined` even though a peer is about to deliver the real data a few ms
+ * later. Accepting that `undefined` as "not found" is exactly what produced
+ * the `Could not resolve hologram soul: … (target not present locally)` false
+ * negatives on freshly-loaded federated data. In `awaitNetwork` mode we use
+ * `.on()` instead, skip the cold `undefined`, and settle once the value
+ * syncs — while still honouring an explicit `null` (a real tombstone) and the
+ * deadline (for nodes no peer ever answers). The common, same-holon read path
+ * keeps the fast `.once()` behaviour so empty/missing local reads resolve
+ * immediately instead of blocking for the full deadline.
  */
-function onceWithTimeout(node, timeoutMs = READ_TIMEOUT_MS) {
+function onceWithTimeout(node, timeoutMs = READ_TIMEOUT_MS, { awaitNetwork = false } = {}) {
+    if (!awaitNetwork) {
+        return new Promise((resolve) => {
+            let done = false;
+            const finish = (v) => { if (!done) { done = true; resolve(v); } };
+            node.once((data) => finish(data));
+            if (timeoutMs > 0) {
+                setTimeout(() => finish(null), timeoutMs);
+            }
+        });
+    }
+
     return new Promise((resolve) => {
         let done = false;
-        const finish = (v) => { if (!done) { done = true; resolve(v); } };
-        node.once((data) => finish(data));
+        const detach = () => { try { if (node.off) node.off(); } catch { /* ignore */ } };
+        const finish = (v) => { if (!done) { done = true; detach(); resolve(v); } };
+        node.on((data) => {
+            if (data === undefined) return; // cold/not-known yet — wait for a peer
+            finish(data); // defined value OR explicit null tombstone — definitive
+        });
         if (timeoutMs > 0) {
             setTimeout(() => finish(null), timeoutMs);
         }
     });
 }
 
+/**
+ * Race a put-result promise against a deadline. If the underlying Gun
+ * ack never arrives, resolve with `queuedResult` so the caller stops
+ * waiting; Gun keeps the write in its local queue and replays it when
+ * a peer is available.
+ *
+ * The first responder wins — both branches are idempotent so the late
+ * ack-driven resolution after timeout is harmlessly ignored.
+ */
+function withWriteTimeout(promise, timeoutMs, queuedResult) {
+    if (!timeoutMs || timeoutMs <= 0) return promise;
+    return new Promise((resolve, reject) => {
+        let done = false;
+        const finish = (fn, val) => { if (!done) { done = true; fn(val); } };
+        promise.then(
+            (v) => finish(resolve, v),
+            (e) => finish(reject, e)
+        );
+        setTimeout(() => finish(resolve, queuedResult), timeoutMs);
+    });
+}
+
 /**
  * Recursively sanitizes a value for storage in GunDB.
  *
@@ -118,7 +187,11 @@ export async function put(holoInstance, holon, lens, data, password = null, opti
         throw new Error('put: Missing required holon or lens parameters:', holon, lens);
     }
 
-    const { disableHologramRedirection = false } = options; // Extract new option
+    const {
+        disableHologramRedirection = false,
+        timeout: writeTimeoutOverride
+    } = options;
+    const writeTimeoutMs = writeTimeoutOverride !== undefined ? writeTimeoutOverride : WRITE_TIMEOUT_MS;
 
     let targetHolon = holon;
     let targetLens = lens;
@@ -231,7 +304,7 @@ export async function put(holoInstance, holon, lens, data, password = null, opti
             });
         }
 
-        return new Promise((resolve, reject) => {
+        const ackPromise = new Promise((resolve, reject) => {
             try {
                 // Sanitize before serialization so undefined/NaN/Infinity etc.
                 // can never produce a malformed payload like `"initiated":,`
@@ -290,22 +363,38 @@ export async function put(holoInstance, holon, lens, data, password = null, opti
                         }
                         // --- End: Hologram Tracking Logic ---
                         
-                        // --- Start: Active Hologram Update Logic (for actual data being stored) ---
+                        // --- Start: Active Hologram Update Logic ---
+                        //
+                        // Walks this node's `_holograms` set and stamps every
+                        // registered hologram with `updated: now` so consumers
+                        // re-resolve and see the latest source data.
+                        //
+                        // Runs for BOTH original-data puts and hologram-update
+                        // puts so updates cascade through multi-hop forwards
+                        // (A → B → C → …) even when the second hop's
+                        // cross-holon registration on the original source
+                        // can't be relied on to make it across the Gun mesh.
+                        // Each hop maintains its own local `_holograms` set
+                        // tracking the next hops, and we walk that set on
+                        // every put — cycle-protected via
+                        // `options._cascadeVisited`.
                         let updatedHolograms = [];
-                        if (!isHologram && !options.isHologramUpdate) {
+                        const currentDataSoul = `${holoInstance.appname}/${targetHolon}/${targetLens}/${targetKey}`;
+                        const cascadeVisited = new Set(options._cascadeVisited || []);
+                        if (!cascadeVisited.has(currentDataSoul)) {
+                            cascadeVisited.add(currentDataSoul);
                             try {
-                                const currentDataSoul = `${holoInstance.appname}/${targetHolon}/${targetLens}/${targetKey}`;
                                 const currentNodeRef = holoInstance.getNodeRef(currentDataSoul);
-                                
-                                // Get the _holograms set for this data
+
+                                // Get the _holograms set for this node
                                 await new Promise((resolveHologramUpdate) => {
                                     currentNodeRef.get('_holograms').once(async (hologramsSet) => {
                                         if (hologramsSet) {
-                                            const hologramSouls = Object.keys(hologramsSet).filter(k => 
-                                                k !== '_' && hologramsSet[k] === true // Only active holograms (deleted ones are null/removed)
+                                            const hologramSouls = Object.keys(hologramsSet).filter(k =>
+                                                k !== '_' && hologramsSet[k] === true && !cascadeVisited.has(k)
                                             );
-                                            
-                                                                        if (hologramSouls.length > 0) {
+
+                                            if (hologramSouls.length > 0) {
                                 // Update each active hologram with an 'updated' timestamp
                                                 const updatePromises = hologramSouls.map(async (hologramSoul) => {
                                                     try {
@@ -319,26 +408,31 @@ export async function put(holoInstance, holon, lens, data, password = null, opti
                                                                 null,
                                                                 { resolveHolograms: false }
                                                             );
-                                                            
+
                                                             if (currentHologram) {
                                                                 // Update the hologram with an 'updated' timestamp
                                                                 const updatedHologram = {
                                                                     ...currentHologram,
                                                                     updated: Date.now()
                                                                 };
-                                                                
+
                                                                 await holoInstance.put(
                                                                     hologramSoulInfo.holon,
                                                                     hologramSoulInfo.lens,
                                                                     updatedHologram,
                                                                     null,
-                                                                    { 
+                                                                    {
                                                                         autoPropagate: false, // Don't auto-propagate hologram updates
                                                                         disableHologramRedirection: true, // Prevent redirection when updating holograms
-                                                                        isHologramUpdate: true // Prevent recursive hologram updates
+                                                                        isHologramUpdate: true,
+                                                                        // Carry the visited set forward so the
+                                                                        // recursive put keeps cascading through
+                                                                        // this hop's `_holograms` set without
+                                                                        // looping back through us.
+                                                                        _cascadeVisited: cascadeVisited
                                                                     }
                                                                 );
-                                                                
+
                                                                                                                 // Add to the list of updated holograms
                                                                 updatedHolograms.push({
                                                                     soul: hologramSoul,
@@ -354,7 +448,7 @@ export async function put(holoInstance, holon, lens, data, password = null, opti
                                                         console.warn(`Error updating hologram ${hologramSoul}:`, hologramUpdateError);
                                                     }
                                                 });
-                                                
+
                                                 await Promise.all(updatePromises);
                                             }
                                         }
@@ -424,6 +518,22 @@ export async function put(holoInstance, holon, lens, data, password = null, opti
                 reject(error);
             }
         });
+
+        // Bound the wait on Gun's put ack so an offline/partitioned mesh
+        // doesn't hang the caller forever. Gun keeps the local write and
+        // its eventual ack callback (subscriber notify, hologram cascade,
+        // propagation) still runs when a peer reappears — we just stop
+        // blocking the awaiting consumer in the meantime.
+        return withWriteTimeout(ackPromise, writeTimeoutMs, {
+            success: true,
+            queued: true,
+            isHologramAtPath: isHologram,
+            pathHolon: targetHolon,
+            pathLens: targetLens,
+            pathKey: targetKey,
+            propagationResult: null,
+            updatedHolograms: []
+        });
     } catch (error) {
         console.error('Error in put:', error);
         throw error;
@@ -454,6 +564,11 @@ export async function get(holoInstance, holon, lens, key, password = null, optio
         validationOptions = {},
         visited,
         timeout = READ_TIMEOUT_MS,
+        // Network-aware read: skip Gun's cold synchronous `undefined` and wait
+        // (up to `timeout`) for a peer to answer. Used by hologram soul
+        // resolution so cross-holon reads aren't misreported as missing. See
+        // `onceWithTimeout`. Off by default to keep same-holon reads fast.
+        awaitNetwork = false,
         // `_deleted: true` is the soft-tombstone convention used by the bot,
         // the web dashboard, and the MCP council tools. Pre-this fix the
         // library was unaware of it and every caller filtered defensively.
@@ -580,7 +695,7 @@ export async function get(holoInstance, holon, lens, key, password = null, optio
             // `.once()` wrapped in a deadline — cold-path reads (peer offline,
             // never-written key) used to hang forever otherwise. After
             // `timeout` ms with no Gun response we treat it as "not found".
-            onceWithTimeout(dataPath, timeout).then(handleData);
+            onceWithTimeout(dataPath, timeout, { awaitNetwork }).then(handleData);
         });
     } catch (error) {
         console.error('Error in get:', error);

package/global.js

@@ -1,14 +1,37 @@
 // holo_global.js
 
+/**
+ * Default deadline (ms) for the put-path's Gun ack callback. See
+ * `WRITE_TIMEOUT_MS` in content.js for the rationale — same hang, same
+ * fix, kept local here so global.js doesn't depend on content.js's
+ * internals.
+ */
+const WRITE_TIMEOUT_MS = 5000;
+
+function withWriteTimeout(promise, timeoutMs, queuedResult) {
+    if (!timeoutMs || timeoutMs <= 0) return promise;
+    return new Promise((resolve, reject) => {
+        let done = false;
+        const finish = (fn, val) => { if (!done) { done = true; fn(val); } };
+        promise.then(
+            (v) => finish(resolve, v),
+            (e) => finish(reject, e)
+        );
+        setTimeout(() => finish(resolve, queuedResult), timeoutMs);
+    });
+}
+
 /**
  * Stores data in a global (non-holon-specific) table.
  * @param {HoloSphere} holoInstance - The HoloSphere instance.
  * @param {string} tableName - The table name to store data in.
  * @param {object} data - The data to store. If it has an 'id' field, it will be used as the key.
  * @param {string} [password] - Optional password for private holon.
+ * @param {object} [options] - Additional options
+ * @param {number} [options.timeout=5000] - Ack deadline in ms; resolves anyway after this so an offline mesh can't hang the caller. Pass `0` to disable.
  * @returns {Promise<void>}
  */
-export async function putGlobal(holoInstance, tableName, data, password = null) {
+export async function putGlobal(holoInstance, tableName, data, password = null, options = {}) {
     try {
         if (!tableName || !data) {
             throw new Error('Table name and data are required');
@@ -63,7 +86,9 @@ export async function putGlobal(holoInstance, tableName, data, password = null)
             });
         }
 
-        return new Promise((resolve, reject) => {
+        const writeTimeoutMs = options.timeout !== undefined ? options.timeout : WRITE_TIMEOUT_MS;
+
+        const ackPromise = new Promise((resolve, reject) => {
             try {
                 // Create a copy of data, stripping read-side envelopes that
                 // must never be persisted (they're attached at resolution time).
@@ -143,6 +168,23 @@ export async function putGlobal(holoInstance, tableName, data, password = null)
                 reject(error);
             }
         });
+
+        // Bound the wait on Gun's put ack so an offline mesh doesn't hang
+        // the caller forever. Gun keeps the write locally and replays it
+        // when a peer reappears. We tag the ack-arrived branch with a
+        // unique sentinel so we can warn (once) when the timeout fired
+        // and still keep the public Promise<void> contract.
+        const ACK_OK = Symbol('ackOk');
+        return withWriteTimeout(
+            ackPromise.then(() => ACK_OK),
+            writeTimeoutMs,
+            undefined
+        ).then((result) => {
+            if (result !== ACK_OK) {
+                console.warn(`putGlobal: no ack within ${writeTimeoutMs}ms for table=${tableName} — write queued locally, will replay on reconnect`);
+            }
+            return undefined;
+        });
     } catch (error) {
         console.error('Error in putGlobal:', error);
         throw error;

package/hologram.js

@@ -168,7 +168,13 @@ export async function resolveHologram(holoInstance, hologram, options = {}) {
                         resolveHolograms: followHolograms,
                     visited: nextVisited,
                     maxDepth: maxDepth,
-                    currentDepth: currentDepth + 1
+                    currentDepth: currentDepth + 1,
+                    // The soul almost always points at a DIFFERENT holon's lens
+                    // this peer never subscribed to, so the node is cold: Gun's
+                    // `.once()` would fire `undefined` synchronously and we'd
+                    // wrongly report "target not present locally". Wait for the
+                    // network round-trip instead.
+                    awaitNetwork: true
                     }
                 );
 

package/holosphere-bundle.esm.js

@@ -1,9 +1,9 @@
 /**
- * HoloSphere ESM Bundle v1.3.0-alpha5
+ * HoloSphere ESM Bundle v1.3.0-alpha8
  * ES6 Module version with all dependencies bundled
  * 
  * Usage:
- * import HoloSphere from 'https://unpkg.com/holosphere@1.3.0-alpha5/holosphere-bundle.esm.js';
+ * import HoloSphere from 'https://unpkg.com/holosphere@1.3.0-alpha8/holosphere-bundle.esm.js';
  * const hs = new HoloSphere('myapp');
  */
 var __create = Object.create;
@@ -24385,7 +24385,13 @@ async function resolveHologram(holoInstance, hologram, options = {}) {
           resolveHolograms: followHolograms,
           visited: nextVisited,
           maxDepth,
-          currentDepth: currentDepth + 1
+          currentDepth: currentDepth + 1,
+          // The soul almost always points at a DIFFERENT holon's lens
+          // this peer never subscribed to, so the node is cold: Gun's
+          // `.once()` would fire `undefined` synchronously and we'd
+          // wrongly report "target not present locally". Wait for the
+          // network round-trip instead.
+          awaitNetwork: true
         }
       );
       if (originalData && !originalData._invalidHologram) {
@@ -25365,21 +25371,64 @@ function clearSchemaCache(holoInstance, lens = null) {
 
 // content.js
 var READ_TIMEOUT_MS = 8e3;
-function onceWithTimeout(node, timeoutMs = READ_TIMEOUT_MS) {
+var WRITE_TIMEOUT_MS = 5e3;
+function onceWithTimeout(node, timeoutMs = READ_TIMEOUT_MS, { awaitNetwork = false } = {}) {
+  if (!awaitNetwork) {
+    return new Promise((resolve) => {
+      let done = false;
+      const finish = (v) => {
+        if (!done) {
+          done = true;
+          resolve(v);
+        }
+      };
+      node.once((data) => finish(data));
+      if (timeoutMs > 0) {
+        setTimeout(() => finish(null), timeoutMs);
+      }
+    });
+  }
   return new Promise((resolve) => {
     let done = false;
+    const detach = () => {
+      try {
+        if (node.off) node.off();
+      } catch {
+      }
+    };
     const finish = (v) => {
       if (!done) {
         done = true;
+        detach();
         resolve(v);
       }
     };
-    node.once((data) => finish(data));
+    node.on((data) => {
+      if (data === void 0) return;
+      finish(data);
+    });
     if (timeoutMs > 0) {
       setTimeout(() => finish(null), timeoutMs);
     }
   });
 }
+function withWriteTimeout(promise, timeoutMs, queuedResult) {
+  if (!timeoutMs || timeoutMs <= 0) return promise;
+  return new Promise((resolve, reject) => {
+    let done = false;
+    const finish = (fn, val) => {
+      if (!done) {
+        done = true;
+        fn(val);
+      }
+    };
+    promise.then(
+      (v) => finish(resolve, v),
+      (e) => finish(reject, e)
+    );
+    setTimeout(() => finish(resolve, queuedResult), timeoutMs);
+  });
+}
 function sanitizeForStorage(value, path = "", seen = /* @__PURE__ */ new WeakSet(), warnings = []) {
   if (value === null) return null;
   const t = typeof value;
@@ -25426,7 +25475,11 @@ async function put(holoInstance, holon, lens, data, password = null, options = {
   if (!holon || !lens) {
     throw new Error("put: Missing required holon or lens parameters:", holon, lens);
   }
-  const { disableHologramRedirection = false } = options;
+  const {
+    disableHologramRedirection = false,
+    timeout: writeTimeoutOverride
+  } = options;
+  const writeTimeoutMs = writeTimeoutOverride !== void 0 ? writeTimeoutOverride : WRITE_TIMEOUT_MS;
   let targetHolon = holon;
   let targetLens = lens;
   let targetKey = data.id;
@@ -25514,7 +25567,7 @@ async function put(holoInstance, holon, lens, data, password = null, options = {
         });
       });
     }
-    return new Promise((resolve, reject) => {
+    const ackPromise = new Promise((resolve, reject) => {
       try {
         const sanitizeWarnings = [];
         let dataToStore = sanitizeForStorage(data, "", /* @__PURE__ */ new WeakSet(), sanitizeWarnings) || {};
@@ -25547,16 +25600,17 @@ async function put(holoInstance, holon, lens, data, password = null, options = {
               }
             }
             let updatedHolograms = [];
-            if (!isHologram2 && !options.isHologramUpdate) {
+            const currentDataSoul = `${holoInstance.appname}/${targetHolon}/${targetLens}/${targetKey}`;
+            const cascadeVisited = new Set(options._cascadeVisited || []);
+            if (!cascadeVisited.has(currentDataSoul)) {
+              cascadeVisited.add(currentDataSoul);
               try {
-                const currentDataSoul = `${holoInstance.appname}/${targetHolon}/${targetLens}/${targetKey}`;
                 const currentNodeRef = holoInstance.getNodeRef(currentDataSoul);
                 await new Promise((resolveHologramUpdate) => {
                   currentNodeRef.get("_holograms").once(async (hologramsSet) => {
                     if (hologramsSet) {
                       const hologramSouls = Object.keys(hologramsSet).filter(
-                        (k) => k !== "_" && hologramsSet[k] === true
-                        // Only active holograms (deleted ones are null/removed)
+                        (k) => k !== "_" && hologramsSet[k] === true && !cascadeVisited.has(k)
                       );
                       if (hologramSouls.length > 0) {
                         const updatePromises = hologramSouls.map(async (hologramSoul) => {
@@ -25585,8 +25639,12 @@ async function put(holoInstance, holon, lens, data, password = null, options = {
                                     // Don't auto-propagate hologram updates
                                     disableHologramRedirection: true,
                                     // Prevent redirection when updating holograms
-                                    isHologramUpdate: true
-                                    // Prevent recursive hologram updates
+                                    isHologramUpdate: true,
+                                    // Carry the visited set forward so the
+                                    // recursive put keeps cascading through
+                                    // this hop's `_holograms` set without
+                                    // looping back through us.
+                                    _cascadeVisited: cascadeVisited
                                   }
                                 );
                                 updatedHolograms.push({
@@ -25664,6 +25722,16 @@ async function put(holoInstance, holon, lens, data, password = null, options = {
         reject(error);
       }
     });
+    return withWriteTimeout(ackPromise, writeTimeoutMs, {
+      success: true,
+      queued: true,
+      isHologramAtPath: isHologram2,
+      pathHolon: targetHolon,
+      pathLens: targetLens,
+      pathKey: targetKey,
+      propagationResult: null,
+      updatedHolograms: []
+    });
   } catch (error) {
     console.error("Error in put:", error);
     throw error;
@@ -25679,6 +25747,11 @@ async function get(holoInstance, holon, lens, key, password = null, options = {}
     validationOptions = {},
     visited,
     timeout = READ_TIMEOUT_MS,
+    // Network-aware read: skip Gun's cold synchronous `undefined` and wait
+    // (up to `timeout`) for a peer to answer. Used by hologram soul
+    // resolution so cross-holon reads aren't misreported as missing. See
+    // `onceWithTimeout`. Off by default to keep same-holon reads fast.
+    awaitNetwork = false,
     // `_deleted: true` is the soft-tombstone convention used by the bot,
     // the web dashboard, and the MCP council tools. Pre-this fix the
     // library was unaware of it and every caller filtered defensively.
@@ -25764,7 +25837,7 @@ async function get(holoInstance, holon, lens, key, password = null, options = {}
         }
       };
       const dataPath = password ? user.get("private").get(lens).get(key) : holoInstance.gun.get(holoInstance.appname).get(holon).get(lens).get(key);
-      onceWithTimeout(dataPath, timeout).then(handleData);
+      onceWithTimeout(dataPath, timeout, { awaitNetwork }).then(handleData);
     });
   } catch (error) {
     console.error("Error in get:", error);
@@ -26336,7 +26409,25 @@ async function deleteNode(holoInstance, holon, lens, key) {
 }
 
 // global.js
-async function putGlobal(holoInstance, tableName, data, password = null) {
+var WRITE_TIMEOUT_MS2 = 5e3;
+function withWriteTimeout2(promise, timeoutMs, queuedResult) {
+  if (!timeoutMs || timeoutMs <= 0) return promise;
+  return new Promise((resolve, reject) => {
+    let done = false;
+    const finish = (fn, val) => {
+      if (!done) {
+        done = true;
+        fn(val);
+      }
+    };
+    promise.then(
+      (v) => finish(resolve, v),
+      (e) => finish(reject, e)
+    );
+    setTimeout(() => finish(resolve, queuedResult), timeoutMs);
+  });
+}
+async function putGlobal(holoInstance, tableName, data, password = null, options = {}) {
   try {
     if (!tableName || !data) {
       throw new Error("Table name and data are required");
@@ -26383,7 +26474,8 @@ async function putGlobal(holoInstance, tableName, data, password = null) {
         });
       });
     }
-    return new Promise((resolve, reject) => {
+    const writeTimeoutMs = options.timeout !== void 0 ? options.timeout : WRITE_TIMEOUT_MS2;
+    const ackPromise = new Promise((resolve, reject) => {
       try {
         let dataToStore = { ...data };
         if (dataToStore._meta !== void 0) {
@@ -26445,6 +26537,17 @@ async function putGlobal(holoInstance, tableName, data, password = null) {
         reject(error);
       }
     });
+    const ACK_OK = Symbol("ackOk");
+    return withWriteTimeout2(
+      ackPromise.then(() => ACK_OK),
+      writeTimeoutMs,
+      void 0
+    ).then((result) => {
+      if (result !== ACK_OK) {
+        console.warn(`putGlobal: no ack within ${writeTimeoutMs}ms for table=${tableName} \u2014 write queued locally, will replay on reconnect`);
+      }
+      return void 0;
+    });
   } catch (error) {
     console.error("Error in putGlobal:", error);
     throw error;
@@ -27167,7 +27270,11 @@ function subscribe(holoInstance, holon, lens, callback) {
         try {
           let parsed = await holoInstance.parse(data);
           if (parsed && holoInstance.isHologram(parsed)) {
+            const hologramSoul = parsed.soul;
             const resolved = await holoInstance.resolveHologram(parsed, { followHolograms: true });
+            if (resolved === null) {
+              console.warn(`Hologram at ${holon}/${lens}/${key} did not resolve (soul=${hologramSoul}); skipping.`);
+            }
             if (resolved !== parsed) {
               parsed = resolved;
             }
@@ -30528,14 +30635,14 @@ var HoloSphere = class {
     return deleteNode(this, holon, lens, key);
   }
   // ================================ GLOBAL FUNCTIONS ================================
-  async putGlobal(tableName, data, password = null) {
-    return putGlobal(this, tableName, data, password);
+  async putGlobal(tableName, data, password = null, options = {}) {
+    return putGlobal(this, tableName, data, password, options);
   }
   /**
    * v2-compatible alias for putGlobal (no password param)
    */
-  async writeGlobal(tableName, data) {
-    return putGlobal(this, tableName, data, null);
+  async writeGlobal(tableName, data, options = {}) {
+    return putGlobal(this, tableName, data, null, options);
   }
   async getGlobal(tableName, key, password = null) {
     return getGlobal(this, tableName, key, password);