holosphere 2.0.0-alpha1 → 2.0.0-alpha2

package/docs/data-model.md

@@ -0,0 +1,476 @@
+# Data Model: HoloSphere
+
+**Feature**: HoloSphere - Holonic Geospatial Communication Infrastructure
+**Date**: 2025-10-07
+**Status**: Complete
+
+## Overview
+This document defines the core data entities and their relationships for HoloSphere. The model supports both geographic and noospheric organization with decentralized storage via GunDB.
+
+---
+
+## Core Entities
+
+### 1. Holon
+**Definition**: A location in either geographic space (H3 hexagonal cell) or noospheric space (URI/URL identified concept).
+
+**Geographic Holon**:
+```javascript
+{
+  id: string,              // H3 cell ID (15+ chars, starts with '8')
+  type: 'geographic',      // Discriminator
+  resolution: number,      // H3 resolution level (0-15)
+  center: {                // Optional: lat/lng of cell center
+    lat: number,
+    lng: number
+  },
+  parents: string[],       // Parent H3 cells (derived from hierarchy)
+  children: string[]       // Child H3 cells (derived from hierarchy)
+}
+```
+
+**Noospheric Holon**:
+```javascript
+{
+  id: string,              // URI/URL (e.g., "nostr://topic/123", "ap://community/abc")
+  type: 'noospheric',      // Discriminator
+  scheme: string,          // Protocol/namespace (e.g., "nostr", "ap", "concept")
+  namespace: string,       // Namespace/domain
+  identifier: string       // Unique ID within namespace
+}
+```
+
+**Validation Rules**:
+- Geographic: ID must be valid H3 format (validated via h3-js `h3IsValid()`)
+- Noospheric: ID must be valid URI per RFC 3986
+- Both types support identical federation and lens operations
+
+**State Transitions**: Immutable structure (holons are location identifiers, not mutable entities)
+
+**Storage Path**: Holons themselves are identifiers, not stored objects. Data is stored within holon/lens paths.
+
+---
+
+### 2. Lens
+**Definition**: A categorical data collection within a holon (e.g., "temperature", "events", "social").
+
+**Structure**:
+```javascript
+{
+  name: string,            // Unique lens identifier within holon
+  schemaUri?: string,      // Optional: URI to JSON Schema for validation
+  strict?: boolean,        // Validation mode: true = blocking, false = logging
+  federation?: {           // Optional: Federation configuration
+    inbound: string[],     // Holons to receive data from
+    outbound: string[]     // Holons to send data to
+  },
+  _meta?: {
+    created: timestamp,
+    updated: timestamp,
+    itemCount: number      // Optional: Cached count
+  }
+}
+```
+
+**Validation Rules**:
+- Name must be non-empty string
+- Schema validation only occurs if `schemaUri` is set
+- Federation arrays contain valid holon IDs (H3 or URIs)
+
+**State Transitions**:
+- Created: When first data item written to holon/lens path
+- Updated: When schema or federation config changes
+- No deletion (lenses persist even if empty)
+
+**Storage Path**: `{appname}/{holonId}/{lensName}/_config`
+
+---
+
+### 3. Data Object
+**Definition**: Individual data record within a lens.
+
+**Structure**:
+```javascript
+{
+  id: string,              // Required: Unique identifier (auto-generated if not provided)
+  [customFields]: any,     // User-defined fields (validated against schema if present)
+  _meta?: {                // Optional: System metadata
+    timestamp: number,     // Creation/update timestamp (Unix epoch ms)
+    resolution?: number,   // H3 resolution (geographic holons only)
+    source?: string,       // Originating holon (for federated data)
+    hologram?: boolean     // True if this is a reference, not original data
+  }
+}
+```
+
+**Validation Rules**:
+- `id` is required (generated via crypto.randomUUID() if missing)
+- Custom fields validated against lens schema if strict mode enabled
+- `_meta` fields are reserved and managed by system
+
+**State Transitions**:
+- Created: Written to Gun at path `{appname}/{holonId}/{lensName}/{id}`
+- Updated: Modified in place (Gun handles conflict resolution)
+- Deleted: Marked as null in Gun (tombstone for sync)
+
+**Storage Path**: `{appname}/{holonId}/{lensName}/{id}`
+
+---
+
+### 4. Hologram
+**Definition**: Lightweight reference to data stored in another holon/lens.
+
+**Structure**:
+```javascript
+{
+  id: string,              // Reference ID (unique within current lens)
+  hologram: true,          // Discriminator flag
+  soul: string,            // Gun soul path to original data
+  target: {                // Parsed reference components
+    appname: string,
+    holonId: string,
+    lensName: string,
+    dataId: string
+  },
+  _meta: {
+    created: timestamp,
+    sourceHolon: string    // Holon where original data lives
+  }
+}
+```
+
+**Validation Rules**:
+- `soul` must be valid Gun path format
+- Target components must parse from soul
+- Circular reference detection during resolution
+
+**State Transitions**:
+- Created: When federation propagates data as reference
+- Resolved: Dereferenced to actual data on read
+- Deleted: When original data is deleted
+
+**Resolution Algorithm**:
+```
+1. Check if hologram flag is true
+2. Parse soul path to target components
+3. Track visited souls to prevent infinite loops
+4. Fetch data from Gun at soul path
+5. If result is also hologram, recurse (max depth: 10)
+6. Return final resolved data or null
+```
+
+**Storage Path**: Same as data objects (stored in lens, distinguished by `hologram: true` flag)
+
+---
+
+### 5. Federation
+**Definition**: Bidirectional data sharing relationship between two holons.
+
+**Structure**:
+```javascript
+{
+  id: string,              // Federation relationship ID
+  sourceHolon: string,     // Sending holon ID
+  targetHolon: string,     // Receiving holon ID
+  lenses: {                // Per-lens configuration
+    [lensName]: {
+      direction: 'inbound' | 'outbound' | 'bidirectional',
+      mode: 'reference' | 'copy',  // Default: reference
+      filter?: Function,   // Optional: Custom filter for selective propagation
+      transform?: Function // Optional: Transform data during federation
+    }
+  },
+  _meta: {
+    established: timestamp,
+    lastSync: timestamp
+  }
+}
+```
+
+**Validation Rules**:
+- Source and target must be valid holon IDs
+- Cannot federate holon with itself
+- Lens names must exist in source holon
+
+**State Transitions**:
+- Established: Configuration created
+- Active: Data propagating based on rules
+- Suspended: Temporarily disabled (federation config exists but inactive)
+- Terminated: Removed (holograms persist but no new propagation)
+
+**Behavior**:
+- **Reference mode (default)**: Creates hologram in target, original data in source
+- **Copy mode**: Duplicates data to target (used when target must be self-sufficient)
+- **Bidirectional**: Both holons have inbound and outbound configured for same lens
+
+**Storage Path**: `{appname}/_federation/{federationId}`
+
+---
+
+### 6. Schema
+**Definition**: JSON Schema (2019 draft) validation rules for a lens.
+
+**Structure**:
+```javascript
+{
+  uri: string,             // Unique schema identifier (URI format)
+  lensName: string,        // Associated lens
+  schema: object,          // JSON Schema 2019 object
+  strict: boolean,         // Validation mode
+  _cache: {                // Cached compiled validator
+    validator: Function,   // Ajv compiled validator
+    cachedAt: timestamp,   // Cache timestamp
+    ttl: number           // Time-to-live (default: 3600000ms = 1 hour)
+  }
+}
+```
+
+**Validation Rules**:
+- Schema must be valid JSON Schema 2019 format
+- URI must be unique across application
+- TTL must be positive integer (milliseconds)
+
+**State Transitions**:
+- Defined: Schema created and stored
+- Cached: Validator compiled and cached
+- Expired: Cache TTL exceeded, recompile on next use
+- Updated: Schema modified, cache invalidated
+
+**Storage Path**: `{appname}/_schemas/{schemaUri}`
+
+---
+
+### 7. Subscription
+**Definition**: Real-time change notification for a holon/lens combination.
+
+**Structure** (runtime only, not persisted):
+```javascript
+{
+  id: string,              // Subscription ID (generated)
+  holonId: string,         // Holon to monitor
+  lensName: string,        // Lens to monitor
+  callback: Function,      // User-provided callback(data, key)
+  options: {
+    includeFederated?: boolean,  // Include data from federated holons
+    filter?: Function,           // Optional filter predicate
+    throttle?: number            // Milliseconds between updates
+  },
+  _internal: {
+    gunListener: Function, // Gun .on() reference for cleanup
+    active: boolean,       // Subscription state
+    createdAt: timestamp
+  }
+}
+```
+
+**Validation Rules**:
+- Holon ID must be valid
+- Lens name must be non-empty
+- Callback must be a function
+- Throttle must be ≥0
+
+**State Transitions**:
+- Subscribed: Listener attached to Gun path
+- Active: Receiving and invoking callbacks
+- Unsubscribed: Listener removed, no longer active
+
+**Lifecycle**:
+```javascript
+// Subscribe
+const subscription = holosphere.subscribe(holonId, lensName, (data, key) => {
+  console.log('Data changed:', data);
+});
+
+// Unsubscribe
+subscription.unsubscribe();
+```
+
+**Storage**: Not persisted (runtime only)
+
+---
+
+### 8. Capability Token
+**Definition**: Cryptographic authorization token for permissions.
+
+**Structure**:
+```javascript
+{
+  id: string,              // Token ID (generated)
+  issuer: string,          // Public key of issuer
+  recipient: string,       // Public key of recipient
+  permissions: string[],   // Array: 'read', 'write', 'delete', 'modify'
+  scope: {                 // What this token grants access to
+    holonId?: string,      // Specific holon (or wildcard '*')
+    lensName?: string      // Specific lens (or wildcard '*')
+  },
+  expires: timestamp,      // Expiration timestamp
+  signature: string,       // secp256k1 signature of token
+  _meta: {
+    issued: timestamp,
+    nonce: string          // Prevents replay attacks
+  }
+}
+```
+
+**Validation Rules**:
+- Issuer and recipient must be valid secp256k1 public keys
+- Permissions must be from allowed set
+- Expires must be future timestamp
+- Signature must verify against issuer's public key
+- Nonce must be unique (prevents replay)
+
+**State Transitions**:
+- Issued: Token created and signed
+- Active: Within validity period
+- Expired: Past expiration timestamp
+- Revoked: Manually invalidated (requires revocation list)
+
+**Verification Algorithm**:
+```
+1. Check token.expires > Date.now()
+2. Verify signature against issuer public key
+3. Check nonce hasn't been used (replay protection)
+4. Validate scope matches requested operation
+5. Confirm permissions include required permission
+```
+
+**Storage Path**: `{appname}/_capabilities/{tokenId}` (optional, tokens can be passed directly)
+
+---
+
+### 9. Social Content
+**Definition**: Protocol-agnostic social data (Nostr events, ActivityPub objects).
+
+**Nostr Event**:
+```javascript
+{
+  id: string,              // Nostr event ID (hex)
+  pubkey: string,          // Author public key (hex)
+  created_at: number,      // Unix timestamp
+  kind: number,            // Nostr event kind (e.g., 1 = text note)
+  tags: string[][],        // Nostr tags
+  content: string,         // Event content
+  sig: string,             // secp256k1 signature
+  _holosphere: {           // HoloSphere metadata
+    holonId: string,       // Geographic/noospheric location
+    lensName: string,      // Storage lens
+    accessLevel: 'public' | 'protected' | 'private'
+  }
+}
+```
+
+**ActivityPub Object**:
+```javascript
+{
+  "@context": string | string[],
+  id: string,              // ActivityPub object URI
+  type: string,            // Object type (e.g., "Note", "Article")
+  actor: string,           // Actor URI
+  published: string,       // ISO 8601 timestamp
+  content: string,         // Object content
+  signature: object,       // JSON-LD signature
+  _holosphere: {           // HoloSphere metadata
+    holonId: string,
+    lensName: string,
+    accessLevel: 'public' | 'protected' | 'private'
+  }
+}
+```
+
+**Validation Rules**:
+- Nostr: Signature must verify per NIP-01
+- ActivityPub: JSON-LD signature must verify
+- Access level determines visibility in queries
+
+**State Transitions**:
+- Published: Created with valid signature
+- Federated: Propagated to other holons
+- Deleted: Marked with deletion event (protocol-specific)
+
+**Storage Path**: `{appname}/{holonId}/social/{eventId}` (default lens: "social")
+
+---
+
+## Entity Relationships
+
+```
+Holon (1) ──── (N) Lens
+  │                │
+  │                │
+  │                └──── (N) Data Object
+  │                          │
+  │                          └──── (N) Hologram (references Data Object)
+  │
+  └──── (N) Federation ──── (N) Holon
+                 │
+                 └──── configures ──── (N) Lens
+
+Schema (1) ──── validates ──── (N) Lens
+
+Subscription ──── monitors ──── (1) Holon + (1) Lens
+
+Capability Token ──── grants access to ──── Holon/Lens scope
+
+Social Content ──── stored as ──── Data Object in Lens
+```
+
+---
+
+## Storage Patterns
+
+### Gun Graph Structure
+```
+{appname}
+├── {holonId}
+│   ├── {lensName}
+│   │   ├── {dataId}           # Data objects
+│   │   ├── {dataId}           # More data objects
+│   │   └── _config            # Lens configuration
+│   └── {anotherLens}
+│       └── ...
+├── _federation
+│   └── {federationId}         # Federation configs
+├── _schemas
+│   └── {schemaUri}            # Schema definitions
+└── _capabilities
+    └── {tokenId}              # Capability tokens (optional)
+```
+
+### Path Examples
+```
+// Geographic data
+"myapp/8928342e20fffff/temperature/sensor-001"
+
+// Noospheric data
+"myapp/nostr:~2Ftopic~2F123/discussions/thread-456"
+
+// Federation config
+"myapp/_federation/geo-to-concept-link"
+
+// Schema
+"myapp/_schemas/https:~2F~2Fschema.example.com~2Ftemperature.json"
+```
+
+**Note**: Gun encodes special characters in paths (e.g., `/` → `~2F`, `:` → `~3A`)
+
+---
+
+## Validation Summary
+
+| Entity | Required Fields | Unique Constraints | References |
+|--------|----------------|-------------------|------------|
+| Holon | id, type | id | - |
+| Lens | name | name within holon | Holon |
+| Data Object | id | id within lens | Lens, optionally Schema |
+| Hologram | id, soul, target | id within lens | Data Object (target) |
+| Federation | id, sourceHolon, targetHolon | id | Holon (source & target) |
+| Schema | uri, schema | uri | Lens |
+| Subscription | id, holonId, lensName, callback | - | Holon, Lens |
+| Capability Token | id, issuer, recipient, expires | id | - |
+| Social Content | (protocol-specific) | id/event ID | Data Object, Lens |
+
+---
+
+## Next Steps
+✅ Data model complete with all entities, relationships, and validation rules
+➡️ Proceed to API contract generation