CHORUS/docs/comprehensive/packages/ucxl.md

UCXL Package Documentation

Overview

The UCXL (Universal Collaboration eXchange Locator) package provides a comprehensive addressing scheme for CHORUS agents to reference, version, and navigate immutable decisions and content across the distributed system. UCXL addresses function similarly to URLs but are specifically designed for temporal navigation, role-based collaboration, and content-addressable storage within the CHORUS ecosystem.

Table of Contents

• UCXL Address Format
• Temporal Navigation
• Decision Publishing
• Content Addressing
• DHT Integration
• Response Codes
• API Reference
• Usage Examples

UCXL Address Format

Address Structure

UCXL addresses follow a standardized URI format:

ucxl://agent:role@project:task/temporal_segment/path

Components

Component	Description	Validation	Examples
agent	Agent identifier or "any" for wildcard	Alphanumeric, hyphens, underscores	agent1, chorus-bot, any
role	Agent role in the project	Alphanumeric, hyphens, underscores	developer, tester, admin, any
project	Project identifier	Alphanumeric, hyphens, underscores	project1, chorus, any
task	Task identifier	Alphanumeric, hyphens, underscores	task1, build, deploy, any
temporal_segment	Version navigation	See Temporal Navigation	*^, *~5, ~~3, ^^2
path	Optional resource path	Alphanumeric, slashes, dots, hyphens	config.json, src/main.go

Example Addresses

// Latest version of a decision
"ucxl://agent1:developer@chorus:build/*^"

// Specific version 5 with file path
"ucxl://agent2:tester@project1:test/*~5/results.json"

// Navigate 3 versions backward
"ucxl://bot:admin@system:backup/~~3"

// Navigate 2 versions forward
"ucxl://ai:researcher@analysis:data/^^2/results"

// Wildcard matching - any agent in developer role
"ucxl://any:developer@chorus:any/*^"

Temporal Navigation

Temporal Segment Types

UCXL supports four types of temporal navigation:

1. Latest Version (*^)

Navigates to the most recent version of the content.

address := "ucxl://agent:role@project:task/*^"
// Always retrieves the latest decision

2. Any Version (*~)

Matches any version of the content (useful for wildcard queries).

address := "ucxl://agent:role@project:task/*~"
// Can retrieve any version that matches other criteria

3. Specific Version (*~N)

References a specific version number (zero-indexed).

address := "ucxl://agent:role@project:task/*~5"
// Retrieves exactly version 5

4. Relative Navigation

Navigate relative to the current position:

Backward (~~N): Move N versions backward

address := "ucxl://agent:role@project:task/~~3"
// Navigate 3 versions backward from current

Forward (^^N): Move N versions forward

address := "ucxl://agent:role@project:task/^^2"
// Navigate 2 versions forward from current

Temporal Navigator

The TemporalNavigator type manages version traversal with history tracking:

// Create navigator with max version
navigator := ucxl.NewTemporalNavigator(10) // Versions 0-10

// Navigate to latest
result, err := navigator.Navigate(ucxl.TemporalSegment{
    Type: ucxl.TemporalLatest,
})

// Navigate backward 3 versions
result, err := navigator.Navigate(ucxl.TemporalSegment{
    Type:      ucxl.TemporalRelative,
    Direction: ucxl.DirectionBackward,
    Count:     3,
})

// Check current position
current := navigator.GetCurrentVersion() // Returns: 7

// Validate before navigation
segment := ucxl.TemporalSegment{
    Type:      ucxl.TemporalRelative,
    Direction: ucxl.DirectionBackward,
    Count:     20,
}
err := navigator.ValidateTemporalSegment(segment)
// Returns error: would go before version 0

Navigation History

The navigator maintains a complete history of temporal traversals:

// Get navigation history
history := navigator.GetHistory()
for _, step := range history {
    fmt.Printf("From %d to %d via %s: success=%v\n",
        step.FromVersion,
        step.ToVersion,
        step.Operation,
        step.Success,
    )
}

// Get last navigation
lastStep := navigator.GetLastNavigation()
if lastStep != nil {
    fmt.Printf("Last navigation: %s\n", lastStep.Operation)
}

// Clear history
navigator.ClearHistory()

// Reset to latest version
navigator.Reset()

Version Metadata

Associate metadata with specific versions:

// Set version information
navigator.SetVersionInfo(5, ucxl.VersionInfo{
    Version:     5,
    Created:     time.Now(),
    Author:      "agent-007",
    Description: "Fixed critical bug in authentication",
    Tags:        []string{"bugfix", "security"},
})

// Retrieve version info
info, exists := navigator.GetVersionInfo(5)
if exists {
    fmt.Printf("Version %d by %s: %s\n",
        info.Version,
        info.Author,
        info.Description,
    )
}

// Get all version metadata
allVersions := navigator.GetAllVersions()

Decision Publishing

DecisionPublisher

The DecisionPublisher handles publishing immutable task completion decisions to encrypted DHT storage. Decisions are content-addressed using SHA-256 hashing and stored with role-based encryption.

// Create decision publisher
publisher := ucxl.NewDecisionPublisher(
    ctx,
    config,
    dhtStorage,
    "node-001",
    "chorus-agent",
)

TaskDecision Schema

type TaskDecision struct {
    Agent         string                 `json:"agent"`
    Role          string                 `json:"role"`
    Project       string                 `json:"project"`
    Task          string                 `json:"task"`
    Decision      string                 `json:"decision"`
    Context       map[string]interface{} `json:"context"`
    Timestamp     time.Time              `json:"timestamp"`
    Success       bool                   `json:"success"`
    ErrorMessage  string                 `json:"error_message,omitempty"`
    FilesModified []string               `json:"files_modified,omitempty"`
    LinesChanged  int                    `json:"lines_changed,omitempty"`
    TestResults   *TestResults           `json:"test_results,omitempty"`
    Dependencies  []string               `json:"dependencies,omitempty"`
    NextSteps     []string               `json:"next_steps,omitempty"`
}

type TestResults struct {
    Passed      int      `json:"passed"`
    Failed      int      `json:"failed"`
    Skipped     int      `json:"skipped"`
    Coverage    float64  `json:"coverage,omitempty"`
    FailedTests []string `json:"failed_tests,omitempty"`
}

Publishing Decisions

Basic Task Completion

err := publisher.PublishTaskCompletion(
    "build-project",
    true,
    "Successfully built project with no errors",
    []string{"src/main.go", "pkg/api/handler.go"},
)

Code Decision with Test Results

testResults := &ucxl.TestResults{
    Passed:   42,
    Failed:   0,
    Skipped:  3,
    Coverage: 87.5,
}

err := publisher.PublishCodeDecision(
    "implement-auth",
    "Implemented JWT authentication with refresh tokens",
    []string{
        "pkg/auth/jwt.go",
        "pkg/auth/middleware.go",
        "pkg/auth/jwt_test.go",
    },
    345, // lines changed
    testResults,
    []string{"github.com/golang-jwt/jwt/v5"},
)

Architectural Decision

err := publisher.PublishArchitecturalDecision(
    "choose-database",
    "Selected PostgreSQL for primary database",
    "PostgreSQL provides ACID compliance, JSON support, and excellent Go libraries",
    []string{
        "MongoDB - considered but lacking strong consistency",
        "MySQL - considered but PostgreSQL has better JSON support",
    },
    []string{
        "Must implement connection pooling",
        "Consider read replicas for scaling",
        "Plan migration strategy from current SQLite",
    },
    []string{
        "Set up PostgreSQL cluster",
        "Implement database migrations",
        "Update connection configuration",
    },
)

Custom Decision

decision := &ucxl.TaskDecision{
    Task:     "security-audit",
    Decision: "Completed security audit - no critical findings",
    Success:  true,
    Context: map[string]interface{}{
        "decision_type":    "security",
        "audit_scope":      "authentication",
        "tools_used":       []string{"gosec", "trivy"},
        "findings_count":   12,
        "critical_count":   0,
        "high_count":       2,
        "medium_count":     5,
        "low_count":        5,
    },
}

err := publisher.PublishTaskDecision(decision)

Querying Decisions

Search Recent Decisions

// Query decisions from last 24 hours
decisions, err := publisher.QueryRecentDecisions(
    "agent-007",              // agent filter
    "developer",              // role filter
    "chorus",                 // project filter
    10,                       // limit
    time.Now().Add(-24*time.Hour), // since
)

for _, metadata := range decisions {
    fmt.Printf("Decision: %s (created: %s)\n",
        metadata.Address,
        metadata.CreatedAt,
    )
}

Retrieve Decision Content

// Get specific decision
decision, err := publisher.GetDecisionContent(
    "ucxl://agent-007:developer@chorus:build/*^",
)

if err != nil {
    log.Fatal(err)
}

fmt.Printf("Task: %s\n", decision.Task)
fmt.Printf("Success: %v\n", decision.Success)
fmt.Printf("Decision: %s\n", decision.Decision)
if decision.TestResults != nil {
    fmt.Printf("Tests: %d passed, %d failed\n",
        decision.TestResults.Passed,
        decision.TestResults.Failed,
    )
}

Decision Subscriptions

Subscribe to new decisions in real-time (polling-based, pubsub coming soon):

err := publisher.SubscribeToDecisions(
    "developer", // role filter
    func(decision *ucxl.TaskDecision, metadata *storage.UCXLMetadata) {
        fmt.Printf("New decision from %s: %s\n",
            decision.Agent,
            decision.Decision,
        )

        // Process decision
        if decision.Success && decision.TestResults != nil {
            if decision.TestResults.Failed > 0 {
                fmt.Printf("Warning: %d tests failed\n",
                    decision.TestResults.Failed,
                )
            }
        }
    },
)

Content Addressing

SHA-256 Hashing

UCXL uses SHA-256 content addressing to ensure decision immutability:

1. Decision Serialization: TaskDecision is serialized to JSON
2. Hash Generation: SHA-256 hash computed from JSON bytes
3. Storage Key: Hash used as DHT storage key
4. Verification: Content can be verified by recomputing hash

// Internal process (handled automatically)
decisionContent, _ := json.MarshalIndent(decision, "", "  ")
hash := sha256.Sum256(decisionContent)
storageKey := hex.EncodeToString(hash[:])

Content Retrieval

Content is retrieved using UCXL addresses, which are resolved to content hashes:

// 1. Parse UCXL address
address, err := ucxl.Parse("ucxl://agent:role@project:task/*^")

// 2. Resolve address to content hash
contentHash, err := dhtStorage.ResolveUCXLAddress(address.String())

// 3. Retrieve content by hash
content, metadata, err := dhtStorage.RetrieveByHash(contentHash)

// 4. Verify content integrity
computedHash := sha256.Sum256(content)
if hex.EncodeToString(computedHash[:]) != contentHash {
    return errors.New("content integrity check failed")
}

DHT Integration

Storage Operations

The UCXL package integrates with CHORUS's encrypted DHT storage layer:

Store Content

err := dhtStorage.StoreUCXLContent(
    ucxlAddress,      // UCXL address
    decisionContent,  // Content bytes
    role,             // Creator role (for encryption)
    "decision",       // Content type
)

Announce Content

After storing, announce content availability to the DHT network:

err := dhtStorage.AnnounceContent(ucxlAddress)
// Broadcasts content availability to DHT peers

Retrieve Content

content, metadata, err := dhtStorage.RetrieveUCXLContent(ucxlAddress)

fmt.Printf("Content type: %s\n", metadata.ContentType)
fmt.Printf("Creator role: %s\n", metadata.CreatorRole)
fmt.Printf("Created at: %s\n", metadata.CreatedAt)
fmt.Printf("Size: %d bytes\n", metadata.Size)

Search Content

query := &storage.SearchQuery{
    Agent:        "agent-007",
    Role:         "developer",
    Project:      "chorus",
    ContentType:  "decision",
    CreatedAfter: time.Now().Add(-7 * 24 * time.Hour),
    Limit:        50,
}

results, err := dhtStorage.SearchContent(query)
for _, metadata := range results {
    fmt.Printf("Found: %s\n", metadata.Address)
}

Role-Based Encryption

Content is encrypted based on the creator's role:

// When storing
err := dhtStorage.StoreUCXLContent(
    address,
    content,
    "developer",  // Creator role - determines encryption key
    contentType,
)

// When retrieving
// Automatic decryption if requester has access to role's key
content, metadata, err := dhtStorage.RetrieveUCXLContent(address)

DHT Metrics

Monitor DHT storage performance:

metrics := dhtStorage.GetMetrics()

fmt.Printf("Total stored: %d\n", metrics["total_stored"])
fmt.Printf("Total retrieved: %d\n", metrics["total_retrieved"])
fmt.Printf("Cache hits: %d\n", metrics["cache_hits"])
fmt.Printf("Cache misses: %d\n", metrics["cache_misses"])

Response Codes

UCXL defines standardized response codes for operations:

Success Codes (2xx)

Code	Description	HTTP Status
UCXL-200-SUCCESS	Request completed successfully	200
UCXL-201-CREATED	Resource created successfully	201
UCXL-202-ACCEPTED	Request accepted for processing	202
UCXL-204-NO_CONTENT	Request completed with no content	204

Client Error Codes (4xx)

Code	Description	HTTP Status
UCXL-400-BAD_REQUEST	Invalid request format	400
UCXL-400-INVALID_ADDRESS	UCXL address validation failed	400
UCXL-400-INVALID_PAYLOAD	Request payload validation failed	400
UCXL-400-TEMPORAL_INVALID	Invalid temporal navigation	400
UCXL-400-INVALID_ROLE	Invalid or unknown role	400
UCXL-401-UNAUTHORIZED	Authentication required	401
UCXL-403-FORBIDDEN	Insufficient permissions	403
UCXL-404-NOT_FOUND	Resource not found	404
UCXL-404-RESOLUTION_FAILED	Address resolution failed	404
UCXL-404-EXPERTISE_NOT_AVAILABLE	Requested expertise not available	404
UCXL-404-PROJECT_NOT_FOUND	Project not found	404
UCXL-408-COLLABORATION_TIMEOUT	Collaboration request timeout	408
UCXL-422-UNPROCESSABLE	Request cannot be processed	422
UCXL-422-NAVIGATION_FAILED	Temporal navigation failed	422

Server Error Codes (5xx)

Code	Description	HTTP Status
UCXL-500-INTERNAL_ERROR	Internal server error	500
UCXL-500-STORAGE_FAILED	DHT storage operation failed	500
UCXL-500-ANNOUNCE_FAILED	Content announcement failed	500
UCXL-500-COLLABORATION_FAILED	Collaboration operation failed	500
UCXL-501-NOT_IMPLEMENTED	Feature not implemented	501
UCXL-503-SERVICE_UNAVAILABLE	Service temporarily unavailable	503

Using Response Codes

// Create response builder
rb := ucxl.NewResponseBuilder("req-12345", "ucxi-server")

// Success response
response := rb.OK(map[string]interface{}{
    "address": address.String(),
    "version": 5,
})

// Error response
error := rb.InvalidAddress(
    "Agent component cannot be empty",
    "/address/agent",
    map[string]interface{}{
        "provided": address.Agent,
        "required": "non-empty string",
    },
)

// Get HTTP status for UCXL code
httpStatus := ucxl.GetHTTPStatus(ucxl.CodeInvalidAddress)
// Returns: 400

API Reference

Address Parsing

// Parse address string
address, err := ucxl.Parse("ucxl://agent:role@project:task/*^")
if err != nil {
    log.Fatal(err)
}

// Access components
fmt.Println(address.Agent)    // "agent"
fmt.Println(address.Role)     // "role"
fmt.Println(address.Project)  // "project"
fmt.Println(address.Task)     // "task"
fmt.Println(address.TemporalSegment.Type) // TemporalLatest

// Convert back to string
canonical := address.String()

Address Validation

// Validate address
err := address.Validate()
if err != nil {
    if valErr, ok := err.(*ucxl.ValidationError); ok {
        fmt.Printf("Validation failed in %s: %s\n",
            valErr.Field,
            valErr.Message,
        )
    }
}

// Quick validation check
if address.IsValid() {
    fmt.Println("Address is valid")
}

Address Matching

// Create pattern with wildcards
pattern, _ := ucxl.Parse("ucxl://any:developer@chorus:any/*^")

// Test if address matches pattern
address, _ := ucxl.Parse("ucxl://agent-007:developer@chorus:build/*^")
if address.Matches(pattern) {
    fmt.Println("Address matches pattern")
}

// Check if address uses wildcards
if address.IsWildcard() {
    fmt.Println("Address contains wildcards")
}

Address Manipulation

// Clone address
addressCopy := address.Clone()

// Modify clone without affecting original
addressCopy.Task = "deploy"
addressCopy.TemporalSegment = ucxl.TemporalSegment{
    Type:  ucxl.TemporalSpecific,
    Count: 10,
}

Usage Examples

Example 1: Publishing and Retrieving Code Decisions

package main

import (
    "context"
    "fmt"
    "log"

    "chorus/pkg/ucxl"
    "chorus/pkg/config"
    "chorus/pkg/storage"
)

func main() {
    ctx := context.Background()
    cfg := config.LoadConfig()
    dhtStorage := storage.NewDHTStorage(cfg)

    // Create publisher
    publisher := ucxl.NewDecisionPublisher(
        ctx,
        cfg,
        dhtStorage,
        "node-001",
        "agent-007",
    )

    // Publish code decision
    testResults := &ucxl.TestResults{
        Passed:   128,
        Failed:   2,
        Skipped:  5,
        Coverage: 84.2,
        FailedTests: []string{
            "TestAuthTokenExpiry",
            "TestRateLimitExceeded",
        },
    }

    err := publisher.PublishCodeDecision(
        "implement-api-v2",
        "Implemented v2 API with improved error handling and rate limiting",
        []string{
            "pkg/api/v2/handler.go",
            "pkg/api/v2/middleware.go",
            "pkg/api/v2/errors.go",
        },
        892,
        testResults,
        []string{
            "github.com/gin-gonic/gin",
            "github.com/go-redis/redis/v8",
        },
    )

    if err != nil {
        log.Fatal(err)
    }

    fmt.Println("Decision published successfully")

    // Retrieve decision
    decision, err := publisher.GetDecisionContent(
        "ucxl://agent-007:developer@chorus:implement-api-v2/*^",
    )

    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("\nRetrieved Decision:\n")
    fmt.Printf("Task: %s\n", decision.Task)
    fmt.Printf("Success: %v\n", decision.Success)
    fmt.Printf("Files Modified: %d\n", len(decision.FilesModified))
    fmt.Printf("Lines Changed: %d\n", decision.LinesChanged)

    if decision.TestResults != nil {
        fmt.Printf("\nTest Results:\n")
        fmt.Printf("  Passed: %d\n", decision.TestResults.Passed)
        fmt.Printf("  Failed: %d\n", decision.TestResults.Failed)
        fmt.Printf("  Coverage: %.1f%%\n", decision.TestResults.Coverage)
    }
}

Example 2: Temporal Navigation

package main

import (
    "fmt"
    "log"
    "time"

    "chorus/pkg/ucxl"
)

func main() {
    // Create navigator with 20 versions (0-20)
    navigator := ucxl.NewTemporalNavigator(20)

    // Add version metadata
    for i := 0; i <= 20; i++ {
        navigator.SetVersionInfo(i, ucxl.VersionInfo{
            Version:     i,
            Created:     time.Now().Add(-time.Duration(20-i) * time.Hour),
            Author:      fmt.Sprintf("agent-%03d", (i%5)+1),
            Description: fmt.Sprintf("Version %d update", i),
            Tags:        []string{"build", "tested"},
        })
    }

    fmt.Printf("Starting at version: %d\n", navigator.GetCurrentVersion())

    // Navigate to specific version
    result, err := navigator.Navigate(ucxl.TemporalSegment{
        Type:  ucxl.TemporalSpecific,
        Count: 15,
    })

    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Navigated to version: %d\n", result.TargetVersion)
    if result.VersionInfo != nil {
        fmt.Printf("  Author: %s\n", result.VersionInfo.Author)
        fmt.Printf("  Created: %s\n", result.VersionInfo.Created)
    }

    // Navigate backward 5 versions
    result, err = navigator.Navigate(ucxl.TemporalSegment{
        Type:      ucxl.TemporalRelative,
        Direction: ucxl.DirectionBackward,
        Count:     5,
    })

    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("After backward navigation: %d\n", result.TargetVersion)

    // Navigate to latest
    result, err = navigator.Navigate(ucxl.TemporalSegment{
        Type: ucxl.TemporalLatest,
    })

    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Latest version: %d\n", result.TargetVersion)

    // Display navigation history
    fmt.Println("\nNavigation History:")
    for i, step := range navigator.GetHistory() {
        status := "✓"
        if !step.Success {
            status = "✗"
        }
        fmt.Printf("%d. %s %s: %d → %d\n",
            i+1,
            status,
            step.Operation,
            step.FromVersion,
            step.ToVersion,
        )
    }
}

Example 3: Address Wildcards and Search

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "chorus/pkg/ucxl"
    "chorus/pkg/config"
    "chorus/pkg/storage"
)

func main() {
    ctx := context.Background()
    cfg := config.LoadConfig()
    dhtStorage := storage.NewDHTStorage(cfg)

    publisher := ucxl.NewDecisionPublisher(
        ctx,
        cfg,
        dhtStorage,
        "node-001",
        "search-agent",
    )

    // Query all developer decisions from last week
    oneWeekAgo := time.Now().Add(-7 * 24 * time.Hour)

    decisions, err := publisher.QueryRecentDecisions(
        "",          // any agent
        "developer", // developer role only
        "chorus",    // chorus project
        100,         // limit
        oneWeekAgo,
    )

    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Found %d decisions\n\n", len(decisions))

    // Group by task
    taskCounts := make(map[string]int)
    successCounts := make(map[string]int)

    for _, metadata := range decisions {
        // Parse address
        addr, err := ucxl.Parse(metadata.Address)
        if err != nil {
            continue
        }

        taskCounts[addr.Task]++

        // Get decision details
        decision, err := publisher.GetDecisionContent(metadata.Address)
        if err != nil {
            continue
        }

        if decision.Success {
            successCounts[addr.Task]++
        }
    }

    // Display statistics
    fmt.Println("Task Statistics:")
    for task, total := range taskCounts {
        success := successCounts[task]
        successRate := float64(success) / float64(total) * 100
        fmt.Printf("  %s: %d total, %d successful (%.1f%%)\n",
            task,
            total,
            success,
            successRate,
        )
    }
}

Example 4: Decision Subscription

package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "os/signal"
    "syscall"

    "chorus/pkg/ucxl"
    "chorus/pkg/config"
    "chorus/pkg/storage"
)

func main() {
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()

    cfg := config.LoadConfig()
    dhtStorage := storage.NewDHTStorage(cfg)

    publisher := ucxl.NewDecisionPublisher(
        ctx,
        cfg,
        dhtStorage,
        "node-001",
        "watcher-agent",
    )

    // Subscribe to all tester decisions
    err := publisher.SubscribeToDecisions(
        "tester",
        func(decision *ucxl.TaskDecision, metadata *storage.UCXLMetadata) {
            fmt.Printf("\n[NEW DECISION] %s\n", metadata.CreatedAt)
            fmt.Printf("Agent: %s\n", decision.Agent)
            fmt.Printf("Task: %s\n", decision.Task)
            fmt.Printf("Success: %v\n", decision.Success)

            if decision.TestResults != nil {
                total := decision.TestResults.Passed +
                        decision.TestResults.Failed +
                        decision.TestResults.Skipped
                fmt.Printf("Tests: %d/%d passed\n",
                    decision.TestResults.Passed,
                    total,
                )

                if decision.TestResults.Failed > 0 {
                    fmt.Printf("⚠ Failed tests:\n")
                    for _, test := range decision.TestResults.FailedTests {
                        fmt.Printf("  - %s\n", test)
                    }
                }
            }

            fmt.Println("---")
        },
    )

    if err != nil {
        log.Fatal(err)
    }

    fmt.Println("Subscribed to tester decisions. Press Ctrl+C to exit.")

    // Wait for interrupt
    sigChan := make(chan os.Signal, 1)
    signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)
    <-sigChan

    fmt.Println("\nShutting down...")
}

Best Practices

Address Design

1. Use meaningful identifiers: Choose descriptive agent, role, project, and task names
2. Prefer specific over wildcards: Use wildcards only when necessary for queries
3. Version consistently: Use semantic versioning strategies for temporal segments
4. Document paths: Use clear file paths in the path component

Decision Publishing

1. Publish atomically: Complete all task work before publishing decision
2. Include context: Provide rich context in the Context field
3. Track dependencies: Always list external dependencies
4. Test before publishing: Ensure test results are accurate
5. Plan next steps: Include actionable next steps for continuity

Temporal Navigation

1. Validate before navigation: Use ValidateTemporalSegment() to check feasibility
2. Handle errors gracefully: Navigation can fail at boundaries
3. Track history: Maintain navigation history for debugging
4. Use version metadata: Annotate versions with useful information

DHT Integration

1. Announce after storing: Always announce content availability
2. Handle network failures: DHT operations can fail; implement retries
3. Monitor metrics: Track DHT performance and storage usage
4. Encrypt sensitive data: Use role-based encryption for sensitive decisions

Error Handling

Common error patterns and how to handle them:

// Address parsing errors
address, err := ucxl.Parse(rawAddress)
if err != nil {
    if valErr, ok := err.(*ucxl.ValidationError); ok {
        log.Printf("Invalid %s: %s", valErr.Field, valErr.Message)
    }
    return err
}

// Temporal navigation errors
result, err := navigator.Navigate(segment)
if err != nil {
    if tcErr, ok := err.(*ucxl.TemporalConstraintError); ok {
        log.Printf("Navigation failed: %s (current: %d, max: %d)",
            tcErr.Message,
            tcErr.CurrentVersion,
            tcErr.MaxVersion,
        )
    }
    return err
}

// DHT storage errors
content, metadata, err := dhtStorage.RetrieveUCXLContent(address)
if err != nil {
    if errors.Is(err, storage.ErrNotFound) {
        log.Println("Decision not found")
    } else if errors.Is(err, storage.ErrDecryptionFailed) {
        log.Println("Insufficient permissions to decrypt content")
    } else {
        log.Printf("DHT retrieval failed: %v", err)
    }
    return err
}

Integration Points

CHORUS Agent Integration

// In agent initialization
publisher := ucxl.NewDecisionPublisher(
    ctx,
    config,
    dhtStorage,
    nodeID,
    agentName,
)
agent.publisher = publisher

// In task execution
func (a *Agent) executeTask(task Task) error {
    // Execute task logic
    result := task.Execute()

    // Publish decision
    err := a.publisher.PublishTaskDecision(&ucxl.TaskDecision{
        Task:     task.Name(),
        Decision: result.Summary(),
        Success:  result.Success(),
        Context:  result.Context(),
    })

    return err
}

UCXI Server Integration

// In UCXI server handlers
func (s *Server) handleResolve(w http.ResponseWriter, r *http.Request) {
    rawAddress := r.URL.Query().Get("address")

    address, err := ucxl.Parse(rawAddress)
    if err != nil {
        rb := ucxl.NewResponseBuilder(requestID, "ucxi-server")
        writeError(w, rb.InvalidAddress(
            "Failed to parse UCXL address",
            "/address",
            err.Error(),
        ))
        return
    }

    // Resolve and return
    content, metadata, err := s.dhtStorage.RetrieveUCXLContent(address.String())
    if err != nil {
        rb := ucxl.NewResponseBuilder(requestID, "ucxi-server")
        writeError(w, rb.NotFound(
            "Decision not found",
            address.String(),
        ))
        return
    }

    rb := ucxl.NewResponseBuilder(requestID, "ucxi-server")
    writeSuccess(w, rb.OK(map[string]interface{}{
        "address":  address.String(),
        "content":  string(content),
        "metadata": metadata,
    }))
}

See Also

• CHORUS Architecture
• DHT Storage
• Agent Collaboration
• SHHH Security Package