holosphere 1.1.20 → 2.0.0-alpha1

package/README.md

@@ -1,471 +1,587 @@
 # HoloSphere
 
-HoloSphere is a JavaScript library that provides a spatial data management system using H3 geospatial indexing and GunDB for distributed storage. It enables you to store, validate, and retrieve data organized by geographic location using holonic principles.
+**Holonic Geospatial Communication Infrastructure**
+
+A JavaScript library implementing holonic geospatial communication infrastructure by combining H3 hexagonal geospatial indexing with Nostr relay-based distributed peer-to-peer storage.
+
+[![Bundle Size](https://img.shields.io/badge/bundle%20size-127%20KB-success)](https://bundlephobia.com)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
+
+## Features
+
+- **Local-First Architecture**: Reads return instantly from persistent storage; writes guaranteed to sync via OutboxQueue
+- **Geographic & Noospheric Organization**: H3 hexagonal indexing (16 resolution levels) + URI-based conceptual spaces
+- **Distributed P2P Storage**: Nostr relay-based persistence with local-first reads and background sync
+- **Offline Support**: Full read/write functionality offline; automatic sync when connectivity returns
+- **Holonic Architecture**: Autonomous holons with hierarchical parent-child relationships
+- **Holograms**: Lightweight references to data with local overrides and automatic resolution
+- **Real-time Subscriptions**: Live data updates with throttling, filtering, and hologram resolution
+- **Federation**: Bidirectional data sharing within and across HoloSphere instances
+- **Cross-Holosphere Federation**: Multi-instance partnerships with capability token exchange
+- **Discovery Protocol**: Automated Nostr-based federation handshake
+- **Schema Validation**: JSON Schema 2019 with strict/permissive modes and URI references
+- **Cryptographic Security**: secp256k1 signatures, capability tokens with permissions and scopes
+- **Social Protocols**: Unified interface for Nostr (NIP-01) and ActivityPub
+- **Hierarchical Aggregation**: Automatic upcast to parent holons (summarize, aggregate, concatenate)
 
-## What is a Holon?
-
-A holon (from Greek 'holos' meaning whole, with suffix 'on' meaning part) is simultaneously a whole and a part. In HoloSphere, holons are implemented as hierarchical geographic cells that can:
+## Installation
 
-1. Act as autonomous units (storing their own data)
-2. Be part of larger holons (through H3's hierarchical structure)
-3. Contain smaller holons (through subdivision)
-4. Interact with peer holons (through the distributed network)
+### npm
+```bash
+npm install holosphere
+```
 
-### Holonic Architecture
+### CDN
+```html
+<script src="https://cdn.jsdelivr.net/npm/holosphere@latest/dist/cdn/holosphere.min.js"></script>
+```
 
-HoloSphere implements holonic architecture in two ways:
+## Quick Start
 
-#### 1. Spatial Hierarchy
 ```javascript
-// Get holons at different scales for a location
-const holon = await sphere.getHolon(lat, lng, 7);  // City level
-const parent = h3.cellToParent(holon, 6);          // Region level
-const children = h3.cellToChildren(holon, 8);       // Neighborhood level
-
-// Get entire hierarchy
-const scales = sphere.getHolonScalespace(holon);    // All containing holons
-```
+import HoloSphere from 'holosphere';
 
-#### 2. Data Organization
-```javascript
-// Store data in different aspects (lenses) of a holon
-await sphere.put(holon, 'environment', {
-    id: 'air-001',
-    temperature: 22.5,
-    humidity: 65
+// Initialize with Nostr relays
+const hs = new HoloSphere({
+  appName: 'myapp',
+  relays: ['wss://relay.damus.io', 'wss://nos.lol'],
+  privateKey: 'your-hex-private-key', // Optional: auto-generated if not provided
+  logLevel: 'INFO'
 });
 
-await sphere.put(holon, 'social', {
-    id: 'event-001',
-    type: 'gathering',
-    participants: 50
+// Convert coordinates to H3 holon (San Francisco, resolution 9 ≈ 1km²)
+const holonId = await hs.toHolon(37.7749, -122.4194, 9);
+
+// Write data to a lens
+await hs.write(holonId, 'temperature', {
+  id: 'sensor-001',
+  celsius: 18.5,
+  timestamp: Date.now()
 });
-```
 
-### Use Cases
+// Read data
+const data = await hs.read(holonId, 'temperature', 'sensor-001');
+console.log(data); // => { id: 'sensor-001', celsius: 18.5, ... }
 
-1. **Localized Structures**
-   - Local environmental monitoring
-   - Community event coordination
-   - Neighborhood resource sharing
-   - Municipal service management
+// Subscribe to real-time updates
+const subscription = hs.subscribe(holonId, 'temperature', (data, key) => {
+  console.log('Temperature updated:', data);
+});
 
-```javascript
-// Example: Local air quality monitoring
-async function monitorLocalAir(lat, lng) {
-    const neighborhood = await sphere.getHolon(lat, lng, 9);
-    
-    // Store reading
-    await sphere.put(neighborhood, 'air-quality', {
-        id: `reading-${Date.now()}`,
-        pm25: 12.5,
-        timestamp: Date.now()
-    });
-    
-    // Get local trends
-    const readings = await sphere.getAll(neighborhood, 'air-quality');
-}
+// Unsubscribe when done
+subscription.unsubscribe();
 ```
 
-2. **Delocalized Structures**
-   - Regional data aggregation
-   - Cross-boundary collaboration
-   - Distributed decision making
-   - Resource flow tracking
+## Local-First Architecture
 
-```javascript
-// Example: Regional resource coordination
-async function coordinateResources(region) {
-    // Get all sub-holons
-    const localities = h3.cellToChildren(region, h3.getResolution(region) + 1);
-    
-    // Gather resource data from each locality
-    const resources = await Promise.all(
-        localities.map(async locality => {
-            return sphere.getAll(locality, 'resources');
-        })
-    );
-    
-    // Compute summaries for parent holon
-    await sphere.compute(region, 'resources', 'summarize');
-}
-```
+HoloSphere implements true local-first principles: your data lives on your device first, with Nostr relays serving as the sync layer.
 
-3. **Hybrid Structures**
-   - Adaptive governance systems
-   - Scalable social networks
-   - Emergency response coordination
-   - Supply chain management
+### How It Works
 
+**Reads are instant:**
 ```javascript
-// Example: Emergency response system
-async function coordinateEmergency(incident) {
-    const epicenter = await sphere.getHolon(incident.lat, incident.lng, 8);
-    const region = h3.cellToParent(epicenter, 6);
-    
-    // Local response
-    await sphere.put(epicenter, 'emergencies', {
-        id: incident.id,
-        type: incident.type,
-        severity: incident.severity
-    });
-    
-    // Regional coordination
-    const nearbyResources = await sphere.getAll(region, 'resources');
-    
-    // Subscribe to updates
-    sphere.subscribe(epicenter, 'emergencies', (data) => {
-        updateResponsePlan(data);
-    });
-}
+// Data returns immediately from local storage
+// Background refresh updates from relays (non-blocking)
+const data = await hs.read(holonId, 'sensors', 'temp-001');
 ```
 
-### Key Benefits
-
-1. **Scalability**: Holons can be nested infinitely, allowing systems to scale organically
-2. **Autonomy**: Each holon manages its own data while participating in larger structures
-3. **Flexibility**: Systems can be organized both hierarchically and peer-to-peer
-4. **Resilience**: Distributed storage ensures no single point of failure
-5. **Adaptability**: Structures can evolve based on changing needs
-
-## Installation
-
-```bash
-npm install holosphere
+**Writes are guaranteed:**
+```javascript
+// Write returns after local persist (~10ms)
+// OutboxQueue ensures delivery to relays with retry
+await hs.write(holonId, 'sensors', { id: 'temp-001', value: 22.5 });
+// Works offline - syncs automatically when online
 ```
 
-## Quick Start
+### Offline Behavior
 
-```javascript
-import HoloSphere from 'holosphere';
+| Operation | Offline | When Online |
+|-----------|---------|-------------|
+| Read | Returns local data | Background refresh |
+| Write | Persists locally | OutboxQueue syncs with retry |
+| Subscribe | Local events only | Receives relay updates |
 
-// Initialize HoloSphere
-const sphere = new HoloSphere('my-app');
+### Configuration
 
-// Store data at a location
-const holon = await sphere.getHolon(40.7128, -74.0060, 7); // NYC at resolution 7
-await sphere.put(holon, 'observations', {
-    id: 'obs-001',
-    temperature: 22.5,
-    timestamp: Date.now()
+```javascript
+const hs = new HoloSphere({
+  appName: 'myapp',
+  relays: ['wss://relay.damus.io'],
+
+  // Local-first options
+  persistence: true,        // Persistent storage (default: true)
+  backgroundSync: true,     // Enable SyncService (default: true)
+  syncInterval: 10000,      // Retry interval in ms (default: 10s)
+  maxRetries: 5,            // Max delivery attempts (default: 5)
+  failedTTL: 86400000,      // Failed event TTL (default: 24h)
 });
 ```
 
-## Real-World Examples
+See [LOCALFIRST.md](./LOCALFIRST.md) for detailed architecture documentation.
 
-### Environmental Monitoring System
+## Core Concepts
 
-```javascript
-// Define a schema for temperature readings
-const tempSchema = {
-    type: 'object',
-    properties: {
-        id: { type: 'string' },
-        temperature: { type: 'number' },
-        humidity: { type: 'number' },
-        timestamp: { type: 'number' }
-    },
-    required: ['id', 'temperature', 'timestamp']
-};
-
-// Set up the system
-const sphere = new HoloSphere('env-monitor', true); // strict mode enabled
-await sphere.setSchema('temperature', tempSchema);
-
-// Store a reading
-async function storeReading(lat, lng, temp, humidity) {
-    const holon = await sphere.getHolon(lat, lng, 8);
-    const reading = {
-        id: `temp-${Date.now()}`,
-        temperature: temp,
-        humidity: humidity,
-        timestamp: Date.now()
-    };
-    
-    return sphere.put(holon, 'temperature', reading);
-}
+### Holons
+Locations in either **geographic space** (H3 hexagonal cells) or **noospheric space** (URI-identified concepts):
 
-// Get all readings for an area
-async function getAreaReadings(lat, lng) {
-    const holon = await sphere.getHolon(lat, lng, 8);
-    return sphere.getAll(holon, 'temperature');
-}
+```javascript
+// Geographic holon (H3 cell at resolution 9)
+const geoHolon = await hs.toHolon(37.7749, -122.4194, 9);
+// => "8928342e20fffff"
 
-// Monitor an area for new readings
-function monitorArea(lat, lng, callback) {
-    const holon = sphere.getHolon(lat, lng, 8);
-    sphere.subscribe(holon, 'temperature', callback);
-}
+// Noospheric holon (arbitrary string ID)
+const conceptHolon = "topic/bitcoin";
 ```
 
-### Location-Based Content System
+### Lenses
+Categorical data collections within a holon:
 
 ```javascript
-// Initialize with AI capabilities for content summarization
-const sphere = new HoloSphere('local-content', false, 'your-openai-key');
-
-// Define content schema
-const contentSchema = {
-    type: 'object',
-    properties: {
-        id: { type: 'string' },
-        title: { type: 'string' },
-        content: { type: 'string' },
-        author: { type: 'string' },
-        timestamp: { type: 'number' }
-    },
-    required: ['id', 'title', 'content', 'author']
-};
-
-await sphere.setSchema('articles', contentSchema);
-
-// Post content for a location
-async function postLocalContent(lat, lng, title, content, author) {
-    const holon = await sphere.getHolon(lat, lng, 7);
-    const article = {
-        id: `article-${Date.now()}`,
-        title,
-        content,
-        author,
-        timestamp: Date.now()
-    };
-    
-    await sphere.put(holon, 'articles', article);
-    
-    // Generate summaries for parent areas
-    await sphere.compute(holon, 'articles', 'summarize');
-}
+await hs.write(holonId, 'events', {
+  id: 'concert-001',
+  name: 'Jazz Night',
+  venue: 'Blue Note SF'
+});
 
-// Get content for multiple zoom levels
-async function getAreaContent(lat, lng) {
-    const holon = await sphere.getHolon(lat, lng, 7);
-    const scales = sphere.getHolonScalespace(holon);
-    
-    const content = {};
-    for (const scale of scales) {
-        content[scale] = await sphere.getAll(scale, 'articles');
-    }
-    
-    return content;
-}
+await hs.write(holonId, 'sensors', {
+  id: 'temp-001',
+  value: 22.5,
+  unit: 'celsius'
+});
 ```
 
-### Data Validation Example
+### Holograms
+Lightweight references to data that can exist in multiple locations while maintaining a single source of truth:
 
 ```javascript
-// Strict validation with custom schema
-const sphere = new HoloSphere('validated-data', true);
-
-const measurementSchema = {
-    type: 'object',
-    properties: {
-        id: { type: 'string' },
-        value: { type: 'number' },
-        unit: { type: 'string' },
-        accuracy: { type: 'number' },
-        timestamp: { type: 'number' }
-    },
-    required: ['id', 'value', 'unit'],
-    additionalProperties: false
-};
-
-await sphere.setSchema('measurements', measurementSchema);
-
-// This will succeed
-await sphere.put(holon, 'measurements', {
-    id: 'measure-1',
-    value: 42.5,
-    unit: 'celsius',
-    accuracy: 0.1,
-    timestamp: Date.now()
+// Create a hologram (reference) in target holon pointing to source data
+await hs.propagateData(
+  sourceData,
+  sourceHolonId,
+  targetHolonId,
+  'events'
+);
+
+// Holograms support local overrides (position, pinned status, etc.)
+await hs.updateHologramOverrides(targetHolonId, 'events', hologramId, {
+  x: 100,
+  y: 200,
+  pinned: true
 });
 
-// This will fail due to schema validation
-await sphere.put(holon, 'measurements', {
-    id: 'measure-2',
-    value: "invalid", // wrong type
-    extra: "field"    // not allowed
-});
+// Resolution merges source data with local overrides
+const resolved = await hs.resolveHologram(hologram);
+// => { ...sourceData, x: 100, y: 200, pinned: true }
 ```
 
-## API Reference
+### Federation (Within Holosphere)
+Bidirectional data sharing between holons:
 
-### Constructor
 ```javascript
-new HoloSphere(
-    appName,    // String: Namespace for your application
-    strict,     // Boolean: Enable strict schema validation (default: false)
-    openaikey   // String: Optional OpenAI API key for AI features
-)
+// Get parent holon (larger geographic region)
+const parents = await hs.getParents(localHolon);
+const regionalHolon = parents[0];
+
+// Establish federation - data in localHolon is visible from regionalHolon
+await hs.federate(localHolon, regionalHolon, 'events', {
+  direction: 'outbound',
+  mode: 'reference' // Creates holograms instead of copies
+});
+
+// Query regional holon sees local data via holograms
+const events = await hs.getFederatedData(regionalHolon, 'events');
 ```
 
-### Core Methods
+### Cross-Holosphere Federation
+Multi-instance partnerships with capability token exchange:
 
-- `async getHolon(lat, lng, resolution)` - Get H3 index for coordinates
-- `async put(holon, lens, data)` - Store data
-- `async get(holon, lens, key)` - Retrieve specific data
-- `async getAll(holon, lens)` - Retrieve all data
-- `async delete(holon, lens, key)` - Delete specific data
-- `async deleteAll(holon, lens)` - Delete all data
-- `async setSchema(lens, schema)` - Set JSON schema for validation
-- `async getSchema(lens)` - Get current schema
-- `subscribe(holon, lens, callback)` - Listen for changes
+```javascript
+// Add a federated partner by their public key
+await hs.addFederatedHolosphere(partnerPubKey, {
+  name: 'Partner Holosphere',
+  permissions: ['read', 'write']
+});
 
-## Storage Architecture
+// Issue capability token for the partner
+const capability = await hs.issueCapabilityForFederation(partnerPubKey, {
+  permissions: ['read', 'write'],
+  scope: { holonId: '*', lensName: 'events' },
+  expiresIn: 86400000 // 24 hours
+});
 
-Data in HoloSphere is organized by:
-- **Holons**: H3 geographic indexes
-- **Lenses**: Data categories/types
-- **Items**: Individual data entries with unique IDs
+// Read data from a federated partner
+const remoteData = await hs.readFromFederatedSource(
+  partnerPubKey,
+  holonId,
+  'events',
+  dataId
+);
+
+// Create a hologram pointing to remote data
+await hs.createCrossHolosphereHologram(
+  partnerPubKey,
+  remoteHolonId,
+  'events',
+  remoteDataId,
+  localHolonId
+);
+```
 
-## Dependencies
+### Discovery Protocol (Nostr-Based)
+Automated federation handshake via Nostr events:
 
-- h3-js: Uber's H3 geospatial indexing
-- gun: Decentralized database
-- ajv: JSON Schema validation
-- openai: AI capabilities (optional)
+```javascript
+// Send federation request to another holosphere
+await hs.sendFederationRequest(targetPubKey, {
+  proposedPermissions: ['read', 'write'],
+  proposedScopes: [{ holonId: '*', lensName: 'events' }],
+  message: 'Requesting federation partnership'
+});
 
-## License
+// Listen for incoming federation requests
+hs.subscribeFederationRequests((request) => {
+  console.log('Federation request from:', request.authorPubKey);
 
-GPL-3.0-or-later
+  // Accept the request
+  hs.acceptFederationRequest(request, {
+    grantedPermissions: ['read'],
+    grantedScopes: [{ holonId: '*', lensName: 'events' }]
+  });
+});
 
-# HoloSphere Federation
+// Subscribe to acceptance/decline responses
+hs.subscribeFederationAcceptances((acceptance) => {
+  console.log('Federation accepted by:', acceptance.authorPubKey);
+});
+```
 
-HoloSphere provides a federation system that allows spaces to share data and messages across different holons. This document outlines the federation functionality and how to use it.
+### Hierarchical Aggregation
+Automatic propagation to parent holons:
 
-## Core Federation Features
+```javascript
+await hs.upcast(localHolon, 'sensors', 'temp-001', {
+  maxLevel: 3,           // Propagate 3 levels up hierarchy
+  operation: 'summarize' // or 'aggregate', 'concatenate'
+});
+```
 
-### Space Federation
-- Create relationships between spaces with clear source-target connections
-- Use soul references to maintain a single source of truth
-- Control data propagation between federated spaces
-- Manage notification settings for each space
+## Authentication & Cryptography
 
-### Message Federation
-- Track messages across federated spaces
-- Maintain message relationships between original and federated copies
-- Update messages consistently across all federated spaces
+### Key Management
+```javascript
+// Derive public key from private key
+const pubKey = hs.getPublicKey(privateKey);
 
-## API Reference
+// Sign content
+const signature = await hs.sign(content, privateKey);
 
-### Space Federation
+// Verify signature
+const isValid = await hs.verify(content, signature, pubKey);
+```
 
-#### `federate(spaceId1, spaceId2, password1, password2, bidirectional)`
-Creates a federation relationship between two spaces.
+### Capability Tokens
+Fine-grained permission control with scope-based access:
 
 ```javascript
-await holosphere.federate('space1', 'space2', 'pass1', 'pass2');
+// Issue a capability token
+const token = await hs.issueCapability(
+  ['read', 'write'],           // Permissions
+  { holonId: '*', lensName: 'events' }, // Scope (supports wildcards)
+  recipientPubKey,             // Recipient
+  { expiresIn: 3600000 }       // Options (1 hour expiry)
+);
+
+// Verify a capability token
+const result = await hs.verifyCapability(
+  token,
+  'write',                     // Required permission
+  { holonId: holonId, lensName: 'events' } // Requested scope
+);
+
+if (result.valid) {
+  // Authorized
+}
 ```
 
-This sets up:
-- space1.federation includes space2
-- space2.notify includes space1
+**Capability Features:**
+- JWT-like base64 encoding
+- Permissions: `read`, `write`, `delete`
+- Scope wildcards: `{ holonId: "*", lensName: "*" }`
+- Automatic expiration
+- Cryptographic signing with secp256k1
 
-Parameters:
-- `spaceId1`: First space ID (source space)
-- `spaceId2`: Second space ID (target space)
-- `password1`: Optional password for first space
-- `password2`: Optional password for second space
-- `bidirectional`: Whether to set up bidirectional notifications (default: true, but generally not needed)
-
-### Data Propagation
+## API Reference
 
-#### `propagate(holon, lens, data, options)`
-Propagates data to federated spaces.
+### Configuration Options
 
 ```javascript
-await holosphere.propagate('space1', 'items', data, {
-  useReferences: true,         // Default: uses soul references 
-  targetSpaces: ['space2']     // Optional: specific targets
+const hs = new HoloSphere({
+  appName: 'myapp',              // Application namespace (default: 'holosphere')
+  relays: [                      // Nostr relay servers
+    'wss://relay.damus.io',
+    'wss://nos.lol'
+  ],
+  privateKey: 'hex...',          // secp256k1 private key (auto-generated if omitted)
+  logLevel: 'WARN',              // 'ERROR' | 'WARN' | 'INFO' | 'DEBUG'
+  hybridMode: true,              // Query both local cache and relays (default: true)
+  enableReconnect: true,         // Auto-reconnect to relays (default: true)
+  enablePing: true,              // Keep-alive pings (default: true)
+
+  // Local-first options
+  persistence: true,             // Enable persistent storage (default: true)
+  dataDir: './data',             // Storage directory for persistence
+  backgroundSync: true,          // Enable SyncService (default: true)
+  syncInterval: 10000,           // Background sync interval in ms (default: 10000)
+  maxRetries: 5,                 // Max retry attempts for failed writes (default: 5)
+  retryBaseDelay: 1000,          // Base delay for exponential backoff (default: 1000ms)
+  retryMaxDelay: 60000,          // Max delay cap for retries (default: 60000ms)
+  failedTTL: 86400000,           // TTL for failed events before purge (default: 24h)
 });
 ```
 
-Parameters:
-- `holon`: The holon identifier
-- `lens`: The lens identifier
-- `data`: The data to propagate
-- `options`: Propagation options
-
-Alternatively, you can use auto-propagation:
+### Spatial Operations
+| Method | Description |
+|--------|-------------|
+| `toHolon(lat, lng, resolution)` | Convert coordinates to H3 holon ID |
+| `getParents(holonId, maxResolution?)` | Get parent holons up hierarchy |
+| `getChildren(holonId)` | Get 7 child holons at next resolution |
+| `isValidH3(holonId)` | Validate H3 format |
+
+### Data Operations
+| Method | Description |
+|--------|-------------|
+| `write(holonId, lensName, data, options?)` | Write data to lens |
+| `read(holonId, lensName, dataId?)` | Read data (single or all) |
+| `update(holonId, lensName, dataId, updates, options?)` | Partial update |
+| `delete(holonId, lensName, dataId, options?)` | Delete data |
+| `getAll(holonId, lensName)` | Get all data in lens |
+
+### Global Table Operations
+| Method | Description |
+|--------|-------------|
+| `writeGlobal(table, data)` | Write non-location-specific data |
+| `readGlobal(table, key?)` | Read global data |
+| `updateGlobal(table, key, updates)` | Update global data |
+| `deleteGlobal(table, key)` | Delete global data |
+| `getAllGlobal(table)` | Get all data in table |
+| `deleteAllGlobal(table)` | Clear entire table |
+
+### Hologram Operations
+| Method | Description |
+|--------|-------------|
+| `createHologram(sourceHolon, sourceLens, sourceId, targetHolon)` | Create reference |
+| `resolveHologram(hologram)` | Resolve to actual data with overrides |
+| `updateHologramOverrides(holon, lens, id, overrides)` | Update local fields |
+| `deleteHologram(holon, lens, id)` | Delete with cleanup |
+| `getActiveHolograms(holon, lens, id)` | Get all refs to data |
+| `cleanupCircularHolograms(holon, lens)` | Remove circular refs |
+
+### Federation Operations
+| Method | Description |
+|--------|-------------|
+| `federate(source, target, lens, options?)` | Establish federation |
+| `federateHolon(source, target, options?)` | Holon-level federation |
+| `getFederatedData(holonId, lens, options?)` | Query federated data |
+| `unfederate(source, target, lens)` | Remove federation |
+| `propagateData(data, source, target, lens)` | Propagate to target |
+
+### Cross-Holosphere Operations
+| Method | Description |
+|--------|-------------|
+| `addFederatedHolosphere(pubKey, options)` | Add partner instance |
+| `removeFederatedHolosphere(pubKey)` | Remove partner |
+| `getFederatedHolospheres()` | List all partners |
+| `getFederationRegistry()` | Get full registry |
+| `issueCapabilityForFederation(pubKey, options)` | Grant access |
+| `storeInboundCapability(pubKey, token)` | Store received token |
+| `readFromFederatedSource(pubKey, holon, lens, id)` | Read remote data |
+| `createCrossHolosphereHologram(pubKey, holon, lens, id, target)` | Remote reference |
+
+### Discovery Protocol Operations
+| Method | Description |
+|--------|-------------|
+| `sendFederationRequest(targetPubKey, options)` | Propose federation |
+| `subscribeFederationRequests(callback)` | Listen for requests |
+| `acceptFederationRequest(request, options)` | Accept proposal |
+| `declineFederationRequest(request, reason)` | Decline proposal |
+| `subscribeFederationAcceptances(callback)` | Track acceptances |
+| `subscribeFederationDeclines(callback)` | Track declines |
+| `getPendingFederationRequests(options)` | Query pending |
+
+### Schema Operations
+| Method | Description |
+|--------|-------------|
+| `setSchema(lensName, schema, strict?)` | Define JSON Schema validation |
+| `getSchema(lensName)` | Retrieve schema |
+| `clearSchema(lensName)` | Remove schema |
+
+### Subscription Operations
+| Method | Description |
+|--------|-------------|
+| `subscribe(holonId, lens, callback, options?)` | Real-time updates |
+| `subscribeGlobal(table, key, callback)` | Global table subscriptions |
+
+**Subscription Options:**
+- `throttle`: Minimum ms between callbacks
+- `filter`: Function to filter events
+- `resolveHolograms`: Auto-resolve hologram references (default: true)
+- `realtimeOnly`: Skip historical data
+
+### Cryptographic Operations
+| Method | Description |
+|--------|-------------|
+| `getPublicKey(privateKey)` | Derive public key |
+| `sign(content, privateKey)` | Sign content |
+| `verify(content, signature, publicKey)` | Verify signature |
+| `issueCapability(permissions, scope, recipient, options?)` | Issue token |
+| `verifyCapability(token, permission, scope)` | Verify token |
+
+### Social Protocol Operations
+| Method | Description |
+|--------|-------------|
+| `publishNostr(event, holonId, lens?)` | Publish Nostr NIP-01 event |
+| `publishActivityPub(object, holonId, lens?)` | Publish ActivityPub object |
+| `querySocial(holonId, options?)` | Query with protocol/access filtering |
+| `verifyNostrEvent(event)` | Verify event signature |
+
+### Hierarchical Operations
+| Method | Description |
+|--------|-------------|
+| `upcast(holonId, lens, dataId, options?)` | Propagate to parent holons |
+
+**Upcast Operations:**
+- `summarize`: Condense data to summary
+- `aggregate`: Combine multiple items
+- `concatenate`: Combine all data
+
+### Utility Operations
+| Method | Description |
+|--------|-------------|
+| `metrics()` | Get operation counts and stats |
+
+## Architecture
+
+HoloSphere follows constitutional principles:
+
+- **Spatial-First**: H3 as universal spatial reference (resolutions 0-15)
+- **Decentralization**: P2P architecture via Nostr relays, no central authority
+- **Single Source of Truth**: Holograms (references) instead of data duplication
+- **Lens-Based Organization**: Independent schemas and federation per category
+- **Real-time Reactive**: Built-in subscriptions with throttling and filtering
+- **Cryptographic Security**: secp256k1 signatures, capability tokens with scopes
+- **Cross-Instance Federation**: Multi-holosphere partnerships via public keys
+- **Schema Flexibility**: Optional strict JSON Schema validation
+- **Hybrid Queries**: Combined local cache + relay queries for performance
+
+### Data Model
 
-```javascript
-await holosphere.put('space1', 'items', data, null, {
-  autoPropagate: true  // Enable auto-propagation
-});
+```
+appName/
+├── holonId/                    # Geographic (H3) or noospheric ID
+│   └── lensName/               # Data category
+│       └── dataId              # Individual data item
+│           ├── ...data fields
+│           └── _meta/          # Metadata
+│               ├── timestamp
+│               ├── creator
+│               ├── source      # Original location (for copies)
+│               └── activeHolograms[] # Tracking refs
+└── _global/                    # Non-spatial data
+    └── tableName/
+        └── key
 ```
 
-### Message Federation
-
-#### `federateMessage(originalChatId, messageId, federatedChatId, federatedMessageId, type)`
-Tracks a federated message across different chats.
+### Hologram Structure
 
 ```javascript
-await holosphere.federateMessage('chat1', 'msg1', 'chat2', 'msg2', 'quest');
+{
+  id: 'hologram-uuid',
+  _isHologram: true,
+  soul: 'appname/sourceHolon/lens/dataId',  // Source path
+  sourceHolonId: 'source-holon',
+  sourceLensName: 'events',
+  sourceDataId: 'original-id',
+
+  // Cross-holosphere (optional)
+  authorPubKey: 'source-pubkey',
+  embeddedCapability: 'base64-token',
+
+  // Local overrides
+  x: 100,
+  y: 200,
+  pinned: true
+}
 ```
 
-#### `getFederatedMessages(originalChatId, messageId)`
-Gets all federated messages for a given original message.
+## Development
 
-```javascript
-const messages = await holosphere.getFederatedMessages('chat1', 'msg1');
-```
+```bash
+# Install dependencies
+npm install
 
-#### `updateFederatedMessages(originalChatId, messageId, updateCallback)`
-Updates a message across all federated chats.
+# Run tests
+npm test
 
-```javascript
-await holosphere.updateFederatedMessages('chat1', 'msg1', async (chatId, messageId) => {
-    // Update message in this chat
-});
-```
+# Watch mode
+npm run test:watch
 
-## Usage Example
+# Coverage
+npm run test:coverage
 
-```javascript
-// Create federation between spaces
-await holosphere.federate('space1', 'space2');
+# Build
+npm run build
 
-// Store data in space1
-const data = { id: 'item1', value: 42 };
-await holosphere.put('space1', 'items', data);
+# Lint
+npm run lint
 
-// Propagate to federated spaces
-await holosphere.propagate('space1', 'items', data);
+# Format
+npm run format
+```
 
-// Retrieve data from space2 (will resolve the reference)
-const item = await holosphere.get('space2', 'items', 'item1');
+## Testing
 
-// Track a federated message
-await holosphere.federateMessage('chat1', 'msg1', 'chat2', 'msg2', 'quest');
+- **375+ tests**: Contract, integration, and unit tests
+- TDD approach: Tests written before implementation
 
-// Update message across all federated chats
-await holosphere.updateFederatedMessages('chat1', 'msg1', async (chatId, messageId) => {
-    await updateMessageInChat(chatId, messageId);
-});
+## Error Handling
+
+```javascript
+import { ValidationError, AuthorizationError, HolosphereError } from 'holosphere';
+
+try {
+  await hs.write(holonId, 'events', invalidData);
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.log('Schema validation failed:', error.message);
+  } else if (error instanceof AuthorizationError) {
+    console.log('Permission denied:', error.message);
+  }
+}
 ```
 
-## Soul References
+## License
 
-When using the default `useReferences: true` with propagation:
+MIT
 
-1. Only a lightweight reference is stored in the federated space
-2. The reference contains the original item's ID and soul path
-3. When accessed, the reference is automatically resolved to the original data
-4. Changes to the original data are immediately visible through references
+## Links
 
-This maintains a single source of truth while keeping storage efficient.
+- [Local-First Architecture](./LOCALFIRST.md)
+- [FOSDEM Proposal](./FOSDEM_PROPOSAL.md)
+- [Full API Documentation](./specs/001-holosphere-holonic-geospatial/contracts/api-interface.md)
+- [Quickstart Guide](./specs/001-holosphere-holonic-geospatial/quickstart.md)
+- [Implementation Plan](./specs/001-holosphere-holonic-geospatial/plan.md)
+- [Data Model](./specs/001-holosphere-holonic-geospatial/data-model.md)
+- [Constitution](./specify/memory/constitution.md)
 
-## Federation Structure
+## Contributing
 
-The federation system uses two key arrays to manage relationships:
+Contributions welcome! Please ensure:
+1. All tests pass (`npm test`)
+2. Code is formatted (`npm run format`)
+3. Linting passes (`npm run lint`)
+4. Constitutional principles are followed
 
-```javascript
-{
-    id: string,
-    name: string,
-    federation: string[],  // Source spaces this holon federates with
-    notify: string[],      // Target spaces to notify of changes
-    timestamp: number
-}
-```
+---
 
+Generated with [Claude Code](https://claude.com/claude-code)