holosphere 2.0.0-alpha7 → 2.0.0-alpha9

package/src/storage/gun-wrapper.js

@@ -1,7 +1,11 @@
 /**
- * GunDB Storage Wrapper with radisk persistence
- * Handles path construction and CRUD operations
- * Note: GunDB doesn't handle nested objects well, so we store data as JSON strings
+ * @fileoverview GunDB Storage Wrapper with radisk persistence.
+ *
+ * Handles path construction and CRUD operations for GunDB storage backend.
+ * Note: GunDB doesn't handle nested objects well, so we store data as JSON strings.
+ * Provides both holon-specific paths and global table operations.
+ *
+ * @module storage/gun-wrapper
  */
 
 import { gunPromise, gunPut, gunCollect } from './gun-async.js';
@@ -11,12 +15,16 @@ import { gunPromise, gunPut, gunCollect } from './gun-async.js';
 // ============================================================================
 
 /**
- * Build Gun path from components
+ * Build Gun path from components.
+ *
  * @param {string} appname - Application namespace
  * @param {string} holon - Holon ID (H3 or URI)
  * @param {string} lens - Lens name
- * @param {string} key - Data key (optional)
+ * @param {string} [key=null] - Data key (optional)
  * @returns {string} Gun path
+ * @example
+ * const path = buildPath('myapp', 'holon123', 'items', 'item1');
+ * // Returns: 'myapp/holon123/items/item1'
  */
 export function buildPath(appname, holon, lens, key = null) {
   // Encode components to handle special characters
@@ -31,11 +39,15 @@ export function buildPath(appname, holon, lens, key = null) {
 }
 
 /**
- * Build Gun path for global tables (app-wide data not tied to holons)
+ * Build Gun path for global tables (app-wide data not tied to holons).
+ *
  * @param {string} appname - Application namespace
  * @param {string} tableName - Global table name (e.g., 'schemas', 'federation')
- * @param {string} key - Data key (optional)
+ * @param {string} [key=null] - Data key (optional)
  * @returns {string} Gun path
+ * @example
+ * const path = buildGlobalPath('myapp', 'schemas', 'user');
+ * // Returns: 'myapp/schemas/user'
  */
 export function buildGlobalPath(appname, tableName, key = null) {
   const encodedTable = encodePathComponent(tableName);
@@ -47,33 +59,63 @@ export function buildGlobalPath(appname, tableName, key = null) {
 }
 
 /**
- * Encode path component to handle special characters
+ * Encode path component to handle special characters.
+ *
  * @private
+ * @param {string} component - Component to encode
+ * @returns {string} Encoded component
  */
 function encodePathComponent(component) {
   return encodeURIComponent(component).replace(/%2F/g, '/');
 }
 
 /**
- * Serialize data for GunDB storage
- * Wraps data in { _json: string } format for Gun compatibility
- * Gun requires an object at graph roots, so we can't store raw JSON strings
- * The deserialization handles both this format and raw JSON strings for reading old data
+ * Navigate to a Gun path using chained .get() calls.
+ *
+ * Gun treats 'a/b/c' as a literal key, not a path.
+ * This function splits the path and chains .get() calls properly.
+ *
  * @private
+ * @param {Object} gun - Gun instance
+ * @param {string} path - Path string like "appname/holon/lens/key"
+ * @returns {Object} Gun chain reference at the path
+ */
+function getGunPath(gun, path) {
+  const parts = path.split('/').filter(p => p.length > 0);
+  let ref = gun;
+  for (const part of parts) {
+    ref = ref.get(part);
+  }
+  return ref;
+}
+
+/**
+ * Serialize data for GunDB storage.
+ *
+ * Stores data as raw JSON string for compatibility with holosphere original.
+ * This matches the format used in holosphere v1 for better interoperability.
+ *
+ * @private
+ * @param {Object} data - Data to serialize
+ * @returns {string} JSON string
  */
 function serializeForGun(data) {
-  return { _json: JSON.stringify(data) };
+  return JSON.stringify(data);
 }
 
 /**
- * Deserialize data from GunDB storage
+ * Deserialize data from GunDB storage.
+ *
  * Handles multiple formats:
  * - Direct JSON string (holosphere original - now default)
  * - _json wrapped format (holosphere2 legacy)
  * - Gun internal references (_["#"])
  * - Gun node data (_[">"])
  * - Plain objects
+ *
  * @private
+ * @param {*} data - Raw data from Gun
+ * @returns {Object|null} Parsed data or null
  */
 function deserializeFromGun(data) {
   if (!data) {
@@ -143,32 +185,55 @@ function deserializeFromGun(data) {
 }
 
 /**
- * Write data to Gun with radisk persistence
+ * Write data to Gun with radisk persistence.
+ *
  * @param {Object} gun - Gun instance
  * @param {string} path - Gun path
  * @param {Object} data - Data to write
- * @returns {Promise<boolean>} Success indicator
+ * @returns {Promise<Object>} Success object with ok and timeout flags
+ * @example
+ * const result = await write(gun, 'myapp/holon1/items/item1', { name: 'Test' });
+ * if (result.timeout) console.warn('Write may not be persisted');
  */
 export async function write(gun, path, data) {
   try {
     const serialized = serializeForGun(data);
-    await gunPut(gun.get(path), serialized, 2000);
-    // Delay to allow Gun to propagate the write (50ms for better reliability)
-    await new Promise(resolve => setTimeout(resolve, 50));
-    return true;
+    const parts = path.split('/').filter(p => p.length > 0);
+    console.log('[gun-wrapper] write:', { path, parts, dataId: data?.id });
+    const ref = getGunPath(gun, path);
+    console.log('[gun-wrapper] write ref soul:', ref?._.get);
+    const ack = await gunPut(ref, serialized, 5000); // Increased timeout from 2s to 5s
+    console.log('[gun-wrapper] write ack:', { ok: ack.ok, timeout: ack.timeout });
+    if (ack.timeout) {
+      console.warn('[gun-wrapper] write timed out (data may not be persisted):', path);
+    }
+    console.log('[gun-wrapper] write complete:', path);
+
+    // Return ack info so caller can handle timeouts
+    return { ok: true, timeout: ack.timeout || false };
   } catch (error) {
+    console.error('[gun-wrapper] write error:', error);
     throw error;
   }
 }
 
 /**
- * Read data from Gun
+ * Read data from Gun.
+ *
  * @param {Object} gun - Gun instance
  * @param {string} path - Gun path
- * @returns {Promise<Object|null>} Data or null if not found
+ * @returns {Promise<Object|null>} Data or null if not found or deleted
+ * @example
+ * const data = await read(gun, 'myapp/holon1/items/item1');
+ * if (data) console.log(data.name);
  */
 export async function read(gun, path) {
-  const rawData = await gunPromise(gun.get(path), 2000);
+  const parts = path.split('/').filter(p => p.length > 0);
+  console.log('[gun-wrapper] read:', { path, parts });
+  const ref = getGunPath(gun, path);
+  console.log('[gun-wrapper] read ref soul:', ref?._.get);
+  const rawData = await gunPromise(ref, 2000);
+  console.log('[gun-wrapper] read rawData:', rawData ? (typeof rawData === 'string' ? rawData.substring(0, 100) : 'object') : 'null');
 
   if (!rawData) {
     return null;
@@ -185,26 +250,36 @@ export async function read(gun, path) {
 }
 
 /**
- * Read all data under a path (lens query)
- * First gets the count of expected items, then collects until count is reached
+ * Read all data under a path (lens query).
+ *
+ * First gets the count of expected items, then collects until count is reached.
+ *
  * @param {Object} gun - Gun instance
  * @param {string} path - Gun path
- * @param {number} timeout - Maximum timeout in ms (default 5000)
+ * @param {number} [timeout=5000] - Maximum timeout in ms
  * @returns {Promise<Object[]>} Array of data objects
+ * @example
+ * const items = await readAll(gun, 'myapp/holon1/items');
+ * console.log(`Found ${items.length} items`);
  */
 export async function readAll(gun, path, timeout = 5000) {
+  const parts = path.split('/').filter(p => p.length > 0);
+  console.log('[gun-wrapper] readAll:', { path, parts });
+
   return new Promise((resolve) => {
     const output = new Map();
     let settled = false;
     let expectedCount = 0;
     let receivedCount = 0;
 
-    const ref = gun.get(path);
+    const ref = getGunPath(gun, path);
+    console.log('[gun-wrapper] readAll ref soul:', ref?._.get);
 
     const tryResolve = () => {
       if (settled) return;
       if (expectedCount > 0 && receivedCount >= expectedCount) {
         settled = true;
+        console.log('[gun-wrapper] readAll resolved with', output.size, 'items');
         resolve(Array.from(output.values()));
       }
     };
@@ -216,18 +291,24 @@ export async function readAll(gun, path, timeout = 5000) {
     // Step 1: Get the parent data to count expected items
     ref.once((parentData) => {
       if (settled) return;
+      console.log('[gun-wrapper] readAll parentData:', parentData);
+      console.log('[gun-wrapper] readAll parentData keys:', parentData ? Object.keys(parentData).filter(k => k !== '_') : 'null');
+      console.log('[gun-wrapper] readAll parentData type:', typeof parentData);
 
       if (!parentData) {
         settled = true;
+        console.log('[gun-wrapper] readAll: no parent data, returning empty');
         resolve([]);
         return;
       }
 
       // Get all keys except Gun metadata
       const keys = Object.keys(parentData).filter(k => k !== '_');
+      console.log('[gun-wrapper] readAll keys:', keys);
 
       if (keys.length === 0) {
         settled = true;
+        console.log('[gun-wrapper] readAll: no keys, returning empty');
         resolve([]);
         return;
       }
@@ -291,14 +372,17 @@ export async function readAll(gun, path, timeout = 5000) {
 }
 
 /**
- * Update data (merge fields)
+ * Update data (merge fields).
+ *
  * @param {Object} gun - Gun instance
  * @param {string} path - Gun path
  * @param {Object} updates - Fields to update
  * @returns {Promise<boolean>} Success indicator
+ * @example
+ * const success = await update(gun, 'myapp/holon1/items/item1', { status: 'active' });
  */
 export async function update(gun, path, updates) {
-  const rawData = await gunPromise(gun.get(path));
+  const rawData = await gunPromise(getGunPath(gun, path));
 
   if (!rawData) {
     return false; // Not found
@@ -315,7 +399,9 @@ export async function update(gun, path, updates) {
 
   try {
     const serialized = serializeForGun(merged);
-    await gunPut(gun.get(path), serialized);
+    await gunPut(getGunPath(gun, path), serialized, 2000);
+    // Add delay for propagation
+    await new Promise(resolve => setTimeout(resolve, 200));
     return true;
   } catch (error) {
     throw error;
@@ -323,15 +409,18 @@ export async function update(gun, path, updates) {
 }
 
 /**
- * Delete data (tombstone)
+ * Delete data (tombstone).
+ *
  * @param {Object} gun - Gun instance
  * @param {string} path - Gun path
  * @returns {Promise<boolean>} Success indicator
+ * @example
+ * const deleted = await deleteData(gun, 'myapp/holon1/items/item1');
  */
 export async function deleteData(gun, path) {
   try {
     // First read existing data to get the id
-    const rawData = await gunPromise(gun.get(path));
+    const rawData = await gunPromise(getGunPath(gun, path));
     if (!rawData) {
       return true; // Already deleted/doesn't exist
     }
@@ -345,7 +434,9 @@ export async function deleteData(gun, path) {
       _deletedAt: Date.now()
     };
 
-    await gunPut(gun.get(path), serializeForGun(tombstone));
+    await gunPut(getGunPath(gun, path), serializeForGun(tombstone), 2000);
+    // Add delay for propagation
+    await new Promise(resolve => setTimeout(resolve, 200));
     return true;
   } catch (error) {
     throw error;
@@ -353,7 +444,8 @@ export async function deleteData(gun, path) {
 }
 
 /**
- * Delete all data under path prefix (tombstone)
+ * Delete all data under path prefix (tombstone).
+ *
  * @param {Object} gun - Gun instance
  * @param {string} path - Gun path prefix
  * @returns {Promise<Object>} Deletion results { success: boolean, count: number }
@@ -374,13 +466,19 @@ export async function deleteAll(gun, path) {
 }
 
 /**
- * Subscribe to data changes
+ * Subscribe to data changes.
+ *
  * @param {Object} gun - Gun instance
  * @param {string} path - Gun path
- * @param {Function} callback - Called on data changes
- * @param {Object} options - Subscription options
- * @param {boolean} options.prefix - Subscribe to all items under path (default: auto-detect)
+ * @param {Function} callback - Called on data changes (data, key) => void
+ * @param {Object} [options={}] - Subscription options
+ * @param {boolean} [options.prefix] - Subscribe to all items under path (default: auto-detect)
  * @returns {Object} Subscription object with unsubscribe method
+ * @example
+ * const sub = subscribe(gun, 'myapp/holon1/items', (data, key) => {
+ *   console.log('Item changed:', key, data);
+ * });
+ * // Later: sub.unsubscribe();
  */
 export function subscribe(gun, path, callback, options = {}) {
   // Detect if this is a prefix subscription
@@ -389,7 +487,7 @@ export function subscribe(gun, path, callback, options = {}) {
 
   if (isPrefix) {
     // Subscribe to all items under this prefix
-    const ref = gun.get(path);
+    const ref = getGunPath(gun, path);
 
     ref.map().on((data, key) => {
       if (data && !key.startsWith('_')) {
@@ -411,7 +509,7 @@ export function subscribe(gun, path, callback, options = {}) {
     };
   } else {
     // Subscribe to single item
-    const listener = gun.get(path).on((data, key) => {
+    const listener = getGunPath(gun, path).on((data, key) => {
       if (data) {
         const deserialized = deserializeFromGun(data);
         if (deserialized && !deserialized._deleted) {
@@ -437,24 +535,31 @@ export function subscribe(gun, path, callback, options = {}) {
 // ============================================================================
 
 /**
- * Write data to a global table
- * Global tables are app-wide data not tied to specific holons (e.g., schemas, federation)
+ * Write data to a global table.
+ *
+ * Global tables are app-wide data not tied to specific holons (e.g., schemas, federation).
+ *
  * @param {Object} gun - Gun instance
  * @param {string} appname - Application namespace
  * @param {string} tableName - Global table name
  * @param {Object} data - Data to write (must have 'id' field)
- * @returns {Promise<boolean>} Success indicator
+ * @returns {Promise<Object>} Success object with ok and timeout flags
+ * @throws {Error} If data doesn't have an id field
+ * @example
+ * await writeGlobal(gun, 'myapp', 'schemas', { id: 'user', type: 'object' });
  */
 export async function writeGlobal(gun, appname, tableName, data) {
   if (!data || !data.id) {
     throw new Error('writeGlobal: data must have an id field');
   }
   const path = buildGlobalPath(appname, tableName, data.id);
+  // Use write function which includes the propagation delay
   return write(gun, path, data);
 }
 
 /**
- * Read data from a global table
+ * Read data from a global table.
+ *
  * @param {Object} gun - Gun instance
  * @param {string} appname - Application namespace
  * @param {string} tableName - Global table name
@@ -467,12 +572,14 @@ export async function readGlobal(gun, appname, tableName, key) {
 }
 
 /**
- * Read all data from a global table
- * Uses same approach as readAll
+ * Read all data from a global table.
+ *
+ * Uses same approach as readAll.
+ *
  * @param {Object} gun - Gun instance
  * @param {string} appname - Application namespace
  * @param {string} tableName - Global table name
- * @param {number} timeout - Timeout in ms (default: 2000)
+ * @param {number} [timeout=2000] - Timeout in ms
  * @returns {Promise<Object[]>} Array of data objects
  */
 export async function readAllGlobal(gun, appname, tableName, timeout = 2000) {
@@ -510,10 +617,13 @@ export async function deleteAllGlobal(gun, appname, tableName) {
 // ============================================================================
 
 /**
- * Parse data from Gun storage, handling various formats
+ * Parse data from Gun storage, handling various formats.
+ *
+ * Handles:
  * - JSON string in _json field
  * - Legacy object format
  * - Gun references
+ *
  * @param {*} rawData - Raw data from Gun
  * @returns {Object|null} Parsed data or null
  */
@@ -522,7 +632,8 @@ export function parse(rawData) {
 }
 
 /**
- * Serialize data for Gun storage
+ * Serialize data for Gun storage.
+ *
  * @param {Object} data - Data to serialize
  * @returns {string} JSON string
  */

package/src/storage/indexeddb-storage.js

@@ -1,20 +1,48 @@
 /**
- * IndexedDB storage adapter for browsers
- * Provides persistent storage with good performance
+ * @fileoverview IndexedDB storage adapter for browsers.
+ *
+ * Provides persistent storage with good performance using browser IndexedDB.
+ * Uses B-tree indexes for efficient prefix queries.
+ *
+ * @module storage/indexeddb-storage
  */
 
 import { PersistentStorage } from './persistent-storage.js';
 
+/**
+ * IndexedDB storage adapter for browsers.
+ *
+ * Provides high-performance persistent storage using IndexedDB with efficient prefix queries.
+ *
+ * @class IndexedDBStorage
+ * @extends PersistentStorage
+ * @example
+ * const storage = new IndexedDBStorage();
+ * await storage.init('myapp');
+ * await storage.put('key1', { id: 'event1', content: 'test' });
+ */
 export class IndexedDBStorage extends PersistentStorage {
+  /**
+   * Create a new IndexedDBStorage instance.
+   */
   constructor() {
     super();
     /** @type {IDBDatabase|null} */
     this.db = null;
     /** @type {string} */
     this.dbName = '';
+    /** @type {string} */
     this.storeName = 'events';
   }
 
+  /**
+   * Initialize storage with namespace.
+   *
+   * Creates or opens the IndexedDB database and object store.
+   *
+   * @param {string} namespace - Storage namespace
+   * @returns {Promise<void>}
+   */
   async init(namespace) {
     this.dbName = `holosphere_${namespace}`;
 
@@ -41,6 +69,13 @@ export class IndexedDBStorage extends PersistentStorage {
     });
   }
 
+  /**
+   * Store an event.
+   *
+   * @param {string} key - Storage key
+   * @param {Object} event - Event data
+   * @returns {Promise<void>}
+   */
   async put(key, event) {
     return new Promise((resolve, reject) => {
       if (!this.db) {
@@ -57,6 +92,12 @@ export class IndexedDBStorage extends PersistentStorage {
     });
   }
 
+  /**
+   * Retrieve an event.
+   *
+   * @param {string} key - Storage key
+   * @returns {Promise<Object|null>} Event data or null
+   */
   async get(key) {
     return new Promise((resolve, reject) => {
       if (!this.db) {
@@ -77,8 +118,12 @@ export class IndexedDBStorage extends PersistentStorage {
   }
 
   /**
-   * @param {string} prefix
-   * @returns {Promise<any[]>}
+   * Retrieve all events matching a prefix.
+   *
+   * Uses IDBKeyRange for efficient B-tree index queries.
+   *
+   * @param {string} prefix - Key prefix to match
+   * @returns {Promise<any[]>} Array of matching events
    */
   async getAll(prefix) {
     return new Promise((resolve, reject) => {
@@ -119,6 +164,12 @@ export class IndexedDBStorage extends PersistentStorage {
     });
   }
 
+  /**
+   * Delete an event.
+   *
+   * @param {string} key - Storage key
+   * @returns {Promise<void>}
+   */
   async delete(key) {
     return new Promise((resolve, reject) => {
       if (!this.db) {
@@ -135,6 +186,11 @@ export class IndexedDBStorage extends PersistentStorage {
     });
   }
 
+  /**
+   * Clear all stored events.
+   *
+   * @returns {Promise<void>}
+   */
   async clear() {
     return new Promise((resolve, reject) => {
       if (!this.db) {
@@ -151,6 +207,11 @@ export class IndexedDBStorage extends PersistentStorage {
     });
   }
 
+  /**
+   * Close the database connection.
+   *
+   * @returns {Promise<void>}
+   */
   async close() {
     if (this.db) {
       this.db.close();

package/src/storage/key-storage-simple.js

@@ -1,9 +1,11 @@
 /**
- * Simple Key Storage for Node.js
- * Basic filesystem-based key management
+ * @fileoverview Simple Key Storage for Node.js.
  *
- * NOTE: This only works in Node.js, not browsers
- * For browsers, keys are managed in localStorage
+ * Basic filesystem-based key management.
+ * NOTE: This only works in Node.js, not browsers.
+ * For browsers, keys are managed in localStorage.
+ *
+ * @module storage/key-storage-simple
  */
 
 import fs from 'fs';
@@ -11,7 +13,10 @@ import path from 'path';
 import os from 'os';
 
 /**
- * Get key storage directory
+ * Get key storage directory.
+ *
+ * @private
+ * @returns {string} Key storage directory path
  */
 function getKeyDir() {
   const configDir = process.env.XDG_CONFIG_HOME ||
@@ -23,7 +28,11 @@ function getKeyDir() {
 }
 
 /**
- * Get key file path for an app
+ * Get key file path for an app.
+ *
+ * @private
+ * @param {string} appName - Application name
+ * @returns {string} Full path to key file
  */
 function getKeyPath(appName) {
   const safeName = appName.replace(/[^a-zA-Z0-9-_]/g, '_');
@@ -31,7 +40,10 @@ function getKeyPath(appName) {
 }
 
 /**
- * Load private key
+ * Load private key from filesystem.
+ *
+ * @param {string} appName - Application name
+ * @returns {string|null} Private key (hex) or null if not found
  */
 export function loadKey(appName) {
   const keyPath = getKeyPath(appName);
@@ -45,7 +57,12 @@ export function loadKey(appName) {
 }
 
 /**
- * Save private key
+ * Save private key to filesystem with secure permissions.
+ *
+ * @param {string} appName - Application name
+ * @param {string} privateKey - Private key (64-character hex string)
+ * @returns {string} Path where key was saved
+ * @throws {Error} If private key format is invalid
  */
 export function saveKey(appName, privateKey) {
   if (!/^[0-9a-f]{64}$/i.test(privateKey)) {
@@ -64,7 +81,13 @@ export function saveKey(appName, privateKey) {
 }
 
 /**
- * Get or create key
+ * Get or create private key.
+ *
+ * Loads existing key or generates and saves a new one.
+ *
+ * @param {string} appName - Application name
+ * @param {Function} generateFn - Function to generate new key (returns hex string)
+ * @returns {string} Private key (hex)
  */
 export function getOrCreateKey(appName, generateFn) {
   const existing = loadKey(appName);