config

type A2AAuth struct {
	Type  string `yaml:"type"`
	Token string `yaml:"token"`
}

type A2AConfig struct {
	Card     string   `yaml:"card"`
	Endpoint string   `yaml:"endpoint,omitempty"`
	Dialect  string   `yaml:"dialect,omitempty"`
	Profile  string   `yaml:"profile,omitempty"`
	Include  []string `yaml:"include,omitempty"`
	Timeout  string   `yaml:"timeout,omitempty"`
	Auth     *A2AAuth `yaml:"auth,omitempty"`
}

type AuthConfig struct {
	// Type is the auth mechanism: "bearer", "api_key", or "oauth".
	Type string `yaml:"type"`
	// Token is the expected token value (supports env var references via $VAR or ${VAR}).
	// Rejected when type is oauth.
	Token string `yaml:"token,omitempty"`
	// Header is the header name for api_key auth (default: "Authorization").
	// Rejected when type is oauth.
	Header string `yaml:"header,omitempty"`
	// Issuer is the authorization server issuer URL. Required when type is oauth.
	Issuer string `yaml:"issuer,omitempty"`
	// Audience is the expected aud value. Required when type is oauth.
	Audience string `yaml:"audience,omitempty"`
	// JWKSURL skips discovery and uses this key set. Optional.
	JWKSURL string `yaml:"jwks_url,omitempty"`
	// RequiredScopes lists scopes that must be present on an accepted token.
	RequiredScopes []string `yaml:"required_scopes,omitempty"`
	// IdentityClaim is the top-level string claim used as the access identifier.
	// Empty means "sub".
	IdentityClaim string `yaml:"identity_claim,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 BuildAction struct {
	Server              string        `json:"server"`
	SourceType          string        `json:"sourceType"`
	DeclaredIdentity    BuildIdentity `json:"declaredIdentity"`
	ResolvedIdentity    BuildIdentity `json:"resolvedIdentity,omitempty"`
	ImageTag            string        `json:"imageTag"`
	Cached              bool          `json:"cached"`
	CacheState          string        `json:"cacheState"`
	Error               string        `json:"error,omitempty"`
	MutableRef          bool          `json:"mutableRef,omitempty"`
	GeneratedDockerfile string        `json:"generatedDockerfile,omitempty"`
}

type BuildIdentity struct {
	Type           string `json:"type"`
	URL            string `json:"url,omitempty"`
	Ref            string `json:"ref,omitempty"`
	Path           string `json:"path,omitempty"`
	ProjectPath    string `json:"projectPath,omitempty"`
	Dockerfile     string `json:"dockerfile,omitempty"`
	Commit         string `json:"commit,omitempty"`
	Package        string `json:"package,omitempty"`
	Version        string `json:"version,omitempty"`
	Artifact       string `json:"artifact,omitempty"`
	ArtifactSHA256 string `json:"artifactSha256,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 ConfigFile struct {
	Target  string `yaml:"target" json:"target"`
	File    string `yaml:"file,omitempty" json:"file,omitempty"`
	Content string `yaml:"content,omitempty" json:"content,omitempty"`
	Mode    string `yaml:"mode,omitempty" json:"mode,omitempty"`
	UID     *int   `yaml:"uid,omitempty" json:"uid,omitempty"`
	GID     *int   `yaml:"gid,omitempty" json:"gid,omitempty"`
}

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

	// 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 DeclarationDiagnostic struct {
	Key       string `json:"key"`
	Code      string `json:"code"`
	Message   string `json:"message"`
	Consumers int    `json:"consumers"`
}

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", "resource", "gateway", "network"
	Name    string     `json:"name"`
	Details []string   `json:"details,omitempty"` // human-readable change descriptions
	// Override is true when a changed detail comes from an override file.
	Override bool `json:"override,omitempty"`
}

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 ExecutionConfig = execution.ExecutionConfig

type ExecutionContract = execution.ExecutionContract

type ExecutionMount = execution.ExecutionMount

type ExecutionTmpfs = execution.ExecutionTmpfs

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. On a loopback bind, empty
	// defaults to ["*"]. A non-loopback bind requires an explicit list that
	// does not contain "*", or the insecure override. "*" is not an allowlist.
	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.
	// gridctl refuses to start on a widened bind without auth and an origin
	// allowlist unless the insecure override is set.
	Bind string `yaml:"bind,omitempty"`

	// InsecureAllowUnauthenticated permits a non-loopback bind without auth
	// and without an explicit origin allowlist. One override covers both
	// refusals. Without it gridctl refuses to start in either 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"`

	// Description is an optional Server Card description, 1 to 100 characters
	// when set. Unset keeps the generated default. Read only by the card builder.
	Description string `yaml:"description,omitempty"`

	// PublicURL is the absolute http(s) origin the Server Card advertises,
	// with an optional port and path prefix and no userinfo, query, or
	// fragment. Unset leaves the card to a trusted Host, or omits remotes.
	// Read only by the card builder.
	PublicURL string `yaml:"public_url,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"`

	// ToolDiscovery controls whether tools/list returns the full catalog
	// (full, the default) or search_tools, call_tool, and the pinned set
	// (deferred). A nil block preserves today's behavior.
	ToolDiscovery *ToolDiscoveryConfig `yaml:"tool_discovery,omitempty" json:"tool_discovery,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.
	// The block, including headers, is read at startup. A change requires a restart.
	Tracing *TracingConfig `yaml:"tracing,omitempty" json:"tracing,omitempty"`

	// Metrics configures optional OTLP metrics export. When nil, no metrics are exported.
	// The block is read at startup, same as tracing. A change requires a restart.
	Metrics *MetricsConfig `yaml:"metrics,omitempty" json:"metrics,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 Layer struct {
	Pack   string `json:"pack"`
	Commit string `json:"commit"`
	Path   string `json:"file"`
	Dir    string `json:"-"`
	Stack  *Stack `json:"-"`
}

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"`
	Discovery string `yaml:"discovery,omitempty" json:"discovery,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 {
	Execution    *ExecutionConfig  `yaml:"execution,omitempty" json:"execution,omitempty"`
	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"`
	Volumes      []string          `yaml:"volumes,omitempty"` // Container mounts: host:container[:mode]
	Configs      []ConfigFile      `yaml:"configs,omitempty" json:"configs,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
	A2A          *A2AConfig        `yaml:"a2a,omitempty"`           // Experimental outbound Agent Card source
	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"`

	// Restart controls whether the health monitor restarts a managed stdio
	// container that inspect reports as not running. Empty means always.
	// on-failure:N requires N from 1 through 4294967295.
	// Accepted and unused on non-container servers.
	Restart string `yaml:"restart,omitempty" json:"restart,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"`

	// ProtocolExtensions declares client extensions the gateway sends on
	// its downstream initialize. The only accepted value is
	// "io.modelcontextprotocol/ui". Empty preserves today's handshake.
	ProtocolExtensions []string `yaml:"protocol_extensions,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"`

	// Headers are extra HTTP headers sent on every downstream request for
	// external URL and OpenAPI servers. Absent or empty preserves today's
	// behavior. Values are treated as sensitive.
	Headers map[string]string `yaml:"headers,omitempty" json:"headers,omitempty"`

	// Description is an operator note. It is accepted on every server kind,
	// preserved by export, and shown in status JSON. It is not a credential.
	Description string `yaml:"description,omitempty" json:"description,omitempty"`

	// Enabled controls whether this server is started and registered.
	// Nil and true are equivalent. False parks the server: it is still
	// validated, but it is not built, started, registered, health-checked,
	// or pinned. Absent preserves today's behavior (Article IX).
	Enabled *bool `yaml:"enabled,omitempty" json:"enabled,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 MetricsConfig struct {
	// OTLP is the HTTP/protobuf exporter. Required fields are validated when
	// the block is present.
	OTLP *OTLPMetricsConfig `yaml:"otlp,omitempty" json:"otlp,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 OTLPMetricsConfig struct {
	// Endpoint is the OTLP endpoint URL. Required when the block is present.
	// A pathless URL is posted to /v1/metrics. Any other path is used as-is.
	Endpoint string `yaml:"endpoint" json:"endpoint"`
	// Headers are sent on the export request. Values expand and are redacted
	// the same way as tracing headers.
	Headers map[string]string `yaml:"headers,omitempty" json:"headers,omitempty"`
	// Interval is how often the reader exports. Go duration string. Default 60s.
	// Minimum 1s.
	Interval string `yaml:"interval,omitempty" json:"interval,omitempty"`
	// Timeout is the export timeout. Go duration string. Default 10s.
	Timeout string `yaml:"timeout,omitempty" json:"timeout,omitempty"`
}

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 Override struct {
	MCPServers map[string]ServerOverride `yaml:"mcp-servers"`
}

type OverrideSelection struct {
	// Path is an explicit override file. Empty means discover
	// stack.override.yaml beside the stack file.
	Path string
	// Suppress ignores every override, including a discovered sibling.
	Suppress bool
	// Required makes a missing explicit Path an error. A discovered
	// sibling that is absent is never an error.
	Required bool
}

type PlanDiff struct {
	HasChanges          bool                    `json:"hasChanges"`
	Items               []DiffItem              `json:"items"`
	Summary             string                  `json:"summary"`
	VariableDiagnostics []DeclarationDiagnostic `json:"variableDiagnostics,omitempty"`
	Builds              []BuildAction           `json:"builds,omitempty"`
	// Override is the override file merged into the proposed stack.
	Override string `json:"override,omitempty"`
}

type PolicyConfig struct {
	// Default is the fate of a call matching no rule and not caught by
	// block_destructive: "allow" (the default when empty) or "block".
	Default string `yaml:"default,omitempty" json:"default,omitempty"`
	// BlockDestructive denies tools whose downstream annotations set
	// destructiveHint. It does not read group override hints. Default false.
	BlockDestructive bool `yaml:"block_destructive,omitempty" json:"block_destructive,omitempty"`
	// Rules are evaluated in order. The last matching rule wins.
	Rules []PolicyRule `yaml:"rules,omitempty" json:"rules,omitempty"`
}

type PolicyRule struct {
	// Match is a path.Match glob over the canonical prefixed tool name,
	// or a literal `server__tool` name.
	Match string `yaml:"match" json:"match"`
	// Action is "allow", "block", or "require_approval".
	Action string `yaml:"action" json:"action"`
}

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 {
	Execution         *execution.Report `json:"execution,omitempty"`
	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"`
	RestartPolicy     string            `json:"restartPolicy,omitempty"`
	RestartExhausted  bool              `json:"restartExhausted,omitempty"`
	ContainerRestarts uint32            `json:"containerRestarts,omitempty"`
}

type RequiresConfig struct {
	// Gridctl is a semver constraint the running gridctl must satisfy.
	// Empty means no constraint.
	Gridctl string `yaml:"gridctl,omitempty" json:"gridctl,omitempty"`
}

type RequiresError struct {
	Constraint string
	Running    string
	// Floor is the highest >= clause that satisfies Constraint, with no v
	// prefix. Empty when Constraint uses ||, or when no such clause exists.
	Floor  string
	Syntax bool
}

type ResolutionResult struct {
	Value   string
	Verdict ResolutionVerdict
	Error   error
}

type ResolutionVerdict string

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)

	// Enabled controls whether this resource is started. Nil and true are
	// equivalent. False parks the resource: it is still validated, but it
	// is not started. Absent preserves today's behavior (Article IX).
	Enabled *bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
}

type RestartPolicy struct {
	Mode string
	Max  uint32
	Raw  string
}

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 RunsConfig struct {
	Enabled    bool           `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	OmitLabels bool           `yaml:"omit_labels,omitempty" json:"omit_labels,omitempty"`
	Retention  *RunsRetention `yaml:"retention,omitempty" json:"retention,omitempty"`
}

type RunsRetention struct {
	MaxSizeMB  int `yaml:"max_size_mb,omitempty" json:"max_size_mb,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 SecretProvider struct {
	Name      string   `yaml:"name" json:"name"`
	Type      string   `yaml:"type" json:"type"`
	Command   []string `yaml:"command,omitempty" json:"command,omitempty"`
	Timeout   string   `yaml:"timeout,omitempty" json:"timeout,omitempty"`
	TokenFile string   `yaml:"token_file,omitempty" json:"token_file,omitempty"`
}

type SecretRef struct {
	Provider string `yaml:"-" json:"-"`
	Path     string `yaml:"-" json:"-"`
	Key      string `yaml:"-" json:"-"`
}

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"`
	Providers []SecretProvider `yaml:"providers,omitempty" json:"providers,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 ServerOverride struct {
	Enabled      *bool             `yaml:"enabled"`
	Env          map[string]string `yaml:"env"`
	Tools        []string          `yaml:"tools"`
	Replicas     *int              `yaml:"replicas"`
	Restart      *string           `yaml:"restart"`
	PingTimeout  *string           `yaml:"ping_timeout"`
	ReadyTimeout *string           `yaml:"ready_timeout"`
	OutputFormat *string           `yaml:"output_format"`
	Headers      map[string]string `yaml:"headers"`
	// contains filtered or unexported fields
}

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", "local", or "pypi"
	URL         string      `yaml:"url,omitempty"`
	Ref         string      `yaml:"ref,omitempty"`
	Path        string      `yaml:"path,omitempty"`
	ProjectPath string      `yaml:"project_path,omitempty"`
	Dockerfile  string      `yaml:"dockerfile,omitempty"`
	Runtime     string      `yaml:"runtime,omitempty"`
	Package     string      `yaml:"package,omitempty"`
	Python      string      `yaml:"python,omitempty"`
	Extras      []string    `yaml:"extras,omitempty"`
	With        []string    `yaml:"with,omitempty"`
	Packages    []string    `yaml:"packages,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"`

	// Override is the override file active for this health check.
	Override string `json:"override,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
	// Requires is an optional tool-version floor. Omitted means no
	// constraint (Article IX). Both the parent and the child constraints
	// apply across extends. Not accepted in an override file or a booster
	// fragment.
	Requires   *RequiresConfig  `yaml:"requires,omitempty" json:"requires,omitempty"`
	Gateway    *GatewayConfig   `yaml:"gateway,omitempty"`
	Logging    *LoggingConfig   `yaml:"logging,omitempty"`
	Telemetry  *TelemetryConfig `yaml:"telemetry,omitempty"` // Opt-in disk persistence for logs/metrics/traces
	Runs       *RunsConfig      `yaml:"runs,omitempty"`      // Opt-in metadata-only persisted dispatch records
	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
	// Policy is the optional top-level `policy:` block: ordered per-tool
	// call rules enforced as a CallGate on every tools/call path. Omitting
	// the block preserves legacy behavior: every listed tool is allowed
	// (Article IX). An empty `policy: {}` is present and permissive
	// (`default` allow, no rules) and still reports configured.
	//
	// Rules are evaluated in order and the last match wins. That differs
	// from the `skills:` deny-then-allow order, so a later allow can carve
	// an exception out of an earlier block. `block_destructive` applies
	// only when no rule matched, and only to a tool whose downstream
	// annotations set destructiveHint. `default` decides the rest ("block"
	// denies; anything else, including omitted, allows).
	//
	// Not inherited across `extends` (matching clients/groups/limits/skills).
	// Distinct from `gridctl validate --policy`, an offline declaration
	// check that does not read this block.
	Policy *PolicyConfig          `yaml:"policy,omitempty" json:"policy,omitempty"`
	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"`
	// Variables documents value-free prerequisites. Declarations are advisory
	// and never participate in expansion or write to the variable store.
	Variables map[string]VariableDeclaration `yaml:"variables,omitempty" json:"variables,omitempty"`

	// References is the variable-usage index, derived during expandStackVars:
	// which consumers reference each ${var:KEY}/${vault:KEY} key. Secret
	// references are indexed under secret:<provider>/<path> as well. 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:"-"`

	// SecretRefs lists distinct ${secret:<provider>/<path>} references in
	// first-seen order. Computed during expansion, never persisted. The
	// reference text stays literal in the field until a later resolve pass.
	SecretRefs []SecretRef `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:"-"`

	// Overrides records field names applied from an override file, keyed by
	// server name. Computed during merge; never persisted.
	Overrides map[string][]string `yaml:"-" json:"-"`

	// OverridePath is the override file merged into this stack. Empty when
	// no override was applied. Computed, never persisted.
	OverridePath string `yaml:"-" json:"-"`

	// DiscoveredOverride is an override file found beside an export source
	// and not merged. ExportNotices reads it. Never persisted.
	DiscoveredOverride string `yaml:"-" json:"-"`
	// contains filtered or unexported fields
}

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 ToolDiscoveryConfig struct {
	// Mode is "full" (default) or "deferred".
	Mode string `yaml:"mode,omitempty" json:"mode,omitempty"`
	// AlwaysExpose lists canonical server__tool names that stay on
	// tools/list in deferred mode, after scope, group, and whitelist filters.
	AlwaysExpose []string `yaml:"always_expose,omitempty" json:"always_expose,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").
	// A pathless URL is posted to /v1/traces. Any other path is used as-is.
	Endpoint string `yaml:"endpoint,omitempty" json:"endpoint,omitempty"`
	// Headers are sent on the OTLP trace export request. Values expand
	// ${var:KEY} and ${secret:} and are registered for log redaction.
	Headers map[string]string `yaml:"headers,omitempty" json:"headers,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"`
	// Line is the 1-based source line for strict-decode findings. Omitted
	// when the checker cannot name a line.
	Line int `json:"line,omitempty"`
}

type ValidationResult struct {
	Execution    map[string]*execution.Report `json:"execution,omitempty"`
	Valid        bool                         `json:"valid"`
	ErrorCount   int                          `json:"errorCount"`
	WarningCount int                          `json:"warningCount"`
	Issues       []ValidationIssue            `json:"issues"`
	// Override is the override file merged or discovered during validation.
	Override string `json:"override,omitempty"`
}

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

type VariableDeclaration struct {
	Required    *bool  `yaml:"required,omitempty" json:"required,omitempty"`
	Secret      *bool  `yaml:"secret,omitempty" json:"secret,omitempty"`
	Type        string `yaml:"type,omitempty" json:"type,omitempty"`
	Description string `yaml:"description,omitempty" json:"description,omitempty"`
	Docs        string `yaml:"docs,omitempty" json:"docs,omitempty"`
}

type VariableMetadata struct {
	Type       string `json:"type"`
	Secret     bool   `json:"secret"`
	Deprecated string `json:"deprecated,omitempty"`
}

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

type VaultSecret struct {
	Key   string
	Value string
}

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