holosphere 1.3.0-alpha4 → 1.3.0-alpha5

package/content.js

@@ -1,5 +1,37 @@
 // 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;
+
+/**
+ * `.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);
+        }
+    });
+}
+
 /**
  * Recursively sanitizes a value for storage in GunDB.
  *
@@ -214,8 +246,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) => {
@@ -400,7 +449,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 +505,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 +523,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 +544,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 +577,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 +594,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 +670,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 +710,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 +724,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 +771,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

@@ -743,15 +743,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 {