holosphere 1.3.0-alpha3 → 1.3.0-alpha4

package/content.js

@@ -1,5 +1,64 @@
 // holo_content.js
 
+/**
+ * Recursively sanitizes a value for storage in GunDB.
+ *
+ * Drops keys whose values would corrupt the graph or round-trip incorrectly:
+ *   - undefined, NaN, Infinity, -Infinity (JSON.stringify silently turns
+ *     these into nothing or "null", which is how malformed payloads like
+ *     `"initiated":,` end up in the graph and surface later as per-character
+ *     parse warnings).
+ *   - functions, symbols, bigints (not JSON-representable).
+ * Preserves null (legitimate Gun tombstone / explicit empty value).
+ * Guards against circular references.
+ *
+ * Logs one warning per dropped path so the caller can fix the producer.
+ */
+function sanitizeForStorage(value, path = '', seen = new WeakSet(), warnings = []) {
+    if (value === null) return null;
+    const t = typeof value;
+
+    if (t === 'number') {
+        if (!Number.isFinite(value)) {
+            warnings.push(`${path || '<root>'}: ${value} (non-finite number)`);
+            return undefined;
+        }
+        return value;
+    }
+    if (t === 'string' || t === 'boolean') return value;
+    if (t === 'undefined' || t === 'function' || t === 'symbol' || t === 'bigint') {
+        warnings.push(`${path || '<root>'}: ${t}`);
+        return undefined;
+    }
+
+    if (t === 'object') {
+        if (seen.has(value)) {
+            warnings.push(`${path || '<root>'}: circular reference`);
+            return undefined;
+        }
+        seen.add(value);
+
+        if (Array.isArray(value)) {
+            const out = [];
+            for (let i = 0; i < value.length; i++) {
+                const cleaned = sanitizeForStorage(value[i], `${path}[${i}]`, seen, warnings);
+                out.push(cleaned === undefined ? null : cleaned);
+            }
+            return out;
+        }
+
+        const out = {};
+        for (const k of Object.keys(value)) {
+            const cleaned = sanitizeForStorage(value[k], path ? `${path}.${k}` : k, seen, warnings);
+            if (cleaned !== undefined) out[k] = cleaned;
+        }
+        return out;
+    }
+
+    warnings.push(`${path || '<root>'}: unsupported type ${t}`);
+    return undefined;
+}
+
 /**
  * Stores content in the specified holon and lens.
  * If the target path already contains a hologram, the put operation will be
@@ -142,15 +201,21 @@ export async function put(holoInstance, holon, lens, data, password = null, opti
 
         return 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).
-                let dataToStore = { ...data };
-                if (dataToStore._meta !== undefined) {
-                    delete dataToStore._meta;
-                }
-                if (dataToStore._hologram !== undefined) {
-                    delete dataToStore._hologram;
+                // Sanitize before serialization so undefined/NaN/Infinity etc.
+                // can never produce a malformed payload like `"initiated":,`
+                // (which is what causes per-character parse warnings on read).
+                const sanitizeWarnings = [];
+                let dataToStore = sanitizeForStorage(data, '', new WeakSet(), sanitizeWarnings) || {};
+                if (sanitizeWarnings.length > 0) {
+                    console.warn(
+                        `holosphere.put: sanitized ${sanitizeWarnings.length} field(s) at ${targetHolon}/${targetLens}/${targetKey} (id=${data.id}):`,
+                        sanitizeWarnings
+                    );
                 }
+                // Strip read-side envelopes that must never be persisted
+                // (they're attached at resolution time).
+                if (dataToStore._meta !== undefined) delete dataToStore._meta;
+                if (dataToStore._hologram !== undefined) delete dataToStore._hologram;
                 const payload = JSON.stringify(dataToStore); // The data being stored
 
                 const putCallback = async (ack) => {

package/federation.js

@@ -6,6 +6,35 @@
 import * as h3 from 'h3-js';
 import { attachHologramMeta } from './hologram.js';
 
+/**
+ * Look up a holon's display name from its `settings` lens.
+ *
+ * Returns the `name` field of the holon's settings document, or null if
+ * settings are missing or unnamed. Callers should fall back to the bare
+ * holon id when this returns null.
+ *
+ * @param {HoloSphere} holosphere
+ * @param {string} space - holon id
+ * @returns {Promise<string|null>}
+ */
+async function getHolonName(holosphere, space) {
+    if (!holosphere || !space) return null;
+    try {
+        const settings = await holosphere.get(space, 'settings', space);
+        if (!settings) return null;
+        if (Array.isArray(settings)) {
+            const found = settings.find(s => s && typeof s.name === 'string' && s.name.trim() !== '');
+            return found ? found.name : null;
+        }
+        if (typeof settings.name === 'string' && settings.name.trim() !== '') {
+            return settings.name;
+        }
+        return null;
+    } catch {
+        return null;
+    }
+}
+
 /**
  * Creates a directional federation relationship between two spaces.
  *
@@ -149,7 +178,18 @@ export async function subscribeFederation(holosphere, spaceId, password = null,
     const subscriptions = [];
     let lastNotificationTime = {};
     
+    // Cache partner display names once at setup. Each callback firing for
+    // a given partner uses the same name without re-reading settings.
+    const partnerNames = new Map();
+
     if (fedInfo.inbound && fedInfo.inbound.length > 0) {
+        await Promise.all(
+            fedInfo.inbound.map(async space => {
+                const name = await getHolonName(holosphere, space);
+                partnerNames.set(space, name);
+            })
+        );
+
         for (const federatedSpace of fedInfo.inbound) {
             // For each lens specified (or all if '*')
             for (const lens of lenses) {
@@ -158,27 +198,34 @@ export async function subscribeFederation(holosphere, spaceId, password = null,
                         try {
                             // Skip if data is missing or not from federated space
                             if (!data || !data.id) return;
-                            
+
                             // Apply throttling if configured
                             const now = Date.now();
                             const key = `${federatedSpace}_${lens}_${data.id}`;
-                            
+
                             if (throttle > 0) {
-                                if (lastNotificationTime[key] && 
+                                if (lastNotificationTime[key] &&
                                     (now - lastNotificationTime[key]) < throttle) {
                                     return; // Skip this notification (throttled)
                                 }
                                 lastNotificationTime[key] = now;
                             }
-                            
-                            // Add federation metadata if not present
-                            if (!data.federation) {
-                                data.federation = {
+
+                            // Add federation metadata if not present.
+                            // Use the canonical `_federation` envelope so it
+                            // matches what propagate() and getFederated()
+                            // produce, and what consumers (UI badges, etc.)
+                            // already check for.
+                            if (!data._federation) {
+                                const partnerName = partnerNames.get(federatedSpace);
+                                data._federation = {
                                     origin: federatedSpace,
-                                    timestamp: now
+                                    sourceLens: lens,
+                                    timestamp: now,
+                                    ...(partnerName ? { originName: partnerName } : {})
                                 };
                             }
-                            
+
                             // Execute callback with the data
                             await callback(data, federatedSpace, lens);
                         } catch (error) {
@@ -476,10 +523,37 @@ export async function getFederated(holosphere, holon, lens, options = {}) {
         spacesToQuery = spacesToQuery.concat(federatedSpaces);
     }
 
+    // Resolve display names for federated partner spaces in parallel, so
+    // every tagged item can carry the holon's name. Compute once per call.
+    const remoteSpaces = spacesToQuery.filter(s => s !== holon);
+    const spaceNames = new Map();
+    await Promise.all(
+        remoteSpaces.map(async space => {
+            const name = await getHolonName(holosphere, space);
+            spaceNames.set(space, name);
+        })
+    );
+
+    // Tag items pulled from a federated partner with the space they came
+    // from (and its resolved display name, if any). Local items are left
+    // untouched so consumers can distinguish own vs. external by absence
+    // or presence of `_federation`.
+    const tagWithSource = (item, space) => {
+        if (!item || space === holon) return item;
+        const originName = spaceNames.get(space);
+        const fed = {
+            ...(item._federation || {}),
+            origin: space,
+            sourceLens: lens
+        };
+        if (originName) fed.originName = originName;
+        return { ...item, _federation: fed };
+    };
+
     // Fetch data from all relevant spaces
     for (const currentSpace of spacesToQuery) {
         if (queryIds && Array.isArray(queryIds)) {
-            // --- Fetch specific IDs using holosphere.get --- 
+            // --- Fetch specific IDs using holosphere.get ---
             console.log(`Fetching specific IDs from ${currentSpace}: ${queryIds.join(', ')}`);
             for (const itemId of queryIds) {
                 if (fetchedItems.has(itemId)) continue; // Skip if already fetched
@@ -487,7 +561,7 @@ export async function getFederated(holosphere, holon, lens, options = {}) {
                     holosphere.get(currentSpace, lens, itemId)
                         .then(item => {
                             if (item) {
-                                fetchedItems.set(itemId, item);
+                                fetchedItems.set(itemId, tagWithSource(item, currentSpace));
                             }
                         })
                         .catch(err => console.warn(`Error fetching item ${itemId} from ${currentSpace}: ${err.message}`))
@@ -504,7 +578,7 @@ export async function getFederated(holosphere, holon, lens, options = {}) {
                     .then(items => {
                         for (const item of items) {
                             if (item && item[idField] && !fetchedItems.has(item[idField])) {
-                                fetchedItems.set(item[idField], item);
+                                fetchedItems.set(item[idField], tagWithSource(item, currentSpace));
                             }
                         }
                     })
@@ -554,7 +628,26 @@ export async function getFederated(holosphere, holon, lens, options = {}) {
                         if (originalData) {
                             // Replace the reference with the resolved data, attaching
                             // the canonical _hologram envelope (single source of truth).
-                            result[i] = attachHologramMeta(originalData, item.soul);
+                            const withMeta = attachHologramMeta(originalData, item.soul);
+                            // Stamp the source holon's display name so consumers
+                            // don't need a second round-trip to render it. Use
+                            // the per-call cache when possible to avoid duplicate
+                            // settings reads across many holograms from the same
+                            // source.
+                            if (withMeta._hologram?.sourceHolon) {
+                                let sourceHolonName = spaceNames.get(withMeta._hologram.sourceHolon);
+                                if (sourceHolonName === undefined) {
+                                    sourceHolonName = await getHolonName(holosphere, withMeta._hologram.sourceHolon);
+                                    spaceNames.set(withMeta._hologram.sourceHolon, sourceHolonName);
+                                }
+                                if (sourceHolonName) {
+                                    withMeta._hologram = {
+                                        ...withMeta._hologram,
+                                        sourceHolonName
+                                    };
+                                }
+                            }
+                            result[i] = withMeta;
                         } else {
                             // Original data not found — keep the id so callers can
                             // identify the broken reference, and surface the error.
@@ -732,6 +825,11 @@ export async function propagate(holosphere, holon, lens, data, options = {}) {
                     // Check if data is already a hologram
                     const isAlreadyHologram = holosphere.isHologram(data);
 
+                    // Resolve our own holon's name once so every propagated
+                    // payload carries it. Falls back to undefined (the field
+                    // is omitted) so consumers can use the bare holon id.
+                    const ownName = await getHolonName(holosphere, holon);
+
                     // For each target space, propagate the data
                     const propagatePromises = spaces.map(async (targetSpace) => {
                         try {
@@ -740,7 +838,8 @@ export async function propagate(holosphere, holon, lens, data, options = {}) {
                                 origin: holon,       // The space from which this data is being propagated
                                 sourceLens: lens,    // The lens from which this data is being propagated
                                 propagatedAt: Date.now(),
-                                originalId: data.id
+                                originalId: data.id,
+                                ...(ownName ? { originName: ownName } : {})
                             };
 
                             if (useHolograms && !isAlreadyHologram) {
@@ -847,7 +946,11 @@ export async function propagate(holosphere, holon, lens, data, options = {}) {
                         
                         // Check if data is already a hologram (reuse from federation section)
                         const isAlreadyHologram = holosphere.isHologram(data);
-                        
+
+                        // Resolve our own holon's name once for parent propagation
+                        // (same as the federation block above).
+                        const ownNameParent = await getHolonName(holosphere, holon);
+
                         // Propagate to each parent hexagon
                         const parentPropagatePromises = parentHexagons.map(async (parentHexagon) => {
                             try {
@@ -858,7 +961,8 @@ export async function propagate(holosphere, holon, lens, data, options = {}) {
                                     propagatedAt: Date.now(),
                                     originalId: data.id,
                                     propagationType: 'parent', // Indicate this is parent propagation
-                                    parentLevel: holonResolution - h3.getResolution(parentHexagon) // How many levels up
+                                    parentLevel: holonResolution - h3.getResolution(parentHexagon), // How many levels up
+                                    ...(ownNameParent ? { originName: ownNameParent } : {})
                                 };
 
                                 if (useHolograms && !isAlreadyHologram) {

package/holosphere-bundle.esm.js

@@ -1,9 +1,9 @@
 /**
- * HoloSphere ESM Bundle v1.3.0-alpha3
+ * HoloSphere ESM Bundle v1.3.0-alpha4
  * ES6 Module version with all dependencies bundled
  * 
  * Usage:
- * import HoloSphere from 'https://unpkg.com/holosphere@1.3.0-alpha3/holosphere-bundle.esm.js';
+ * import HoloSphere from 'https://unpkg.com/holosphere@1.3.0-alpha4/holosphere-bundle.esm.js';
  * const hs = new HoloSphere('myapp');
  */
 var __create = Object.create;
@@ -24322,6 +24322,23 @@ async function resolveHologram(holoInstance, hologram, options = {}) {
 }
 
 // federation.js
+async function getHolonName(holosphere, space) {
+  if (!holosphere || !space) return null;
+  try {
+    const settings = await holosphere.get(space, "settings", space);
+    if (!settings) return null;
+    if (Array.isArray(settings)) {
+      const found = settings.find((s) => s && typeof s.name === "string" && s.name.trim() !== "");
+      return found ? found.name : null;
+    }
+    if (typeof settings.name === "string" && settings.name.trim() !== "") {
+      return settings.name;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
 async function federate(holosphere, spaceId1, spaceId2, password1 = null, password2 = null, bidirectional = true, lensConfig = {}) {
   if (!spaceId1 || !spaceId2) {
     throw new Error("federate: Missing required space IDs");
@@ -24424,7 +24441,14 @@ async function subscribeFederation(holosphere, spaceId, password = null, callbac
   }
   const subscriptions2 = [];
   let lastNotificationTime = {};
+  const partnerNames = /* @__PURE__ */ new Map();
   if (fedInfo.inbound && fedInfo.inbound.length > 0) {
+    await Promise.all(
+      fedInfo.inbound.map(async (space) => {
+        const name = await getHolonName(holosphere, space);
+        partnerNames.set(space, name);
+      })
+    );
     for (const federatedSpace of fedInfo.inbound) {
       for (const lens of lenses) {
         try {
@@ -24439,10 +24463,13 @@ async function subscribeFederation(holosphere, spaceId, password = null, callbac
                 }
                 lastNotificationTime[key] = now;
               }
-              if (!data.federation) {
-                data.federation = {
+              if (!data._federation) {
+                const partnerName = partnerNames.get(federatedSpace);
+                data._federation = {
                   origin: federatedSpace,
-                  timestamp: now
+                  sourceLens: lens,
+                  timestamp: now,
+                  ...partnerName ? { originName: partnerName } : {}
                 };
               }
               await callback(data, federatedSpace, lens);
@@ -24635,6 +24662,25 @@ async function getFederated(holosphere, holon, lens, options = {}) {
     const federatedSpaces = maxFederatedSpaces === -1 ? fedInfo.inbound : fedInfo.inbound.slice(0, maxFederatedSpaces);
     spacesToQuery = spacesToQuery.concat(federatedSpaces);
   }
+  const remoteSpaces = spacesToQuery.filter((s) => s !== holon);
+  const spaceNames = /* @__PURE__ */ new Map();
+  await Promise.all(
+    remoteSpaces.map(async (space) => {
+      const name = await getHolonName(holosphere, space);
+      spaceNames.set(space, name);
+    })
+  );
+  const tagWithSource = (item, space) => {
+    if (!item || space === holon) return item;
+    const originName = spaceNames.get(space);
+    const fed = {
+      ...item._federation || {},
+      origin: space,
+      sourceLens: lens
+    };
+    if (originName) fed.originName = originName;
+    return { ...item, _federation: fed };
+  };
   for (const currentSpace of spacesToQuery) {
     if (queryIds && Array.isArray(queryIds)) {
       console.log(`Fetching specific IDs from ${currentSpace}: ${queryIds.join(", ")}`);
@@ -24643,7 +24689,7 @@ async function getFederated(holosphere, holon, lens, options = {}) {
         fetchPromises.push(
           holosphere.get(currentSpace, lens, itemId).then((item) => {
             if (item) {
-              fetchedItems.set(itemId, item);
+              fetchedItems.set(itemId, tagWithSource(item, currentSpace));
             }
           }).catch((err) => console.warn(`Error fetching item ${itemId} from ${currentSpace}: ${err.message}`))
         );
@@ -24657,7 +24703,7 @@ async function getFederated(holosphere, holon, lens, options = {}) {
         holosphere.getAll(currentSpace, lens).then((items) => {
           for (const item of items) {
             if (item && item[idField] && !fetchedItems.has(item[idField])) {
-              fetchedItems.set(item[idField], item);
+              fetchedItems.set(item[idField], tagWithSource(item, currentSpace));
             }
           }
         }).catch((err) => console.warn(`Error fetching all items from ${currentSpace}: ${err.message}`))
@@ -24689,7 +24735,21 @@ async function getFederated(holosphere, holon, lens, options = {}) {
             );
             console.log(`Original data found via soul path:`, JSON.stringify(originalData));
             if (originalData) {
-              result[i] = attachHologramMeta(originalData, item.soul);
+              const withMeta = attachHologramMeta(originalData, item.soul);
+              if (withMeta._hologram?.sourceHolon) {
+                let sourceHolonName = spaceNames.get(withMeta._hologram.sourceHolon);
+                if (sourceHolonName === void 0) {
+                  sourceHolonName = await getHolonName(holosphere, withMeta._hologram.sourceHolon);
+                  spaceNames.set(withMeta._hologram.sourceHolon, sourceHolonName);
+                }
+                if (sourceHolonName) {
+                  withMeta._hologram = {
+                    ...withMeta._hologram,
+                    sourceHolonName
+                  };
+                }
+              }
+              result[i] = withMeta;
             } else {
               result[i] = {
                 id: item.id,
@@ -24813,6 +24873,7 @@ async function propagate(holosphere, holon, lens, data, options = {}) {
         });
         if (spaces.length > 0) {
           const isAlreadyHologram = holosphere.isHologram(data);
+          const ownName = await getHolonName(holosphere, holon);
           const propagatePromises = spaces.map(async (targetSpace) => {
             try {
               let payloadToPut;
@@ -24822,7 +24883,8 @@ async function propagate(holosphere, holon, lens, data, options = {}) {
                 sourceLens: lens,
                 // The lens from which this data is being propagated
                 propagatedAt: Date.now(),
-                originalId: data.id
+                originalId: data.id,
+                ...ownName ? { originName: ownName } : {}
               };
               if (useHolograms && !isAlreadyHologram) {
                 const newHologram = holosphere.createHologram(holon, lens, data);
@@ -24907,6 +24969,7 @@ async function propagate(holosphere, holon, lens, data, options = {}) {
           if (parentHexagons.length > 0) {
             result.parentPropagation.messages.push(`Found ${parentHexagons.length} parent hexagons to propagate to: ${parentHexagons.join(", ")}`);
             const isAlreadyHologram = holosphere.isHologram(data);
+            const ownNameParent = await getHolonName(holosphere, holon);
             const parentPropagatePromises = parentHexagons.map(async (parentHexagon) => {
               try {
                 let payloadToPut;
@@ -24919,8 +24982,9 @@ async function propagate(holosphere, holon, lens, data, options = {}) {
                   originalId: data.id,
                   propagationType: "parent",
                   // Indicate this is parent propagation
-                  parentLevel: holonResolution - getResolution(parentHexagon)
+                  parentLevel: holonResolution - getResolution(parentHexagon),
                   // How many levels up
+                  ...ownNameParent ? { originName: ownNameParent } : {}
                 };
                 if (useHolograms && !isAlreadyHologram) {
                   const newHologram = holosphere.createHologram(holon, lens, data);
@@ -25188,6 +25252,45 @@ function clearSchemaCache(holoInstance, lens = null) {
 }
 
 // content.js
+function sanitizeForStorage(value, path = "", seen = /* @__PURE__ */ new WeakSet(), warnings = []) {
+  if (value === null) return null;
+  const t = typeof value;
+  if (t === "number") {
+    if (!Number.isFinite(value)) {
+      warnings.push(`${path || "<root>"}: ${value} (non-finite number)`);
+      return void 0;
+    }
+    return value;
+  }
+  if (t === "string" || t === "boolean") return value;
+  if (t === "undefined" || t === "function" || t === "symbol" || t === "bigint") {
+    warnings.push(`${path || "<root>"}: ${t}`);
+    return void 0;
+  }
+  if (t === "object") {
+    if (seen.has(value)) {
+      warnings.push(`${path || "<root>"}: circular reference`);
+      return void 0;
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+      const out2 = [];
+      for (let i = 0; i < value.length; i++) {
+        const cleaned = sanitizeForStorage(value[i], `${path}[${i}]`, seen, warnings);
+        out2.push(cleaned === void 0 ? null : cleaned);
+      }
+      return out2;
+    }
+    const out = {};
+    for (const k of Object.keys(value)) {
+      const cleaned = sanitizeForStorage(value[k], path ? `${path}.${k}` : k, seen, warnings);
+      if (cleaned !== void 0) out[k] = cleaned;
+    }
+    return out;
+  }
+  warnings.push(`${path || "<root>"}: unsupported type ${t}`);
+  return void 0;
+}
 async function put(holoInstance, holon, lens, data, password = null, options = {}) {
   if (!data) {
     throw new Error("put: Missing required data parameter");
@@ -25285,13 +25388,16 @@ async function put(holoInstance, holon, lens, data, password = null, options = {
     }
     return new Promise((resolve, reject) => {
       try {
-        let dataToStore = { ...data };
-        if (dataToStore._meta !== void 0) {
-          delete dataToStore._meta;
-        }
-        if (dataToStore._hologram !== void 0) {
-          delete dataToStore._hologram;
+        const sanitizeWarnings = [];
+        let dataToStore = sanitizeForStorage(data, "", /* @__PURE__ */ new WeakSet(), sanitizeWarnings) || {};
+        if (sanitizeWarnings.length > 0) {
+          console.warn(
+            `holosphere.put: sanitized ${sanitizeWarnings.length} field(s) at ${targetHolon}/${targetLens}/${targetKey} (id=${data.id}):`,
+            sanitizeWarnings
+          );
         }
+        if (dataToStore._meta !== void 0) delete dataToStore._meta;
+        if (dataToStore._hologram !== void 0) delete dataToStore._hologram;
         const payload = JSON.stringify(dataToStore);
         const putCallback = async (ack) => {
           if (ack.err) {