holosphere 2.0.0-alpha10 → 2.0.0-alpha12

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 ===
 
   /**
@@ -276,10 +326,14 @@ class HoloSphereBase extends HoloSphereCore {
    * @throws {AuthorizationError} If capability token is invalid
    */
   async write(holonId, lensName, data, options = {}) {
-    if (!holonId || typeof holonId !== 'string') {
+    // Auto-convert to strings for convenience
+    if (holonId != null) holonId = String(holonId);
+    if (lensName != null) lensName = String(lensName);
+
+    if (!holonId) {
       throw new ValidationError('ValidationError: holonId must be a non-empty string');
     }
-    if (!lensName || typeof lensName !== 'string') {
+    if (!lensName) {
       throw new ValidationError('ValidationError: lensName must be a non-empty string');
     }
     if (!data || typeof data !== 'object') {
@@ -296,6 +350,9 @@ class HoloSphereBase extends HoloSphereCore {
 
     if (!data.id) {
       data.id = `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    } else {
+      // Auto-convert data.id to string for convenience
+      data.id = String(data.id);
     }
 
     // Add metadata
@@ -318,7 +375,7 @@ class HoloSphereBase extends HoloSphereCore {
     // OPTIMISTIC UPDATE: Store in write cache and clear from delete cache
     this._writeCache.set(path, { data: { ...data }, timestamp: Date.now() });
     this._deleteCache.delete(path);
-    this._log('INFO', '📝 CACHE WRITE', {
+    this._log('DEBUG', '📝 CACHE WRITE', {
       path,
       dataId: data.id,
       cacheSize: this._writeCache.size,
@@ -353,7 +410,7 @@ class HoloSphereBase extends HoloSphereCore {
    */
   async _syncWriteToRelay(holonId, lensName, data, path, options) {
     const startTime = Date.now();
-    this._log('INFO', '🔄 RELAY SYNC START', {
+    this._log('DEBUG', '🔄 RELAY SYNC START', {
       path,
       dataId: data.id,
       relays: this.client?.relays?.map(r => r.url) || ['local-only']
@@ -378,7 +435,7 @@ class HoloSphereBase extends HoloSphereCore {
       if (!this._metrics.totalWriteTime) this._metrics.totalWriteTime = 0;
       this._metrics.totalWriteTime += duration;
 
-      this._log('INFO', '✅ RELAY SYNC SUCCESS', {
+      this._log('DEBUG', '✅ RELAY SYNC SUCCESS', {
         path,
         dataId: data.id,
         duration: `${duration}ms`,
@@ -479,6 +536,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.
@@ -594,19 +676,66 @@ class HoloSphereBase extends HoloSphereCore {
    * @throws {AuthorizationError} If capability token is invalid
    */
   async read(holonId, lensName, dataId = null, options = {}) {
-    if (!holonId || typeof holonId !== 'string') {
+    // Auto-convert to strings for convenience
+    if (holonId != null) holonId = String(holonId);
+    if (lensName != null) lensName = String(lensName);
+    if (dataId != null) dataId = String(dataId);
+
+    if (!holonId) {
       throw new ValidationError('ValidationError: holonId must be a non-empty string');
     }
-    if (!lensName || typeof lensName !== 'string') {
+    if (!lensName) {
       throw new ValidationError('ValidationError: lensName must be a non-empty string');
     }
 
+    // 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
+      const capability = await this._getCapabilityForAuthor(targetPubkey, { holonId, lensName, dataId });
+      if (!capability) {
+        this._log('DEBUG', 'No capability for author', { holonId, targetPubkey });
+        return dataId ? null : [];
+      }
+      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();
@@ -617,18 +746,18 @@ class HoloSphereBase extends HoloSphereCore {
 
       // Check delete cache first - if deleted, return null immediately
       if (this._deleteCache.has(path)) {
-        this._log('INFO', '🗑️ CACHE READ: Deleted item', {
+        this._log('DEBUG', '🗑️ CACHE READ: Deleted item', {
           path,
           source: 'delete-cache',
           deleteCacheSize: this._deleteCache.size
         });
         result = null;
       } else {
-        // Check write cache for optimistic reads
-        const cached = this._writeCache.get(path);
+        // Check write cache for optimistic reads (only for own data)
+        const cached = !isOtherAuthor ? this._writeCache.get(path) : null;
         if (cached) {
           const cacheAge = Date.now() - cached.timestamp;
-          this._log('INFO', '⚡ CACHE HIT: Write cache', {
+          this._log('DEBUG', '⚡ CACHE HIT: Write cache', {
             path,
             source: 'write-cache',
             cacheAge: `${cacheAge}ms`,
@@ -636,9 +765,9 @@ 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('INFO', '💾 STORAGE READ', {
+          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',
             found: !!result,
@@ -648,11 +777,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 });
     }
 
@@ -782,7 +911,7 @@ class HoloSphereBase extends HoloSphereCore {
     // OPTIMISTIC UPDATE: Store in write cache and clear from delete cache
     this._writeCache.set(path, { data: { ...mergedData }, timestamp: Date.now() });
     this._deleteCache.delete(path);
-    this._log('INFO', '✏️ CACHE UPDATE', {
+    this._log('DEBUG', '✏️ CACHE UPDATE', {
       path,
       dataId,
       updatedFields: Object.keys(updates),
@@ -808,7 +937,7 @@ class HoloSphereBase extends HoloSphereCore {
    */
   async _syncUpdateToRelay(holonId, lensName, dataId, mergedData, existingData, path) {
     const startTime = Date.now();
-    this._log('INFO', '🔄 UPDATE SYNC START', {
+    this._log('DEBUG', '🔄 UPDATE SYNC START', {
       path,
       dataId,
       relays: this.client?.relays?.map(r => r.url) || ['local-only']
@@ -822,7 +951,7 @@ class HoloSphereBase extends HoloSphereCore {
       if (!this._metrics.totalWriteTime) this._metrics.totalWriteTime = 0;
       this._metrics.totalWriteTime += duration;
 
-      this._log('INFO', '✅ UPDATE SYNC SUCCESS', {
+      this._log('DEBUG', '✅ UPDATE SYNC SUCCESS', {
         path,
         dataId,
         duration: `${duration}ms`,
@@ -865,13 +994,18 @@ class HoloSphereBase extends HoloSphereCore {
    * @throws {AuthorizationError} If not owner and no valid capability token
    */
   async delete(holonId, lensName, dataId, options = {}) {
-    if (!holonId || typeof holonId !== 'string') {
+    // Auto-convert to strings for convenience
+    if (holonId != null) holonId = String(holonId);
+    if (lensName != null) lensName = String(lensName);
+    if (dataId != null) dataId = String(dataId);
+
+    if (!holonId) {
       throw new ValidationError('ValidationError: holonId must be a non-empty string');
     }
-    if (!lensName || typeof lensName !== 'string') {
+    if (!lensName) {
       throw new ValidationError('ValidationError: lensName must be a non-empty string');
     }
-    if (!dataId || typeof dataId !== 'string') {
+    if (!dataId) {
       throw new ValidationError('ValidationError: dataId must be a non-empty string');
     }
 
@@ -920,7 +1054,7 @@ class HoloSphereBase extends HoloSphereCore {
     // OPTIMISTIC DELETE: Remove from write cache and add to delete cache
     this._writeCache.delete(path);
     this._deleteCache.add(path);
-    this._log('INFO', '🗑️ CACHE DELETE', {
+    this._log('DEBUG', '🗑️ CACHE DELETE', {
       path,
       dataId,
       deleteCacheSize: this._deleteCache.size,
@@ -935,14 +1069,14 @@ class HoloSphereBase extends HoloSphereCore {
 
     // Delete from storage (background unless blocking)
     const startTime = Date.now();
-    this._log('INFO', '🔄 DELETE SYNC START', { path, dataId });
+    this._log('DEBUG', '🔄 DELETE SYNC START', { path, dataId });
 
     const deletePromise = storage.deleteData(this.client, path).then(() => {
       const duration = Date.now() - startTime;
       this._metrics.deletes++;
       // Clear from delete cache after successful sync
       this._deleteCache.delete(path);
-      this._log('INFO', '✅ DELETE SYNC SUCCESS', {
+      this._log('DEBUG', '✅ DELETE SYNC SUCCESS', {
         path,
         dataId,
         duration: `${duration}ms`,
@@ -983,6 +1117,10 @@ class HoloSphereBase extends HoloSphereCore {
    * @returns {Promise<boolean>} True if write succeeded
    */
   async writeGlobal(table, data) {
+    // Auto-convert to strings for convenience
+    if (table != null) table = String(table);
+    if (data?.id != null) data.id = String(data.id);
+
     return globalTables.writeGlobal(this.client, this.config.appName, table, data);
   }
 
@@ -994,6 +1132,10 @@ class HoloSphereBase extends HoloSphereCore {
    * @returns {Promise<Object|Array|null>} Data object, array of objects, or null
    */
   async readGlobal(table, key = null) {
+    // Auto-convert to strings for convenience
+    if (table != null) table = String(table);
+    if (key != null) key = String(key);
+
     return globalTables.readGlobal(this.client, this.config.appName, table, key);
   }
 
@@ -1006,6 +1148,10 @@ class HoloSphereBase extends HoloSphereCore {
    * @returns {Promise<boolean>} True if update succeeded
    */
   async updateGlobal(table, key, updates) {
+    // Auto-convert to strings for convenience
+    if (table != null) table = String(table);
+    if (key != null) key = String(key);
+
     return globalTables.updateGlobal(this.client, this.config.appName, table, key, updates);
   }
 
@@ -1017,6 +1163,10 @@ class HoloSphereBase extends HoloSphereCore {
    * @returns {Promise<boolean>} True if deletion succeeded
    */
   async deleteGlobal(table, key) {
+    // Auto-convert to strings for convenience
+    if (table != null) table = String(table);
+    if (key != null) key = String(key);
+
     return globalTables.deleteGlobal(this.client, this.config.appName, table, key);
   }
 
@@ -1027,6 +1177,9 @@ class HoloSphereBase extends HoloSphereCore {
    * @returns {Promise<Array>} Array of all data objects in the table
    */
   async getAllGlobal(table) {
+    // Auto-convert to strings for convenience
+    if (table != null) table = String(table);
+
     return globalTables.getAllGlobal(this.client, this.config.appName, table);
   }
 
@@ -1037,6 +1190,9 @@ class HoloSphereBase extends HoloSphereCore {
    * @returns {Promise<boolean>} True if deletion succeeded
    */
   async deleteAllGlobal(table) {
+    // Auto-convert to strings for convenience
+    if (table != null) table = String(table);
+
     return globalTables.deleteAllGlobal(this.client, this.config.appName, table);
   }
 
@@ -1061,6 +1217,10 @@ class HoloSphereBase extends HoloSphereCore {
    * @returns {Promise<boolean>} True if deletion succeeded
    */
   async deleteAll(holonId, lensName) {
+    // Auto-convert to strings for convenience
+    if (holonId != null) holonId = String(holonId);
+    if (lensName != null) lensName = String(lensName);
+
     const path = storage.buildPath(this.config.appName, holonId, lensName);
     return storage.deleteAll(this.client, path);
   }
@@ -1136,56 +1296,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
@@ -1194,10 +1309,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;
 
@@ -1207,6 +1323,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,
@@ -1214,7 +1331,10 @@ class HoloSphereBase extends HoloSphereCore {
         fromHolon,
         toHolon,
         lensName,
-        mode
+        mode,
+        {
+          sourceAuthorPubKey: sourceAuthorPubKey || this.client.publicKey,
+        }
       );
     }
   }
@@ -1239,25 +1359,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.
    *
@@ -1369,6 +1470,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,
@@ -1376,7 +1478,11 @@ class HoloSphereBase extends HoloSphereCore {
       sourceHolon,
       targetHolon,
       lensName,
-      mode
+      mode,
+      {
+        sourceAuthorPubKey: options.sourceAuthorPubKey || this.client.publicKey,
+        capability: options.capability,
+      }
     );
   }
 
@@ -2224,10 +2330,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';