serv

type AgentConfig = gjagent.Config

type AggregationInfo struct {
	Available   []string `json:"available"`
	Usage       string   `json:"usage"`
	Limitations []string `json:"limitations,omitempty"`
}

type AggregationsSyntax struct {
	Functions        []string `json:"functions"`
	Usage            string   `json:"usage"`
	HasuraCompatible string   `json:"hasura_compatible"`
	WithGroup        string   `json:"with_group"`
}

type AnalyticsDirectivesSyntax struct {
	Directives []string `json:"directives"`
	Usage      string   `json:"usage"`
	Arguments  string   `json:"arguments"`
	Rules      []string `json:"rules"`
	Dialects   string   `json:"dialects"`
}

type ApplyDatabaseSetupResult struct {
	Applied       bool              `json:"applied"`
	Success       bool              `json:"success"`
	Message       string            `json:"message"`
	DatabaseAlias string            `json:"database_alias,omitempty"`
	TableCount    int               `json:"table_count"`
	Tables        []string          `json:"tables,omitempty"`
	Verification  ApplyVerification `json:"verification"`
	Errors        []string          `json:"errors,omitempty"`
	Next          *NextGuidance     `json:"next,omitempty"`
}

type ApplyVerification struct {
	AuthStatus  string `json:"auth_status,omitempty"`
	ProbeStatus string `json:"probe_status_code,omitempty"`
	AuthError   string `json:"auth_error,omitempty"`
}

type Auth = auth.Auth

type AuthLogin struct {
	// Enable the built-in login flow
	Enabled bool `jsonschema:"title=Enable Built-in Login,default=false"`

	// TTL of issued local JWTs (default: 720h = 30 days)
	TokenTTL time.Duration `mapstructure:"token_ttl" jsonschema:"title=Issued Token TTL"`

	// Issuer value stamped onto every locally-minted JWT. Must match
	// `auth.jwt.issuer` if that is set.
	Issuer string `jsonschema:"title=JWT Issuer Claim"`

	// Audience value stamped onto every locally-minted JWT. Must match
	// `auth.jwt.audience` if that is set. Defaults to "graphjin-cli".
	Audience string `jsonschema:"title=JWT Audience Claim"`

	// AudienceGraphjin is a convenience shortcut: when true, the issued JWT's
	// `aud` claim is set to the canonical value "graphjin-cli". Saves having
	// to remember / type the magic string. Mutually exclusive with Audience.
	AudienceGraphjin bool `mapstructure:"audience_graphjin" jsonschema:"title=Use GraphJin Default Audience (graphjin-cli)"`

	// OIDC identity provider used to authenticate humans.
	OIDC AuthLoginOIDC `jsonschema:"title=OIDC Provider"`
}

type AuthLoginOIDC struct {
	// OIDC issuer URL — discovery happens at
	// <issuer_url>/.well-known/openid-configuration
	IssuerURL string `mapstructure:"issuer_url" jsonschema:"title=OIDC Issuer URL,example=https://accounts.google.com"`

	// Registered OAuth client ID / secret for this GraphJin deployment.
	ClientID     string `mapstructure:"client_id" jsonschema:"title=OAuth Client ID"`
	ClientSecret string `mapstructure:"client_secret" jsonschema:"title=OAuth Client Secret"`

	// Scopes requested. Defaults to ["openid","email","profile"].
	Scopes []string `jsonschema:"title=Requested Scopes"`

	// Optional post-authentication allow-lists. If both are empty, any verified
	// identity is accepted.
	AllowedEmails  []string `mapstructure:"allowed_emails" jsonschema:"title=Allowed Email Addresses"`
	AllowedDomains []string `mapstructure:"allowed_domains" jsonschema:"title=Allowed Email Domains"`
}

type CacheEntry struct {
	Data         []byte `json:"d"`
	Compressed   bool   `json:"c,omitempty"`
	OriginalSize int    `json:"o,omitempty"`
	FreshUntil   int64  `json:"f"`
	StaleUntil   int64  `json:"s"`
}

type CacheMetrics struct {
	Hits          atomic.Int64
	Misses        atomic.Int64
	Invalidations atomic.Int64
	BytesCached   atomic.Int64
	BytesSaved    atomic.Int64 // Compression savings
	Errors        atomic.Int64
	SWRRefreshes  atomic.Int64
}

type CachingConfig struct {
	// Disable response caching (caching is enabled by default)
	Disable bool `mapstructure:"disable" jsonschema:"title=Disable Caching,default=false"`

	// Default TTL for cached responses in seconds (hard TTL)
	TTL int `mapstructure:"ttl" jsonschema:"title=Cache TTL,default=3600"`

	// Soft TTL for stale-while-revalidate in seconds (0 = disabled)
	FreshTTL int `mapstructure:"fresh_ttl" jsonschema:"title=Fresh TTL for SWR,default=300"`

	// Tables to exclude from caching
	ExcludeTables []string `mapstructure:"exclude_tables" jsonschema:"title=Exclude Tables"`
}

type CatalogCapabilitiesResult struct {
	Capabilities []CatalogItem `json:"capabilities"`
}

type CatalogCardResult struct {
	Card    CatalogItem              `json:"card"`
	Details []core.CatalogCardDetail `json:"details,omitempty"`
	Edges   []core.CatalogEdge       `json:"edges,omitempty"`
	Next    *NextGuidance            `json:"next,omitempty"`
}

type CatalogEntrypointsResult struct {
	Entrypoints []CatalogItem `json:"entrypoints"`
}

type CatalogItem struct {
	ID               string  `json:"id"`
	Kind             string  `json:"kind"`
	Name             string  `json:"name,omitempty"`
	Title            string  `json:"title,omitempty"`
	Summary          string  `json:"summary,omitempty"`
	DatabaseName     string  `json:"database_name,omitempty"`
	SchemaName       string  `json:"schema_name,omitempty"`
	TableName        string  `json:"table_name,omitempty"`
	ColumnName       string  `json:"column_name,omitempty"`
	Source           string  `json:"source,omitempty"`
	RiskLevel        string  `json:"risk_level,omitempty"`
	Confidence       string  `json:"confidence,omitempty"`
	Sensitive        bool    `json:"sensitive,omitempty"`
	Sensitivity      string  `json:"sensitivity,omitempty"`
	EvidenceJSON     string  `json:"evidence_json,omitempty"`
	ExamplesJSON     string  `json:"examples_json,omitempty"`
	SuggestedNext    string  `json:"suggested_next_json,omitempty"`
	DetailRef        string  `json:"detail_ref,omitempty"`
	DetailsJSON      string  `json:"details_json,omitempty"`
	EdgesJSON        string  `json:"edges_json,omitempty"`
	QueryJSON        string  `json:"query_json,omitempty"`
	InputSchemaJSON  string  `json:"input_schema_json,omitempty"`
	OutputSchemaJSON string  `json:"output_schema_json,omitempty"`
	SafetyJSON       string  `json:"safety_json,omitempty"`
	Enabled          bool    `json:"enabled,omitempty"`
	CapabilityKind   string  `json:"capability_kind,omitempty"`
	GraphQLQuery     string  `json:"graphql_query,omitempty"`
	GraphQLMutation  string  `json:"graphql_mutation,omitempty"`
	CreatedAt        string  `json:"created_at,omitempty"`
	UpdatedAt        string  `json:"updated_at,omitempty"`
	Score            float64 `json:"score,omitempty"`
	SearchRank       float64 `json:"search_rank,omitempty"`

	// Match is carried internally from the service-owned catalog search into
	// the top-level explain map. It is deliberately omitted from each card so
	// explanations have one stable, non-duplicated response shape.
	Match core.CatalogMatch `json:"-"`
}

type CatalogOverviewResource struct {
	GeneratedAt     string                   `json:"generated_at"`
	Revision        string                   `json:"revision,omitempty"`
	SourceRevisions map[string]string        `json:"source_revisions,omitempty"`
	Guidance        []string                 `json:"guidance"`
	Entrypoints     []core.CatalogEntryPoint `json:"entrypoints"`
	Capabilities    []core.CatalogCapability `json:"capabilities"`
	Cards           []core.CatalogCard       `json:"cards"`
	CardLimitHint   string                   `json:"card_limit_hint"`
}

type CatalogQueryResult struct {
	GeneratedAt     string            `json:"generated_at"`
	Revision        string            `json:"revision,omitempty"`
	SourceRevisions map[string]string `json:"source_revisions,omitempty"`
	Count           int               `json:"count"`
	Limit           int               `json:"limit,omitempty"`
	Offset          int               `json:"offset,omitempty"`
	// Truncated is true when this page filled the limit and more matching items
	// likely exist. Page with offset (or narrow with search/where) until false.
	Truncated         bool                         `json:"truncated"`
	Cards             []CatalogItem                `json:"cards"`
	Matches           map[string]core.CatalogMatch `json:"matches,omitempty"`
	CapabilityProfile *MCPCapabilityProfile        `json:"capability_profile,omitempty"`
	Next              *NextGuidance                `json:"next,omitempty"`
}

type CatalogSearchConfig struct {
	Semantic SemanticCatalogSearchConfig `mapstructure:"semantic" jsonschema:"title=Semantic Catalog Search"`
}

type CodeSQLMutationDSL struct {
	ReadBeforeWrite string   `json:"read_before_write"`
	Preview         string   `json:"preview"`
	Apply           string   `json:"apply"`
	Locks           string   `json:"locks"`
	FileOps         []string `json:"file_ops"`
	Rules           []string `json:"rules"`
}

type ColumnConfigInput struct {
	Name       string `json:"name"`
	Type       string `json:"type,omitempty"`
	Primary    bool   `json:"primary,omitempty"`
	Array      bool   `json:"array,omitempty"`
	FullText   bool   `json:"full_text,omitempty"`
	ForeignKey string `json:"related_to,omitempty"`
}

type ColumnStats struct {
	NullFraction *float64 `json:"null_fraction,omitempty"`
	// Negative = fraction-of-rows (postgres pg_stats convention).
	DistinctCount    *float64    `json:"distinct_count,omitempty"`
	MostCommonValues []EnumValue `json:"most_common_values,omitempty"`
	HistogramBounds  []string    `json:"histogram_bounds,omitempty"`
}

type ColumnTypeInfo struct {
	Type           string   `json:"type"`
	ValidOperators []string `json:"valid_operators"`
}

type Config struct {
	// Configuration for the GraphJin compiler core
	Core `mapstructure:",squash" jsonschema:"title=Compiler Configuration"`

	// Configuration for the GraphJin Service
	Serv `mapstructure:",squash" jsonschema:"title=Service Configuration"`

	// Name of another config file in the same directory to inherit and
	// override (one level only; the inherited file cannot itself inherit).
	// Example: prod.yml sets `inherits: dev` to start from dev.yml values.
	Inherits string `mapstructure:"inherits" jsonschema:"title=Inherit From Config File"`
	// contains filtered or unexported fields
}

type ConfigUpdateRequest struct {
	Databases map[string]DatabaseConfigInput `json:"databases,omitempty"`
	Metadata  *core.MetadataConfig           `json:"metadata,omitempty"`
	Tables    []TableConfigInput             `json:"tables,omitempty"`
	Roles     []RoleConfigInput              `json:"roles,omitempty"`
	Blocklist []string                       `json:"blocklist,omitempty"`
	Functions []FunctionConfigInput          `json:"functions,omitempty"`
}

type ConfigUpdateResult struct {
	Success           bool          `json:"success"`
	Message           string        `json:"message"`
	Changes           []string      `json:"changes,omitempty"`
	Errors            []string      `json:"errors,omitempty"`
	Databases         []string      `json:"databases,omitempty"`
	Scope             string        `json:"scope,omitempty"`
	ReloadMode        string        `json:"reload_mode,omitempty"`
	ReloadStrategy    string        `json:"reload_strategy,omitempty"`
	ChangedSources    []string      `json:"changed_sources,omitempty"`
	ReloadFallback    bool          `json:"reload_fallback,omitempty"`
	Valid             bool          `json:"valid,omitempty"`
	Applied           bool          `json:"applied,omitempty"`
	Mode              string        `json:"mode,omitempty"`
	PreviewID         string        `json:"preview_id,omitempty"`
	ExpiresAt         string        `json:"expires_at,omitempty"`
	CatalogRevision   string        `json:"catalog_revision,omitempty"`
	ChangeSummaryJSON string        `json:"change_summary_json,omitempty"`
	FindingsJSON      string        `json:"findings_json,omitempty"`
	ErrorsJSON        string        `json:"errors_json,omitempty"`
	Next              *NextGuidance `json:"next,omitempty"`
}

type ConnectDisconnect struct {
	Connect    string `json:"connect"`
	Disconnect string `json:"disconnect"`
}

type ConnectionTestResult struct {
	Success       bool               `json:"success"`
	Candidate     DiscoveredDatabase `json:"candidate"`
	RecommendedDB string             `json:"recommended_dbname,omitempty"`
	Next          *NextGuidance      `json:"next,omitempty"`
}

type Core = core.Config

type CursorCache interface {
	// Set stores a cursor and returns a short numeric ID
	Set(ctx context.Context, cursor string) (uint64, error)

	// Get retrieves a cursor by its numeric ID
	Get(ctx context.Context, id uint64) (string, error)

	// Close releases resources
	Close() error
}

type DDLApplyResult struct {
	Success           bool     `json:"success"`
	OperationsApplied int      `json:"operations_applied"`
	TablesCreated     []string `json:"tables_created,omitempty"`
	ColumnsAdded      []string `json:"columns_added,omitempty"`
	Message           string   `json:"message"`
}

type DDLOperationInfo struct {
	Type        string `json:"type"`
	Table       string `json:"table"`
	Column      string `json:"column,omitempty"`
	SQL         string `json:"sql"`
	Destructive bool   `json:"destructive"`
}

type DDLPreviewResult struct {
	Operations []DDLOperationInfo `json:"operations"`
	Summary    DDLSummary         `json:"summary"`
}

type DDLSummary struct {
	Total          int `json:"total"`
	TablesToCreate int `json:"tables_to_create"`
	ColumnsToAdd   int `json:"columns_to_add"`
	IndexesToAdd   int `json:"indexes_to_add"`
	DestructiveOps int `json:"destructive_count"`
}

type DataQualityFlag struct {
	Table   string `json:"table"`
	Column  string `json:"column,omitempty"`
	Kind    string `json:"kind"`
	Message string `json:"message"`
}

type Database struct {
	ConnString string `mapstructure:"connection_string" jsonschema:"title=Connection String"`
	Type       string `` /* 152-byte string literal not displayed */
	Host       string `jsonschema:"title=Host"`
	Port       uint16 `jsonschema:"title=Port"`
	DBName     string `jsonschema:"title=Database Name"`
	User       string `jsonschema:"title=User"`
	Password   string `jsonschema:"title=Password"`
	Schema     string `jsonschema:"title=Postgres Schema"`

	// File path for SQLite databases
	Path string `jsonschema:"title=File Path (SQLite)"`

	// Size of database connection pool
	PoolSize int `mapstructure:"pool_size" jsonschema:"title=Connection Pool Size"`

	// Max number of active database connections allowed
	MaxConnections int `mapstructure:"max_connections" jsonschema:"title=Maximum Connections"`

	// Max time after which idle database connections are closed
	MaxConnIdleTime time.Duration `mapstructure:"max_connection_idle_time" jsonschema:"title=Connection Idel Time"`

	// Max time after which database connections are not reused
	MaxConnLifeTime time.Duration `mapstructure:"max_connection_life_time" jsonschema:"title=Connection Life Time"`

	// Database ping timeout is used for db health checking
	PingTimeout time.Duration `mapstructure:"ping_timeout" jsonschema:"title=Healthcheck Ping Timeout"`

	// Set up an secure TLS encrypted database connection
	EnableTLS bool `mapstructure:"enable_tls" jsonschema:"title=Enable TLS"`

	// Required for TLS. For example with Google Cloud SQL it's
	// <gcp-project-id>:<cloud-sql-instance>
	ServerName string `mapstructure:"server_name" jsonschema:"title=TLS Server Name"`

	// Required for TLS. Can be a file path or the contents of the PEM file
	ServerCert string `mapstructure:"server_cert" jsonschema:"title=Server Certificate"`

	// Required for TLS. Can be a file path or the contents of the PEM file
	ClientCert string `mapstructure:"client_cert" jsonschema:"title=Client Certificate"`

	// Required for TLS. Can be a file path or the contents of the pem file
	ClientKey string `mapstructure:"client_key" jsonschema:"title=Client Key"`

	// MSSQL: disable TLS encryption (default: true in go-mssqldb)
	Encrypt *bool `mapstructure:"encrypt" jsonschema:"title=MSSQL Encrypt"`

	// MSSQL: trust server certificate without validation
	TrustServerCertificate *bool `mapstructure:"trust_server_certificate" jsonschema:"title=MSSQL Trust Server Certificate"`

	// Snowflake key pair authentication (PKCS#8 PEM format).
	// Generate key: openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8
	PrivateKeyPath string `mapstructure:"private_key_path" jsonschema:"title=Private Key File Path (Snowflake)"`
	PrivateKeyPEM  string `mapstructure:"private_key_pem" jsonschema:"title=Private Key PEM (Snowflake)"`
	KeyPassphrase  string `mapstructure:"key_passphrase" jsonschema:"title=Key Passphrase (Snowflake)"`

	// Cassandra / Amazon Keyspaces consistency level (default LOCAL_QUORUM).
	Consistency string `mapstructure:"consistency" jsonschema:"title=Cassandra Consistency Level"`
}

type DatabaseConfigInput struct {
	Type        string `json:"type"`
	ConnString  string `json:"connection_string,omitempty"`
	Host        string `json:"host,omitempty"`
	Port        int    `json:"port,omitempty"`
	DBName      string `json:"dbname,omitempty"`
	User        string `json:"user,omitempty"`
	Password    string `json:"password,omitempty"`
	Path        string `json:"path,omitempty"`
	Schema      string `json:"schema,omitempty"`
	ReadOnly    bool   `json:"read_only,omitempty"`
	InferDBRefs *bool  `json:"infer_db_refs,omitempty"`
}

type DatabaseConnection struct {
	Name      string   `json:"name"`
	Type      string   `json:"type"`
	Host      string   `json:"host"`
	Databases []string `json:"databases"`
	Active    bool     `json:"active"`
	Error     string   `json:"error,omitempty"`
}

type DatabaseOverview struct {
	Database            string              `json:"database"`
	AnalyticsMode       bool                `json:"analytics_mode"`
	TotalTables         int                 `json:"total_tables"`
	TotalColumns        int                 `json:"total_columns"`
	ApproxRowTotal      int64               `json:"approx_row_total,omitempty"`
	Schemas             []SchemaStats       `json:"schemas,omitempty"`
	TopNamespacesByRows []NamespaceRollup   `json:"top_namespaces_by_rows,omitempty"`
	OverallDateRange    *DateRange          `json:"overall_date_range,omitempty"`
	Functions           []core.FunctionInfo `json:"functions,omitempty"`
}

type DateRange struct {
	Min string `json:"min,omitempty"`
	Max string `json:"max,omitempty"`
}

type DeleteConfigInput struct {
	Filters []string `json:"filters,omitempty"`
	Columns []string `json:"columns,omitempty"`
	Block   bool     `json:"block,omitempty"`
}

type DiscoverResult struct {
	Databases    []DiscoveredDatabase `json:"databases"`
	Summary      DiscoverSummary      `json:"summary"`
	DockerStatus string               `json:"docker_status"`
	Next         *NextGuidance        `json:"next,omitempty"`
}

type DiscoverSummary struct {
	TotalFound     int      `json:"total_found"`
	DatabaseTypes  []string `json:"database_types"`
	ScanDurationMs int64    `json:"scan_duration_ms"`
}

type DiscoverTarget struct {
	Type             string `json:"type,omitempty"`
	Host             string `json:"host"`
	Port             int    `json:"port,omitempty"`
	SourceLabel      string `json:"source_label,omitempty"`
	User             string `json:"user,omitempty"`
	Password         string `json:"password,omitempty"`
	DBName           string `json:"dbname,omitempty"`
	ConnectionString string `json:"connection_string,omitempty"`
}

type DiscoveredDatabase struct {
	Type          string         `json:"type"`
	Host          string         `json:"host,omitempty"`
	Port          int            `json:"port,omitempty"`
	FilePath      string         `json:"file_path,omitempty"`
	CandidateID   string         `json:"candidate_id,omitempty"`
	Rank          int            `json:"rank,omitempty"`
	Confidence    string         `json:"confidence,omitempty"`
	Reasons       []string       `json:"reasons,omitempty"`
	NextActions   []string       `json:"next_actions,omitempty"`
	ProbeStatus   string         `json:"probe_status_code,omitempty"`
	Source        string         `json:"source"`
	Status        string         `json:"status"`
	Databases     []string       `json:"databases,omitempty"`
	AuthStatus    string         `json:"auth_status,omitempty"`
	AuthUser      string         `json:"auth_user,omitempty"`
	AuthError     string         `json:"auth_error,omitempty"`
	DockerInfo    *DockerDBInfo  `json:"docker_info,omitempty"`
	ConfigSnippet map[string]any `json:"config_snippet"`
}

type DiscoveryCacheConfig struct {
	// Enabled starts GraphJin Service from validated filesystem generations and
	// moves schema refreshes onto the coordinated generation path.
	Enabled *bool `mapstructure:"enabled" jsonschema:"title=Enable Discovery Cache,default=true"`

	// Path stores immutable full schema snapshots, manifests, activation
	// receipts, and semantic indexes. Horizontal replicas must share this path.
	Path string `mapstructure:"path" jsonschema:"title=Discovery Cache Path,default=.graphjin/discovery"`

	// RefreshInterval controls background live-schema checks after startup.
	RefreshInterval time.Duration `mapstructure:"refresh_interval" jsonschema:"title=Discovery Refresh Interval,default=5m"`

	// StartupWait bounds cold follower and explicit refresh activation waits.
	StartupWait time.Duration `mapstructure:"startup_wait" jsonschema:"title=Discovery Startup Wait,default=2m"`

	// RetainGenerations is the number of activated generations kept when the
	// configured filesystem supports deletion.
	RetainGenerations int `mapstructure:"retain_generations" jsonschema:"title=Retained Discovery Generations,default=2"`
}

type DiscoveryCost struct {
	UsesLiveQueries bool   `json:"uses_live_queries"`
	Scope           string `json:"scope,omitempty"`
	Cache           string `json:"cache,omitempty"`
}

type DiscoveryFullPayload struct {
	Database         string             `json:"database"`
	Tables           []TableDetailEntry `json:"tables"`
	DatabaseOverview DatabaseOverview   `json:"database_overview"`
}

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

type DiscoveryPayload struct {
	Database         string            `json:"database"`
	Tables           []TableIndexEntry `json:"tables"`
	Insights         SchemaInsights    `json:"insights"`
	DatabaseOverview DatabaseOverview  `json:"database_overview"`
}

type DiscoverySubscription struct {
	Result chan *DiscoveryPayload
	// contains filtered or unexported fields
}

type DockerDBInfo struct {
	ContainerID   string `json:"container_id"`
	ContainerName string `json:"container_name"`
	Image         string `json:"image"`
	Ports         string `json:"ports"`
}

type DuplicateFlag struct {
	Table          string   `json:"table"`
	Schemas        []string `json:"schemas"`
	FKSchema       string   `json:"fk_schema,omitempty"`
	Recommendation string   `json:"recommendation,omitempty"`
}

type EnhancedError struct {
	Message     string `json:"message"`
	Suggestion  string `json:"suggestion,omitempty"`
	RelatedTool string `json:"related_tool,omitempty"`
	// Kind, Table, Column are populated by enhanceExecError when the
	// error came from SQL execution and the dialect was identifiable.
	// Consumers can switch on Kind without parsing the prose.
	Kind   string `json:"kind,omitempty"`
	Table  string `json:"table,omitempty"`
	Column string `json:"column,omitempty"`
	// Hint carries a structured rewrite when the schema cross-check
	// detects that the error is misleading (e.g. column actually exists
	// on the table but was dropped by a CTE projection).
	Hint string `json:"hint,omitempty"`
}

type EnumProfile struct {
	Values        []EnumValue `json:"values,omitempty"`
	DistinctCount int64       `json:"distinct_count"`
	Truncated     bool        `json:"truncated,omitempty"`
}

type EnumValue struct {
	Value string `json:"value"`
	Count int64  `json:"count"`
}

type ErrorInfo struct {
	Message    string         `json:"message"`
	Extensions map[string]any `json:"extensions,omitempty"`
}

type ExampleQuery struct {
	Description string `json:"description"`
	Query       string `json:"query"`
}

type ExecErrorClass struct {
	Kind   string
	Table  string
	Column string
}

type ExecuteResult struct {
	Data   json.RawMessage `json:"data"`
	Errors []ErrorInfo     `json:"errors,omitempty"`
	// Truncation marks result lists that reached their compiled row limit —
	// pages, not populations. Callers must not aggregate over them.
	Truncation *gjagent.TruncationInfo `json:"truncation,omitempty"`
}

type FKDisambiguationCandidate struct {
	Column  string `json:"column"`
	Snippet string `json:"snippet"`
}

type FKDisambiguationEntry struct {
	Target     string                      `json:"target"`
	Ambiguous  bool                        `json:"ambiguous"`
	Candidates []FKDisambiguationCandidate `json:"candidates"`
	SyntaxHint string                      `json:"syntax_hint"`
}

type FilterOperators struct {
	Comparison []string `json:"comparison"`
	List       []string `json:"list"`
	Null       []string `json:"null"`
	Text       []string `json:"text"`
	JSON       []string `json:"json"`
	Spatial    []string `json:"spatial"`
}

type FixQueryErrorResult struct {
	Title         string   `json:"title"`
	GuideMarkdown string   `json:"guide_markdown"`
	Kind          string   `json:"kind"`
	Diagnosis     string   `json:"diagnosis"`
	RepairedQuery string   `json:"repaired_query,omitempty"`
	FollowUpTools []string `json:"follow_up_tools,omitempty"`
}

type ForeignKeyRef struct {
	Column   string `json:"column"`
	Target   string `json:"target"`
	Database string `json:"database,omitempty"`
}

type FunctionConfigInput struct {
	Name       string `json:"name"`
	Schema     string `json:"schema,omitempty"`
	ReturnType string `json:"return_type"`
}

type GraphQLHelpResult struct {
	For                   string                `json:"for"`
	Summary               string                `json:"summary"`
	Bootstrap             []string              `json:"bootstrap,omitempty"`
	TopicRoutes           []HelpRoute           `json:"topic_routes,omitempty"`
	ReplacesTools         []ToolReplaces        `json:"replaces_tools,omitempty"`
	RecommendedFirstQuery string                `json:"recommended_first_query"`
	GraphQLQuery          string                `json:"graphql_query"`
	GraphQLVariables      map[string]any        `json:"graphql_variables"`
	CatalogRows           []CatalogItem         `json:"catalog_rows"`
	Examples              []string              `json:"examples,omitempty"`
	Safety                map[string]any        `json:"safety,omitempty"`
	CapabilityProfile     *MCPCapabilityProfile `json:"capability_profile,omitempty"`
	Next                  *NextGuidance         `json:"next,omitempty"`
}

type HealthResult struct {
	Status       string         `json:"status"`
	DatabaseType string         `json:"database_type,omitempty"`
	PingLatency  string         `json:"ping_latency,omitempty"`
	SchemaReady  bool           `json:"schema_ready"`
	TableCount   int            `json:"table_count"`
	PoolStats    *PoolStatsInfo `json:"pool_stats,omitempty"`
	Error        string         `json:"error,omitempty"`
}

type HelpRoute struct {
	Need        string `json:"need"`
	For         string `json:"for"`
	FirstCall   string `json:"first_call"`
	DetailQuery string `json:"detail_query"`
}

type HookFn func(*core.Result)

type HttpService struct {
	atomic.Value
	// contains filtered or unexported fields
}

type HubTable struct {
	Name    string `json:"name"`
	FKCount int    `json:"fk_count"`
}

type IndexInfo struct {
	Name    string   `json:"name"`
	Columns []string `json:"columns"`
	Unique  bool     `json:"unique,omitempty"`
	Primary bool     `json:"primary,omitempty"`
	Type    string   `json:"type,omitempty"`
}

type InsertConfigInput struct {
	Filters []string          `json:"filters,omitempty"`
	Columns []string          `json:"columns,omitempty"`
	Presets map[string]string `json:"presets,omitempty"`
	Block   bool              `json:"block,omitempty"`
}

type JSRuntimeAPI struct {
	Runtime         string              `json:"runtime"`
	RuntimeStatus   string              `json:"runtime_status"`
	EntryPoint      string              `json:"entry_point"`
	WorkflowTimeout int                 `json:"workflow_timeout_seconds"`
	Globals         []JSRuntimeGlobal   `json:"globals"`
	Functions       []JSRuntimeFunction `json:"functions"`
	Notes           []string            `json:"notes,omitempty"`
}

type JSRuntimeFunction struct {
	Name        string         `json:"name"`
	Tool        string         `json:"tool,omitempty"`
	Description string         `json:"description,omitempty"`
	Arguments   map[string]any `json:"arguments,omitempty"`
	Required    []string       `json:"required,omitempty"`
}

type JSRuntimeGlobal struct {
	Name        string `json:"name"`
	Type        string `json:"type"`
	Description string `json:"description"`
}

type JWTConfig = auth.JWTConfig

type KeystoreConfig struct {
	Key  string `mapstructure:"key" jsonschema:"title=Keystore Key" jsonschema_extras:"x-graphjin-sensitive=secret"`
	Path string `mapstructure:"path" jsonschema:"title=Keystore Path"`
}

type ListDatabasesResult struct {
	Connections    []DatabaseConnection `json:"connections"`
	TotalDatabases int                  `json:"total_databases"`
}

type ListNamespacesResult struct {
	Database   string            `json:"database,omitempty"`
	Namespaces []NamespaceRollup `json:"namespaces"`
	Count      int               `json:"count"`
}

type ListTablesResult struct {
	Database        string            `json:"database,omitempty"`
	Databases       []string          `json:"databases,omitempty"`
	Schema          string            `json:"schema,omitempty"`
	Tables          []TableIndexEntry `json:"tables"`
	Count           int               `json:"count"`
	Total           int               `json:"total"`
	TopTablesByRows []TableRef        `json:"top_tables_by_rows,omitempty"`
	NextCursor      string            `json:"next_cursor,omitempty"`
	HasMore         bool              `json:"has_more,omitempty"`
}

type MCPCLIResource struct {
	Command string
	URI     string
	Short   string
}

type MCPCapabilityProfile struct {
	Mode                  string                 `json:"mode,omitempty"`
	SourcesMode           bool                   `json:"sources_mode"`
	RoleClass             string                 `json:"role_class"`
	Authenticated         bool                   `json:"authenticated"`
	CatalogRevision       string                 `json:"catalog_revision,omitempty"`
	AvailableTools        []string               `json:"available_tools,omitempty"`
	AllowedActions        []string               `json:"allowed_actions,omitempty"`
	AvailableRoots        []MCPRootProfile       `json:"available_roots,omitempty"`
	BlockedRoots          []MCPRootProfile       `json:"blocked_roots,omitempty"`
	VisibleCapabilities   []MCPCatalogCapability `json:"visible_capabilities,omitempty"`
	RecommendedEntrypoint string                 `json:"recommended_entrypoint,omitempty"`
	SafetyNotes           []string               `json:"safety_notes,omitempty"`
}

type MCPCatalogCapability struct {
	ID             string `json:"id"`
	Kind           string `json:"kind"`
	Name           string `json:"name,omitempty"`
	Summary        string `json:"summary,omitempty"`
	Enabled        bool   `json:"enabled,omitempty"`
	CapabilityKind string `json:"capability_kind,omitempty"`
}

type MCPConfig struct {
	// Disable the MCP server. MCP is enabled by default except for legacy
	// database-only prod/agentic configs, where it must be explicitly enabled.
	Disable bool `mapstructure:"disable" jsonschema:"title=Disable MCP Server,default=false"`

	// OAuth exposes standards-compatible authorization discovery for remote MCP clients.
	OAuth MCPOAuthConfig `mapstructure:"oauth" jsonschema:"title=MCP OAuth Configuration"`

	// Allow mutation operations via raw MCP GraphQL execution.
	// Auto-enabled in dev mode. Default: false
	AllowMutations bool `mapstructure:"allow_mutations" jsonschema:"title=Allow Mutations,default=false"`

	// Allow arbitrary GraphQL queries (vs only saved queries from allow-list)
	// Auto-enabled in dev mode. Default: false
	AllowRawQueries bool `mapstructure:"allow_raw_queries" jsonschema:"title=Allow Raw Queries,default=false"`

	// IncludeToolsWithAgent keeps the low-level MCP tools (query_catalog,
	// graphql_help, execute_saved_query, execute_graphql, validate_where_clause,
	// schema tools) registered even when the ask_graphjin_agent tool is enabled.
	// Dev and agentic configs expose both the agent and primitives by default.
	// Set false to make the agent the only front-door tool.
	IncludeToolsWithAgent bool `` /* 187-byte string literal not displayed */

	// LegacyDiscovery keeps legacy HTTP helper endpoints such as
	// /api/v1/discovery and /api/v1/workflows available for compatibility.
	// It no longer expands the MCP tool surface; MCP is catalog-first.
	LegacyDiscovery bool `mapstructure:"legacy_discovery" jsonschema:"title=Enable Legacy Discovery Tools,default=false"`

	// Default user ID for stdio transport (CLI). Can be overridden by GRAPHJIN_USER_ID env var.
	StdioUserID string `mapstructure:"stdio_user_id" jsonschema:"title=Stdio User ID"`

	// Default user role for stdio transport (CLI). Can be overridden by GRAPHJIN_USER_ROLE env var.
	StdioUserRole string `mapstructure:"stdio_user_role" jsonschema:"title=Stdio User Role"`

	// Run in MCP-only mode - disables GraphQL, REST saved-query API, WebUI, and OpenAPI endpoints.
	// Health check and MCP endpoints remain available. Legacy HTTP helper endpoints
	// also remain available only when legacy_discovery is enabled.
	Only bool `mapstructure:"only" jsonschema:"title=MCP Only Mode,default=false"`

	// CursorCacheTTL in seconds for cursor ID cache (default: 1800 = 30 min)
	// Cursors are cached to allow short numeric IDs for LLM-friendly pagination
	CursorCacheTTL int `mapstructure:"cursor_cache_ttl" jsonschema:"title=Cursor Cache TTL,default=1800"`

	// CursorCacheSize max entries for in-memory cursor cache fallback (default: 10000)
	CursorCacheSize int `mapstructure:"cursor_cache_size" jsonschema:"title=Cursor Cache Size,default=10000"`

	// AllowConfigUpdates enables MCP tools that can modify GraphJin configuration
	// WARNING: Allows LLMs to change database connections, table configs, and roles
	// Only enable in trusted environments. Default: false
	AllowConfigUpdates bool `mapstructure:"allow_config_updates" jsonschema:"title=Allow Config Updates,default=false"`

	// AllowSchemaReload enables the MCP reload_schema tool for manual schema refresh
	// Useful when user adds tables and wants immediate discovery without waiting for poll
	// Default: false (auto-enabled in dev mode if not explicitly set)
	AllowSchemaReload bool `mapstructure:"allow_schema_reload" jsonschema:"title=Allow Schema Reload,default=false"`

	// AllowSchemaUpdates enables MCP tools to preview and apply database schema changes (DDL)
	// Uses GraphJin DDL (db.ddl) format. Auto-enabled in dev mode. Default: false
	AllowSchemaUpdates bool `mapstructure:"allow_schema_updates" jsonschema:"title=Allow Schema Updates,default=false"`

	// AllowWorkflowUpdates enables workflow writes through gj_workflow.
	// Saved workflows are discoverable via workflow catalog items. Execution
	// through gj_workflow_execution is controlled by normal read_only table/source
	// configuration because it is an insert-shaped managed mutation.
	// Auto-enabled in dev mode. Default: false
	AllowWorkflowUpdates bool `mapstructure:"allow_workflow_updates" jsonschema:"title=Allow Workflow Updates,default=false"`

	// AllowWorkflowExecution keeps the legacy HTTP workflow execution surface
	// available when legacy discovery is enabled. MCP workflow execution uses
	// catalog discovery plus gj_workflow_execution.
	// Auto-enabled in dev mode. Default: false
	AllowWorkflowExecution bool `mapstructure:"allow_workflow_execution" jsonschema:"title=Allow Workflow Execution,default=false"`

	// AllowDevTools enables advanced introspection MCP tools (explain_query, explore_relationships, audit_role_permissions).
	// These expose SQL, relationship graphs, and role permissions — useful for development/debugging.
	// Auto-enabled in dev mode. Default: false
	AllowDevTools bool `mapstructure:"allow_dev_tools" jsonschema:"title=Allow Dev Tools,default=false"`

	// DefaultDBAllowed when true allows configuring and discovering system/default
	// databases (e.g. postgres, mysql, master). Default: false
	DefaultDBAllowed bool `mapstructure:"default_db_allowed" jsonschema:"title=Allow Default Databases,default=false"`

	// WorkflowTimeout in seconds for JavaScript workflow execution.
	// Workflows that exceed this duration are interrupted. Default: 5
	WorkflowTimeout int `mapstructure:"workflow_timeout" jsonschema:"title=Workflow Timeout (seconds),default=5"`
	// contains filtered or unexported fields
}

type MCPConfigResponse struct {
	ActiveDatabase string               `json:"active_database,omitempty"`
	Sources        any                  `json:"sources,omitempty"`
	System         core.SystemConfig    `json:"system,omitempty"`
	Workflows      core.WorkflowsConfig `json:"workflows,omitempty"`
	Databases      any                  `json:"databases,omitempty"`
	Relationships  any                  `json:"relationships,omitempty"`
	Metadata       core.MetadataConfig  `json:"metadata,omitempty"`
	Tables         any                  `json:"tables,omitempty"`
	Roles          any                  `json:"roles,omitempty"`
	Blocklist      []string             `json:"blocklist,omitempty"`
	Functions      any                  `json:"functions,omitempty"`
	Resolvers      any                  `json:"resolvers,omitempty"`
	MCP            MCPConfig            `json:"mcp,omitempty"`
}

type MCPOAuthConfig struct {
	// Enable OAuth metadata/challenge support for the MCP HTTP endpoint.
	Enabled bool `mapstructure:"enabled" jsonschema:"title=Enable MCP OAuth,default=false"`

	// Mode selects the authorization-server strategy: builtin uses auth_login
	// to run an authorization-code + PKCE flow; external advertises the
	// configured AuthorizationServers and validates bearer tokens via auth.jwt.
	Mode string `mapstructure:"mode" jsonschema:"title=MCP OAuth Mode,enum=builtin,enum=external"`

	// Resource is the expected OAuth audience/resource value. Defaults to the
	// public /api/v1/mcp URL for the incoming request.
	Resource string `mapstructure:"resource" jsonschema:"title=MCP OAuth Resource"`

	// Issuer is the authorization server issuer. In builtin mode it defaults to
	// the public origin of the incoming request.
	Issuer string `mapstructure:"issuer" jsonschema:"title=MCP OAuth Issuer"`

	// AuthorizationServers are advertised by protected-resource metadata in
	// external mode. Defaults to Issuer when empty.
	AuthorizationServers []string `mapstructure:"authorization_servers" jsonschema:"title=MCP OAuth Authorization Servers"`

	// Scopes advertised and accepted by the MCP authorization server.
	Scopes []string `mapstructure:"scopes" jsonschema:"title=MCP OAuth Scopes"`

	// DynamicClientRegistration exposes RFC 7591 registration in builtin mode.
	DynamicClientRegistration bool `mapstructure:"dynamic_client_registration" jsonschema:"title=Enable MCP OAuth Dynamic Client Registration,default=true"`

	// ClientIDMetadataDocuments lets clients use CIMD URLs instead of DCR.
	ClientIDMetadataDocuments bool `mapstructure:"client_id_metadata_documents" jsonschema:"title=Enable MCP OAuth Client ID Metadata Documents,default=true"`

	// AccessTokenTTL controls builtin-mode access token lifetime.
	AccessTokenTTL time.Duration `mapstructure:"access_token_ttl" jsonschema:"title=MCP OAuth Access Token TTL"`

	// RefreshTokenTTL controls builtin-mode refresh token lifetime.
	RefreshTokenTTL time.Duration `mapstructure:"refresh_token_ttl" jsonschema:"title=MCP OAuth Refresh Token TTL"`
}

type MCPRootProfile struct {
	Root       string `json:"root"`
	AccessMode string `json:"access_mode,omitempty"`
	Available  bool   `json:"available"`
	Reason     string `json:"reason,omitempty"`
}

type MCPToolEvent struct {
	SessionID  string
	Tool       string
	Arguments  map[string]any
	IsError    bool
	DurationMS int64
}

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

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

type MistakeExample struct {
	Wrong  string `json:"wrong"`
	Right  string `json:"right"`
	Reason string `json:"reason"`
}

type MutationOperations struct {
	Insert            string `json:"insert"`
	InsertConflictGet string `json:"insert_conflict_get"`
	BulkInsert        string `json:"bulk_insert"`
	Update            string `json:"update"`
	BulkUpdate        string `json:"bulk_update"`
	UpdateWhere       string `json:"update_where"`
	Upsert            string `json:"upsert"`
	Delete            string `json:"delete"`
	OpenAPICall       string `json:"openapi_call"`
}

type MutationSyntaxReference struct {
	AnalyticsModeRules []string           `json:"analytics_mode_rules,omitempty"`
	Operations         MutationOperations `json:"operations"`
	CodeSQL            CodeSQLMutationDSL `json:"codesql,omitempty"`
	NestedMutations    NestedMutationInfo `json:"nested_mutations"`
	ConnectDisconnect  ConnectDisconnect  `json:"connect_disconnect"`
	Returning          ReturningInfo      `json:"returning"`
	Validation         ValidationSyntax   `json:"validation"`
	CommonMistakes     []MistakeExample   `json:"common_mistakes"`
	Examples           []QueryExample     `json:"examples"`
}

type Mux interface {
	Handle(string, http.Handler)
	ServeHTTP(http.ResponseWriter, *http.Request)
}

type NamespaceRollup = corediscovery.NamespaceRollup

type NamespaceRoute struct {
	Database   string `json:"database"`
	TableCount int    `json:"table_count"`
	Default    bool   `json:"default,omitempty"`
}

type NestedMutationInfo struct {
	Description string `json:"description"`
	Example     string `json:"example"`
}

type NextGuidance struct {
	StateCode       string       `json:"state_code"`
	RecommendedTool string       `json:"recommended_tool,omitempty"`
	Options         []NextOption `json:"options,omitempty"`
}

type NextOption struct {
	Tool         string         `json:"tool"`
	Priority     int            `json:"priority"`
	Reason       string         `json:"reason,omitempty"`
	When         string         `json:"when,omitempty"`
	RequiredArgs []string       `json:"required_args,omitempty"`
	OptionalArgs []string       `json:"optional_args,omitempty"`
	ArgsTemplate map[string]any `json:"args_template,omitempty"`
}

type NumericStats struct {
	Min   string `json:"min,omitempty"`
	Max   string `json:"max,omitempty"`
	Avg   string `json:"avg,omitempty"`
	Sum   string `json:"sum,omitempty"`
	Count int64  `json:"count"`
}

type OnboardingStatusResult struct {
	ConfiguredDatabases []string      `json:"configured_databases"`
	ActiveDatabase      string        `json:"active_database,omitempty"`
	SchemaReady         bool          `json:"schema_ready"`
	TableCount          int           `json:"table_count"`
	Warnings            []string      `json:"warnings,omitempty"`
	Next                *NextGuidance `json:"next,omitempty"`
}

type OperatorSeed struct {
	UserID string
	// Role is the role seeded watches run under. Watch subscriptions execute
	// with the owner's stored role, so this is what decides what a standing
	// question can see — keep it least-privilege.
	Role string
	// ConsoleRole is the role the console adopts, when it differs from Role.
	// Reading the control-plane roots the console renders needs wider access
	// than running a watch does, so the two are allowed to diverge rather than
	// forcing watches to run with console-shaped privileges.
	ConsoleRole string
	AccountID   string
	Watches     []WatchSeed

	// Report receives one line per watch so the caller can render progress in
	// its own status stream. It is never called with an error the caller is
	// expected to handle: seeding is best-effort by design.
	Report func(name, status, message string)
}

type Option func(*graphjinService) error

type OrderingSyntax struct {
	Simple     string `json:"simple"`
	Multiple   string `json:"multiple"`
	Nested     string `json:"nested"`
	CustomList string `json:"custom_list"`
	NullsFirst string `json:"nulls_first"`
	NullsLast  string `json:"nulls_last"`
}

type PaginationSyntax struct {
	LimitOffset    string `json:"limit_offset"`
	ForwardCursor  string `json:"forward_cursor"`
	BackwardCursor string `json:"backward_cursor"`
	CursorField    string `json:"cursor_field"`
	Distinct       string `json:"distinct"`
}

type Payload struct {
	Data   json.RawMessage `json:"data,omitempty"`
	Errors []core.Error    `json:"errors,omitempty"`
}

type PoolStatsInfo struct {
	MaxOpenConnections int    `json:"max_open_connections"`
	OpenConnections    int    `json:"open_connections"`
	InUse              int    `json:"in_use"`
	Idle               int    `json:"idle"`
	WaitCount          int64  `json:"wait_count"`
	WaitDuration       string `json:"wait_duration"`
}

type QueryConfigInput struct {
	Limit            int      `json:"limit,omitempty"`
	Filters          []string `json:"filters,omitempty"`
	Columns          []string `json:"columns,omitempty"`
	DisableFunctions bool     `json:"disable_functions,omitempty"`
	Block            bool     `json:"block,omitempty"`
}

type QueryExample struct {
	Description string `json:"description"`
	Query       string `json:"query"`
	Variables   string `json:"variables,omitempty"`
}

type QueryExamplesForSyntax struct {
	Basic         []QueryExample `json:"basic"`
	Filtering     []QueryExample `json:"filtering"`
	Relationships []QueryExample `json:"relationships"`
	Pagination    []QueryExample `json:"pagination"`
	Aggregations  []QueryExample `json:"aggregations"`
	Analytics     []QueryExample `json:"analytics"`
	Recursive     []QueryExample `json:"recursive"`
	Spatial       []QueryExample `json:"spatial"`
	RemoteJoins   []QueryExample `json:"remote_joins"`
}

type QueryPattern struct {
	Name              string `json:"name"`
	Title             string `json:"title"`
	Question          string `json:"question"`
	Rule              string `json:"rule"`
	Why               string `json:"why"`
	WrongExample      string `json:"wrong_example,omitempty"`
	WrongReason       string `json:"wrong_reason,omitempty"`
	RightExample      string `json:"right_example"`
	AutoTraversalNote string `json:"auto_traversal_note,omitempty"`
}

type QuerySyntaxReference struct {
	AnalyticsModeRules  []string                  `json:"analytics_mode_rules,omitempty"`
	Patterns            []QueryPattern            `json:"patterns,omitempty"`
	FilterOperators     FilterOperators           `json:"filter_operators"`
	LogicalOperators    []string                  `json:"logical_operators"`
	Pagination          PaginationSyntax          `json:"pagination"`
	Ordering            OrderingSyntax            `json:"ordering"`
	Aggregations        AggregationsSyntax        `json:"aggregations"`
	AnalyticsDirectives AnalyticsDirectivesSyntax `json:"analytics_directives"`
	Recursive           RecursiveSyntax           `json:"recursive"`
	FullTextSearch      string                    `json:"full_text_search"`
	Directives          map[string]string         `json:"directives"`
	Variables           VariablesSyntax           `json:"variables"`
	JSONPaths           string                    `json:"json_paths"`
	CommonMistakes      []MistakeExample          `json:"common_mistakes"`
	Examples            QueryExamplesForSyntax    `json:"examples"`
}

type QueryTemplate struct {
	Name        string `json:"name"`
	Kind        string `json:"kind"`
	Table       string `json:"table"`
	Description string `json:"description,omitempty"`
	Query       string `json:"query"`
}

type RateLimiter struct {
	// The number of events per second
	Rate float64 `jsonschema:"title=Connection Rate"`

	// Bucket a burst of at most 'bucket' number of events
	Bucket int `jsonschema:"title=Bucket Size"`

	// The header that contains the client ip
	IPHeader string `mapstructure:"ip_header" jsonschema:"title=IP From HTTP Header,example=X-Forwarded-For"`
}

type RecursiveSyntax struct {
	FindParents  string `json:"find_parents"`
	FindChildren string `json:"find_children"`
}

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

type RedisConfig struct {
	// Redis connection URL (e.g., redis://localhost:6379/0)
	URL string `mapstructure:"url" jsonschema:"title=Redis URL"`
}

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

type RelationshipPath struct {
	From  string          `json:"from"`
	To    string          `json:"to"`
	Steps []core.PathStep `json:"steps,omitempty"`
}

type RelationshipRef struct {
	Table  string `json:"table"`
	Column string `json:"column,omitempty"`
	Type   string `json:"type,omitempty"`
}

type ResolverConfigInput struct {
	Name        string           `json:"name"`
	Type        string           `json:"type"`
	Schema      string           `json:"schema,omitempty"`
	Table       string           `json:"table"`
	Column      string           `json:"column,omitempty"`
	StripPath   string           `json:"strip_path,omitempty"`
	URL         string           `json:"url,omitempty"`
	Debug       bool             `json:"debug,omitempty"`
	PassHeaders []string         `json:"pass_headers,omitempty"`
	SetHeaders  []SetHeaderInput `json:"set_headers,omitempty"`
}

type ResponseCache interface {
	// Get retrieves a cached response
	// Returns (data, isStale, found)
	Get(ctx context.Context, key string) ([]byte, bool, bool)

	// Set stores a response with dependency refs for invalidation.
	Set(ctx context.Context, key string, data []byte, refs []core.RowRef, queryStartTime time.Time) error

	// InvalidateRows invalidates cache entries for dependency refs.
	InvalidateRows(ctx context.Context, refs []core.RowRef) error

	// InvalidateTables invalidates cache entries for whole tables when row-level
	// tracking is insufficient, such as external source reindexing.
	InvalidateTables(ctx context.Context, tables []string) error

	// SubmitRefresh enqueues a stale-while-revalidate refresh on the worker pool.
	// Returns false if SWR is disabled or the pool is full/shutdown.
	SubmitRefresh(key string, fn core.RefreshFn) bool

	// Metrics returns the cache metrics
	Metrics() *CacheMetrics

	// Close releases resources
	Close() error
}

type ReturningInfo struct {
	Description string `json:"description"`
	Example     string `json:"example"`
}

type RoleConfigInput struct {
	Name    string                 `json:"name"`
	Comment string                 `json:"comment,omitempty"`
	Match   string                 `json:"match,omitempty"`
	Tables  []RoleTableConfigInput `json:"tables,omitempty"`
}

type RoleInfo struct {
	Name    string           `json:"name"`
	Comment string           `json:"comment,omitempty"`
	Match   string           `json:"match,omitempty"`
	Tables  []core.RoleTable `json:"tables,omitempty"`
}

type RoleTableConfigInput struct {
	Name     string             `json:"name"`
	Schema   string             `json:"schema,omitempty"`
	Database string             `json:"database,omitempty"`
	ReadOnly bool               `json:"read_only,omitempty"`
	Query    *QueryConfigInput  `json:"query,omitempty"`
	Insert   *InsertConfigInput `json:"insert,omitempty"`
	Update   *UpdateConfigInput `json:"update,omitempty"`
	Upsert   *UpsertConfigInput `json:"upsert,omitempty"`
	Delete   *DeleteConfigInput `json:"delete,omitempty"`
}

type RuntimeEventsConfig struct {
	// MaxEvents is the maximum number of recent event rows retained.
	MaxEvents int `mapstructure:"max_events" jsonschema:"title=Runtime Event Limit,default=1000"`

	// TTLSeconds controls how long event rows are retained.
	TTLSeconds int `mapstructure:"ttl_seconds" jsonschema:"title=Runtime Event TTL Seconds,default=86400"`
}

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

type SchemaInsights struct {
	Database          string             `json:"database"`
	DatabaseOverview  *DatabaseOverview  `json:"database_overview,omitempty"`
	HubTables         []HubTable         `json:"hub_tables,omitempty"`
	RelationshipPaths []RelationshipPath `json:"relationship_paths,omitempty"`
	NamespaceRouting  []NamespaceRoute   `json:"namespace_routing,omitempty"`
	QueryTemplates    []QueryTemplate    `json:"query_templates,omitempty"`
	DuplicateFlags    []DuplicateFlag    `json:"duplicate_flags,omitempty"`
	DataQualityFlags  []DataQualityFlag  `json:"data_quality_flags,omitempty"`
}

type SchemaStats struct {
	Name           string `json:"name"`
	TableCount     int    `json:"table_count"`
	ApproxRowTotal int64  `json:"approx_row_total"`
}

type SecretsConfig struct {
	Keystore KeystoreConfig `mapstructure:"keystore" jsonschema:"title=Encrypted Keystore"`
}

type SemanticCatalogSearchConfig struct {
	// Enabled adds Ax-backed semantic recall to the lexical catalog baseline.
	Enabled bool `mapstructure:"enabled" jsonschema:"title=Enable Semantic Catalog Search,default=false"`

	// Provider is the Ax embedding provider name.
	Provider string `mapstructure:"provider" jsonschema:"title=Embedding Provider,default=openai"`

	// EmbeddingModel is required when semantic search is enabled and forms part
	// of the persisted embedding-space fingerprint.
	EmbeddingModel string `mapstructure:"embedding_model" jsonschema:"title=Embedding Model"`

	// APIKeyEnv names the environment variable containing the provider key.
	APIKeyEnv string `mapstructure:"api_key_env" jsonschema:"title=Embedding API Key Environment Variable,default=OPENAI_API_KEY"`

	// BaseURL optionally overrides the provider endpoint and forms part of the
	// persisted embedding-space fingerprint.
	BaseURL string `mapstructure:"base_url" jsonschema:"title=Embedding Provider Base URL"`

	// Dimensions selects tiny (768), small (1536), medium (3072), or the
	// provider-native default. Named sizes are validated strictly.
	Dimensions string `mapstructure:"dimensions" jsonschema:"title=Embedding Dimensions,default=small,enum=tiny,enum=small,enum=medium,enum=default"`
}

type SemanticEmbeddingClient interface {
	Embed(ctx context.Context, texts []string, dimensions *int) ([][]float32, error)
}

type Serv struct {
	// Application name is used in log and debug messages
	AppName string `mapstructure:"app_name" jsonschema:"title=Application Name"`

	// Legacy production switch. Prefer top-level mode for new configs.
	Production bool `jsonschema:"title=Production Mode,default=false"`

	// Stops the catalog from sampling the small value sets of enum-like columns
	// (status, severity, plan, and similar). Those sets let an agent filter on a
	// real value instead of inventing one, so leaving this off is recommended;
	// set it when even low-cardinality values must not appear in catalog cards.
	DisableColumnValueSampling bool `mapstructure:"disable_column_value_sampling" jsonschema:"title=Disable Catalog Column Value Sampling,default=false"`

	// The default path to find all configuration files and scripts
	ConfigPath string `mapstructure:"config_path" jsonschema:"title=Config Path"`

	// Logging level must be one of debug, error, warn, info
	LogLevel string `mapstructure:"log_level" jsonschema:"title=Log Level,enum=debug,enum=error,enum=warn,enum=info"`

	// Logging Format: "auto" (default, colored console in dev, JSON in production),
	// "json" (always JSON), or "simple" (always colored console)
	LogFormat string `mapstructure:"log_format" jsonschema:"title=Logging Format,enum=auto,enum=json,enum=simple"`

	// The host and port the service runs on. Example localhost:8080
	HostPort string `mapstructure:"host_port" jsonschema:"title=Host and Port"`

	// Host to run the service on
	Host string `jsonschema:"title=Host"`

	// Port to run the service on
	Port string `jsonschema:"title=Port"`

	// Enables HTTP compression
	HTTPGZip bool `mapstructure:"http_compress" jsonschema:"title=Enable Compression,default=true"`

	// Sets the API rate limits
	RateLimiter RateLimiter `mapstructure:"rate_limiter" jsonschema:"title=Set API Rate Limiting"`

	// Enables the Server-Timing HTTP header
	ServerTiming bool `mapstructure:"server_timing" jsonschema:"title=Server Timing HTTP Header,default=true"`

	// Enable the web UI. Defaults on in dev and agentic modes, off in prod.
	WebUI bool `mapstructure:"web_ui" jsonschema:"title=Enable Web UI,default=false"`

	// Evaluation report state directory for the non-production Trainer console.
	// Relative paths resolve from config_path. Set to "off" to disable the API.
	EvalStateDir string `mapstructure:"eval_state_dir" jsonschema:"title=Evaluation Report State Directory"`

	// Enable OpenTrace request tracing
	EnableTracing bool `mapstructure:"enable_tracing" jsonschema:"title=Enable Tracing,default=true"`

	// Enables reloading the service on config changes. Disabled in production
	WatchAndReload bool `mapstructure:"reload_on_config_change" jsonschema:"title=Reload Config"`

	// Enable blocking requests with a HTTP 401 on auth failure
	AuthFailBlock bool `mapstructure:"auth_fail_block" jsonschema:"title=Block Request on Authorization Failure"`

	// Sets the HTTP CORS Access-Control-Allow-Origin header
	AllowedOrigins []string `mapstructure:"cors_allowed_origins" jsonschema:"title=HTTP CORS Allowed Origins"`

	// Sets the HTTP CORS Access-Control-Allow-Headers header
	AllowedHeaders []string `mapstructure:"cors_allowed_headers" jsonschema:"title=HTTP CORS Allowed Headers"`

	// Enables debug logs for CORS
	DebugCORS bool `mapstructure:"cors_debug" jsonschema:"title=Log CORS"`

	// Sets the HTTP Cache-Control header
	CacheControl string `mapstructure:"cache_control" jsonschema:"title=Enable Cache-Control"`

	// Sets the default authentication used by the service
	Auth Auth `jsonschema:"title=Authentication"`

	// Database configuration
	DB Database `mapstructure:"database" jsonschema:"title=Database"`

	// MCP (Model Context Protocol) server configuration
	MCP MCPConfig `mapstructure:"mcp" jsonschema:"title=MCP Configuration"`

	// Server-side GraphJin discovery/answer agent configuration
	Agent AgentConfig `mapstructure:"agent" jsonschema:"title=GraphJin Agent Configuration"`

	// Local encrypted secrets configuration
	Secrets SecretsConfig `mapstructure:"secrets" jsonschema:"title=Secrets"`

	// Redis configuration
	Redis RedisConfig `mapstructure:"redis" jsonschema:"title=Redis Configuration"`

	// Coordinated, filesystem-backed database discovery cache.
	DiscoveryCache DiscoveryCacheConfig `mapstructure:"discovery_cache" jsonschema:"title=Discovery Cache Configuration"`

	// Catalog retrieval configuration.
	CatalogSearch CatalogSearchConfig `mapstructure:"catalog_search" jsonschema:"title=Catalog Search Configuration"`

	// Runtime event configuration
	RuntimeEvents RuntimeEventsConfig `mapstructure:"runtime_events" jsonschema:"title=Runtime Events Configuration"`

	// Response caching configuration
	Caching CachingConfig `mapstructure:"caching" jsonschema:"title=Caching Configuration"`

	// Multipart upload configuration (graphql-multipart-request-spec)
	Uploads UploadsConfig `mapstructure:"uploads" jsonschema:"title=Multipart Uploads"`

	// Built-in OIDC login that mints local JWTs for the CLI / MCP client
	AuthLogin AuthLogin `mapstructure:"auth_login" jsonschema:"title=Built-in Login (OIDC)"`
}

type SetHeaderInput struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

type SetupPlanResult struct {
	Candidates  []DiscoveredDatabase `json:"candidates"`
	Checklist   []string             `json:"selection_checklist"`
	Recommended string               `json:"recommended_candidate_id,omitempty"`
	Next        *NextGuidance        `json:"next,omitempty"`
}

type TableConfigInput struct {
	Name      string              `json:"name"`
	Source    string              `json:"source,omitempty"`
	Database  string              `json:"database,omitempty"`
	ReadOnly  bool                `json:"read_only,omitempty"`
	Blocklist []string            `json:"blocklist,omitempty"`
	Columns   []ColumnConfigInput `json:"columns,omitempty"`
	OrderBy   map[string][]string `json:"order_by,omitempty"`
}

type TableDetailEntry struct {
	TableIndexEntry
	Schema  *core.TableSchema `json:"schema,omitempty"`
	Profile *TableProfile     `json:"profile,omitempty"`
}

type TableIndexEntry struct {
	Name        string `json:"name"`
	Schema      string `json:"schema,omitempty"`
	Database    string `json:"database,omitempty"`
	Type        string `json:"type,omitempty"`
	Comment     string `json:"comment,omitempty"`
	ColumnCount int    `json:"column_count,omitempty"`
	// nil = unknown (catalog stats unavailable); 0 = measured zero.
	RowCountApprox    *int64          `json:"row_count_approx,omitempty"`
	PrimaryKeys       []string        `json:"primary_keys,omitempty"`
	ForeignKeys       []ForeignKeyRef `json:"foreign_keys,omitempty"`
	KeyColumns        []string        `json:"key_columns,omitempty"`
	ColumnTypeSummary map[string]int  `json:"column_type_summary,omitempty"`
	JoinTargets       []string        `json:"join_targets,omitempty"`
	DuplicateIn       []string        `json:"duplicate_in,omitempty"`
}

type TableListOptions struct {
	Search string
	Schema string
	Limit  int
	Cursor string
}

type TableProfile struct {
	RowCountApprox *int64                  `json:"row_count_approx,omitempty"`
	DateRanges     map[string]DateRange    `json:"date_ranges,omitempty"`
	EnumValues     map[string]EnumProfile  `json:"enum_values,omitempty"`
	NumericStats   map[string]NumericStats `json:"numeric_stats,omitempty"`
	ColumnStats    map[string]ColumnStats  `json:"column_stats,omitempty"`
	SampleRows     []map[string]any        `json:"sample_rows,omitempty"`
}

type TableRef struct {
	Name           string `json:"name"`
	Schema         string `json:"schema,omitempty"`
	RowCountApprox int64  `json:"row_count_approx"`
}

type TableSampleResult struct {
	Database string        `json:"database"`
	Schema   string        `json:"schema,omitempty"`
	Table    string        `json:"table"`
	Status   string        `json:"status"`
	Stats    *TableProfile `json:"stats,omitempty"`

	PrimaryKeys           []string                `json:"primary_keys,omitempty"`
	ForeignKeys           []ForeignKeyRef         `json:"foreign_keys,omitempty"`
	OutgoingRels          []RelationshipRef       `json:"outgoing_relationships,omitempty"`
	IncomingRels          []RelationshipRef       `json:"incoming_relationships,omitempty"`
	FKDisambiguation      []FKDisambiguationEntry `json:"fk_disambiguation,omitempty"`
	Indexes               []IndexInfo             `json:"indexes,omitempty"`
	Aggregations          *AggregationInfo        `json:"aggregations,omitempty"`
	ExampleQueries        []ExampleQuery          `json:"example_queries,omitempty"`
	AnalyticsModeRules    []string                `json:"analytics_mode_rules,omitempty"`
	AggregationHint       string                  `json:"aggregation_hint,omitempty"`
	TemporalFilterWarning string                  `json:"temporal_filter_warning,omitempty"`

	Cost DiscoveryCost `json:"cost"`
}

type TableSchemaWithAggregations struct {
	*core.TableSchema
	Aggregations   AggregationInfo `json:"aggregations"`
	ExampleQueries []ExampleQuery  `json:"example_queries,omitempty"`
}

type ToolReplaces struct {
	Tool        string `json:"tool"`
	Replacement string `json:"replacement"`
	For         string `json:"for,omitempty"`
}

type UpdateConfigInput struct {
	Filters []string          `json:"filters,omitempty"`
	Columns []string          `json:"columns,omitempty"`
	Presets map[string]string `json:"presets,omitempty"`
	Block   bool              `json:"block,omitempty"`
}

type UploadsConfig struct {
	// Enable multipart/form-data parsing on /api/v1/graphql
	Enabled bool `mapstructure:"enabled" jsonschema:"title=Enable Uploads,default=false"`

	// MaxSize is the per-request multipart body limit in bytes.
	// Defaults to 25 MB when zero.
	MaxSize int64 `mapstructure:"max_size" jsonschema:"title=Max Upload Size (bytes),default=26214400"`

	// AllowedMIME, when non-empty, restricts the accepted content types.
	// Glob patterns are supported: "image/*", "application/pdf".
	AllowedMIME []string `mapstructure:"allowed_mime" jsonschema:"title=Allowed MIME Types"`

	// Storage names a filesystems[].name to stream uploads into. When
	// empty, the legacy inline-base64 mode is used. When set, files
	// are written to the backend and the variable becomes the object
	// metadata instead of inlined data.
	Storage string `mapstructure:"storage" jsonschema:"title=Filesystem Table for Streaming"`

	// StorageKeyPrefix is prepended to the backend key for every
	// uploaded file. Useful for namespacing by tenant or role.
	// Example: "avatars/{date}/" — the {date} marker is substituted
	// at request time with YYYY/MM/DD.
	StorageKeyPrefix string `mapstructure:"storage_key_prefix" jsonschema:"title=Storage Key Prefix"`
}

type UpsertConfigInput struct {
	Filters []string          `json:"filters,omitempty"`
	Columns []string          `json:"columns,omitempty"`
	Presets map[string]string `json:"presets,omitempty"`
	Block   bool              `json:"block,omitempty"`
}

type ValidationSyntax struct {
	Directive string   `json:"directive"`
	Options   []string `json:"options"`
	Example   string   `json:"example"`
}

type VariablesSyntax struct {
	Declaration string   `json:"declaration"`
	Types       []string `json:"types"`
	Example     string   `json:"example"`
}

type WatchSeed struct {
	Name           string
	Description    string
	Query          string
	SavedQueryName string
	VariablesJSON  string
	DeliveryJSON   string
	AbsenceJSON    string
	EnrichJSON     string
}

type WhereValidationError struct {
	Path       string `json:"path"`
	Error      string `json:"error"`
	Message    string `json:"message"`
	ColumnType string `json:"column_type,omitempty"`
	Suggestion string `json:"suggestion,omitempty"`
}

type WhereValidationResult struct {
	Valid          bool                      `json:"valid"`
	Errors         []WhereValidationError    `json:"errors,omitempty"`
	Warnings       []string                  `json:"warnings,omitempty"`
	CompilerErrors []string                  `json:"compiler_errors,omitempty"`
	ValidatedBy    string                    `json:"validated_by,omitempty"`
	ExampleQuery   string                    `json:"example_query,omitempty"`
	ColumnInfo     map[string]ColumnTypeInfo `json:"column_info,omitempty"`
}

type WorkflowGuide struct {
	QueryWorkflow      []string          `json:"query_workflow"`
	MutationWorkflow   []string          `json:"mutation_workflow"`
	Tips               []string          `json:"tips"`
	AnalyticsModeRules []string          `json:"analytics_mode_rules,omitempty"`
	QueryPatterns      []QueryPattern    `json:"query_patterns,omitempty"`
	ToolSequences      map[string]string `json:"tool_sequences"`
}

type WorkflowInfo struct {
	Name             string             `json:"name"`
	Description      string             `json:"description"`
	Tags             []string           `json:"tags,omitempty"`
	Variables        []WorkflowVariable `json:"variables,omitempty"`
	CreatedAt        string             `json:"created_at,omitempty"`
	UpdatedAt        string             `json:"updated_at,omitempty"`
	WorkflowRevision string             `json:"workflow_revision,omitempty"`
}

type WorkflowMeta struct {
	Description string             `json:"description"`
	Tags        []string           `json:"tags,omitempty"`
	Variables   []WorkflowVariable `json:"variables,omitempty"`
	CreatedAt   string             `json:"created_at,omitempty"`
	UpdatedAt   string             `json:"updated_at,omitempty"`
}

type WorkflowVariable struct {
	Name        string `json:"name"`
	Type        string `json:"type,omitempty"`
	Description string `json:"description,omitempty"`
	Required    bool   `json:"required,omitempty"`
}