holosphere 1.3.0-alpha4 → 1.3.0-alpha7

package/content.js

@@ -1,5 +1,77 @@
 // holo_content.js
 
+/**
+ * Default deadline (ms) for the read paths' `.once()` calls. Gun's `.once()`
+ * never fires when the requested node isn't in the local graph and no peer
+ * answers (cold-start, offline, partitioned mesh) — past consumers worked
+ * around this by wrapping every `getAll` in their own `Promise.race(reject,
+ * setTimeout(8000))`. Owning it here means the spinner can never hang
+ * indefinitely on a cold path and every caller stops needing the wrapper.
+ *
+ * Pick `READ_TIMEOUT_MS = 0` (or pass `{ timeout: 0 }`) to opt out of the
+ * fallback and keep the historical "wait forever" behaviour.
+ */
+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
+ * disable the deadline.
+ *
+ * The first responder wins — both branches are idempotent so a late
+ * `.once()` callback after timeout is harmlessly ignored.
+ */
+function onceWithTimeout(node, timeoutMs = READ_TIMEOUT_MS) {
+    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);
+        }
+    });
+}
+
+/**
+ * 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.
  *
@@ -86,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;
@@ -199,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":,`
@@ -214,8 +290,25 @@ export async function put(holoInstance, holon, lens, data, password = null, opti
                 }
                 // Strip read-side envelopes that must never be persisted
                 // (they're attached at resolution time).
+                //
+                // `_hologram` and `_meta` are always read-side-only.
+                //
+                // `_federation` is also read-side for ordinary writes — it
+                // describes where data was fetched from, not where it
+                // currently lives. The one legitimate carrier is federation
+                // propagation, which writes hologram envelopes (top-level
+                // `id` + `soul`) tagged with `_federation` provenance; we
+                // detect that via `isHologram(data)` and leave it alone.
+                // Without this, a UI that reads a federated record and puts
+                // it back ends up persisting stale `_federation.origin`
+                // metadata, which then drives downstream code (federation
+                // propagators, hologram resolvers) to write or follow
+                // pointers that don't match the current storage location —
+                // producing "broken hologram" garbage-collection cascades
+                // that silently delete the user's write.
                 if (dataToStore._meta !== undefined) delete dataToStore._meta;
                 if (dataToStore._hologram !== undefined) delete dataToStore._hologram;
+                if (!isHologram && dataToStore._federation !== undefined) delete dataToStore._federation;
                 const payload = JSON.stringify(dataToStore); // The data being stored
 
                 const putCallback = async (ack) => {
@@ -241,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 {
@@ -270,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,
@@ -305,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);
                                             }
                                         }
@@ -375,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;
@@ -400,7 +530,19 @@ export async function get(holoInstance, holon, lens, key, password = null, optio
     }
 
     // Destructure options, including visited
-    const { resolveHolograms = true, validationOptions = {}, visited } = options;
+    const {
+        resolveHolograms = true,
+        validationOptions = {},
+        visited,
+        timeout = READ_TIMEOUT_MS,
+        // `_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.
+        // Now `get` returns `null` for tombstoned records by default; pass
+        // `includeDeleted: true` to surface them (admin/debug views,
+        // history reconstruction, etc.).
+        includeDeleted = false,
+    } = options;
 
     // Get schema for validation if in strict mode
     let schema = null;
@@ -444,6 +586,14 @@ export async function get(holoInstance, holon, lens, key, password = null, optio
                         return;
                     }
 
+                    // Treat the harvest-side `_deleted: true` soft-tombstone
+                    // as "not found" by default. Callers that want to see
+                    // tombstones can pass `{ includeDeleted: true }`.
+                    if (!includeDeleted && parsed._deleted === true) {
+                        resolve(null);
+                        return;
+                    }
+
                     // Check if this is a hologram that needs to be resolved
                     if (resolveHolograms && holoInstance.isHologram(parsed)) {
                         const resolvedValue = await holoInstance.resolveHologram(parsed, {
@@ -454,17 +604,20 @@ export async function get(holoInstance, holon, lens, key, password = null, optio
                         });
 
                         if (resolvedValue === null) {
-                            // This means resolveHologram determined the target doesn't exist or encountered an error
-                            console.warn(`Broken hologram detected at ${holon}/${lens}/${key}. Removing it...`);
-                            
-                            try {
-                                // Delete the broken hologram
-                                await holoInstance.delete(holon, lens, key, password);
-                                console.log(`Successfully removed broken hologram from ${holon}/${lens}/${key}`);
-                            } catch (cleanupError) {
-                                console.error(`Failed to remove broken hologram at ${holon}/${lens}/${key}:`, cleanupError);
-                            }
-                            
+                            // `resolveHologram` returned null. DON'T treat this
+                            // as a permission to delete — null fires for several
+                            // transient reasons:
+                            //   - source soul not in our local Gun graph yet
+                            //     (peer offline, federation propagation in flight)
+                            //   - maxDepth (10) reached on a deep hologram chain
+                            //   - circular reference detected mid-chain
+                            //   - any internal resolve error
+                            // None of these prove the pointer is permanently
+                            // broken, but the old behaviour `await delete(...)`
+                            // here permanently destroyed real data on the first
+                            // transient miss. Skip the entry instead; a real
+                            // garbage collector should own dead-pointer cleanup.
+                            console.warn(`Hologram at ${holon}/${lens}/${key} did not resolve (soul=${parsed.soul}); skipping.`);
                             resolve(null);
                             return;
                         }
@@ -472,7 +625,7 @@ export async function get(holoInstance, holon, lens, key, password = null, optio
                         // If it returned the hologram itself (if we ever revert to that), this logic would need adjustment.
                         // For now, assume resolvedValue is either the resolved data or we've returned null above.
 
-                        if (resolvedValue !== parsed) { 
+                        if (resolvedValue !== parsed) {
                             parsed = resolvedValue;
                         }
                     }
@@ -505,7 +658,10 @@ export async function get(holoInstance, holon, lens, key, password = null, optio
                 user.get('private').get(lens).get(key) :
                 holoInstance.gun.get(holoInstance.appname).get(holon).get(lens).get(key);
 
-            dataPath.once(handleData);
+            // `.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);
         });
     } catch (error) {
         console.error('Error in get:', error);
@@ -519,12 +675,23 @@ export async function get(holoInstance, holon, lens, key, password = null, optio
  * @param {string} holon - The holon identifier.
  * @param {string} lens - The lens from which to retrieve content.
  * @param {string} [password] - Optional password for private holon.
+ * @param {object} [options] - Additional options.
+ * @param {number} [options.timeout=READ_TIMEOUT_MS] - Per-`.once()` deadline
+ *   (ms); the shallow probe falls back to "empty" after this on cold paths
+ *   where Gun never responds. Pass `0` to disable and keep the historical
+ *   "wait forever" behaviour.
  * @returns {Promise<Array<object>>} - The retrieved content.
  */
-export async function getAll(holoInstance, holon, lens, password = null) {
+export async function getAll(holoInstance, holon, lens, password = null, options = {}) {
     if (!holon || !lens) {
         throw new Error('getAll: Missing required parameters');
     }
+    const {
+        timeout = READ_TIMEOUT_MS,
+        // See `get` above: `_deleted: true` records are dropped from the
+        // response unless the caller opts in.
+        includeDeleted = false,
+    } = options;
 
     const schema = await holoInstance.getSchema(lens);
     if (!schema && holoInstance.strict) {
@@ -584,9 +751,12 @@ export async function getAll(holoInstance, holon, lens, password = null) {
                 holoInstance.gun.get(holoInstance.appname).get(holon).get(lens);
 
             // PASS 1: Get shallow node to determine expected item count.
-            // Retry once if empty — Gun's .once() reads from local cache, which
-            // may be cold immediately after startup before peers have synced.
-            const shallowOnce = () => new Promise((res) => dataPath.once((d) => res(d)));
+            // Wrapped in a deadline (see `onceWithTimeout`) so cold paths
+            // resolve `null` after `timeout` ms instead of hanging forever.
+            // We still retry once below — Gun's `.once()` reads from local
+            // cache, which may be cold immediately after startup before
+            // peers have synced.
+            const shallowOnce = () => onceWithTimeout(dataPath, timeout);
 
             const processShallow = (data) => {
                 if (!data) {
@@ -621,6 +791,11 @@ export async function getAll(holoInstance, holon, lens, password = null) {
                         const parsed = await holoInstance.parse(itemData);
                         if (!parsed || !parsed.id) return;
 
+                        // Drop `_deleted: true` soft-tombstones by default;
+                        // callers wanting them in the result pass
+                        // `{ includeDeleted: true }` to `getAll`.
+                        if (!includeDeleted && parsed._deleted === true) return;
+
                         if (holoInstance.isHologram(parsed)) {
                             try {
                                 const resolved = await holoInstance.resolveHologram(parsed, {
@@ -630,12 +805,11 @@ export async function getAll(holoInstance, holon, lens, password = null) {
                                 });
 
                                 if (resolved === null) {
-                                    console.warn(`Broken hologram detected in getAll for key ${key}. Removing it...`);
-                                    try {
-                                        await holoInstance.delete(holon, lens, key, password);
-                                    } catch (cleanupError) {
-                                        console.error(`Failed to remove broken hologram at ${holon}/${lens}/${key}:`, cleanupError);
-                                    }
+                                    // See `get()` above: null is not proof of a
+                                    // permanently dead pointer. Skip the entry
+                                    // without deleting so transient resolution
+                                    // failures don't destroy real data.
+                                    console.warn(`Hologram at ${holon}/${lens}/${key} did not resolve (soul=${parsed.soul}); skipping.`);
                                     return;
                                 }
 
@@ -678,11 +852,10 @@ export async function getAll(holoInstance, holon, lens, password = null) {
                         return processItem(inline, key);
                     }
                     // Otherwise fetch the leaf — sub-graph reference path.
-                    return new Promise((resolveItem) => {
-                        dataPath.get(key).once((itemData) => {
-                            processItem(itemData, key).then(resolveItem, resolveItem);
-                        });
-                    });
+                    // Same deadline as the shallow probe; a single missing
+                    // leaf can't stall the whole batch.
+                    return onceWithTimeout(dataPath.get(key), timeout)
+                        .then((itemData) => processItem(itemData, key));
                 })).then(() => resolve(Array.from(output.values())));
             };
 

package/federation.js

@@ -480,7 +480,7 @@ export async function removeNotify(holosphere, spaceId1, spaceId2, password1 = n
  */
 export async function getFederated(holosphere, holon, lens, options = {}) {
     // Set default options and extract queryIds
-    const { 
+    const {
         queryIds = null, // New option
         aggregate = false,
         idField = 'id',
@@ -490,9 +490,16 @@ export async function getFederated(holosphere, holon, lens, options = {}) {
         mergeStrategy = null,
         includeLocal = true,
         includeFederated = true,
-        resolveReferences = true, 
+        resolveReferences = true,
         maxFederatedSpaces = -1,
-        timeout = 10000
+        timeout = 10000,
+        // When `resolveReferences` is on, source-soul fetches that fail get
+        // replaced with `{ id, _hologram: { isHologram: false, error } }`
+        // error stubs (federation.js around line 654). By default we filter
+        // those out of the response so consumers never render broken-card
+        // placeholders. Set `includeUnresolvedStubs: true` if you actually
+        // want to surface the failure to the user (e.g. an admin/debug view).
+        includeUnresolvedStubs = false
     } = options;
     
     console.log(`resolveReferences option: ${resolveReferences}`);
@@ -737,14 +744,28 @@ export async function getFederated(holosphere, holon, lens, options = {}) {
                 count: group.length,
                 timestamp: Date.now()
             };
-            
+
             return base;
         });
-        
-        return aggregatedData;
+
+        return includeUnresolvedStubs ? aggregatedData : aggregatedData.filter(isResolved);
     }
-    
-    return result;
+
+    return includeUnresolvedStubs ? result : result.filter(isResolved);
+}
+
+/**
+ * True for any record that isn't an unresolved-reference error stub.
+ *
+ * `getFederated` produces stubs of the shape
+ * `{ id, _hologram: { isHologram: false, error, ... } }` when a source
+ * soul can't be resolved (peer offline, federation in flight, etc.).
+ * Default response now filters those out so consumers don't render
+ * broken-card placeholders.
+ */
+function isResolved(item) {
+    if (!item || typeof item !== 'object') return false;
+    return item._hologram?.isHologram !== false;
 }
 
 /**
@@ -795,7 +816,12 @@ export async function propagate(holosphere, holon, lens, data, options = {}) {
         
         // Only propagate if we have outbound partners configured.
         if (fedInfo && fedInfo.outbound && fedInfo.outbound.length > 0) {
-            let spaces = fedInfo.outbound;
+            // Never propagate back to ourselves. Writing a hologram to the
+            // source holon overwrites the original data with a self-
+            // referencing pointer, and HoloSphere's get() then auto-deletes
+            // it as a "broken hologram" (resolveHologram returns null because
+            // the soul resolves to itself), silently destroying the entry.
+            let spaces = fedInfo.outbound.filter(s => String(s) !== String(holon));
 
             if (targetSpaces && Array.isArray(targetSpaces) && targetSpaces.length > 0) {
                 spaces = spaces.filter(space => targetSpaces.includes(space));
@@ -860,11 +886,19 @@ export async function propagate(holosphere, holon, lens, data, options = {}) {
                                     }
                                 };
                             }
-                            
+
+                            // Defensive: even if the outbound list somehow
+                            // contains the source holon, never write a self-
+                            // hologram. The source already has the original.
+                            if (String(targetSpace) === String(holon)) {
+                                result.skipped++;
+                                return true;
+                            }
+
                             // Store in the target space with redirection disabled and no further auto-propagation
-                            await holosphere.put(targetSpace, lens, payloadToPut, null, { 
-                                disableHologramRedirection: true, 
-                                autoPropagate: false 
+                            await holosphere.put(targetSpace, lens, payloadToPut, null, {
+                                disableHologramRedirection: true,
+                                autoPropagate: false
                             });
 
                             result.success++;

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;
@@ -743,15 +785,18 @@ export async function deleteAllGlobal(holoInstance, tableName, password = null)
 
 /**
  * Subscribe to real-time changes in a global table.
+ *
+ * Returns synchronously — see {@link subscribe} for the same rationale.
+ *
  * @param {HoloSphere} holoInstance - The HoloSphere instance.
  * @param {string} tableName - The table name to subscribe to.
  * @param {string|null} key - Specific key to subscribe to, or null for all keys.
  * @param {function} callback - Callback for data changes.
  * @param {object} [options] - Subscription options.
  * @param {boolean} [options.realtimeOnly] - Only fire for new changes.
- * @returns {Promise<{ unsubscribe: () => void }>}
+ * @returns {{ unsubscribe: () => void, stop: () => void }}
  */
-export async function subscribeGlobal(holoInstance, tableName, key, callback, options = {}) {
+export function subscribeGlobal(holoInstance, tableName, key, callback, options = {}) {
     const dataPath = holoInstance.gun.get(holoInstance.appname).get(tableName);
     let active = true;
 

package/hologram.js

@@ -175,11 +175,28 @@ export async function resolveHologram(holoInstance, hologram, options = {}) {
             if (originalData && !originalData._invalidHologram) {
                     // Attach the canonical `_hologram` envelope. This is the only
                     // resolved-hologram indicator HoloSphere emits.
-                    return attachHologramMeta(originalData, hologram.soul);
+                    const withMeta = attachHologramMeta(originalData, hologram.soul);
+                    // Stamp the source holon's display name so every consumer
+                    // (subscribe, get, getAll, getFederated) has it without a
+                    // second round-trip. Cached on the instance, so a batch of
+                    // holograms from the same source resolves the name once.
+                    if (withMeta._hologram?.sourceHolon && typeof holoInstance.getHolonName === 'function') {
+                        try {
+                            const sourceHolonName = await holoInstance.getHolonName(withMeta._hologram.sourceHolon);
+                            if (sourceHolonName) {
+                                withMeta._hologram = { ...withMeta._hologram, sourceHolonName };
+                            }
+                        } catch { /* best-effort — name lookup must not fail the resolve */ }
+                    }
+                    return withMeta;
                 } else {
-                console.warn(`!!! Original data NOT FOUND for soul: ${hologram.soul}. Removing broken hologram.`);
-                
-                // Return null to indicate the hologram should be removed
+                // Note: this is informational, not a permission to delete. The
+                // source soul may simply not be reachable yet (peer offline,
+                // federation propagation in flight). Callers must decide on
+                // their own GC policy; this function only reports the miss.
+                console.warn(`Could not resolve hologram soul: ${hologram.soul} (target not present locally)`);
+
+                // Return null so the caller skips this entry.
                 return null;
                 }
             } else {