bzzz/old-docs/BZZZ_V2_UCXL_DEVELOPMENT_PLAN.md

# 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.