bzzz/slurp/temporal/README.md

# SLURP Temporal Decision Graph System

The Temporal Decision Graph System implements decision-hop based temporal analysis, tracking how context and decisions evolve through decision relationships rather than chronological time.

## Purpose

This module provides:

- **Decision-Based Temporal Analysis**: Track related decisions by decision distance, not time
- **Context Evolution**: Monitor how understanding deepens over time
- **Decision Influence Graphs**: Map how decisions affect other decisions
- **Temporal Queries**: Query context "as it was" at any decision point
- **Decision Genealogy**: Track the lineage and rationale of decisions

## Key Innovation: Decision Hops vs Time

Traditional temporal systems track changes chronologically. SLURP's temporal system tracks changes by **decision relationships**:

- **Decision Hop 0**: Original context/decision
- **Decision Hop 1**: Decisions directly influenced by the original
- **Decision Hop 2**: Decisions influenced by hop-1 decisions
- **Decision Hop N**: N-degrees of decision influence away

This provides **conceptual relevance** similar to RAG systems - finding related decisions by influence rather than time proximity.

## Architecture

### Core Components

#### TemporalContextNode
```python
@dataclass
class TemporalContextNode:
    ucxl_address: str          # What file/component this affects
    timestamp: str             # When the decision occurred
    version: int               # Monotonic version number
    
    # Context at this decision point
    summary: str
    purpose: str
    technologies: List[str]
    tags: List[str]
    insights: List[str]
    
    # Decision metadata
    change_reason: ContextChangeReason  # Why context changed
    parent_version: Optional[int]       # Previous version
    decision_metadata: DecisionMetadata # Who, why, how confident
    
    # Decision influence graph
    influences: List[str]      # UCXL addresses this decision influences
    influenced_by: List[str]   # UCXL addresses that influenced this
```

#### DecisionMetadata
```python
@dataclass
class DecisionMetadata:
    decision_maker: str         # Who made the decision
    decision_id: Optional[str]  # Git commit, ticket ID, etc.
    decision_rationale: str     # Why the decision was made
    impact_scope: str          # local, module, project, system
    confidence_level: float    # How confident in this decision
    external_references: List[str]  # Links to PRs, issues, docs
```

### Decision Change Reasons

The system tracks **why** context changes:

- `INITIAL_CREATION`: First context creation
- `CODE_CHANGE`: File/code modifications
- `DESIGN_DECISION`: Architectural or design choices
- `REFACTORING`: Code structure improvements
- `ARCHITECTURE_CHANGE`: System-wide architectural changes
- `REQUIREMENTS_CHANGE`: Changed requirements/specifications
- `LEARNING_EVOLUTION`: Improved understanding over time
- `RAG_ENHANCEMENT`: RAG system provided better insights
- `TEAM_INPUT`: Human team member input/corrections
- `BUG_DISCOVERY`: Found issues that change understanding
- `PERFORMANCE_INSIGHT`: Performance analysis changed context
- `SECURITY_REVIEW`: Security analysis added context

## Key Features

### Decision-Hop Analysis
```python
# Find all decisions within 3 hops of a component
related_decisions = temporal_graph.find_related_decisions(
    "ucxl://any:any@BZZZ:RUSTLE-testing/src/main.rs", 
    max_hops=3
)

# Get decision timeline (by decision influence, not time)
timeline = temporal_graph.get_decision_timeline(
    ucxl_address, 
    include_related=True, 
    max_hops=2
)
```

### Decision Path Discovery
```python
# Find shortest decision path between two components
path = temporal_graph.find_decision_path(
    from_address="ucxl://any:any@BZZZ:RUSTLE-testing/src/main.rs",
    to_address="ucxl://any:any@BZZZ:RUSTLE-testing/src/api.rs"
)
```

### Context Time Travel
```python
# Get context as it was at a specific decision point
historical_context = temporal_graph.get_version_at_time(
    ucxl_address, 
    target_time=datetime(2024, 1, 15)
)

# Get complete evolution history
evolution = temporal_graph.get_context_evolution(ucxl_address)
```

### Confidence Evolution Tracking
The system tracks how confidence in context changes over time:

```python
confidence_adjustments = {
    RAG_ENHANCEMENT: +0.1,      # RAG usually improves confidence
    TEAM_INPUT: +0.15,          # Human input is valuable
    LEARNING_EVOLUTION: +0.1,   # Learning improves understanding
    BUG_DISCOVERY: -0.15,       # Bugs indicate misunderstanding
    ARCHITECTURE_CHANGE: -0.05, # Major changes create uncertainty
}
```

## Decision Influence Propagation

When a decision changes context, it propagates influence to related components:

1. **Direct Influence**: Components directly affected by the decision
2. **Indirect Influence**: Components affected by the directly influenced ones
3. **Staleness Propagation**: Increases staleness indicator for affected contexts
4. **Re-analysis Triggers**: May trigger automated re-analysis of stale contexts

### Staleness Calculation
```python
def calculate_staleness_impact(reason, impact_scope):
    base_staleness = {
        "local": 0.1,
        "module": 0.3, 
        "project": 0.5,
        "system": 0.8
    }[impact_scope]
    
    reason_multipliers = {
        ARCHITECTURE_CHANGE: 2.0,
        REQUIREMENTS_CHANGE: 1.5,
        REFACTORING: 1.2,
        CODE_CHANGE: 1.0
    }
    
    return base_staleness * reason_multipliers.get(reason, 1.0)
```

## Integration with BZZZ Leader System

### Leader-Coordinated Temporal Updates
- **Leader Authority**: Only Leader can create new temporal context versions
- **Decision Validation**: Leader validates and approves decision metadata
- **Consistency Guarantee**: Single source of truth for decision evolution
- **Failover Handling**: Temporal graph transfers with leadership election

### Role-Based Temporal Access
- **Decision Visibility**: Agents see temporal context relevant to their role
- **Encrypted Temporal Data**: Decision history encrypted per role
- **Need-to-Know Temporal**: Only relevant decision paths visible
- **Audit Trail**: Complete log of temporal context access

## Query Patterns

### Temporal Context Queries
```python
# What decisions led to this current state?
decision_path = get_decision_ancestry(ucxl_address)

# What would be affected if I change this component?
impact_analysis = find_decision_influence_cone(ucxl_address, max_depth=5)

# Show me all decisions made by this person/system
maker_decisions = filter_decisions_by_maker("tony")

# Find components that evolved similarly to this one
similar_evolution = find_similar_decision_patterns(ucxl_address)
```

### Decision Pattern Analysis
```python
# Analyze decision-making patterns over time
patterns = temporal_graph.analyze_decision_patterns()
# Returns:
# - decision_makers: Who makes what types of decisions
# - change_reasons: Most common reasons for context changes  
# - impact_scopes: Distribution of decision impact levels
# - decision_frequency: Decision activity over time
```

## Performance Characteristics

### Decision Graph Traversal
- **Bounded Depth**: Configurable maximum decision hop depth
- **Efficient Pathfinding**: Breadth-first search with early termination
- **Cached Relationships**: In-memory caching of decision relationships
- **Lazy Loading**: Load decision details only when needed

### Storage Efficiency
- **Differential Versioning**: Only store changes between versions
- **Decision Deduplication**: Reuse common decision metadata
- **Compressed History**: Compress old temporal data
- **Index Optimization**: Efficient indexing for temporal queries

## Use Cases

### Architectural Decision Tracking
- **Why was this design chosen?**: Trace back through decision genealogy
- **What else was affected?**: Find all components influenced by a decision
- **Who should review changes?**: Identify decision makers for related components
- **Risk Assessment**: Understand decision confidence and validation history

### Impact Analysis
- **Change Impact**: What decisions would be affected by this change?
- **Regression Risk**: Has similar context been changed before? What happened?
- **Knowledge Transfer**: New team members can see decision rationale history
- **Technical Debt**: Identify areas with low-confidence or outdated decisions

### Learning and Optimization
- **Decision Quality**: Track which types of decisions lead to better outcomes
- **Team Patterns**: Understand how different team members make decisions
- **Context Staleness**: Identify areas needing decision review/update
- **Knowledge Evolution**: See how understanding improved over time

## Future Enhancements

- **ML-Based Decision Prediction**: Predict likely next decisions based on patterns
- **Automated Staleness Detection**: ML models to identify potentially stale context
- **Decision Recommendation**: Suggest reviewers based on decision history
- **Cross-Project Decision Learning**: Learn from decisions across multiple projects
- **Real-time Decision Streaming**: WebSocket-based decision update notifications