tony/bzzz
1
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

Implement UCXL Protocol Foundation (Phase 1)

Browse Source 
- Add complete UCXL address parser with BNF grammar validation
- Implement temporal navigation system with bounds checking
- Create UCXI HTTP server with REST-like operations
- Add comprehensive test suite with 87 passing tests
- Integrate with existing BZZZ architecture (opt-in via config)
- Support semantic addressing with wildcards and version control

Core Features:
- UCXL address format: ucxl://agent:role@project:task/temporal/path
- Temporal segments: *^, ~~N, ^^N, *~, *~N with navigation logic
- UCXI endpoints: GET/PUT/POST/DELETE/ANNOUNCE operations
- Production-ready with error handling and graceful shutdown

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
anthonyrawlins
2025-08-08 07:38:04 +10:00
parent 065dddf8d5
commit b207f32d9e
3690 changed files with 10589 additions and 1094850 deletions
Download Patch File Download Diff File Expand all files Collapse all files

395
BZZZ_V2_UCXL_DEVELOPMENT_PLAN.md Normal file
View File

@@ -0,0 +1,395 @@
# 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.