platform

type APIGatewayConfig struct {
	// EmbedJobs tunes the api-gateway embedding job queue.
	EmbedJobs APIGatewayEmbedJobsConfig `yaml:"embed_jobs"`

	// Memory bounds the gateway's response-body memory footprint across
	// all connections so a burst of large responses cannot OOMKill the
	// pod (issue #535).
	Memory APIGatewayMemoryConfig `yaml:"memory"`

	// SelfConnection configures the built-in platform-admin connection
	// that points the API gateway at the platform's own admin REST API.
	SelfConnection APIGatewaySelfConnectionConfig `yaml:"self_connection"`
}

type APIGatewayEmbedJobsConfig struct {
	// Workers is the number of goroutines per pod that claim and
	// process jobs in parallel. Multiple goroutines share the queue;
	// the lease + SKIP LOCKED predicate in Claim prevents two
	// goroutines (in the same pod or across pods) from picking the
	// same job. Zero or negative falls back to 1, which preserves
	// the pre-#430 single-goroutine behavior. Production deployments
	// with many specs and a fast embedder benefit from 2-4; CPU-only
	// embedders typically saturate at 1 because the bottleneck is
	// the embedding model, not the gateway. See #430.
	Workers int `yaml:"workers"`

	// EmbedTimeout caps an individual batched embedding HTTP call the
	// worker issues to Ollama's /api/embed endpoint. The shared
	// embedding.DefaultTimeout (30s) is tuned for the singular
	// /api/embeddings path used by request-path callers (memory recall,
	// capture_insight, etc.) where Ollama returns in 1-3s. The batched
	// path can take 60+ seconds for a 32-text chunk on CPU-only Ollama;
	// using the 30s default makes the worker timeout-storm on every
	// spec write (#445). Zero or negative falls back to 5 minutes,
	// which covers a 32-text batch on CPU Ollama with margin. Operators
	// on GPU embedders can lower this to keep the failure floor tight.
	EmbedTimeout time.Duration `yaml:"embed_timeout"`

	// BatchSize is the number of operations the worker hands to
	// the embedding provider per upstream EmbedBatch call.
	// Smaller batches keep one slow chunk's lost progress small
	// at the cost of more per-call overhead; larger batches
	// amortize that overhead. Zero or negative falls back to
	// 32 (embedjobs.DefaultEmbedBatchSize), the value that
	// shipped before this knob was operator-controlled.
	//
	// Tune lower (e.g. 16) when a CPU-only provider's per-batch
	// latency exceeds EmbedTimeout on full chunks; tune higher
	// (e.g. 64) on GPU providers where per-call overhead
	// dominates per-text compute. See #479.
	BatchSize int `yaml:"batch_size"`

	// LeaseDuration is the lifetime a Claim stamps on a job and
	// the cadence the worker's heartbeat goroutine renews it.
	// The reaper releases leases past this window so a pod that
	// genuinely crashed mid-embed has its job picked up by
	// another worker. Zero or negative falls back to 10 minutes
	// (embedjobs.DefaultLeaseDuration), the value that shipped
	// before this knob was operator-controlled.
	//
	// On CPU-only embedders processing large specs (~150+ ops),
	// total compute can exceed 10 minutes even though every
	// individual batch finishes in 2-3 minutes. The heartbeat
	// (lease_duration / 3 cadence) keeps the lease alive while
	// chunks are completing, so this value caps "pod went
	// silent" rather than "embed batch is slow" — but it must
	// still be greater than EmbedTimeout so a single batch can
	// finish inside one lease window before the heartbeat fires
	// its first renewal. See #479.
	LeaseDuration time.Duration `yaml:"lease_duration"`

	// RetentionDays bounds how long finished index_jobs history is
	// kept. The queue records one row per reconciler sweep per unit
	// (every 5 minutes, on every replica), so succeeded history grows
	// without limit; the retainer periodically deletes succeeded and
	// resolved-failed rows older than this window. Open failures
	// (status='failed' with no resolved_at) and in-flight rows
	// (pending / running) are never purged regardless of age, so the
	// failure-triage surface and the active queue are unaffected.
	//
	// Zero falls back to 14 days (indexjobs.DefaultRetentionDays), a
	// window that keeps a useful span of throughput / latency / job-log
	// history for the admin Indexing dashboard while bounding the table.
	// A negative value disables retention entirely (history grows
	// unbounded), for deployments that prefer to manage cleanup
	// externally. See #523.
	RetentionDays int `yaml:"retention_days"`
}

type APIGatewayMemoryConfig struct {
	// MaxInFlightBytes is the global ceiling on bytes committed to
	// api_invoke_endpoint response-body buffering across all api
	// connections. A buffered read that would push committed bytes past
	// this is rejected with a structured 429 (retryable) before the
	// buffer is allocated. 0 = disabled (no global cap; per-connection
	// max_response_bytes still applies per request). api_export is exempt:
	// it streams directly to S3 (issue #537) and never buffers the full
	// body, so it does not consume this budget.
	//
	// Sizing: budget roughly 3x the raw body size per concurrent large
	// request (raw body + decoded copy + JSON-escaped envelope copy) and
	// leave headroom for GC and the other toolkits' working set. A safe
	// target keeps
	//   max_in_flight_bytes ≈ (container_memory_limit × 0.6) / 3
	// so peak buffering stays well under the heap even at full
	// utilization. Do NOT set this to the whole container limit or
	// GOMEMLIMIT — that leaves no room for the transient marshaling
	// copies or for GC.
	MaxInFlightBytes int64 `yaml:"max_in_flight_bytes"`

	// RawMaxBytes caps a single raw passthrough response on the
	// /api/v1/gateway/{connection}/invoke-raw REST route
	// (all-or-nothing). An upstream whose declared Content-Length
	// exceeds this is rejected with 413 (non-retryable) before any bytes
	// are streamed. 0 = no cap: the raw path streams (io.Copy) instead
	// of buffering, so process memory stays bounded regardless of body
	// size — the cap is a policy guard, not a memory guard.
	RawMaxBytes int64 `yaml:"raw_max_bytes"`
}

type APIGatewaySelfConnectionConfig struct {
	// Enabled gates self-registration. Nil = auto (on when prerequisites
	// are met); set explicitly to override.
	Enabled *bool `yaml:"enabled"`
	// BaseURL overrides the loopback admin API base URL the connection
	// targets. Empty derives http://127.0.0.1:<port> from the server
	// listen address. Set this only when the admin API is reachable at a
	// different loopback address than the main listener.
	BaseURL string `yaml:"base_url"`
}

type APIKeyAuthConfig struct {
	Enabled bool        `yaml:"enabled"`
	Keys    []APIKeyDef `yaml:"keys"`
}

type APIKeyDef struct {
	Key         string   `yaml:"key"`
	Name        string   `yaml:"name"`
	Email       string   `yaml:"email"`
	Description string   `yaml:"description"`
	Roles       []string `yaml:"roles"`
}

type APIKeyDefinition struct {
	Name        string     `json:"name"`
	KeyHash     string     `json:"key_hash"`
	Email       string     `json:"email,omitempty"`
	Description string     `json:"description,omitempty"`
	Roles       []string   `json:"roles"`
	ExpiresAt   *time.Time `json:"expires_at,omitempty"`
	CreatedBy   string     `json:"created_by"`
	CreatedAt   time.Time  `json:"created_at"`
}

type APIKeyStore interface {
	List(ctx context.Context) ([]APIKeyDefinition, error)
	Set(ctx context.Context, def APIKeyDefinition) error
	Delete(ctx context.Context, name string) error
}

type AdminConfig struct {
	Enabled    *bool  `yaml:"enabled"`
	Persona    string `yaml:"persona"`     // required admin persona (default: "admin")
	PathPrefix string `yaml:"path_prefix"` // URL prefix (default: "/api/v1/admin")
}

type AppConfig struct {
	// Enabled controls whether this app is active.
	Enabled bool `yaml:"enabled"`

	// Tools lists the tool names this app attaches to.
	Tools []string `yaml:"tools"`

	// AssetsPath is the absolute filesystem path to the app's assets directory.
	// This should point to a directory containing the app's HTML/JS/CSS files.
	// Optional for built-in apps that use embedded assets; setting it overrides the embedded content.
	AssetsPath string `yaml:"assets_path"`

	// ResourceURI is the MCP resource URI for this app (e.g., "ui://query-results").
	// If not specified, defaults to "ui://<app-name>".
	ResourceURI string `yaml:"resource_uri"`

	// EntryPoint is the main HTML file within AssetsPath (e.g., "index.html").
	// Defaults to "index.html" if not specified.
	EntryPoint string `yaml:"entry_point"`

	// CSP defines Content Security Policy requirements for the app.
	CSP *CSPAppConfig `yaml:"csp"`

	// Config holds app-specific configuration that will be injected
	// into the HTML as JSON.
	Config map[string]any `yaml:"config"`
}

type AuditConfig struct {
	Enabled      *bool `yaml:"enabled"`
	LogToolCalls *bool `yaml:"log_tool_calls"`
	// LogParameters controls whether tool-call arguments are stored on the
	// event. Enabled by default (nil = enabled); set log_parameters: false to
	// store a null Parameters field when the arguments may carry sensitive data
	// that even redaction cannot make safe to retain.
	LogParameters *bool `yaml:"log_parameters"`
	// RedactKeys lists top-level argument keys whose values are replaced with
	// "[REDACTED]" in the middleware, before the event ever leaves the request
	// path. Matching is case-insensitive; nested keys are not matched (top-level
	// only, by design).
	RedactKeys []string `yaml:"redact_keys"`
	// Delivery selects the store-write path: "async" (default) or "sync". See
	// the Audit delivery mode constants.
	Delivery      string `yaml:"delivery"`
	RetentionDays int    `yaml:"retention_days"`
}

type AuthConfig struct {
	OIDC           OIDCAuthConfig       `yaml:"oidc"`
	APIKeys        APIKeyAuthConfig     `yaml:"api_keys"`
	BrowserSession BrowserSessionConfig `yaml:"browser_session"`
	AllowAnonymous bool                 `yaml:"allow_anonymous"` // default: false
}

type BasicAuthConfig struct {
	Username string `yaml:"username"`
	Password string `yaml:"password"`
}

type BrowserSessionConfig struct {
	Enabled    bool          `yaml:"enabled"`
	CookieName string        `yaml:"cookie_name"` // default: "mcp_session"
	TTL        time.Duration `yaml:"ttl"`         // default: 8h
	SigningKey string        `yaml:"signing_key"` // base64-encoded HMAC key
	Secure     *bool         `yaml:"secure"`      // HTTPS-only cookie; defaults to true, set false only for local HTTP
	Domain     string        `yaml:"domain"`
	// SameSite is the cookie SameSite attribute: "lax" (default), "strict", or
	// "none". "none" requires secure=true and makes X-CSRF-Token the sole CSRF
	// defense (a startup warning is logged).
	SameSite string `yaml:"same_site"`
}

type CSPAppConfig struct {
	// ResourceDomains lists origins for static resources (scripts, images, styles, fonts).
	ResourceDomains []string `yaml:"resource_domains"`

	// ConnectDomains lists origins for network requests (fetch/XHR/WebSocket).
	ConnectDomains []string `yaml:"connect_domains"`

	// FrameDomains lists origins for nested iframes.
	FrameDomains []string `yaml:"frame_domains"`

	// ClipboardWrite requests write access to the clipboard.
	ClipboardWrite bool `yaml:"clipboard_write"`
}

type CacheConfig struct {
	Enabled bool          `yaml:"enabled"`
	TTL     time.Duration `yaml:"ttl"`
}

type ClientLoggingConfig struct {
	Enabled *bool `yaml:"enabled"`
}

type Closer interface {
	Close() error
}

type Component interface {
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
}

type Config struct {
	APIVersion string           `yaml:"apiVersion"`
	Meta       ConfigMeta       `yaml:"config"`
	Server     ServerConfig     `yaml:"server"`
	Auth       AuthConfig       `yaml:"auth"`
	OAuth      OAuthConfig      `yaml:"oauth"`
	Database   DatabaseConfig   `yaml:"database"`
	Personas   PersonasConfig   `yaml:"personas"`
	Toolkits   map[string]any   `yaml:"toolkits"`
	Tools      ToolsConfig      `yaml:"tools"`
	Semantic   SemanticConfig   `yaml:"semantic"`
	Query      QueryConfig      `yaml:"query"`
	Storage    StorageConfig    `yaml:"storage"`
	Enrichment EnrichmentConfig `yaml:"enrichment"`
	Tuning     TuningConfig     `yaml:"tuning"`

	// EnrichmentDeprecated accepts the legacy "injection" key so configs written
	// before the rename to "enrichment" still load. applyEnrichmentCompat folds it
	// onto Enrichment and warns. Remove in a future apiVersion.
	EnrichmentDeprecated *EnrichmentConfig   `yaml:"injection"`
	Audit                AuditConfig         `yaml:"audit"`
	MCPApps              MCPAppsConfig       `yaml:"mcpapps"`
	Sessions             SessionsConfig      `yaml:"sessions"`
	Knowledge            KnowledgeConfig     `yaml:"knowledge"`
	Memory               MemoryConfig        `yaml:"memory"`
	Portal               PortalConfig        `yaml:"portal"`
	Admin                AdminConfig         `yaml:"admin"`
	Resources            ResourcesConfig     `yaml:"resources"`
	Progress             ProgressConfig      `yaml:"progress"`
	ClientLogging        ClientLoggingConfig `yaml:"client_logging"`
	Icons                IconsConfig         `yaml:"icons"`
	Elicitation          ElicitationConfig   `yaml:"elicitation"`
	Workflow             WorkflowConfig      `yaml:"workflow"`
	SessionGate          SessionGateConfig   `yaml:"session_gate"`
	RateLimit            RateLimitConfig     `yaml:"rate_limit"`
	APIGateway           APIGatewayConfig    `yaml:"apigateway"`
	Observability        ObservabilityConfig `yaml:"observability"`
	// contains filtered or unexported fields
}

type ConfigEnvelope struct {
	APIVersion string `yaml:"apiVersion"`
}

type ConfigMeta struct {
	// Strict controls how unrecognized YAML keys are handled. When nil (the
	// default for this release) unknown keys are logged as a prominent warning
	// and ignored, so existing configs keep loading while operators are alerted
	// to drift. Set `config.strict: true` to reject unknown keys with a hard
	// error instead (recommended: catches typos and stale keys at startup).
	//
	// A future release will flip the default so unknown keys are an error
	// unless `config.strict: false` is set as a temporary escape hatch.
	Strict *bool `yaml:"strict"`
}

type ConfigVersionInfo struct {
	APIVersion        string   `json:"api_version"`
	SupportedVersions []string `json:"supported_versions"`
	LatestVersion     string   `json:"latest_version"`
}

type ConnectionInstance struct {
	Kind        string         `json:"kind" example:"trino"`
	Name        string         `json:"name" example:"acme-warehouse"`
	Config      map[string]any `json:"config"`
	Description string         `json:"description" example:"Production data warehouse"`
	CreatedBy   string         `json:"created_by" example:"admin@example.com"`
	UpdatedAt   time.Time      `json:"updated_at" example:"2026-01-15T14:30:00Z"`
}

type ConnectionReloadOp int

type ConnectionRulesDef struct {
	Allow []string `yaml:"allow,omitempty"`
	Deny  []string `yaml:"deny,omitempty"`
}

type ConnectionSource = connsource.Source

type ConnectionSourceMap = connsource.Map

type ConnectionStore interface {
	List(ctx context.Context) ([]ConnectionInstance, error)
	Get(ctx context.Context, kind, name string) (*ConnectionInstance, error)
	Set(ctx context.Context, inst ConnectionInstance) error
	Delete(ctx context.Context, kind, name string) error

	// Persistent reports whether the store survives process restarts.
	// True for database-backed implementations, false for noop / in-memory
	// stubs. The platform uses this to decide whether to auto-activate
	// features whose state would be lost without persistence (e.g. the
	// mcp gateway toolkit, where authcode-grant connections rely on the
	// token store keeping refresh tokens across restarts).
	Persistent() bool
}

type ContextDef struct {
	DescriptionPrefix         string `yaml:"description_prefix,omitempty"`
	DescriptionOverride       string `yaml:"description_override,omitempty"`
	AgentInstructionsSuffix   string `yaml:"agent_instructions_suffix,omitempty"`
	AgentInstructionsOverride string `yaml:"agent_instructions_override,omitempty"`
}

type CostEstimationConfig struct {
	// Enabled controls whether query cost estimation triggers elicitation.
	// Enabled by default (nil = enabled); set enabled: false to disable.
	Enabled *bool `yaml:"enabled"`

	// RowThreshold is the estimated row count above which confirmation is requested.
	// Default: 1000000 (1 million rows).
	RowThreshold int64 `yaml:"row_threshold"`
}

type CustomResourceDef struct {
	URI         string `yaml:"uri"`
	Name        string `yaml:"name"`
	Description string `yaml:"description,omitempty"`
	MIMEType    string `yaml:"mime_type"`
	Content     string `yaml:"content,omitempty"`      // inline text/JSON/SVG
	ContentFile string `yaml:"content_file,omitempty"` // absolute or relative path
}

type DCRConfig struct {
	Enabled bool `yaml:"enabled"`
	// AllowedRedirectPatterns are regex patterns for redirect URIs that
	// dynamically registered clients may use. The registration endpoint is
	// unauthenticated, so registration is denied when this is empty unless
	// AllowAllRedirectURIs explicitly opts out of pattern matching.
	AllowedRedirectPatterns []string `yaml:"allowed_redirect_patterns"`
	AllowAllRedirectURIs    bool     `yaml:"allow_all_redirect_uris"`
}

type DatabaseConfig struct {
	DSN          string `yaml:"dsn"`
	MaxOpenConns int    `yaml:"max_open_conns"`
}

type ElicitationConfig struct {
	// Enabled is the master switch for all elicitation features.
	// Enabled by default (nil = enabled); set enabled: false to disable.
	Enabled *bool `yaml:"enabled"`

	// CostEstimation configures query cost estimation and confirmation.
	CostEstimation CostEstimationConfig `yaml:"cost_estimation"`

	// PIIConsent configures PII access consent.
	PIIConsent PIIConsentConfig `yaml:"pii_consent"`
}

type EmbeddingConfig struct {
	Provider string            `yaml:"provider"` // "ollama" or "noop"
	Ollama   OllamaEmbedConfig `yaml:"ollama"`
}

type EnrichmentConfig struct {
	// The four cross-enrichment flags default to true (nil = enabled). They are
	// the platform's core differentiator and are read-only: each no-ops safely
	// when its provider (semantic / query / storage) is absent, so defaulting on
	// is safe and removes the need to opt every deployment into enrichment. Set
	// the flag to false explicitly to disable. Read via the Is*Enabled helpers.
	TrinoSemanticEnrichment  *bool              `yaml:"trino_semantic_enrichment"`
	DataHubQueryEnrichment   *bool              `yaml:"datahub_query_enrichment"`
	S3SemanticEnrichment     *bool              `yaml:"s3_semantic_enrichment"`
	DataHubStorageEnrichment *bool              `yaml:"datahub_storage_enrichment"`
	EstimateRowCounts        bool               `yaml:"estimate_row_counts"`
	SessionDedup             SessionDedupConfig `yaml:"session_dedup"`

	// UnwrapJSON defaults the unwrap_json parameter to true on trino_query
	// and trino_execute, so single-row VARCHAR-of-JSON responses (e.g. from
	// OpenSearch/Elasticsearch raw_query) are returned as parsed objects
	// instead of double-encoded strings. Defaults to true (nil = enabled).
	UnwrapJSON *bool `yaml:"unwrap_json"`

	// ColumnContextFiltering limits column-level semantic enrichment to
	// columns referenced in the SQL query. Saves tokens when queries
	// touch a subset of a wide table. Defaults to true (nil = enabled).
	ColumnContextFiltering *bool `yaml:"column_context_filtering"`

	// SearchSchemaPreview adds a bounded column-name+type preview to
	// datahub_search query_context, eliminating the intermediate
	// datahub_get_schema or trino_describe_table call before writing SQL.
	// Defaults to true (nil = enabled).
	SearchSchemaPreview *bool `yaml:"search_schema_preview"`

	// SchemaPreviewMaxColumns caps how many columns appear in each
	// schema preview. Defaults to 15 (nil = 15).
	SchemaPreviewMaxColumns *int `yaml:"schema_preview_max_columns"`

	// SemanticFallback enables the issue #444 fallback path: when a
	// URN-equality lookup for a Trino table misses on the semantic
	// provider, the platform calls SearchTables with Mode=semantic
	// and surfaces the top hit as a SUGGESTED match (annotated with
	// match_kind=semantic so the model knows it is similarity-
	// inferred, not URN-resolved). Audit rows record
	// enrichment_match_kind so operators can measure false-positive
	// rate. Default off. Requires the semantic provider to support
	// the "semantic" search mode (DataHub does as of v1.8.1).
	SemanticFallback *bool `yaml:"semantic_fallback"`

	// SemanticFallbackTopK is how many similarity-search hits the
	// fallback surfaces per miss. Default 1. Caps at 10 to keep
	// suggested-match output bounded; operators wanting broader
	// recall should adjust persona scope or query patterns, not
	// flood the response with low-rank suggestions.
	SemanticFallbackTopK *int `yaml:"semantic_fallback_top_k"`

	// MemoryLimit caps how many memory records the platform recalls and
	// renders into the memory_context enrichment block per tool call.
	// Defaults to 5 (nil = 5). Issue #761.
	MemoryLimit *int `yaml:"memory_limit"`

	// MemoryContextBudgetBytes bounds the byte size of the rendered memory
	// summaries appended per tool call. Records beyond the budget are listed
	// as compact id+reference stubs (still fetchable, not dropped); at least
	// one record is always rendered. Defaults to 1500 (nil = 1500). Set to 0
	// to disable the budget (render every recalled record). Issue #761.
	MemoryContextBudgetBytes *int `yaml:"memory_context_budget_bytes"`

	// MemorySummaryBytes caps each rendered memory record to a summary-first
	// excerpt so the agent fetches the full record by reference only when it
	// matters. Defaults to 280 (nil = 280). Set to 0 to render full content.
	// Issue #761.
	MemorySummaryBytes *int `yaml:"memory_summary_bytes"`
}

type Features struct {
	SemanticEnrichment bool                `json:"semantic_enrichment"`
	QueryEnrichment    bool                `json:"query_enrichment"`
	StorageEnrichment  bool                `json:"storage_enrichment"`
	AuditLogging       bool                `json:"audit_logging"`
	KnowledgeCapture   bool                `json:"knowledge_capture"`
	KnowledgeApply     *KnowledgeApplyInfo `json:"knowledge_apply,omitempty"`
	ManagedResources   bool                `json:"managed_resources"`
}

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

type IconDef struct {
	// Source is the icon URL (HTTP/HTTPS) or data URI.
	Source string `yaml:"src"`

	// MIMEType is the optional MIME type (e.g., "image/svg+xml").
	MIMEType string `yaml:"mime_type,omitempty"`
}

type IconsConfig struct {
	// Enabled is the master switch for icon injection.
	// Enabled by default (nil = enabled); set enabled: false to disable.
	Enabled *bool `yaml:"enabled"`

	// Tools maps tool names to their icon definitions.
	Tools map[string]IconDef `yaml:"tools"`

	// Resources maps resource URI templates to their icon definitions.
	Resources map[string]IconDef `yaml:"resources"`

	// Prompts maps prompt names to their icon definitions.
	Prompts map[string]IconDef `yaml:"prompts"`
}

type ImplementorConfig struct {
	Name string `yaml:"name"` // display name (e.g., "ACME Corp")
	Logo string `yaml:"logo"` // URL to logo SVG (fetched at startup for inline rendering)
	URL  string `yaml:"url"`  // link URL (e.g., "https://acme.com")
}

type Info struct {
	Name                string                `json:"name"`
	Version             string                `json:"version"`
	Description         string                `json:"description,omitempty"`
	Tags                []string              `json:"tags,omitempty"`
	SessionID           string                `json:"session_id,omitempty"`
	SessionExpiresAt    string                `json:"session_expires_at,omitempty"`
	AgentInstructions   string                `json:"agent_instructions,omitempty"`
	Toolkits            []string              `json:"toolkits"`
	ToolkitDescriptions map[string]string     `json:"toolkit_descriptions,omitempty"`
	PortalURL           string                `json:"portal_url,omitempty"`
	Persona             *PersonaInfo          `json:"persona,omitempty"`
	Prompts             []registry.PromptInfo `json:"prompts,omitempty"`
	Features            Features              `json:"features"`
	ConfigVersion       ConfigVersionInfo     `json:"config_version"`
}

type KnowledgeApplyConfig struct {
	Enabled             *bool  `yaml:"enabled"`
	DataHubConnection   string `yaml:"datahub_connection"`
	RequireConfirmation bool   `yaml:"require_confirmation"`
}

type KnowledgeApplyInfo struct {
	Enabled           bool             `json:"enabled"`
	DataHubConnection string           `json:"datahub_connection,omitempty"`
	ReviewQueue       *ReviewQueueInfo `json:"review_queue,omitempty"`
}

type KnowledgeConfig struct {
	Enabled *bool                          `yaml:"enabled"`
	Apply   KnowledgeApplyConfig           `yaml:"apply"`
	Pages   knowledgepage.PageGuardsConfig `yaml:"pages"` // write guards (#705); see knowledgepage
	// ReflexiveCapture configures auto-capture of query-error corrections (#635):
	// when a query errors and a later related query on the same connection
	// succeeds in the same session, the platform mints a "misconception + fix"
	// memory. Captures enter review (reviewed sink-class), so the blast radius is
	// a pending insight, not live catalog state. Auto-enabled with the memory
	// subsystem; see pkg/platform/reflexivecapture.
	ReflexiveCapture reflexivecapture.Config `yaml:"reflexive_capture"`

	// SearchProviderTimeout bounds each knowledge provider arm in the `search`
	// fan-out; default 5s, a negative value disables it.
	SearchProviderTimeout time.Duration `yaml:"search_provider_timeout"`
	// SearchEmbedTimeout bounds the serial intent-embedding step in `search`,
	// independent of the fan-out bound; default 5s, a negative value disables it.
	SearchEmbedTimeout time.Duration `yaml:"search_embed_timeout"`
}

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

type MCPAppsConfig struct {
	// Enabled is the master switch for MCP Apps support.
	// Nil (not set) defaults to true — the built-in platform-info app is always registered.
	// Set to false explicitly to disable all MCP Apps.
	Enabled *bool `yaml:"enabled"`

	// Apps configures individual MCP Apps.
	Apps map[string]AppConfig `yaml:"apps"`
}

type ManagedResourcesCfg struct {
	Enabled      *bool  `yaml:"enabled"`       // nil = auto (enabled when DB available)
	URIScheme    string `yaml:"uri_scheme"`    // default: "mcp"
	S3Connection string `yaml:"s3_connection"` // name of S3 toolkit instance
	S3Bucket     string `yaml:"s3_bucket"`     // bucket for resource blobs (default: "managed-resources")
}

type MemoryConfig struct {
	Enabled   *bool           `yaml:"enabled"`
	Embedding EmbeddingConfig `yaml:"embedding"`
	Staleness StalenessConfig `yaml:"staleness"`
}

type NoopAPIKeyStore struct{}

type NoopConnectionStore struct{}

type OAuthClientConfig struct {
	ID           string   `yaml:"id"`
	Secret       string   `yaml:"secret"` // #nosec G117 -- API key secret from admin YAML config
	RedirectURIs []string `yaml:"redirect_uris"`
}

type OAuthConfig struct {
	Enabled    bool   `yaml:"enabled"`
	Issuer     string `yaml:"issuer"`
	SigningKey string `yaml:"signing_key"` // Base64-encoded HMAC key for JWT signing
	// PreviousSigningKeys are base64-encoded HMAC keys retained for verification
	// only after a signing-key rotation. New tokens are always signed with
	// SigningKey; tokens minted with a prior key still verify while that key
	// remains here. Rotate in two phases (add the new key here as verify-only
	// everywhere first, then promote it to signing_key) so no replica signs with
	// a key its peers have not yet learned; see the "Rotating the signing key"
	// runbook in docs/auth/oauth-server.md.
	PreviousSigningKeys []string `yaml:"previous_signing_keys"`
	// AllowEphemeralSigningKey permits an HTTP deployment to boot without a
	// configured signing_key, generating a per-process key instead. UNSAFE for
	// multi-replica deployments: each replica mints tokens its peers reject.
	// Intended only for single-replica HTTP dev setups. Default false.
	AllowEphemeralSigningKey bool                 `yaml:"allow_ephemeral_signing_key"`
	Clients                  []OAuthClientConfig  `yaml:"clients"`
	DCR                      DCRConfig            `yaml:"dcr"`
	RateLimit                OAuthRateLimitConfig `yaml:"rate_limit"`
	Upstream                 *UpstreamIDPConfig   `yaml:"upstream,omitempty"`
}

type OAuthRateLimitConfig struct {
	Enabled *bool `yaml:"enabled"`
	// TrustedProxies lists CIDRs whose X-Forwarded-For headers are trusted for
	// client attribution. Empty (the default) trusts none: the direct peer
	// address is used and forwarding headers are ignored, which is the correct
	// safe default when the deployment's proxy topology is unknown.
	TrustedProxies []string           `yaml:"trusted_proxies"`
	Token          OAuthRateLimitRule `yaml:"token"`    // default: 60 rpm, burst 10
	Register       OAuthRateLimitRule `yaml:"register"` // default: 10 rpm, burst 3
}

type OAuthRateLimitRule struct {
	RequestsPerMinute int `yaml:"requests_per_minute"`
	Burst             int `yaml:"burst"`
}

type OIDCAuthConfig struct {
	Enabled       bool     `yaml:"enabled"`
	Issuer        string   `yaml:"issuer"`
	ClientID      string   `yaml:"client_id"`
	ClientSecret  string   `yaml:"client_secret"` // #nosec G117 -- OIDC secret from admin config
	Audience      string   `yaml:"audience"`
	RoleClaimPath string   `yaml:"role_claim_path"`
	RolePrefix    string   `yaml:"role_prefix"`
	Scopes        []string `yaml:"scopes"` // default: [openid, profile, email]
}

type ObservabilityConfig struct {
	Prometheus PrometheusConfig `yaml:"prometheus"`
}

type OllamaEmbedConfig struct {
	URL     string        `yaml:"url"`
	Model   string        `yaml:"model"`
	Timeout time.Duration `yaml:"timeout"`
	// MaxInputBytes caps the byte length of each text sent to Ollama.
	// Zero selects embedding.DefaultMaxInputBytes. Raise it only when
	// running an embedding model with a larger context than
	// nomic-embed-text's 2048 tokens. See embedding.DefaultMaxInputBytes
	// and #623.
	MaxInputBytes int `yaml:"max_input_bytes"`
}

type Option func(*Options)

type Options struct {
	// Config is the platform configuration.
	Config *Config

	// Database connection (optional, will be created from config if not provided).
	DB *sql.DB

	// SemanticProvider (optional, will be created from config if not provided).
	SemanticProvider semantic.Provider

	// QueryProvider (optional, will be created from config if not provided).
	QueryProvider query.Provider

	// StorageProvider (optional, will be created from config if not provided).
	StorageProvider storage.Provider

	// Authenticator (optional, will be created from config if not provided).
	Authenticator middleware.Authenticator

	// Authorizer (optional, will be created from config if not provided).
	Authorizer middleware.Authorizer

	// AuditLogger (optional, will be created from config if not provided).
	// The audit middleware invokes Log synchronously on the tool-call path
	// (the enqueue is expected to be non-blocking), so an injected logger
	// MUST NOT block on storage — wrap a slow sink in audit.NewAsyncWriter,
	// as the default config-created logger does (#884). The config-created
	// path is already backed by a bounded async writer.
	AuditLogger middleware.AuditLogger

	// PersonaRegistry (optional, will be created from config if not provided).
	PersonaRegistry *persona.Registry

	// ToolkitRegistry (optional, will be created if not provided).
	ToolkitRegistry *registry.Registry

	// RuleEngine (optional, will be created from config if not provided).
	RuleEngine *tuning.RuleEngine

	// SessionStore (optional, will be created from config if not provided).
	SessionStore session.Store

	// ConnectionStore (optional, will be created from config if not provided).
	// Allows tests to inject a controlled instance store without standing
	// up a real database, and lets advanced embedders provide alternative
	// persistence backends.
	ConnectionStore ConnectionStore
}

type PIIConsentConfig struct {
	// Enabled controls whether PII table access triggers elicitation.
	// Enabled by default (nil = enabled); set enabled: false to disable.
	Enabled *bool `yaml:"enabled"`
}

type PersonaDef struct {
	DisplayName string             `yaml:"display_name"`
	Description string             `yaml:"description,omitempty"`
	Roles       []string           `yaml:"roles"`
	Tools       ToolRulesDef       `yaml:"tools"`
	Connections ConnectionRulesDef `yaml:"connections"`
	Context     ContextDef         `yaml:"context"`
	Priority    int                `yaml:"priority,omitempty"`
}

type PersonaInfo struct {
	Name        string `json:"name"`
	DisplayName string `json:"display_name"`
	Description string `json:"description,omitempty"`
}

type PersonasConfig struct {
	Definitions    map[string]PersonaDef `yaml:",inline"`
	DefaultPersona string                `yaml:"default_persona"`
	RoleMapping    RoleMappingConfig     `yaml:"role_mapping"`
}

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

type PortalConfig struct {
	Enabled         *bool                 `yaml:"enabled"`
	Title           string                `yaml:"title"`             // sidebar/branding title (default: "MCP Data Platform")
	Tagline         string                `yaml:"tagline"`           // login-screen subtitle (default: "Sign in to access the platform.")
	OIDCButtonLabel string                `yaml:"oidc_button_label"` // login-screen SSO button text (default: "Sign in with OIDC")
	Logo            string                `yaml:"logo"`              // URL to logo (fallback for both themes)
	LogoLight       string                `yaml:"logo_light"`        // URL to logo for light theme
	LogoDark        string                `yaml:"logo_dark"`         // URL to logo for dark theme
	S3Connection    string                `yaml:"s3_connection"`     // name of the S3 toolkit instance to use
	S3Bucket        string                `yaml:"s3_bucket"`         // bucket for artifact storage (default: "portal-assets")
	S3Prefix        string                `yaml:"s3_prefix"`         // key prefix within the bucket (default: "artifacts/")
	PublicBaseURL   string                `yaml:"public_base_url"`   // base URL for portal links (e.g., "https://portal.example.com")
	MaxContentSize  int                   `yaml:"max_content_size"`  // max artifact size in bytes (default: 10MB)
	Implementor     ImplementorConfig     `yaml:"implementor"`       // optional implementor brand (far-left header zone)
	RateLimit       PortalRateLimitConfig `yaml:"rate_limit"`
	Export          PortalExportConfig    `yaml:"export"` // trino_export configuration
}

type PortalExportConfig struct {
	Enabled        *bool  `yaml:"enabled"`         // auto-enabled when portal+trino are configured
	MaxRows        int    `yaml:"max_rows"`        // hard row cap (default: 100000)
	MaxBytes       int64  `yaml:"max_bytes"`       // hard byte cap (default: 100MB)
	DefaultTimeout string `yaml:"default_timeout"` // default query timeout (default: "5m")
	MaxTimeout     string `yaml:"max_timeout"`     // max query timeout (default: "10m")
}

type PortalRateLimitConfig struct {
	RequestsPerMinute int `yaml:"requests_per_minute"` // default: 60
	BurstSize         int `yaml:"burst_size"`          // default: 10
	// TrustedProxies lists CIDRs whose X-Forwarded-For headers are trusted for
	// client attribution, mirroring oauth.rate_limit.trusted_proxies. Empty (the
	// default) trusts none: the direct peer address is used and forwarding
	// headers are ignored, which is the correct safe default when the
	// deployment's proxy topology is unknown. Set this to your reverse-proxy or
	// ingress CIDRs so per-client limiting attributes to the real client instead
	// of collapsing onto the proxy IP.
	TrustedProxies []string `yaml:"trusted_proxies"`
}

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

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

type ProgressConfig struct {
	Enabled *bool `yaml:"enabled"`
}

type PrometheusConfig struct {
	URL       string          `yaml:"url"`
	Timeout   time.Duration   `yaml:"timeout"`
	BasicAuth BasicAuthConfig `yaml:"basic_auth"`
	// RateLimitPerSecond caps proxied queries per persona per second.
	// Zero selects the default (10).
	RateLimitPerSecond int `yaml:"rate_limit_per_second"`
}

type PromptArgumentConfig struct {
	Name        string `yaml:"name"`
	Description string `yaml:"description"`
	Required    bool   `yaml:"required"`
}

type PromptConfig struct {
	Name        string                 `yaml:"name"`
	Description string                 `yaml:"description"`
	Content     string                 `yaml:"content"`
	Arguments   []PromptArgumentConfig `yaml:"arguments"`
}

type QueryConfig struct {
	Provider   string           `yaml:"provider"` // "trino", "noop"
	Instance   string           `yaml:"instance"`
	URNMapping URNMappingConfig `yaml:"urn_mapping"`
}

type RateLimitConfig struct {
	// Enabled toggles the limiter. Enabled by default (nil = enabled); set
	// enabled: false to remove the limiter from the chain entirely. The
	// generous default keeps default-on safe for existing deployments.
	Enabled *bool `yaml:"enabled"`

	// RequestsPerMinute is the sustained per-user tools/call rate. Non-positive
	// values fall back to the default (defaultRateLimitRPM).
	RequestsPerMinute int `yaml:"requests_per_minute"`

	// Burst is the token-bucket depth: the largest instantaneous burst a single
	// user may issue before the sustained rate governs. Non-positive values fall
	// back to the default (defaultRateLimitBurst).
	Burst int `yaml:"burst"`

	// ExemptTools lists tool names that are never rate limited. platform_info is
	// always exempt (added implicitly) so a throttled agent can still re-read
	// the platform guidance it needs to back off intelligently; add others here.
	ExemptTools []string `yaml:"exempt_tools"`
}

type ResourcesConfig struct {
	// Enabled gates the schema/glossary/availability resource templates and the
	// DataHub->Trino resource links (ResourceLinksEnabled). Read-only serving, so
	// it defaults to true (nil = enabled); set false to disable. Read via IsEnabled.
	Enabled *bool               `yaml:"enabled"`
	Custom  []CustomResourceDef `yaml:"custom"`  // always registered when non-empty
	Managed ManagedResourcesCfg `yaml:"managed"` // human-uploaded resources via portal
}

type ReviewQueueInfo struct {
	Pending              int `json:"pending"`
	OldestPendingAgeDays int `json:"oldest_pending_age_days,omitempty"`
	PendingOver30d       int `json:"pending_over_30d,omitempty"`
}

type RoleMappingConfig struct {
	OIDCToPersona map[string]string `yaml:"oidc_to_persona"`
}

type RulesConfig struct {
	QualityThreshold float64 `yaml:"quality_threshold"`
}

type RuntimeConfig struct {
	// Transport is the resolved server transport ("stdio", "http", or "sse").
	Transport string
	// Address is the server's listen address (e.g. ":8080"). It supplies the
	// port for the loopback base URL of the platform-admin self-connection.
	Address string
}

type SemanticConfig struct {
	Provider   string                        `yaml:"provider"` // "datahub", "noop"
	Instance   string                        `yaml:"instance"`
	Cache      CacheConfig                   `yaml:"cache"`
	URNMapping URNMappingConfig              `yaml:"urn_mapping"`
	Lineage    datahubsemantic.LineageConfig `yaml:"lineage"`
}

type ServerConfig struct {
	Name              string           `yaml:"name"`
	Version           string           `yaml:"version"`
	Description       string           `yaml:"description"`
	Tags              []string         `yaml:"tags"`               // Discovery keywords for routing
	AgentInstructions string           `yaml:"agent_instructions"` // Inline operational guidance for AI agents
	Prompts           []PromptConfig   `yaml:"prompts"`            // Platform-level MCP prompts
	BuiltinPrompts    map[string]bool  `yaml:"builtin_prompts"`    // Enable/disable built-in workflow prompts
	Transport         string           `yaml:"transport"`          // "stdio", "http" (or "sse" for backward compat)
	Address           string           `yaml:"address"`
	TLS               TLSConfig        `yaml:"tls"`
	Streamable        StreamableConfig `yaml:"streamable"`
	Shutdown          ShutdownConfig   `yaml:"shutdown"`
}

type SessionDedupConfig = dedup.Config

type SessionGateConfig struct {
	// Enabled activates the session initialization gate.
	Enabled bool `yaml:"enabled"`

	// InitTool is the tool that initializes the session (default: "platform_info").
	InitTool string `yaml:"init_tool"`

	// ExemptTools lists tool names that bypass the gate (e.g., "list_connections").
	ExemptTools []string `yaml:"exempt_tools"`
}

type SessionHandlesConfig struct {
	// Enabled activates handle minting, schema advertisement, and validation.
	// Default on (nil = enabled); set enabled: false for byte-identical legacy
	// transport-session behavior.
	Enabled *bool `yaml:"enabled"`

	// TTL is the handle lifetime, refreshed on use. Defaults to 8h.
	TTL time.Duration `yaml:"ttl"`

	// Require refuses any gated tool call that does not carry a valid
	// platform_info-minted handle (SESSION_REQUIRED). A transport session is not
	// accepted as a fallback (issue #800). Default on (nil = required); set
	// require: false for a softer landing during rollout, where a handle-less
	// call falls back to the transport session instead of being refused.
	Require *bool `yaml:"require"`
}

type SessionsConfig struct {
	// Store selects the session storage backend: "memory" (default) or "database".
	Store string `yaml:"store"`

	// TTL is the session lifetime. Defaults to streamable.session_timeout.
	TTL time.Duration `yaml:"ttl"`

	// CleanupInterval is how often the cleanup routine runs. Defaults to 1m.
	CleanupInterval time.Duration `yaml:"cleanup_interval"`

	// BroadcastChannel overrides the postgres LISTEN/NOTIFY channel name
	// used for cross-replica MCP notification fan-out. Defaults to
	// "mcp_notifications". Override when multiple deployments share a
	// single postgres instance and must NOT cross-broadcast
	// tools/list_changed events to each other's downstream agents.
	BroadcastChannel string `yaml:"broadcast_channel"`

	// Handles configures explicit session handles (issue #792). When enabled,
	// platform_info mints a session_id that the model threads back as an
	// ordinary argument on every subsequent tool call — the pattern the MCP
	// 2026-07-28 spec recommends after removing the protocol-level session and
	// the Mcp-Session-Id header (SEP-2567).
	Handles SessionHandlesConfig `yaml:"handles"`
}

type ShutdownConfig struct {
	// GracePeriod is the maximum time to drain in-flight requests after
	// receiving a shutdown signal. Defaults to 25s (fits within K8s 30s
	// terminationGracePeriodSeconds with headroom for pre-shutdown delay).
	GracePeriod time.Duration `yaml:"grace_period"`

	// PreShutdownDelay is the time to sleep after marking the pod as
	// not-ready and before starting the HTTP drain. This gives the K8s
	// load balancer time to deregister the pod. Defaults to 2s.
	PreShutdownDelay time.Duration `yaml:"pre_shutdown_delay"`
}

type StalenessConfig struct {
	Enabled   bool          `yaml:"enabled"`
	Interval  time.Duration `yaml:"interval"`
	BatchSize int           `yaml:"batch_size"`
}

type StorageConfig struct {
	Provider string `yaml:"provider"` // "s3", "noop"
	Instance string `yaml:"instance"`
}

type StreamableConfig struct {
	// SessionTimeout is how long an idle session persists before cleanup.
	// Defaults to 30 minutes.
	SessionTimeout time.Duration `yaml:"session_timeout"`
	// Stateless disables session tracking (no Mcp-Session-Id validation).
	Stateless bool `yaml:"stateless"`
}

type TLSConfig struct {
	Enabled  bool   `yaml:"enabled"`
	CertFile string `yaml:"cert_file"`
	KeyFile  string `yaml:"key_file"`
}

type ToolInfo struct {
	Name string
	Kind string
}

type ToolRulesDef struct {
	Allow []string `yaml:"allow"`
	Deny  []string `yaml:"deny"`
}

type ToolsConfig struct {
	Allow                []string          `yaml:"allow"`
	Deny                 []string          `yaml:"deny"`
	DescriptionOverrides map[string]string `yaml:"description_overrides"`
}

type TuningConfig struct {
	Rules      RulesConfig `yaml:"rules"`
	PromptsDir string      `yaml:"prompts_dir"`
}

type URNMappingConfig struct {
	// Platform overrides the platform name used in DataHub URN building.
	// For example, if Trino queries a PostgreSQL database, set this to "postgres"
	// so URNs match DataHub's platform identifier.
	Platform string `yaml:"platform"`

	// CatalogMapping maps catalog names between systems.
	// For semantic provider: maps Trino catalogs to DataHub catalogs (rdbms → warehouse)
	// For query provider: maps DataHub catalogs to Trino catalogs (warehouse → rdbms)
	CatalogMapping map[string]string `yaml:"catalog_mapping"`
}

type UpstreamIDPConfig struct {
	Issuer       string `yaml:"issuer"`        // OIDC issuer URL (any OIDC-compliant IdP, e.g. Keycloak)
	ClientID     string `yaml:"client_id"`     // MCP Server's client ID in the upstream IdP
	ClientSecret string `yaml:"client_secret"` // #nosec G117 -- MCP Server's client secret from admin YAML config
	RedirectURI  string `yaml:"redirect_uri"`  // Callback URL (e.g., http://localhost:8080/oauth/callback)

	// AuthorizationEndpoint and TokenEndpoint optionally override OIDC discovery.
	// By default the broker discovers these from
	// <issuer>/.well-known/openid-configuration; set them only for IdPs whose
	// discovery document is broken or unreachable. Discovery is skipped entirely
	// only when BOTH are set.
	AuthorizationEndpoint string `yaml:"authorization_endpoint,omitempty"`
	TokenEndpoint         string `yaml:"token_endpoint,omitempty"`
}

type VersionConverter func(data []byte) (*Config, error)

type VersionInfo struct {
	// Version is the version string (e.g., "v1").
	Version string

	// Status is the lifecycle state of this version.
	Status VersionStatus

	// DeprecationMessage is shown when a deprecated version is loaded.
	DeprecationMessage string

	// MigrationGuide is shown when a removed version is loaded.
	MigrationGuide string

	// Converter transforms raw YAML bytes into a Config. Nil means
	// standard YAML unmarshalling is used (i.e., the version matches
	// the current schema).
	Converter VersionConverter
}

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

type VersionStatus int

type WorkflowConfig struct {
	// RequireSearch is the search-first hard gate. Enabled by default
	// (nil = enabled); set require_search: false to fully disable gating.
	// When enabled, query tools are refused (the handler never runs) until a
	// discovery tool has been called at least once in the session.
	RequireSearch *bool `yaml:"require_search"`

	// DiscoveryTools lists tool names that satisfy the gate.
	// Defaults to just "search", the universal discovery front door.
	DiscoveryTools []string `yaml:"discovery_tools"`

	// QueryTools lists tool names that are gated by discovery.
	// Defaults to trino_query and trino_execute.
	QueryTools []string `yaml:"query_tools"`
}