holosphere 2.0.0-alpha11 → 2.0.0-alpha13

package/src/index.js

@@ -21,6 +21,11 @@ import * as schema from './schema/validator.js';
 import { ValidationError } from './schema/validator.js';
 import * as federation from './federation/hologram.js';
 import * as handshake from './federation/handshake.js';
+import * as holonRegistry from './federation/holon-registry.js';
+import * as registry from './federation/registry.js';
+import * as capabilities from './federation/capabilities.js';
+import * as requestCard from './federation/request-card.js';
+import * as cardStorage from './federation/card-storage.js';
 import * as crypto from './crypto/secp256k1.js';
 import * as nostrUtils from './crypto/nostr-utils.js';
 import * as social from './content/social-protocols.js';
@@ -254,6 +259,51 @@ class HoloSphereBase extends HoloSphereCore {
     return spatial.isValidH3(holonId);
   }
 
+  // === Holon Registry Operations ===
+
+  /**
+   * Register a holon with a public key.
+   * Maps a holonId (H3, chatId, concept) to a keypair owner.
+   *
+   * @param {string} holonId - Holon identifier to register
+   * @param {string} publicKey - 64-char hex public key (owner)
+   * @param {Object} [options={}] - Registration options
+   * @param {string} [options.alias] - Human-readable name
+   * @returns {Promise<boolean>} Success indicator
+   */
+  async registerHolon(holonId, publicKey, options = {}) {
+    return holonRegistry.registerHolon(this.client, this.config.appName, holonId, publicKey, options);
+  }
+
+  /**
+   * Look up a holon's registration.
+   *
+   * @param {string} holonId - Holon identifier
+   * @returns {Promise<Object|null>} Registry entry { holonId, publicKey, alias } or null
+   */
+  async lookupHolon(holonId) {
+    return holonRegistry.lookupHolon(this.client, this.config.appName, holonId);
+  }
+
+  /**
+   * Unregister a holon.
+   *
+   * @param {string} holonId - Holon identifier
+   * @returns {Promise<boolean>} Success indicator
+   */
+  async unregisterHolon(holonId) {
+    return holonRegistry.unregisterHolon(this.client, this.config.appName, holonId);
+  }
+
+  /**
+   * List all registered holons.
+   *
+   * @returns {Promise<Object[]>} Array of registry entries
+   */
+  async getRegisteredHolons() {
+    return holonRegistry.listRegisteredHolons(this.client, this.config.appName);
+  }
+
   // === Data Operations ===
 
   /**
@@ -271,6 +321,7 @@ class HoloSphereBase extends HoloSphereCore {
    * @param {boolean} [options.autoPropagate=true] - Whether to propagate to federated holons
    * @param {Object} [options.propagationOptions] - Options for propagation
    * @param {boolean} [options.blocking=false] - If true, wait for relay confirmation before returning
+   * @param {string} [options.signingKey] - Private key to sign with (hex format). If not provided, uses holosphere's default key.
    * @returns {Promise<boolean>} True if write succeeded (or queued for optimistic writes)
    * @throws {ValidationError} If holonId, lensName, or data is invalid
    * @throws {AuthorizationError} If capability token is invalid
@@ -377,7 +428,8 @@ class HoloSphereBase extends HoloSphereCore {
       }
 
       // Regular write to relay
-      await storage.write(this.client, path, data);
+      const writeOptions = options.signingKey ? { signingKey: options.signingKey } : {};
+      await storage.write(this.client, path, data, writeOptions);
 
       const endTime = Date.now();
       const duration = endTime - startTime;
@@ -486,6 +538,31 @@ class HoloSphereBase extends HoloSphereCore {
     return true;
   }
 
+  /**
+   * Resolve holonId to public key.
+   * If holonId is already a 64-char hex pubkey, returns it directly.
+   * Otherwise, looks up the holon registry.
+   *
+   * @private
+   * @param {string} holonId - Holon identifier
+   * @returns {Promise<string|null>} Public key or null if not found
+   */
+  async _resolveHolonToPubkey(holonId) {
+    return holonRegistry.resolveHolonToPubkey(this.client, this.config.appName, holonId);
+  }
+
+  /**
+   * Check if we have a stored capability for a given author and scope.
+   *
+   * @private
+   * @param {string} authorPubKey - Author's public key
+   * @param {Object} scope - Scope to check (holonId, lensName, dataId)
+   * @returns {Promise<Object|null>} Capability entry or null
+   */
+  async _getCapabilityForAuthor(authorPubKey, scope) {
+    return registry.getCapabilityForAuthor(this.client, this.config.appName, authorPubKey, scope);
+  }
+
   /**
    * Recursively resolves holograms (references) to their source data.
    * Handles circular reference detection and local overrides.
@@ -613,12 +690,98 @@ class HoloSphereBase extends HoloSphereCore {
       throw new ValidationError('ValidationError: lensName must be a non-empty string');
     }
 
+    // OPTIMIZATION: Check local caches first before any network/registry operations
+    // This ensures data we just wrote can be read back immediately (important for capability-based writes)
+    if (dataId) {
+      const earlyPath = storage.buildPath(this.config.appName, holonId, lensName, dataId);
+
+      // Check delete cache first - if deleted, return null immediately
+      if (this._deleteCache.has(earlyPath)) {
+        this._log('DEBUG', '🗑️ EARLY CACHE: Deleted item', { path: earlyPath });
+        return null;
+      }
+
+      // Check write cache - if this instance wrote data, return it immediately
+      const cached = this._writeCache.get(earlyPath);
+      if (cached) {
+        const cacheAge = Date.now() - cached.timestamp;
+        this._log('DEBUG', '⚡ EARLY CACHE HIT: Write cache', {
+          path: earlyPath,
+          cacheAge: `${cacheAge}ms`
+        });
+        // Still resolve holograms if needed
+        const { resolveHolograms = true } = options;
+        if (resolveHolograms && cached.data) {
+          return this._resolveHolograms(cached.data);
+        }
+        return cached.data;
+      }
+    }
+
+    // Resolve holonId to public key (if registered)
+    const targetPubkey = await this._resolveHolonToPubkey(holonId);
+
+    // Determine if reading another author's data
+    // If holonId can't be resolved, treat as own data (backwards compatible for H3 holons)
+    const isOtherAuthor = targetPubkey && targetPubkey !== this.client.publicKey;
+    let readOptions = {};
+
+    // Explicit capability token takes precedence
     const capToken = options.capabilityToken || options.capability;
     if (capToken) {
       const authorized = await this.verifyCapability(capToken, 'read', { holonId, lensName, dataId });
       if (!authorized) {
         throw new AuthorizationError('AuthorizationError: Invalid capability token for read operation', 'read');
       }
+      // Use target author for reading
+      if (isOtherAuthor) {
+        readOptions.authors = [targetPubkey];
+      }
+    } else if (isOtherAuthor) {
+      // Auto-check capability for other author's data
+      this._log('DEBUG', '🔍 Looking up capability for federated author', {
+        holonId,
+        lensName,
+        dataId: dataId || '*',
+        targetPubkey: targetPubkey?.slice(0, 12) + '...',
+        myPubkey: this.client?.publicKey?.slice(0, 12) + '...'
+      });
+      const capability = await this._getCapabilityForAuthor(targetPubkey, { holonId, lensName, dataId });
+      if (!capability) {
+        this._log('WARN', '❌ No capability found for federated author - returning empty', {
+          holonId,
+          lensName,
+          targetPubkey: targetPubkey?.slice(0, 12) + '...'
+        });
+        return dataId ? null : [];
+      }
+      this._log('DEBUG', '✅ Capability found for federated author', {
+        holonId,
+        lensName,
+        targetPubkey: targetPubkey?.slice(0, 12) + '...'
+      });
+      readOptions.authors = [targetPubkey];
+    }
+
+    // Include federated authors to see holograms written by federation partners
+    // This enables visibility of holograms created during federation
+    if (!isOtherAuthor) {
+      try {
+        const federatedAuthors = await registry.getFederatedAuthorsForScope(
+          this.client,
+          this.config.appName,
+          { holonId, lensName, dataId },
+          'read'
+        );
+        if (federatedAuthors.length > 0) {
+          const partnerPubkeys = federatedAuthors.map(f => f.pubKey);
+          // Include self + all federated partners
+          readOptions.authors = [this.client.publicKey, ...partnerPubkeys];
+          this._log('DEBUG', 'Including federated authors', { count: partnerPubkeys.length });
+        }
+      } catch (err) {
+        this._log('WARN', 'Failed to get federated authors', { error: err.message });
+      }
     }
 
     const startTime = Date.now();
@@ -637,6 +800,8 @@ class HoloSphereBase extends HoloSphereCore {
         result = null;
       } else {
         // Check write cache for optimistic reads
+        // Always check write cache first - if this instance wrote data, it should be able to read it back
+        // regardless of holon ownership (important for capability-based writes)
         const cached = this._writeCache.get(path);
         if (cached) {
           const cacheAge = Date.now() - cached.timestamp;
@@ -648,8 +813,8 @@ class HoloSphereBase extends HoloSphereCore {
           });
           result = cached.data;
         } else {
-          this._log('DEBUG', '📖 CACHE MISS: Reading from storage', { path });
-          result = await storage.read(this.client, path);
+          this._log('DEBUG', '📖 CACHE MISS: Reading from storage', { path, authors: readOptions.authors });
+          result = await storage.read(this.client, path, readOptions);
           this._log('DEBUG', '💾 STORAGE READ', {
             path,
             source: 'storage',
@@ -660,11 +825,11 @@ class HoloSphereBase extends HoloSphereCore {
       }
     } else {
       const path = storage.buildPath(this.config.appName, holonId, lensName);
-      this._log('DEBUG', 'readAll', { holonId, lensName, path });
+      this._log('DEBUG', 'readAll', { holonId, lensName, path, authors: readOptions.authors });
 
       // For readAll, merge cached writes with storage results and filter deleted
-      const storageResult = await storage.readAll(this.client, path);
-      result = this._mergeWithWriteCache(storageResult, path);
+      const storageResult = await storage.readAll(this.client, path, readOptions);
+      result = isOtherAuthor ? storageResult : this._mergeWithWriteCache(storageResult, path);
       this._log('DEBUG', 'readAll result', { count: Array.isArray(result) ? result.length : 0 });
     }
 
@@ -1179,56 +1344,11 @@ class HoloSphereBase extends HoloSphereCore {
   }
 
   // === Federation Operations ===
-
-  /**
-   * Sets up federation between two holons for a specific lens.
-   * Federation enables data sharing and synchronization between holons.
-   *
-   * @param {string} sourceHolon - Source holon H3 cell ID
-   * @param {string} targetHolon - Target holon H3 cell ID
-   * @param {string} lensName - Name of the lens to federate
-   * @param {Object} [options={}] - Federation options
-   * @param {string} [options.direction='outbound'] - Direction: 'inbound', 'outbound', or 'bidirectional'
-   * @param {string} [options.mode='reference'] - Mode: 'reference' (hologram) or 'copy'
-   * @param {Function} [options.filter] - Filter function to select which data to federate
-   * @returns {Promise<boolean>} True if federation was set up successfully
-   * @throws {Error} If trying to federate a holon with itself or invalid direction
-   */
-  async federate(sourceHolon, targetHolon, lensName, options = {}) {
-    const { direction = 'outbound', mode = 'reference', filter = null } = options;
-
-    // Validation
-    if (sourceHolon === targetHolon) {
-      throw new Error('Cannot federate a holon with itself');
-    }
-    if (!['inbound', 'outbound', 'bidirectional'].includes(direction)) {
-      throw new Error(`Invalid direction: ${direction}. Must be 'inbound', 'outbound', or 'bidirectional'`);
-    }
-
-    // Store federation config
-    await federation.setupFederation(
-      this.client,
-      this.config.appName,
-      sourceHolon,
-      targetHolon,
-      lensName,
-      options
-    );
-
-    // Actually propagate existing data based on direction
-    if (direction === 'outbound' || direction === 'bidirectional') {
-      await this._propagateExistingData(sourceHolon, targetHolon, lensName, { mode, filter });
-    }
-    if (direction === 'inbound' || direction === 'bidirectional') {
-      await this._propagateExistingData(targetHolon, sourceHolon, lensName, { mode, filter });
-    }
-
-    this._metrics.federations = (this._metrics.federations || 0) + 1;
-    return true;
-  }
+  // Note: federate() and unfederate() methods are provided by withFederationMethods mixin
 
   /**
    * Propagates existing data from one holon to another.
+   * UNIFIED MODEL: Passes sourceAuthorPubKey for capability-based federation.
    *
    * @private
    * @param {string} fromHolon - Source holon H3 cell ID
@@ -1237,10 +1357,11 @@ class HoloSphereBase extends HoloSphereCore {
    * @param {Object} [options={}] - Propagation options
    * @param {string} [options.mode='reference'] - Mode: 'reference' or 'copy'
    * @param {Function} [options.filter] - Filter function to select data
+   * @param {string} [options.sourceAuthorPubKey] - Source author's public key (defaults to client.publicKey)
    * @returns {Promise<void>}
    */
   async _propagateExistingData(fromHolon, toHolon, lensName, options = {}) {
-    const { mode = 'reference', filter = null } = options;
+    const { mode = 'reference', filter = null, sourceAuthorPubKey } = options;
     const existingData = await this.read(fromHolon, lensName, null, { resolveHolograms: false });
     if (!existingData) return;
 
@@ -1250,6 +1371,7 @@ class HoloSphereBase extends HoloSphereCore {
       if (item.hologram === true) continue;
       // Apply filter if provided
       if (filter && !filter(item)) continue;
+      // UNIFIED MODEL: Pass sourceAuthorPubKey for capability-based federation
       await federation.propagateData(
         this.client,
         this.config.appName,
@@ -1257,7 +1379,10 @@ class HoloSphereBase extends HoloSphereCore {
         fromHolon,
         toHolon,
         lensName,
-        mode
+        mode,
+        {
+          sourceAuthorPubKey: sourceAuthorPubKey || this.client.publicKey,
+        }
       );
     }
   }
@@ -1282,25 +1407,6 @@ class HoloSphereBase extends HoloSphereCore {
     return this._resolveHolograms(data);
   }
 
-  /**
-   * Removes federation between two holons for a specific lens.
-   *
-   * @param {string} sourceHolon - Source holon H3 cell ID
-   * @param {string} targetHolon - Target holon H3 cell ID
-   * @param {string} lensName - Name of the lens
-   * @returns {Promise<boolean>} Always returns true (idempotent operation)
-   */
-  async unfederate(sourceHolon, targetHolon, lensName) {
-    // Remove federation config for this relationship - idempotent
-    const configPath = storage.buildPath(this.config.appName, sourceHolon, lensName, '_federation');
-    try {
-      await storage.deleteData(this.client, configPath);
-    } catch (e) {
-      // Ignore errors - already unfederated or doesn't exist
-    }
-    return true;
-  }
-
   /**
    * Updates local override values on a hologram.
    *
@@ -1412,6 +1518,7 @@ class HoloSphereBase extends HoloSphereCore {
   async propagateData(data, sourceHolon, targetHolon, lensName, options = {}) {
     // Extract mode from options, default to 'reference' for hologram creation
     const mode = options.mode || 'reference';
+    // UNIFIED MODEL: Pass sourceAuthorPubKey for capability-based federation
     return federation.propagateData(
       this.client,
       this.config.appName,
@@ -1419,7 +1526,11 @@ class HoloSphereBase extends HoloSphereCore {
       sourceHolon,
       targetHolon,
       lensName,
-      mode
+      mode,
+      {
+        sourceAuthorPubKey: options.sourceAuthorPubKey || this.client.publicKey,
+        capability: options.capability,
+      }
     );
   }
 
@@ -2267,10 +2378,33 @@ export {
 // Re-export types and utilities
 export { spatial, storage, schema, federation, handshake, crypto, nostrUtils, social, subscriptions, hierarchical };
 
+// Re-export federation submodules
+export { capabilities, requestCard, cardStorage, holonRegistry, registry };
+
 // Re-export specific utilities used in tests
 export { matchScope } from './crypto/secp256k1.js';
 export { createHologram } from './federation/hologram.js';
 
+// Re-export federation card functions
+export {
+  createFederationCard,
+  getVisibleLenses,
+  getLensConfigForHandshake,
+  toggleLens,
+  toggleCardExpansion,
+  dismissCard,
+} from './federation/request-card.js';
+
+// Re-export card storage functions
+export {
+  saveCard,
+  getCard,
+  getDisplayableCards,
+  dismissRequest,
+  markResponseProcessed,
+  isResponseProcessed,
+} from './federation/card-storage.js';
+
 // Export AI factory function
 export { createAIServices } from './ai/index.js';