holosphere 2.0.0-alpha8 → 2.0.0-alpha9

package/dist/{index-4XHHKe6S.js → index-DJXftyvB.js}

@@ -4,12 +4,14 @@ import { latLngToCell, getResolution, cellToParent, cellToChildren, isValidCell
 import Ajv from "ajv";
 class OutboxQueue {
   /**
+   * Create a new OutboxQueue.
+   *
    * @param {Object} persistentStorage - Storage adapter (IndexedDB/FileSystem)
-   * @param {Object} options - Configuration options
-   * @param {number} options.maxRetries - Max retry attempts (default: 5)
-   * @param {number} options.baseDelay - Base delay in ms (default: 1000)
-   * @param {number} options.maxDelay - Max delay cap in ms (default: 60000)
-   * @param {number} options.failedTTL - TTL for failed events in ms (default: 24 hours)
+   * @param {Object} [options={}] - Configuration options
+   * @param {number} [options.maxRetries=5] - Max retry attempts
+   * @param {number} [options.baseDelay=1000] - Base delay in ms
+   * @param {number} [options.maxDelay=60000] - Max delay cap in ms (1 minute)
+   * @param {number} [options.failedTTL=86400000] - TTL for failed events in ms (24 hours)
    */
   constructor(persistentStorage, options = {}) {
     this.storage = persistentStorage;
@@ -20,10 +22,11 @@ class OutboxQueue {
     this.failedTTL = options.failedTTL || 24 * 60 * 60 * 1e3;
   }
   /**
-   * Add an event to the outbox queue
+   * Add an event to the outbox queue.
+   *
    * @param {Object} event - Signed Nostr event
    * @param {string[]} relays - Target relay URLs
-   * @returns {Promise<Object>} Queue entry
+   * @returns {Promise<Object>} Queue entry with metadata
    */
   async enqueue(event, relays) {
     const entry = {
@@ -41,9 +44,13 @@ class OutboxQueue {
     return entry;
   }
   /**
-   * Mark an event as sent (removes from queue if successful)
+   * Mark an event as sent.
+   *
+   * Removes from queue if at least one relay accepted, otherwise schedules retry.
+   *
    * @param {string} eventId - Event ID
    * @param {string[]} successfulRelays - Relays that accepted the event
+   * @returns {Promise<void>}
    */
   async markSent(eventId, successfulRelays) {
     const key = `${this.queuePrefix}${eventId}`;
@@ -56,8 +63,14 @@ class OutboxQueue {
     }
   }
   /**
-   * Schedule a retry with exponential backoff
+   * Schedule a retry with exponential backoff.
+   *
+   * Uses exponential backoff with jitter. Marks as failed if max retries exceeded.
+   *
    * @private
+   * @param {string} key - Storage key
+   * @param {Object} entry - Queue entry
+   * @returns {Promise<void>}
    */
   async _scheduleRetry(key, entry) {
     entry.retries++;
@@ -75,7 +88,8 @@ class OutboxQueue {
     await this.storage.put(key, entry);
   }
   /**
-   * Get all pending events ready for retry
+   * Get all pending events ready for retry.
+   *
    * @returns {Promise<Object[]>} Pending queue entries sorted by creation time
    */
   async getPendingEvents() {
@@ -84,7 +98,8 @@ class OutboxQueue {
     return allEntries.filter((e) => e && e.status === "pending" && e.nextRetryAt <= now).sort((a, b2) => a.createdAt - b2.createdAt);
   }
   /**
-   * Get all failed events (exceeded max retries)
+   * Get all failed events (exceeded max retries).
+   *
    * @returns {Promise<Object[]>} Failed queue entries
    */
   async getFailedEvents() {
@@ -92,8 +107,9 @@ class OutboxQueue {
     return allEntries.filter((e) => e && e.status === "failed");
   }
   /**
-   * Get queue statistics
-   * @returns {Promise<Object>} Stats object
+   * Get queue statistics.
+   *
+   * @returns {Promise<Object>} Stats object with total, pending, failed counts and oldest timestamps
    */
   async getStats() {
     const allEntries = await this.storage.getAll(this.queuePrefix);
@@ -121,8 +137,9 @@ class OutboxQueue {
     return stats;
   }
   /**
-   * Purge failed events older than maxAge
-   * @param {number} maxAge - Max age in ms (default: 24 hours)
+   * Purge failed events older than maxAge.
+   *
+   * @param {number} [maxAge] - Max age in ms (defaults to failedTTL)
    * @returns {Promise<number>} Number of entries purged
    */
   async purgeOldFailed(maxAge = this.failedTTL) {
@@ -138,7 +155,8 @@ class OutboxQueue {
     return purged;
   }
   /**
-   * Clear all entries from the queue
+   * Clear all entries from the queue.
+   *
    * @returns {Promise<number>} Number of entries cleared
    */
   async clear() {
@@ -153,7 +171,10 @@ class OutboxQueue {
     return cleared;
   }
   /**
-   * Manually retry a failed event
+   * Manually retry a failed event.
+   *
+   * Resets retry counter and status to allow manual retry of a failed event.
+   *
    * @param {string} eventId - Event ID to retry
    * @returns {Promise<Object|null>} Updated entry or null if not found
    */
@@ -173,10 +194,12 @@ class OutboxQueue {
 }
 class SyncService {
   /**
-   * @param {Object} client - NostrClient instance
-   * @param {Object} options - Configuration options
-   * @param {number} options.interval - Sync interval in ms (default: 10000)
-   * @param {boolean} options.autoStart - Start automatically (default: false)
+   * Create a new SyncService.
+   *
+   * @param {Object} client - NostrClient instance with outboxQueue
+   * @param {Object} [options={}] - Configuration options
+   * @param {number} [options.interval=10000] - Sync interval in ms (10 seconds)
+   * @param {boolean} [options.autoStart=false] - Start automatically
    */
   constructor(client, options = {}) {
     this.client = client;
@@ -189,7 +212,9 @@ class SyncService {
     }
   }
   /**
-   * Start the background sync service
+   * Start the background sync service.
+   *
+   * @returns {void}
    */
   start() {
     if (this.running) return;
@@ -197,7 +222,9 @@ class SyncService {
     this._scheduleNextRun();
   }
   /**
-   * Stop the background sync service
+   * Stop the background sync service.
+   *
+   * @returns {void}
    */
   stop() {
     this.running = false;
@@ -207,22 +234,28 @@ class SyncService {
     }
   }
   /**
-   * Check if the service is running
-   * @returns {boolean}
+   * Check if the service is running.
+   *
+   * @returns {boolean} True if service is running
    */
   isRunning() {
     return this.running;
   }
   /**
-   * Force an immediate sync (useful for testing or manual trigger)
-   * @returns {Promise<Object>} Sync result
+   * Force an immediate sync.
+   *
+   * Useful for testing or manual trigger.
+   *
+   * @returns {Promise<Object>} Sync result with processed, succeeded, failed, purged counts
    */
   async syncNow() {
     return this._processOutbox();
   }
   /**
-   * Schedule the next run
+   * Schedule the next run.
+   *
    * @private
+   * @returns {void}
    */
   _scheduleNextRun() {
     if (!this.running) return;
@@ -231,8 +264,10 @@ class SyncService {
     }, this.interval);
   }
   /**
-   * Main loop iteration
+   * Main loop iteration.
+   *
    * @private
+   * @returns {Promise<void>}
    */
   async _runLoop() {
     if (!this.running) return;
@@ -244,9 +279,12 @@ class SyncService {
     this._scheduleNextRun();
   }
   /**
-   * Process pending events in the outbox
+   * Process pending events in the outbox.
+   *
+   * Retries pending events and purges old failed events.
+   *
    * @private
-   * @returns {Promise<Object>} Processing result
+   * @returns {Promise<Object>} Processing result with counts
    */
   async _processOutbox() {
     if (this._processing) {
@@ -285,8 +323,9 @@ class SyncService {
     return result;
   }
   /**
-   * Get sync service statistics
-   * @returns {Promise<Object>} Stats including queue status
+   * Get sync service statistics.
+   *
+   * @returns {Promise<Object>} Stats including running status, interval, and queue status
    */
   async getStats() {
     const stats = {
@@ -302,56 +341,77 @@ class SyncService {
 }
 class PersistentStorage {
   /**
-   * Initialize storage
+   * Initialize storage with namespace.
+   *
+   * @abstract
    * @param {string} namespace - Storage namespace (appName)
    * @returns {Promise<void>}
+   * @throws {Error} Must be implemented by subclass
    */
   async init(namespace) {
     throw new Error("init() must be implemented by subclass");
   }
   /**
-   * Store event
+   * Store event.
+   *
+   * @abstract
    * @param {string} key - Event ID or d-tag
    * @param {Object} event - Nostr event
    * @returns {Promise<void>}
+   * @throws {Error} Must be implemented by subclass
    */
   async put(key, event) {
     throw new Error("put() must be implemented by subclass");
   }
   /**
-   * Retrieve event
+   * Retrieve event.
+   *
+   * @abstract
    * @param {string} key - Event ID or d-tag
    * @returns {Promise<Object|null>} Event or null
+   * @throws {Error} Must be implemented by subclass
    */
   async get(key) {
     throw new Error("get() must be implemented by subclass");
   }
   /**
-   * Get all events matching prefix
+   * Get all events matching prefix.
+   *
+   * @abstract
    * @param {string} prefix - Key prefix
    * @returns {Promise<any[]>} Array of events
+   * @throws {Error} Must be implemented by subclass
    */
   async getAll(prefix) {
     throw new Error("getAll() must be implemented by subclass");
   }
   /**
-   * Delete event
+   * Delete event.
+   *
+   * @abstract
    * @param {string} key - Event ID or d-tag
    * @returns {Promise<void>}
+   * @throws {Error} Must be implemented by subclass
    */
   async delete(key) {
     throw new Error("delete() must be implemented by subclass");
   }
   /**
-   * Clear all data in namespace
+   * Clear all data in namespace.
+   *
+   * @abstract
    * @returns {Promise<void>}
+   * @throws {Error} Must be implemented by subclass
    */
   async clear() {
     throw new Error("clear() must be implemented by subclass");
   }
   /**
-   * Close storage
+   * Close storage connection.
+   *
+   * @abstract
    * @returns {Promise<void>}
+   * @throws {Error} Must be implemented by subclass
    */
   async close() {
     throw new Error("close() must be implemented by subclass");
@@ -361,12 +421,12 @@ async function createPersistentStorage(namespace, options = {}) {
   const isBrowser = typeof window !== "undefined" && typeof window.indexedDB !== "undefined";
   typeof process !== "undefined" && process.versions && void 0;
   if (isBrowser) {
-    const { IndexedDBStorage } = await import("./indexeddb-storage-lExjjFlV.js");
+    const { IndexedDBStorage } = await import("./indexeddb-storage-BFt6hMeF.js");
     const storage = new IndexedDBStorage();
     await storage.init(namespace);
     return storage;
   } else {
-    const { MemoryStorage } = await import("./memory-storage-C68adso2.js");
+    const { MemoryStorage } = await import("./memory-storage-C9HuoL2E.js");
     const storage = new MemoryStorage();
     await storage.init(namespace);
     return storage;
@@ -393,10 +453,21 @@ const WRITE_DEBOUNCE_MS = 500;
 const authorSubscriptions = /* @__PURE__ */ new Map();
 const AUTHOR_SUB_INIT_TIMEOUT = 5e3;
 class LRUCache {
+  /**
+   * Create a new LRU cache.
+   *
+   * @param {number} [maxSize=500] - Maximum number of entries
+   */
   constructor(maxSize = 500) {
     this.maxSize = maxSize;
     this.cache = /* @__PURE__ */ new Map();
   }
+  /**
+   * Get an entry from the cache.
+   *
+   * @param {string} key - Cache key
+   * @returns {*} Cached value or undefined
+   */
   get(key) {
     if (!this.cache.has(key)) return void 0;
     const value = this.cache.get(key);
@@ -457,13 +528,20 @@ function ensureWebSocket() {
 }
 class NostrClient {
   /**
-   * @param {Object} config - Configuration options
-   * @param {string[]} config.relays - Array of relay URLs
-   * @param {string} config.privateKey - Private key for signing (hex format)
-   * @param {boolean} config.enableReconnect - Auto-reconnect on disconnect (default: true)
-   * @param {boolean} config.enablePing - Auto-ping relays (default: true)
-   * @param {string} config.appName - Application name for storage namespace
-   * @param {boolean} config.persistence - Enable persistent storage (default: true)
+   * Create a new NostrClient.
+   *
+   * @param {Object} [config={}] - Configuration options
+   * @param {string[]} [config.relays=[]] - Array of relay URLs
+   * @param {string} [config.privateKey] - Private key for signing (hex format)
+   * @param {boolean} [config.enableReconnect=true] - Auto-reconnect on disconnect
+   * @param {boolean} [config.enablePing=true] - Auto-ping relays
+   * @param {string} [config.appName] - Application name for storage namespace
+   * @param {boolean} [config.persistence=true] - Enable persistent storage
+   * @param {number} [config.cacheSize=500] - Maximum cache size
+   * @param {number} [config.persistBatchMs=100] - Batch persist writes within this window
+   * @param {boolean} [config.backgroundSync=true] - Enable background sync service
+   * @param {string} [config.dataDir] - Data directory for persistent storage
+   * @throws {Error} If relays is not an array
    */
   constructor(config = {}) {
     if (config.relays && !Array.isArray(config.relays)) {
@@ -483,8 +561,10 @@ class NostrClient {
     this._initReady = this._initialize();
   }
   /**
-   * Initialize WebSocket polyfill and pool
+   * Initialize WebSocket polyfill and pool.
+   *
    * @private
+   * @returns {Promise<void>}
    */
   async _initialize() {
     await ensureWebSocket();
@@ -673,13 +753,21 @@ class NostrClient {
     return Array.from(bytes2).map((b2) => b2.toString(16).padStart(2, "0")).join("");
   }
   /**
-   * Publish event to relays
-   * Supports debouncing for replaceable events (kind 30000-39999) to avoid rapid updates
+   * Publish event to relays.
+   *
+   * Supports debouncing for replaceable events (kind 30000-39999) to avoid rapid updates.
+   *
    * @param {Object} event - Unsigned event object
-   * @param {Object} options - Publish options
-   * @param {boolean} options.waitForRelays - Wait for relay confirmation (default: false for speed)
-   * @param {boolean} options.debounce - Debounce rapid writes to same d-tag (default: true for replaceable events)
+   * @param {Object} [options={}] - Publish options
+   * @param {boolean} [options.waitForRelays=false] - Wait for relay confirmation
+   * @param {boolean} [options.debounce=true] - Debounce rapid writes to same d-tag
    * @returns {Promise<Object>} Signed event with relay publish results
+   * @example
+   * const result = await client.publish({
+   *   kind: 30000,
+   *   tags: [['d', 'mypath']],
+   *   content: JSON.stringify({ name: 'Test' })
+   * });
    */
   async publish(event, options = {}) {
     await this._initReady;
@@ -792,14 +880,22 @@ class NostrClient {
     return { successful, failed, results: formattedResults };
   }
   /**
-   * Query events from relays
-   * Uses long-lived subscription for cache updates - avoids polling
+   * Query events from relays.
+   *
+   * Uses long-lived subscription for cache updates - avoids polling.
+   *
    * @param {Object} filter - Nostr filter object
-   * @param {Object} options - Query options
-   * @param {number} options.timeout - Query timeout in ms (default: 30000, set to 0 for no timeout)
-   * @param {boolean} options.localFirst - Return local cache immediately, refresh in background (default: true)
-   * @param {boolean} options.forceRelay - Force relay query even if subscription cache is available (default: false)
+   * @param {Object} [options={}] - Query options
+   * @param {number} [options.timeout=30000] - Query timeout in ms (set to 0 for no timeout)
+   * @param {boolean} [options.localFirst=true] - Return local cache immediately, refresh in background
+   * @param {boolean} [options.forceRelay=false] - Force relay query even if subscription cache is available
    * @returns {Promise<Array>} Array of events
+   * @example
+   * const events = await client.query({
+   *   kinds: [30000],
+   *   authors: [client.publicKey],
+   *   '#d': ['mypath']
+   * });
    */
   async query(filter, options = {}) {
     await this._initReady;
@@ -1082,12 +1178,21 @@ class NostrClient {
     return event.id;
   }
   /**
-   * Subscribe to events
-   * Uses subscription deduplication to avoid creating multiple identical subscriptions
+   * Subscribe to events.
+   *
+   * Uses subscription deduplication to avoid creating multiple identical subscriptions.
+   *
    * @param {Object} filter - Nostr filter object
    * @param {Function} onEvent - Callback for each event
-   * @param {Object} options - Subscription options
-   * @returns {Object} Subscription object with unsubscribe method
+   * @param {Object} [options={}] - Subscription options
+   * @param {Function} [options.onEOSE] - Callback when End Of Stored Events is received
+   * @returns {Promise<Object>} Subscription object with unsubscribe method and id
+   * @example
+   * const sub = await client.subscribe(
+   *   { kinds: [30000], authors: [client.publicKey] },
+   *   (event) => console.log('Event:', event)
+   * );
+   * // Later: sub.unsubscribe();
    */
   async subscribe(filter, onEvent, options = {}) {
     await this._initReady;
@@ -1382,9 +1487,11 @@ class NostrClient {
     }
   }
   /**
-   * Close all connections and subscriptions
-   * @param {Object} options - Close options
-   * @param {boolean} options.flush - Flush pending writes before closing (default: true)
+   * Close all connections and subscriptions.
+   *
+   * @param {Object} [options={}] - Close options
+   * @param {boolean} [options.flush=true] - Flush pending writes before closing
+   * @returns {Promise<void>}
    */
   async close(options = {}) {
     const shouldFlush = options.flush !== false;
@@ -2443,6 +2550,12 @@ async function updateFederatedMessages(backend, originalChatId, messageId, updat
   }
 }
 class StorageBackend {
+  /**
+   * Creates a new StorageBackend instance.
+   *
+   * @param {Object} config - Backend-specific configuration
+   * @throws {Error} If instantiated directly (abstract class)
+   */
   constructor(config) {
     if (new.target === StorageBackend) {
       throw new Error("StorageBackend is abstract and cannot be instantiated directly");
@@ -2569,7 +2682,8 @@ class StorageBackend {
 }
 class GunReferenceHandler {
   /**
-   * Create a new reference handler
+   * Create a new reference handler.
+   *
    * @param {string} appname - Application namespace
    */
   constructor(appname) {
@@ -2712,7 +2826,8 @@ class GunReferenceHandler {
 }
 class GunAuth {
   /**
-   * Create a new authentication handler
+   * Create a new authentication handler.
+   *
    * @param {Object} gun - Gun instance
    * @param {string} appname - Application namespace
    */
@@ -3007,10 +3122,11 @@ const META_SCHEMA = {
 };
 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;
@@ -3217,6 +3333,18 @@ class GunSchemaValidator {
   }
 }
 class GunDBBackend extends StorageBackend {
+  /**
+   * Create a new GunDB backend instance.
+   * @param {Object} config - Backend configuration
+   * @param {string} [config.appName='holosphere'] - Application namespace
+   * @param {string[]} [config.peers=[]] - Array of peer URLs
+   * @param {boolean} [config.radisk=true] - Enable radisk persistence
+   * @param {boolean} [config.localStorage=true] - Enable localStorage
+   * @param {string} [config.dataDir='radata'] - Data directory for Node.js
+   * @param {string} [config.privateKey] - Optional existing private key
+   * @param {string} [config.publicKey] - Optional existing public key
+   * @param {boolean} [config.strict=false] - Enable strict schema validation
+   */
   constructor(config) {
     super(config);
     this.gun = null;
@@ -3889,6 +4017,7 @@ const scripts = {
   build: "vite build",
   "build:cdn": "vite build --config vite.config.cdn.js",
   "build:all": "npm run build && npm run build:cdn",
+  docs: "jsdoc -c jsdoc.json",
   test: "vitest run",
   "test:watch": "vitest",
   "test:coverage": "vitest run --coverage",
@@ -3909,8 +4038,16 @@ const keywords = [
   "erc20",
   "fractal"
 ];
-const author = "";
-const license = "MIT";
+const author = "Roberto Valenti";
+const license = "AGPL-3.0-or-later";
+const repository = {
+  type: "git",
+  url: "https://github.com/liminalvillage/holosphere2.git"
+};
+const homepage = "https://github.com/liminalvillage/holosphere2#readme";
+const bugs = {
+  url: "https://github.com/liminalvillage/holosphere2/issues"
+};
 const dependencies = {
   "@noble/curves": "^1.3.0",
   ajv: "^8.12.0",
@@ -3927,7 +4064,9 @@ const optionalDependencies = {
 };
 const devDependencies = {
   "@vitest/coverage-v8": "^1.3.0",
+  "clean-jsdoc-theme": "^4.3.0",
   eslint: "^8.57.0",
+  jsdoc: "^4.0.4",
   prettier: "^3.2.5",
   terser: "^5.44.0",
   vite: "^5.1.0",
@@ -3951,6 +4090,9 @@ const pkg = {
   keywords,
   author,
   license,
+  repository,
+  homepage,
+  bugs,
   dependencies,
   optionalDependencies,
   devDependencies,
@@ -4536,7 +4678,10 @@ let HoloSphere$1 = class HoloSphere {
   // LIFECYCLE
   // ============================================================================
   /**
-   * Close the backend and clean up resources
+   * Closes the backend and cleans up resources.
+   * Should be called when done using the HoloSphere instance.
+   *
+   * @returns {void}
    */
   close() {
     if (this._backend) {
@@ -4641,7 +4786,7 @@ async function nostrGet(client, path, kind2 = 3e4, options = {}) {
       else {
         try {
           const data = JSON.parse(persistedEvent.content);
-          if (data._deleted) {
+          if (!data || data._deleted) {
             return null;
           }
           if (options.includeAuthor) {
@@ -4694,7 +4839,7 @@ async function _executeNostrGet(client, path, kind2, authors, timeout, options)
   const event = authoredEvents.sort((a, b2) => b2.created_at - a.created_at)[0];
   try {
     const data = JSON.parse(event.content);
-    if (data._deleted) {
+    if (!data || data._deleted) {
       return null;
     }
     if (options.includeAuthor) {
@@ -4723,7 +4868,7 @@ async function nostrGetAll(client, pathPrefix, kind2 = 3e4, options = {}) {
         if (!existing || event.created_at > existing.created_at) {
           try {
             const data = JSON.parse(event.content);
-            if (data._deleted) {
+            if (!data || data._deleted) {
               byPath.delete(path);
               continue;
             }
@@ -4781,7 +4926,7 @@ async function _executeNostrGetAll(client, pathPrefix, kind2, authors, timeout,
     if (!existing || event.created_at > existing.created_at) {
       try {
         const data = JSON.parse(event.content);
-        if (data._deleted) {
+        if (!data || data._deleted) {
           byPath.delete(dTag);
           continue;
         }
@@ -4993,7 +5138,7 @@ function nostrSubscribe(client, path, callback, options = {}) {
       }
       try {
         const data = JSON.parse(event.content);
-        if (data._deleted) {
+        if (!data || data._deleted) {
           return;
         }
         for (const cb of callbacks) {
@@ -5075,7 +5220,7 @@ async function nostrSubscribeMany(client, pathPrefix, callback, options = {}) {
     if (dTag && dTag.startsWith(pathPrefix)) {
       try {
         const data = JSON.parse(event.content);
-        if (data._deleted) {
+        if (!data || data._deleted) {
           return;
         }
         acceptedCount++;
@@ -5346,6 +5491,12 @@ const ajv = new Ajv({ allErrors: true, strict: false });
 const schemaCache = /* @__PURE__ */ new Map();
 const CACHE_TTL = 36e5;
 let ValidationError$1 = class ValidationError extends Error {
+  /**
+   * Creates a new ValidationError.
+   *
+   * @param {string} message - Error message
+   * @param {Array} [errors=[]] - Array of Ajv error objects
+   */
   constructor(message, errors = []) {
     super(message);
     this.name = "ValidationError";
@@ -5794,7 +5945,7 @@ const sha256 = sha256$1;
 let secp256k1 = null;
 async function loadCrypto() {
   if (!secp256k1) {
-    const module2 = await import("./secp256k1-OM8siPyy.js");
+    const module2 = await import("./secp256k1-CreY7Pcl.js");
     secp256k1 = module2.secp256k1;
   }
   return secp256k1;
@@ -7309,17 +7460,23 @@ async function createSubscription(client, path, callback, options = {}) {
   };
 }
 class SubscriptionRegistry {
+  /**
+   * Create a new subscription registry.
+   */
   constructor() {
     this.subscriptions = /* @__PURE__ */ new Map();
   }
   /**
-   * Register a subscription
+   * Register a subscription by ID.
+   * @param {string} id - Unique subscription identifier
+   * @param {Object} subscription - Subscription object with unsubscribe method
    */
   register(id2, subscription) {
     this.subscriptions.set(id2, subscription);
   }
   /**
-   * Unregister a subscription
+   * Unregister and unsubscribe a subscription by ID.
+   * @param {string} id - Subscription identifier to remove
    */
   unregister(id2) {
     const subscription = this.subscriptions.get(id2);
@@ -7329,7 +7486,7 @@ class SubscriptionRegistry {
     }
   }
   /**
-   * Unsubscribe all
+   * Unsubscribe all registered subscriptions and clear the registry.
    */
   unsubscribeAll() {
     for (const [id2, subscription] of this.subscriptions) {
@@ -7338,7 +7495,8 @@ class SubscriptionRegistry {
     this.subscriptions.clear();
   }
   /**
-   * Get active subscription count
+   * Get the count of active subscriptions.
+   * @returns {number} Number of active subscriptions
    */
   count() {
     return this.subscriptions.size;
@@ -13472,11 +13630,16 @@ class LLMService {
     this.temperature = options.temperature || 0.7;
   }
   /**
-   * Send a message to the LLM
-   * @param {string} systemPrompt - System prompt
-   * @param {string} userMessage - User message
-   * @param {Object} options - Override options
+   * Send a single-turn message to the LLM with system and user prompts.
+   *
+   * @param {string} systemPrompt - System prompt defining role and behavior
+   * @param {string} userMessage - User message content
+   * @param {Object} [options={}] - Override options
+   * @param {string} [options.model] - Override model
+   * @param {number} [options.maxTokens] - Override max tokens
+   * @param {number} [options.temperature] - Override temperature
    * @returns {Promise<string>} Response content
+   * @throws {Error} If LLM request fails
    */
   async sendMessage(systemPrompt, userMessage, options = {}) {
     try {
@@ -13495,10 +13658,15 @@ class LLMService {
     }
   }
   /**
-   * Send multiple messages (conversation)
-   * @param {Array<{role: string, content: string}>} messages - Messages array
-   * @param {Object} options - Override options
+   * Send multiple messages in a conversation format.
+   *
+   * @param {Array<{role: string, content: string}>} messages - Array of message objects with role and content
+   * @param {Object} [options={}] - Override options
+   * @param {string} [options.model] - Override model
+   * @param {number} [options.maxTokens] - Override max tokens
+   * @param {number} [options.temperature] - Override temperature
    * @returns {Promise<string>} Response content
+   * @throws {Error} If LLM chat fails
    */
   async chat(messages, options = {}) {
     try {
@@ -13514,30 +13682,36 @@ class LLMService {
     }
   }
   /**
-   * Summarize text
+   * Generate a concise summary of text while preserving key information.
+   *
    * @param {string} text - Text to summarize
-   * @param {Object} options - Options (maxLength, style)
-   * @returns {Promise<string>} Summary
+   * @param {Object} [options={}] - Summarization options
+   * @param {number} [options.maxLength] - Maximum word count for summary
+   * @param {string} [options.style] - Summary style (e.g., 'bullet points', 'executive summary')
+   * @returns {Promise<string>} Summary text
    */
   async summarize(text, options = {}) {
     const systemPrompt = `You are a helpful assistant that summarizes text concisely while preserving key information. Keep summaries clear and focused.${options.maxLength ? ` Keep the summary under ${options.maxLength} words.` : ""}${options.style ? ` Style: ${options.style}.` : ""}`;
     return this.sendMessage(systemPrompt, text, { temperature: 0.5 });
   }
   /**
-   * Analyze text from a specific perspective
+   * Analyze text from a specific perspective or aspect.
+   *
    * @param {string} text - Text to analyze
-   * @param {string} aspect - Aspect to analyze (sentiment, themes, tone, etc.)
-   * @returns {Promise<string>} Analysis
+   * @param {string} aspect - Analysis aspect (e.g., 'sentiment', 'themes', 'tone', 'bias')
+   * @returns {Promise<string>} Structured analysis
    */
   async analyze(text, aspect) {
     const systemPrompt = `You are an expert analyst. Analyze the following text from the perspective of "${aspect}". Provide a clear, structured analysis.`;
     return this.sendMessage(systemPrompt, text, { temperature: 0.3 });
   }
   /**
-   * Extract keywords from text
+   * Extract key words and phrases from text.
+   *
    * @param {string} text - Text to extract keywords from
-   * @param {number} maxKeywords - Maximum keywords (default: 10)
-   * @returns {Promise<string[]>} Array of keywords
+   * @param {number} [maxKeywords=10] - Maximum number of keywords to extract
+   * @returns {Promise<string[]>} Array of keyword strings
+   * @throws {Error} If JSON parsing fails after retry attempts
    */
   async extractKeywords(text, maxKeywords = 10) {
     const systemPrompt = `Extract the ${maxKeywords} most important keywords or key phrases from the text. Return ONLY a JSON array of strings, nothing else. Example: ["keyword1", "keyword2"]`;
@@ -13553,10 +13727,11 @@ class LLMService {
     }
   }
   /**
-   * Categorize text into given categories
+   * Categorize text into one of the provided categories with confidence score.
+   *
    * @param {string} text - Text to categorize
-   * @param {string[]} categories - Available categories
-   * @returns {Promise<{category: string, confidence: number, reasoning: string}>}
+   * @param {string[]} categories - Available category options
+   * @returns {Promise<{category: string, confidence: number, reasoning: string}>} Categorization result
    */
   async categorize(text, categories) {
     const systemPrompt = `Categorize the following text into one of these categories: ${categories.join(", ")}.
@@ -13573,9 +13748,10 @@ Return ONLY a JSON object with: {"category": "chosen_category", "confidence": 0.
     }
   }
   /**
-   * Translate text to target language
+   * Translate text to a target language.
+   *
    * @param {string} text - Text to translate
-   * @param {string} targetLanguage - Target language
+   * @param {string} targetLanguage - Target language name (e.g., 'Spanish', 'French')
    * @returns {Promise<string>} Translated text
    */
   async translate(text, targetLanguage) {
@@ -13583,10 +13759,11 @@ Return ONLY a JSON object with: {"category": "chosen_category", "confidence": 0.
     return this.sendMessage(systemPrompt, text, { temperature: 0.3 });
   }
   /**
-   * Generate questions about content
+   * Generate insightful questions about the content.
+   *
    * @param {string} text - Text to generate questions about
-   * @param {number} count - Number of questions (default: 5)
-   * @returns {Promise<string[]>} Array of questions
+   * @param {number} [count=5] - Number of questions to generate
+   * @returns {Promise<string[]>} Array of question strings
    */
   async generateQuestions(text, count = 5) {
     const systemPrompt = `Generate ${count} insightful questions about the following text. Return ONLY a JSON array of question strings, nothing else. Example: ["Question 1?", "Question 2?"]`;
@@ -13602,11 +13779,15 @@ Return ONLY a JSON object with: {"category": "chosen_category", "confidence": 0.
     }
   }
   /**
-   * Get JSON response from LLM
-   * @param {string} systemPrompt - System prompt
+   * Get a structured JSON response from the LLM with automatic parsing.
+   * Attempts to extract JSON from response even if surrounded by additional text.
+   *
+   * @param {string} systemPrompt - System prompt (JSON instruction will be appended)
    * @param {string} userMessage - User message
-   * @param {Object} options - Options
-   * @returns {Promise<Object>} Parsed JSON response
+   * @param {Object} [options={}] - Request options
+   * @param {number} [options.temperature=0.2] - Temperature (defaults to 0.2 for structured output)
+   * @returns {Promise<Object>} Parsed JSON object
+   * @throws {Error} If JSON parsing fails completely
    */
   async getJSON(systemPrompt, userMessage, options = {}) {
     const response = await this.sendMessage(
@@ -13633,10 +13814,13 @@ class SchemaExtractor {
     this.llm = llmService;
   }
   /**
-   * Extract data from text based on JSON schema
-   * @param {string} text - Text to extract from
-   * @param {Object} schema - JSON schema defining expected structure
-   * @param {Object} options - Extraction options
+   * Extract structured data from text according to a JSON schema.
+   * Uses LLM to intelligently parse unstructured text and map to schema fields.
+   *
+   * @param {string} text - Unstructured text to extract from
+   * @param {Object} schema - JSON schema defining target structure
+   * @param {Object} [options={}] - Extraction options
+   * @param {number} [options.maxTokens=2000] - Maximum tokens for response
    * @returns {Promise<Object>} Extracted data conforming to schema
    */
   async extractToSchema(text, schema, options = {}) {
@@ -13753,10 +13937,12 @@ Return JSON with ONLY the missing fields that you can extract. Do not modify exi
     return missing;
   }
   /**
-   * Validate extracted data against schema
-   * @param {Object} data - Extracted data
-   * @param {Object} schema - JSON schema
-   * @returns {{valid: boolean, errors: string[]}}
+   * Validate extracted data against a JSON schema.
+   * Performs basic type checking and required field validation.
+   *
+   * @param {Object} data - Extracted data to validate
+   * @param {Object} schema - JSON schema to validate against
+   * @returns {{valid: boolean, errors: string[]}} Validation result with error list
    */
   validateExtraction(data, schema) {
     const errors = [];
@@ -13813,11 +13999,14 @@ class JSONOps {
     this.llm = llmService;
   }
   /**
-   * Semantically merge two JSON objects
+   * Semantically merge two JSON objects with intelligent deduplication.
+   * Combines information from both objects, resolving conflicts semantically.
+   *
    * @param {Object} obj1 - First object
    * @param {Object} obj2 - Second object
-   * @param {Object} options - Merge options
-   * @returns {Promise<Object>} Merged object
+   * @param {Object} [options={}] - Merge options
+   * @param {boolean} [options.preferSecond=false] - Prefer second object's values in conflicts
+   * @returns {Promise<Object>} Merged object with combined information
    */
   async add(obj1, obj2, options = {}) {
     const systemPrompt = `You are a JSON merge expert. Semantically merge these two JSON objects.
@@ -14016,9 +14205,11 @@ class Embeddings2 {
     this.holosphere = holosphere;
   }
   /**
-   * Generate embedding for text
+   * Generate a vector embedding for the given text.
+   *
    * @param {string} text - Text to embed
-   * @returns {Promise<number[]>} Embedding vector
+   * @returns {Promise<number[]>} Embedding vector (1536 dimensions by default)
+   * @throws {Error} If embedding generation fails
    */
   async embed(text) {
     try {
@@ -14048,10 +14239,13 @@ class Embeddings2 {
     }
   }
   /**
-   * Calculate cosine similarity between two vectors
-   * @param {number[]} vec1 - First vector
-   * @param {number[]} vec2 - Second vector
-   * @returns {number} Similarity score (0-1)
+   * Calculate cosine similarity between two embedding vectors.
+   * Returns a score between -1 and 1, where 1 indicates identical vectors.
+   *
+   * @param {number[]} vec1 - First embedding vector
+   * @param {number[]} vec2 - Second embedding vector
+   * @returns {number} Similarity score (0-1 for normalized vectors)
+   * @throws {Error} If vectors have different lengths
    */
   cosineSimilarity(vec1, vec2) {
     if (vec1.length !== vec2.length) {
@@ -14094,12 +14288,17 @@ class Embeddings2 {
     return itemWithEmbedding;
   }
   /**
-   * Semantic search within a holon/lens
-   * @param {string} query - Search query
+   * Perform semantic search within a holon/lens using vector similarity.
+   * Returns items ranked by semantic similarity to the query.
+   *
+   * @param {string} query - Natural language search query
    * @param {string} holon - Holon identifier
    * @param {string} lens - Lens name
-   * @param {Object} options - Search options
-   * @returns {Promise<Array<{item: Object, similarity: number}>>} Ranked results
+   * @param {Object} [options={}] - Search options
+   * @param {number} [options.limit=10] - Maximum results to return
+   * @param {number} [options.threshold=0.5] - Minimum similarity score (0-1)
+   * @returns {Promise<Array<{item: Object, similarity: number}>>} Results ranked by similarity descending
+   * @throws {Error} If HoloSphere instance not configured
    */
   async semanticSearch(query, holon, lens, options = {}) {
     if (!this.holosphere) {
@@ -14137,10 +14336,12 @@ class Embeddings2 {
     return this.semanticSearch(text, holon, lens, options);
   }
   /**
-   * Cluster items by semantic similarity
+   * Cluster items by semantic similarity using k-means algorithm.
+   * Automatically generates embeddings for items that don't have them.
+   *
    * @param {Object[]} items - Items to cluster
-   * @param {number} numClusters - Approximate number of clusters
-   * @returns {Promise<Object[][]>} Clustered items
+   * @param {number} [numClusters=5] - Target number of clusters
+   * @returns {Promise<Object[][]>} Array of clusters, each containing related items
    */
   async cluster(items, numClusters = 5) {
     const itemsWithEmbeddings = await Promise.all(
@@ -14246,10 +14447,14 @@ class Council {
     return DEFAULT_PERSPECTIVES;
   }
   /**
-   * Ask a question to the council
-   * @param {string} question - Question to ask
-   * @param {Object} options - Options
-   * @returns {Promise<{perspectives: Array, summary: string}>}
+   * Ask a question to the council and receive diverse perspective responses.
+   *
+   * @param {string} question - Question to ask the council
+   * @param {Object} [options={}] - Options
+   * @param {boolean} [options.parallel=true] - Query perspectives in parallel or sequentially
+   * @param {boolean} [options.includeSummary=true] - Generate a synthesis summary
+   * @param {Array} [options.perspectives] - Override default perspectives
+   * @returns {Promise<{question: string, perspectives: Array, summary: string, timestamp: number}>} Council responses
    */
   async ask(question, options = {}) {
     const { parallel = true, includeSummary = true } = options;
@@ -14416,10 +14621,16 @@ class TTS {
     this.defaultModel = MODELS.TTS_1;
   }
   /**
-   * Convert text to speech
-   * @param {string} text - Text to convert
-   * @param {Object} options - TTS options
-   * @returns {Promise<Buffer>} Audio buffer (MP3)
+   * Convert text to speech audio.
+   *
+   * @param {string} text - Text to convert to speech
+   * @param {Object} [options={}] - TTS generation options
+   * @param {string} [options.voice] - Voice to use (from VOICES enum)
+   * @param {string} [options.model] - Model to use (from MODELS enum)
+   * @param {number} [options.speed=1.0] - Speech speed (0.25 to 4.0)
+   * @param {string} [options.responseFormat='mp3'] - Audio format (mp3, opus, aac, flac)
+   * @returns {Promise<Buffer>} Audio buffer
+   * @throws {Error} If TTS generation fails
    */
   async speak(text, options = {}) {
     const {
@@ -14763,7 +14974,7 @@ class Classifier {
   }
   /**
    * Register multiple lenses
-   * @param {Object<string, {description: string, schema?: Object}>} lenses
+   * @param {Object.<string, Object>} lenses - Map of lens names to config objects with description and optional schema
    */
   registerLenses(lenses) {
     for (const [name2, config] of Object.entries(lenses)) {
@@ -17430,6 +17641,10 @@ const networks = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProp
   listNetworks
 }, Symbol.toStringTag, { value: "Module" }));
 class ChainManager {
+  /**
+   * Create a new ChainManager instance.
+   * @param {Object} [config={}] - Configuration options
+   */
   constructor(config = {}) {
     this.config = config;
     this.provider = null;
@@ -17440,22 +17655,24 @@ class ChainManager {
     this._initialized = false;
   }
   /**
-   * Initialize ethers.js (lazy load)
+   * Initialize ethers.js library (lazy load).
    * @private
+   * @returns {Promise<Object>} Ethers.js module
    */
   async _loadEthers() {
     if (!this.ethers) {
-      const ethersModule = await import("./index-BjP1TXGz.js");
+      const ethersModule = await import("./index-DeZ1xz_s.js");
       this.ethers = ethersModule;
     }
     return this.ethers;
   }
   /**
-   * Connect to a network
+   * Connect to a network using RPC provider.
    * @param {string} networkName - Network name (e.g., 'sepolia', 'polygon')
    * @param {string} [privateKey] - Private key for signing transactions
    * @param {string} [rpcUrl] - Custom RPC URL (overrides default)
-   * @returns {Promise<{provider, signer, network}>}
+   * @returns {Promise<{provider: Object, signer: Object|null, network: Object, networkName: string, config: Object}>} Connection details
+   * @throws {Error} If network is unsupported and no custom RPC URL provided
    */
   async connect(networkName, privateKey, rpcUrl) {
     const ethers = await this._loadEthers();
@@ -17485,9 +17702,10 @@ class ChainManager {
     };
   }
   /**
-   * Connect using browser wallet (MetaMask, etc.)
+   * Connect using browser wallet (MetaMask, etc.).
    * @param {string} [networkName] - Optionally switch to this network
-   * @returns {Promise<{provider, signer, network, address}>}
+   * @returns {Promise<{provider: Object, signer: Object, network: Object, address: string}>} Connection details including user address
+   * @throws {Error} If no browser wallet is detected
    */
   async connectBrowser(networkName) {
     const ethers = await this._loadEthers();
@@ -17514,8 +17732,11 @@ class ChainManager {
     };
   }
   /**
-   * Switch to a different network (browser wallet only)
+   * Switch to a different network (browser wallet only).
+   * Adds the network to the wallet if it doesn't exist.
    * @param {string} networkName - Target network name
+   * @returns {Promise<void>}
+   * @throws {Error} If not using a browser wallet or network is unknown
    */
   async switchNetwork(networkName) {
     if (typeof window === "undefined" || !window.ethereum) {
@@ -17554,16 +17775,18 @@ class ChainManager {
     this.networkName = networkName;
   }
   /**
-   * Get the current provider
-   * @returns {Provider}
+   * Get the current provider.
+   * @returns {Object} Ethers.js provider instance
+   * @throws {Error} If not initialized
    */
   getProvider() {
     this._requireInitialized();
     return this.provider;
   }
   /**
-   * Get the current signer
-   * @returns {Signer}
+   * Get the current signer.
+   * @returns {Object} Ethers.js signer instance
+   * @throws {Error} If not initialized or no signer available
    */
   getSigner() {
     this._requireInitialized();
@@ -17573,17 +17796,19 @@ class ChainManager {
     return this.signer;
   }
   /**
-   * Get the connected address
-   * @returns {Promise<string>}
+   * Get the connected wallet address.
+   * @returns {Promise<string>} Ethereum address
+   * @throws {Error} If no signer available
    */
   async getAddress() {
     const signer = this.getSigner();
     return signer.getAddress();
   }
   /**
-   * Get ETH balance of an address
+   * Get ETH balance of an address.
    * @param {string} [address] - Address to check (defaults to signer)
-   * @returns {Promise<string>} Balance in ETH
+   * @returns {Promise<string>} Balance in ETH as decimal string
+   * @throws {Error} If not initialized or no address/signer available
    */
   async getBalance(address) {
     this._requireInitialized();
@@ -17596,25 +17821,27 @@ class ChainManager {
     return ethers.formatEther(balance);
   }
   /**
-   * Get current network configuration
-   * @returns {Object}
+   * Get current network configuration.
+   * @returns {Object} Network configuration object
+   * @throws {Error} If not initialized
    */
   getNetworkConfig() {
     this._requireInitialized();
     return getNetwork(this.networkName);
   }
   /**
-   * Get current chain ID
-   * @returns {number}
+   * Get current chain ID.
+   * @returns {number} Chain ID as number
+   * @throws {Error} If not initialized
    */
   getChainId() {
     this._requireInitialized();
     return Number(this.network.chainId);
   }
   /**
-   * Check if connected to the expected network
+   * Check if connected to the expected network.
    * @param {string} expectedNetwork - Expected network name
-   * @returns {boolean}
+   * @returns {boolean} True if on expected network
    */
   isOnNetwork(expectedNetwork) {
     if (!this._initialized) return false;
@@ -17623,11 +17850,12 @@ class ChainManager {
     return this.getChainId() === expected.chainId;
   }
   /**
-   * Create a contract instance
+   * Create a contract instance.
    * @param {string} address - Contract address
    * @param {Array} abi - Contract ABI
    * @param {boolean} [useSigner=true] - Use signer for write operations
-   * @returns {Contract}
+   * @returns {Promise<Object>} Ethers.js Contract instance
+   * @throws {Error} If not initialized
    */
   async getContract(address, abi2, useSigner = true) {
     this._requireInitialized();
@@ -17636,11 +17864,12 @@ class ChainManager {
     return new ethers.Contract(address, abi2, signerOrProvider);
   }
   /**
-   * Deploy a contract
+   * Deploy a contract.
    * @param {Array} abi - Contract ABI
    * @param {string} bytecode - Contract bytecode
    * @param {Array} [constructorArgs=[]] - Constructor arguments
-   * @returns {Promise<{contract, address, deployTx}>}
+   * @returns {Promise<{contract: Object, address: string, deployTx: Object, txHash: string}>} Deployment details
+   * @throws {Error} If not initialized or no signer available
    */
   async deployContract(abi2, bytecode2, constructorArgs = []) {
     this._requireInitialized();
@@ -17661,27 +17890,30 @@ class ChainManager {
     };
   }
   /**
-   * Wait for a transaction to be mined
+   * Wait for a transaction to be mined.
    * @param {string} txHash - Transaction hash
    * @param {number} [confirmations=1] - Number of confirmations to wait for
-   * @returns {Promise<TransactionReceipt>}
+   * @returns {Promise<Object>} Transaction receipt
+   * @throws {Error} If not initialized
    */
   async waitForTransaction(txHash, confirmations = 1) {
     this._requireInitialized();
     return this.provider.waitForTransaction(txHash, confirmations);
   }
   /**
-   * Estimate gas for a transaction
+   * Estimate gas for a transaction.
    * @param {Object} tx - Transaction object
-   * @returns {Promise<bigint>}
+   * @returns {Promise<bigint>} Estimated gas amount
+   * @throws {Error} If not initialized
    */
   async estimateGas(tx) {
     this._requireInitialized();
     return this.provider.estimateGas(tx);
   }
   /**
-   * Get current gas price
-   * @returns {Promise<{gasPrice: string, maxFeePerGas: string, maxPriorityFeePerGas: string}>}
+   * Get current gas price and fee data.
+   * @returns {Promise<{gasPrice: string|null, maxFeePerGas: string|null, maxPriorityFeePerGas: string|null}>} Fee data in gwei
+   * @throws {Error} If not initialized
    */
   async getGasPrice() {
     this._requireInitialized();
@@ -17694,28 +17926,29 @@ class ChainManager {
     };
   }
   /**
-   * Parse units (e.g., ETH to wei)
+   * Parse units (e.g., ETH to wei).
    * @param {string|number} value - Value to parse
    * @param {string|number} [unit='ether'] - Unit name or decimals
-   * @returns {bigint}
+   * @returns {Promise<bigint>} Parsed value as bigint
    */
   async parseUnits(value, unit = "ether") {
     const ethers = await this._loadEthers();
     return ethers.parseUnits(value.toString(), unit);
   }
   /**
-   * Format units (e.g., wei to ETH)
+   * Format units (e.g., wei to ETH).
    * @param {bigint|string} value - Value to format
    * @param {string|number} [unit='ether'] - Unit name or decimals
-   * @returns {string}
+   * @returns {Promise<string>} Formatted value as decimal string
    */
   async formatUnits(value, unit = "ether") {
     const ethers = await this._loadEthers();
     return ethers.formatUnits(value, unit);
   }
   /**
-   * Check if manager is initialized
+   * Check if manager is initialized.
    * @private
+   * @throws {Error} If not initialized
    */
   _requireInitialized() {
     if (!this._initialized) {
@@ -17723,14 +17956,14 @@ class ChainManager {
     }
   }
   /**
-   * Check if connected
-   * @returns {boolean}
+   * Check if connected to a network.
+   * @returns {boolean} True if connected
    */
   isConnected() {
     return this._initialized && this.provider !== null;
   }
   /**
-   * Disconnect and clean up
+   * Disconnect and clean up resources.
    */
   disconnect() {
     this.provider = null;
@@ -26203,31 +26436,36 @@ const ABIs = {
   TestToken: TestTokenABI
 };
 class ContractDeployer {
+  /**
+   * Create a new ContractDeployer instance.
+   * @param {ChainManager} chainManager - Chain manager instance
+   */
   constructor(chainManager) {
     this.chainManager = chainManager;
     this.deployedContracts = {};
     this.ethers = null;
   }
   /**
-   * Load ethers from chain manager
+   * Load ethers.js library.
    * @private
+   * @returns {Promise<Object>} Ethers.js module
    */
   async _loadEthers() {
     if (!this.ethers) {
-      this.ethers = await import("./index-BjP1TXGz.js");
+      this.ethers = await import("./index-DeZ1xz_s.js");
     }
     return this.ethers;
   }
   /**
-   * 1-CLICK DEPLOY: Deploy entire Holosphere contract infrastructure
-   * Deploys: All factories + Holons registry + optional TestToken
-   *
-   * @param {Object} options - Deployment options
+   * 1-CLICK DEPLOY: Deploy entire Holosphere contract infrastructure.
+   * Deploys all factories, Holons registry, and optional TestToken.
+   * @param {Object} [options={}] - Deployment options
    * @param {string} [options.botAddress] - Bot address for managed operations (defaults to deployer)
    * @param {string} [options.testTokenSupply='1000000'] - Initial supply for test token (in whole tokens)
    * @param {boolean} [options.deployTestToken=true] - Whether to deploy test token
-   * @param {Function} [options.onProgress] - Callback for deployment progress
-   * @returns {Promise<Object>} Deployed contract addresses and instances
+   * @param {Function} [options.onProgress] - Callback for deployment progress updates
+   * @returns {Promise<Object>} Deployment details including contract addresses, explorer URLs, and metadata
+   * @throws {Error} If deployment fails
    */
   async deployAll(options = {}) {
     const ethers = await this._loadEthers();
@@ -26326,12 +26564,16 @@ class ContractDeployer {
     }
   }
   /**
-   * Deploy a Splitter contract for a holon (fractal ownership)
+   * Deploy a Splitter contract for fractal ownership distribution.
    * @param {string} holonId - Holon identifier
    * @param {string} name - Contract display name
    * @param {number} [splitPercentage=70] - Internal/External split (e.g., 70 = 70% internal, 30% external)
-   * @param {Object} [options] - Additional options
-   * @returns {Promise<{contract, address, txHash}>}
+   * @param {Object} [options={}] - Additional deployment options
+   * @param {string} [options.creatorUserId] - Creator user ID (defaults to holonId)
+   * @param {string} [options.managedFactory] - Managed factory address
+   * @param {string} [options.zonedFactory] - Zoned factory address
+   * @returns {Promise<{contract: Object, address: string, txHash: string, holonId: string, type: string, splitPercentage: number}>} Deployment details
+   * @throws {Error} If factories not deployed
    */
   async deploySplitter(holonId, name2, splitPercentage = 70, options = {}) {
     const signer = this.chainManager.getSigner();
@@ -26358,10 +26600,11 @@ class ContractDeployer {
     };
   }
   /**
-   * Deploy a Managed contract (appreciation-based distribution)
+   * Deploy a Managed contract for appreciation-based distribution.
    * @param {string} name - Contract name
-   * @param {Object} [options] - Additional options
-   * @returns {Promise<{contract, address, txHash}>}
+   * @param {Object} [options={}] - Additional deployment options
+   * @param {string} [options.botAddress] - Bot address for managing appreciation (defaults to deployer)
+   * @returns {Promise<{contract: Object, address: string, txHash: string, type: string}>} Deployment details
    */
   async deployManaged(name2, options = {}) {
     const signer = this.chainManager.getSigner();
@@ -26378,11 +26621,13 @@ class ContractDeployer {
     };
   }
   /**
-   * Deploy a Zoned contract (tier-based distribution)
+   * Deploy a Zoned contract for tier-based distribution.
    * @param {string} name - Contract name
    * @param {number} [nZones=6] - Number of zones
-   * @param {Object} [options] - Additional options
-   * @returns {Promise<{contract, address, txHash}>}
+   * @param {Object} [options={}] - Additional deployment options
+   * @param {string} [options.botAddress] - Bot address for managing zones (defaults to deployer)
+   * @param {string} [options.creatorUserId] - Creator user ID (defaults to 'creator')
+   * @returns {Promise<{contract: Object, address: string, txHash: string, type: string, nZones: number}>} Deployment details
    */
   async deployZoned(name2, nZones = 6, options = {}) {
     const signer = this.chainManager.getSigner();
@@ -26401,11 +26646,11 @@ class ContractDeployer {
     };
   }
   /**
-   * Deploy an Appreciative contract (peer-to-peer appreciation)
+   * Deploy an Appreciative contract for peer-to-peer appreciation.
    * @param {string} name - Contract name
    * @param {string} creatorUserId - Creator's user ID
-   * @param {Object} [options] - Additional options
-   * @returns {Promise<{contract, address, txHash}>}
+   * @param {Object} [options={}] - Additional deployment options
+   * @returns {Promise<{contract: Object, address: string, txHash: string, type: string}>} Deployment details
    */
   async deployAppreciative(name2, creatorUserId, options = {}) {
     const signer = this.chainManager.getSigner();
@@ -26421,13 +26666,15 @@ class ContractDeployer {
     };
   }
   /**
-   * Deploy a Bundle contract (2-way split with steepness)
-   * This is the simplest way to deploy a holon - no registry needed!
+   * Deploy a Bundle contract for 2-way split with steepness-based zone decay.
+   * This is the simplest way to deploy a holon - no registry needed.
    * @param {string} name - Contract name
-   * @param {number} [steepness=500000000000000000n] - Steepness factor (0.5e18 = 50% decay)
+   * @param {bigint|string} [steepness] - Steepness factor (e.g., 0.5e18 = 50% decay, defaults to 0.5e18)
    * @param {number} [nZones=6] - Number of zones
-   * @param {Object} [options] - Additional options
-   * @returns {Promise<{contract, address, txHash}>}
+   * @param {Object} [options={}] - Additional deployment options
+   * @param {string} [options.creatorUserId] - Creator user ID (defaults to 'creator')
+   * @returns {Promise<{contract: Object, address: string, txHash: string, type: string, steepness: bigint, nZones: number, creatorUserId: string, name: string}>} Deployment details
+   * @throws {Error} If bytecode is not available
    */
   async deployBundle(name2, steepness, nZones = 6, options = {}) {
     const ethers = await this._loadEthers();
@@ -26455,12 +26702,14 @@ class ContractDeployer {
     };
   }
   /**
-   * Deploy a Bundle contract directly (simplified 1-click deployment)
-   * No registry needed - just deploys and returns the address
+   * Deploy a Bundle contract directly (simplified 1-click deployment).
+   * No registry needed - just deploys and returns the address.
    * @param {string} holonId - Unique identifier for the holon
    * @param {string} name - Display name for the holon
-   * @param {Object} [options] - Options { steepness, nZones }
-   * @returns {Promise<{address, txHash, contract}>}
+   * @param {Object} [options={}] - Deployment options
+   * @param {bigint|string} [options.steepness] - Steepness factor
+   * @param {number} [options.nZones=6] - Number of zones
+   * @returns {Promise<{contract: Object, address: string, txHash: string, type: string, steepness: bigint, nZones: number, creatorUserId: string, name: string}>} Deployment details
    */
   async deployBundleDirect(holonId, name2, options = {}) {
     const steepness = options.steepness;
@@ -26471,9 +26720,9 @@ class ContractDeployer {
     });
   }
   /**
-   * Deploy a TestToken (ERC20 for testing)
+   * Deploy a TestToken ERC20 for testing.
    * @param {string} [initialSupply='1000000'] - Initial supply in whole tokens
-   * @returns {Promise<{contract, address, txHash}>}
+   * @returns {Promise<{contract: Object, address: string, txHash: string, type: string, initialSupply: string}>} Deployment details
    */
   async deployTestToken(initialSupply = "1000000") {
     const ethers = await this._loadEthers();
@@ -26490,11 +26739,12 @@ class ContractDeployer {
     };
   }
   /**
-   * Create a holon bundle through the Holons registry
+   * Create a holon bundle through the Holons registry.
    * @param {string} creatorUserId - Creator's user ID
    * @param {string} name - Bundle name
    * @param {number} [parameter=70] - Split parameter
-   * @returns {Promise<{address, txHash}>}
+   * @returns {Promise<{address: string, txHash: string, name: string, creatorUserId: string}>} Created holon details
+   * @throws {Error} If Holons registry not deployed
    */
   async createHolonBundle(creatorUserId, name2, parameter = 70) {
     if (!this.deployedContracts.holons) {
@@ -26523,10 +26773,11 @@ class ContractDeployer {
     };
   }
   /**
-   * Get contract instance by address
+   * Get contract instance by address and type.
    * @param {string} address - Contract address
-   * @param {string} type - Contract type (Splitter, Managed, Zoned, etc.)
-   * @returns {Promise<Contract>}
+   * @param {string} type - Contract type (Splitter, Managed, Zoned, Appreciative, Bundle, Holons, TestToken)
+   * @returns {Promise<Object>} Ethers.js Contract instance
+   * @throws {Error} If unknown contract type
    */
   async getContract(address, type2) {
     const abi2 = ABIs[type2];
@@ -26536,22 +26787,26 @@ class ContractDeployer {
     return this.chainManager.getContract(address, abi2.abi);
   }
   /**
-   * Get deployed contract addresses
-   * @returns {Object}
+   * Get deployed contract addresses.
+   * @returns {Object} Map of contract names to addresses
    */
   getDeployedAddresses() {
     return { ...this.deployedContracts };
   }
   /**
-   * Load previously deployed contracts
-   * @param {Object} addresses - Contract addresses
+   * Load previously deployed contract addresses.
+   * @param {Object} addresses - Map of contract names to addresses
    */
   loadDeployedAddresses(addresses) {
     this.deployedContracts = { ...addresses };
   }
   /**
-   * Internal: Deploy a contract
+   * Internal helper to deploy a contract.
    * @private
+   * @param {Array} abi - Contract ABI
+   * @param {string} bytecode - Contract bytecode
+   * @param {Array} constructorArgs - Constructor arguments
+   * @returns {Promise<{contract: Object, address: string, txHash: string, explorerUrl: string|null}>} Deployment result
    */
   async _deployContract(abi2, bytecode2, constructorArgs) {
     const result = await this.chainManager.deployContract(abi2, bytecode2, constructorArgs);
@@ -26564,6 +26819,12 @@ class ContractDeployer {
   }
 }
 class ContractOperations {
+  /**
+   * Create a new ContractOperations instance.
+   * @param {Object} contract - Ethers.js Contract instance
+   * @param {string} type - Contract type (Splitter, Managed, Zoned, Appreciative, Bundle)
+   * @param {ChainManager} chainManager - Chain manager instance
+   */
   constructor(contract, type2, chainManager) {
     this.contract = contract;
     this.type = type2;
@@ -26571,12 +26832,13 @@ class ContractOperations {
     this.ethers = null;
   }
   /**
-   * Load ethers dynamically
+   * Load ethers.js library dynamically.
    * @private
+   * @returns {Promise<Object>} Ethers.js module
    */
   async _loadEthers() {
     if (!this.ethers) {
-      this.ethers = await import("./index-BjP1TXGz.js");
+      this.ethers = await import("./index-DeZ1xz_s.js");
     }
     return this.ethers;
   }
@@ -26584,9 +26846,9 @@ class ContractOperations {
   //                         MEMBER MANAGEMENT
   // ========================================================================
   /**
-   * Add a single member to the contract
+   * Add a single member to the contract.
    * @param {string} userId - User identifier (string-based, e.g., 'alice', 'telegram_12345')
-   * @returns {Promise<{txHash, receipt}>}
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
    */
   async addMember(userId) {
     const tx = await this.contract.addMember(userId);
@@ -26594,9 +26856,9 @@ class ContractOperations {
     return { txHash: receipt.hash, receipt };
   }
   /**
-   * Add multiple members at once (batch operation)
+   * Add multiple members at once (batch operation).
    * @param {string[]} userIds - Array of user identifiers
-   * @returns {Promise<{txHash, receipt}>}
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
    */
   async addMembers(userIds) {
     const tx = await this.contract.addMembers(userIds);
@@ -26604,8 +26866,8 @@ class ContractOperations {
     return { txHash: receipt.hash, receipt };
   }
   /**
-   * Get all member user IDs
-   * @returns {Promise<string[]>}
+   * Get all member user IDs.
+   * @returns {Promise<string[]>} Array of user IDs
    */
   async getMembers() {
     await this.contract.userIds();
@@ -26627,9 +26889,9 @@ class ContractOperations {
     }
   }
   /**
-   * Check if a user is a member
+   * Check if a user is a member.
    * @param {string} userId - User identifier
-   * @returns {Promise<boolean>}
+   * @returns {Promise<boolean>} True if user is a member
    */
   async isMember(userId) {
     try {
@@ -26642,7 +26904,7 @@ class ContractOperations {
     }
   }
   /**
-   * Get the address associated with a user ID
+   * Get the Ethereum address associated with a user ID.
    * @param {string} userId - User identifier
    * @returns {Promise<string>} Ethereum address (or zero address if not set)
    */
@@ -26653,10 +26915,10 @@ class ContractOperations {
   //                         FUND DISTRIBUTION
   // ========================================================================
   /**
-   * Trigger reward distribution for ERC20 tokens
+   * Trigger reward distribution for ERC20 tokens.
    * @param {string} tokenAddress - ERC20 token contract address
    * @param {string|bigint} amount - Amount in wei (or token's smallest unit)
-   * @returns {Promise<{txHash, receipt}>}
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
    */
   async reward(tokenAddress, amount) {
     const ethers = await this._loadEthers();
@@ -26666,9 +26928,9 @@ class ContractOperations {
     return { txHash: receipt.hash, receipt };
   }
   /**
-   * Trigger reward distribution for ETH
+   * Trigger reward distribution for ETH.
    * @param {string} amount - Amount in ETH (e.g., '1.5' for 1.5 ETH)
-   * @returns {Promise<{txHash, receipt}>}
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
    */
   async rewardEth(amount) {
     const ethers = await this._loadEthers();
@@ -26682,9 +26944,9 @@ class ContractOperations {
     return { txHash: receipt.hash, receipt };
   }
   /**
-   * Send ETH directly to contract (triggers receive/fallback)
+   * Send ETH directly to contract (triggers receive/fallback).
    * @param {string} amount - Amount in ETH
-   * @returns {Promise<{txHash, receipt}>}
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
    */
   async sendEth(amount) {
     const ethers = await this._loadEthers();
@@ -26698,10 +26960,10 @@ class ContractOperations {
     return { txHash: receipt.hash, receipt };
   }
   /**
-   * Claim accumulated rewards for a user
+   * Claim accumulated rewards for a user.
    * @param {string} userId - User identifier
    * @param {string} beneficiaryAddress - Ethereum address to receive funds
-   * @returns {Promise<{txHash, receipt}>}
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
    */
   async claim(userId, beneficiaryAddress) {
     const tx = await this.contract.claim(userId, beneficiaryAddress);
@@ -26709,9 +26971,9 @@ class ContractOperations {
     return { txHash: receipt.hash, receipt };
   }
   /**
-   * Get ETH balance for a user
+   * Get ETH balance for a user.
    * @param {string} userId - User identifier
-   * @returns {Promise<string>} Balance in ETH
+   * @returns {Promise<string>} Balance in ETH as decimal string
    */
   async getEthBalance(userId) {
     const ethers = await this._loadEthers();
@@ -26719,10 +26981,10 @@ class ContractOperations {
     return ethers.formatEther(balance);
   }
   /**
-   * Get ERC20 token balance for a user
+   * Get ERC20 token balance for a user.
    * @param {string} userId - User identifier
    * @param {string} tokenAddress - ERC20 token address
-   * @returns {Promise<string>} Balance in tokens (18 decimals assumed)
+   * @returns {Promise<string>} Balance in tokens (18 decimals assumed) as decimal string
    */
   async getTokenBalance(userId, tokenAddress) {
     const ethers = await this._loadEthers();
@@ -26730,17 +26992,17 @@ class ContractOperations {
     return ethers.formatUnits(balance, 18);
   }
   /**
-   * Check if user has already claimed
+   * Check if user has already claimed rewards.
    * @param {string} userId - User identifier
-   * @returns {Promise<boolean>}
+   * @returns {Promise<boolean>} True if user has claimed
    */
   async hasClaimed(userId) {
     return this.contract.hasClaimed(userId);
   }
   /**
-   * Get total deposited amount for a token
+   * Get total deposited amount for a token.
    * @param {string} tokenAddress - Token address (use zero address for ETH)
-   * @returns {Promise<string>}
+   * @returns {Promise<string>} Total deposited as decimal string
    */
   async getTotalDeposited(tokenAddress) {
     const ethers = await this._loadEthers();
@@ -26751,10 +27013,11 @@ class ContractOperations {
   //                         SPLITTER OPERATIONS
   // ========================================================================
   /**
-   * Set the internal/external split percentages (Splitter only)
+   * Set the internal/external split percentages (Splitter only).
    * @param {number} internalPct - Internal percentage (0-100)
    * @param {number} externalPct - External percentage (0-100, must sum to 100 with internal)
-   * @returns {Promise<{txHash, receipt}>}
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
+   * @throws {Error} If percentages don't sum to 100 or not a Splitter contract
    */
   async setContractSplit(internalPct, externalPct) {
     this._requireType(["Splitter"]);
@@ -26766,8 +27029,9 @@ class ContractOperations {
     return { txHash: receipt.hash, receipt };
   }
   /**
-   * Get current split percentages (Splitter only)
-   * @returns {Promise<{internal: number, external: number}>}
+   * Get current split percentages (Splitter only).
+   * @returns {Promise<{internal: number, external: number}>} Split percentages
+   * @throws {Error} If not a Splitter contract
    */
   async getContractSplit() {
     this._requireType(["Splitter"]);
@@ -27127,8 +27391,10 @@ class ContractOperations {
   //                            UTILITIES
   // ========================================================================
   /**
-   * Require specific contract type(s)
+   * Require specific contract type(s).
    * @private
+   * @param {string[]} allowedTypes - Array of allowed contract types
+   * @throws {Error} If contract type doesn't match
    */
   _requireType(allowedTypes) {
     if (!allowedTypes.includes(this.type)) {
@@ -27136,26 +27402,26 @@ class ContractOperations {
     }
   }
   /**
-   * Get raw contract instance for advanced usage
-   * @returns {Contract}
+   * Get raw contract instance for advanced usage.
+   * @returns {Object} Ethers.js Contract instance
    */
   getRawContract() {
     return this.contract;
   }
   /**
-   * Execute a raw contract call
+   * Execute a raw contract call.
    * @param {string} method - Method name
-   * @param {Array} args - Method arguments
-   * @returns {Promise<any>}
+   * @param {...*} args - Method arguments
+   * @returns {Promise<*>} Method return value
    */
   async call(method, ...args) {
     return this.contract[method](...args);
   }
   /**
-   * Execute a raw contract transaction
+   * Execute a raw contract transaction.
    * @param {string} method - Method name
-   * @param {Array} args - Method arguments
-   * @returns {Promise<{txHash, receipt}>}
+   * @param {...*} args - Method arguments
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
    */
   async send(method, ...args) {
     const tx = await this.contract[method](...args);
@@ -27164,6 +27430,11 @@ class ContractOperations {
   }
 }
 class HolonContracts {
+  /**
+   * Create a new HolonContracts instance.
+   * @param {ChainManager} chainManager - Chain manager instance
+   * @param {ContractDeployer} [deployer] - Contract deployer instance (auto-created if not provided)
+   */
   constructor(chainManager, deployer) {
     this.chainManager = chainManager;
     this.deployer = deployer || new ContractDeployer(chainManager);
@@ -27171,18 +27442,19 @@ class HolonContracts {
     this.storage = null;
   }
   /**
-   * Set storage adapter for persisting holon-contract mappings
-   * @param {Object} storage - Storage adapter with get/set methods
+   * Set storage adapter for persisting holon-contract mappings.
+   * @param {Object} storage - Storage adapter with get/set/delete methods
    */
   setStorage(storage) {
     this.storage = storage;
   }
   /**
-   * Deploy a new contract for a holon
+   * Deploy a new contract for a holon.
    * @param {string} holonId - Holon identifier
    * @param {string} [type='Splitter'] - Contract type (Splitter, Managed, Zoned, Appreciative, Bundle)
-   * @param {Object} [options] - Deployment options
-   * @returns {Promise<{contract, address, operations}>}
+   * @param {Object} [options={}] - Deployment options (varies by contract type)
+   * @returns {Promise<{contract: Object, address: string, operations: ContractOperations, txHash: string, type: string}>} Deployment details
+   * @throws {Error} If holon already has a contract
    */
   async deploy(holonId, type2 = "Splitter", options = {}) {
     if (this.holonContracts.has(holonId)) {
@@ -27241,11 +27513,12 @@ class HolonContracts {
     };
   }
   /**
-   * Link a holon to an existing contract
+   * Link a holon to an existing deployed contract.
    * @param {string} holonId - Holon identifier
    * @param {string} contractAddress - Existing contract address
    * @param {string} [type='Splitter'] - Contract type
-   * @returns {Promise<{contract, address, operations}>}
+   * @returns {Promise<{contract: Object, address: string, operations: ContractOperations, type: string}>} Link details
+   * @throws {Error} If holon already has a contract or contract is invalid
    */
   async link(holonId, contractAddress, type2 = "Splitter") {
     if (this.holonContracts.has(holonId)) {
@@ -27280,9 +27553,9 @@ class HolonContracts {
     };
   }
   /**
-   * Unlink a holon from its contract
+   * Unlink a holon from its contract.
    * @param {string} holonId - Holon identifier
-   * @returns {boolean} True if unlinked, false if no contract was linked
+   * @returns {Promise<boolean>} True if unlinked, false if no contract was linked
    */
   async unlink(holonId) {
     if (!this.holonContracts.has(holonId)) {
@@ -27295,52 +27568,52 @@ class HolonContracts {
     return true;
   }
   /**
-   * Get contract for a holon
+   * Get contract instance for a holon.
    * @param {string} holonId - Holon identifier
-   * @returns {Contract|null}
+   * @returns {Object|null} Ethers.js Contract instance or null if not found
    */
   getContract(holonId) {
     const data = this.holonContracts.get(holonId);
     return data?.contract || null;
   }
   /**
-   * Get contract address for a holon
+   * Get contract address for a holon.
    * @param {string} holonId - Holon identifier
-   * @returns {string|null}
+   * @returns {string|null} Contract address or null if not found
    */
   getAddress(holonId) {
     const data = this.holonContracts.get(holonId);
     return data?.address || null;
   }
   /**
-   * Get operations wrapper for a holon
+   * Get operations wrapper for a holon.
    * @param {string} holonId - Holon identifier
-   * @returns {ContractOperations|null}
+   * @returns {ContractOperations|null} Operations wrapper or null if not found
    */
   getOperations(holonId) {
     const data = this.holonContracts.get(holonId);
     return data?.operations || null;
   }
   /**
-   * Get contract type for a holon
+   * Get contract type for a holon.
    * @param {string} holonId - Holon identifier
-   * @returns {string|null}
+   * @returns {string|null} Contract type or null if not found
    */
   getType(holonId) {
     const data = this.holonContracts.get(holonId);
     return data?.type || null;
   }
   /**
-   * Check if a holon has a contract
+   * Check if a holon has a linked contract.
    * @param {string} holonId - Holon identifier
-   * @returns {boolean}
+   * @returns {boolean} True if holon has a contract
    */
   hasContract(holonId) {
     return this.holonContracts.has(holonId);
   }
   /**
-   * Get all holon-contract mappings
-   * @returns {Array<{holonId, address, type}>}
+   * Get all holon-contract mappings.
+   * @returns {Array<{holonId: string, address: string, type: string, deployedAt?: string, linkedAt?: string}>} Array of mappings
    */
   listAll() {
     const result = [];
@@ -27356,9 +27629,9 @@ class HolonContracts {
     return result;
   }
   /**
-   * Get holons by contract type
+   * Get holons by contract type.
    * @param {string} type - Contract type
-   * @returns {Array<{holonId, address}>}
+   * @returns {Array<{holonId: string, address: string}>} Array of holons with matching type
    */
   getByType(type2) {
     const result = [];
@@ -27373,8 +27646,8 @@ class HolonContracts {
     return result;
   }
   /**
-   * Load holon-contract mappings from storage
-   * @returns {Promise<number>} Number of mappings loaded
+   * Load holon-contract mappings from storage.
+   * @returns {Promise<number>} Number of mappings successfully loaded
    */
   async loadFromStorage() {
     if (!this.storage) {
@@ -27405,8 +27678,10 @@ class HolonContracts {
     return loaded;
   }
   /**
-   * Save a holon-contract mapping to storage
+   * Save a holon-contract mapping to storage.
    * @private
+   * @param {string} holonId - Holon identifier
+   * @param {Object} data - Holon contract data
    */
   async _saveMapping(holonId, data) {
     if (!this.storage) return;
@@ -27425,10 +27700,10 @@ class HolonContracts {
     }
   }
   /**
-   * Get required holon operations (throws if not linked)
+   * Get required holon operations, throwing if not linked.
    * @param {string} holonId - Holon identifier
-   * @returns {ContractOperations}
-   * @throws {Error} If holon has no contract
+   * @returns {ContractOperations} Operations wrapper
+   * @throws {Error} If holon has no linked contract
    */
   requireOperations(holonId) {
     const ops = this.getOperations(holonId);
@@ -27462,6 +27737,10 @@ const SANKEY_EVENTS = {
   ContractSplitConfigured: "ContractSplitConfigured"
 };
 class EventListener {
+  /**
+   * Create a new EventListener instance.
+   * @param {ChainManager} chainManager - Chain manager instance
+   */
   constructor(chainManager) {
     this.chainManager = chainManager;
     this.listeners = /* @__PURE__ */ new Map();
@@ -27470,10 +27749,10 @@ class EventListener {
     this.sankeyLinks = [];
   }
   /**
-   * Start listening to all Sankey-relevant events on a contract
-   * @param {string} contractAddress - The contract address
+   * Start listening to all Sankey-relevant events on a contract.
+   * @param {string} contractAddress - Contract address
    * @param {string} holonId - Human-readable holon identifier
-   * @param {Object} contract - ethers.js contract instance
+   * @param {Object} contract - Ethers.js contract instance
    */
   async listenToContract(contractAddress, holonId, contract) {
     const eventFilters = [
@@ -27502,7 +27781,8 @@ class EventListener {
     this.listeners.set(contractAddress, { contract, holonId });
   }
   /**
-   * Stop listening to a contract
+   * Stop listening to a specific contract.
+   * @param {string} contractAddress - Contract address
    */
   stopListening(contractAddress) {
     const listener = this.listeners.get(contractAddress);
@@ -27512,7 +27792,7 @@ class EventListener {
     }
   }
   /**
-   * Stop all listeners
+   * Stop all active listeners.
    */
   stopAll() {
     for (const [address, listener] of this.listeners) {
@@ -27521,7 +27801,12 @@ class EventListener {
     this.listeners.clear();
   }
   /**
-   * Handle incoming event and transform to Sankey data
+   * Handle incoming event and transform to Sankey data.
+   * @private
+   * @param {string} eventName - Event name
+   * @param {Array} args - Event arguments
+   * @param {string} contractAddress - Contract address
+   * @param {string} holonId - Holon identifier
    */
   _handleEvent(eventName, args, contractAddress, holonId) {
     const event = args[args.length - 1];
@@ -27542,7 +27827,11 @@ class EventListener {
     }
   }
   /**
-   * Parse event data based on event type
+   * Parse event data based on event type.
+   * @private
+   * @param {string} eventName - Event name
+   * @param {Array} args - Event arguments
+   * @returns {Object} Parsed event data
    */
   _parseEventData(eventName, args) {
     switch (eventName) {
@@ -27635,7 +27924,9 @@ class EventListener {
     }
   }
   /**
-   * Update Sankey nodes and links based on event
+   * Update Sankey nodes and links based on event.
+   * @private
+   * @param {Object} event - Parsed event object
    */
   _updateSankeyData(event) {
     const { type: type2, data } = event;
@@ -27697,7 +27988,11 @@ class EventListener {
     }
   }
   /**
-   * Ensure a node exists in the Sankey graph
+   * Ensure a node exists in the Sankey graph.
+   * @private
+   * @param {string} id - Node ID
+   * @param {string} type - Node type (external, contract, user, wallet)
+   * @param {string} label - Display label
    */
   _ensureNode(id2, type2, label) {
     if (!this.sankeyNodes.has(id2)) {
@@ -27705,9 +28000,13 @@ class EventListener {
     }
   }
   /**
-   * Get Sankey-compatible data for visualization
-   * @param {Object} options - Filter options
-   * @returns {Object} { nodes: [], links: [] }
+   * Get Sankey-compatible data for visualization.
+   * @param {Object} [options={}] - Filter options
+   * @param {string} [options.tokenAddress] - Filter by token address
+   * @param {number} [options.fromBlock] - Filter from block number
+   * @param {number} [options.toBlock] - Filter to block number
+   * @param {string} [options.minValue] - Minimum value to include
+   * @returns {Object} Sankey data with nodes and links arrays
    */
   getSankeyData(options = {}) {
     const { tokenAddress, fromBlock, toBlock, minValue } = options;
@@ -27750,8 +28049,8 @@ class EventListener {
     };
   }
   /**
-   * Get aggregated flow summary
-   * @returns {Object} Summary statistics
+   * Get aggregated flow summary statistics.
+   * @returns {Object} Summary with inflow/outflow totals and distribution breakdown
    */
   getFlowSummary() {
     const summary = {
@@ -27787,10 +28086,13 @@ class EventListener {
     };
   }
   /**
-   * Query historical events from blockchain
-   * @param {Object} contract - ethers.js contract instance
+   * Query historical events from blockchain.
+   * @param {Object} contract - Ethers.js contract instance
    * @param {string} eventName - Event name to query
-   * @param {Object} options - { fromBlock, toBlock }
+   * @param {Object} [options={}] - Query options
+   * @param {number} [options.fromBlock=0] - Starting block number
+   * @param {number|string} [options.toBlock='latest'] - Ending block number
+   * @returns {Promise<Array>} Array of parsed events
    */
   async queryPastEvents(contract, eventName, options = {}) {
     const { fromBlock = 0, toBlock = "latest" } = options;
@@ -27811,10 +28113,11 @@ class EventListener {
     }
   }
   /**
-   * Build Sankey data from historical events
-   * @param {Object} contract - ethers.js contract instance
+   * Build Sankey data from historical blockchain events.
+   * @param {Object} contract - Ethers.js contract instance
    * @param {string} holonId - Holon identifier
-   * @param {Object} options - Query options
+   * @param {Object} [options={}] - Query options (fromBlock, toBlock)
+   * @returns {Promise<Object>} Sankey data with nodes and links
    */
   async buildFromHistory(contract, holonId, options = {}) {
     const eventTypes = [
@@ -27836,7 +28139,7 @@ class EventListener {
     return this.getSankeyData();
   }
   /**
-   * Clear all stored data
+   * Clear all stored event data.
    */
   clear() {
     this.eventHistory = [];
@@ -27844,7 +28147,8 @@ class EventListener {
     this.sankeyLinks = [];
   }
   /**
-   * Export data for persistence
+   * Export data for persistence.
+   * @returns {Object} Serializable event data
    */
   export() {
     return {
@@ -27857,7 +28161,8 @@ class EventListener {
     };
   }
   /**
-   * Import previously exported data
+   * Import previously exported data.
+   * @param {Object} data - Previously exported data
    */
   import(data) {
     this.eventHistory = data.events || [];
@@ -35834,16 +36139,18 @@ function formatEthNumber(wei) {
 }
 class ContractQueries {
   /**
-   * @param {ethers.Provider} provider - ethers.js provider
+   * Create a new ContractQueries instance.
+   * @param {Object} provider - Ethers.js provider instance
    */
   constructor(provider) {
     this.provider = provider;
   }
   /**
-   * Get a contract instance with the appropriate ABI
+   * Get a contract instance with the appropriate ABI.
    * @param {string} address - Contract address
-   * @param {string} flavor - Contract flavor (Splitter, Managed, Zoned, Appreciative, Bundle)
-   * @returns {ethers.Contract}
+   * @param {string} flavor - Contract flavor (Splitter, Managed, Zoned, Appreciative, Bundle, Holons)
+   * @returns {Object} Ethers.js Contract instance
+   * @throws {Error} If unknown contract flavor
    */
   getContract(address, flavor) {
     const abi2 = ContractABIs[flavor];
@@ -35853,9 +36160,9 @@ class ContractQueries {
     return new Contract(address, abi2, this.provider);
   }
   /**
-   * Auto-detect contract flavor by calling flavor()
+   * Auto-detect contract flavor by calling flavor() method.
    * @param {string} address - Contract address
-   * @returns {Promise<string>} Contract flavor
+   * @returns {Promise<string>} Contract flavor or 'Unknown'
    */
   async detectFlavor(address) {
     const minAbi = [
@@ -35871,7 +36178,10 @@ class ContractQueries {
   }
   // ==================== COMMON QUERIES ====================
   /**
-   * Get basic contract info
+   * Get basic contract information.
+   * @param {string} address - Contract address
+   * @param {string} flavor - Contract flavor
+   * @returns {Promise<{address: string, name: string, flavor: string, version: string, creator: string, memberCount: number}>} Contract info
    */
   async getContractInfo(address, flavor) {
     const contract = this.getContract(address, flavor);
@@ -35892,7 +36202,10 @@ class ContractQueries {
     };
   }
   /**
-   * Get all members (userIds)
+   * Get all member user IDs.
+   * @param {string} address - Contract address
+   * @param {string} flavor - Contract flavor
+   * @returns {Promise<string[]>} Array of user IDs
    */
   async getMembers(address, flavor) {
     const contract = this.getContract(address, flavor);
@@ -35905,7 +36218,11 @@ class ContractQueries {
     return members;
   }
   /**
-   * Get user's ETH balance
+   * Get user's ETH balance in the contract.
+   * @param {string} address - Contract address
+   * @param {string} flavor - Contract flavor
+   * @param {string} userId - User identifier
+   * @returns {Promise<{wei: string, eth: number}>} Balance in wei and ETH
    */
   async getUserEthBalance(address, flavor, userId) {
     const contract = this.getContract(address, flavor);
@@ -35916,7 +36233,12 @@ class ContractQueries {
     };
   }
   /**
-   * Get user's token balance
+   * Get user's ERC20 token balance in the contract.
+   * @param {string} address - Contract address
+   * @param {string} flavor - Contract flavor
+   * @param {string} userId - User identifier
+   * @param {string} tokenAddress - ERC20 token address
+   * @returns {Promise<{wei: string, formatted: number}>} Token balance
    */
   async getUserTokenBalance(address, flavor, userId, tokenAddress) {
     const contract = this.getContract(address, flavor);
@@ -35927,7 +36249,11 @@ class ContractQueries {
     };
   }
   /**
-   * Get total deposited for a token
+   * Get total deposited amount for a token.
+   * @param {string} address - Contract address
+   * @param {string} flavor - Contract flavor
+   * @param {string} [tokenAddress] - Token address (defaults to ETH/zero address)
+   * @returns {Promise<{wei: string, formatted: number}>} Total deposited
    */
   async getTotalDeposited(address, flavor, tokenAddress) {
     const contract = this.getContract(address, flavor);
@@ -35939,7 +36265,11 @@ class ContractQueries {
     };
   }
   /**
-   * Check if user has claimed
+   * Check if user has claimed their rewards.
+   * @param {string} address - Contract address
+   * @param {string} flavor - Contract flavor
+   * @param {string} userId - User identifier
+   * @returns {Promise<boolean>} True if claimed
    */
   async hasClaimed(address, flavor, userId) {
     const contract = this.getContract(address, flavor);
@@ -36272,7 +36602,9 @@ class ContractQueries {
   }
   // ==================== FULL SNAPSHOT ====================
   /**
-   * Get complete contract state snapshot
+   * Get complete contract state snapshot including all members and configuration.
+   * @param {string} address - Contract address
+   * @returns {Promise<Object>} Complete contract state
    */
   async getFullSnapshot(address) {
     const flavor = await this.detectFlavor(address);
@@ -36325,37 +36657,89 @@ class ContractQueries {
 }
 function withAIMethods(Base) {
   return class extends Base {
+    /**
+     * Internal method to ensure AI services are initialized.
+     * @private
+     * @throws {Error} If AI services are not initialized
+     */
     _requireAI() {
       if (!this._ai) {
         throw new Error("AI services not initialized. Provide openaiKey in config.");
       }
     }
     // --- Core LLM Methods ---
+    /**
+     * Summarize text using AI.
+     * @param {string} text - Text content to summarize
+     * @param {Object} [options={}] - Summarization options (model, maxLength, etc.)
+     * @returns {Promise<string>} Generated summary
+     */
     async summarize(text, options = {}) {
       this._requireAI();
       return this._ai.llm.summarize(text, options);
     }
+    /**
+     * Analyze text for a specific aspect using AI.
+     * @param {string} text - Text content to analyze
+     * @param {string} aspect - Aspect to analyze (e.g., 'sentiment', 'tone', 'themes')
+     * @param {Object} [options={}] - Analysis options
+     * @returns {Promise<string>} Analysis result
+     */
     async analyze(text, aspect, options = {}) {
       this._requireAI();
       return this._ai.llm.analyze(text, aspect, options);
     }
+    /**
+     * Extract keywords from text using AI.
+     * @param {string} text - Text content to process
+     * @param {Object} [options={}] - Extraction options (count, focus, etc.)
+     * @returns {Promise<string[]>} Array of extracted keywords
+     */
     async extractKeywords(text, options = {}) {
       this._requireAI();
       return this._ai.llm.extractKeywords(text, options);
     }
+    /**
+     * Categorize text into one of the provided categories.
+     * @param {string} text - Text content to categorize
+     * @param {string[]} categories - Array of possible categories
+     * @param {Object} [options={}] - Categorization options
+     * @returns {Promise<string>} Selected category
+     */
     async categorize(text, categories, options = {}) {
       this._requireAI();
       return this._ai.llm.categorize(text, categories, options);
     }
+    /**
+     * Translate text to target language using AI.
+     * @param {string} text - Text to translate
+     * @param {string} targetLanguage - Target language (e.g., 'Spanish', 'French')
+     * @param {Object} [options={}] - Translation options
+     * @returns {Promise<string>} Translated text
+     */
     async translate(text, targetLanguage, options = {}) {
       this._requireAI();
       return this._ai.llm.translate(text, targetLanguage, options);
     }
+    /**
+     * Generate questions from text using AI.
+     * @param {string} text - Text content to generate questions from
+     * @param {Object} [options={}] - Generation options (count, type, etc.)
+     * @returns {Promise<string[]>} Array of generated questions
+     */
     async generateQuestions(text, options = {}) {
       this._requireAI();
       return this._ai.llm.generateQuestions(text, options);
     }
     // --- Schema Extraction ---
+    /**
+     * Extract structured data from text according to a lens schema.
+     * @param {string} text - Text to extract data from
+     * @param {string} lensName - Name of lens with defined schema
+     * @param {Object} [options={}] - Extraction options
+     * @returns {Promise<Object>} Extracted data matching schema
+     * @throws {Error} If schema not found for lens
+     */
     async extractToSchema(text, lensName, options = {}) {
       this._requireAI();
       const schemaObj = await this.getSchema(lensName);
@@ -36365,189 +36749,482 @@ function withAIMethods(Base) {
       return this._ai.schemaExtractor.extractToSchema(text, schemaObj, options);
     }
     // --- Fuzzy JSON Operations ---
+    /**
+     * AI-powered fuzzy addition of JSON objects.
+     * @param {Object} obj1 - First object
+     * @param {Object} obj2 - Second object
+     * @param {Object} [options={}] - Operation options
+     * @returns {Promise<Object>} Result of fuzzy addition
+     */
     async jsonAdd(obj1, obj2, options = {}) {
       this._requireAI();
       return this._ai.jsonOps.add(obj1, obj2, options);
     }
+    /**
+     * AI-powered fuzzy subtraction of JSON objects.
+     * @param {Object} obj1 - Object to subtract from
+     * @param {Object} obj2 - Object to subtract
+     * @param {Object} [options={}] - Operation options
+     * @returns {Promise<Object>} Result of fuzzy subtraction
+     */
     async jsonSubtract(obj1, obj2, options = {}) {
       this._requireAI();
       return this._ai.jsonOps.subtract(obj1, obj2, options);
     }
+    /**
+     * AI-powered fuzzy union of JSON objects.
+     * @param {Object} obj1 - First object
+     * @param {Object} obj2 - Second object
+     * @param {Object} [options={}] - Operation options
+     * @returns {Promise<Object>} Result of fuzzy union
+     */
     async jsonUnion(obj1, obj2, options = {}) {
       this._requireAI();
       return this._ai.jsonOps.union(obj1, obj2, options);
     }
+    /**
+     * AI-powered fuzzy difference of JSON objects.
+     * @param {Object} obj1 - First object
+     * @param {Object} obj2 - Second object
+     * @param {Object} [options={}] - Operation options
+     * @returns {Promise<Object>} Result of fuzzy difference
+     */
     async jsonDifference(obj1, obj2, options = {}) {
       this._requireAI();
       return this._ai.jsonOps.difference(obj1, obj2, options);
     }
+    /**
+     * AI-powered fuzzy concatenation of JSON objects.
+     * @param {Object} obj1 - First object
+     * @param {Object} obj2 - Second object
+     * @param {Object} [options={}] - Operation options
+     * @returns {Promise<Object>} Result of fuzzy concatenation
+     */
     async jsonConcatenate(obj1, obj2, options = {}) {
       this._requireAI();
       return this._ai.jsonOps.concatenate(obj1, obj2, options);
     }
     // --- Embeddings & Semantic Search ---
+    /**
+     * Generate embedding vector for text.
+     * @param {string} text - Text to embed
+     * @returns {Promise<number[]>} Embedding vector
+     */
     async embed(text) {
       this._requireAI();
       return this._ai.embeddings.embed(text);
     }
+    /**
+     * Perform semantic search on holon data using embeddings.
+     * @param {string} query - Search query text
+     * @param {string} holonId - Holon to search within
+     * @param {string} lensName - Lens to search within
+     * @param {Object} [options={}] - Search options (limit, threshold, etc.)
+     * @returns {Promise<Object[]>} Ranked search results
+     */
     async semanticSearch(query, holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.embeddings.semanticSearch(query, holonId, lensName, options);
     }
+    /**
+     * Store data with automatically generated embedding.
+     * @param {string} holonId - Holon ID to store in
+     * @param {string} lensName - Lens name to store under
+     * @param {Object} data - Data object to store
+     * @param {string} [textField='description'] - Field to use for embedding generation
+     * @returns {Promise<Object>} Stored data with embedding
+     */
     async storeWithEmbedding(holonId, lensName, data, textField = "description") {
       this._requireAI();
       return this._ai.embeddings.storeWithEmbedding(holonId, lensName, data, textField);
     }
     // --- Multi-Perspective Council ---
+    /**
+     * Ask a question to the multi-perspective AI council.
+     * @param {string} question - Question to ask
+     * @param {Object} [options={}] - Council options (perspectives, synthesis, etc.)
+     * @returns {Promise<Object>} Council responses and synthesis
+     */
     async askCouncil(question, options = {}) {
       this._requireAI();
       return this._ai.council.ask(question, options);
     }
+    /**
+     * Ask a question to a custom set of perspectives.
+     * @param {string} question - Question to ask
+     * @param {string[]} perspectives - Array of perspective descriptions
+     * @param {Object} [options={}] - Council options
+     * @returns {Promise<Object>} Custom council responses and synthesis
+     */
     async askCouncilCustom(question, perspectives, options = {}) {
       this._requireAI();
       return this._ai.council.askCustom(question, perspectives, options);
     }
     // --- Text-to-Speech ---
+    /**
+     * Convert text to speech audio.
+     * @param {string} text - Text to convert to speech
+     * @param {string} [voice='nova'] - Voice to use (alloy, echo, fable, onyx, nova, shimmer)
+     * @param {Object} [options={}] - TTS options (speed, format, etc.)
+     * @returns {Promise<Buffer>} Audio buffer
+     */
     async textToSpeech(text, voice = "nova", options = {}) {
       this._requireAI();
       return this._ai.tts.speak(text, voice, options);
     }
+    /**
+     * Convert text to speech audio (base64 encoded).
+     * @param {string} text - Text to convert to speech
+     * @param {string} [voice='nova'] - Voice to use
+     * @param {Object} [options={}] - TTS options
+     * @returns {Promise<string>} Base64-encoded audio
+     */
     async textToSpeechBase64(text, voice = "nova", options = {}) {
       this._requireAI();
       return this._ai.tts.speakBase64(text, voice, options);
     }
     // --- Natural Language Queries ---
+    /**
+     * Execute a natural language query on holon data.
+     * @param {string} query - Natural language query
+     * @param {string|null} [holonId=null] - Optional holon to query
+     * @param {string|null} [lensName=null] - Optional lens to query
+     * @param {Object} [options={}] - Query options
+     * @returns {Promise<Object>} Query results
+     */
     async nlQuery(query, holonId = null, lensName = null, options = {}) {
       this._requireAI();
       return this._ai.nlQuery.execute(query, holonId, lensName, options);
     }
+    /**
+     * Parse a natural language query into structured components.
+     * @param {string} query - Natural language query
+     * @returns {Promise<Object>} Parsed query structure
+     */
     async parseNLQuery(query) {
       this._requireAI();
       return this._ai.nlQuery.parse(query);
     }
     // --- Auto-Classification ---
+    /**
+     * Classify content to determine appropriate lens.
+     * @param {string|Object} content - Content to classify
+     * @param {Object} [options={}] - Classification options
+     * @returns {Promise<string>} Recommended lens name
+     */
     async classifyToLens(content, options = {}) {
       this._requireAI();
       return this._ai.classifier.classifyToLens(content, options);
     }
+    /**
+     * Automatically classify and store content in appropriate lens.
+     * @param {string} holonId - Holon to store in
+     * @param {string|Object} content - Content to classify and store
+     * @param {Object} [options={}] - Storage options
+     * @returns {Promise<Object>} Stored data with classification info
+     */
     async autoStore(holonId, content, options = {}) {
       this._requireAI();
       return this._ai.classifier.autoStore(holonId, content, options);
     }
+    /**
+     * Register a lens for auto-classification.
+     * @param {string} lensName - Lens name to register
+     * @param {string} description - Lens description for classification
+     * @param {string[]} [keywords=[]] - Keywords associated with lens
+     */
     registerLensForClassification(lensName, description2, keywords2 = []) {
       this._requireAI();
       this._ai.classifier.registerLens(lensName, description2, keywords2);
     }
     // --- Spatial Analysis ---
+    /**
+     * Analyze a geographic region using AI.
+     * @param {string} holonId - H3 holon ID to analyze
+     * @param {string|null} [lensName=null] - Optional lens to focus on
+     * @param {string|null} [aspect=null] - Optional aspect to analyze
+     * @param {Object} [options={}] - Analysis options
+     * @returns {Promise<Object>} Region analysis
+     */
     async analyzeRegion(holonId, lensName = null, aspect = null, options = {}) {
       this._requireAI();
       return this._ai.spatial.analyzeRegion(holonId, lensName, aspect, options);
     }
+    /**
+     * Compare two geographic regions using AI.
+     * @param {string} holon1 - First H3 holon ID
+     * @param {string} holon2 - Second H3 holon ID
+     * @param {string|null} [lensName=null] - Optional lens to focus comparison
+     * @returns {Promise<Object>} Comparison analysis
+     */
     async compareRegions(holon1, holon2, lensName = null) {
       this._requireAI();
       return this._ai.spatial.compareRegions(holon1, holon2, lensName);
     }
+    /**
+     * Analyze spatial trends over time.
+     * @param {string} holonId - H3 holon ID
+     * @param {string} lensName - Lens to analyze trends for
+     * @param {Object|null} [timeRange=null] - Time range for trend analysis
+     * @returns {Promise<Object>} Trend analysis
+     */
     async spatialTrends(holonId, lensName, timeRange = null) {
       this._requireAI();
       return this._ai.spatial.spatialTrends(holonId, lensName, timeRange);
     }
     // --- Smart Aggregation ---
+    /**
+     * Intelligently upcast data with AI-powered aggregation.
+     * @param {string} holonId - H3 holon ID to upcast from
+     * @param {string} lensName - Lens to upcast
+     * @param {Object} [options={}] - Upcast options
+     * @returns {Promise<Object>} Smart upcast result
+     */
     async smartUpcast(holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.aggregation.smartUpcast(holonId, lensName, options);
     }
+    /**
+     * Generate AI-powered summary of holon data.
+     * @param {string} holonId - Holon ID to summarize
+     * @returns {Promise<string>} Generated holon summary
+     */
     async generateHolonSummary(holonId) {
       this._requireAI();
       return this._ai.aggregation.generateHolonSummary(holonId);
     }
     // --- Federation Advisor ---
+    /**
+     * Get AI suggestions for holon federations.
+     * @param {string} holonId - Holon to analyze for federation
+     * @param {Object} [options={}] - Suggestion options
+     * @returns {Promise<Object[]>} Array of federation suggestions
+     */
     async suggestFederations(holonId, options = {}) {
       this._requireAI();
       return this._ai.federationAdvisor.suggestFederations(holonId, options);
     }
+    /**
+     * Analyze health of holon's federations.
+     * @param {string} holonId - Holon to analyze
+     * @returns {Promise<Object>} Federation health report
+     */
     async analyzeFederationHealth(holonId) {
       this._requireAI();
       return this._ai.federationAdvisor.analyzeFederationHealth(holonId);
     }
+    /**
+     * Get AI recommendations for optimizing federations.
+     * @param {string} holonId - Holon to optimize
+     * @returns {Promise<Object>} Optimization recommendations
+     */
     async optimizeFederation(holonId) {
       this._requireAI();
       return this._ai.federationAdvisor.optimizeFederation(holonId);
     }
     // --- Relationship Discovery ---
+    /**
+     * Discover relationships between data items using AI.
+     * @param {string} holonId - Holon to analyze
+     * @param {string|null} [lensName=null] - Optional lens to focus on
+     * @returns {Promise<Object[]>} Discovered relationships
+     */
     async discoverRelationships(holonId, lensName = null) {
       this._requireAI();
       return this._ai.relationships.discoverRelationships(holonId, lensName);
     }
+    /**
+     * Find similar items using AI and embeddings.
+     * @param {Object} item - Item to find similar items for
+     * @param {string} holonId - Holon to search within
+     * @param {string|null} [lensName=null] - Optional lens to search
+     * @param {Object} [options={}] - Search options (limit, threshold, etc.)
+     * @returns {Promise<Object[]>} Similar items
+     */
     async findSimilar(item, holonId, lensName = null, options = {}) {
       this._requireAI();
       return this._ai.relationships.findSimilar(item, holonId, lensName, options);
     }
+    /**
+     * Build relationship graph for holon data.
+     * @param {string} holonId - Holon ID
+     * @param {string} lensName - Lens to build graph for
+     * @returns {Promise<Object>} Relationship graph structure
+     */
     async buildRelationshipGraph(holonId, lensName) {
       this._requireAI();
       return this._ai.relationships.buildGraph(holonId, lensName);
     }
+    /**
+     * Get AI suggestions for connecting an item to others.
+     * @param {Object} item - Item to suggest connections for
+     * @param {string} holonId - Holon context
+     * @param {string} lensName - Lens context
+     * @returns {Promise<Object[]>} Connection suggestions
+     */
     async suggestConnections(item, holonId, lensName) {
       this._requireAI();
       return this._ai.relationships.suggestConnections(item, holonId, lensName);
     }
     // --- Task Breakdown ---
+    /**
+     * Break down complex item into subtasks using AI.
+     * @param {Object} item - Item to break down
+     * @param {string} holonId - Holon to store breakdown in
+     * @param {string} lensName - Lens to use for subtasks
+     * @param {Object} [options={}] - Breakdown options (depth, strategy, etc.)
+     * @returns {Promise<Object>} Breakdown structure
+     */
     async breakdown(item, holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.taskBreakdown.breakdown(item, holonId, lensName, options);
     }
+    /**
+     * Get AI suggestion for breakdown strategy.
+     * @param {Object} item - Item to analyze
+     * @returns {Promise<Object>} Suggested breakdown strategy
+     */
     async suggestBreakdownStrategy(item) {
       this._requireAI();
       return this._ai.taskBreakdown.suggestStrategy(item);
     }
+    /**
+     * Flatten hierarchical breakdown into linear array.
+     * @param {Object} breakdownResult - Breakdown structure to flatten
+     * @returns {Object[]} Flattened breakdown items
+     */
     flattenBreakdown(breakdownResult) {
       this._requireAI();
       return this._ai.taskBreakdown.flatten(breakdownResult);
     }
+    /**
+     * Get dependency-ordered list of breakdown items.
+     * @param {Object} breakdownResult - Breakdown structure
+     * @returns {Object[]} Items ordered by dependencies
+     */
     getBreakdownDependencyOrder(breakdownResult) {
       this._requireAI();
       return this._ai.taskBreakdown.getDependencyOrder(breakdownResult);
     }
+    /**
+     * Get progress status of breakdown items.
+     * @param {string} holonId - Holon ID
+     * @param {string} lensName - Lens name
+     * @param {string} itemId - Parent item ID
+     * @returns {Promise<Object>} Progress report
+     */
     async getBreakdownProgress(holonId, lensName, itemId) {
       this._requireAI();
       return this._ai.taskBreakdown.getProgress(holonId, lensName, itemId);
     }
     // --- H3 Geospatial AI ---
+    /**
+     * Get AI suggestion for optimal H3 resolution for item.
+     * @param {Object} item - Item to analyze
+     * @param {Object} [options={}] - Analysis options
+     * @returns {Promise<number>} Suggested H3 resolution level
+     */
     async suggestH3Resolution(item, options = {}) {
       this._requireAI();
       return this._ai.h3ai.suggestResolution(item, options);
     }
+    /**
+     * Analyze H3 distribution patterns in data.
+     * @param {string} holonId - H3 holon to analyze
+     * @param {string} lensName - Lens to analyze
+     * @param {Object} [options={}] - Analysis options
+     * @returns {Promise<Object>} Distribution analysis
+     */
     async analyzeH3Distribution(holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.h3ai.analyzeDistribution(holonId, lensName, options);
     }
+    /**
+     * Find relevance of neighbor H3 cells.
+     * @param {string} holonId - H3 holon ID
+     * @param {string} lensName - Lens to analyze
+     * @param {Object} [options={}] - Analysis options
+     * @returns {Promise<Object[]>} Neighbor relevance scores
+     */
     async findH3NeighborRelevance(holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.h3ai.findNeighborRelevance(holonId, lensName, options);
     }
+    /**
+     * Get AI suggestion for geographic scope of item.
+     * @param {Object} item - Item to analyze
+     * @param {string} holonId - Context holon
+     * @param {string} lensName - Context lens
+     * @param {Object} [options={}] - Analysis options
+     * @returns {Promise<Object>} Geographic scope suggestion
+     */
     async suggestGeographicScope(item, holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.h3ai.suggestGeographicScope(item, holonId, lensName, options);
     }
+    /**
+     * Analyze H3 coverage patterns.
+     * @param {string} holonId - H3 holon to analyze
+     * @param {string} lensName - Lens to analyze
+     * @param {Object} [options={}] - Analysis options
+     * @returns {Promise<Object>} Coverage analysis
+     */
     async analyzeH3Coverage(holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.h3ai.analyzeCoverage(holonId, lensName, options);
     }
+    /**
+     * Get insights across different H3 resolutions.
+     * @param {string} holonId - H3 holon to analyze
+     * @param {string} lensName - Lens to analyze
+     * @param {Object} [options={}] - Analysis options
+     * @returns {Promise<Object>} Cross-resolution insights
+     */
     async crossH3ResolutionInsights(holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.h3ai.crossResolutionInsights(holonId, lensName, options);
     }
+    /**
+     * Get AI suggestion for migrating item to different H3 resolution.
+     * @param {Object} item - Item to migrate
+     * @param {string} holonId - Current holon
+     * @param {string} lensName - Lens context
+     * @param {Object} [options={}] - Migration options
+     * @returns {Promise<Object>} Migration suggestion
+     */
     async suggestH3Migration(item, holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.h3ai.suggestMigration(item, holonId, lensName, options);
     }
+    /**
+     * Generate comprehensive geographic report for holon.
+     * @param {string} holonId - H3 holon to report on
+     * @param {Object} [options={}] - Report options
+     * @returns {Promise<string>} Generated geographic report
+     */
     async generateH3Report(holonId, options = {}) {
       this._requireAI();
       return this._ai.h3ai.generateGeographicReport(holonId, options);
     }
+    /**
+     * Find geographic clusters in holon data.
+     * @param {string} holonId - H3 holon to analyze
+     * @param {string} lensName - Lens to analyze
+     * @param {Object} [options={}] - Clustering options
+     * @returns {Promise<Object[]>} Identified clusters
+     */
     async findH3Clusters(holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.h3ai.findGeographicClusters(holonId, lensName, options);
     }
+    /**
+     * Analyze geographic impact of an item.
+     * @param {Object} item - Item to analyze impact for
+     * @param {string} holonId - Context holon
+     * @param {string} lensName - Context lens
+     * @param {Object} [options={}] - Analysis options
+     * @returns {Promise<Object>} Impact analysis
+     */
     async analyzeH3Impact(item, holonId, lensName, options = {}) {
       this._requireAI();
       return this._ai.h3ai.analyzeGeographicImpact(item, holonId, lensName, options);
@@ -36556,15 +37233,33 @@ function withAIMethods(Base) {
 }
 function withContractMethods(Base) {
   return class extends Base {
+    /**
+     * Check if contracts are initialized.
+     * @returns {boolean} True if contracts initialized
+     */
     hasContracts() {
       return this._contracts !== null;
     }
+    /**
+     * Ensure contracts are initialized, throw if not.
+     * @private
+     * @returns {Object} Contracts object
+     * @throws {Error} If contracts not initialized
+     */
     _requireContracts() {
       if (!this._contracts) {
         throw new Error("Contracts not initialized. Call initContracts() first.");
       }
       return this._contracts;
     }
+    /**
+     * Initialize contracts with server-side configuration (Node.js).
+     * @param {Object} config - Contract configuration
+     * @param {string} config.network - Network name (mainnet, sepolia, hardhat, etc.)
+     * @param {string} config.privateKey - Private key for signing transactions
+     * @param {string} [config.rpcUrl] - Optional custom RPC URL
+     * @returns {Promise<Object>} Connection info with network details and address
+     */
     async initContracts(config) {
       const chainManager = new ChainManager(config);
       const connectionInfo = await chainManager.connect(
@@ -36585,6 +37280,11 @@ function withContractMethods(Base) {
         address: config.privateKey ? await chainManager.getAddress() : null
       };
     }
+    /**
+     * Initialize contracts with browser wallet (MetaMask, etc.).
+     * @param {string} network - Network name to connect to
+     * @returns {Promise<Object>} Connection info with network details
+     */
     async initContractsBrowser(network) {
       const chainManager = new ChainManager();
       const connectionInfo = await chainManager.connectBrowser(network);
@@ -36598,76 +37298,190 @@ function withContractMethods(Base) {
       };
       return connectionInfo;
     }
+    /**
+     * Deploy all core contracts (factory, templates, etc.).
+     * @param {Object} [options={}] - Deployment options
+     * @returns {Promise<Object>} Deployment result with addresses
+     */
     async deployContracts(options = {}) {
       const { deployer } = this._requireContracts();
       return deployer.deployAll(options);
     }
+    /**
+     * Load previously deployed contract addresses.
+     * @param {Object} addresses - Map of contract names to addresses
+     */
     loadDeployedContracts(addresses) {
       const { deployer } = this._requireContracts();
       deployer.loadDeployedAddresses(addresses);
     }
+    /**
+     * Get all deployed contract addresses.
+     * @returns {Object} Map of contract names to addresses
+     */
     getDeployedContracts() {
       const { deployer } = this._requireContracts();
       return deployer.getDeployedAddresses();
     }
+    /**
+     * Deploy a new contract for a holon.
+     * @param {string} holonId - Holon ID to deploy contract for
+     * @param {string} [type='Splitter'] - Contract type (Splitter, Managed, Zoned, Appreciative, Bundle)
+     * @param {Object} [options={}] - Deployment options
+     * @returns {Promise<Object>} Deployment result with contract address
+     */
     async deployHolonContract(holonId, type2 = "Splitter", options = {}) {
       const { holonContracts } = this._requireContracts();
       return holonContracts.deploy(holonId, type2, options);
     }
+    /**
+     * Link an existing contract to a holon.
+     * @param {string} holonId - Holon ID to link
+     * @param {string} contractAddress - Contract address to link
+     * @param {string} [type='Splitter'] - Contract type
+     * @returns {Promise<void>}
+     */
     async linkHolonContract(holonId, contractAddress, type2 = "Splitter") {
       const { holonContracts } = this._requireContracts();
       return holonContracts.link(holonId, contractAddress, type2);
     }
+    /**
+     * Unlink contract from a holon.
+     * @param {string} holonId - Holon ID to unlink
+     * @returns {Promise<void>}
+     */
     async unlinkHolonContract(holonId) {
       const { holonContracts } = this._requireContracts();
       return holonContracts.unlink(holonId);
     }
+    /**
+     * Get contract instance for a holon.
+     * @param {string} holonId - Holon ID
+     * @returns {Object|null} Contract instance or null if not found
+     */
     getHolonContract(holonId) {
       if (!this._contracts) return null;
       return this._contracts.holonContracts.getContract(holonId);
     }
+    /**
+     * Get contract address for a holon.
+     * @param {string} holonId - Holon ID
+     * @returns {string|null} Contract address or null if not found
+     */
     getHolonContractAddress(holonId) {
       if (!this._contracts) return null;
       return this._contracts.holonContracts.getAddress(holonId);
     }
+    /**
+     * Check if holon has a linked contract.
+     * @param {string} holonId - Holon ID to check
+     * @returns {boolean} True if contract exists
+     */
     hasHolonContract(holonId) {
       if (!this._contracts) return false;
       return this._contracts.holonContracts.hasContract(holonId);
     }
+    /**
+     * List all holon contracts.
+     * @returns {Array<{holonId: string, address: string, type: string}>} Array of holon contract info
+     */
     listHolonContracts() {
       if (!this._contracts) return [];
       return this._contracts.holonContracts.listAll();
     }
+    /**
+     * Get operations interface for a holon contract.
+     * @param {string} holonId - Holon ID
+     * @returns {Object} Operations object with contract methods
+     * @throws {Error} If holon has no contract
+     */
     getHolonOperations(holonId) {
       const { holonContracts } = this._requireContracts();
       return holonContracts.requireOperations(holonId);
     }
     // ========== MEMBER MANAGEMENT ==========
+    /**
+     * Add a member to holon contract.
+     * @param {string} holonId - Holon ID
+     * @param {string} userId - User ID to add
+     * @returns {Promise<Object>} Transaction result
+     */
     async contractAddMember(holonId, userId) {
       return this.getHolonOperations(holonId).addMember(userId);
     }
+    /**
+     * Add multiple members to holon contract.
+     * @param {string} holonId - Holon ID
+     * @param {string[]} userIds - Array of user IDs to add
+     * @returns {Promise<Object>} Transaction result
+     */
     async contractAddMembers(holonId, userIds) {
       return this.getHolonOperations(holonId).addMembers(userIds);
     }
+    /**
+     * Check if user is a member of holon contract.
+     * @param {string} holonId - Holon ID
+     * @param {string} userId - User ID to check
+     * @returns {Promise<boolean>} True if user is member
+     */
     async contractIsMember(holonId, userId) {
       return this.getHolonOperations(holonId).isMember(userId);
     }
     // ========== FUND DISTRIBUTION ==========
+    /**
+     * Distribute ERC20 token rewards to contract members.
+     * @param {string} holonId - Holon ID
+     * @param {string} tokenAddress - ERC20 token contract address
+     * @param {string|number} amount - Amount to distribute
+     * @returns {Promise<Object>} Transaction result
+     */
     async contractReward(holonId, tokenAddress, amount) {
       return this.getHolonOperations(holonId).reward(tokenAddress, amount);
     }
+    /**
+     * Distribute ETH rewards to contract members.
+     * @param {string} holonId - Holon ID
+     * @param {string|number} amount - Amount of ETH to distribute (in wei)
+     * @returns {Promise<Object>} Transaction result
+     */
     async contractRewardEth(holonId, amount) {
       return this.getHolonOperations(holonId).rewardEth(amount);
     }
+    /**
+     * Send ETH to holon contract.
+     * @param {string} holonId - Holon ID
+     * @param {string|number} amount - Amount of ETH to send (in wei)
+     * @returns {Promise<Object>} Transaction result
+     */
     async contractSendEth(holonId, amount) {
       return this.getHolonOperations(holonId).sendEth(amount);
     }
+    /**
+     * Claim user's share of distributed funds.
+     * @param {string} holonId - Holon ID
+     * @param {string} userId - User ID claiming funds
+     * @param {string} beneficiaryAddress - Address to send claimed funds to
+     * @returns {Promise<Object>} Transaction result
+     */
     async contractClaim(holonId, userId, beneficiaryAddress) {
       return this.getHolonOperations(holonId).claim(userId, beneficiaryAddress);
     }
+    /**
+     * Get user's claimable ETH balance.
+     * @param {string} holonId - Holon ID
+     * @param {string} userId - User ID to check
+     * @returns {Promise<string>} ETH balance in wei
+     */
     async contractGetEthBalance(holonId, userId) {
       return this.getHolonOperations(holonId).getEthBalance(userId);
     }
+    /**
+     * Get user's claimable token balance.
+     * @param {string} holonId - Holon ID
+     * @param {string} userId - User ID to check
+     * @param {string} tokenAddress - Token contract address
+     * @returns {Promise<string>} Token balance
+     */
     async contractGetTokenBalance(holonId, userId, tokenAddress) {
       return this.getHolonOperations(holonId).getTokenBalance(userId, tokenAddress);
     }
@@ -36756,9 +37570,17 @@ function withContractMethods(Base) {
     async contractGetTotalDeposited(holonId, tokenAddress) {
       return this.getHolonOperations(holonId).getTotalDeposited(tokenAddress);
     }
+    /**
+     * Get network utility functions.
+     * @returns {Object} Network utilities module
+     */
     getNetworkUtils() {
       return networks;
     }
+    /**
+     * Get the chain manager instance.
+     * @returns {Object|null} ChainManager instance or null if not initialized
+     */
     getChainManager() {
       return this._contracts?.chainManager || null;
     }
@@ -36997,6 +37819,12 @@ async function getPendingFederationRequests(client, options = {}) {
   return pending;
 }
 class AuthorizationError extends Error {
+  /**
+   * Creates a new AuthorizationError.
+   *
+   * @param {string} message - Error message describing the authorization failure
+   * @param {string|null} [requiredPermission=null] - The permission that was required
+   */
   constructor(message, requiredPermission = null) {
     super(message);
     this.name = "AuthorizationError";
@@ -37004,6 +37832,11 @@ class AuthorizationError extends Error {
   }
 }
 class ValidationError2 extends Error {
+  /**
+   * Creates a new ValidationError.
+   *
+   * @param {string} message - Error message describing the validation failure
+   */
   constructor(message) {
     super(message);
     this.name = "ValidationError";
@@ -37012,6 +37845,13 @@ class ValidationError2 extends Error {
 function withFederationMethods(Base) {
   return class extends Base {
     // === Cross-Holosphere Federation ===
+    /**
+     * Add a federated HoloSphere partner by public key.
+     * @param {string} pubKey - Public key (hex) of the federated HoloSphere
+     * @param {Object} [options={}] - Federation options (metadata, capabilities, etc.)
+     * @returns {Promise<Object>} Federation registration result
+     * @throws {ValidationError} If pubKey is invalid
+     */
     async addFederatedHolosphere(pubKey, options = {}) {
       if (!pubKey || typeof pubKey !== "string") {
         throw new ValidationError2("pubKey must be a valid public key string");
@@ -37023,6 +37863,11 @@ function withFederationMethods(Base) {
         options
       );
     }
+    /**
+     * Remove a federated HoloSphere partner.
+     * @param {string} pubKey - Public key of the partner to remove
+     * @returns {Promise<void>}
+     */
     async removeFederatedHolosphere(pubKey) {
       return removeFederatedPartner(
         this.client,
@@ -37030,18 +37875,32 @@ function withFederationMethods(Base) {
         pubKey
       );
     }
+    /**
+     * Get all federated HoloSphere public keys.
+     * @returns {Promise<string[]>} Array of federated public keys
+     */
     async getFederatedHolospheres() {
       return getFederatedAuthors(
         this.client,
         this.config.appName
       );
     }
+    /**
+     * Get the complete federation registry.
+     * @returns {Promise<Object>} Federation registry with all partners and capabilities
+     */
     async getFederationRegistry() {
       return getFederationRegistry(
         this.client,
         this.config.appName
       );
     }
+    /**
+     * Store an inbound capability token from a federated partner.
+     * @param {string} partnerPubKey - Partner's public key
+     * @param {Object} capabilityInfo - Capability token and metadata
+     * @returns {Promise<void>}
+     */
     async storeInboundCapability(partnerPubKey, capabilityInfo) {
       return storeInboundCapability(
         this.client,
@@ -37050,6 +37909,15 @@ function withFederationMethods(Base) {
         capabilityInfo
       );
     }
+    /**
+     * Read data from a federated source with capability verification.
+     * @param {string} sourcePubKey - Source HoloSphere public key
+     * @param {string} holonId - Holon ID to read from
+     * @param {string} lensName - Lens name to read from
+     * @param {string|null} [dataId=null] - Optional specific data ID (null for all)
+     * @returns {Promise<Object|Object[]>} Data from federated source
+     * @throws {AuthorizationError} If capability verification fails
+     */
     async readFromFederatedSource(sourcePubKey, holonId, lensName, dataId = null) {
       const capabilityEntry = await getCapabilityForAuthor(
         this.client,
@@ -37082,6 +37950,19 @@ function withFederationMethods(Base) {
         });
       }
     }
+    /**
+     * Create a cross-HoloSphere hologram reference.
+     * Links data from another HoloSphere into this one using capability-based access.
+     * @param {string} sourcePubKey - Source HoloSphere public key
+     * @param {string} sourceHolon - Source holon ID
+     * @param {string} lensName - Lens name
+     * @param {string} dataId - Data ID
+     * @param {string} targetHolon - Target holon in this HoloSphere
+     * @param {Object} [options={}] - Hologram options
+     * @param {boolean} [options.embedCapability=true] - Embed capability in hologram
+     * @returns {Promise<Object>} Created hologram
+     * @throws {AuthorizationError} If no valid capability exists
+     */
     async createCrossHolosphereHologram(sourcePubKey, sourceHolon, lensName, dataId, targetHolon, options = {}) {
       const { embedCapability = true } = options;
       const capabilityEntry = await getCapabilityForAuthor(
@@ -37108,6 +37989,17 @@ function withFederationMethods(Base) {
       await write(this.client, targetPath, hologram$1);
       return hologram$1;
     }
+    /**
+     * Issue a capability token for federated access.
+     * Grants another HoloSphere permission to access data with specified scope.
+     * @param {string} targetPubKey - Target HoloSphere public key to grant access to
+     * @param {Object} scope - Access scope (holonId, lensName, dataId patterns)
+     * @param {string[]} permissions - Array of permissions ('read', 'write', etc.)
+     * @param {Object} [options={}] - Capability options
+     * @param {number} [options.expiresIn=3600000] - Expiration time in milliseconds
+     * @param {boolean} [options.trackInRegistry=true] - Store in federation registry
+     * @returns {Promise<string>} Capability token
+     */
     async issueCapabilityForFederation(targetPubKey, scope, permissions, options = {}) {
       const { expiresIn = 36e5, trackInRegistry = true } = options;
       const token = await issueCapability(
@@ -37147,11 +38039,23 @@ function withFederationMethods(Base) {
       }
       return token;
     }
+    /**
+     * Hash a capability token for storage.
+     * @private
+     * @param {string} token - Capability token to hash
+     * @returns {Promise<string>} SHA256 hash of token
+     */
     async _hashToken(token) {
       const encoder = new TextEncoder();
       return bytesToHex$1(sha256(encoder.encode(token)));
     }
     // === Nostr Discovery Protocol ===
+    /**
+     * Send a federation request to another HoloSphere via Nostr.
+     * @param {string} targetPubKey - Target HoloSphere public key
+     * @param {Object} [options={}] - Request options (message, metadata, etc.)
+     * @returns {Promise<Object>} Request event
+     */
     async sendFederationRequest(targetPubKey, options = {}) {
       return sendFederationRequest(
         this.client,
@@ -37160,9 +38064,20 @@ function withFederationMethods(Base) {
         options
       );
     }
+    /**
+     * Subscribe to incoming federation requests.
+     * @param {Function} callback - Callback function (request) => void
+     * @returns {Promise<Object>} Subscription object with unsubscribe method
+     */
     async subscribeFederationRequests(callback) {
       return subscribeFederationRequests(this.client, callback);
     }
+    /**
+     * Accept a federation request and establish partnership.
+     * @param {Object} request - Federation request object
+     * @param {Object} [options={}] - Acceptance options (capabilities to grant, etc.)
+     * @returns {Promise<Object>} Acceptance event
+     */
     async acceptFederationRequest(request, options = {}) {
       return acceptFederationRequest(
         this.client,
@@ -37171,6 +38086,12 @@ function withFederationMethods(Base) {
         options
       );
     }
+    /**
+     * Decline a federation request.
+     * @param {Object} request - Federation request object
+     * @param {string} [reason=''] - Optional reason for declining
+     * @returns {Promise<Object>} Decline event
+     */
     async declineFederationRequest(request, reason = "") {
       return declineFederationRequest(
         this.client,
@@ -37179,6 +38100,11 @@ function withFederationMethods(Base) {
         reason
       );
     }
+    /**
+     * Subscribe to federation request acceptances.
+     * @param {Function} callback - Callback function (acceptance) => void
+     * @returns {Promise<Object>} Subscription object with unsubscribe method
+     */
     async subscribeFederationAcceptances(callback) {
       return subscribeFederationAcceptances(
         this.client,
@@ -37186,9 +38112,19 @@ function withFederationMethods(Base) {
         callback
       );
     }
+    /**
+     * Subscribe to federation request declines.
+     * @param {Function} callback - Callback function (decline) => void
+     * @returns {Promise<Object>} Subscription object with unsubscribe method
+     */
     async subscribeFederationDeclines(callback) {
       return subscribeFederationDeclines(this.client, callback);
     }
+    /**
+     * Get all pending federation requests.
+     * @param {Object} [options={}] - Query options (limit, since, etc.)
+     * @returns {Promise<Object[]>} Array of pending requests
+     */
     async getPendingFederationRequests(options = {}) {
       return getPendingFederationRequests(this.client, options);
     }
@@ -37228,7 +38164,31 @@ function createAIServices(apiKey, holosphere = null, options = {}, openaiClient
     h3ai
   };
 }
+/**
+ * @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
+ */
 class HoloSphereBase extends HoloSphere$1 {
+  /**
+   * 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);
     this.schemas = /* @__PURE__ */ new Map();
@@ -37246,17 +38206,40 @@ class HoloSphereBase extends HoloSphere$1 {
     }
     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(name2) {
     if (typeof process !== "undefined" && process.env) {
       return process.env[name2];
     }
     return void 0;
   }
+  /**
+   * 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 === void 0 || value === null) return void 0;
     const parsed = parseFloat(value);
     return isNaN(parsed) ? void 0 : 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,
@@ -37283,26 +38266,79 @@ class HoloSphereBase extends HoloSphere$1 {
     this._ai.taskBreakdown = new TaskBreakdown(this._ai.llm, this);
     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 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 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 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 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$1("ValidationError: holonId must be a non-empty string");
@@ -37400,6 +38436,15 @@ class HoloSphereBase extends HoloSphere$1 {
     }
     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 = /* @__PURE__ */ new Set()) {
     if (!data) return data;
     if (Array.isArray(data)) {
@@ -37478,6 +38523,19 @@ class HoloSphereBase extends HoloSphere$1 {
     }
     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$1("ValidationError: holonId must be a non-empty string");
@@ -37516,6 +38574,21 @@ class HoloSphereBase extends HoloSphere$1 {
     this._metrics.totalReadTime += endTime - startTime;
     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$1("ValidationError: holonId must be a non-empty string");
@@ -37565,6 +38638,18 @@ class HoloSphereBase extends HoloSphere$1 {
     }
     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$1("ValidationError: holonId must be a non-empty string");
@@ -37605,33 +38690,97 @@ class HoloSphereBase extends HoloSphere$1 {
     return true;
   }
   // === 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 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 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 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 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 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 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 = buildPath(this.config.appName, holonId, lensName);
     return 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$1("ValidationError: lensName must be a non-empty string");
@@ -37653,14 +38802,40 @@ class HoloSphereBase extends HoloSphere$1 {
     }
     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);
   }
   // === 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;
     if (sourceHolon === targetHolon) {
@@ -37686,6 +38861,18 @@ class HoloSphereBase extends HoloSphere$1 {
     this._metrics.federations = (this._metrics.federations || 0) + 1;
     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, toHolon2, lensName, options = {}) {
     const { mode = "reference", filter = null } = options;
     const existingData = await this.read(fromHolon, lensName, null, { resolveHolograms: false });
@@ -37705,6 +38892,15 @@ class HoloSphereBase extends HoloSphere$1 {
       );
     }
   }
+  /**
+   * 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 = buildPath(this.config.appName, holonId, lensName);
@@ -37712,6 +38908,14 @@ class HoloSphereBase extends HoloSphere$1 {
     if (!data || !resolveHolograms) return data;
     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) {
     const configPath = buildPath(this.config.appName, sourceHolon, lensName, "_federation");
     try {
@@ -37720,6 +38924,15 @@ class HoloSphereBase extends HoloSphere$1 {
     }
     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 updateHologramOverrides(
       this.client,
@@ -37730,6 +38943,15 @@ class HoloSphereBase extends HoloSphere$1 {
       overrides
     );
   }
+  /**
+   * 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 createHologram(
       sourceHolon,
@@ -37739,6 +38961,14 @@ class HoloSphereBase extends HoloSphere$1 {
       this.config.appName
     );
   }
+  /**
+   * 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) {
     const path = buildPath(this.config.appName, holonId, lensName, dataId);
     const sourceData = await read(this.client, path);
@@ -37747,6 +38977,15 @@ class HoloSphereBase extends HoloSphere$1 {
     }
     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 removeActiveHologram(
       this.client,
@@ -37757,6 +38996,15 @@ class HoloSphereBase extends HoloSphere$1 {
       targetHolon
     );
   }
+  /**
+   * 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 deleteHologram(
       this.client,
@@ -37767,6 +39015,17 @@ class HoloSphereBase extends HoloSphere$1 {
       options
     );
   }
+  /**
+   * 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 = {}) {
     const mode = options.mode || "reference";
     return propagateData(
@@ -37779,18 +39038,51 @@ class HoloSphereBase extends HoloSphere$1 {
       mode
     );
   }
+  /**
+   * 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$1, options = {}) {
     return resolveHologram(this.client, hologram$1, /* @__PURE__ */ 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 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 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 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 cleanupCircularHolograms(
       this.client,
@@ -37800,6 +39092,15 @@ class HoloSphereBase extends HoloSphere$1 {
       options
     );
   }
+  /**
+   * 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 cleanupCircularHologramsByIds(
       this.client,
@@ -37810,6 +39111,17 @@ class HoloSphereBase extends HoloSphere$1 {
       options
     );
   }
+  /**
+   * 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);
     const targets = federationData?.federated || federationData?.outbound || [];
@@ -37828,6 +39140,13 @@ class HoloSphereBase extends HoloSphere$1 {
     }
     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");
@@ -37844,8 +39163,22 @@ class HoloSphereBase extends HoloSphere$1 {
     }
     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");
     }
@@ -37891,7 +39224,7 @@ class HoloSphereBase extends HoloSphere$1 {
     };
     const success = await this.writeGlobal("federation", federationData);
     this.clearCache("federation");
-    if (success) {
+    if (success && !skipPropagation) {
       for (const lens of lensConfig.inbound || []) {
         await this.federate(targetHolon, sourceHolon, lens, { direction: "outbound", mode: "reference" });
       }
@@ -37901,6 +39234,13 @@ class HoloSphereBase extends HoloSphere$1 {
     }
     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;
@@ -37923,16 +39263,43 @@ class HoloSphereBase extends HoloSphere$1 {
     }
     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;
     return federationData.lensConfig[targetHolon] || null;
   }
   // === 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 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");
@@ -37962,6 +39329,15 @@ class HoloSphereBase extends HoloSphere$1 {
       }
     };
   }
+  /**
+   * 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 subscribeGlobal(
       this.client,
@@ -37973,22 +39349,71 @@ class HoloSphereBase extends HoloSphere$1 {
     );
   }
   // === 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 getPublicKey$1(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 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 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 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 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") {
     validateNostrEvent(event, true, true);
     const enrichedEvent = {
@@ -38004,6 +39429,16 @@ class HoloSphereBase extends HoloSphere$1 {
     await write(this.client, path, eventWithProtocol);
     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") {
     validateActivityPubObject(object, true);
     const activity = transformActivityPubObject({
@@ -38012,6 +39447,18 @@ class HoloSphereBase extends HoloSphere$1 {
     });
     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);
@@ -38025,12 +39472,37 @@ class HoloSphereBase extends HoloSphere$1 {
       return true;
     });
   }
+  /**
+   * 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) {
     const { id: id2, pubkey, created_at, kind: kind2, tags, content, sig } = event;
     const standardEvent = { id: id2, pubkey, created_at, kind: kind2, tags, content, sig };
     return verifyEvent(standardEvent);
   }
   // === 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;
@@ -38047,46 +39519,142 @@ class HoloSphereBase extends HoloSphere$1 {
     };
   }
   // === 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()) {
@@ -38270,4 +39838,4 @@ export {
   exists as y,
   bytes as z
 };
-//# sourceMappingURL=index-4XHHKe6S.js.map
+//# sourceMappingURL=index-DJXftyvB.js.map