CHORUS/pkg/slurp/interfaces.go

package slurp

import (
	"context"
)

// Core interfaces for the SLURP contextual intelligence system.
// These interfaces define the contracts for hierarchical context resolution,
// temporal evolution tracking, distributed storage, and intelligent analysis.

// ContextResolver defines the interface for hierarchical context resolution.
//
// The resolver implements bounded hierarchy traversal with caching and
// role-based access control, providing efficient context resolution for
// UCXL addresses through cascading inheritance patterns.
type ContextResolver interface {
	// Resolve resolves context for a UCXL address using cascading inheritance.
	// This is the primary method for context resolution with default depth limits.
	Resolve(ctx context.Context, ucxlAddress string) (*ResolvedContext, error)
	
	// ResolveWithDepth resolves context with bounded depth limit.
	// Provides fine-grained control over hierarchy traversal depth for
	// performance optimization and resource management.
	ResolveWithDepth(ctx context.Context, ucxlAddress string, maxDepth int) (*ResolvedContext, error)
	
	// BatchResolve efficiently resolves multiple UCXL addresses.
	// Uses parallel processing, request deduplication, and shared caching
	// for optimal performance with bulk operations.
	BatchResolve(ctx context.Context, addresses []string) (map[string]*ResolvedContext, error)
	
	// InvalidateCache invalidates cached resolution for an address.
	// Used when underlying context changes to ensure fresh resolution.
	InvalidateCache(ucxlAddress string) error
	
	// InvalidatePattern invalidates cached resolutions matching a pattern.
	// Useful for bulk cache invalidation when hierarchies change.
	InvalidatePattern(pattern string) error
	
	// GetStatistics returns resolver performance and operational statistics.
	GetStatistics() *ResolverStatistics
	
	// SetDepthLimit sets the default depth limit for resolution operations.
	SetDepthLimit(maxDepth int) error
	
	// GetDepthLimit returns the current default depth limit.
	GetDepthLimit() int
	
	// ClearCache clears all cached resolutions.
	ClearCache() error
}

// HierarchyManager manages the context hierarchy with bounded traversal.
//
// Provides operations for maintaining the hierarchical structure of
// context nodes while enforcing depth limits and consistency constraints.
type HierarchyManager interface {
	// LoadHierarchy loads the context hierarchy from storage.
	// Must be called before other operations to initialize the hierarchy.
	LoadHierarchy(ctx context.Context) error
	
	// AddNode adds a context node to the hierarchy.
	// Validates hierarchy constraints and updates relationships.
	AddNode(ctx context.Context, node *ContextNode) error
	
	// UpdateNode updates an existing context node.
	// Preserves hierarchy relationships while updating content.
	UpdateNode(ctx context.Context, node *ContextNode) error
	
	// RemoveNode removes a context node and handles children.
	// Provides options for handling orphaned children (promote, delete, reassign).
	RemoveNode(ctx context.Context, nodeID string) error
	
	// GetNode retrieves a context node by ID.
	GetNode(ctx context.Context, nodeID string) (*ContextNode, error)
	
	// TraverseUp traverses up the hierarchy with bounded depth.
	// Returns ancestor nodes within the specified depth limit.
	TraverseUp(ctx context.Context, startPath string, maxDepth int) ([]*ContextNode, error)
	
	// TraverseDown traverses down the hierarchy with bounded depth.
	// Returns descendant nodes within the specified depth limit.
	TraverseDown(ctx context.Context, startPath string, maxDepth int) ([]*ContextNode, error)
	
	// GetChildren gets immediate children of a node.
	GetChildren(ctx context.Context, nodeID string) ([]*ContextNode, error)
	
	// GetParent gets the immediate parent of a node.
	GetParent(ctx context.Context, nodeID string) (*ContextNode, error)
	
	// GetPath gets the full path from root to a node.
	GetPath(ctx context.Context, nodeID string) ([]*ContextNode, error)
	
	// ValidateHierarchy validates hierarchy integrity and constraints.
	// Checks for cycles, orphans, and consistency violations.
	ValidateHierarchy(ctx context.Context) error
	
	// RebuildIndex rebuilds internal indexes for hierarchy operations.
	RebuildIndex(ctx context.Context) error
	
	// GetHierarchyStats returns statistics about the hierarchy.
	GetHierarchyStats(ctx context.Context) (*HierarchyStats, error)
}

// GlobalContextManager manages global contexts that apply everywhere.
//
// Global contexts provide system-wide applicable metadata that is
// automatically included in all context resolutions regardless of
// hierarchy position.
type GlobalContextManager interface {
	// AddGlobalContext adds a context that applies globally.
	// Global contexts are merged into all resolution results.
	AddGlobalContext(ctx context.Context, context *ContextNode) error
	
	// RemoveGlobalContext removes a global context.
	RemoveGlobalContext(ctx context.Context, contextID string) error
	
	// UpdateGlobalContext updates an existing global context.
	UpdateGlobalContext(ctx context.Context, context *ContextNode) error
	
	// ListGlobalContexts lists all global contexts.
	// Returns contexts ordered by priority/specificity.
	ListGlobalContexts(ctx context.Context) ([]*ContextNode, error)
	
	// GetGlobalContext retrieves a specific global context.
	GetGlobalContext(ctx context.Context, contextID string) (*ContextNode, error)
	
	// ApplyGlobalContexts applies global contexts to a resolution.
	// Called automatically during resolution process.
	ApplyGlobalContexts(ctx context.Context, resolved *ResolvedContext) error
	
	// EnableGlobalContext enables/disables a global context.
	EnableGlobalContext(ctx context.Context, contextID string, enabled bool) error
	
	// SetGlobalContextPriority sets priority for global context application.
	SetGlobalContextPriority(ctx context.Context, contextID string, priority int) error
}

// TemporalGraph manages the temporal evolution of context.
//
// Implements decision-hop based temporal analysis for tracking how
// context evolves through different decision points rather than
// simple chronological progression.
type TemporalGraph interface {
	// CreateInitialContext creates the first version of context.
	// Establishes the starting point for temporal evolution tracking.
	CreateInitialContext(ctx context.Context, ucxlAddress string, 
	                    contextData *ContextNode, creator string) (*TemporalNode, error)
	
	// EvolveContext creates a new temporal version due to a decision.
	// Records the decision that caused the change and updates the graph.
	EvolveContext(ctx context.Context, ucxlAddress string, 
	             newContext *ContextNode, reason ChangeReason, 
	             decision *DecisionMetadata) (*TemporalNode, error)
	
	// GetLatestVersion gets the most recent temporal node.
	GetLatestVersion(ctx context.Context, ucxlAddress string) (*TemporalNode, error)
	
	// GetVersionAtDecision gets context as it was at a specific decision point.
	// Navigation based on decision hops, not chronological time.
	GetVersionAtDecision(ctx context.Context, ucxlAddress string, 
	                    decisionHop int) (*TemporalNode, error)
	
	// GetEvolutionHistory gets complete evolution history.
	// Returns all temporal versions ordered by decision sequence.
	GetEvolutionHistory(ctx context.Context, ucxlAddress string) ([]*TemporalNode, error)
	
	// AddInfluenceRelationship adds influence between contexts.
	// Establishes that decisions in one context affect another.
	AddInfluenceRelationship(ctx context.Context, influencer, influenced string) error
	
	// RemoveInfluenceRelationship removes an influence relationship.
	RemoveInfluenceRelationship(ctx context.Context, influencer, influenced string) error
	
	// GetInfluenceRelationships gets all influence relationships for a context.
	GetInfluenceRelationships(ctx context.Context, ucxlAddress string) ([]string, []string, error)
	
	// FindRelatedDecisions finds decisions within N decision hops.
	// Explores the decision graph by conceptual distance, not time.
	FindRelatedDecisions(ctx context.Context, ucxlAddress string, 
	                    maxHops int) ([]*DecisionPath, error)
	
	// FindDecisionPath finds shortest decision path between addresses.
	// Returns the path of decisions connecting two contexts.
	FindDecisionPath(ctx context.Context, from, to string) ([]*DecisionStep, error)
	
	// AnalyzeDecisionPatterns analyzes decision-making patterns.
	// Identifies patterns in how decisions are made and contexts evolve.
	AnalyzeDecisionPatterns(ctx context.Context) (*DecisionAnalysis, error)
	
	// ValidateTemporalIntegrity validates temporal graph integrity.
	// Checks for inconsistencies and corruption in temporal data.
	ValidateTemporalIntegrity(ctx context.Context) error
	
	// CompactHistory compacts old temporal data to save space.
	// Removes detailed history while preserving key decision points.
	CompactHistory(ctx context.Context, beforeTime *time.Time) error
}

// DecisionNavigator handles decision-hop based navigation.
//
// Provides navigation through the decision graph based on conceptual
// distance rather than chronological time, enabling exploration of
// related changes and decision sequences.
type DecisionNavigator interface {
	// NavigateDecisionHops navigates by decision distance, not time.
	// Moves through the decision graph by the specified number of hops.
	NavigateDecisionHops(ctx context.Context, ucxlAddress string, 
	                    hops int, direction NavigationDirection) (*TemporalNode, error)
	
	// GetDecisionTimeline gets timeline ordered by decision sequence.
	// Returns decisions in the order they were made, not chronological order.
	GetDecisionTimeline(ctx context.Context, ucxlAddress string, 
	                   includeRelated bool, maxHops int) (*DecisionTimeline, error)
	
	// FindStaleContexts finds contexts that may be outdated.
	// Identifies contexts that haven't been updated despite related changes.
	FindStaleContexts(ctx context.Context, stalenessThreshold float64) ([]*StaleContext, error)
	
	// ValidateDecisionPath validates a decision path is reachable.
	// Verifies that a path exists and is traversable.
	ValidateDecisionPath(ctx context.Context, path []*DecisionStep) error
	
	// GetNavigationHistory gets navigation history for a session.
	GetNavigationHistory(ctx context.Context, sessionID string) ([]*DecisionStep, error)
	
	// ResetNavigation resets navigation state to latest versions.
	ResetNavigation(ctx context.Context, ucxlAddress string) error
}

// DistributedStorage handles distributed storage of context data.
//
// Provides encrypted, role-based storage using the existing BZZZ DHT
// infrastructure with consistency guarantees and conflict resolution.
type DistributedStorage interface {
	// Store stores context data in the DHT with encryption.
	// Data is encrypted based on access level and role requirements.
	Store(ctx context.Context, key string, data interface{}, 
	      accessLevel crypto.AccessLevel) error
	
	// Retrieve retrieves and decrypts context data.
	// Automatically handles decryption based on current role permissions.
	Retrieve(ctx context.Context, key string) (interface{}, error)
	
	// Delete removes context data from storage.
	// Handles distributed deletion and cleanup.
	Delete(ctx context.Context, key string) error
	
	// Exists checks if a key exists in storage.
	Exists(ctx context.Context, key string) (bool, error)
	
	// List lists keys matching a pattern.
	List(ctx context.Context, pattern string) ([]string, error)
	
	// Index creates searchable indexes for context data.
	// Enables efficient searching and filtering operations.
	Index(ctx context.Context, key string, metadata *IndexMetadata) error
	
	// Search searches indexed context data.
	// Supports complex queries with role-based filtering.
	Search(ctx context.Context, query *SearchQuery) ([]*SearchResult, error)
	
	// Sync synchronizes with other nodes.
	// Ensures consistency across the distributed system.
	Sync(ctx context.Context) error
	
	// GetStorageStats returns storage statistics and health information.
	GetStorageStats(ctx context.Context) (*StorageStats, error)
	
	// Backup creates a backup of stored data.
	Backup(ctx context.Context, destination string) error
	
	// Restore restores data from backup.
	Restore(ctx context.Context, source string) error
}

// EncryptedStorage provides role-based encrypted storage.
//
// Extends basic storage with advanced encryption features including
// multi-role encryption, key rotation, and access control enforcement.
type EncryptedStorage interface {
	// StoreEncrypted stores data encrypted for specific roles.
	// Supports multi-role encryption for shared access.
	StoreEncrypted(ctx context.Context, key string, data interface{}, 
	              roles []string) error
	
	// RetrieveDecrypted retrieves and decrypts data using current role.
	// Automatically selects appropriate decryption key.
	RetrieveDecrypted(ctx context.Context, key string) (interface{}, error)
	
	// CanAccess checks if current role can access data.
	// Validates access without retrieving the actual data.
	CanAccess(ctx context.Context, key string) (bool, error)
	
	// ListAccessibleKeys lists keys accessible to current role.
	// Filters keys based on current role permissions.
	ListAccessibleKeys(ctx context.Context) ([]string, error)
	
	// ReEncryptForRoles re-encrypts data for different roles.
	// Useful for permission changes and access control updates.
	ReEncryptForRoles(ctx context.Context, key string, newRoles []string) error
	
	// GetAccessRoles gets roles that can access a specific key.
	GetAccessRoles(ctx context.Context, key string) ([]string, error)
	
	// RotateKeys rotates encryption keys for enhanced security.
	RotateKeys(ctx context.Context, keyAge time.Duration) error
	
	// ValidateEncryption validates encryption integrity.
	ValidateEncryption(ctx context.Context, key string) error
}

// ContextGenerator generates context metadata (admin-only).
//
// Provides intelligent context generation using analysis of file content,
// structure, patterns, and existing context. Restricted to admin nodes
// to prevent unauthorized context modification.
type ContextGenerator interface {
	// GenerateContext generates context for a path (requires admin role).
	// Analyzes content, structure, and patterns to create comprehensive context.
	GenerateContext(ctx context.Context, path string, 
	               options *GenerationOptions) (*ContextNode, error)
	
	// RegenerateHierarchy regenerates entire hierarchy (admin-only).
	// Rebuilds context hierarchy from scratch with improved analysis.
	RegenerateHierarchy(ctx context.Context, rootPath string,
	                   options *GenerationOptions) (*HierarchyStats, error)
	
	// ValidateGeneration validates generated context quality.
	// Ensures generated context meets quality and consistency standards.
	ValidateGeneration(ctx context.Context, context *ContextNode) (*ValidationResult, error)
	
	// EstimateGenerationCost estimates resource cost of generation.
	// Helps with resource planning and operation scheduling.
	EstimateGenerationCost(ctx context.Context, scope string) (*CostEstimate, error)
	
	// GenerateBatch generates context for multiple paths efficiently.
	// Optimized for bulk generation operations.
	GenerateBatch(ctx context.Context, paths []string, 
	             options *GenerationOptions) (map[string]*ContextNode, error)
	
	// ScheduleGeneration schedules background context generation.
	// Queues generation tasks for processing during low-activity periods.
	ScheduleGeneration(ctx context.Context, paths []string, 
	                  options *GenerationOptions, priority int) error
	
	// GetGenerationStatus gets status of background generation tasks.
	GetGenerationStatus(ctx context.Context) (*GenerationStatus, error)
	
	// CancelGeneration cancels pending generation tasks.
	CancelGeneration(ctx context.Context, taskID string) error
}

// ContextAnalyzer analyzes context data for patterns and quality.
//
// Provides comprehensive analysis of context quality, consistency,
// and patterns to identify improvement opportunities and issues.
type ContextAnalyzer interface {
	// AnalyzeContext analyzes context quality and consistency.
	// Evaluates individual context nodes for quality and accuracy.
	AnalyzeContext(ctx context.Context, context *ContextNode) (*AnalysisResult, error)
	
	// DetectPatterns detects patterns across contexts.
	// Identifies recurring patterns that can improve context generation.
	DetectPatterns(ctx context.Context, contexts []*ContextNode) ([]*Pattern, error)
	
	// SuggestImprovements suggests context improvements.
	// Provides actionable recommendations for context enhancement.
	SuggestImprovements(ctx context.Context, context *ContextNode) ([]*Suggestion, error)
	
	// CalculateConfidence calculates confidence score.
	// Assesses confidence in context accuracy and completeness.
	CalculateConfidence(ctx context.Context, context *ContextNode) (float64, error)
	
	// DetectInconsistencies detects inconsistencies in hierarchy.
	// Identifies conflicts and inconsistencies across related contexts.
	DetectInconsistencies(ctx context.Context) ([]*Inconsistency, error)
	
	// AnalyzeTrends analyzes trends in context evolution.
	// Identifies patterns in how contexts change over time.
	AnalyzeTrends(ctx context.Context, timeRange time.Duration) (*TrendAnalysis, error)
	
	// CompareContexts compares contexts for similarity and differences.
	CompareContexts(ctx context.Context, context1, context2 *ContextNode) (*ComparisonResult, error)
	
	// ValidateConsistency validates consistency across hierarchy.
	ValidateConsistency(ctx context.Context, rootPath string) ([]*ConsistencyIssue, error)
}

// PatternMatcher matches context patterns and templates.
//
// Provides pattern matching capabilities for context standardization,
// template application, and automated context improvement.
type PatternMatcher interface {
	// MatchPatterns matches context against known patterns.
	// Identifies which patterns apply to a given context.
	MatchPatterns(ctx context.Context, context *ContextNode) ([]*PatternMatch, error)
	
	// RegisterPattern registers a new context pattern.
	// Adds patterns that can be used for matching and generation.
	RegisterPattern(ctx context.Context, pattern *ContextPattern) error
	
	// UnregisterPattern removes a context pattern.
	UnregisterPattern(ctx context.Context, patternID string) error
	
	// UpdatePattern updates an existing pattern.
	UpdatePattern(ctx context.Context, pattern *ContextPattern) error
	
	// ListPatterns lists all registered patterns.
	// Returns patterns ordered by priority and usage frequency.
	ListPatterns(ctx context.Context) ([]*ContextPattern, error)
	
	// GetPattern retrieves a specific pattern.
	GetPattern(ctx context.Context, patternID string) (*ContextPattern, error)
	
	// ApplyPattern applies a pattern to context.
	// Updates context to match pattern template.
	ApplyPattern(ctx context.Context, context *ContextNode, patternID string) (*ContextNode, error)
	
	// ValidatePattern validates pattern definition.
	ValidatePattern(ctx context.Context, pattern *ContextPattern) (*ValidationResult, error)
	
	// GetPatternUsage gets usage statistics for patterns.
	GetPatternUsage(ctx context.Context) (map[string]int, error)
}

// QueryEngine provides context search and query interfaces.
//
// Enables complex querying of context data with support for full-text
// search, faceted search, temporal queries, and role-based filtering.
type QueryEngine interface {
	// Query performs a general context query.
	// Supports complex queries with multiple criteria and filters.
	Query(ctx context.Context, query *SearchQuery) ([]*SearchResult, error)
	
	// SearchByTag finds contexts by tag.
	// Optimized search for tag-based filtering.
	SearchByTag(ctx context.Context, tags []string) ([]*SearchResult, error)
	
	// SearchByTechnology finds contexts by technology.
	// Finds contexts using specific technologies.
	SearchByTechnology(ctx context.Context, technologies []string) ([]*SearchResult, error)
	
	// SearchByPath finds contexts by path pattern.
	// Supports glob patterns and regex for path matching.
	SearchByPath(ctx context.Context, pathPattern string) ([]*SearchResult, error)
	
	// TemporalQuery performs temporal-aware queries.
	// Queries context as it existed at specific decision points.
	TemporalQuery(ctx context.Context, query *SearchQuery, 
	             temporal *TemporalFilter) ([]*SearchResult, error)
	
	// FuzzySearch performs fuzzy text search.
	// Handles typos and approximate matching.
	FuzzySearch(ctx context.Context, text string, threshold float64) ([]*SearchResult, error)
	
	// GetSuggestions gets search suggestions and auto-complete.
	GetSuggestions(ctx context.Context, prefix string, limit int) ([]string, error)
	
	// GetFacets gets faceted search information.
	// Returns available filters and their counts.
	GetFacets(ctx context.Context, query *SearchQuery) (map[string]map[string]int, error)
	
	// BuildIndex builds search indexes for efficient querying.
	BuildIndex(ctx context.Context, rebuild bool) error
	
	// OptimizeIndex optimizes search indexes for performance.
	OptimizeIndex(ctx context.Context) error
	
	// GetQueryStats gets query performance statistics.
	GetQueryStats(ctx context.Context) (*QueryStats, error)
}

// Additional supporting interfaces for comprehensive functionality

// CacheManager manages caching for performance optimization
type CacheManager interface {
	Get(ctx context.Context, key string) (interface{}, error)
	Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error
	Delete(ctx context.Context, key string) error
	Clear(ctx context.Context) error
	GetStats() *CacheStats
}

// EventEmitter emits events for monitoring and integration
type EventEmitter interface {
	Emit(ctx context.Context, eventType EventType, data map[string]interface{}) error
	Subscribe(eventType EventType, handler EventHandler) error
	Unsubscribe(eventType EventType, handler EventHandler) error
}

// HealthChecker provides health checking capabilities
type HealthChecker interface {
	CheckHealth(ctx context.Context) (*HealthStatus, error)
	GetComponentHealth(ctx context.Context, component string) (*ComponentHealth, error)
	RegisterHealthCheck(component string, checker func(context.Context) error) error
}

// Additional types needed by interfaces

import "time"

type StorageStats struct {
	TotalKeys        int64         `json:"total_keys"`
	TotalSize        int64         `json:"total_size"`
	IndexSize        int64         `json:"index_size"`
	CacheSize        int64         `json:"cache_size"`
	ReplicationStatus string       `json:"replication_status"`
	LastSync         time.Time     `json:"last_sync"`
	SyncErrors       int64         `json:"sync_errors"`
	AvailableSpace   int64         `json:"available_space"`
}

type GenerationStatus struct {
	ActiveTasks      int           `json:"active_tasks"`
	QueuedTasks      int           `json:"queued_tasks"`
	CompletedTasks   int           `json:"completed_tasks"`
	FailedTasks      int           `json:"failed_tasks"`
	EstimatedCompletion time.Time  `json:"estimated_completion"`
	CurrentTask      *GenerationTask `json:"current_task,omitempty"`
}

type GenerationTask struct {
	ID           string        `json:"id"`
	Path         string        `json:"path"`
	Status       string        `json:"status"`
	Progress     float64       `json:"progress"`
	StartedAt    time.Time     `json:"started_at"`
	EstimatedCompletion time.Time `json:"estimated_completion"`
	Error        string        `json:"error,omitempty"`
}

type TrendAnalysis struct {
	TimeRange        time.Duration `json:"time_range"`
	TotalChanges     int          `json:"total_changes"`
	ChangeVelocity   float64      `json:"change_velocity"`
	DominantReasons  []ChangeReason `json:"dominant_reasons"`
	QualityTrend     string       `json:"quality_trend"`
	ConfidenceTrend  string       `json:"confidence_trend"`
	MostActiveAreas  []string     `json:"most_active_areas"`
	EmergingPatterns []*Pattern   `json:"emerging_patterns"`
	AnalyzedAt       time.Time    `json:"analyzed_at"`
}

type ComparisonResult struct {
	SimilarityScore  float64      `json:"similarity_score"`
	Differences      []*Difference `json:"differences"`
	CommonElements   []string     `json:"common_elements"`
	Recommendations  []*Suggestion `json:"recommendations"`
	ComparedAt       time.Time    `json:"compared_at"`
}

type Difference struct {
	Field        string      `json:"field"`
	Value1       interface{} `json:"value1"`
	Value2       interface{} `json:"value2"`
	DifferenceType string    `json:"difference_type"`
	Significance float64     `json:"significance"`
}

type ConsistencyIssue struct {
	Type         string    `json:"type"`
	Description  string    `json:"description"`
	AffectedNodes []string `json:"affected_nodes"`
	Severity     string    `json:"severity"`
	Suggestion   string    `json:"suggestion"`
	DetectedAt   time.Time `json:"detected_at"`
}

type QueryStats struct {
	TotalQueries     int64         `json:"total_queries"`
	AverageQueryTime time.Duration `json:"average_query_time"`
	CacheHitRate     float64       `json:"cache_hit_rate"`
	IndexUsage       map[string]int64 `json:"index_usage"`
	PopularQueries   []string      `json:"popular_queries"`
	SlowQueries      []string      `json:"slow_queries"`
	ErrorRate        float64       `json:"error_rate"`
}

type CacheStats struct {
	HitRate      float64   `json:"hit_rate"`
	MissRate     float64   `json:"miss_rate"`
	TotalHits    int64     `json:"total_hits"`
	TotalMisses  int64     `json:"total_misses"`
	CurrentSize  int64     `json:"current_size"`
	MaxSize      int64     `json:"max_size"`
	Evictions    int64     `json:"evictions"`
	LastEviction time.Time `json:"last_eviction"`
}

type HealthStatus struct {
	Overall     string                      `json:"overall"`
	Components  map[string]*ComponentHealth `json:"components"`
	CheckedAt   time.Time                   `json:"checked_at"`
	Version     string                      `json:"version"`
	Uptime      time.Duration               `json:"uptime"`
}

type ComponentHealth struct {
	Status      string            `json:"status"`
	Message     string            `json:"message,omitempty"`
	LastCheck   time.Time         `json:"last_check"`
	ResponseTime time.Duration    `json:"response_time"`
	Metadata    map[string]interface{} `json:"metadata,omitempty"`
}