config

type AdministratorConfig struct {
	Provider    string `yaml:"provider" json:"provider"`                           // OAuth/SAML provider ID (required)
	ProviderId  string `yaml:"provider_id,omitempty" json:"provider_id,omitempty"` // Provider's user ID (for users, preferred)
	Email       string `yaml:"email,omitempty" json:"email,omitempty"`             // Provider's email (for users, fallback)
	GroupName   string `yaml:"group_name,omitempty" json:"group_name,omitempty"`   // Group name (for groups)
	SubjectType string `yaml:"subject_type" json:"subject_type"`                   // "user" or "group" (required)
}

type AlertingConfig struct {
	Enabled       bool   `yaml:"enabled" env:"TMI_ALERTING_ENABLED"`
	WebhookURL    string `yaml:"webhook_url" env:"TMI_ALERTING_WEBHOOK_URL"`
	WebhookSecret string `yaml:"webhook_secret" env:"TMI_ALERTING_WEBHOOK_SECRET"`
}

type AuthConfig struct {
	JWT                  JWTConfig    `yaml:"jwt"`
	OAuth                OAuthConfig  `yaml:"oauth"`
	SAML                 SAMLConfig   `yaml:"saml"`
	Cookie               CookieConfig `yaml:"cookie"`
	AutoPromoteFirstUser bool         `yaml:"auto_promote_first_user" env:"TMI_AUTH_AUTO_PROMOTE_FIRST_USER"`
	EveryoneIsAReviewer  bool         `yaml:"everyone_is_a_reviewer" env:"TMI_AUTH_EVERYONE_IS_A_REVIEWER"`
	BuildMode            string       `yaml:"build_mode" env:"TMI_BUILD_MODE"` // dev, test, or production
	// StepUpWindowSeconds controls how recent the auth_time JWT claim must be
	// for /admin/* writes (#355). Default 300 (5 minutes); minimum 60.
	StepUpWindowSeconds int `yaml:"step_up_window_seconds" env:"TMI_AUTH_STEP_UP_WINDOW_SECONDS"`
}

type CORSConfig struct {
	AllowedOrigins []string `yaml:"allowed_origins" env:"TMI_CORS_ALLOWED_ORIGINS"` // Comma-separated allowed origins
}

type Category int

type Config struct {
	Server                    ServerConfig            `yaml:"server"`
	Database                  DatabaseConfig          `yaml:"database"`
	Auth                      AuthConfig              `yaml:"auth"`
	WebSocket                 WebSocketConfig         `yaml:"websocket"`
	Webhooks                  WebhookConfig           `yaml:"webhooks"`
	Logging                   LoggingConfig           `yaml:"logging"`
	Operator                  OperatorConfig          `yaml:"operator"`
	Secrets                   SecretsConfig           `yaml:"secrets"`
	Administrators            []AdministratorConfig   `yaml:"administrators"`
	Timmy                     TimmyConfig             `yaml:"timmy"`
	SSRF                      SSRFConfig              `yaml:"ssrf"`
	Observability             ObservabilityConfig     `yaml:"observability"`
	ContentSources            ContentSourcesConfig    `yaml:"content_sources"`
	ContentExtractors         ContentExtractorsConfig `yaml:"content_extractors"`
	ContentOAuth              ContentOAuthConfig      `yaml:"content_oauth"`
	ContentTokenEncryptionKey string                  `yaml:"content_token_encryption_key" env:"TMI_CONTENT_TOKEN_ENCRYPTION_KEY"`
	Alerting                  AlertingConfig          `yaml:"alerting"`
	// contains filtered or unexported fields
}

type ConfigClass struct {
	Category   Category
	Secret     bool
	ValueKind  ValueKind
	Delivery   *Delivery // nil for CategoryBootstrap
	Visibility Visibility
	Mutability Mutability
	Consumers  []Consumer
	Required   bool
}

type ConfluenceConfig struct {
	Enabled bool `yaml:"enabled" env:"TMI_CONTENT_SOURCE_CONFLUENCE_ENABLED"`
}

type ConnectionPoolConfig struct {
	MaxOpenConns    int `yaml:"max_open_conns" env:"TMI_DB_MAX_OPEN_CONNS"`         // Maximum open connections (default: 10)
	MaxIdleConns    int `yaml:"max_idle_conns" env:"TMI_DB_MAX_IDLE_CONNS"`         // Maximum idle connections (default: 2)
	ConnMaxLifetime int `yaml:"conn_max_lifetime" env:"TMI_DB_CONN_MAX_LIFETIME"`   // Max connection lifetime in seconds (default: 240)
	ConnMaxIdleTime int `yaml:"conn_max_idle_time" env:"TMI_DB_CONN_MAX_IDLE_TIME"` // Max idle time in seconds (default: 30)
}

type Consumer int

type ContentExtractorsConfig struct {
	CompressedSizeBytes       int64         `yaml:"compressed_size_bytes" env:"TMI_CONTENT_EXTRACTORS_COMPRESSED_SIZE_BYTES"`
	DecompressedSizeBytes     int64         `yaml:"decompressed_size_bytes" env:"TMI_CONTENT_EXTRACTORS_DECOMPRESSED_SIZE_BYTES"`
	PartSizeBytes             int64         `yaml:"part_size_bytes" env:"TMI_CONTENT_EXTRACTORS_PART_SIZE_BYTES"`
	PPTXSlides                int           `yaml:"pptx_slides" env:"TMI_CONTENT_EXTRACTORS_PPTX_SLIDES"`
	XLSXCells                 int           `yaml:"xlsx_cells" env:"TMI_CONTENT_EXTRACTORS_XLSX_CELLS"`
	MarkdownSizeBytes         int64         `yaml:"markdown_size_bytes" env:"TMI_CONTENT_EXTRACTORS_MARKDOWN_SIZE_BYTES"`
	WallClockBudget           time.Duration `yaml:"wall_clock_budget" env:"TMI_CONTENT_EXTRACTORS_WALL_CLOCK_BUDGET"`
	PerUserConcurrencyDefault int           `yaml:"per_user_concurrency_default" env:"TMI_CONTENT_EXTRACTORS_PER_USER_CONCURRENCY_DEFAULT"`
	// AsyncEnabled routes extraction through the async worker pipeline instead
	// of inline processing. Requires NATS. Default false (inline mode).
	AsyncEnabled bool `yaml:"async_enabled" env:"TMI_EXTRACTION_ASYNC_ENABLED"`
}

type ContentOAuthConfig struct {
	CallbackURL            string                                `yaml:"callback_url" env:"TMI_CONTENT_OAUTH_CALLBACK_URL"`
	AllowedClientCallbacks []string                              `yaml:"allowed_client_callbacks"`
	Providers              map[string]ContentOAuthProviderConfig `yaml:"providers"`
}

type ContentOAuthProviderConfig struct {
	Enabled              bool              `yaml:"enabled"`
	Name                 string            `yaml:"name"`
	Icon                 string            `yaml:"icon"`
	ClientID             string            `yaml:"client_id"`
	ClientSecret         string            `yaml:"client_secret"`
	AuthURL              string            `yaml:"auth_url"`
	TokenURL             string            `yaml:"token_url"`
	UserinfoURL          string            `yaml:"userinfo_url"`
	RevocationURL        string            `yaml:"revocation_url"`
	RequiredScopes       []string          `yaml:"required_scopes"`
	ExtraAuthorizeParams map[string]string `yaml:"extra_authorize_params"`
}

type ContentSourcesConfig struct {
	GoogleDrive     GoogleDriveConfig     `yaml:"google_drive"`
	GoogleWorkspace GoogleWorkspaceConfig `yaml:"google_workspace"`
	Confluence      ConfluenceConfig      `yaml:"confluence"`
	Microsoft       MicrosoftConfig       `yaml:"microsoft"`
}

type CookieConfig struct {
	Enabled bool   `yaml:"enabled" env:"TMI_COOKIE_ENABLED"` // Enable HttpOnly cookie-based auth (default: true)
	Domain  string `yaml:"domain" env:"TMI_COOKIE_DOMAIN"`   // Cookie domain; leave empty for a host-only cookie (recommended). Never inferred from the bind address (#497).
	Secure  bool   `yaml:"secure" env:"TMI_COOKIE_SECURE"`   // Require HTTPS (auto-derived from TLSEnabled if not set)
}

type DatabaseConfig struct {
	URL                  string               `yaml:"url" env:"TMI_DATABASE_URL"`                              // Connection string URL (12-factor app pattern) - REQUIRED
	OracleWalletLocation string               `yaml:"oracle_wallet_location" env:"TMI_ORACLE_WALLET_LOCATION"` // Path to Oracle wallet directory (Oracle ADB only)
	ConnectionPool       ConnectionPoolConfig `yaml:"connection_pool"`
	Redis                RedisConfig          `yaml:"redis"`
}

type Delivery struct {
	// StampedIntoEnvelope: the monolith copies this into job envelopes.
	StampedIntoEnvelope bool
	// SharedInvariant: the monolith ALSO consumes this; ingest and the
	// monolith must agree. The validation suite enforces that SharedInvariant
	// implies StampedIntoEnvelope.
	SharedInvariant bool
}

type DiscoveredField struct {
	// DottedKey is the lower-snake-case dotted path produced from yaml
	// tags (e.g. "auth.cookie.enabled").
	DottedKey string

	// EnvVar is the value of the `env` struct tag on the leaf field, or
	// "" if absent. Used by the test to flag fields that should plumb a
	// TMI_* env var but don't.
	EnvVar string
}

type EmbeddingProfile struct {
	Model     string `json:"model"`
	Endpoint  string `json:"endpoint"`
	Dimension int    `json:"dimension"`
}

type Flags struct {
	ConfigFile     string
	GenerateConfig bool
	ShowVersion    bool
}

type GoogleDriveConfig struct {
	Enabled              bool   `yaml:"enabled" env:"TMI_CONTENT_SOURCE_GOOGLE_DRIVE_ENABLED"`
	ServiceAccountEmail  string `yaml:"service_account_email" env:"TMI_CONTENT_SOURCE_GOOGLE_DRIVE_SERVICE_ACCOUNT_EMAIL"`
	CredentialsFile      string `yaml:"credentials_file" env:"TMI_CONTENT_SOURCE_GOOGLE_DRIVE_CREDENTIALS_FILE"`
	BrowserOAuthClientID string `yaml:"browser_oauth_client_id" env:"TMI_CONTENT_SOURCE_GOOGLE_DRIVE_BROWSER_OAUTH_CLIENT_ID"`
	PickerDeveloperKey   string `yaml:"picker_developer_key" env:"TMI_CONTENT_SOURCE_GOOGLE_DRIVE_PICKER_DEVELOPER_KEY"`
	PickerAppID          string `yaml:"picker_app_id" env:"TMI_CONTENT_SOURCE_GOOGLE_DRIVE_PICKER_APP_ID"`
}

type GoogleWorkspaceConfig struct {
	Enabled            bool   `yaml:"enabled" env:"TMI_CONTENT_SOURCE_GOOGLE_WORKSPACE_ENABLED"`
	PickerDeveloperKey string `yaml:"picker_developer_key" env:"TMI_CONTENT_SOURCE_GOOGLE_WORKSPACE_PICKER_DEVELOPER_KEY"`
	PickerAppID        string `yaml:"picker_app_id" env:"TMI_CONTENT_SOURCE_GOOGLE_WORKSPACE_PICKER_APP_ID"`
}

type JWTConfig struct {
	Secret              string `yaml:"secret" env:"TMI_JWT_SECRET"`
	ExpirationSeconds   int    `yaml:"expiration_seconds" env:"TMI_JWT_EXPIRATION_SECONDS"`
	SigningMethod       string `yaml:"signing_method" env:"TMI_JWT_SIGNING_METHOD"`
	RefreshTokenDays    int    `yaml:"refresh_token_days" env:"TMI_REFRESH_TOKEN_DAYS"`       // Refresh token TTL in days (default: 7)
	SessionLifetimeDays int    `yaml:"session_lifetime_days" env:"TMI_SESSION_LIFETIME_DAYS"` // Absolute session lifetime in days (default: 7)
}

type LoggingConfig struct {
	// Level is the minimum log level to emit. One of: debug, info, warn, error.
	Level string `yaml:"level" env:"TMI_LOG_LEVEL"`
	// IsDev enables developer-friendly text formatting plus source file/line
	// tagging on every record. Production deployments should set this false.
	IsDev bool `yaml:"is_dev" env:"TMI_LOG_IS_DEV"`
	// IsTest forces test-mode behavior (e.g., stable timestamps).
	IsTest bool `yaml:"is_test" env:"TMI_LOG_IS_TEST"`
	// LogDir is the directory holding the active log file (tmi.log) and
	// rotated backups. Created on startup if missing. Default: "logs".
	LogDir string `yaml:"log_dir" env:"TMI_LOG_DIR"`
	// MaxAgeDays is the maximum number of days to retain rotated backup
	// files before lumberjack deletes them. 0 = retain indefinitely
	// (subject to MaxBackups). Default: 7.
	MaxAgeDays int `yaml:"max_age_days" env:"TMI_LOG_MAX_AGE_DAYS"`
	// MaxSizeMB is the maximum size of the active log file (logs/tmi.log)
	// in megabytes before lumberjack rotates it. The active file is renamed
	// with a timestamp suffix and a fresh tmi.log is opened. Default: 100.
	MaxSizeMB int `yaml:"max_size_mb" env:"TMI_LOG_MAX_SIZE_MB"`
	// MaxBackups is the maximum number of rotated backup files to retain.
	// 0 = retain all (subject to MaxAgeDays). Default: 10.
	MaxBackups int `yaml:"max_backups" env:"TMI_LOG_MAX_BACKUPS"`
	// AlsoLogToConsole, when true, mirrors every log line to stdout in
	// addition to the file. Useful in development. Default: true.
	AlsoLogToConsole bool `yaml:"also_log_to_console" env:"TMI_LOG_ALSO_LOG_TO_CONSOLE"`
	// CloudErrorThreshold is the number of consecutive cloud-sink write
	// failures observed at 60-second poll intervals before a single Warn
	// entry is emitted. Counter resets on a quiet interval. Set to 0 to
	// disable the alarm. Default: 5.
	CloudErrorThreshold int `yaml:"cloud_error_threshold" env:"TMI_LOG_CLOUD_ERROR_THRESHOLD"`

	// Enhanced debug logging options
	LogAPIRequests              bool `yaml:"log_api_requests" env:"TMI_LOG_API_REQUESTS"`
	LogAPIResponses             bool `yaml:"log_api_responses" env:"TMI_LOG_API_RESPONSES"`
	LogWebSocketMsg             bool `yaml:"log_websocket_messages" env:"TMI_LOG_WEBSOCKET_MESSAGES"`
	RedactAuthTokens            bool `yaml:"redact_auth_tokens" env:"TMI_LOG_REDACT_AUTH_TOKENS"`
	SuppressUnauthenticatedLogs bool `yaml:"suppress_unauthenticated_logs" env:"TMI_LOG_SUPPRESS_UNAUTH_LOGS"`
}

type MicrosoftConfig struct {
	Enabled             bool   `yaml:"enabled" env:"TMI_CONTENT_SOURCE_MICROSOFT_ENABLED"`
	TenantID            string `yaml:"tenant_id" env:"TMI_CONTENT_SOURCE_MICROSOFT_TENANT_ID"`
	ClientID            string `yaml:"client_id" env:"TMI_CONTENT_SOURCE_MICROSOFT_CLIENT_ID"`
	ApplicationObjectID string `yaml:"application_object_id" env:"TMI_CONTENT_SOURCE_MICROSOFT_APPLICATION_OBJECT_ID"`
	PickerOrigin        string `yaml:"picker_origin" env:"TMI_CONTENT_SOURCE_MICROSOFT_PICKER_ORIGIN"`
}

type MigratableSetting struct {
	Key         string
	Value       string
	Type        string
	Description string
	Secret      bool   // true = mask value in API responses (kept for back-compat; mirrors Class.Secret)
	Source      string // "config" or "environment"
	EnvVar      string // TMI_* environment variable that overrides this setting ("" if none)
	Class       ConfigClass
	// Explicit reports whether an operator actually supplied this value —
	// the env var is set, or the key was present in the YAML file — as
	// opposed to it being the struct default that every key carries.
	//
	// The settings service needs this to decide precedence. Source alone
	// cannot: it reports "config" both for "written in the file" and for
	// "nobody ever set this", and treating the latter as configured is what
	// made every operational database value unreachable (#415).
	Explicit bool
}

type Mutability int

type OAuthConfig struct {
	CallbackURL string                         `yaml:"callback_url" env:"TMI_OAUTH_CALLBACK_URL"`
	Providers   map[string]OAuthProviderConfig `yaml:"providers"`
	// ClientCallbackAllowList controls which client_callback URLs the
	// /oauth2/authorize endpoint is willing to redirect to after a successful
	// login. Each entry is either an exact URL or a wildcard pattern ending
	// in "*". An empty list rejects any client_callback (fail-closed). Set
	// via env TMI_OAUTH_CLIENT_CALLBACK_ALLOWLIST as a comma-separated list.
	ClientCallbackAllowList []string `yaml:"client_callback_allowlist" env:"TMI_OAUTH_CLIENT_CALLBACK_ALLOWLIST"`
}

type OAuthProviderConfig struct {
	ID               string             `yaml:"id"`
	Name             string             `yaml:"name"`
	Enabled          bool               `yaml:"enabled"`
	Icon             string             `yaml:"icon"`
	ClientID         string             `yaml:"client_id"`
	ClientSecret     string             `yaml:"client_secret"`
	AuthorizationURL string             `yaml:"authorization_url"`
	TokenURL         string             `yaml:"token_url"`
	UserInfo         []UserInfoEndpoint `yaml:"userinfo"`
	Issuer           string             `yaml:"issuer"`
	JWKSURL          string             `yaml:"jwks_url"`
	Scopes           []string           `yaml:"scopes"`
	AdditionalParams map[string]string  `yaml:"additional_params"`
	AuthHeaderFormat string             `yaml:"auth_header_format,omitempty"`
	AcceptHeader     string             `yaml:"accept_header,omitempty"`
}

type ObservabilityConfig struct {
	Enabled        bool    `yaml:"enabled" env:"TMI_OTEL_ENABLED"`
	SamplingRate   float64 `yaml:"sampling_rate" env:"TMI_OTEL_SAMPLING_RATE"`
	PrometheusPort int     `yaml:"prometheus_port" env:"TMI_OTEL_PROMETHEUS_PORT"`
}

type OperatorConfig struct {
	Name         string `yaml:"name" env:"TMI_OPERATOR_NAME"`
	Contact      string `yaml:"contact" env:"TMI_OPERATOR_CONTACT"`
	Jurisdiction string `yaml:"jurisdiction" env:"TMI_OPERATOR_JURISDICTION"`
}

type ProcessEnvVar struct {
	// Name is the exact variable name or, for a Pattern, the documented
	// shape with the operator-supplied part in angle brackets, e.g.
	// "TMI_SECRET_<KEY>"; the text before the first '<' is the prefix the
	// code scans for.
	Name string
	// Binary names the reader: "server", "rotator" or "workers" (chunkembed,
	// extractor, worker-probe, component-controller).
	Binary string
	// Purpose is the one-line operator-facing description. No angle
	// brackets, backticks or pipes — it is rendered into a Markdown table.
	Purpose string
	// Secret marks a value that must never be logged or echoed.
	Secret bool
	// Pattern marks Name as a prefix pattern rather than a fixed name.
	Pattern bool
}

type RedisConfig struct {
	URL        string `yaml:"url" env:"TMI_REDIS_URL"` // Connection string URL (redis://[:password@]host:port[/db]), takes precedence over individual fields; rediss:// also enables TLS
	Host       string `yaml:"host" env:"TMI_REDIS_HOST"`
	Port       string `yaml:"port" env:"TMI_REDIS_PORT"`
	Password   string `yaml:"password" env:"TMI_REDIS_PASSWORD"`
	DB         int    `yaml:"db" env:"TMI_REDIS_DB"`
	TLSEnabled bool   `yaml:"tls_enabled" env:"TMI_REDIS_TLS_ENABLED"` // Connect with TLS; the server cert is verified against tls_ca_file only
	TLSCAFile  string `yaml:"tls_ca_file" env:"TMI_REDIS_TLS_CA_FILE"` // PEM CA that signed the Redis server certificate (required when TLS is on)
}

type SAMLConfig struct {
	Enabled   bool                          `yaml:"enabled" env:"TMI_SAML_ENABLED"`
	Providers map[string]SAMLProviderConfig `yaml:"providers"`
}

type SAMLProviderConfig struct {
	ID                  string `yaml:"id"`
	Name                string `yaml:"name"`
	Enabled             bool   `yaml:"enabled"`
	Icon                string `yaml:"icon"`
	EntityID            string `yaml:"entity_id"`
	MetadataURL         string `yaml:"metadata_url"`
	MetadataXML         string `yaml:"metadata_xml"`
	ACSURL              string `yaml:"acs_url"`
	SLOURL              string `yaml:"slo_url"`
	SPPrivateKey        string `yaml:"sp_private_key"`
	SPPrivateKeyPath    string `yaml:"sp_private_key_path"`
	SPCertificate       string `yaml:"sp_certificate"`
	SPCertificatePath   string `yaml:"sp_certificate_path"`
	IDPMetadataURL      string `yaml:"idp_metadata_url"`
	IDPMetadataB64XML   string `yaml:"idp_metadata_b64xml"` // Base64-encoded IdP metadata XML
	AllowIDPInitiated   bool   `yaml:"allow_idp_initiated"`
	ForceAuthn          bool   `yaml:"force_authn"`
	SignRequests        bool   `yaml:"sign_requests"`
	NameIDAttribute     string `yaml:"name_id_attribute"`
	EmailAttribute      string `yaml:"email_attribute"`
	NameAttribute       string `yaml:"name_attribute"`
	GivenNameAttribute  string `yaml:"given_name_attribute"`
	FamilyNameAttribute string `yaml:"family_name_attribute"`
	GroupsAttribute     string `yaml:"groups_attribute"`
}

type SSRFConfig struct {
	IssueURI      SSRFURIConfig `yaml:"issue_uri"`
	DocumentURI   SSRFURIConfig `yaml:"document_uri"`
	RepositoryURI SSRFURIConfig `yaml:"repository_uri"`
	Timmy         SSRFURIConfig `yaml:"timmy"`
	Webhook       SSRFURIConfig `yaml:"webhook"`
}

type SSRFURIConfig struct {
	Allowlist string `yaml:"allowlist"`
	Schemes   string `yaml:"schemes"`
}

type SecretResolver interface {
	// ResolveVault returns the secret value stored at the given vault path.
	ResolveVault(ctx context.Context, path string) (string, error)
}

type SecretsConfig struct {
	Provider string `yaml:"provider" env:"TMI_SECRETS_PROVIDER"` // "env" (default), "file", "vault", "aws"

	// Directory holding one file per secret key (provider "file").
	FileDir string `yaml:"file_dir" env:"TMI_SECRETS_FILE_DIR"`

	// HashiCorp Vault (design only - implementation deferred)
	VaultAddress string `yaml:"vault_address" env:"TMI_VAULT_ADDRESS"`
	VaultToken   string `yaml:"vault_token" env:"TMI_VAULT_TOKEN"`
	VaultPath    string `yaml:"vault_path" env:"TMI_VAULT_PATH"`

	// AWS Secrets Manager
	AWSRegion     string `yaml:"aws_region" env:"TMI_AWS_REGION"`
	AWSSecretName string `yaml:"aws_secret_name" env:"TMI_AWS_SECRET_NAME"`
}

type ServerConfig struct {
	Port                string        `yaml:"port" env:"TMI_SERVER_PORT"`
	Interface           string        `yaml:"interface" env:"TMI_SERVER_INTERFACE"`
	BaseURL             string        `yaml:"base_url" env:"TMI_SERVER_BASE_URL"` // Public base URL for callbacks (auto-inferred if empty)
	ReadTimeout         time.Duration `yaml:"read_timeout" env:"TMI_SERVER_READ_TIMEOUT"`
	WriteTimeout        time.Duration `yaml:"write_timeout" env:"TMI_SERVER_WRITE_TIMEOUT"`
	IdleTimeout         time.Duration `yaml:"idle_timeout" env:"TMI_SERVER_IDLE_TIMEOUT"`
	TLSEnabled          bool          `yaml:"tls_enabled" env:"TMI_SERVER_TLS_ENABLED"`
	TLSCertFile         string        `yaml:"tls_cert_file" env:"TMI_SERVER_TLS_CERT_FILE"`
	TLSKeyFile          string        `yaml:"tls_key_file" env:"TMI_SERVER_TLS_KEY_FILE"`
	TLSSubjectName      string        `yaml:"tls_subject_name" env:"TMI_SERVER_TLS_SUBJECT_NAME"`
	HTTPToHTTPSRedirect bool          `yaml:"http_to_https_redirect" env:"TMI_SERVER_HTTP_TO_HTTPS_REDIRECT"`
	TrustedProxies      []string      `yaml:"trusted_proxies" env:"TMI_TRUSTED_PROXIES"`             // Comma-separated CIDRs/IPs for X-Forwarded-For validation
	RateLimitPublicRPM  int           `yaml:"ratelimit_public_rpm" env:"TMI_RATELIMIT_PUBLIC_RPM"`   // Requests/min per IP for public endpoints (default: 10)
	DisableRateLimiting bool          `yaml:"disable_rate_limiting" env:"TMI_DISABLE_RATE_LIMITING"` // Disable all rate limiting (dev/test only)
	// RequireIfMatch controls optimistic-locking enforcement on PUT/PATCH
	// (T14 / #385). When false (default this release), missing If-Match returns
	// a Deprecation/Warning header but the write proceeds. When true, missing
	// If-Match returns 428 Precondition Required. Flip to true in the next release.
	RequireIfMatch bool       `yaml:"require_if_match" env:"TMI_REQUIRE_IF_MATCH"`
	CORS           CORSConfig `yaml:"cors"`
}

type SettingDef struct {
	// Key is the canonical dotted setting key, e.g. "server.port".
	Key string
	// Class is the full classification: category, visibility, secrecy,
	// mutability, consumers, delivery.
	Class ConfigClass
	// Type is the value's canonical type: "string", "bool", "int",
	// "float", or "json".
	Type string
	// Description is human-readable and required; it feeds generated docs
	// and the admin API.
	Description string
	// Default is the canonical string form of the compiled-in default.
	// Required for operational settings, which have no config file to
	// fall back to.
	Default string

	// YAMLPath, EnvVar and Get are populated only for settings currently
	// delivered by config file or environment: all bootstrap settings, plus
	// operational settings still in transition (see Transitional).
	YAMLPath string
	EnvVar   string
	// Get extracts this setting's current value from a loaded Config as a
	// canonical string. Nil for settings with no config-file path.
	Get func(*Config) string

	// Transitional marks an operational setting that still has a config/env
	// delivery path during the Phase A-E cutover described in the spec.
	// Every Transitional entry is scheduled for removal in Phase E; the
	// ratchet test in Task 9 prevents new ones from being added.
	Transitional bool

	// Seeded marks an operational setting that is written into the
	// system_settings table on database initialisation. It is deliberately
	// explicit rather than inferred: the set of seeded keys does not
	// coincide with any other property of a setting, and inferring it wrong
	// would either seed rows nobody set or stop seeding rows the server
	// expects. Only operational settings may be Seeded.
	Seeded bool

	// OmitWhenEmpty reproduces the conditional emission of the pre-registry
	// builders: this setting is left out of GetMigratableSettings() entirely
	// when its value is empty, rather than emitted with an empty value.
	//
	// It is load-bearing, not cosmetic. DefaultOperationalSettings() feeds
	// both SeedDefaults (which would otherwise write a row per omitted key on
	// every fresh database) and #794's origin backfill (which uses the same
	// set to decide seeded-vs-explicit, and therefore env-vs-database
	// precedence on existing databases).
	//
	// Phase E removes this along with the rest of the transitional machinery.
	OmitWhenEmpty bool
}

type StampedConfig struct {
	Embedding EmbeddingProfile `json:"embedding"`
}

type StampedConfigProvider interface {
	Get(ctx context.Context) (StampedConfig, error)
}

type TimmyConfig struct {
	Enabled     bool   `yaml:"enabled" env:"TMI_TIMMY_ENABLED"`
	LLMProvider string `yaml:"llm_provider" env:"TMI_TIMMY_LLM_PROVIDER"`
	LLMModel    string `yaml:"llm_model" env:"TMI_TIMMY_LLM_MODEL"`
	LLMAPIKey   string `yaml:"llm_api_key" env:"TMI_TIMMY_LLM_API_KEY"`
	LLMBaseURL  string `yaml:"llm_base_url" env:"TMI_TIMMY_LLM_BASE_URL"`
	// LLMMaxTokens is the maximum tokens a chat completion may generate.
	// Anthropic's Messages API requires it on every request (#754 phase 2);
	// OpenAI's does not. Zero means "use the provider backend's default"
	// (internal/llm.anthropicDefaultMaxTokens for Anthropic; unset/provider
	// default for OpenAI) — see DefaultTimmyConfig for the seeded value.
	LLMMaxTokens                    int    `yaml:"llm_max_tokens" env:"TMI_TIMMY_LLM_MAX_TOKENS"`
	TextEmbeddingProvider           string `yaml:"text_embedding_provider" env:"TMI_TIMMY_TEXT_EMBEDDING_PROVIDER"`
	TextEmbeddingModel              string `yaml:"text_embedding_model" env:"TMI_TIMMY_TEXT_EMBEDDING_MODEL"`
	TextEmbeddingAPIKey             string `yaml:"text_embedding_api_key" env:"TMI_TIMMY_TEXT_EMBEDDING_API_KEY"`
	TextEmbeddingBaseURL            string `yaml:"text_embedding_base_url" env:"TMI_TIMMY_TEXT_EMBEDDING_BASE_URL"`
	EmbeddingDimension              int    `yaml:"embedding_dimension" env:"TMI_TIMMY_EMBEDDING_DIMENSION"`
	TextRetrievalTopK               int    `yaml:"text_retrieval_top_k" env:"TMI_TIMMY_TEXT_RETRIEVAL_TOP_K"`
	CodeEmbeddingProvider           string `yaml:"code_embedding_provider" env:"TMI_TIMMY_CODE_EMBEDDING_PROVIDER"`
	CodeEmbeddingModel              string `yaml:"code_embedding_model" env:"TMI_TIMMY_CODE_EMBEDDING_MODEL"`
	CodeEmbeddingAPIKey             string `yaml:"code_embedding_api_key" env:"TMI_TIMMY_CODE_EMBEDDING_API_KEY"`
	CodeEmbeddingBaseURL            string `yaml:"code_embedding_base_url" env:"TMI_TIMMY_CODE_EMBEDDING_BASE_URL"`
	CodeRetrievalTopK               int    `yaml:"code_retrieval_top_k" env:"TMI_TIMMY_CODE_RETRIEVAL_TOP_K"`
	QueryDecompositionEnabled       bool   `yaml:"query_decomposition_enabled" env:"TMI_TIMMY_QUERY_DECOMPOSITION_ENABLED"`
	RerankProvider                  string `yaml:"rerank_provider" env:"TMI_TIMMY_RERANK_PROVIDER"`
	RerankModel                     string `yaml:"rerank_model" env:"TMI_TIMMY_RERANK_MODEL"`
	RerankAPIKey                    string `yaml:"rerank_api_key" env:"TMI_TIMMY_RERANK_API_KEY"`
	RerankBaseURL                   string `yaml:"rerank_base_url" env:"TMI_TIMMY_RERANK_BASE_URL"`
	RerankTopK                      int    `yaml:"rerank_top_k" env:"TMI_TIMMY_RERANK_TOP_K"`
	MaxConversationHistory          int    `yaml:"max_conversation_history" env:"TMI_TIMMY_MAX_CONVERSATION_HISTORY"`
	OperatorSystemPrompt            string `yaml:"operator_system_prompt" env:"TMI_TIMMY_OPERATOR_SYSTEM_PROMPT"`
	MaxMemoryMB                     int    `yaml:"max_memory_mb" env:"TMI_TIMMY_MAX_MEMORY_MB"`
	InactivityTimeoutSeconds        int    `yaml:"inactivity_timeout_seconds" env:"TMI_TIMMY_INACTIVITY_TIMEOUT_SECONDS"`
	MaxMessagesPerUserPerHour       int    `yaml:"max_messages_per_user_per_hour" env:"TMI_TIMMY_MAX_MESSAGES_PER_USER_PER_HOUR"`
	MaxSessionsPerThreatModel       int    `yaml:"max_sessions_per_threat_model" env:"TMI_TIMMY_MAX_SESSIONS_PER_THREAT_MODEL"`
	MaxConcurrentLLMRequests        int    `yaml:"max_concurrent_llm_requests" env:"TMI_TIMMY_MAX_CONCURRENT_LLM_REQUESTS"`
	ChunkSize                       int    `yaml:"chunk_size" env:"TMI_TIMMY_CHUNK_SIZE"`
	ChunkOverlap                    int    `yaml:"chunk_overlap" env:"TMI_TIMMY_CHUNK_OVERLAP"`
	LLMTimeoutSeconds               int    `yaml:"llm_timeout_seconds" env:"TMI_TIMMY_LLM_TIMEOUT_SECONDS"`
	EmbeddingCleanupIntervalMinutes int    `yaml:"embedding_cleanup_interval_minutes" env:"TMI_TIMMY_EMBEDDING_CLEANUP_INTERVAL_MINUTES"`
	EmbeddingIdleDaysActive         int    `yaml:"embedding_idle_days_active" env:"TMI_TIMMY_EMBEDDING_IDLE_DAYS_ACTIVE"`
	EmbeddingIdleDaysClosed         int    `yaml:"embedding_idle_days_closed" env:"TMI_TIMMY_EMBEDDING_IDLE_DAYS_CLOSED"`

	// DumpExtractedTextToNote, when true, persists the markdown produced by
	// each successful content extraction as a Note on the parent threat
	// model. Dev/test inspection aid only — the server refuses to start
	// with this flag enabled if Auth.BuildMode == "production".
	DumpExtractedTextToNote bool `yaml:"dump_extracted_text_to_note" env:"TMI_TIMMY_DUMP_EXTRACTED_TEXT_TO_NOTE"`
}

type UserInfoEndpoint struct {
	URL    string            `yaml:"url" json:"url"`
	Claims map[string]string `yaml:"claims" json:"claims,omitempty"`
}

type ValueKind int

type Visibility int

type WebSocketConfig struct {
	InactivityTimeoutSeconds int `yaml:"inactivity_timeout_seconds" env:"TMI_WEBSOCKET_INACTIVITY_TIMEOUT_SECONDS"`
}

type WebhookConfig struct {
	AllowHTTPTargets bool `yaml:"allow_http_targets" env:"TMI_WEBHOOK_ALLOW_HTTP_TARGETS"` // Allow non-HTTPS webhook URLs (e.g., for intra-cluster communication)
}