ports

type AgentFinder interface {
	// FindAgentsByRole finds available agents by role.
	FindAgentsByRole(ctx context.Context, role string) ([]string, error)
}

type ConditionEvaluator interface {
	// EvaluateCondition evaluates a condition string against current context.
	EvaluateCondition(ctx context.Context, condition string, facts map[string]interface{}) (bool, error)
}

type Extractor interface {
	// Extract converts free-text input to a structured payload.
	// The returned value should be a Go struct that can be flattened to Datalog facts.
	Extract(ctx context.Context, text string) (any, error)
}

type GenePoolPort interface {
	// LoadActiveGenes fetches the relevant domain logic bounds for the current phase.
	// The frame parameter is an interface to avoid circular imports.
	LoadActiveGenes(ctx context.Context, frame any) ([]any, error)
}

type GenerativePort interface {
	// Generate produces structured output based on the assembled CognitiveFrame.
	// The frame parameter is an interface to avoid circular imports.
	Generate(ctx context.Context, frame any) (any, error)
}

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

type KnowledgeStore interface {
	// Recall retrieves the top-K most relevant facts for a query.
	// Uses graphID to scope the search to a specific knowledge tier/graph.
	Recall(ctx context.Context, query string, topK int, graphID string) ([]core.Atom, error)

	// GetFacts retrieves facts matching a specific pattern (subject/predicate/object).
	// Uses graphID to scope the search to a specific knowledge tier/graph.
	GetFacts(ctx context.Context, subject, predicate, object, graphID string) ([]core.Quad, error)

	// StreamFacts streams facts matching a pattern using zero-copy iteration.
	// Uses graphID to scope the search to a specific knowledge tier/graph.
	StreamFacts(ctx context.Context, subject, predicate, object, graphID string) func(func(core.Quad) bool)
}

type ReasoningPort interface {
	// VerifyExecutes evaluates a Datalog query and returns structural Audit results.
	VerifyWithDatalog(ctx context.Context, datalogQuery string) ([]map[string]string, error)
}

type SessionStateStore interface {
	// Create creates a new workflow instance in session memory.
	Create(ctx context.Context, instance *core.WorkflowInstance) error

	// Get retrieves a workflow instance by session key.
	Get(ctx context.Context, sessionKey string) (*core.WorkflowInstance, error)

	// Update updates an existing workflow instance.
	Update(ctx context.Context, instance *core.WorkflowInstance) error

	// Delete removes a workflow instance from session memory.
	Delete(ctx context.Context, sessionKey string) error

	// Exists checks if a workflow instance exists.
	Exists(ctx context.Context, sessionKey string) bool

	// List returns all workflow instances for a session.
	List(ctx context.Context, sessionID string) ([]*core.WorkflowInstance, error)

	// ClearSession removes all instances for a session (cleanup).
	ClearSession(ctx context.Context, sessionID string) error
}

type StoragePort interface {
	// SaveTrace records the final result of a CognitiveFrame epoch.
	// The frame parameter is an interface to avoid circular imports.
	SaveTrace(ctx context.Context, frame any) error
}

type TransientFact struct {
	Subject   string
	Predicate string
	Object    string
	Graph     string
	CreatedAt string // ISO8601 timestamp
}

type TransientStore interface {
	// Put stores a fact in the session's transient memory.
	Put(ctx context.Context, sessionID, key string, fact *TransientFact) error

	// Get retrieves a fact from the session's transient memory.
	Get(ctx context.Context, sessionID, key string) (*TransientFact, error)

	// GetAll retrieves all facts for a session.
	GetAll(ctx context.Context, sessionID string) ([]*TransientFact, error)

	// Delete removes a fact from the session's transient memory.
	Delete(ctx context.Context, sessionID, key string) error

	// ClearSession removes all facts for a session.
	ClearSession(ctx context.Context, sessionID string) error

	// ToAtoms converts all session facts to core.Atom format for Brain evaluation.
	ToAtoms(ctx context.Context, sessionID string) ([]core.Atom, error)

	// ToQuads converts all session facts to core.Quad format for storage.
	ToQuads(ctx context.Context, sessionID string) ([]core.Quad, error)
}

type WorkflowLoader interface {
	// LoadWorkflow loads a workflow definition by ID.
	LoadWorkflow(ctx context.Context, workflowID string) (*core.WorkflowDef, error)
}