holosphere 1.3.0-alpha7 → 1.3.0-alpha9

package/content.js

@@ -38,12 +38,41 @@ const WRITE_TIMEOUT_MS = 5000;
  *
  * The first responder wins — both branches are idempotent so a late
  * `.once()` callback after timeout is harmlessly ignored.
+ *
+ * Pass `{ awaitNetwork: true }` for cold reads that MUST reach the network —
+ * notably cross-holon hologram soul resolution. Gun's `.once()` fires
+ * synchronously with whatever is in the local graph and never re-fires; for a
+ * node we never subscribed to (another holon's lens), that first value is
+ * `undefined` even though a peer is about to deliver the real data a few ms
+ * later. Accepting that `undefined` as "not found" is exactly what produced
+ * the `Could not resolve hologram soul: … (target not present locally)` false
+ * negatives on freshly-loaded federated data. In `awaitNetwork` mode we use
+ * `.on()` instead, skip the cold `undefined`, and settle once the value
+ * syncs — while still honouring an explicit `null` (a real tombstone) and the
+ * deadline (for nodes no peer ever answers). The common, same-holon read path
+ * keeps the fast `.once()` behaviour so empty/missing local reads resolve
+ * immediately instead of blocking for the full deadline.
  */
-function onceWithTimeout(node, timeoutMs = READ_TIMEOUT_MS) {
+function onceWithTimeout(node, timeoutMs = READ_TIMEOUT_MS, { awaitNetwork = false } = {}) {
+    if (!awaitNetwork) {
+        return new Promise((resolve) => {
+            let done = false;
+            const finish = (v) => { if (!done) { done = true; resolve(v); } };
+            node.once((data) => finish(data));
+            if (timeoutMs > 0) {
+                setTimeout(() => finish(null), timeoutMs);
+            }
+        });
+    }
+
     return new Promise((resolve) => {
         let done = false;
-        const finish = (v) => { if (!done) { done = true; resolve(v); } };
-        node.once((data) => finish(data));
+        const detach = () => { try { if (node.off) node.off(); } catch { /* ignore */ } };
+        const finish = (v) => { if (!done) { done = true; detach(); resolve(v); } };
+        node.on((data) => {
+            if (data === undefined) return; // cold/not-known yet — wait for a peer
+            finish(data); // defined value OR explicit null tombstone — definitive
+        });
         if (timeoutMs > 0) {
             setTimeout(() => finish(null), timeoutMs);
         }
@@ -535,6 +564,11 @@ export async function get(holoInstance, holon, lens, key, password = null, optio
         validationOptions = {},
         visited,
         timeout = READ_TIMEOUT_MS,
+        // Network-aware read: skip Gun's cold synchronous `undefined` and wait
+        // (up to `timeout`) for a peer to answer. Used by hologram soul
+        // resolution so cross-holon reads aren't misreported as missing. See
+        // `onceWithTimeout`. Off by default to keep same-holon reads fast.
+        awaitNetwork = false,
         // `_deleted: true` is the soft-tombstone convention used by the bot,
         // the web dashboard, and the MCP council tools. Pre-this fix the
         // library was unaware of it and every caller filtered defensively.
@@ -661,7 +695,7 @@ export async function get(holoInstance, holon, lens, key, password = null, optio
             // `.once()` wrapped in a deadline — cold-path reads (peer offline,
             // never-written key) used to hang forever otherwise. After
             // `timeout` ms with no Gun response we treat it as "not found".
-            onceWithTimeout(dataPath, timeout).then(handleData);
+            onceWithTimeout(dataPath, timeout, { awaitNetwork }).then(handleData);
         });
     } catch (error) {
         console.error('Error in get:', error);

package/federation.js

@@ -4,7 +4,7 @@
  */
 
 import * as h3 from 'h3-js';
-import { attachHologramMeta } from './hologram.js';
+import { attachHologramMeta, parseSoulPath } from './hologram.js';
 
 /**
  * Look up a holon's display name from its `settings` lens.
@@ -887,11 +887,32 @@ 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)) {
+                            // Never write a hologram to the holon its soul
+                            // already points at — that overwrites the original
+                            // record with a pointer to itself (a circular
+                            // hologram that can never resolve, so get() logs
+                            // "CIRCULAR … Breaking loop" forever). Two cases:
+                            //   • target === source: the source already holds
+                            //     the original; don't self-hologram it.
+                            //   • forwarding a RECEIVED hologram back toward its
+                            //     birthplace via a third hop (A→B propagates,
+                            //     then B→A federation echoes the hologram — whose
+                            //     soul still points at A — home). The plain
+                            //     `target === holon` check misses this because
+                            //     here `holon` is B, not A.
+                            const soulTargetHolon =
+                                payloadToPut && typeof payloadToPut.soul === 'string'
+                                    ? parseSoulPath(payloadToPut.soul)?.holon
+                                    : null;
+                            if (
+                                String(targetSpace) === String(holon) ||
+                                (soulTargetHolon != null &&
+                                    String(soulTargetHolon) === String(targetSpace))
+                            ) {
                                 result.skipped++;
+                                result.messages.push(
+                                    `Skipped self-referential propagation of ${data.id} to ${targetSpace} (hologram soul already points there).`
+                                );
                                 return true;
                             }
 
@@ -1018,10 +1039,31 @@ export async function propagate(holosphere, holon, lens, data, options = {}) {
                                     };
                                 }
                                 
+                                // Same self-reference guard as partner
+                                // propagation: never write a hologram to the
+                                // holon its soul points at (would create a
+                                // circular self-pointer that can never resolve).
+                                const soulTargetHolonParent =
+                                    payloadToPut && typeof payloadToPut.soul === 'string'
+                                        ? parseSoulPath(payloadToPut.soul)?.holon
+                                        : null;
+                                if (
+                                    String(parentHexagon) === String(holon) ||
+                                    (soulTargetHolonParent != null &&
+                                        String(soulTargetHolonParent) === String(parentHexagon))
+                                ) {
+                                    result.parentPropagation.skipped =
+                                        (result.parentPropagation.skipped || 0) + 1;
+                                    result.parentPropagation.messages.push(
+                                        `Skipped self-referential parent propagation of ${data.id} to ${parentHexagon} (hologram soul already points there).`
+                                    );
+                                    return true;
+                                }
+
                                 // Store in the parent hexagon with redirection disabled and no further auto-propagation
-                                await holosphere.put(parentHexagon, lens, payloadToPut, null, { 
-                                    disableHologramRedirection: true, 
-                                    autoPropagate: false 
+                                await holosphere.put(parentHexagon, lens, payloadToPut, null, {
+                                    disableHologramRedirection: true,
+                                    autoPropagate: false
                                 });
 
                                 console.log(`[Federation] Successfully propagated to parent hexagon: ${parentHexagon}`);

package/hologram.js

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

package/holosphere-bundle.esm.js

@@ -1,9 +1,9 @@
 /**
- * HoloSphere ESM Bundle v1.3.0-alpha7
+ * HoloSphere ESM Bundle v1.3.0-alpha9
  * ES6 Module version with all dependencies bundled
  * 
  * Usage:
- * import HoloSphere from 'https://unpkg.com/holosphere@1.3.0-alpha7/holosphere-bundle.esm.js';
+ * import HoloSphere from 'https://unpkg.com/holosphere@1.3.0-alpha9/holosphere-bundle.esm.js';
  * const hs = new HoloSphere('myapp');
  */
 var __create = Object.create;
@@ -24385,7 +24385,13 @@ async function resolveHologram(holoInstance, hologram, options = {}) {
           resolveHolograms: followHolograms,
           visited: nextVisited,
           maxDepth,
-          currentDepth: currentDepth + 1
+          currentDepth: currentDepth + 1,
+          // The soul almost always points at a DIFFERENT holon's lens
+          // this peer never subscribed to, so the node is cold: Gun's
+          // `.once()` would fire `undefined` synchronously and we'd
+          // wrongly report "target not present locally". Wait for the
+          // network round-trip instead.
+          awaitNetwork: true
         }
       );
       if (originalData && !originalData._invalidHologram) {
@@ -25012,8 +25018,12 @@ async function propagate(holosphere, holon, lens, data, options = {}) {
                   }
                 };
               }
-              if (String(targetSpace) === String(holon)) {
+              const soulTargetHolon = payloadToPut && typeof payloadToPut.soul === "string" ? parseSoulPath(payloadToPut.soul)?.holon : null;
+              if (String(targetSpace) === String(holon) || soulTargetHolon != null && String(soulTargetHolon) === String(targetSpace)) {
                 result.skipped++;
+                result.messages.push(
+                  `Skipped self-referential propagation of ${data.id} to ${targetSpace} (hologram soul already points there).`
+                );
                 return true;
               }
               await holosphere.put(targetSpace, lens, payloadToPut, null, {
@@ -25116,6 +25126,14 @@ async function propagate(holosphere, holon, lens, data, options = {}) {
                     }
                   };
                 }
+                const soulTargetHolonParent = payloadToPut && typeof payloadToPut.soul === "string" ? parseSoulPath(payloadToPut.soul)?.holon : null;
+                if (String(parentHexagon) === String(holon) || soulTargetHolonParent != null && String(soulTargetHolonParent) === String(parentHexagon)) {
+                  result.parentPropagation.skipped = (result.parentPropagation.skipped || 0) + 1;
+                  result.parentPropagation.messages.push(
+                    `Skipped self-referential parent propagation of ${data.id} to ${parentHexagon} (hologram soul already points there).`
+                  );
+                  return true;
+                }
                 await holosphere.put(parentHexagon, lens, payloadToPut, null, {
                   disableHologramRedirection: true,
                   autoPropagate: false
@@ -25366,16 +25384,41 @@ function clearSchemaCache(holoInstance, lens = null) {
 // content.js
 var READ_TIMEOUT_MS = 8e3;
 var WRITE_TIMEOUT_MS = 5e3;
-function onceWithTimeout(node, timeoutMs = READ_TIMEOUT_MS) {
+function onceWithTimeout(node, timeoutMs = READ_TIMEOUT_MS, { awaitNetwork = false } = {}) {
+  if (!awaitNetwork) {
+    return new Promise((resolve) => {
+      let done = false;
+      const finish = (v) => {
+        if (!done) {
+          done = true;
+          resolve(v);
+        }
+      };
+      node.once((data) => finish(data));
+      if (timeoutMs > 0) {
+        setTimeout(() => finish(null), timeoutMs);
+      }
+    });
+  }
   return new Promise((resolve) => {
     let done = false;
+    const detach = () => {
+      try {
+        if (node.off) node.off();
+      } catch {
+      }
+    };
     const finish = (v) => {
       if (!done) {
         done = true;
+        detach();
         resolve(v);
       }
     };
-    node.once((data) => finish(data));
+    node.on((data) => {
+      if (data === void 0) return;
+      finish(data);
+    });
     if (timeoutMs > 0) {
       setTimeout(() => finish(null), timeoutMs);
     }
@@ -25716,6 +25759,11 @@ async function get(holoInstance, holon, lens, key, password = null, options = {}
     validationOptions = {},
     visited,
     timeout = READ_TIMEOUT_MS,
+    // Network-aware read: skip Gun's cold synchronous `undefined` and wait
+    // (up to `timeout`) for a peer to answer. Used by hologram soul
+    // resolution so cross-holon reads aren't misreported as missing. See
+    // `onceWithTimeout`. Off by default to keep same-holon reads fast.
+    awaitNetwork = false,
     // `_deleted: true` is the soft-tombstone convention used by the bot,
     // the web dashboard, and the MCP council tools. Pre-this fix the
     // library was unaware of it and every caller filtered defensively.
@@ -25801,7 +25849,7 @@ async function get(holoInstance, holon, lens, key, password = null, options = {}
         }
       };
       const dataPath = password ? user.get("private").get(lens).get(key) : holoInstance.gun.get(holoInstance.appname).get(holon).get(lens).get(key);
-      onceWithTimeout(dataPath, timeout).then(handleData);
+      onceWithTimeout(dataPath, timeout, { awaitNetwork }).then(handleData);
     });
   } catch (error) {
     console.error("Error in get:", error);
@@ -27234,7 +27282,11 @@ function subscribe(holoInstance, holon, lens, callback) {
         try {
           let parsed = await holoInstance.parse(data);
           if (parsed && holoInstance.isHologram(parsed)) {
+            const hologramSoul = parsed.soul;
             const resolved = await holoInstance.resolveHologram(parsed, { followHolograms: true });
+            if (resolved === null) {
+              console.warn(`Hologram at ${holon}/${lens}/${key} did not resolve (soul=${hologramSoul}); skipping.`);
+            }
             if (resolved !== parsed) {
               parsed = resolved;
             }

package/holosphere-bundle.js

@@ -1,5 +1,5 @@
 /**
- * HoloSphere Bundle v1.3.0-alpha7
+ * HoloSphere Bundle v1.3.0-alpha9
  * Holonic Geospatial Communication Infrastructure
  * 
  * Includes:
@@ -9,7 +9,7 @@
  * - Ajv (JSON schema validation)
  * 
  * Usage:
- * <script src="https://unpkg.com/holosphere@1.3.0-alpha7/holosphere-bundle.js"></script>
+ * <script src="https://unpkg.com/holosphere@1.3.0-alpha9/holosphere-bundle.js"></script>
  * <script>
  *   const hs = new HoloSphere('myapp');
  * </script>
@@ -24411,7 +24411,13 @@ var HoloSphere = (() => {
             resolveHolograms: followHolograms,
             visited: nextVisited,
             maxDepth,
-            currentDepth: currentDepth + 1
+            currentDepth: currentDepth + 1,
+            // The soul almost always points at a DIFFERENT holon's lens
+            // this peer never subscribed to, so the node is cold: Gun's
+            // `.once()` would fire `undefined` synchronously and we'd
+            // wrongly report "target not present locally". Wait for the
+            // network round-trip instead.
+            awaitNetwork: true
           }
         );
         if (originalData && !originalData._invalidHologram) {
@@ -25038,8 +25044,12 @@ var HoloSphere = (() => {
                     }
                   };
                 }
-                if (String(targetSpace) === String(holon)) {
+                const soulTargetHolon = payloadToPut && typeof payloadToPut.soul === "string" ? parseSoulPath(payloadToPut.soul)?.holon : null;
+                if (String(targetSpace) === String(holon) || soulTargetHolon != null && String(soulTargetHolon) === String(targetSpace)) {
                   result.skipped++;
+                  result.messages.push(
+                    `Skipped self-referential propagation of ${data.id} to ${targetSpace} (hologram soul already points there).`
+                  );
                   return true;
                 }
                 await holosphere.put(targetSpace, lens, payloadToPut, null, {
@@ -25142,6 +25152,14 @@ var HoloSphere = (() => {
                       }
                     };
                   }
+                  const soulTargetHolonParent = payloadToPut && typeof payloadToPut.soul === "string" ? parseSoulPath(payloadToPut.soul)?.holon : null;
+                  if (String(parentHexagon) === String(holon) || soulTargetHolonParent != null && String(soulTargetHolonParent) === String(parentHexagon)) {
+                    result.parentPropagation.skipped = (result.parentPropagation.skipped || 0) + 1;
+                    result.parentPropagation.messages.push(
+                      `Skipped self-referential parent propagation of ${data.id} to ${parentHexagon} (hologram soul already points there).`
+                    );
+                    return true;
+                  }
                   await holosphere.put(parentHexagon, lens, payloadToPut, null, {
                     disableHologramRedirection: true,
                     autoPropagate: false
@@ -25392,16 +25410,41 @@ var HoloSphere = (() => {
   // content.js
   var READ_TIMEOUT_MS = 8e3;
   var WRITE_TIMEOUT_MS = 5e3;
-  function onceWithTimeout(node, timeoutMs = READ_TIMEOUT_MS) {
+  function onceWithTimeout(node, timeoutMs = READ_TIMEOUT_MS, { awaitNetwork = false } = {}) {
+    if (!awaitNetwork) {
+      return new Promise((resolve) => {
+        let done = false;
+        const finish = (v) => {
+          if (!done) {
+            done = true;
+            resolve(v);
+          }
+        };
+        node.once((data) => finish(data));
+        if (timeoutMs > 0) {
+          setTimeout(() => finish(null), timeoutMs);
+        }
+      });
+    }
     return new Promise((resolve) => {
       let done = false;
+      const detach = () => {
+        try {
+          if (node.off) node.off();
+        } catch {
+        }
+      };
       const finish = (v) => {
         if (!done) {
           done = true;
+          detach();
           resolve(v);
         }
       };
-      node.once((data) => finish(data));
+      node.on((data) => {
+        if (data === void 0) return;
+        finish(data);
+      });
       if (timeoutMs > 0) {
         setTimeout(() => finish(null), timeoutMs);
       }
@@ -25742,6 +25785,11 @@ var HoloSphere = (() => {
       validationOptions = {},
       visited,
       timeout = READ_TIMEOUT_MS,
+      // Network-aware read: skip Gun's cold synchronous `undefined` and wait
+      // (up to `timeout`) for a peer to answer. Used by hologram soul
+      // resolution so cross-holon reads aren't misreported as missing. See
+      // `onceWithTimeout`. Off by default to keep same-holon reads fast.
+      awaitNetwork = false,
       // `_deleted: true` is the soft-tombstone convention used by the bot,
       // the web dashboard, and the MCP council tools. Pre-this fix the
       // library was unaware of it and every caller filtered defensively.
@@ -25827,7 +25875,7 @@ var HoloSphere = (() => {
           }
         };
         const dataPath = password ? user.get("private").get(lens).get(key) : holoInstance.gun.get(holoInstance.appname).get(holon).get(lens).get(key);
-        onceWithTimeout(dataPath, timeout).then(handleData);
+        onceWithTimeout(dataPath, timeout, { awaitNetwork }).then(handleData);
       });
     } catch (error) {
       console.error("Error in get:", error);
@@ -27260,7 +27308,11 @@ var HoloSphere = (() => {
           try {
             let parsed = await holoInstance.parse(data);
             if (parsed && holoInstance.isHologram(parsed)) {
+              const hologramSoul = parsed.soul;
               const resolved = await holoInstance.resolveHologram(parsed, { followHolograms: true });
+              if (resolved === null) {
+                console.warn(`Hologram at ${holon}/${lens}/${key} did not resolve (soul=${hologramSoul}); skipping.`);
+              }
               if (resolved !== parsed) {
                 parsed = resolved;
               }