holosphere 2.0.0-alpha0 → 2.0.0-alpha10

package/src/index.js

@@ -1,22 +1,31 @@
 /**
- * HoloSphere - Holonic Geospatial Communication Infrastructure
- * Public API
+ * @fileoverview HoloSphere - Holonic Geospatial Communication Infrastructure
+ *
+ * This is the main entry point for the HoloSphere library, providing a comprehensive
+ * distributed P2P geospatial communication system. It combines H3 hexagonal indexing
+ * for spatial organization, Nostr protocol for distributed storage, smart contracts
+ * for fund distribution, and AI services for intelligent data processing.
+ *
+ * @module holosphere
+ * @author HoloSphere Team
+ * @license MIT
  */
 
 import { HoloSphere as HoloSphereCore } from './core/holosphere.js';
 import * as spatial from './spatial/h3-operations.js';
-import * as storage from './storage/nostr-wrapper.js';
+import * as storage from './storage/unified-storage.js';
+import * as nostrStorage from './storage/nostr-wrapper.js';
 import * as nostrAsync from './storage/nostr-async.js';
 import * as globalTables from './storage/global-tables.js';
 import * as schema from './schema/validator.js';
 import { ValidationError } from './schema/validator.js';
 import * as federation from './federation/hologram.js';
+import * as handshake from './federation/handshake.js';
 import * as crypto from './crypto/secp256k1.js';
+import * as nostrUtils from './crypto/nostr-utils.js';
 import * as social from './content/social-protocols.js';
 import * as subscriptions from './subscriptions/manager.js';
 import * as hierarchical from './hierarchical/upcast.js';
-import * as registry from './federation/registry.js';
-import * as discovery from './federation/discovery.js';
 
 // AI Module imports
 import { LLMService } from './ai/llm-service.js';
@@ -34,16 +43,72 @@ import { RelationshipDiscovery } from './ai/relationships.js';
 import { TaskBreakdown } from './ai/breakdown.js';
 import { H3AI } from './ai/h3-ai.js';
 
+// Contracts Module imports
+import { ChainManager } from './contracts/chain-manager.js';
+import { ContractDeployer, ABIs as ContractABIs } from './contracts/deployer.js';
+import { HolonContracts } from './contracts/holon-contracts.js';
+import { ContractOperations } from './contracts/operations.js';
+import { EventListener, SANKEY_EVENTS } from './contracts/event-listener.js';
+import { ContractQueries } from './contracts/queries.js';
+import * as networks from './contracts/networks.js';
+
+// Mixin imports
+import { withAIMethods } from './lib/ai-methods.js';
+import { withContractMethods } from './lib/contract-methods.js';
+import { withFederationMethods } from './lib/federation-methods.js';
+import { AuthorizationError } from './lib/errors.js';
+
 /**
- * Main HoloSphere class with all methods
+ * Base HoloSphere class with core data operations.
+ * Extends HoloSphereCore with schema validation, caching, subscriptions, and AI capabilities.
+ *
+ * @class HoloSphereBase
+ * @extends HoloSphereCore
  */
-export class HoloSphere extends HoloSphereCore {
+class HoloSphereBase extends HoloSphereCore {
+  /**
+   * Creates a new HoloSphereBase instance.
+   *
+   * @param {Object} config - Configuration options
+   * @param {string} config.appName - Application namespace for data isolation
+   * @param {string} [config.backend='nostr'] - Storage backend type ('nostr', 'gundb', 'activitypub')
+   * @param {string[]} [config.relays] - Nostr relay URLs for distributed storage
+   * @param {string} [config.openaiKey] - OpenAI API key for AI services
+   * @param {Object} [config.aiOptions] - AI service configuration
+   * @param {string} [config.aiOptions.model] - OpenAI model to use
+   * @param {number} [config.aiOptions.temperature] - Temperature for AI responses
+   */
   constructor(config) {
     super(config);
+    /** @type {Map<string, {schema: Object, strict: boolean, timestamp: number}>} */
     this.schemas = new Map();
+    /** @type {Map<string, any>} */
+    this._cache = new Map();
+    /** @type {subscriptions.SubscriptionRegistry} */
     this.subscriptionRegistry = new subscriptions.SubscriptionRegistry();
 
+    /**
+     * Write cache for optimistic updates.
+     * Stores data immediately so reads return fresh data before relay sync completes.
+     * @type {Map<string, {data: Object, timestamp: number}>}
+     */
+    this._writeCache = new Map();
+
+    /**
+     * Pending write promises for deduplication.
+     * @type {Map<string, Promise>}
+     */
+    this._pendingWrites = new Map();
+
+    /**
+     * Delete cache for optimistic deletes.
+     * Tracks paths that have been deleted so reads don't return stale storage data.
+     * @type {Set<string>}
+     */
+    this._deleteCache = new Set();
+
     // Initialize AI services if openaiKey is provided or OPENAI_API_KEY env var is set
+    /** @type {Object|null} */
     this._ai = null;
     const openaiKey = config.openaiKey || this._getEnv('OPENAI_API_KEY');
     if (openaiKey) {
@@ -54,11 +119,18 @@ export class HoloSphere extends HoloSphereCore {
       };
       this._initializeAI(openaiKey, aiOptions);
     }
+
+    // Contracts module (lazy initialized)
+    /** @type {Object|null} */
+    this._contracts = null;
   }
 
   /**
-   * Get environment variable (works in Node.js)
+   * Gets an environment variable value (Node.js only).
+   *
    * @private
+   * @param {string} name - Environment variable name
+   * @returns {string|undefined} Environment variable value or undefined
    */
   _getEnv(name) {
     if (typeof process !== 'undefined' && process.env) {
@@ -68,8 +140,11 @@ export class HoloSphere extends HoloSphereCore {
   }
 
   /**
-   * Parse float from string, return undefined if invalid
+   * Parses a string value to a float.
+   *
    * @private
+   * @param {string|undefined|null} value - Value to parse
+   * @returns {number|undefined} Parsed float or undefined if invalid
    */
   _parseFloat(value) {
     if (value === undefined || value === null) return undefined;
@@ -78,28 +153,29 @@ export class HoloSphere extends HoloSphereCore {
   }
 
   /**
-   * Initialize AI services
+   * 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 = {}) {
-    // Build LLM options from config
     const llmOptions = {
       ...options.llm,
       model: options.model || options.llm?.model,
       temperature: options.temperature ?? options.llm?.temperature,
     };
 
-    // Create shared LLM service
     this._ai = {
       llm: new LLMService(apiKey, llmOptions),
     };
 
-    // Create OpenAI client for embeddings and TTS
     const OpenAI = require('openai').default;
     const openai = new OpenAI({ apiKey });
     this._ai.openai = openai;
 
-    // Create all services
     this._ai.embeddings = new Embeddings(openai, this);
     this._ai.schemaExtractor = new SchemaExtractor(this._ai.llm);
     this._ai.jsonOps = new JSONOps(this._ai.llm);
@@ -116,41 +192,90 @@ export class HoloSphere extends HoloSphereCore {
   }
 
   /**
-   * Check if AI services are initialized
-   * @returns {boolean}
+   * Checks if AI services are initialized.
+   *
+   * @returns {boolean} True if AI services are available
    */
   hasAI() {
     return this._ai !== null;
   }
 
   /**
-   * Get AI services object (for advanced usage)
-   * @returns {Object|null}
+   * Gets the initialized AI services object.
+   *
+   * @returns {Object|null} AI services object containing llm, embeddings, etc., or null if not initialized
    */
   getAIServices() {
     return this._ai;
   }
 
   // === Spatial Operations ===
+
+  /**
+   * Converts geographic coordinates to an H3 holon ID.
+   *
+   * @param {number} lat - Latitude (-90 to 90)
+   * @param {number} lng - Longitude (-180 to 180)
+   * @param {number} resolution - H3 resolution level (0-15)
+   * @returns {Promise<string>} H3 cell ID representing the holon
+   */
   async toHolon(lat, lng, resolution) {
     return spatial.toHolon(lat, lng, resolution);
   }
 
+  /**
+   * Gets all parent holons at higher resolutions.
+   *
+   * @param {string} holonId - H3 cell ID
+   * @param {number} [maxResolution] - Maximum resolution to traverse up to
+   * @returns {Promise<string[]>} Array of parent H3 cell IDs
+   */
   async getParents(holonId, maxResolution) {
     return spatial.getParents(holonId, maxResolution);
   }
 
+  /**
+   * Gets all child holons at the next resolution level.
+   *
+   * @param {string} holonId - H3 cell ID
+   * @returns {Promise<string[]>} Array of child H3 cell IDs
+   */
   async getChildren(holonId) {
     return spatial.getChildren(holonId);
   }
 
+  /**
+   * Validates if a string is a valid H3 cell ID.
+   *
+   * @param {string} holonId - String to validate
+   * @returns {boolean} True if valid H3 cell ID
+   */
   isValidH3(holonId) {
     return spatial.isValidH3(holonId);
   }
 
   // === Data Operations ===
+
+  /**
+   * Writes data to a specific holon and lens.
+   * By default, write is optimistic (non-blocking) - returns immediately after caching locally.
+   * Data is synced to relays in the background.
+   *
+   * @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
+   * @param {boolean} [options.blocking=false] - If true, wait for relay confirmation before returning
+   * @returns {Promise<boolean>} True if write succeeded (or queued for optimistic writes)
+   * @throws {ValidationError} If holonId, lensName, or data is invalid
+   * @throws {AuthorizationError} If capability token is invalid
+   */
   async write(holonId, lensName, data, options = {}) {
-    // Validate inputs
     if (!holonId || typeof holonId !== 'string') {
       throw new ValidationError('ValidationError: holonId must be a non-empty string');
     }
@@ -161,212 +286,314 @@ export class HoloSphere extends HoloSphereCore {
       throw new ValidationError('ValidationError: data must be an object');
     }
 
-    // Check authorization if capability token provided
     const capToken = options.capabilityToken || options.capability;
     if (capToken) {
-      const authorized = await this.verifyCapability(
-        capToken,
-        'write',
-        { holonId, lensName }
-      );
+      const authorized = await this.verifyCapability(capToken, 'write', { holonId, lensName });
       if (!authorized) {
         throw new AuthorizationError('AuthorizationError: Invalid capability token for write operation', 'write');
       }
     }
 
-    // Auto-generate ID if not provided
     if (!data.id) {
       data.id = `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
     }
 
-    // Check if we're writing to an existing hologram location
+    // Add metadata
+    if (!data._meta) data._meta = {};
+    data._meta.createdAt = data._meta.createdAt || Date.now();
+    data._meta.updatedAt = Date.now();
+
     const path = storage.buildPath(this.config.appName, holonId, lensName, data.id);
-    const existingData = await storage.read(this.client, path);
-
-    // If existing data is a hologram, split the write between local overrides and source
-    if (existingData && existingData.hologram === true && existingData.target) {
-      // Fields that define the hologram structure (never overwrite these)
-      const hologramStructureFields = ['hologram', 'soul', 'target', 'id', '_meta'];
-      // Fields that exist in the hologram as local overrides
-      const localOverrideFields = Object.keys(existingData).filter(k => !hologramStructureFields.includes(k));
-
-      // Split data: local fields stay local, everything else goes to source
-      const localData = {
-        ...existingData,  // Keep hologram structure
-      };
-      const sourceUpdates = {};
-
-      for (const [key, value] of Object.entries(data)) {
-        if (hologramStructureFields.includes(key)) {
-          // Skip - don't overwrite hologram structure
-          continue;
-        } else if (key === '_hologram') {
-          // Skip - this is resolved metadata, not real data
-          continue;
-        } else if (localOverrideFields.includes(key)) {
-          // This field exists in the hologram - update locally
-          localData[key] = value;
-        } else {
-          // This field doesn't exist in hologram - update source
-          sourceUpdates[key] = value;
-        }
+    this._log('DEBUG', 'write', { holonId, lensName, dataId: data.id, path, blocking: !!options.blocking });
+
+    // Validate synchronously if schema exists
+    if (options.validate !== false && this.schemas.has(lensName)) {
+      const schemaObj = this.schemas.get(lensName);
+      const strict = options.strict !== undefined ? options.strict : schemaObj.strict;
+      if (schemaObj.schema && typeof schemaObj.schema === 'object' && !schemaObj.schema.$ref) {
+        schema.validate(data, schemaObj.schema, lensName, strict);
       }
+    }
 
-      // Schema validation for source updates (if schema exists)
-      if (Object.keys(sourceUpdates).length > 0 && options.validate !== false && this.schemas.has(lensName)) {
-        // Read current source data to merge with updates for validation
-        const sourcePath = storage.buildPath(
-          existingData.target.appname || this.config.appName,
-          existingData.target.holonId,
-          existingData.target.lensName,
-          existingData.target.dataId
-        );
-        const currentSourceData = await storage.read(this.client, sourcePath);
-        const mergedSourceData = { ...currentSourceData, ...sourceUpdates };
+    // OPTIMISTIC UPDATE: Store in write cache and clear from delete cache
+    this._writeCache.set(path, { data: { ...data }, timestamp: Date.now() });
+    this._deleteCache.delete(path);
+    this._log('INFO', '📝 CACHE WRITE', {
+      path,
+      dataId: data.id,
+      cacheSize: this._writeCache.size,
+      mode: options.blocking ? 'blocking' : 'optimistic'
+    });
 
-        const schemaObj = this.schemas.get(lensName);
-        const strict = options.strict !== undefined ? options.strict : schemaObj.strict;
+    // Queue background sync
+    const syncPromise = this._syncWriteToRelay(holonId, lensName, data, path, options);
 
-        if (schemaObj.schema && typeof schemaObj.schema === 'object' && !schemaObj.schema.$ref) {
-          schema.validate(mergedSourceData, schemaObj.schema, lensName, strict);
-        }
-      }
+    // If blocking mode, wait for relay confirmation
+    if (options.blocking) {
+      this._log('DEBUG', '⏳ BLOCKING: Waiting for relay confirmation', { path });
+      return syncPromise;
+    }
 
-      // Update local hologram with its override fields
-      const startTime = Date.now();
-      await storage.write(this.client, path, localData);
-
-      // Update source data with non-local fields (partial update, not replace)
-      if (Object.keys(sourceUpdates).length > 0) {
-        const sourceAppname = existingData.target.appname || this.config.appName;
-        const sourceHolonId = existingData.target.holonId;
-        const sourceLensName = existingData.target.lensName;
-        const sourceDataId = existingData.target.dataId;
-
-        const sourcePath = storage.buildPath(sourceAppname, sourceHolonId, sourceLensName, sourceDataId);
-        await storage.update(this.client, sourcePath, sourceUpdates);
-
-        // Refresh timestamps on all activeHolograms in source data's _meta
-        await federation.refreshActiveHolograms(
-          this.client,
-          sourceAppname,
-          sourceHolonId,
-          sourceLensName,
-          sourceDataId
-        );
+    // Non-blocking: return immediately, sync happens in background
+    this._log('DEBUG', '⚡ OPTIMISTIC: Returning immediately, sync in background', { path });
+    return true;
+  }
+
+  /**
+   * Syncs a write operation to the relay in the background.
+   * Handles hologram writes, propagation, and error logging.
+   *
+   * @private
+   * @param {string} holonId - Holon ID
+   * @param {string} lensName - Lens name
+   * @param {Object} data - Data to write
+   * @param {string} path - Storage path
+   * @param {Object} options - Write options
+   * @returns {Promise<boolean>} True if write succeeded
+   */
+  async _syncWriteToRelay(holonId, lensName, data, path, options) {
+    const startTime = Date.now();
+    this._log('INFO', '🔄 RELAY SYNC START', {
+      path,
+      dataId: data.id,
+      relays: this.client?.relays?.map(r => r.url) || ['local-only']
+    });
+
+    try {
+      // Check for existing hologram
+      const existingData = await storage.read(this.client, path);
+
+      // Handle hologram writes
+      if (existingData && existingData.hologram === true && existingData.target) {
+        this._log('DEBUG', '🔗 Syncing hologram write', { path, target: existingData.target });
+        return this._syncHologramWrite(existingData, data, path, lensName, options);
       }
 
+      // Regular write to relay
+      await storage.write(this.client, path, data);
+
       const endTime = Date.now();
+      const duration = endTime - startTime;
       this._metrics.writes++;
       if (!this._metrics.totalWriteTime) this._metrics.totalWriteTime = 0;
-      this._metrics.totalWriteTime += (endTime - startTime);
+      this._metrics.totalWriteTime += duration;
+
+      this._log('INFO', '✅ RELAY SYNC SUCCESS', {
+        path,
+        dataId: data.id,
+        duration: `${duration}ms`,
+        totalWrites: this._metrics.writes
+      });
+
+      // Clear from write cache after successful sync (optional - keeps cache smaller)
+      // this._writeCache.delete(path);
+
+      // Handle propagation in background
+      const { autoPropagate = true } = options;
+      if (autoPropagate && !data.hologram) {
+        this._log('DEBUG', '📤 Starting propagation', { path });
+        this.propagate(holonId, lensName, data, options.propagationOptions || {})
+          .catch(err => this._log('WARN', '⚠️ Propagation failed', { path, error: err.message }));
+      }
 
       return true;
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      this._log('ERROR', '❌ RELAY SYNC FAILED', {
+        path,
+        dataId: data.id,
+        duration: `${duration}ms`,
+        error: error.message,
+        stack: error.stack?.split('\n')[1]?.trim()
+      });
+      // Keep data in write cache - will be retried or eventually consistent
+      this._log('WARN', '💾 Data retained in write cache for retry', { path, cacheSize: this._writeCache.size });
+      return false;
     }
+  }
 
-    // Regular write (not a hologram) - proceed normally
-    // Add metadata
-    if (!data._meta) {
-      data._meta = {};
+  /**
+   * Handles hologram write synchronization.
+   *
+   * @private
+   */
+  async _syncHologramWrite(existingData, data, path, lensName, options) {
+    const hologramStructureFields = ['hologram', 'soul', 'target', 'id', '_meta'];
+    const localOverrideFields = Object.keys(existingData).filter(k => !hologramStructureFields.includes(k));
+
+    const localData = { ...existingData };
+    const sourceUpdates = {};
+
+    for (const [key, value] of Object.entries(data)) {
+      if (hologramStructureFields.includes(key) || key === '_hologram') continue;
+      if (localOverrideFields.includes(key)) {
+        localData[key] = value;
+      } else {
+        sourceUpdates[key] = value;
+      }
     }
-    data._meta.timestamp = Date.now();
 
-    // Schema validation if exists
-    if (options.validate !== false && this.schemas.has(lensName)) {
+    if (Object.keys(sourceUpdates).length > 0 && options.validate !== false && this.schemas.has(lensName)) {
+      const sourcePath = storage.buildPath(
+        existingData.target.appname || this.config.appName,
+        existingData.target.holonId,
+        existingData.target.lensName,
+        existingData.target.dataId
+      );
+      const currentSourceData = await storage.read(this.client, sourcePath);
+      const mergedSourceData = { ...currentSourceData, ...sourceUpdates };
+
       const schemaObj = this.schemas.get(lensName);
       const strict = options.strict !== undefined ? options.strict : schemaObj.strict;
 
-      // If schema is a URI reference
-      if (schemaObj.schema && typeof schemaObj.schema === 'object' && schemaObj.schema.$ref) {
-        // URI schemas cannot be validated - skip validation in both modes
-        // In a real implementation, URIs would be resolved first
-        // For now, we allow writes through (no validation possible)
-      } else if (schemaObj.schema && typeof schemaObj.schema === 'object') {
-        // Validate if schema is an actual object
-        schema.validate(data, schemaObj.schema, lensName, strict);
+      if (schemaObj.schema && typeof schemaObj.schema === 'object' && !schemaObj.schema.$ref) {
+        schema.validate(mergedSourceData, schemaObj.schema, lensName, strict);
       }
     }
 
-    // Write to storage
     const startTime = Date.now();
-    const success = await storage.write(this.client, path, data);
-    const endTime = Date.now();
-
-    if (success) {
-      this._metrics.writes++;
-      // Track average write time
-      if (!this._metrics.totalWriteTime) this._metrics.totalWriteTime = 0;
-      this._metrics.totalWriteTime += (endTime - startTime);
-
-      // Refresh timestamps on all activeHolograms in the source data's _meta
-      // This allows interfaces to detect updates automatically
-      if (data._meta && Array.isArray(data._meta.activeHolograms) && data._meta.activeHolograms.length > 0) {
-        const result = await federation.refreshActiveHolograms(
-          this.client,
-          this.config.appName,
-          holonId,
-          lensName,
-          data.id,
-          data  // Pass the data we already have
-        );
-        // Update the written data with refreshed timestamps (already done in-place by refreshActiveHolograms)
-        if (result.refreshed > 0) {
-          // Re-write to persist the updated activeHolograms timestamps
-          await storage.write(this.client, path, result.sourceData);
-        }
-      }
+    await storage.write(this.client, path, localData);
+
+    if (Object.keys(sourceUpdates).length > 0) {
+      const sourcePath = storage.buildPath(
+        existingData.target.appname || this.config.appName,
+        existingData.target.holonId,
+        existingData.target.lensName,
+        existingData.target.dataId
+      );
+      await storage.update(this.client, sourcePath, sourceUpdates);
+      await federation.refreshActiveHolograms(
+        this.client,
+        existingData.target.appname || this.config.appName,
+        existingData.target.holonId,
+        existingData.target.lensName,
+        existingData.target.dataId
+      );
     }
 
-    return success;
+    const endTime = Date.now();
+    this._metrics.writes++;
+    if (!this._metrics.totalWriteTime) this._metrics.totalWriteTime = 0;
+    this._metrics.totalWriteTime += (endTime - startTime);
+
+    return true;
   }
 
   /**
-   * Resolve holograms recursively
+   * Recursively resolves holograms (references) to their source data.
+   * Handles circular reference detection and local overrides.
+   *
    * @private
-   * @param {*} data - Data that may contain holograms (object, array, or primitive)
-   * @returns {Promise<*>} Resolved data
+   * @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) {
-    // Handle null/undefined
+  async _resolveHolograms(data, visited = new Set()) {
     if (!data) return data;
 
-    // Handle arrays - resolve each item and filter out nulls
     if (Array.isArray(data)) {
       const resolved = [];
       for (const item of data) {
-        const resolvedItem = await this._resolveHolograms(item);
-        // Only add non-null items to preserve array integrity
-        if (resolvedItem != null) {
+        const resolvedItem = await this._resolveHolograms(item, new Set());
+        if (resolvedItem !== null) {
           resolved.push(resolvedItem);
         }
       }
       return resolved;
     }
 
-    // Handle objects
-    if (typeof data === 'object') {
-      // Check if this is a hologram - ONLY if explicitly marked with hologram:true
-      // Having a 'soul' property alone does NOT make it a hologram (soul is used for metadata/linking)
-      const isHologram = data.hologram === true;
+    if (data && typeof data === 'object') {
+      if (data.hologram === true && data.target) {
+        const sourcePath = storage.buildPath(
+          data.target.appname || this.config.appName,
+          data.target.holonId,
+          data.target.lensName,
+          data.target.dataId
+        );
+        this._log('DEBUG', 'resolving hologram', {
+          hologramId: data.id,
+          sourcePath,
+          targetHolon: data.target.holonId,
+          targetLens: data.target.lensName,
+          targetDataId: data.target.dataId
+        });
+
+        // Circular reference detection
+        if (visited.has(sourcePath)) {
+          this._log('WARN', 'Circular hologram reference detected', { sourcePath });
+          return null;
+        }
+        visited.add(sourcePath);
+
+        let resolveOptions = {};
+        if (data.target.authorPubKey) {
+          resolveOptions.authors = [data.target.authorPubKey];
+          resolveOptions.includeAuthor = true;
+        }
 
-      if (isHologram) {
-        const resolved = await federation.resolveHologram(this.client, data);
-        // Recursively resolve the resolved data (in case it contains more holograms)
-        return resolved ? await this._resolveHolograms(resolved) : null;
-      }
+        const sourceData = await storage.read(this.client, sourcePath, resolveOptions);
+        this._log('DEBUG', 'hologram source fetched', { found: !!sourceData, sourcePath });
+        if (sourceData) {
+          // If source is also a hologram, recursively resolve it
+          let resolvedSource = sourceData;
+          if (sourceData.hologram === true && sourceData.target) {
+            resolvedSource = await this._resolveHolograms(sourceData, visited);
+            if (resolvedSource === null) {
+              return null; // Circular reference or unresolvable
+            }
+          }
 
-      // Not a hologram, but might contain holograms in nested properties
-      // For now, just return as-is to avoid deep traversal overhead
-      // If needed, we can add deep resolution later
-      return data;
-    }
+          // Get local override fields from the hologram (excluding hologram structure fields)
+          const hologramStructureFields = ['hologram', 'soul', 'target', '_meta', 'id', 'capability', 'crossHolosphere'];
+          const localOverrides = {};
+          for (const [k, v] of Object.entries(data)) {
+            if (!hologramStructureFields.includes(k)) {
+              localOverrides[k] = v;
+            }
+          }
+
+          const merged = {
+            ...resolvedSource,
+            ...localOverrides,
+            _hologram: {
+              isHologram: true,
+              soul: data.soul,
+              sourceHolon: data.target.holonId,
+              source: data.target,
+              localOverrides: Object.keys(localOverrides),
+              crossHolosphere: data.crossHolosphere || false,
+            }
+          };
+
+          // Preserve source _meta but add hologram source info
+          if (resolvedSource._meta) {
+            merged._meta = { ...resolvedSource._meta, source: data.target.holonId };
+          } else {
+            merged._meta = { source: data.target.holonId };
+          }
 
-    // Primitive value
+          return merged;
+        }
+        return null; // Source not found
+      }
+    }
     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 = {}) {
-    // Validate inputs
     if (!holonId || typeof holonId !== 'string') {
       throw new ValidationError('ValidationError: holonId must be a non-empty string');
     }
@@ -374,316 +601,569 @@ export class HoloSphere extends HoloSphereCore {
       throw new ValidationError('ValidationError: lensName must be a non-empty string');
     }
 
-    const startTime = Date.now();
-    this._metrics.reads++;
-
-    // Build the scope for capability lookup
-    const scope = { holonId, lensName };
-    if (dataId) scope.dataId = dataId;
-
-    // Get federated authors (partners who granted us read access)
-    // Default: federated=true unless explicitly disabled
-    const federated = options.federated !== false;
-    let authors = [this.client.publicKey]; // Always include our own data
-
-    if (federated) {
-      try {
-        const federatedAuthors = await registry.getFederatedAuthorsForScope(
-          this.client,
-          this.config.appName,
-          scope,
-          'read'
-        );
-        // Add federated author pubKeys
-        for (const { pubKey } of federatedAuthors) {
-          if (!authors.includes(pubKey)) {
-            authors.push(pubKey);
-          }
-        }
-      } catch (error) {
-        // Silently continue with just our own data if federation lookup fails
-        console.debug('[read] Federation lookup failed, using local only:', error.message);
+    const capToken = options.capabilityToken || options.capability;
+    if (capToken) {
+      const authorized = await this.verifyCapability(capToken, 'read', { holonId, lensName, dataId });
+      if (!authorized) {
+        throw new AuthorizationError('AuthorizationError: Invalid capability token for read operation', 'read');
       }
     }
 
-    // Query options including federated authors
-    const queryOptions = {
-      authors,
-      includeAuthor: true, // Track which author each item came from
-    };
+    const startTime = Date.now();
+    let result;
 
     if (dataId) {
       const path = storage.buildPath(this.config.appName, holonId, lensName, dataId);
-      const data = await storage.read(this.client, path, queryOptions);
-
-      // Filter out deleted items
-      if (data && data._deleted) {
-        const endTime = Date.now();
-        if (!this._metrics.totalReadTime) this._metrics.totalReadTime = 0;
-        this._metrics.totalReadTime += (endTime - startTime);
-        return null;
-      }
 
-      // Always resolve holograms
-      const resolved = await this._resolveHolograms(data);
-
-      const endTime = Date.now();
-      if (!this._metrics.totalReadTime) this._metrics.totalReadTime = 0;
-      this._metrics.totalReadTime += (endTime - startTime);
-      return resolved;
+      // Check delete cache first - if deleted, return null immediately
+      if (this._deleteCache.has(path)) {
+        this._log('INFO', '🗑️ CACHE READ: Deleted item', {
+          path,
+          source: 'delete-cache',
+          deleteCacheSize: this._deleteCache.size
+        });
+        result = null;
+      } else {
+        // Check write cache for optimistic reads
+        const cached = this._writeCache.get(path);
+        if (cached) {
+          const cacheAge = Date.now() - cached.timestamp;
+          this._log('INFO', '⚡ CACHE HIT: Write cache', {
+            path,
+            source: 'write-cache',
+            cacheAge: `${cacheAge}ms`,
+            writeCacheSize: this._writeCache.size
+          });
+          result = cached.data;
+        } else {
+          this._log('DEBUG', '📖 CACHE MISS: Reading from storage', { path });
+          result = await storage.read(this.client, path);
+          this._log('INFO', '💾 STORAGE READ', {
+            path,
+            source: 'storage',
+            found: !!result,
+            isHologram: result?.hologram === true
+          });
+        }
+      }
     } else {
       const path = storage.buildPath(this.config.appName, holonId, lensName);
-      const result = await storage.readAll(this.client, path, {
-        ...queryOptions,
-        hybrid: this.config.hybridMode
-      });
+      this._log('DEBUG', 'readAll', { holonId, lensName, path });
+
+      // For readAll, merge cached writes with storage results and filter deleted
+      const storageResult = await storage.readAll(this.client, path);
+      result = this._mergeWithWriteCache(storageResult, path);
+      this._log('DEBUG', 'readAll result', { count: Array.isArray(result) ? result.length : 0 });
+    }
 
-      // Always resolve holograms in array results
-      const resolved = await this._resolveHolograms(result);
+    const { resolveHolograms = true } = options;
+    if (resolveHolograms && result) {
+      this._log('DEBUG', 'resolving holograms', { itemCount: Array.isArray(result) ? result.length : 1 });
+      result = await this._resolveHolograms(result);
+    }
 
-      // Filter out deleted items
-      const filtered = Array.isArray(resolved)
-        ? resolved.filter(item => !item || !item._deleted)
-        : (resolved && resolved._deleted ? null : resolved);
+    const endTime = Date.now();
+    this._metrics.reads++;
+    if (!this._metrics.totalReadTime) this._metrics.totalReadTime = 0;
+    this._metrics.totalReadTime += (endTime - startTime);
 
-      const endTime = Date.now();
-      if (!this._metrics.totalReadTime) this._metrics.totalReadTime = 0;
-      this._metrics.totalReadTime += (endTime - startTime);
-      return filtered;
+    return result;
+  }
+
+  /**
+   * Merges storage results with write cache for readAll operations.
+   * Cached writes take precedence over storage data.
+   * Deleted items are filtered out.
+   *
+   * @private
+   * @param {Array} storageResult - Results from storage
+   * @param {string} pathPrefix - Path prefix for filtering cache
+   * @returns {Array} Merged results
+   */
+  _mergeWithWriteCache(storageResult, pathPrefix) {
+    const results = Array.isArray(storageResult) ? [...storageResult] : [];
+    const resultMap = new Map(results.map(item => [item.id, item]));
+
+    // Check for cached writes matching this path prefix
+    for (const [cachedPath, cached] of this._writeCache.entries()) {
+      if (cachedPath.startsWith(pathPrefix + '/')) {
+        // Cached write - update or add to results
+        const cachedData = cached.data;
+        if (cachedData.id) {
+          resultMap.set(cachedData.id, cachedData);
+        }
+      }
+    }
+
+    // Filter out deleted items
+    for (const deletedPath of this._deleteCache) {
+      if (deletedPath.startsWith(pathPrefix + '/')) {
+        // Extract the dataId from the path (last segment)
+        const dataId = deletedPath.split('/').pop();
+        resultMap.delete(dataId);
+      }
     }
+
+    return Array.from(resultMap.values());
   }
 
+  /**
+   * Updates existing data in a specific holon and lens.
+   * By default, update is optimistic (non-blocking) - returns immediately after caching merged data.
+   * Data is synced to relays in the background.
+   *
+   * @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
+   * @param {boolean} [options.blocking=false] - If true, wait for relay confirmation before returning
+   * @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 = {}) {
-    // Check authorization if capability token provided
+    if (!holonId || typeof holonId !== 'string') {
+      throw new ValidationError('ValidationError: holonId must be a non-empty string');
+    }
+    if (!lensName || typeof lensName !== 'string') {
+      throw new ValidationError('ValidationError: lensName must be a non-empty string');
+    }
+    if (!dataId || typeof dataId !== 'string') {
+      throw new ValidationError('ValidationError: dataId must be a non-empty string');
+    }
+    if (!updates || typeof updates !== 'object') {
+      throw new ValidationError('ValidationError: updates must be an object');
+    }
+
     const capToken = options.capabilityToken || options.capability;
     if (capToken) {
-      const authorized = await this.verifyCapability(
-        capToken,
-        'write',
-        { holonId, lensName }
-      );
+      const authorized = await this.verifyCapability(capToken, 'write', { holonId, lensName, dataId });
       if (!authorized) {
         throw new AuthorizationError('AuthorizationError: Invalid capability token for update operation', 'write');
       }
     }
 
-    // Read raw data (without resolving) to check if it's a hologram
     const path = storage.buildPath(this.config.appName, holonId, lensName, dataId);
-    const rawData = await storage.read(this.client, path);
-
-    // If this is a hologram, split updates between local overrides and source
-    if (rawData && rawData.hologram === true && rawData.target) {
-      // Fields that are stored in the hologram itself (local overrides)
-      // These are fields that exist in the hologram beyond the core hologram structure
-      const hologramStructureFields = ['hologram', 'soul', 'target', 'id', '_meta'];
-      const localOverrideFields = Object.keys(rawData).filter(k => !hologramStructureFields.includes(k));
-
-      // Split updates: local fields stay local, everything else goes to source
-      const localUpdates = {};
-      const sourceUpdates = {};
-
-      for (const [key, value] of Object.entries(updates)) {
-        if (hologramStructureFields.includes(key)) {
-          // Skip hologram structure fields entirely
-          continue;
-        } else if (localOverrideFields.includes(key)) {
-          // This field exists in the hologram - update locally
-          localUpdates[key] = value;
-        } else {
-          // This field doesn't exist in hologram - update source
-          sourceUpdates[key] = value;
-        }
-      }
 
-      // Update local hologram overrides
-      if (Object.keys(localUpdates).length > 0) {
-        await storage.update(this.client, path, localUpdates);
-      }
+    // Check write cache first, then storage
+    const cached = this._writeCache.get(path);
+    const existingData = cached ? cached.data : await storage.read(this.client, path);
+    const dataSource = cached ? 'write-cache' : 'storage';
 
-      // Update source data
-      if (Object.keys(sourceUpdates).length > 0) {
-        const sourcePath = storage.buildPath(
-          rawData.target.appname || this.config.appName,
-          rawData.target.holonId,
-          rawData.target.lensName,
-          rawData.target.dataId
-        );
-        await storage.update(this.client, sourcePath, sourceUpdates);
-      }
+    if (!existingData) {
+      this._log('DEBUG', '✏️ UPDATE: Data not found', { path, dataId });
+      return false;
+    }
 
-      return true;
+    this._log('DEBUG', '✏️ UPDATE: Found data', { path, dataId, source: dataSource });
+
+    // Handle hologram updates - delegate to write() which is already optimistic
+    if (existingData.hologram === true && existingData.target) {
+      this._log('DEBUG', '🔗 Updating hologram', { path });
+      return this.write(holonId, lensName, { ...existingData, ...updates, id: dataId }, options);
     }
 
-    // Regular data (not a hologram) - proceed with normal update
-    // Schema validation if exists and updates data
+    const mergedData = { ...existingData, ...updates };
+    mergedData._meta = mergedData._meta || {};
+    mergedData._meta.updatedAt = Date.now();
+
     if (options.validate !== false && this.schemas.has(lensName)) {
-      const existing = await this.read(holonId, lensName, dataId);
-      const merged = { ...existing, ...updates };
       const schemaObj = this.schemas.get(lensName);
       const strict = options.strict !== undefined ? options.strict : schemaObj.strict;
-
-      // If schema is a URI reference
-      if (schemaObj.schema && typeof schemaObj.schema === 'object' && schemaObj.schema.$ref) {
-        // URI schemas cannot be validated - skip validation in both modes
-        // In a real implementation, URIs would be resolved first
-        // For now, we allow updates through (no validation possible)
-      } else if (schemaObj.schema && typeof schemaObj.schema === 'object') {
-        schema.validate(merged, schemaObj.schema, lensName, strict);
+      if (schemaObj.schema && typeof schemaObj.schema === 'object' && !schemaObj.schema.$ref) {
+        schema.validate(mergedData, schemaObj.schema, lensName, strict);
       }
     }
 
-    return storage.update(this.client, path, updates);
+    // OPTIMISTIC UPDATE: Store in write cache and clear from delete cache
+    this._writeCache.set(path, { data: { ...mergedData }, timestamp: Date.now() });
+    this._deleteCache.delete(path);
+    this._log('INFO', '✏️ CACHE UPDATE', {
+      path,
+      dataId,
+      updatedFields: Object.keys(updates),
+      cacheSize: this._writeCache.size,
+      mode: options.blocking ? 'blocking' : 'optimistic'
+    });
+
+    // Queue background sync
+    const syncPromise = this._syncUpdateToRelay(holonId, lensName, dataId, mergedData, existingData, path);
+
+    if (options.blocking) {
+      this._log('DEBUG', '⏳ BLOCKING: Waiting for update confirmation', { path });
+      return syncPromise;
+    }
+
+    return true;
+  }
+
+  /**
+   * Syncs an update operation to the relay in the background.
+   *
+   * @private
+   */
+  async _syncUpdateToRelay(holonId, lensName, dataId, mergedData, existingData, path) {
+    const startTime = Date.now();
+    this._log('INFO', '🔄 UPDATE SYNC START', {
+      path,
+      dataId,
+      relays: this.client?.relays?.map(r => r.url) || ['local-only']
+    });
+
+    try {
+      await storage.write(this.client, path, mergedData);
+      const duration = Date.now() - startTime;
+
+      this._metrics.writes++;
+      if (!this._metrics.totalWriteTime) this._metrics.totalWriteTime = 0;
+      this._metrics.totalWriteTime += duration;
+
+      this._log('INFO', '✅ UPDATE SYNC SUCCESS', {
+        path,
+        dataId,
+        duration: `${duration}ms`,
+        totalWrites: this._metrics.writes
+      });
+
+      if (existingData._meta && existingData._meta.activeHolograms) {
+        this._log('DEBUG', '🔗 Refreshing active holograms', { path });
+        federation.refreshActiveHolograms(this.client, this.config.appName, holonId, lensName, dataId)
+          .catch(err => this._log('WARN', '⚠️ Hologram refresh failed', { path, error: err.message }));
+      }
+
+      return true;
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      this._log('ERROR', '❌ UPDATE SYNC FAILED', {
+        path,
+        dataId,
+        duration: `${duration}ms`,
+        error: error.message,
+        stack: error.stack?.split('\n')[1]?.trim()
+      });
+      this._log('WARN', '💾 Data retained in write cache for retry', { path, cacheSize: this._writeCache.size });
+      return false;
+    }
   }
 
+  /**
+   * Deletes data from a specific holon and lens.
+   * By default, delete is optimistic (non-blocking) - returns immediately after cache invalidation.
+   *
+   * @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
+   * @param {boolean} [options.blocking=false] - If true, wait for relay confirmation before returning
+   * @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 = {}) {
-    // Read existing data to check ownership and get activeHolograms
-    const existing = await this.read(holonId, lensName, dataId);
+    if (!holonId || typeof holonId !== 'string') {
+      throw new ValidationError('ValidationError: holonId must be a non-empty string');
+    }
+    if (!lensName || typeof lensName !== 'string') {
+      throw new ValidationError('ValidationError: lensName must be a non-empty string');
+    }
+    if (!dataId || typeof dataId !== 'string') {
+      throw new ValidationError('ValidationError: dataId must be a non-empty string');
+    }
+
+    const path = storage.buildPath(this.config.appName, holonId, lensName, dataId);
+
+    // Check write cache first, then storage
+    const cached = this._writeCache.get(path);
+    let existingData = cached ? cached.data : null;
+    let dataSource = cached ? 'write-cache' : null;
+
+    if (!existingData) {
+      existingData = await storage.read(this.client, path);
+      dataSource = existingData ? 'storage' : null;
+    }
 
-    // If data doesn't exist, return false
-    if (!existing) {
+    // Return false if data doesn't exist in cache or storage
+    if (!existingData) {
+      this._log('DEBUG', '🗑️ DELETE: Data not found', { path });
       return false;
     }
 
-    // Check authorization
-    const capToken = options.capabilityToken || options.capability;
-    const creator = existing._creator || existing.owner;
-    const currentUser = this.client.publicKey;
+    this._log('DEBUG', '🗑️ DELETE: Found data', { path, source: dataSource });
 
-    // Authorization logic:
-    // 1. If capability token provided, verify it
-    // 2. Else if data has a creator/owner AND it's not the current user, deny
-    // 3. Else allow (no owner or current user is owner)
+    // Check authorization: owner can delete, others need capability token
+    const dataOwner = existingData.owner || existingData._creator;
+    const isOwner = !dataOwner || dataOwner === this.client.publicKey;
 
-    if (capToken) {
-      const authorized = await this.verifyCapability(
-        capToken,
-        'delete',
-        { holonId, lensName }
-      );
+    const capToken = options.capabilityToken || options.capability;
+    if (!isOwner) {
+      // Non-owner must provide a valid capability token
+      if (!capToken) {
+        throw new AuthorizationError('AuthorizationError: Capability token required for delete operation', 'delete');
+      }
+      const authorized = await this.verifyCapability(capToken, 'delete', { holonId, lensName, dataId });
       if (!authorized) {
-        const error = new AuthorizationError('AuthorizationError: Invalid capability token for delete operation', 'delete');
-        throw error;
+        throw new AuthorizationError('AuthorizationError: Invalid capability token for delete operation', 'delete');
       }
-    } else if (creator && creator !== currentUser) {
-      // Data has an owner and it's not the current user - require authorization
-      const error = new AuthorizationError('AuthorizationError: Delete operation requires capability token', 'delete');
-      throw error;
-    }
-    // else: no owner or current user is owner - allow deletion
-
-    // Delete all holograms that point to this data
-    if (existing._meta?.activeHolograms && Array.isArray(existing._meta.activeHolograms)) {
-      console.info(`🗑️ Deleting ${existing._meta.activeHolograms.length} holograms for ${holonId}/${lensName}/${dataId}`);
-      for (const hologramEntry of existing._meta.activeHolograms) {
-        try {
-          const hologramPath = storage.buildPath(
-            this.config.appName,
-            hologramEntry.targetHolon,
-            lensName,
-            dataId
-          );
-          await storage.deleteData(this.client, hologramPath);
-          console.info(`   ✓ Deleted hologram in ${hologramEntry.targetHolon}`);
-        } catch (err) {
-          console.warn(`   ⚠️ Failed to delete hologram in ${hologramEntry.targetHolon}:`, err.message);
-        }
+    } else if (capToken) {
+      // Owner provided a token - validate it anyway
+      const authorized = await this.verifyCapability(capToken, 'delete', { holonId, lensName, dataId });
+      if (!authorized) {
+        throw new AuthorizationError('AuthorizationError: Invalid capability token for delete operation', 'delete');
       }
     }
 
-    const path = storage.buildPath(this.config.appName, holonId, lensName, dataId);
-    return storage.deleteData(this.client, path);
+    // OPTIMISTIC DELETE: Remove from write cache and add to delete cache
+    this._writeCache.delete(path);
+    this._deleteCache.add(path);
+    this._log('INFO', '🗑️ CACHE DELETE', {
+      path,
+      dataId,
+      deleteCacheSize: this._deleteCache.size,
+      writeCacheSize: this._writeCache.size,
+      mode: options.blocking ? 'blocking' : 'optimistic'
+    });
+
+    if (existingData.hologram === true) {
+      this._log('DEBUG', '🔗 Deleting hologram', { path });
+      return this.deleteHologram(holonId, lensName, dataId, options);
+    }
+
+    // Delete from storage (background unless blocking)
+    const startTime = Date.now();
+    this._log('INFO', '🔄 DELETE SYNC START', { path, dataId });
+
+    const deletePromise = storage.deleteData(this.client, path).then(() => {
+      const duration = Date.now() - startTime;
+      this._metrics.deletes++;
+      // Clear from delete cache after successful sync
+      this._deleteCache.delete(path);
+      this._log('INFO', '✅ DELETE SYNC SUCCESS', {
+        path,
+        dataId,
+        duration: `${duration}ms`,
+        totalDeletes: this._metrics.deletes,
+        deleteCacheSize: this._deleteCache.size
+      });
+      return true;
+    }).catch(error => {
+      const duration = Date.now() - startTime;
+      this._log('ERROR', '❌ DELETE SYNC FAILED', {
+        path,
+        dataId,
+        duration: `${duration}ms`,
+        error: error.message
+      });
+      // Keep in delete cache so reads still return null
+      this._log('WARN', '💾 Path retained in delete cache', { path, deleteCacheSize: this._deleteCache.size });
+      return false;
+    });
+
+    if (options.blocking) {
+      this._log('DEBUG', '⏳ BLOCKING: Waiting for delete confirmation', { path });
+      return deletePromise;
+    }
+
+    // Non-blocking: return immediately
+    this._log('DEBUG', '⚡ OPTIMISTIC: Returning immediately, delete sync in background', { path });
+    return true;
   }
 
-  // === Global Data Operations ===
+  // === Global Tables ===
+
+  /**
+   * Writes data to a global table (not holon-specific).
+   *
+   * @param {string} table - Name of the global table
+   * @param {Object} data - Data object to write (must have an id field)
+   * @returns {Promise<boolean>} True if write succeeded
+   */
   async writeGlobal(table, data) {
     return globalTables.writeGlobal(this.client, this.config.appName, table, data);
   }
 
+  /**
+   * Reads data from a global table.
+   *
+   * @param {string} table - Name of the global table
+   * @param {string|null} [key=null] - Specific key to read, or null to read all
+   * @returns {Promise<Object|Array|null>} Data object, array of objects, or null
+   */
   async readGlobal(table, key = null) {
     return globalTables.readGlobal(this.client, this.config.appName, table, key);
   }
 
+  /**
+   * Updates data in a global table.
+   *
+   * @param {string} table - Name of the global table
+   * @param {string} key - Key of the data to update
+   * @param {Object} updates - Object containing fields to update
+   * @returns {Promise<boolean>} True if update succeeded
+   */
   async updateGlobal(table, key, updates) {
     return globalTables.updateGlobal(this.client, this.config.appName, table, key, updates);
   }
 
+  /**
+   * Deletes data from a global table.
+   *
+   * @param {string} table - Name of the global table
+   * @param {string} key - Key of the data to delete
+   * @returns {Promise<boolean>} True if deletion succeeded
+   */
   async deleteGlobal(table, key) {
     return globalTables.deleteGlobal(this.client, this.config.appName, table, key);
   }
 
+  /**
+   * Gets all data from a global table.
+   *
+   * @param {string} table - Name of the global table
+   * @returns {Promise<Array>} Array of all data objects in the table
+   */
   async getAllGlobal(table) {
-    return globalTables.readGlobal(this.client, this.config.appName, table);
+    return globalTables.getAllGlobal(this.client, this.config.appName, table);
   }
 
+  /**
+   * Deletes all data from a global table.
+   *
+   * @param {string} table - Name of the global table
+   * @returns {Promise<boolean>} True if deletion succeeded
+   */
   async deleteAllGlobal(table) {
     return globalTables.deleteAllGlobal(this.client, this.config.appName, table);
   }
 
-  // === Holon Data Operations ===
+  // === 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);
+    return this.read(holonId, lensName, null);
   }
 
+  /**
+   * Deletes all data from a specific holon and lens.
+   *
+   * @param {string} holonId - H3 cell ID for the holon
+   * @param {string} lensName - Name of the lens (data category)
+   * @returns {Promise<boolean>} True if deletion succeeded
+   */
   async deleteAll(holonId, lensName) {
     const path = storage.buildPath(this.config.appName, holonId, lensName);
     return storage.deleteAll(this.client, path);
   }
 
   // === Schema Operations ===
-  async setSchema(lensName, schemaObj, strict = false) {
-    let resolvedSchema = schemaObj;
-
-    // If schemaObj is a string (URI), store as reference
-    if (typeof schemaObj === 'string') {
-      // Store as URI reference - validation will happen when used
-      resolvedSchema = { $ref: schemaObj };
-    }
 
-    if (!resolvedSchema || (typeof resolvedSchema !== 'object' && typeof resolvedSchema !== 'boolean')) {
-      throw new ValidationError('Schema must be a valid JSON Schema object or boolean');
+  /**
+   * Sets a JSON Schema for validating data in a specific lens.
+   *
+   * @param {string} lensName - Name of the lens to associate the schema with
+   * @param {Object|string} schemaInput - JSON Schema object or URI reference
+   * @param {boolean} [strict=false] - If true, validation will reject additional properties
+   * @returns {Promise<void>}
+   * @throws {ValidationError} If lensName is invalid or schema format is invalid
+   */
+  async setSchema(lensName, schemaInput, strict = false) {
+    if (!lensName || typeof lensName !== 'string') {
+      throw new ValidationError('ValidationError: lensName must be a non-empty string');
     }
 
-    // Validate that it's a valid JSON Schema (basic check) - only for actual schemas, not refs
-    if (typeof resolvedSchema === 'object' && !resolvedSchema.$ref) {
-      if (!resolvedSchema.type && !resolvedSchema.properties && !resolvedSchema.items && resolvedSchema !== true && resolvedSchema !== false) {
-        throw new ValidationError('ValidationError: Invalid JSON Schema format - must have type, properties, or items');
+    // Handle null/undefined
+    if (schemaInput == null) {
+      throw new ValidationError('ValidationError: schema cannot be null or undefined');
+    }
+
+    let schemaObj;
+
+    // Handle URI string - store as $ref
+    if (typeof schemaInput === 'string') {
+      schemaObj = { $ref: schemaInput };
+    } else if (typeof schemaInput === 'object') {
+      // Validate it looks like a JSON Schema (must have type or $ref or properties or items)
+      const isValidSchema = schemaInput.$ref ||
+        schemaInput.type ||
+        schemaInput.properties ||
+        schemaInput.items ||
+        schemaInput.allOf ||
+        schemaInput.anyOf ||
+        schemaInput.oneOf ||
+        schemaInput.$schema;
+
+      if (!isValidSchema) {
+        throw new ValidationError('ValidationError: Invalid JSON Schema format');
       }
+      schemaObj = schemaInput;
+    } else {
+      throw new ValidationError('ValidationError: schema must be an object or URI string');
     }
 
-    this.schemas.set(lensName, { schema: resolvedSchema, strict });
+    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);
-    schema.clearSchemaCache(lensName);
+    // Returns undefined for contract compliance
   }
 
   // === Federation Operations ===
+
+  /**
+   * Sets up federation between two holons for a specific lens.
+   * Federation enables data sharing and synchronization between holons.
+   *
+   * @param {string} sourceHolon - Source holon H3 cell ID
+   * @param {string} targetHolon - Target holon H3 cell ID
+   * @param {string} lensName - Name of the lens to federate
+   * @param {Object} [options={}] - Federation options
+   * @param {string} [options.direction='outbound'] - Direction: 'inbound', 'outbound', or 'bidirectional'
+   * @param {string} [options.mode='reference'] - Mode: 'reference' (hologram) or 'copy'
+   * @param {Function} [options.filter] - Filter function to select which data to federate
+   * @returns {Promise<boolean>} True if federation was set up successfully
+   * @throws {Error} If trying to federate a holon with itself or invalid direction
+   */
   async federate(sourceHolon, targetHolon, lensName, options = {}) {
-    // Validate self-federation
+    const { direction = 'outbound', mode = 'reference', filter = null } = options;
+
+    // Validation
     if (sourceHolon === targetHolon) {
       throw new Error('Cannot federate a holon with itself');
     }
-
-    // Validate direction (if provided)
-    if (options.direction && !['inbound', 'outbound', 'bidirectional'].includes(options.direction)) {
-      throw new Error('Invalid federation direction - must be inbound, outbound, or bidirectional');
-    }
-
-    // Handle bidirectional as both inbound and outbound
-    if (options.direction === 'bidirectional') {
-      const { direction, ...restOptions } = options;
-      const outboundResult = await this.federate(sourceHolon, targetHolon, lensName, { ...restOptions, direction: 'outbound' });
-      const inboundResult = await this.federate(sourceHolon, targetHolon, lensName, { ...restOptions, direction: 'inbound' });
-      return outboundResult && inboundResult;
+    if (!['inbound', 'outbound', 'bidirectional'].includes(direction)) {
+      throw new Error(`Invalid direction: ${direction}. Must be 'inbound', 'outbound', or 'bidirectional'`);
     }
 
-    const result = await federation.setupFederation(
+    // Store federation config
+    await federation.setupFederation(
       this.client,
       this.config.appName,
       sourceHolon,
@@ -692,133 +1172,100 @@ export class HoloSphere extends HoloSphereCore {
       options
     );
 
-    if (result) {
-      if (!this._metrics.federations) this._metrics.federations = 0;
-      this._metrics.federations++;
+    // Actually propagate existing data based on direction
+    if (direction === 'outbound' || direction === 'bidirectional') {
+      await this._propagateExistingData(sourceHolon, targetHolon, lensName, { mode, filter });
+    }
+    if (direction === 'inbound' || direction === 'bidirectional') {
+      await this._propagateExistingData(targetHolon, sourceHolon, lensName, { mode, filter });
+    }
 
-      // By default, propagate existing data when federation is set up
-      // Set propagateExisting: false to only federate future writes
-      const propagateExisting = options.propagateExisting !== false;
-
-      if (!propagateExisting) {
-        return result;
-      }
-
-      // Propagate existing data based on direction
-      // Default to 'outbound' (source -> target) if no direction specified
-      const direction = options.direction || 'outbound';
-      const mode = options.mode || 'reference';
-      const filter = options.filter;
-
-      if (direction === 'outbound') {
-        // Source -> Target: propagate data from source to target
-        // Check if receiver accepts this lens in their inbound
-        const targetFederation = await this.getFederation(targetHolon);
-        const receiverLensConfig = targetFederation?.lensConfig?.[sourceHolon];
-        if (receiverLensConfig && receiverLensConfig.inbound && !receiverLensConfig.inbound.includes(lensName)) {
-          console.log(`Skipping outbound propagation - ${targetHolon} doesn't accept lens '${lensName}' in inbound from ${sourceHolon}`);
-        } else {
-          // Read raw data to avoid resolving holograms
-          const path = storage.buildPath(this.config.appName, sourceHolon, lensName);
-          const sourceData = await storage.readAll(this.client, path);
-          const sourceArray = Array.isArray(sourceData) ? sourceData : (sourceData ? [sourceData] : []);
-
-          for (const item of sourceArray) {
-            if (item.id === '_federation') continue; // Skip federation config
-            // Skip items that are already holograms or from another source
-            if (item.hologram === true) continue;
-            if (item._meta && item._meta.source && item._meta.source !== sourceHolon) continue;
-            if (filter && !filter(item)) continue; // Apply filter if provided
-
-            await federation.propagateData(
-              this.client,
-              this.config.appName,
-              item,
-              sourceHolon,
-              targetHolon,
-              lensName,
-              mode
-            );
-          }
-        }
-      }
+    this._metrics.federations = (this._metrics.federations || 0) + 1;
+    return true;
+  }
 
-      if (direction === 'inbound') {
-        // Target -> Source: propagate data from target to source
-        // Check if receiver (source) accepts this lens in their inbound
-        const sourceFederation = await this.getFederation(sourceHolon);
-        const receiverLensConfig = sourceFederation?.lensConfig?.[targetHolon];
-        if (receiverLensConfig && receiverLensConfig.inbound && !receiverLensConfig.inbound.includes(lensName)) {
-          console.log(`Skipping inbound propagation - ${sourceHolon} doesn't accept lens '${lensName}' in inbound from ${targetHolon}`);
-        } else {
-          // Read raw data to avoid resolving holograms
-          const path = storage.buildPath(this.config.appName, targetHolon, lensName);
-          const targetData = await storage.readAll(this.client, path);
-          const targetArray = Array.isArray(targetData) ? targetData : (targetData ? [targetData] : []);
-
-          for (const item of targetArray) {
-            if (item.id === '_federation') continue; // Skip federation config
-            // Skip items that are already holograms or from another source
-            if (item.hologram === true) continue;
-            if (item._meta && item._meta.source && item._meta.source !== targetHolon) continue;
-            if (filter && !filter(item)) continue; // Apply filter if provided
-
-            await federation.propagateData(
-              this.client,
-              this.config.appName,
-              item,
-              targetHolon,
-              sourceHolon,
-              lensName,
-              mode
-            );
-          }
-        }
-      }
+  /**
+   * Propagates existing data from one holon to another.
+   *
+   * @private
+   * @param {string} fromHolon - Source holon H3 cell ID
+   * @param {string} toHolon - Target holon H3 cell ID
+   * @param {string} lensName - Name of the lens
+   * @param {Object} [options={}] - Propagation options
+   * @param {string} [options.mode='reference'] - Mode: 'reference' or 'copy'
+   * @param {Function} [options.filter] - Filter function to select data
+   * @returns {Promise<void>}
+   */
+  async _propagateExistingData(fromHolon, toHolon, lensName, options = {}) {
+    const { mode = 'reference', filter = null } = options;
+    const existingData = await this.read(fromHolon, lensName, null, { resolveHolograms: false });
+    if (!existingData) return;
+
+    const items = Array.isArray(existingData) ? existingData : [existingData];
+    for (const item of items) {
+      // Skip holograms to avoid circular propagation
+      if (item.hologram === true) continue;
+      // Apply filter if provided
+      if (filter && !filter(item)) continue;
+      await federation.propagateData(
+        this.client,
+        this.config.appName,
+        item,
+        fromHolon,
+        toHolon,
+        lensName,
+        mode
+      );
     }
-
-    return result;
   }
 
+  /**
+   * Gets federated data from a holon, optionally resolving holograms.
+   *
+   * @param {string} holonId - H3 cell ID for the holon
+   * @param {string} lensName - Name of the lens
+   * @param {Object} [options={}] - Options
+   * @param {boolean} [options.resolveHolograms=true] - Whether to resolve hologram references
+   * @returns {Promise<Array|null>} Array of data objects or null
+   */
   async getFederatedData(holonId, lensName, options = {}) {
     const { resolveHolograms = true } = options;
+    const path = storage.buildPath(this.config.appName, holonId, lensName);
+    const data = await storage.readAll(this.client, path);
 
-    // For getFederatedData, we just return the local data
-    // The federation setup already propagates data (as holograms or copies)
-    // So all federated data should already be accessible locally
-
-    if (resolveHolograms) {
-      // Use normal read which auto-resolves holograms
-      const localData = await this.read(holonId, lensName);
-      const localArray = Array.isArray(localData) ? localData : (localData ? [localData] : []);
-
-      // Filter out federation config and nulls
-      return localArray.filter(item => item != null && item.id !== '_federation');
-    } else {
-      // Read without resolving holograms - need to read raw data
-      const path = storage.buildPath(this.config.appName, holonId, lensName);
-      const rawData = await storage.readAll(this.client, path);
-      const rawArray = Array.isArray(rawData) ? rawData : (rawData ? [rawData] : []);
+    if (!data || !resolveHolograms) return data;
 
-      // Filter out federation config
-      return rawArray.filter(item => item != null && item.id !== '_federation');
-    }
+    // Resolve holograms using existing method
+    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) {
-    // Delete federation config (idempotent - always returns true)
-    const path = storage.buildPath(this.config.appName, sourceHolon, lensName, '_federation');
-    await storage.deleteData(this.client, path);
+    // Remove federation config for this relationship - idempotent
+    const configPath = storage.buildPath(this.config.appName, sourceHolon, lensName, '_federation');
+    try {
+      await storage.deleteData(this.client, configPath);
+    } catch (e) {
+      // Ignore errors - already unfederated or doesn't exist
+    }
     return true;
   }
 
   /**
-   * Update local overrides on a hologram (e.g., position, pinned status)
-   * @param {string} holonId - Holon where the hologram lives
-   * @param {string} lensName - Lens name (e.g., 'quests')
-   * @param {string} dataId - Data ID of the hologram
-   * @param {Object} overrides - Local fields to update (e.g., { x: 100, y: 200 })
-   * @returns {Promise<boolean>} Success indicator
+   * Updates local override values on a hologram.
+   *
+   * @param {string} holonId - H3 cell ID where the hologram exists
+   * @param {string} lensName - Name of the lens
+   * @param {string} dataId - ID of the hologram
+   * @param {Object} overrides - Object containing local override values
+   * @returns {Promise<boolean>} True if update succeeded
    */
   async updateHologramOverrides(holonId, lensName, dataId, overrides) {
     return federation.updateHologramOverrides(
@@ -832,17 +1279,15 @@ export class HoloSphere extends HoloSphereCore {
   }
 
   /**
-   * Create a hologram (lightweight reference) for federation
-   * @param {string} sourceHolon - Source holon ID where the original data lives
-   * @param {string} lensName - Lens name (e.g., 'quests')
-   * @param {Object} data - Data object (must have an 'id' property)
-   * @param {string} [targetHolon] - Optional target holon ID (defaults to sourceHolon)
-   * @returns {Object} Hologram object ready to be written to a holon
+   * 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) {
-    if (!data || !data.id) {
-      throw new Error('createHologram: data must have an id property');
-    }
     return federation.createHologram(
       sourceHolon,
       targetHolon || sourceHolon,
@@ -853,29 +1298,31 @@ export class HoloSphere extends HoloSphereCore {
   }
 
   /**
-   * Get active holograms for a specific data item
-   * Returns the activeHolograms array from the source data's _meta
-   * @param {string} holonId - Source holon ID
-   * @param {string} lensName - Lens name (e.g., 'quests')
-   * @param {string} dataId - Data ID to get holograms for
-   * @returns {Promise<Object[]>} Array of hologram info objects with timestamps
+   * 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 data = await this.read(holonId, lensName, dataId);
-    if (!data || !data._meta || !Array.isArray(data._meta.activeHolograms)) {
+    // Read the source data and return its activeHolograms list
+    const path = storage.buildPath(this.config.appName, holonId, lensName, dataId);
+    const sourceData = await storage.read(this.client, path);
+    if (!sourceData || !sourceData._meta || !sourceData._meta.activeHolograms) {
       return [];
     }
-    return data._meta.activeHolograms;
+    return sourceData._meta.activeHolograms;
   }
 
   /**
-   * Remove a hologram reference from source data's _meta.activeHolograms
-   * Call this when a hologram is deleted
-   * @param {string} sourceHolon - Source holon ID
-   * @param {string} lensName - Lens name
-   * @param {string} dataId - Data ID
-   * @param {string} targetHolon - Target holon where hologram lives
-   * @returns {Promise<boolean>} Success indicator
+   * Removes an active hologram reference from a source data item.
+   *
+   * @param {string} sourceHolon - Source holon H3 cell ID
+   * @param {string} lensName - Name of the lens
+   * @param {string} dataId - ID of the source data
+   * @param {string} targetHolon - Target holon where the hologram exists
+   * @returns {Promise<boolean>} True if removal succeeded
    */
   async removeActiveHologram(sourceHolon, lensName, dataId, targetHolon) {
     return federation.removeActiveHologram(
@@ -889,12 +1336,13 @@ export class HoloSphere extends HoloSphereCore {
   }
 
   /**
-   * Delete a hologram and clean up activeHolograms on the original source
-   * @param {string} holonId - Holon where the hologram lives
-   * @param {string} lensName - Lens name
-   * @param {string} dataId - Data ID of the hologram
-   * @param {Object} options - Optional settings
-   * @returns {Promise<Object>} Result with deletion info
+   * Deletes a hologram and cleans up its references.
+   *
+   * @param {string} holonId - H3 cell ID where the hologram exists
+   * @param {string} lensName - Name of the lens
+   * @param {string} dataId - ID of the hologram to delete
+   * @param {Object} [options={}] - Delete options
+   * @returns {Promise<boolean>} True if deletion succeeded
    */
   async deleteHologram(holonId, lensName, dataId, options = {}) {
     return federation.deleteHologram(
@@ -908,18 +1356,19 @@ export class HoloSphere extends HoloSphereCore {
   }
 
   /**
-   * Propagate data to a specific target holon (creates hologram or copy)
-   * Use this for direct propagation; use propagate() for federation-based propagation
+   * Propagates data from source holon to target holon.
+   *
    * @param {Object} data - Data to propagate
-   * @param {string} sourceHolon - Source holon ID
-   * @param {string} targetHolon - Target holon ID
-   * @param {string} lensName - Lens name
-   * @param {Object} options - Options
-   * @param {string} options.mode - 'reference' (creates hologram) or 'copy' (copies data)
-   * @returns {Promise<boolean>} Success indicator
+   * @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 = 'reference' } = options;
+    // Extract mode from options, default to 'reference' for hologram creation
+    const mode = options.mode || 'reference';
     return federation.propagateData(
       this.client,
       this.config.appName,
@@ -932,49 +1381,98 @@ export class HoloSphere extends HoloSphereCore {
   }
 
   /**
-   * Resolve a hologram to its actual data, merging local overrides
+   * Resolves a hologram to its source data.
+   *
    * @param {Object} hologram - Hologram object to resolve
-   * @returns {Promise<Object|null>} Resolved data or null
+   * @param {Object} [options={}] - Resolution options
+   * @returns {Promise<Object|null>} Resolved data or null if source not found
    */
-  async resolveHologram(hologram) {
-    return federation.resolveHologram(this.client, hologram);
+  async resolveHologram(hologram, options = {}) {
+    return federation.resolveHologram(this.client, hologram, new Set(), [], { ...options, appname: this.config.appName });
   }
 
   /**
-   * Check if data is a hologram (unresolved reference)
-   * @param {Object} data - Data to check
-   * @returns {boolean} True if data is a hologram
+   * Checks if an object is a hologram (unresolved reference).
+   *
+   * @param {Object} data - Data object to check
+   * @returns {boolean} True if the object is a hologram
    */
   isHologram(data) {
     return federation.isHologram(data);
   }
 
   /**
-   * Check if data was resolved from a hologram
-   * @param {Object} data - Data to check
-   * @returns {boolean} True if data was resolved from a hologram
+   * Checks if an object is a resolved hologram (has _hologram metadata).
+   *
+   * @param {Object} data - Data object to check
+   * @returns {boolean} True if the object is a resolved hologram
    */
   isResolvedHologram(data) {
     return federation.isResolvedHologram(data);
   }
 
   /**
-   * Get hologram source information from resolved data
-   * @param {Object} data - Resolved data
-   * @returns {Object|null} Source info { soul, sourceHolon, localOverrides } or null
+   * Gets the source information from a hologram or resolved hologram.
+   *
+   * @param {Object} data - Hologram or resolved hologram object
+   * @returns {Object|null} Source information or null
    */
   getHologramSource(data) {
     return federation.getHologramSource(data);
   }
 
   /**
-   * Cleanup circular holograms in a holon's lens
-   * Detects and removes holograms that create circular references (A→B→A)
-   * @param {string} holonId - Holon to clean up
-   * @param {string} lensName - Lens name to check
-   * @param {Object} options - Optional settings
-   * @param {boolean} options.dryRun - If true, only report what would be deleted
-   * @returns {Promise<Object>} Result with cleanup info
+   * Updates platform-specific data for an active hologram entry.
+   * Used by platform clients (Telegram, Discord, etc.) to store their message IDs.
+   *
+   * @param {string} sourceHolon - Source holon ID where the original data lives
+   * @param {string} lensName - Lens name (e.g., 'quests', 'events')
+   * @param {string} dataId - Data ID
+   * @param {string} targetHolon - Target holon ID where the hologram exists
+   * @param {string} platform - Platform name (e.g., 'telegram', 'discord')
+   * @param {Object} platformData - Platform-specific data (e.g., { messageId: 123 })
+   * @returns {Promise<boolean>} Success indicator
+   */
+  async updateHologramPlatform(sourceHolon, lensName, dataId, targetHolon, platform, platformData) {
+    return federation.updateActiveHologramPlatform(
+      this.client,
+      this.config.appName,
+      sourceHolon,
+      lensName,
+      dataId,
+      targetHolon,
+      platform,
+      platformData
+    );
+  }
+
+  /**
+   * Gets active holograms for a data item, optionally filtered by platform.
+   *
+   * @param {string} sourceHolon - Source holon ID
+   * @param {string} lensName - Lens name
+   * @param {string} dataId - Data ID
+   * @param {string} [platform] - Optional platform filter (e.g., 'telegram')
+   * @returns {Promise<Array>} Array of hologram entries with platform data
+   */
+  async getActiveHolograms(sourceHolon, lensName, dataId, platform = null) {
+    return federation.getActiveHolograms(
+      this.client,
+      this.config.appName,
+      sourceHolon,
+      lensName,
+      dataId,
+      platform
+    );
+  }
+
+  /**
+   * Cleans up circular hologram references in a holon.
+   *
+   * @param {string} holonId - H3 cell ID of the holon
+   * @param {string} lensName - Name of the lens
+   * @param {Object} [options={}] - Cleanup options
+   * @returns {Promise<Object>} Cleanup results
    */
   async cleanupCircularHolograms(holonId, lensName, options = {}) {
     return federation.cleanupCircularHolograms(
@@ -987,14 +1485,13 @@ export class HoloSphere extends HoloSphereCore {
   }
 
   /**
-   * Cleanup circular holograms for a specific list of IDs
-   * Use this when you don't have an index but know which IDs to check
-   * @param {string} holonId - Holon to clean up
-   * @param {string} lensName - Lens name
+   * 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 - Optional settings
-   * @param {boolean} options.dryRun - If true, only report what would be deleted
-   * @returns {Promise<Object>} Result with cleanup info
+   * @param {Object} [options={}] - Cleanup options
+   * @returns {Promise<Object>} Cleanup results
    */
   async cleanupCircularHologramsByIds(holonId, lensName, dataIds, options = {}) {
     return federation.cleanupCircularHologramsByIds(
@@ -1008,130 +1505,59 @@ export class HoloSphere extends HoloSphereCore {
   }
 
   /**
-   * Propagate data to federated holons and optionally to parent holons
-   * @param {string} holonId - Source holon ID
-   * @param {string} lensName - Lens name (e.g., 'quests')
-   * @param {Object} data - Data or hologram to propagate
-   * @param {Object} options - Propagation options
-   * @param {boolean} options.useHolograms - Use holograms instead of copies (default: true)
-   * @param {boolean} options.propagateToParents - Propagate to parent holons for H3 holons (default: false)
-   * @param {number} options.maxParentLevels - Maximum parent levels to propagate (default: 3)
-   * @returns {Promise<Object>} Result with success/failure counts
+   * 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 {
-      useHolograms = true,
-      propagateToParents = false,
-      maxParentLevels = 3
-    } = options;
-
-    const result = {
-      success: 0,
-      failed: 0,
-      targets: [],
-      parentPropagation: null
-    };
-
-    // Get federation config for this holon
     const federationData = await this.getFederation(holonId);
-
-    // Propagate to federated holons (outbound)
-    if (federationData && federationData.outbound) {
-      for (const targetHolon of federationData.outbound) {
-        // Check if sender has this lens configured for outbound to this target
-        const senderLensConfig = federationData.lensConfig?.[targetHolon];
-        if (senderLensConfig && senderLensConfig.outbound && !senderLensConfig.outbound.includes(lensName)) {
-          continue; // Skip - sender hasn't configured this lens for outbound to this target
-        }
-
-        // Check if receiver accepts this lens in their inbound from sender
-        try {
-          const targetFederation = await this.getFederation(targetHolon);
-          const receiverLensConfig = targetFederation?.lensConfig?.[holonId];
-          if (receiverLensConfig && receiverLensConfig.inbound && !receiverLensConfig.inbound.includes(lensName)) {
-            console.log(`Skipping propagation to ${targetHolon} - lens '${lensName}' not in their inbound config for ${holonId}`);
-            continue; // Skip - receiver doesn't accept this lens from sender
-          }
-        } catch (error) {
-          console.warn(`Could not verify receiver's inbound config for ${targetHolon}, proceeding anyway:`, error);
-        }
-
-        try {
-          const mode = useHolograms ? 'reference' : 'copy';
-          await federation.propagateData(
-            this.client,
-            this.config.appName,
-            data,
-            holonId,
-            targetHolon,
-            lensName,
-            mode
-          );
-          result.success++;
-          result.targets.push(targetHolon);
-        } catch (error) {
-          console.error(`Failed to propagate to ${targetHolon}:`, error);
-          result.failed++;
-        }
-      }
-    }
-
-    // Propagate to parent holons (for H3/geographic holons)
-    if (propagateToParents && spatial.isValidH3(holonId)) {
-      const parents = spatial.getParents(holonId);
-      const targetParents = parents.slice(0, maxParentLevels);
-
-      result.parentPropagation = {
-        success: 0,
-        failed: 0,
-        targets: []
-      };
-
-      for (const parentHolon of targetParents) {
-        try {
-          const mode = useHolograms ? 'reference' : 'copy';
-          await federation.propagateData(
-            this.client,
-            this.config.appName,
-            data,
-            holonId,
-            parentHolon,
-            lensName,
-            mode
-          );
-          result.parentPropagation.success++;
-          result.parentPropagation.targets.push(parentHolon);
-        } catch (error) {
-          console.error(`Failed to propagate to parent ${parentHolon}:`, error);
-          result.parentPropagation.failed++;
-        }
-      }
+    // getFederation returns an object with federated array, not an array directly
+    const targets = federationData?.federated || federationData?.outbound || [];
+    if (!targets || targets.length === 0) return;
+
+    const { useHolograms = true, resolveExisting = true } = options;
+    const results = [];
+
+    for (const targetHolonId of targets) {
+      const result = await this.propagateData(
+        data,
+        holonId,
+        targetHolonId,
+        lensName,
+        { useHolograms, resolveExisting }
+      );
+      results.push({ parent: targetHolonId, ...result });
     }
 
-    return result;
+    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');
     }
-    const data = await this.getGlobal('federation', holonId);
+    const data = await this.readGlobal('federation', holonId);
     if (!data) return null;
 
-    // Ensure arrays exist (in case data from storage is malformed)
-    if (!Array.isArray(data.inbound)) {
-      data.inbound = [];
-    }
-    if (!Array.isArray(data.outbound)) {
-      data.outbound = [];
-    }
-    if (!data.lensConfig || typeof data.lensConfig !== 'object') {
-      data.lensConfig = {};
-    }
+    if (!Array.isArray(data.inbound)) data.inbound = [];
+    if (!Array.isArray(data.outbound)) data.outbound = [];
+    if (!data.lensConfig || typeof data.lensConfig !== 'object') data.lensConfig = {};
+    if (!data.partnerNames || typeof data.partnerNames !== 'object') data.partnerNames = {};
 
-    // Backwards compatibility: populate federated from inbound/outbound if it doesn't exist
     if (!Array.isArray(data.federated)) {
-      // Combine inbound and outbound into a unique set
       const allFederated = new Set([...data.inbound, ...data.outbound]);
       data.federated = Array.from(allFederated);
     }
@@ -1140,94 +1566,82 @@ export class HoloSphere extends HoloSphereCore {
   }
 
   /**
-   * Federate two holons at the holon level (manages multiple lenses)
-   * This is a higher-level method that manages federation metadata and lens-specific federations
-   * @param {string} sourceHolon - Source holon ID
-   * @param {string} targetHolon - Target holon ID
-   * @param {Object} options - Federation options
-   * @param {Object} options.lensConfig - Lens configuration {inbound: [], outbound: []}
-   * @returns {Promise<boolean>} Success indicator
+   * 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: [] } } = options;
+    const { lensConfig = { inbound: [], outbound: [] }, partnerName = null, skipPropagation = false } = options;
 
-    // Validate self-federation
     if (sourceHolon === targetHolon) {
       throw new Error('Cannot federate a holon with itself');
     }
 
-    // Get or create federation record for source holon
-    let federationData = await this.getGlobal('federation', sourceHolon) || {
+    let federationData = await this.readGlobal('federation', sourceHolon) || {
       id: sourceHolon,
       name: sourceHolon,
       federated: [],
       inbound: [],
       outbound: [],
       lensConfig: {},
+      partnerNames: {},
       timestamp: Date.now()
     };
 
-    // Ensure arrays exist (in case data from storage is malformed)
-    if (!Array.isArray(federationData.federated)) {
-      federationData.federated = [];
-    }
-    if (!Array.isArray(federationData.inbound)) {
-      federationData.inbound = [];
-    }
-    if (!Array.isArray(federationData.outbound)) {
-      federationData.outbound = [];
-    }
-    if (!federationData.lensConfig || typeof federationData.lensConfig !== 'object') {
-      federationData.lensConfig = {};
-    }
+    if (!Array.isArray(federationData.federated)) federationData.federated = [];
+    if (!Array.isArray(federationData.inbound)) federationData.inbound = [];
+    if (!Array.isArray(federationData.outbound)) federationData.outbound = [];
+    if (!federationData.lensConfig || typeof federationData.lensConfig !== 'object') federationData.lensConfig = {};
+    if (!federationData.partnerNames || typeof federationData.partnerNames !== 'object') federationData.partnerNames = {};
 
-    // Always add target to federated list (tracks all federation links)
     if (!federationData.federated.includes(targetHolon)) {
       federationData.federated.push(targetHolon);
     }
 
-    // Add target to inbound/outbound lists based on lensConfig
-    // If there are outbound lenses, add to outbound list
+    // Store the partner's name if provided
+    if (partnerName) {
+      federationData.partnerNames[targetHolon] = partnerName;
+    }
+
     if (lensConfig.outbound && lensConfig.outbound.length > 0) {
       if (!federationData.outbound.includes(targetHolon)) {
         federationData.outbound.push(targetHolon);
       }
     } else {
-      // Remove from outbound if no outbound lenses
       federationData.outbound = federationData.outbound.filter(id => id !== targetHolon);
     }
 
-    // If there are inbound lenses, add to inbound list
     if (lensConfig.inbound && lensConfig.inbound.length > 0) {
       if (!federationData.inbound.includes(targetHolon)) {
         federationData.inbound.push(targetHolon);
       }
     } else {
-      // Remove from inbound if no inbound lenses
       federationData.inbound = federationData.inbound.filter(id => id !== targetHolon);
     }
 
-    // Store lens configuration for this target holon
     federationData.lensConfig[targetHolon] = {
       inbound: lensConfig.inbound || [],
       outbound: lensConfig.outbound || [],
       timestamp: Date.now()
     };
 
-    // Save federation metadata
     const success = await this.writeGlobal('federation', federationData);
-
-    // Clear cache so getFederation returns fresh data immediately
     this.clearCache('federation');
 
-    // Setup lens-specific federations
-    if (success) {
-      // Federate each lens specified in inbound array (receive from target)
+    // Only propagate existing data if skipPropagation is false
+    if (success && !skipPropagation) {
       for (const lens of (lensConfig.inbound || [])) {
         await this.federate(targetHolon, sourceHolon, lens, { direction: 'outbound', mode: 'reference' });
       }
-
-      // Federate each lens specified in outbound array (send to target)
       for (const lens of (lensConfig.outbound || [])) {
         await this.federate(sourceHolon, targetHolon, lens, { direction: 'outbound', mode: 'reference' });
       }
@@ -1237,45 +1651,33 @@ export class HoloSphere extends HoloSphereCore {
   }
 
   /**
-   * Unfederate two holons at the holon level
-   * @param {string} sourceHolon - Source holon ID
-   * @param {string} targetHolon - Target holon ID
-   * @returns {Promise<boolean>} Success indicator
+   * 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) {
-    // Get federation record
-    const federationData = await this.getGlobal('federation', sourceHolon);
-    if (!federationData) {
-      return false;
-    }
+    const federationData = await this.readGlobal('federation', sourceHolon);
+    if (!federationData) return false;
 
-    // Get lens config for this target before removing
     const lensConfig = federationData.lensConfig?.[targetHolon];
 
-    // Remove target from federation lists
     federationData.federated = (federationData.federated || []).filter(id => id !== targetHolon);
     federationData.inbound = (federationData.inbound || []).filter(id => id !== targetHolon);
     federationData.outbound = (federationData.outbound || []).filter(id => id !== targetHolon);
 
-    // Remove lens config for this target
     if (federationData.lensConfig) {
       delete federationData.lensConfig[targetHolon];
     }
 
-    // Update federation metadata
     const success = await this.writeGlobal('federation', federationData);
-
-    // Clear cache so getFederation returns fresh data immediately
     this.clearCache('federation');
 
-    // Unfederate lens-specific federations
     if (success && lensConfig) {
-      // Unfederate each lens that was in inbound array
       for (const lens of (lensConfig.inbound || [])) {
         await this.unfederate(targetHolon, sourceHolon, lens);
       }
-
-      // Unfederate each lens that was in outbound array
       for (const lens of (lensConfig.outbound || [])) {
         await this.unfederate(sourceHolon, targetHolon, lens);
       }
@@ -1285,47 +1687,59 @@ export class HoloSphere extends HoloSphereCore {
   }
 
   /**
-   * Get the lens configuration for a specific federated holon
-   * @param {string} sourceHolon - Source holon ID
-   * @param {string} targetHolon - Target holon ID
-   * @returns {Promise<Object|null>} Lens config {inbound: [], outbound: []} or null
+   * 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.getGlobal('federation', sourceHolon);
-    if (!federationData || !federationData.lensConfig) {
-      return null;
-    }
+    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 hierarchical.upcast(this.client, this.config.appName, holonId, lensName, dataId, options);
+    return hierarchical.upcast(this, holonId, lensName, dataId, options);
   }
 
-  // === Subscription Operations ===
+  // === 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');
     }
-
     const path = storage.buildPath(this.config.appName, holonId, lensName);
-
-    // Default to real-time only mode (only receive new events, not historical)
-    const subscriptionOptions = {
-      realtimeOnly: true,  // Only get events from subscription time forward
-      ...options
-    };
-
+    const subscriptionOptions = { realtimeOnly: true, ...options };
     const subscriptionId = `${holonId}-${lensName}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
     let innerSubscription = null;
     let unsubscribeCalled = false;
 
-    // Start async subscription setup in background
     subscriptions.createSubscription(this.client, path, callback, subscriptionOptions)
       .then(subscription => {
         innerSubscription = subscription;
-        // If unsubscribe was called before setup completed, clean up immediately
         if (unsubscribeCalled) {
           subscription.unsubscribe();
         } else {
@@ -1336,1334 +1750,512 @@ export class HoloSphere extends HoloSphereCore {
         this._log('ERROR', 'Subscription setup failed', { path, error: err.message });
       });
 
-    this._metrics.subscriptions++;
-
-    // Return synchronous subscription object
+    this._metrics.subscriptions = (this._metrics.subscriptions || 0) + 1;
     return {
       unsubscribe: () => {
         unsubscribeCalled = true;
         if (innerSubscription) {
           this.subscriptionRegistry.unregister(subscriptionId);
         }
-      },
+      }
     };
   }
 
   /**
-   * Subscribe to global table changes
-   * @param {string} table - The global table name (e.g., 'federation')
-   * @param {string} key - The specific key within the table (e.g., holonId)
-   * @param {Function} callback - Callback function called on data changes
-   * @param {Object} options - Subscription options
-   * @returns {Object} Subscription object with unsubscribe method
+   * 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 = {}) {
-    if (typeof callback !== 'function') {
-      throw new TypeError('callback must be a function');
-    }
-
-    // Build global table path: appname/table/key
-    const path = `${this.config.appName}/${table}/${key}`;
-
-    // Default to real-time only mode
-    const subscriptionOptions = {
-      realtimeOnly: true,
-      ...options
-    };
-
-    const subscription = await subscriptions.createSubscription(this.client, path, callback, subscriptionOptions);
-
-    const subscriptionId = `global-${table}-${key}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
-    this.subscriptionRegistry.register(subscriptionId, subscription);
-    this._metrics.subscriptions++;
-
-    return {
-      unsubscribe: () => {
-        this.subscriptionRegistry.unregister(subscriptionId);
-      },
-    };
+    return globalTables.subscribeGlobal(
+      this.client,
+      this.config.appName,
+      table,
+      key,
+      callback,
+      options
+    );
   }
 
   // === Crypto Operations ===
+
+  /**
+   * Derives a public key from a private key.
+   *
+   * @param {string} privateKey - Hex-encoded private key
+   * @returns {Promise<string>} Hex-encoded public key
+   */
   async getPublicKey(privateKey) {
     return crypto.getPublicKey(privateKey);
   }
 
+  /**
+   * Signs content with a private key.
+   *
+   * @param {string|Object} content - Content to sign
+   * @param {string} privateKey - Hex-encoded private key
+   * @returns {Promise<string>} Hex-encoded signature
+   */
   async sign(content, privateKey) {
     return crypto.sign(content, privateKey);
   }
 
+  /**
+   * Verifies a signature against content and public key.
+   *
+   * @param {string|Object} content - Original content
+   * @param {string} signature - Hex-encoded signature
+   * @param {string} publicKey - Hex-encoded public key
+   * @returns {Promise<boolean>} True if signature is valid
+   */
   async verify(content, signature, publicKey) {
     return crypto.verify(content, signature, publicKey);
   }
 
+  /**
+   * Issues a capability token for authorization.
+   *
+   * @param {string[]} permissions - Array of permissions ('read', 'write', 'delete')
+   * @param {Object} scope - Scope of the capability (holonId, lensName, etc.)
+   * @param {string} recipient - Public key of the recipient
+   * @param {Object} [options] - Additional options
+   * @returns {Promise<string>} Signed capability token
+   */
   async issueCapability(permissions, scope, recipient, options) {
     return crypto.issueCapability(permissions, scope, recipient, options);
   }
 
+  /**
+   * Verifies a capability token.
+   *
+   * @param {string} token - Capability token to verify
+   * @param {string} requiredPermission - Required permission to check
+   * @param {Object} scope - Scope to verify against
+   * @returns {Promise<boolean>} True if token is valid and has required permission
+   */
   async verifyCapability(token, requiredPermission, scope) {
     return crypto.verifyCapability(token, requiredPermission, scope);
   }
 
   // === Social Protocol Operations ===
+
+  /**
+   * Publishes a Nostr event to a holon.
+   *
+   * @param {Object} event - Nostr event object
+   * @param {number} event.kind - Event kind
+   * @param {string} event.content - Event content
+   * @param {Array} [event.tags] - Event tags
+   * @param {string} holonId - H3 cell ID for the holon
+   * @param {string} [lensName='social'] - Name of the lens
+   * @returns {Promise<boolean>} True if publish succeeded
+   */
   async publishNostr(event, holonId, lensName = 'social') {
-    // Validate with throwing error (partial=true allows missing id/pubkey/sig)
-    social.validateNostrEvent(event, true, true);
+    // Validate Nostr event format
+    social.validateNostrEvent(event, true, true); // partial=true, throwOnError=true
 
-    // Sign the event if not already signed
-    if (!event.id || !event.pubkey || !event.sig) {
-      // Use nostr-tools to properly sign the event
-      const { finalizeEvent } = await import('nostr-tools');
-      const signedEvent = finalizeEvent(event, this.client.privateKey);
+    const enrichedEvent = {
+      ...event,
+      tags: [...(event.tags || []), ['h', holonId], ['l', lensName]],
+    };
+    const signedEvent = nostrUtils.signEvent(enrichedEvent, this.client.privateKey);
 
-      // Update event with signature fields
-      event.id = signedEvent.id;
-      event.pubkey = signedEvent.pubkey;
-      event.sig = signedEvent.sig;
-    }
+    // Add protocol field for querySocial filtering
+    const eventWithProtocol = {
+      ...signedEvent,
+      protocol: 'nostr',
+    };
 
-    const transformed = social.transformNostrEvent(event);
-    return this.write(holonId, lensName, transformed);
+    const path = storage.buildPath(this.config.appName, holonId, lensName, signedEvent.id);
+    await storage.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') {
-    // Validate with throwing error
-    social.validateActivityPubObject(object, true);
+    // Validate ActivityPub object format
+    social.validateActivityPubObject(object, true); // throwOnError=true
 
-    const transformed = social.transformActivityPubObject(object);
-    return this.write(holonId, lensName, transformed);
+    const activity = social.transformActivityPubObject({
+      ...object,
+      actor: object.actor || this.client.publicKey,
+    });
+    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 { protocol, accessLevel } = options;
-    let data = await this.read(holonId, 'social');
-
-    if (protocol) {
-      data = social.filterByProtocol(data, protocol);
-    }
-
-    if (accessLevel) {
-      data = social.filterByAccessLevel(data, accessLevel);
-    }
-
-    // Parse tags back to array for Nostr events (stored as JSON string)
-    if (Array.isArray(data)) {
-      data = data.map(item => {
-        if (item.protocol === 'nostr' && typeof item.tags === 'string') {
-          return { ...item, tags: JSON.parse(item.tags) };
-        }
-        return item;
-      });
-    }
-
-    return data;
+    const lensName = options.lens || 'social';
+    const data = await this.read(holonId, lensName);
+
+    if (!data) return [];
+    const items = Array.isArray(data) ? data : [data];
+
+    return items.filter(item => {
+      // 'all' means don't filter by protocol
+      if (options.protocol && options.protocol !== 'all' && item.protocol !== options.protocol) return false;
+      if (options.type && item.type !== options.type) return false;
+      if (options.since && item.created_at < options.since) return false;
+      if (options.until && item.created_at > options.until) return false;
+      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) {
-    // Verify a Nostr event signature
-    const { verifyEvent } = await import('nostr-tools');
-
-    // Parse tags if they're stored as a string
-    const eventToVerify = {
-      ...event,
-      tags: typeof event.tags === 'string' ? JSON.parse(event.tags) : event.tags
-    };
-
-    return verifyEvent(eventToVerify);
+    // Extract only standard Nostr event fields for verification
+    // (nostr-tools can't serialize events with extra properties like 'protocol')
+    const { id, pubkey, created_at, kind, tags, content, sig } = event;
+    const standardEvent = { id, pubkey, created_at, kind, tags, content, sig };
+    return nostrUtils.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 baseMetrics = super.metrics();
+    const reads = this._metrics.reads || 0;
+    const writes = this._metrics.writes || 0;
+    const totalReadTime = this._metrics.totalReadTime || 0;
+    const totalWriteTime = this._metrics.totalWriteTime || 0;
+
     return {
-      ...baseMetrics,
+      reads,
+      writes,
+      deletes: this._metrics.deletes || 0,
       federations: this._metrics.federations || 0,
-      avgWriteTime: this._metrics.writes > 0
-        ? (this._metrics.totalWriteTime || 0) / this._metrics.writes
-        : 0,
-      avgReadTime: this._metrics.reads > 0
-        ? (this._metrics.totalReadTime || 0) / this._metrics.reads
-        : 0,
+      subscriptions: this._metrics.subscriptions || 0,
+      avgReadTime: reads > 0 ? totalReadTime / reads : 0,
+      avgWriteTime: writes > 0 ? totalWriteTime / writes : 0,
+    };
+  }
+
+  /**
+   * Returns the current status of optimistic caches for debugging.
+   * Useful for understanding what data is pending sync or marked as deleted.
+   *
+   * @returns {Object} Cache status object
+   * @returns {number} return.writeCacheSize - Number of items in write cache (pending sync)
+   * @returns {number} return.deleteCacheSize - Number of items in delete cache (pending delete sync)
+   * @returns {Array<Object>} return.writeCacheEntries - Array of write cache entries with path and age
+   * @returns {Array<string>} return.deleteCachePaths - Array of paths marked as deleted
+   */
+  getCacheStatus() {
+    const now = Date.now();
+    const writeCacheEntries = [];
+
+    for (const [path, entry] of this._writeCache.entries()) {
+      writeCacheEntries.push({
+        path,
+        dataId: entry.data?.id,
+        age: `${now - entry.timestamp}ms`,
+        timestamp: new Date(entry.timestamp).toISOString()
+      });
+    }
+
+    return {
+      writeCacheSize: this._writeCache.size,
+      deleteCacheSize: this._deleteCache.size,
+      writeCacheEntries,
+      deleteCachePaths: Array.from(this._deleteCache)
     };
   }
 
-  // === Functional Aliases ===
-  // Common CRUD-style aliases for data operations
+  /**
+   * Clears the optimistic caches. Useful for testing or resetting state.
+   * Warning: This may cause inconsistencies if there are pending syncs.
+   */
+  clearCaches() {
+    const writeSize = this._writeCache.size;
+    const deleteSize = this._deleteCache.size;
+    this._writeCache.clear();
+    this._deleteCache.clear();
+    this._log('WARN', '🧹 CACHES CLEARED', {
+      writeCacheCleared: writeSize,
+      deleteCacheCleared: deleteSize
+    });
+  }
+
+  // === Aliases ===
 
   /**
-   * Alias for write() - stores data in a holon/lens
-   * @alias write
+   * 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 read() - retrieves data from a holon/lens
-   * @alias read
+   * 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 delete() - removes data from a holon/lens
-   * @alias delete
+   * 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 writeGlobal() - stores data in global table
-   * @alias writeGlobal
+   * 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 readGlobal() - retrieves data from global table
-   * @alias readGlobal
+   * 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 deleteGlobal() - removes data from global table
-   * @alias deleteGlobal
+   * 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 setSchema() - defines a schema for a lens
-   * @alias setSchema
+   * 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 getSchema() - retrieves schema for a lens
-   * @alias getSchema
+   * Alias for {@link HoloSphereBase#getSchema}.
+   * @param {string} lensName - Lens name
+   * @returns {Promise<Object|null>}
    */
   async fetchSchema(lensName) {
     return this.getSchema(lensName);
   }
 
   /**
-   * Alias for clearSchema() - removes schema for a lens
-   * @alias clearSchema
+   * Alias for {@link HoloSphereBase#clearSchema}.
+   * @param {string} lensName - Lens name
+   * @returns {Promise<void>}
    */
   async removeSchema(lensName) {
     return this.clearSchema(lensName);
   }
 
   /**
-   * Store data - more semantic alias for write
-   * @alias write
+   * 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);
   }
 
   /**
-   * Fetch data - more semantic alias for read
-   * @alias read
+   * 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);
   }
 
   /**
-   * Save data - alternative alias for write
-   * @alias write
+   * 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);
   }
 
   /**
-   * Load data - alternative alias for read
-   * @alias read
+   * 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 ===
+
   /**
-   * Clear the internal cache (or specific entries matching a pattern)
-   * Useful after write operations when you need to immediately read fresh data
-   * @param {string} [pattern] - Optional pattern to match cache keys (clears all if not provided)
+   * Clears the internal cache.
+   *
+   * @param {string|null} [pattern=null] - If provided, only clear cache entries matching this pattern
    */
   clearCache(pattern = null) {
-    if (this.client && this.client.clearCache) {
-      this.client.clearCache(pattern);
+    if (pattern) {
+      for (const key of this._cache.keys()) {
+        if (key.includes(pattern)) {
+          this._cache.delete(key);
+        }
+      }
+    } else {
+      this._cache.clear();
     }
   }
+}
 
-  // === AI Operations ===
-
-  /**
-   * Check if AI is available and throw if not
-   * @private
-   */
-  _requireAI() {
-    if (!this._ai) {
-      throw new Error('AI services not initialized. Provide openaiKey in config.');
-    }
-  }
+/**
+ * Main HoloSphere class - composed from base + all mixins
+ */
+export const HoloSphere = withContractMethods(
+  withFederationMethods(
+    withAIMethods(HoloSphereBase)
+  )
+);
 
-  // --- Core LLM Methods ---
+// Export error classes
+export { AuthorizationError };
+export { ValidationError };
 
-  /**
-   * Summarize text using AI
-   * @param {string} text - Text to summarize
-   * @param {Object} options - Options for summarization
-   * @returns {Promise<string>} Summary
-   */
-  async summarize(text, options = {}) {
-    this._requireAI();
-    return this._ai.llm.summarize(text, options);
-  }
+// Re-export AI module classes
+export {
+  LLMService,
+  SchemaExtractor,
+  JSONOps,
+  Embeddings,
+  Council,
+  TTS,
+  VOICES,
+  MODELS,
+  NLQuery,
+  Classifier,
+  SpatialAnalysis,
+  SmartAggregation,
+  FederationAdvisor,
+  RelationshipDiscovery,
+  TaskBreakdown,
+  H3AI,
+};
 
-  /**
-   * Analyze text from a specific perspective
-   * @param {string} text - Text to analyze
-   * @param {string} aspect - Perspective to analyze from
-   * @param {Object} options - Options
-   * @returns {Promise<string>} Analysis
-   */
-  async analyze(text, aspect, options = {}) {
-    this._requireAI();
-    return this._ai.llm.analyze(text, aspect, options);
-  }
+// Re-export types and utilities
+export { spatial, storage, schema, federation, handshake, crypto, nostrUtils, social, subscriptions, hierarchical };
 
-  /**
-   * Extract keywords from text
-   * @param {string} text - Text to extract keywords from
-   * @param {Object} options - Options
-   * @returns {Promise<string[]>} Keywords
-   */
-  async extractKeywords(text, options = {}) {
-    this._requireAI();
-    return this._ai.llm.extractKeywords(text, options);
-  }
+// Re-export specific utilities used in tests
+export { matchScope } from './crypto/secp256k1.js';
+export { createHologram } from './federation/hologram.js';
 
-  /**
-   * Categorize text into one of the provided categories
-   * @param {string} text - Text to categorize
-   * @param {string[]} categories - Available categories
-   * @param {Object} options - Options
-   * @returns {Promise<string>} Selected category
-   */
-  async categorize(text, categories, options = {}) {
-    this._requireAI();
-    return this._ai.llm.categorize(text, categories, options);
-  }
+// Export AI factory function
+export { createAIServices } from './ai/index.js';
 
-  /**
-   * Translate text to a target language
-   * @param {string} text - Text to translate
-   * @param {string} targetLanguage - Target language
-   * @param {Object} options - Options
-   * @returns {Promise<string>} Translated text
-   */
-  async translate(text, targetLanguage, options = {}) {
-    this._requireAI();
-    return this._ai.llm.translate(text, targetLanguage, options);
-  }
+// Export Contracts module classes for standalone use
+export {
+  ChainManager,
+  ContractDeployer,
+  HolonContracts,
+  ContractOperations,
+  ContractABIs,
+  EventListener,
+  ContractQueries,
+  SANKEY_EVENTS
+};
 
-  /**
-   * Generate questions based on text
-   * @param {string} text - Text to generate questions from
-   * @param {Object} options - Options
-   * @returns {Promise<string[]>} Generated questions
-   */
-  async generateQuestions(text, options = {}) {
-    this._requireAI();
-    return this._ai.llm.generateQuestions(text, options);
-  }
-
-  // --- Schema Extraction ---
-
-  /**
-   * Extract structured data from text based on a lens schema
-   * @param {string} text - Natural language text
-   * @param {string} lensName - Name of the lens to get schema from
-   * @param {Object} options - Options
-   * @returns {Promise<Object>} Extracted structured data
-   */
-  async extractToSchema(text, lensName, options = {}) {
-    this._requireAI();
-    const schemaObj = await this.getSchema(lensName);
-    if (!schemaObj) {
-      throw new Error(`No schema found for lens: ${lensName}`);
-    }
-    return this._ai.schemaExtractor.extractToSchema(text, schemaObj, options);
-  }
-
-  // --- Fuzzy JSON Operations ---
-
-  /**
-   * Semantically merge two JSON objects
-   * @param {Object} obj1 - First object
-   * @param {Object} obj2 - Second object
-   * @param {Object} options - Options
-   * @returns {Promise<Object>} Merged object
-   */
-  async jsonAdd(obj1, obj2, options = {}) {
-    this._requireAI();
-    return this._ai.jsonOps.add(obj1, obj2, options);
-  }
-
-  /**
-   * Remove concepts from obj1 based on obj2
-   * @param {Object} obj1 - Base object
-   * @param {Object} obj2 - Object with concepts to remove
-   * @param {Object} options - Options
-   * @returns {Promise<Object>} Result
-   */
-  async jsonSubtract(obj1, obj2, options = {}) {
-    this._requireAI();
-    return this._ai.jsonOps.subtract(obj1, obj2, options);
-  }
-
-  /**
-   * Union two objects with intelligent deduplication
-   * @param {Object} obj1 - First object
-   * @param {Object} obj2 - Second object
-   * @param {Object} options - Options
-   * @returns {Promise<Object>} United object
-   */
-  async jsonUnion(obj1, obj2, options = {}) {
-    this._requireAI();
-    return this._ai.jsonOps.union(obj1, obj2, options);
-  }
-
-  /**
-   * Find semantic differences between two objects
-   * @param {Object} obj1 - First object
-   * @param {Object} obj2 - Second object
-   * @param {Object} options - Options
-   * @returns {Promise<Object>} Differences
-   */
-  async jsonDifference(obj1, obj2, options = {}) {
-    this._requireAI();
-    return this._ai.jsonOps.difference(obj1, obj2, options);
-  }
-
-  /**
-   * Semantically concatenate objects/arrays
-   * @param {Object} obj1 - First object
-   * @param {Object} obj2 - Second object
-   * @param {Object} options - Options
-   * @returns {Promise<Object>} Concatenated result
-   */
-  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 in a holon/lens
-   * @param {string} query - Search query
-   * @param {string} holonId - Holon to search in
-   * @param {string} lensName - Lens to search in
-   * @param {Object} options - Search options
-   * @returns {Promise<Array>} Search results
-   */
-  async semanticSearch(query, holonId, lensName, options = {}) {
-    this._requireAI();
-    return this._ai.embeddings.semanticSearch(query, holonId, lensName, options);
-  }
-
-  /**
-   * Store data with embedding for later semantic search
-   * @param {string} holonId - Holon ID
-   * @param {string} lensName - Lens name
-   * @param {Object} data - Data to store
-   * @param {string} textField - Field to generate embedding from
-   * @returns {Promise<boolean>} Success
-   */
-  async storeWithEmbedding(holonId, lensName, data, textField = 'description') {
-    this._requireAI();
-    return this._ai.embeddings.storeWithEmbedding(holonId, lensName, data, textField);
-  }
-
-  // --- Multi-Perspective Council ---
-
-  /**
-   * Ask the council of perspectives for wisdom
-   * @param {string} question - Question to ask
-   * @param {Object} options - Options
-   * @returns {Promise<Object>} Council responses
-   */
-  async askCouncil(question, options = {}) {
-    this._requireAI();
-    return this._ai.council.ask(question, options);
-  }
-
-  /**
-   * Ask council with custom perspectives
-   * @param {string} question - Question to ask
-   * @param {string[]} perspectives - Custom perspectives
-   * @param {Object} options - Options
-   * @returns {Promise<Object>} Council responses
-   */
-  async askCouncilCustom(question, perspectives, options = {}) {
-    this._requireAI();
-    return this._ai.council.askCustom(question, perspectives, options);
-  }
-
-  // --- Text-to-Speech ---
-
-  /**
-   * Convert text to speech
-   * @param {string} text - Text to speak
-   * @param {string} voice - Voice to use
-   * @param {Object} options - TTS options
-   * @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 as base64
-   * @param {string} text - Text to speak
-   * @param {string} voice - Voice to use
-   * @param {Object} options - TTS options
-   * @returns {Promise<string>} Base64 audio
-   */
-  async textToSpeechBase64(text, voice = 'nova', options = {}) {
-    this._requireAI();
-    return this._ai.tts.speakBase64(text, voice, options);
-  }
-
-  // --- Natural Language Queries ---
-
-  /**
-   * Query data using natural language
-   * @param {string} query - Natural language query
-   * @param {string} holonId - Holon to query (optional)
-   * @param {string} lensName - Lens to query (optional)
-   * @param {Object} options - Options
-   * @returns {Promise<Array>} Query results
-   */
-  async nlQuery(query, holonId = null, lensName = null, options = {}) {
-    this._requireAI();
-    return this._ai.nlQuery.execute(query, holonId, lensName, options);
-  }
-
-  /**
-   * Parse natural language query to structured query
-   * @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 suggest the best lens
-   * @param {Object} content - Content to classify
-   * @param {Object} options - Options
-   * @returns {Promise<Object>} Classification result
-   */
-  async classifyToLens(content, options = {}) {
-    this._requireAI();
-    return this._ai.classifier.classifyToLens(content, options);
-  }
-
-  /**
-   * Automatically store content in the best lens
-   * @param {string} holonId - Holon ID
-   * @param {Object} content - Content to store
-   * @param {Object} options - Options
-   * @returns {Promise<Object>} Storage result
-   */
-  async autoStore(holonId, content, options = {}) {
-    this._requireAI();
-    return this._ai.classifier.autoStore(holonId, content, options);
-  }
-
-  /**
-   * Register a lens with the classifier
-   * @param {string} lensName - Lens name
-   * @param {string} description - Lens description
-   * @param {string[]} keywords - Keywords for this lens
-   */
-  registerLensForClassification(lensName, description, keywords = []) {
-    this._requireAI();
-    this._ai.classifier.registerLens(lensName, description, keywords);
-  }
-
-  // --- Spatial Analysis ---
-
-  /**
-   * AI-powered analysis of a geographic region
-   * @param {string} holonId - Holon to analyze
-   * @param {string} lensName - Lens to analyze (optional)
-   * @param {string} aspect - Aspect to focus on (optional)
-   * @param {Object} options - Options
-   * @returns {Promise<Object>} Analysis result
-   */
-  async analyzeRegion(holonId, lensName = null, aspect = null, options = {}) {
-    this._requireAI();
-    return this._ai.spatial.analyzeRegion(holonId, lensName, aspect, options);
-  }
-
-  /**
-   * Compare data between two regions
-   * @param {string} holon1 - First holon
-   * @param {string} holon2 - Second holon
-   * @param {string} lensName - Lens to compare (optional)
-   * @returns {Promise<Object>} Comparison result
-   */
-  async compareRegions(holon1, holon2, lensName = null) {
-    this._requireAI();
-    return this._ai.spatial.compareRegions(holon1, holon2, lensName);
-  }
-
-  /**
-   * Identify trends over time/space
-   * @param {string} holonId - Holon to analyze
-   * @param {string} lensName - Lens
-   * @param {Object} timeRange - Time range
-   * @returns {Promise<Object>} Trends
-   */
-  async spatialTrends(holonId, lensName, timeRange = null) {
-    this._requireAI();
-    return this._ai.spatial.spatialTrends(holonId, lensName, timeRange);
-  }
-
-  // --- Smart Aggregation ---
-
-  /**
-   * AI-summarized hierarchical aggregation up the holon tree
-   * @param {string} holonId - Starting holon
-   * @param {string} lensName - Lens to aggregate
-   * @param {Object} options - Options
-   * @returns {Promise<Object>} Aggregation result
-   */
-  async smartUpcast(holonId, lensName, options = {}) {
-    this._requireAI();
-    return this._ai.aggregation.smartUpcast(holonId, lensName, options);
-  }
-
-  /**
-   * Generate comprehensive holon summary
-   * @param {string} holonId - Holon to summarize
-   * @returns {Promise<Object>} Summary
-   */
-  async generateHolonSummary(holonId) {
-    this._requireAI();
-    return this._ai.aggregation.generateHolonSummary(holonId);
-  }
-
-  // --- Federation Advisor ---
-
-  /**
-   * Get AI suggestions for federation partners
-   * @param {string} holonId - Holon to find partners for
-   * @param {Object} options - Options including candidateHolons
-   * @returns {Promise<Object>} Federation suggestions
-   */
-  async suggestFederations(holonId, options = {}) {
-    this._requireAI();
-    return this._ai.federationAdvisor.suggestFederations(holonId, options);
-  }
-
-  /**
-   * Analyze federation health
-   * @param {string} holonId - Holon to analyze
-   * @returns {Promise<Object>} Health analysis
-   */
-  async analyzeFederationHealth(holonId) {
-    this._requireAI();
-    return this._ai.federationAdvisor.analyzeFederationHealth(holonId);
-  }
-
-  /**
-   * Get federation optimization suggestions
-   * @param {string} holonId - Holon to optimize
-   * @returns {Promise<Object>} Optimization suggestions
-   */
-  async optimizeFederation(holonId) {
-    this._requireAI();
-    return this._ai.federationAdvisor.optimizeFederation(holonId);
-  }
-
-  // --- Relationship Discovery ---
-
-  /**
-   * Discover hidden relationships in data
-   * @param {string} holonId - Holon to analyze
-   * @param {string} lensName - Lens (optional)
-   * @returns {Promise<Object>} Discovered relationships
-   */
-  async discoverRelationships(holonId, lensName = null) {
-    this._requireAI();
-    return this._ai.relationships.discoverRelationships(holonId, lensName);
-  }
-
-  /**
-   * Find semantically similar items
-   * @param {Object} item - Item to find similar items for
-   * @param {string} holonId - Holon to search in
-   * @param {string} lensName - Lens to search in (optional)
-   * @param {Object} options - Options
-   * @returns {Promise<Array>} Similar items
-   */
-  async findSimilar(item, holonId, lensName = null, options = {}) {
-    this._requireAI();
-    return this._ai.relationships.findSimilar(item, holonId, lensName, options);
-  }
-
-  /**
-   * Build relationship graph
-   * @param {string} holonId - Holon
-   * @param {string} lensName - Lens
-   * @returns {Promise<Object>} Graph structure
-   */
-  async buildRelationshipGraph(holonId, lensName) {
-    this._requireAI();
-    return this._ai.relationships.buildGraph(holonId, lensName);
-  }
-
-  /**
-   * Suggest connections for an item
-   * @param {Object} item - Item to find connections for
-   * @param {string} holonId - Holon
-   * @param {string} lensName - Lens
-   * @returns {Promise<Object>} Suggested connections
-   */
-  async suggestConnections(item, holonId, lensName) {
-    this._requireAI();
-    return this._ai.relationships.suggestConnections(item, holonId, lensName);
-  }
-
-  // --- Task Breakdown ---
-
-  /**
-   * Recursively break down a task/quest into subtasks
-   * @param {Object} item - The item to break down (must have id)
-   * @param {string} holonId - Holon where the item lives
-   * @param {string} lensName - Lens name (e.g., 'quests', 'tasks')
-   * @param {Object} options - Breakdown options
-   * @param {number} options.depth - Maximum recursion depth (default: 2)
-   * @param {number|Object} options.stepsPerLevel - Subtasks per level (default: {min:3, max:5})
-   * @param {boolean} options.useContext - Look at other items for context (default: true)
-   * @param {boolean} options.storeResults - Store generated subtasks (default: true)
-   * @returns {Promise<Object>} Breakdown result with tree structure
-   */
-  async breakdown(item, holonId, lensName, options = {}) {
-    this._requireAI();
-    return this._ai.taskBreakdown.breakdown(item, holonId, lensName, options);
-  }
-
-  /**
-   * Suggest breakdown strategy for a task
-   * @param {Object} item - Item to analyze
-   * @returns {Promise<Object>} Suggested breakdown strategy
-   */
-  async suggestBreakdownStrategy(item) {
-    this._requireAI();
-    return this._ai.taskBreakdown.suggestStrategy(item);
-  }
-
-  /**
-   * Flatten a breakdown tree into a list
-   * @param {Object} breakdownResult - Result from breakdown()
-   * @returns {Object[]} Flat list of all items
-   */
-  flattenBreakdown(breakdownResult) {
-    this._requireAI();
-    return this._ai.taskBreakdown.flatten(breakdownResult);
-  }
-
-  /**
-   * Get items in dependency order for execution
-   * @param {Object} breakdownResult - Result from breakdown()
-   * @returns {Object[]} Items in dependency order
-   */
-  getBreakdownDependencyOrder(breakdownResult) {
-    this._requireAI();
-    return this._ai.taskBreakdown.getDependencyOrder(breakdownResult);
-  }
-
-  /**
-   * Get progress on a breakdown tree
-   * @param {string} holonId - Holon ID
-   * @param {string} lensName - Lens name
-   * @param {string} itemId - Root item ID
-   * @returns {Promise<Object>} Progress summary
-   */
-  async getBreakdownProgress(holonId, lensName, itemId) {
-    this._requireAI();
-    return this._ai.taskBreakdown.getProgress(holonId, lensName, itemId);
-  }
-
-  // --- H3 Geospatial AI ---
-
-  /**
-   * Suggest optimal H3 resolution for a task/project
-   * @param {Object} item - Item to analyze
-   * @param {Object} options - Options including currentResolution
-   * @returns {Promise<Object>} Resolution recommendation
-   */
-  async suggestH3Resolution(item, options = {}) {
-    this._requireAI();
-    return this._ai.h3ai.suggestResolution(item, options);
-  }
-
-  /**
-   * Analyze geographic distribution of data in a region
-   * @param {string} holonId - Parent holon to analyze
-   * @param {string} lensName - Lens to analyze
-   * @param {Object} options - Options
-   * @returns {Promise<Object>} Distribution analysis
-   */
-  async analyzeH3Distribution(holonId, lensName, options = {}) {
-    this._requireAI();
-    return this._ai.h3ai.analyzeDistribution(holonId, lensName, options);
-  }
-
-  /**
-   * Find relevant data from neighboring H3 cells
-   * @param {string} holonId - Center holon
-   * @param {string} lensName - Lens to search
-   * @param {Object} options - Options including ringSize
-   * @returns {Promise<Object>} Neighbor analysis
-   */
-  async findH3NeighborRelevance(holonId, lensName, options = {}) {
-    this._requireAI();
-    return this._ai.h3ai.findNeighborRelevance(holonId, lensName, options);
-  }
-
-  /**
-   * Suggest geographic expansion or contraction for an item
-   * @param {Object} item - Item to analyze
-   * @param {string} holonId - Current holon
-   * @param {string} lensName - Lens
-   * @param {Object} options - Options
-   * @returns {Promise<Object>} Scope suggestions
-   */
-  async suggestGeographicScope(item, holonId, lensName, options = {}) {
-    this._requireAI();
-    return this._ai.h3ai.suggestGeographicScope(item, holonId, lensName, options);
-  }
-
-  /**
-   * Analyze coverage gaps in a region
-   * @param {string} holonId - Region to analyze
-   * @param {string} lensName - Lens
-   * @param {Object} options - Options including targetResolution
-   * @returns {Promise<Object>} Coverage analysis
-   */
-  async analyzeH3Coverage(holonId, lensName, options = {}) {
-    this._requireAI();
-    return this._ai.h3ai.analyzeCoverage(holonId, lensName, options);
-  }
-
-  /**
-   * Find patterns across multiple H3 resolutions
-   * @param {string} holonId - Starting holon
-   * @param {string} lensName - Lens
-   * @param {Object} options - Options including levels
-   * @returns {Promise<Object>} Cross-resolution insights
-   */
-  async crossH3ResolutionInsights(holonId, lensName, options = {}) {
-    this._requireAI();
-    return this._ai.h3ai.crossResolutionInsights(holonId, lensName, options);
-  }
-
-  /**
-   * Suggest item migration between holons based on geographic fit
-   * @param {Object} item - Item to analyze
-   * @param {string} holonId - Current location
-   * @param {string} lensName - Lens
-   * @param {Object} options - Options including searchRadius
-   * @returns {Promise<Object>} Migration suggestions
-   */
-  async suggestH3Migration(item, holonId, lensName, options = {}) {
-    this._requireAI();
-    return this._ai.h3ai.suggestMigration(item, holonId, lensName, options);
-  }
-
-  /**
-   * Generate a geographic activity report for a region
-   * @param {string} holonId - Region to report on
-   * @param {Object} options - Options including lenses array
-   * @returns {Promise<Object>} Geographic report
-   */
-  async generateH3Report(holonId, options = {}) {
-    this._requireAI();
-    return this._ai.h3ai.generateGeographicReport(holonId, options);
-  }
-
-  /**
-   * Find geographic clusters of related items
-   * @param {string} holonId - Region to analyze
-   * @param {string} lensName - Lens
-   * @param {Object} options - Options including clusterResolution
-   * @returns {Promise<Object>} Geographic 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
-   * @param {string} holonId - Item's holon
-   * @param {string} lensName - Lens
-   * @param {Object} options - Options
-   * @returns {Promise<Object>} Impact analysis
-   */
-  async analyzeH3Impact(item, holonId, lensName, options = {}) {
-    this._requireAI();
-    return this._ai.h3ai.analyzeGeographicImpact(item, holonId, lensName, options);
-  }
-
-  // === Cross-Holosphere Federation ===
-
-  /**
-   * Add a federated holosphere partner (manual key exchange)
-   * @param {string} pubKey - Partner's public key
-   * @param {Object} options - Federation options
-   * @param {string} options.alias - Human-readable name for this partner
-   * @param {Object[]} options.inboundCapabilities - Capabilities they've granted us
-   * @returns {Promise<boolean>} Success indicator
-   */
-  async addFederatedHolosphere(pubKey, options = {}) {
-    if (!pubKey || typeof pubKey !== 'string') {
-      throw new ValidationError('pubKey must be a valid public key string');
-    }
-
-    return registry.addFederatedPartner(
-      this.client,
-      this.config.appName,
-      pubKey,
-      options
-    );
-  }
-
-  /**
-   * Remove a federated holosphere partner
-   * @param {string} pubKey - Partner's public key
-   * @returns {Promise<boolean>} Success indicator
-   */
-  async removeFederatedHolosphere(pubKey) {
-    return registry.removeFederatedPartner(
-      this.client,
-      this.config.appName,
-      pubKey
-    );
-  }
-
-  /**
-   * Get all federated holosphere public keys
-   * @returns {Promise<string[]>} Array of federated public keys
-   */
-  async getFederatedHolospheres() {
-    return registry.getFederatedAuthors(
-      this.client,
-      this.config.appName
-    );
-  }
-
-  /**
-   * Get the full federation registry for this holosphere
-   * @returns {Promise<Object>} Federation registry
-   */
-  async getFederationRegistry() {
-    return registry.getFederationRegistry(
-      this.client,
-      this.config.appName
-    );
-  }
-
-  /**
-   * Store a capability token received from another holosphere
-   * @param {string} partnerPubKey - Partner's public key
-   * @param {Object} capabilityInfo - Capability information
-   * @param {string} capabilityInfo.token - The capability token
-   * @param {Object} capabilityInfo.scope - Token scope
-   * @param {string[]} capabilityInfo.permissions - Granted permissions
-   * @param {number} capabilityInfo.expires - Expiration timestamp
-   * @returns {Promise<boolean>} Success indicator
-   */
-  async storeInboundCapability(partnerPubKey, capabilityInfo) {
-    return registry.storeInboundCapability(
-      this.client,
-      this.config.appName,
-      partnerPubKey,
-      capabilityInfo
-    );
-  }
-
-  /**
-   * Read data from a federated source (cross-holosphere)
-   * @param {string} sourcePubKey - Source holosphere's public key
-   * @param {string} holonId - Holon ID
-   * @param {string} lensName - Lens name
-   * @param {string} dataId - Optional specific data ID
-   * @returns {Promise<Object|Object[]|null>} Data from federated source
-   */
-  async readFromFederatedSource(sourcePubKey, holonId, lensName, dataId = null) {
-    // Get capability for this source
-    const capabilityEntry = await registry.getCapabilityForAuthor(
-      this.client,
-      this.config.appName,
-      sourcePubKey,
-      { holonId, lensName, dataId }
-    );
-
-    if (!capabilityEntry) {
-      throw new AuthorizationError('No valid capability for federated source', 'read');
-    }
-
-    // Verify capability is still valid
-    const isValid = await this.verifyCapability(
-      capabilityEntry.token,
-      'read',
-      { holonId, lensName, dataId }
-    );
-
-    if (!isValid) {
-      throw new AuthorizationError('Capability verification failed', 'read');
-    }
-
-    // Read with specific author
-    if (dataId) {
-      const path = storage.buildPath(this.config.appName, holonId, lensName, dataId);
-      return nostrAsync.nostrGet(this.client, path, 30000, {
-        authors: [sourcePubKey],
-        includeAuthor: true,
-      });
-    } else {
-      const path = storage.buildPath(this.config.appName, holonId, lensName);
-      return nostrAsync.nostrGetAll(this.client, path, 30000, {
-        authors: [sourcePubKey],
-        includeAuthor: true,
-      });
-    }
-  }
-
-  /**
-   * Create a cross-holosphere hologram with embedded capability
-   * @param {string} sourcePubKey - Source holosphere's public key
-   * @param {string} sourceHolon - Source holon ID
-   * @param {string} lensName - Lens name
-   * @param {string} dataId - Data ID
-   * @param {string} targetHolon - Target holon ID (where hologram will live)
-   * @param {Object} options - Creation options
-   * @param {boolean} options.embedCapability - Whether to embed capability in hologram (default: true)
-   * @returns {Promise<Object>} Hologram object
-   */
-  async createCrossHolosphereHologram(sourcePubKey, sourceHolon, lensName, dataId, targetHolon, options = {}) {
-    const { embedCapability = true } = options;
-
-    // Get capability for this source
-    const capabilityEntry = await registry.getCapabilityForAuthor(
-      this.client,
-      this.config.appName,
-      sourcePubKey,
-      { holonId: sourceHolon, lensName, dataId }
-    );
-
-    if (!capabilityEntry) {
-      throw new AuthorizationError('No valid capability for cross-holosphere hologram', 'read');
-    }
-
-    // Create hologram with embedded capability
-    const hologram = federation.createHologram(
-      sourceHolon,
-      targetHolon,
-      lensName,
-      dataId,
-      this.config.appName,
-      {
-        authorPubKey: sourcePubKey,
-        capability: embedCapability ? capabilityEntry.token : null,
-      }
-    );
-
-    // Write hologram to target holon
-    const targetPath = storage.buildPath(this.config.appName, targetHolon, lensName, dataId);
-    await storage.write(this.client, targetPath, hologram);
-
-    return hologram;
-  }
-
-  /**
-   * Issue a capability token for federation with another holosphere
-   * @param {string} targetPubKey - Recipient's public key
-   * @param {Object} scope - Capability scope { holonId, lensName, dataId? }
-   * @param {string[]} permissions - Array of permissions ['read', 'write', 'delete']
-   * @param {Object} options - Additional options
-   * @param {number} options.expiresIn - Expiration in ms (default: 1 hour)
-   * @param {boolean} options.trackInRegistry - Store in registry (default: true)
-   * @returns {Promise<string>} Capability token
-   */
-  async issueCapabilityForFederation(targetPubKey, scope, permissions, options = {}) {
-    const { expiresIn = 3600000, trackInRegistry = true } = options;
-
-    const token = await crypto.issueCapability(
-      permissions,
-      scope,
-      targetPubKey,
-      {
-        expiresIn,
-        issuerKey: this.client.privateKey,
-      }
-    );
-
-    // Track in registry
-    if (trackInRegistry) {
-      // Ensure partner exists in registry
-      const partner = await registry.getFederatedPartner(
-        this.client,
-        this.config.appName,
-        targetPubKey
-      );
-
-      if (!partner) {
-        await registry.addFederatedPartner(
-          this.client,
-          this.config.appName,
-          targetPubKey,
-          { addedVia: 'capability_issued' }
-        );
-      }
-
-      await registry.storeOutboundCapability(
-        this.client,
-        this.config.appName,
-        targetPubKey,
-        {
-          tokenHash: await this._hashToken(token),
-          scope,
-          permissions,
-          expires: Date.now() + expiresIn,
-        }
-      );
-    }
-
-    return token;
-  }
-
-  /**
-   * Hash a token for storage (don't store full token)
-   * @private
-   */
-  async _hashToken(token) {
-    const { sha256 } = await import('@noble/hashes/sha256');
-    const { bytesToHex } = await import('@noble/hashes/utils');
-    const encoder = new TextEncoder();
-    return bytesToHex(sha256(encoder.encode(token)));
-  }
-
-  // === Nostr Discovery Protocol (Optional) ===
-
-  /**
-   * Send a federation request via Nostr
-   * @param {string} targetPubKey - Target holosphere's public key
-   * @param {Object} options - Request options
-   * @param {Object} options.scope - Requested scope { holonId, lensName }
-   * @param {string[]} options.permissions - Requested permissions
-   * @param {string} options.message - Optional message
-   * @returns {Promise<Object>} Published event info
-   */
-  async sendFederationRequest(targetPubKey, options = {}) {
-    return discovery.sendFederationRequest(
-      this.client,
-      this.config.appName,
-      targetPubKey,
-      options
-    );
-  }
-
-  /**
-   * Subscribe to incoming federation requests
-   * @param {Function} callback - Called with each request
-   * @returns {Promise<Object>} Subscription with unsubscribe method
-   */
-  async subscribeFederationRequests(callback) {
-    return discovery.subscribeFederationRequests(this.client, callback);
-  }
-
-  /**
-   * Accept a federation request
-   * @param {Object} request - Request object from subscription
-   * @param {Object} options - Acceptance options
-   * @returns {Promise<Object>} Published acceptance event info
-   */
-  async acceptFederationRequest(request, options = {}) {
-    return discovery.acceptFederationRequest(
-      this.client,
-      this.config.appName,
-      request,
-      options
-    );
-  }
-
-  /**
-   * Decline a federation request
-   * @param {Object} request - Request object from subscription
-   * @param {string} reason - Optional decline reason
-   * @returns {Promise<Object>} Published decline event info
-   */
-  async declineFederationRequest(request, reason = '') {
-    return discovery.declineFederationRequest(
-      this.client,
-      this.config.appName,
-      request,
-      reason
-    );
-  }
-
-  /**
-   * Subscribe to federation acceptances (responses to our requests)
-   * @param {Function} callback - Called with each acceptance
-   * @returns {Promise<Object>} Subscription with unsubscribe method
-   */
-  async subscribeFederationAcceptances(callback) {
-    return discovery.subscribeFederationAcceptances(
-      this.client,
-      this.config.appName,
-      callback
-    );
-  }
-
-  /**
-   * Subscribe to federation declines
-   * @param {Function} callback - Called with each decline
-   * @returns {Promise<Object>} Subscription with unsubscribe method
-   */
-  async subscribeFederationDeclines(callback) {
-    return discovery.subscribeFederationDeclines(this.client, callback);
-  }
-
-  /**
-   * Get pending federation requests (requests we've sent that haven't been answered)
-   * @param {Object} options - Query options
-   * @returns {Promise<Object[]>} Array of pending requests
-   */
-  async getPendingFederationRequests(options = {}) {
-    return discovery.getPendingFederationRequests(this.client, options);
-  }
-}
-
-// Export error classes
-export class AuthorizationError extends Error {
-  constructor(message, requiredPermission = null) {
-    super(message);
-    this.name = 'AuthorizationError';
-    this.requiredPermission = requiredPermission;
-  }
-}
-
-export class HolosphereError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = 'HolosphereError';
-  }
-}
-
-// Re-export ValidationError from validator module
-export { ValidationError } from './schema/validator.js';
-
-// Export utilities
-export { nostrAsync };
-
-// Export hologram helper functions
+// Export network utilities
 export {
-  isHologram,
-  isResolvedHologram,
-  getHologramSource,
-  updateHologramOverrides,
-  addActiveHologram,
-  removeActiveHologram,
-  refreshActiveHolograms,
-  deleteHologram,
-  propagateData,
-  createHologram,
-  resolveHologram,
-  cleanupCircularHolograms,
-  cleanupCircularHologramsByIds
-} from './federation/hologram.js';
-
-// Export federation registry functions
-export {
-  getFederationRegistry,
-  addFederatedPartner,
-  removeFederatedPartner,
-  getFederatedAuthors,
-  getCapabilityForAuthor,
-  storeInboundCapability,
-  storeOutboundCapability,
-  cleanupExpiredCapabilities
-} from './federation/registry.js';
-
-// Export Nostr discovery protocol functions
-export {
-  sendFederationRequest,
-  subscribeFederationRequests,
-  acceptFederationRequest,
-  declineFederationRequest,
-  subscribeFederationAcceptances,
-  subscribeFederationDeclines,
-  getPendingFederationRequests
-} from './federation/discovery.js';
-
-// Export scope matching utility
-export { matchScope } from './crypto/secp256k1.js';
-
-// Export AI modules for standalone use
-export {
-  LLMService,
-  SchemaExtractor,
-  JSONOps,
-  Embeddings,
-  Council,
-  TTS,
-  VOICES,
-  MODELS,
-  NLQuery,
-  Classifier,
-  SpatialAnalysis,
-  SmartAggregation,
-  FederationAdvisor,
-  RelationshipDiscovery,
-  TaskBreakdown,
-  H3AI
-};
-
-// Export AI factory function
-export { createAIServices } from './ai/index.js';
+  NETWORKS,
+  getNetwork,
+  getNetworksByType,
+  listNetworks,
+  isNetworkSupported,
+  getTxUrl,
+  getAddressUrl
+} from './contracts/networks.js';
+
+// Export contracts namespace
+export { networks };
 
 // Default export for backward compatibility
 export default HoloSphere;