core

type Action interface {
	// Execute performs the action's logic.
	Execute(ctx context.Context, input Envelope) (Envelope, error)

	// Metadata returns the action's metadata.
	Metadata() ActionMetadata
}

type ActionEnvelope struct {
	Name      string                 // Action name matching Registry (e.g., "generate_csd")
	Arguments map[string]interface{} // Parameters derived from Datalog bindings
	SessionID string                 // Session ID for accessing TransientStore
}

type ActionMetadata struct {
	// Name is the unique identifier for the action.
	Name string
	// Type describes the category of the action.
	Type string
	// InputContentType specifies the expected input format.
	InputContentType ContentType
	// InputType is the string name of the Go input type.
	InputType string
	// OutputType is the string name of the Go output type.
	OutputType string
	// IsDynamic indicates if the input type is generic.
	IsDynamic bool
}

type AgentMemory interface {
	// --- Sequential History ---
	// Read retrieves the chat history for a given session.
	Read(ctx context.Context, sessionID string) ([]Message, error)
	// Append adds new messages to the history.
	Append(ctx context.Context, sessionID string, msgs []Message) error

	// --- Semantic Memory (RAG) ---
	// Recall retrieves relevant context based on the current query.
	Recall(ctx context.Context, query string) (string, error)
	// Memorize stores a new interaction (Input/Output) for future recall.
	Memorize(ctx context.Context, query string, answer string) error

	// Init performs any necessary setup (e.g. connecting to DB).
	Init(ctx context.Context) error
}

type AgentMemoryWithFacts interface {
	AgentMemory
	// RecallWithFacts retrieves context and associated metadata (e.g. doc IDs).
	RecallWithFacts(ctx context.Context, query string) (string, map[string]any, error)
}

type AlignmentError struct {
	Message string
	RuleID  string
}

type Answer struct {
	Text string         `json:"text"`
	Meta map[string]any `json:"meta,omitempty"`
}

type Atom struct {
	Predicate    string    `json:"predicate"`
	Subject      string    `json:"subject"`
	Object       string    `json:"object"`
	Weight       float64   `json:"weight"` // 1.0 (Fact) to 0.1 (Guess)
	OriginIntent IntentStr `json:"origin_intent,omitempty"`
}

type AuditRecord struct {
	Step         int            `json:"step"`
	Rules        []RuleSnapshot `json:"rules"`
	Outcome      string         `json:"outcome"` // "PROCEED", "HALT", "RETRY", "ROUTE"
	Timestamp    string         `json:"timestamp"`
	LatencyMs    int64          `json:"latency_ms"`
	FactCount    int            `json:"fact_count"`
	MatchedCount int            `json:"matched_count"`
}

type AuditTrail struct {
	MatchedRules []RuleInference // The rules that matched and contributed to the decision
	Timestamp    time.Time       // When the decision was made
	EngineID     string          // Identifier for the policy engine instance
	Query        string          // The original query that was evaluated
	FactCount    int             // Number of facts evaluated
	MatchedCount int             // Number of matching results
	LatencyMs    int64           // Time taken to evaluate (for performance monitoring)
}

type Breaker interface {
	Execute(req func() (any, error)) (any, error)
	Name() string
}

type ConfigEvent struct {
	Key     string
	Content []byte
	Type    string
}

type ContentType string

type ConversationHistory struct {
	// Messages is the ordered list of messages in the conversation.
	Messages []Message `json:"messages"`
}

type Decision struct {
	Outcome    string            // Matches DecisionProceed, DecisionHalt, etc.
	Target     string            // Used if Outcome == DecisionRoute
	Reasons    []string          // Explanations
	Meta       map[string]string // Side-channel data (risk scores, latency budget)
	AuditTrail *AuditTrail       // Detailed execution trace
	Action     *ActionEnvelope   // Action to be executed (decoupled from Go implementation)
}

type Document struct {
	ID       string         `json:"id,omitempty"`
	Content  string         `json:"content"`
	Vector   []float32      `json:"vector,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
	Score    float32        `json:"score,omitempty"` // Re-ranking score
}

type EdgeDef struct {
	From      string
	To        string
	Condition string
}

type Embedder interface {
	// Embed generates a vector for a single text string.
	Embed(ctx context.Context, text string) ([]float32, error)

	// EmbedBatch generates vectors for multiple strings.
	EmbedBatch(ctx context.Context, texts []string) ([][]float32, error)

	// Dimension returns the vector size (e.g., 768 for Google GenAI).
	Dimension() int
}

type Envelope struct {
	// ID is the unique identifier for this specific data envelope.
	ID uuid.UUID `json:"id"`
	// Payload is the actual data being transported.
	// Note: Field name preserved as Payload for compatibility, tagged as "data".
	Payload any `json:"data"`
	// Metadata stores key-value pairs for control plane signaling.
	Metadata map[string]any `json:"metadata,omitempty"`
	// Error stores any error encountered during processing.
	Error error `json:"error,omitempty"`

	// SecurityLabels holds taint tags (e.g., "secret", "pii") for information flow control.
	SecurityLabels []string `json:"security_labels,omitempty"`
	// Facts holds structured logical facts extracted from the payload.
	Facts []string `json:"facts,omitempty"`
	// ContentType indicates whether the payload is a Struct or JSON.
	ContentType ContentType `json:"content_type,omitempty"`

	// ContextFacts contains flattened quad facts for Datalog evaluation.
	ContextFacts []Quad `json:"context_facts,omitempty"`
	// Violations holds GenePool axiom violations after Shadow Audit.
	Violations []ViolationRule `json:"violations,omitempty"`
}

type Evaluator interface {
	// AssessPlan evaluates the policy for a given input (General purpose).
	// It returns a Decision struct with the outcome.
	// Formerly: Assess
	AssessPlan(ctx context.Context, input Envelope) (Decision, error)

	// Assess performs the Pre-Check phase (input validation).
	// Formerly: Authorize
	Assess(ctx context.Context, actionMeta ActionMetadata, input Envelope) error

	// Reflect evaluates the outcome of an action (Post-Check).
	// Formerly: Validate
	Reflect(ctx context.Context, actionMeta ActionMetadata, output Envelope) (Envelope, error)

	// EvaluateSteering determines the next step (Retry/Route) based on the output.
	EvaluateSteering(ctx context.Context, input Envelope) (string, map[string]string, error)

	// GetActionConfig queries the engine for dynamic configuration parameters.
	GetActionConfig(ctx context.Context, input Envelope) (map[string]string, error)

	// CheckRequirement checks if a capability is needed. e.g., requires(Req, "memory").
	CheckRequirement(ctx context.Context, input Envelope, reqName string) (bool, error)

	// LoadPolicy loads policy rules from a source string or file content.
	LoadPolicy(ctx context.Context, source string) error

	// LoadGherkinPolicy loads a Gherkin feature file and compiles it to Datalog.
	LoadGherkinPolicy(ctx context.Context, featureContent string) error

	// LoadFacts injects dynamic facts into the engine.
	LoadFacts(facts []string) error

	// RegisterAction registers action metadata for discovery/planning.
	RegisterAction(meta ActionMetadata) error

	// Query executes a Datalog query and returns all matching solutions.
	// It is used by the planner to reason about goals and generate action sequences.
	Query(ctx context.Context, facts []string, queryStr string) ([]map[string]string, error)

	// Logger returns the engine's logger.
	Logger() Logger
}

type ExecutionContext struct {
	// RetryCount tracks the number of retry attempts for the current action.
	RetryCount int `json:"retry_count"`
	// FeedbackHistory stores all feedback messages from previous retry attempts.
	FeedbackHistory []string `json:"feedback_history,omitempty"`
	// CurrentHistory contains the conversation history for this session.
	CurrentHistory []Message `json:"current_history,omitempty"`
}

type Extractor interface {
	Extract(ctx context.Context, input string, schema any) error
}

type FactLoader interface {
	LoadFacts(ctx context.Context, source string) ([]string, error)
}

type GenerateOption func(o *GenerationConfig)

type GenerationConfig struct {
	Temperature   float64
	MaxTokens     int
	TopP          float64
	StopSequences []string
	Model         string
	JSONMode      bool
	// OutputType is used by Genkit to enforce structured output (schema).
	OutputType any
	// Metadata stores arbitrary per-request metadata (e.g., middleware config).
	Metadata map[string]any
}

type HistoryStore interface {
	// Read retrieves the chat history for a given session.
	Read(ctx context.Context, sessionID string) ([]Message, error)

	// Append adds new messages to the history.
	Append(ctx context.Context, sessionID string, msgs []Message) error
}

type InputError struct {
	Err error
}

type IntentStr string

type LLMResponse struct {
	Text  string
	Usage map[string]int
}

type Logger interface {
	// Debug records verbose diagnostic information about control flow or
	// intermediate state. Arguments are interpreted as key/value pairs.
	Debug(msg string, fields ...any)

	// Info records high-level lifecycle events such as component start or
	// stop. Arguments are interpreted as key/value pairs.
	Info(msg string, fields ...any)

	// Warn records recoverable issues that deserve operator attention but
	// do not stop execution. Arguments are interpreted as key/value pairs.
	Warn(msg string, fields ...any)

	// Error records failures. Implementations should treat the "error"
	// key specially when present. Arguments are interpreted as key/value pairs.
	Error(msg string, fields ...any)

	// With returns a child logger that automatically appends the supplied
	// key/value pairs to every log record.
	With(fields ...any) Logger
}

type MemoryMode string

type Message struct {
	// Role indicates the sender of the message.
	Role string `json:"role"`
	// Content is the textual body of the message.
	Content string `json:"content"`
}

type Meter interface {
	Counter(name string, val int64, tags map[string]string)
	Histogram(name string, val float64, tags map[string]string)
}

type NodeDef struct {
	ID        string
	AgentRole string
	TaskType  string
	Config    map[string]interface{}
}

type NodeResult struct {
	NodeID     string
	AgentID    string
	Input      interface{}
	Output     interface{}
	Error      error
	StartTime  time.Time
	Duration   time.Duration
	RetryCount int
}

type NopEmbedder struct{}

type NopLogger struct{}

type NopSpan struct{}

type NopStore struct{}

type NopTracer struct{}

type NopVectorStore struct{}

type PolicyViolationError struct {
	Tier       string
	RuleID     string
	Violation  string
	Suggestion string
}

type PreProcessor interface {
	Process(ctx context.Context, input Envelope) (map[string]any, error)
}

type Quad struct {
	Subject   string // Source entity (e.g., "User:Bob")
	Predicate string // Relationship (e.g., "has_role")
	Object    string // Target value (e.g., "Admin", "42")
	Graph     string // Namespace/Context (e.g., "global")
}

type Query struct {
	Text string         `json:"text"`
	Meta map[string]any `json:"meta,omitempty"`
}

type ResourceMonitor interface {
	CountTokens(ctx context.Context, text string) (int, error)
	CheckBudget(ctx context.Context, key string, cost int) (bool, error)
}

type RiskEngine interface {
	CalculateRisk(ctx context.Context, input Envelope) (float64, error)
}

type RuleInference struct {
	RuleName   string            // The name/ID of the rule (e.g., "can_execute")
	Tier       Tier              // The governance tier (T0_Axiom, T1_Governance, T2_Playbook, T3_User)
	Definition string            // The original Datalog rule definition
	SourceFile string            // Source file where the rule was defined
	Bindings   map[string]string // Variable bindings from unification (e.g., X="agent-001")
	Predicate  string            // The predicate name that matched
}

type RuleSnapshot struct {
	RuleName   string            `json:"rule_name"`
	Tier       string            `json:"tier"`
	Definition string            `json:"definition,omitempty"`
	SourceFile string            `json:"source_file,omitempty"`
	Predicate  string            `json:"predicate,omitempty"`
	Bindings   map[string]string `json:"bindings,omitempty"`
}

type SessionState struct {
	// SessionID is the unique identifier for the persistent thread.
	SessionID string `json:"session_id"`

	// ActiveEnvelope is the current envelope including Payload, Metadata, and Labels.
	ActiveEnvelope Envelope `json:"active_envelope"`

	// ExecutionCtx contains the current RetryCount, FeedbackHistory, and CurrentHistory.
	ExecutionCtx ExecutionContext `json:"execution_context"`

	// LogicalFacts are the Datalog facts derived during the last successful reflection.
	LogicalFacts []string `json:"logical_facts,omitempty"`

	// PayloadType stores the Go type name of the payload for reconstruction.
	// This is used during hydration to unmarshal the payload back to its original type.
	PayloadType string `json:"payload_type,omitempty"`

	// AuditRecords captures the governance audit trail across steps.
	// Each entry records which rules matched, their tier, and the decision made.
	// Appended per step — never overwritten.
	AuditRecords []AuditRecord `json:"audit_records,omitempty"`
}

type Span interface {
	End()
	SetAttributes(attributes map[string]any)
	SetStatus(code string, msg string)
	RecordError(err error)
}

type StateManager interface {
	// Hydrate reconstructs a session state from durable storage.
	// Returns nil, nil if the session does not exist (first run).
	Hydrate(ctx context.Context, sessionID string) (*SessionState, error)

	// Checkpoint persists the current session state after a successful execution.
	Checkpoint(ctx context.Context, state *SessionState) error

	// ExtractFacts extracts Datalog facts from an envelope for persistence.
	ExtractFacts(ctx context.Context, envelope Envelope) ([]string, error)
}

type StateProvider interface {
	// Get retrieves the state associated with a session ID.
	//
	// Parameters:
	//   - ctx: Context for cancellation.
	//   - sessionID: The unique identifier for the session.
	//
	// Returns:
	//   - The state object (as any), or an error if retrieval fails.
	Get(ctx context.Context, sessionID string) (any, error)

	// Set stores the state for a session ID.
	//
	// Parameters:
	//   - ctx: Context for cancellation.
	//   - sessionID: The unique identifier for the session.
	//   - state: The state object to store.
	//
	// Returns:
	//   - An error if the operation fails.
	Set(ctx context.Context, sessionID string, state any) error

	// Delete removes the state for a session ID.
	//
	// Parameters:
	//   - ctx: Context for cancellation.
	//   - sessionID: The unique identifier for the session.
	//
	// Returns:
	//   - An error if the operation fails.
	Delete(ctx context.Context, sessionID string) error

	// Close cleans up any resources held by the provider (e.g., database connections).
	//
	// Parameters:
	//   - ctx: Context for cancellation.
	//
	// Returns:
	//   - An error if cleanup fails.
	Close(ctx context.Context) error
}

type StreamChunk struct {
	Text string
	Err  error
}

type SupervisorError struct {
	Reason error
}

type TextGenerator interface {
	// Complete generates text from a prompt.
	Complete(ctx context.Context, prompt string) (string, error)

	// Generate generates text with options.
	Generate(ctx context.Context, prompt string, opts ...GenerateOption) (*LLMResponse, error)

	// Stream generates a stream of text.
	Stream(ctx context.Context, prompt string) (<-chan StreamChunk, error)
}

type Tier string

type Tracer interface {
	// Start creates a new span with the given name and returns a context and span.
	Start(ctx context.Context, name string) (context.Context, Span)
}

type ValidationError struct {
	Field   string
	Message string
}

type VectorStore interface {
	Upsert(ctx context.Context, id string, content string) error
	Search(ctx context.Context, query string, topK int) ([]string, error)
	Get(ctx context.Context, id string) (string, error)
}

type ViolationRule struct {
	RuleID      string `json:"rule_id"`
	Description string `json:"description"`
	Severity    int    `json:"severity"` // 0 = Halt, 1 = Retry, 2 = Warn
}

type WorkflowDef struct {
	ID         string
	Name       string
	Version    string
	RootNodeID string
	Nodes      map[string]NodeDef
	Edges      []EdgeDef
}

type WorkflowInstance struct {
	WorkflowID     string                 // Reference to WorkflowDef
	SessionID      string                 // Unique session identifier
	CurrentNodeID  string                 // Current node being executed
	Variables      map[string]interface{} // Session variables (transient)
	Metadata       map[string]string      // Execution metadata
	LoopCounters   map[string]int         // Loop/iteration counters
	CompletedNodes []string               // Nodes that have completed
	FailedNodes    []string               // Nodes that failed
	Status         WorkflowInstanceStatus
	StartedAt      time.Time
	UpdatedAt      time.Time
}

type WorkflowInstanceStatus string

type WorkflowResult struct {
	WorkflowID  string
	Status      WorkflowStatus
	Output      interface{}
	NodeResults map[string]*NodeResult
	Error       error
	StartTime   time.Time
	EndTime     time.Time
}

type WorkflowStatus string