holosphere 2.0.0-alpha2 → 2.0.0-alpha4

package/src/index.js

@@ -5,18 +5,19 @@
 
 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,13 +35,29 @@ 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
  */
-export class HoloSphere extends HoloSphereCore {
+class HoloSphereBase extends HoloSphereCore {
   constructor(config) {
     super(config);
     this.schemas = new Map();
+    this._cache = new Map();
     this.subscriptionRegistry = new subscriptions.SubscriptionRegistry();
 
     // Initialize AI services if openaiKey is provided or OPENAI_API_KEY env var is set
@@ -54,12 +71,11 @@ export class HoloSphere extends HoloSphereCore {
       };
       this._initializeAI(openaiKey, aiOptions);
     }
+
+    // Contracts module (lazy initialized)
+    this._contracts = null;
   }
 
-  /**
-   * Get environment variable (works in Node.js)
-   * @private
-   */
   _getEnv(name) {
     if (typeof process !== 'undefined' && process.env) {
       return process.env[name];
@@ -67,39 +83,27 @@ export class HoloSphere extends HoloSphereCore {
     return undefined;
   }
 
-  /**
-   * Parse float from string, return undefined if invalid
-   * @private
-   */
   _parseFloat(value) {
     if (value === undefined || value === null) return undefined;
     const parsed = parseFloat(value);
     return isNaN(parsed) ? undefined : parsed;
   }
 
-  /**
-   * Initialize AI services
-   * @private
-   */
   _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);
@@ -115,18 +119,10 @@ export class HoloSphere extends HoloSphereCore {
     this._ai.h3ai = new H3AI(this._ai.llm, this);
   }
 
-  /**
-   * Check if AI services are initialized
-   * @returns {boolean}
-   */
   hasAI() {
     return this._ai !== null;
   }
 
-  /**
-   * Get AI services object (for advanced usage)
-   * @returns {Object|null}
-   */
   getAIServices() {
     return this._ai;
   }
@@ -149,8 +145,8 @@ export class HoloSphere extends HoloSphereCore {
   }
 
   // === Data Operations ===
+
   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,60 +157,39 @@ 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
     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
+    // Handle hologram writes
     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 localData = { ...existingData };
       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
+        if (hologramStructureFields.includes(key) || key === '_hologram') continue;
+        if (localOverrideFields.includes(key)) {
           localData[key] = value;
         } else {
-          // This field doesn't exist in hologram - update source
           sourceUpdates[key] = value;
         }
       }
 
-      // 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,
@@ -232,27 +207,23 @@ export class HoloSphere extends HoloSphereCore {
         }
       }
 
-      // 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);
+        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);
-
-        // Refresh timestamps on all activeHolograms in source data's _meta
         await federation.refreshActiveHolograms(
           this.client,
-          sourceAppname,
-          sourceHolonId,
-          sourceLensName,
-          sourceDataId
+          existingData.target.appname || this.config.appName,
+          existingData.target.holonId,
+          existingData.target.lensName,
+          existingData.target.dataId
         );
       }
 
@@ -264,109 +235,120 @@ export class HoloSphere extends HoloSphereCore {
       return true;
     }
 
-    // Regular write (not a hologram) - proceed normally
-    // Add metadata
-    if (!data._meta) {
-      data._meta = {};
-    }
-    data._meta.timestamp = Date.now();
+    // Regular write
+    if (!data._meta) data._meta = {};
+    data._meta.createdAt = data._meta.createdAt || Date.now();
+    data._meta.updatedAt = Date.now();
 
-    // Schema validation if 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 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
+      if (schemaObj.schema && typeof schemaObj.schema === 'object' && !schemaObj.schema.$ref) {
         schema.validate(data, schemaObj.schema, lensName, strict);
       }
     }
 
-    // Write to storage
     const startTime = Date.now();
-    const success = await storage.write(this.client, path, data);
+    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);
+    this._metrics.writes++;
+    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);
-        }
-      }
+    const { autoPropagate = true } = options;
+    if (autoPropagate && !data.hologram) {
+      await this.propagate(holonId, lensName, data, options.propagationOptions || {});
     }
 
-    return success;
+    return true;
   }
 
-  /**
-   * Resolve holograms recursively
-   * @private
-   * @param {*} data - Data that may contain holograms (object, array, or primitive)
-   * @returns {Promise<*>} Resolved 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
+        );
 
-      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;
-      }
+        // Circular reference detection
+        if (visited.has(sourcePath)) {
+          console.warn(`Circular hologram reference detected: ${sourcePath}`);
+          return null;
+        }
+        visited.add(sourcePath);
 
-      // 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;
-    }
+        let resolveOptions = {};
+        if (data.target.authorPubKey) {
+          resolveOptions.authors = [data.target.authorPubKey];
+          resolveOptions.includeAuthor = true;
+        }
+
+        const sourceData = await storage.read(this.client, sourcePath, resolveOptions);
+        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
+            }
+          }
 
-    // Primitive value
+          // 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 };
+          }
+
+          return merged;
+        }
+        return null; // Source not found
+      }
+    }
     return data;
   }
 
   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,227 +356,150 @@ 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;
+      result = await storage.read(this.client, path);
     } else {
       const path = storage.buildPath(this.config.appName, holonId, lensName);
-      const result = await storage.readAll(this.client, path, {
-        ...queryOptions,
-        hybrid: this.config.hybridMode
-      });
+      result = await storage.readAll(this.client, path);
+    }
 
-      // Always resolve holograms in array results
-      const resolved = await this._resolveHolograms(result);
+    const { resolveHolograms = true } = options;
+    if (resolveHolograms) {
+      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;
   }
 
   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);
-      }
+    const existingData = await storage.read(this.client, path);
 
-      // 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) {
+      return false;
+    }
 
-      return true;
+    // Handle hologram updates
+    if (existingData.hologram === true && existingData.target) {
+      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);
+    const startTime = Date.now();
+    await storage.write(this.client, path, mergedData);
+    const endTime = Date.now();
+
+    this._metrics.writes++;
+    if (!this._metrics.totalWriteTime) this._metrics.totalWriteTime = 0;
+    this._metrics.totalWriteTime += (endTime - startTime);
+
+    if (existingData._meta && existingData._meta.activeHolograms) {
+      await federation.refreshActiveHolograms(this.client, this.config.appName, holonId, lensName, dataId);
+    }
+
+    return true;
   }
 
   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);
+    const existingData = await storage.read(this.client, path);
 
-    // If data doesn't exist, return false
-    if (!existing) {
+    // Return false if data doesn't exist
+    if (!existingData) {
       return false;
     }
 
-    // Check authorization
-    const capToken = options.capabilityToken || options.capability;
-    const creator = existing._creator || existing.owner;
-    const currentUser = this.client.publicKey;
-
-    // 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);
+    if (existingData.hologram === true) {
+      return this.deleteHologram(holonId, lensName, dataId, options);
+    }
+
+    await storage.deleteData(this.client, path);
+    this._metrics.deletes++;
+    return true;
   }
 
-  // === Global Data Operations ===
+  // === Global Tables ===
   async writeGlobal(table, data) {
     return globalTables.writeGlobal(this.client, this.config.appName, table, data);
   }
@@ -612,16 +517,16 @@ export class HoloSphere extends HoloSphereCore {
   }
 
   async getAllGlobal(table) {
-    return globalTables.readGlobal(this.client, this.config.appName, table);
+    return globalTables.getAllGlobal(this.client, this.config.appName, table);
   }
 
   async deleteAllGlobal(table) {
     return globalTables.deleteAllGlobal(this.client, this.config.appName, table);
   }
 
-  // === Holon Data Operations ===
+  // === Batch Operations ===
   async getAll(holonId, lensName) {
-    return this.read(holonId, lensName);
+    return this.read(holonId, lensName, null);
   }
 
   async deleteAll(holonId, lensName) {
@@ -630,27 +535,41 @@ export class HoloSphere extends HoloSphereCore {
   }
 
   // === 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');
+  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() });
   }
 
   async getSchema(lensName) {
@@ -660,30 +579,23 @@ export class HoloSphere extends HoloSphereCore {
 
   async clearSchema(lensName) {
     this.schemas.delete(lensName);
-    schema.clearSchemaCache(lensName);
+    // Returns undefined for contract compliance
   }
 
   // === Federation Operations ===
   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,134 +604,63 @@ export class HoloSphere extends HoloSphereCore {
       options
     );
 
-    if (result) {
-      if (!this._metrics.federations) this._metrics.federations = 0;
-      this._metrics.federations++;
-
-      // By default, propagate existing data when federation is set up
-      // Set propagateExisting: false to only federate future writes
-      const propagateExisting = options.propagateExisting !== false;
+    // 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 });
+    }
 
-      if (!propagateExisting) {
-        return result;
-      }
+    this._metrics.federations = (this._metrics.federations || 0) + 1;
+    return true;
+  }
 
-      // 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
-            );
-          }
-        }
-      }
+  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;
 
-      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
-            );
-          }
-        }
-      }
+    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;
   }
 
   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);
   }
 
   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
-   */
   async updateHologramOverrides(holonId, lensName, dataId, overrides) {
     return federation.updateHologramOverrides(
       this.client,
@@ -831,18 +672,7 @@ 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
-   */
   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,
@@ -852,31 +682,16 @@ 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
-   */
   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;
-  }
-
-  /**
-   * 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
-   */
+    return sourceData._meta.activeHolograms;
+  }
+
   async removeActiveHologram(sourceHolon, lensName, dataId, targetHolon) {
     return federation.removeActiveHologram(
       this.client,
@@ -888,14 +703,6 @@ 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
-   */
   async deleteHologram(holonId, lensName, dataId, options = {}) {
     return federation.deleteHologram(
       this.client,
@@ -907,19 +714,9 @@ 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
-   * @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
-   */
   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,
@@ -931,51 +728,22 @@ export class HoloSphere extends HoloSphereCore {
     );
   }
 
-  /**
-   * Resolve a hologram to its actual data, merging local overrides
-   * @param {Object} hologram - Hologram object to resolve
-   * @returns {Promise<Object|null>} Resolved data or null
-   */
-  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
-   */
   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
-   */
   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
-   */
   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
-   */
   async cleanupCircularHolograms(holonId, lensName, options = {}) {
     return federation.cleanupCircularHolograms(
       this.client,
@@ -986,16 +754,6 @@ 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
-   * @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
-   */
   async cleanupCircularHologramsByIds(holonId, lensName, dataIds, options = {}) {
     return federation.cleanupCircularHologramsByIds(
       this.client,
@@ -1007,131 +765,41 @@ 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
-   */
   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;
   }
 
   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 = {};
 
-    // 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);
     }
@@ -1139,25 +807,14 @@ export class HoloSphere extends HoloSphereCore {
     return data;
   }
 
-  /**
-   * 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
-   */
   async federateHolon(sourceHolon, targetHolon, options = {}) {
     const { lensConfig = { inbound: [], outbound: [] } } = 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: [],
@@ -1167,67 +824,44 @@ export class HoloSphere extends HoloSphereCore {
       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 = {};
 
-    // 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
     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)
       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' });
       }
@@ -1236,46 +870,27 @@ export class HoloSphere extends HoloSphereCore {
     return success;
   }
 
-  /**
-   * Unfederate two holons at the holon level
-   * @param {string} sourceHolon - Source holon ID
-   * @param {string} targetHolon - Target holon ID
-   * @returns {Promise<boolean>} Success indicator
-   */
   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);
       }
@@ -1284,48 +899,31 @@ export class HoloSphere extends HoloSphereCore {
     return success;
   }
 
-  /**
-   * 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
-   */
   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 ===
   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 ===
   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,52 +934,26 @@ 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
-   */
   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 ===
@@ -1407,1242 +979,161 @@ export class HoloSphere extends HoloSphereCore {
 
   // === Social Protocol Operations ===
   async publishNostr(event, holonId, lensName = 'social') {
-    // Validate with throwing error (partial=true allows missing id/pubkey/sig)
-    social.validateNostrEvent(event, true, 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);
-
-      // Update event with signature fields
-      event.id = signedEvent.id;
-      event.pubkey = signedEvent.pubkey;
-      event.sig = signedEvent.sig;
-    }
+    // Validate Nostr event format
+    social.validateNostrEvent(event, true, true); // partial=true, throwOnError=true
 
-    const transformed = social.transformNostrEvent(event);
-    return this.write(holonId, lensName, transformed);
+    const enrichedEvent = {
+      ...event,
+      tags: [...(event.tags || []), ['h', holonId], ['l', lensName]],
+    };
+    const signedEvent = nostrUtils.signEvent(enrichedEvent, this.client.privateKey);
+
+    // Add protocol field for querySocial filtering
+    const eventWithProtocol = {
+      ...signedEvent,
+      protocol: 'nostr',
+    };
+
+    const path = storage.buildPath(this.config.appName, holonId, lensName, signedEvent.id);
+    await storage.write(this.client, path, eventWithProtocol);
+    return true;
   }
 
   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);
   }
 
   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;
+    });
   }
 
   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 ===
   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,
     };
   }
 
-  // === Functional Aliases ===
-  // Common CRUD-style aliases for data operations
-
-  /**
-   * Alias for write() - stores data in a holon/lens
-   * @alias write
-   */
+  // === Aliases ===
   async put(holonId, lensName, data, options = {}) {
     return this.write(holonId, lensName, data, options);
   }
 
-  /**
-   * Alias for read() - retrieves data from a holon/lens
-   * @alias read
-   */
   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
-   */
   async remove(holonId, lensName, dataId, options = {}) {
     return this.delete(holonId, lensName, dataId, options);
   }
 
-  /**
-   * Alias for writeGlobal() - stores data in global table
-   * @alias writeGlobal
-   */
   async putGlobal(table, data) {
     return this.writeGlobal(table, data);
   }
 
-  /**
-   * Alias for readGlobal() - retrieves data from global table
-   * @alias readGlobal
-   */
   async getGlobal(table, key = null) {
     return this.readGlobal(table, key);
   }
 
-  /**
-   * Alias for deleteGlobal() - removes data from global table
-   * @alias deleteGlobal
-   */
   async removeGlobal(table, key) {
     return this.deleteGlobal(table, key);
   }
 
-  /**
-   * Alias for setSchema() - defines a schema for a lens
-   * @alias setSchema
-   */
   async defineSchema(lensName, schemaObj, strict = false) {
     return this.setSchema(lensName, schemaObj, strict);
   }
 
-  /**
-   * Alias for getSchema() - retrieves schema for a lens
-   * @alias getSchema
-   */
   async fetchSchema(lensName) {
     return this.getSchema(lensName);
   }
 
-  /**
-   * Alias for clearSchema() - removes schema for a lens
-   * @alias clearSchema
-   */
   async removeSchema(lensName) {
     return this.clearSchema(lensName);
   }
 
-  /**
-   * Store data - more semantic alias for write
-   * @alias write
-   */
   async store(holonId, lensName, data, options = {}) {
     return this.write(holonId, lensName, data, options);
   }
 
-  /**
-   * Fetch data - more semantic alias for read
-   * @alias read
-   */
   async fetch(holonId, lensName, dataId = null, options = {}) {
     return this.read(holonId, lensName, dataId, options);
   }
 
-  /**
-   * Save data - alternative alias for write
-   * @alias write
-   */
   async save(holonId, lensName, data, options = {}) {
     return this.write(holonId, lensName, data, options);
   }
 
-  /**
-   * Load data - alternative alias for read
-   * @alias read
-   */
   async load(holonId, lensName, dataId = null, options = {}) {
     return this.read(holonId, lensName, dataId, options);
   }
 
-  /**
-   * 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)
-   */
+  // === Cache ===
   clearCache(pattern = null) {
-    if (this.client && this.client.clearCache) {
-      this.client.clearCache(pattern);
-    }
-  }
-
-  // === 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.');
-    }
-  }
-
-  // --- Core LLM Methods ---
-
-  /**
-   * 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);
-  }
-
-  /**
-   * 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);
-  }
-
-  /**
-   * 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);
-  }
-
-  /**
-   * 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);
-  }
-
-  /**
-   * 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);
-  }
-
-  /**
-   * 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,
+    if (pattern) {
+      for (const key of this._cache.keys()) {
+        if (key.includes(pattern)) {
+          this._cache.delete(key);
         }
-      );
+      }
+    } else {
+      this._cache.clear();
     }
-
-    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 };
+/**
+ * Main HoloSphere class - composed from base + all mixins
+ */
+export const HoloSphere = withContractMethods(
+  withFederationMethods(
+    withAIMethods(HoloSphereBase)
+  )
+);
 
-// Export hologram helper functions
-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 error classes
+export { AuthorizationError };
+export { ValidationError };
 
-// Export AI modules for standalone use
+// Re-export AI module classes
 export {
   LLMService,
   SchemaExtractor,
@@ -2659,11 +1150,44 @@ export {
   FederationAdvisor,
   RelationshipDiscovery,
   TaskBreakdown,
-  H3AI
+  H3AI,
 };
 
+// Re-export types and utilities
+export { spatial, storage, schema, federation, handshake, crypto, nostrUtils, social, subscriptions, hierarchical };
+
+// Re-export specific utilities used in tests
+export { matchScope } from './crypto/secp256k1.js';
+export { createHologram } from './federation/hologram.js';
+
 // Export AI factory function
 export { createAIServices } from './ai/index.js';
 
+// Export Contracts module classes for standalone use
+export {
+  ChainManager,
+  ContractDeployer,
+  HolonContracts,
+  ContractOperations,
+  ContractABIs,
+  EventListener,
+  ContractQueries,
+  SANKEY_EVENTS
+};
+
+// Export network utilities
+export {
+  NETWORKS,
+  getNetwork,
+  getNetworksByType,
+  listNetworks,
+  isNetworkSupported,
+  getTxUrl,
+  getAddressUrl
+} from './contracts/networks.js';
+
+// Export contracts namespace
+export { networks };
+
 // Default export for backward compatibility
 export default HoloSphere;