bzzz/slurp/temporal

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

@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

@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

# 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

# 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

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

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

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

# 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

# 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