domain

type AIModelInfo struct {
	ID         string `json:"id"`                   // Model identifier (e.g., "text-embedding-3-small")
	Name       string `json:"name"`                 // Display name
	Dimensions int    `json:"dimensions,omitempty"` // For embedding models only
}

type AIProvider string

type AIProviderInfo struct {
	ID              string        `json:"id"`                    // Provider identifier (matches AIProvider)
	Name            string        `json:"name"`                  // Display name
	Models          []AIModelInfo `json:"models"`                // Available models
	RequiresAPIKey  bool          `json:"requires_api_key"`      // Whether API key is needed
	RequiresBaseURL bool          `json:"requires_base_url"`     // Whether base URL is needed (e.g., Ollama)
	APIKeyURL       string        `json:"api_key_url,omitempty"` // URL to get API key
}

type AISettings struct {
	TeamID    string            `json:"team_id"`
	Embedding EmbeddingSettings `json:"embedding"`
	LLM       LLMSettings       `json:"llm"`
	UpdatedAt time.Time         `json:"updated_at"`
}

type AnalyticsPeriod struct {
	Start time.Time `json:"start"`
	End   time.Time `json:"end"`
}

type AuthContext struct {
	UserID    string `json:"user_id"`
	Email     string `json:"email"`
	Name      string `json:"name"`
	Role      Role   `json:"role"`
	TeamID    string `json:"team_id"`
	SessionID string `json:"session_id"`
}

type AuthMethod string

type AuthProvider struct {
	Type         ProviderType `json:"type"`
	Name         string       `json:"name"`         // Display name
	AuthURL      string       `json:"auth_url"`     // OAuth authorization URL
	TokenURL     string       `json:"token_url"`    // OAuth token URL
	Scopes       []string     `json:"scopes"`       // Required OAuth scopes
	ClientID     string       `json:"client_id"`    // OAuth client ID (public)
	ClientSecret string       `json:"-"`            // OAuth client secret (never serialize)
	RedirectURL  string       `json:"redirect_url"` // OAuth callback URL
}

type AuthorizationCode struct {
	Code          string    `json:"code"`
	ClientID      string    `json:"client_id"`
	UserID        string    `json:"user_id"`
	RedirectURI   string    `json:"redirect_uri"`
	Scopes        []string  `json:"scopes"`
	CodeChallenge string    `json:"code_challenge"` // PKCE S256 challenge
	Resource      string    `json:"resource"`       // RFC 8707 resource indicator (audience)
	ExpiresAt     time.Time `json:"expires_at"`     // 10 minutes
	Used          bool      `json:"used"`           // single-use flag
	CreatedAt     time.Time `json:"created_at"`
}

type AuthorizeRequest struct {
	ResponseType        string `json:"response_type"` // "code"
	ClientID            string `json:"client_id"`
	RedirectURI         string `json:"redirect_uri"`
	Scope               string `json:"scope"`                 // Space-delimited scopes
	State               string `json:"state,omitempty"`       // CSRF token
	CodeChallenge       string `json:"code_challenge"`        // PKCE challenge
	CodeChallengeMethod string `json:"code_challenge_method"` // "S256"
	Resource            string `json:"resource,omitempty"`    // RFC 8707 resource indicator
}

type AvailabilityFunc func(ctx context.Context, t CapabilityType) bool

type AvailabilityResolver interface {
	// IsAvailable returns true when the runtime can support this
	// capability now. Returning false for a capability that has been
	// registered is normal — it just means the backend isn't configured
	// or healthy at this moment.
	//
	// For an unknown capability type (one not registered) the resolver
	// SHOULD return false to surface the configuration mistake.
	IsAvailable(ctx context.Context, t CapabilityType) bool
}

type Caller struct {
	// Source identifies the entry point that constructed this Caller.
	Source CallerSource `json:"source"`

	// UserID is the authenticated user performing the request.
	// Empty string signals an unauthenticated or service-to-service call.
	UserID string `json:"user_id"`
}

type CallerSource string

type Capability struct {
	Type        CapabilityType   `json:"type"`
	DisplayName string           `json:"display_name"`
	Description string           `json:"description"`
	Phase       PipelinePhase    `json:"phase"`
	BackendID   string           `json:"backend_id,omitempty"`
	DependsOn   []CapabilityType `json:"depends_on,omitempty"`
	Grants      []CapabilityType `json:"grants,omitempty"`

	// Available means the runtime can support this capability (backends are
	// configured, services are healthy, etc.). Computed by the resolver.
	Available bool `json:"available"`

	// Enabled means the operator has turned this capability on. Reflects
	// per-team preference, falling back to the descriptor's DefaultEnabled.
	Enabled bool `json:"enabled"`
}

type CapabilityDescriptor struct {
	// Type is the unique string key. Must match the registry's view.
	Type CapabilityType `json:"type"`

	// DisplayName is the human-readable label rendered in the admin UI.
	DisplayName string `json:"display_name"`

	// Description is one-line guidance text rendered alongside the toggle.
	Description string `json:"description"`

	// Phase indicates whether this is an indexing or search capability.
	Phase PipelinePhase `json:"phase"`

	// BackendID is an optional tag identifying the implementation backend
	// (e.g. "opensearch", "pgvector", "llm"). Used purely for UX
	// (grouping, badges); the capability resolution path does not consult
	// it. Empty when the capability has no specific backend.
	BackendID string `json:"backend_id,omitempty"`

	// DependsOn lists other capability types that must be enabled and
	// available for this capability to function. The resolver cascades
	// disable: if any dependency is not active, this capability is
	// marked disabled.
	DependsOn []CapabilityType `json:"depends_on,omitempty"`

	// Grants lists capabilities that this capability enables. Reverse of
	// DependsOn — purely informational for the UI today.
	Grants []CapabilityType `json:"grants,omitempty"`

	// DefaultEnabled is the toggle's default value when no per-team
	// preference exists. The resolver uses this as the initial enabled
	// state before applying stored preferences.
	DefaultEnabled bool `json:"default_enabled"`
}

type CapabilityPreferences struct {
	TeamID    string                  `json:"team_id"`
	Toggles   map[CapabilityType]bool `json:"toggles"`
	UpdatedAt time.Time               `json:"updated_at"`
}

type CapabilityRegistry interface {
	// Register adds a descriptor to the registry. Returns an error when a
	// descriptor with the same Type is already registered — duplicate
	// registration is a programmer error and must surface, not silently
	// overwrite.
	Register(d CapabilityDescriptor) error

	// All returns every registered descriptor. The returned slice is a
	// copy; mutation does not affect the registry.
	All() []CapabilityDescriptor

	// Get returns the descriptor for the given type, or false if no
	// descriptor with that type is registered.
	Get(t CapabilityType) (CapabilityDescriptor, bool)
}

type CapabilityType string

type Change struct {
	Type        ChangeType                                `json:"type"`
	Document    *Document                                 `json:"document,omitempty"`   // For added/modified
	Content     string                                    `json:"content,omitempty"`    // Eager content; ignored when LoadContent is set
	LoadContent func(ctx context.Context) (string, error) `json:"-"`                    // Optional. When set, invoked once during processing to fetch content lazily.
	DeletedID   string                                    `json:"deleted_id,omitempty"` // For deleted
	ExternalID  string                                    `json:"external_id"`          // ID from source system
}

type ChangePasswordRequest struct {
	CurrentPassword string `json:"current_password"`
	NewPassword     string `json:"new_password"`
}

type ChangeType string

type ClientRegistrationRequest struct {
	Name                    string           `json:"client_name"`
	RedirectURIs            []string         `json:"redirect_uris"`
	GrantTypes              []OAuthGrantType `json:"grant_types,omitempty"`
	ResponseTypes           []string         `json:"response_types,omitempty"`
	Scopes                  ScopeList        `json:"scope,omitempty"` // Space-delimited string or array
	ApplicationType         string           `json:"application_type,omitempty"`
	TokenEndpointAuthMethod string           `json:"token_endpoint_auth_method,omitempty"`
}

type ClientRegistrationResponse struct {
	ClientID                string           `json:"client_id"`
	ClientSecret            string           `json:"client_secret,omitempty"` // Only returned once for confidential clients
	Name                    string           `json:"client_name"`
	RedirectURIs            []string         `json:"redirect_uris"`
	GrantTypes              []OAuthGrantType `json:"grant_types"`
	ResponseTypes           []string         `json:"response_types"`
	Scopes                  ScopeList        `json:"scope"`
	ApplicationType         string           `json:"application_type"`
	TokenEndpointAuthMethod string           `json:"token_endpoint_auth_method"`
	ClientIDIssuedAt        int64            `json:"client_id_issued_at"` // Unix timestamp
}

type CompletionRequest struct {
	// SystemPrompt sets the system-level instructions for the LLM
	SystemPrompt string `json:"system_prompt"`

	// UserPrompt is the user's input or query to the LLM
	UserPrompt string `json:"user_prompt"`

	// MaxTokens limits the length of the generated response
	// If 0, the LLM provider's default is used
	MaxTokens int `json:"max_tokens,omitempty"`

	// Temperature controls randomness in the response (0.0 to 2.0)
	// Lower values make output more focused and deterministic
	// Higher values make output more creative and random
	Temperature float64 `json:"temperature,omitempty"`

	// ResponseSchema is an optional JSON Schema that constrains the LLM output
	// to a specific structure. Used for structured data extraction.
	// The actual schema format depends on the LLM provider.
	ResponseSchema any `json:"response_schema,omitempty"`
}

type CompletionResponse struct {
	// Content is the generated text from the LLM
	Content string `json:"content"`

	// Usage tracks token consumption for this request
	Usage TokenUsage `json:"usage"`
}

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

type Connection struct {
	ID           string       `json:"id"`
	Name         string       `json:"name"`
	Platform     PlatformType `json:"platform"`      // NEW: authentication boundary
	ProviderType ProviderType `json:"provider_type"` // kept for backward compat
	AuthMethod   AuthMethod   `json:"auth_method"`

	// Secrets contains decrypted secret values (never persisted as-is)
	// This is populated when fetching from store, nil when listing
	Secrets *ConnectionSecrets `json:"-"`

	// OAuth metadata (non-secret, safe to expose)
	OAuthTokenType string     `json:"oauth_token_type,omitempty"`
	OAuthExpiry    *time.Time `json:"oauth_expiry,omitempty"`
	OAuthScopes    []string   `json:"oauth_scopes,omitempty"`

	// AccountID is the provider account identifier (email, username)
	// Used for display and uniqueness constraint
	AccountID string `json:"account_id,omitempty"`

	// TenantID identifies the organization-level identity scope this connection
	// is valid for (e.g. a directory tenant, customer ID, or org name depending
	// on the provider). Only set for AuthMethodAppOnly connections; empty for
	// delegated connections. The format is provider-defined.
	TenantID string `json:"tenant_id,omitempty"`

	// AppCredentialsRef is a reference into the secret store pointing to the
	// long-lived application credential (client secret or certificate) used for
	// AuthMethodAppOnly flows. It is an opaque identifier — the credential
	// itself is never stored on the Connection record.
	AppCredentialsRef string `json:"app_credentials_ref,omitempty"`

	CreatedAt  time.Time  `json:"created_at"`
	UpdatedAt  time.Time  `json:"updated_at"`
	LastUsedAt *time.Time `json:"last_used_at,omitempty"`
}

type ConnectionSecrets struct {
	// OAuth2 tokens
	AccessToken  string `json:"access_token,omitempty"`
	RefreshToken string `json:"refresh_token,omitempty"`

	// API Key (for api_key auth method)
	APIKey string `json:"api_key,omitempty"`

	// Service Account JSON (for service_account auth method, e.g., Google)
	ServiceAccountJSON string `json:"service_account_json,omitempty"`
}

type ConnectionSummary struct {
	ID                string       `json:"id"`
	Name              string       `json:"name"`
	Platform          PlatformType `json:"platform"` // NEW
	ProviderType      ProviderType `json:"provider_type"`
	AuthMethod        AuthMethod   `json:"auth_method"`
	AccountID         string       `json:"account_id,omitempty"`
	OAuthExpiry       *time.Time   `json:"oauth_expiry,omitempty"`
	TenantID          string       `json:"tenant_id,omitempty"`
	AppCredentialsRef string       `json:"app_credentials_ref,omitempty"`
	CreatedAt         time.Time    `json:"created_at"`
	LastUsedAt        *time.Time   `json:"last_used_at,omitempty"`
}

type Container struct {
	ID       string         `json:"id"`
	Name     string         `json:"name"`
	Type     string         `json:"type,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

type CredentialSummary struct {
	ID           string       `json:"id"`
	ProviderType ProviderType `json:"provider_type"`
	AuthMethod   AuthMethod   `json:"auth_method"`
	Name         string       `json:"name"`
	HasToken     bool         `json:"has_token"`
	TokenExpiry  *time.Time   `json:"token_expiry,omitempty"`
	CreatedAt    time.Time    `json:"created_at"`
}

type Credentials struct {
	ID           string       `json:"id"`
	ProviderType ProviderType `json:"provider_type"`
	AuthMethod   AuthMethod   `json:"auth_method"`
	Name         string       `json:"name"` // User-friendly name

	// OAuth2 fields
	AccessToken  string     `json:"-"` // Never serialize
	RefreshToken string     `json:"-"` // Never serialize
	TokenExpiry  *time.Time `json:"token_expiry,omitempty"`
	Scopes       []string   `json:"scopes,omitempty"`

	// API Key / PAT
	APIKey string `json:"-"` // Never serialize

	// Basic Auth
	Username string `json:"-"` // Never serialize
	Password string `json:"-"` // Never serialize

	// Service Account (e.g., Google)
	ServiceAccountJSON string `json:"-"` // Never serialize

	// Metadata
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
	CreatedBy string    `json:"created_by"` // User ID
}

type Document struct {
	ID         string            `json:"id"`
	SourceID   string            `json:"source_id"`
	ExternalID string            `json:"external_id"` // ID from the source system
	Path       string            `json:"path"`        // Path or URL in source
	Title      string            `json:"title"`
	MimeType   string            `json:"mime_type"`
	Metadata   map[string]string `json:"metadata"`
	CreatedAt  time.Time         `json:"created_at"`
	UpdatedAt  time.Time         `json:"updated_at"`
	IndexedAt  time.Time         `json:"indexed_at"`
}

type DocumentContent struct {
	DocumentID string            `json:"document_id"`
	SourceID   string            `json:"source_id"`
	Title      string            `json:"title"`
	Body       string            `json:"body"`
	Path       string            `json:"path"`
	MimeType   string            `json:"mime_type"`
	Metadata   map[string]string `json:"metadata"`
}

type DocumentIDFilter struct {
	Apply bool     `json:"apply"`
	IDs   []string `json:"ids"`
}

type EmbeddingConfig struct {
	Provider   AIProvider `json:"provider"`
	Model      string     `json:"model"`
	Dimensions int        `json:"dimensions"`
	BatchSize  int        `json:"batch_size"`
}

type EmbeddingSettings struct {
	Provider AIProvider `json:"provider"`
	Model    string     `json:"model"`
}

type Filters struct {
	MimeTypes  []string   `json:"mime_types,omitempty"`
	DateAfter  *time.Time `json:"date_after,omitempty"`
	DateBefore *time.Time `json:"date_before,omitempty"`
}

type JobDetail struct {
	// Task is the main task information
	Task *Task `json:"task"`

	// SourceName is the name of the source (if applicable)
	SourceName string `json:"source_name,omitempty"`

	// ExecutionLogs contains log entries for this job (future enhancement)
	ExecutionLogs []string `json:"execution_logs,omitempty"`

	// RetryHistory shows previous retry attempts
	RetryHistory []*RetryAttempt `json:"retry_history,omitempty"`
}

type JobHistory struct {
	// Jobs is the list of historical job executions
	Jobs []*Task `json:"jobs"`

	// TotalCount is the total number of jobs matching the query
	TotalCount int64 `json:"total_count"`

	// HasMore indicates if there are more jobs beyond the current page
	HasMore bool `json:"has_more"`
}

type JobStats struct {
	// Total jobs across all statuses
	TotalJobs int64 `json:"total_jobs"`

	// PendingJobs is the number of jobs waiting to be processed
	PendingJobs int64 `json:"pending_jobs"`

	// ProcessingJobs is the number of jobs currently being processed
	ProcessingJobs int64 `json:"processing_jobs"`

	// CompletedJobs is the number of successfully completed jobs
	CompletedJobs int64 `json:"completed_jobs"`

	// FailedJobs is the number of failed jobs
	FailedJobs int64 `json:"failed_jobs"`

	// SuccessRate is the percentage of successful jobs (0-100)
	SuccessRate float64 `json:"success_rate"`

	// AverageDuration is the average job duration in milliseconds
	AverageDuration float64 `json:"average_duration_ms"`

	// TotalRetries is the total number of retry attempts
	TotalRetries int64 `json:"total_retries"`

	// JobsByType shows the breakdown by task type
	JobsByType map[TaskType]int64 `json:"jobs_by_type"`

	// Period is the time range for these statistics
	Period AnalyticsPeriod `json:"period"`
}

type LLMSettings struct {
	Provider AIProvider `json:"provider"`
	Model    string     `json:"model"`
}

type LoginRequest struct {
	Email    string `json:"email"`
	Password string `json:"password"`
}

type LoginResponse struct {
	Token        string       `json:"token"`
	RefreshToken string       `json:"refresh_token,omitempty"`
	ExpiresAt    time.Time    `json:"expires_at"`
	User         *UserSummary `json:"user"`
}

type OAuthAccessToken struct {
	ID        string    `json:"id"` // jti claim
	ClientID  string    `json:"client_id"`
	UserID    string    `json:"user_id"`
	Scopes    []string  `json:"scopes"`
	Audience  string    `json:"audience"`   // Resource indicator (MCP server URL)
	ExpiresAt time.Time `json:"expires_at"` // Short-lived (15 min default)
	CreatedAt time.Time `json:"created_at"`
	Revoked   bool      `json:"revoked"`
}

type OAuthClient struct {
	ID                      string           `json:"id"`                         // client_id (UUID)
	SecretHash              string           `json:"-"`                          // bcrypt hash of client_secret (empty for public clients)
	Name                    string           `json:"name"`                       // Human-readable name
	RedirectURIs            []string         `json:"redirect_uris"`              // Registered redirect URIs
	GrantTypes              []OAuthGrantType `json:"grant_types"`                // Allowed grant types
	ResponseTypes           []string         `json:"response_types"`             // Allowed response types (e.g., "code")
	Scopes                  []string         `json:"scopes"`                     // Allowed scopes
	ApplicationType         string           `json:"application_type"`           // "native" or "web"
	TokenEndpointAuthMethod string           `json:"token_endpoint_auth_method"` // "client_secret_post" or "none" (public)
	Active                  bool             `json:"active"`                     // Whether the client is active
	CreatedAt               time.Time        `json:"created_at"`
	UpdatedAt               time.Time        `json:"updated_at"`
}

type OAuthGrantType string

type OAuthRefreshToken struct {
	ID            string    `json:"id"`
	AccessTokenID string    `json:"access_token_id"` // Associated access token
	ClientID      string    `json:"client_id"`
	UserID        string    `json:"user_id"`
	Scopes        []string  `json:"scopes"`
	Audience      string    `json:"audience"`
	ExpiresAt     time.Time `json:"expires_at"` // 30 days
	CreatedAt     time.Time `json:"created_at"`
	Revoked       bool      `json:"revoked"`
	RotatedTo     string    `json:"rotated_to"` // New token ID after rotation (empty if current)
}

type PasswordResetConfirm struct {
	Token       string `json:"token"`
	NewPassword string `json:"new_password"`
}

type PasswordResetRequest struct {
	Email string `json:"email"`
}

type PipelinePhase string

type PlatformType string

type ProviderConfig struct {
	ProviderType ProviderType

	// Decrypted secrets (never persisted as-is)
	Secrets *ProviderSecrets

	// Non-secret configuration (can override defaults)
	AuthURL     string   // OAuth authorization URL
	TokenURL    string   // OAuth token URL
	Scopes      []string // OAuth scopes
	RedirectURI string   // OAuth callback URL

	// Metadata
	Enabled   bool
	CreatedAt time.Time
	UpdatedAt time.Time
}

type ProviderConfigSummary struct {
	ProviderType ProviderType
	Enabled      bool
	HasSecrets   bool // true if secrets are configured
	CreatedAt    time.Time
	UpdatedAt    time.Time
}

type ProviderMetadata struct {
	Type        ProviderType
	DisplayName string
	Platform    PlatformType
	IconID      string
}

type ProviderSecrets struct {
	ClientID     string `json:"client_id,omitempty"`
	ClientSecret string `json:"client_secret,omitempty"`
	APIKey       string `json:"api_key,omitempty"` // For non-OAuth providers
}

type ProviderType string

type QueryFrequency struct {
	Query string `json:"query"`
	Count int64  `json:"count"`
}

type RefreshRequest struct {
	RefreshToken string `json:"refresh_token"`
}

type RetryAttempt struct {
	// Attempt is the attempt number (1-indexed)
	Attempt int `json:"attempt"`

	// Error is the error message from this attempt
	Error string `json:"error"`

	// Timestamp is when this attempt occurred
	Timestamp time.Time `json:"timestamp"`
}

type RevokeRequest struct {
	Token         string `json:"token"`
	TokenTypeHint string `json:"token_type_hint,omitempty"` // "access_token" or "refresh_token"
}

type Role string

type RuntimeConfig struct {

	// Static (set at startup, read-only)
	SessionBackend string // "redis" or "postgres"
	// contains filtered or unexported fields
}

type ScheduledTask struct {
	// ID is the unique identifier for this scheduled task
	ID string `json:"id"`

	// Name is a human-readable name for the task
	Name string `json:"name"`

	// Type is the task type to create when triggered
	Type TaskType `json:"type"`

	// TeamID is the team this schedule belongs to
	TeamID string `json:"team_id"`

	// Interval is how often to run the task
	Interval time.Duration `json:"interval"`

	// Enabled indicates if the schedule is active
	Enabled bool `json:"enabled"`

	// LastRun is when the task was last triggered
	LastRun *time.Time `json:"last_run,omitempty"`

	// NextRun is when the task should next be triggered
	NextRun time.Time `json:"next_run"`

	// LastError contains the last error if the scheduled task failed
	LastError string `json:"last_error,omitempty"`
}

type ScopeList []string

type SearchAnalytics struct {
	// TotalSearches is the total number of searches in the period
	TotalSearches int64 `json:"total_searches"`

	// UniqueUsers is the number of unique users who searched
	UniqueUsers int64 `json:"unique_users"`

	// AverageDuration is the average search duration in milliseconds
	AverageDuration float64 `json:"average_duration_ms"`

	// AverageResults is the average number of results per search
	AverageResults float64 `json:"average_results"`

	// TopQueries are the most common search queries
	TopQueries []QueryFrequency `json:"top_queries"`

	// SearchesByMode shows the breakdown by search mode
	SearchesByMode map[SearchMode]int64 `json:"searches_by_mode"`

	// Period is the time range for these analytics
	Period AnalyticsPeriod `json:"period"`
}

type SearchMetrics struct {
	// FastSearches is the number of searches under 100ms
	FastSearches int64 `json:"fast_searches"`

	// MediumSearches is the number of searches 100ms-500ms
	MediumSearches int64 `json:"medium_searches"`

	// SlowSearches is the number of searches over 500ms
	SlowSearches int64 `json:"slow_searches"`

	// P50Duration is the 50th percentile search duration in milliseconds
	P50Duration float64 `json:"p50_duration_ms"`

	// P95Duration is the 95th percentile search duration in milliseconds
	P95Duration float64 `json:"p95_duration_ms"`

	// P99Duration is the 99th percentile search duration in milliseconds
	P99Duration float64 `json:"p99_duration_ms"`

	// ZeroResultSearches is the number of searches that returned no results
	ZeroResultSearches int64 `json:"zero_result_searches"`

	// Period is the time range for these metrics
	Period AnalyticsPeriod `json:"period"`
}

type SearchMode string

type SearchOptions struct {
	Mode             SearchMode         `json:"mode"`
	Limit            int                `json:"limit"`
	Offset           int                `json:"offset"`
	SourceIDs        []string           `json:"source_ids,omitempty"`         // Filter by sources
	DocumentIDFilter *DocumentIDFilter  `json:"document_id_filter,omitempty"` // Three-case filter (see DocumentIDFilter godoc). Nil = no filter.
	Filters          Filters            `json:"filters,omitempty"`
	BoostTerms       map[string]float64 `json:"boost_terms,omitempty"` // term -> boost factor

	// Phrases lists user-quoted phrases extracted by the query parser. Each is
	// run as a match_phrase clause against title^3 and content alongside the
	// main query terms — without this the standard analyser drops the quotes
	// and a "merge sort" search collapses into two unrelated tokens.
	Phrases []string `json:"phrases,omitempty"`

	// PipelineID optionally selects a registered search pipeline by ID.
	// Empty string falls back to the default ("default-search"). Callers
	// can register additional pipelines via PipelineRegistry and route
	// per-request by setting this field.
	PipelineID string `json:"pipeline_id,omitempty"`

	// Caller identifies the entity making the search request. Nil means the
	// origin is unknown. Stages that gate on caller identity (e.g. sensitivity
	// masker) treat nil as non-MCP (skip execution). Populated by HTTP handlers
	// (CallerSourceDirect) and MCP handlers (CallerSourceMCP).
	Caller *Caller `json:"caller,omitempty"`
}

type SearchQuery struct {
	// ID is the unique identifier for this search query log entry
	ID string `json:"id"`

	// TeamID is the team that performed the search
	TeamID string `json:"team_id"`

	// UserID is the user who performed the search
	UserID string `json:"user_id"`

	// Query is the search text that was submitted
	Query string `json:"query"`

	// Mode is the search mode used (hybrid, text, semantic)
	Mode SearchMode `json:"mode"`

	// ResultCount is the number of results returned
	ResultCount int `json:"result_count"`

	// Duration is how long the search took to execute (in nanoseconds)
	Duration int64 `json:"duration"`

	// SourceIDs are the source IDs that were filtered (if any)
	SourceIDs []string `json:"source_ids,omitempty"`

	// Filters are the additional filters applied
	HasFilters bool `json:"has_filters"`

	// CreatedAt is when the search was performed
	CreatedAt time.Time `json:"created_at"`
}

type SearchResult struct {
	Query      string              `json:"query"`
	Mode       SearchMode          `json:"mode"`
	Results    []*SearchResultItem `json:"results"`
	TotalCount int                 `json:"total_count"`
	Took       time.Duration       `json:"took" swaggertype:"integer" example:"1500000"`
}

type SearchResultItem struct {
	DocumentID string    `json:"document_id"`
	SourceID   string    `json:"source_id"`
	Title      string    `json:"title"`
	Path       string    `json:"path"`
	MimeType   string    `json:"mime_type"`
	Snippet    string    `json:"snippet"`
	Score      float64   `json:"score"`
	IndexedAt  time.Time `json:"indexed_at"`

	// Metadata carries arbitrary key-value annotations produced by pipeline
	// stages and copied through from pipeline.PresentedResult.Metadata by the
	// search service.
	//
	// This mirrors the Metadata fields already present on pipeline.Candidate
	// and pipeline.PresentedResult: stages can attach derived information to a
	// result (faceting hints, ranking signals, query-expansion match info,
	// stage-specific outcome flags) and have it survive the projection from
	// the pipeline's internal types to the public domain type.
	//
	// Keys are convention-based and stage-specific; the search service does
	// not interpret them, it only forwards what the presenter exposes.
	// Driving adapters (HTTP handlers, MCP servers, downstream services) read
	// keys they care about and ignore the rest.
	//
	// Stages that do not need to attach metadata may leave this nil.
	Metadata map[string]any `json:"metadata,omitempty"`
}

type Session struct {
	ID           string    `json:"id"`
	UserID       string    `json:"user_id"`
	Token        string    `json:"token"`
	RefreshToken string    `json:"refresh_token,omitempty"`
	ExpiresAt    time.Time `json:"expires_at"`
	CreatedAt    time.Time `json:"created_at"`
	UserAgent    string    `json:"user_agent,omitempty"`
	IPAddress    string    `json:"ip_address,omitempty"`
}

type Settings struct {
	TeamID string `json:"team_id"`

	// Search Defaults
	DefaultSearchMode SearchMode `json:"default_search_mode"`
	ResultsPerPage    int        `json:"results_per_page"`
	MaxResultsPerPage int        `json:"max_results_per_page"`

	// Sync Configuration
	SyncIntervalMinutes int                    `json:"sync_interval_minutes"`
	SyncEnabled         bool                   `json:"sync_enabled"`
	SyncExclusions      *SyncExclusionSettings `json:"sync_exclusions,omitempty"`

	// Metadata
	UpdatedAt time.Time `json:"updated_at"`
	UpdatedBy string    `json:"updated_by"` // User ID
}

type Source struct {
	ID           string       `json:"id"`
	Name         string       `json:"name"`
	ProviderType ProviderType `json:"provider_type"`
	Config       SourceConfig `json:"config"`
	Enabled      bool         `json:"enabled"`
	CreatedAt    time.Time    `json:"created_at"`
	UpdatedAt    time.Time    `json:"updated_at"`
	CreatedBy    string       `json:"created_by"` // User ID of creator

	// ConnectionID references the connector connection for authentication
	ConnectionID string `json:"connection_id,omitempty"`

	// Containers lists the containers to index (typed)
	// Empty means index all accessible containers
	// Examples: repos for GitHub, channels for Slack, folders for Drive
	Containers []Container `json:"containers,omitempty"`
}

type SourceConfig struct {
	// Common fields
	CredentialID string `json:"credential_id,omitempty"`

	// GitHub/GitLab
	Owner      string   `json:"owner,omitempty"`
	Repository string   `json:"repository,omitempty"`
	Branch     string   `json:"branch,omitempty"`
	Paths      []string `json:"paths,omitempty"`

	// Slack
	Channels []string `json:"channels,omitempty"`

	// Notion
	DatabaseIDs []string `json:"database_ids,omitempty"`
	PageIDs     []string `json:"page_ids,omitempty"`

	// Confluence
	SpaceKeys []string `json:"space_keys,omitempty"`

	// Google Drive
	FolderIDs []string `json:"folder_ids,omitempty"`

	// Jira
	ProjectKeys []string `json:"project_keys,omitempty"`
	JQL         string   `json:"jql,omitempty"`

	// Generic
	BaseURL string            `json:"base_url,omitempty"`
	Extra   map[string]string `json:"extra,omitempty"`
}

type SourceSummary struct {
	Source        *Source    `json:"source"`
	DocumentCount int        `json:"document_count"`
	LastSyncAt    *time.Time `json:"last_sync_at,omitempty"`
	SyncStatus    string     `json:"sync_status"`
}

type SyncEvent struct {
	// ID is the unique identifier for this sync event log entry
	ID string `json:"id"`

	// TeamID is the team that owns the source being synced
	TeamID string `json:"team_id"`

	// SourceID is the source that was synced
	SourceID string `json:"source_id"`

	// SourceName is the display name of the source at sync time
	SourceName string `json:"source_name"`

	// ProviderType identifies the connector type (github, notion, etc.)
	ProviderType ProviderType `json:"provider_type"`

	// Status indicates if the sync completed successfully or failed
	Status SyncStatus `json:"status"`

	// DocumentsAdded is the number of new documents discovered
	DocumentsAdded int `json:"documents_added"`

	// DocumentsUpdated is the number of existing documents modified
	DocumentsUpdated int `json:"documents_updated"`

	// DocumentsDeleted is the number of documents removed
	DocumentsDeleted int `json:"documents_deleted"`

	// ChunksIndexed is the total number of chunks created/updated in the vector store
	ChunksIndexed int `json:"chunks_indexed"`

	// ErrorCount is the number of errors encountered during sync
	ErrorCount int `json:"error_count"`

	// ErrorMessage contains the primary error message if Status is failed
	ErrorMessage string `json:"error_message,omitempty"`

	// DurationSeconds is how long the sync operation took to execute
	DurationSeconds float64 `json:"duration_seconds"`

	// CreatedAt is when the sync event was logged
	CreatedAt time.Time `json:"created_at"`
}

type SyncExclusionSettings struct {
	// EnabledPatterns are the default patterns that are currently enabled
	EnabledPatterns []string `json:"enabled_patterns"`

	// DisabledPatterns are the default patterns that have been toggled off
	DisabledPatterns []string `json:"disabled_patterns"`

	// CustomPatterns are user-defined exclusion patterns
	CustomPatterns []string `json:"custom_patterns"`

	// MimeExclusions are MIME type patterns to exclude (e.g., "image/*", "font/*")
	MimeExclusions []string `json:"mime_exclusions"`
}

type SyncFailedDoc struct {
	// SourceID is the parent source — the (source_id, external_id) pair
	// is the primary key.
	SourceID string `json:"source_id"`

	// ExternalID is the connector's identifier for the doc that failed.
	// Not the Sercha-internal document_id: failures often happen before
	// any internal row gets created.
	ExternalID string `json:"external_id"`

	// AttemptCount is the number of times we've tried this doc since the
	// row was created. Drives backoff and the terminal cutoff.
	AttemptCount int `json:"attempt_count"`

	// LastError is the error message from the most recent attempt,
	// truncated by the store layer for storage hygiene.
	LastError string `json:"last_error"`

	// LastAttemptedAt is when the most recent attempt ran. Useful for
	// "stuck since X" presentations in admin UIs.
	LastAttemptedAt time.Time `json:"last_attempted_at"`

	// NextRetryAfter is the earliest time the orchestrator should retry
	// this doc. The retry pre-pass picks rows where
	// next_retry_after <= now() AND terminal = false.
	NextRetryAfter time.Time `json:"next_retry_after"`

	// Terminal is true once the row has exceeded the configured maximum
	// attempt count. Excluded from automatic retry; remains in the table
	// for operator visibility.
	Terminal bool `json:"terminal"`

	// CreatedAt is when the first failure for this (source_id,
	// external_id) was recorded.
	CreatedAt time.Time `json:"created_at"`
}

type SyncResult struct {
	SourceID string    `json:"source_id"`
	Success  bool      `json:"success"`
	Skipped  bool      `json:"skipped,omitempty"` // true when another sync was already in progress for this source
	Stats    SyncStats `json:"stats"`
	Error    string    `json:"error,omitempty"`
	Duration float64   `json:"duration_seconds"`
	Cursor   string    `json:"cursor,omitempty"`
}

type SyncState struct {
	SourceID    string     `json:"source_id"`
	Status      SyncStatus `json:"status"`
	LastSyncAt  *time.Time `json:"last_sync_at,omitempty"`
	NextSyncAt  *time.Time `json:"next_sync_at,omitempty"`
	Cursor      string     `json:"cursor,omitempty"` // Pagination cursor for incremental sync
	Stats       SyncStats  `json:"stats"`
	Error       string     `json:"error,omitempty"`
	StartedAt   *time.Time `json:"started_at,omitempty"`
	CompletedAt *time.Time `json:"completed_at,omitempty"`
}

type SyncStats struct {
	DocumentsAdded   int `json:"documents_added"`
	DocumentsUpdated int `json:"documents_updated"`
	DocumentsDeleted int `json:"documents_deleted"`
	ChunksIndexed    int `json:"chunks_indexed"`
	Errors           int `json:"errors"`
}

type SyncStatus string

type Task struct {
	// ID is the unique identifier for this task
	ID string `json:"id"`

	// Type identifies what kind of task this is
	Type TaskType `json:"type"`

	// TeamID is the team this task belongs to
	TeamID string `json:"team_id"`

	// Payload contains task-specific data
	// For sync_source: {"source_id": "src-123"}
	// For sync_container: {"source_id": "src-123", "container_id": "cnt-456"}
	// For sync_all: {} (empty)
	Payload map[string]string `json:"payload"`

	// Status is the current state of the task
	Status TaskStatus `json:"status"`

	// Priority determines processing order (higher = more urgent)
	// Default is 0, range is -100 to 100
	Priority int `json:"priority"`

	// Attempts is how many times this task has been attempted
	Attempts int `json:"attempts"`

	// MaxAttempts is the maximum retry count before giving up
	MaxAttempts int `json:"max_attempts"`

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

	// CreatedAt is when the task was enqueued
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt is when the task was last modified
	UpdatedAt time.Time `json:"updated_at"`

	// StartedAt is when processing began (nil if not started)
	StartedAt *time.Time `json:"started_at,omitempty"`

	// CompletedAt is when processing finished (nil if not complete)
	CompletedAt *time.Time `json:"completed_at,omitempty"`

	// ScheduledFor is when the task should be processed (for delayed tasks)
	ScheduledFor time.Time `json:"scheduled_for"`
}

type TaskResult struct {
	TaskID      string        `json:"task_id"`
	Success     bool          `json:"success"`
	Error       string        `json:"error,omitempty"`
	Duration    time.Duration `json:"duration"`
	ItemsCount  int           `json:"items_count,omitempty"`  // e.g., documents synced
	ErrorsCount int           `json:"errors_count,omitempty"` // e.g., documents failed
}

type TaskStatus string

type TaskTrigger string

type TaskType string

type Team struct {
	ID        string    `json:"id"`
	Name      string    `json:"name"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type TokenClaims struct {
	UserID    string `json:"user_id"`
	Email     string `json:"email"`
	Role      Role   `json:"role"`
	TeamID    string `json:"team_id"`
	SessionID string `json:"session_id"`
	IssuedAt  int64  `json:"iat"`
	ExpiresAt int64  `json:"exp"`
}

type TokenRequest struct {
	GrantType    OAuthGrantType `json:"grant_type"`
	Code         string         `json:"code,omitempty"`         // For authorization_code grant
	RedirectURI  string         `json:"redirect_uri,omitempty"` // For authorization_code grant
	ClientID     string         `json:"client_id"`
	ClientSecret string         `json:"client_secret,omitempty"` // For confidential clients
	CodeVerifier string         `json:"code_verifier,omitempty"` // PKCE verifier
	RefreshToken string         `json:"refresh_token,omitempty"` // For refresh_token grant
	Resource     string         `json:"resource,omitempty"`      // RFC 8707 resource indicator
}

type TokenResponse struct {
	AccessToken  string `json:"access_token"`
	TokenType    string `json:"token_type"`              // "Bearer"
	ExpiresIn    int64  `json:"expires_in"`              // Seconds until expiration
	RefreshToken string `json:"refresh_token,omitempty"` // Optional refresh token
	Scope        string `json:"scope,omitempty"`         // Space-delimited scopes
}

type TokenUsage struct {
	// PromptTokens is the number of tokens in the input prompt
	PromptTokens int `json:"prompt_tokens"`

	// CompletionTokens is the number of tokens in the generated response
	CompletionTokens int `json:"completion_tokens"`

	// TotalTokens is the sum of prompt and completion tokens
	TotalTokens int `json:"total_tokens"`
}

type UpcomingJobs struct {
	// PendingTasks are tasks ready to be processed now
	PendingTasks []*Task `json:"pending_tasks"`

	// ScheduledTasks are recurring task schedules
	ScheduledTasks []*ScheduledTask `json:"scheduled_tasks"`

	// NextScheduledRun is when the next scheduled task will run
	NextScheduledRun *time.Time `json:"next_scheduled_run,omitempty"`
}

type User struct {
	ID           string     `json:"id"`
	Email        string     `json:"email"`
	PasswordHash string     `json:"-"` // Never serialize
	Name         string     `json:"name"`
	Role         Role       `json:"role"`
	TeamID       string     `json:"team_id"`
	Active       bool       `json:"active"`
	CreatedAt    time.Time  `json:"created_at"`
	UpdatedAt    time.Time  `json:"updated_at"`
	LastLoginAt  *time.Time `json:"last_login_at,omitempty"`
}

type UserSummary struct {
	ID          string     `json:"id"`
	Email       string     `json:"email"`
	Name        string     `json:"name"`
	Role        Role       `json:"role"`
	Active      bool       `json:"active"`
	LastLoginAt *time.Time `json:"last_login_at,omitempty"`
}