// Package temporal provides decision-hop temporal analysis for the SLURP contextual intelligence system.
//
// This package implements temporal analysis of context evolution based on decision points
// rather than chronological time. It tracks how contexts change through different decisions,
// analyzes decision influence networks, and provides navigation through the decision graph
// to understand the evolution of project understanding over time.
//
// Key Features:
//   - Decision-hop based temporal analysis instead of chronological progression
//   - Context evolution tracking through decision influence graphs
//   - Temporal navigation by conceptual distance rather than time
//   - Decision pattern analysis and learning from historical changes
//   - Staleness detection based on decision relationships
//   - Conflict detection and resolution in temporal context
//   - Decision impact analysis and propagation tracking
//
// Core Concepts:
//   - Decision Hops: Conceptual distance measured by decision relationships
//   - Temporal Nodes: Context snapshots at specific decision points
//   - Influence Graph: Network of decisions that affect each other
//   - Decision Timeline: Sequence of decisions affecting a context
//   - Staleness Score: Measure of how outdated context is relative to decisions
//
// Core Components:
//   - TemporalGraph: Main interface for temporal context management
//   - DecisionNavigator: Navigation through decision-hop space
//   - InfluenceAnalyzer: Analysis of decision influence relationships
//   - StalenessDetector: Detection of outdated contexts
//   - ConflictDetector: Detection of temporal conflicts
//   - PatternAnalyzer: Analysis of decision-making patterns
//
// Integration Points:
//   - pkg/slurp/context: Context types and resolution
//   - pkg/slurp/intelligence: Decision metadata generation
//   - pkg/slurp/storage: Persistent temporal data storage
//   - pkg/ucxl: UCXL address parsing and handling
//   - Version control systems: Git commit correlation
//
// Example Usage:
//
//	graph := temporal.NewTemporalGraph(storage, intelligence)
//	ctx := context.Background()
//	
//	// Create initial context version
//	initial, err := graph.CreateInitialContext(ctx, address, contextNode, "developer")
//	if err != nil {
//	    log.Fatal(err)
//	}
//	
//	// Evolve context due to a decision
//	decision := &DecisionMetadata{
//	    ID: "commit-abc123",
//	    Maker: "developer",
//	    Rationale: "Refactored for better performance",
//	}
//	evolved, err := graph.EvolveContext(ctx, address, newContext, 
//	                                   ReasonRefactoring, decision)
//	
//	// Navigate through decision timeline
//	timeline, err := navigator.GetDecisionTimeline(ctx, address, true, 5)
//	if err != nil {
//	    log.Fatal(err)
//	}
//	
//	// Find contexts affected by a decision
//	affected, err := graph.FindRelatedDecisions(ctx, address, 3)
//	for _, path := range affected {
//	    fmt.Printf("Decision path: %d hops to %s\n", 
//	               path.HopDistance, path.ToAddress)
//	}
//
// Decision-Hop Analysis:
// Unlike traditional time-based analysis, this system measures context evolution
// by conceptual distance through decision relationships. A decision that affects
// multiple related components may be "closer" to those components than chronologically
// recent but unrelated changes. This provides more meaningful context for
// understanding code evolution and architectural decisions.
//
// Temporal Navigation:
// Navigation through the temporal space allows developers to understand how
// decisions led to the current state, explore alternative decision paths,
// and identify points where different approaches were taken. This supports
// architectural archaeology and decision rationale understanding.
//
// Performance Characteristics:
// - O(log N) lookup for temporal nodes by decision hop
// - O(N) traversal for decision paths within hop limits  
// - Cached decision influence graphs for fast relationship queries
// - Background analysis for pattern detection and staleness scoring
// - Incremental updates to minimize computational overhead
//
// Consistency Model:
// Temporal data maintains consistency through eventual convergence across
// the cluster, with conflict resolution based on decision metadata and
// vector clocks. The system handles concurrent decision recording and
// provides mechanisms for resolving temporal conflicts when they occur.
package temporal