heimdall

type ActionContext struct {
	context.Context

	// UserMessage is what the user said to trigger this action
	UserMessage string

	// Params extracted from user message by SLM
	Params map[string]interface{}

	// Database routes Cypher/search operations across logical databases.
	Database DatabaseRouter

	// Metrics provides runtime metrics
	Metrics MetricsReader

	// Bifrost provides communication bridge to the user
	// Use this to send progress updates, request confirmation, etc.
	Bifrost BifrostBridge

	// PrincipalRoles are the authenticated principal's role names (from request context).
	// Plugins can use this with DatabaseAccessMode and ResolvedAccess to enforce per-DB access.
	PrincipalRoles []string

	// DatabaseAccessMode is the principal's per-database see/access mode (from request context).
	// Use CanAccessDatabase(dbName) before running Cypher against a database.
	DatabaseAccessMode auth.DatabaseAccessMode

	// ResolvedAccess returns per-database read/write for the principal (from request context).
	// Use for mutation checks: ResolvedAccess(dbName).Write before CREATE/DELETE/SET/etc.
	ResolvedAccess func(dbName string) auth.ResolvedAccess
}

type ActionFunc struct {
	Name        string                                         // Full name: heimdall.{plugin}.{action} (MCP tool "name")
	Handler     func(ctx ActionContext) (*ActionResult, error) // The action handler
	Description string                                         // Human-readable description (MCP "description")
	Category    string                                         // Grouping: monitoring, optimization, curation
	// InputSchema is optional JSON Schema for parameters (MCP "inputSchema").
	// When nil or empty, ActionsAsMCPTools() uses DefaultActionInputSchema.
	InputSchema json.RawMessage
}

type ActionInvoker struct {
	// contains filtered or unexported fields
}

type ActionOpcode int

type ActionResponse struct {
	Action     ActionOpcode   `json:"action"`
	Confidence float64        `json:"confidence"`
	Reasoning  string         `json:"reasoning"`
	Params     map[string]any `json:"params,omitempty"`
}

type ActionResult struct {
	Success bool                   `json:"success"`
	Message string                 `json:"message"`
	Data    map[string]interface{} `json:"data,omitempty"`
}

type AsyncEngineStats interface {
	Stats() (pendingWrites, totalFlushes int64)
}

type Bifrost struct {
	// contains filtered or unexported fields
}

type BifrostBridge interface {
	// SendMessage sends a message to connected Bifrost clients.
	// The message appears as a system message in the chat.
	SendMessage(msg string) error

	// SendNotification sends a notification with a specific type.
	// Types: "info", "warning", "error", "success"
	SendNotification(notifType, title, message string) error

	// Broadcast sends a message to all connected clients.
	// Useful for system-wide announcements.
	Broadcast(msg string) error

	// RequestConfirmation asks the user to confirm an action.
	// Returns true if user confirms, false if they decline or timeout.
	// The action parameter describes what needs confirmation.
	RequestConfirmation(action string) (bool, error)

	// IsConnected returns true if there are active Bifrost connections.
	IsConnected() bool

	// ConnectionCount returns the number of active Bifrost connections.
	ConnectionCount() int
}

type BifrostClient struct {
	ID          string
	Flusher     http.Flusher
	Writer      http.ResponseWriter
	ConnectedAt time.Time
	LastPing    time.Time
}

type BifrostMessage struct {
	Type      string                 `json:"type"`      // "message", "notification", "confirmation"
	Timestamp int64                  `json:"timestamp"` // Unix timestamp
	Content   string                 `json:"content,omitempty"`
	Title     string                 `json:"title,omitempty"`
	Level     string                 `json:"level,omitempty"` // "info", "warning", "error", "success"
	Data      map[string]interface{} `json:"data,omitempty"`
}

type CacheMetrics struct {
	Size      int     `json:"size"`
	MaxSize   int     `json:"max_size"`
	Hits      uint64  `json:"hits"`
	Misses    uint64  `json:"misses"`
	HitRate   float64 `json:"hit_rate"`
	Evictions uint64  `json:"evictions"`
	TTL       string  `json:"ttl"`
}

type CancellationInfo struct {
	Reason      string `json:"reason"`
	CancelledBy string `json:"cancelled_by"`
	Phase       string `json:"phase"` // "PrePrompt" or "PreExecute"
}

type ChatChoice struct {
	Index        int          `json:"index"`
	Message      *ChatMessage `json:"message,omitempty"`
	Delta        *ChatMessage `json:"delta,omitempty"` // For streaming
	FinishReason string       `json:"finish_reason,omitempty"`
}

type ChatMessage struct {
	Role      string             `json:"role"` // "system", "user", "assistant"
	Content   string             `json:"content"`
	ToolCalls []ChatToolCallWire `json:"tool_calls,omitempty"`
}

type ChatRequest struct {
	Model       string               `json:"model"`
	Messages    []ChatMessage        `json:"messages"`
	Tools       []ChatToolDefinition `json:"tools,omitempty"`
	Stream      bool                 `json:"stream,omitempty"`
	MaxTokens   int                  `json:"max_tokens,omitempty"`
	Temperature float32              `json:"temperature,omitempty"`
	TopP        float32              `json:"top_p,omitempty"`
}

type ChatResponse struct {
	ID      string       `json:"id"`
	Object  string       `json:"object"` // "chat.completion" or "chat.completion.chunk"
	Model   string       `json:"model"`
	Created int64        `json:"created"`
	Choices []ChatChoice `json:"choices"`
	Usage   *ChatUsage   `json:"usage,omitempty"`
}

type ChatToolCallWire struct {
	ID       string               `json:"id"`
	Type     string               `json:"type"`
	Function ChatToolFunctionWire `json:"function"`
}

type ChatToolDefinition struct {
	Type     string                     `json:"type,omitempty"`
	Function ChatToolDefinitionFunction `json:"function"`
}

type ChatToolDefinitionFunction struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	Parameters  json.RawMessage `json:"parameters,omitempty"`
}

type ChatToolFunctionWire struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

type ChatUsage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

type ClusterStats struct {
	NumClusters    int     `json:"num_clusters"`
	EmbeddingCount int     `json:"embedding_count"`
	IsClustered    bool    `json:"is_clustered"`
	AvgClusterSize float64 `json:"avg_cluster_size,omitempty"`
	Iterations     int     `json:"iterations,omitempty"`
}

type Config struct {
	// Enabled controls whether Heimdall (the cognitive guardian) is active.
	// When enabled, Bifrost (the chat interface) is automatically enabled.
	// Default: false (opt-in feature)
	Enabled bool `json:"enabled"`

	// BifrostEnabled controls the Bifrost chat interface.
	// Automatically set to true when Heimdall is enabled.
	// Cannot be enabled independently - Bifrost requires Heimdall.
	BifrostEnabled bool `json:"bifrost_enabled"`

	ModelsDir   string  `json:"models_dir"`
	Model       string  `json:"model"`
	Provider    string  `json:"provider"`     // local, ollama, openai, vllm
	APIURL      string  `json:"api_url"`      // for ollama/openai
	APIKey      string  `json:"api_key"`      // for openai
	ContextSize int     `json:"context_size"` // Context window size (single-shot, max out)
	BatchSize   int     `json:"batch_size"`   // Batch size (match context for single-shot)
	MaxTokens   int     `json:"max_tokens"`
	Temperature float32 `json:"temperature"`
	GPULayers   int     `json:"gpu_layers"`

	// Feature toggles
	AnomalyDetection bool          `json:"anomaly_detection"`
	AnomalyInterval  time.Duration `json:"anomaly_interval"`
	RuntimeDiagnosis bool          `json:"runtime_diagnosis"`
	RuntimeInterval  time.Duration `json:"runtime_interval"`
	MemoryCuration   bool          `json:"memory_curation"`
	CurationInterval time.Duration `json:"curation_interval"`
}

type DatabaseEvent struct {
	// Type identifies what kind of event occurred
	Type DatabaseEventType `json:"type"`

	// Timestamp when the event occurred
	Timestamp time.Time `json:"timestamp"`

	// RequestID links to the originating request (if applicable)
	RequestID string `json:"request_id,omitempty"`

	// NodeID for node events
	NodeID string `json:"node_id,omitempty"`

	// NodeLabels for node events
	NodeLabels []string `json:"node_labels,omitempty"`

	// RelationshipID for relationship events
	RelationshipID string `json:"relationship_id,omitempty"`

	// RelationshipType for relationship events
	RelationshipType string `json:"relationship_type,omitempty"`

	// SourceNodeID for relationship events
	SourceNodeID string `json:"source_node_id,omitempty"`

	// TargetNodeID for relationship events
	TargetNodeID string `json:"target_node_id,omitempty"`

	// Properties that were set/changed
	Properties map[string]interface{} `json:"properties,omitempty"`

	// OldProperties for update events (what was there before)
	OldProperties map[string]interface{} `json:"old_properties,omitempty"`

	// Query is the Cypher query that was executed
	Query string `json:"query,omitempty"`

	// QueryParams are the parameters passed to the query
	QueryParams map[string]interface{} `json:"query_params,omitempty"`

	// Duration of query execution
	Duration time.Duration `json:"duration,omitempty"`

	// RowsAffected by the query
	RowsAffected int64 `json:"rows_affected,omitempty"`

	// Error message if the query failed
	Error string `json:"error,omitempty"`

	// IndexName for index events
	IndexName string `json:"index_name,omitempty"`

	// IndexLabel for index events
	IndexLabel string `json:"index_label,omitempty"`

	// IndexProperty for index events
	IndexProperty string `json:"index_property,omitempty"`

	// UserID who triggered the event (if authenticated)
	UserID string `json:"user_id,omitempty"`

	// Source identifies where the event came from (e.g., "bolt", "http", "internal")
	Source string `json:"source,omitempty"`

	// Metadata for any additional event-specific data
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type DatabaseEventHook interface {
	// OnDatabaseEvent is called when a database event occurs.
	// This is fire-and-forget (does not block database operations).
	// The plugin should handle errors internally and not panic.
	//
	// Events are delivered asynchronously - the database operation
	// has already completed by the time this is called.
	//
	// Plugins can use this to:
	//   - Build audit logs
	//   - Track usage patterns
	//   - Trigger alerts on specific events
	//   - Update caches
	//   - Collect metrics
	OnDatabaseEvent(event *DatabaseEvent)
}

type DatabaseEventType string

type DatabaseMetrics struct {
	NodeCount        int64                  `json:"node_count"`
	EdgeCount        int64                  `json:"edge_count"`
	LabelCounts      map[string]int64       `json:"label_counts,omitempty"`
	IndexCount       int                    `json:"index_count"`
	PropertyIndexes  int                    `json:"property_indexes"`
	CompositeIndexes int                    `json:"composite_indexes"`
	MVCCLifecycle    map[string]interface{} `json:"mvcc_lifecycle,omitempty"`
}

type DatabaseMetricsSource interface {
	// Core stats
	Stats() interface{} // Returns DBStats or similar

	// Node/Edge counts
	NodeCount() (int64, error)
	EdgeCount() (int64, error)

	// Embed queue
	EmbedQueueStats() interface{}

	// Storage engine
	GetAsyncEngine() AsyncEngineStats
	GetWAL() WALStats
	GetSchemaManager() SchemaManagerStats

	// Query cache
	GetQueryCache() QueryCacheStats

	// GPU
	GetGPUManager() GPUManagerStats

	// Encryption
	EncryptionStats() map[string]interface{}
}

type DatabaseRouter interface {
	// DefaultDatabaseName returns the configured default database name.
	DefaultDatabaseName() string

	// ResolveDatabase resolves a database alias or name to the underlying database name.
	ResolveDatabase(nameOrAlias string) (string, error)

	// ListDatabases returns the known logical database names.
	ListDatabases() []string

	// Query executes a Cypher query against the specified logical database.
	//
	// NOTE: Despite the historical "read-only" naming, this method may execute write
	// queries depending on the underlying Cypher engine. Treat it as a general Cypher
	// execution entrypoint unless your implementation enforces read-only semantics.
	Query(ctx context.Context, database string, cypher string, params map[string]interface{}) ([]map[string]interface{}, error)

	// Stats returns database statistics for the specified logical database.
	Stats(database string) (DatabaseStats, error)

	// Discover performs semantic search with graph traversal in the specified database.
	// Returns search results with related nodes up to the specified depth.
	Discover(ctx context.Context, database string, query string, nodeTypes []string, limit int, depth int) (*DiscoverResult, error)
}

type DatabaseStats struct {
	NodeCount         int64            `json:"node_count"`
	RelationshipCount int64            `json:"relationship_count"`
	LabelCounts       map[string]int64 `json:"label_counts"`
	ClusterStats      *ClusterStats    `json:"cluster_stats,omitempty"`
	FeatureFlags      *FeatureFlags    `json:"feature_flags,omitempty"`
}

type DefaultLogger struct {
	// contains filtered or unexported fields
}

type DiscoverResult struct {
	Results []SearchResult `json:"results"`
	Method  string         `json:"method"` // "vector" or "keyword"
	Total   int            `json:"total"`
}

type Embedder interface {
	Embed(ctx context.Context, text string) ([]float32, error)
	ChunkText(text string, maxTokens, overlap int) ([]string, error)
}

type EmbeddingMetrics struct {
	WorkerRunning     bool    `json:"worker_running"`
	Processed         int     `json:"processed"`
	Failed            int     `json:"failed"`
	QueueLength       int     `json:"queue_length"`
	NodesWithEmbed    int64   `json:"nodes_with_embeddings"`
	NodesWithoutEmbed int64   `json:"nodes_without_embeddings"`
	EmbedRate         float64 `json:"embed_rate"`
	Provider          string  `json:"provider"`
	Model             string  `json:"model"`
	Dimensions        int     `json:"dimensions"`
}

type FeatureFlags struct {
	// Core Heimdall flags
	HeimdallEnabled          bool `json:"heimdall_enabled"`
	HeimdallAnomalyDetection bool `json:"heimdall_anomaly_detection"`
	HeimdallRuntimeDiagnosis bool `json:"heimdall_runtime_diagnosis"`
	HeimdallMemoryCuration   bool `json:"heimdall_memory_curation"`

	// Clustering (derived from search stats)
	ClusteringEnabled bool `json:"clustering_enabled"`

	// Topology/prediction flags
	TopologyEnabled bool `json:"topology_enabled"`
	KalmanEnabled   bool `json:"kalman_enabled"`

	// Runtime flags (derived from DB state)
	AsyncWritesEnabled bool `json:"async_writes_enabled"`
}

type FeatureFlagsSource interface {
	GetHeimdallEnabled() bool
	GetHeimdallModel() string
	GetHeimdallProvider() string
	GetHeimdallAPIURL() string
	GetHeimdallAPIKey() string
	GetHeimdallGPULayers() int
	GetHeimdallContextSize() int
	GetHeimdallBatchSize() int
	GetHeimdallMaxTokens() int
	GetHeimdallTemperature() float32
	GetHeimdallAnomalyDetection() bool
	GetHeimdallRuntimeDiagnosis() bool
	GetHeimdallMemoryCuration() bool
	GetHeimdallMaxContextTokens() int
	GetHeimdallMaxSystemTokens() int
	GetHeimdallMaxUserTokens() int
}

type FullLifecycleHook interface {
	PrePromptHook
	PreExecuteHook
	PostExecuteHook
	SynthesisHook
	DatabaseEventHook
}

type GPUManagerStats interface {
	IsEnabled() bool
	Device() interface{}
	Stats() interface{}
	AllocatedMemoryMB() int
}

type GPUMetrics struct {
	Available     bool   `json:"available"`
	Enabled       bool   `json:"enabled"`
	DeviceName    string `json:"device_name,omitempty"`
	Backend       string `json:"backend,omitempty"`
	MemoryMB      int    `json:"memory_mb,omitempty"`
	AllocatedMB   int    `json:"allocated_mb"`
	OperationsGPU int64  `json:"operations_gpu"`
	OperationsCPU int64  `json:"operations_cpu"`
	FallbackCount int64  `json:"fallback_count"`
}

type GenerateParams struct {
	MaxTokens   int
	Temperature float32
	TopP        float32
	TopK        int
	StopTokens  []string
}

type Generator interface {
	// Generate produces a complete response.
	Generate(ctx context.Context, prompt string, params GenerateParams) (string, error)

	// GenerateStream produces tokens via callback.
	GenerateStream(ctx context.Context, prompt string, params GenerateParams, callback func(token string) error) error

	// Close releases model resources.
	Close() error

	// ModelPath returns the loaded model path.
	ModelPath() string
}

type GeneratorLoader func(modelPath string, gpuLayers, contextSize, batchSize int) (Generator, error)

type GeneratorWithTools interface {
	Generator

	// GenerateWithTools runs one round of chat with tools. messages is the full conversation
	// so far (system, user, optional assistant+tool_calls, tool results, ...). Returns content
	// (text reply) and/or toolCalls. Handler executes toolCalls, appends messages, and calls
	// again until toolCalls is empty (agentic loop).
	GenerateWithTools(ctx context.Context, messages []ToolRoundMessage, tools []MCPTool, params GenerateParams) (content string, toolCalls []ParsedToolCall, err error)
}

type GraphEdge struct {
	ID         string
	Type       string
	SourceID   string
	TargetID   string
	Properties map[string]interface{}
}

type Handler struct {
	// contains filtered or unexported fields
}

type HeimdallInvoker interface {
	// InvokeAction directly invokes a registered action by name.
	// The action must be registered (e.g., "heimdall_watcher_status").
	// Results are returned synchronously.
	//
	// Example:
	//   result, err := ctx.Heimdall.InvokeAction("heimdall_anomaly_detect", map[string]interface{}{
	//       "threshold": 0.8,
	//   })
	InvokeAction(ctx context.Context, action string, params map[string]interface{}) (*ActionResult, error)

	// SendPrompt sends a natural language prompt to the SLM for processing.
	// The SLM will interpret the prompt and may invoke registered actions.
	// Results are returned after the SLM processes the request.
	//
	// Example:
	//   result, err := ctx.Heimdall.SendPrompt("Analyze recent error patterns")
	SendPrompt(ctx context.Context, prompt string) (*ActionResult, error)

	// InvokeActionAsync invokes an action without waiting for result.
	// Use this for fire-and-forget scenarios where you don't need the result.
	// Results will be broadcast via Bifrost to connected clients.
	InvokeActionAsync(action string, params map[string]interface{})

	// SendPromptAsync sends a prompt without waiting for result.
	// Results will be broadcast via Bifrost to connected clients.
	SendPromptAsync(prompt string)

	// SendRawPrompt sends a prompt directly to the LLM without action routing context.
	// Use this for synthesis or direct question-answering where you don't want
	// the SLM to try parsing actions from the response.
	//
	// Example:
	//   result, err := ctx.Heimdall.SendRawPrompt("Answer this question: How many nodes?")
	SendRawPrompt(ctx context.Context, prompt string) (*ActionResult, error)
}

type HeimdallPlugin interface {

	// Name returns the plugin/subsystem identifier (e.g., "anomaly", "health", "curator")
	Name() string

	// Version returns the plugin version (semver format)
	Version() string

	// Type must return "heimdall" to identify this as a Heimdall plugin
	Type() string

	// Description returns human-readable description of what this subsystem does
	Description() string

	// Initialize is called when the subsystem is loaded
	// Receives context for accessing database, config, etc.
	Initialize(ctx SubsystemContext) error

	// Start begins the subsystem's background operations (if any)
	Start() error

	// Stop halts the subsystem's background operations
	Stop() error

	// Shutdown is called when the subsystem is being unloaded
	Shutdown() error

	// Status returns current subsystem status
	Status() SubsystemStatus

	// Health returns detailed health information
	Health() SubsystemHealth

	// Metrics returns subsystem-specific metrics for the SLM to analyze
	Metrics() map[string]interface{}

	// Config returns current configuration
	Config() map[string]interface{}

	// Configure updates subsystem configuration
	// The SLM can use this to tune subsystem behavior
	Configure(settings map[string]interface{}) error

	// Schema returns the configuration schema (for validation)
	ConfigSchema() map[string]interface{}

	// Actions returns all actions this subsystem provides
	// Map key is the action name (e.g., "detect"), will be prefixed as slm.{name}.{action}
	Actions() map[string]ActionFunc

	// Summary returns a text summary of current subsystem state
	// Used by SLM to understand what the subsystem is doing
	Summary() string

	// RecentEvents returns recent notable events from this subsystem
	// Used by SLM for contextual awareness
	RecentEvents(limit int) []SubsystemEvent
}

type InMemoryToolRunner interface {
	// ToolDefinitions returns tool definitions for the LLM (name, description, inputSchema).
	ToolDefinitions() []MCPTool
	// ToolNames returns the list of tool names this runner handles (for dispatch).
	ToolNames() []string
	// CallTool executes the named tool with the given arguments in the given database context.
	// dbName is the logical database name (e.g. from DefaultDatabaseName()); use "" for default.
	CallTool(ctx context.Context, name string, args map[string]interface{}, dbName string) (interface{}, error)
}

type LiveHeimdallInvoker struct {
	// contains filtered or unexported fields
}

type LoadedHeimdallPlugin struct {
	Plugin  HeimdallPlugin // The actual plugin implementing full interface
	Path    string         // Path to .so file (empty for built-in)
	Builtin bool           // True if this is a built-in plugin
}

type MCPTool struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	InputSchema json.RawMessage `json:"inputSchema"`
}

type Manager struct {
	// contains filtered or unexported fields
}

type ManagerStats struct {
	ModelPath    string    `json:"model_path"`
	RequestCount int64     `json:"request_count"`
	ErrorCount   int64     `json:"error_count"`
	LastUsed     time.Time `json:"last_used"`
	Enabled      bool      `json:"enabled"`
}

type MetricsCollector struct {
	// contains filtered or unexported fields
}

type MetricsReader interface {
	// Runtime returns current runtime metrics
	Runtime() RuntimeMetrics
}

type ModelInfo struct {
	Name         string    `json:"name"`
	Path         string    `json:"path"`
	Type         ModelType `json:"type"`
	SizeBytes    int64     `json:"size_bytes"`
	Quantization string    `json:"quantization,omitempty"`
	Loaded       bool      `json:"loaded"`
	LastUsed     time.Time `json:"last_used,omitempty"`
	VRAMEstimate int64     `json:"vram_estimate_bytes"`
}

type ModelType string

type NoOpBifrost struct{}

type NoOpHeimdallInvoker struct{}

type NodeData struct {
	ID         string
	Labels     []string
	Properties map[string]interface{}
}

type NornicDBMetrics struct {
	// Server metrics
	Server ServerMetrics `json:"server"`

	// Database metrics
	Database DatabaseMetrics `json:"database"`

	// Storage engine metrics
	Storage StorageMetrics `json:"storage"`

	// Cache metrics
	Cache CacheMetrics `json:"cache"`

	// Embedding metrics
	Embedding EmbeddingMetrics `json:"embedding"`

	// GPU metrics
	GPU GPUMetrics `json:"gpu"`

	// Query metrics
	Query QueryMetrics `json:"query"`

	// Runtime metrics
	Runtime RuntimeMetrics `json:"runtime"`

	// Timestamp
	CollectedAt time.Time `json:"collected_at"`
}

type ParsedAction struct {
	Action string                 `json:"action"`
	Params map[string]interface{} `json:"params"`
}

type ParsedToolCall struct {
	Id        string
	Name      string
	Arguments string
}

type PluginOrdering interface {
	// Priority controls ordering when there are no explicit dependencies.
	// Higher values run earlier.
	Priority() int

	// Before lists plugin names that must run after this plugin.
	Before() []string

	// After lists plugin names that must run before this plugin.
	After() []string
}

type PostExecuteContext struct {
	// Context carries request cancellation and deadlines.
	Context context.Context

	// RequestID for tracking
	RequestID string

	// Action that was executed
	Action string

	// Params that were passed
	Params map[string]interface{}

	// Result from the action execution
	Result *ActionResult

	// Duration of action execution
	Duration time.Duration

	// PluginData from earlier phases
	PluginData map[string]interface{}

	// WasCancelled indicates if the request was cancelled in an earlier phase
	WasCancelled bool

	// CancellationInfo contains details if cancelled
	CancellationInfo *CancellationInfo
	// contains filtered or unexported fields
}

type PostExecuteHook interface {
	// PostExecute is called AFTER action execution completes.
	// Plugins can:
	//   - Log execution metrics
	//   - Update internal state
	//   - Cache results
	//   - Trigger side effects
	// This is fire-and-forget (does not block response).
	PostExecute(ctx *PostExecuteContext)
}

type PreExecuteContext struct {
	// Context carries request cancellation and deadlines.
	Context context.Context

	// RequestID for tracking
	RequestID string

	// RequestTime when the request started
	RequestTime time.Time

	// Action is the parsed action name (e.g., "heimdall_watcher_status")
	Action string

	// Params are the parsed action parameters
	Params map[string]interface{}

	// RawResponse is the raw SLM response (for inspection if needed)
	RawResponse string

	// PluginData from the PrePrompt phase
	PluginData map[string]interface{}

	// Database routes Cypher/search operations across logical databases.
	Database DatabaseRouter

	// Metrics provides runtime metrics
	Metrics MetricsReader

	// PrincipalRoles are the authenticated principal's role names (from request context).
	PrincipalRoles []string

	// DatabaseAccessMode is the principal's per-database see/access mode (from request context).
	DatabaseAccessMode auth.DatabaseAccessMode

	// ResolvedAccess returns per-database read/write for the principal (from request context).
	ResolvedAccess func(dbName string) auth.ResolvedAccess
	// contains filtered or unexported fields
}

type PreExecuteHook interface {
	// PreExecute is called AFTER Heimdall responds, BEFORE action execution.
	// Plugins can perform async operations:
	//   - Fetch additional data from external services
	//   - Validate/modify params
	//   - Abort execution by setting Continue=false
	// The done callback MUST be called when complete.
	PreExecute(ctx *PreExecuteContext, done func(PreExecuteResult))
}

type PreExecuteResult struct {
	// Continue indicates whether to proceed with execution.
	// Set to false to abort the action.
	Continue bool

	// ModifiedParams replaces the original params if non-nil.
	ModifiedParams map[string]interface{}

	// AdditionalContext is merged into ActionContext.
	AdditionalContext map[string]interface{}

	// AbortMessage is returned to user if Continue=false.
	AbortMessage string

	// Error if something went wrong during pre-execute.
	Error error
}

type PrePromptHook interface {
	// PrePrompt is called BEFORE sending the prompt to Heimdall.
	// The ActionPrompt field is IMMUTABLE (already set, read-only).
	// Plugins can modify mutable fields:
	//   - AdditionalInstructions: Add context, constraints, guidance
	//   - Examples: Add domain-specific examples
	//   - PluginData: Store state for later phases
	// Return error to log warning (does not abort request).
	PrePrompt(ctx *PromptContext) error
}

type PromptBudgetInfo struct {
	SystemTokens    int `json:"system_tokens"`
	UserTokens      int `json:"user_tokens"`
	TotalTokens     int `json:"total_tokens"`
	MaxSystem       int `json:"max_system"`
	MaxUser         int `json:"max_user"`
	MaxTotal        int `json:"max_total"`
	SystemAvailable int `json:"system_available"`
	UserAvailable   int `json:"user_available"`
}

type PromptContext struct {
	// Context carries request cancellation and deadlines.
	Context context.Context

	// RequestID for tracking through the lifecycle
	RequestID string

	// RequestTime when the request started
	RequestTime time.Time

	// ActionPrompt contains all registered actions formatted for the SLM.
	// This is always injected at the start of the system prompt.
	// Plugins CANNOT modify this field.
	ActionPrompt string

	// UserMessage is the current user input
	UserMessage string

	// Messages is the full conversation history
	Messages []ChatMessage

	// ExternalTools are tool definitions provided by the client (e.g. Continue/OpenAI tools).
	// These are exposed to the underlying model in addition to Heimdall's built-in actions.
	ExternalTools []MCPTool

	// AdditionalInstructions are appended after ActionPrompt.
	// Plugins add context, constraints, or guidance here.
	AdditionalInstructions string

	// Examples help Heimdall understand user intent.
	// Plugins can add domain-specific examples.
	Examples []PromptExample

	// PluginData persists through the request lifecycle.
	// Plugins can store state here for use in PreExecute/PostExecute.
	PluginData map[string]interface{}
	// contains filtered or unexported fields
}

type PromptExample struct {
	UserSays   string // What the user might say
	ActionJSON string // The JSON action Heimdall should output
}

type QueryCacheStats interface {
	Stats() interface{}
}

type QueryDatabase interface {
	// Query executes a read-only Cypher query
	Query(ctx context.Context, cypher string, params map[string]interface{}) ([]map[string]interface{}, error)

	// Stats returns basic database stats
	Stats() interface{}

	// NodeCount returns total nodes
	NodeCount() (int64, error)

	// EdgeCount returns total edges
	EdgeCount() (int64, error)
}

type QueryExecutor struct {
	// contains filtered or unexported fields
}

type QueryMetrics struct {
	TotalQueries     int64         `json:"total_queries"`
	SlowQueries      int64         `json:"slow_queries"`
	AvgExecutionTime time.Duration `json:"avg_execution_time"`
	CacheHitRate     float64       `json:"cache_hit_rate"`
	ThresholdMs      int64         `json:"threshold_ms"`
}

type QueuedNotification struct {
	Type    string `json:"type"` // "info", "warning", "error", "success", "progress"
	Title   string `json:"title"`
	Message string `json:"message"`
}

type RealMetricsReader struct{}

type RelatedNode struct {
	ID           string `json:"id"`
	Type         string `json:"type,omitempty"`
	Title        string `json:"title,omitempty"`
	Distance     int    `json:"distance"`            // Hops from the source node
	Relationship string `json:"relationship"`        // Relationship type
	Direction    string `json:"direction,omitempty"` // "incoming", "outgoing", or ""
	Path         string `json:"path,omitempty"`      // Path description
}

type RuntimeMetrics struct {
	GoroutineCount int    `json:"goroutine_count"`
	MemoryAllocMB  uint64 `json:"memory_alloc_mb"`
	NumGC          uint32 `json:"num_gc"`
}

type SchemaManagerStats interface {
	GetIndexStats() interface{}
}

type SearchResult struct {
	ID             string                 `json:"id"`
	Type           string                 `json:"type"`
	Title          string                 `json:"title,omitempty"`
	ContentPreview string                 `json:"content_preview,omitempty"`
	Similarity     float64                `json:"similarity"`
	Properties     map[string]interface{} `json:"properties,omitempty"`
	Related        []RelatedNode          `json:"related,omitempty"`
}

type SemanticSearchResult struct {
	ID         string
	Labels     []string
	Properties map[string]interface{}
	Score      float64
}

type SemanticSearcher interface {
	// HybridSearch performs vector + text search with pre-computed embedding
	HybridSearch(ctx context.Context, query string, queryEmbedding []float32, labels []string, limit int) ([]*SemanticSearchResult, error)
	// Search performs full-text BM25 search
	Search(ctx context.Context, query string, labels []string, limit int) ([]*SemanticSearchResult, error)
	// Neighbors returns connected node IDs
	Neighbors(ctx context.Context, nodeID string) ([]string, error)
	// GetEdgesForNode returns edges for a node
	GetEdgesForNode(ctx context.Context, nodeID string) ([]*GraphEdge, error)
	// GetNode retrieves a node by ID
	GetNode(ctx context.Context, nodeID string) (*NodeData, error)
}

type ServerMetrics struct {
	Uptime         time.Duration `json:"uptime"`
	RequestsTotal  int64         `json:"requests_total"`
	ErrorsTotal    int64         `json:"errors_total"`
	ActiveRequests int64         `json:"active_requests"`
	SlowQueryCount int64         `json:"slow_query_count"`
	RequestsPerSec float64       `json:"requests_per_sec"`
}

type ServerMetricsSource interface {
	Stats() interface{}
	SlowQueryCount() int64
}

type StorageMetrics struct {
	// Async engine stats
	PendingWrites int64 `json:"pending_writes"`
	TotalFlushes  int64 `json:"total_flushes"`

	// WAL stats
	WALSequence    uint64    `json:"wal_sequence"`
	WALEntries     uint64    `json:"wal_entries"`
	WALBytes       uint64    `json:"wal_bytes"`
	WALTotalWrites uint64    `json:"wal_total_writes"`
	WALTotalSyncs  uint64    `json:"wal_total_syncs"`
	WALLastSync    time.Time `json:"wal_last_sync"`

	// Node config stats
	NodeConfigs    int64   `json:"node_configs"`
	ConfigChecks   int64   `json:"config_checks"`
	ConfigsBlocked int64   `json:"configs_blocked"`
	BlockRate      float64 `json:"block_rate"`

	// Edge meta stats
	EdgeMetaRecords      int64            `json:"edge_meta_records"`
	EdgeMetaMaterialized int64            `json:"edge_meta_materialized"`
	EdgeMetaBySignal     map[string]int64 `json:"edge_meta_by_signal,omitempty"`
}

type StreamEvent struct {
	Event string `json:"event,omitempty"` // "message", "done", "error"
	Data  string `json:"data"`
}

type SubsystemContext struct {
	// Config is the Heimdall configuration
	Config Config

	// Database routes Cypher/search operations across logical databases.
	// This is multi-database aware (Neo4j 4.x style) and should be used instead of
	// relying on a single default database.
	Database DatabaseRouter

	// Metrics provides runtime metrics
	Metrics MetricsReader

	// Logger for subsystem logging
	Logger SubsystemLogger

	// Bifrost provides the communication bridge to connected clients
	// Plugins can use this to send messages, notifications, and request input
	Bifrost BifrostBridge

	// Heimdall provides autonomous action invocation for plugins.
	// Plugins can use this to trigger actions or send prompts to the SLM
	// based on accumulated events or other triggers.
	Heimdall HeimdallInvoker
}

type SubsystemEvent struct {
	Time    time.Time              `json:"time"`
	Type    string                 `json:"type"` // "info", "warning", "error", "action"
	Message string                 `json:"message"`
	Data    map[string]interface{} `json:"data,omitempty"`
}

type SubsystemHealth struct {
	Status    SubsystemStatus        `json:"status"`
	Healthy   bool                   `json:"healthy"`
	Message   string                 `json:"message,omitempty"`
	LastCheck time.Time              `json:"last_check"`
	Details   map[string]interface{} `json:"details,omitempty"`
}

type SubsystemLogger interface {
	Debug(msg string, args ...interface{})
	Info(msg string, args ...interface{})
	Warn(msg string, args ...interface{})
	Error(msg string, args ...interface{})
}

type SubsystemManager struct {
	// contains filtered or unexported fields
}

type SubsystemStatus string

type SynthesisContext struct {
	// Context carries request cancellation and deadlines.
	Context context.Context

	// RequestID for tracking
	RequestID string

	// UserQuestion is the original user message
	UserQuestion string

	// Action that was executed
	Action string

	// Result from the action execution
	Result *ActionResult

	// PluginData from earlier phases
	PluginData map[string]interface{}

	// Database routes Cypher/search operations across logical databases.
	Database DatabaseRouter
}

type SynthesisHook interface {
	// Synthesize transforms action results into a user-friendly response.
	//
	// Return values:
	//   - Non-empty string: Use this as the final response (skips default synthesis)
	//   - Empty string: Continue with default LLM-based synthesis
	//
	// The done callback MUST be called when complete.
	Synthesize(ctx *SynthesisContext, done func(response string))
}

type TokenBudget struct {
	MaxContext int // Total context window
	MaxSystem  int // System prompt budget
	MaxUser    int // User message budget
}

type ToolRoundMessage struct {
	Role       string           // "system", "user", "assistant", "tool"
	Content    string           // For tool role: the result content (e.g. JSON or text)
	ToolCalls  []ParsedToolCall // For assistant: tool invocations from the model
	ToolCallID string           // For tool role: which call this result is for (OpenAI id)
}

type WALStats interface {
	Stats() interface{}
}