config

type AuthConfig struct {
	// Type is the auth mechanism: "bearer" or "api_key".
	Type string `yaml:"type"`
	// Token is the expected token value (supports env var references via $VAR or ${VAR}).
	Token string `yaml:"token"`
	// Header is the header name for api_key auth (default: "Authorization").
	Header string `yaml:"header,omitempty"`
}

type AutoscaleConfig struct {
	// Min is the minimum number of healthy replicas to maintain.
	// >= 0. Must be >= 1 when IdleToZero is false.
	Min int `yaml:"min" json:"min"`
	// Max is the upper bound on replica count. >= 1, >= Min, <= 32.
	Max int `yaml:"max" json:"max"`
	// TargetInFlight is the per-replica in-flight request count the scaler
	// tries to hold the median at or below. >= 1.
	TargetInFlight int `yaml:"target_in_flight" json:"target_in_flight"`
	// ScaleUpAfter is how long the window median must exceed the target
	// before spawning a replica. Default 30s. Minimum 10s.
	ScaleUpAfter string `yaml:"scale_up_after,omitempty" json:"scale_up_after,omitempty"`
	// ScaleDownAfter is how long the window median must be below the target
	// before reaping a replica. Default 5m. Minimum 1m.
	ScaleDownAfter string `yaml:"scale_down_after,omitempty" json:"scale_down_after,omitempty"`
	// WarmPool keeps this many extra idle-ready replicas above the load-derived
	// target at all times. Default 0. Must satisfy Min + WarmPool <= Max.
	WarmPool int `yaml:"warm_pool,omitempty" json:"warm_pool,omitempty"`
	// IdleToZero allows the scaler to reap every replica after a sustained
	// idle. Min may be 0 only when IdleToZero is true. Default false.
	IdleToZero bool `yaml:"idle_to_zero,omitempty" json:"idle_to_zero,omitempty"`
}

type ClientProfile struct {
	// Aliases are raw clientInfo.name values that should resolve to this
	// profile, for reconciling a wire identity that differs from the profile
	// key without relying on the built-in normalization heuristic.
	Aliases []string `yaml:"aliases,omitempty"`
	// Servers is an allow-list of MCP server names. Empty means all servers.
	Servers []string `yaml:"servers,omitempty"`
	// Tools is an allow-list of prefixed tool names. Empty means all tools
	// within the allowed servers.
	Tools []string `yaml:"tools,omitempty"`
}

type ClientsConfig struct {
	// Default is the policy for clients that match no profile: "deny" (the
	// default when empty) or "allow".
	Default string `yaml:"default,omitempty"`
	// Profiles maps a stable client identifier to its access allow-list.
	Profiles map[string]ClientProfile `yaml:"profiles,omitempty"`
}

type Consumer struct {
	Kind  ReferenceKind `json:"kind"`
	Name  string        `json:"name,omitempty"`
	Field string        `json:"field"`

	// Target names the workload a scoped secrets.sets entry injects into, and
	// TargetKind says whether that is a server or a resource. Both are set only
	// on RefKindSecretsSet consumers built from a scoped set: one such consumer
	// is synthesized per receiving workload, so the UI can name and navigate to
	// each one. An unscoped set fans out to everything and produces a single
	// consumer with both fields empty.
	//
	// Name keeps holding the set name in every case. Callers that ask "is this
	// variable's own set actively injected" compare against Name, so widening
	// that field to mean the workload would silently break them.
	Target     string        `json:"target,omitempty"`
	TargetKind ReferenceKind `json:"targetKind,omitempty"`
}

type DependencyStatus struct {
	Status  string   `json:"status"` // "resolved", "missing"
	Missing []string `json:"missing,omitempty"`
}

type DiffAction string

type DiffItem struct {
	Action  DiffAction `json:"action"`
	Kind    string     `json:"kind"` // "mcp-server", "agent", "resource", "a2a-agent", "gateway", "network"
	Name    string     `json:"name"`
	Details []string   `json:"details,omitempty"` // human-readable change descriptions
}

type DriftStatus struct {
	Status  string   `json:"status"` // "in-sync", "drifted", "unknown"
	Added   []string `json:"added,omitempty"`
	Removed []string `json:"removed,omitempty"`
	Changed []string `json:"changed,omitempty"`
}

type GatewayConfig struct {
	// Name overrides the identity the gateway announces to MCP clients in the
	// initialize response (serverInfo.name). Some clients (VS Code / GitHub
	// Copilot) display this value rather than the entry key from their own
	// config file, so distinct gateways need distinct names to be told apart.
	// Empty keeps the default "gridctl-gateway".
	Name string `yaml:"name,omitempty" json:"name,omitempty"`

	// AllowedOrigins lists origins for CORS.
	// When not set, defaults to ["*"] (allow all) for backward compatibility.
	// Set explicit origins to restrict cross-origin access.
	AllowedOrigins []string `yaml:"allowed_origins,omitempty"`

	// Bind is the address the gateway's HTTP listener binds. When not set,
	// defaults to 127.0.0.1 (loopback only), so the API, web UI, and gateway
	// are unreachable from other hosts. Set "0.0.0.0" to listen on every
	// interface; the --bind and --bind-all flags override this field.
	// Widening the bind without setting auth logs a warning at startup.
	Bind string `yaml:"bind,omitempty"`

	// InsecureAllowUnauthenticated permits a non-loopback bind with no auth
	// configured. Without it gridctl refuses to start in that combination.
	// Exists alongside the --insecure-allow-unauthenticated flag because a
	// flag can be dropped by whatever wraps the process; a config field
	// survives that.
	InsecureAllowUnauthenticated bool `yaml:"insecure_allow_unauthenticated,omitempty"`

	// AllowedHosts lists additional Host header values accepted on the MCP
	// endpoint when a request arrives over loopback. Loopback hosts
	// (localhost, 127.0.0.0/8, ::1) are always accepted, so the default of
	// unset means loopback-only and needs no configuration. Set this only
	// when a reverse proxy or container hostname fronts the gateway.
	AllowedHosts []string    `yaml:"allowed_hosts,omitempty"`
	Auth         *AuthConfig `yaml:"auth,omitempty"`

	// CodeMode controls whether the gateway replaces individual tool definitions
	// with two meta-tools (search + execute). Values: "off" (default), "on".
	CodeMode string `yaml:"code_mode,omitempty"`
	// CodeModeTimeout is the execution timeout in seconds (default: 30).
	CodeModeTimeout int `yaml:"code_mode_timeout,omitempty"`

	// OutputFormat sets the default output format for tool call results.
	// Values: "json" (default), "toon", "csv", "text".
	// Per-server output_format overrides this value.
	OutputFormat string `yaml:"output_format,omitempty"`

	// MaxToolResultBytes sets the maximum size of a tool result in bytes before truncation.
	// Results exceeding this limit are truncated with a suffix indicating the original size.
	// Default: 65536 (64KB). Set to 0 to use the default.
	MaxToolResultBytes int `yaml:"maxToolResultBytes,omitempty" json:"maxToolResultBytes,omitempty"`

	// Tracing configures distributed tracing. When nil, tracing is enabled with defaults.
	Tracing *TracingConfig `yaml:"tracing,omitempty" json:"tracing,omitempty"`

	// Security configures security features such as schema pinning. When nil, defaults apply.
	Security *GatewaySecurityConfig `yaml:"security,omitempty" json:"security,omitempty"`

	// Tokenizer selects the token counting strategy.
	// Values: "embedded" (default) uses the cl100k_base BPE vocabulary (pure Go, no network).
	// "api" uses Anthropic's count_tokens endpoint for exact counts — Anthropic-specific,
	// requires network access and an API key, wrong for non-Anthropic model routing.
	Tokenizer string `yaml:"tokenizer,omitempty"`
	// TokenizerAPIKey overrides ANTHROPIC_API_KEY for the api tokenizer mode.
	// When unset, the api tokenizer falls back to the ANTHROPIC_API_KEY environment variable.
	TokenizerAPIKey string `yaml:"tokenizer_api_key,omitempty"`
}

type GatewaySecurityConfig struct {
	// SchemaPinning configures TOFU schema pinning for MCP tool definitions.
	SchemaPinning *SchemaPinningConfig `yaml:"schema_pinning,omitempty" json:"schema_pinning,omitempty"`
}

type GroupConfig struct {
	Description string `yaml:"description,omitempty" json:"description,omitempty"`
	// Servers includes every tool of the named stack servers.
	Servers []string `yaml:"servers,omitempty" json:"servers,omitempty"`
	// Tools includes specific prefixed tool names ("github__create_issue").
	Tools []string `yaml:"tools,omitempty" json:"tools,omitempty"`
	// Exclude subtracts prefixed tool names, applied after inclusion.
	Exclude []string `yaml:"exclude,omitempty" json:"exclude,omitempty"`
	// Overrides customizes individual member tools, keyed by canonical
	// prefixed name. Renames and rewrites exist only at this group's
	// exposure boundary; dispatch, scoping, limits, pins, and telemetry
	// always operate on canonical names.
	Overrides map[string]GroupOverride `yaml:"overrides,omitempty" json:"overrides,omitempty"`
}

type GroupOverride struct {
	// Name renames the tool at the exposure boundary (a flat alias, no
	// "__"). The canonical name still routes and is still accepted on call.
	Name string `yaml:"name,omitempty" json:"name,omitempty"`
	// Description replaces the tool's description verbatim. Empty keeps
	// the original.
	Description     string `yaml:"description,omitempty" json:"description,omitempty"`
	ReadOnlyHint    *bool  `yaml:"read_only_hint,omitempty" json:"read_only_hint,omitempty"`
	DestructiveHint *bool  `yaml:"destructive_hint,omitempty" json:"destructive_hint,omitempty"`
	IdempotentHint  *bool  `yaml:"idempotent_hint,omitempty" json:"idempotent_hint,omitempty"`
	OpenWorldHint   *bool  `yaml:"open_world_hint,omitempty" json:"open_world_hint,omitempty"`
}

type IssueSeverity string

type LimitsConfig struct {
	RateLimits []RateLimit `yaml:"rate_limits,omitempty" json:"rate_limits,omitempty"`
}

type LinkEntry struct {
	Client   string `yaml:"client" json:"client"`
	Group    string `yaml:"group,omitempty" json:"group,omitempty"`
	ClientID string `yaml:"client_id,omitempty" json:"client_id,omitempty"`
	Name     string `yaml:"name,omitempty" json:"name,omitempty"`
}

type LoadOption func(*loadConfig)

type LoggingConfig struct {
	// File is the path to the log file. When set, logs are written to both the
	// in-memory ring buffer (web UI) and this file simultaneously.
	File string `yaml:"file,omitempty" json:"file,omitempty"`
	// MaxSizeMB is the maximum log file size in megabytes before rotation (default: 100).
	MaxSizeMB int `yaml:"maxSizeMB,omitempty" json:"maxSizeMB,omitempty"`
	// MaxAgeDays is the maximum number of days to retain old log files (default: 7).
	MaxAgeDays int `yaml:"maxAgeDays,omitempty" json:"maxAgeDays,omitempty"`
	// MaxBackups is the maximum number of compressed old log files to keep (default: 3).
	MaxBackups int `yaml:"maxBackups,omitempty" json:"maxBackups,omitempty"`
}

type MCPServer struct {
	Name         string            `yaml:"name"`
	Image        string            `yaml:"image,omitempty"`
	Source       *Source           `yaml:"source,omitempty"`
	URL          string            `yaml:"url,omitempty"`       // External server URL (no container)
	Port         int               `yaml:"port,omitempty"`      // For HTTP transport (container-based)
	Transport    string            `yaml:"transport,omitempty"` // "http" (default), "stdio", or "sse"
	Command      []string          `yaml:"command,omitempty"`   // Override container command or remote command for SSH
	Env          map[string]string `yaml:"env,omitempty"`
	BuildArgs    map[string]string `yaml:"build_args,omitempty"`
	Network      string            `yaml:"network,omitempty"`       // Network to join (for multi-network mode)
	SSH          *SSHConfig        `yaml:"ssh,omitempty"`           // SSH connection config for remote servers
	OpenAPI      *OpenAPIConfig    `yaml:"openapi,omitempty"`       // OpenAPI spec config for API-backed servers
	Tools        []string          `yaml:"tools,omitempty"`         // Tool whitelist (empty = all tools exposed)
	OutputFormat string            `yaml:"output_format,omitempty"` // Output format override: "json", "toon", "csv", "text"
	PinSchemas   *bool             `yaml:"pin_schemas,omitempty"`   // Override gateway schema pinning for this server (nil = inherit)
	// ReadyTimeout overrides the HTTP/SSE readiness wait for container-based servers.
	// Accepts any time.Duration string (e.g. "60s", "2m"). Empty/"0" inherits the gateway default (30s).
	// Ignored for stdio, local process, SSH, OpenAPI, and external transports.
	ReadyTimeout string `yaml:"ready_timeout,omitempty"`

	// PingTimeout overrides the per-ping deadline used by the gateway health monitor.
	// Accepts any time.Duration string (e.g. "10s"). Empty/"0" inherits DefaultPingTimeout (5s).
	// Tune this for slow upstreams (e.g. HTTP servers with many tools) where the
	// 5s default can flake under autoscale spawn load.
	PingTimeout string `yaml:"ping_timeout,omitempty"`

	// ProtocolGeneration overrides MCP protocol-generation resolution for
	// this server: "auto" (default, same as empty) probes server/discover
	// and falls back to the initialize handshake; "handshake" and
	// "stateless" skip the probe and force one generation. An escape
	// hatch for peers the probe misclassifies; absent means today's
	// auto-negotiation exactly.
	ProtocolGeneration string `yaml:"protocol_generation,omitempty"`

	// Replicas is the number of independent processes to spawn for this server.
	// Defaults to 1. Values >1 load-balance JSON-RPC tool calls across replicas
	// using ReplicaPolicy. Not supported for external URL or OpenAPI transports.
	Replicas int `yaml:"replicas,omitempty" json:"replicas,omitempty"`

	// ReplicaPolicy selects the dispatch policy when Replicas > 1.
	// Valid values: "round-robin" (default), "least-connections".
	ReplicaPolicy string `yaml:"replica_policy,omitempty" json:"replica_policy,omitempty"`

	// Autoscale, when set, replaces the static Replicas count with reactive
	// autoscaling bounded by Min and Max. Mutually exclusive with Replicas.
	// Not supported on external URL or OpenAPI transports.
	Autoscale *AutoscaleConfig `yaml:"autoscale,omitempty" json:"autoscale,omitempty"`

	// Telemetry, when set, overrides stack-global telemetry persistence for
	// this server. nil fields inherit; *bool fields explicitly opt in or out.
	Telemetry *MCPServerTelemetry `yaml:"telemetry,omitempty" json:"telemetry,omitempty"`

	// Auth configures downstream authentication for external URL servers:
	// a static bearer token, a static custom header, or OAuth 2.1 brokering
	// handled by the gateway. nil (the default) preserves the existing
	// unauthenticated behavior. Only valid on external URL servers.
	Auth *ServerAuth `yaml:"auth,omitempty" json:"auth,omitempty"`
}

type MCPServerPersistence struct {
	Logs    *bool `yaml:"logs,omitempty" json:"logs,omitempty"`
	Metrics *bool `yaml:"metrics,omitempty" json:"metrics,omitempty"`
	Traces  *bool `yaml:"traces,omitempty" json:"traces,omitempty"`
}

type MCPServerTelemetry struct {
	Persist MCPServerPersistence `yaml:"persist,omitempty" json:"persist,omitempty"`
}

type ModelPreferenceScope struct {
	// Rewrite opts the scope into projection rewrite: projected files
	// carry the resolved preference, and affected skill projections are
	// forced to copy channel (status names the reason). Default false =
	// pure pass-through.
	Rewrite bool `yaml:"rewrite,omitempty" json:"rewrite,omitempty"`
	// Default applies where the author declared nothing.
	Default string `yaml:"default,omitempty" json:"default,omitempty"`
	// Overrides maps exact registry names (case-sensitive, no globs) to
	// the preference applied regardless of the author's declaration.
	// Unknown names warn at validate time but never error: the skill may
	// arrive later via pack.
	Overrides map[string]string `yaml:"overrides,omitempty" json:"overrides,omitempty"`
}

type ModelPreferencesConfig struct {
	// Skills is the policy for skill projections (pkg/skillsync).
	Skills *ModelPreferenceScope `yaml:"skills,omitempty" json:"skills,omitempty"`
	// Agents is the policy for agent projections (pkg/agentsync).
	Agents *ModelPreferenceScope `yaml:"agents,omitempty" json:"agents,omitempty"`
}

type Network struct {
	Name   string `yaml:"name"`
	Driver string `yaml:"driver"`
}

type OpenAPIAuth struct {
	Type     string `yaml:"type"`               // "bearer", "header", "query", "oauth2", or "basic"
	TokenEnv string `yaml:"tokenEnv,omitempty"` // Env var name containing bearer token (for type: bearer)
	Header   string `yaml:"header,omitempty"`   // Header name (for type: header, e.g., "X-API-Key")
	ValueEnv string `yaml:"valueEnv,omitempty"` // Env var name containing header value (for type: header or query)

	// Query param auth (type: query)
	ParamName string `yaml:"paramName,omitempty"` // Query parameter name (for type: query)

	// OAuth2 client credentials (type: oauth2)
	ClientIdEnv     string   `yaml:"clientIdEnv,omitempty"`     // Env var name containing OAuth2 client ID
	ClientSecretEnv string   `yaml:"clientSecretEnv,omitempty"` // Env var name containing OAuth2 client secret
	TokenUrl        string   `yaml:"tokenUrl,omitempty"`        // OAuth2 token endpoint URL
	Scopes          []string `yaml:"scopes,omitempty"`          // OAuth2 scopes to request

	// Basic auth (type: basic)
	UsernameEnv string `yaml:"usernameEnv,omitempty"` // Env var name containing username
	PasswordEnv string `yaml:"passwordEnv,omitempty"` // Env var name containing password
}

type OpenAPIConfig struct {
	Spec       string            `yaml:"spec"`                 // URL or local file path to OpenAPI spec (JSON or YAML)
	BaseURL    string            `yaml:"baseUrl,omitempty"`    // Override the server URL from the spec
	Auth       *OpenAPIAuth      `yaml:"auth,omitempty"`       // Authentication configuration
	TLS        *OpenAPITLS       `yaml:"tls,omitempty"`        // TLS/mTLS configuration (transport-layer)
	Operations *OperationsFilter `yaml:"operations,omitempty"` // Filter which operations become tools
}

type OpenAPITLS struct {
	CertFile           string `yaml:"certFile,omitempty"`           // Client certificate file path (required for mTLS)
	KeyFile            string `yaml:"keyFile,omitempty"`            // Client private key file path (required for mTLS)
	CaFile             string `yaml:"caFile,omitempty"`             // Custom CA certificate file path
	InsecureSkipVerify bool   `yaml:"insecureSkipVerify,omitempty"` // Skip server certificate verification (dangerous)
}

type OperationsFilter struct {
	Include []string `yaml:"include,omitempty"` // Operation IDs to include (whitelist)
	Exclude []string `yaml:"exclude,omitempty"` // Operation IDs to exclude (blacklist)
}

type PlanDiff struct {
	HasChanges bool       `json:"hasChanges"`
	Items      []DiffItem `json:"items"`
	Summary    string     `json:"summary"`
}

type RateLimit struct {
	Client string `yaml:"client,omitempty" json:"client,omitempty"`
	Server string `yaml:"server,omitempty" json:"server,omitempty"`
	Tool   string `yaml:"tool,omitempty" json:"tool,omitempty"`
	// CallsPerMinute is the sustained rate. Must be positive.
	CallsPerMinute int `yaml:"calls_per_minute" json:"calls_per_minute"`
	// Burst is the bucket capacity; 0 selects the default.
	Burst int `yaml:"burst,omitempty" json:"burst,omitempty"`
}

type ReferenceIndex map[string][]Consumer

type ReferenceKind string

type ReplicaHealth struct {
	ReplicaID        int    `json:"replicaId"`
	State            string `json:"state"` // "healthy" | "unhealthy" | "restarting"
	InFlight         int64  `json:"inFlight"`
	UptimeSeconds    int64  `json:"uptimeSeconds,omitempty"`
	LastError        string `json:"lastError,omitempty"`
	NextRetrySeconds int64  `json:"nextRetrySeconds,omitempty"`
	RestartAttempts  uint32 `json:"restartAttempts,omitempty"`
	PID              int    `json:"pid,omitempty"`
	ContainerID      string `json:"containerId,omitempty"`
}

type Resolver func(name string) (string, bool)

type Resource struct {
	Name    string            `yaml:"name"`
	Image   string            `yaml:"image"`
	Env     map[string]string `yaml:"env,omitempty"`
	Ports   []string          `yaml:"ports,omitempty"`
	Volumes []string          `yaml:"volumes,omitempty"`
	Network string            `yaml:"network,omitempty"` // Network to join (for multi-network mode)
}

type RetentionConfig struct {
	MaxSizeMB  int `yaml:"max_size_mb,omitempty" json:"max_size_mb,omitempty"`
	MaxBackups int `yaml:"max_backups,omitempty" json:"max_backups,omitempty"`
	MaxAgeDays int `yaml:"max_age_days,omitempty" json:"max_age_days,omitempty"`
}

type SSHConfig struct {
	Host           string `yaml:"host"`                     // Required: hostname or IP address
	User           string `yaml:"user"`                     // Required: SSH username
	Port           int    `yaml:"port,omitempty"`           // Optional: SSH port (default 22)
	IdentityFile   string `yaml:"identityFile,omitempty"`   // Optional: path to SSH private key
	KnownHostsFile string `yaml:"knownHostsFile,omitempty"` // Optional: path to known_hosts file; enables StrictHostKeyChecking=yes
	JumpHost       string `yaml:"jumpHost,omitempty"`       // Optional: bastion/jump host ([user@]host[:port])
}

type SchemaPinningConfig struct {
	// Enabled controls whether schema pinning is active. Default: true.
	// A pointer so an omitted `enabled:` inherits the default-on behavior
	// rather than YAML's zero value (false); set it explicitly to false to
	// disable pinning for the whole stack.
	Enabled *bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	// Action is the response when drift is detected: "warn" (default) or "block".
	// warn: log a structured diff and continue serving.
	// block: reject all tool calls from the drifted server until approved.
	Action string `yaml:"action,omitempty" json:"action,omitempty"`
	// Scan controls the poisoning heuristics run over tool definitions at
	// pin and drift time. Default: true. Findings are always advisory; this
	// toggle never affects hashing, drift detection, or the approve flow.
	Scan *bool `yaml:"scan,omitempty" json:"scan,omitempty"`
	// ScanIgnore suppresses scan findings by code (e.g. ["P004"]). Useful
	// for silencing a heuristic that false-positives on a legitimate stack.
	ScanIgnore []string `yaml:"scan_ignore,omitempty" json:"scan_ignore,omitempty"`
}

type SecretSetRef struct {
	Name      string   `yaml:"name" json:"name"`
	Servers   []string `yaml:"servers,omitempty" json:"servers,omitempty"`
	Resources []string `yaml:"resources,omitempty" json:"resources,omitempty"`
	// contains filtered or unexported fields
}

type Secrets struct {
	Sets []SecretSetRef `yaml:"sets,omitempty" json:"sets,omitempty"`
}

type ServerAuth struct {
	Type string `yaml:"type"` // "bearer", "header", or "oauth"

	// Static bearer token (type: bearer). Sent as "Authorization: Bearer <token>".
	// Use ${VAR} or ${var:KEY} references rather than literal secrets.
	Token string `yaml:"token,omitempty"`

	// Static header (type: header).
	Header string `yaml:"header,omitempty"` // header name, e.g. "X-API-Key"
	Value  string `yaml:"value,omitempty"`  // header value; use ${VAR} references

	// OAuth 2.1 brokering (type: oauth). All fields optional: scopes default
	// to what the server advertises, and a pre-registered client_id (plus
	// client_secret when the provider issued one) bypasses dynamic client
	// registration for authorization servers that do not support it.
	Scopes       []string `yaml:"scopes,omitempty"`
	ClientID     string   `yaml:"client_id,omitempty"`
	ClientSecret string   `yaml:"client_secret,omitempty"`
}

type SkillsPolicyConfig struct {
	// Default is the fate of a skill matching neither list: "allow" (the
	// default when empty) or "deny".
	Default string `yaml:"default,omitempty" json:"default,omitempty"`
	// Allow lists skill-name globs admitted even under default: deny.
	Allow []string `yaml:"allow,omitempty" json:"allow,omitempty"`
	// Deny lists skill-name globs hidden from exposure; deny beats allow.
	Deny []string `yaml:"deny,omitempty" json:"deny,omitempty"`
}

type Source struct {
	Type       string      `yaml:"type"` // "git" or "local"
	URL        string      `yaml:"url,omitempty"`
	Ref        string      `yaml:"ref,omitempty"`
	Path       string      `yaml:"path,omitempty"`
	Dockerfile string      `yaml:"dockerfile,omitempty"`
	Auth       *SourceAuth `yaml:"auth,omitempty"`
}

type SourceAuth struct {
	Method        string `yaml:"method,omitempty"`         // "", "none", "token", "ssh-agent", "ssh-key"
	CredentialRef string `yaml:"credential_ref,omitempty"` // e.g. "${vault:GIT_TOKEN}" — resolved on every clone/fetch
	SSHUser       string `yaml:"ssh_user,omitempty"`       // defaults to "git" when empty
	SSHKeyPath    string `yaml:"ssh_key_path,omitempty"`   // required for method "ssh-key"
}

type SpecHealth struct {
	Validation   ValidationStatus `json:"validation"`
	Drift        DriftStatus      `json:"drift"`
	Dependencies DependencyStatus `json:"dependencies"`

	// Replicas reports live per-replica health for every server that has
	// more than one replica registered. Servers with replicas <= 1 are
	// omitted so the shape is backward compatible with single-replica
	// deployments. Keyed by server name.
	Replicas map[string][]ReplicaHealth `json:"replicas,omitempty"`
}

type Stack struct {
	Version    string                 `yaml:"version"`
	Name       string                 `yaml:"name"`
	Extends    string                 `yaml:"extends,omitempty"` // Path to a parent stack file for composition
	Gateway    *GatewayConfig         `yaml:"gateway,omitempty"`
	Logging    *LoggingConfig         `yaml:"logging,omitempty"`
	Telemetry  *TelemetryConfig       `yaml:"telemetry,omitempty"` // Opt-in disk persistence for logs/metrics/traces
	Secrets    *Secrets               `yaml:"secrets,omitempty"`   // Variable set references
	Network    Network                `yaml:"network"`             // Single network (simple mode)
	Networks   []Network              `yaml:"networks,omitempty"`  // Multiple networks (advanced mode)
	MCPServers []MCPServer            `yaml:"mcp-servers"`
	Resources  []Resource             `yaml:"resources,omitempty"`
	Clients    *ClientsConfig         `yaml:"clients,omitempty"`                        // Optional per-client access scoping (NetworkPolicy semantics)
	Limits     *LimitsConfig          `yaml:"limits,omitempty" json:"limits,omitempty"` // Optional rate limits enforced at dispatch
	Groups     map[string]GroupConfig `yaml:"groups,omitempty" json:"groups,omitempty"` // Optional named tool bundles, each at /groups/{name}/mcp
	Skills     *SkillsPolicyConfig    `yaml:"skills,omitempty" json:"skills,omitempty"` // Optional global skill exposure policy (allow/deny name globs)

	// ModelPreferences is the optional top-level `model_preferences:`
	// block: per-scope model preference defaults and overrides applied to
	// skill and agent projections. Omitting the block preserves legacy
	// behavior; projections are byte-identical pass-throughs (Article
	// IX). Deliberately a sibling of Skills, never nested under it: the
	// `skills:` block is gateway exposure policy, an unrelated domain.
	// Not inherited across `extends` (matching clients/groups/limits).
	ModelPreferences *ModelPreferencesConfig `yaml:"model_preferences,omitempty" json:"model_preferences,omitempty"`

	// Link declares LLM clients that `gridctl apply` connects to this
	// stack's gateway once it is healthy. See LinkEntry for entry forms and
	// reconcile semantics. Empty (the default) preserves legacy behavior:
	// linking stays a manual `gridctl link` step. Not inherited across
	// `extends` (matching clients/groups/limits).
	Link []LinkEntry `yaml:"link,omitempty" json:"link,omitempty"`

	// Experimental enables registered experimental feature flags by name
	// (see pkg/flags for the registry and lifecycle). Omitted (the default)
	// enables nothing — Article IX by construction. Unknown, graduated, and
	// removed names warn at validate and apply time but never block a
	// deploy. Deliberately typed map[string]bool so YAML 1.1 boolean
	// spellings (on/yes) decode as booleans.
	Experimental map[string]bool `yaml:"experimental,omitempty" json:"experimental,omitempty"`

	// References is the variable-usage index, derived during expandStackVars:
	// which consumers reference each ${var:KEY}/${vault:KEY} key. It is computed
	// from the stack, not persisted with it — the yaml/json "-" tags keep it out
	// of every existing serialization path. Nil until a stack is loaded/expanded.
	References ReferenceIndex `yaml:"-" json:"-"`

	// UnresolvedRefs lists the ${var:KEY}/${vault:KEY} keys that the resolver
	// used at expansion time could not satisfy and that carry no default
	// operator, in first-seen order. It is the loader's own definition of
	// "missing": a reference written as ${var:KEY:-fallback} resolves to its
	// default and is deliberately absent here even though it still appears in
	// References.
	//
	// The meaning depends on the resolver. LoadStack with a vault yields keys
	// missing from vault and environment both, which is exactly what it refuses
	// to deploy. ValidateStackFile expands with the environment alone, so its
	// list is a superset that callers narrow by checking the vault themselves
	// (see the drift endpoint). Computed, never persisted.
	UnresolvedRefs []string `yaml:"-" json:"-"`
}

type TelemetryConfig struct {
	// Persist names which signals are written to disk by default. Per-server
	// blocks can override individual signals.
	Persist TelemetryPersistence `yaml:"persist,omitempty" json:"persist,omitempty"`
	// Retention controls lumberjack rotation for every persisted signal file.
	// SetDefaults fills sensible defaults when this block is omitted.
	Retention *RetentionConfig `yaml:"retention,omitempty" json:"retention,omitempty"`
}

type TelemetryPersistence struct {
	Logs    bool `yaml:"logs,omitempty" json:"logs,omitempty"`
	Metrics bool `yaml:"metrics,omitempty" json:"metrics,omitempty"`
	Traces  bool `yaml:"traces,omitempty" json:"traces,omitempty"`
}

type TracingConfig struct {
	// Enabled controls whether tracing is active. Default: true.
	// A pointer so an omitted `enabled:` inherits the default-on behavior
	// rather than YAML's zero value (false); set it explicitly to false to
	// disable tracing.
	Enabled *bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	// Sampling is the head-based sampling rate [0.0, 1.0]. Default: 1.0.
	Sampling float64 `yaml:"sampling,omitempty" json:"sampling,omitempty"`
	// Retention is how long completed traces are kept in memory (e.g. "24h"). Default: "24h".
	Retention string `yaml:"retention,omitempty" json:"retention,omitempty"`
	// Export selects an exporter: "otlp" or "" (none).
	Export string `yaml:"export,omitempty" json:"export,omitempty"`
	// Endpoint is the OTLP endpoint URL (e.g. "http://localhost:4318").
	Endpoint string `yaml:"endpoint,omitempty" json:"endpoint,omitempty"`
	// MaxTraces is the in-memory ring buffer capacity (number of traces). Default: 1000.
	MaxTraces int `yaml:"max_traces,omitempty" json:"max_traces,omitempty"`
	// IncludeInfra admits spans from non-gridctl instrumentation scopes (e.g.
	// Docker SDK HTTP self-instrumentation) into the UI trace buffer. Default: false.
	IncludeInfra bool `yaml:"include_infra,omitempty" json:"include_infra,omitempty"`
}

type ValidationError struct {
	Field   string
	Message string
}

type ValidationErrors []ValidationError

type ValidationIssue struct {
	Field    string        `json:"field"`
	Message  string        `json:"message"`
	Severity IssueSeverity `json:"severity"`
}

type ValidationResult struct {
	Valid        bool              `json:"valid"`
	ErrorCount   int               `json:"errorCount"`
	WarningCount int               `json:"warningCount"`
	Issues       []ValidationIssue `json:"issues"`
}

type ValidationStatus struct {
	Status       string `json:"status"` // "valid", "warnings", "errors"
	ErrorCount   int    `json:"errorCount"`
	WarningCount int    `json:"warningCount"`
}

type VaultLookup interface {
	Get(key string) (string, bool)
}

type VaultSecret struct {
	Key   string
	Value string
}

type VaultSetLookup interface {
	VaultLookup
	GetSetSecrets(setName string) []VaultSecret
}