interfaces

type AgentEngine interface {
	// Execute executes the agent with conversation history and returns a stream of events
	// imageURLs is optional - when provided, images are passed to the LLM as multimodal content
	Execute(
		ctx context.Context,
		sessionID, messageID, query string,
		llmContext []chat.Message,
		imageURLs ...[]string,
	) (*types.AgentState, error)

	// SetMemoryPrompt supplies the long-term memory envelope for this run.
	// It must be called before Execute; an empty string is a no-op.
	SetMemoryPrompt(prompt string)

	// SetSteerSink enables mid-run message injection for this run. Nil
	// (default) disables it; when set, the engine drains user-appended
	// messages at every round boundary and persists accepted ones through
	// the sink. Must be called before Execute.
	SetSteerSink(sink types.SteerSink)

	// SetContextCheckpointSink enables persisting compaction summaries that
	// end on a stored turn, so later turns start from them. Nil (default)
	// keeps compaction local to the turn. Must be called before Execute.
	SetContextCheckpointSink(sink types.ContextCheckpointSink)
}

type AgentService interface {
	// CreateAgentEngine creates an agent engine with the given configuration and EventBus.
	// Conversation history is loaded by the caller (see service.LoadAgentHistory) and
	// passed into AgentEngine.Execute; the engine itself is stateless across turns.
	CreateAgentEngine(
		ctx context.Context,
		config *types.AgentConfig,
		chatModel chat.Chat,
		rerankModel rerank.Reranker,
		eventBus *event.EventBus,
		sessionID, assistantMessageID string,
	) (AgentEngine, error)

	// ValidateConfig validates an agent configuration
	ValidateConfig(config *types.AgentConfig) error
}

type AgentShareRepository interface {
	Create(ctx context.Context, share *types.AgentShare) error
	GetByID(ctx context.Context, id string) (*types.AgentShare, error)
	GetByAgentAndOrg(ctx context.Context, agentID string, orgID string) (*types.AgentShare, error)
	Update(ctx context.Context, share *types.AgentShare) error
	Delete(ctx context.Context, id string) error
	DeleteByAgentIDAndSourceTenant(ctx context.Context, agentID string, sourceTenantID uint64) error
	DeleteByOrganizationID(ctx context.Context, orgID string) error
	DeleteByOrganizationAndSourceTenant(ctx context.Context, orgID string, sourceTenantID uint64) error
	ListByAgent(ctx context.Context, agentID string) ([]*types.AgentShare, error)
	ListByOrganization(ctx context.Context, orgID string) ([]*types.AgentShare, error)
	ListByOrganizations(ctx context.Context, orgIDs []string) ([]*types.AgentShare, error)
	ListSharedAgentsForTenant(ctx context.Context, tenantID uint64) ([]*types.AgentShare, error)
	GetShareByAgentIDAndSourceForTenant(ctx context.Context, tenantID uint64, agentID string, sourceTenantID uint64) (*types.AgentShare, error)
	CountByOrganizations(ctx context.Context, orgIDs []string) (map[string]int64, error)
	// GetShareByAgentIDForTenant returns one share for the given agentID that the tenant can access (tenant in org), excluding source_tenant_id == excludeTenantID.
	GetShareByAgentIDForTenant(ctx context.Context, tenantID uint64, agentID string, excludeTenantID uint64) (*types.AgentShare, error)
}

type AgentShareService interface {
	ShareAgent(ctx context.Context, agentID string, orgID string, userID string, tenantID uint64, permission types.OrgMemberRole) (*types.AgentShare, error)
	RemoveShare(ctx context.Context, shareID string, userID string, tenantID uint64) error
	ListSharesByAgent(ctx context.Context, agentID string, tenantID uint64) ([]*types.AgentShare, error)
	ListSharesByOrganization(ctx context.Context, orgID string) ([]*types.AgentShare, error)
	ListSharedAgents(ctx context.Context, tenantID uint64, callerTenantRole types.TenantRole) ([]*types.SharedAgentInfo, error)
	ListSharedAgentsInOrganization(ctx context.Context, orgID string, tenantID uint64, callerTenantRole types.TenantRole) ([]*types.OrganizationSharedAgentItem, error)
	// ListSharedAgentsInOrganizations returns per-org agent list (batch, for sidebar count merge).
	ListSharedAgentsInOrganizations(ctx context.Context, orgIDs []string, tenantID uint64, callerTenantRole types.TenantRole) (map[string][]*types.OrganizationSharedAgentItem, error)
	// SetSharedAgentDisabledByMe sets whether the current tenant has "disabled" this shared agent for their conversation dropdown (per-tenant preference; will be revisited in a follow-up PR).
	SetSharedAgentDisabledByMe(ctx context.Context, tenantID uint64, agentID string, sourceTenantID uint64, disabled bool) error
	// GetSharedAgentForTenant returns the shared agent by agentID if the caller's tenant has access; used to resolve KB scope for @ mention.
	GetSharedAgentForTenant(ctx context.Context, tenantID uint64, callerTenantRole types.TenantRole, agentID string, sourceTenantID ...uint64) (*types.CustomAgent, error)
	// TenantCanAccessKBViaSomeSharedAgent returns true if the caller's tenant has at least one shared agent that can access the given KB (for opening KB detail from "通过智能体可见" list without passing agent_id).
	TenantCanAccessKBViaSomeSharedAgent(ctx context.Context, tenantID uint64, callerTenantRole types.TenantRole, kb *types.KnowledgeBase) (bool, error)
	GetShare(ctx context.Context, shareID string) (*types.AgentShare, error)
	GetShareByAgentAndOrg(ctx context.Context, agentID string, orgID string) (*types.AgentShare, error)
	// GetShareByAgentIDForTenant returns one share for the given agentID that the tenant can access, excluding source_tenant_id == excludeTenantID (e.g. caller's own tenant to get shared-from-other only).
	GetShareByAgentIDForTenant(ctx context.Context, tenantID uint64, agentID string, excludeTenantID uint64) (*types.AgentShare, error)
	// CountByOrganizations returns share counts per organization (for sidebar); excludes deleted agents
	CountByOrganizations(ctx context.Context, orgIDs []string) (map[string]int64, error)
}

type AgentStreamEvent struct {
	Type      string                 `json:"type"`      // "thought", "tool_call", "tool_result", "final_answer", "error", "references"
	Content   string                 `json:"content"`   // Incremental content
	Data      map[string]interface{} `json:"data"`      // Additional structured data
	Done      bool                   `json:"done"`      // Whether this is the last event
	Iteration int                    `json:"iteration"` // Current iteration number
}

type AttachmentDocument struct {
	Attachment types.MessageAttachment
	Document   *types.TemporaryDocument
	ParsedPath string
	Warning    string
}

type AttachmentImage struct {
	DataURI string
	// Non-nil means description was attempted; an empty value must not trigger
	// another VLM call in the engine. Native vision keeps this nil.
	Description *string
	Files       map[string]string
	Warning     string
}

type AttachmentImageRead struct {
	Number int
	Image  *AttachmentImage
	Err    error
}

type AttachmentReader interface {
	List(context.Context) ([]AttachmentDocument, error)
	Resolve(ctx context.Context, ref string, wait bool) (*AttachmentDocument, error)
	// ReadImages authorizes the document once and reads the numbered images
	// concurrently. The error covers the whole batch; per-image failures are
	// reported in the aligned results.
	ReadImages(
		ctx context.Context, documentID string, numbers []int, detail, focus string,
	) ([]AttachmentImageRead, error)
	WaitTimeout() time.Duration
}

type AuditLogQuery struct {
	AfterID      uint64
	Limit        int
	Action       types.AuditAction
	Outcome      types.AuditOutcome
	ActorUserID  string
	ScopeType    string
	ScopeID      string
	UnscopedOnly bool
}

type AuditLogRepository interface {
	Create(ctx context.Context, entry *types.AuditLog) error
	List(ctx context.Context, tenantID uint64, q *AuditLogQuery) ([]*types.AuditLog, error)
	// CountSinceForDedup is the rate-limit primitive for LogDenied —
	// returns the count of matching rows in the trailing window so the
	// service can skip writing duplicates. Filter is
	// (tenant_id, actor_user_id, action, request_path, created_at >= since).
	CountSinceForDedup(
		ctx context.Context,
		tenantID uint64,
		actorUserID string,
		action types.AuditAction,
		requestPath string,
		since time.Time,
	) (int64, error)
	// DeleteOlderThan removes audit rows whose created_at is strictly
	// before cutoff and returns the affected row count. It is the
	// retention primitive driven by the daily background sweep.
	// Implementations should delete in a single statement (no per-row
	// fetch) so the long-tail cost stays at "one DELETE per sweep".
	DeleteOlderThan(ctx context.Context, cutoff time.Time) (int64, error)
}

type AuditLogService interface {
	// Log writes a single audit entry. Callers fill TenantID + Action +
	// any per-event fields; the service fills CreatedAt if zero.
	Log(ctx context.Context, entry *types.AuditLog) error
	// LogDenied records a middleware-level reject decision. Subject to
	// 1-minute sliding-window dedup keyed by
	// (tenant_id, actor_user_id, action, request_path) so a probing
	// client cannot flood the table.
	LogDenied(
		ctx context.Context,
		c *gin.Context,
		tenantID uint64,
		actorUserID, actorRole string,
		requiredRole types.TenantRole,
	) error
	List(ctx context.Context, tenantID uint64, q *AuditLogQuery) ([]*types.AuditLog, error)
	// Purge deletes rows whose created_at is strictly older than the
	// retention horizon. retentionDays <= 0 makes the call a no-op,
	// which keeps the daily sweep cheap when retention is disabled.
	// Returns rows deleted; transient repo errors propagate.
	Purge(ctx context.Context, retentionDays int) (int64, error)
}

type AuthTokenRepository interface {
	// CreateToken creates an auth token
	CreateToken(ctx context.Context, token *types.AuthToken) error
	// GetTokenByValue gets a token by its value
	GetTokenByValue(ctx context.Context, tokenValue string) (*types.AuthToken, error)
	// GetTokenByID gets a token by its primary key
	GetTokenByID(ctx context.Context, id string) (*types.AuthToken, error)
	// GetTokensByUserID gets all tokens for a user
	GetTokensByUserID(ctx context.Context, userID string) ([]*types.AuthToken, error)
	// UpdateToken updates a token
	UpdateToken(ctx context.Context, token *types.AuthToken) error
	// DeleteToken deletes a token
	DeleteToken(ctx context.Context, id string) error
	// DeleteExpiredTokens deletes all expired tokens
	DeleteExpiredTokens(ctx context.Context) error
	// RevokeTokensByUserID revokes all tokens for a user
	RevokeTokensByUserID(ctx context.Context, userID string) error
}

type ChunkImageInfo struct {
	KnowledgeID string `gorm:"column:knowledge_id"`
	ImageInfo   string `gorm:"column:image_info"`
}

type ChunkRepository interface {
	// ListAllChunksByKnowledgeID includes every type and storage status for
	// scoped lifecycle operations; UI pagination hides unindexed chunks.
	ListAllChunksByKnowledgeID(ctx context.Context, tenantID uint64, knowledgeID string) ([]*types.Chunk, error)

	// CreateChunks creates chunks
	CreateChunks(ctx context.Context, chunks []*types.Chunk) error
	// GetChunkByID gets a chunk by id
	GetChunkByID(ctx context.Context, tenantID uint64, id string) (*types.Chunk, error)
	// GetChunkByIDOnly gets a chunk by id without tenant filter (for permission resolution)
	GetChunkByIDOnly(ctx context.Context, id string) (*types.Chunk, error)
	// GetChunkBySeqID gets a chunk by seq_id
	GetChunkBySeqID(ctx context.Context, tenantID uint64, seqID int64) (*types.Chunk, error)
	// ListChunksByID lists chunks by ids
	ListChunksByID(ctx context.Context, tenantID uint64, ids []string) ([]*types.Chunk, error)
	// ListChunksByIDOnly lists chunks by ids without tenant filter (for shared KB resolution).
	ListChunksByIDOnly(ctx context.Context, ids []string) ([]*types.Chunk, error)
	// ListChunksBySeqID lists chunks by seq_ids
	ListChunksBySeqID(ctx context.Context, tenantID uint64, seqIDs []int64) ([]*types.Chunk, error)
	// ListChunksByKnowledgeID lists the knowledge's text chunks. Despite the name
	// it filters to chunk_type = 'text'; reach for ListChunksByKnowledgeIDAndTypes
	// when summary, parent_text or image chunks are needed too.
	ListChunksByKnowledgeID(ctx context.Context, tenantID uint64, knowledgeID string) ([]*types.Chunk, error)
	// ListChunksByKnowledgeIDAndTypes lists the knowledge's chunks restricted to
	// the given chunk types, ordered by chunk_index.
	ListChunksByKnowledgeIDAndTypes(
		ctx context.Context, tenantID uint64, knowledgeID string, chunkTypes []types.ChunkType,
	) ([]*types.Chunk, error)
	// ListPagedChunksByKnowledgeID lists paged chunks by knowledge id.
	// When tagIDs is non-empty, results are filtered by tag_id (OR semantics).
	// knowledgeType: "faq" or "manual" - determines sort order and search behavior
	//   - FAQ: sorts by updated_at, searchField can be "standard_question", "similar_questions", "answers", or "" for all
	//   - Document (manual): sorts by chunk_index, keyword searches content only
	// sortOrder: "asc" for ascending, default is descending
	// searchField: specifies which field to search in (only applicable for FAQ type)
	// isEnabled: when non-nil, filters chunks by their enabled state. Agent/model
	// consumers must pass true so disabled content never enters model context.
	ListPagedChunksByKnowledgeID(
		ctx context.Context,
		tenantID uint64,
		knowledgeID string,
		page *types.Pagination,
		chunkType []types.ChunkType,
		tagIDs []string,
		keyword string,
		searchField string,
		sortOrder string,
		knowledgeType string,
		isEnabled *bool,
	) ([]*types.Chunk, int64, error)
	ListChunkByParentID(ctx context.Context, tenantID uint64, parentID string) ([]*types.Chunk, error)
	// ListChunkNeighbors returns up to `before` enabled chunks immediately
	// preceding chunkIndex and up to `after` immediately following it, in
	// document order, restricted to chunkTypes. It walks chunk_index rather
	// than list positions, so gaps left by other chunk types (parents,
	// summaries, images) do not shift the neighbourhood.
	ListChunkNeighbors(
		ctx context.Context,
		tenantID uint64,
		knowledgeID string,
		chunkIndex int,
		before int,
		after int,
		chunkTypes []types.ChunkType,
	) ([]*types.Chunk, error)
	// ListChunksByParentIDs lists chunks whose parent_chunk_id is in the given list
	ListChunksByParentIDs(ctx context.Context, tenantID uint64, parentIDs []string) ([]*types.Chunk, error)
	// ListChunksByParentIDsOnly lists chunks by parent IDs without tenant filter
	// (for shared KB resolution).
	ListChunksByParentIDsOnly(ctx context.Context, parentIDs []string) ([]*types.Chunk, error)
	// UpdateChunk updates a chunk
	UpdateChunk(ctx context.Context, chunk *types.Chunk) error
	// CreateChunkRevision stores an immutable snapshot of a superseded revision.
	CreateChunkRevision(ctx context.Context, revision *types.ChunkRevision) error
	// SaveChunkRevision atomically snapshots the old row and applies the new
	// row only when its revision still matches expectedRevision.
	SaveChunkRevision(ctx context.Context, chunk *types.Chunk, revision *types.ChunkRevision, expectedRevision int) error
	// ListChunkRevisions returns snapshots ordered newest first.
	ListChunkRevisions(ctx context.Context, tenantID uint64, chunkID string) ([]*types.ChunkRevision, error)
	// GetChunkRevision returns one historical snapshot.
	GetChunkRevision(ctx context.Context, tenantID uint64, chunkID string, revision int) (*types.ChunkRevision, error)
	// UpdateChunks updates chunks in batch
	UpdateChunks(ctx context.Context, chunks []*types.Chunk) error
	// SaveChunks persists full chunk objects in a single transaction using GORM Save (UPDATE).
	SaveChunks(ctx context.Context, chunks []*types.Chunk) error
	// UpdateChunkFieldsByIDs sets the same column values (e.g. {"status": 2})
	// on every listed chunk of the tenant with one UPDATE per batch of IDs.
	// updated_at is set automatically.
	UpdateChunkFieldsByIDs(ctx context.Context, tenantID uint64, ids []string, fields map[string]interface{}) error
	// DeleteChunk deletes a chunk
	DeleteChunk(ctx context.Context, tenantID uint64, id string) error
	// DeleteChunks deletes chunks by IDs in batch
	DeleteChunks(ctx context.Context, tenantID uint64, ids []string) error
	// DeleteChunksByKnowledgeID deletes chunks by knowledge id
	DeleteChunksByKnowledgeID(ctx context.Context, tenantID uint64, knowledgeID string) error
	// DeleteByKnowledgeList deletes all chunks for a knowledge list
	DeleteByKnowledgeList(ctx context.Context, tenantID uint64, knowledgeIDs []string) error
	// ListImageInfoByKnowledgeIDs returns non-empty (knowledge_id, image_info) pairs for image cleanup.
	ListImageInfoByKnowledgeIDs(ctx context.Context, tenantID uint64, knowledgeIDs []string) ([]ChunkImageInfo, error)
	// ListImageAssets returns one page of a KB's de-duplicated image assets
	// (one per image_info entry, keyed by URL) with the query's filters and
	// sort applied in the database, plus the filtered total.
	ListImageAssets(
		ctx context.Context, tenantID uint64, kbID string, q *types.ImageAssetQuery,
	) ([]types.ImageAssetRow, int64, error)
	// MoveChunksByKnowledgeID updates knowledge_base_id for all chunks of a knowledge item
	MoveChunksByKnowledgeID(ctx context.Context, tenantID uint64, knowledgeID string, targetKBID string) error
	// DeleteChunksByTagID deletes all chunks with the specified tag ID
	// Returns the IDs of deleted chunks for index cleanup
	DeleteChunksByTagID(ctx context.Context, tenantID uint64, kbID string, tagID string, excludeIDs []string) ([]string, error)
	// CountChunksByKnowledgeBaseID counts the number of chunks in a knowledge base.
	CountChunksByKnowledgeBaseID(ctx context.Context, tenantID uint64, kbID string) (int64, error)
	// DeleteUnindexedChunks deletes unindexed chunks by knowledge id and chunk index range
	DeleteUnindexedChunks(ctx context.Context, tenantID uint64, knowledgeID string) ([]*types.Chunk, error)
	// ListAllFAQChunksByKnowledgeID lists all FAQ chunks for a knowledge ID
	// only ID and ContentHash fields for efficiency
	ListAllFAQChunksByKnowledgeID(ctx context.Context, tenantID uint64, knowledgeID string) ([]*types.Chunk, error)
	// ListAllFAQChunksWithMetadataByKnowledgeBaseID lists all FAQ chunks for a knowledge base ID
	// returns ID and Metadata fields for duplicate question checking
	ListAllFAQChunksWithMetadataByKnowledgeBaseID(ctx context.Context, tenantID uint64, kbID string) ([]*types.Chunk, error)
	// FindFAQChunkWithDuplicateQuestion finds a single FAQ chunk whose standard_question or
	// similar_questions overlap with the given question list. Returns nil if no duplicate found.
	FindFAQChunkWithDuplicateQuestion(ctx context.Context, tenantID uint64, kbID string, excludeChunkID string, questions []string) (*types.Chunk, error)
	// ListAllFAQChunksForExport lists all FAQ chunks for export with full metadata, tag_id, is_enabled, and flags
	ListAllFAQChunksForExport(ctx context.Context, tenantID uint64, knowledgeID string) ([]*types.Chunk, error)
	// UpdateChunkFlagsBatch updates flags for multiple chunks in batch using a single SQL statement.
	// setFlags: map of chunk ID to flags to set (OR operation)
	// clearFlags: map of chunk ID to flags to clear (AND NOT operation)
	UpdateChunkFlagsBatch(ctx context.Context, tenantID uint64, kbID string, setFlags map[string]types.ChunkFlags, clearFlags map[string]types.ChunkFlags) error
	// UpdateChunkFieldsByTagID updates fields for all chunks with the specified tag ID.
	// Supports updating is_enabled, flags, and tag_id fields.
	// newTagID: if not nil, updates tag_id to this value (empty string means uncategorized)
	UpdateChunkFieldsByTagID(ctx context.Context, tenantID uint64, kbID string, tagID string, isEnabled *bool, setFlags types.ChunkFlags, clearFlags types.ChunkFlags, newTagID *string, excludeIDs []string) ([]string, error)
	// FAQChunkDiff compares FAQ chunks between two knowledge bases and returns the differences.
	FAQChunkDiff(ctx context.Context, srcTenantID uint64, srcKBID string, dstTenantID uint64, dstKBID string) (*types.FAQChunkDiffResult, error)
	// ListFAQChunkStatusByIDs loads status fields for FAQ clone sync.
	ListFAQChunkStatusByIDs(ctx context.Context, tenantID uint64, ids []string) (map[string]*types.FAQChunkStatus, error)

	// ListRecommendedFAQChunks lists FAQ chunks with the recommended flag set.
	// Filter by explicitly selected kbIDs, knowledgeIDs, and/or FAQ tagIDs.
	// Returns up to `limit` chunks sorted by updated_at descending.
	ListRecommendedFAQChunks(ctx context.Context, tenantID uint64, kbIDs []string, knowledgeIDs []string, tagIDs []string, limit int) ([]*types.Chunk, error)

	// ListRecentDocumentChunksWithQuestions lists recent document chunks that have generated questions.
	// Filter by kbIDs and/or knowledgeIDs. At least one of them must be non-empty.
	// Returns up to `limit` chunks sorted by updated_at descending.
	ListRecentDocumentChunksWithQuestions(ctx context.Context, tenantID uint64, kbIDs []string, knowledgeIDs []string, limit int) ([]*types.Chunk, error)
}

type ChunkService interface {
	// CreateChunks creates chunks
	CreateChunks(ctx context.Context, chunks []*types.Chunk) error
	// GetChunkByID gets a chunk by id (uses tenant from context)
	GetChunkByID(ctx context.Context, id string) (*types.Chunk, error)
	// GetChunkByIDOnly gets a chunk by id without tenant filter (for permission resolution)
	GetChunkByIDOnly(ctx context.Context, id string) (*types.Chunk, error)
	// ListChunksByKnowledgeID lists chunks by knowledge id
	ListChunksByKnowledgeID(ctx context.Context, knowledgeID string) ([]*types.Chunk, error)
	// ListPagedChunksByKnowledgeID lists paged chunks by knowledge id
	ListPagedChunksByKnowledgeID(
		ctx context.Context,
		knowledgeID string,
		page *types.Pagination,
		chunkType []types.ChunkType,
	) (*types.PageResult, error)
	// ListImagesByKnowledgeBaseID lists the image assets of a KB with keyword
	// search, schema-driven attribute filters, sorting and pagination.
	ListImagesByKnowledgeBaseID(
		ctx context.Context,
		kbID string,
		page *types.Pagination,
		filter *types.ImageListFilter,
	) (*types.PageResult, error)
	// UpdateChunk updates a chunk
	UpdateChunk(ctx context.Context, chunk *types.Chunk) error
	// UpdateChunks updates chunks in batch
	UpdateChunks(ctx context.Context, chunks []*types.Chunk) error
	// DeleteChunk deletes a chunk
	DeleteChunk(ctx context.Context, id string) error
	// DeleteChunks deletes chunks by IDs in batch
	DeleteChunks(ctx context.Context, ids []string) error
	// DeleteChunksByKnowledgeID deletes chunks by knowledge id
	DeleteChunksByKnowledgeID(ctx context.Context, knowledgeID string) error
	// DeleteByKnowledgeList deletes all chunks for a knowledge list
	DeleteByKnowledgeList(ctx context.Context, ids []string) error
	// ListChunkByParentID lists chunks by parent id
	ListChunkByParentID(ctx context.Context, tenantID uint64, parentID string) ([]*types.Chunk, error)
	// GetRepository gets the chunk repository
	GetRepository() ChunkRepository
	// DeleteGeneratedQuestion deletes a single generated question from a chunk by question ID
	// This updates the chunk metadata and removes the corresponding vector index
	DeleteGeneratedQuestion(ctx context.Context, chunkID string, questionID string) error
	// UpdateDocumentChunk applies a revision-checked edit and synchronizes retrieval indices.
	UpdateDocumentChunk(ctx context.Context, chunkID string, content *string, isEnabled *bool, expectedRevision *int) (*types.Chunk, error)
	// ListChunkRevisions lists immutable snapshots for a chunk.
	ListChunkRevisions(ctx context.Context, chunkID string) ([]*types.ChunkRevision, error)
	// RevertDocumentChunk restores a historical revision as a new current revision.
	RevertDocumentChunk(ctx context.Context, chunkID string, revision int, expectedRevision *int) (*types.Chunk, error)
	// UpsertGeneratedQuestion creates or updates a generated retrieval question.
	UpsertGeneratedQuestion(ctx context.Context, chunkID string, questionID string, question string) (*types.GeneratedQuestion, error)
}

type CustomAgentRepository interface {
	// CreateAgent creates an agent record
	// Parameters:
	//   - ctx: Context information
	//   - agent: Agent object
	// Returns:
	//   - Possible errors such as database connection failure, unique constraint conflicts, etc.
	CreateAgent(ctx context.Context, agent *types.CustomAgent) error

	// GetAgentByID queries an agent by ID and tenant
	// Parameters:
	//   - ctx: Context information
	//   - id: Agent ID
	//   - tenantID: Tenant ID for isolation
	// Returns:
	//   - Agent object, if found
	//   - Possible errors such as record not existing, database errors, etc.
	GetAgentByID(ctx context.Context, id string, tenantID uint64) (*types.CustomAgent, error)

	// ListAgentsByTenantID lists all agents for a specific tenant
	// Parameters:
	//   - ctx: Context information
	//   - tenantID: Tenant ID
	// Returns:
	//   - List of agent objects
	//   - Possible errors such as database errors, etc.
	ListAgentsByTenantID(ctx context.Context, tenantID uint64) ([]*types.CustomAgent, error)

	// UpdateAgent updates an agent record
	// Parameters:
	//   - ctx: Context information
	//   - agent: Agent object containing update information
	// Returns:
	//   - Possible errors such as record not existing, database errors, etc.
	UpdateAgent(ctx context.Context, agent *types.CustomAgent) error

	// DeleteAgent deletes an agent record
	// Parameters:
	//   - ctx: Context information
	//   - id: Agent ID
	//   - tenantID: Tenant ID for isolation (required for composite primary key)
	// Returns:
	//   - Possible errors such as record not existing, database errors, etc.
	DeleteAgent(ctx context.Context, id string, tenantID uint64) error

	// CountByModelID counts active agents in the tenant whose config references
	// the given model ID (chat, rerank, VLM, ASR, query-understand, etc.).
	CountByModelID(ctx context.Context, tenantID uint64, modelID string) (int64, error)
	// ListModelUsages returns the minimal active agent projections that
	// reference the model, with every matching binding merged per object.
	// Implementations must cap the result at types.ModelUsageListLimit;
	// callers that need the untruncated size should use CountByModelID.
	ListModelUsages(ctx context.Context, tenantID uint64, modelID string) ([]types.ModelUsageResource, error)

	// CountBySandboxConfigID counts agents pointing at a sandbox config.
	//
	// Used only to warn the admin which agents reference a config; never use it
	// to refuse operations. Agent references are permanent state, so blocking on
	// them would make credential rotation impossible.
	CountBySandboxConfigID(ctx context.Context, tenantID uint64, configID string) (int64, error)

	// ListNamesBySandboxConfigID returns agent names pointing at a sandbox config.
	//
	// Used only to warn the admin which agents reference a config; never use it
	// to refuse operations. Agent references are permanent state, so blocking on
	// them would make credential rotation impossible.
	ListNamesBySandboxConfigID(ctx context.Context, tenantID uint64, configID string) ([]string, error)
}

type CustomAgentService interface {
	// CreateAgent creates a new custom agent
	// Parameters:
	//   - ctx: Context information, carrying request tracking, user identity, etc.
	//   - agent: Agent object containing basic information and configuration
	// Returns:
	//   - Created agent object (including automatically generated ID)
	//   - Possible errors such as insufficient permissions, validation errors, etc.
	CreateAgent(ctx context.Context, agent *types.CustomAgent) (*types.CustomAgent, error)

	// GetAgentByID retrieves agent information by ID (uses tenant from context)
	// Parameters:
	//   - ctx: Context information
	//   - id: Unique identifier of the agent
	// Returns:
	//   - Agent object, if found (including built-in agents)
	//   - Possible errors such as not existing, insufficient permissions, etc.
	GetAgentByID(ctx context.Context, id string) (*types.CustomAgent, error)

	// GetAgentByIDAndTenant retrieves agent by ID and tenant (for shared agents; skips built-in resolution)
	GetAgentByIDAndTenant(ctx context.Context, id string, tenantID uint64) (*types.CustomAgent, error)

	// ListAgents lists all agents under the current tenant (including built-in agents)
	// Parameters:
	//   - ctx: Context information, containing tenant information
	// Returns:
	//   - List of agent objects (built-in agents first, then custom agents sorted by creation time)
	//   - Possible errors such as insufficient permissions, etc.
	ListAgents(ctx context.Context) ([]*types.CustomAgent, error)

	// UpdateAgent updates agent information
	// Parameters:
	//   - ctx: Context information
	//   - agent: Agent object containing update information
	// Returns:
	//   - Updated agent object
	//   - Possible errors such as not existing, insufficient permissions, cannot modify built-in, etc.
	// avatar carries field presence the agent struct cannot express: nil means
	// the caller did not send an avatar and the stored one must survive, while
	// a pointer to "" is an explicit clear.
	UpdateAgent(ctx context.Context, agent *types.CustomAgent, avatar *string) (*types.CustomAgent, error)

	// DeleteAgent deletes an agent
	// Parameters:
	//   - ctx: Context information
	//   - id: Unique identifier of the agent
	// Returns:
	//   - Possible errors such as not existing, insufficient permissions, cannot delete built-in, etc.
	DeleteAgent(ctx context.Context, id string) error

	// CopyAgent creates a copy of an existing agent
	// Parameters:
	//   - ctx: Context information
	//   - id: Unique identifier of the agent to copy
	// Returns:
	//   - The newly created agent copy
	//   - Possible errors such as not existing, insufficient permissions, etc.
	CopyAgent(ctx context.Context, id string) (*types.CustomAgent, error)

	// GetSuggestedQuestions returns suggested questions for the agent based on its
	// associated knowledge bases. When kbIDs or knowledgeIDs are provided, they override
	// the agent's default knowledge base selection.
	// Parameters:
	//   - ctx: Context information
	//   - agentID: Agent ID
	//   - kbIDs: Optional knowledge base IDs to override agent config
	//   - knowledgeIDs: Optional knowledge item IDs to further filter
	//   - tagScopes: Optional KB-scoped knowledge tags (OR semantics within each KB)
	//   - limit: Maximum number of questions to return
	// Returns:
	//   - List of suggested questions
	//   - Possible errors
	GetSuggestedQuestions(ctx context.Context, agentID string, kbIDs []string, knowledgeIDs []string, tagScopes []types.TagScope, limit int) ([]types.SuggestedQuestion, error)

	// GetKnowledgeSuggestedQuestions returns only knowledge-derived candidates.
	// It is independent of whether starter suggestions are enabled and is used
	// as a source/fallback for contextual follow-up generation.
	GetKnowledgeSuggestedQuestions(ctx context.Context, agentID string, kbIDs []string, knowledgeIDs []string, tagScopes []types.TagScope, limit int) ([]types.SuggestedQuestion, error)
}

type DataSourceRepository interface {
	// Create inserts a new data source record
	Create(ctx context.Context, ds *types.DataSource) error

	// FindByID retrieves a data source by ID
	FindByID(ctx context.Context, id string) (*types.DataSource, error)

	// FindByKnowledgeBase lists all data sources for a knowledge base
	FindByKnowledgeBase(ctx context.Context, kbID string) ([]*types.DataSource, error)

	// Update updates an existing data source
	Update(ctx context.Context, ds *types.DataSource) error

	// UpdateSyncState updates only fields produced by a sync run.
	UpdateSyncState(ctx context.Context, ds *types.DataSource) error

	// Delete performs a soft delete
	Delete(ctx context.Context, id string) error

	// FindActive retrieves all active data sources (used for scheduling)
	FindActive(ctx context.Context) ([]*types.DataSource, error)
}

type DataSourceService interface {
	// CreateDataSource creates a new data source configuration
	CreateDataSource(ctx context.Context, ds *types.DataSource) (*types.DataSource, error)

	// GetDataSource retrieves a data source by ID
	GetDataSource(ctx context.Context, id string) (*types.DataSource, error)

	// ListDataSources lists all data sources for a knowledge base
	ListDataSources(ctx context.Context, kbID string) ([]*types.DataSource, error)

	// UpdateDataSource updates an existing data source
	UpdateDataSource(ctx context.Context, ds *types.DataSource) (*types.DataSource, error)

	// DeleteDataSource deletes a data source (soft delete)
	DeleteDataSource(ctx context.Context, id string) error

	// UpdateDataSourceCredentials replaces the connector credential map.
	// DataSource credentials are per-connector atomic — there is no
	// individual-field PUT, the whole map gets replaced. Returns the updated
	// data source so the caller can re-fetch the redacted shape.
	UpdateDataSourceCredentials(
		ctx context.Context, id string, credentials map[string]interface{},
	) (*types.DataSource, error)

	// ClearDataSourceCredentials wipes the connector credential map.
	// Idempotent on already-empty credentials.
	ClearDataSourceCredentials(ctx context.Context, id string) error

	// ValidateConnection tests the connection to an external data source
	ValidateConnection(ctx context.Context, dsID string) error

	// ValidateCredentials tests connectivity using raw credentials without persisting anything.
	// This is used by the frontend "Test Connection" button before creating a data source.
	ValidateCredentials(ctx context.Context, connectorType string, credentials map[string]interface{}) error

	// ListAvailableResources lists resources available for sync in the external system.
	// parentID enables lazy loading: "" lists the top level, a resource ExternalID lists its children.
	ListAvailableResources(ctx context.Context, dsID string, parentID string) ([]types.Resource, error)

	// ResolveResourceAncestors returns the deduplicated ExternalIDs of every
	// ancestor that must be expanded to reveal the given (possibly deeply nested)
	// resources in a lazily-loaded picker. Used to restore an existing selection
	// when editing a data source.
	ResolveResourceAncestors(ctx context.Context, dsID string, resourceIDs []string) ([]string, error)

	// ManualSync triggers an immediate sync for a data source
	ManualSync(ctx context.Context, dsID string) (*types.SyncLog, error)

	// PauseDataSource pauses a data source's scheduled syncs
	PauseDataSource(ctx context.Context, id string) error

	// ResumeDataSource resumes a paused data source
	ResumeDataSource(ctx context.Context, id string) error

	// GetSyncLogs retrieves sync history for a data source
	GetSyncLogs(ctx context.Context, dsID string, limit int, offset int) ([]*types.SyncLog, error)

	// GetSyncLog retrieves a specific sync log entry
	GetSyncLog(ctx context.Context, syncLogID string) (*types.SyncLog, error)

	// ProcessSync handles the actual sync operation (called by asynq task)
	ProcessSync(ctx context.Context, task *asynq.Task) error
}

type DatasetService interface {
	// GetDatasetByID retrieves QA pairs from dataset by ID
	GetDatasetByID(ctx context.Context, datasetID string) ([]*types.QAPair, error)
}

type DocReader interface {
	Read(ctx context.Context, req *types.ReadRequest) (*types.ReadResult, error)
}

type DocumentReader interface {
	DocReader
	Reconnect(addr string) error
	IsConnected() bool
	// ListEngines queries the remote docreader for its registered parser engines.
	// Returns engines the remote service supports, allowing auto-discovery of
	// newly added engines without Go code changes.
	ListEngines(ctx context.Context, overrides map[string]string) ([]types.ParserEngineInfo, error)
}

type EmbedChannelRepository interface {
	Create(ctx context.Context, ch *types.EmbedChannel) error
	GetByID(ctx context.Context, id string) (*types.EmbedChannel, error)
	GetByPublishToken(ctx context.Context, token string) (*types.EmbedChannel, error)
	ListByAgent(ctx context.Context, tenantID uint64, agentID string) ([]*types.EmbedChannel, error)
	ListByTenant(ctx context.Context, tenantID uint64) ([]*types.EmbedChannel, error)
	Update(ctx context.Context, ch *types.EmbedChannel) error
	Delete(ctx context.Context, tenantID uint64, id string) error
}

type EmbedChannelService interface {
	Create(ctx context.Context, tenantID uint64, agentID string, req *types.EmbedChannel) (*types.EmbedChannel, string, error)
	ListByAgent(ctx context.Context, tenantID uint64, agentID string) ([]*types.EmbedChannel, error)
	ListByTenant(ctx context.Context, tenantID uint64) ([]*types.EmbedChannel, error)
	Update(ctx context.Context, tenantID uint64, id string, req *types.EmbedChannel, enabled *bool, showSuggested *bool, allowWebSearch *bool, allowFileUpload *bool, defaultLocale *string, webhookURL *string, webhookSecret *string) (*types.EmbedChannel, error)
	Delete(ctx context.Context, tenantID uint64, id string) error
	RotateToken(ctx context.Context, tenantID uint64, id string) (*types.EmbedChannel, string, error)
	LookupForEmbed(ctx context.Context, channelID, token string) (*types.EmbedChannel, error)
	LookupEnabledChannel(ctx context.Context, channelID string) (*types.EmbedChannel, error)
	IssueSessionToken(ctx context.Context, channelID string) (sessionToken string, expiresIn int, err error)
	IssuePreviewSession(ctx context.Context, tenantID uint64, channelID string) (sessionToken string, expiresIn int, err error)
	ResolveSessionToken(ctx context.Context, token string) (channelID string, err error)
	PublicConfig(ctx context.Context, ch *types.EmbedChannel) types.EmbedChannelPublicConfig
	SuggestedQuestions(ctx context.Context, ch *types.EmbedChannel, limit int) ([]types.SuggestedQuestion, error)
	EmbedChunk(ctx context.Context, ch *types.EmbedChannel, chunkID string) (*types.Chunk, error)
	EmbedDisplayTitle(ctx context.Context, ch *types.EmbedChannel) string
	GetOwnedChannel(ctx context.Context, tenantID uint64, id string) (*types.EmbedChannel, error)
}

type EngineFactory func(ctx context.Context, store types.VectorStore) (RetrieveEngineService, error)

type EvalHook interface {
	// Handle processes evaluation state change
	Handle(ctx context.Context, state types.EvalState, index int, data interface{}) error
}

type EvaluationService interface {
	// Evaluation starts a new evaluation task
	Evaluation(ctx context.Context, datasetID string, knowledgeBaseID string,
		chatModelID string, rerankModelID string,
	) (*types.EvaluationDetail, error)
	// EvaluationResult retrieves evaluation result by task ID
	EvaluationResult(ctx context.Context, taskID string) (*types.EvaluationDetail, error)
}

type FileService interface {
	// CheckConnectivity verifies that the storage backend is reachable and
	// properly configured (e.g. bucket exists, credentials valid).
	CheckConnectivity(ctx context.Context) error
	// SaveFile saves a file.
	SaveFile(ctx context.Context, file *multipart.FileHeader, tenantID uint64, knowledgeID string) (string, error)
	// SaveBytes saves bytes data to a file and returns the file path.
	// If temp is true, the file will be saved to a temporary storage that may auto-expire.
	SaveBytes(ctx context.Context, data []byte, tenantID uint64, fileName string, temp bool) (string, error)
	// GetFile retrieves a file.
	GetFile(ctx context.Context, filePath string) (io.ReadCloser, error)
	// GetFileURL returns a download URL for the file (if supported by the storage backend).
	GetFileURL(ctx context.Context, filePath string) (string, error)
	// DeleteFile deletes a file.
	DeleteFile(ctx context.Context, filePath string) error
	// CopyFile copies an existing stored object to a NEW object owned by
	// (tenantID, knowledgeID), returning the new provider:// path. The copy is
	// independent: deleting the source never affects it. Returns ErrCrossBackendCopy
	// when srcPath belongs to a different storage provider than this service.
	CopyFile(ctx context.Context, srcPath string, tenantID uint64, knowledgeID string) (string, error)
}

type FilteredWebSearchProvider interface {
	SearchWithFilters(ctx context.Context, query string, maxResults int, includeDate bool,
		filters types.WebSearchFilters) ([]*types.WebSearchResult, error)
}

type KBResourceLookup interface {
	IsReferencedByKnowledgeBase(ctx context.Context, tenantID uint64, kbID, reference string) (bool, error)
}

type KBShareRepository interface {
	// CRUD
	Create(ctx context.Context, share *types.KnowledgeBaseShare) error
	GetByID(ctx context.Context, id string) (*types.KnowledgeBaseShare, error)
	GetByKBAndOrg(ctx context.Context, kbID string, orgID string) (*types.KnowledgeBaseShare, error)
	Update(ctx context.Context, share *types.KnowledgeBaseShare) error
	Delete(ctx context.Context, id string) error
	// DeleteByKnowledgeBaseID soft-deletes all shares for a knowledge base (e.g. when KB is deleted)
	DeleteByKnowledgeBaseID(ctx context.Context, kbID string) error
	// DeleteByOrganizationID soft-deletes all shares for an organization (e.g. when the org is deleted)
	DeleteByOrganizationID(ctx context.Context, orgID string) error
	// DeleteByOrganizationAndSourceTenant soft-deletes the shares a tenant made
	// into an organization (e.g. when the tenant leaves or is removed)
	DeleteByOrganizationAndSourceTenant(ctx context.Context, orgID string, sourceTenantID uint64) error

	// List
	ListByKnowledgeBase(ctx context.Context, kbID string) ([]*types.KnowledgeBaseShare, error)
	ListByOrganization(ctx context.Context, orgID string) ([]*types.KnowledgeBaseShare, error)
	ListByOrganizations(ctx context.Context, orgIDs []string) ([]*types.KnowledgeBaseShare, error)
	CountByOrganizations(ctx context.Context, orgIDs []string) (map[string]int64, error)

	// Query for tenant's accessible shared knowledge bases
	ListSharedKBsForTenant(ctx context.Context, tenantID uint64) ([]*types.KnowledgeBaseShare, error)

	// Count shares
	CountSharesByKnowledgeBaseID(ctx context.Context, kbID string) (int64, error)
	CountSharesByKnowledgeBaseIDs(ctx context.Context, kbIDs []string) (map[string]int64, error)
}

type KBShareService interface {
	// Share Management
	ShareKnowledgeBase(ctx context.Context, kbID string, orgID string, userID string, tenantID uint64, permission types.OrgMemberRole) (*types.KnowledgeBaseShare, error)
	UpdateSharePermission(ctx context.Context, shareID string, permission types.OrgMemberRole, userID string, tenantID uint64) error
	RemoveShare(ctx context.Context, shareID string, userID string, tenantID uint64) error

	// Query
	// ListSharesByKnowledgeBase lists shares for a KB; tenantID must own the KB (authz check).
	ListSharesByKnowledgeBase(ctx context.Context, kbID string, tenantID uint64) ([]*types.KnowledgeBaseShare, error)
	ListSharesByOrganization(ctx context.Context, orgID string) ([]*types.KnowledgeBaseShare, error)
	ListSharedKnowledgeBases(ctx context.Context, tenantID uint64, callerTenantRole types.TenantRole) ([]*types.SharedKnowledgeBaseInfo, error)
	ListSharedKnowledgeBasesInOrganization(ctx context.Context, orgID string, tenantID uint64, callerTenantRole types.TenantRole) ([]*types.OrganizationSharedKnowledgeBaseItem, error)
	// ListSharedKnowledgeBaseIDsByOrganizations returns per-org direct shared KB IDs (batch, for sidebar count).
	ListSharedKnowledgeBaseIDsByOrganizations(ctx context.Context, orgIDs []string, tenantID uint64) (map[string][]string, error)
	GetShare(ctx context.Context, shareID string) (*types.KnowledgeBaseShare, error)
	GetShareByKBAndOrg(ctx context.Context, kbID string, orgID string) (*types.KnowledgeBaseShare, error)

	// Permission Check (Plan 3: tenant-keyed). Returns the effective
	// OrgMemberRole the caller can use against the shared KB after the
	// 3-D cap, plus a bool indicating whether *any* share matches the
	// caller's tenant. callerTenantRole is the caller's tenant-RBAC
	// role and is used to apply the Viewer cap.
	CheckTenantKBPermission(ctx context.Context, kbID string, callerTenantID uint64, callerTenantRole types.TenantRole) (types.OrgMemberRole, bool, error)
	// HasTenantKBPermission is a thin "do I have at least N" wrapper over
	// CheckTenantKBPermission.
	HasTenantKBPermission(ctx context.Context, kbID string, callerTenantID uint64, callerTenantRole types.TenantRole, requiredRole types.OrgMemberRole) (bool, error)

	// Get source tenant for cross-tenant embedding
	GetKBSourceTenant(ctx context.Context, kbID string) (uint64, error)

	// Count shares for knowledge bases
	CountSharesByKnowledgeBaseIDs(ctx context.Context, kbIDs []string) (map[string]int64, error)
	// CountByOrganizations returns share counts per organization (for sidebar); excludes deleted KBs
	CountByOrganizations(ctx context.Context, orgIDs []string) (map[string]int64, error)
}

type KnowledgeBaseProfileService interface {
	// BuildAggregate computes the live aggregate (counts, samples, hash) for
	// the knowledge base without calling a model.
	BuildAggregate(ctx context.Context, kb *types.KnowledgeBase) (*types.KnowledgeBaseProfileAggregate, error)
	// GenerateKnowledgeBaseProfile rebuilds the generated description. With
	// force=false it returns the stored profile untouched when the aggregate
	// hash still matches. The returned profile is also written to kb.
	GenerateKnowledgeBaseProfile(
		ctx context.Context, kb *types.KnowledgeBase, force bool,
	) (*types.KnowledgeBaseProfile, error)
	// RequestKnowledgeBaseProfileRefresh enqueues an asynchronous rebuild.
	// It is a no-op when automatic generation is disabled unless force is set.
	RequestKnowledgeBaseProfileRefresh(ctx context.Context, kb *types.KnowledgeBase, force bool) error
	// Handle is the asynq entry point for types.TypeKnowledgeBaseProfile.
	Handle(ctx context.Context, task *asynq.Task) error
}

type KnowledgeBaseRepository interface {
	// CreateKnowledgeBase creates a knowledge base record
	// Parameters:
	//   - ctx: Context information
	//   - kb: Knowledge base object
	// Returns:
	//   - Possible errors such as database connection failure, unique constraint conflicts, etc.
	CreateKnowledgeBase(ctx context.Context, kb *types.KnowledgeBase) error

	// GetKnowledgeBaseByID queries a knowledge base by ID
	// Parameters:
	//   - ctx: Context information
	//   - id: Knowledge base ID
	// Returns:
	//   - Knowledge base object, if found
	//   - Possible errors such as record not existing, database errors, etc.
	GetKnowledgeBaseByID(ctx context.Context, id string) (*types.KnowledgeBase, error)

	// GetKnowledgeBaseByIDAndTenant queries a knowledge base by ID scoped to a tenant.
	// Returns ErrKnowledgeBaseNotFound if the KB does not exist or does not belong to the tenant.
	// Parameters:
	//   - ctx: Context information
	//   - id: Knowledge base ID
	//   - tenantID: Tenant ID (enforces tenant isolation)
	// Returns:
	//   - Knowledge base object, if found and owned by tenant
	//   - Possible errors such as record not existing or wrong tenant, database errors, etc.
	GetKnowledgeBaseByIDAndTenant(ctx context.Context, id string, tenantID uint64) (*types.KnowledgeBase, error)

	// GetKnowledgeBaseByIDs queries knowledge bases by multiple IDs
	// Parameters:
	//   - ctx: Context information
	//   - ids: List of knowledge base IDs
	// Returns:
	//   - List of knowledge base objects
	//   - Possible errors such as database errors, etc.
	GetKnowledgeBaseByIDs(ctx context.Context, ids []string) ([]*types.KnowledgeBase, error)

	// ListKnowledgeBases lists all knowledge bases in the system
	// Parameters:
	//   - ctx: Context information
	// Returns:
	//   - List of knowledge base objects
	//   - Possible errors such as database errors, etc.
	ListKnowledgeBases(ctx context.Context) ([]*types.KnowledgeBase, error)

	// ListKnowledgeBasesByTenantID lists all knowledge bases for a specific tenant
	// Parameters:
	//   - ctx: Context information
	//   - tenantID: Tenant ID
	// Returns:
	//   - List of knowledge base objects
	//   - Possible errors such as database errors, etc.
	ListKnowledgeBasesByTenantID(ctx context.Context, tenantID uint64) ([]*types.KnowledgeBase, error)

	// UpdateKnowledgeBase updates a knowledge base record
	// Parameters:
	//   - ctx: Context information
	//   - kb: Knowledge base object containing update information
	// Returns:
	//   - Possible errors such as record not existing, database errors, etc.
	UpdateKnowledgeBase(ctx context.Context, kb *types.KnowledgeBase) error

	// DeleteKnowledgeBase deletes a knowledge base record
	// Parameters:
	//   - ctx: Context information
	//   - id: Knowledge base ID
	// Returns:
	//   - Possible errors such as record not existing, database errors, etc.
	DeleteKnowledgeBase(ctx context.Context, id string) error

	// CountByVectorStoreID counts active KBs bound to the given vector store
	// within a tenant scope. Accepts a *gorm.DB handle so callers can share a
	// transaction (e.g., the VectorStore delete guard's row-lock context) or
	// run standalone (pass nil → uses the repository's default db).
	//
	// The soft-delete filter is applied automatically by the gorm.DeletedAt
	// scope on KnowledgeBase; implementations MUST NOT add an explicit
	// `deleted_at IS NULL` predicate (avoids divergence with the auto-scope).
	CountByVectorStoreID(ctx context.Context, db *gorm.DB, tenantID uint64, storeID string) (int64, error)

	// CountByModelID counts active KBs in the tenant that reference the given
	// model ID in any model-binding field (embedding, summary, VLM, ASR, etc.).
	CountByModelID(ctx context.Context, tenantID uint64, modelID string) (int64, error)
	// ListModelUsages returns the minimal active KB projections that reference
	// the model, with every matching binding merged per object. Implementations
	// must cap the result at types.ModelUsageListLimit; callers that need the
	// untruncated size should use CountByModelID.
	ListModelUsages(ctx context.Context, tenantID uint64, modelID string) ([]types.ModelUsageResource, error)
	// SetUserKBPin inserts or removes a row in user_kb_pins for the given
	// (tenant, user, kb) triple. Returns the resulting pinned_at (nil when
	// pinned=false) and an error. The tenant_id is captured to support
	// efficient "wipe a tenant" cleanups even though (user_id, kb_id)
	// alone would be unique in practice.
	SetUserKBPin(
		ctx context.Context, tenantID uint64, userID string, kbID string, pinned bool,
	) (pinnedAt *time.Time, err error)
	// UpdateKnowledgeBaseGeneratedProfile writes only the generated_profile
	// column so a background regeneration never races a concurrent settings
	// save on the rest of the row.
	UpdateKnowledgeBaseGeneratedProfile(ctx context.Context, id string, profile *types.KnowledgeBaseProfile) error

	// ListUserKBPinIDs returns the kb_id → pinned_at map of every KB the
	// given user has personally pinned in this tenant. Used by the list
	// path to stamp KnowledgeBase.IsPinned / PinnedAt without a per-row
	// roundtrip.
	ListUserKBPinIDs(
		ctx context.Context, tenantID uint64, userID string,
	) (map[string]time.Time, error)
}

type KnowledgeBaseService interface {
	// CreateKnowledgeBase creates a new knowledge base
	// Parameters:
	//   - ctx: Context information, carrying request tracking, user identity, etc.
	//   - kb: Knowledge base object containing basic information
	// Returns:
	//   - Created knowledge base object (including automatically generated ID)
	//   - Possible errors such as insufficient permissions, duplicate names, etc.
	CreateKnowledgeBase(ctx context.Context, kb *types.KnowledgeBase) (*types.KnowledgeBase, error)

	// GetKnowledgeBaseByID retrieves knowledge base information by ID
	// Parameters:
	//   - ctx: Context information
	//   - id: Unique identifier of the knowledge base
	// Returns:
	//   - Knowledge base object, if found
	//   - Possible errors such as not existing, insufficient permissions, etc.
	GetKnowledgeBaseByID(ctx context.Context, id string) (*types.KnowledgeBase, error)

	// GetKnowledgeBaseByIDOnly retrieves knowledge base by ID without tenant filter
	// Used for cross-tenant shared KB access where permission is checked elsewhere
	// Parameters:
	//   - ctx: Context information
	//   - id: Unique identifier of the knowledge base
	// Returns:
	//   - Knowledge base object, if found
	//   - Possible errors such as not existing, etc.
	GetKnowledgeBaseByIDOnly(ctx context.Context, id string) (*types.KnowledgeBase, error)

	// GetKnowledgeBasesByIDsOnly retrieves knowledge bases by IDs without tenant filter (batch).
	GetKnowledgeBasesByIDsOnly(ctx context.Context, ids []string) ([]*types.KnowledgeBase, error)

	// FillKnowledgeBaseCounts fills KnowledgeCount, ChunkCount, IsProcessing, ProcessingCount for the given KB (uses kb.TenantID).
	FillKnowledgeBaseCounts(ctx context.Context, kb *types.KnowledgeBase) error

	// ListKnowledgeBases lists all knowledge bases under the current tenant
	// Parameters:
	//   - ctx: Context information, containing tenant information
	// Returns:
	//   - List of knowledge base objects
	//   - Possible errors such as insufficient permissions, etc.
	ListKnowledgeBases(ctx context.Context) ([]*types.KnowledgeBase, error)
	// ListKnowledgeBasesByTenantID lists all knowledge bases for a specific tenant (e.g. for shared agent context).
	ListKnowledgeBasesByTenantID(ctx context.Context, tenantID uint64) ([]*types.KnowledgeBase, error)

	// UpdateKnowledgeBase updates knowledge base information
	// Parameters:
	//   - ctx: Context information
	//   - id: Unique identifier of the knowledge base
	//   - name: New knowledge base name
	//   - description: New knowledge base description
	//   - config: Knowledge base configuration, including chunking strategy, vectorization settings, etc.
	//   - vlmConfig: Optional multimodal (vision) config; nil means no change
	// Returns:
	//   - Updated knowledge base object
	//   - Possible errors such as not existing, insufficient permissions, etc.
	UpdateKnowledgeBase(ctx context.Context,
		id string, name string, description string, config *types.KnowledgeBaseConfig, vlmConfig *types.VLMConfig,
	) (*types.KnowledgeBase, error)

	// DeleteKnowledgeBase deletes a knowledge base
	// Parameters:
	//   - ctx: Context information
	//   - id: Unique identifier of the knowledge base
	// Returns:
	//   - Possible errors such as not existing, insufficient permissions, etc.
	DeleteKnowledgeBase(ctx context.Context, id string) error

	// TogglePinKnowledgeBase toggles the pin status of a knowledge base
	TogglePinKnowledgeBase(ctx context.Context, id string) (*types.KnowledgeBase, error)

	// HybridSearch performs hybrid search (vector + keywords) in the knowledge base
	// Parameters:
	//   - ctx: Context information
	//   - id: Unique identifier of the knowledge base
	//   - params: Search parameters, including query text, thresholds, etc.
	// Returns:
	//   - List of search results, sorted by relevance
	//   - Possible errors such as not existing, insufficient permissions, search engine errors, etc.
	HybridSearch(ctx context.Context, id string, params types.SearchParams) ([]*types.SearchResult, error)

	// HybridSearchWithRerank is HybridSearch plus the optional rerank stage
	// requested by params.Rerank, returning rerank diagnostics beside the
	// results. It serves the hybrid-search API; internal callers rerank on
	// their own and use HybridSearch.
	HybridSearchWithRerank(ctx context.Context, id string, params types.SearchParams) (*types.RetrievalResult, error)

	// GetQueryEmbedding computes the query embedding using the embedding model
	// associated with the given knowledge base. This allows callers to pre-compute
	// and reuse embeddings across multiple KBs that share the same model.
	GetQueryEmbedding(ctx context.Context, kbID string, queryText string) ([]float32, error)

	// ResolveEmbeddingModelKeys resolves embedding model IDs to their actual
	// model identity key (name + endpoint). KBs using the same underlying model
	// across different tenants will share the same key, enabling optimal grouping.
	// Returns a map from KB ID to model identity key string.
	ResolveEmbeddingModelKeys(ctx context.Context, kbs []*types.KnowledgeBase) map[string]string

	// CopyKnowledgeBase copies a knowledge base
	// Parameters:
	//   - ctx: Context information
	//   - sourceID: Source knowledge base ID
	//   - targetID: Target knowledge base ID
	// Returns:
	//   - Copied knowledge base object
	//   - Possible errors such as not existing, insufficient permissions, etc.
	CopyKnowledgeBase(ctx context.Context, src string, dst string) (*types.KnowledgeBase, *types.KnowledgeBase, error)

	// DuplicateKnowledgeBase creates a new settings-only knowledge base duplicate.
	// It does not copy knowledge entries, chunks, FAQ rows, wiki pages, indexes,
	// data sources, shares, pins, or task state. A new UUID is always generated.
	DuplicateKnowledgeBase(ctx context.Context, src string) (*types.KnowledgeBase, error)

	// GetRepository gets the knowledge base repository
	// Parameters:
	//   - ctx: Context with authentication and request information
	//
	// Returns:
	//   - interfaces.KnowledgeBaseRepository: Knowledge base repository
	GetRepository() KnowledgeBaseRepository

	// ProcessKBDelete handles async knowledge base deletion task
	// Parameters:
	//   - ctx: Context information
	//   - t: Asynq task containing KBDeletePayload
	// Returns:
	//   - Possible errors during deletion
	ProcessKBDelete(ctx context.Context, t *asynq.Task) error
	// ReadChunkImage reads the image a search result shows (the first image
	// of its image_info) from the storage of its knowledge base. The result
	// must come from a search the caller was authorized to run.
	ReadChunkImage(ctx context.Context, result *types.SearchResult) ([]byte, error)
}

type KnowledgeBaseTaskCanceller interface {
	// CancelTasksForKnowledgeBase removes pending/scheduled/retry tasks
	// associated with kbID and signals matching active workers to stop.
	// knowledgeIDs covers batch tasks whose payload references documents but
	// does not carry the parent knowledge-base ID. dataSourceIDs covers sync
	// tasks whose payload only identifies a data source.
	CancelTasksForKnowledgeBase(
		ctx context.Context,
		kbID string,
		knowledgeIDs []string,
		dataSourceIDs []string,
	) (deleted int, cancelled int, err error)
}

type KnowledgeIndexMover interface {
	MoveKnowledgeIndices(
		ctx context.Context,
		sourceKB, targetKB, knowledgeID string,
		chunkIDs []string,
		dimension int,
		knowledgeType string,
	) error
}

type KnowledgeRepository interface {
	CreateKnowledge(ctx context.Context, knowledge *types.Knowledge) error
	GetKnowledgeByID(ctx context.Context, tenantID uint64, id string) (*types.Knowledge, error)
	// GetKnowledgeByIDOnly returns knowledge by ID without tenant filter (for permission resolution).
	GetKnowledgeByIDOnly(ctx context.Context, id string) (*types.Knowledge, error)
	ListKnowledgeByKnowledgeBaseID(ctx context.Context, tenantID uint64, kbID string) ([]*types.Knowledge, error)
	// ListPagedKnowledgeByKnowledgeBaseID lists all knowledge in a knowledge base
	// with pagination. The filter struct controls optional dimensions (tag, keyword,
	// file type, parse status, source channel, updated time range); pass a zero
	// struct to disable all filters.
	ListPagedKnowledgeByKnowledgeBaseID(ctx context.Context,
		tenantID uint64, kbID string, page *types.Pagination, filter types.KnowledgeListFilter,
	) ([]*types.Knowledge, int64, error)
	UpdateKnowledge(ctx context.Context, knowledge *types.Knowledge) error
	// UpdateKnowledgeForTransfer conditionally persists a transfer checkpoint
	// and its storage delta in one transaction, without inserting missing rows.
	UpdateKnowledgeForTransfer(ctx context.Context, before, after *types.Knowledge) error

	// UpdateKnowledgeBatch updates knowledge items in batch
	UpdateKnowledgeBatch(ctx context.Context, knowledgeList []*types.Knowledge) error
	DeleteKnowledge(ctx context.Context, tenantID uint64, id string) error
	DeleteKnowledgeList(ctx context.Context, tenantID uint64, ids []string) error
	GetKnowledgeBatch(ctx context.Context, tenantID uint64, ids []string) ([]*types.Knowledge, error)
	// GetKnowledgeBatchByIDOnly returns knowledge by IDs without tenant filter
	// (for shared-KB resolution; callers check permissions on every row).
	GetKnowledgeBatchByIDOnly(ctx context.Context, ids []string) ([]*types.Knowledge, error)
	// CheckKnowledgeExists checks if knowledge already exists.
	// For file types, check by fileHash or (fileName+fileSize).
	// For URL types, check by URL.
	// Returns whether it exists, the existing knowledge object (if any), and possible error.
	CheckKnowledgeExists(
		ctx context.Context,
		tenantID uint64,
		kbID string,
		params *types.KnowledgeCheckParams,
	) (bool, *types.Knowledge, error)
	// ListKnowledgeFolderCounts aggregates the number of knowledge entries
	// stored directly in each folder_path of a knowledge base.
	ListKnowledgeFolderCounts(
		ctx context.Context,
		tenantID uint64,
		kbID string,
	) ([]*types.KnowledgeFolderCount, error)
	// UpdateKnowledgeFolderPath files the given entries under folderPath.
	UpdateKnowledgeFolderPath(
		ctx context.Context,
		tenantID uint64,
		kbID string,
		ids []string,
		folderPath string,
	) (int64, error)
	// RenameKnowledgeFolderPath rewrites folder_path for a folder and all of its
	// descendants. Renaming onto an existing path merges the folders.
	RenameKnowledgeFolderPath(
		ctx context.Context,
		tenantID uint64,
		kbID string,
		from string,
		to string,
	) (int64, error)
	// AminusB returns the IDs of knowledge in A that have no counterpart in B,
	// comparing file_hash as a multiset (so duplicate-count differences and
	// NULL/empty hashes are handled correctly, letting a clone converge).
	AminusB(ctx context.Context, Atenant uint64, A string, Btenant uint64, B string) ([]string, error)
	UpdateKnowledgeColumn(ctx context.Context, id string, column string, value interface{}) error
	// UpdateKnowledgeColumns updates multiple columns of a knowledge row in a single
	// statement so callers that flip several related fields (e.g. parse_status +
	// error_message) cannot leave the row in a half-updated state.
	UpdateKnowledgeColumns(ctx context.Context, id string, values map[string]interface{}) error
	// UpdateActiveDeletingKnowledgeColumns updates an active, non-deleted knowledge row
	// only when it is still in the transient deleting state.
	UpdateActiveDeletingKnowledgeColumns(
		ctx context.Context,
		tenantID uint64,
		kbID, id string,
		values map[string]interface{},
	) (bool, error)
	// FinalizeSubtask atomically decrements pending_subtasks_count for the
	// given knowledge and promotes parse_status from "finalizing" to
	// "completed" when the count reaches zero. Returns the post-decrement
	// count, whether this caller's UPDATE was the one that promoted the
	// row, and any error.
	FinalizeSubtask(ctx context.Context, id string) (int, bool, error)
	// SetFinalizing atomically transitions a row from "processing" to
	// "finalizing" and writes the initial pending_subtasks_count. Returns
	// whether the transition took place (false when the row's parse_status
	// was no longer "processing", e.g. user cancelled / deleted in flight).
	SetFinalizing(ctx context.Context, id string, expectedSubtasks int) (bool, error)
	// CompleteProcessingWithoutSubtasks atomically completes a still-processing
	// document that has no enrichment tasks, without overriding cancel/delete.
	CompleteProcessingWithoutSubtasks(ctx context.Context, id string) (bool, error)
	// CountKnowledgeByKnowledgeBaseID counts the number of knowledge items in a knowledge base.
	CountKnowledgeByKnowledgeBaseID(ctx context.Context, tenantID uint64, kbID string) (int64, error)
	// CountKnowledgeByStatus counts the number of knowledge items with the specified parse status.
	CountKnowledgeByStatus(ctx context.Context, tenantID uint64, kbID string, parseStatuses []string) (int64, error)
	// SearchKnowledge searches knowledge items by keyword across the tenant.
	// fileTypes: optional list of file extensions to filter by (e.g., ["csv", "xlsx"])
	SearchKnowledge(ctx context.Context, tenantID uint64, keyword string, offset, limit int, fileTypes []string) ([]*types.Knowledge, bool, error)

	// FindByMetadataKey finds a knowledge item by a key-value pair in the metadata JSON column.
	// Used by data source sync to locate existing items by external_id.
	FindByMetadataKey(ctx context.Context, tenantID uint64, kbID string, key string, value string) (*types.Knowledge, error)
	// FindByMetadataKeyPrefix finds knowledge items whose metadata[key] starts
	// with the given prefix. Used to sweep an external node's attachment sub-items.
	FindByMetadataKeyPrefix(ctx context.Context, tenantID uint64, kbID string, key string, prefix string) ([]*types.Knowledge, error)
	// FindByDataSourceExternalID finds a knowledge item owned by one data source
	// and identified by the source's external item ID.
	FindByDataSourceExternalID(
		ctx context.Context, tenantID uint64, kbID, dataSourceID, externalID string,
	) (*types.Knowledge, error)
	// HardDeleteKnowledge physically removes a row after DeleteKnowledge's soft-delete
	// cascade. Sync-internal deletions use this so rows never become tombstones.
	HardDeleteKnowledge(ctx context.Context, tenantID uint64, id string) error
	// HardDeleteKnowledgeList is the batch counterpart of HardDeleteKnowledge.
	HardDeleteKnowledgeList(ctx context.Context, tenantID uint64, ids []string) error
	// SearchKnowledgeInScopes searches knowledge items by keyword within the given (tenant_id, kb_id) scopes (own + shared).
	SearchKnowledgeInScopes(ctx context.Context, scopes []types.KnowledgeSearchScope, keyword string, offset, limit int, fileTypes []string) ([]*types.Knowledge, bool, int64, error)
	// ListIDsByTagIDs returns all knowledge IDs that have any of the specified tag IDs (OR semantics).
	ListIDsByTagIDs(ctx context.Context, tenantID uint64, kbID string, tagIDs []string) ([]string, error)
	// SetKnowledgeTags replaces all tags for a single knowledge entry (deletes old, inserts new).
	SetKnowledgeTags(ctx context.Context, knowledgeID string, tagIDs []string) error
	// AddKnowledgeTagRelations attaches tags without removing existing ones,
	// after validating that the knowledge and every tag belong to the given
	// tenant and knowledge base. Duplicate deliveries are idempotent.
	AddKnowledgeTagRelations(
		ctx context.Context,
		tenantID uint64,
		kbID, knowledgeID string,
		tagIDs []string,
	) error
	// GetKnowledgeTags returns tags for multiple knowledge IDs.
	GetKnowledgeTags(ctx context.Context, knowledgeIDs []string) (map[string][]*types.KnowledgeTag, error)
	// DeleteKnowledgeTagRelations deletes all tag relations for a knowledge entry.
	DeleteKnowledgeTagRelations(ctx context.Context, knowledgeID string) error
	// ListKnowledgeProfileRows returns the lightweight projection used to
	// aggregate a knowledge-base description: every enabled document that has
	// finished parsing (completed or finalizing), without content columns.
	ListKnowledgeProfileRows(ctx context.Context, tenantID uint64, kbID string) ([]*types.KnowledgeProfileRow, error)
}

type KnowledgeService interface {
	// CreateKnowledgeFromFile creates knowledge from a file.
	// channel identifies the ingestion channel (e.g. "web", "api", "wechat"); empty defaults to "web".
	CreateKnowledgeFromFile(
		ctx context.Context,
		kbID string,
		file *multipart.FileHeader,
		metadata map[string]string,
		enableMultimodel *bool,
		customFileName string,
		tagIDs []string,
		channel string,
		processOverrides *types.KnowledgeProcessOverrides,
	) (*types.Knowledge, error)
	// CreateKnowledgeFromURL creates knowledge from a URL.
	// When fileName or fileType is provided (or the URL path has a known file extension),
	// the URL is treated as a direct file download instead of a web page crawl.
	// channel identifies the ingestion channel; empty defaults to "web".
	CreateKnowledgeFromURL(
		ctx context.Context,
		kbID string,
		url string,
		fileName string,
		fileType string,
		enableMultimodel *bool,
		title string,
		tagIDs []string,
		channel string,
		processOverrides *types.KnowledgeProcessOverrides,
	) (*types.Knowledge, error)
	// CreateKnowledgeFromPassage creates knowledge from text passages.
	// channel identifies the ingestion channel; empty defaults to "web".
	CreateKnowledgeFromPassage(ctx context.Context, kbID string, passage []string, channel string) (*types.Knowledge, error)
	// CreateKnowledgeFromPassageSync creates knowledge from text passages and waits until chunks are indexed.
	CreateKnowledgeFromPassageSync(ctx context.Context, kbID string, passage []string, channel string) (*types.Knowledge, error)
	// CreateKnowledgeFromManual creates or saves manual Markdown knowledge content.
	// channel identifies the ingestion channel; empty defaults to "web".
	CreateKnowledgeFromManual(
		ctx context.Context,
		kbID string,
		payload *types.ManualKnowledgePayload,
		channel string,
	) (*types.Knowledge, error)
	// GetKnowledgeByID retrieves knowledge by ID (uses tenant from context).
	GetKnowledgeByID(ctx context.Context, id string) (*types.Knowledge, error)
	// GetKnowledgeByIDOnly retrieves knowledge by ID without tenant filter (for permission resolution).
	GetKnowledgeByIDOnly(ctx context.Context, id string) (*types.Knowledge, error)
	// GetOwningKBCreatorID resolves a knowledge ID to the CreatorID of its
	// owning KnowledgeBase, scoped to the caller's tenant. Used by the
	// per-KB ownership lookups in handler/rbac_lookups.go (PR 5, #1303) so
	// chunk and knowledge sub-resource routes can inherit the same
	// "creator-of-the-KB OR Admin+" gate that KB-level routes already use.
	// Returns the underlying repository sentinel errors unchanged so
	// callers can map them to middleware.ErrResourceNotFound.
	GetOwningKBCreatorID(ctx context.Context, knowledgeID string) (string, error)
	// GetKnowledgeBatch retrieves a batch of knowledge by IDs.
	GetKnowledgeBatch(ctx context.Context, tenantID uint64, ids []string) ([]*types.Knowledge, error)
	// GetKnowledgeBatchWithSharedAccess retrieves knowledge by IDs including items from shared KBs the user has access to.
	GetKnowledgeBatchWithSharedAccess(ctx context.Context, tenantID uint64, ids []string) ([]*types.Knowledge, error)
	// ListKnowledgeIDsByTagIDs returns document knowledge IDs carrying any of
	// the specified KB-local tags.
	ListKnowledgeIDsByTagIDs(ctx context.Context, tenantID uint64, kbID string, tagIDs []string) ([]string, error)
	// ListKnowledgeByKnowledgeBaseID lists all knowledge under a knowledge base.
	ListKnowledgeByKnowledgeBaseID(ctx context.Context, kbID string) ([]*types.Knowledge, error)
	// ListPagedKnowledgeByKnowledgeBaseID lists all knowledge under a knowledge base
	// with pagination. The filter struct controls optional dimensions (tag, keyword,
	// file type, parse status, source channel, updated time range); pass a zero
	// struct to disable all filters.
	ListPagedKnowledgeByKnowledgeBaseID(
		ctx context.Context,
		kbID string,
		page *types.Pagination,
		filter types.KnowledgeListFilter,
	) (*types.PageResult, error)
	// ListKnowledgeFolderTree returns the folder hierarchy derived from the
	// folder_path of every knowledge entry in a knowledge base, with per-folder
	// document counts. It powers the document sidebar tree.
	ListKnowledgeFolderTree(ctx context.Context, kbID string) (*types.KnowledgeFolderTree, error)
	// MoveKnowledgeToFolder re-files knowledge entries under the given folder
	// path (empty means the knowledge base top level). Folders are derived from
	// the stored paths, so a path that does not exist yet is created implicitly.
	MoveKnowledgeToFolder(
		ctx context.Context,
		kbID string,
		ids []string,
		folderPath string,
	) (int64, error)
	// RenameKnowledgeFolder moves a folder and everything below it to a new path.
	RenameKnowledgeFolder(ctx context.Context, kbID string, from string, to string) (int64, error)
	// DeleteKnowledge deletes knowledge by ID.
	DeleteKnowledge(ctx context.Context, id string) error
	// DeleteKnowledgeList requires an explicit write grant for every affected KB.
	// It validates the complete selection before changing any deletion state.
	DeleteKnowledgeList(ctx context.Context, ids []string) error
	// GetKnowledgeFile retrieves the file associated with the knowledge.
	GetKnowledgeFile(ctx context.Context, id string) (io.ReadCloser, string, error)
	// UpdateKnowledge updates knowledge information.
	UpdateKnowledge(ctx context.Context, knowledge *types.Knowledge) error
	// RegenerateKnowledgeSummary refreshes the document description and summary retrieval chunk.
	RegenerateKnowledgeSummary(ctx context.Context, knowledgeID string) (*types.Knowledge, error)
	// RequestKnowledgeSummaryRefresh enqueues an async summary refresh.
	RequestKnowledgeSummaryRefresh(ctx context.Context, knowledgeID string) error
	// RegenerateChunkQuestions rebuilds the auxiliary questions for one current chunk revision.
	RegenerateChunkQuestions(ctx context.Context, chunkID string) ([]types.GeneratedQuestion, error)
	// UpdateManualKnowledge updates manual Markdown knowledge content.
	UpdateManualKnowledge(
		ctx context.Context,
		knowledgeID string,
		payload *types.ManualKnowledgePayload,
	) (*types.Knowledge, error)
	// ReparseKnowledge deletes existing document content and re-parses the knowledge asynchronously.
	// When processOverrides is non-nil, it is validated and persisted to the knowledge metadata
	// before re-parsing, letting callers adjust parse config on reparse; nil keeps stored overrides.
	ReparseKnowledge(
		ctx context.Context,
		knowledgeID string,
		processOverrides *types.KnowledgeProcessOverrides,
	) (*types.Knowledge, error)
	// ReplaceKnowledgeFile replaces the source file of an existing file knowledge
	// while preserving its ID, then re-parses it. A path-qualified customFileName
	// also sets the folder; a bare filename keeps the current folder. Metadata
	// entries are merged into the stored metadata. Identical content on this
	// same path returns a DuplicateKnowledgeError without re-parsing.
	ReplaceKnowledgeFile(
		ctx context.Context,
		knowledgeID string,
		file *multipart.FileHeader,
		customFileName string,
		metadata map[string]string,
	) (*types.Knowledge, error)
	// CancelKnowledgeParse marks an in-progress parse as cancelled by the
	// user. The knowledge row and any partially written chunks/index are
	// kept; downstream queued tasks for the same knowledge are best-effort
	// dequeued and active workers are signalled to stop at their next
	// checkpoint. Idempotent — returns the existing row when the knowledge
	// is already cancelled. Returns an error when the knowledge is in a
	// terminal state (completed / failed) or being deleted.
	CancelKnowledgeParse(ctx context.Context, knowledgeID string) (*types.Knowledge, error)
	// CloneKnowledgeBase clones knowledge to another knowledge base.
	CloneKnowledgeBase(ctx context.Context, srcID, dstID string) error
	// UpdateImageInfo updates image information for a knowledge chunk.
	UpdateImageInfo(ctx context.Context, knowledgeID string, chunkID string, imageInfo string) error
	// ListFAQEntries lists FAQ entries under a FAQ knowledge base.
	// When tagUUIDs is non-empty, results are filtered by tag UUID on FAQ chunks (OR semantics).
	// searchField: specifies which field to search in ("standard_question", "similar_questions", "answers", "" for all)
	// sortOrder: "asc" for time ascending (updated_at ASC), default is time descending (updated_at DESC)
	ListFAQEntries(
		ctx context.Context,
		kbID string,
		page *types.Pagination,
		tagUUIDs []string,
		legacyTagSeqID int64,
		keyword string,
		searchField string,
		sortOrder string,
		isEnabled *bool,
	) (*types.PageResult, error)
	// UpsertFAQEntries imports or appends FAQ entries asynchronously.
	// When DryRun is true, only validates entries without actually importing.
	// Returns task ID (Knowledge ID) for tracking import progress.
	UpsertFAQEntries(ctx context.Context, kbID string, payload *types.FAQBatchUpsertPayload) (string, error)
	// CreateFAQEntry creates a single FAQ entry synchronously.
	CreateFAQEntry(ctx context.Context, kbID string, payload *types.FAQEntryPayload) (*types.FAQEntry, error)
	// GetFAQEntry retrieves a single FAQ entry by seq_id.
	GetFAQEntry(ctx context.Context, kbID string, entrySeqID int64) (*types.FAQEntry, error)
	// UpdateFAQEntry updates a single FAQ entry.
	UpdateFAQEntry(ctx context.Context, kbID string, entrySeqID int64, payload *types.FAQEntryPayload) (*types.FAQEntry, error)
	// AddSimilarQuestions adds similar questions to a FAQ entry.
	AddSimilarQuestions(ctx context.Context, kbID string, entrySeqID int64, questions []string) (*types.FAQEntry, error)
	// UpdateFAQEntryFieldsBatch updates multiple fields for FAQ entries in batch.
	// Supports updating is_enabled, is_recommended, tag_id, and other fields in a single call.
	UpdateFAQEntryFieldsBatch(ctx context.Context, kbID string, req *types.FAQEntryFieldsBatchUpdate) error
	// DeleteFAQEntries deletes FAQ entries in batch by seq_id.
	DeleteFAQEntries(ctx context.Context, kbID string, entrySeqIDs []int64) error
	// SearchFAQEntries searches FAQ entries using hybrid search.
	SearchFAQEntries(ctx context.Context, kbID string, req *types.FAQSearchRequest) ([]*types.FAQEntry, error)
	// ExportFAQEntries exports all FAQ entries for a knowledge base as CSV data.
	ExportFAQEntries(ctx context.Context, kbID string) ([]byte, error)
	// ExportFAQEntriesJSON exports all FAQ entries as a JSON array compatible with FAQEntryPayload.
	ExportFAQEntriesJSON(ctx context.Context, kbID string) ([]byte, error)
	// UpdateKnowledgeTagBatch updates tag for document knowledge items in batch.
	// authorizedKBID restricts all updates to knowledge items belonging to this KB;
	// an empty value still requires an explicit write grant for every affected KB.
	UpdateKnowledgeTagBatch(ctx context.Context, authorizedKBID string, updates map[string][]string) error
	// SetKnowledgeTags replaces all tags for a single knowledge entry.
	SetKnowledgeTags(ctx context.Context, knowledgeID string, tagIDs []string) error
	// GetKnowledgeTags returns tags for multiple knowledge IDs.
	GetKnowledgeTags(ctx context.Context, knowledgeIDs []string) (map[string][]*types.KnowledgeTag, error)
	// UpdateFAQEntryTagBatch updates tag for FAQ entries in batch.
	// Key: entry seq_id, Value: tag seq_id (nil to remove tag)
	UpdateFAQEntryTagBatch(ctx context.Context, kbID string, updates map[int64]*int64) error
	// GetRepository gets the knowledge repository
	GetRepository() KnowledgeRepository
	// ProcessManualUpdate handles Asynq manual knowledge update tasks (cleanup + re-indexing)
	ProcessManualUpdate(ctx context.Context, t *asynq.Task) error
	// ProcessDocument handles Asynq document processing tasks
	ProcessDocument(ctx context.Context, t *asynq.Task) error
	// ProcessFAQImport handles Asynq FAQ import tasks
	ProcessFAQImport(ctx context.Context, t *asynq.Task) error
	// ProcessQuestionGeneration handles Asynq question generation tasks
	ProcessQuestionGeneration(ctx context.Context, t *asynq.Task) error
	// ProcessSummaryGeneration handles Asynq summary generation tasks
	ProcessSummaryGeneration(ctx context.Context, t *asynq.Task) error
	// ProcessKBClone handles Asynq knowledge base clone tasks
	ProcessKBClone(ctx context.Context, t *asynq.Task) error
	// ProcessKnowledgeMove handles Asynq knowledge move tasks
	ProcessKnowledgeMove(ctx context.Context, t *asynq.Task) error
	// ProcessKnowledgeListDelete handles Asynq knowledge list delete tasks
	ProcessKnowledgeListDelete(ctx context.Context, t *asynq.Task) error
	// ProcessKnowledgeListReparse handles Asynq knowledge list reparse tasks
	ProcessKnowledgeListReparse(ctx context.Context, t *asynq.Task) error
	// GetKBCloneProgress retrieves the progress of a knowledge base clone task
	GetKBCloneProgress(ctx context.Context, taskID string) (*types.KBCloneProgress, error)
	// SaveKBCloneProgress saves the progress of a knowledge base clone task
	SaveKBCloneProgress(ctx context.Context, progress *types.KBCloneProgress) error
	// GetKnowledgeMoveProgress retrieves the progress of a knowledge move task
	GetKnowledgeMoveProgress(ctx context.Context, taskID string) (*types.KnowledgeMoveProgress, error)
	// SaveKnowledgeMoveProgress saves the progress of a knowledge move task
	SaveKnowledgeMoveProgress(ctx context.Context, progress *types.KnowledgeMoveProgress) error
	// GetFAQImportProgress retrieves the progress of an FAQ import task
	GetFAQImportProgress(ctx context.Context, taskID string) (*types.FAQImportProgress, error)
	// UpdateLastFAQImportResultDisplayStatus updates the display status of FAQ import result
	UpdateLastFAQImportResultDisplayStatus(ctx context.Context, kbID string, displayStatus string) error
	// SearchKnowledge searches knowledge items by keyword across the tenant.
	// fileTypes: optional list of file extensions to filter by (e.g., ["csv", "xlsx"])
	SearchKnowledge(ctx context.Context, keyword string, offset, limit int, fileTypes []string) ([]*types.Knowledge, bool, int64, error)
	// SearchKnowledgeForScopes searches knowledge within the given (tenant_id, kb_id) scopes (e.g. for shared agent context).
	SearchKnowledgeForScopes(ctx context.Context, scopes []types.KnowledgeSearchScope, keyword string, offset, limit int, fileTypes []string) ([]*types.Knowledge, bool, int64, error)
}

type KnowledgeTagRepository interface {
	Create(ctx context.Context, tag *types.KnowledgeTag) error
	Update(ctx context.Context, tag *types.KnowledgeTag) error
	GetByID(ctx context.Context, tenantID uint64, id string) (*types.KnowledgeTag, error)
	// GetBySeqID retrieves a tag by its seq_id.
	GetBySeqID(ctx context.Context, tenantID uint64, seqID int64) (*types.KnowledgeTag, error)
	// GetByIDs retrieves multiple tags by their IDs in a single query.
	GetByIDs(ctx context.Context, tenantID uint64, ids []string) ([]*types.KnowledgeTag, error)
	// GetBySeqIDs retrieves multiple tags by their seq_ids in a single query.
	GetBySeqIDs(ctx context.Context, tenantID uint64, seqIDs []int64) ([]*types.KnowledgeTag, error)
	GetByName(ctx context.Context, tenantID uint64, kbID string, name string) (*types.KnowledgeTag, error)
	ListByKB(
		ctx context.Context,
		tenantID uint64,
		kbID string,
		page *types.Pagination,
		keyword string,
	) ([]*types.KnowledgeTag, int64, error)
	Delete(ctx context.Context, tenantID uint64, id string) error
	// CountReferences returns number of knowledges and chunks that reference the tag.
	CountReferences(
		ctx context.Context,
		tenantID uint64,
		kbID string,
		tagID string,
	) (knowledgeCount int64, chunkCount int64, err error)
	// BatchCountReferences returns number of knowledges and chunks for multiple tags in a single query.
	// Returns a map of tagID -> {knowledgeCount, chunkCount}
	BatchCountReferences(
		ctx context.Context,
		tenantID uint64,
		kbID string,
		tagIDs []string,
	) (map[string]types.TagReferenceCounts, error)
	// DeleteUnusedTags deletes tags that are not referenced by any knowledge or chunk.
	DeleteUnusedTags(ctx context.Context, tenantID uint64, kbID string) (int64, error)
}

type KnowledgeTagService interface {
	// ListTags lists all tags under a knowledge base with associated statistics.
	ListTags(ctx context.Context, kbID string, page *types.Pagination, keyword string) (*types.PageResult, error)
	// CreateTag creates a new tag under a knowledge base.
	CreateTag(ctx context.Context, kbID string, name string, color string, sortOrder int) (*types.KnowledgeTag, error)
	// UpdateTag updates tag basic information.
	UpdateTag(ctx context.Context, id string, name *string, color *string, sortOrder *int) (*types.KnowledgeTag, error)
	// DeleteTag deletes a tag.
	// When contentOnly=true, only deletes the content under the tag but keeps the tag itself.
	// excludeIDs: IDs of chunks to exclude from deletion (only valid when deleting chunks)
	DeleteTag(ctx context.Context, id string, force bool, contentOnly bool, excludeIDs []string) error
	// FindOrCreateTagByName finds a tag by name or creates it if not exists.
	FindOrCreateTagByName(ctx context.Context, kbID string, name string) (*types.KnowledgeTag, error)
	// ProcessIndexDelete handles async index deletion task
	ProcessIndexDelete(ctx context.Context, t *asynq.Task) error
}

type MCPEndpointRepository interface {
	Create(ctx context.Context, ep *types.MCPEndpoint) error
	GetByID(ctx context.Context, id string) (*types.MCPEndpoint, error)
	GetByTokenHash(ctx context.Context, tokenHash string) (*types.MCPEndpoint, error)
	ListByTenant(ctx context.Context, tenantID uint64) ([]*types.MCPEndpoint, error)
	Update(ctx context.Context, ep *types.MCPEndpoint) error
	Delete(ctx context.Context, tenantID uint64, id string) error
	TouchLastUsed(ctx context.Context, id string) error
}

type MCPEndpointService interface {
	// Create stores a new endpoint and returns it together with the one-time
	// plaintext token.
	Create(ctx context.Context, tenantID uint64, ep *types.MCPEndpoint) (*types.MCPEndpoint, string, error)
	Get(ctx context.Context, tenantID uint64, id string) (*types.MCPEndpoint, error)
	List(ctx context.Context, tenantID uint64) ([]*types.MCPEndpoint, error)
	Update(ctx context.Context, tenantID uint64, id string, upd MCPEndpointUpdate) (*types.MCPEndpoint, error)
	Delete(ctx context.Context, tenantID uint64, id string) error
	// RotateToken replaces the bearer token and returns the new plaintext.
	RotateToken(ctx context.Context, tenantID uint64, id string) (*types.MCPEndpoint, string, error)
	// Authenticate resolves a bearer token presented on the MCP surface to an
	// enabled endpoint whose ID matches. It returns ErrMCPEndpointNotFound or
	// ErrMCPEndpointDisabled style sentinels on failure.
	Authenticate(ctx context.Context, endpointID, token string) (*types.MCPEndpoint, error)
}

type MCPEndpointUpdate struct {
	Name               *string
	Description        *string
	Enabled            *bool
	KnowledgeBaseIDs   *[]string
	Tools              *[]string
	DefaultAgentID     *string
	RateLimitPerMinute *int
}

type MCPMetadataRepository interface {
	GetMetadata(context.Context, uint64, string, string) (*types.MCPMetadata, error)
	ListMetadataSummaries(context.Context, uint64, []string) ([]*types.MCPMetadataSummary, error)
	SaveMetadata(context.Context, *types.MCPMetadata) error
}

type MCPMetadataService interface {
	// GetMCPMetadata reads only persisted metadata; nil means never synchronized.
	GetMCPMetadata(context.Context, uint64, string) (*types.MCPMetadata, error)
	// ListMCPMetadataSummaries returns persisted directory counts for the list UI.
	ListMCPMetadataSummaries(context.Context, uint64, []*types.MCPService) (map[string]*types.MCPMetadataSummary, error)
	// PersistMCPMetadata stores a complete directory already listed on an authorized connection.
	PersistMCPMetadata(context.Context, uint64, string, []*types.MCPTool, string) error
	// RefreshMCPMetadata explicitly connects and atomically replaces a complete snapshot.
	RefreshMCPMetadata(context.Context, uint64, string) (*types.MCPMetadata, error)
}

type MCPOAuthRepository interface {
	// GetClient returns the registered OAuth client for a service, or
	// (nil, nil) when none has been registered yet.
	GetClient(ctx context.Context, tenantID uint64, serviceID string) (*types.MCPOAuthClient, error)

	// SaveClient creates or updates the registered OAuth client for a service.
	SaveClient(ctx context.Context, client *types.MCPOAuthClient) error

	// DeleteClient removes the registered OAuth client for a service.
	DeleteClient(ctx context.Context, tenantID uint64, serviceID string) error

	// GetToken returns the stored token for (tenant, user, service), or
	// (nil, nil) when the user has not authorized yet.
	GetToken(ctx context.Context, tenantID uint64, userID, serviceID string) (*types.MCPOAuthToken, error)

	// GetTokenForPrincipal returns the stored token for (tenant, principal, service),
	// or (nil, nil) when the principal has not authorized yet.
	GetTokenForPrincipal(
		ctx context.Context, tenantID uint64, principal types.Principal, serviceID string,
	) (*types.MCPOAuthToken, error)

	// SaveToken creates or updates the per-user token for a service.
	SaveToken(ctx context.Context, token *types.MCPOAuthToken) error

	// SaveTokenForPrincipal creates or updates the per-principal token for a service.
	SaveTokenForPrincipal(ctx context.Context, token *types.MCPOAuthToken) error

	// DeleteToken removes the per-user token for a service (revoke /
	// re-authorize).
	DeleteToken(ctx context.Context, tenantID uint64, userID, serviceID string) error

	// DeleteTokenForPrincipal removes the per-principal token for a service.
	DeleteTokenForPrincipal(ctx context.Context, tenantID uint64, principal types.Principal, serviceID string) error

	// TryAcquireTokenRefreshLease atomically claims the right to use a refresh
	// token. This prevents concurrent instances from presenting the same
	// rotating refresh token to the authorization server.
	TryAcquireTokenRefreshLease(
		ctx context.Context,
		tenantID uint64,
		principal types.Principal,
		serviceID, leaseID string,
		leaseUntil time.Time,
	) (bool, error)

	// ReleaseTokenRefreshLease releases a lease only when leaseID still owns it.
	ReleaseTokenRefreshLease(
		ctx context.Context,
		tenantID uint64,
		principal types.Principal,
		serviceID, leaseID string,
	) error
}

type MCPServiceRepository interface {
	// Create creates a new MCP service
	Create(ctx context.Context, service *types.MCPService) error

	// GetByID retrieves an MCP service by ID and tenant ID
	GetByID(ctx context.Context, tenantID uint64, id string) (*types.MCPService, error)

	// List retrieves all MCP services for a tenant
	List(ctx context.Context, tenantID uint64) ([]*types.MCPService, error)

	// ListEnabled retrieves all enabled MCP services for a tenant
	ListEnabled(ctx context.Context, tenantID uint64) ([]*types.MCPService, error)

	// ListByIDs retrieves MCP services by multiple IDs for a tenant
	ListByIDs(ctx context.Context, tenantID uint64, ids []string) ([]*types.MCPService, error)

	// Update updates an MCP service
	Update(ctx context.Context, service *types.MCPService) error

	// Delete deletes an MCP service (soft delete)
	Delete(ctx context.Context, tenantID uint64, id string) error
}

type MCPServiceService interface {
	// CreateMCPService creates a new MCP service
	CreateMCPService(ctx context.Context, service *types.MCPService) error

	// GetMCPServiceByID retrieves an MCP service by ID
	GetMCPServiceByID(ctx context.Context, tenantID uint64, id string) (*types.MCPService, error)

	// ListMCPServices lists all MCP services for a tenant
	ListMCPServices(ctx context.Context, tenantID uint64) ([]*types.MCPService, error)

	// ListMCPMetadataSummaries returns persisted directory counts for the list UI.
	ListMCPMetadataSummaries(context.Context, uint64, []*types.MCPService) (map[string]*types.MCPMetadataSummary, error)

	// ListMCPServicesByIDs retrieves multiple MCP services by IDs
	ListMCPServicesByIDs(ctx context.Context, tenantID uint64, ids []string) ([]*types.MCPService, error)

	// UpdateMCPService updates an MCP service. updateFields records presence for
	// scalar fields whose zero values cannot represent omission. Supported keys
	// are "name", "description", "usage_instructions", "enabled", "auth_type",
	// and "api_key_header"; a nil map means none of those
	// scalar fields were provided.
	UpdateMCPService(
		ctx context.Context,
		service *types.MCPService,
		updateFields map[string]bool,
	) error

	// DeleteMCPService deletes an MCP service
	DeleteMCPService(ctx context.Context, tenantID uint64, id string) error

	// TestMCPService tests the connection to an MCP service and returns available tools/resources
	TestMCPService(ctx context.Context, tenantID uint64, id string) (*types.MCPTestResult, error)

	// GetMCPServiceTools retrieves the list of tools from an MCP service
	GetMCPServiceTools(ctx context.Context, tenantID uint64, id string) ([]*types.MCPTool, error)

	// GetMCPServiceResources retrieves the list of resources from an MCP service
	GetMCPServiceResources(ctx context.Context, tenantID uint64, id string) ([]*types.MCPResource, error)

	// UpdateMCPCredentials writes one or more credential fields on the auth
	// config. Nil pointer means "do not touch this field". Returns the updated
	// service (with current AuthConfig) so the handler can derive the
	// configured/not-configured metadata for the response.
	//
	// Implementations MUST close any active MCP client connection for this
	// service so the next upstream call reconnects with the new credential.
	UpdateMCPCredentials(
		ctx context.Context, tenantID uint64, id string, apiKey, token, clientSecret *string,
	) (*types.MCPService, error)

	// ClearMCPCredential removes a single credential field. field must be
	// "api_key", "token" or "client_secret"; other values must be rejected by
	// the caller.
	// Implementations MUST close any active MCP client connection for this
	// service. Clearing a field that is already empty is a no-op (no error).
	ClearMCPCredential(ctx context.Context, tenantID uint64, id, field string) error
}

type MCPToolApprovalRepository interface {
	ListByService(ctx context.Context, tenantID uint64, serviceID string) ([]*types.MCPToolApproval, error)
	IsRequired(ctx context.Context, tenantID uint64, serviceID, toolName string) (bool, error)
	IsEnabled(ctx context.Context, tenantID uint64, serviceID, toolName string) (bool, error)
	UpsertPolicy(ctx context.Context, tenantID uint64, serviceID, toolName string, patch types.MCPToolPolicyPatch) error
}

type MCPToolApprovalService interface {
	ListByService(ctx context.Context, tenantID uint64, serviceID string) ([]*types.MCPToolApproval, error)
	SetPolicy(ctx context.Context, tenantID uint64, serviceID, toolName string, requireApproval, enabled *bool) error
	SetRequireApproval(ctx context.Context, tenantID uint64, serviceID, toolName string, require bool) error
	SetEnabled(ctx context.Context, tenantID uint64, serviceID, toolName string, enabled bool) error
	IsRequired(ctx context.Context, tenantID uint64, serviceID, toolName string) (bool, error)
	IsEnabled(ctx context.Context, tenantID uint64, serviceID, toolName string) (bool, error)
}

type MemoryExtractionFailure struct {
	Session types.MemoryExtractionSession
	End     types.MemoryMessageCursor
	Code    string
}

type MemoryRecall struct {
	// Prompt is the ready-to-append envelope, empty when nothing was recalled.
	Prompt string
	// Items are the situational items plus the resident items that produced
	// Prompt, in the order they appear. Surfaced to the chat UI.
	Items []*types.MemoryItem
}

type MemoryRepository interface {
	// GetSubject returns the memory space, or (nil, nil) when it does not exist.
	GetSubject(ctx context.Context, scope MemoryScope) (*types.MemorySubject, error)
	// EnsureSubject returns the memory space, creating it on first use.
	EnsureSubject(ctx context.Context, scope MemoryScope) (*types.MemorySubject, error)
	// UpdateSubjectEnabled flips the per-user opt out.
	UpdateSubjectEnabled(ctx context.Context, scope MemoryScope, enabled bool) error
	// UpdateSubjectBlock stores the rendered resident block and item count.
	UpdateSubjectBlock(ctx context.Context, scope MemoryScope, block string, itemCount int) error
	// EnqueuePendingSession records that a session has turns past the cursor
	// and claims the in-flight slot when no run is already scheduled. It
	// returns the subject as it was before the update plus whether this call
	// is the one responsible for enqueuing the task, so a burst of turns
	// produces exactly one task and never a dropped turn.
	EnqueuePendingSession(
		ctx context.Context, scope MemoryScope, sessionID string, inFlightTimeout time.Duration,
	) (*types.MemorySubject, bool, error)
	// ClaimPendingSessions leases a snapshot without removing durable work.
	// A nil batch means no work remains; RetryAt defers a busy lease.
	ClaimPendingSessions(ctx context.Context, scope MemoryScope, fallbackSession, leaseID string, ttl time.Duration) (*types.MemoryExtractionBatch, error)
	// CheckpointExtraction acknowledges a processed segment (or a recorded
	// skip). A concurrent enqueue changes Revision and keeps the session pending.
	CheckpointExtraction(ctx context.Context, scope MemoryScope, leaseID string, session types.MemoryExtractionSession, cursor types.MemoryMessageCursor, drained bool) error
	HasPendingExtraction(ctx context.Context, scope MemoryScope) (bool, error)
	// RecordExtractionFailure returns true after the bounded invalid-output
	// retry budget. It preserves a failure range without storing transcript text.
	RecordExtractionFailure(
		ctx context.Context, scope MemoryScope, leaseID string, session MemoryExtractionFailure,
	) (bool, error)
	FinishExtraction(ctx context.Context, scope MemoryScope, leaseID string) error
	// Empty leaseID only releases a queued task, never a running worker.
	ReleaseExtractionSlot(ctx context.Context, scope MemoryScope, leaseID string) error
	// SaveItem atomically inserts and resolves active/pending replacements.
	SaveItem(ctx context.Context, scope MemoryScope, item *types.MemoryItem, replacesID string) error
	// ConfirmPendingItem atomically activates a proposal and retires its target.
	ConfirmPendingItem(ctx context.Context, scope MemoryScope, id string) error

	// CreateItem inserts one memory item.
	CreateItem(ctx context.Context, item *types.MemoryItem) error
	// GetItem returns one item inside the scope, or (nil, nil) when absent.
	GetItem(ctx context.Context, scope MemoryScope, id string) (*types.MemoryItem, error)
	// ListActiveByKinds returns active items of the given kinds, newest first.
	ListActiveByKinds(ctx context.Context, scope MemoryScope, kinds []string, limit int) ([]*types.MemoryItem, error)
	// ListActiveResident returns the items that belong in the always-injected
	// block: stable traits, plus anything the user explicitly asked to keep.
	ListActiveResident(ctx context.Context, scope MemoryScope, limit int) ([]*types.MemoryItem, error)
	// ListItems returns items for the memory manager, filtered by status.
	ListItems(ctx context.Context, scope MemoryScope, status string, limit, offset int) ([]*types.MemoryItem, int64, error)
	// FindActiveByKey returns the active item occupying a topic key, if any.
	FindActiveByKey(ctx context.Context, scope MemoryScope, normalizedKey string) (*types.MemoryItem, error)
	// UpdateItemContent rewrites an item edited in the memory manager.
	UpdateItemContent(ctx context.Context, scope MemoryScope, id, content, normalizedKey string, importance int) error
	// SupersedeItem marks an outdated item as replaced by another one.
	SupersedeItem(ctx context.Context, scope MemoryScope, id, supersededBy string) error
	// DeleteItem physically removes one item. Forgetting means forgetting.
	DeleteItem(ctx context.Context, scope MemoryScope, id string) error
	// DeleteAll removes every item in the scope and returns how many were removed.
	DeleteAll(ctx context.Context, scope MemoryScope) (int64, error)
	// TouchUsed records that items were injected into a turn.
	TouchUsed(ctx context.Context, scope MemoryScope, ids []string) error
	// AddTombstone records that a statement was deliberately forgotten. Only
	// the topic, a fingerprint and the originating message are stored, never
	// the statement itself.
	AddTombstone(ctx context.Context, scope MemoryScope, topic, fingerprint, sourceMessageID string) error
	// HasTombstoneForMessage reports whether a memory derived from this message
	// was rejected within the given window. The window matters: this rule
	// exists to stop the re-derivation that happens one debounce later, not to
	// ban a message for good.
	HasTombstoneForMessage(
		ctx context.Context, scope MemoryScope, sourceMessageID string, within time.Duration,
	) (bool, error)
	// ListTombstones returns the most recent rejections for this subject.
	ListTombstones(ctx context.Context, scope MemoryScope, limit int) ([]*types.MemoryTombstone, error)
	// HasTombstone reports whether this exact statement was already forgotten.
	HasTombstone(ctx context.Context, scope MemoryScope, fingerprint string) (bool, error)
	// ExpireOverdue archives items whose expires_at has passed and returns how
	// many were archived.
	ExpireOverdue(ctx context.Context, scope MemoryScope) (int64, error)
	// MarkConsolidated records that this subject's whole store was just
	// reviewed, so the next review waits out the interval.
	MarkConsolidated(ctx context.Context, scope MemoryScope) error
	// MarkForcedConsolidated records that this subject asked for a review
	// themselves. Kept apart from MarkConsolidated so the daily pass and the
	// button rate limit each other independently.
	MarkForcedConsolidated(ctx context.Context, scope MemoryScope) error
	// UpsertItemEmbedding stores or replaces the vector for one memory.
	UpsertItemEmbedding(ctx context.Context, scope MemoryScope, embedding *types.MemoryItemEmbedding) error
	// DeleteItemEmbedding drops one memory's vector. What a memory embeds to
	// can change after it is written — an interest embeds the other wordings
	// of its subject — and dropping the vector is how the existing backfill is
	// asked to rebuild it.
	DeleteItemEmbedding(ctx context.Context, scope MemoryScope, itemID string) error
	// ItemEmbeddings loads the vectors for the given items, keyed by item id.
	// Only vectors produced by modelID are returned: vectors from a different
	// model are not comparable, so mixing them would score nonsense.
	ItemEmbeddings(ctx context.Context, scope MemoryScope, itemIDs []string, modelID string) (map[string][]float32, error)
	// SearchItemsByVector returns this subject's semantically closest items,
	// ranked by the database over every vector it holds.
	//
	// It replaces "list some items, then score the ones that happened to be
	// listed". That order was the bug: candidates were chosen by importance,
	// which says nothing about whether an item answers the question, so a
	// well-matching memory outside the listed window could not be found at all.
	SearchItemsByVector(ctx context.Context, scope MemoryScope, query MemoryVectorQuery) ([]MemoryVectorHit, error)
	// SyncVectorColumn copies stored vectors into the database's own vector
	// type for rows written before there was one. Returns how many it moved,
	// and 0 on a deployment that scores in process. No model calls: the vector
	// already exists, only its representation is behind.
	SyncVectorColumn(ctx context.Context, scope MemoryScope, limit int) (int, error)
	// ItemsMissingEmbeddings returns active items that have no vector yet, so a
	// background pass can fill them in.
	ItemsMissingEmbeddings(ctx context.Context, scope MemoryScope, modelID string, limit int) ([]*types.MemoryItem, error)
	// ListLive returns items of one kind that the user can see: in use plus
	// proposed and awaiting a decision.
	ListLive(ctx context.Context, scope MemoryScope, kind string, limit int) ([]*types.MemoryItem, error)

	// BumpTopic records one more sighting of a topic and returns the running
	// total, so a caller can decide whether it has recurred enough to promote.
	BumpTopic(
		ctx context.Context, scope MemoryScope, topic, normalizedKey, alias string,
	) (*types.MemoryTopicStat, error)
	// RenameTopic gives a subject a better canonical label, keeping the old one
	// as an alias. Reports false when another row already holds the new key.
	RenameTopic(ctx context.Context, scope MemoryScope, oldKey, newKey, newLabel string) (bool, error)
	// MarkTopicPromoted stops a topic from being promoted again.
	MarkTopicPromoted(ctx context.Context, scope MemoryScope, normalizedKey string) error
	// TopTopics returns the most-asked topics, newest activity first.
	TopTopics(ctx context.Context, scope MemoryScope, limit int) ([]*types.MemoryTopicStat, error)
	// TopicByKey returns one subject's statistics, or nil when it is not
	// tracked. It exists so an interest can be embedded together with the
	// other wordings this person has used for the same subject.
	TopicByKey(ctx context.Context, scope MemoryScope, normalizedKey string) (*types.MemoryTopicStat, error)
	// TopicByID returns one topic row inside the scope, or (nil, nil) when it
	// is absent. Used by the memory manager so a user can promote or dismiss
	// a subject that has not yet become a memory.
	TopicByID(ctx context.Context, scope MemoryScope, id string) (*types.MemoryTopicStat, error)
	// ListUnpromotedTopics returns subjects that have been counted but have
	// not yet become an interest, closest to the threshold first.
	ListUnpromotedTopics(ctx context.Context, scope MemoryScope, limit, offset int) ([]*types.MemoryTopicStat, int64, error)
	// DeleteTopic removes one topic row. Counting starts over if the subject
	// is asked about again, unless a tombstone blocks promotion.
	DeleteTopic(ctx context.Context, scope MemoryScope, id string) error
	// DeleteAllTopics drops every topic counter in the scope. Clearing memory
	// has to include these, or a subject sitting at N-1 would promote on the
	// next question after the user asked to forget everything.
	DeleteAllTopics(ctx context.Context, scope MemoryScope) error

	// BumpDocAffinity records that an answer for this person drew on a document.
	BumpDocAffinity(ctx context.Context, scope MemoryScope, docs []types.MemoryDocAffinity) error
	// DocAffinity returns this person's affinity for the given documents.
	DocAffinity(ctx context.Context, scope MemoryScope, knowledgeIDs []string) (map[string]int, error)
	// TopDocAffinity returns the documents this person relies on most.
	TopDocAffinity(ctx context.Context, scope MemoryScope, limit int) ([]*types.MemoryDocAffinity, error)
	// DocAffinityByID returns one affinity row inside the scope, or (nil, nil)
	// when it is absent.
	DocAffinityByID(ctx context.Context, scope MemoryScope, id string) (*types.MemoryDocAffinity, error)
	// ListFamiliarDocs returns documents cited often enough to count as a
	// habit, most-used first.
	ListFamiliarDocs(ctx context.Context, scope MemoryScope, minHits, limit, offset int) ([]*types.MemoryDocAffinity, int64, error)
	// DeleteDocAffinity removes one document counter.
	DeleteDocAffinity(ctx context.Context, scope MemoryScope, id string) error
	// DeleteAllDocAffinity drops every document counter in the scope.
	DeleteAllDocAffinity(ctx context.Context, scope MemoryScope) error
	// ArchiveLowestRanked archives active items beyond the capacity cap and
	// returns how many were archived.
	ArchiveLowestRanked(ctx context.Context, scope MemoryScope, keep int) (int64, error)
	// CountActive returns the number of active items in the scope.
	CountActive(ctx context.Context, scope MemoryScope) (int64, error)
}

type MemoryScope struct {
	TenantID  uint64
	SubjectID string
}

type MemorySearchResult struct {
	// Available is false when memory is off at any level — workspace, user or
	// the agent handling this request.
	Available bool
	// Items are the matches, most relevant first.
	Items []*types.MemoryItem
}

type MemoryService interface {
	// Recall assembles the memory to inject for one turn. It performs no LLM
	// calls and returns an empty recall (never an error) whenever memory is
	// disabled at any level, so callers can use it unconditionally.
	Recall(ctx context.Context, query string) MemoryRecall
	// SearchMemory ranks the user's stored memories against an arbitrary
	// query, for callers that need to reach past what Recall's per-turn budget
	// admitted. Like Recall it performs no LLM call and never errors.
	SearchMemory(ctx context.Context, query string, limit int) MemorySearchResult
	// MemoryAvailable reports whether this request may read memory at all:
	// the workspace switch, the user's own opt out and the agent's preference
	// combined.
	//
	// Read paths do not need this — Recall and SearchMemory already degrade on
	// their own. It exists for callers that must decide whether to *offer* a
	// memory-backed feature, where the difference between "off" and "empty"
	// has to be settled before anything is built rather than after it is
	// called.
	MemoryAvailable(ctx context.Context) bool
	// RetrievalContextFor returns what memory contributes to retrieval. Like
	// Recall it makes no model call and degrades to an empty value.
	RetrievalContextFor(ctx context.Context) RetrievalContext
	// DocumentAffinity scores the given documents by how much this person has
	// relied on them before. Absent documents simply have no entry.
	DocumentAffinity(ctx context.Context, knowledgeIDs []string) map[string]int
	// RecordAnswerSources notes which documents an answer drew on, which is the
	// only per-person retrieval signal available without asking anything.
	RecordAnswerSources(ctx context.Context, refs []types.MemoryDocAffinity)
	// ObserveQuestionTopics counts what a person asked about so a recurring
	// subject can become an interest. Returns any newly promoted interests.
	ObserveQuestionTopics(ctx context.Context, topics []string) []string
	// Remember stores a statement the user explicitly asked to keep.
	Remember(ctx context.Context, item types.MemoryItem) (*types.MemoryItem, error)
	// ScheduleExtraction debounces and enqueues background distillation for a
	// finished turn. Best effort: failures are logged, never returned.
	ScheduleExtraction(ctx context.Context, sessionID, messageID, chatModelID string)
	// Handle runs the background distillation task.
	Handle(ctx context.Context, task *asynq.Task) error

	// ListItems backs the memory manager list.
	ListItems(ctx context.Context, status string, limit, offset int) ([]*types.MemoryItem, int64, error)
	// ListTopics returns subjects that have been counted but not yet promoted
	// into an interest, so the memory manager can show what is still forming.
	ListTopics(ctx context.Context, limit, offset int) ([]*types.MemoryTopicView, int64, error)
	// PromoteTopic turns a counted subject into an interest immediately,
	// without waiting for the remaining hits.
	PromoteTopic(ctx context.Context, id string) (*types.MemoryItem, error)
	// DeleteTopic stops tracking a subject. The refusal is remembered so the
	// same topic is not promoted automatically later.
	DeleteTopic(ctx context.Context, id string) error
	// ListDocuments returns documents this person keeps drawing answers from.
	ListDocuments(ctx context.Context, limit, offset int) ([]*types.MemoryDocView, int64, error)
	// DeleteDocument stops using one document as a personal retrieval signal.
	DeleteDocument(ctx context.Context, id string) error
	// FamiliarKnowledgeIDs returns the knowledge ids that have been cited
	// often enough to count as a habit. Used to highlight Wiki pages whose
	// source documents this person actually works from. Empty on any failure
	// so callers can use it unconditionally.
	FamiliarKnowledgeIDs(ctx context.Context) []string
	// CreateItem adds a memory typed by the user in the memory manager.
	CreateItem(ctx context.Context, kind, content string, importance int) (*types.MemoryItem, error)
	// ConfirmItem accepts a memory the system inferred, so it starts being used.
	ConfirmItem(ctx context.Context, id string) (*types.MemoryItem, error)
	// RejectItem declines an inference and remembers the refusal, so the same
	// guess is not proposed again next week.
	RejectItem(ctx context.Context, id string) error
	// UpdateItem edits one item's content and importance.
	UpdateItem(ctx context.Context, id, content string, importance int) (*types.MemoryItem, error)
	// DeleteItem forgets one item.
	DeleteItem(ctx context.Context, id string) error
	// Clear forgets everything in the caller's memory space.
	Clear(ctx context.Context) (int64, error)
	// ConsolidateNow reviews the caller's store for near-duplicates and stale
	// tasks immediately, without waiting for the daily distillation pass.
	ConsolidateNow(ctx context.Context) (*types.MemoryConsolidationResult, error)
	// GetSettings returns the effective per-user memory settings.
	GetSettings(ctx context.Context) (*types.MemorySettings, error)
	// SetEnabled flips the per-user opt out.
	SetEnabled(ctx context.Context, enabled bool) error
}

type MemoryVectorHit struct {
	Item  *types.MemoryItem
	Score float64
}

type MemoryVectorQuery struct {
	// ModelID pins the vector space. Vectors from another model are skipped
	// rather than scored, because the distance between them is meaningless.
	ModelID string
	// Vector is the embedded query.
	Vector []float32
	// Kinds restricts which memories may come back. Empty means every kind.
	Kinds []string
	// MinScore is the cosine floor below which a match is not a match.
	MinScore float64
	// Limit is how many hits to return, best first.
	Limit int
}

type MessageFileBindingLookup interface {
	GetMessageFileBindings(
		ctx context.Context,
		tenantID uint64,
		reference, messageID string,
	) (*types.MessageFileBindings, error)
}

type MessageRepository interface {
	// CreateMessage creates a message
	CreateMessage(ctx context.Context, message *types.Message) (*types.Message, error)
	// GetMessage gets a message
	GetMessage(ctx context.Context, sessionID string, id string) (*types.Message, error)
	// GetMessagesBySession gets all messages of a session
	GetMessagesBySession(ctx context.Context, sessionID string, page int, pageSize int) ([]*types.Message, error)
	// GetRecentMessagesBySession gets recent messages of a session
	GetRecentMessagesBySession(ctx context.Context, sessionID string, limit int) ([]*types.Message, error)
	// GetMessagesBySessionBeforeTime gets messages before a specific time of a session
	GetMessagesBySessionBeforeTime(
		ctx context.Context, sessionID string, beforeTime time.Time, limit int,
	) ([]*types.Message, error)
	// ListMessagesBySessionAfterTime returns messages created strictly after
	// afterTime, oldest first. Long-term memory distillation walks forward from
	// a watermark, so it needs the oldest unprocessed messages rather than the
	// newest ones: paging from the newest end would skip everything in between
	// once a session outruns the page size.
	ListMessagesBySessionAfterTime(
		ctx context.Context, sessionID string, afterTime time.Time, limit int,
	) ([]*types.Message, error)
	// ListMessagesBySessionAfterCursor uses (created_at, id) for lossless paging.
	ListMessagesBySessionAfterCursor(ctx context.Context, sessionID string, cursor types.MemoryMessageCursor, limit int) ([]*types.Message, error)
	// ListMessagesBySessionBeforeCursor pages a session backwards: up to limit
	// messages sorting strictly before (before, beforeID), newest first. A zero
	// cursor starts from the newest message.
	ListMessagesBySessionBeforeCursor(
		ctx context.Context, sessionID string, before time.Time, beforeID string, limit int,
	) ([]*types.Message, error)
	// ListMessagesBySessionUpTo returns every message sorting strictly before
	// the (boundary, boundaryID) composite cursor, oldest first. Used by
	// session fork to copy the history preceding a fork point.
	ListMessagesBySessionUpTo(
		ctx context.Context, sessionID string, boundary time.Time, boundaryID string,
	) ([]*types.Message, error)
	// UpdateMessage updates a message
	UpdateMessage(ctx context.Context, message *types.Message) error
	// UpdateMessageImages updates only the images JSONB column for a message
	UpdateMessageImages(ctx context.Context, sessionID, messageID string, images types.MessageImages) error
	// UpdateMessageRenderedContent updates the rendered_content column for a user message
	UpdateMessageRenderedContent(ctx context.Context, sessionID, messageID string, renderedContent string) error
	// UpdateMessageContextCheckpoint writes only the context_checkpoint column
	// of an assistant message.
	UpdateMessageContextCheckpoint(
		ctx context.Context, sessionID, messageID string, checkpoint *types.ContextCheckpoint,
	) error
	// GetLatestContextCheckpoint returns the newest assistant message in the
	// session that carries a context checkpoint, projected to the columns
	// history loading needs, or nil when there is none.
	GetLatestContextCheckpoint(ctx context.Context, sessionID string) (*types.Message, error)
	// DeleteMessage deletes a message
	DeleteMessage(ctx context.Context, sessionID string, id string) error
	// DeleteMessagesFrom deletes every message at or after the
	// (boundary, boundaryID) composite cursor and returns the deleted rows,
	// oldest first. inclusive keeps or drops the boundary message itself,
	// which is what separates a user rewind point from an assistant one.
	DeleteMessagesFrom(
		ctx context.Context, sessionID string, boundary time.Time, boundaryID string, inclusive bool,
	) ([]*types.Message, error)
	// DeleteMessagesBySessionID deletes all messages belonging to a session
	DeleteMessagesBySessionID(ctx context.Context, sessionID string) error
	// GetFirstMessageOfUser gets the first message of a user
	GetFirstMessageOfUser(ctx context.Context, sessionID string) (*types.Message, error)
	// SearchMessagesByKeyword searches messages by keyword across sessions for a tenant
	// OwnedSessionIDs narrows a set of session ids to the ones this person owns.
	OwnedSessionIDs(ctx context.Context, tenantID uint64, ownerID string, sessionIDs []string) (map[string]bool, error)
	SearchMessagesByKeyword(ctx context.Context, tenantID uint64, ownerID, keyword string, sessionIDs []string, limit int) ([]*types.MessageWithSession, error)
	// GetMessagesByKnowledgeIDs retrieves messages by their associated Knowledge IDs
	GetMessagesByKnowledgeIDs(ctx context.Context, knowledgeIDs []string) ([]*types.MessageWithSession, error)
	// GetMessagesByRequestIDs retrieves messages by request ID inside one session
	// (used to fetch Q&A pair partners). Empty sessionID returns no rows.
	GetMessagesByRequestIDs(
		ctx context.Context, sessionID string, requestIDs []string,
	) ([]*types.MessageWithSession, error)
	// GetKnowledgeIDsBySessionID retrieves all knowledge IDs for messages in a session
	GetKnowledgeIDsBySessionID(ctx context.Context, sessionID string) ([]string, error)
	// UpdateMessageKnowledgeID updates the knowledge_id field for a message
	UpdateMessageKnowledgeID(ctx context.Context, messageID string, knowledgeID string) error
	// GetSessionArtifacts returns every skill-produced MessageArtifact recorded
	// against any assistant message of the session, in creation order. The
	// implementation only projects the artifacts JSONB column, so it stays
	// cheap even for long conversations. Empty slice + nil error means the
	// session has no artifacts yet (never an error).
	GetSessionArtifacts(ctx context.Context, sessionID string) (types.MessageArtifacts, error)
	// ListArtifactLibrary returns one page of the latest artifact versions in
	// the sessions query.TenantID / query.UserID can see, plus the total.
	ListArtifactLibrary(
		ctx context.Context, query *types.ArtifactLibraryQuery,
	) ([]*types.ArtifactLibraryItem, int64, error)
	// FindSessionArtifact returns the live artifact row addressed by
	// (session, message, position), or nil when there is none. A tombstoned
	// row reads as absent.
	FindSessionArtifact(
		ctx context.Context, sessionID, messageID string, position int,
	) (*types.MessageArtifactRecord, error)
	// FindSessionArtifactVersions returns every live row of the session sharing
	// sourcePath — the regenerations the artifact library folds into one entry.
	// An empty sourcePath yields nothing: such artifacts have no version group.
	FindSessionArtifactVersions(
		ctx context.Context, sessionID, sourcePath string,
	) ([]types.MessageArtifactRecord, error)
	// SoftDeleteSessionArtifacts tombstones the referenced rows and returns the
	// subset it marked, leaving out rows another caller already tombstoned.
	SoftDeleteSessionArtifacts(
		ctx context.Context, sessionID string, refs []types.ArtifactRef, at time.Time,
	) ([]types.ArtifactRef, error)
	// CountLiveArtifactsByURL counts undeleted artifact rows pointing at a
	// stored object, across every session. Callers use it as the last guard
	// before reclaiming bytes that a fork copy, a legacy raw path or a later
	// re-attachment may still need.
	CountLiveArtifactsByURL(ctx context.Context, url string) (int64, error)
	// GetSessionAttachments returns every user-uploaded attachment recorded in
	// the session. Implementations should project only the attachments column.
	GetSessionAttachments(ctx context.Context, sessionID string) (types.MessageAttachments, error)
	// RewriteSandboxCheckpoints replaces SandboxID on every copied checkpoint
	// in the session that still points at oldSandboxID, keeping CommitSHA and
	// CommittedAt. Used after a forked sandbox boots so a later fork-of-fork
	// compares against the live handle rather than the parent's sandbox.
	RewriteSandboxCheckpoints(ctx context.Context, sessionID, oldSandboxID, newSandboxID string) error
}

type MessageService interface {
	// CreateMessage creates a message
	CreateMessage(ctx context.Context, message *types.Message) (*types.Message, error)

	// GetMessage gets a message
	GetMessage(ctx context.Context, sessionID string, id string) (*types.Message, error)

	// GetMessagesBySession gets all messages of a session
	GetMessagesBySession(ctx context.Context, sessionID string, page int, pageSize int) ([]*types.Message, error)

	// GetRecentMessagesBySession gets recent messages of a session
	GetRecentMessagesBySession(ctx context.Context, sessionID string, limit int) ([]*types.Message, error)

	// GetMessagesBySessionBeforeTime gets messages before a specific time of a session
	GetMessagesBySessionBeforeTime(
		ctx context.Context, sessionID string, beforeTime time.Time, limit int,
	) ([]*types.Message, error)

	// UpdateMessage updates a message
	UpdateMessage(ctx context.Context, message *types.Message) error

	// UpdateMessageImages updates only the images JSONB column for a message.
	UpdateMessageImages(ctx context.Context, sessionID, messageID string, images types.MessageImages) error

	// UpdateMessageRenderedContent updates the rendered_content column for a user message.
	UpdateMessageRenderedContent(ctx context.Context, sessionID, messageID string, renderedContent string) error

	// DeleteMessage deletes a message
	DeleteMessage(ctx context.Context, sessionID string, id string) error

	// ClearSessionMessages deletes all messages in a session, along with their chat history KB entries
	ClearSessionMessages(ctx context.Context, sessionID string) error

	// SearchMessages searches messages by keyword and/or vector similarity across the caller's own sessions.
	// Uses the chat history knowledge base for vector search instead of in-memory computation.
	SearchMessages(ctx context.Context, params *types.MessageSearchParams) (*types.MessageSearchResult, error)

	// IndexMessageToKB indexes a message (Q&A pair) into the chat history knowledge base asynchronously.
	// Called after assistant message is created to enable future vector search.
	IndexMessageToKB(ctx context.Context, userQuery string, assistantAnswer string, messageID string, sessionID string)

	// DeleteMessageKnowledge deletes the Knowledge entry associated with a message from the chat history KB.
	DeleteMessageKnowledge(ctx context.Context, knowledgeID string)

	// DeleteSessionKnowledge deletes all Knowledge entries for messages in a session from the chat history KB.
	DeleteSessionKnowledge(ctx context.Context, sessionID string)

	// GetChatHistoryKBStats returns statistics about the chat history knowledge base (indexed message count, etc.)
	GetChatHistoryKBStats(ctx context.Context) (*types.ChatHistoryKBStats, error)

	// GetSessionArtifacts returns every skill-produced MessageArtifact
	// recorded against any assistant message of the session. Used to power
	// the frontend "download files generated in this session" drawer and
	// to clean up storage blobs on session deletion.
	GetSessionArtifacts(ctx context.Context, sessionID string) (types.MessageArtifacts, error)

	// ListArtifactLibrary lists the latest version of every artifact across
	// the caller's sessions, newest first. Tenant and owner scope come from
	// ctx; query.TenantID and query.UserID are overwritten.
	ListArtifactLibrary(ctx context.Context, query *types.ArtifactLibraryQuery) (*types.PageResult, error)

	// DeleteSessionArtifact tombstones a skill-generated file (and optionally
	// every version of it) in a session the caller owns, and reports the blobs
	// whose bytes the caller should now reclaim. Shared-agent read access does
	// not carry delete rights.
	DeleteSessionArtifact(
		ctx context.Context, req *types.ArtifactDeleteRequest,
	) (*types.ArtifactDeleteResult, error)
}

type MessageSuggestionRepository interface {
	GetByCacheKey(
		ctx context.Context,
		tenantID uint64,
		assistantMessageID string,
		placement string,
		configHash string,
		locale string,
	) (*types.MessageSuggestionSet, error)
	GetByID(ctx context.Context, tenantID uint64, sessionID string, id string) (*types.MessageSuggestionSet, error)
	AcquireGeneration(
		ctx context.Context,
		set *types.MessageSuggestionSet,
		regenerate bool,
	) (*types.MessageSuggestionSet, bool, error)
	Save(ctx context.Context, set *types.MessageSuggestionSet) error
	CreateEvent(ctx context.Context, event *types.MessageSuggestionEvent) error
	DeleteByMessageID(ctx context.Context, tenantID uint64, sessionID string, messageID string) error
	DeleteBySessionID(ctx context.Context, tenantID uint64, sessionID string) error
}

type MessageSuggestionService interface {
	EnsureFollowUps(
		ctx context.Context,
		sessionID string,
		assistantMessageID string,
		regenerate bool,
	) (*types.MessageSuggestionSet, error)
	GetFollowUps(
		ctx context.Context,
		sessionID string,
		assistantMessageID string,
	) (*types.MessageSuggestionSet, error)
	RecordEvent(
		ctx context.Context,
		sessionID string,
		setID string,
		questionID string,
		eventType string,
	) error
	ValidateAttribution(ctx context.Context, sessionID string, query string, attribution *types.SuggestionAttribution) error
}

type Metrics interface {
	// Compute calculates metric score based on input data
	Compute(metricInput *types.MetricInput) float64
}

type ModelRepository interface {
	// Create creates a model
	Create(ctx context.Context, model *types.Model) error
	// GetByID gets a model by ID
	GetByID(ctx context.Context, tenantID uint64, id string) (*types.Model, error)
	// List lists all models
	List(
		ctx context.Context,
		tenantID uint64,
		modelType types.ModelType,
		source types.ModelSource,
	) ([]*types.Model, error)
	// Update updates a model
	Update(ctx context.Context, model *types.Model) error
	// Delete deletes a model
	Delete(ctx context.Context, tenantID uint64, id string) error
	// ClearDefaultByType clears the default flag for all models of a specific type
	// optionally excluding a specific model ID.
	ClearDefaultByType(ctx context.Context, tenantID uint, modelType types.ModelType, excludeID string) error
}

type ModelService interface {
	// CreateModel creates a model
	CreateModel(ctx context.Context, model *types.Model) error
	// CopyModel clones a tenant model. The model name stays the source
	// identifier; displayName is the caller-chosen label. Stored credentials
	// are copied with the row. An active local model is not downloaded again.
	CopyModel(ctx context.Context, sourceID, displayName string) (*types.Model, error)
	// GetModelByID gets a model by ID
	GetModelByID(ctx context.Context, id string) (*types.Model, error)
	// ListModels lists all models
	ListModels(ctx context.Context) ([]*types.Model, error)
	// UpdateModel updates a model
	UpdateModel(ctx context.Context, model *types.Model) error
	// DeleteModel deletes a model
	DeleteModel(ctx context.Context, id string) error

	// UpdateModelCredentials writes one or more credential fields on the
	// model's Parameters. Nil pointer means "do not touch this field";
	// empty string is treated as no-op (use ClearModelCredential to remove).
	// Returns the updated model.
	UpdateModelCredentials(ctx context.Context, id string, apiKey, appSecret *string) (*types.Model, error)
	// ClearModelCredential removes a single credential field. field must be
	// "api_key" or "app_secret". Clearing an already-empty field is a no-op.
	ClearModelCredential(ctx context.Context, id, field string) error
	// GetEmbeddingModel gets an embedding model
	GetEmbeddingModel(ctx context.Context, modelId string) (embedding.Embedder, error)
	// GetEmbeddingModelForTenant gets an embedding model for a specific tenant (for cross-tenant sharing)
	GetEmbeddingModelForTenant(ctx context.Context, modelId string, tenantID uint64) (embedding.Embedder, error)
	// GetRerankModel gets a rerank model
	GetRerankModel(ctx context.Context, modelId string) (rerank.Reranker, error)
	// GetChatModel gets a chat model
	GetChatModel(ctx context.Context, modelId string) (chat.Chat, error)
	// GetVLMModel gets a vision language model
	GetVLMModel(ctx context.Context, modelId string) (vlm.VLM, error)
	// GetASRModel gets an automatic speech recognition model
	GetASRModel(ctx context.Context, modelId string) (asr.ASR, error)
}

type OrganizationRepository interface {
	// Organization CRUD
	Create(ctx context.Context, org *types.Organization) error
	GetByID(ctx context.Context, id string) (*types.Organization, error)
	GetByInviteCode(ctx context.Context, inviteCode string) (*types.Organization, error)
	ListByTenantID(ctx context.Context, tenantID uint64) ([]*types.Organization, error)
	ListSearchable(ctx context.Context, query string, limit int) ([]*types.Organization, error)
	Update(ctx context.Context, org *types.Organization) error
	Delete(ctx context.Context, id string) error

	// Tenant member operations
	// AddTenantMember inserts the membership; a positive memberLimit is enforced
	// atomically with the insert.
	AddTenantMember(ctx context.Context, member *types.OrganizationTenantMember, memberLimit int) error
	RemoveTenantMember(ctx context.Context, orgID string, tenantID uint64) error
	UpdateTenantMemberRole(ctx context.Context, orgID string, tenantID uint64, role types.OrgMemberRole) error
	ListTenantMembers(ctx context.Context, orgID string) ([]*types.OrganizationTenantMember, error)
	GetTenantMember(ctx context.Context, orgID string, tenantID uint64) (*types.OrganizationTenantMember, error)
	ListTenantMembersByTenantForOrgs(ctx context.Context, tenantID uint64, orgIDs []string) (map[string]*types.OrganizationTenantMember, error)
	CountTenantMembers(ctx context.Context, orgID string) (int64, error)

	// Invite code
	UpdateInviteCode(ctx context.Context, orgID string, inviteCode string, expiresAt *time.Time) error

	// Join requests (still keyed on the *requesting* user, but a single
	// pending request per (org, tenant) since the approve action grants
	// the whole tenant access).
	CreateJoinRequest(ctx context.Context, request *types.OrganizationJoinRequest) error
	GetJoinRequestByID(ctx context.Context, id string) (*types.OrganizationJoinRequest, error)
	GetPendingJoinRequestByTenant(ctx context.Context, orgID string, tenantID uint64) (*types.OrganizationJoinRequest, error)
	GetPendingRequestByTenantAndType(ctx context.Context, orgID string, tenantID uint64, requestType types.JoinRequestType) (*types.OrganizationJoinRequest, error)
	ListJoinRequests(ctx context.Context, orgID string, status types.JoinRequestStatus) ([]*types.OrganizationJoinRequest, error)
	CountJoinRequests(ctx context.Context, orgID string, status types.JoinRequestStatus) (int64, error)
	UpdateJoinRequestStatus(ctx context.Context, id string, status types.JoinRequestStatus, reviewedBy string, reviewMessage string) error
}

type OrganizationService interface {
	// Organization CRUD
	CreateOrganization(ctx context.Context, userID string, tenantID uint64, req *types.CreateOrganizationRequest) (*types.Organization, error)
	GetOrganization(ctx context.Context, id string) (*types.Organization, error)
	GetOrganizationByInviteCode(ctx context.Context, inviteCode string) (*types.Organization, error)
	ListTenantOrganizations(ctx context.Context, tenantID uint64) ([]*types.Organization, error)
	UpdateOrganization(ctx context.Context, id string, userID string, tenantID uint64, req *types.UpdateOrganizationRequest) (*types.Organization, error)
	DeleteOrganization(ctx context.Context, id string, userID string, tenantID uint64) error

	// Member Management (Plan 3: members are tenants)
	// AddTenantMember adds a tenant to the org with the given role; representativeUserID
	// is only used for display labelling.
	AddTenantMember(ctx context.Context, orgID string, tenantID uint64, representativeUserID string, role types.OrgMemberRole) error
	RemoveTenantMember(ctx context.Context, orgID string, memberTenantID uint64, operatorUserID string, operatorTenantID uint64) error
	UpdateTenantMemberRole(ctx context.Context, orgID string, memberTenantID uint64, role types.OrgMemberRole, operatorUserID string, operatorTenantID uint64) error
	ListTenantMembers(ctx context.Context, orgID string) ([]*types.OrganizationTenantMember, error)
	GetTenantMember(ctx context.Context, orgID string, tenantID uint64) (*types.OrganizationTenantMember, error)

	// Invite Code
	GenerateInviteCode(ctx context.Context, orgID string, userID string, tenantID uint64) (string, error)
	JoinByInviteCode(ctx context.Context, inviteCode string, userID string, tenantID uint64) (*types.Organization, error)
	// Searchable organizations (discovery)
	SearchSearchableOrganizations(ctx context.Context, tenantID uint64, query string, limit int) (*types.ListSearchableOrganizationsResponse, error)
	JoinByOrganizationID(ctx context.Context, orgID string, userID string, tenantID uint64, message string, requestedRole types.OrgMemberRole) (*types.Organization, error)

	// Join Requests (for organizations that require approval)
	SubmitJoinRequest(ctx context.Context, orgID string, userID string, tenantID uint64, message string, requestedRole types.OrgMemberRole) (*types.OrganizationJoinRequest, error)
	ListJoinRequests(ctx context.Context, orgID string) ([]*types.OrganizationJoinRequest, error)
	CountPendingJoinRequests(ctx context.Context, orgID string) (int64, error)
	ReviewJoinRequest(ctx context.Context, orgID string, requestID string, approved bool, reviewerID string, reviewerTenantID uint64, message string, assignRole *types.OrgMemberRole) error

	// Role Upgrade Requests (for existing tenants to request higher permissions)
	RequestRoleUpgrade(ctx context.Context, orgID string, userID string, tenantID uint64, requestedRole types.OrgMemberRole, message string) (*types.OrganizationJoinRequest, error)
	GetPendingUpgradeRequest(ctx context.Context, orgID string, tenantID uint64) (*types.OrganizationJoinRequest, error)

	// Permission Check (drive purely off the requesting tenant)
	IsTenantOrgAdmin(ctx context.Context, orgID string, tenantID uint64) (bool, error)
	GetTenantRoleInOrg(ctx context.Context, orgID string, tenantID uint64) (types.OrgMemberRole, error)
}

type ResourceCatalog interface {
	Register(ctx context.Context, tenantID uint64, physicalPath string, meta ResourceRegistration) (string, error)
	Resolve(ctx context.Context, reference string) (*types.StoredResource, error)
	ResolvePath(ctx context.Context, value string) (string, *types.StoredResource, error)
	Bind(ctx context.Context, reference, ownerType, ownerID, relation string) error
	// Release drops one owner's claim on a resource and reports how many
	// claims remain. Callers use the count to decide whether the bytes may be
	// deleted: a resource still referenced by another owner — the assistant
	// message an answer was saved from, a second knowledge entry — must
	// survive the owner being removed.
	//
	// remaining is -1 when the answer is unknown (the reference is not a
	// catalog handle, or the count could not be read), which callers should
	// treat as "delete as before" rather than as "keep forever".
	Release(ctx context.Context, reference, ownerType, ownerID string) (remaining int64, err error)
	// ListReferencesByOwner returns derived resource:// handles still claimed
	// by any of the given owners (extracted images and markdown attachments).
	// Source files are omitted: reparse/cleanup must keep the original
	// document, which knowledge delete removes through FilePath.
	//
	// Knowledge-delete paths union this with ImageInfo URLs so markdown-only
	// images are released even when multimodal never wrote ImageInfo. Cleanup
	// before a re-index must not: it leaves the knowledge in place, and the
	// handles it released could not be re-bound once DeleteFile marked them
	// deleted.
	ListReferencesByOwner(ctx context.Context, ownerType string, ownerIDs ...string) ([]string, error)
	MarkDeleted(ctx context.Context, reference string) error
	CreateAccessGrant(ctx context.Context, reference string, ttl time.Duration) (string, error)
	ResolveAccessGrant(ctx context.Context, token string) (*types.StoredResource, error)
}

type ResourceCleaner interface {
	Register(cleanup types.CleanupFunc)
	RegisterWithName(name string, cleanup types.CleanupFunc)
	// Promote moves callbacks registered under name so Cleanup runs them
	// first. Cleanup's order is reverse registration order.
	Promote(name string)
	Cleanup(ctx context.Context) []error
}

type ResourceRegistration struct {
	Kind         string
	MimeType     string
	OriginalName string
	Size         int64
	ContentHash  string
	Temporary    bool
}

type ResourceRepository interface {
	Create(ctx context.Context, resource *types.StoredResource) error
	GetByID(ctx context.Context, id string) (*types.StoredResource, error)
	GetByHandle(ctx context.Context, handle string) (*types.StoredResource, error)
	GetByTenantLocation(ctx context.Context, tenantID uint64, locationHash string) (*types.StoredResource, error)
	MarkDeleted(ctx context.Context, id string) error
	CreateBinding(ctx context.Context, binding *types.ResourceBinding) error
	DeleteBinding(ctx context.Context, resourceID, ownerType, ownerID string) error
	CountBindings(ctx context.Context, resourceID string) (int64, error)
	ListHandlesByOwner(ctx context.Context, ownerType string, ownerIDs, relations []string) ([]string, error)
	IsReferencedByKnowledgeBase(
		ctx context.Context,
		tenantID uint64,
		kbID, resourceID string,
	) (bool, error)
	GetMessageFileBindings(
		ctx context.Context,
		tenantID uint64,
		resourceID, messageID string,
	) (*types.MessageFileBindings, error)
	CreateGrant(ctx context.Context, grant *types.ResourceAccessGrant) error
	GetValidGrant(ctx context.Context, tokenHash string, now time.Time) (*types.ResourceAccessGrant, error)
	DeleteExpiredGrants(ctx context.Context, before time.Time) error
}

type RetrievalContext struct {
	// Background is a compact description of the person, for query rewriting.
	Background string
	// Interests are the topics they keep returning to.
	Interests []string
	// Documents are titles they rely on, as vocabulary for the rewriter.
	Documents []string
	// Items are the memories behind the above, so the UI can show what
	// influenced retrieval instead of it happening invisibly.
	Items []*types.MemoryItem
}

type RetrieveEngine interface {
	// EngineType gets the retrieve engine type
	EngineType() types.RetrieverEngineType

	// Retrieve executes the retrieve
	Retrieve(ctx context.Context, params types.RetrieveParams) ([]*types.RetrieveResult, error)

	// Support gets the supported retrieve types
	Support() []types.RetrieverType
}

type RetrieveEngineRegistry interface {
	// Register registers the retrieve engine service
	Register(indexService RetrieveEngineService) error
	// GetRetrieveEngineService gets the retrieve engine service
	GetRetrieveEngineService(engineType types.RetrieverEngineType) (RetrieveEngineService, error)
	// GetAllRetrieveEngineServices gets all retrieve engine services
	GetAllRetrieveEngineServices() []RetrieveEngineService

	// GetByStoreID returns the engine service registered for a specific DB store ID.
	//
	// IMPORTANT: This method does NOT verify tenant ownership of the returned
	// store. Callers MUST use the CreateRetrieveEngineForKB /
	// CreateRetrieveEngineFromPayload factory functions in the retriever package
	// rather than calling this directly. The factories wrap GetByStoreID with
	// tenant ownership verification (defense-in-depth against cross-tenant IDOR).
	GetByStoreID(storeID string) (RetrieveEngineService, error)

	// GetOrLoadByStoreID returns the engine for storeID, rebuilding it from the
	// database when this process has no entry for it. The registry is per-process:
	// an engine registered on one instance is missing on every other until that
	// instance restarts, and an engine whose creation failed during startup stays
	// missing even across restarts. Rebuilding on demand lets both cases recover
	// without an operator-driven rollout.
	//
	// Unlike GetByStoreID, this method scopes its database lookup to tenantID, so
	// it cannot hydrate a store belonging to another tenant. Callers should still
	// verify ownership first: the tenant scope is defense-in-depth, not a
	// replacement for the ownership check.
	GetOrLoadByStoreID(
		ctx context.Context, tenantID uint64, storeID string,
	) (RetrieveEngineService, error)
}

type RetrieveEngineRepository interface {
	// Save saves the index info
	Save(ctx context.Context, indexInfo *types.IndexInfo, params map[string]any) error

	// BatchSave saves the index info list
	BatchSave(ctx context.Context, indexInfoList []*types.IndexInfo, params map[string]any) error

	// EstimateStorageSize estimates the storage size
	EstimateStorageSize(ctx context.Context, indexInfoList []*types.IndexInfo, params map[string]any) int64

	// DeleteByChunkIDList deletes the index info by chunk id list
	DeleteByChunkIDList(ctx context.Context, indexIDList []string, dimension int, knowledgeType string) error
	// DeleteBySourceIDList deletes the index info by source id list
	DeleteBySourceIDList(ctx context.Context, sourceIDList []string, dimension int, knowledgeType string) error
	// 复制索引数据
	// sourceKnowledgeBaseID: 源知识库ID
	// sourceToTargetChunkIDMap: 源分块ID到目标分块ID的映射关系
	// targetKnowledgeBaseID: 目标知识库ID
	// params: 额外参数，如向量表示等
	CopyIndices(
		ctx context.Context,
		sourceKnowledgeBaseID string,
		sourceToTargetKBIDMap map[string]string,
		sourceToTargetChunkIDMap map[string]string,
		targetKnowledgeBaseID string,
		dimension int,
		knowledgeType string,
	) error

	// DeleteByKnowledgeIDList deletes the index info by knowledge id list
	DeleteByKnowledgeIDList(ctx context.Context, knowledgeIDList []string, dimension int, knowledgeType string) error

	// BatchUpdateChunkEnabledStatus updates the enabled status of chunks in batch
	// chunkStatusMap: map of chunk ID to enabled status (true = enabled, false = disabled)
	BatchUpdateChunkEnabledStatus(ctx context.Context, chunkStatusMap map[string]bool) error

	// BatchUpdateChunkTagID updates the tag ID of chunks in batch
	// chunkTagMap: map of chunk ID to tag ID (empty string means no tag)
	BatchUpdateChunkTagID(ctx context.Context, chunkTagMap map[string]string) error

	// RetrieveEngine retrieves the engine
	RetrieveEngine
}

type RetrieveEngineService interface {
	// Index indexes the index info
	Index(ctx context.Context,
		embedder embedding.Embedder,
		indexInfo *types.IndexInfo,
		retrieverTypes []types.RetrieverType,
	) error

	// BatchIndex indexes the index info list
	BatchIndex(ctx context.Context,
		embedder embedding.Embedder,
		indexInfoList []*types.IndexInfo,
		retrieverTypes []types.RetrieverType,
	) error

	// EstimateStorageSize estimates the storage size
	EstimateStorageSize(ctx context.Context,
		embedder embedding.Embedder,
		indexInfoList []*types.IndexInfo,
		retrieverTypes []types.RetrieverType,
	) int64
	// CopyIndices 从源知识库复制索引到目标知识库，免去重新计算嵌入向量的开销
	// sourceKnowledgeBaseID: 源知识库ID
	// sourceToTargetChunkIDMap: 源分块ID到目标分块ID的映射关系，key为源分块ID，value为目标分块ID
	// targetKnowledgeBaseID: 目标知识库ID
	CopyIndices(
		ctx context.Context,
		sourceKnowledgeBaseID string,
		sourceToTargetKBIDMap map[string]string,
		sourceToTargetChunkIDMap map[string]string,
		targetKnowledgeBaseID string,
		dimension int,
		knowledgeType string,
	) error

	// DeleteByChunkIDList deletes the index info by chunk id list
	DeleteByChunkIDList(ctx context.Context, indexIDList []string, dimension int, knowledgeType string) error

	// DeleteBySourceIDList deletes the index info by source id list
	DeleteBySourceIDList(ctx context.Context, sourceIDList []string, dimension int, knowledgeType string) error

	// DeleteByKnowledgeIDList deletes the index info by knowledge id list
	DeleteByKnowledgeIDList(ctx context.Context, knowledgeIDList []string, dimension int, knowledgeType string) error

	// BatchUpdateChunkEnabledStatus updates the enabled status of chunks in batch
	// chunkStatusMap: map of chunk ID to enabled status (true = enabled, false = disabled)
	BatchUpdateChunkEnabledStatus(ctx context.Context, chunkStatusMap map[string]bool) error

	// BatchUpdateChunkTagID updates the tag ID of chunks in batch
	// chunkTagMap: map of chunk ID to tag ID (empty string means no tag)
	BatchUpdateChunkTagID(ctx context.Context, chunkTagMap map[string]string) error

	// RetrieveEngine retrieves the engine
	RetrieveEngine
}

type RetrieveGraphRepository interface {
	// AddGraph adds a graph to the repository
	AddGraph(ctx context.Context, namespace types.NameSpace, graphs []*types.GraphData) error
	// DelGraph deletes a graph from the repository
	DelGraph(ctx context.Context, namespace []types.NameSpace) error
	// SearchNode searches for nodes in the repository
	SearchNode(ctx context.Context, namespace types.NameSpace, nodes []string) (*types.GraphData, error)
}

type RuntimeTaskInspector interface {
	ListRuntimeTasks(
		ctx context.Context,
		queue string,
		state types.RuntimeTaskState,
		cursor string,
		pageSize int,
	) (page types.RuntimeTaskPage, supported bool, err error)
	GetRuntimeTask(ctx context.Context, queue, taskID string) (task *types.RuntimeTaskInfo, supported bool, err error)
	RunRuntimeTask(ctx context.Context, queue, taskID string) (supported bool, err error)
	DeleteRuntimeTask(ctx context.Context, queue, taskID string) (supported bool, err error)
	// ForceDeleteRuntimeTask removes a queue record without checking the
	// operator-facing AllowedActions. Used when the business row is already
	// gone but a retry/pending task survived (orphan cleanup).
	ForceDeleteRuntimeTask(ctx context.Context, queue, taskID string) (supported bool, err error)
	// PurgeArchivedRuntimeTasks removes every archived (finally-failed) task
	// from one queue in a single call and returns how many records were
	// deleted. It only ever touches the archived (dead-letter) set, so live
	// pending/active/scheduled/retry tasks are never affected. Business state
	// is intentionally left untouched: archived tasks have already had their
	// document status flipped to "failed" on their last retry, mirroring the
	// semantics of deleting archived records one by one.
	PurgeArchivedRuntimeTasks(ctx context.Context, queue string) (deleted int, supported bool, err error)
}

type SessionRepository interface {
	// Create creates a session
	Create(ctx context.Context, session *types.Session) (*types.Session, error)
	// Get gets a session visible to the tenant/user scope.
	Get(ctx context.Context, tenantID uint64, userID string, id string) (*types.Session, error)
	// GetByID loads a session by tenant and id without user scoping. Callers
	// must enforce access (e.g. embed channel + session signature).
	GetByID(ctx context.Context, tenantID uint64, id string) (*types.Session, error)
	// GetIMPlatform returns the IM platform bound to a session via
	// im_channel_sessions, or "" when the session has no IM mapping. Used to
	// classify a session's origin folder on read without a full list query.
	GetIMPlatform(ctx context.Context, tenantID uint64, sessionID string) (string, error)
	// GetByTenantID gets all sessions visible to the tenant/user scope.
	GetByTenantID(ctx context.Context, tenantID uint64, userID string) ([]*types.Session, error)
	// GetPagedByTenantID gets paged sessions visible to the tenant/user scope.
	GetPagedByTenantID(ctx context.Context, tenantID uint64, userID string, page *types.Pagination) ([]*types.Session, int64, error)
	// QueryPaged lists sessions with filters, user-scoped ownership and pin-aware ordering.
	QueryPaged(ctx context.Context, q *types.SessionListQuery) ([]*types.SessionListItem, int64, error)
	// Update updates a session visible to the tenant/user scope.
	Update(ctx context.Context, session *types.Session, userID string) (int64, error)
	// SetOwnerID assigns sessions.user_id for a tenant-scoped row.
	SetOwnerID(ctx context.Context, tenantID uint64, id, ownerID string) (int64, error)
	// UpdateLastRequestState persists the most recent input-bar state for a
	// session (agent, model, KB scope, etc.) so the chat UI can restore it
	// when the session is reopened. Scope rules match Update.
	UpdateLastRequestState(ctx context.Context, tenantID uint64, userID string, sessionID string, state *types.SessionLastRequestState) (int64, error)
	// SetPinned pins or unpins a session row scoped by tenant.
	// userID, when non-empty, is enforced so users cannot pin sessions they don't own.
	// Returns the number of rows affected; 0 means the session doesn't exist or is
	// not visible to this caller.
	SetPinned(ctx context.Context, tenantID uint64, userID string, id string, pinned bool) (int64, error)
	// Delete deletes a session visible to the tenant/user scope.
	Delete(ctx context.Context, tenantID uint64, userID string, id string) (int64, error)
	// BatchDelete deletes multiple sessions visible to the tenant/user scope.
	BatchDelete(ctx context.Context, tenantID uint64, userID string, ids []string) (int64, error)
	// DeleteAllByTenantID deletes all sessions visible to the tenant/user scope.
	DeleteAllByTenantID(ctx context.Context, tenantID uint64, userID string) (int64, error)
	// CreateForked persists a forked session and its copied history atomically.
	CreateForked(ctx context.Context, session *types.Session, messages []*types.Message) error
	// UpdateForkBootstrap overwrites a session's fork bootstrap. Passing nil clears it.
	UpdateForkBootstrap(ctx context.Context, sessionID string, b *types.ForkBootstrap) error
	// ListUnconsumedForks returns fork bootstraps the snapshot reaper should
	// try to retire: unopened forks older than olderThan, plus consumed forks
	// that still name a snapshot.
	ListUnconsumedForks(ctx context.Context, olderThan time.Time) ([]*types.Session, error)
	// HasOtherUnconsumedForkSnapshot reports whether another session still
	// needs snapshotID to boot. excludeSessionID is the row currently being
	// consumed or reaped.
	HasOtherUnconsumedForkSnapshot(ctx context.Context, snapshotID, excludeSessionID string) (bool, error)
	// UnconsumedForkSnapshotHolders returns session IDs that still need
	// snapshotID to provision. The reaper uses this to avoid deleting a
	// snapshot while a fork within retention still depends on it.
	UnconsumedForkSnapshotHolders(ctx context.Context, snapshotID string) ([]string, error)
	// CreateForkSnapshotLease records a provider snapshot ID before the forked
	// session row exists, so a crash or CreateForked failure cannot hide it
	// from the reaper.
	CreateForkSnapshotLease(ctx context.Context, lease *types.ForkSnapshotLease) error
	// DeleteForkSnapshotLease drops a lease after the session owns the
	// snapshot, or after the snapshot itself has been deleted.
	DeleteForkSnapshotLease(ctx context.Context, snapshotID string) error
	// ListStaleForkSnapshotLeases returns leases older than olderThan.
	ListStaleForkSnapshotLeases(ctx context.Context, olderThan time.Time) ([]*types.ForkSnapshotLease, error)
}

type SessionService interface {
	// CreateSession creates a session
	CreateSession(ctx context.Context, session *types.Session) (*types.Session, error)
	// GetSession gets a session, honoring the caller's per-user scope with an
	// Admin+ read fallback for tenant channel sessions (API / IM / embed).
	// Use only for read paths.
	GetSession(ctx context.Context, id string) (*types.Session, error)
	// GetOwnedSession gets a session strictly within the caller's owner scope
	// (no Admin+ API-key fallback). Write/mutation endpoints must use this so a
	// tenant admin cannot alter API-key sessions they can only read.
	GetOwnedSession(ctx context.Context, id string) (*types.Session, error)
	// GetSessionByID loads a session by tenant and id without user scoping.
	GetSessionByID(ctx context.Context, tenantID uint64, id string) (*types.Session, error)
	// SetSessionOwnerID assigns sessions.user_id for the given session row.
	SetSessionOwnerID(ctx context.Context, tenantID uint64, sessionID, ownerID string) error
	// GetSessionsByTenant gets all sessions of a tenant
	GetSessionsByTenant(ctx context.Context) ([]*types.Session, error)
	// GetPagedSessionsByTenant gets paged sessions of a tenant
	GetPagedSessionsByTenant(ctx context.Context, page *types.Pagination) (*types.PageResult, error)
	// UpdateSession updates a session
	UpdateSession(ctx context.Context, session *types.Session) error
	// UpdateSessionLastRequestState records the input-bar state used for the
	// most recent QA request on this session. Best-effort: callers should log
	// but not surface failures to the user.
	UpdateSessionLastRequestState(ctx context.Context, sessionID string, state *types.SessionLastRequestState) error
	// DeleteSession deletes a session
	DeleteSession(ctx context.Context, id string) error
	// BatchDeleteSessions deletes multiple sessions by IDs
	BatchDeleteSessions(ctx context.Context, ids []string) error
	// DeleteAllSessions deletes all sessions for the current tenant
	DeleteAllSessions(ctx context.Context) error
	// ListSessions returns a page of sessions for the current tenant/user with
	// search/source filters and pin-aware ordering. User scope is pulled from ctx.
	ListSessions(ctx context.Context, query *types.SessionListQuery) (*types.PageResult, error)
	// CountSessionsBySource returns the total for a source filter without the
	// Admin+ gate applied by ListSessions (for aggregate stats endpoints).
	CountSessionsBySource(ctx context.Context, query *types.SessionListQuery) (int64, error)
	// SetSessionPinned pins or unpins the session for the current user scope.
	// Returns the number of rows affected; 0 signals "not found" to the handler.
	SetSessionPinned(ctx context.Context, sessionID string, pinned bool) (int64, error)
	// GenerateTitle generates a title for the current conversation
	// modelID: optional model ID to use for title generation (if empty, uses first available KnowledgeQA model)
	GenerateTitle(ctx context.Context, session *types.Session, messages []types.Message, modelID string) (string, error)
	// GenerateTitleAsync generates a title for the session asynchronously
	// It emits an event when the title is generated
	// modelID: optional model ID to use for title generation (if empty, uses first available KnowledgeQA model)
	GenerateTitleAsync(ctx context.Context, session *types.Session, userQuery string, modelID string, eventBus *event.EventBus)
	// KnowledgeQA performs knowledge-based question answering.
	// Events are emitted through eventBus (references, answer chunks, completion).
	KnowledgeQA(ctx context.Context, req *types.QARequest, eventBus *event.EventBus) error
	// KnowledgeQAByEvent performs knowledge-based question answering by event
	KnowledgeQAByEvent(ctx context.Context, chatManage *types.ChatManage, eventList []types.EventType) error
	// SearchKnowledge performs knowledge-based search, without summarization
	// knowledgeBaseIDs: list of knowledge base IDs to search (supports multi-KB)
	// knowledgeIDs: list of specific knowledge (file) IDs to search
	// opts: caller overrides of the tenant retrieval config; nil keeps it
	SearchKnowledge(
		ctx context.Context,
		knowledgeBaseIDs []string,
		knowledgeIDs []string,
		tagScopes []types.TagScope,
		query string,
		opts *types.KnowledgeSearchOptions,
	) (*types.RetrievalResult, error)
	// AgentQA performs agent-based question answering with conversation history and streaming support.
	AgentQA(ctx context.Context, req *types.QARequest, eventBus *event.EventBus) error
}