config

type AutoExpandConfig struct {
	Enabled            bool   `toml:"enabled"`
	MaxDepth           int    `toml:"max_depth"`
	MaxNewSkillsPerRun int    `toml:"max_new_skills_per_run"`
	LLMProvider        string `toml:"llm_provider"` // "openai" | "anthropic" | "local" | "helixllm"
	LLMModel           string `toml:"llm_model"`
	// LLMAPIKey is resolved from the environment via ${VAR} interpolation
	// (e.g. "${ANTHROPIC_API_KEY}") -- NEVER a literal secret in tracked
	// config (§11.4.10). Empty is permitted; the provider client is still
	// constructed and the first real request surfaces the auth failure.
	LLMAPIKey string `toml:"llm_api_key"`
	// LLMBaseURL is REQUIRED for the "local"/"helixllm" providers (an
	// OpenAI-compatible chat-completions base URL) and ignored otherwise.
	LLMBaseURL string `toml:"llm_base_url"`
}

type CacheConfig struct {
	// Enabled turns the cache on. When false, a NoopCache is used and all
	// cache operations are no-ops (graceful degradation).
	Enabled bool `toml:"enabled"`
	// RedisURL is the Redis connection string (e.g. "redis://localhost:6379").
	RedisURL string `toml:"redis_url"`
	// SkillTTL is the TTL for cached skill content.
	SkillTTL time.Duration `toml:"skill_ttl"`
	// SearchTTL is the TTL for cached search results.
	SearchTTL time.Duration `toml:"search_ttl"`
	// TreeTTL is the TTL for cached dependency trees.
	TreeTTL time.Duration `toml:"tree_ttl"`
}

type CodeAnalysisConfig struct {
	Enabled         bool     `toml:"enabled"`
	Languages       []string `toml:"languages"`
	MaxFileSizeKB   int      `toml:"max_file_size_kb"`
	ExcludePatterns []string `toml:"exclude_patterns"`
	// AllowedRoot is the single allowlisted filesystem root that a submitted
	// project_path (learn_from_project MCP tool, and any other code-analysis
	// entry point) MUST canonicalize inside (§G31 path-traversal / LFI
	// guard -- GAPS_AND_RISKS_REGISTER.md). Canonicalization resolves
	// symlinks (filepath.EvalSymlinks) so a symlink planted inside
	// AllowedRoot cannot be used to escape it.
	//
	// FAIL-CLOSED BY DEFAULT: an empty AllowedRoot rejects EVERY
	// project_path submission rather than silently allow-listing the whole
	// filesystem (same fail-closed posture as Server.APIKeys/AuthDisabled
	// and Server.AllowedOrigins above). Operators MUST set this deliberately
	// to the directory tree learn_from_project is meant to scan (e.g. a
	// dedicated projects/workspaces root) before the tool accepts any
	// submission. Prefer the HELIX_CODEANALYSIS_ALLOWED_ROOT environment
	// override, or ${VAR} interpolation in the TOML value, so the path
	// never needs to be hardcoded into tracked config.
	AllowedRoot string `toml:"allowed_root"`
}

type CodeGraphConfig struct {
	Enabled             bool   `toml:"enabled"`
	Transport           string `toml:"transport"` // "stdio" | "http"
	Endpoint            string `toml:"endpoint"`  // HTTP endpoint (if transport=http)
	SyncIntervalSeconds int    `toml:"sync_interval_seconds"`
	AutoIndexOnLearn    bool   `toml:"auto_index_on_learn"`
	WatchEnabled        bool   `toml:"watch_enabled"` // requires fsnotify
}

type Config struct {
	Server       ServerConfig       `toml:"server"`
	Database     DatabaseConfig     `toml:"database"`
	Embedding    EmbeddingConfig    `toml:"embedding"`
	Validation   ValidationConfig   `toml:"validation"`
	AutoExpand   AutoExpandConfig   `toml:"autoexpand"`
	CodeAnalysis CodeAnalysisConfig `toml:"codeanalysis"`
	CodeGraph    CodeGraphConfig    `toml:"codegraph"`
	MCP          MCPConfig          `toml:"mcp"`
	Registry     RegistryConfig     `toml:"registry"`
	Logging      LoggingConfig      `toml:"logging"`
	Cache        CacheConfig        `toml:"cache"`
	Metrics      MetricsConfig      `toml:"metrics"`
	Tenant       TenantConfig       `toml:"tenant"`
	SourceSync   SourceSyncConfig   `toml:"source_sync"`
}

type DatabaseConfig struct {
	Host           string        `toml:"host"`
	Port           int           `toml:"port"`
	Database       string        `toml:"database"`
	User           string        `toml:"user"`
	Password       string        `toml:"password"`
	SSLMode        string        `toml:"ssl_mode"`
	MaxConnections int           `toml:"max_connections"`
	ConnectTimeout time.Duration `toml:"connect_timeout"`
	// Replica holds optional read-replica configuration. When a replica DSN is
	// provided, read operations are routed to the replica and writes go to the
	// primary. When empty, all traffic goes to the primary pool.
	Replica ReplicaConfig `toml:"replica"`
}

type EmbeddingConfig struct {
	Provider      string `toml:"provider"`       // "openai" | "local"
	Dimensions    int    `toml:"dimensions"`     // e.g. 768
	Model         string `toml:"model"`          // e.g. "text-embedding-3-small"
	APIKey        string `toml:"api_key"`        // OpenAI API key (env override recommended)
	LocalEndpoint string `toml:"local_endpoint"` // URL for local model server
}

type LoggingConfig struct {
	Level  string `toml:"level"`  // "debug" | "info" | "warn" | "error"
	Format string `toml:"format"` // "json" | "console"
}

type MCPConfig struct {
	Enabled   bool   `toml:"enabled"`
	Transport string `toml:"transport"` // "stdio" | "http"
}

type MetricsConfig struct {
	// Enabled turns metrics collection on. When false, the /metrics
	// endpoint is not registered and counters are not incremented.
	Enabled bool `toml:"enabled"`
	// Path is the HTTP path for the metrics endpoint (default "/metrics").
	Path string `toml:"path"`
}

type RateLimitConfig struct {
	// Enabled installs the limiter on the live router. Off leaves the surface
	// unthrottled (only appropriate behind a trusted upstream limiter).
	Enabled bool `toml:"enabled"`
	// RequestsPerSecond is the steady-state token refill rate per client key.
	RequestsPerSecond float64 `toml:"requests_per_second"`
	// Burst is the maximum instantaneous number of requests a single client key
	// may make before being throttled (the token-bucket depth).
	Burst int `toml:"burst"`
	// TTL is the idle window after which an unused per-client limiter entry is
	// reaped (housekeeping that releases long-idle keys).
	TTL time.Duration `toml:"ttl"`
	// MaxClients is the HARD upper bound on the number of distinct client keys
	// tracked at once. It — not the TTL reap — is what makes the tracking map
	// genuinely bounded: when the cap is reached the least-recently-used entry
	// is evicted, so a distinct-IP flood cannot grow the map without bound (F2).
	// A non-positive value falls back to a safe default in the limiter.
	MaxClients int `toml:"max_clients"`
}

type RegistryConfig struct {
	ReviewIntervalHours int     `toml:"review_interval_hours"`
	CoverageThreshold   float64 `toml:"coverage_threshold"`
}

type ReplicaConfig struct {
	// DSN is the PostgreSQL connection string for the read replica. When
	// empty the system falls back to the primary for all operations.
	DSN string `toml:"dsn"`
	// MaxLagSeconds is the maximum acceptable replication lag in seconds.
	// If the replica's lag exceeds this threshold, reads are routed to the
	// primary until the lag subsides. A value <= 0 disables lag checking.
	MaxLagSeconds int `toml:"max_lag_seconds"`
	// MaxConnections is the connection pool size for the replica.
	MaxConnections int `toml:"max_connections"`
}

type ServerConfig struct {
	Host         string `toml:"host"`
	HTTPPort     int    `toml:"http_port"`
	HTTP3Port    int    `toml:"http3_port"`
	EnableHTTP3  bool   `toml:"enable_http3"`
	EnableBrotli bool   `toml:"enable_brotli"`
	TLSCert      string `toml:"tls_cert"`
	TLSKey       string `toml:"tls_key"`
	// AllowedOrigins is the CORS allowlist of exact origins permitted to make
	// cross-origin requests (e.g. "https://app.example.com"). A single "*"
	// entry allows any origin but only without credentials. Empty (the default)
	// disallows all cross-origin access.
	AllowedOrigins []string `toml:"allowed_origins"`
	// APIKeys is the set of valid keys that authenticate /api/v1 requests via
	// the X-API-Key header. Prefer providing these through the HELIX_API_KEYS
	// environment override (comma-separated) so secrets never live in tracked
	// config (§11.4.10). When APIKeys is empty AND AuthDisabled is false, the
	// server fails CLOSED and refuses every /api/v1 request.
	APIKeys []string `toml:"api_keys"`
	// AuthDisabled explicitly runs the API with NO authentication. It must be
	// set deliberately and is logged loudly at startup. Absent keys without
	// this flag is a fail-closed error, never a silent open server.
	AuthDisabled bool `toml:"auth_disabled"`
	// RateLimit configures the per-client token-bucket limiter applied on the
	// live router BEFORE authentication (§G22 DoS hardening). Disabled leaves
	// the limiter off entirely.
	RateLimit RateLimitConfig `toml:"rate_limit"`
	// MaxRequestBodyBytes caps the accepted request body (§G22). A body whose
	// declared Content-Length exceeds this is rejected with 413 before it is
	// read, and streamed bodies are truncated at the cap. A value <= 0 falls
	// back to the 100 MiB default (api.DefaultMaxBodyBytes) in the router.
	MaxRequestBodyBytes int64 `toml:"max_request_body_bytes"`
}

type SourceSyncConfig struct {
	// Enabled turns on the source sync worker. When false, no automatic
	// sync cycles run, but manual syncs via MCP/REST are still available.
	Enabled bool `toml:"enabled"`
	// IntervalMinutes is how often the sync worker checks for sources
	// that need re-syncing (default 60).
	IntervalMinutes int `toml:"interval_minutes"`
	// MaxConcurrentSyncs is the maximum number of sources that can be
	// synced simultaneously (default 2).
	MaxConcurrentSyncs int `toml:"max_concurrent_syncs"`
	// LicenseAllowlist is the set of SPDX license identifiers that
	// permit redistribution of upstream skill content. An empty upstream
	// license is always treated as NOT allowed. An empty allowlist means
	// ALL licenses are gated (no body redistributed).
	LicenseAllowlist []string `toml:"license_allowlist"`
	// GitHubTokenEnv is the environment variable name that holds the
	// GitHub API token for source sync (default "HELIX_SOURCE_SYNC_GITHUB_TOKEN").
	GitHubTokenEnv string `toml:"github_token_env"`
}

type TenantConfig struct {
	// Required makes tenant resolution mandatory. When true, requests without
	// a resolvable tenant are rejected with 403. When false, unscoped requests
	// pass through (single-tenant backward compatibility).
	Required bool `toml:"required"`
	// DefaultTenant is the UUID of the fallback tenant used when no explicit
	// tenant is provided via header or API key mapping. Empty disables the
	// fallback.
	DefaultTenant string `toml:"default_tenant"`
	// APIKeyTenants maps API key strings to tenant UUIDs. When an authenticated
	// request's API key appears in this map, the corresponding tenant is used.
	APIKeyTenants map[string]string `toml:"api_key_tenants"`
	// RateLimit controls per-tenant rate limiting (§11.4.84). When enabled,
	// each tenant receives an independent token-bucket rate limiter.
	RateLimit TenantRateLimitConfig `toml:"rate_limit"`
}

type TenantRateLimitConfig struct {
	// Enabled installs the per-tenant rate limiter on the API router.
	Enabled bool `toml:"enabled"`
	// RequestsPerMinute is the steady-state refill rate per tenant.
	RequestsPerMinute int `toml:"requests_per_minute"`
	// BurstSize is the maximum instantaneous number of requests a tenant
	// may make before being throttled (token-bucket depth).
	BurstSize int `toml:"burst_size"`
}

type ValidationConfig struct {
	Enabled             bool `toml:"enabled"`
	JurySize            int  `toml:"jury_size"`          // number of validators
	ApprovalThreshold   int  `toml:"approval_threshold"` // votes required
	AutoApproveEvidence bool `toml:"auto_approve_evidence"`
	RequireHumanReview  bool `toml:"require_human_review"`
}