holosphere 2.0.0-alpha1 → 2.0.0-alpha2

package/docs/research.md

@@ -0,0 +1,362 @@
+# Phase 0: Research & Technical Decisions
+
+**Feature**: HoloSphere - Holonic Geospatial Communication Infrastructure
+**Date**: 2025-10-07
+**Status**: Complete
+
+## Overview
+This document captures technical research and decisions for implementing HoloSphere, a JavaScript library combining H3 hexagonal geospatial indexing with GunDB distributed P2P storage. All technical context items have been resolved through specification clarifications and architectural planning.
+
+---
+
+## 1. Core Technology Stack
+
+### Decision: JavaScript (ES2020+) with Node.js 18+ and Modern Browsers
+**Rationale**:
+- JavaScript provides native cross-platform support for both Node.js and browser environments
+- ES2020+ features (optional chaining, nullish coalescing, dynamic imports) improve code quality
+- Node.js 18+ provides stable LTS support with modern ECMAScript features
+- Modern browsers universally support ES6 modules for tree-shaking and efficient bundling
+
+**Alternatives Considered**:
+- TypeScript: Adds type safety but increases build complexity; decided to provide TypeScript definitions (.d.ts) without full TS implementation
+- Rust/WASM: Better performance but increases bundle size and reduces accessibility for JavaScript developers
+
+**Implementation Notes**:
+- Use ESM as primary module format with CommonJS compatibility via build tooling
+- Leverage dynamic imports for lazy loading of crypto operations
+- Target ES2020 for broad compatibility while enabling modern features
+
+---
+
+## 2. Geospatial Indexing
+
+### Decision: h3-js Library for H3 Hexagonal Grid Operations
+**Rationale**:
+- Official Uber H3 JavaScript implementation with proven reliability
+- Supports all 16 resolution levels (0-15) covering global to ~1m² precision
+- Provides efficient parent-child hierarchy operations for scalespace queries
+- Active maintenance and comprehensive documentation
+
+**Alternatives Considered**:
+- Custom H3 implementation: Unnecessary complexity, error-prone
+- S2 geometry: Less mature JavaScript ecosystem, less intuitive hexagonal structure
+- Geohash: Irregular cell boundaries, poor hierarchical properties compared to hexagons
+
+**Key Operations**:
+- `geoToH3()`: Convert lat/lng to H3 cell ID
+- `h3ToParent()`: Navigate up hierarchy for upcast operations
+- `h3ToChildren()`: Navigate down hierarchy for drill-down queries
+- `h3IsValid()`: Validate H3 format (must start with '8', ≥15 chars)
+
+---
+
+## 3. Distributed Storage
+
+### Decision: GunDB with Radisk Adapter
+**Rationale**:
+- GunDB provides decentralized P2P architecture without central servers (constitutional requirement)
+- Built-in real-time synchronization and reactive subscriptions
+- Radisk adapter ensures local-first persistence (IndexedDB in browser, filesystem in Node.js)
+- Eventual consistency with conflict resolution (last-write-wins) aligns with federation requirements
+
+**Alternatives Considered**:
+- OrbitDB: More complex setup, less mature ecosystem
+- Automerge: Excellent CRDT support but larger bundle size, narrower use case
+- Custom WebRTC + IndexedDB: Too much complexity to build from scratch
+
+**Implementation Strategy**:
+- Initialize GunDB with radisk adapter by default in all environments
+- Configure peer connections for distributed sync (optional central relays for NAT traversal)
+- Use Gun's graph structure for natural holon/lens/data hierarchy
+- Path structure: `appname.holon.lens.key` maps to Gun graph nodes
+
+**Radisk Configuration**:
+```javascript
+// Browser
+Gun({ radisk: true })
+
+// Node.js
+Gun({ file: 'data/holosphere' })
+```
+
+---
+
+## 4. Cryptographic Operations
+
+### Decision: @noble/curves for secp256k1 Operations
+**Rationale**:
+- Industry-standard secp256k1 curve (same as Bitcoin, Ethereum, Nostr)
+- Lightweight, audited implementation with no native dependencies
+- Supports signing, verification, key derivation
+- Lazy initialization reduces startup cost when crypto features not immediately needed
+
+**Alternatives Considered**:
+- elliptic.js: Larger bundle size, less actively maintained
+- Native Web Crypto API: Limited to P-256 curve, doesn't support secp256k1
+- noble-secp256k1 (standalone): @noble/curves supersedes this with better ergonomics
+
+**Cryptographic Features**:
+- Content signing (Nostr/ActivityPub protocol support)
+- Capability token generation and verification
+- Password-based holon access control (combined with Gun's SEA module)
+- Lazy loading via dynamic imports to avoid initialization cost
+
+**Bundle Impact**: ~30KB minified+gzipped for secp256k1 operations
+
+---
+
+## 5. Schema Validation
+
+### Decision: Ajv (Another JSON Schema Validator)
+**Rationale**:
+- Industry standard for JSON Schema validation
+- Supports JSON Schema 2019 draft (constitutional requirement)
+- Fast performance through JIT compilation
+- Small bundle size (~50KB minified+gzipped)
+- Supports custom error messages and formats
+
+**Alternatives Considered**:
+- joi: More focused on runtime validation, less standard schema format
+- yup: Similar to joi, lacks JSON Schema compatibility
+- Custom validation: Reinventing the wheel, missing edge cases
+
+**Implementation Strategy**:
+- Cache compiled schemas with 1-hour TTL (configurable)
+- Provide strict mode (blocking) and permissive mode (logging only)
+- Schema storage: Schemas stored in Gun alongside data for decentralized distribution
+- Per-lens schemas with independent validation rules
+
+**Cache Design**:
+```javascript
+const schemaCache = new Map(); // key: lens name, value: { validator, timestamp }
+const CACHE_TTL = 3600000; // 1 hour in milliseconds
+```
+
+---
+
+## 6. Testing Framework
+
+### Decision: Vitest for Unit and Integration Testing
+**Rationale**:
+- Fast, Vite-powered test runner with excellent DX
+- Native ESM support (no transpilation needed)
+- Compatible with Jest API (familiar patterns)
+- Built-in code coverage reporting
+- Supports both Node.js and browser environment testing
+
+**Alternatives Considered**:
+- Jest: Slower, requires transpilation for ESM, heavier dependency footprint
+- Mocha + Chai: Requires more configuration, less integrated tooling
+- uvu: Lightweight but less feature-complete
+
+**Test Organization**:
+- **Unit tests**: One test file per feature module (tests/unit/*.test.js)
+- **Integration tests**: Cross-module scenarios (tests/integration/*.test.js)
+- **Contract tests**: API surface validation (tests/contract/*.test.js)
+
+**Coverage Requirements**: ≥80% line coverage per constitutional mandate for reliability
+
+---
+
+## 7. Build and Distribution
+
+### Decision: Multi-format Build (ESM, CommonJS, CDN)
+**Rationale**:
+- ESM provides tree-shaking for optimal bundle sizes
+- CommonJS ensures compatibility with legacy Node.js tools
+- CDN bundle enables direct browser usage without build tools
+
+**Build Tools**:
+- **Vite**: Fast ESM-native bundler for development and production builds
+- **Rollup** (via Vite): Bundle optimization and multi-format output
+- **terser**: Minification for production builds
+
+**Output Formats**:
+```
+dist/
+├── esm/            # ES modules (primary, tree-shakeable)
+│   └── holosphere.js
+├── cjs/            # CommonJS (Node.js compatibility)
+│   └── holosphere.cjs
+└── cdn/            # UMD bundle with all dependencies
+    └── holosphere.min.js  # <1MB minified+gzipped target
+```
+
+**Package.json Configuration**:
+```json
+{
+  "type": "module",
+  "main": "./dist/cjs/holosphere.cjs",
+  "module": "./dist/esm/holosphere.js",
+  "browser": "./dist/cdn/holosphere.min.js",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/holosphere.js",
+      "require": "./dist/cjs/holosphere.cjs"
+    }
+  }
+}
+```
+
+---
+
+## 8. Performance Optimization Strategies
+
+### Lazy Initialization
+**Decision**: Defer expensive operations until first use
+**Implementation**:
+- Crypto module loaded via dynamic import on first signature operation
+- Schema validator compiled on first validation request
+- H3 library loaded upfront (small footprint, core functionality)
+
+### Caching Strategy
+**Decision**: Multi-level caching with configurable TTLs
+**Caches**:
+1. **Schema cache**: Compiled validators (1-hour TTL)
+2. **Hologram resolution cache**: Recently resolved references (5-minute TTL)
+3. **H3 parent hierarchy cache**: Precomputed parent chains (permanent, small memory footprint)
+
+### Bundle Size Optimization
+**Target**: <1MB minified+gzipped including all dependencies
+**Techniques**:
+- Tree-shakeable ESM exports (only import what you use)
+- Lazy loading of crypto and validation modules
+- Efficient dependency selection (prefer smaller, focused libraries)
+- Code splitting for advanced features (social protocol integrations)
+
+**Estimated Bundle Breakdown**:
+- Core + Spatial: ~100KB
+- GunDB + Radisk: ~400KB
+- H3-js: ~150KB
+- @noble/curves (lazy): ~30KB
+- Ajv (lazy): ~50KB
+- Social protocols (lazy): ~100KB
+- **Total (full feature set)**: ~830KB minified+gzipped ✅
+
+---
+
+## 9. Social Protocol Integration
+
+### Decision: Pluggable Protocol Adapters for Nostr and ActivityPub
+**Rationale**:
+- Unified interface masks protocol differences
+- Extensible design allows future protocol additions
+- Lazy loading keeps base bundle small for users who don't need social features
+
+**Nostr Integration**:
+- Event signing with secp256k1 (NIP-01)
+- Event validation and signature verification
+- Stigmergic access levels via tag filtering
+
+**ActivityPub Integration**:
+- JSON-LD signature verification
+- Actor/Object model mapping to HoloSphere entities
+- HTTP signatures for authenticated federation
+
+**Common Interface**:
+```javascript
+class SocialProtocol {
+  async sign(content, privateKey) { /* ... */ }
+  async verify(content, signature, publicKey) { /* ... */ }
+  toHolosphereFormat(protocolContent) { /* ... */ }
+  fromHolosphereFormat(holosphereContent) { /* ... */ }
+}
+```
+
+---
+
+## 10. Development Workflow
+
+### Decision: Standard npm-based Development Workflow
+**Rationale**:
+- Familiar to JavaScript developers
+- Excellent tooling ecosystem
+- Easy CI/CD integration
+
+**Scripts**:
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage",
+    "lint": "eslint src/**/*.js",
+    "format": "prettier --write src/**/*.js"
+  }
+}
+```
+
+**Quality Gates**:
+- ESLint for code quality
+- Prettier for consistent formatting
+- Vitest coverage threshold (≥80%)
+- Pre-commit hooks via husky (optional)
+
+---
+
+## 11. Cross-Dimensional Federation
+
+### Decision: URI/URL Scheme for Noospheric Holons
+**Rationale**:
+- Extends federation beyond geographic space into conceptual dimensions
+- Enables external namespace integration (e.g., `nostr://topic/123`, `ap://community/abc`)
+- Maintains architectural consistency with geographic holons
+
+**Noospheric Holon Patterns**:
+- Protocol-specific: `nostr://topic/{topicId}`, `ap://community/{communityId}`
+- Custom schemes: `concept://{namespace}/{id}`, `idea://{domain}/{id}`
+- URI validation follows RFC 3986 for consistency
+
+**Federation Behavior**:
+- Same federation mechanics as geographic holons (bidirectional, lens-specific)
+- Cross-dimensional links: Geographic holon ↔ Noospheric holon federation
+- Reference-based propagation (holograms) maintains single source of truth
+
+---
+
+## 12. Error Handling and Observability
+
+### Decision: Structured Logging with JSON Format
+**Rationale**:
+- Machine-parseable logs enable automated monitoring
+- Configurable verbosity levels (ERROR, WARN, INFO, DEBUG)
+- Metrics collection for operation counts and timing
+
+**Logging Interface**:
+```javascript
+logger.error({ event: 'validation_failed', lens: 'events', error: err.message });
+logger.warn({ event: 'schema_cache_miss', lens: 'temperature' });
+logger.info({ event: 'federation_established', from: h3_1, to: h3_2 });
+logger.debug({ event: 'hologram_resolved', id: 'xyz', depth: 2 });
+```
+
+**Metrics**:
+- Operation counters (writes, reads, federations, subscriptions)
+- Timing histograms (validation duration, hologram resolution time)
+- Error rates by operation type
+
+---
+
+## Summary of Resolved Technical Decisions
+
+| Area | Decision | Rationale |
+|------|----------|-----------|
+| **Language** | JavaScript ES2020+ | Cross-platform, modern features, broad ecosystem |
+| **Runtime** | Node.js 18+ & modern browsers | LTS support, universal compatibility |
+| **Geospatial** | h3-js | Official H3 implementation, proven reliability |
+| **Storage** | GunDB + Radisk | P2P architecture, local-first, real-time sync |
+| **Crypto** | @noble/curves (secp256k1) | Industry standard, lightweight, audited |
+| **Validation** | Ajv (JSON Schema 2019) | Standard-compliant, fast, small footprint |
+| **Testing** | Vitest | Fast, ESM-native, excellent DX |
+| **Build** | Vite + Rollup | Multi-format output, tree-shaking, optimization |
+| **Bundle** | <1MB minified+gzipped | Lazy loading, efficient dependencies |
+| **Logging** | Structured JSON | Machine-parseable, multi-level verbosity |
+
+---
+
+## Next Steps
+
+✅ All technical context items resolved - no NEEDS CLARIFICATION remaining
+➡️ Proceed to Phase 1: Design & Contracts

package/docs/spec.md

@@ -0,0 +1,244 @@
+# Feature Specification: HoloSphere - Holonic Geospatial Communication Infrastructure
+
+**Feature Branch**: `001-holosphere-holonic-geospatial`
+**Created**: 2025-10-06
+**Status**: Draft
+**Input**: User description: "HoloSphere Technical Specification & API Reference - A JavaScript library implementing holonic geospatial communication infrastructure by combining H3 hexagonal geospatial indexing with GunDB distributed peer-to-peer storage."
+
+## Execution Flow (main)
+```
+1. Parse user description from Input
+   → If empty: ERROR "No feature description provided"
+2. Extract key concepts from description
+   → Identified: holonic architecture, H3 geospatial indexing, GunDB P2P storage, lenses, federation
+3. For each unclear aspect:
+   → No major ambiguities - technical specification provided
+4. Fill User Scenarios & Testing section
+   → User flows: spatial data management, federation, real-time subscriptions
+5. Generate Functional Requirements
+   → Each requirement must be testable
+6. Identify Key Entities (if data involved)
+7. Run Review Checklist
+   → Spec focuses on user needs, avoids implementation details
+8. Return: SUCCESS (spec ready for planning)
+```
+
+---
+
+## ⚡ Quick Guidelines
+- ✅ Focus on WHAT users need and WHY
+- ❌ Avoid HOW to implement (no tech stack, APIs, code structure)
+- 👥 Written for business stakeholders, not developers
+
+---
+
+## User Scenarios & Testing *(mandatory)*
+
+### Primary User Story
+Developers need to build distributed applications where data is organized by location - both geographic (physical space) and noospheric (conceptual space). Data is stored in holons, categorized into different types (lenses), and can be shared between locations (federation). The system must support multi-scale geographic operations from global to hyper-local (building-level) precision, enable federation across dimensions (linking geographic locations with conceptual spaces), support real-time data synchronization, and work in offline/distributed environments without central servers. While geographic space is inherently federated through spatial hierarchy, the noosphere enables organization by ideas, concepts, and relationships beyond physical constraints.
+
+### Acceptance Scenarios
+
+1. **Given** a geographic coordinate (latitude/longitude) and desired precision level, **When** a user stores data at that location, **Then** the data is stored in the appropriate geographic cell and retrievable by location and data category
+
+2. **Given** data stored in a local geographic area, **When** that area federates with a larger region, **Then** data automatically propagates to the regional level while maintaining a single source of truth
+
+3. **Given** multiple applications using the same geographic coordinate system, **When** they subscribe to changes in a geographic area, **Then** they receive real-time updates when data changes in that location
+
+4. **Given** data with specific validation rules (schema), **When** invalid data is submitted, **Then** the system prevents storage in strict mode or logs warnings in permissive mode
+
+5. **Given** hierarchical geographic areas (city → state → country → global), **When** local data is created, **Then** references automatically propagate up the hierarchy enabling multi-scale queries
+
+6. **Given** social content published in a geographic area, **When** users interact across different protocols (Nostr, ActivityPub), **Then** content is accessible and verifiable across protocol boundaries
+
+7. **Given** data has been written to a holon, **When** the application crashes or browser tab closes before sync, **Then** all confirmed writes are recoverable from radisk persistence on restart with no data loss
+
+8. **Given** a user attempts to delete data created by another user, **When** the delete operation is called without a valid capability token with delete permission, **Then** the system rejects the operation and returns an authorization error
+
+### Edge Cases
+- What happens when network connectivity is lost? (System must continue operating locally with radisk persistence and sync when reconnected)
+- How does the system handle conflicting data in federated holons? (Last-write-wins with GunDB conflict resolution, no data loss)
+- What happens when a hologram reference points to deleted data? (Returns null gracefully)
+- How does the system prevent infinite loops in nested holograms? (Tracks visited references during resolution)
+- What happens when schema validation changes after data is stored? (Existing data grandfathered, new data validated against current schema)
+- What happens if a write operation fails before disk persistence? (Write is retried or error returned; success indicator only after confirmed disk write)
+- What happens during browser tab closure or app crash? (All data persisted to radisk remains intact and recoverable on restart)
+- What happens when someone tries to delete data they don't own? (Delete operation rejected with authorization error unless valid capability token with delete permission provided)
+- What happens when a capability token expires during a delete operation? (Operation rejected; token must be valid at time of execution)
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+**Spatial Data Management**
+- **FR-001**: System MUST convert geographic coordinates (latitude/longitude) to hexagonal grid cells at 16 different resolution levels (global to ~1m²)
+- **FR-002**: System MUST organize all data using geographic location as primary key (holon)
+- **FR-003**: System MUST support hierarchical parent-child relationships between geographic cells automatically
+- **FR-004**: System MUST enable querying all parent cells containing a given location (scalespace)
+
+**Data Organization & Storage**
+- **FR-005**: System MUST support categorical organization of data within each location (lenses)
+- **FR-006**: System MUST store data in a structured path format: application/location/category/identifier (where location can be H3 cell ID or URI/URL for noospheric holons)
+- **FR-007**: System MUST generate unique identifiers automatically if not provided
+- **FR-008**: System MUST support optional metadata including timestamps and resolution tracking
+
+**Schema & Validation**
+- **FR-009**: System MUST support JSON Schema validation (2019 draft) for data categories
+- **FR-010**: System MUST provide both strict validation mode (blocking) and permissive mode (logging only)
+- **FR-011**: System MUST cache schemas with configurable time-to-live for performance
+- **FR-012**: Users MUST be able to define, retrieve, and clear validation schemas per data category
+
+**Reference System (Holograms)**
+- **FR-013**: System MUST support lightweight references (holograms) instead of data duplication
+- **FR-014**: System MUST automatically resolve references to actual data when retrieved
+- **FR-015**: System MUST detect and prevent infinite loops in nested references
+- **FR-016**: System MUST support both automatic and manual reference resolution
+
+**Federation**
+- **FR-017**: System MUST enable bidirectional data sharing between geographic locations
+- **FR-018**: System MUST support selective federation by data category (lens-specific)
+- **FR-019**: System MUST support both inbound (receive) and outbound (send) federation configuration
+- **FR-020**: System MUST propagate data to federated locations automatically by default
+- **FR-021**: System MUST use references (not copies) when propagating to federated locations by default
+- **FR-022**: Users MUST be able to query combined local and federated data with automatic deduplication
+- **FR-023**: System MUST support federation beyond geographic space into conceptual/noospheric dimensions
+- **FR-024**: System MUST enable cross-dimensional linking where holons can federate across both spatial and non-spatial organizational schemes
+
+**Hierarchical Aggregation**
+- **FR-025**: System MUST support automatic propagation of data to parent geographic cells (upcast)
+- **FR-026**: System MUST support aggregation operations (summarize, aggregate, concatenate) across hierarchy levels
+- **FR-027**: System MUST limit hierarchical propagation to configurable maximum levels
+
+**Real-time Subscriptions**
+- **FR-028**: System MUST enable real-time subscriptions to changes in specific location/category combinations
+- **FR-029**: System MUST invoke callbacks when subscribed data changes
+- **FR-030**: Users MUST be able to unsubscribe from real-time updates
+- **FR-031**: System MUST support federation-specific subscriptions with lens filtering and throttling
+
+**Distributed Storage**
+- **FR-032**: System MUST operate in peer-to-peer mode without requiring central servers
+- **FR-033**: System MUST support local-first operation with automatic synchronization
+- **FR-034**: System MUST persist data locally by default using GunDB with radisk storage
+- **FR-035**: System MUST support configurable peer connections for distributed sync
+- **FR-069**: System MUST use radisk storage adapter in both npm package and CDN bundle versions
+- **FR-070**: System MUST ensure write operations are persisted to disk before returning success
+- **FR-071**: System MUST prevent data loss through automatic conflict resolution and synchronization
+- **FR-072**: System MUST maintain data integrity during network partitions and offline periods
+
+**Access Control & Security**
+- **FR-036**: System MUST support optional password-based access control per geographic location
+- **FR-037**: System MUST support cryptographic signatures for content verification to prevent data tampering
+- **FR-038**: System MUST issue and verify capability tokens for authorization
+- **FR-039**: System MUST support stigmergic (indirect coordination) access control levels
+- **FR-066**: System MUST enforce capability token expiration to prevent unauthorized access
+- **FR-067**: System MUST prevent replay attacks on signed content and capability tokens
+- **FR-068**: System MUST provide basic DoS protection through rate limiting and resource constraints
+- **FR-074**: System MUST require valid capability token with delete permission to delete data created by others
+- **FR-075**: System MUST allow data creators to delete their own data without additional authorization
+- **FR-076**: System MUST verify data ownership or capability token before processing delete operations
+- **FR-077**: System MUST reject delete operations that lack proper authorization with clear error messages
+
+**Cross-Protocol Support**
+- **FR-040**: System MUST unify social protocols (Nostr, ActivityPub) under common interface
+- **FR-041**: System MUST validate protocol-specific content formats
+- **FR-042**: System MUST verify cryptographic signatures for social content
+- **FR-043**: Users MUST be able to filter social content by protocol and access level
+
+**Global Data Operations**
+- **FR-044**: System MUST support non-location-specific data storage (global tables)
+- **FR-045**: System MUST provide consistent CRUD operations for both location-specific and global data
+
+**Performance & Efficiency**
+- **FR-046**: System MUST initialize cryptographic components lazily (on first use)
+- **FR-047**: System MUST cache frequently accessed data with configurable expiration
+- **FR-048**: System MUST support batch operations to reduce network overhead
+- **FR-049**: System MUST provide browser bundle size < 1 MB minified+gzipped including all dependencies
+- **FR-061**: System MUST NOT enforce hard limits on data volume per holon (bounded only by available storage and network capacity)
+
+**Error Handling & Reliability**
+- **FR-050**: System MUST return boolean success indicators for state-changing operations
+- **FR-051**: System MUST provide detailed error messages for federation failures
+- **FR-052**: System MUST handle connection failures with retry logic
+- **FR-053**: System MUST gracefully degrade when optional features are unavailable
+
+**Observability**
+- **FR-062**: System MUST provide structured logging in JSON format
+- **FR-063**: System MUST capture metrics for operation counts and timing
+- **FR-064**: System MUST support configurable log verbosity levels
+- **FR-065**: System MUST log all errors, warnings, and significant state transitions
+
+**Multi-Platform Support**
+- **FR-054**: System MUST operate in Node.js server environments with radisk persistence
+- **FR-055**: System MUST operate in browser environments with radisk persistence
+- **FR-056**: System MUST be distributable via CDN for direct browser usage with radisk included
+- **FR-057**: System MUST support both CommonJS and ES Module imports
+- **FR-073**: Both npm and CDN distributions MUST include GunDB radisk adapter for data persistence
+
+**Testing & Quality**
+- **FR-058**: Every feature MUST have dedicated unit tests covering all core functionality
+- **FR-059**: System MUST maintain test coverage for all public API methods
+- **FR-060**: Tests MUST be organized by feature module with clear test isolation
+
+### Key Entities
+
+- **Holon**: Geographic location represented as H3 hexagonal cell OR conceptual location in noospheric space identified by URI/URL scheme (e.g., "nostr://topic/123", "ap://community/abc"); contains multiple lenses; supports hierarchical parent-child relationships (resolutions 0-15 for geographic); can be federated with other holons across both spatial and noospheric dimensions
+
+- **Lens**: Data category within a holon (e.g., temperature, events, social content, ideas, concepts); has optional validation schema; has independent federation configuration; contains key-value data pairs; enables cross-dimensional organization
+
+- **Data Object**: Individual data record within a lens; has required unique ID; has optional custom fields; has optional metadata (_meta with timestamp, resolution tracking); follows path structure: appname/holon/lens/key
+
+- **Hologram**: Lightweight reference to data stored elsewhere; contains ID and soul path; automatically resolves to actual data; prevents data duplication; tracks visited references to prevent loops
+
+- **Federation**: Bidirectional relationship between holons; has inbound lens configuration (what to receive); has outbound lens configuration (what to send); supports selective data sharing; uses holograms for propagation; enables cross-dimensional linking between geographic and noospheric holons
+
+- **Schema**: JSON Schema (2019 draft) validation rules for a lens; cached with TTL; enforced in strict mode, logged in permissive mode; independently defined per lens
+
+- **Subscription**: Real-time change notification for holon/lens combination; invokes callback on data changes; provides unsubscribe mechanism; supports throttling and filtering
+
+- **Capability Token**: Cryptographic authorization token; grants specific permissions (read, write, delete, modify); has expiration timestamp; has designated recipient; uses Nostr signatures for verification; transferable between parties; required for delete operations on data created by others
+
+- **Social Content**: Protocol-agnostic social data; supports Nostr and ActivityPub native formats; has cryptographic signature; has stigmergic access level; stored in holons with geographic context
+
+---
+
+## Clarifications
+
+### Session 2025-10-07
+- Q: How should noospheric (conceptual) holons be identified and structured? → A: URI/URL scheme allowing external namespace integration (e.g., "nostr://topic/123", "ap://community/abc")
+- Q: What are the performance targets for browser bundle size? → A: < 1 MB minified+gzipped (comprehensive, including all dependencies)
+- Q: What are the expected data scale limits per holon? → A: No enforced limits (bounded only by available storage and network capacity)
+- Q: What observability features must be provided for monitoring and debugging? → A: Standard: Structured logging (JSON), metrics (operation counts/timing), configurable verbosity
+- Q: What security threats should the system defend against? → A: Standard: Unauthorized data access, data tampering, replay attacks, token expiration enforcement, basic DoS protection
+
+---
+
+## Review & Acceptance Checklist
+*GATE: Automated checks run during main() execution*
+
+### Content Quality
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+### Requirement Completeness
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+---
+
+## Execution Status
+*Updated by main() during processing*
+
+- [x] User description parsed
+- [x] Key concepts extracted
+- [x] Ambiguities marked
+- [x] User scenarios defined
+- [x] Requirements generated
+- [x] Entities identified
+- [x] Review checklist passed
+
+---