holosphere 2.0.0-alpha20 → 2.0.0-alpha22

package/src/federation/hologram.js

@@ -1,23 +1,31 @@
 /**
- * @fileoverview Unified Federation and Hologram (Reference) Management.
+ * @fileoverview Hologram — the core federation infrastructure.
  *
- * Provides hologram (lightweight reference) creation, resolution, and management.
- * Holograms enable data to appear in multiple holons while maintaining a single
- * source of truth.
+ * A hologram is a lightweight reference (pointer) from one holon to data
+ * in another holon. It enables data to appear in multiple holons while
+ * maintaining a single source of truth.
  *
- * UNIFIED MODEL: All federation is capability-based. Every hologram includes:
- * - authorPubKey: The public key of the data owner (can be self)
- * - capability: A capability token (self-issued for same-author federation)
+ * SIMPLIFIED MODEL (v2):
+ * - authorPubKey: identifies WHO wrote the source data
+ * - No capability tokens — federation membership (pubkey list) controls visibility
+ * - Anyone can write anywhere (Nostr is open-write); reads are filtered by federation
  *
- * This unifies "in-federation" (same author) and "cross-federation" (different authors)
- * into a single consistent model.
+ * The hologram is the core infrastructure of federation:
+ * 1. It points to source data (soul / target)
+ * 2. It knows the author (authorPubKey)
+ * 3. It resolves to the actual data on read
+ * 4. It supports local overrides (x, y, pinned, etc.)
  *
  * @module federation/hologram
  */
 
-import { buildPath, write, read, update } from '../storage/unified-storage.js';
-import { verifyCapability, issueCapability, verifyCapabilityIssuer, decodeCapability } from '../crypto/secp256k1.js';
-import { getCapabilityForAuthor, storeInboundCapability } from './registry.js';
+import { buildPath, write, read, update } from '../storage/nostr-wrapper.js';
+import { isPubkey } from '../crypto/secp256k1.js';
+import {
+  encryptNIP44,
+  createDMEvent,
+  generateNonce,
+} from '../crypto/nostr-utils.js';
 
 /** @constant {number} Maximum depth for hologram resolution chain */
 const MAX_RESOLUTION_DEPTH = 10;
@@ -85,42 +93,32 @@ export async function wouldCreateCircularHologram(client, appname, sourceHolon,
 }
 
 /**
- * Create a hologram (lightweight reference) - UNIFIED MODEL
+ * Create a hologram (lightweight reference).
  *
- * All holograms now include authorPubKey and capability for consistency.
- * This unifies "in-federation" (same author) and "cross-federation" (different authors).
+ * A hologram is a pointer — it says "the real data lives at soul,
+ * written by authorPubKey." No capability tokens needed; federation
+ * membership (a pubkey list) controls who gets to see what on read.
  *
  * @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 - Hologram options (authorPubKey and capability are required)
- * @param {string} options.authorPubKey - Source author's public key (REQUIRED - can be self)
- * @param {string} options.capability - Capability token (REQUIRED - self-issued for same author)
- * @returns {Object} Hologram object with unified structure
- * @throws {Error} If authorPubKey or capability is missing
+ * @param {Object} options - Hologram options
+ * @param {string} options.authorPubKey - Source author's public key (REQUIRED)
+ * @returns {Object} Hologram object
+ * @throws {Error} If authorPubKey is missing
  */
 export function createHologram(sourceHolon, targetHolon, lensName, dataId, appname, options = {}) {
   const { authorPubKey } = options;
-  let { capability } = options;
 
-  // Validate required fields for unified model
   if (!authorPubKey) {
-    throw new Error('authorPubKey is required for hologram creation (unified model)');
-  }
-  if (!capability) {
-    throw new Error('capability is required for hologram creation (unified model)');
-  }
-
-  // Normalize capability - ensure it's the token string, not a capability object
-  if (typeof capability === 'object' && capability.token) {
-    capability = capability.token;
+    throw new Error('authorPubKey is required for hologram creation');
   }
 
   const soul = buildPath(appname, sourceHolon, lensName, dataId);
 
-  const hologram = {
+  return {
     id: dataId,
     hologram: true,
     soul,
@@ -129,29 +127,25 @@ export function createHologram(sourceHolon, targetHolon, lensName, dataId, appna
       holonId: sourceHolon,
       lensName,
       dataId,
-      authorPubKey,  // Always present in unified model
+      authorPubKey,
     },
-    capability,  // Always the token string (normalized above)
     _meta: {
       created: Date.now(),
       lastUpdated: Date.now(),
       sourceHolon,
-      source: sourceHolon,  // Alias for compatibility
+      source: sourceHolon,
       sourcePubKey: authorPubKey,
-      grantedAt: Date.now(),
     },
   };
-
-  return hologram;
 }
 
 /**
- * Create a hologram with automatic capability issuance - UNIFIED MODEL
+ * Create a hologram for a given author.
  *
- * This is the preferred method for creating holograms. It automatically issues
- * a capability token (self-capability if same author, cross-capability otherwise).
+ * This is the preferred method for creating holograms. It just needs the
+ * source author's public key — no capability tokens are issued or stored.
  *
- * @param {Object} client - Nostr client instance (must have publicKey and optionally privateKey)
+ * @param {Object} client - Nostr client instance (must have publicKey)
  * @param {string} sourceHolon - Source holon ID
  * @param {string} targetHolon - Target holon ID
  * @param {string} lensName - Lens name
@@ -159,103 +153,59 @@ export function createHologram(sourceHolon, targetHolon, lensName, dataId, appna
  * @param {string} appname - Application namespace
  * @param {Object} options - Hologram options
  * @param {string} [options.sourceAuthorPubKey] - Source author's public key (defaults to client.publicKey)
- * @param {string} [options.sourceAuthorPrivKey] - Source author's private key for signing capability (defaults to client.privateKey)
- * @param {string} [options.targetAuthorPubKey] - Target author's public key (defaults to client.publicKey)
- * @param {string} [options.capability] - Pre-issued capability (if not provided, one will be issued)
- * @param {string[]} [options.permissions=['read']] - Permissions for auto-issued capability
- * @param {number} [options.expiresIn=null] - Capability expiration in ms (null = no expiration)
- * @returns {Promise<Object>} Hologram object with unified structure
+ * @param {string} [options.capability] - Ignored (kept for backward compat)
+ * @returns {Promise<Object>} Hologram object
  */
 export async function createHologramWithCapability(client, sourceHolon, targetHolon, lensName, dataId, appname, options = {}) {
-  const {
-    sourceAuthorPubKey = client.publicKey,
-    sourceAuthorPrivKey = client.privateKey,  // Allow passing author's private key for signing
-    targetAuthorPubKey = client.publicKey,
-    capability: providedCapability = null,
-    permissions = ['read'],
-    expiresIn = null,
-  } = options;
-
-  let capability = providedCapability;
-
-  // Issue capability if not provided
-  if (!capability) {
-    const isSelfCapability = sourceAuthorPubKey === targetAuthorPubKey;
-
-    // Issue capability - for self-caps, no expiration by default
-    capability = await issueCapability(
-      permissions,
-      { holonId: sourceHolon, lensName, dataId },
-      targetAuthorPubKey,
-      {
-        expiresIn: expiresIn !== undefined ? expiresIn : null, // Hologram capabilities don't expire — they live as long as the hologram
-        issuer: sourceAuthorPubKey,
-        issuerKey: sourceAuthorPrivKey,  // Use passed private key (holon's key when federated via holonsbot)
-      }
-    );
-
-    // Store the capability in registry for cross-author federation
-    if (!isSelfCapability && client.privateKey) {
-      await storeInboundCapability(client, appname, sourceAuthorPubKey, {
-        token: capability,
-        scope: { holonId: sourceHolon, lensName, dataId },
-        permissions,
-        isSelfCapability: false,
-      });
-    }
-  }
+  const sourceAuthorPubKey = options.sourceAuthorPubKey || client.publicKey;
 
   return createHologram(sourceHolon, targetHolon, lensName, dataId, appname, {
     authorPubKey: sourceAuthorPubKey,
-    capability,
   });
 }
 
 /**
- * Resolve hologram to actual data, merging local overrides - UNIFIED MODEL
+ * Resolve hologram to actual data, merging local overrides.
  *
- * In the unified model, ALL holograms have authorPubKey and capability.
- * Resolution always:
- * 1. Verifies the capability token
- * 2. Fetches data with author filter
+ * Resolution is simple:
+ * 1. Detect circular references
+ * 2. Fetch source data using authorPubKey as author filter
+ * 3. Merge with local overrides
  *
- * This provides consistent security for both self and cross-author holograms.
+ * No capability verification — federation membership controls visibility
+ * at the read() layer, not at hologram resolution.
  *
  * @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 {string} options.appname - Application namespace
  * @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)
- * @param {boolean} options.skipCapabilityVerification - Skip capability check (for internal use only)
  * @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, skipCapabilityVerification = false } = options;
+  const { deleteCircular = true, hologramPath = null } = options;
 
   if (!hologram || !hologram.hologram) {
     return hologram; // Not a hologram, return as-is
   }
 
+  // Lens holograms expand at read time (in index.js), not during resolution
+  if (hologram.lens === true) {
+    return null;
+  }
+
   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
+    console.warn(`Circular reference detected: ${chainStr}`);
+
     if (deleteCircular && hologramPath) {
-      console.info(`   🗑️ Deleting circular hologram at: ${hologramPath}`);
       await write(client, hologramPath, null);
     }
 
@@ -263,102 +213,20 @@ export async function resolveHologram(client, hologram, visited = new Set(), cha
   }
 
   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;
-
-  // UNIFIED MODEL: All holograms have authorPubKey and capability
-  // Get capability - try embedded first, then registry fallback
-  let capability = hologram.capability;
+  // Fetch source data — use authorPubKey as author filter if present
   const authorPubKey = target.authorPubKey;
-
-  // Normalize capability - extract token string if it's a capability object
-  if (capability && typeof capability === 'object' && capability.token) {
-    capability = capability.token;
-  }
-
-  if (!capability && options.appname && authorPubKey) {
-    // Fallback to registry lookup
-    const capEntry = await getCapabilityForAuthor(
-      client,
-      options.appname,
-      authorPubKey,
-      {
-        holonId: target.holonId,
-        lensName: target.lensName,
-        dataId: target.dataId,
-      }
-    );
-    if (capEntry) {
-      // Extract token string from capability entry
-      capability = capEntry.token || capEntry;
-    }
-  }
-
-  // Verify capability (unified model - always verify unless explicitly skipped)
-  if (!skipCapabilityVerification) {
-    if (!capability) {
-      console.warn(`❌ Hologram missing capability: ${soul}`);
-      return null;
-    }
-
-    // OBJECT-CAPABILITY SECURITY: Verify capability issuer matches claimed authorPubKey
-    // This prevents forged capabilities where someone signs a capability for data they don't own
-    if (authorPubKey) {
-      const issuerMatch = await verifyCapabilityIssuer(capability, authorPubKey);
-      if (!issuerMatch) {
-        console.warn(`❌ Capability issuer does not match authorPubKey for hologram: ${soul}`);
-        console.warn(`   Expected author: ${authorPubKey?.slice(0, 12)}...`);
-        const decoded = decodeCapability(capability);
-        if (decoded) {
-          console.warn(`   Actual issuer: ${decoded.issuer?.slice(0, 12)}...`);
-        }
-        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 hologram: ${soul}`);
-      return null;
-    }
-  }
-
-  // UNIFIED MODEL: Always fetch with author filter if authorPubKey is present
-  if (authorPubKey) {
-    sourceData = await read(client, soul, {
-      authors: [authorPubKey]
-    });
-  } else {
-    // Legacy fallback for holograms without authorPubKey
-    sourceData = await read(client, soul);
-  }
+  const sourceData = authorPubKey
+    ? await read(client, soul, { authors: [authorPubKey] })
+    : await read(client, soul);
 
   if (!sourceData) {
     return null;
@@ -366,7 +234,6 @@ export async function resolveHologram(client, hologram, visited = new Set(), cha
 
   // 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 });
   }
 
@@ -375,7 +242,7 @@ export async function resolveHologram(client, hologram, visited = new Set(), cha
 }
 
 /**
- * Merge hologram local overrides with source data - UNIFIED MODEL
+ * Merge hologram local overrides with source data.
  * @private
  * @param {Object} hologram - Hologram object
  * @param {Object} sourceData - Source data
@@ -457,10 +324,10 @@ export async function setupFederation(
 }
 
 /**
- * Propagate data to federated location - UNIFIED MODEL
+ * Propagate data to federated location.
  *
- * In the unified model, all holograms require authorPubKey and capability.
- * This function automatically issues capabilities for propagation.
+ * Creates a hologram (reference) or copy in the target holon.
+ * No capability tokens needed — just the author's pubkey.
  *
  * @param {Object} client - Nostr client instance (must have publicKey)
  * @param {string} appname - Application namespace
@@ -471,8 +338,6 @@ export async function setupFederation(
  * @param {string} mode - 'reference' or 'copy'
  * @param {Object} options - Propagation options
  * @param {string} [options.sourceAuthorPubKey] - Source author (defaults to client.publicKey)
- * @param {string} [options.sourceAuthorPrivKey] - Source author's private key for signing capability (defaults to client.privateKey)
- * @param {string} [options.capability] - Pre-issued capability (auto-issued if not provided)
  * @returns {Promise<boolean>} Success indicator
  */
 export async function propagateData(
@@ -493,97 +358,13 @@ export async function propagateData(
     return true;
   }
 
-  // Don't propagate holograms back to avoid circular references
-  // If this data is already a hologram pointing to the target, skip it
+  // Don't propagate holograms — holograms should only be created explicitly
   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;
+    console.info(`⏭️ Skipping propagation - data is already a hologram (no transitive copy):`);
+    console.info(`   Data ID: ${dataId}`);
+    console.info(`   Source holon: ${sourceHolon}`);
+    console.info(`   Target holon: ${targetHolon}`);
+    return true;
   }
 
   // For non-hologram data, check if targetHolon is already in activeHolograms
@@ -616,15 +397,9 @@ export async function propagateData(
       return false;
     }
 
-    // UNIFIED MODEL: Create hologram with capability
+    // Create hologram — just a pointer with the author's pubkey
     const sourceAuthorPubKey = options.sourceAuthorPubKey || client.publicKey;
 
-    // Determine targetAuthorPubKey - the person who should be able to read the hologram
-    // If targetHolon is a 64-char hex pubkey, use it directly as the target author
-    // Otherwise, this needs to be resolved via holon registry (TODO: add resolution)
-    const isPubkey = typeof targetHolon === 'string' && /^[0-9a-f]{64}$/i.test(targetHolon);
-    const targetAuthorPubKey = options.targetAuthorPubKey || (isPubkey ? targetHolon : client.publicKey);
-
     const hologram = await createHologramWithCapability(
       client,
       sourceHolon,
@@ -632,13 +407,7 @@ export async function propagateData(
       lensName,
       dataId,
       appname,
-      {
-        sourceAuthorPubKey,
-        sourceAuthorPrivKey: options.sourceAuthorPrivKey,  // Pass through for holon-signed capabilities
-        targetAuthorPubKey,
-        capability: options.capability,
-        permissions: ['read'],
-      }
+      { sourceAuthorPubKey }
     );
 
     const targetPath = buildPath(appname, targetHolon, lensName, dataId);
@@ -712,6 +481,157 @@ export function isHologram(data) {
   return data && data.hologram === true;
 }
 
+// ============================================================================
+// Lens Holograms — "share this entire lens from this author"
+// ============================================================================
+
+/**
+ * Create a lens hologram — a reference meaning "all data in this lens from this author".
+ *
+ * Unlike an item hologram (which points at a single data item), a lens hologram
+ * expands at read time: the reader fetches every item in the source lens and merges
+ * them into the local results.
+ *
+ * @param {string} sourceHolon - Source holon ID (where data lives)
+ * @param {string} lensName - Lens name
+ * @param {string} appname - Application namespace
+ * @param {Object} options
+ * @param {string} options.author - Public key of the author whose data this points to
+ * @returns {Object} Lens hologram object
+ */
+export function createLensHologram(sourceHolon, lensName, appname, { author }) {
+  if (!author) {
+    throw new Error('author is required for lens hologram creation');
+  }
+
+  const soul = buildPath(appname, sourceHolon, lensName);
+
+  return {
+    id: `_lens_${author}`,
+    hologram: true,
+    lens: true,           // distinguishes from item hologram
+    soul,
+    target: {
+      app: appname,
+      holon: sourceHolon,
+      lens: lensName,
+      author,
+    },
+    _meta: {
+      created: Date.now(),
+      lastUpdated: Date.now(),
+      sourceHolon,
+      sourcePubKey: author,
+    },
+  };
+}
+
+/**
+ * Check if data is a lens hologram (all-items reference).
+ * @param {Object} data - Data to check
+ * @returns {boolean} True if this is a lens hologram
+ */
+export function isLensHologram(data) {
+  return !!(data && data.hologram === true && data.lens === true);
+}
+
+// ============================================================================
+// DM Helpers — send share / share_ack payloads via NIP-44 encrypted DM
+// ============================================================================
+
+/**
+ * Send a 'share' DM to a target pubkey.
+ *
+ * @param {Object} client - NostrClient instance with publish method
+ * @param {string} privateKey - Sender's hex private key
+ * @param {string} targetPubKey - Recipient's hex public key
+ * @param {Object} payload - Share payload
+ * @param {string} payload.source - Source holon ID
+ * @param {string} payload.lens - Lens name
+ * @param {string|null} payload.item - Data ID (null for lens-level share)
+ * @param {string} payload.author - Author public key
+ * @param {Array} [payload.keys] - Optional bundled lens encryption keys
+ * @param {string} [payload.msg] - Optional message
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function sendShare(client, privateKey, targetPubKey, payload) {
+  try {
+    const dm = {
+      type: 'share',
+      id: generateNonce(),
+      source: payload.source,
+      lens: payload.lens,
+      item: payload.item || null,
+      author: payload.author,
+      keys: payload.keys || [],
+      msg: payload.msg || '',
+      timestamp: Date.now(),
+    };
+
+    const content = JSON.stringify(dm);
+    const encrypted = encryptNIP44(privateKey, targetPubKey, content);
+    const event = createDMEvent(targetPubKey, encrypted, privateKey);
+
+    if (client?.publish) {
+      await client.publish(event);
+      console.log('[Share] Share DM sent to:', targetPubKey.substring(0, 8) + '...');
+      return true;
+    }
+    console.error('[Share] No publish method on client');
+    return false;
+  } catch (error) {
+    console.error('[Share] Failed to send share DM:', error);
+    return false;
+  }
+}
+
+/**
+ * Send a 'share_ack' DM (accept or reject response).
+ *
+ * @param {Object} client - NostrClient instance with publish method
+ * @param {string} privateKey - Sender's hex private key
+ * @param {string} targetPubKey - Recipient's hex public key
+ * @param {Object} payload - Ack payload
+ * @param {string} payload.id - Original share id being acknowledged
+ * @param {string} payload.source - Source holon ID
+ * @param {string} payload.lens - Lens name
+ * @param {string|null} payload.item - Data ID (null for lens-level)
+ * @param {string} payload.author - Author public key
+ * @param {'accepted'|'rejected'} payload.status - Acceptance status
+ * @param {string} [payload.msg] - Optional message
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function sendAck(client, privateKey, targetPubKey, payload) {
+  try {
+    const dm = {
+      type: 'share_ack',
+      id: payload.id,
+      source: payload.source,
+      lens: payload.lens,
+      item: payload.item || null,
+      author: payload.author,
+      status: payload.status,
+      msg: payload.msg || '',
+      timestamp: Date.now(),
+    };
+
+    const content = JSON.stringify(dm);
+    const encrypted = encryptNIP44(privateKey, targetPubKey, content);
+    const event = createDMEvent(targetPubKey, encrypted, privateKey);
+
+    if (client?.publish) {
+      await client.publish(event);
+      console.log('[Share] Ack DM sent to:', targetPubKey.substring(0, 8) + '...', 'status:', payload.status);
+      return true;
+    }
+    console.error('[Share] No publish method on client');
+    return false;
+  } catch (error) {
+    console.error('[Share] Failed to send ack DM:', error);
+    return false;
+  }
+}
+
 /**
  * Check if data was resolved from a hologram
  * @param {Object} data - Data to check
@@ -738,36 +658,31 @@ export function getHologramSource(data) {
 }
 
 /**
- * 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
+ * Follow a hologram chain to find the real (non-hologram) source data.
+ * If the data at the given location is a hologram, follows .target references
+ * until real data is found or max depth is reached.
+ * @private
  * @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} holon - Starting holon ID
+ * @param {string} lens - Lens name
  * @param {string} dataId - Data ID
- * @param {string} targetHolon - Target holon ID (where hologram lives)
- * @returns {Promise<boolean>} Success indicator
+ * @param {number} [maxDepth=10] - Maximum chain depth
+ * @returns {Promise<{ sourcePath: string, sourceData: Object }|null>} Real source or null
  */
-export async function addActiveHologram(client, appname, sourceHolon, lensName, dataId, targetHolon) {
+async function followToRealSource(client, appname, holon, lens, dataId, maxDepth = 10) {
   let currentAppname = appname;
-  let currentHolon = sourceHolon;
-  let currentLens = lensName;
+  let currentHolon = holon;
+  let currentLens = lens;
   let currentDataId = dataId;
   let sourcePath = buildPath(currentAppname, currentHolon, currentLens, currentDataId);
 
-  // Read existing source data
-  // Note: May return null if called immediately after write (before relay persistence)
-  // This is expected - the hologram still works, we just can't track activeHolograms
   let sourceData = await read(client, sourcePath);
   if (!sourceData) {
-    return false;
+    return null;
   }
 
-  // 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;
@@ -778,10 +693,34 @@ export async function addActiveHologram(client, appname, sourceHolon, lensName,
 
     sourceData = await read(client, sourcePath);
     if (!sourceData) {
-      return false;
+      return null;
     }
   }
 
+  return { sourcePath, sourceData };
+}
+
+/**
+ * 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) {
+  // Note: May return null if called immediately after write (before relay persistence)
+  // This is expected - the hologram still works, we just can't track activeHolograms
+  const result = await followToRealSource(client, appname, sourceHolon, lensName, dataId);
+  if (!result) {
+    return false;
+  }
+
+  const { sourcePath, sourceData } = result;
 
   // Initialize _meta and activeHolograms if needed
   if (!sourceData._meta) {
@@ -827,34 +766,12 @@ export async function addActiveHologram(client, appname, sourceHolon, lensName,
  * @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) {
+  const result = await followToRealSource(client, appname, sourceHolon, lensName, dataId);
+  if (!result) {
     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;
-    }
-  }
+  const { sourcePath, sourceData } = result;
 
   if (!sourceData._meta || !Array.isArray(sourceData._meta.activeHolograms)) {
     return false;
@@ -887,35 +804,12 @@ export async function removeActiveHologram(client, appname, sourceHolon, lensNam
  * @returns {Promise<boolean>} Success indicator
  */
 export async function updateActiveHologramPlatform(client, appname, sourceHolon, lensName, dataId, targetHolon, platform, platformData) {
-  let currentAppname = appname;
-  let currentHolon = sourceHolon;
-  let currentLens = lensName;
-  let currentDataId = dataId;
-  let sourcePath = buildPath(currentAppname, currentHolon, currentLens, currentDataId);
-
-  // Read existing source data
-  // Note: May return null if called immediately after write (before relay persistence)
-  let sourceData = await read(client, sourcePath);
-  if (!sourceData) {
+  const result = await followToRealSource(client, appname, sourceHolon, lensName, dataId);
+  if (!result) {
     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;
-    }
-  }
+  const { sourcePath, sourceData } = result;
 
   if (!sourceData._meta || !Array.isArray(sourceData._meta.activeHolograms)) {
     console.warn(`No activeHolograms found for ${sourcePath}`);
@@ -1132,96 +1026,17 @@ export async function deleteHologram(client, appname, holonId, lensName, dataId,
  * @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;
+  // Read the lens index to get all item IDs
+  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 { scanned: 0, circularFound: 0, deleted: 0, errors: [], details: [] };
   }
+
+  return cleanupCircularHologramsByIds(client, appname, holonId, lensName, lensIndex.items, options);
 }
 
 /**