holosphere 2.0.0-alpha1 → 2.0.0-alpha10

package/src/storage/nostr-async.js

@@ -1,21 +1,52 @@
 /**
- * Nostr Async Utilities
- * Provides Promise-based wrappers and async patterns for Nostr operations
+ * @fileoverview Nostr Async Utilities.
+ *
+ * Provides Promise-based wrappers and async patterns for Nostr operations.
+ * Includes local-first data access, query deduplication, subscription management,
+ * and background refresh capabilities for optimal performance.
+ *
+ * @module storage/nostr-async
  */
 
 /**
- * Global subscription manager to prevent duplicate subscriptions
- * Maps: pathPrefix -> subscription object
+ * Global subscription manager to prevent duplicate subscriptions.
+ * Maps: subscriptionKey -> subscription object
+ * @private
  */
 const globalSubscriptions = new Map();
 
 /**
- * Write data as Nostr event (parameterized replaceable event)
+ * Single-path subscription manager (for nostrSubscribe).
+ * Maps: subscriptionKey -> { subscription, callbacks: [] }
+ * @private
+ */
+const singlePathSubscriptions = new Map();
+
+/**
+ * Query deduplication for nostrGet - prevents duplicate relay queries.
+ * Maps: queryKey -> { promise, timestamp, callbacks: [] }
+ * @private
+ */
+const pendingQueries = new Map();
+
+/**
+ * Time window for query deduplication (2 seconds).
+ * @private
+ * @constant {number}
+ */
+const QUERY_DEDUP_WINDOW = 2000;
+
+/**
+ * Write data as Nostr event (parameterized replaceable event).
+ *
  * @param {Object} client - NostrClient instance
  * @param {string} path - Path identifier (encoded in d-tag)
  * @param {Object} data - Data to store
- * @param {number} kind - Event kind (default: 30000 for parameterized replaceable)
- * @returns {Promise<Object>} Published event result
+ * @param {number} [kind=30000] - Event kind (default: 30000 for parameterized replaceable)
+ * @returns {Promise<Object>} Published event result with relay responses
+ * @example
+ * const result = await nostrPut(client, 'myapp/holon123/items/item1', { name: 'Test' });
+ * console.log(result.event.id); // Event ID
  */
 export async function nostrPut(client, path, data, kind = 30000) {
   const dataEvent = {
@@ -32,52 +63,137 @@ export async function nostrPut(client, path, data, kind = 30000) {
 }
 
 /**
- * Read data from Nostr (query by d-tag)
- * LOCAL-FIRST: Checks persistent storage first, never blocks on network
+ * Read data from Nostr (query by d-tag).
+ *
+ * LOCAL-FIRST: Checks persistent storage first, never blocks on network.
+ * Uses query deduplication to prevent duplicate relay queries within a time window.
+ *
  * @param {Object} client - NostrClient instance
  * @param {string} path - Path identifier
- * @param {number} kind - Event kind (default: 30000)
- * @param {Object} options - Query options
- * @param {string[]} options.authors - Array of public keys to query (default: [client.publicKey])
- * @param {boolean} options.includeAuthor - If true, adds _author field to returned data
- * @param {boolean} options.skipPersistent - If true, skip persistent storage check (default: false)
+ * @param {number} [kind=30000] - Event kind (default: 30000)
+ * @param {Object} [options={}] - Query options
+ * @param {string[]} [options.authors] - Array of public keys to query (default: [client.publicKey])
+ * @param {boolean} [options.includeAuthor=false] - If true, adds _author field to returned data
+ * @param {boolean} [options.skipPersistent=false] - If true, skip persistent storage check
+ * @param {number} [options.timeout=30000] - Query timeout in milliseconds
  * @returns {Promise<Object|null>} Data or null if not found
+ * @example
+ * const data = await nostrGet(client, 'myapp/holon1/items/item1');
+ * if (data) {
+ *   console.log(data.name);
+ * }
  */
 export async function nostrGet(client, path, kind = 30000, options = {}) {
   const timeout = options.timeout !== undefined ? options.timeout : 30000;
   const authors = options.authors || [client.publicKey];
 
-  // LOCAL-FIRST: Check persistent storage FIRST (never blocks on network)
+  // CHECK LRU CACHE FIRST (always up-to-date, even before batched persist)
+  // This ensures immediate reads after writes return fresh data
+  if (!options.skipCache && client.getCachedByPath) {
+    const cachedEvent = client.getCachedByPath(path, kind);
+    if (cachedEvent && cachedEvent.content) {
+      // Verify author is in requested authors list
+      if (authors.includes(cachedEvent.pubkey)) {
+        try {
+          const data = JSON.parse(cachedEvent.content);
+
+          // Skip null/undefined or deleted items
+          if (!data || data._deleted) {
+            return null;
+          }
+
+          // Optionally include author information
+          if (options.includeAuthor) {
+            data._author = cachedEvent.pubkey;
+          }
+
+          return data;
+        } catch (error) {
+          // Fall through if parsing fails
+        }
+      }
+    }
+  }
+
+  // LOCAL-FIRST: Check persistent storage (may be slightly stale due to batched writes)
   if (!options.skipPersistent && client.persistentGet) {
     const persistedEvent = await client.persistentGet(path);
     if (persistedEvent && persistedEvent.content) {
-      try {
-        const data = JSON.parse(persistedEvent.content);
+      // Verify author is in requested authors list (persistent storage may have cached events from other authors)
+      if (!authors.includes(persistedEvent.pubkey)) {
+        // Author mismatch - fall through to relay query
+      } else {
+        try {
+          const data = JSON.parse(persistedEvent.content);
 
-        // Skip deleted items
-        if (data._deleted) {
-          return null;
-        }
+          // Skip null/undefined or deleted items
+          if (!data || data._deleted) {
+            return null;
+          }
 
-        // Optionally include author information
-        if (options.includeAuthor) {
-          data._author = persistedEvent.pubkey;
-        }
+          // Optionally include author information
+          if (options.includeAuthor) {
+            data._author = persistedEvent.pubkey;
+          }
 
-        // Trigger background refresh from relays (fire-and-forget)
-        if (client.refreshPathInBackground) {
-          client.refreshPathInBackground(path, kind, { authors, timeout });
-        }
+          // Trigger background refresh from relays (fire-and-forget)
+          if (client.refreshPathInBackground) {
+            client.refreshPathInBackground(path, kind, { authors, timeout });
+          }
 
-        return data;
-      } catch (error) {
-        // Fall through to relay query if parsing fails
-        console.warn('[nostrGet] Failed to parse persisted event:', error);
+          return data;
+        } catch (error) {
+          // Fall through to relay query if parsing fails
+          console.warn('[nostrGet] Failed to parse persisted event:', error);
+        }
       }
     }
   }
 
-  // Fallback to relay query (existing logic)
+  // Query deduplication: Check if same query is already pending
+  const queryKey = `get:${client.publicKey}:${kind}:${path}:${authors.join(',')}`;
+  const pending = pendingQueries.get(queryKey);
+
+  if (pending && Date.now() - pending.timestamp < QUERY_DEDUP_WINDOW) {
+    // Reuse pending query result
+    return pending.promise;
+  }
+
+  // Create new query with deduplication
+  const queryPromise = _executeNostrGet(client, path, kind, authors, timeout, options);
+
+  pendingQueries.set(queryKey, {
+    promise: queryPromise,
+    timestamp: Date.now(),
+  });
+
+  // Clean up after promise resolves
+  queryPromise.finally(() => {
+    // Remove from pending after a short delay to allow coalescing
+    setTimeout(() => {
+      const current = pendingQueries.get(queryKey);
+      if (current && current.promise === queryPromise) {
+        pendingQueries.delete(queryKey);
+      }
+    }, QUERY_DEDUP_WINDOW);
+  });
+
+  return queryPromise;
+}
+
+/**
+ * Internal function to execute nostrGet query.
+ *
+ * @private
+ * @param {Object} client - NostrClient instance
+ * @param {string} path - Path identifier
+ * @param {number} kind - Event kind
+ * @param {string[]} authors - Array of author public keys
+ * @param {number} timeout - Query timeout
+ * @param {Object} options - Query options
+ * @returns {Promise<Object|null>} Data or null
+ */
+async function _executeNostrGet(client, path, kind, authors, timeout, options) {
   const filter = {
     kinds: [kind],
     authors: authors, // Support multiple authors for cross-holosphere queries
@@ -87,37 +203,52 @@ export async function nostrGet(client, path, kind = 30000, options = {}) {
 
   const events = await client.query(filter, { timeout });
 
-  if (events.length === 0) {
+  // Filter by author (relays may not respect authors filter)
+  const authoredEvents = events.filter(event => authors.includes(event.pubkey));
+
+  if (authoredEvents.length === 0) {
     return null;
   }
 
-  // Get most recent event (across all authors)
-  const event = events.sort((a, b) => b.created_at - a.created_at)[0];
+  // Get most recent event (across allowed authors)
+  const event = authoredEvents.sort((a, b) => b.created_at - a.created_at)[0];
 
   try {
     const data = JSON.parse(event.content);
+    // Skip null/undefined or deleted items
+    if (!data || data._deleted) {
+      return null;
+    }
     // Optionally include author information
     if (options.includeAuthor) {
       data._author = event.pubkey;
     }
     return data;
   } catch (error) {
-    console.error('Failed to parse event content:', error);
+    // Silent - return null for unparseable events
     return null;
   }
 }
 
 /**
- * Query all events under a path prefix
- * LOCAL-FIRST: Checks persistent storage first, never blocks on network
+ * Query all events under a path prefix.
+ *
+ * LOCAL-FIRST: Checks persistent storage first, never blocks on network.
+ * Uses query deduplication to prevent duplicate relay queries within a time window.
+ *
  * @param {Object} client - NostrClient instance
  * @param {string} pathPrefix - Path prefix to match
- * @param {number} kind - Event kind (default: 30000)
- * @param {Object} options - Query options
- * @param {string[]} options.authors - Array of public keys to query (default: [client.publicKey])
- * @param {boolean} options.includeAuthor - If true, adds _author field to returned data
- * @param {boolean} options.skipPersistent - If true, skip persistent storage check (default: false)
+ * @param {number} [kind=30000] - Event kind (default: 30000)
+ * @param {Object} [options={}] - Query options
+ * @param {string[]} [options.authors] - Array of public keys to query (default: [client.publicKey])
+ * @param {boolean} [options.includeAuthor=false] - If true, adds _author field to returned data
+ * @param {boolean} [options.skipPersistent=false] - If true, skip persistent storage check
+ * @param {number} [options.timeout=30000] - Query timeout in milliseconds
+ * @param {number} [options.limit=1000] - Maximum number of events to retrieve
  * @returns {Promise<Array>} Array of data objects
+ * @example
+ * const items = await nostrGetAll(client, 'myapp/holon1/items/');
+ * console.log(`Found ${items.length} items`);
  */
 export async function nostrGetAll(client, pathPrefix, kind = 30000, options = {}) {
   const timeout = options.timeout !== undefined ? options.timeout : 30000;
@@ -133,6 +264,9 @@ export async function nostrGetAll(client, pathPrefix, kind = 30000, options = {}
       for (const event of persistedEvents) {
         if (!event || !event.tags) continue;
 
+        // Verify author is in requested authors list (persistent storage may have cached events from other authors)
+        if (!authors.includes(event.pubkey)) continue;
+
         const dTag = event.tags.find(t => t[0] === 'd');
         if (!dTag || !dTag[1] || !dTag[1].startsWith(pathPrefix)) continue;
 
@@ -143,8 +277,11 @@ export async function nostrGetAll(client, pathPrefix, kind = 30000, options = {}
           try {
             const data = JSON.parse(event.content);
 
-            // Skip deleted items
-            if (data._deleted) continue;
+            // Handle null/undefined or deleted items - remove from map if this is newer
+            if (!data || data._deleted) {
+              byPath.delete(path);
+              continue;
+            }
 
             // Optionally include author information
             if (options.includeAuthor) {
@@ -167,7 +304,50 @@ export async function nostrGetAll(client, pathPrefix, kind = 30000, options = {}
     }
   }
 
-  // Fallback to relay query (existing logic)
+  // Query deduplication: Check if same query is already pending
+  const queryKey = `getAll:${client.publicKey}:${kind}:${pathPrefix}:${authors.join(',')}`;
+  const pending = pendingQueries.get(queryKey);
+
+  if (pending && Date.now() - pending.timestamp < QUERY_DEDUP_WINDOW) {
+    // Reuse pending query result
+    return pending.promise;
+  }
+
+  // Create new query with deduplication
+  const queryPromise = _executeNostrGetAll(client, pathPrefix, kind, authors, timeout, limit, options);
+
+  pendingQueries.set(queryKey, {
+    promise: queryPromise,
+    timestamp: Date.now(),
+  });
+
+  // Clean up after promise resolves
+  queryPromise.finally(() => {
+    setTimeout(() => {
+      const current = pendingQueries.get(queryKey);
+      if (current && current.promise === queryPromise) {
+        pendingQueries.delete(queryKey);
+      }
+    }, QUERY_DEDUP_WINDOW);
+  });
+
+  return queryPromise;
+}
+
+/**
+ * Internal function to execute nostrGetAll query.
+ *
+ * @private
+ * @param {Object} client - NostrClient instance
+ * @param {string} pathPrefix - Path prefix to match
+ * @param {number} kind - Event kind
+ * @param {string[]} authors - Array of author public keys
+ * @param {number} timeout - Query timeout
+ * @param {number} limit - Maximum results
+ * @param {Object} options - Query options
+ * @returns {Promise<Array>} Array of data objects
+ */
+async function _executeNostrGetAll(client, pathPrefix, kind, authors, timeout, limit, options) {
   const filter = {
     kinds: [kind],
     authors: authors,
@@ -176,10 +356,12 @@ export async function nostrGetAll(client, pathPrefix, kind = 30000, options = {}
 
   const events = await client.query(filter, { timeout });
 
-  // Filter by path prefix in application layer
+  // Filter by path prefix AND verify author (relays may not respect authors filter)
   const matching = events.filter(event => {
     const dTag = event.tags.find(t => t[0] === 'd');
-    return dTag && dTag[1] && dTag[1].startsWith(pathPrefix);
+    const pathMatches = dTag && dTag[1] && dTag[1].startsWith(pathPrefix);
+    const authorAllowed = authors.includes(event.pubkey);
+    return pathMatches && authorAllowed;
   });
 
   // Parse content and group by d-tag (keep latest only, across all authors)
@@ -192,8 +374,11 @@ export async function nostrGetAll(client, pathPrefix, kind = 30000, options = {}
       try {
         const data = JSON.parse(event.content);
 
-        // Skip deleted items
-        if (data._deleted) continue;
+        // Handle null/undefined or deleted items - remove from map if this is newer
+        if (!data || data._deleted) {
+          byPath.delete(dTag);
+          continue;
+        }
 
         // Optionally include author information
         if (options.includeAuthor) {
@@ -201,7 +386,7 @@ export async function nostrGetAll(client, pathPrefix, kind = 30000, options = {}
         }
         byPath.set(dTag, { data, created_at: event.created_at });
       } catch (error) {
-        console.error('Failed to parse event content:', error);
+        // Silent - skip unparseable events
       }
     }
   }
@@ -211,14 +396,18 @@ export async function nostrGetAll(client, pathPrefix, kind = 30000, options = {}
 }
 
 /**
- * Query all events under a path prefix (HYBRID MODE - local + relay)
- * Checks local cache first, then merges with relay data
+ * Query all events under a path prefix (HYBRID MODE - local + relay).
+ *
+ * Checks local cache first, then merges with relay data.
+ *
  * @param {Object} client - NostrClient instance
  * @param {string} pathPrefix - Path prefix to match
- * @param {number} kind - Event kind (default: 30000)
- * @param {Object} options - Query options
- * @param {string[]} options.authors - Array of public keys to query (default: [client.publicKey])
- * @param {boolean} options.includeAuthor - If true, adds _author field to returned data
+ * @param {number} [kind=30000] - Event kind (default: 30000)
+ * @param {Object} [options={}] - Query options
+ * @param {string[]} [options.authors] - Array of public keys to query (default: [client.publicKey])
+ * @param {boolean} [options.includeAuthor=false] - If true, adds _author field to returned data
+ * @param {number} [options.timeout=30000] - Query timeout in milliseconds
+ * @param {number} [options.limit=1000] - Maximum number of events to retrieve
  * @returns {Promise<Array>} Array of data objects (merged from local + relay)
  */
 export async function nostrGetAllHybrid(client, pathPrefix, kind = 30000, options = {}) {
@@ -237,10 +426,12 @@ export async function nostrGetAllHybrid(client, pathPrefix, kind = 30000, option
 
   const events = await queryMethod.call(client, filter, { timeout });
 
-  // Filter by path prefix in application layer
+  // Filter by path prefix AND verify author (relays may not respect authors filter)
   const matching = events.filter(event => {
     const dTag = event.tags.find(t => t[0] === 'd');
-    return dTag && dTag[1] && dTag[1].startsWith(pathPrefix);
+    const pathMatches = dTag && dTag[1] && dTag[1].startsWith(pathPrefix);
+    const authorAllowed = authors.includes(event.pubkey);
+    return pathMatches && authorAllowed;
   });
 
   // Parse content and group by d-tag (keep latest only)
@@ -252,13 +443,22 @@ export async function nostrGetAllHybrid(client, pathPrefix, kind = 30000, option
     if (!existing || event.created_at > existing.created_at) {
       try {
         const data = JSON.parse(event.content);
+        // Skip null or non-object content
+        if (data === null || typeof data !== 'object') {
+          continue;
+        }
+        // Handle deleted items - remove from map if this is newer
+        if (data._deleted) {
+          byPath.delete(dTag);
+          continue;
+        }
         // Optionally include author information
         if (options.includeAuthor) {
           data._author = event.pubkey;
         }
         byPath.set(dTag, { data, created_at: event.created_at });
       } catch (error) {
-        console.error('Failed to parse event content:', error);
+        // Silent - skip unparseable events
       }
     }
   }
@@ -268,11 +468,19 @@ export async function nostrGetAllHybrid(client, pathPrefix, kind = 30000, option
 }
 
 /**
- * Delete data (publish deletion event - NIP-09)
+ * Delete data (publish deletion event - NIP-09).
+ *
+ * Publishes a tombstone event and a NIP-09 deletion event to mark data as deleted.
+ *
  * @param {Object} client - NostrClient instance
  * @param {string} path - Path identifier
- * @param {number} kind - Original event kind (default: 30000)
- * @returns {Promise<Object>} Deletion event result
+ * @param {number} [kind=30000] - Original event kind (default: 30000)
+ * @returns {Promise<Object>} Deletion event result with status
+ * @example
+ * const result = await nostrDelete(client, 'myapp/holon1/items/item1');
+ * if (result.reason !== 'not_found') {
+ *   console.log('Item deleted successfully');
+ * }
  */
 export async function nostrDelete(client, path, kind = 30000) {
   // Read existing data first
@@ -289,7 +497,7 @@ export async function nostrDelete(client, path, kind = 30000) {
   };
 
   // Publish tombstone as replacement event
-  // This ensures reads will see _deleted flag
+  // This ensures reads will see _deleted flag (also updates LRU cache via _cacheEvent)
   const result = await nostrPut(client, path, tombstone, kind);
 
   // Also delete from persistent storage to prevent resurrection on restart
@@ -301,11 +509,6 @@ export async function nostrDelete(client, path, kind = 30000) {
     }
   }
 
-  // Clear from memory cache
-  if (client.clearCache) {
-    client.clearCache(path);
-  }
-
   // Also publish NIP-09 deletion event for relay compliance
   const coordinate = `${kind}:${client.publicKey}:${path}`;
   const deletionEvent = {
@@ -319,25 +522,29 @@ export async function nostrDelete(client, path, kind = 30000) {
 
   // Publish deletion event (best effort, don't block on failure)
   try {
-    const publishResult = await client.publish(deletionEvent);
-    console.log(`✅ NIP-09 deletion event published for ${path}:`, {
-      coordinate,
-      relays: publishResult?.relays?.length || 0,
-      successful: publishResult?.successful || []
-    });
+    await client.publish(deletionEvent);
+    // Silent success - deletion queued
   } catch (error) {
-    console.error(`❌ Failed to publish NIP-09 deletion event for ${path}:`, error.message);
+    // Silent - deletion will be retried
   }
 
   return result;
 }
 
+// Rate limit delay between bulk delete operations (ms)
+const DELETE_RATE_LIMIT_MS = 100;
+
 /**
- * Delete all data with path prefix (publish deletion events - NIP-09)
+ * Delete all data with path prefix (publish deletion events - NIP-09).
+ * Includes built-in rate limiting to avoid overwhelming relays.
+ *
  * @param {Object} client - NostrClient instance
  * @param {string} pathPrefix - Path prefix to delete all items under
- * @param {number} kind - Original event kind (default: 30000)
- * @returns {Promise<Object>} Deletion results
+ * @param {number} [kind=30000] - Original event kind (default: 30000)
+ * @returns {Promise<Object>} Deletion results with success count
+ * @example
+ * const result = await nostrDeleteAll(client, 'myapp/holon1/items/');
+ * console.log(`Deleted ${result.count} items`);
  */
 export async function nostrDeleteAll(client, pathPrefix, kind = 30000) {
   // Query events from relay
@@ -388,9 +595,10 @@ export async function nostrDeleteAll(client, pathPrefix, kind = 30000) {
     return { success: true, count: 0, results: [] };
   }
 
-  // Publish tombstone events for each matching item
+  // Publish tombstone events for each matching item (with rate limiting)
   const tombstoneResults = [];
-  for (const event of matching) {
+  for (let i = 0; i < matching.length; i++) {
+    const event = matching[i];
     const dTag = event.tags.find(t => t[0] === 'd')[1];
 
     try {
@@ -400,7 +608,7 @@ export async function nostrDeleteAll(client, pathPrefix, kind = 30000) {
         _deletedAt: Date.now()
       };
 
-      // Publish tombstone replacement
+      // Publish tombstone replacement (this also updates LRU cache via _cacheEvent)
       const result = await nostrPut(client, dTag, tombstone, kind);
       tombstoneResults.push(result);
 
@@ -413,9 +621,9 @@ export async function nostrDeleteAll(client, pathPrefix, kind = 30000) {
         }
       }
 
-      // Clear from memory cache
-      if (client.clearCache) {
-        client.clearCache(dTag);
+      // Rate limit: add delay between deletes to avoid overwhelming relays
+      if (i < matching.length - 1 && DELETE_RATE_LIMIT_MS > 0) {
+        await new Promise(resolve => setTimeout(resolve, DELETE_RATE_LIMIT_MS));
       }
     } catch (error) {
       console.error(`Failed to delete item ${dTag}:`, error);
@@ -438,15 +646,10 @@ export async function nostrDeleteAll(client, pathPrefix, kind = 30000) {
       content: '', // Optional deletion reason/note
     };
 
-    const publishResult = await client.publish(deletionEvent);
-    console.log(`✅ NIP-09 bulk deletion event published for ${pathPrefix}:`, {
-      itemsDeleted: matching.length,
-      coordinates: coordinates.length,
-      relays: publishResult?.relays?.length || 0,
-      successful: publishResult?.successful || []
-    });
+    await client.publish(deletionEvent);
+    // Silent success - bulk deletion queued
   } catch (error) {
-    console.error(`❌ Failed to publish NIP-09 bulk deletion event for ${pathPrefix}:`, error.message);
+    // Silent - bulk deletion will be retried
   }
 
   return {
@@ -457,16 +660,60 @@ export async function nostrDeleteAll(client, pathPrefix, kind = 30000) {
 }
 
 /**
- * Subscribe to path changes
+ * Subscribe to path changes.
+ *
+ * Uses subscription deduplication - multiple subscribers to same path share one relay subscription.
+ *
  * @param {Object} client - NostrClient instance
  * @param {string} path - Path to subscribe to
  * @param {Function} callback - Callback function (data, event) => void
- * @param {Object} options - Subscription options
+ * @param {Object} [options={}] - Subscription options
+ * @param {number} [options.kind=30000] - Event kind to subscribe to
  * @returns {Object} Subscription object with unsubscribe method
+ * @example
+ * const sub = nostrSubscribe(client, 'myapp/holon1/items/item1', (data, event) => {
+ *   console.log('Item updated:', data);
+ * });
+ * // Later: sub.unsubscribe();
  */
 export function nostrSubscribe(client, path, callback, options = {}) {
   const kind = options.kind || 30000;
-  const includeInitial = options.includeInitial !== false;
+
+  // Create unique key for this subscription
+  const subscriptionKey = `single:${client.publicKey}:${kind}:${path}`;
+
+  // Check if we already have an active subscription for this path
+  const existing = singlePathSubscriptions.get(subscriptionKey);
+  if (existing) {
+    // Add callback to existing subscription
+    existing.callbacks.push(callback);
+
+    // Return wrapper that removes only this callback on unsubscribe
+    return {
+      unsubscribe: () => {
+        const idx = existing.callbacks.indexOf(callback);
+        if (idx > -1) {
+          existing.callbacks.splice(idx, 1);
+        }
+
+        // If no more callbacks, unsubscribe the whole thing
+        if (existing.callbacks.length === 0) {
+          existing.subscription.unsubscribe();
+          singlePathSubscriptions.delete(subscriptionKey);
+        }
+      }
+    };
+  }
+
+  // Create new subscription
+  const callbacks = [callback];
+  const subscriptionInfo = {
+    callbacks,
+    subscription: null,
+  };
+
+  // Store before creating subscription to handle race conditions
+  singlePathSubscriptions.set(subscriptionKey, subscriptionInfo);
 
   const filter = {
     kinds: [kind],
@@ -475,40 +722,61 @@ export function nostrSubscribe(client, path, callback, options = {}) {
     limit: 10, // Limit results for single item subscription
   };
 
-  let initialLoadComplete = false;
-
   const subscription = client.subscribe(
     filter,
     (event) => {
       // Verify event is from our public key (relay may not respect author filter)
       if (event.pubkey !== client.publicKey) {
-        console.warn('[nostrSubscribe] Rejecting event from different author:', {
-          expected: client.publicKey,
-          received: event.pubkey,
-          eventId: event.id
-        });
         return;
       }
 
       try {
         const data = JSON.parse(event.content);
-        callback(data, event);
+
+        // Skip null/undefined or deleted items - don't send tombstones to subscribers
+        if (!data || data._deleted) {
+          return;
+        }
+
+        // Dispatch to all registered callbacks
+        for (const cb of callbacks) {
+          try {
+            cb(data, event);
+          } catch (err) {
+            console.error('Subscription callback error:', err);
+          }
+        }
       } catch (error) {
         console.error('Failed to parse event in subscription:', error);
       }
     },
     {
       onEOSE: () => {
-        initialLoadComplete = true;
+        // EOSE received
       },
     }
   );
 
-  return subscription;
+  subscriptionInfo.subscription = subscription;
+
+  return {
+    unsubscribe: () => {
+      const idx = callbacks.indexOf(callback);
+      if (idx > -1) {
+        callbacks.splice(idx, 1);
+      }
+
+      // If no more callbacks, unsubscribe the whole thing
+      if (callbacks.length === 0) {
+        subscription.unsubscribe();
+        singlePathSubscriptions.delete(subscriptionKey);
+      }
+    }
+  };
 }
 
 /**
- * Subscribe to path prefix (multiple paths)
+ * Subscribe to path prefix (multiple paths).
  *
  * Subscribes to data events and uses Page Visibility API to refresh when tab becomes visible.
  * Note: Nostr relays do not broadcast replaceable event updates to active subscriptions.
@@ -516,8 +784,14 @@ export function nostrSubscribe(client, path, callback, options = {}) {
  * @param {Object} client - NostrClient instance
  * @param {string} pathPrefix - Path prefix to match
  * @param {Function} callback - Callback function (data, path, event) => void
- * @param {Object} options - Subscription options
+ * @param {Object} [options={}] - Subscription options
+ * @param {number} [options.kind=30000] - Event kind to subscribe to
  * @returns {Promise<Object>} Subscription object with unsubscribe method
+ * @example
+ * const sub = await nostrSubscribeMany(client, 'myapp/holon1/items/', (data, path, event) => {
+ *   console.log('Item event:', data);
+ * });
+ * // Later: sub.unsubscribe();
  */
 export async function nostrSubscribeMany(client, pathPrefix, callback, options = {}) {
   const kind = options.kind || 30000;
@@ -589,9 +863,15 @@ export async function nostrSubscribeMany(client, pathPrefix, callback, options =
 
     // Client-side prefix filter
     if (dTag && dTag.startsWith(pathPrefix)) {
-      acceptedCount++;
       try {
         const data = JSON.parse(event.content);
+
+        // Skip null/undefined data or deleted items - don't send tombstones to subscribers
+        if (!data || data._deleted) {
+          return;
+        }
+
+        acceptedCount++;
         // Notify all registered callbacks
         for (const cb of callbacks) {
           cb(data, dTag, event);
@@ -672,12 +952,16 @@ export async function nostrSubscribeMany(client, pathPrefix, callback, options =
 }
 
 /**
- * Update data (merge with existing)
+ * Update data (merge with existing).
+ *
  * @param {Object} client - NostrClient instance
  * @param {string} path - Path identifier
  * @param {Object} updates - Fields to update
- * @param {number} kind - Event kind (default: 30000)
+ * @param {number} [kind=30000] - Event kind (default: 30000)
  * @returns {Promise<Object>} Updated event result
+ * @throws {Error} If no data found at path
+ * @example
+ * await nostrUpdate(client, 'myapp/holon1/items/item1', { status: 'completed' });
  */
 export async function nostrUpdate(client, path, updates, kind = 30000) {
   // Read existing data
@@ -695,10 +979,11 @@ export async function nostrUpdate(client, path, updates, kind = 30000) {
 }
 
 /**
- * Batch read multiple paths
+ * Batch read multiple paths.
+ *
  * @param {Object} client - NostrClient instance
  * @param {string[]} paths - Array of paths
- * @param {number} kind - Event kind (default: 30000)
+ * @param {number} [kind=30000] - Event kind (default: 30000)
  * @returns {Promise<Object>} Object mapping paths to data
  */
 export async function nostrBatchGet(client, paths, kind = 30000) {
@@ -739,10 +1024,11 @@ export async function nostrBatchGet(client, paths, kind = 30000) {
 }
 
 /**
- * Batch write multiple paths
+ * Batch write multiple paths.
+ *
  * @param {Object} client - NostrClient instance
  * @param {Object} pathDataMap - Object mapping paths to data
- * @param {number} kind - Event kind (default: 30000)
+ * @param {number} [kind=30000] - Event kind (default: 30000)
  * @returns {Promise<Array>} Array of publish results
  */
 export async function nostrBatchPut(client, pathDataMap, kind = 30000) {
@@ -754,11 +1040,13 @@ export async function nostrBatchPut(client, pathDataMap, kind = 30000) {
 }
 
 /**
- * Retry operation with exponential backoff
+ * Retry operation with exponential backoff.
+ *
  * @param {Function} operation - Async function to retry
- * @param {number} maxRetries - Max retry attempts (default: 3)
- * @param {number} baseDelay - Base delay in ms (default: 100ms)
+ * @param {number} [maxRetries=3] - Max retry attempts
+ * @param {number} [baseDelay=100] - Base delay in ms
  * @returns {Promise<any>} Promise resolving to operation result
+ * @throws {Error} Last error if all retries fail
  */
 export async function nostrRetry(operation, maxRetries = 3, baseDelay = 100) {
   let lastError;
@@ -779,12 +1067,14 @@ export async function nostrRetry(operation, maxRetries = 3, baseDelay = 100) {
 }
 
 /**
- * Wait for specific condition on data
+ * Wait for specific condition on data.
+ *
  * @param {Object} client - NostrClient instance
  * @param {string} path - Path to watch
  * @param {Function} predicate - Condition function (data) => boolean
- * @param {number} timeout - Timeout in ms (default: 5000ms)
+ * @param {number} [timeout=5000] - Timeout in ms
  * @returns {Promise<any>} Promise resolving when condition is met
+ * @throws {Error} If timeout occurs before condition is met
  */
 export async function nostrWaitFor(client, path, predicate, timeout = 5000) {
   return new Promise((resolve, reject) => {