holosphere 2.0.0-alpha7 → 2.0.0-alpha9

package/src/index.js

@@ -1,6 +1,14 @@
 /**
- * HoloSphere - Holonic Geospatial Communication Infrastructure
- * Public API
+ * @fileoverview HoloSphere - Holonic Geospatial Communication Infrastructure
+ *
+ * This is the main entry point for the HoloSphere library, providing a comprehensive
+ * distributed P2P geospatial communication system. It combines H3 hexagonal indexing
+ * for spatial organization, Nostr protocol for distributed storage, smart contracts
+ * for fund distribution, and AI services for intelligent data processing.
+ *
+ * @module holosphere
+ * @author HoloSphere Team
+ * @license MIT
  */
 
 import { HoloSphere as HoloSphereCore } from './core/holosphere.js';
@@ -51,16 +59,36 @@ import { withFederationMethods } from './lib/federation-methods.js';
 import { AuthorizationError } from './lib/errors.js';
 
 /**
- * Base HoloSphere class with core data operations
+ * Base HoloSphere class with core data operations.
+ * Extends HoloSphereCore with schema validation, caching, subscriptions, and AI capabilities.
+ *
+ * @class HoloSphereBase
+ * @extends HoloSphereCore
  */
 class HoloSphereBase extends HoloSphereCore {
+  /**
+   * Creates a new HoloSphereBase instance.
+   *
+   * @param {Object} config - Configuration options
+   * @param {string} config.appName - Application namespace for data isolation
+   * @param {string} [config.backend='nostr'] - Storage backend type ('nostr', 'gundb', 'activitypub')
+   * @param {string[]} [config.relays] - Nostr relay URLs for distributed storage
+   * @param {string} [config.openaiKey] - OpenAI API key for AI services
+   * @param {Object} [config.aiOptions] - AI service configuration
+   * @param {string} [config.aiOptions.model] - OpenAI model to use
+   * @param {number} [config.aiOptions.temperature] - Temperature for AI responses
+   */
   constructor(config) {
     super(config);
+    /** @type {Map<string, {schema: Object, strict: boolean, timestamp: number}>} */
     this.schemas = new Map();
+    /** @type {Map<string, any>} */
     this._cache = new Map();
+    /** @type {subscriptions.SubscriptionRegistry} */
     this.subscriptionRegistry = new subscriptions.SubscriptionRegistry();
 
     // Initialize AI services if openaiKey is provided or OPENAI_API_KEY env var is set
+    /** @type {Object|null} */
     this._ai = null;
     const openaiKey = config.openaiKey || this._getEnv('OPENAI_API_KEY');
     if (openaiKey) {
@@ -73,9 +101,17 @@ class HoloSphereBase extends HoloSphereCore {
     }
 
     // Contracts module (lazy initialized)
+    /** @type {Object|null} */
     this._contracts = null;
   }
 
+  /**
+   * Gets an environment variable value (Node.js only).
+   *
+   * @private
+   * @param {string} name - Environment variable name
+   * @returns {string|undefined} Environment variable value or undefined
+   */
   _getEnv(name) {
     if (typeof process !== 'undefined' && process.env) {
       return process.env[name];
@@ -83,12 +119,28 @@ class HoloSphereBase extends HoloSphereCore {
     return undefined;
   }
 
+  /**
+   * Parses a string value to a float.
+   *
+   * @private
+   * @param {string|undefined|null} value - Value to parse
+   * @returns {number|undefined} Parsed float or undefined if invalid
+   */
   _parseFloat(value) {
     if (value === undefined || value === null) return undefined;
     const parsed = parseFloat(value);
     return isNaN(parsed) ? undefined : parsed;
   }
 
+  /**
+   * Initializes AI services with the provided API key.
+   *
+   * @private
+   * @param {string} apiKey - OpenAI API key
+   * @param {Object} [options={}] - AI configuration options
+   * @param {string} [options.model] - OpenAI model to use
+   * @param {number} [options.temperature] - Temperature for AI responses
+   */
   _initializeAI(apiKey, options = {}) {
     const llmOptions = {
       ...options.llm,
@@ -119,33 +171,87 @@ class HoloSphereBase extends HoloSphereCore {
     this._ai.h3ai = new H3AI(this._ai.llm, this);
   }
 
+  /**
+   * Checks if AI services are initialized.
+   *
+   * @returns {boolean} True if AI services are available
+   */
   hasAI() {
     return this._ai !== null;
   }
 
+  /**
+   * Gets the initialized AI services object.
+   *
+   * @returns {Object|null} AI services object containing llm, embeddings, etc., or null if not initialized
+   */
   getAIServices() {
     return this._ai;
   }
 
   // === Spatial Operations ===
+
+  /**
+   * Converts geographic coordinates to an H3 holon ID.
+   *
+   * @param {number} lat - Latitude (-90 to 90)
+   * @param {number} lng - Longitude (-180 to 180)
+   * @param {number} resolution - H3 resolution level (0-15)
+   * @returns {Promise<string>} H3 cell ID representing the holon
+   */
   async toHolon(lat, lng, resolution) {
     return spatial.toHolon(lat, lng, resolution);
   }
 
+  /**
+   * Gets all parent holons at higher resolutions.
+   *
+   * @param {string} holonId - H3 cell ID
+   * @param {number} [maxResolution] - Maximum resolution to traverse up to
+   * @returns {Promise<string[]>} Array of parent H3 cell IDs
+   */
   async getParents(holonId, maxResolution) {
     return spatial.getParents(holonId, maxResolution);
   }
 
+  /**
+   * Gets all child holons at the next resolution level.
+   *
+   * @param {string} holonId - H3 cell ID
+   * @returns {Promise<string[]>} Array of child H3 cell IDs
+   */
   async getChildren(holonId) {
     return spatial.getChildren(holonId);
   }
 
+  /**
+   * Validates if a string is a valid H3 cell ID.
+   *
+   * @param {string} holonId - String to validate
+   * @returns {boolean} True if valid H3 cell ID
+   */
   isValidH3(holonId) {
     return spatial.isValidH3(holonId);
   }
 
   // === Data Operations ===
 
+  /**
+   * Writes data to a specific holon and lens.
+   *
+   * @param {string} holonId - H3 cell ID for the holon
+   * @param {string} lensName - Name of the lens (data category)
+   * @param {Object} data - Data object to write (must have or will be assigned an id)
+   * @param {Object} [options={}] - Write options
+   * @param {string} [options.capabilityToken] - Capability token for authorization
+   * @param {boolean} [options.validate=true] - Whether to validate against schema
+   * @param {boolean} [options.strict] - Override schema strict mode
+   * @param {boolean} [options.autoPropagate=true] - Whether to propagate to federated holons
+   * @param {Object} [options.propagationOptions] - Options for propagation
+   * @returns {Promise<boolean>} True if write succeeded
+   * @throws {ValidationError} If holonId, lensName, or data is invalid
+   * @throws {AuthorizationError} If capability token is invalid
+   */
   async write(holonId, lensName, data, options = {}) {
     if (!holonId || typeof holonId !== 'string') {
       throw new ValidationError('ValidationError: holonId must be a non-empty string');
@@ -170,6 +276,7 @@ class HoloSphereBase extends HoloSphereCore {
     }
 
     const path = storage.buildPath(this.config.appName, holonId, lensName, data.id);
+    this._log('DEBUG', 'write', { holonId, lensName, dataId: data.id, path });
     const existingData = await storage.read(this.client, path);
 
     // Handle hologram writes
@@ -264,6 +371,15 @@ class HoloSphereBase extends HoloSphereCore {
     return true;
   }
 
+  /**
+   * Recursively resolves holograms (references) to their source data.
+   * Handles circular reference detection and local overrides.
+   *
+   * @private
+   * @param {Object|Array|null} data - Data that may contain holograms
+   * @param {Set<string>} [visited=new Set()] - Set of visited paths for circular detection
+   * @returns {Promise<Object|Array|null>} Resolved data with holograms replaced by source data
+   */
   async _resolveHolograms(data, visited = new Set()) {
     if (!data) return data;
 
@@ -286,10 +402,17 @@ class HoloSphereBase extends HoloSphereCore {
           data.target.lensName,
           data.target.dataId
         );
+        this._log('DEBUG', 'resolving hologram', {
+          hologramId: data.id,
+          sourcePath,
+          targetHolon: data.target.holonId,
+          targetLens: data.target.lensName,
+          targetDataId: data.target.dataId
+        });
 
         // Circular reference detection
         if (visited.has(sourcePath)) {
-          console.warn(`Circular hologram reference detected: ${sourcePath}`);
+          this._log('WARN', 'Circular hologram reference detected', { sourcePath });
           return null;
         }
         visited.add(sourcePath);
@@ -301,6 +424,7 @@ class HoloSphereBase extends HoloSphereCore {
         }
 
         const sourceData = await storage.read(this.client, sourcePath, resolveOptions);
+        this._log('DEBUG', 'hologram source fetched', { found: !!sourceData, sourcePath });
         if (sourceData) {
           // If source is also a hologram, recursively resolve it
           let resolvedSource = sourceData;
@@ -348,6 +472,19 @@ class HoloSphereBase extends HoloSphereCore {
     return data;
   }
 
+  /**
+   * Reads data from a specific holon and lens.
+   *
+   * @param {string} holonId - H3 cell ID for the holon
+   * @param {string} lensName - Name of the lens (data category)
+   * @param {string|null} [dataId=null] - Specific data ID, or null to read all
+   * @param {Object} [options={}] - Read options
+   * @param {string} [options.capabilityToken] - Capability token for authorization
+   * @param {boolean} [options.resolveHolograms=true] - Whether to resolve hologram references
+   * @returns {Promise<Object|Array|null>} Data object, array of objects, or null if not found
+   * @throws {ValidationError} If holonId or lensName is invalid
+   * @throws {AuthorizationError} If capability token is invalid
+   */
   async read(holonId, lensName, dataId = null, options = {}) {
     if (!holonId || typeof holonId !== 'string') {
       throw new ValidationError('ValidationError: holonId must be a non-empty string');
@@ -369,14 +506,19 @@ class HoloSphereBase extends HoloSphereCore {
 
     if (dataId) {
       const path = storage.buildPath(this.config.appName, holonId, lensName, dataId);
+      this._log('DEBUG', 'read', { holonId, lensName, dataId, path });
       result = await storage.read(this.client, path);
+      this._log('DEBUG', 'read result', { found: !!result, isHologram: result?.hologram === true });
     } else {
       const path = storage.buildPath(this.config.appName, holonId, lensName);
+      this._log('DEBUG', 'readAll', { holonId, lensName, path });
       result = await storage.readAll(this.client, path);
+      this._log('DEBUG', 'readAll result', { count: Array.isArray(result) ? result.length : 0 });
     }
 
     const { resolveHolograms = true } = options;
-    if (resolveHolograms) {
+    if (resolveHolograms && result) {
+      this._log('DEBUG', 'resolving holograms', { itemCount: Array.isArray(result) ? result.length : 1 });
       result = await this._resolveHolograms(result);
     }
 
@@ -388,6 +530,21 @@ class HoloSphereBase extends HoloSphereCore {
     return result;
   }
 
+  /**
+   * Updates existing data in a specific holon and lens.
+   *
+   * @param {string} holonId - H3 cell ID for the holon
+   * @param {string} lensName - Name of the lens (data category)
+   * @param {string} dataId - ID of the data to update
+   * @param {Object} updates - Object containing fields to update
+   * @param {Object} [options={}] - Update options
+   * @param {string} [options.capabilityToken] - Capability token for authorization
+   * @param {boolean} [options.validate=true] - Whether to validate against schema
+   * @param {boolean} [options.strict] - Override schema strict mode
+   * @returns {Promise<boolean>} True if update succeeded, false if data not found
+   * @throws {ValidationError} If holonId, lensName, dataId, or updates is invalid
+   * @throws {AuthorizationError} If capability token is invalid
+   */
   async update(holonId, lensName, dataId, updates, options = {}) {
     if (!holonId || typeof holonId !== 'string') {
       throw new ValidationError('ValidationError: holonId must be a non-empty string');
@@ -449,6 +606,18 @@ class HoloSphereBase extends HoloSphereCore {
     return true;
   }
 
+  /**
+   * Deletes data from a specific holon and lens.
+   *
+   * @param {string} holonId - H3 cell ID for the holon
+   * @param {string} lensName - Name of the lens (data category)
+   * @param {string} dataId - ID of the data to delete
+   * @param {Object} [options={}] - Delete options
+   * @param {string} [options.capabilityToken] - Capability token for authorization
+   * @returns {Promise<boolean>} True if deletion succeeded, false if data not found
+   * @throws {ValidationError} If holonId, lensName, or dataId is invalid
+   * @throws {AuthorizationError} If not owner and no valid capability token
+   */
   async delete(holonId, lensName, dataId, options = {}) {
     if (!holonId || typeof holonId !== 'string') {
       throw new ValidationError('ValidationError: holonId must be a non-empty string');
@@ -500,41 +669,108 @@ class HoloSphereBase extends HoloSphereCore {
   }
 
   // === Global Tables ===
+
+  /**
+   * Writes data to a global table (not holon-specific).
+   *
+   * @param {string} table - Name of the global table
+   * @param {Object} data - Data object to write (must have an id field)
+   * @returns {Promise<boolean>} True if write succeeded
+   */
   async writeGlobal(table, data) {
     return globalTables.writeGlobal(this.client, this.config.appName, table, data);
   }
 
+  /**
+   * Reads data from a global table.
+   *
+   * @param {string} table - Name of the global table
+   * @param {string|null} [key=null] - Specific key to read, or null to read all
+   * @returns {Promise<Object|Array|null>} Data object, array of objects, or null
+   */
   async readGlobal(table, key = null) {
     return globalTables.readGlobal(this.client, this.config.appName, table, key);
   }
 
+  /**
+   * Updates data in a global table.
+   *
+   * @param {string} table - Name of the global table
+   * @param {string} key - Key of the data to update
+   * @param {Object} updates - Object containing fields to update
+   * @returns {Promise<boolean>} True if update succeeded
+   */
   async updateGlobal(table, key, updates) {
     return globalTables.updateGlobal(this.client, this.config.appName, table, key, updates);
   }
 
+  /**
+   * Deletes data from a global table.
+   *
+   * @param {string} table - Name of the global table
+   * @param {string} key - Key of the data to delete
+   * @returns {Promise<boolean>} True if deletion succeeded
+   */
   async deleteGlobal(table, key) {
     return globalTables.deleteGlobal(this.client, this.config.appName, table, key);
   }
 
+  /**
+   * Gets all data from a global table.
+   *
+   * @param {string} table - Name of the global table
+   * @returns {Promise<Array>} Array of all data objects in the table
+   */
   async getAllGlobal(table) {
     return globalTables.getAllGlobal(this.client, this.config.appName, table);
   }
 
+  /**
+   * Deletes all data from a global table.
+   *
+   * @param {string} table - Name of the global table
+   * @returns {Promise<boolean>} True if deletion succeeded
+   */
   async deleteAllGlobal(table) {
     return globalTables.deleteAllGlobal(this.client, this.config.appName, table);
   }
 
   // === Batch Operations ===
+
+  /**
+   * Gets all data from a specific holon and lens.
+   *
+   * @param {string} holonId - H3 cell ID for the holon
+   * @param {string} lensName - Name of the lens (data category)
+   * @returns {Promise<Array|null>} Array of data objects or null
+   */
   async getAll(holonId, lensName) {
     return this.read(holonId, lensName, null);
   }
 
+  /**
+   * Deletes all data from a specific holon and lens.
+   *
+   * @param {string} holonId - H3 cell ID for the holon
+   * @param {string} lensName - Name of the lens (data category)
+   * @returns {Promise<boolean>} True if deletion succeeded
+   */
   async deleteAll(holonId, lensName) {
     const path = storage.buildPath(this.config.appName, holonId, lensName);
     return storage.deleteAll(this.client, path);
   }
 
   // === Schema Operations ===
+
+  /**
+   * Sets a JSON Schema for validating data in a specific lens.
+   *
+   * @param {string} lensName - Name of the lens to associate the schema with
+   * @param {Object|string} schemaInput - JSON Schema object or URI reference
+   * @param {boolean} [strict=false] - If true, validation will reject additional properties
+   * @returns {Promise<void>}
+   * @throws {ValidationError} If lensName is invalid or schema format is invalid
+   */
   async setSchema(lensName, schemaInput, strict = false) {
     if (!lensName || typeof lensName !== 'string') {
       throw new ValidationError('ValidationError: lensName must be a non-empty string');
@@ -572,17 +808,44 @@ class HoloSphereBase extends HoloSphereCore {
     this.schemas.set(lensName, { schema: schemaObj, strict, timestamp: Date.now() });
   }
 
+  /**
+   * Gets the JSON Schema for a specific lens.
+   *
+   * @param {string} lensName - Name of the lens
+   * @returns {Promise<Object|null>} The schema object or null if not set
+   */
   async getSchema(lensName) {
     const schemaObj = this.schemas.get(lensName);
     return schemaObj ? schemaObj.schema : null;
   }
 
+  /**
+   * Clears the JSON Schema for a specific lens.
+   *
+   * @param {string} lensName - Name of the lens
+   * @returns {Promise<void>}
+   */
   async clearSchema(lensName) {
     this.schemas.delete(lensName);
     // Returns undefined for contract compliance
   }
 
   // === Federation Operations ===
+
+  /**
+   * Sets up federation between two holons for a specific lens.
+   * Federation enables data sharing and synchronization between holons.
+   *
+   * @param {string} sourceHolon - Source holon H3 cell ID
+   * @param {string} targetHolon - Target holon H3 cell ID
+   * @param {string} lensName - Name of the lens to federate
+   * @param {Object} [options={}] - Federation options
+   * @param {string} [options.direction='outbound'] - Direction: 'inbound', 'outbound', or 'bidirectional'
+   * @param {string} [options.mode='reference'] - Mode: 'reference' (hologram) or 'copy'
+   * @param {Function} [options.filter] - Filter function to select which data to federate
+   * @returns {Promise<boolean>} True if federation was set up successfully
+   * @throws {Error} If trying to federate a holon with itself or invalid direction
+   */
   async federate(sourceHolon, targetHolon, lensName, options = {}) {
     const { direction = 'outbound', mode = 'reference', filter = null } = options;
 
@@ -616,6 +879,18 @@ class HoloSphereBase extends HoloSphereCore {
     return true;
   }
 
+  /**
+   * Propagates existing data from one holon to another.
+   *
+   * @private
+   * @param {string} fromHolon - Source holon H3 cell ID
+   * @param {string} toHolon - Target holon H3 cell ID
+   * @param {string} lensName - Name of the lens
+   * @param {Object} [options={}] - Propagation options
+   * @param {string} [options.mode='reference'] - Mode: 'reference' or 'copy'
+   * @param {Function} [options.filter] - Filter function to select data
+   * @returns {Promise<void>}
+   */
   async _propagateExistingData(fromHolon, toHolon, lensName, options = {}) {
     const { mode = 'reference', filter = null } = options;
     const existingData = await this.read(fromHolon, lensName, null, { resolveHolograms: false });
@@ -639,6 +914,15 @@ class HoloSphereBase extends HoloSphereCore {
     }
   }
 
+  /**
+   * Gets federated data from a holon, optionally resolving holograms.
+   *
+   * @param {string} holonId - H3 cell ID for the holon
+   * @param {string} lensName - Name of the lens
+   * @param {Object} [options={}] - Options
+   * @param {boolean} [options.resolveHolograms=true] - Whether to resolve hologram references
+   * @returns {Promise<Array|null>} Array of data objects or null
+   */
   async getFederatedData(holonId, lensName, options = {}) {
     const { resolveHolograms = true } = options;
     const path = storage.buildPath(this.config.appName, holonId, lensName);
@@ -650,6 +934,14 @@ class HoloSphereBase extends HoloSphereCore {
     return this._resolveHolograms(data);
   }
 
+  /**
+   * Removes federation between two holons for a specific lens.
+   *
+   * @param {string} sourceHolon - Source holon H3 cell ID
+   * @param {string} targetHolon - Target holon H3 cell ID
+   * @param {string} lensName - Name of the lens
+   * @returns {Promise<boolean>} Always returns true (idempotent operation)
+   */
   async unfederate(sourceHolon, targetHolon, lensName) {
     // Remove federation config for this relationship - idempotent
     const configPath = storage.buildPath(this.config.appName, sourceHolon, lensName, '_federation');
@@ -661,6 +953,15 @@ class HoloSphereBase extends HoloSphereCore {
     return true;
   }
 
+  /**
+   * Updates local override values on a hologram.
+   *
+   * @param {string} holonId - H3 cell ID where the hologram exists
+   * @param {string} lensName - Name of the lens
+   * @param {string} dataId - ID of the hologram
+   * @param {Object} overrides - Object containing local override values
+   * @returns {Promise<boolean>} True if update succeeded
+   */
   async updateHologramOverrides(holonId, lensName, dataId, overrides) {
     return federation.updateHologramOverrides(
       this.client,
@@ -672,6 +973,15 @@ class HoloSphereBase extends HoloSphereCore {
     );
   }
 
+  /**
+   * Creates a hologram (reference) object structure.
+   *
+   * @param {string} sourceHolon - Source holon H3 cell ID where the original data lives
+   * @param {string} lensName - Name of the lens
+   * @param {Object} data - Data object containing the id to reference
+   * @param {string} [targetHolon=null] - Target holon for the hologram, defaults to sourceHolon
+   * @returns {Object} Hologram object structure
+   */
   createHologram(sourceHolon, lensName, data, targetHolon = null) {
     return federation.createHologram(
       sourceHolon,
@@ -682,6 +992,14 @@ class HoloSphereBase extends HoloSphereCore {
     );
   }
 
+  /**
+   * Gets all active holograms (references) pointing to a specific data item.
+   *
+   * @param {string} holonId - H3 cell ID of the source holon
+   * @param {string} lensName - Name of the lens
+   * @param {string} dataId - ID of the source data
+   * @returns {Promise<Array>} Array of active hologram references
+   */
   async getActiveHolograms(holonId, lensName, dataId) {
     // Read the source data and return its activeHolograms list
     const path = storage.buildPath(this.config.appName, holonId, lensName, dataId);
@@ -692,6 +1010,15 @@ class HoloSphereBase extends HoloSphereCore {
     return sourceData._meta.activeHolograms;
   }
 
+  /**
+   * Removes an active hologram reference from a source data item.
+   *
+   * @param {string} sourceHolon - Source holon H3 cell ID
+   * @param {string} lensName - Name of the lens
+   * @param {string} dataId - ID of the source data
+   * @param {string} targetHolon - Target holon where the hologram exists
+   * @returns {Promise<boolean>} True if removal succeeded
+   */
   async removeActiveHologram(sourceHolon, lensName, dataId, targetHolon) {
     return federation.removeActiveHologram(
       this.client,
@@ -703,6 +1030,15 @@ class HoloSphereBase extends HoloSphereCore {
     );
   }
 
+  /**
+   * Deletes a hologram and cleans up its references.
+   *
+   * @param {string} holonId - H3 cell ID where the hologram exists
+   * @param {string} lensName - Name of the lens
+   * @param {string} dataId - ID of the hologram to delete
+   * @param {Object} [options={}] - Delete options
+   * @returns {Promise<boolean>} True if deletion succeeded
+   */
   async deleteHologram(holonId, lensName, dataId, options = {}) {
     return federation.deleteHologram(
       this.client,
@@ -714,6 +1050,17 @@ class HoloSphereBase extends HoloSphereCore {
     );
   }
 
+  /**
+   * Propagates data from source holon to target holon.
+   *
+   * @param {Object} data - Data to propagate
+   * @param {string} sourceHolon - Source holon H3 cell ID
+   * @param {string} targetHolon - Target holon H3 cell ID
+   * @param {string} lensName - Name of the lens
+   * @param {Object} [options={}] - Propagation options
+   * @param {string} [options.mode='reference'] - Mode: 'reference' creates hologram, 'copy' duplicates data
+   * @returns {Promise<Object>} Result of propagation
+   */
   async propagateData(data, sourceHolon, targetHolon, lensName, options = {}) {
     // Extract mode from options, default to 'reference' for hologram creation
     const mode = options.mode || 'reference';
@@ -728,22 +1075,55 @@ class HoloSphereBase extends HoloSphereCore {
     );
   }
 
+  /**
+   * Resolves a hologram to its source data.
+   *
+   * @param {Object} hologram - Hologram object to resolve
+   * @param {Object} [options={}] - Resolution options
+   * @returns {Promise<Object|null>} Resolved data or null if source not found
+   */
   async resolveHologram(hologram, options = {}) {
     return federation.resolveHologram(this.client, hologram, new Set(), [], { ...options, appname: this.config.appName });
   }
 
+  /**
+   * Checks if an object is a hologram (unresolved reference).
+   *
+   * @param {Object} data - Data object to check
+   * @returns {boolean} True if the object is a hologram
+   */
   isHologram(data) {
     return federation.isHologram(data);
   }
 
+  /**
+   * Checks if an object is a resolved hologram (has _hologram metadata).
+   *
+   * @param {Object} data - Data object to check
+   * @returns {boolean} True if the object is a resolved hologram
+   */
   isResolvedHologram(data) {
     return federation.isResolvedHologram(data);
   }
 
+  /**
+   * Gets the source information from a hologram or resolved hologram.
+   *
+   * @param {Object} data - Hologram or resolved hologram object
+   * @returns {Object|null} Source information or null
+   */
   getHologramSource(data) {
     return federation.getHologramSource(data);
   }
 
+  /**
+   * Cleans up circular hologram references in a holon.
+   *
+   * @param {string} holonId - H3 cell ID of the holon
+   * @param {string} lensName - Name of the lens
+   * @param {Object} [options={}] - Cleanup options
+   * @returns {Promise<Object>} Cleanup results
+   */
   async cleanupCircularHolograms(holonId, lensName, options = {}) {
     return federation.cleanupCircularHolograms(
       this.client,
@@ -754,6 +1134,15 @@ class HoloSphereBase extends HoloSphereCore {
     );
   }
 
+  /**
+   * Cleans up circular hologram references for specific data IDs.
+   *
+   * @param {string} holonId - H3 cell ID of the holon
+   * @param {string} lensName - Name of the lens
+   * @param {string[]} dataIds - Array of data IDs to check
+   * @param {Object} [options={}] - Cleanup options
+   * @returns {Promise<Object>} Cleanup results
+   */
   async cleanupCircularHologramsByIds(holonId, lensName, dataIds, options = {}) {
     return federation.cleanupCircularHologramsByIds(
       this.client,
@@ -765,6 +1154,17 @@ class HoloSphereBase extends HoloSphereCore {
     );
   }
 
+  /**
+   * Propagates data to all federated holons.
+   *
+   * @param {string} holonId - Source holon H3 cell ID
+   * @param {string} lensName - Name of the lens
+   * @param {Object} data - Data to propagate
+   * @param {Object} [options={}] - Propagation options
+   * @param {boolean} [options.useHolograms=true] - Whether to create holograms
+   * @param {boolean} [options.resolveExisting=true] - Whether to resolve existing data
+   * @returns {Promise<Array|undefined>} Array of propagation results or undefined if no targets
+   */
   async propagate(holonId, lensName, data, options = {}) {
     const federationData = await this.getFederation(holonId);
     // getFederation returns an object with federated array, not an array directly
@@ -788,6 +1188,13 @@ class HoloSphereBase extends HoloSphereCore {
     return results;
   }
 
+  /**
+   * Gets the federation configuration for a holon.
+   *
+   * @param {string} holonId - H3 cell ID of the holon
+   * @returns {Promise<Object|null>} Federation configuration object or null
+   * @throws {Error} If holonId is not provided
+   */
   async getFederation(holonId) {
     if (!holonId) {
       throw new Error('getFederation: Missing holon ID');
@@ -808,8 +1215,22 @@ class HoloSphereBase extends HoloSphereCore {
     return data;
   }
 
+  /**
+   * Establishes a holon-level federation relationship.
+   *
+   * @param {string} sourceHolon - Source holon H3 cell ID
+   * @param {string} targetHolon - Target holon H3 cell ID
+   * @param {Object} [options={}] - Federation options
+   * @param {Object} [options.lensConfig] - Lens configuration for federation
+   * @param {string[]} [options.lensConfig.inbound] - Lenses for inbound federation
+   * @param {string[]} [options.lensConfig.outbound] - Lenses for outbound federation
+   * @param {string} [options.partnerName] - Human-readable name for the partner holon
+   * @param {boolean} [options.skipPropagation=false] - Skip propagating existing data
+   * @returns {Promise<boolean>} True if federation was established
+   * @throws {Error} If trying to federate a holon with itself
+   */
   async federateHolon(sourceHolon, targetHolon, options = {}) {
-    const { lensConfig = { inbound: [], outbound: [] }, partnerName = null } = options;
+    const { lensConfig = { inbound: [], outbound: [] }, partnerName = null, skipPropagation = false } = options;
 
     if (sourceHolon === targetHolon) {
       throw new Error('Cannot federate a holon with itself');
@@ -866,7 +1287,8 @@ class HoloSphereBase extends HoloSphereCore {
     const success = await this.writeGlobal('federation', federationData);
     this.clearCache('federation');
 
-    if (success) {
+    // Only propagate existing data if skipPropagation is false
+    if (success && !skipPropagation) {
       for (const lens of (lensConfig.inbound || [])) {
         await this.federate(targetHolon, sourceHolon, lens, { direction: 'outbound', mode: 'reference' });
       }
@@ -878,6 +1300,13 @@ class HoloSphereBase extends HoloSphereCore {
     return success;
   }
 
+  /**
+   * Removes a holon-level federation relationship.
+   *
+   * @param {string} sourceHolon - Source holon H3 cell ID
+   * @param {string} targetHolon - Target holon H3 cell ID
+   * @returns {Promise<boolean>} True if unfederation succeeded, false if no federation existed
+   */
   async unfederateHolon(sourceHolon, targetHolon) {
     const federationData = await this.readGlobal('federation', sourceHolon);
     if (!federationData) return false;
@@ -907,6 +1336,13 @@ class HoloSphereBase extends HoloSphereCore {
     return success;
   }
 
+  /**
+   * Gets the federation configuration between two holons.
+   *
+   * @param {string} sourceHolon - Source holon H3 cell ID
+   * @param {string} targetHolon - Target holon H3 cell ID
+   * @returns {Promise<Object|null>} Lens configuration or null
+   */
   async getFederatedConfig(sourceHolon, targetHolon) {
     const federationData = await this.readGlobal('federation', sourceHolon);
     if (!federationData || !federationData.lensConfig) return null;
@@ -914,11 +1350,33 @@ class HoloSphereBase extends HoloSphereCore {
   }
 
   // === Hierarchical Operations ===
+
+  /**
+   * Performs hierarchical upcast aggregation.
+   * Aggregates data from child holons up to parent holons in the H3 hierarchy.
+   *
+   * @param {string} holonId - Starting holon H3 cell ID
+   * @param {string} lensName - Name of the lens
+   * @param {string} dataId - ID of the data to upcast
+   * @param {Object} [options={}] - Upcast options
+   * @returns {Promise<Object>} Aggregation result
+   */
   async upcast(holonId, lensName, dataId, options = {}) {
     return hierarchical.upcast(this, holonId, lensName, dataId, options);
   }
 
   // === Subscriptions ===
+
+  /**
+   * Subscribes to real-time updates for a holon and lens.
+   *
+   * @param {string} holonId - H3 cell ID for the holon
+   * @param {string} lensName - Name of the lens
+   * @param {Function} callback - Callback function called with updated data
+   * @param {Object} [options={}] - Subscription options
+   * @returns {{unsubscribe: Function}} Subscription object with unsubscribe method
+   * @throws {TypeError} If callback is not a function
+   */
   subscribe(holonId, lensName, callback, options = {}) {
     if (typeof callback !== 'function') {
       throw new TypeError('callback must be a function');
@@ -953,6 +1411,15 @@ class HoloSphereBase extends HoloSphereCore {
     };
   }
 
+  /**
+   * Subscribes to real-time updates for a global table.
+   *
+   * @param {string} table - Name of the global table
+   * @param {string} key - Key to subscribe to
+   * @param {Function} callback - Callback function called with updated data
+   * @param {Object} [options={}] - Subscription options
+   * @returns {Promise<{unsubscribe: Function}>} Subscription object
+   */
   async subscribeGlobal(table, key, callback, options = {}) {
     return globalTables.subscribeGlobal(
       this.client,
@@ -965,27 +1432,78 @@ class HoloSphereBase extends HoloSphereCore {
   }
 
   // === Crypto Operations ===
+
+  /**
+   * Derives a public key from a private key.
+   *
+   * @param {string} privateKey - Hex-encoded private key
+   * @returns {Promise<string>} Hex-encoded public key
+   */
   async getPublicKey(privateKey) {
     return crypto.getPublicKey(privateKey);
   }
 
+  /**
+   * Signs content with a private key.
+   *
+   * @param {string|Object} content - Content to sign
+   * @param {string} privateKey - Hex-encoded private key
+   * @returns {Promise<string>} Hex-encoded signature
+   */
   async sign(content, privateKey) {
     return crypto.sign(content, privateKey);
   }
 
+  /**
+   * Verifies a signature against content and public key.
+   *
+   * @param {string|Object} content - Original content
+   * @param {string} signature - Hex-encoded signature
+   * @param {string} publicKey - Hex-encoded public key
+   * @returns {Promise<boolean>} True if signature is valid
+   */
   async verify(content, signature, publicKey) {
     return crypto.verify(content, signature, publicKey);
   }
 
+  /**
+   * Issues a capability token for authorization.
+   *
+   * @param {string[]} permissions - Array of permissions ('read', 'write', 'delete')
+   * @param {Object} scope - Scope of the capability (holonId, lensName, etc.)
+   * @param {string} recipient - Public key of the recipient
+   * @param {Object} [options] - Additional options
+   * @returns {Promise<string>} Signed capability token
+   */
   async issueCapability(permissions, scope, recipient, options) {
     return crypto.issueCapability(permissions, scope, recipient, options);
   }
 
+  /**
+   * Verifies a capability token.
+   *
+   * @param {string} token - Capability token to verify
+   * @param {string} requiredPermission - Required permission to check
+   * @param {Object} scope - Scope to verify against
+   * @returns {Promise<boolean>} True if token is valid and has required permission
+   */
   async verifyCapability(token, requiredPermission, scope) {
     return crypto.verifyCapability(token, requiredPermission, scope);
   }
 
   // === Social Protocol Operations ===
+
+  /**
+   * Publishes a Nostr event to a holon.
+   *
+   * @param {Object} event - Nostr event object
+   * @param {number} event.kind - Event kind
+   * @param {string} event.content - Event content
+   * @param {Array} [event.tags] - Event tags
+   * @param {string} holonId - H3 cell ID for the holon
+   * @param {string} [lensName='social'] - Name of the lens
+   * @returns {Promise<boolean>} True if publish succeeded
+   */
   async publishNostr(event, holonId, lensName = 'social') {
     // Validate Nostr event format
     social.validateNostrEvent(event, true, true); // partial=true, throwOnError=true
@@ -1007,6 +1525,16 @@ class HoloSphereBase extends HoloSphereCore {
     return true;
   }
 
+  /**
+   * Publishes an ActivityPub object to a holon.
+   *
+   * @param {Object} object - ActivityPub object
+   * @param {string} object.type - ActivityPub type (Note, Article, etc.)
+   * @param {string} [object.actor] - Actor ID (defaults to client public key)
+   * @param {string} holonId - H3 cell ID for the holon
+   * @param {string} [lensName='social'] - Name of the lens
+   * @returns {Promise<boolean>} True if publish succeeded
+   */
   async publishActivityPub(object, holonId, lensName = 'social') {
     // Validate ActivityPub object format
     social.validateActivityPubObject(object, true); // throwOnError=true
@@ -1018,6 +1546,18 @@ class HoloSphereBase extends HoloSphereCore {
     return this.write(holonId, lensName, activity);
   }
 
+  /**
+   * Queries social protocol data from a holon.
+   *
+   * @param {string} holonId - H3 cell ID for the holon
+   * @param {Object} [options={}] - Query options
+   * @param {string} [options.lens='social'] - Name of the lens
+   * @param {string} [options.protocol] - Filter by protocol ('nostr', 'activitypub', 'all')
+   * @param {string} [options.type] - Filter by content type
+   * @param {number} [options.since] - Filter events after this timestamp
+   * @param {number} [options.until] - Filter events before this timestamp
+   * @returns {Promise<Array>} Array of matching social items
+   */
   async querySocial(holonId, options = {}) {
     const lensName = options.lens || 'social';
     const data = await this.read(holonId, lensName);
@@ -1035,6 +1575,19 @@ class HoloSphereBase extends HoloSphereCore {
     });
   }
 
+  /**
+   * Verifies a Nostr event signature.
+   *
+   * @param {Object} event - Nostr event to verify
+   * @param {string} event.id - Event ID
+   * @param {string} event.pubkey - Author public key
+   * @param {number} event.created_at - Creation timestamp
+   * @param {number} event.kind - Event kind
+   * @param {Array} event.tags - Event tags
+   * @param {string} event.content - Event content
+   * @param {string} event.sig - Event signature
+   * @returns {Promise<boolean>} True if event signature is valid
+   */
   async verifyNostrEvent(event) {
     // Extract only standard Nostr event fields for verification
     // (nostr-tools can't serialize events with extra properties like 'protocol')
@@ -1044,6 +1597,19 @@ class HoloSphereBase extends HoloSphereCore {
   }
 
   // === Metrics ===
+
+  /**
+   * Gets performance metrics for this HoloSphere instance.
+   *
+   * @returns {Object} Metrics object
+   * @returns {number} return.reads - Number of read operations
+   * @returns {number} return.writes - Number of write operations
+   * @returns {number} return.deletes - Number of delete operations
+   * @returns {number} return.federations - Number of federation operations
+   * @returns {number} return.subscriptions - Number of active subscriptions
+   * @returns {number} return.avgReadTime - Average read time in milliseconds
+   * @returns {number} return.avgWriteTime - Average write time in milliseconds
+   */
   metrics() {
     const reads = this._metrics.reads || 0;
     const writes = this._metrics.writes || 0;
@@ -1062,59 +1628,157 @@ class HoloSphereBase extends HoloSphereCore {
   }
 
   // === Aliases ===
+
+  /**
+   * Alias for {@link HoloSphereBase#write}.
+   * @param {string} holonId - H3 cell ID for the holon
+   * @param {string} lensName - Name of the lens
+   * @param {Object} data - Data to write
+   * @param {Object} [options] - Write options
+   * @returns {Promise<boolean>}
+   */
   async put(holonId, lensName, data, options = {}) {
     return this.write(holonId, lensName, data, options);
   }
 
+  /**
+   * Alias for {@link HoloSphereBase#read}.
+   * @param {string} holonId - H3 cell ID for the holon
+   * @param {string} lensName - Name of the lens
+   * @param {string|null} [dataId] - Specific data ID or null
+   * @param {Object} [options] - Read options
+   * @returns {Promise<Object|Array|null>}
+   */
   async get(holonId, lensName, dataId = null, options = {}) {
     return this.read(holonId, lensName, dataId, options);
   }
 
+  /**
+   * Alias for {@link HoloSphereBase#delete}.
+   * @param {string} holonId - H3 cell ID for the holon
+   * @param {string} lensName - Name of the lens
+   * @param {string} dataId - Data ID to delete
+   * @param {Object} [options] - Delete options
+   * @returns {Promise<boolean>}
+   */
   async remove(holonId, lensName, dataId, options = {}) {
     return this.delete(holonId, lensName, dataId, options);
   }
 
+  /**
+   * Alias for {@link HoloSphereBase#writeGlobal}.
+   * @param {string} table - Global table name
+   * @param {Object} data - Data to write
+   * @returns {Promise<boolean>}
+   */
   async putGlobal(table, data) {
     return this.writeGlobal(table, data);
   }
 
+  /**
+   * Alias for {@link HoloSphereBase#readGlobal}.
+   * @param {string} table - Global table name
+   * @param {string|null} [key] - Key to read
+   * @returns {Promise<Object|Array|null>}
+   */
   async getGlobal(table, key = null) {
     return this.readGlobal(table, key);
   }
 
+  /**
+   * Alias for {@link HoloSphereBase#deleteGlobal}.
+   * @param {string} table - Global table name
+   * @param {string} key - Key to delete
+   * @returns {Promise<boolean>}
+   */
   async removeGlobal(table, key) {
     return this.deleteGlobal(table, key);
   }
 
+  /**
+   * Alias for {@link HoloSphereBase#setSchema}.
+   * @param {string} lensName - Lens name
+   * @param {Object|string} schemaObj - Schema object or URI
+   * @param {boolean} [strict] - Strict mode
+   * @returns {Promise<void>}
+   */
   async defineSchema(lensName, schemaObj, strict = false) {
     return this.setSchema(lensName, schemaObj, strict);
   }
 
+  /**
+   * Alias for {@link HoloSphereBase#getSchema}.
+   * @param {string} lensName - Lens name
+   * @returns {Promise<Object|null>}
+   */
   async fetchSchema(lensName) {
     return this.getSchema(lensName);
   }
 
+  /**
+   * Alias for {@link HoloSphereBase#clearSchema}.
+   * @param {string} lensName - Lens name
+   * @returns {Promise<void>}
+   */
   async removeSchema(lensName) {
     return this.clearSchema(lensName);
   }
 
+  /**
+   * Alias for {@link HoloSphereBase#write}.
+   * @param {string} holonId - H3 cell ID for the holon
+   * @param {string} lensName - Name of the lens
+   * @param {Object} data - Data to write
+   * @param {Object} [options] - Write options
+   * @returns {Promise<boolean>}
+   */
   async store(holonId, lensName, data, options = {}) {
     return this.write(holonId, lensName, data, options);
   }
 
+  /**
+   * Alias for {@link HoloSphereBase#read}.
+   * @param {string} holonId - H3 cell ID for the holon
+   * @param {string} lensName - Name of the lens
+   * @param {string|null} [dataId] - Specific data ID or null
+   * @param {Object} [options] - Read options
+   * @returns {Promise<Object|Array|null>}
+   */
   async fetch(holonId, lensName, dataId = null, options = {}) {
     return this.read(holonId, lensName, dataId, options);
   }
 
+  /**
+   * Alias for {@link HoloSphereBase#write}.
+   * @param {string} holonId - H3 cell ID for the holon
+   * @param {string} lensName - Name of the lens
+   * @param {Object} data - Data to write
+   * @param {Object} [options] - Write options
+   * @returns {Promise<boolean>}
+   */
   async save(holonId, lensName, data, options = {}) {
     return this.write(holonId, lensName, data, options);
   }
 
+  /**
+   * Alias for {@link HoloSphereBase#read}.
+   * @param {string} holonId - H3 cell ID for the holon
+   * @param {string} lensName - Name of the lens
+   * @param {string|null} [dataId] - Specific data ID or null
+   * @param {Object} [options] - Read options
+   * @returns {Promise<Object|Array|null>}
+   */
   async load(holonId, lensName, dataId = null, options = {}) {
     return this.read(holonId, lensName, dataId, options);
   }
 
   // === Cache ===
+
+  /**
+   * Clears the internal cache.
+   *
+   * @param {string|null} [pattern=null] - If provided, only clear cache entries matching this pattern
+   */
   clearCache(pattern = null) {
     if (pattern) {
       for (const key of this._cache.keys()) {