holosphere 1.1.20 → 2.0.0-alpha1

package/src/index.js

@@ -0,0 +1,2669 @@
+/**
+ * HoloSphere - Holonic Geospatial Communication Infrastructure
+ * Public API
+ */
+
+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 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 crypto from './crypto/secp256k1.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';
+import { SchemaExtractor } from './ai/schema-extractor.js';
+import { JSONOps } from './ai/json-ops.js';
+import { Embeddings } from './ai/embeddings.js';
+import { Council } from './ai/council.js';
+import { TTS, VOICES, MODELS } from './ai/tts.js';
+import { NLQuery } from './ai/nl-query.js';
+import { Classifier } from './ai/classifier.js';
+import { SpatialAnalysis } from './ai/spatial.js';
+import { SmartAggregation } from './ai/aggregation.js';
+import { FederationAdvisor } from './ai/federation-ai.js';
+import { RelationshipDiscovery } from './ai/relationships.js';
+import { TaskBreakdown } from './ai/breakdown.js';
+import { H3AI } from './ai/h3-ai.js';
+
+/**
+ * Main HoloSphere class with all methods
+ */
+export class HoloSphere extends HoloSphereCore {
+  constructor(config) {
+    super(config);
+    this.schemas = new Map();
+    this.subscriptionRegistry = new subscriptions.SubscriptionRegistry();
+
+    // Initialize AI services if openaiKey is provided or OPENAI_API_KEY env var is set
+    this._ai = null;
+    const openaiKey = config.openaiKey || this._getEnv('OPENAI_API_KEY');
+    if (openaiKey) {
+      const aiOptions = {
+        ...config.aiOptions,
+        model: config.aiOptions?.model || this._getEnv('HOLOSPHERE_AI_MODEL'),
+        temperature: config.aiOptions?.temperature ?? this._parseFloat(this._getEnv('HOLOSPHERE_AI_TEMPERATURE')),
+      };
+      this._initializeAI(openaiKey, aiOptions);
+    }
+  }
+
+  /**
+   * Get environment variable (works in Node.js)
+   * @private
+   */
+  _getEnv(name) {
+    if (typeof process !== 'undefined' && process.env) {
+      return process.env[name];
+    }
+    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);
+    this._ai.council = new Council(this._ai.llm);
+    this._ai.tts = new TTS(openai);
+    this._ai.nlQuery = new NLQuery(this._ai.llm, this);
+    this._ai.classifier = new Classifier(this._ai.llm, this);
+    this._ai.spatial = new SpatialAnalysis(this._ai.llm, this);
+    this._ai.aggregation = new SmartAggregation(this._ai.llm, this);
+    this._ai.federationAdvisor = new FederationAdvisor(this._ai.llm, this, this._ai.embeddings);
+    this._ai.relationships = new RelationshipDiscovery(this._ai.llm, this, this._ai.embeddings);
+    this._ai.taskBreakdown = new TaskBreakdown(this._ai.llm, this);
+    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;
+  }
+
+  // === Spatial Operations ===
+  async toHolon(lat, lng, resolution) {
+    return spatial.toHolon(lat, lng, resolution);
+  }
+
+  async getParents(holonId, maxResolution) {
+    return spatial.getParents(holonId, maxResolution);
+  }
+
+  async getChildren(holonId) {
+    return spatial.getChildren(holonId);
+  }
+
+  isValidH3(holonId) {
+    return spatial.isValidH3(holonId);
+  }
+
+  // === 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');
+    }
+    if (!lensName || typeof lensName !== 'string') {
+      throw new ValidationError('ValidationError: lensName must be a non-empty string');
+    }
+    if (!data || typeof data !== 'object') {
+      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 }
+      );
+      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
+    if (existingData && existingData.hologram === true && existingData.target) {
+      // Fields that define the hologram structure (never overwrite these)
+      const hologramStructureFields = ['hologram', 'soul', 'target', 'id', '_meta'];
+      // Fields that exist in the hologram as local overrides
+      const localOverrideFields = Object.keys(existingData).filter(k => !hologramStructureFields.includes(k));
+
+      // Split data: local fields stay local, everything else goes to source
+      const localData = {
+        ...existingData,  // Keep hologram structure
+      };
+      const sourceUpdates = {};
+
+      for (const [key, value] of Object.entries(data)) {
+        if (hologramStructureFields.includes(key)) {
+          // Skip - don't overwrite hologram structure
+          continue;
+        } else if (key === '_hologram') {
+          // Skip - this is resolved metadata, not real data
+          continue;
+        } else if (localOverrideFields.includes(key)) {
+          // This field exists in the hologram - update locally
+          localData[key] = value;
+        } else {
+          // This field doesn't exist in hologram - update source
+          sourceUpdates[key] = value;
+        }
+      }
+
+      // Schema validation for source updates (if schema exists)
+      if (Object.keys(sourceUpdates).length > 0 && options.validate !== false && this.schemas.has(lensName)) {
+        // Read current source data to merge with updates for validation
+        const sourcePath = storage.buildPath(
+          existingData.target.appname || this.config.appName,
+          existingData.target.holonId,
+          existingData.target.lensName,
+          existingData.target.dataId
+        );
+        const currentSourceData = await storage.read(this.client, sourcePath);
+        const mergedSourceData = { ...currentSourceData, ...sourceUpdates };
+
+        const schemaObj = this.schemas.get(lensName);
+        const strict = options.strict !== undefined ? options.strict : schemaObj.strict;
+
+        if (schemaObj.schema && typeof schemaObj.schema === 'object' && !schemaObj.schema.$ref) {
+          schema.validate(mergedSourceData, schemaObj.schema, lensName, strict);
+        }
+      }
+
+      // Update local hologram with its override fields
+      const startTime = Date.now();
+      await storage.write(this.client, path, localData);
+
+      // Update source data with non-local fields (partial update, not replace)
+      if (Object.keys(sourceUpdates).length > 0) {
+        const sourceAppname = existingData.target.appname || this.config.appName;
+        const sourceHolonId = existingData.target.holonId;
+        const sourceLensName = existingData.target.lensName;
+        const sourceDataId = existingData.target.dataId;
+
+        const sourcePath = storage.buildPath(sourceAppname, sourceHolonId, sourceLensName, sourceDataId);
+        await storage.update(this.client, sourcePath, sourceUpdates);
+
+        // Refresh timestamps on all activeHolograms in source data's _meta
+        await federation.refreshActiveHolograms(
+          this.client,
+          sourceAppname,
+          sourceHolonId,
+          sourceLensName,
+          sourceDataId
+        );
+      }
+
+      const endTime = Date.now();
+      this._metrics.writes++;
+      if (!this._metrics.totalWriteTime) this._metrics.totalWriteTime = 0;
+      this._metrics.totalWriteTime += (endTime - startTime);
+
+      return true;
+    }
+
+    // Regular write (not a hologram) - proceed normally
+    // Add metadata
+    if (!data._meta) {
+      data._meta = {};
+    }
+    data._meta.timestamp = 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
+        schema.validate(data, schemaObj.schema, lensName, strict);
+      }
+    }
+
+    // Write to storage
+    const startTime = Date.now();
+    const success = await storage.write(this.client, path, data);
+    const endTime = Date.now();
+
+    if (success) {
+      this._metrics.writes++;
+      // Track average write time
+      if (!this._metrics.totalWriteTime) this._metrics.totalWriteTime = 0;
+      this._metrics.totalWriteTime += (endTime - startTime);
+
+      // Refresh timestamps on all activeHolograms in the source data's _meta
+      // This allows interfaces to detect updates automatically
+      if (data._meta && Array.isArray(data._meta.activeHolograms) && data._meta.activeHolograms.length > 0) {
+        const result = await federation.refreshActiveHolograms(
+          this.client,
+          this.config.appName,
+          holonId,
+          lensName,
+          data.id,
+          data  // Pass the data we already have
+        );
+        // Update the written data with refreshed timestamps (already done in-place by refreshActiveHolograms)
+        if (result.refreshed > 0) {
+          // Re-write to persist the updated activeHolograms timestamps
+          await storage.write(this.client, path, result.sourceData);
+        }
+      }
+    }
+
+    return success;
+  }
+
+  /**
+   * 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
+    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) {
+          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 (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;
+      }
+
+      // 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;
+    }
+
+    // Primitive value
+    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');
+    }
+    if (!lensName || typeof lensName !== 'string') {
+      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);
+      }
+    }
+
+    // Query options including federated authors
+    const queryOptions = {
+      authors,
+      includeAuthor: true, // Track which author each item came from
+    };
+
+    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;
+    } else {
+      const path = storage.buildPath(this.config.appName, holonId, lensName);
+      const result = await storage.readAll(this.client, path, {
+        ...queryOptions,
+        hybrid: this.config.hybridMode
+      });
+
+      // Always resolve holograms in array results
+      const resolved = 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();
+      if (!this._metrics.totalReadTime) this._metrics.totalReadTime = 0;
+      this._metrics.totalReadTime += (endTime - startTime);
+      return filtered;
+    }
+  }
+
+  async update(holonId, lensName, dataId, updates, options = {}) {
+    // Check authorization if capability token provided
+    const capToken = options.capabilityToken || options.capability;
+    if (capToken) {
+      const authorized = await this.verifyCapability(
+        capToken,
+        'write',
+        { holonId, lensName }
+      );
+      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);
+      }
+
+      // 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);
+      }
+
+      return true;
+    }
+
+    // Regular data (not a hologram) - proceed with normal update
+    // Schema validation if exists and updates data
+    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);
+      }
+    }
+
+    return storage.update(this.client, path, updates);
+  }
+
+  async delete(holonId, lensName, dataId, options = {}) {
+    // Read existing data to check ownership and get activeHolograms
+    const existing = await this.read(holonId, lensName, dataId);
+
+    // If data doesn't exist, return false
+    if (!existing) {
+      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)
+
+    if (capToken) {
+      const authorized = await this.verifyCapability(
+        capToken,
+        'delete',
+        { holonId, lensName }
+      );
+      if (!authorized) {
+        const error = new AuthorizationError('AuthorizationError: Invalid capability token for delete operation', 'delete');
+        throw error;
+      }
+    } 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);
+        }
+      }
+    }
+
+    const path = storage.buildPath(this.config.appName, holonId, lensName, dataId);
+    return storage.deleteData(this.client, path);
+  }
+
+  // === Global Data Operations ===
+  async writeGlobal(table, data) {
+    return globalTables.writeGlobal(this.client, this.config.appName, table, data);
+  }
+
+  async readGlobal(table, key = null) {
+    return globalTables.readGlobal(this.client, this.config.appName, table, key);
+  }
+
+  async updateGlobal(table, key, updates) {
+    return globalTables.updateGlobal(this.client, this.config.appName, table, key, updates);
+  }
+
+  async deleteGlobal(table, key) {
+    return globalTables.deleteGlobal(this.client, this.config.appName, table, key);
+  }
+
+  async getAllGlobal(table) {
+    return globalTables.readGlobal(this.client, this.config.appName, table);
+  }
+
+  async deleteAllGlobal(table) {
+    return globalTables.deleteAllGlobal(this.client, this.config.appName, table);
+  }
+
+  // === Holon Data Operations ===
+  async getAll(holonId, lensName) {
+    return this.read(holonId, lensName);
+  }
+
+  async deleteAll(holonId, lensName) {
+    const path = storage.buildPath(this.config.appName, holonId, lensName);
+    return storage.deleteAll(this.client, path);
+  }
+
+  // === Schema Operations ===
+  async setSchema(lensName, schemaObj, strict = false) {
+    let resolvedSchema = schemaObj;
+
+    // If schemaObj is a string (URI), store as reference
+    if (typeof schemaObj === 'string') {
+      // Store as URI reference - validation will happen when used
+      resolvedSchema = { $ref: schemaObj };
+    }
+
+    if (!resolvedSchema || (typeof resolvedSchema !== 'object' && typeof resolvedSchema !== 'boolean')) {
+      throw new ValidationError('Schema must be a valid JSON Schema object or boolean');
+    }
+
+    // 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');
+      }
+    }
+
+    this.schemas.set(lensName, { schema: resolvedSchema, strict });
+  }
+
+  async getSchema(lensName) {
+    const schemaObj = this.schemas.get(lensName);
+    return schemaObj ? schemaObj.schema : null;
+  }
+
+  async clearSchema(lensName) {
+    this.schemas.delete(lensName);
+    schema.clearSchemaCache(lensName);
+  }
+
+  // === Federation Operations ===
+  async federate(sourceHolon, targetHolon, lensName, options = {}) {
+    // Validate self-federation
+    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;
+    }
+
+    const result = await federation.setupFederation(
+      this.client,
+      this.config.appName,
+      sourceHolon,
+      targetHolon,
+      lensName,
+      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;
+
+      if (!propagateExisting) {
+        return result;
+      }
+
+      // Propagate existing data based on direction
+      // Default to 'outbound' (source -> target) if no direction specified
+      const direction = options.direction || 'outbound';
+      const mode = options.mode || 'reference';
+      const filter = options.filter;
+
+      if (direction === 'outbound') {
+        // Source -> Target: propagate data from source to target
+        // Check if receiver accepts this lens in their inbound
+        const targetFederation = await this.getFederation(targetHolon);
+        const receiverLensConfig = targetFederation?.lensConfig?.[sourceHolon];
+        if (receiverLensConfig && receiverLensConfig.inbound && !receiverLensConfig.inbound.includes(lensName)) {
+          console.log(`Skipping outbound propagation - ${targetHolon} doesn't accept lens '${lensName}' in inbound from ${sourceHolon}`);
+        } else {
+          // Read raw data to avoid resolving holograms
+          const path = storage.buildPath(this.config.appName, sourceHolon, lensName);
+          const sourceData = await storage.readAll(this.client, path);
+          const sourceArray = Array.isArray(sourceData) ? sourceData : (sourceData ? [sourceData] : []);
+
+          for (const item of sourceArray) {
+            if (item.id === '_federation') continue; // Skip federation config
+            // Skip items that are already holograms or from another source
+            if (item.hologram === true) continue;
+            if (item._meta && item._meta.source && item._meta.source !== sourceHolon) continue;
+            if (filter && !filter(item)) continue; // Apply filter if provided
+
+            await federation.propagateData(
+              this.client,
+              this.config.appName,
+              item,
+              sourceHolon,
+              targetHolon,
+              lensName,
+              mode
+            );
+          }
+        }
+      }
+
+      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
+            );
+          }
+        }
+      }
+    }
+
+    return result;
+  }
+
+  async getFederatedData(holonId, lensName, options = {}) {
+    const { resolveHolograms = true } = options;
+
+    // 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] : []);
+
+      // Filter out federation config
+      return rawArray.filter(item => item != null && item.id !== '_federation');
+    }
+  }
+
+  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);
+    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,
+      this.config.appName,
+      holonId,
+      lensName,
+      dataId,
+      overrides
+    );
+  }
+
+  /**
+   * 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,
+      lensName,
+      data.id,
+      this.config.appName
+    );
+  }
+
+  /**
+   * 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)) {
+      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
+   */
+  async removeActiveHologram(sourceHolon, lensName, dataId, targetHolon) {
+    return federation.removeActiveHologram(
+      this.client,
+      this.config.appName,
+      sourceHolon,
+      lensName,
+      dataId,
+      targetHolon
+    );
+  }
+
+  /**
+   * 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,
+      this.config.appName,
+      holonId,
+      lensName,
+      dataId,
+      options
+    );
+  }
+
+  /**
+   * 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;
+    return federation.propagateData(
+      this.client,
+      this.config.appName,
+      data,
+      sourceHolon,
+      targetHolon,
+      lensName,
+      mode
+    );
+  }
+
+  /**
+   * 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);
+  }
+
+  /**
+   * 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,
+      this.config.appName,
+      holonId,
+      lensName,
+      options
+    );
+  }
+
+  /**
+   * 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,
+      this.config.appName,
+      holonId,
+      lensName,
+      dataIds,
+      options
+    );
+  }
+
+  /**
+   * 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++;
+        }
+      }
+    }
+
+    return result;
+  }
+
+  async getFederation(holonId) {
+    if (!holonId) {
+      throw new Error('getFederation: Missing holon ID');
+    }
+    const data = await this.getGlobal('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 = {};
+    }
+
+    // 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);
+    }
+
+    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) || {
+      id: sourceHolon,
+      name: sourceHolon,
+      federated: [],
+      inbound: [],
+      outbound: [],
+      lensConfig: {},
+      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 = {};
+    }
+
+    // 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' });
+      }
+    }
+
+    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;
+    }
+
+    // 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);
+      }
+    }
+
+    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;
+    }
+    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);
+  }
+
+  // === Subscription Operations ===
+  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 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 {
+          this.subscriptionRegistry.register(subscriptionId, subscription);
+        }
+      })
+      .catch(err => {
+        this._log('ERROR', 'Subscription setup failed', { path, error: err.message });
+      });
+
+    this._metrics.subscriptions++;
+
+    // Return synchronous subscription object
+    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);
+      },
+    };
+  }
+
+  // === Crypto Operations ===
+  async getPublicKey(privateKey) {
+    return crypto.getPublicKey(privateKey);
+  }
+
+  async sign(content, privateKey) {
+    return crypto.sign(content, privateKey);
+  }
+
+  async verify(content, signature, publicKey) {
+    return crypto.verify(content, signature, publicKey);
+  }
+
+  async issueCapability(permissions, scope, recipient, options) {
+    return crypto.issueCapability(permissions, scope, recipient, options);
+  }
+
+  async verifyCapability(token, requiredPermission, scope) {
+    return crypto.verifyCapability(token, requiredPermission, scope);
+  }
+
+  // === 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;
+    }
+
+    const transformed = social.transformNostrEvent(event);
+    return this.write(holonId, lensName, transformed);
+  }
+
+  async publishActivityPub(object, holonId, lensName = 'social') {
+    // Validate with throwing error
+    social.validateActivityPubObject(object, true);
+
+    const transformed = social.transformActivityPubObject(object);
+    return this.write(holonId, lensName, transformed);
+  }
+
+  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;
+  }
+
+  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);
+  }
+
+  // === Metrics ===
+  metrics() {
+    const baseMetrics = super.metrics();
+    return {
+      ...baseMetrics,
+      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,
+    };
+  }
+
+  // === Functional Aliases ===
+  // Common CRUD-style aliases for data operations
+
+  /**
+   * Alias for write() - stores data in a holon/lens
+   * @alias write
+   */
+  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)
+   */
+  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,
+        }
+      );
+    }
+
+    return token;
+  }
+
+  /**
+   * Hash a token for storage (don't store full token)
+   * @private
+   */
+  async _hashToken(token) {
+    const { sha256 } = await import('@noble/hashes/sha256');
+    const { bytesToHex } = await import('@noble/hashes/utils');
+    const encoder = new TextEncoder();
+    return bytesToHex(sha256(encoder.encode(token)));
+  }
+
+  // === Nostr Discovery Protocol (Optional) ===
+
+  /**
+   * Send a federation request via Nostr
+   * @param {string} targetPubKey - Target holosphere's public key
+   * @param {Object} options - Request options
+   * @param {Object} options.scope - Requested scope { holonId, lensName }
+   * @param {string[]} options.permissions - Requested permissions
+   * @param {string} options.message - Optional message
+   * @returns {Promise<Object>} Published event info
+   */
+  async sendFederationRequest(targetPubKey, options = {}) {
+    return discovery.sendFederationRequest(
+      this.client,
+      this.config.appName,
+      targetPubKey,
+      options
+    );
+  }
+
+  /**
+   * Subscribe to incoming federation requests
+   * @param {Function} callback - Called with each request
+   * @returns {Promise<Object>} Subscription with unsubscribe method
+   */
+  async subscribeFederationRequests(callback) {
+    return discovery.subscribeFederationRequests(this.client, callback);
+  }
+
+  /**
+   * Accept a federation request
+   * @param {Object} request - Request object from subscription
+   * @param {Object} options - Acceptance options
+   * @returns {Promise<Object>} Published acceptance event info
+   */
+  async acceptFederationRequest(request, options = {}) {
+    return discovery.acceptFederationRequest(
+      this.client,
+      this.config.appName,
+      request,
+      options
+    );
+  }
+
+  /**
+   * Decline a federation request
+   * @param {Object} request - Request object from subscription
+   * @param {string} reason - Optional decline reason
+   * @returns {Promise<Object>} Published decline event info
+   */
+  async declineFederationRequest(request, reason = '') {
+    return discovery.declineFederationRequest(
+      this.client,
+      this.config.appName,
+      request,
+      reason
+    );
+  }
+
+  /**
+   * Subscribe to federation acceptances (responses to our requests)
+   * @param {Function} callback - Called with each acceptance
+   * @returns {Promise<Object>} Subscription with unsubscribe method
+   */
+  async subscribeFederationAcceptances(callback) {
+    return discovery.subscribeFederationAcceptances(
+      this.client,
+      this.config.appName,
+      callback
+    );
+  }
+
+  /**
+   * Subscribe to federation declines
+   * @param {Function} callback - Called with each decline
+   * @returns {Promise<Object>} Subscription with unsubscribe method
+   */
+  async subscribeFederationDeclines(callback) {
+    return discovery.subscribeFederationDeclines(this.client, callback);
+  }
+
+  /**
+   * Get pending federation requests (requests we've sent that haven't been answered)
+   * @param {Object} options - Query options
+   * @returns {Promise<Object[]>} Array of pending requests
+   */
+  async getPendingFederationRequests(options = {}) {
+    return discovery.getPendingFederationRequests(this.client, options);
+  }
+}
+
+// Export error classes
+export class AuthorizationError extends Error {
+  constructor(message, requiredPermission = null) {
+    super(message);
+    this.name = 'AuthorizationError';
+    this.requiredPermission = requiredPermission;
+  }
+}
+
+export class HolosphereError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'HolosphereError';
+  }
+}
+
+// Re-export ValidationError from validator module
+export { ValidationError } from './schema/validator.js';
+
+// Export utilities
+export { nostrAsync };
+
+// Export hologram helper functions
+export {
+  isHologram,
+  isResolvedHologram,
+  getHologramSource,
+  updateHologramOverrides,
+  addActiveHologram,
+  removeActiveHologram,
+  refreshActiveHolograms,
+  deleteHologram,
+  propagateData,
+  createHologram,
+  resolveHologram,
+  cleanupCircularHolograms,
+  cleanupCircularHologramsByIds
+} from './federation/hologram.js';
+
+// Export federation registry functions
+export {
+  getFederationRegistry,
+  addFederatedPartner,
+  removeFederatedPartner,
+  getFederatedAuthors,
+  getCapabilityForAuthor,
+  storeInboundCapability,
+  storeOutboundCapability,
+  cleanupExpiredCapabilities
+} from './federation/registry.js';
+
+// Export Nostr discovery protocol functions
+export {
+  sendFederationRequest,
+  subscribeFederationRequests,
+  acceptFederationRequest,
+  declineFederationRequest,
+  subscribeFederationAcceptances,
+  subscribeFederationDeclines,
+  getPendingFederationRequests
+} from './federation/discovery.js';
+
+// Export scope matching utility
+export { matchScope } from './crypto/secp256k1.js';
+
+// Export AI modules for standalone use
+export {
+  LLMService,
+  SchemaExtractor,
+  JSONOps,
+  Embeddings,
+  Council,
+  TTS,
+  VOICES,
+  MODELS,
+  NLQuery,
+  Classifier,
+  SpatialAnalysis,
+  SmartAggregation,
+  FederationAdvisor,
+  RelationshipDiscovery,
+  TaskBreakdown,
+  H3AI
+};
+
+// Export AI factory function
+export { createAIServices } from './ai/index.js';
+
+// Default export for backward compatibility
+export default HoloSphere;