holosphere 2.0.0-alpha10 → 2.0.0-alpha12

package/src/federation/request-card.js

@@ -0,0 +1,373 @@
+/**
+ * @fileoverview Federation Request Card Configuration
+ *
+ * Provides a card-based configuration system for federation requests.
+ * After inputting a public key, displays a card with all available lenses
+ * that can be configured for the federation request.
+ *
+ * @module federation/request-card
+ */
+
+import { issueCapabilitiesForLenses } from './capabilities.js';
+
+/**
+ * @typedef {Object} LensConfig
+ * @property {string} name - Lens name
+ * @property {boolean} enabled - Whether lens is enabled for federation
+ * @property {string} direction - 'inbound', 'outbound', or 'bidirectional'
+ * @property {string[]} permissions - Permissions to grant ('read', 'write')
+ */
+
+/**
+ * @typedef {Object} FederationCardConfig
+ * @property {string} partnerPubKey - Partner's public key
+ * @property {string} partnerName - Partner's display name (optional)
+ * @property {string} holonId - Local holon ID
+ * @property {string} holonName - Local holon display name
+ * @property {LensConfig[]} lenses - Lens configurations
+ * @property {string} message - Optional message to partner
+ * @property {number} createdAt - Card creation timestamp
+ * @property {string} status - 'pending', 'sent', 'accepted', 'rejected', 'dismissed'
+ */
+
+/**
+ * @typedef {Object} CardDisplayOptions
+ * @property {number} initialLensCount - Number of lenses to show initially (default: 3)
+ * @property {boolean} expanded - Whether card is expanded to show all lenses
+ * @property {boolean} showPermissions - Whether to show permission toggles
+ */
+
+// Default number of lenses to show before "Show more" button
+const DEFAULT_INITIAL_LENS_COUNT = 3;
+
+/**
+ * Create a federation request card configuration
+ * @param {Object} params - Card parameters
+ * @param {string} params.partnerPubKey - Partner's public key
+ * @param {string} params.partnerName - Partner's display name
+ * @param {string} params.holonId - Local holon ID
+ * @param {string} params.holonName - Local holon display name
+ * @param {string[]} params.availableLenses - All available lens names
+ * @param {Object} params.defaultConfig - Default lens configuration
+ * @returns {FederationCardConfig} Card configuration
+ */
+export function createFederationCard({
+  partnerPubKey,
+  partnerName = null,
+  holonId,
+  holonName,
+  availableLenses = [],
+  defaultConfig = {},
+}) {
+  const {
+    defaultDirection = 'bidirectional',
+    defaultPermissions = ['read'],
+    enabledByDefault = true,
+  } = defaultConfig;
+
+  // Create lens configurations for all available lenses
+  const lenses = availableLenses.map(name => ({
+    name,
+    enabled: enabledByDefault,
+    direction: defaultDirection,
+    permissions: [...defaultPermissions],
+  }));
+
+  return {
+    id: `fedcard_${partnerPubKey.substring(0, 8)}_${Date.now()}`,
+    partnerPubKey,
+    partnerName,
+    holonId,
+    holonName,
+    lenses,
+    message: '',
+    createdAt: Date.now(),
+    status: 'pending',
+    expanded: false,
+  };
+}
+
+/**
+ * Update a lens configuration in a card
+ * @param {FederationCardConfig} card - Card configuration
+ * @param {string} lensName - Lens name to update
+ * @param {Partial<LensConfig>} updates - Updates to apply
+ * @returns {FederationCardConfig} Updated card
+ */
+export function updateLensConfig(card, lensName, updates) {
+  const lensIndex = card.lenses.findIndex(l => l.name === lensName);
+  if (lensIndex === -1) return card;
+
+  const updatedLenses = [...card.lenses];
+  updatedLenses[lensIndex] = {
+    ...updatedLenses[lensIndex],
+    ...updates,
+  };
+
+  return {
+    ...card,
+    lenses: updatedLenses,
+  };
+}
+
+/**
+ * Toggle a lens enabled/disabled state
+ * @param {FederationCardConfig} card - Card configuration
+ * @param {string} lensName - Lens name to toggle
+ * @returns {FederationCardConfig} Updated card
+ */
+export function toggleLens(card, lensName) {
+  const lens = card.lenses.find(l => l.name === lensName);
+  if (!lens) return card;
+
+  return updateLensConfig(card, lensName, { enabled: !lens.enabled });
+}
+
+/**
+ * Enable all lenses in a card
+ * @param {FederationCardConfig} card - Card configuration
+ * @returns {FederationCardConfig} Updated card
+ */
+export function enableAllLenses(card) {
+  return {
+    ...card,
+    lenses: card.lenses.map(l => ({ ...l, enabled: true })),
+  };
+}
+
+/**
+ * Disable all lenses in a card
+ * @param {FederationCardConfig} card - Card configuration
+ * @returns {FederationCardConfig} Updated card
+ */
+export function disableAllLenses(card) {
+  return {
+    ...card,
+    lenses: card.lenses.map(l => ({ ...l, enabled: false })),
+  };
+}
+
+/**
+ * Toggle card expansion to show all lenses
+ * @param {FederationCardConfig} card - Card configuration
+ * @returns {FederationCardConfig} Updated card
+ */
+export function toggleCardExpansion(card) {
+  return {
+    ...card,
+    expanded: !card.expanded,
+  };
+}
+
+/**
+ * Get lenses to display based on expansion state
+ * @param {FederationCardConfig} card - Card configuration
+ * @param {number} initialCount - Number of lenses to show when collapsed
+ * @returns {Object} { visibleLenses, hiddenCount, isExpanded }
+ */
+export function getVisibleLenses(card, initialCount = DEFAULT_INITIAL_LENS_COUNT) {
+  const allLenses = card.lenses;
+  const isExpanded = card.expanded;
+
+  if (isExpanded || allLenses.length <= initialCount) {
+    return {
+      visibleLenses: allLenses,
+      hiddenCount: 0,
+      isExpanded: true,
+    };
+  }
+
+  return {
+    visibleLenses: allLenses.slice(0, initialCount),
+    hiddenCount: allLenses.length - initialCount,
+    isExpanded: false,
+  };
+}
+
+/**
+ * Get enabled lenses from a card
+ * @param {FederationCardConfig} card - Card configuration
+ * @returns {LensConfig[]} Enabled lenses
+ */
+export function getEnabledLenses(card) {
+  return card.lenses.filter(l => l.enabled);
+}
+
+/**
+ * Get lens configuration for handshake (inbound/outbound arrays)
+ * @param {FederationCardConfig} card - Card configuration
+ * @returns {Object} { inbound: string[], outbound: string[] }
+ */
+export function getLensConfigForHandshake(card) {
+  const inbound = [];
+  const outbound = [];
+
+  for (const lens of card.lenses) {
+    if (!lens.enabled) continue;
+
+    if (lens.direction === 'inbound' || lens.direction === 'bidirectional') {
+      inbound.push(lens.name);
+    }
+    if (lens.direction === 'outbound' || lens.direction === 'bidirectional') {
+      outbound.push(lens.name);
+    }
+  }
+
+  return { inbound, outbound };
+}
+
+/**
+ * Update card status
+ * @param {FederationCardConfig} card - Card configuration
+ * @param {string} status - New status
+ * @returns {FederationCardConfig} Updated card
+ */
+export function updateCardStatus(card, status) {
+  return {
+    ...card,
+    status,
+    updatedAt: Date.now(),
+  };
+}
+
+/**
+ * Dismiss a card (mark as dismissed so it doesn't reappear)
+ * @param {FederationCardConfig} card - Card configuration
+ * @returns {FederationCardConfig} Updated card with dismissed status
+ */
+export function dismissCard(card) {
+  return updateCardStatus(card, 'dismissed');
+}
+
+/**
+ * Check if a card should be displayed
+ * @param {FederationCardConfig} card - Card configuration
+ * @returns {boolean} True if card should be displayed
+ */
+export function shouldDisplayCard(card) {
+  return card.status !== 'dismissed' && card.status !== 'rejected';
+}
+
+/**
+ * Convert card configuration to handshake request params
+ * @param {FederationCardConfig} card - Card configuration
+ * @returns {Object} Params for initiateFederationHandshake
+ */
+export function cardToHandshakeParams(card) {
+  const lensConfig = getLensConfigForHandshake(card);
+
+  return {
+    partnerPubKey: card.partnerPubKey,
+    holonId: card.holonId,
+    holonName: card.holonName,
+    lensConfig,
+    message: card.message,
+  };
+}
+
+/**
+ * Generate capabilities for a card's outbound lenses
+ * @param {Object} client - NostrClient instance
+ * @param {FederationCardConfig} card - Card configuration
+ * @returns {Promise<Object[]>} Array of capability info objects
+ */
+export async function generateCapabilitiesForCard(client, card) {
+  const { outbound } = getLensConfigForHandshake(card);
+
+  if (outbound.length === 0) {
+    return [];
+  }
+
+  return issueCapabilitiesForLenses(
+    client,
+    card.holonId,
+    outbound,
+    card.partnerPubKey,
+    { permissions: ['read'] }
+  );
+}
+
+/**
+ * Render card as a simple text representation (for CLI/logs)
+ * @param {FederationCardConfig} card - Card configuration
+ * @param {CardDisplayOptions} options - Display options
+ * @returns {string} Text representation
+ */
+export function renderCardAsText(card, options = {}) {
+  const { initialLensCount = DEFAULT_INITIAL_LENS_COUNT } = options;
+  const { visibleLenses, hiddenCount, isExpanded } = getVisibleLenses(card, initialLensCount);
+  const { inbound, outbound } = getLensConfigForHandshake(card);
+
+  const lines = [
+    `┌─────────────────────────────────────────────────────┐`,
+    `│ Federation Request                                  │`,
+    `├─────────────────────────────────────────────────────┤`,
+    `│ Partner: ${(card.partnerName || card.partnerPubKey.substring(0, 16) + '...').padEnd(40)}│`,
+    `│ Status:  ${card.status.padEnd(40)}│`,
+    `├─────────────────────────────────────────────────────┤`,
+    `│ Lenses:                                             │`,
+  ];
+
+  for (const lens of visibleLenses) {
+    const status = lens.enabled ? '✓' : '○';
+    const dir = lens.direction === 'bidirectional' ? '↔' :
+                lens.direction === 'inbound' ? '←' : '→';
+    lines.push(`│   ${status} ${lens.name.padEnd(20)} ${dir.padEnd(22)}│`);
+  }
+
+  if (hiddenCount > 0) {
+    lines.push(`│   ... and ${hiddenCount} more lenses (click to expand)    │`);
+  }
+
+  lines.push(`├─────────────────────────────────────────────────────┤`);
+  lines.push(`│ Sharing: ${outbound.length} lenses  |  Receiving: ${inbound.length} lenses`.padEnd(52) + `│`);
+  lines.push(`└─────────────────────────────────────────────────────┘`);
+
+  return lines.join('\n');
+}
+
+/**
+ * Serialize card for storage
+ * @param {FederationCardConfig} card - Card configuration
+ * @returns {Object} Serialized card
+ */
+export function serializeCard(card) {
+  return {
+    ...card,
+    serializedAt: Date.now(),
+  };
+}
+
+/**
+ * Deserialize card from storage
+ * @param {Object} data - Serialized card data
+ * @returns {FederationCardConfig} Card configuration
+ */
+export function deserializeCard(data) {
+  return {
+    ...data,
+    expanded: data.expanded || false,
+    lenses: data.lenses || [],
+  };
+}
+
+export default {
+  createFederationCard,
+  updateLensConfig,
+  toggleLens,
+  enableAllLenses,
+  disableAllLenses,
+  toggleCardExpansion,
+  getVisibleLenses,
+  getEnabledLenses,
+  getLensConfigForHandshake,
+  updateCardStatus,
+  dismissCard,
+  shouldDisplayCard,
+  cardToHandshakeParams,
+  generateCapabilitiesForCard,
+  renderCardAsText,
+  serializeCard,
+  deserializeCard,
+  DEFAULT_INITIAL_LENS_COUNT,
+};

package/src/hierarchical/upcast.js

@@ -1,11 +1,14 @@
 /**
  * @fileoverview Hierarchical aggregation (upcast) operations for propagating data to parent holons.
  * Implements upcast operations (FR-025 to FR-027) for H3-based geographic hierarchies.
+ *
+ * UNIFIED MODEL: Uses createHologramWithCapability for consistent capability-based federation.
+ *
  * @module hierarchical/upcast
  */
 
 import { getParents, isValidH3 } from '../spatial/h3-operations.js';
-import { createHologram } from '../federation/hologram.js';
+import { createHologramWithCapability } from '../federation/hologram.js';
 import { write } from '../storage/unified-storage.js';
 
 /**
@@ -50,6 +53,7 @@ export async function upcast(hs, holonId, lensName, dataId, options = {}) {
 
 /**
  * Propagate data to a parent holon by creating a hologram reference.
+ * UNIFIED MODEL: Uses createHologramWithCapability for consistent capability-based federation.
  * @private
  * @param {Object} client - Nostr client instance
  * @param {string} appname - Application name
@@ -69,8 +73,20 @@ async function propagateToParent(
   dataId,
   operation
 ) {
-  // Create hologram reference
-  const hologram = createHologram(sourceHolon, parentHolon, lensName, dataId, appname);
+  // UNIFIED MODEL: Create hologram with capability
+  const hologram = await createHologramWithCapability(
+    client,
+    sourceHolon,
+    parentHolon,
+    lensName,
+    dataId,
+    appname,
+    {
+      // Use client's public key as source author (self-federation for upcast)
+      sourceAuthorPubKey: client.publicKey,
+      permissions: ['read'],
+    }
+  );
 
   // Add operation metadata
   hologram._meta.operation = operation;