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 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 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 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 Capability string

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"`
	// 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 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 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, or ErrNotFound
	// if the app has no releases.
	LatestRelease(ctx context.Context, app string) (Release, error)
	// Releases returns all releases for app, oldest first. An app with no releases
	// yields an empty slice and no error.
	Releases(ctx context.Context, app string) ([]Release, error)
	// DeleteReleases removes all release records for app — the durable side of an app
	// teardown. 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

	// 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"`
}

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
	// 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
}

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 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 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 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"`
	// 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"`
	// 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 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 ScaleResult struct {
	App              string `json:"app"`
	PreviousReplicas int32  `json:"previous_replicas"`
	Replicas         int32  `json:"replicas"`
}

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"`
}