holosphere 2.0.0-alpha0 → 2.0.0-alpha10

package/CHANGELOG.md

@@ -0,0 +1,473 @@
+# Changelog
+
+All notable changes to HoloSphere are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+# HoloSphere 2.0 (Complete Rewrite)
+
+## [2.0.0-alpha10] - 2025-12-22
+
+### Added
+- **Optimistic Updates**: All write operations (`write`, `update`, `delete`) are now non-blocking by default
+  - Data is cached immediately for instant UI responsiveness (~1ms return time)
+  - Background sync to relays ensures durability with automatic retry
+  - New `blocking: true` option for operations requiring relay confirmation
+  - Write cache ensures reads return fresh data immediately after writes
+  - Delete cache prevents stale data from being returned after deletions
+- **Cache-First Reads**: `read()` now checks local cache before storage for optimistic consistency
+
+### Changed
+- `write()` returns immediately after caching (was: waited for relay sync)
+- `update()` returns immediately after caching merged data
+- `delete()` returns immediately after cache invalidation
+- `read()` checks write cache → delete cache → storage (in that order)
+
+### Migration Notes
+- **Default behavior changed**: Writes are now optimistic (non-blocking)
+- For operations requiring confirmation, add `{ blocking: true }`:
+  ```javascript
+  await hs.write(holonId, 'lens', data, { blocking: true });
+  ```
+- Subscription callbacks now fire after relay sync (use blocking writes if immediate callbacks needed)
+
+---
+
+## [2.0.0-alpha8] - 2025-12-15
+
+### Added
+- **CDN Build Support**: New browser-ready bundle for direct script tag inclusion
+- **Widget Examples**: Ready-to-use widget examples for quick integration
+
+### Fixed
+- `skipPropagation` option for `federateHolon` to control hologram propagation
+- Null data handling in Nostr backend for edge cases
+
+---
+
+## [2.0.0-alpha7] - 2025-12-14
+
+### Fixed
+- **GunDB Backend Hologram Support**: Proper deserialization and count logic for holograms
+- Optimized Gun backend with count-based collection for `readAll` operations
+
+---
+
+## [2.0.0-alpha5] - 2025-12-12
+
+### Added
+- **Smart Contracts Integration**: Complete Ethereum contract system for fractal fund distribution
+  - Splitter, Managed, Zoned, Appreciative, and Bundle contract types
+  - Multi-chain support (Ethereum, Polygon, Arbitrum, Base, Optimism)
+  - Contract deployment, operations, and event listening
+- **Unified Storage Layer**: Abstract backend interface supporting multiple storage technologies
+- **TypeScript Type Definitions**: Full TypeScript support with comprehensive type definitions
+
+### Changed
+- **Nostr Client Optimization**: Long-lived subscriptions, query deduplication, and intelligent caching
+- Improved npm package structure with proper gitignore and npmignore
+
+### Fixed
+- Federation handshake protocol improvements
+
+---
+
+## [2.0.0-alpha0] - 2025-12-05
+
+### Added
+- **AI Module**: Comprehensive AI integration using OpenAI
+  - LLM service with summarization, analysis, categorization, translation
+  - Vector embeddings and semantic search
+  - Multi-perspective Council for balanced decision-making
+  - Natural language query interface
+  - Schema extraction from unstructured text
+  - Fuzzy JSON operations (semantic merge, diff, union)
+  - Spatial analysis and H3 geospatial AI
+  - Task breakdown with hierarchical decomposition
+  - Relationship discovery and federation advisor
+- **True Local-First Architecture**: Guaranteed delivery with outbox queue and sync service
+- **Circular Hologram Prevention**: Safeguards against infinite reference loops
+- **Comprehensive Capability Tests**: Full test suite for capability-based authorization
+
+### Changed
+- Major project restructure with modular organization
+- Enhanced documentation for local-first architecture
+
+---
+
+## [2.0.0-alpha] - 2025-12-04
+
+### Added
+- **Capability Tokens for Federation**: Secure cross-HoloSphere authorization
+  - Time-limited capability tokens with cryptographic signatures
+  - Scope-based permissions (holon, lens, data level)
+  - Inbound/outbound capability registry
+- **Multi-HoloSphere Support**: Federation between multiple HoloSphere instances
+- **FOSDEM 2025 Proposal**: Local-first devroom talk proposal
+
+### Documentation
+- Added LOCALFIRST.md with honest assessment of local-first architecture
+- Updated VIBE.md to clarify actual vs aspirational architecture
+- Added npm.flow.fund intentions for spatial value flows
+
+---
+
+## [2.0.0-dev] - 2025-11-26
+
+### Added
+- **Working Hologram Federation on Nostr**: First successful cross-holon data references
+- **Cached Write Returns**: Immediate consistency for newly written data
+
+### Changed
+- Improved delete operation semantics with tombstone markers
+- Fixed hologram resolution and cross-reference handling
+
+---
+
+## [2.0.0-dev] - 2025-11-22
+
+### Added
+- **Nostr Subscription Improvements**: Better startup logging and subscription handling
+- **Global Write API**: Consistent API for non-holon-specific data storage
+
+### Fixed
+- Global write API inconsistencies resolved
+- Data import functionality improvements
+
+---
+
+## [2.0.0-dev] - 2025-11-17
+
+### Added
+- **Nostr-based Prediction Market**: Quest coordination using prediction markets
+  - Interactive web demo for prediction market visualization
+  - Polygon-based hexagon selection for geographic predictions
+- **Hologram Specification Compliance**: Full compliance with hologram reference spec
+- **Polygon-Based Federation**: Geographic region selection for federation
+
+### Changed
+- Updated VIBE.md to reflect Nostr integration architecture
+- Removed deprecated demo files in favor of new prediction market demo
+
+---
+
+## [2.0.0-dev] - 2025-11-10
+
+### Added
+- **Comprehensive Documentation**: Full API documentation and code cleanup
+- **Test Suite**: Working test infrastructure
+
+### Changed
+- Major code cleanup and organization
+
+---
+
+## [2.0.0-dev] - 2025-11-08
+
+### Added
+- **Working Prototype**: First functional version of HoloSphere 2.0
+- **NPM Package**: Initial package.json configuration
+
+---
+
+## [2.0.0-dev] - 2025-10-30
+
+### Added
+- **Global Functions**: Non-location-specific data operations
+  - `writeGlobal`, `readGlobal`, `updateGlobal`, `deleteGlobal`
+  - Support for application-wide data (schemas, configs, preferences)
+
+---
+
+## [2.0.0-dev] - 2025-10-17
+
+### Added
+- **First Version of 2.0**: Initial implementation of HoloSphere 2.0 architecture
+  - Complete rewrite with Nostr as primary storage backend
+  - New modular architecture with pluggable backends
+
+---
+
+## [2.0.0-dev] - 2025-10-06
+
+### Added
+- **Initial Commit**: Project scaffolding from Specify template
+- Beginning of HoloSphere 2.0 development
+
+---
+
+# HoloSphere 1.x (Original GunDB Implementation)
+
+## [1.1.18] - 2025-11-17
+
+### Added
+- **Permaculture Flower Ecosystem**: Web examples for 14 ecosystem projects
+  - Interactive Mapbox + H3 demo pages
+  - Unique landing pages with professional imagery
+  - Federation system binding ecosystem together
+- **Vibe Coding Instructions**: Development guidelines documentation
+
+---
+
+## [1.1.13] - 2025-08-07
+
+### Changed
+- **Switched to Radisk**: Improved persistence with radisk storage
+
+---
+
+## [1.1.12] - 2025-06-15
+
+### Added
+- **Automatic H3 Parent Propagation**: Data automatically propagates to parent hexagons
+- **CDN Bundle**: HTML CDN bundle with usage example
+
+### Fixed
+- Hex detection for parent propagation
+- Hologram propagation and deletion edge cases
+
+---
+
+## [1.1.11] - 2025-04-21
+
+### Added
+- **Version Function**: Programmatic version checking
+- **Gun Options in Constructor**: Pass custom Gun configuration options
+
+### Fixed
+- Various stability improvements
+- Authentication flow refinements
+
+---
+
+## [1.1.10] - 2025-04-05
+
+### Added
+- **Holograms**: Lightweight cross-holon data references
+  - Hologram lists attached to target data
+  - `isHologram` metadata for resolved references
+- **Put to Hologram**: Writing to a hologram stores in original location
+- **Lens-Aware Federation**: Federation propagation checks lens configuration
+
+### Fixed
+- Auth subscriptions and deletes
+- Federation and reference resolution
+- Reference cycle detection (checks previously visited locations)
+
+### Changed
+- Removed legacy federation logic
+- Refactored holosphere.js into multiple files for maintainability
+
+---
+
+## [1.1.9] - 2025-04-02
+
+### Changed
+- **Refactored getAll/getGlobal**: Better handling for user authentication
+- **Improved API Consistency**: Unified promise handling across functions
+- **Enhanced put/get Logic**: Better password handling
+
+### Removed
+- `.env` files and Babel dependencies (cleanup)
+
+---
+
+## [1.1.6] - 2025-03-19
+
+### Added
+- **Federation with References**: Reworked federation system using reference-based approach
+- **Bot Integration**: Federation functionality for HolonsBot integration
+- **Release Candidate 1**: First production-ready release
+
+### Changed
+- Updated READMEs and TypeScript typings
+
+---
+
+## [1.1.5] - 2025-03-17
+
+### Added
+- **Spaces**: First implementation of isolated data spaces
+- **New Authentication System**: Reworked auth with improved security
+
+### Fixed
+- Subscription and schema retrieval
+- Compute function improvements
+- Test infrastructure (federation + spaces auth)
+
+---
+
+## [1.1.0] - 2025-02-13
+
+### Added
+- **All Tests Passing**: Complete test coverage
+- **Spaces Authentication**: Combined federation and spaces auth testing
+
+### Fixed
+- Testing infrastructure improvements
+
+---
+
+## [1.0.5] - 2025-01-31
+
+### Added
+- **Safety Fixes**: Additional validation and error handling
+- **Cast/Publish Fixes**: Improved data publishing workflow
+
+---
+
+## [1.0.4] - 2024-12-31
+
+### Added
+- **First Working Publish/Casting**: Data publishing to network
+- **Fixed getAllGlobal**: Corrected global data retrieval
+
+---
+
+## [1.0.3] - 2024-12-18
+
+### Added
+- **TypeScript Migration**: Switched everything to TypeScript
+- **Parse Function**: Reintroduced data parsing functionality
+
+### Fixed
+- JavaScript compilation issues
+- Minor TypeScript configuration issues
+
+---
+
+## [1.0.2] - 2024-12-08
+
+### Changed
+- **Naming Convention Cleanup**: Removed voting, cleaned up APIs
+- **All Tests Running**: Complete test suite execution
+
+---
+
+## [1.0.1] - 2024-11-22
+
+### Added
+- **Global Functions**: Application-wide data operations
+  - `writeGlobal`, `readGlobal`, `updateGlobal`, `deleteGlobal`
+- **Test Suite**: Initial test coverage
+- **TypeScript Types**: Type definitions for API
+
+### Changed
+- Updated README documentation
+
+---
+
+## [1.0.0] - 2024-10-21
+
+### Added
+- **Initial Release**: First version of HoloSphere
+- **GunDB Integration**: Real-time P2P data synchronization
+- **H3 Hexagonal Indexing**: Geographic data organization
+- **Basic CRUD Operations**: `put`, `get`, `getAll`, `delete`
+- **Reference System**: Cross-holon data references
+- **MIT License**: Open source licensing
+
+---
+
+# Architecture Overview
+
+## Core Concepts
+
+- **Holons**: Geographic locations identified by H3 hexagonal indexes (16 resolution levels)
+- **Lenses**: Named data collections within holons (e.g., "projects", "events", "quests")
+- **Holograms**: Lightweight references to data in other holons (federated pointers)
+- **Capabilities**: Cryptographic tokens for authorization across federated instances
+
+## Storage Backends (2.0+)
+
+| Backend | Protocol | Use Case |
+|---------|----------|----------|
+| Nostr | NIP-01 events | Decentralized P2P storage |
+| GunDB | CRDT + WebRTC | Real-time collaboration |
+| ActivityPub | Fediverse | Social federation |
+
+## Smart Contracts (2.0+)
+
+| Contract | Purpose |
+|----------|---------|
+| Splitter | Internal/external fund split with fractal nesting |
+| Managed | Appreciation-based distribution |
+| Zoned | Tier-based zone rewards |
+| Appreciative | Peer-to-peer appreciation |
+| Bundle | All-in-one 2-way split with steepness |
+
+---
+
+# Migration Notes
+
+## From 1.x to 2.0
+
+HoloSphere 2.0 is a complete rewrite with breaking changes:
+
+1. **Storage Layer**: Now uses pluggable backends (Nostr, GunDB, ActivityPub)
+2. **Federation**: New capability-based authorization system
+3. **API Changes**: Unified async/await API across all operations
+4. **AI Integration**: Optional OpenAI-powered features
+5. **Package Name**: Published as `holosphere@next` on npm
+
+### API Changes
+
+```javascript
+// 1.x style (GunDB only)
+const hs = new HoloSphere({ gun: gunInstance });
+hs.put(holon, lens, data, callback);
+hs.get(holon, lens, id, callback);
+
+// 2.0 style (pluggable backends)
+const hs = new HoloSphere({
+  appName: 'myapp',
+  backend: 'nostr', // or 'gundb', 'activitypub'
+  relays: ['wss://relay.example.com']
+});
+await hs.init();
+await hs.write(holon, lens, data);
+const result = await hs.read(holon, lens, id);
+```
+
+### Key Differences
+
+| Feature | 1.x | 2.0 |
+|---------|-----|-----|
+| Storage | GunDB only | Nostr, GunDB, ActivityPub |
+| API Style | Callbacks | Async/await |
+| Federation | Reference-based | Capability tokens |
+| AI Features | None | Full OpenAI integration |
+| Smart Contracts | None | Ethereum multi-chain |
+
+---
+
+# Contributors
+
+- Roberto Valenti ([@liminalvillage](https://github.com/liminalvillage))
+- Claude (AI pair programmer)
+- qbfrank
+- polux0
+
+---
+
+[2.0.0-alpha8]: https://github.com/liminalvillage/holosphere/compare/v2.0.0-alpha7...v2.0.0-alpha8
+[2.0.0-alpha7]: https://github.com/liminalvillage/holosphere/compare/v2.0.0-alpha5...v2.0.0-alpha7
+[2.0.0-alpha5]: https://github.com/liminalvillage/holosphere/compare/v2.0.0-alpha0...v2.0.0-alpha5
+[2.0.0-alpha0]: https://github.com/liminalvillage/holosphere/compare/v2.0.0-alpha...v2.0.0-alpha0
+[1.1.18]: https://github.com/liminalvillage/holosphere/compare/v1.1.12...v1.1.18
+[1.1.12]: https://github.com/liminalvillage/holosphere/compare/v1.1.11...v1.1.12
+[1.1.11]: https://github.com/liminalvillage/holosphere/compare/v1.1.10...v1.1.11
+[1.1.10]: https://github.com/liminalvillage/holosphere/compare/v1.1.9...v1.1.10
+[1.1.9]: https://github.com/liminalvillage/holosphere/compare/v1.1.6...v1.1.9
+[1.1.6]: https://github.com/liminalvillage/holosphere/compare/v1.1.5...v1.1.6
+[1.1.5]: https://github.com/liminalvillage/holosphere/compare/v1.1.0...v1.1.5
+[1.1.0]: https://github.com/liminalvillage/holosphere/compare/v1.0.5...v1.1.0
+[1.0.5]: https://github.com/liminalvillage/holosphere/compare/v1.0.4...v1.0.5
+[1.0.4]: https://github.com/liminalvillage/holosphere/compare/v1.0.3...v1.0.4
+[1.0.3]: https://github.com/liminalvillage/holosphere/compare/v1.0.2...v1.0.3
+[1.0.2]: https://github.com/liminalvillage/holosphere/compare/v1.0.1...v1.0.2
+[1.0.1]: https://github.com/liminalvillage/holosphere/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/liminalvillage/holosphere/releases/tag/v1.0.0