holosphere 1.1.20 → 2.0.0-alpha1

package/src/federation/hologram.js

@@ -0,0 +1,1042 @@
+/**
+ * Federation and Hologram (reference) Management
+ */
+
+import { buildPath, write, read, update } from '../storage/nostr-wrapper.js';
+import { verifyCapability } from '../crypto/secp256k1.js';
+import { getCapabilityForAuthor } from './registry.js';
+
+const MAX_RESOLUTION_DEPTH = 10;
+
+/**
+ * Check if creating a hologram would result in a circular reference
+ * This follows the chain from the source to see if it eventually points back to the target
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} sourceHolon - Source holon ID (where original data lives)
+ * @param {string} targetHolon - Target holon ID (where hologram would be created)
+ * @param {string} lensName - Lens name
+ * @param {string} dataId - Data ID
+ * @returns {Promise<Object>} Result with { isCircular, chain }
+ */
+export async function wouldCreateCircularHologram(client, appname, sourceHolon, targetHolon, lensName, dataId) {
+  const visited = new Set();
+  const chain = [];
+
+  let currentHolon = sourceHolon;
+  let currentLens = lensName;
+  let currentDataId = dataId;
+  let currentAppname = appname;
+
+  // Follow the chain to see if we eventually reach targetHolon
+  while (visited.size < MAX_RESOLUTION_DEPTH) {
+    const key = `${currentAppname}:${currentHolon}:${currentLens}:${currentDataId}`;
+
+    if (visited.has(key)) {
+      // Already visited this node - there's a cycle in the existing chain
+      return { isCircular: true, chain, reason: 'existing_cycle' };
+    }
+
+    visited.add(key);
+    chain.push({ holon: currentHolon, lens: currentLens, dataId: currentDataId });
+
+    // Check if current holon is our target - this would create a circular reference
+    if (currentHolon === targetHolon) {
+      return { isCircular: true, chain, reason: 'would_create_cycle' };
+    }
+
+    // Read the data at current location
+    const path = buildPath(currentAppname, currentHolon, currentLens, currentDataId);
+    const data = await read(client, path);
+
+    if (!data) {
+      // Data doesn't exist - no circular reference possible from this chain
+      return { isCircular: false, chain };
+    }
+
+    if (!data.hologram || !data.target) {
+      // Not a hologram - chain ends here, no circular reference
+      return { isCircular: false, chain };
+    }
+
+    // Follow the hologram to its target
+    currentAppname = data.target.appname || currentAppname;
+    currentHolon = data.target.holonId;
+    currentLens = data.target.lensName || currentLens;
+    currentDataId = data.target.dataId || currentDataId;
+  }
+
+  // Max depth reached - treat as potential circular to be safe
+  return { isCircular: true, chain, reason: 'max_depth_exceeded' };
+}
+
+/**
+ * Create a hologram (lightweight reference)
+ * @param {string} sourceHolon - Source holon ID
+ * @param {string} targetHolon - Target holon ID
+ * @param {string} lensName - Lens name
+ * @param {string} dataId - Data ID
+ * @param {string} appname - Application namespace
+ * @param {Object} options - Optional cross-holosphere settings
+ * @param {string} options.authorPubKey - Source author's public key (for cross-holosphere)
+ * @param {string} options.capability - Capability token (for cross-holosphere)
+ * @returns {Object} Hologram object
+ */
+export function createHologram(sourceHolon, targetHolon, lensName, dataId, appname, options = {}) {
+  const { authorPubKey = null, capability = null } = options;
+
+  const soul = buildPath(appname, sourceHolon, lensName, dataId);
+
+  const hologram = {
+    id: dataId,
+    hologram: true,
+    soul,
+    target: {
+      appname,
+      holonId: sourceHolon,
+      lensName,
+      dataId,
+    },
+    _meta: {
+      created: Date.now(),
+      sourceHolon,
+      source: sourceHolon,  // Alias for compatibility
+    },
+  };
+
+  // Cross-holosphere enhancements
+  if (authorPubKey) {
+    hologram.crossHolosphere = true;
+    hologram.target.authorPubKey = authorPubKey;
+    hologram._meta.sourcePubKey = authorPubKey;
+  }
+
+  if (capability) {
+    hologram.capability = capability;
+    hologram._meta.grantedAt = Date.now();
+  }
+
+  return hologram;
+}
+
+/**
+ * Resolve hologram to actual data, merging local overrides
+ * Supports cross-holosphere holograms with capability token verification
+ * @param {Object} client - Nostr client instance
+ * @param {Object} hologram - Hologram object
+ * @param {Set} visited - Visited souls (circular reference detection)
+ * @param {Array} chain - Chain of souls for debugging circular references
+ * @param {Object} options - Resolution options
+ * @param {string} options.appname - Application namespace (for registry lookup)
+ * @param {boolean} options.deleteCircular - If true, delete circular holograms when detected (default: true)
+ * @param {string} options.hologramPath - Path of the hologram being resolved (for deletion)
+ * @returns {Promise<Object|null>} Resolved data with _hologram metadata, or null
+ */
+export async function resolveHologram(client, hologram, visited = new Set(), chain = [], options = {}) {
+  const { deleteCircular = true, hologramPath = null } = options;
+
+  if (!hologram || !hologram.hologram) {
+    return hologram; // Not a hologram, return as-is
+  }
+
+  const { soul } = hologram;
+  const target = hologram.target || {};
+
+  // Circular reference detection
+  if (visited.has(soul)) {
+    const chainStr = [...chain, soul].join(' → ');
+    console.warn(`🔄 Circular reference detected - removing hologram`);
+    console.warn(`   Soul: ${soul}`);
+    console.warn(`   Chain: ${chainStr}`);
+    console.warn(`   Source holon: ${target.holonId || 'unknown'}`);
+    console.warn(`   Lens: ${target.lensName || 'unknown'}`);
+    console.warn(`   Data ID: ${target.dataId || hologram.id || 'unknown'}`);
+    console.warn(`   Resolution depth: ${visited.size}`);
+
+    // Delete the circular hologram
+    if (deleteCircular && hologramPath) {
+      console.info(`   🗑️ Deleting circular hologram at: ${hologramPath}`);
+      await write(client, hologramPath, null);
+    }
+
+    return null;
+  }
+
+  if (visited.size >= MAX_RESOLUTION_DEPTH) {
+    const chainStr = [...chain, soul].join(' → ');
+    console.warn(`⚠️ Max resolution depth (${MAX_RESOLUTION_DEPTH}) exceeded - removing hologram`);
+    console.warn(`   Current soul: ${soul}`);
+    console.warn(`   Chain: ${chainStr}`);
+    console.warn(`   Source holon: ${target.holonId || 'unknown'}`);
+    console.warn(`   Lens: ${target.lensName || 'unknown'}`);
+
+    // Delete the problematic hologram
+    if (deleteCircular && hologramPath) {
+      console.info(`   🗑️ Deleting deep chain hologram at: ${hologramPath}`);
+      await write(client, hologramPath, null);
+    }
+
+    return null;
+  }
+
+  visited.add(soul);
+  chain.push(soul);
+
+  let sourceData;
+
+  // Handle cross-holosphere holograms
+  if (hologram.crossHolosphere && target.authorPubKey) {
+    // Get capability - try embedded first, then registry fallback
+    let capability = hologram.capability;
+
+    if (!capability && options.appname) {
+      // Fallback to registry lookup
+      const capEntry = await getCapabilityForAuthor(
+        client,
+        options.appname,
+        target.authorPubKey,
+        {
+          holonId: target.holonId,
+          lensName: target.lensName,
+          dataId: target.dataId,
+        }
+      );
+      if (capEntry) {
+        capability = capEntry.token;
+      }
+    }
+
+    // Verify capability before resolving
+    if (!capability) {
+      console.warn(`❌ Cross-holosphere hologram missing capability: ${soul}`);
+      return null;
+    }
+
+    const isValid = await verifyCapability(
+      capability,
+      'read',
+      {
+        holonId: target.holonId,
+        lensName: target.lensName,
+        dataId: target.dataId,
+      }
+    );
+
+    if (!isValid) {
+      console.warn(`❌ Capability verification failed for cross-holosphere hologram: ${soul}`);
+      return null;
+    }
+
+    // Read from federated source (different author)
+    sourceData = await read(client, soul, {
+      authors: [target.authorPubKey]
+    });
+  } else {
+    // Same-holosphere resolution (original behavior)
+    sourceData = await read(client, soul);
+  }
+
+  if (!sourceData) {
+    return null;
+  }
+
+  // If source data is also a hologram, recursively resolve
+  if (sourceData.hologram) {
+    // Pass the soul as the hologramPath so circular holograms can be deleted
+    return resolveHologram(client, sourceData, visited, chain, { ...options, hologramPath: soul });
+  }
+
+  // Merge hologram with source data
+  return mergeHologramWithSource(hologram, sourceData);
+}
+
+/**
+ * Merge hologram local overrides with source data
+ * @private
+ * @param {Object} hologram - Hologram object
+ * @param {Object} sourceData - Source data
+ * @returns {Object} Merged data with _hologram metadata
+ */
+function mergeHologramWithSource(hologram, sourceData) {
+  // Extract local overrides from the hologram (exclude hologram-specific fields)
+  const hologramOnlyFields = ['hologram', 'soul', 'target', '_meta', 'id', 'capability', 'crossHolosphere'];
+  const localOverrides = {};
+  const localOverrideKeys = [];
+
+  for (const key of Object.keys(hologram)) {
+    if (!hologramOnlyFields.includes(key)) {
+      localOverrides[key] = hologram[key];
+      localOverrideKeys.push(key);
+    }
+  }
+
+  // Merge: source data + local overrides + hologram metadata
+  const sourceHolon = hologram._meta?.sourceHolon || hologram._meta?.source || hologram.target?.holonId;
+  const resolved = {
+    ...sourceData,           // Original data from source
+    ...localOverrides,       // Local overrides (x, y, pinned, etc.)
+    _hologram: {
+      isHologram: true,
+      soul: hologram.soul,
+      sourceHolon: sourceHolon,
+      localOverrides: localOverrideKeys,
+      crossHolosphere: hologram.crossHolosphere || false,
+      sourcePubKey: hologram._meta?.sourcePubKey || null,
+    }
+  };
+
+  // Preserve original _meta and add source from hologram
+  if (sourceData._meta) {
+    resolved._meta = { ...sourceData._meta, source: sourceHolon };
+  } else {
+    resolved._meta = { source: sourceHolon };
+  }
+
+  return resolved;
+}
+
+/**
+ * Setup federation between holons
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} sourceHolon - Source holon ID
+ * @param {string} targetHolon - Target holon ID
+ * @param {string} lensName - Lens name
+ * @param {Object} options - Federation options
+ * @param {string} options.direction - 'inbound' or 'outbound'
+ * @param {string} options.mode - 'reference' or 'copy'
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function setupFederation(
+  client,
+  appname,
+  sourceHolon,
+  targetHolon,
+  lensName,
+  options = {}
+) {
+  const { direction = 'outbound', mode = 'reference' } = options;
+
+  const federationConfig = {
+    sourceHolon,
+    targetHolon,
+    lensName,
+    direction,
+    mode,
+    created: Date.now(),
+  };
+
+  // Store federation config
+  const configPath = buildPath(appname, sourceHolon, lensName, '_federation');
+  return write(client, configPath, federationConfig);
+}
+
+/**
+ * Propagate data to federated location
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {Object} data - Data to propagate
+ * @param {string} sourceHolon - Source holon ID
+ * @param {string} targetHolon - Target holon ID
+ * @param {string} lensName - Lens name
+ * @param {string} mode - 'reference' or 'copy'
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function propagateData(
+  client,
+  appname,
+  data,
+  sourceHolon,
+  targetHolon,
+  lensName,
+  mode = 'reference'
+) {
+  const dataId = data.id;
+
+  // Don't create hologram to the same holon - it would point to itself
+  if (sourceHolon === targetHolon) {
+    console.info(`⏭️ Skipping propagation - source and target are the same holon: ${sourceHolon}`);
+    return true;
+  }
+
+  // Don't propagate holograms back to avoid circular references
+  // If this data is already a hologram pointing to the target, skip it
+  if (data.hologram === true) {
+    // Check if this hologram would create a circular reference
+    if (data.target && data.target.holonId === targetHolon) {
+      console.info(`🔄 Skipping propagation - would create circular reference:`);
+      console.info(`   Data ID: ${dataId}`);
+      console.info(`   Source holon: ${sourceHolon}`);
+      console.info(`   Target holon: ${targetHolon}`);
+      console.info(`   Hologram points to: ${data.target.holonId}`);
+      console.info(`   Lens: ${lensName}`);
+      console.info(`   Original soul: ${data.soul || 'unknown'}`);
+      return true;
+    }
+
+    // Check if targetHolon is already in the original source's activeHolograms
+    // This prevents creating duplicate holograms when the target already has one
+    if (data.target) {
+      const originalSourcePath = buildPath(
+        data.target.appname || appname,
+        data.target.holonId,
+        data.target.lensName || lensName,
+        data.target.dataId || dataId
+      );
+      const originalSource = await read(client, originalSourcePath);
+
+      if (originalSource?._meta?.activeHolograms) {
+        const alreadyHasHologram = originalSource._meta.activeHolograms.some(
+          h => h.targetHolon === targetHolon
+        );
+        if (alreadyHasHologram) {
+          console.info(`⏭️ Skipping propagation - target already in activeHolograms:`);
+          console.info(`   Data ID: ${dataId}`);
+          console.info(`   Original source: ${data.target.holonId}`);
+          console.info(`   Target holon: ${targetHolon}`);
+          return true;
+        }
+      }
+    }
+
+    // Deep circular check for hologram copy - ensure the original source doesn't eventually point to target
+    const originalSourceHolon = data.target.holonId;
+    const originalDataId = data.target.dataId || dataId;
+    const originalLens = data.target.lensName || lensName;
+    const originalAppname = data.target.appname || appname;
+
+    const circularCheck = await wouldCreateCircularHologram(
+      client, originalAppname, originalSourceHolon, targetHolon, originalLens, originalDataId
+    );
+
+    if (circularCheck.isCircular) {
+      const chainStr = circularCheck.chain.map(c => c.holon).join(' → ');
+      console.warn(`🔄 Preventing circular hologram copy:`);
+      console.warn(`   Data ID: ${dataId}`);
+      console.warn(`   Original source: ${originalSourceHolon}`);
+      console.warn(`   Would copy to: ${targetHolon}`);
+      console.warn(`   Existing chain: ${chainStr}`);
+      console.warn(`   Reason: ${circularCheck.reason}`);
+      return false;
+    }
+
+    // When propagating a hologram, copy it instead of creating a hologram of a hologram
+    // This maintains the reference to the original source
+    const targetPath = buildPath(appname, targetHolon, lensName, dataId);
+    const copiedHologram = {
+      ...data,
+      _meta: {
+        ...data._meta,
+        copiedFrom: sourceHolon,
+        copiedAt: Date.now()
+      }
+    };
+    const success = await write(client, targetPath, copiedHologram);
+
+    // Add this new location to the original source's activeHolograms
+    if (success && data.target) {
+      await addActiveHologram(
+        client,
+        data.target.appname || appname,
+        data.target.holonId,
+        data.target.lensName || lensName,
+        data.target.dataId || dataId,
+        targetHolon
+      );
+      console.info(`📋 Copied hologram to ${targetHolon}:`);
+      console.info(`   Data ID: ${dataId}`);
+      console.info(`   Original source: ${data.target.holonId}`);
+      console.info(`   Copied from: ${sourceHolon}`);
+    }
+
+    return success;
+  }
+
+  // For non-hologram data, check if targetHolon is already in activeHolograms
+  if (mode === 'reference' && data._meta?.activeHolograms) {
+    const alreadyHasHologram = data._meta.activeHolograms.some(
+      h => h.targetHolon === targetHolon
+    );
+    if (alreadyHasHologram) {
+      console.info(`⏭️ Skipping propagation - target already in activeHolograms:`);
+      console.info(`   Data ID: ${dataId}`);
+      console.info(`   Source holon: ${sourceHolon}`);
+      console.info(`   Target holon: ${targetHolon}`);
+      return true;
+    }
+  }
+
+  if (mode === 'reference') {
+    // Deep circular reference check - follow the chain from source to see if it would loop back
+    const circularCheck = await wouldCreateCircularHologram(
+      client, appname, sourceHolon, targetHolon, lensName, dataId
+    );
+
+    if (circularCheck.isCircular) {
+      const chainStr = circularCheck.chain.map(c => c.holon).join(' → ');
+      console.warn(`🔄 Preventing circular hologram creation:`);
+      console.warn(`   Data ID: ${dataId}`);
+      console.warn(`   Would create: ${sourceHolon} → ${targetHolon}`);
+      console.warn(`   Existing chain: ${chainStr}`);
+      console.warn(`   Reason: ${circularCheck.reason}`);
+      return false;
+    }
+
+    // Create hologram in target
+    const hologram = createHologram(sourceHolon, targetHolon, lensName, dataId, appname);
+    const targetPath = buildPath(appname, targetHolon, lensName, dataId);
+    const success = await write(client, targetPath, hologram);
+
+    // Add hologram to source data's _meta.activeHolograms for tracking
+    if (success) {
+      await addActiveHologram(client, appname, sourceHolon, lensName, dataId, targetHolon);
+    }
+
+    return success;
+  } else {
+    // Copy data to target
+    const targetPath = buildPath(appname, targetHolon, lensName, dataId);
+    return write(client, targetPath, { ...data, _meta: { ...data._meta, source: sourceHolon } });
+  }
+}
+
+/**
+ * Update local overrides on an existing hologram
+ * This allows storing holon-specific data (position, pinned status, etc.) on a hologram
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} holonId - Holon where the hologram lives
+ * @param {string} lensName - Lens name
+ * @param {string} dataId - Data ID
+ * @param {Object} overrides - Local override fields to set (e.g., { x: 100, y: 200, pinned: true })
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function updateHologramOverrides(client, appname, holonId, lensName, dataId, overrides) {
+  const path = buildPath(appname, holonId, lensName, dataId);
+
+  // Read existing hologram
+  const existing = await read(client, path);
+
+  if (!existing) {
+    console.warn(`Hologram not found at ${path}`);
+    return false;
+  }
+
+  // Only update if it's actually a hologram
+  if (!existing.hologram) {
+    console.warn(`Data at ${path} is not a hologram, cannot update overrides`);
+    return false;
+  }
+
+  // Merge overrides into hologram (but don't allow overriding hologram-specific fields)
+  const protectedFields = ['hologram', 'soul', 'target', '_meta', 'id'];
+  const safeOverrides = {};
+
+  for (const [key, value] of Object.entries(overrides)) {
+    if (!protectedFields.includes(key)) {
+      safeOverrides[key] = value;
+    }
+  }
+
+  const updated = {
+    ...existing,
+    ...safeOverrides
+  };
+
+  return write(client, path, updated);
+}
+
+/**
+ * Check if data is a hologram (unresolved reference)
+ * @param {Object} data - Data to check
+ * @returns {boolean} True if data is an unresolved hologram
+ */
+export function isHologram(data) {
+  return data && data.hologram === true;
+}
+
+/**
+ * Check if data was resolved from a hologram
+ * @param {Object} data - Data to check
+ * @returns {boolean} True if data was resolved from a hologram
+ */
+export function isResolvedHologram(data) {
+  return data && data._hologram && data._hologram.isHologram === true;
+}
+
+/**
+ * Get hologram source information from resolved data
+ * @param {Object} data - Resolved data
+ * @returns {Object|null} Source info { soul, sourceHolon, localOverrides } or null
+ */
+export function getHologramSource(data) {
+  if (!isResolvedHologram(data)) {
+    return null;
+  }
+  return {
+    soul: data._hologram.soul,
+    sourceHolon: data._hologram.sourceHolon,
+    localOverrides: data._hologram.localOverrides || []
+  };
+}
+
+/**
+ * Add a hologram reference to the source data's _meta.activeHolograms
+ * This tracks all holograms pointing to this specific data item
+ * If the source is itself a hologram, follows the chain to find the real source
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} sourceHolon - Source holon ID (where original data lives)
+ * @param {string} lensName - Lens name
+ * @param {string} dataId - Data ID
+ * @param {string} targetHolon - Target holon ID (where hologram lives)
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function addActiveHologram(client, appname, sourceHolon, lensName, dataId, targetHolon) {
+  let currentAppname = appname;
+  let currentHolon = sourceHolon;
+  let currentLens = lensName;
+  let currentDataId = dataId;
+  let sourcePath = buildPath(currentAppname, currentHolon, currentLens, currentDataId);
+
+  // Read existing source data
+  let sourceData = await read(client, sourcePath);
+  if (!sourceData) {
+    console.warn(`Source data not found at ${sourcePath}`);
+    return false;
+  }
+
+  // If source is a hologram, follow the chain to find the real source
+  // This ensures activeHolograms is always tracked on the actual data, not on holograms
+  let depth = 0;
+  const maxDepth = 10;
+  while (sourceData.hologram === true && sourceData.target && depth < maxDepth) {
+    depth++;
+    currentAppname = sourceData.target.appname || currentAppname;
+    currentHolon = sourceData.target.holonId;
+    currentLens = sourceData.target.lensName || currentLens;
+    currentDataId = sourceData.target.dataId || currentDataId;
+    sourcePath = buildPath(currentAppname, currentHolon, currentLens, currentDataId);
+
+    sourceData = await read(client, sourcePath);
+    if (!sourceData) {
+      console.warn(`Real source data not found at ${sourcePath}`);
+      return false;
+    }
+  }
+
+  if (depth > 0) {
+    console.info(`📍 Followed hologram chain (depth: ${depth}) to real source: ${currentHolon}/${currentLens}/${currentDataId}`);
+  }
+
+  // Initialize _meta and activeHolograms if needed
+  if (!sourceData._meta) {
+    sourceData._meta = {};
+  }
+  if (!Array.isArray(sourceData._meta.activeHolograms)) {
+    sourceData._meta.activeHolograms = [];
+  }
+
+  const now = Date.now();
+
+  // Check if this hologram already exists
+  const existingIndex = sourceData._meta.activeHolograms.findIndex(
+    h => h.targetHolon === targetHolon
+  );
+
+  if (existingIndex >= 0) {
+    // Update existing entry
+    sourceData._meta.activeHolograms[existingIndex].lastUpdated = now;
+  } else {
+    // Add new entry
+    sourceData._meta.activeHolograms.push({
+      targetHolon,
+      created: now,
+      lastUpdated: now
+    });
+  }
+
+  // Write to the real source path (not the original one if we followed a chain)
+  return write(client, sourcePath, sourceData);
+}
+
+/**
+ * Remove a hologram reference from the source data's _meta.activeHolograms
+ * If the source is itself a hologram, follows the chain to find the real source
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} sourceHolon - Source holon ID
+ * @param {string} lensName - Lens name
+ * @param {string} dataId - Data ID
+ * @param {string} targetHolon - Target holon ID
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function removeActiveHologram(client, appname, sourceHolon, lensName, dataId, targetHolon) {
+  let currentAppname = appname;
+  let currentHolon = sourceHolon;
+  let currentLens = lensName;
+  let currentDataId = dataId;
+  let sourcePath = buildPath(currentAppname, currentHolon, currentLens, currentDataId);
+
+  // Read existing source data
+  let sourceData = await read(client, sourcePath);
+  if (!sourceData) {
+    return false;
+  }
+
+  // If source is a hologram, follow the chain to find the real source
+  let depth = 0;
+  const maxDepth = 10;
+  while (sourceData.hologram === true && sourceData.target && depth < maxDepth) {
+    depth++;
+    currentAppname = sourceData.target.appname || currentAppname;
+    currentHolon = sourceData.target.holonId;
+    currentLens = sourceData.target.lensName || currentLens;
+    currentDataId = sourceData.target.dataId || currentDataId;
+    sourcePath = buildPath(currentAppname, currentHolon, currentLens, currentDataId);
+
+    sourceData = await read(client, sourcePath);
+    if (!sourceData) {
+      return false;
+    }
+  }
+
+  if (!sourceData._meta || !Array.isArray(sourceData._meta.activeHolograms)) {
+    return false;
+  }
+
+  const initialLength = sourceData._meta.activeHolograms.length;
+  sourceData._meta.activeHolograms = sourceData._meta.activeHolograms.filter(
+    h => h.targetHolon !== targetHolon
+  );
+
+  // Only write if something changed
+  if (sourceData._meta.activeHolograms.length < initialLength) {
+    return write(client, sourcePath, sourceData);
+  }
+
+  return false;
+}
+
+/**
+ * Refresh lastUpdated timestamps on all activeHolograms in source data
+ * Also updates the hologram objects in target holons
+ * Called when source data is updated
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} sourceHolon - Source holon ID
+ * @param {string} lensName - Lens name
+ * @param {string} dataId - Data ID that was updated
+ * @param {Object} sourceData - The source data object (already read, to avoid re-reading)
+ * @returns {Promise<Object>} Result with refreshed count
+ */
+export async function refreshActiveHolograms(client, appname, sourceHolon, lensName, dataId, sourceData = null) {
+  // Read source data if not provided
+  if (!sourceData) {
+    const sourcePath = buildPath(appname, sourceHolon, lensName, dataId);
+    sourceData = await read(client, sourcePath);
+  }
+
+  if (!sourceData || !sourceData._meta || !Array.isArray(sourceData._meta.activeHolograms)) {
+    return { refreshed: 0, holograms: [] };
+  }
+
+  const now = Date.now();
+  const refreshed = [];
+
+  // Update timestamps on all activeHolograms
+  for (const hologramEntry of sourceData._meta.activeHolograms) {
+    hologramEntry.lastUpdated = now;
+
+    // Also update the hologram itself in the target holon
+    const hologramPath = buildPath(appname, hologramEntry.targetHolon, lensName, dataId);
+    const hologram = await read(client, hologramPath);
+
+    if (hologram && hologram.hologram === true) {
+      // Update hologram's _meta.lastUpdated
+      if (!hologram._meta) hologram._meta = {};
+      hologram._meta.lastUpdated = now;
+      await write(client, hologramPath, hologram);
+      refreshed.push({
+        targetHolon: hologramEntry.targetHolon,
+        dataId,
+        timestamp: now
+      });
+    }
+  }
+
+  // Source data's activeHolograms timestamps are updated in-place
+  // The caller should save sourceData if needed
+
+  return { refreshed: refreshed.length, holograms: refreshed, sourceData };
+}
+
+/**
+ * Delete a hologram and clean up the activeHolograms list on the original source
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} holonId - Holon where the hologram lives (to be deleted from)
+ * @param {string} lensName - Lens name
+ * @param {string} dataId - Data ID of the hologram
+ * @param {Object} options - Optional settings
+ * @param {boolean} options.deleteData - If true, actually delete the data (default: true)
+ * @returns {Promise<Object>} Result with deletion info
+ */
+export async function deleteHologram(client, appname, holonId, lensName, dataId, options = {}) {
+  const { deleteData = true } = options;
+  const path = buildPath(appname, holonId, lensName, dataId);
+  const result = {
+    success: false,
+    wasHologram: false,
+    sourceHolon: null,
+    activeHologramsUpdated: false,
+    error: null
+  };
+
+  try {
+    // Read the hologram to get source information
+    const hologram = await read(client, path);
+
+    if (!hologram) {
+      console.warn(`🗑️ Hologram not found at ${path}`);
+      result.error = 'Hologram not found';
+      return result;
+    }
+
+    // Check if it's actually a hologram
+    if (hologram.hologram === true && hologram.target) {
+      result.wasHologram = true;
+      result.sourceHolon = hologram.target.holonId;
+
+      console.info(`🗑️ Deleting hologram:`);
+      console.info(`   Path: ${path}`);
+      console.info(`   Data ID: ${dataId}`);
+      console.info(`   From holon: ${holonId}`);
+      console.info(`   Source holon: ${hologram.target.holonId}`);
+      console.info(`   Lens: ${lensName}`);
+
+      // Remove from source's activeHolograms list
+      const removed = await removeActiveHologram(
+        client,
+        hologram.target.appname || appname,
+        hologram.target.holonId,
+        hologram.target.lensName || lensName,
+        hologram.target.dataId || dataId,
+        holonId
+      );
+
+      result.activeHologramsUpdated = removed;
+
+      if (removed) {
+        console.info(`   ✓ Removed from activeHolograms on source`);
+      } else {
+        console.warn(`   ⚠️ Could not update activeHolograms on source (may already be removed)`);
+      }
+    } else {
+      console.info(`🗑️ Deleting non-hologram data at ${path}`);
+    }
+
+    // Delete the hologram data if requested
+    if (deleteData) {
+      // Write null to delete (or use a delete function if available)
+      const deleted = await write(client, path, null);
+      result.success = deleted;
+
+      if (deleted) {
+        console.info(`   ✓ Hologram deleted successfully`);
+      } else {
+        console.warn(`   ⚠️ Failed to delete hologram data`);
+        result.error = 'Failed to delete hologram data';
+      }
+    } else {
+      result.success = true;
+    }
+
+    return result;
+  } catch (error) {
+    console.error(`❌ Error deleting hologram at ${path}:`, error);
+    result.error = error.message || 'Unknown error';
+    return result;
+  }
+}
+
+/**
+ * Cleanup circular holograms in a holon's lens
+ * This detects and removes holograms that create circular references (A→B→A)
+ * Useful for cleaning up existing bad data created before circular reference prevention was added
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} holonId - Holon to clean up
+ * @param {string} lensName - Lens name to check
+ * @param {Object} options - Optional settings
+ * @param {boolean} options.dryRun - If true, only report what would be deleted (default: false)
+ * @returns {Promise<Object>} Result with cleanup info
+ */
+export async function cleanupCircularHolograms(client, appname, holonId, lensName, options = {}) {
+  const { dryRun = false } = options;
+  const result = {
+    scanned: 0,
+    circularFound: 0,
+    deleted: 0,
+    errors: [],
+    details: []
+  };
+
+  console.info(`🧹 ${dryRun ? '[DRY RUN] ' : ''}Cleaning up circular holograms in ${holonId}/${lensName}...`);
+
+  try {
+    // Get all data in this lens
+    const basePath = buildPath(appname, holonId, lensName);
+    // We need to iterate through all items - this requires listing capability
+    // For now, we'll rely on the caller to provide a list of IDs to check
+    // or we can use a different approach
+
+    // Alternative: Read the lens index if it exists
+    const lensIndexPath = buildPath(appname, holonId, lensName, '_index');
+    const lensIndex = await read(client, lensIndexPath);
+
+    if (!lensIndex || !Array.isArray(lensIndex.items)) {
+      console.warn(`   No index found for ${holonId}/${lensName}, cannot scan for circular references`);
+      console.info(`   Tip: Provide specific IDs to check using cleanupCircularHologramsByIds()`);
+      return result;
+    }
+
+    for (const itemId of lensIndex.items) {
+      result.scanned++;
+      const itemPath = buildPath(appname, holonId, lensName, itemId);
+      const item = await read(client, itemPath);
+
+      if (!item || item.hologram !== true || !item.target) {
+        continue; // Not a hologram, skip
+      }
+
+      // This is a hologram - check if it creates a circular reference
+      const sourceHolon = item.target.holonId;
+      const sourceDataId = item.target.dataId || itemId;
+      const sourceLens = item.target.lensName || lensName;
+
+      // Read the source data
+      const sourcePath = buildPath(item.target.appname || appname, sourceHolon, sourceLens, sourceDataId);
+      const sourceData = await read(client, sourcePath);
+
+      if (sourceData && sourceData.hologram === true && sourceData.target) {
+        // Source is also a hologram - check if it points back
+        if (sourceData.target.holonId === holonId) {
+          result.circularFound++;
+          const detail = {
+            itemId,
+            path: itemPath,
+            pointsTo: `${sourceHolon}/${sourceLens}/${sourceDataId}`,
+            circularWith: `${sourceData.target.holonId}/${sourceData.target.lensName}/${sourceData.target.dataId}`
+          };
+          result.details.push(detail);
+
+          console.warn(`   🔄 Found circular hologram:`);
+          console.warn(`      ${holonId}/${lensName}/${itemId} → ${sourceHolon}/${sourceLens}/${sourceDataId} → ${holonId}`);
+
+          if (!dryRun) {
+            // Delete this hologram
+            const deleteResult = await deleteHologram(client, appname, holonId, lensName, itemId);
+            if (deleteResult.success) {
+              result.deleted++;
+              console.info(`      ✓ Deleted circular hologram`);
+            } else {
+              result.errors.push({ itemId, error: deleteResult.error });
+              console.error(`      ❌ Failed to delete: ${deleteResult.error}`);
+            }
+          }
+        }
+      }
+    }
+
+    console.info(`🧹 Cleanup complete for ${holonId}/${lensName}:`);
+    console.info(`   Scanned: ${result.scanned}`);
+    console.info(`   Circular found: ${result.circularFound}`);
+    console.info(`   Deleted: ${result.deleted}`);
+    if (result.errors.length > 0) {
+      console.warn(`   Errors: ${result.errors.length}`);
+    }
+
+    return result;
+  } catch (error) {
+    console.error(`❌ Error during cleanup:`, error);
+    result.errors.push({ error: error.message });
+    return result;
+  }
+}
+
+/**
+ * Cleanup circular holograms for a specific list of IDs
+ * Use this when you don't have an index but know which IDs to check
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} holonId - Holon to clean up
+ * @param {string} lensName - Lens name
+ * @param {string[]} dataIds - Array of data IDs to check
+ * @param {Object} options - Optional settings
+ * @param {boolean} options.dryRun - If true, only report what would be deleted
+ * @returns {Promise<Object>} Result with cleanup info
+ */
+export async function cleanupCircularHologramsByIds(client, appname, holonId, lensName, dataIds, options = {}) {
+  const { dryRun = false } = options;
+  const result = {
+    scanned: 0,
+    circularFound: 0,
+    deleted: 0,
+    errors: [],
+    details: []
+  };
+
+  console.info(`🧹 ${dryRun ? '[DRY RUN] ' : ''}Cleaning up circular holograms for ${dataIds.length} IDs in ${holonId}/${lensName}...`);
+
+  for (const itemId of dataIds) {
+    result.scanned++;
+    const itemPath = buildPath(appname, holonId, lensName, itemId);
+    const item = await read(client, itemPath);
+
+    if (!item || item.hologram !== true || !item.target) {
+      continue; // Not a hologram, skip
+    }
+
+    // This is a hologram - check if it creates a circular reference
+    const sourceHolon = item.target.holonId;
+    const sourceDataId = item.target.dataId || itemId;
+    const sourceLens = item.target.lensName || lensName;
+
+    // Read the source data
+    const sourcePath = buildPath(item.target.appname || appname, sourceHolon, sourceLens, sourceDataId);
+    const sourceData = await read(client, sourcePath);
+
+    if (sourceData && sourceData.hologram === true && sourceData.target) {
+      // Source is also a hologram - check if it points back
+      if (sourceData.target.holonId === holonId) {
+        result.circularFound++;
+        const detail = {
+          itemId,
+          path: itemPath,
+          pointsTo: `${sourceHolon}/${sourceLens}/${sourceDataId}`,
+          circularWith: `${sourceData.target.holonId}/${sourceData.target.lensName}/${sourceData.target.dataId}`
+        };
+        result.details.push(detail);
+
+        console.warn(`   🔄 Found circular hologram: ${itemId}`);
+        console.warn(`      Chain: ${holonId} → ${sourceHolon} → ${holonId}`);
+
+        if (!dryRun) {
+          // Delete this hologram
+          const deleteResult = await deleteHologram(client, appname, holonId, lensName, itemId);
+          if (deleteResult.success) {
+            result.deleted++;
+            console.info(`      ✓ Deleted`);
+          } else {
+            result.errors.push({ itemId, error: deleteResult.error });
+            console.error(`      ❌ Failed: ${deleteResult.error}`);
+          }
+        }
+      }
+    }
+  }
+
+  console.info(`🧹 Cleanup complete: scanned=${result.scanned}, circular=${result.circularFound}, deleted=${result.deleted}`);
+  return result;
+}