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
}

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 string `json:"name"`
	Type string `json:"type"`
	// 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"`
}

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

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

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 BuildRequest struct {
	Env         string    `json:"env,omitempty"`
	Source      SourceRef `json:"source"`
	TargetImage string    `json:"target_image"`
	Confirm     bool      `json:"confirm,omitempty"`
}

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"`
	Provider      ProviderCapability      `json:"provider"`
	DNS           DNSCapability           `json:"dns"`
}

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

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

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
}

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 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 a named
	// environment (ADR-0035 phase 2c): "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 {
	// 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 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 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"`
	CreatedAt time.Time `json:"created_at"`
}

type RemoveAddonOptions struct {
	// 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 {
	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 {
	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"`
}

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 RollbackResult struct {
	Release               Release `json:"release"`
	RolledBackToReleaseID string  `json:"rolled_back_to_release_id"`
	SupersededReleaseID   string  `json:"superseded_release_id"`
}

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

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