holosphere 1.3.0-alpha0 → 1.3.0-alpha4

package/global.js

@@ -65,11 +65,15 @@ export async function putGlobal(holoInstance, tableName, data, password = null)
 
         return new Promise((resolve, reject) => {
             try {
-                // Create a copy of data without the _meta field if it exists
+                // Create a copy of data, stripping read-side envelopes that
+                // must never be persisted (they're attached at resolution time).
                 let dataToStore = { ...data };
                 if (dataToStore._meta !== undefined) {
                     delete dataToStore._meta;
                 }
+                if (dataToStore._hologram !== undefined) {
+                    delete dataToStore._hologram;
+                }
                 const payload = JSON.stringify(dataToStore);
 
                 // Check if the data being stored is a hologram
@@ -327,8 +331,12 @@ export async function getAllGlobal(holoInstance, tableName, password = null) {
                 user.get('private').get(tableName) :
                 holoInstance.gun.get(holoInstance.appname).get(tableName);
 
-            // PASS 1: Get shallow node to determine expected item count
-            dataPath.once((data) => {
+            // 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)));
+
+            const processShallow = (data) => {
                 if (!data) {
                     resolve([]);
                     return;
@@ -350,60 +358,63 @@ export async function getAllGlobal(holoInstance, tableName, password = null) {
                     return;
                 }
 
-                // PASS 2: Use map().once() to iterate and get full item data
-                let receivedCount = 0;
-
-                dataPath.map().once(async (itemData, key) => {
-                    if (!itemData || key === '_') {
-                        receivedCount++;
-                        if (receivedCount >= expectedCount) {
-                            await Promise.all(pendingProcessing);
-                            resolve(output);
-                        }
-                        return;
-                    }
-
-                    const processingPromise = (async () => {
-                        try {
-                            const parsed = await holoInstance.parse(itemData);
-                            if (!parsed) return;
+                // PASS 2: iterate explicitly over the filtered keys.
+                // Avoid dataPath.map().once() — it fires for null tombstone
+                // siblings and can resolve before real items are processed.
+                const processItem = async (itemData, key) => {
+                    if (!itemData) return;
+                    try {
+                        const parsed = await holoInstance.parse(itemData);
+                        if (!parsed) return;
 
-                            if (holoInstance.isHologram(parsed)) {
-                                const resolved = await holoInstance.resolveHologram(parsed, {
-                                    followHolograms: true
-                                });
+                        if (holoInstance.isHologram(parsed)) {
+                            const resolved = await holoInstance.resolveHologram(parsed, {
+                                followHolograms: true
+                            });
 
-                                if (resolved === null) {
-                                    try {
-                                        await holoInstance.deleteGlobal(tableName, key, password);
-                                    } catch (deleteError) {
-                                        console.error(`Failed to delete invalid global hologram at ${tableName}/${key}:`, deleteError);
-                                    }
-                                    return;
+                            if (resolved === null) {
+                                try {
+                                    await holoInstance.deleteGlobal(tableName, key, password);
+                                } catch (deleteError) {
+                                    console.error(`Failed to delete invalid global hologram at ${tableName}/${key}:`, deleteError);
                                 }
+                                return;
+                            }
 
-                                if (resolved !== parsed) {
-                                    output.push(resolved);
-                                } else {
-                                    output.push(parsed);
-                                }
+                            if (resolved !== parsed) {
+                                output.push(resolved);
                             } else {
                                 output.push(parsed);
                             }
-                        } catch (error) {
-                            console.error('Error parsing data:', error);
+                        } else {
+                            output.push(parsed);
                         }
-                    })();
-
-                    pendingProcessing.push(processingPromise);
-                    receivedCount++;
+                    } catch (error) {
+                        console.error('Error parsing data:', error);
+                    }
+                };
 
-                    if (receivedCount >= expectedCount) {
-                        await Promise.all(pendingProcessing);
-                        resolve(output);
+                Promise.all(keys.map((key) => {
+                    const inline = data[key];
+                    if (typeof inline !== 'object' || inline === null) {
+                        return processItem(inline, key);
                     }
-                });
-            });
+                    return new Promise((resolveItem) => {
+                        dataPath.get(key).once((itemData) => {
+                            processItem(itemData, key).then(resolveItem, resolveItem);
+                        });
+                    });
+                })).then(() => resolve(output));
+            };
+
+            (async () => {
+                let data = await shallowOnce();
+                if (!data) {
+                    await new Promise(r => setTimeout(r, 1500));
+                    data = await shallowOnce();
+                }
+                processShallow(data);
+            })();
         });
     } catch (error) {
         console.error('Error in getAllGlobal:', error);

package/hologram.js

@@ -78,7 +78,37 @@ export function isHologram(data) {
 }
 
 /**
- * Resolves a hologram to its actual data
+ * Attaches the canonical `_hologram` envelope to data resolved from a soul reference.
+ *
+ * This is the SINGLE source of truth for resolved-hologram metadata in HoloSphere.
+ * Every code path that returns "data resolved from a hologram reference" must go
+ * through this helper so consumers can rely on one shape.
+ *
+ * @param {object} originalData - The data fetched from the source holon/lens/key.
+ * @param {string} hologramSoul - The soul path the hologram pointed at.
+ * @returns {object} - originalData merged with `_hologram: { isHologram, soul, sourceHolon, sourceLens, sourceKey, resolvedAt }`.
+ */
+export function attachHologramMeta(originalData, hologramSoul) {
+    const parts = parseSoulPath(hologramSoul);
+    return {
+        ...originalData,
+        _hologram: {
+            isHologram: true,
+            soul: hologramSoul,
+            sourceHolon: parts?.holon ?? null,
+            sourceLens: parts?.lens ?? null,
+            sourceKey: parts?.key ?? null,
+            resolvedAt: Date.now(),
+        },
+    };
+}
+
+/**
+ * Resolves a hologram to its actual data.
+ *
+ * On success, the returned object spreads `originalData` and attaches the
+ * canonical `_hologram` envelope (see {@link attachHologramMeta}).
+ *
  * @param {HoloSphere} holoInstance - The HoloSphere instance.
  * @param {object} hologram - The hologram to resolve
  * @param {object} [options] - Optional parameters
@@ -86,7 +116,7 @@ export function isHologram(data) {
  * @param {Set<string>} [options.visited] - Internal use: Tracks visited souls to prevent loops
  * @param {number} [options.maxDepth=10] - Maximum resolution depth to prevent infinite loops
  * @param {number} [options.currentDepth=0] - Current resolution depth
- * @returns {Promise<object|null>} - The resolved data, null if resolution failed due to target not found, or the original hologram for circular/invalid cases.
+ * @returns {Promise<object|null>} - The resolved data with `_hologram` attached, null if resolution failed due to target not found, or the original hologram for circular/invalid cases.
  */
 export async function resolveHologram(holoInstance, hologram, options = {}) {
     if (!isHologram(hologram)) {
@@ -143,16 +173,9 @@ export async function resolveHologram(holoInstance, hologram, options = {}) {
                 );
 
             if (originalData && !originalData._invalidHologram) {
-                    // Structure for the returned object - isHologram (top-level) is removed
-                    return {
-                        ...originalData,
-                        _meta: {
-                            ...(originalData._meta || {}), // Preserve original _meta
-                            resolvedFromHologram: true,    // This is now the primary indicator
-                        hologramSoul: hologram.soul,   // Clarified meta field
-                        resolutionDepth: currentDepth
-                        }
-                    };
+                    // Attach the canonical `_hologram` envelope. This is the only
+                    // resolved-hologram indicator HoloSphere emits.
+                    return attachHologramMeta(originalData, hologram.soul);
                 } else {
                 console.warn(`!!! Original data NOT FOUND for soul: ${hologram.soul}. Removing broken hologram.`);
                 
@@ -179,5 +202,6 @@ export default {
     createHologram,
     parseSoulPath,
     isHologram,
-    resolveHologram
-}; 
+    resolveHologram,
+    attachHologramMeta
+};