holosphere 1.1.20 → 2.0.0-alpha0

package/tests/unit/hierarchical.test.js

@@ -0,0 +1,399 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import HoloSphere from '../../src/index.js';
+
+describe('Unit: Hierarchical Module (T033.5)', () => {
+  let hs;
+  let testHolonId;
+
+  beforeEach(async () => {
+    hs = new HoloSphere({ relays: [], appName: 'test-hierarchical-unit' });
+    testHolonId = await hs.toHolon(37.7749, -122.4194, 10);
+  });
+
+  describe('Upcast operation with summarize mode', () => {
+    it('should upcast with summarize operation', async () => {
+      await hs.write(testHolonId, 'events', {
+        id: 'event-001',
+        name: 'Test Event',
+        attendees: 25
+      });
+
+      const success = await hs.upcast(testHolonId, 'events', 'event-001', {
+        operation: 'summarize'
+      });
+
+      expect(success).toBe(true);
+    });
+
+    it('should create count summary in parent holons', async () => {
+      await hs.write(testHolonId, 'items', {
+        id: 'item-001',
+        value: 'data'
+      });
+
+      await hs.upcast(testHolonId, 'items', 'item-001', {
+        operation: 'summarize',
+        maxLevel: 1
+      });
+
+      const parents = await hs.getParents(testHolonId);
+      if (parents.length > 0) {
+        const parentData = await hs.read(parents[0], 'items');
+        expect(Array.isArray(parentData)).toBe(true);
+      }
+    });
+
+    it('should increment count on multiple upcasts', async () => {
+      await hs.write(testHolonId, 'counts', { id: 'c1', value: 1 });
+      await hs.write(testHolonId, 'counts', { id: 'c2', value: 2 });
+
+      await hs.upcast(testHolonId, 'counts', 'c1', { operation: 'summarize' });
+      await hs.upcast(testHolonId, 'counts', 'c2', { operation: 'summarize' });
+
+      // Parent should have count of 2
+    });
+  });
+
+  describe('Upcast operation with aggregate mode', () => {
+    it('should upcast with aggregate operation', async () => {
+      await hs.write(testHolonId, 'stats', {
+        id: 'stat-001',
+        total: 100,
+        count: 5
+      });
+
+      const success = await hs.upcast(testHolonId, 'stats', 'stat-001', {
+        operation: 'aggregate'
+      });
+
+      expect(success).toBe(true);
+    });
+
+    it('should merge object fields in parent holons', async () => {
+      await hs.write(testHolonId, 'data', {
+        id: 'data-001',
+        values: { a: 1, b: 2 }
+      });
+
+      await hs.upcast(testHolonId, 'data', 'data-001', {
+        operation: 'aggregate',
+        maxLevel: 1
+      });
+
+      const parents = await hs.getParents(testHolonId);
+      if (parents.length > 0) {
+        const parentData = await hs.read(parents[0], 'data');
+        expect(Array.isArray(parentData)).toBe(true);
+      }
+    });
+
+    it('should combine multiple aggregates', async () => {
+      await hs.write(testHolonId, 'totals', {
+        id: 't1',
+        sum: 10,
+        count: 2
+      });
+
+      await hs.write(testHolonId, 'totals', {
+        id: 't2',
+        sum: 15,
+        count: 3
+      });
+
+      await hs.upcast(testHolonId, 'totals', 't1', { operation: 'aggregate' });
+      await hs.upcast(testHolonId, 'totals', 't2', { operation: 'aggregate' });
+
+      // Parent should have merged aggregates
+    });
+  });
+
+  describe('Upcast operation with concatenate mode', () => {
+    it('should upcast with concatenate operation (default)', async () => {
+      await hs.write(testHolonId, 'lists', {
+        id: 'list-001',
+        items: [1, 2, 3]
+      });
+
+      const success = await hs.upcast(testHolonId, 'lists', 'list-001', {
+        operation: 'concatenate'
+      });
+
+      expect(success).toBe(true);
+    });
+
+    it('should use concatenate as default operation', async () => {
+      await hs.write(testHolonId, 'arrays', {
+        id: 'array-001',
+        data: ['a', 'b', 'c']
+      });
+
+      const success = await hs.upcast(testHolonId, 'arrays', 'array-001');
+
+      expect(success).toBe(true);
+    });
+
+    it('should concatenate arrays in parent holons', async () => {
+      await hs.write(testHolonId, 'sequences', {
+        id: 'seq-001',
+        values: [1, 2]
+      });
+
+      await hs.upcast(testHolonId, 'sequences', 'seq-001', {
+        operation: 'concatenate',
+        maxLevel: 1
+      });
+
+      const parents = await hs.getParents(testHolonId);
+      if (parents.length > 0) {
+        const parentData = await hs.read(parents[0], 'sequences');
+        expect(Array.isArray(parentData)).toBe(true);
+      }
+    });
+
+    it('should handle multiple concatenations', async () => {
+      await hs.write(testHolonId, 'combined', {
+        id: 'c1',
+        items: ['x', 'y']
+      });
+
+      await hs.write(testHolonId, 'combined', {
+        id: 'c2',
+        items: ['z']
+      });
+
+      await hs.upcast(testHolonId, 'combined', 'c1', { operation: 'concatenate' });
+      await hs.upcast(testHolonId, 'combined', 'c2', { operation: 'concatenate' });
+
+      // Parent should have concatenated arrays
+    });
+  });
+
+  describe('MaxLevel limit enforcement (default: 3 levels)', () => {
+    it('should respect maxLevel limit', async () => {
+      await hs.write(testHolonId, 'limited', {
+        id: 'lim-001',
+        data: 'test'
+      });
+
+      const success = await hs.upcast(testHolonId, 'limited', 'lim-001', {
+        maxLevel: 2
+      });
+
+      expect(success).toBe(true);
+    });
+
+    it('should use default maxLevel of 3 when not specified', async () => {
+      await hs.write(testHolonId, 'default', {
+        id: 'def-001',
+        data: 'test'
+      });
+
+      const success = await hs.upcast(testHolonId, 'default', 'def-001');
+
+      expect(success).toBe(true);
+      // Should propagate up 3 levels by default
+    });
+
+    it('should stop at maxLevel', async () => {
+      await hs.write(testHolonId, 'stop', {
+        id: 'stop-001',
+        data: 'test'
+      });
+
+      await hs.upcast(testHolonId, 'stop', 'stop-001', { maxLevel: 1 });
+
+      const parents = await hs.getParents(testHolonId);
+
+      // Data should be in immediate parent
+      if (parents.length > 0) {
+        const parent1Data = await hs.read(parents[0], 'stop');
+        expect(Array.isArray(parent1Data)).toBe(true);
+      }
+
+      // Data should NOT be in grandparent (beyond maxLevel)
+      if (parents.length > 1) {
+        const parent2Data = await hs.read(parents[1], 'stop');
+        const hasUpcastData = parent2Data.some(d => d.id === 'stop-001');
+        expect(hasUpcastData).toBe(false);
+      }
+    });
+
+    it('should allow unlimited levels with maxLevel: Infinity', async () => {
+      await hs.write(testHolonId, 'unlimited', {
+        id: 'unl-001',
+        data: 'test'
+      });
+
+      const success = await hs.upcast(testHolonId, 'unlimited', 'unl-001', {
+        maxLevel: Infinity
+      });
+
+      expect(success).toBe(true);
+    });
+  });
+
+  describe('Parent hierarchy traversal', () => {
+    it('should traverse up parent hierarchy', async () => {
+      await hs.write(testHolonId, 'traverse', {
+        id: 'trav-001',
+        data: 'test'
+      });
+
+      const success = await hs.upcast(testHolonId, 'traverse', 'trav-001', {
+        maxLevel: 3
+      });
+
+      expect(success).toBe(true);
+
+      const parents = await hs.getParents(testHolonId);
+      expect(parents.length).toBeGreaterThan(0);
+    });
+
+    it('should write to each parent level', async () => {
+      await hs.write(testHolonId, 'levels', {
+        id: 'lev-001',
+        data: 'test'
+      });
+
+      await hs.upcast(testHolonId, 'levels', 'lev-001', { maxLevel: 2 });
+
+      const parents = await hs.getParents(testHolonId);
+
+      // Check each parent level has data
+      for (let i = 0; i < Math.min(parents.length, 2); i++) {
+        const parentData = await hs.read(parents[i], 'levels');
+        expect(Array.isArray(parentData)).toBe(true);
+      }
+    });
+
+    it('should use H3 parent function for traversal', async () => {
+      const parents = await hs.getParents(testHolonId);
+
+      expect(parents.length).toBeGreaterThan(0);
+
+      // Each parent should be a valid H3 ID
+      parents.forEach(parent => {
+        expect(hs.isValidH3(parent)).toBe(true);
+      });
+    });
+  });
+
+  describe('Error: noospheric holons (no spatial hierarchy)', () => {
+    it('should throw Error for noospheric holon upcast', async () => {
+      const noospheric = 'nostr://topic/test';
+
+      await hs.write(noospheric, 'content', {
+        id: 'post-001',
+        text: 'Test post'
+      });
+
+      await expect(
+        hs.upcast(noospheric, 'content', 'post-001')
+      ).rejects.toThrow(Error);
+    });
+
+    it('should throw Error for URI-based holons', async () => {
+      const uriHolon = 'concept://philosophy/ethics';
+
+      await hs.write(uriHolon, 'ideas', {
+        id: 'idea-001',
+        text: 'Test idea'
+      });
+
+      await expect(
+        hs.upcast(uriHolon, 'ideas', 'idea-001')
+      ).rejects.toThrow(Error);
+    });
+
+    it('should throw Error for URL-based holons', async () => {
+      const urlHolon = 'https://example.com/topic/test';
+
+      await hs.write(urlHolon, 'content', {
+        id: 'content-001',
+        data: 'test'
+      });
+
+      await expect(
+        hs.upcast(urlHolon, 'content', 'content-001')
+      ).rejects.toThrow(Error);
+    });
+
+    it('should work only with geographic (H3) holons', async () => {
+      const geographic = await hs.toHolon(37.7749, -122.4194, 10);
+
+      await hs.write(geographic, 'geo-data', {
+        id: 'geo-001',
+        value: 'test'
+      });
+
+      await expect(
+        hs.upcast(geographic, 'geo-data', 'geo-001')
+      ).resolves.toBe(true);
+    });
+  });
+
+  describe('Integration with spatial module', () => {
+    it('should use spatial module for parent resolution', async () => {
+      const parents = await hs.getParents(testHolonId);
+
+      expect(parents.length).toBeGreaterThan(0);
+      parents.forEach(parent => {
+        expect(hs.isValidH3(parent)).toBe(true);
+      });
+    });
+
+    it('should respect H3 hierarchy levels', async () => {
+      await hs.write(testHolonId, 'h3-test', {
+        id: 'h3-001',
+        data: 'test'
+      });
+
+      await hs.upcast(testHolonId, 'h3-test', 'h3-001', { maxLevel: 2 });
+
+      // Should follow H3 parent-child relationships
+      const parents = await hs.getParents(testHolonId);
+      expect(parents.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('Integration with storage module', () => {
+    it('should write holograms to parent holons', async () => {
+      await hs.write(testHolonId, 'hologram-test', {
+        id: 'holo-001',
+        data: 'test'
+      });
+
+      await hs.upcast(testHolonId, 'hologram-test', 'holo-001', {
+        maxLevel: 1
+      });
+
+      const parents = await hs.getParents(testHolonId);
+      if (parents.length > 0) {
+        const parentData = await hs.read(parents[0], 'hologram-test');
+        expect(Array.isArray(parentData)).toBe(true);
+      }
+    });
+
+    it('should create references not copies', async () => {
+      await hs.write(testHolonId, 'ref-test', {
+        id: 'ref-001',
+        value: 'original'
+      });
+
+      await hs.upcast(testHolonId, 'ref-test', 'ref-001', { maxLevel: 1 });
+
+      // Update original
+      await hs.update(testHolonId, 'ref-test', 'ref-001', { value: 'updated' });
+
+      // Parent should reflect update (reference, not copy)
+      const parents = await hs.getParents(testHolonId);
+      if (parents.length > 0) {
+        const parentData = await hs.getFederatedData(parents[0], 'ref-test');
+        const item = parentData.find(d => d.id === 'ref-001');
+        if (item) {
+          expect(item.value).toBe('updated');
+        }
+      }
+    });
+  });
+});

package/tests/unit/integration/scenario-01-geographic-storage.test.js

@@ -0,0 +1,74 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import HoloSphere from '../../../src/index.js';
+
+describe('Integration: Scenario 1 - Geographic Data Storage and Retrieval', () => {
+  let hs;
+
+  beforeEach(() => {
+    hs = new HoloSphere({ relays: [], appName: 'scenario-01' });
+  });
+
+  it('should complete full geographic storage workflow', async () => {
+    // Step 1: Convert coordinates to H3 holon at resolution 9 (~1km²)
+    const sanFrancisco = await hs.toHolon(37.7749, -122.4194, 9);
+    expect(typeof sanFrancisco).toBe('string');
+    expect(sanFrancisco).toMatch(/^8[0-9a-f]+$/);
+
+    // Step 2: Store temperature data in "temperature" lens
+    const success = await hs.write(
+      sanFrancisco,
+      'temperature',
+      {
+        id: 'sensor-001',
+        celsius: 18.5,
+        timestamp: Date.now(),
+        source: 'weather-station-1'
+      }
+    );
+    expect(success).toBe(true);
+
+    // Step 3: Retrieve data by location and category
+    const temp = await hs.read(sanFrancisco, 'temperature', 'sensor-001');
+    expect(temp).toMatchObject({
+      id: 'sensor-001',
+      celsius: 18.5,
+      source: 'weather-station-1'
+    });
+
+    // Step 4: Query all temperature data in this holon
+    const allTemps = await hs.read(sanFrancisco, 'temperature');
+    expect(Array.isArray(allTemps)).toBe(true);
+    expect(allTemps.length).toBeGreaterThanOrEqual(1);
+    expect(allTemps.some(t => t.id === 'sensor-001')).toBe(true);
+  });
+
+  it('should validate coordinates converted to H3 hexagon', async () => {
+    const holonId = await hs.toHolon(37.7749, -122.4194, 9);
+    expect(hs.isValidH3(holonId)).toBe(true);
+  });
+
+  it('should store and retrieve data at specific location with category', async () => {
+    const holon = await hs.toHolon(40.7128, -74.0060, 9); // New York
+
+    await hs.write(holon, 'events', {
+      id: 'event-001',
+      name: 'Concert',
+      venue: 'Madison Square Garden'
+    });
+
+    const event = await hs.read(holon, 'events', 'event-001');
+    expect(event.name).toBe('Concert');
+    expect(event.venue).toBe('Madison Square Garden');
+  });
+
+  it('should support multiple data items in same category', async () => {
+    const holon = await hs.toHolon(37.7749, -122.4194, 9);
+
+    await hs.write(holon, 'temperature', { id: 'sensor-A', celsius: 20 });
+    await hs.write(holon, 'temperature', { id: 'sensor-B', celsius: 21 });
+    await hs.write(holon, 'temperature', { id: 'sensor-C', celsius: 19 });
+
+    const all = await hs.read(holon, 'temperature');
+    expect(all.length).toBeGreaterThanOrEqual(3);
+  });
+});

package/tests/unit/integration/scenario-02-federation.test.js

@@ -0,0 +1,76 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import HoloSphere from '../../../src/index.js';
+
+describe('Integration: Scenario 2 - Hierarchical Federation with Single Source of Truth', () => {
+  let hs;
+
+  beforeEach(() => {
+    hs = new HoloSphere({ relays: [], appName: 'scenario-02' });
+  });
+
+  it('should complete hierarchical federation workflow', async () => {
+    // Step 1: Create data in local area (resolution 9)
+    const localHolon = await hs.toHolon(37.7749, -122.4194, 9);
+    await hs.write(localHolon, 'events', {
+      id: 'concert-001',
+      name: 'Jazz Night',
+      venue: 'Blue Note SF'
+    });
+
+    // Step 2: Get parent holon (resolution 7 = ~5km² region)
+    const parents = await hs.getParents(localHolon, 7);
+    const regionalHolon = parents[0];
+    expect(typeof regionalHolon).toBe('string');
+
+    // Step 3: Establish federation (local → regional)
+    const fedSuccess = await hs.federate(localHolon, regionalHolon, 'events', {
+      direction: 'outbound',
+      mode: 'reference'  // Uses holograms, not copies
+    });
+    expect(fedSuccess).toBe(true);
+
+    // Step 4: Query regional holon - sees local data via reference
+    const regionalEvents = await hs.getFederatedData(regionalHolon, 'events');
+    expect(Array.isArray(regionalEvents)).toBe(true);
+    expect(regionalEvents.length).toBeGreaterThanOrEqual(1);
+    expect(regionalEvents.some(e => e.id === 'concert-001')).toBe(true);
+
+    // Step 5: Update local data
+    await hs.update(localHolon, 'events', 'concert-001', {
+      name: 'Jazz Night - SOLD OUT'
+    });
+
+    // Step 6: Regional view automatically reflects change (single source of truth)
+    const updatedRegional = await hs.getFederatedData(regionalHolon, 'events');
+    const updatedEvent = updatedRegional.find(e => e.id === 'concert-001');
+    expect(updatedEvent.name).toBe('Jazz Night - SOLD OUT');
+  });
+
+  it('should validate federation uses references (holograms), not copies', async () => {
+    const local = await hs.toHolon(37.7749, -122.4194, 10);
+    const parents = await hs.getParents(local);
+    const regional = parents[0];
+
+    await hs.write(local, 'data', { id: 'item-1', value: 'original' });
+    await hs.federate(local, regional, 'data', { mode: 'reference' });
+
+    // Update should be reflected immediately
+    await hs.update(local, 'data', 'item-1', { value: 'updated' });
+
+    const regionalData = await hs.getFederatedData(regional, 'data');
+    const item = regionalData.find(d => d.id === 'item-1');
+    expect(item.value).toBe('updated');
+  });
+
+  it('should validate regional queries include federated local data', async () => {
+    const local = await hs.toHolon(40.7128, -74.0060, 9);
+    const parents = await hs.getParents(local);
+    const regional = parents[0];
+
+    await hs.write(local, 'notes', { id: 'note-1', text: 'Local note' });
+    await hs.federate(local, regional, 'notes');
+
+    const regionalNotes = await hs.getFederatedData(regional, 'notes');
+    expect(regionalNotes.some(n => n.id === 'note-1')).toBe(true);
+  });
+});

package/tests/unit/integration/scenario-03-subscriptions.test.js

@@ -0,0 +1,102 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import HoloSphere from '../../../src/index.js';
+
+describe('Integration: Scenario 3 - Real-time Subscriptions', () => {
+  let hs;
+
+  beforeEach(() => {
+    hs = new HoloSphere({ relays: [], appName: 'scenario-03' });
+  });
+
+  it('should complete real-time subscription workflow', async () => {
+    // Step 1: Subscribe to temperature changes
+    const holon = await hs.toHolon(37.7749, -122.4194, 9);
+    const updates = [];
+
+    const subscription = hs.subscribe(holon, 'temperature', (data, key) => {
+      updates.push({ key, data });
+    });
+
+    expect(subscription).toHaveProperty('unsubscribe');
+
+    // Step 2: Write new data - subscription fires
+    await hs.write(holon, 'temperature', {
+      id: 'sensor-002',
+      celsius: 19.2
+    });
+
+    // Wait for async updates
+    await new Promise(resolve => setTimeout(resolve, 200));
+
+    expect(updates.length).toBeGreaterThanOrEqual(1);
+
+    // Step 3: Update existing data - subscription fires again
+    await hs.update(holon, 'temperature', 'sensor-002', { celsius: 19.8 });
+
+    await new Promise(resolve => setTimeout(resolve, 200));
+
+    expect(updates.length).toBeGreaterThanOrEqual(2);
+
+    // Step 4: Unsubscribe - no more updates
+    subscription.unsubscribe();
+
+    const beforeUnsubscribe = updates.length;
+
+    await hs.write(holon, 'temperature', { id: 'sensor-003', celsius: 20.0 });
+    await new Promise(resolve => setTimeout(resolve, 200));
+
+    expect(updates.length).toBe(beforeUnsubscribe); // No new updates
+  });
+
+  it('should validate subscriptions receive real-time updates', async () => {
+    const holon = await hs.toHolon(40.7128, -74.0060, 9);
+    const callback = vi.fn();
+
+    const sub = hs.subscribe(holon, 'events', callback);
+
+    await hs.write(holon, 'events', { id: 'event-1', name: 'Test Event' });
+    await new Promise(resolve => setTimeout(resolve, 200));
+
+    expect(callback).toHaveBeenCalled();
+    sub.unsubscribe();
+  });
+
+  it('should validate callbacks invoked on data changes', async () => {
+    const holon = await hs.toHolon(37.7749, -122.4194, 9);
+    const dataReceived = [];
+
+    const sub = hs.subscribe(holon, 'test', (data) => {
+      dataReceived.push(data);
+    });
+
+    await hs.write(holon, 'test', { id: 'item-1', value: 'A' });
+    await hs.write(holon, 'test', { id: 'item-2', value: 'B' });
+
+    await new Promise(resolve => setTimeout(resolve, 200));
+
+    expect(dataReceived.length).toBeGreaterThanOrEqual(2);
+    sub.unsubscribe();
+  });
+
+  it('should validate unsubscribe stops updates', async () => {
+    const holon = await hs.toHolon(37.7749, -122.4194, 9);
+    let callCount = 0;
+
+    const sub = hs.subscribe(holon, 'counter', () => {
+      callCount++;
+    });
+
+    await hs.write(holon, 'counter', { id: 'c1', value: 1 });
+    await new Promise(resolve => setTimeout(resolve, 100));
+
+    const countBeforeUnsubscribe = callCount;
+
+    sub.unsubscribe();
+
+    await hs.write(holon, 'counter', { id: 'c2', value: 2 });
+    await hs.write(holon, 'counter', { id: 'c3', value: 3 });
+    await new Promise(resolve => setTimeout(resolve, 100));
+
+    expect(callCount).toBe(countBeforeUnsubscribe);
+  });
+});