holosphere 1.3.0-alpha5 → 1.3.0-alpha7

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
@@ -32,6 +50,28 @@ function onceWithTimeout(node, timeoutMs = READ_TIMEOUT_MS) {
     });
 }
 
+/**
+ * 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 +158,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 +275,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 +334,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 +379,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 +419,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 +489,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;

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/holosphere-bundle.esm.js

@@ -1,9 +1,9 @@
 /**
- * HoloSphere ESM Bundle v1.3.0-alpha5
+ * HoloSphere ESM Bundle v1.3.0-alpha7
  * 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-alpha7/holosphere-bundle.esm.js';
  * const hs = new HoloSphere('myapp');
  */
 var __create = Object.create;
@@ -25365,6 +25365,7 @@ function clearSchemaCache(holoInstance, lens = null) {
 
 // content.js
 var READ_TIMEOUT_MS = 8e3;
+var WRITE_TIMEOUT_MS = 5e3;
 function onceWithTimeout(node, timeoutMs = READ_TIMEOUT_MS) {
   return new Promise((resolve) => {
     let done = false;
@@ -25380,6 +25381,23 @@ function onceWithTimeout(node, timeoutMs = READ_TIMEOUT_MS) {
     }
   });
 }
+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 +25444,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 +25536,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 +25569,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 +25608,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 +25691,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;
@@ -26336,7 +26373,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 +26438,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 +26501,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;
@@ -30528,14 +30595,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);

package/holosphere-bundle.js

@@ -1,5 +1,5 @@
 /**
- * HoloSphere Bundle v1.3.0-alpha5
+ * HoloSphere Bundle v1.3.0-alpha7
  * Holonic Geospatial Communication Infrastructure
  * 
  * Includes:
@@ -9,7 +9,7 @@
  * - Ajv (JSON schema validation)
  * 
  * Usage:
- * <script src="https://unpkg.com/holosphere@1.3.0-alpha5/holosphere-bundle.js"></script>
+ * <script src="https://unpkg.com/holosphere@1.3.0-alpha7/holosphere-bundle.js"></script>
  * <script>
  *   const hs = new HoloSphere('myapp');
  * </script>
@@ -25391,6 +25391,7 @@ var HoloSphere = (() => {
 
   // content.js
   var READ_TIMEOUT_MS = 8e3;
+  var WRITE_TIMEOUT_MS = 5e3;
   function onceWithTimeout(node, timeoutMs = READ_TIMEOUT_MS) {
     return new Promise((resolve) => {
       let done = false;
@@ -25406,6 +25407,23 @@ var HoloSphere = (() => {
       }
     });
   }
+  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;
@@ -25452,7 +25470,11 @@ var HoloSphere = (() => {
     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;
@@ -25540,7 +25562,7 @@ var HoloSphere = (() => {
           });
         });
       }
-      return new Promise((resolve, reject) => {
+      const ackPromise = new Promise((resolve, reject) => {
         try {
           const sanitizeWarnings = [];
           let dataToStore = sanitizeForStorage(data, "", /* @__PURE__ */ new WeakSet(), sanitizeWarnings) || {};
@@ -25573,16 +25595,17 @@ var HoloSphere = (() => {
                 }
               }
               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) => {
@@ -25611,8 +25634,12 @@ var HoloSphere = (() => {
                                       // 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({
@@ -25690,6 +25717,16 @@ var HoloSphere = (() => {
           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;
@@ -26362,7 +26399,25 @@ var HoloSphere = (() => {
   }
 
   // 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");
@@ -26409,7 +26464,8 @@ var HoloSphere = (() => {
           });
         });
       }
-      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) {
@@ -26471,6 +26527,17 @@ var HoloSphere = (() => {
           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;
@@ -30554,14 +30621,14 @@ var HoloSphere = (() => {
       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);