holosphere 2.0.0-alpha0 → 2.0.0-alpha10

package/src/hierarchical/upcast.js

@@ -1,26 +1,30 @@
 /**
- * Hierarchical Aggregation (Upcast Operations)
- * FR-025 to FR-027
+ * @fileoverview Hierarchical aggregation (upcast) operations for propagating data to parent holons.
+ * Implements upcast operations (FR-025 to FR-027) for H3-based geographic hierarchies.
+ * @module hierarchical/upcast
  */
 
 import { getParents, isValidH3 } from '../spatial/h3-operations.js';
 import { createHologram } from '../federation/hologram.js';
-import { write } from '../storage/nostr-wrapper.js';
+import { write } from '../storage/unified-storage.js';
 
 /**
- * Upcast data to parent holons in hierarchy
- * @param {Object} client - Nostr client instance
- * @param {string} appname - Application namespace
- * @param {string} holonId - Source holon ID (must be H3)
- * @param {string} lensName - Lens name
- * @param {string} dataId - Data ID
- * @param {Object} options - Upcast options
- * @param {number} options.maxLevel - Maximum levels to propagate (default: 3)
- * @param {string} options.operation - 'summarize', 'aggregate', or 'concatenate'
- * @returns {Promise<boolean>} Success indicator
+ * Upcast data to parent holons in the H3 hierarchy.
+ * Creates holograms in parent holons referencing the source data.
+ * @param {Object} hs - HoloSphere instance
+ * @param {string} holonId - Source holon ID (must be valid H3 index)
+ * @param {string} lensName - Lens name for the data
+ * @param {string} dataId - Data identifier to upcast
+ * @param {Object} [options={}] - Upcast configuration options
+ * @param {number} [options.maxLevel=3] - Maximum levels to propagate upward
+ * @param {string} [options.operation='concatenate'] - Aggregation operation: 'summarize', 'aggregate', or 'concatenate'
+ * @returns {Promise<boolean>} True if upcast succeeded
+ * @throws {Error} If holonId is not a valid H3 index
  */
-export async function upcast(client, appname, holonId, lensName, dataId, options = {}) {
-  const { maxLevel = 3, operation = 'summarize' } = options;
+export async function upcast(hs, holonId, lensName, dataId, options = {}) {
+  const { maxLevel = 3, operation = 'concatenate' } = options;
+  const client = hs.client;
+  const appname = hs.config.appName;
 
   // Validate H3 format
   if (!isValidH3(holonId)) {
@@ -45,8 +49,16 @@ export async function upcast(client, appname, holonId, lensName, dataId, options
 }
 
 /**
- * Propagate data to parent holon
+ * Propagate data to a parent holon by creating a hologram reference.
  * @private
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application name
+ * @param {string} sourceHolon - Source holon ID
+ * @param {string} parentHolon - Parent holon ID to propagate to
+ * @param {string} lensName - Lens name
+ * @param {string} dataId - Data identifier
+ * @param {string} operation - Aggregation operation type
+ * @returns {Promise<Object>} Write operation result
  */
 async function propagateToParent(
   client,
@@ -70,9 +82,10 @@ async function propagateToParent(
 }
 
 /**
- * Summarize operation (count aggregation)
- * @param {Object[]} items - Data items
- * @returns {Object} Summary object
+ * Summarize operation for count-based aggregation.
+ * Returns a summary object with the count of items.
+ * @param {Object[]} items - Array of data items to summarize
+ * @returns {Object} Summary object with operation type, count, and summary flag
  */
 export function summarize(items) {
   return {
@@ -83,9 +96,10 @@ export function summarize(items) {
 }
 
 /**
- * Aggregate operation (merge objects)
- * @param {Object[]} items - Data items
- * @returns {Object} Aggregated object
+ * Aggregate operation for merging objects.
+ * Combines all items into a single object using Object.assign.
+ * @param {Object[]} items - Array of objects to merge
+ * @returns {Object} Aggregated object with all properties merged
  */
 export function aggregate(items) {
   const result = { operation: 'aggregate' };
@@ -98,9 +112,10 @@ export function aggregate(items) {
 }
 
 /**
- * Concatenate operation (array merge)
- * @param {Array[]} items - Array items
- * @returns {Array} Concatenated array
+ * Concatenate operation for flattening nested arrays.
+ * Flattens all input arrays into a single array.
+ * @param {Array[]} items - Array of arrays to concatenate
+ * @returns {Object} Object with operation type and flattened items array
  */
 export function concatenate(items) {
   return {