# BZZZ v2: UCXL/UCXI Integration Development Plan ## 1. Executive Summary BZZZ v2 represents a fundamental paradigm shift from a task coordination system using the `bzzz://` protocol to a semantic context publishing system built on the Universal Context eXchange Language (UCXL) and UCXL Interface (UCXI) protocols. This plan outlines the complete transformation of BZZZ into a distributed semantic decision graph that integrates with SLURP for global context management. ### Key Changes: - **Protocol Migration**: `bzzz://` → UCXL addresses (`ucxl://agent:role@project:task/temporal_segment/path`) - **Temporal Navigation**: Support for `~~` (backward), `^^` (forward), `*^` (latest), `*~` (first) - **Decision Publishing**: Agents publish structured decision nodes to SLURP after task completion - **Citation Model**: Academic-style justification chains with bounded reasoning - **Semantic Addressing**: Context as addressable resources with wildcards (`any:any`) ## 2. UCXL Protocol Architecture ### 2.1 Address Format ``` ucxl://agent:role@project:task/temporal_segment/path ``` #### Components: - **Agent**: AI agent identifier (e.g., `gpt4`, `claude`, `any`) - **Role**: Agent role context (e.g., `architect`, `reviewer`, `any`) - **Project**: Project namespace (e.g., `bzzz`, `chorus`, `any`) - **Task**: Task identifier (e.g., `implement-auth`, `refactor`, `any`) - **Temporal Segment**: Time-based navigation (`~~`, `^^`, `*^`, `*~`, ISO timestamps) - **Path**: Resource path within context (e.g., `/decisions/architecture.json`) #### Examples: ``` ucxl://gpt4:architect@bzzz:v2-migration/*^/decisions/protocol-choice.json ucxl://any:any@chorus:*/*~/planning/requirements.md ucxl://claude:reviewer@bzzz:auth-system/2025-08-07T14:30:00/code-review.json ``` ### 2.2 UCXI Interface Operations #### Core Verbs: - **GET**: Retrieve context from address - **PUT**: Store/update context at address - **POST**: Create new context entry - **DELETE**: Remove context - **ANNOUNCE**: Broadcast context availability #### Extended Operations: - **NAVIGATE**: Temporal navigation (`~~`, `^^`) - **QUERY**: Search across semantic dimensions - **SUBSCRIBE**: Listen for context updates ## 3. System Architecture Transformation ### 3.1 Current Architecture (v1) ``` ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ GitHub │ │ P2P │ │ BZZZ │ │ Issues │────│ libp2p │────│ Agents │ │ │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ │ │ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │Task Claims │ │ Pub/Sub │ │ Execution │ │& Assignment │ │ Messaging │ │ & Results │ └─────────────┘ └─────────────┘ └─────────────┘ ``` ### 3.2 New Architecture (v2) ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ UCXL │ │ SLURP │ │ Decision │ │ Validator │────│ Context │────│ Graph │ │ Online │ │ Ingestion │ │ Publishing │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ UCXL │ │ P2P DHT │ │ BZZZ │ │ Browser │────│ Resolution │────│ Agents │ │ Time Machine UI │ │ Network │ │ GPT-4 + MCP │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Temporal │ │ Semantic │ │ Citation │ │ Navigation │ │ Addressing │ │ Justification │ │ ~~, ^^, *^ │ │ any:any │ │ Chains │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` ### 3.3 Component Integration #### UCXL Address Resolution - **Local Cache**: Recent context cached for performance - **DHT Lookup**: Distributed hash table for address resolution - **Temporal Index**: Time-based indexing for navigation - **Semantic Router**: Route requests based on address patterns #### SLURP Decision Publishing - **Decision Schema**: Structured JSON format for decisions - **Justification Chains**: Link to supporting contexts - **Citation Model**: Academic-style references with provenance - **Bounded Reasoning**: Prevent infinite justification loops ## 4. Implementation Plan: 8-Week Timeline ### Week 1-2: Foundation & Protocol Implementation #### Week 1: UCXL Address Parser & Core Types **Deliverables:** - Replace `pkg/protocol/uri.go` with UCXL address parser - Implement temporal navigation tokens (`~~`, `^^`, `*^`, `*~`) - Core UCXL address validation and normalization - Unit tests for address parsing and matching **Key Files:** - `/pkg/protocol/ucxl_address.go` - `/pkg/protocol/temporal_navigator.go` - `/pkg/protocol/ucxl_address_test.go` #### Week 2: UCXI Interface Operations **Deliverables:** - UCXI HTTP server with REST-like operations (GET/PUT/POST/DELETE/ANNOUNCE) - Context storage backend (initially local filesystem) - Temporal indexing for navigation support - Integration with existing P2P network **Key Files:** - `/pkg/ucxi/server.go` - `/pkg/ucxi/operations.go` - `/pkg/storage/context_store.go` - `/pkg/temporal/index.go` ### Week 3-4: DHT & Semantic Resolution #### Week 3: P2P DHT for UCXL Resolution **Deliverables:** - Extend existing libp2p DHT for UCXL address resolution - Semantic address routing (handle `any:any` wildcards) - Distributed context discovery and availability announcements - Address priority scoring for multi-match resolution **Key Files:** - `/pkg/dht/ucxl_resolver.go` - `/pkg/routing/semantic_router.go` - `/pkg/discovery/context_discovery.go` #### Week 4: Temporal Navigation Implementation **Deliverables:** - Time-based context navigation (`~~` backward, `^^` forward) - Snapshot management for temporal consistency - Temporal query optimization - Context versioning and history tracking **Key Files:** - `/pkg/temporal/navigator.go` - `/pkg/temporal/snapshots.go` - `/pkg/storage/versioned_store.go` ### Week 5-6: Decision Graph & SLURP Integration #### Week 5: Decision Node Schema & Publishing **Deliverables:** - Structured decision node JSON schema matching SLURP requirements - Decision publishing pipeline after task completion - Citation chain validation and bounded reasoning - Decision graph visualization data **Decision Node Schema:** ```json { "decision_id": "uuid", "ucxl_address": "ucxl://gpt4:architect@bzzz:v2/*^/architecture.json", "timestamp": "2025-08-07T14:30:00Z", "agent_id": "gpt4-bzzz-node-01", "decision_type": "architecture_choice", "context": { "project": "bzzz", "task": "v2-migration", "scope": "protocol-selection" }, "justification": { "reasoning": "UCXL provides temporal navigation and semantic addressing...", "alternatives_considered": ["custom_protocol", "extend_bzzz"], "criteria": ["scalability", "semantic_richness", "ecosystem_compatibility"] }, "citations": [ { "type": "justified_by", "ucxl_address": "ucxl://any:any@chorus:requirements/*~/analysis.md", "relevance": "high", "excerpt": "system must support temporal context navigation" } ], "impacts": [ { "type": "replaces", "ucxl_address": "ucxl://any:any@bzzz:v1/*^/protocol.go", "reason": "migrating from bzzz:// to ucxl:// addressing" } ] } ``` **Key Files:** - `/pkg/decisions/schema.go` - `/pkg/decisions/publisher.go` - `/pkg/integration/slurp_publisher.go` #### Week 6: SLURP Integration & Context Publishing **Deliverables:** - SLURP client for decision node publishing - Context curation pipeline (decision nodes only, no ephemeral chatter) - Citation validation and loop detection - Integration with existing task completion workflow **Key Files:** - `/pkg/integration/slurp_client.go` - `/pkg/curation/decision_curator.go` - `/pkg/validation/citation_validator.go` ### Week 7-8: Agent Integration & Testing #### Week 7: GPT-4 Agent UCXL Integration **Deliverables:** - Update agent configuration for UCXL operation mode - MCP tools for UCXI operations (GET/PUT/POST/ANNOUNCE) - Context sharing between agents via UCXL addresses - Agent decision publishing after task completion **Key Files:** - `/agent/ucxl_config.go` - `/mcp-server/src/tools/ucxi-tools.ts` - `/agent/context_publisher.go` #### Week 8: End-to-End Testing & Validation **Deliverables:** - Comprehensive integration tests for UCXL/UCXI operations - Temporal navigation testing scenarios - Decision graph publishing and retrieval tests - Performance benchmarks for distributed resolution - Documentation and deployment guides **Key Files:** - `/test/integration/ucxl_e2e_test.go` - `/test/scenarios/temporal_navigation_test.go` - `/test/performance/resolution_benchmarks.go` ## 5. Data Models & Schemas ### 5.1 UCXL Address Structure ```go type UCXLAddress struct { Agent string `json:"agent"` // Agent identifier Role string `json:"role"` // Agent role Project string `json:"project"` // Project namespace Task string `json:"task"` // Task identifier TemporalSegment string `json:"temporal_segment"` // Time navigation Path string `json:"path"` // Resource path Query string `json:"query,omitempty"` // Query parameters Fragment string `json:"fragment,omitempty"` // Fragment identifier Raw string `json:"raw"` // Original address string } ``` ### 5.2 Context Storage Schema ```go type ContextEntry struct { Address UCXLAddress `json:"address"` Content map[string]interface{} `json:"content"` Metadata ContextMetadata `json:"metadata"` Version int64 `json:"version"` CreatedAt time.Time `json:"created_at"` UpdatedAt time.Time `json:"updated_at"` } type ContextMetadata struct { ContentType string `json:"content_type"` Size int64 `json:"size"` Checksum string `json:"checksum"` Provenance string `json:"provenance"` Tags []string `json:"tags"` Relationships map[string]string `json:"relationships"` } ``` ### 5.3 Temporal Index Schema ```go type TemporalIndex struct { AddressPattern string `json:"address_pattern"` Entries []TemporalIndexEntry `json:"entries"` FirstEntry *time.Time `json:"first_entry"` LatestEntry *time.Time `json:"latest_entry"` } type TemporalIndexEntry struct { Timestamp time.Time `json:"timestamp"` Version int64 `json:"version"` Address UCXLAddress `json:"address"` Checksum string `json:"checksum"` } ``` ## 6. Integration with CHORUS Infrastructure ### 6.1 WHOOSH Search Integration - Index UCXL addresses and content for search - Temporal search queries (`find decisions after 2025-08-01`) - Semantic search across agent:role@project:task dimensions - Citation graph search and exploration ### 6.2 SLURP Context Ingestion - Publish decision nodes to SLURP after task completion - Context curation to filter decision-worthy content - Global context graph building via SLURP - Cross-project context sharing and discovery ### 6.3 N8N Workflow Integration - UCXL address monitoring and alerting workflows - Decision node publishing automation - Context validation and quality assurance workflows - Integration with UCXL Validator for continuous validation ## 7. Security & Performance Considerations ### 7.1 Security - **Access Control**: Role-based access to context addresses - **Validation**: Schema validation for all UCXL operations - **Provenance**: Cryptographic signing of decision nodes - **Bounded Reasoning**: Prevent infinite citation loops ### 7.2 Performance - **Caching**: Local context cache with TTL-based invalidation - **Indexing**: Efficient temporal and semantic indexing - **Sharding**: Distribute context storage across cluster nodes - **Compression**: Context compression for storage efficiency ### 7.3 Monitoring - **Metrics**: UCXL operation latency and success rates - **Alerting**: Failed address resolution and publishing errors - **Health Checks**: Context store health and replication status - **Usage Analytics**: Popular address patterns and access patterns ## 8. Migration Strategy ### 8.1 Backward Compatibility - **Translation Layer**: Convert `bzzz://` addresses to UCXL format - **Gradual Migration**: Support both protocols during transition - **Data Migration**: Convert existing task data to UCXL context format - **Agent Updates**: Staged rollout of UCXL-enabled agents ### 8.2 Deployment Strategy - **Blue/Green Deployment**: Maintain v1 while deploying v2 - **Feature Flags**: Enable UCXL features incrementally - **Monitoring**: Comprehensive monitoring during migration - **Rollback Plan**: Ability to revert to v1 if needed ## 9. Success Criteria ### 9.1 Functional Requirements - [ ] UCXL address parsing and validation - [ ] Temporal navigation (`~~`, `^^`, `*^`, `*~`) - [ ] Decision node publishing to SLURP - [ ] P2P context resolution via DHT - [ ] Agent integration with MCP UCXI tools ### 9.2 Performance Requirements - [ ] Address resolution < 100ms for cached contexts - [ ] Decision publishing < 5s end-to-end - [ ] Support for 1000+ concurrent context operations - [ ] Temporal navigation < 50ms for recent contexts ### 9.3 Integration Requirements - [ ] SLURP context ingestion working - [ ] WHOOSH search integration functional - [ ] UCXL Validator integration complete - [ ] UCXL Browser can navigate BZZZ contexts ## 10. Documentation & Training ### 10.1 Technical Documentation - UCXL/UCXI API reference - Agent integration guide - Context publishing best practices - Temporal navigation patterns ### 10.2 Operational Documentation - Deployment and configuration guide - Monitoring and alerting setup - Troubleshooting common issues - Performance tuning guidelines This development plan transforms BZZZ from a simple task coordination system into a sophisticated semantic context publishing platform that aligns with the UCXL ecosystem vision while maintaining its distributed P2P architecture and integration with the broader CHORUS infrastructure.