holosphere 2.0.0-alpha8 → 2.0.0-alpha9

package/src/storage/gun-federation.js

@@ -1,19 +1,28 @@
 /**
- * GunDB Federation Module
- * Provides methods for creating, managing, and using federated spaces
+ * @fileoverview GunDB Federation Module.
  *
- * Ported from holosphere/federation.js to work with the GunDBBackend
+ * Provides methods for creating, managing, and using federated spaces.
+ * Supports data propagation with references for lightweight federation,
+ * aggregation across federated sources, and subscription to federated changes.
+ *
+ * Ported from holosphere/federation.js to work with the GunDBBackend.
+ *
+ * @module storage/gun-federation
  */
 
 /**
- * Creates a federation relationship between two spaces
+ * Creates a federation relationship between two spaces.
+ *
  * Federation is bidirectional by default, and data propagation uses soul references by default.
  *
  * @param {Object} backend - The GunDBBackend instance
  * @param {string} spaceId1 - The first space ID
  * @param {string} spaceId2 - The second space ID
- * @param {boolean} bidirectional - Whether to set up bidirectional notifications (default: true)
+ * @param {boolean} [bidirectional=true] - Whether to set up bidirectional notifications
  * @returns {Promise<boolean>} True if federation was created successfully
+ * @throws {Error} If space IDs are missing or identical
+ * @example
+ * await federate(backend, 'space1', 'space2');
  */
 export async function federate(backend, spaceId1, spaceId2, bidirectional = true) {
   if (!spaceId1 || !spaceId2) {

package/src/storage/gun-references.js

@@ -1,19 +1,30 @@
 /**
- * GunDB Reference Handler
- * Handles creation and resolution of data references for federation
+ * @fileoverview GunDB Reference Handler.
  *
+ * Handles creation and resolution of data references for federation.
  * References use a "soul" pattern: appname/holon/lens/key
- * This allows lightweight propagation without data duplication
+ * This allows lightweight propagation without data duplication.
+ *
+ * @module storage/gun-references
  */
 
 import { read } from './gun-wrapper.js';
 
 /**
- * Reference handler for GunDB backend
+ * Reference handler for GunDB backend.
+ *
+ * Manages creation, detection, and resolution of data references.
+ *
+ * @class GunReferenceHandler
+ * @example
+ * const handler = new GunReferenceHandler('myapp');
+ * const ref = handler.createReference('holon1', 'items', { id: '123', name: 'Test' });
+ * const resolved = await handler.resolveReference(gun, ref);
  */
 export class GunReferenceHandler {
   /**
-   * Create a new reference handler
+   * Create a new reference handler.
+   *
    * @param {string} appname - Application namespace
    */
   constructor(appname) {

package/src/storage/gun-schema.js

@@ -1,14 +1,20 @@
 /**
- * GunDB Schema Validator
- * Handles JSON Schema validation for data stored in GunDB
+ * @fileoverview GunDB Schema Validator.
  *
- * Schemas are stored in the global 'schemas' table
- * Validation uses AJV (Another JSON Schema Validator) with JSON Schema 2019
+ * Handles JSON Schema validation for data stored in GunDB.
+ * Schemas are stored in the global 'schemas' table.
+ * Validation uses AJV (Another JSON Schema Validator) with JSON Schema 2019.
+ *
+ * @module storage/gun-schema
  */
 
 import { writeGlobal, readGlobal, readAllGlobal, deleteGlobal } from './gun-wrapper.js';
 
-// Default meta-schema for validating schema definitions
+/**
+ * Default meta-schema for validating schema definitions.
+ * @private
+ * @constant {Object}
+ */
 const META_SCHEMA = {
   type: 'object',
   required: ['type'],
@@ -23,14 +29,23 @@ const META_SCHEMA = {
 };
 
 /**
- * Schema validator for GunDB backend
+ * Schema validator for GunDB backend.
+ *
+ * Provides JSON Schema validation with caching and lazy-loaded AJV.
+ *
+ * @class GunSchemaValidator
+ * @example
+ * const validator = new GunSchemaValidator({ strict: true });
+ * await validator.init();
+ * await validator.setSchema(gun, 'myapp', 'user', { type: 'object', properties: { name: { type: 'string' } } });
  */
 export class GunSchemaValidator {
   /**
-   * Create a new schema validator
-   * @param {Object} options - Validator options
-   * @param {boolean} options.strict - Whether to enforce strict validation (default: false)
-   * @param {number} options.cacheMaxAge - Schema cache TTL in ms (default: 3600000 = 1 hour)
+   * Create a new schema validator.
+   *
+   * @param {Object} [options={}] - Validator options
+   * @param {boolean} [options.strict=false] - Whether to enforce strict validation
+   * @param {number} [options.cacheMaxAge=3600000] - Schema cache TTL in ms (1 hour)
    */
   constructor(options = {}) {
     this.strict = options.strict || false;

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,17 +59,22 @@ 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, '/');
 }
 
 /**
- * Navigate to a Gun path using chained .get() calls
+ * 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"
@@ -73,24 +90,32 @@ function getGunPath(gun, path) {
 }
 
 /**
- * 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
+ * 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.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) {
@@ -160,11 +185,15 @@ 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 {
@@ -189,10 +218,14 @@ export async function write(gun, path, data) {
 }
 
 /**
- * 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 parts = path.split('/').filter(p => p.length > 0);
@@ -217,12 +250,17 @@ 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);
@@ -334,11 +372,14 @@ 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(getGunPath(gun, path));
@@ -368,10 +409,13 @@ 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 {
@@ -400,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 }
@@ -421,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
@@ -484,13 +535,18 @@ 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) {
@@ -502,7 +558,8 @@ export async function writeGlobal(gun, appname, tableName, 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
@@ -515,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) {
@@ -558,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
  */
@@ -570,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);