client

type APIError struct {
	StatusCode int
	Code       string
	Message    string
	// NeedsConfirmation is true when a guardrail held the operation for confirmation
	// rather than refusing it: retrying with confirm set lets it proceed (ADR-0020).
	NeedsConfirmation bool
	// ServerVersion is the control plane's release version, set on a CodeClientTooOld refusal so a
	// client can name the version it must reach in an install-aware remedy of its own (ADR-0039).
	ServerVersion string
	// ServerInstallID is the id of the install that answered, set on a CodeInstallMismatch refusal
	// (ADR-0084 §5). It is the counterpart of ServerVersion: the refusal message already names both
	// ids, and carrying the answering one structurally lets a caller re-point a target at the install
	// that is actually there without parsing prose.
	ServerInstallID string
}

type AddProviderRequest struct {
	Name      string `json:"name,omitempty"`
	Type      string `json:"type"`
	SecretKey string `json:"secret_key,omitempty"`
	Token     string `json:"token,omitempty"`

	// The fields below configure an OBJECT-STORAGE provider (ADR-0063), whose credential is a PAIR
	// and whose configuration names a destination. AccessKeyID and SecretAccessKey are credential
	// VALUES and are held to exactly the same rules as Token: body only, never logged, never
	// echoed back.
	Endpoint        string `json:"endpoint,omitempty"`
	Region          string `json:"region,omitempty"`
	Bucket          string `json:"bucket,omitempty"`
	CreateBucket    bool   `json:"create_bucket,omitempty"`
	RetentionDays   int    `json:"retention_days,omitempty"`
	AccessKeyID     string `json:"access_key_id,omitempty"`
	SecretAccessKey string `json:"secret_access_key,omitempty"`
	Confirm         bool   `json:"confirm,omitempty"`
}

type Addon struct {
	// Name is the instance's name IN THE CLUSTER — what `kubectl get` shows. For an environment's
	// first instance it is the same string as Label; for every later one it is a generated
	// `burrow-<type>-<id>` the operator never types (ADR-0091 §2).
	Name string `json:"name"`
	Type string `json:"type"`
	// Label is what a person calls this instance: what `--name` takes and what a guardrail key holds
	// (ADR-0091 §1). Empty on a row from a control plane that predates labels, where the name is the
	// answer.
	Label string `json:"label,omitempty"`
	// Environment is the environment this instance serves (ADR-0067 §1): each environment gets its
	// own instance, so this is what distinguishes two rows of the same type.
	Environment string `json:"environment,omitempty"`
	Mode        string `json:"mode"`
	// Backend is the concrete implementation serving this instance: "victorialogs" for logs,
	// "cloudnative-pg" for the Postgres add-on, whose instance is a CloudNativePG Cluster the
	// operator reconciles (ADR-0066 §1).
	Backend      string   `json:"backend,omitempty"`
	Image        string   `json:"image,omitempty"`
	Endpoint     string   `json:"endpoint"`
	Capabilities []string `json:"capabilities"`
	Ready        bool     `json:"ready"`
	// Warning is a non-blocking note about the install, not persisted anywhere: today, that the
	// instance was created WITHOUT write-ahead-log archiving because the cluster has no pgBackRest
	// plugin, even though an object-storage destination is registered (ADR-0066 §3). Empty when
	// there is nothing to say.
	Warning string `json:"warning,omitempty"`
	// Backups is what this instance does about backups, read back from the instance itself at install
	// time. Nil on a row read from the registry: it is a fact about one moment, not a property of the
	// add-on, so it is never persisted.
	Backups *AddonBackups `json:"backups,omitempty"`
}

type AddonBackups struct {
	State string `json:"state"`
	// Provider is the registry name of the object store, reported only when the instance's own
	// repository is demonstrably the one that provider names.
	Provider string `json:"provider,omitempty"`
	// Bucket and RepoPath come from the instance's pgBackRest stanza, not from what the install
	// resolved.
	Bucket   string `json:"bucket,omitempty"`
	RepoPath string `json:"repo_path,omitempty"`
	// RetentionDays is how long a full backup is kept; 0 when the repository declares no window.
	RetentionDays int `json:"retention_days,omitempty"`
	// Schedule is the base backup's cron expression in CloudNativePG's six-field form (leading field
	// is seconds).
	Schedule string `json:"schedule,omitempty"`
	// BaseBackup is one of the AddonBaseBackup* values, empty when the instance does not archive.
	BaseBackup string `json:"base_backup,omitempty"`
	// Detail is one line elaborating the state, safe to print.
	Detail string `json:"detail,omitempty"`
}

type AddonListing struct {
	Addons          []Addon          `json:"addons"`
	RetainedVolumes []RetainedVolume `json:"retained_volumes,omitempty"`
}

type AddonSetting struct {
	Setting     string `json:"setting"`
	Value       string `json:"value"`
	Description string `json:"description"`
	// Consequence is what changing this setting does — that adding a standby restarts every attached
	// app, that a grown volume never shrinks. It rides the listing rather than living in help text
	// because the listing is where somebody is deciding whether to change the value.
	Consequence string `json:"consequence"`
}

type AddonSettingsResult struct {
	Addon       string         `json:"addon"`
	Environment string         `json:"environment"`
	Instance    string         `json:"instance"`
	Settings    []AddonSetting `json:"settings"`
}

type AttachResult struct {
	App   string `json:"app"`
	Addon string `json:"addon"`
	// Environment is the environment whose instance the database was provisioned on (ADR-0067 §1) —
	// which is what says WHICH database the app was given, since databases keep their simple names.
	Environment string `json:"environment,omitempty"`
	SecretKey   string `json:"secret_key"`
	// PreviousSecretKey is the name the attachment used before this call, present only when this
	// attach RENAMED it: the connection string moved to SecretKey and this key was removed, because
	// the attach rotated the password and the old name would otherwise hold a dead one (issue #462).
	PreviousSecretKey string `json:"previous_secret_key,omitempty"`
	// ReadSecretKey is the variable the READ ADDRESS was written under, present only when the
	// instance has a standby for it to point at (ADR-0081 §2). An instance with none has no `-ro`
	// endpoint, so the variable is absent rather than present and resolving to nothing.
	ReadSecretKey string `json:"read_secret_key,omitempty"`
}

type AuditEntry struct {
	ID            int64             `json:"id,omitempty"`
	Timestamp     time.Time         `json:"timestamp"`
	Operation     string            `json:"operation"`
	Target        string            `json:"target,omitempty"`
	Args          map[string]string `json:"args,omitempty"`
	GuardrailCode string            `json:"guardrail_code,omitempty"`
	Disposition   string            `json:"disposition,omitempty"`
	Outcome       string            `json:"outcome"`
	Result        string            `json:"result,omitempty"`
	Caller        string            `json:"caller,omitempty"`
	// Principal is the acting identity (the actor), distinct from Caller (the control-plane
	// boundary). The json tag must match the engine's AuditEntry.Principal tag exactly — the two
	// structs serialize/deserialize across the API, and a mismatched tag would silently drop the
	// field (ADR-0038).
	Principal string `json:"principal,omitempty"`
	// ClientVersion is the release version of the client that drove the operation, from the
	// X-Burrow-Client-Version handshake (ADR-0039). Empty for a pre-handshake client. The json tag
	// must match the engine's AuditEntry.ClientVersion tag exactly, or the field would silently drop.
	ClientVersion string `json:"client_version,omitempty"`
}

type AuditFilter struct {
	App       string
	Operation string
	Outcome   string
	Limit     int
}

type AutoDeployResult struct {
	App        string `json:"app"`
	Env        string `json:"env"`
	Level      string `json:"level"`
	Repository string `json:"repository,omitempty"`
	Current    string `json:"current,omitempty"`
	Target     string `json:"target,omitempty"`
	Upgrade    string `json:"upgrade,omitempty"`
	Checked    bool   `json:"checked,omitempty"`
	Note       string `json:"note,omitempty"`
	// DisabledReason is why auto-deploy is off when the safety stop turned it off (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 AutoscaleRequest struct {
	Env     string `json:"env,omitempty"`
	Min     int32  `json:"min"`
	Max     int32  `json:"max"`
	CPU     int32  `json:"cpu"`
	Memory  int32  `json:"memory,omitempty"`
	Confirm bool   `json:"confirm,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 Backup struct {
	ID string `json:"id"`
	// Kind is which mechanism took it: "logical" (one app's `pg_dump`) or "physical" (a
	// CloudNativePG base backup of the whole instance). A physical backup has no App.
	Kind string `json:"kind,omitempty"`
	App  string `json:"app"`
	// Environment is the environment whose instance the dump was taken from (ADR-0067 §1). A dump is
	// only a valid source for the environment it came from.
	Environment string `json:"environment,omitempty"`
	CreatedAt   string `json:"created_at"`
	Path        string `json:"path,omitempty"`
	// Volume is the claim the dump was written to — this environment's backup claim. Each
	// environment holds its dumps on its own volume, so the path alone does not address a dump.
	Volume    string `json:"volume,omitempty"`
	SizeBytes int64  `json:"size_bytes,omitempty"`
	Status    string `json:"status"`
	// Destination is where this backup's bytes ended up: "object-store" for one that left the
	// cluster, "cluster" for one that did not (ADR-0063). It is recorded per backup rather than
	// derived from the current configuration, so registering a destination today does not make
	// yesterday's in-cluster dumps read as durable.
	Destination string `json:"destination,omitempty"`
	// Provider and ObjectKey address the dump at the vendor. Names and a key, never a credential.
	Provider  string `json:"provider,omitempty"`
	ObjectKey string `json:"object_key,omitempty"`
	// FailureReason is why a failed backup failed, from a closed set a caller can branch on;
	// FailureDetail is one Burrow-authored line. Neither carries a vendor response body.
	FailureReason string `json:"failure_reason,omitempty"`
	FailureDetail string `json:"failure_detail,omitempty"`
}

type BackupDestinationHealth struct {
	Provider  string `json:"provider"`
	Endpoint  string `json:"endpoint,omitempty"`
	Bucket    string `json:"bucket,omitempty"`
	Reachable bool   `json:"reachable"`
	// Detail is one Burrow-authored line describing what was observed. Never a vendor response body
	// and never a credential.
	Detail string `json:"detail,omitempty"`
}

type BackupHealth struct {
	Addon       string `json:"addon"`
	App         string `json:"app,omitempty"`
	Environment string `json:"environment,omitempty"`
	ObservedAt  string `json:"observed_at"`
	// State is "never", "cluster-only" or "durable" — what kind of coverage exists, not a verdict
	// against a threshold.
	State string `json:"state"`
	// LastSuccess is the newest completed backup wherever it went; LastDurableSuccess is the newest
	// one that reached an object store, which is the age ADR-0063 §7 is about.
	LastSuccess        *BackupObservation `json:"last_success,omitempty"`
	LastDurableSuccess *BackupObservation `json:"last_durable_success,omitempty"`
	LastFailure        *BackupObservation `json:"last_failure,omitempty"`
	// Pending counts rows still recorded as pending. A pending row never reads as a success.
	Pending      int                       `json:"pending,omitempty"`
	Destinations []BackupDestinationHealth `json:"destinations,omitempty"`
	Summary      string                    `json:"summary"`
}

type BackupObservation struct {
	ID          string `json:"id"`
	App         string `json:"app"`
	Environment string `json:"environment,omitempty"`
	At          string `json:"at"`
	// AgeSeconds is how long ago the backup was recorded. Seconds, not a rendered duration, so a
	// caller compares a number rather than parsing prose.
	AgeSeconds  int64  `json:"age_seconds"`
	Status      string `json:"status"`
	Destination string `json:"destination,omitempty"`
	Provider    string `json:"provider,omitempty"`
	SizeBytes   int64  `json:"size_bytes,omitempty"`
	// Reason and Detail are set on a failure only. Neither carries a vendor response body.
	Reason string `json:"reason,omitempty"`
	Detail string `json:"detail,omitempty"`
}

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

type BearerTransport struct {
	// BaseURL is the control plane's origin, e.g. https://burrow-cloud.dev. It must be HTTPS: a
	// bearer credential is a password on every request, and Connect refuses to put one on the wire in
	// the clear.
	BaseURL string
	// Token is the stored credential. It is never rendered — not by Connect, not by an error from
	// this file, and not by the client this returns.
	Token string
	// Name is the calling binary (ClientNameCLI or ClientNameAgent), sent as X-Burrow-Client so a
	// too-old refusal names the binary the user must actually update (ADR-0039). Empty omits it.
	Name string
	// Version is this client's release version, sent as X-Burrow-Client-Version so the control plane
	// can make version skew legible instead of opaque (ADR-0039). Empty omits the header.
	Version string
	// InstallID is the install this caller expects to reach, sent as X-Burrow-Install (ADR-0084 §5).
	// It is empty for the managed product, which is one control plane rather than an install someone
	// stood up and could stand up again — there is no id to record and nothing to confuse it with.
	// The field is here because this is the second of the two places every outbound request passes
	// through, and a self-hosted burrowd given a front door of its own (ADR-0084 §7) is reached over
	// exactly this transport. Leaving the header out of one choke point would make the check hold
	// only for whichever route a caller happened to take.
	InstallID string
	// Rejected is what the caller is told when the control plane refuses the credential. It exists
	// because a bare 401 is the least useful thing a signed-in person can be shown: the credential
	// was accepted an hour ago, so what changed is worth naming — it was revoked from the console, or
	// the sign-in it came from no longer exists. Each binary supplies its own wording because the
	// remedy differs. Empty falls back to a generic sentence rather than showing the raw refusal.
	Rejected string
}

type BuildRequest struct {
	Env         string    `json:"env,omitempty"`
	Source      SourceRef `json:"source"`
	TargetImage string    `json:"target_image"`
	Confirm     bool      `json:"confirm,omitempty"`
	// Progress receives the build's stages as the control plane reports them (issue #503): the build's
	// own stages and then the deploy stages it hands off to, as one continuous sequence. Setting it is
	// what asks for them: Build then negotiates the streaming response, and a control plane that does
	// not offer one is handled transparently. Nil — the default, and the shape that goes on the wire,
	// since json ignores this field — is the build this package has always issued.
	//
	// It is called from Build's own goroutine as each line arrives, so a slow reporter slows the read.
	// It is never called after Build returns.
	Progress func(DeployProgress) `json:"-"`
}

type BuildResult struct {
	Digest string       `json:"digest"`
	Deploy DeployResult `json:"deploy"`
}

type CapacityReport struct {
	Nodes           []NodeCapacity `json:"nodes"`
	Cluster         NodeCapacity   `json:"cluster"`
	TopCPU          []Consumer     `json:"top_cpu"`
	TopMemory       []Consumer     `json:"top_memory"`
	BuildCPUMillis  int64          `json:"build_cpu_millis"`
	BuildMemBytes   int64          `json:"build_mem_bytes"`
	BuildFits       bool           `json:"build_fits"`
	BuildFitsNode   string         `json:"build_fits_node,omitempty"`
	Verdict         string         `json:"verdict"`
	UtilizationNote string         `json:"utilization_note"`
}

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

type ChecksResult struct {
	App          string       `json:"app"`
	Environment  string       `json:"environment,omitempty"`
	Enabled      bool         `json:"enabled"`
	Dependencies []Dependency `json:"dependencies"`
	Note         string       `json:"note,omitempty"`
}

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

type CloudNativePGCapability struct {
	Present bool   `json:"present"`
	Ready   bool   `json:"ready"`
	Version string `json:"version,omitempty"`
	Pinned  string `json:"pinned,omitempty"`
}

type ClusterCapabilities struct {
	Ingress       IngressCapability       `json:"ingress"`
	Storage       StorageCapability       `json:"storage"`
	LoadBalancer  LoadBalancerCapability  `json:"load_balancer"`
	CertManager   CertManagerCapability   `json:"cert_manager"`
	MetricsServer MetricsServerCapability `json:"metrics_server"`
	CloudNativePG CloudNativePGCapability `json:"cloudnative_pg"`
	PgBackRest    PgBackRestCapability    `json:"pgbackrest"`
	// ControlPlaneDatabase is which shape the control plane's own database runs in (ADR-0086 §2).
	ControlPlaneDatabase ControlPlaneDatabaseCapability `json:"control_plane_database"`
	Provider             ProviderCapability             `json:"provider"`
	DNS                  DNSCapability                  `json:"dns"`
}

type ClusterCredential struct {
	// PrincipalID is the opaque, stable identity this credential authenticates as.
	PrincipalID string `json:"principal_id"`
	// Principal is that principal's human-readable handle.
	Principal string `json:"principal"`
	// Admin is whether the principal may issue a credential for somebody else.
	Admin bool `json:"admin"`
	// CredentialID is which credential this is, so a revocation can name it.
	CredentialID string `json:"credential_id"`
	// Kind is what the credential is held by, as burrowd STORED it. It is reported, never chosen:
	// a caller-declared kind would make a `deny` that binds the agent cooperative (ADR-0084 §3).
	Kind string `json:"kind"`
	// ExpiresAt is when the credential stops authenticating, RFC 3339, or empty when it does not.
	ExpiresAt string `json:"expires_at,omitempty"`
	// InstallID is the id of the install that issued this. It is what lets the caller record, in the
	// same round trip, which Burrow the credential belongs to (ADR-0084 §5) — a fact a second person
	// has no other authenticated way to learn before they hold a credential.
	InstallID string `json:"install_id,omitempty"`
	// Token is the secret. See the type's own note.
	Token string `json:"token"`
}

type ConfigureAddonResult struct {
	Addon       string `json:"addon"`
	Environment string `json:"environment"`
	Instance    string `json:"instance"`
	Setting     string `json:"setting"`
	From        string `json:"from"`
	To          string `json:"to"`
	// Changed is false when the instance was already in the shape that was asked for; nothing was
	// written and nothing was restarted.
	Changed     bool              `json:"changed"`
	ReadAddress ReadAddressChange `json:"read_address"`
}

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 ControlPlaneDatabaseCapability struct {
	Kind     string `json:"kind,omitempty"`
	Ready    bool   `json:"ready"`
	BackedUp bool   `json:"backed_up"`
}

type Coverage struct {
	Since          time.Time           `json:"since"`
	Until          time.Time           `json:"until"`
	Windows        []ObservationWindow `json:"windows"`
	Gaps           []CoverageGap       `json:"gaps"`
	DegradedSweeps int64               `json:"degraded_sweeps,omitempty"`
	Detail         string              `json:"detail,omitempty"`
}

type CoverageGap struct {
	From time.Time `json:"from"`
	To   time.Time `json:"to"`
}

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

type Dependency struct {
	Kind        string `json:"kind"`
	Provisioned string `json:"provisioned"`
	EnvKey      string `json:"env_key,omitempty"`
	Endpoint    string `json:"endpoint,omitempty"`
}

type DependencyResult struct {
	Kind    string `json:"kind"`
	Outcome string `json:"outcome"`
	Reason  string `json:"reason,omitempty"`
	Detail  string `json:"detail,omitempty"`
	Status  int    `json:"status,omitempty"`
}

type DeployProgress struct {
	Stage  string `json:"stage"`
	Status string `json:"status"`
}

type DeployRequest struct {
	Env         string   `json:"env,omitempty"`
	Image       string   `json:"image"`
	Command     []string `json:"command,omitempty"`
	MetricsPort int32    `json:"metrics_port,omitempty"`
	Replicas    int32    `json:"replicas"`
	Confirm     bool     `json:"confirm,omitempty"`
	// NoWait asks the control plane to answer at submission instead of at outcome (ADR-0092 §3): the
	// Deployment is written and the deploy returns without observing whether the new pods became
	// ready, so DeployResult.Rollout is nil. The default — waiting — is the zero value.
	NoWait bool `json:"no_wait,omitempty"`
	// Progress receives the deploy's stages as the control plane reports them (issue #480). Setting
	// it is what asks for them: Deploy then negotiates the streaming response, and a control plane
	// that does not offer one is handled transparently. Nil — the default, and the shape that goes on
	// the wire, since json ignores this field — is the deploy this package has always issued.
	//
	// It is called from Deploy's own goroutine as each line arrives, so a slow reporter slows the
	// read. It is never called after Deploy returns.
	Progress func(DeployProgress) `json:"-"`
}

type DeployResult struct {
	Release             Release `json:"release"`
	SupersededReleaseID string  `json:"superseded_release_id,omitempty"`
	// Hints are non-blocking notes about the deploy (ADR-0052 §8): today, a nudge toward semver when
	// the deployed tag cannot be classified for auto-update. They never gate the deploy.
	Hints []string `json:"hints,omitempty"`
	// Dependencies is what the deploy-time dependency check found (ADR-0076 §4): for each thing
	// Burrow provisioned for this app, whether the app could reach it from inside its own container.
	// A failed entry sits on a SUCCESSFUL deploy — the check is reported, never fatal.
	Dependencies []DependencyResult `json:"dependencies,omitempty"`
	// Rollout is what the deploy observed of its own rollout (ADR-0092): whether the new replicas
	// became ready, and if not, why. NIL MEANS UNOBSERVED and never "fine" — a deploy that was asked
	// not to wait (DeployRequest.NoWait), or a control plane older than the field.
	Rollout *RolloutReport `json:"rollout,omitempty"`
}

type DetachAddonOptions struct {
	// Instance is the LABEL of the instance to detach from (ADR-0091 §3). Empty is the environment's
	// default instance; detaching one attachment leaves every other one the app holds alone.
	Instance string
	// DeleteData also DESTROYS the app's database, with its rows (ADR-0090 §2). Without it the detach
	// takes the app's access away and keeps the data, so re-attaching gets it back.
	DeleteData bool
	// Confirm satisfies the addon.detach guardrail hold. It is not the data-loss acknowledgement.
	Confirm bool
}

type DirectTransport struct {
	BaseURL string
	Token   string
	// Name is the calling binary (ClientNameCLI or ClientNameAgent), sent as X-Burrow-Client so a
	// too-old refusal names the binary the user must actually update (ADR-0039). Empty omits it.
	Name string
	// Version is this client's release version, sent as X-Burrow-Client-Version so burrowd can make
	// version skew legible instead of opaque (ADR-0039). Empty omits the header.
	Version string
	// InstallID is the install this caller expects to reach, sent as X-Burrow-Install so a control
	// plane that is a different install refuses the request and says so (ADR-0084 §5). Empty omits
	// the header, and is served.
	InstallID string
}

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

type Environment struct {
	Name      string `json:"name"`
	Namespace string `json:"namespace"`
	Default   bool   `json:"default"`
}

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

type Failure struct {
	ID     int64     `json:"id,omitempty"`
	Object ObjectRef `json:"object"`
	// Reason is a member of the ledger's closed vocabulary — the field to branch on, in preference
	// to parsing Detail.
	Reason string `json:"reason"`
	// Detail is one bounded, Burrow-authored line of context. It never carries a secret value.
	Detail string `json:"detail,omitempty"`
	// FirstSeen is when the failure began: the answer to "when did it start".
	FirstSeen time.Time `json:"first_seen"`
	// LastSeen is when it was last observed: the answer to "is it still happening".
	LastSeen time.Time `json:"last_seen"`
	// ResolvedAt is when it stopped being observed, nil while it is still active.
	ResolvedAt *time.Time `json:"resolved_at,omitempty"`
	// Occurrences is how many observations found it present, counting the one that opened the row.
	Occurrences int64 `json:"occurrences"`
}

type FailureKind = string

type FailureQuery struct {
	// Kind restricts to one class of object (app, addon, backup, exposure); empty matches any.
	Kind FailureKind
	// Name restricts to one object name; empty matches any.
	Name string
	// Env restricts to one environment; empty matches any.
	Env string
	// Reason restricts to one reason from the ledger's closed vocabulary; empty matches any.
	Reason string
	// Since bounds the answer to failures last seen within this much of now and widens it to
	// history. It is sent as a duration and resolved against the CONTROL PLANE's clock, which is the
	// clock that wrote the rows.
	Since time.Duration
	// All widens the answer to resolved failures with no time bound beyond the ledger's retention.
	All bool
	// Limit caps the rows returned. Zero applies the server's default cap.
	Limit int
}

type FailureReport struct {
	Failures []Failure `json:"failures"`
	Coverage Coverage  `json:"coverage"`
}

type GuardScope struct {
	Env  string
	Name string
}

type Guardrail struct {
	Code        string `json:"code"`
	Disposition string `json:"disposition"`
	Description string `json:"description"`
	// Source reports where a guardrail's effective disposition came from when listed for something
	// narrower than the whole cluster (ADR-0035 phase 2c, ADR-0085 §2): "name" (set for the one app
	// or add-on instance asked about), "env" (an environment-specific override), "global" (the
	// global policy), or "default" (the built-in default). It is empty in the global listing.
	Source string `json:"source,omitempty"`
}

type HealthResult struct {
	App         string `json:"app"`
	Environment string `json:"environment,omitempty"`
	// Path and Port are the DECLARED endpoint; empty and zero when none was declared.
	Path string `json:"path,omitempty"`
	Port int32  `json:"port,omitempty"`
	// Probe is what Burrow authors: "http", "tcp", or "none".
	Probe     string `json:"probe"`
	ProbePort int32  `json:"probe_port,omitempty"`
	ProbePath string `json:"probe_path,omitempty"`
	// Source is where the probe came from: "endpoint", "exposure" (the conservative TCP default on
	// the published port), or "none".
	Source string `json:"source"`
	// Liveness is always false: Burrow never sets a liveness probe by default (ADR-0076 §1). It is
	// reported anyway because "does this restart my container?" is the first question a reader has.
	Liveness bool `json:"liveness"`
	// Hint is the ADR-0076 §5 guidance, present when no endpoint has been declared.
	Hint string `json:"hint,omitempty"`
	// AppliesOn says when the reported probe reaches the running pods, when it is not there yet.
	AppliesOn string `json:"applies_on,omitempty"`
}

type Hook struct {
	App         string   `json:"app"`
	Environment string   `json:"environment"`
	Phase       string   `json:"phase"`
	Command     []string `json:"command"`
}

type IngressCapability struct {
	Present bool     `json:"present"`
	Classes []string `json:"classes,omitempty"`
}

type InstallAddonOptions struct {
	// Name is the LABEL of the instance to install: naming one stands a SECOND instance up beside the
	// environment's own (ADR-0091 §1). Empty is the environment's default instance, which is what
	// every add-on command has always meant.
	Name string
	// Confirm satisfies the addon.install guardrail's confirmation hold.
	Confirm bool
	// ArchiveDestination names the object-storage provider a Postgres instance archives to
	// (ADR-0066 §3). Only needed when more than one is registered.
	ArchiveDestination string
}

type LifecycleCheck struct {
	Status string `json:"status"`
	Detail string `json:"detail"`
	Rule   string `json:"rule,omitempty"`
	Backup string `json:"backup,omitempty"`
}

type Limit struct {
	Code        string `json:"code"`
	Value       string `json:"value"`
	Description string `json:"description"`
	Kind        string `json:"kind"`
	Scope       string `json:"scope"`
	EnvScoped   bool   `json:"env_scoped"`
	Default     string `json:"default"`
}

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 MetricSample struct {
	Labels map[string]string `json:"labels,omitempty"`
	Value  string            `json:"value"`
	Time   string            `json:"time,omitempty"`
}

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

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 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 ObjectRef struct {
	Kind        FailureKind `json:"kind"`
	Name        string      `json:"name"`
	Environment string      `json:"environment,omitempty"`
}

type ObjectStoreConfig struct {
	Endpoint           string `json:"endpoint"`
	Region             string `json:"region,omitempty"`
	Bucket             string `json:"bucket"`
	Created            bool   `json:"created,omitempty"`
	AccessKeyIDKey     string `json:"access_key_id_key"`
	SecretAccessKeyKey string `json:"secret_access_key_key"`
	RetentionDays      int    `json:"retention_days,omitempty"`
}

type ObservationWindow struct {
	ID             int64     `json:"id,omitempty"`
	StartedAt      time.Time `json:"started_at"`
	Until          time.Time `json:"until"`
	Sweeps         int64     `json:"sweeps"`
	DegradedSweeps int64     `json:"degraded_sweeps,omitempty"`
	Detail         string    `json:"detail,omitempty"`
}

type PgBackRestCapability struct {
	Present bool   `json:"present"`
	Ready   bool   `json:"ready"`
	Pinned  string `json:"pinned,omitempty"`
}

type Provider struct {
	Name         string    `json:"name"`
	Type         string    `json:"type"`
	Capabilities []string  `json:"capabilities"`
	SecretKey    string    `json:"secret_key"`
	CreatedAt    time.Time `json:"created_at"`
	// ObjectStore is the non-secret destination an object-storage provider was registered with —
	// endpoint, region, the RECORDED bucket, and the NAMES of the two burrow-credentials keys
	// holding the credential pair (ADR-0063 §1). Nil for every other provider type.
	ObjectStore *ObjectStoreConfig `json:"object_store,omitempty"`
	// Verification is what configuration-time verification observed: the probe object written and
	// deleted, the bucket, and the lifecycle reconciliation (ADR-0063 §2-§4). It is present on the
	// registration that performed the checks and absent from a listing, because it describes one
	// moment rather than a stored fact.
	Verification *ProviderVerification `json:"verification,omitempty"`
}

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

type ProviderVerification struct {
	Bucket        string         `json:"bucket"`
	BucketCreated bool           `json:"bucket_created"`
	ProbeObject   bool           `json:"probe_object"`
	Lifecycle     LifecycleCheck `json:"lifecycle"`
}

type PublishRequest struct {
	Env      string `json:"env,omitempty"`
	Host     string `json:"host"`
	Port     int32  `json:"port"`
	NoTLS    bool   `json:"no_tls,omitempty"`
	Issuer   string `json:"issuer,omitempty"`
	SkipDNS  bool   `json:"skip_dns,omitempty"`
	Provider string `json:"provider,omitempty"`
	Confirm  bool   `json:"confirm,omitempty"`
}

type PublishResult struct {
	App                string `json:"app"`
	Env                string `json:"env,omitempty"`
	Host               string `json:"host"`
	Port               int32  `json:"port"`
	URL                string `json:"url,omitempty"`
	Address            string `json:"address,omitempty"`
	Exposed            bool   `json:"exposed"`
	DNSProvider        string `json:"dns_provider,omitempty"`
	DNSRecordType      string `json:"dns_record_type,omitempty"`
	DNSPointsAtCluster bool   `json:"dns_points_at_cluster"`
	HTTPVerified       bool   `json:"http_verified"`
	TLSRequested       bool   `json:"tls_requested"`
	TLSAttached        bool   `json:"tls_attached"`
	CertReady          bool   `json:"cert_ready"`
	Reachable          bool   `json:"reachable"`
	BlockedOn          string `json:"blocked_on,omitempty"`
	Next               string `json:"next,omitempty"`
	Summary            string `json:"summary"`
}

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"`
	TLS                bool     `json:"tls"`
	CertReady          bool     `json:"cert_ready"`
	DNSPointsAtCluster bool     `json:"dns_points_at_cluster"`
	DNSAddresses       []string `json:"dns_addresses,omitempty"`
	Reachable          bool     `json:"reachable"`
	URL                string   `json:"url,omitempty"`
	BlockedOn          string   `json:"blocked_on,omitempty"`
	Summary            string   `json:"summary"`
}

type ReadAddressChange struct {
	Action   string        `json:"action"`
	Apps     []string      `json:"apps"`
	Stranded []StrandedApp `json:"stranded,omitempty"`
	Note     string        `json:"note,omitempty"`
}

type Release struct {
	ID          string            `json:"id"`
	App         string            `json:"app"`
	Environment string            `json:"environment,omitempty"`
	Image       string            `json:"image"`
	Digest      string            `json:"digest,omitempty"`
	Env         map[string]string `json:"env,omitempty"`
	Command     []string          `json:"command,omitempty"`
	Replicas    int32             `json:"replicas"`
	Status      string            `json:"status"`
	Supersedes  string            `json:"supersedes,omitempty"`
	// Trigger is how the deploy was triggered (ADR-0052 §5): "manual" for an explicit CLI or agent
	// deploy, "auto" for the pull-based passive watcher. AutoLevel and AutoTag are set only for auto.
	Trigger   string `json:"trigger,omitempty"`
	AutoLevel string `json:"auto_level,omitempty"`
	AutoTag   string `json:"auto_tag,omitempty"`
	// Rollout is what the deploy observed of this release's rollout (ADR-0092 §4): "settled",
	// "unsettled", or empty when the deploy did not wait. It sits BESIDE Status, which records what
	// Burrow applied rather than what the cluster then did with it. RolloutReason names why an
	// unsettled rollout did not settle.
	Rollout       string    `json:"rollout,omitempty"`
	RolloutReason string    `json:"rollout_reason,omitempty"`
	CreatedAt     time.Time `json:"created_at"`
}

type RemoveAddonOptions struct {
	// Environment scopes a removal that names an instance by its LABEL rather than by its registry
	// name (ADR-0091 §2): a label is unique within an environment, so `analytics` needs to know which
	// one. A removal that names a registry name needs none of it and keeps its old shape.
	Environment string
	// DeleteData is the explicit opt-in that also DESTROYS the add-on's data volume — for Postgres,
	// every attached app's database. Without it the removal tears down the workload and leaves the
	// volume, so a reinstall picks the data back up.
	DeleteData bool
	// SkipFinalBackup destroys the data without the final backup ADR-0064 §5 otherwise takes first.
	// It exists because an add-on is often removed BECAUSE it is wedged, and a wedged instance
	// cannot be dumped — without it a broken add-on would be undeletable.
	SkipFinalBackup bool
	// BackupDestination names the object-storage provider the final backup goes to, needed only when
	// several are registered.
	BackupDestination string
	// Confirm satisfies the addon.remove guardrail hold. It is not the data-loss acknowledgement.
	Confirm bool
}

type RemoveAddonResult struct {
	// Instance is the LABEL the operator addressed the instance by (ADR-0091 §1). Empty from a
	// control plane that predates labels, where Name is the answer.
	Instance string `json:"instance,omitempty"`
	Name     string `json:"name"`
	Type     string `json:"type"`
	// Namespace is where the add-on's resources, and any retained volume, live.
	Namespace string `json:"namespace,omitempty"`
	// DataDeleted reports whether the add-on's data volume was destroyed.
	DataDeleted bool `json:"data_deleted"`
	// RetainedDataVolume is the PVC left in place; empty when the add-on had no volume or it was
	// deleted.
	RetainedDataVolume string `json:"retained_data_volume,omitempty"`
	// RetainedBackupVolume is the backup PVC left in place; empty when no backup volume exists.
	RetainedBackupVolume string `json:"retained_backup_volume,omitempty"`
	// AttachedApps are the apps that held a database on this instance at removal time.
	AttachedApps []string `json:"attached_apps,omitempty"`
	// FinalBackups are the backups taken before the data volume was destroyed, one per attached
	// database (ADR-0064 §5). Each reached an object store — the removal is abandoned otherwise — so
	// this is the list of copies that outlived the instance.
	FinalBackups []Backup `json:"final_backups,omitempty"`
	// FinalBackupSkipped reports that the data was destroyed with no off-cluster copy, and
	// FinalBackupNote says why. Reported rather than inferred from an empty FinalBackups: "nothing
	// was backed up" and "nothing needed backing up" must not look the same.
	FinalBackupSkipped bool   `json:"final_backup_skipped,omitempty"`
	FinalBackupNote    string `json:"final_backup_note,omitempty"`
}

type RestoreInstanceOptions struct {
	// Instance is the LABEL of the instance to rewind (ADR-0091 §4). Empty is the environment's
	// default instance.
	Instance         string
	Backup           string
	ToTime           string
	Latest           bool
	SkipSafetyBackup bool
	// Destination names the object-storage provider holding this instance's repository; empty
	// resolves it when exactly one is registered.
	Destination string
	Confirm     bool
}

type RestoreInstanceResult struct {
	Addon       string `json:"addon"`
	Environment string `json:"environment"`
	Instance    string `json:"instance"`
	// RecoveryTarget is the point that was recovered to. It is deliberately not `target`, which is
	// the control plane the command acted on (ADR-0078 §4).
	RecoveryTarget string `json:"recovery_target"`
	// SafetyBackup is the physical backup taken of the pre-restore state, which is the way back from
	// a restore to the wrong point. SafetyBackupNote says why there is none when there is none.
	SafetyBackup     string `json:"safety_backup,omitempty"`
	SafetyBackupNote string `json:"safety_backup_note,omitempty"`
	// Apps is every app that was on the instance, by name — the blast radius, recorded rather than
	// counted. Reconnected is those now pointing at the recovered instance; Stranded is those the
	// cutover could not finish for.
	Apps        []string      `json:"apps"`
	Reconnected []string      `json:"reconnected"`
	Stranded    []StrandedApp `json:"stranded,omitempty"`
	// Verification is what the recovered instance was found to hold before any app was reconnected
	// to it — the answer to "is the data actually there", which is the only question a restore is
	// asked. A recovery that came up holding none of it is an ERROR rather than a result carrying a
	// bad status, so what arrives here is confirmed or unknown.
	Verification RestoreVerification `json:"verification"`
}

type RestoreVerification struct {
	Status    string   `json:"status"`
	Databases []string `json:"databases"`
	Missing   []string `json:"missing,omitempty"`
	Note      string   `json:"note,omitempty"`
}

type RetainedVolume struct {
	// Name is the claim name — what `kubectl delete pvc` takes to reclaim the storage.
	Name string `json:"name"`
	// Namespace is the add-on namespace the claim lives in.
	Namespace string `json:"namespace,omitempty"`
	// Addon is the add-on type the volume belonged to.
	Addon string `json:"addon"`
	// Environment is the environment the claim served (ADR-0067 §1). Empty for a claim created
	// before add-ons were per-environment, which is the default environment's.
	Environment string `json:"environment,omitempty"`
	// Role is what the claim holds: "data" (the add-on's own volume) or "backup" (its dumps).
	Role string `json:"role"`
	// Size is the claim's capacity, e.g. "10Gi". Size, not cost: cost needs the provider's pricing.
	Size string `json:"size,omitempty"`
	// ReinstallAdopts reports whether reinstalling the add-on picks this volume back up with its
	// data intact.
	ReinstallAdopts bool `json:"reinstall_adopts"`
}

type RollbackOptions struct {
	// Confirm satisfies a guardrail whose disposition holds the rollback for confirmation.
	Confirm bool
	// SkipHooks rolls back without running the app's `pre-rollback` hook. The hook stays configured
	// and the control plane records the skip. It is set by the operator CLI's `--skip-hooks` and by
	// nothing on the agent surface (ADR-0080 §3).
	SkipHooks bool
	// NoWait returns at submission instead of waiting for the restored image's rollout, and reports
	// the outcome as unknown rather than as good (ADR-0093 §2). The zero value waits, so a caller that
	// does not set it gets the report; it is set by the operator CLI's `--wait=false` and by nothing
	// on the agent surface.
	NoWait bool
}

type RollbackResult struct {
	Release               Release `json:"release"`
	RolledBackToReleaseID string  `json:"rolled_back_to_release_id"`
	// SupersededReleaseID is the release being rolled back AWAY FROM, which is the one still serving
	// when the rollback's rollout does not become ready (ADR-0093 §2).
	SupersededReleaseID string `json:"superseded_release_id"`
	// Rollout is what the rollback observed of its own rollout (ADR-0093 §1): whether the restored
	// image's replicas became ready, and if not, why. NIL MEANS UNOBSERVED and never "fine" — a
	// rollback asked not to wait (RollbackOptions.NoWait), or a control plane older than the field.
	Rollout *RolloutReport `json:"rollout,omitempty"`
	// Hints are the control plane's non-blocking notes about the rollback: that a `pre-rollback` hook
	// was skipped and which command did not run (ADR-0080 §4), and what a `post-deploy` hook made of
	// the rollout (ADR-0072 §4). The field must exist here or the notes are decoded away before any
	// caller sees them — a skip that is reported to nobody is the silence the flag exists to avoid.
	Hints []string `json:"hints,omitempty"`
}

type RolloutReport struct {
	Settled bool   `json:"settled"`
	Reason  string `json:"reason,omitempty"`
	Detail  string `json:"detail,omitempty"`
	Issue   string `json:"issue,omitempty"`
}

type RunRequest struct {
	Env        string   `json:"env,omitempty"`
	Command    []string `json:"command"`
	TTLSeconds *int32   `json:"ttl_seconds,omitempty"`
	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 bool   `json:"timed_out,omitempty"`
}

type SQLError struct {
	Message  string `json:"message"`
	SQLState string `json:"sqlstate,omitempty"`
	Detail   string `json:"detail,omitempty"`
	Hint     string `json:"hint,omitempty"`
	Position int32  `json:"position,omitempty"`
}

type SQLResult struct {
	Addon       string   `json:"addon"`
	App         string   `json:"app"`
	Environment string   `json:"environment"`
	Columns     []string `json:"columns"`
	// Rows are the result's rows, aligned with Columns. A NULL is a nil entry (JSON null), which is
	// the distinction a plain string per cell would lose.
	Rows     [][]*string `json:"rows"`
	RowCount int         `json:"row_count"`
	// Truncated reports the result had more rows than RowLimit and the rest were not read — reported
	// rather than silent (ADR-0087 §7).
	Truncated bool `json:"truncated"`
	RowLimit  int  `json:"row_limit"`
	// Command is Postgres's command tag ("SELECT 3", "UPDATE 2"), absent for a truncated read.
	Command      string    `json:"command,omitempty"`
	RowsAffected int64     `json:"rows_affected"`
	Error        *SQLError `json:"error,omitempty"`
}

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

type SecretMount struct {
	Key      string `json:"key"`
	Filename string `json:"filename"`
	Path     string `json:"path"`
	// NoEnv is true when the key is FILE-ONLY: read from the file above and kept out of the app's
	// environment (ADR-0089 §4). False is the default a mount arrives with — it adds a file and
	// leaves the variable alone.
	NoEnv bool `json:"no_env"`
}

type SecretMounts struct {
	Dir        string        `json:"dir"`
	Enumerated bool          `json:"enumerated"`
	Mounts     []SecretMount `json:"mounts"`
}

type SourceRef struct {
	Repo string `json:"Repo"`
	Ref  string `json:"Ref"`
}

type StatusResult struct {
	App        string         `json:"app"`
	HasRelease bool           `json:"has_release"`
	Release    Release        `json:"release,omitempty"`
	Running    bool           `json:"running"`
	Workload   WorkloadStatus `json:"workload,omitempty"`
	// Failures is the app's recent failure history from the ledger (ADR-0074 §8), oldest first,
	// resolved episodes included. Workload above is the live present tense; this is the part
	// nothing can reconstruct afterwards — whether it crash-looped at 02:00 and recovered.
	Failures []Failure `json:"failures,omitempty"`
	// Coverage is what the observer was doing over that window. An empty Failures list means
	// "nothing broke" only if Coverage says something was watching.
	Coverage Coverage `json:"coverage"`
}

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

type StrandedApp struct {
	App    string `json:"app"`
	Reason string `json:"reason"`
}

type Transport interface {
	// Connect returns a control-plane API client, resolving any credential it needs.
	Connect(ctx context.Context) (*Client, error)
}

type WorkloadStatus struct {
	App             string `json:"app"`
	Kind            string `json:"kind"`
	Image           string `json:"image"`
	DesiredReplicas int32  `json:"desired_replicas"`
	ReadyReplicas   int32  `json:"ready_replicas"`
	UpdatedReplicas int32  `json:"updated_replicas"`
	Available       bool   `json:"available"`
	// Issue is a human- and agent-actionable explanation of why an unavailable workload is
	// blocked — an image the cluster cannot pull (naming the registry and the
	// `burrow config registry login` fix), a pod no node can run (naming the taint or the
	// resource), a container crash-looping (naming the exit code); empty when the workload is
	// healthy. IssueReason is the machine-usable reason behind it, a member of the closed set
	// controlplane.IssueReasons() enumerates (e.g. "ImagePullBackOff", "Unschedulable",
	// "CrashLoopBackOff"), for branching without parsing the prose. See ADR-0006, ADR-0074 §2.
	Issue       string `json:"issue,omitempty"`
	IssueReason string `json:"issue_reason,omitempty"`
}