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:

{
  "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

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

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

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.