controlplane

type AddDomainRequest struct {
	Host     string `json:"host"`
	Provider string `json:"provider"`
	// Address is the external IP or hostname to point Host at. Optional when App is set.
	Address string `json:"address,omitempty"`
	// App is an exposed application whose ingress external address Host should point at, used
	// when Address is empty so the agent need not look the address up itself.
	App string `json:"app,omitempty"`
	// Confirm acknowledges the dns.write guardrail so the operation proceeds past it.
	Confirm bool `json:"confirm,omitempty"`
}

type AddProviderRequest struct {
	// Name identifies the provider; empty defaults to the type.
	Name string `json:"name,omitempty"`
	// Type is the vendor this provider talks to.
	Type ProviderType `json:"type"`
	// SecretKey is the key in burrow-credentials the token is written under; empty defaults to Name.
	SecretKey string `json:"secret_key,omitempty"`
	// Token is the vendor API token VALUE. It is written to burrow-credentials after validation and
	// is never logged, stored in Postgres, or echoed back (ADR-0030).
	Token string `json:"token,omitempty"`
}

type AddonInfo struct {
	Name string    `json:"name"`
	Type AddonType `json:"type"`
	// Mode is how the backend is provided: "installed" (Burrow deployed it) or "connected"
	// (an existing backend the user runs). Installed-only for now; connect lands later (ADR-0026).
	Mode string `json:"mode"`
	// Backend is the concrete adapter implementation backing this add-on (e.g. "victorialogs").
	Backend      string   `json:"backend,omitempty"`
	Image        string   `json:"image,omitempty"`
	Endpoint     string   `json:"endpoint"` // in-cluster host:port the app or agent reaches it on
	Capabilities []string `json:"capabilities"`
	// SecretKey is the non-secret key under which this add-on's bearer token lives in the
	// burrow-credentials Secret (ADR-0023). Empty means the backend is unauthenticated; the
	// token itself never travels here — only the key (ADR-0004).
	SecretKey string `json:"secret_key,omitempty"`
	// CreatedAt is when the add-on was registered, read from the injected clock.
	CreatedAt time.Time `json:"created_at,omitempty"`
	// Ready is a live property — whether the backing Deployment is available. It is probed
	// from the cluster at list time and never persisted in the registry.
	Ready bool `json:"ready"`
}

type AddonSpec struct {
	Type AddonType
	// Backend is the concrete adapter implementation that backs this add-on (e.g.
	// "victorialogs"), recorded in the registry so the agent knows which adapter serves it.
	Backend string
	// Image is the pinned container image for the backing service.
	Image string
	// Port is the service port the app (or the agent, for an observability add-on) reaches it on.
	Port int32
	// StorageGi requests a persistent volume of this size in GiB; 0 is ephemeral. Stateful
	// stores (logs, metrics) persist so data survives a restart.
	StorageGi int
	// Capabilities are what the agent can query this add-on for (e.g. "logs"). For an
	// installed default it is fixed; a connected backend may derive or probe its own (ADR-0026).
	Capabilities []string
	// Summary is a one-line description for the catalog listing.
	Summary string
}

type AddonType string

type AmbiguousEnvironmentError struct {
	// Environments are the registered environments the caller must choose among (the implicit
	// `default` first, then the named ones in name order, as ListEnvironments returns them).
	Environments []Environment
}

type App struct {
	// Name identifies the app within the control plane and names its Kubernetes
	// workload. It must be a DNS-1123 label (lowercase alphanumerics and '-').
	Name string
}

type AppEnvRef struct {
	App string `json:"app"`
	Env string `json:"env"`
}

type AttachResult struct {
	App   string    `json:"app"`
	Addon AddonType `json:"addon"`
	// SecretKey is the env-var name under which the generated connection string was written into
	// the app's per-app Secret. The value is never returned (ADR-0029/0031).
	SecretKey string `json:"secret_key"`
}

type AuditEntry struct {
	// ID is the store-assigned row identity (0 before it is persisted). Newest rows have the
	// largest IDs.
	ID int64 `json:"id,omitempty"`
	// Timestamp comes from the injected clock, never ambient time (ADR-0010).
	Timestamp time.Time `json:"timestamp"`
	// Operation is the logical operation: deploy, scale, rollback, app_delete, expose,
	// dns_write, dns_delete, addon_install, addon_remove.
	Operation string `json:"operation"`
	// Target is what the operation acted on: an app, a host, or an add-on name. It may be
	// empty for an operation that names nothing.
	Target string `json:"target,omitempty"`
	// Args is the redacted, per-operation allowlist of salient parameters. Never secret values.
	Args map[string]string `json:"args,omitempty"`
	// GuardrailCode is the guardrail that applied (e.g. app.expose_public). Empty on an execution
	// row, which is the second half of a trail whose decision row already named the guardrail.
	GuardrailCode string `json:"guardrail_code,omitempty"`
	// Disposition is the guardrail's effective disposition (allow/confirm/deny) at decision time.
	Disposition string `json:"disposition,omitempty"`
	// Outcome is the categorical result (see AuditOutcome).
	Outcome AuditOutcome `json:"outcome"`
	// Result is the execution result: empty on success, or a short error summary on a failed
	// outcome. It never carries a secret value.
	Result string `json:"result,omitempty"`
	// Caller is the authenticated caller. Identity is coarse until an auth model exists
	// (ADR-0027): today it is a constant naming the control-plane boundary.
	Caller string `json:"caller,omitempty"`
	// Principal is the acting identity — the actor behind the operation, distinct from Caller
	// (the control-plane boundary that authenticated the request). Today every agent shares one
	// ServiceAccount, so it is a constant ("shared-agent"); the principal seam (ADR-0038) is
	// where a future TokenReview→SSO identity resolution fills in a real per-user value, so
	// attribution becomes additive rather than a migration of past rows' meaning.
	Principal string `json:"principal,omitempty"`
	// ClientVersion is the release version of the client (CLI or MCP server) that drove the
	// operation, read from the X-Burrow-Client-Version handshake header (ADR-0039). It records which
	// client acted, next to the principal (who) and the server's own version — so version skew is
	// legible after the fact. Empty for a pre-handshake client that sent no version. The json tag must
	// match the client-side AuditEntry tag exactly (the struct crosses the API), or the field would
	// silently drop.
	ClientVersion string `json:"client_version,omitempty"`
}

type AuditFilter struct {
	// App restricts to rows whose target is this app/host/addon name; empty matches any.
	App string
	// Operation restricts to one operation name; empty matches any.
	Operation string
	// Outcome restricts to one outcome; empty matches any.
	Outcome AuditOutcome
	// Limit caps the number of rows returned, newest first. Zero or negative applies the
	// store's default cap.
	Limit int
}

type AuditOutcome string

type AutoDeployConfig struct {
	// Interval is the base poll cadence. Zero or negative applies DefaultAutoDeployInterval.
	Interval time.Duration
	// Backoff is how long a failed tag (or a hint-less rate-limit) is held off. Zero applies
	// DefaultAutoDeployBackoff.
	Backoff time.Duration
	// Jitter returns the actual wait before the next cycle, given the base interval, so many
	// pollers do not stampede the registry in lockstep (ADR-0052 §7). Nil applies a default of
	// the base interval +/- up to 10%. It is injected so a test drives the cadence deterministically.
	Jitter func(base time.Duration) time.Duration
	// After returns a channel that fires after d — the seam the run loop waits on between cycles.
	// Nil applies time.After. It is injected (rather than reading the wall clock) so a test drives
	// the loop with no real sleeping and no ambient time (ADR-0010).
	After func(d time.Duration) <-chan time.Time
}

type AutoDeployLevel string

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

type AutoDeployStatus struct {
	App        string          `json:"app"`
	Env        string          `json:"env"`
	Level      AutoDeployLevel `json:"level"`
	Repository string          `json:"repository,omitempty"` // current image reference with the tag stripped (e.g. "ghcr.io/user/app"), for building the deploy hint
	Current    string          `json:"current,omitempty"`    // current running semver tag, when known
	Target     string          `json:"target,omitempty"`     // tag auto-deploy would move to within the level, "" if none / already current
	Upgrade    string          `json:"upgrade,omitempty"`    // highest version above the level's cap, surfaced as an available upgrade, "" if none
	Checked    bool            `json:"checked"`              // whether the registry upgrade check actually ran
	Note       string          `json:"note,omitempty"`       // when Checked is false, a short human reason
	// DisabledReason is why auto-deploy is off, when it was turned off by the safety stop rather than
	// by a human (ADR-0052 §5): "disabled by rollback" or "disabled by downgrade". Empty when the
	// level was human-set or is not off.
	DisabledReason string `json:"disabled_reason,omitempty"`
}

type AutoscaleResult struct {
	App              string `json:"app"`
	Env              string `json:"env,omitempty"`
	MinReplicas      int32  `json:"min_replicas"`
	MaxReplicas      int32  `json:"max_replicas"`
	CPUPercent       int32  `json:"cpu_percent"`
	MemoryPercent    int32  `json:"memory_percent,omitempty"`
	MetricsAvailable bool   `json:"metrics_available"`
	Warning          string `json:"warning,omitempty"`
}

type AutoscaleSpec struct {
	// MinReplicas is the floor the autoscaler will not scale below. Must be at least 1.
	MinReplicas int32 `json:"min_replicas"`
	// MaxReplicas is the ceiling the autoscaler will not scale above. Must be >= MinReplicas and is
	// itself bounded by the replica-ceiling guardrail (Policy.MaxReplicas).
	MaxReplicas int32 `json:"max_replicas"`
	// CPUPercent is the target average CPU utilization (1..100) the autoscaler holds the app at.
	CPUPercent int32 `json:"cpu_percent"`
	// MemoryPercent is the target average memory utilization (1..100), or 0 to add no memory metric.
	MemoryPercent int32 `json:"memory_percent,omitempty"`
}

type Backup struct {
	// ID is the backup identifier, minted from the IDs seam — also the dump filename stem.
	ID string `json:"id"`
	// App is the application whose database was dumped.
	App string `json:"app"`
	// CreatedAt is when the backup was recorded, read from the injected clock.
	CreatedAt time.Time `json:"created_at"`
	// Path is the on-PVC location of the dump (e.g. /backups/<app>/<id>.dump). It is a path on a
	// volume burrowd does not mount — never a credential.
	Path string `json:"path,omitempty"`
	// SizeBytes is the dump's size in bytes, or 0 when unknown.
	SizeBytes int64 `json:"size_bytes,omitempty"`
	// Status is the lifecycle state of this backup.
	Status BackupStatus `json:"status"`
}

type BackupResult struct {
	Backup Backup `json:"backup"`
}

type BackupStatus string

type BuildRequest struct {
	App string `json:"app"`
	// Env is the environment to deploy the built image into (ADR-0035): empty or "default" targets the
	// implicit default environment, a registered name targets that environment. An unregistered name
	// is an error, surfaced by the deploy the build hands off to.
	Env string `json:"env,omitempty"`
	// Source is the git reference the builder clones and checks out inside the cluster.
	Source SourceRef `json:"source"`
	// TargetImage is the pullable repo:tag reference the built image is pushed to; the resulting deploy
	// pins the digest the builder returns. In this phase it is supplied explicitly; the optional
	// in-cluster registry as the zero-config default push target (ADR-0053 §5) is a later phase.
	TargetImage string `json:"target_image"`
	// Confirm acknowledges the app.deploy guardrail whose disposition is confirm, letting the deploy
	// the build hands off to proceed past it (ADR-0020). It has no effect on a guardrail set to deny.
	Confirm bool `json:"confirm,omitempty"`
}

type BuildResult struct {
	// Digest is the content digest of the built image (e.g. "sha256:..."), the immutable identity the
	// deployed release pins.
	Digest string `json:"digest"`
	// Deploy is the guarded deploy the built image flowed into (ADR-0053 §4).
	Deploy DeployResult `json:"deploy"`
}

type Builder interface {
	// Build clones source inside the cluster, builds an image, pushes it to targetImage (a pullable
	// repo:tag reference), and returns the resulting image content digest (e.g. "sha256:..."). Only
	// the git reference and the target reference cross into the builder — never source bytes; the
	// builder clones the actual code from git inside the cluster (ADR-0004/0053 §3). It returns an
	// error on any clone, build, or push failure; the caller surfaces that structurally and does NOT
	// touch the deploy path. On success the returned digest is the immutable identity the resulting
	// guarded deploy pins (ADR-0053 §4).
	//
	// insecure marks the push target as a plain-HTTP registry the push must not verify TLS against —
	// set only for the in-cluster registry, which serves plain HTTP in-cluster (ADR-0054 §5). The
	// engine is the single place that knows this: it sets insecure when it defaults the target to the
	// in-cluster registry, and leaves it false for a caller-supplied external target, which is pushed
	// over TLS. The base-image pull during the build always uses TLS regardless — insecure applies
	// only to the push to targetImage.
	//
	// cred is the resolved source-provider credential (ADR-0057). When it carries a token the builder
	// authenticates the clone to a PRIVATE git source and the buildah push/pull to the provider's
	// registry with it, by mounting it into the build Job — never as a Job env var or command-line
	// argument. The zero value (IsZero) is the public-source, credential-free path. The token is a
	// secret: an implementation must not log it, echo it, or place it in an error.
	Build(ctx context.Context, source SourceRef, targetImage string, insecure bool, cred SourceCredential) (digest string, err error)
}

type Capability string

type CapacityProber interface {
	// ReadResourceState reads node allocatable and pod requests read-only. It never writes.
	ReadResourceState(ctx context.Context) (ClusterResourceState, error)
}

type CapacityReport struct {
	// Nodes is the per-node breakdown, one entry per schedulable node.
	Nodes []NodeCapacity `json:"nodes"`
	// Cluster is the cluster-wide total (its Name is empty).
	Cluster NodeCapacity `json:"cluster"`
	// TopCPU lists the pods requesting the most CPU, most first; TopMemory the most memory.
	TopCPU    []Consumer `json:"top_cpu"`
	TopMemory []Consumer `json:"top_memory"`
	// BuildCPUMillis / BuildMemBytes are the resource request the verdict pre-flights (a typical
	// in-cluster build: a quarter of a CPU, 512 MB).
	BuildCPUMillis int64 `json:"build_cpu_millis"`
	BuildMemBytes  int64 `json:"build_mem_bytes"`
	// BuildFits is true when at least one node has enough free CPU AND memory at once to schedule
	// that build. A build pod lands on a single node, so headroom split across nodes does not count.
	BuildFits bool `json:"build_fits"`
	// BuildFitsNode names the node the build would schedule on when BuildFits is true.
	BuildFitsNode string `json:"build_fits_node,omitempty"`
	// Verdict is the short, plain-language recommendation (plain CPU units, memory in MB/GB).
	Verdict string `json:"verdict"`
	// UtilizationNote records that this is scheduling headroom only and what metrics-server would add.
	UtilizationNote string `json:"utilization_note"`
}

type CertManagerCapability struct {
	Present bool `json:"present"`
}

type Clock interface {
	// Now returns the current time.
	Now() time.Time
}

type ClusterCapabilities struct {
	// Ingress is the ingress-controller situation: whether a controller is actually running, and
	// which IngressClass(es) exist.
	Ingress IngressCapability `json:"ingress"`
	// Storage is the default-StorageClass situation: whether a default exists and its name.
	Storage StorageCapability `json:"storage"`
	// LoadBalancer is whether Service type=LoadBalancer is likely supported, detected from whatever
	// services LoadBalancers — a cloud provider, k3s's servicelb, or MetalLB.
	LoadBalancer LoadBalancerCapability `json:"load_balancer"`
	// CertManager is whether cert-manager is installed, detected via its API group (its CRDs).
	CertManager CertManagerCapability `json:"cert_manager"`
	// MetricsServer is whether metrics-server is serving the Kubernetes Metrics API (metrics.k8s.io),
	// detected via API-group discovery. It powers `kubectl top`, HPA CPU/memory autoscaling, and the
	// utilization layer of capacity reporting; Burrow auto-ensures it as a baseline (ADR-0054 §1).
	MetricsServer MetricsServerCapability `json:"metrics_server"`
	// Provider is the detected cloud provider, inferred from node labels / providerID.
	Provider ProviderCapability `json:"provider"`
	// DNS is whether a DNS provider is configured in the registry (ADR-0023) — a control-plane
	// fact, not a cluster read. It is filled by the engine, not the cluster probe.
	DNS DNSCapability `json:"dns"`
}

type ClusterProber interface {
	// DetectCapabilities reads the cluster's capabilities read-only. It never writes.
	DetectCapabilities(ctx context.Context) (ClusterCapabilities, error)
}

type ClusterResourceState struct {
	Nodes []NodeAllocatable
	Pods  []PodRequest
}

type ConnectBackend struct {
	// Name is the backend identifier (e.g. "loki"), used as the add-on Backend and as the
	// querier key the engine dispatches on.
	Name string
	// Capabilities are what the agent can query a connected instance of this backend for. They
	// are derived from the backend, not declared by the user (ADR-0026): a single-capability
	// backend like Loki implies "logs".
	Capabilities []string
	// Summary is a one-line description for the connectable-backend listing.
	Summary string
}

type Consumer struct {
	Namespace string `json:"namespace"`
	Name      string `json:"name"`
	Node      string `json:"node,omitempty"`
	CPUMillis int64  `json:"cpu_millis"`
	MemBytes  int64  `json:"mem_bytes"`
}

type Credentials interface {
	// Token returns the token stored under key in burrow-credentials, or ErrNotFound when
	// the Secret or the key is absent.
	Token(ctx context.Context, key string) (string, error)
	// SetToken upserts key=value into burrow-credentials, creating the Secret if absent
	// (ADR-0030). The value arrives over burrowd's authenticated, TLS-protected control-plane
	// API — never over MCP — and is written straight to the Secret: it is NEVER logged, never
	// stored in Postgres, and never returned in a response. Any error names the key only, never
	// the value.
	SetToken(ctx context.Context, key, value string) error
}

type DNSCapability struct {
	Configured bool     `json:"configured"`
	Providers  []string `json:"providers,omitempty"`
}

type DNSFactory interface {
	DNS(t ProviderType, token string) (DNSProvider, error)
}

type DNSProvider interface {
	// VerifyAccess confirms the token authenticates and can manage DNS, with a cheap read
	// call against the vendor. It returns ErrInvalid when the vendor rejects the token.
	VerifyAccess(ctx context.Context) error
	// EnsureRecord creates or updates the record so r.Name resolves to r.Value (ADR-0018). It
	// is idempotent: re-applying the same record is a no-op. It returns ErrNotFound when no
	// zone the provider manages covers r.Name.
	EnsureRecord(ctx context.Context, r DNSRecord) error
	// DeleteRecord removes the A/CNAME record(s) the provider holds for host. It returns
	// ErrNotFound when no managed zone covers host or no such record exists.
	DeleteRecord(ctx context.Context, host string) error
}

type DNSRecord struct {
	// Type is A or CNAME.
	Type DNSRecordType
	// Name is the fully-qualified host, e.g. app.example.com.
	Name string
	// Value is the target: an IPv4 address for an A record, a hostname for a CNAME.
	Value string
	// TTL is the record's time to live in seconds; 0 means the provider's default.
	TTL int
}

type DNSRecordType string

type Database interface {
	// SaveRelease persists r. An existing release with the same ID is overwritten
	// (releases are immutable in meaning; this supports status transitions during a
	// single rollout).
	SaveRelease(ctx context.Context, r Release) error
	// Release returns the release with the given ID, or ErrNotFound.
	Release(ctx context.Context, id string) (Release, error)
	// LatestRelease returns the most recently saved release for app in env, or ErrNotFound if
	// the app has no releases there. Releases are keyed per (app, environment) (ADR-0052 Phase 4a):
	// env is the canonical environment name (the reserved "default" for the implicit default
	// environment).
	LatestRelease(ctx context.Context, app, env string) (Release, error)
	// Releases returns all releases for app in env, oldest first, keyed per (app, environment).
	// An app with no releases there yields an empty slice and no error.
	Releases(ctx context.Context, app, env string) ([]Release, error)
	// ListReleases returns all releases for app in env, NEWEST first — the deploy timeline the
	// history surface reads (the same rows deploys already write, read the other way round from
	// Releases). Releases are keyed per (app, environment) (ADR-0052 Phase 4a). An app with no
	// releases there yields an empty slice and no error.
	ListReleases(ctx context.Context, app, env string) ([]Release, error)
	// DeleteReleases removes all release records for app across every environment — the durable
	// side of an app teardown, which removes the whole app. Deleting the releases of an app that
	// has none is a no-op, not an error.
	DeleteReleases(ctx context.Context, app string) error

	// AppEnv returns the non-secret environment store for app: the app-global current
	// config rendered into the workload at apply time (ADR-0028). An app with no env yields
	// an empty map and no error.
	AppEnv(ctx context.Context, app string) (map[string]string, error)
	// SetAppEnv upserts one env key for app in the store.
	SetAppEnv(ctx context.Context, app, key, value string) error
	// UnsetAppEnv removes one env key for app from the store. Removing a key that is not set
	// is a no-op, not an error.
	UnsetAppEnv(ctx context.Context, app, key string) error

	// Policy returns the current guardrail policy: the stored guardrail dispositions
	// overlaid on the built-in defaults (DefaultPolicy), so a store with nothing set
	// returns DefaultPolicy and newly-added guardrails get a sensible default (ADR-0020).
	Policy(ctx context.Context) (Policy, error)
	// SetGuardrail persists the disposition for one guardrail — the write behind
	// `guard set`. It rejects an invalid disposition.
	SetGuardrail(ctx context.Context, code GuardrailCode, d Disposition) error

	// AutoDeployLevel returns the auto-deploy level configured for app in the named environment
	// (ADR-0052 §2). A missing configuration resolves to DefaultAutoDeployLevel (off): auto-deploy is
	// opt-in, so an app with no stored row is off and is never polled (ADR-0058). env is the canonical
	// environment name (the reserved "default" for the implicit default environment).
	AutoDeployLevel(ctx context.Context, app, env string) (AutoDeployLevel, error)
	// SetAutoDeployLevel upserts the auto-deploy level for app in the named environment — the write
	// behind `burrow app auto-deploy <app> <level>`. It rejects an invalid level. It CLEARS any
	// stored disable reason: a human setting the level is the deliberate re-enable action that
	// removes a rollback or downgrade note (ADR-0052 §5).
	SetAutoDeployLevel(ctx context.Context, app, env string, level AutoDeployLevel) error
	// DisableAutoDeploy sets app's level to off in the named environment AND records why (e.g.
	// "disabled by rollback") — the safety stop of ADR-0052 §5, so the watcher does not fight a
	// deliberate downgrade. It upserts, overwriting any prior level and reason.
	DisableAutoDeploy(ctx context.Context, app, env, reason string) error
	// AutoDeployCandidates returns the distinct (app, environment) pairs the pull-based watcher may
	// reconcile: every app that has a recorded release, paired with the environment it was released
	// into (ADR-0052 Phase 4b). Candidacy is "has a running release" — the set the poller can compare
	// a registry tag against — not "has a stored level row"; the poller reads each pair's level and
	// skips those that are off, which is the default (ADR-0058), so an app that never opted in is read
	// and skipped before any registry call. None yields an empty slice and no error.
	AutoDeployCandidates(ctx context.Context) ([]AppEnvRef, error)
	// AutoDeployReason returns the stored disable reason for app in the named environment, or ""
	// when the level was human-set or is the default (no stored override) — the reason surfaced
	// next to an off level (ADR-0052 §5).
	AutoDeployReason(ctx context.Context, app, env string) (string, error)

	// SaveProvider upserts a provider in the registry by name (ADR-0023). It stores only
	// the non-secret registry entry — type, capabilities, and the key under which the token
	// lives in the burrow-credentials Secret — never the token itself.
	SaveProvider(ctx context.Context, p Provider) error
	// Provider returns the provider with the given name, or ErrNotFound.
	Provider(ctx context.Context, name string) (Provider, error)
	// Providers returns all configured providers, name order. None yields an empty slice
	// and no error.
	Providers(ctx context.Context) ([]Provider, error)

	// SaveAddon upserts an add-on in the registry by name (ADR-0025). It stores the non-secret
	// registry entry — type, mode, backend, endpoint, and capabilities — never the live
	// readiness, which is probed from the cluster.
	SaveAddon(ctx context.Context, a AddonInfo) error
	// Addon returns the add-on with the given name, or ErrNotFound.
	Addon(ctx context.Context, name string) (AddonInfo, error)
	// Addons returns all registered add-ons, name order. None yields an empty slice and no
	// error. The returned entries carry no live readiness.
	Addons(ctx context.Context) ([]AddonInfo, error)
	// DeleteAddon removes the named add-on from the registry, or ErrNotFound if absent.
	DeleteAddon(ctx context.Context, name string) error

	// AppendAudit appends one audit row (ADR-0027). The log is append-only: there is no
	// update or delete path. The store assigns the row identity and orders rows by it.
	AppendAudit(ctx context.Context, entry AuditEntry) error
	// Audit returns audit rows matching filter, newest first, capped by filter.Limit (a
	// store default when unset). No matches yields an empty slice and no error.
	Audit(ctx context.Context, filter AuditFilter) ([]AuditEntry, error)

	// RecordBackup persists a new backup row (ADR-0032). burrowd records it pending before
	// starting the backup Job. The row names the app, the on-PVC path, and the status — never a
	// credential. An existing row with the same ID is overwritten.
	RecordBackup(ctx context.Context, b Backup) error
	// SetBackupStatus updates a recorded backup's status (and, when known, its size) — the
	// completed/failed transition burrowd writes when the Job finishes. Setting the status of an
	// unknown backup id returns ErrNotFound.
	SetBackupStatus(ctx context.Context, id string, status BackupStatus, sizeBytes int64) error
	// ListBackups returns recorded backups, newest first. An empty app lists every app's backups;
	// a non-empty app restricts to that app. No matches yields an empty slice and no error.
	ListBackups(ctx context.Context, app string) ([]Backup, error)
	// GetBackup returns the backup with the given id, or ErrNotFound.
	GetBackup(ctx context.Context, id string) (Backup, error)

	// CreateEnvironment registers a named environment mapping name to namespace (ADR-0035 phase 2).
	// It rejects a duplicate name (the name is the primary key) with an ErrInvalid-wrapped error.
	// The reserved `default` environment is never stored here — it is synthesized by the engine.
	CreateEnvironment(ctx context.Context, name, namespace string) error
	// ListEnvironments returns the registered environments ordered by name. None yields an empty
	// slice and no error. The synthesized `default` environment is not included; the engine
	// prepends it.
	ListEnvironments(ctx context.Context) ([]Environment, error)
	// GetEnvironment returns the registered environment with the given name, or ErrNotFound.
	GetEnvironment(ctx context.Context, name string) (Environment, error)
}

type DatabaseProvisioner interface {
	// EnsureAppDatabase idempotently provisions an isolated database and login role for app on the
	// shared instance and returns the app's DATABASE_URL (a postgres:// connection string carrying
	// a freshly generated role password). It rotates the role password on every call, so a re-attach
	// returns a fresh, working URL with no orphaned state. The app name is validated against a strict
	// identifier pattern and every SQL identifier is quoted BEFORE any SQL runs, so a name can never
	// carry SQL. The returned string is a secret value — the caller writes it straight into the app's
	// Secret and never logs, audits, or returns it.
	EnsureAppDatabase(ctx context.Context, app string) (databaseURL string, err error)
	// DropAppDatabase removes app's database and login role from the shared instance — the
	// destructive side of detach. Dropping a database/role that is already absent is a no-op, not an
	// error. The app name is validated before any SQL, exactly as in EnsureAppDatabase.
	DropAppDatabase(ctx context.Context, app string) error
}

type DeployRequest struct {
	App string `json:"app"`
	// Env is the environment to deploy into (ADR-0035 phase 2b): empty or "default" targets the
	// implicit default environment's namespace, a registered name targets that environment's
	// namespace. An unregistered name is an error.
	Env     string   `json:"env,omitempty"`
	Image   string   `json:"image"`
	Command []string `json:"command,omitempty"`
	// MetricsPort, when positive, annotates the deployed pod so the metrics add-on scrapes
	// /metrics on this container port (ADR-0026). Zero adds no annotations.
	MetricsPort int32 `json:"metrics_port,omitempty"`
	Replicas    int32 `json:"replicas"`
	// Confirm acknowledges a guardrail whose disposition is confirm, letting the operation
	// proceed past it (ADR-0020). It has no effect on a guardrail set to deny.
	Confirm bool `json:"confirm,omitempty"`
}

type DeployResult struct {
	// Release is the new release that is now running.
	Release Release `json:"release"`
	// SupersededReleaseID is the release this deploy replaced, or "" if it was the
	// first deploy of the app. It is the handle a rollback would return to.
	SupersededReleaseID string `json:"superseded_release_id,omitempty"`
	// Hints are non-blocking notes about the deploy the agent can reason over (ADR-0052 §8): today,
	// a nudge toward semver when the deployed tag cannot be classified for auto-update. They never
	// gate or fail the deploy — any reference deploys (ADR-0007). Empty when there is nothing to note.
	Hints []string `json:"hints,omitempty"`
}

type Deps struct {
	Kubernetes Kubernetes
	Database   Database
	Clock      Clock
	IDs        IDSource
	Resolver   Resolver
	// Credentials reads vendor tokens from the burrow-credentials Secret (ADR-0023).
	Credentials Credentials
	// DNS builds a DNSProvider for a vendor type and token (ADR-0023).
	DNS DNSFactory
	// Logs maps a backend id (e.g. "victorialogs", "loki") to the querier serving an installed
	// or connected logs add-on. Optional — an empty or nil map is allowed, and the engine errors
	// cleanly on a logs query when no querier is wired for the add-on's backend (ADR-0026).
	Logs map[string]LogsQuerier
	// Metrics maps a backend id (e.g. "prometheus", "victoriametrics") to the querier serving an
	// installed or connected metrics add-on. Optional — an empty or nil map is allowed, and the
	// engine errors cleanly on a metrics query when no querier is wired for the add-on's backend
	// (ADR-0026).
	Metrics map[string]MetricsQuerier
	// DatabaseProvisioner provisions a per-app database and role on the installed Postgres add-on
	// (ADR-0031). Optional — nil is allowed, and the engine errors cleanly (ErrNotImplemented) on a
	// Postgres attach when it is not wired.
	DatabaseProvisioner DatabaseProvisioner
	// ClusterProber detects the cluster's read-only capabilities (ADR-0034). Optional — nil is
	// allowed, and the engine errors cleanly (ErrNotImplemented) on a capabilities read when it is
	// not wired.
	ClusterProber ClusterProber
	// CapacityProber reads the cluster's scheduling-capacity facts (node allocatable, pod requests)
	// for the headroom surface (issue #275). Optional — nil is allowed, and the engine errors cleanly
	// (ErrNotImplemented) on a capacity read when it is not wired.
	CapacityProber CapacityProber
	// RegistryClient lists an image repository's tags for the auto-deploy read/watch (ADR-0052).
	// Optional — nil is allowed, and the auto-deploy show degrades to reporting the level alone
	// when it is not wired. It is OUTBOUND-only and never used on the core deploy path (ADR-0040).
	RegistryClient RegistryClient
	// Builder builds an image from a git source reference inside the cluster for the optional
	// in-cluster build path (ADR-0053). Optional — nil is allowed, and the engine errors cleanly
	// (ErrNotImplemented) on a build when it is not wired.
	Builder Builder
	// BuildRegistry is the in-cluster registry reference host:port the in-cluster build defaults its
	// push target to when the caller supplies none — the zero-config default push target for a build
	// (ADR-0053 §5). Optional — an empty value means a build with no explicit target errors, and a
	// caller-supplied target always overrides it (external registries stay fully supported). burrowd
	// sets it from BURROW_BUILD_REGISTRY, which `burrow cluster registry install` wires to the
	// in-cluster registry it deploys.
	BuildRegistry string
	// BuildPublicRegistry is the PUBLIC registry host the in-cluster build's resulting deploy
	// references so the node pulls through the ingress over TLS, distinct from BuildRegistry (the
	// internal push endpoint) — ADR-0054 §5. Optional — an empty value falls back to referencing the
	// internal push endpoint. burrowd sets it from BURROW_BUILD_PUBLIC_REGISTRY, which
	// `burrow cluster registry install --host` wires to the registry's public ingress hostname.
	BuildPublicRegistry string
	// AppNamespace is the namespace burrowd deploys apps into (BURROW_NAMESPACE) — the namespace of
	// the implicit `default` environment (ADR-0035 phase 2). Optional — an empty value defaults to
	// "default", matching the kube Adapter.
	AppNamespace string
}

type Disposition string

type DomainResult struct {
	Host     string `json:"host"`
	Provider string `json:"provider"`
	Type     string `json:"type,omitempty"`
	Address  string `json:"address,omitempty"`
}

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

type Environment struct {
	// Name is the environment handle, a DNS-1123 label (e.g. "staging", "prod").
	Name string `json:"name"`
	// Namespace is the Kubernetes namespace this environment's apps deploy into.
	Namespace string `json:"namespace"`
	// Default reports whether this is the implicit `default` environment (the app namespace
	// burrowd already runs against). Registered environments are never default.
	Default bool `json:"default"`
	// CreatedAt is when the environment was registered, read from the injected clock. It is the
	// zero time for the synthesized default environment.
	CreatedAt time.Time `json:"created_at,omitempty"`
}

type ExposeRequest struct {
	App string `json:"app"`
	// Env is the environment whose namespace the app lives in (ADR-0035 phase 2b): empty or
	// "default" targets the default environment, a registered name targets that environment.
	Env  string `json:"env,omitempty"`
	Host string `json:"host"`
	Port int32  `json:"port"`
	// TLS requests an HTTPS certificate for Host via cert-manager; Issuer names the
	// ClusterIssuer to use.
	TLS    bool   `json:"tls,omitempty"`
	Issuer string `json:"issuer,omitempty"`
	// Confirm acknowledges the app.expose_public guardrail so the operation proceeds past it.
	Confirm bool `json:"confirm,omitempty"`
}

type ExposeResult struct {
	App  string `json:"app"`
	Host string `json:"host"`
	Port int32  `json:"port"`
	URL  string `json:"url"`
}

type ExposeSpec struct {
	// App is the application to expose; its workload provides the Service's backends.
	App string
	// Host is the external hostname to route, e.g. app.example.com.
	Host string
	// Port is the app's container port the Service forwards to. Must be positive.
	Port int32
	// TLS requests an HTTPS certificate for Host via cert-manager (the Ingress is annotated
	// for the Issuer ClusterIssuer, and a TLS Secret is named for cert-manager to fill).
	TLS bool
	// Issuer is the cert-manager ClusterIssuer to request the certificate from when TLS.
	Issuer string
}

type ExposureStatus struct {
	Exposed bool
	Host    string
	Address string
	// TLS reports whether the Ingress requests a certificate (its spec has a TLS entry).
	TLS bool
	// CertReady reports whether the requested TLS certificate has been issued (its Secret holds a
	// certificate). It is meaningful only when TLS is true.
	CertReady bool
}

type GuardrailCode string

type GuardrailError struct {
	// Operation is the operation that was gated (e.g. "deploy", "scale").
	Operation string
	// Code is the machine-readable guardrail that tripped.
	Code GuardrailCode
	// Message is a human-readable explanation.
	Message string
	// Requested is the value the caller asked for (e.g. the replica count).
	Requested int32
	// Limit is the relevant policy limit, when the code involves one.
	Limit int32
	// NeedsConfirmation is true when the operation was not refused outright but requires
	// explicit confirmation to proceed (disposition confirm). A plain deny leaves it false.
	NeedsConfirmation bool
}

type GuardrailInfo struct {
	Code        GuardrailCode `json:"code"`
	Disposition Disposition   `json:"disposition"`
	Description string        `json:"description"`
	// Source reports where the effective disposition came from when the guardrail is inspected for a
	// named environment (ADR-0035 phase 2c): "env" for an environment-specific override, "global" for
	// the global policy, or "default" for the built-in default. It is empty for the global listing.
	Source string `json:"source,omitempty"`
}

type IDSource interface {
	// NewID returns a fresh release identifier.
	NewID() string
}

type IngressCapability struct {
	// Present is true only when a ready ingress controller is running — the signal that an expose
	// will actually get an external address and admission webhook. It is not implied by Classes.
	Present bool `json:"present"`
	// Classes are the IngressClass names that exist, sorted. A class may be present while Present is
	// false (an orphan class whose controller was removed).
	Classes []string `json:"classes,omitempty"`
}

type Kubernetes interface {
	// WithNamespace returns a view of this seam whose per-app resource operations (deploy,
	// status, logs, scale, delete, expose/unexpose, and the per-app Secret) act in ns instead
	// of the configured app namespace — the mechanism that routes an operation to a named
	// environment's namespace (ADR-0035 phase 2). Add-on operations are unaffected: add-ons live
	// in their own namespace. An empty ns, or ns equal to the configured app namespace, returns a
	// view equivalent to the receiver, so default-environment behavior is identical to before
	// environments existed.
	WithNamespace(ns string) Kubernetes

	// ApplyWorkload creates or updates the workload for spec.App to match spec.
	ApplyWorkload(ctx context.Context, spec WorkloadSpec) error
	// WorkloadStatus returns the observed state of app's workload, or ErrNotFound if
	// no workload exists for it.
	WorkloadStatus(ctx context.Context, app string) (WorkloadStatus, error)
	// ListWorkloads returns the observed state of every Burrow-managed workload in the
	// namespace (for an apps listing). No workloads is an empty slice, not an error.
	ListWorkloads(ctx context.Context) ([]WorkloadStatus, error)

	// DeployAddon installs a building-block backing service per spec — a workload, a
	// ClusterIP Service, and a persistent volume when the spec asks for one — and returns
	// the instance's connection info (ADR-0025). Installing an already-installed add-on is
	// idempotent.
	DeployAddon(ctx context.Context, spec AddonSpec) (AddonInfo, error)
	// AddonReady reports whether the named add-on's backing Deployment is available. It is a
	// cheap single-Deployment readiness probe — readiness is a live property, not stored in the
	// registry. A missing Deployment is reported as not ready (false, nil), not an error.
	AddonReady(ctx context.Context, name string) (bool, error)
	// DeleteAddon removes the named add-on instance and its resources. Removing an add-on
	// that is not installed returns ErrNotFound.
	DeleteAddon(ctx context.Context, name string) error
	// ScaleWorkload sets the desired replica count for app's workload.
	ScaleWorkload(ctx context.Context, app string, replicas int32) error

	// ApplyAutoscaler creates or updates an autoscaling/v2 HorizontalPodAutoscaler named after app,
	// targeting app's Deployment, per spec — the replica band and the CPU (and optional memory)
	// utilization targets (ADR-0006). It is create-or-update: re-applying adjusts the existing HPA.
	// Creating the HPA does not require metrics-server; only its scaling does.
	ApplyAutoscaler(ctx context.Context, app string, spec AutoscaleSpec) error
	// DeleteAutoscaler removes app's HorizontalPodAutoscaler. Deleting an absent HPA is a no-op, not
	// an error, so turning autoscaling off is idempotent.
	DeleteAutoscaler(ctx context.Context, app string) error
	// AutoscalerActive reports whether app has an active HorizontalPodAutoscaler owning its replica
	// count. A workload apply consults it so a deploy (or rollback, or config/secret reapply) leaves
	// the HPA-managed count untouched rather than resetting it. A missing HPA is reported as inactive
	// (false, nil), not an error.
	AutoscalerActive(ctx context.Context, app string) (bool, error)
	// MetricsAPIAvailable reports whether the metrics.k8s.io API group is served (metrics-server is
	// installed), so the engine can warn that an applied HPA will not scale until it is. It is
	// best-effort by contract: the engine treats an error as "absent" and warns rather than failing,
	// so a discovery hiccup never blocks applying the HPA.
	MetricsAPIAvailable(ctx context.Context) (bool, error)
	// Logs returns recent log lines for app's workload.
	Logs(ctx context.Context, app string, opts LogOptions) ([]LogLine, error)
	// DeleteWorkload removes app's workload. Deleting a missing workload returns
	// ErrNotFound.
	DeleteWorkload(ctx context.Context, app string) error

	// Expose makes app reachable at a hostname by creating (or updating) a Service and an
	// Ingress that routes the host to it (ADR-0018). It does not create the workload —
	// Deploy does — and whether the host is actually reachable also depends on an ingress
	// controller and DNS, which the reachability surface reports on.
	Expose(ctx context.Context, spec ExposeSpec) error
	// Unexpose removes the Service and Ingress created by Expose. Unexposing an app that
	// was never exposed returns ErrNotFound.
	Unexpose(ctx context.Context, app string) error
	// ExposureStatus reports whether app is exposed, at what host, and the external address
	// the ingress controller assigned its Ingress (read from the Ingress's
	// status.loadBalancer — empty until a controller processes it). A never-exposed app
	// returns a zero ExposureStatus and no error.
	ExposureStatus(ctx context.Context, app string) (ExposureStatus, error)

	// SecretKeys returns the env-var names held in app's per-app Secret
	// (burrow-app-<app>-secrets), sorted, never the values (ADR-0028/0004). A missing
	// Secret yields an empty slice and no error — an app with no secrets set.
	SecretKeys(ctx context.Context, app string) ([]string, error)
	// SetSecretValue upserts one key=value into app's per-app Secret, creating the
	// Secret if absent (ADR-0029). The value arrives over burrowd's authenticated
	// control-plane API and is written here to the Kubernetes Secret — it is NEVER
	// logged, never audited (the audit log records the key name only), never stored in
	// Postgres, and never carried over MCP. Any error this returns must name the app and
	// key only, never the value.
	SetSecretValue(ctx context.Context, app, key, value string) error
	// UnsetSecretKey removes one key from app's per-app Secret. A missing Secret or a
	// missing key is a no-op, not an error — unsetting what is already absent succeeds.
	// The value never crosses this seam: only the key name does.
	UnsetSecretKey(ctx context.Context, app, key string) error
	// RestartWorkload triggers a rolling update of app's Deployment by bumping the
	// pod-template annotation burrow.cloud/restarted-at to at. It is how a secret change
	// (read only at pod start via envFrom) forces the running app to pick it up. A missing
	// Deployment returns ErrNotFound; the caller treats that as "nothing running to roll".
	RestartWorkload(ctx context.Context, app string, at time.Time) error

	// RunBackupJob runs a one-shot Job in the add-on namespace that pg_dumps app's database on the
	// installed Postgres instance to /<backup-pvc>/<app>/<backupID>.dump (custom format), ensuring
	// the backup PVC first (ADR-0032). The Job connects as the superuser, reading the password from
	// the burrow-postgres Secret via secretKeyRef env — never a CLI argument, never logged. It
	// blocks until the Job completes, returns an error if the Job fails or times out, and reaps the
	// Job on success. It returns the dump's size in bytes when the dump container reported it (the
	// pod's terminated-state message), or 0 when unknown. app is validated before any Job is built.
	RunBackupJob(ctx context.Context, app, backupID string) (sizeBytes int64, err error)
	// RunRestoreJob runs a one-shot Job in the add-on namespace that pg_restores
	// /<backup-pvc>/<app>/<backupID>.dump into app's database (--clean --if-exists, so it replaces
	// current contents). Like RunBackupJob it reads the superuser password only via secretKeyRef,
	// blocks until the Job completes, errors on failure or timeout, and reaps the Job on success.
	// app is validated before any Job is built.
	RunRestoreJob(ctx context.Context, app, backupID string) error

	// RunJob runs spec.Command as a one-shot Job in the app namespace (this seam view's namespace),
	// built from the app's own current image (spec.Image) and its config env plus per-app Secret via
	// envFrom, so DATABASE_URL and every secret resolve as the app sees them (ADR-0048 §2). It blocks
	// until the Job finishes, then captures the pod's output and the container's exit code into a
	// RunResult and returns it. A non-zero exit is a NORMAL structured outcome, not an error: the
	// error return is reserved for a launch, poll, or timeout failure (ADR-0048 §3). The finished Job
	// is garbage-collected by Kubernetes' native ttlSecondsAfterFinished, set from spec.TTLSeconds, so
	// there is no imperative reap (ADR-0048 §7). spec.App is validated before any Job is built.
	RunJob(ctx context.Context, spec RunSpec) (RunResult, error)
}

type LoadBalancerCapability struct {
	Supported bool   `json:"supported"`
	Inferred  bool   `json:"inferred"`
	Provider  string `json:"provider,omitempty"`
}

type LogEntry struct {
	Time    string `json:"time,omitempty"`
	Message string `json:"message"`
	Pod     string `json:"pod,omitempty"`
}

type LogLine struct {
	Pod       string    `json:"pod"`
	Timestamp time.Time `json:"timestamp"`
	Message   string    `json:"message"`
}

type LogOptions struct {
	// TailLines bounds how many of the most recent lines to return. Zero means an
	// adapter-defined default.
	TailLines int
}

type LogsQuerier interface {
	// QueryLogs runs query against the logs store reachable at endpoint (an in-cluster
	// host:port) and returns up to limit matching records, most recent first. token is a bearer
	// credential for an authenticated backend; an empty token means unauthenticated and no
	// Authorization header is sent.
	QueryLogs(ctx context.Context, endpoint, query string, limit int, token string) ([]LogEntry, error)
}

type MetricSample struct {
	Labels map[string]string `json:"labels,omitempty"`
	Value  string            `json:"value"`
	Time   string            `json:"time,omitempty"`
}

type MetricsQuerier interface {
	// QueryMetrics runs an instant PromQL query against the Prometheus-API-compatible store reachable
	// at endpoint (an in-cluster host:port) and returns the matching samples. token is a bearer
	// credential for an authenticated backend; an empty token means unauthenticated and no
	// Authorization header is sent.
	QueryMetrics(ctx context.Context, endpoint, query string, token string) ([]MetricSample, error)
}

type MetricsServerCapability struct {
	Present bool `json:"present"`
}

type MissingPrerequisitesError struct {
	// Host is the hostname the exposure targeted.
	Host string
	// TLS reports whether the exposure asked for HTTPS (so TLS prerequisites applied).
	TLS bool
	// Missing enumerates the prerequisites that are absent, each with its fix.
	Missing []Prerequisite
}

type NextTagResult struct {
	App     string    `json:"app"`
	Env     string    `json:"env"`
	Current string    `json:"current,omitempty"`
	Next    *NextTags `json:"next,omitempty"`
	Note    string    `json:"note,omitempty"`
}

type NextTags struct {
	Patch string `json:"patch"`
	Minor string `json:"minor"`
	Major string `json:"major"`
}

type NodeAllocatable struct {
	Name      string
	CPUMillis int64
	MemBytes  int64
}

type NodeCapacity struct {
	Name           string `json:"name,omitempty"`
	Pods           int    `json:"pods"`
	AllocCPUMillis int64  `json:"alloc_cpu_millis"`
	UsedCPUMillis  int64  `json:"committed_cpu_millis"`
	FreeCPUMillis  int64  `json:"free_cpu_millis"`
	AllocMemBytes  int64  `json:"alloc_mem_bytes"`
	UsedMemBytes   int64  `json:"committed_mem_bytes"`
	FreeMemBytes   int64  `json:"free_mem_bytes"`
}

type PodRequest struct {
	Namespace string
	Name      string
	Node      string
	CPUMillis int64
	MemBytes  int64
}

type Policy struct {
	// Dispositions configures how each guardrail is enforced — allow, confirm, or deny
	// (ADR-0020), keyed by GuardrailCode. A guardrail with no entry here defaults to deny:
	// the safe default.
	Dispositions map[GuardrailCode]Disposition
	// MaxReplicas is the largest replica count permitted before the app.replica_ceiling
	// guardrail's disposition applies. Must be positive.
	MaxReplicas int32
}

type Prerequisite struct {
	// Name is the missing piece (e.g. "ingress controller", "cert-manager", "DNS provider").
	Name string `json:"name"`
	// Detail says what is missing and why the exposure needs it.
	Detail string `json:"detail"`
	// Fix is the burrow command that provisions it.
	Fix string `json:"fix"`
}

type Provider struct {
	// Name identifies the provider within the registry. It defaults to the type but can be
	// set explicitly so a user can register two providers of the same type. It must be a
	// DNS-1123 label.
	Name string `json:"name"`
	// Type is the vendor this provider talks to.
	Type ProviderType `json:"type"`
	// Capabilities are the services this provider serves, derived from its type.
	Capabilities []Capability `json:"capabilities"`
	// SecretKey is the key under which this provider's token lives in burrow-credentials.
	SecretKey string `json:"secret_key"`
	// CreatedAt is when the provider was registered, read from the injected clock.
	CreatedAt time.Time `json:"created_at"`
}

type ProviderCapability struct {
	Cloud string `json:"cloud,omitempty"`
	Name  string `json:"name,omitempty"`
}

type ProviderType string

type ReachabilityResult struct {
	App                string   `json:"app"`
	Deployed           bool     `json:"deployed"`
	Ready              bool     `json:"ready"`
	Exposed            bool     `json:"exposed"`
	Host               string   `json:"host,omitempty"`
	Address            string   `json:"address,omitempty"` // controller-assigned external address
	TLS                bool     `json:"tls"`               // the Ingress requests an HTTPS certificate
	CertReady          bool     `json:"cert_ready"`        // the requested TLS certificate has been issued
	DNSPointsAtCluster bool     `json:"dns_points_at_cluster"`
	DNSAddresses       []string `json:"dns_addresses,omitempty"`
	// Reachable is the converged verdict: every link in the chain is green and the app is live.
	Reachable bool `json:"reachable"`
	// URL is where the app is live when Reachable (https when TLS was requested, else http); it
	// is empty until Reachable.
	URL string `json:"url,omitempty"`
	// BlockedOn names the first unready link when not Reachable (e.g. "ingress controller",
	// "tls certificate", "dns"); it is empty when Reachable. It is the one link to fix next.
	BlockedOn string `json:"blocked_on,omitempty"`
	Summary   string `json:"summary"`
}

type RegistryAuth struct {
	Username string
	Password string
}

type RegistryClient interface {
	// ListTags returns the tags available in the repository named by imageRef (a reference
	// like "ghcr.io/user/app:1.2.3" or the bare repo). auth carries optional basic-auth
	// credentials for a private repo; the zero value lists anonymously. It follows the Docker
	// Registry HTTP API v2 tag-list pagination and the standard Bearer-token auth flow.
	ListTags(ctx context.Context, imageRef string, auth RegistryAuth) ([]string, error)
}

type Release struct {
	// ID is the control-plane-assigned identifier for this release. It is minted by
	// the deploy engine, not here, so the domain type stays free of ambient identity.
	ID string `json:"id"`
	// App is the name of the App this release belongs to.
	App string `json:"app"`
	// Environment is the canonical environment this release was deployed into (ADR-0052 §5):
	// a named environment, or "default" for the implicit default environment. Releases are
	// keyed per (app, environment), so an app can have an independent history in each.
	Environment string `json:"environment,omitempty"`
	// Image is the pullable container image reference the deploy named (ADR-0007).
	Image string `json:"image"`
	// Digest is the content digest of the running Image, when known (e.g. "sha256:...").
	// burrowd never resolves it against the registry (ADR-0040); it is an observed value
	// read back from Kubernetes, so it is empty until observed. Read-back is a deferred
	// follow-up (ADR-0040 §3), so for now it is left unset.
	Digest string `json:"digest,omitempty"`
	// Env is the environment passed to the workload.
	Env map[string]string `json:"env,omitempty"`
	// Command overrides the image's default command, when set.
	Command []string `json:"command,omitempty"`
	// MetricsPort, when positive, is the container port the app serves Prometheus metrics on.
	// The deploy annotates the pod (prometheus.io/scrape, /port, /path) so the metrics add-on's
	// scraper discovers and scrapes /metrics on it. Zero means no metrics annotations (ADR-0026).
	MetricsPort int32 `json:"metrics_port,omitempty"`
	// Replicas is the desired replica count.
	Replicas int32 `json:"replicas"`
	// Status is the lifecycle state of this release.
	Status ReleaseStatus `json:"status"`
	// Supersedes is the ID of the release this one replaced, if any — the chain that
	// lets rollback walk back to a prior known-good release.
	Supersedes string `json:"supersedes,omitempty"`
	// Trigger is how this deploy was triggered (ADR-0052 §5): "manual" for an explicit CLI or
	// agent deploy — the default for every deploy today — or "auto" for the pull-based passive
	// watcher (Phase 4b). Empty on rows written before provenance existed.
	Trigger ReleaseTrigger `json:"trigger,omitempty"`
	// AutoLevel is the auto-deploy level that applied when the watcher took this release
	// (ADR-0052 §5). Set only for an auto trigger; empty for a manual deploy.
	AutoLevel AutoDeployLevel `json:"auto_level,omitempty"`
	// AutoTag is the resolved tag the watcher moved to when it took this release (ADR-0052 §5).
	// Set only for an auto trigger; empty for a manual deploy.
	AutoTag string `json:"auto_tag,omitempty"`
	// CreatedAt is when the control plane recorded this release, read from the
	// injected clock (never from ambient time).
	CreatedAt time.Time `json:"created_at"`
}

type ReleaseStatus string

type ReleaseTrigger string

type RemoveDomainRequest struct {
	Host     string `json:"host"`
	Provider string `json:"provider"`
	// Confirm acknowledges the dns.delete guardrail so the operation proceeds past it.
	Confirm bool `json:"confirm,omitempty"`
}

type Resolver interface {
	// LookupHost returns the IP addresses host resolves to, or an error (e.g. NXDOMAIN).
	LookupHost(ctx context.Context, host string) ([]string, error)
}

type RollbackResult struct {
	// Release is the new release created by the rollback (carrying the prior
	// reference) and now running.
	Release Release `json:"release"`
	// RolledBackToReleaseID is the prior release whose reference was restored.
	RolledBackToReleaseID string `json:"rolled_back_to_release_id"`
	// SupersededReleaseID is the release that was running before the rollback.
	SupersededReleaseID string `json:"superseded_release_id"`
}

type RunRequest struct {
	App string `json:"app"`
	// Env is the environment whose namespace the command runs in (ADR-0035): empty or "default"
	// targets the default environment, a registered name targets that environment.
	Env string `json:"env,omitempty"`
	// Command is the command and its arguments to run, as an argv. It must be non-empty.
	Command []string `json:"command"`
	// TTLSeconds overrides how long the finished Job lingers before Kubernetes garbage-collects it
	// (ttlSecondsAfterFinished; ADR-0048 §7). Nil applies the default (one hour); a value — including
	// 0, delete as soon as the output is captured — overrides it. A negative value is rejected.
	TTLSeconds *int32 `json:"ttl_seconds,omitempty"`
	// Confirm acknowledges the app.run guardrail whose disposition is confirm, letting the command
	// proceed past it (ADR-0020). It has no effect on a guardrail set to deny.
	Confirm bool `json:"confirm,omitempty"`
}

type RunResult struct {
	App      string `json:"app"`
	ExitCode int    `json:"exit_code"`
	Stdout   string `json:"stdout,omitempty"`
	Stderr   string `json:"stderr,omitempty"`
	// TimedOut reports the command did not finish within the run window (10 minutes).
	TimedOut bool `json:"timed_out,omitempty"`
}

type RunSpec struct {
	App string
	// ID is the unique run identifier the Job name derives from (burrow-run-<ID>), minted by the
	// engine's ID seam so the Job name is deterministic in tests.
	ID string
	// Image is the app's currently-deployed image the command runs in (ADR-0048 §2).
	Image string
	// Command is the command and its arguments run as the container's command.
	Command []string
	// Env is the app's non-secret config, sourced as container env alongside the per-app Secret.
	Env map[string]string
	// TTLSeconds is the Job's ttlSecondsAfterFinished — how long the finished Job lingers before
	// Kubernetes garbage-collects it (ADR-0048 §7). Zero deletes it as soon as it finishes.
	TTLSeconds int32
}

type ScaleResult struct {
	App              string `json:"app"`
	PreviousReplicas int32  `json:"previous_replicas"`
	Replicas         int32  `json:"replicas"`
}

type SourceCredential struct {
	// Provider is the source provider the token authenticates (github, gitlab), which fixes the git
	// host and the registry host the token also covers (ADR-0057 §1).
	Provider ProviderType
	// Token is the provider token VALUE (an OSS Personal Access Token). It lives in memory in burrowd
	// only long enough to be written into the build Job's mounted Secret.
	Token string
}

type SourceRef struct {
	// Repo is the git repository URL to clone (e.g. "https://github.com/user/app").
	Repo string
	// Ref is the commit SHA or tag to check out. A build pins an exact reference, so it is required.
	Ref string
}

type StatusResult struct {
	App string `json:"app"`
	// HasRelease reports whether the control plane has any release recorded for the
	// app; Release holds the most recent one when true.
	HasRelease bool    `json:"has_release"`
	Release    Release `json:"release,omitempty"`
	// Running reports whether a workload currently exists in the cluster; Workload
	// holds its observed state when true.
	Running  bool           `json:"running"`
	Workload WorkloadStatus `json:"workload,omitempty"`
}

type StorageCapability struct {
	DefaultPresent bool     `json:"default_present"`
	DefaultClass   string   `json:"default_class,omitempty"`
	Classes        []string `json:"classes,omitempty"`
}

type WorkloadKind string

type WorkloadSpec struct {
	App     string
	Kind    WorkloadKind
	Image   string
	Env     map[string]string
	Command []string
	// MetricsPort, when positive, is the container port the app serves Prometheus metrics on.
	// buildDeployment annotates the pod template (prometheus.io/scrape, /port, /path) so the
	// metrics add-on's scraper discovers and scrapes /metrics on it. Zero adds no annotations.
	MetricsPort int32
	Replicas    int32
	// ReleaseID is the release this workload is applying. It is stamped on the pod template (under
	// ReleaseAnnotation) so a new release always rolls the workload, even when the image reference
	// is unchanged; re-applying the same release reuses the same ID, so the apply stays idempotent.
	// Empty adds no annotation.
	ReleaseID string
}

type WorkloadStatus struct {
	App             string       `json:"app"`
	Kind            WorkloadKind `json:"kind"`
	Image           string       `json:"image"`
	DesiredReplicas int32        `json:"desired_replicas"`
	ReadyReplicas   int32        `json:"ready_replicas"`
	UpdatedReplicas int32        `json:"updated_replicas"`
	// Available reports whether the workload currently meets its availability
	// condition (enough ready replicas to serve).
	Available bool `json:"available"`
	// Issue is a human- and agent-actionable explanation of why an unavailable workload is
	// blocked, when the cluster reports a genuinely blocking pod condition — e.g. a pull
	// failure that names the image, the registry host, and the `burrow config registry login`
	// fix (ADR-0006). It is best-effort enrichment: empty when the workload is healthy or
	// when no blocking condition was observed, so it never becomes a required field.
	Issue string `json:"issue,omitempty"`
	// IssueReason is the raw, machine-usable Kubernetes reason behind Issue (e.g.
	// "ImagePullBackOff" or "ErrImagePull"), for an agent that wants to branch on the cause
	// rather than parse the prose. Empty whenever Issue is empty.
	IssueReason string `json:"issue_reason,omitempty"`
}