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

	// Endpoint is the S3-compatible API endpoint. Object storage is addressed by endpoint rather
	// than by vendor (ADR-0063 §1): the vendor is whoever answers it.
	Endpoint string `json:"endpoint,omitempty"`
	// Region is the region the S3 request is signed for.
	Region string `json:"region,omitempty"`
	// Bucket names an EXISTING bucket to use. Mutually exclusive with CreateBucket: Burrow either
	// creates the bucket it will own or is pointed at one, and never infers a bucket by name
	// (ADR-0063 §4).
	Bucket string `json:"bucket,omitempty"`
	// CreateBucket asks Burrow to create its own bucket, with a readable prefix and a random
	// component, and record the name it created (ADR-0063 §4). It trips the bucket.create guardrail.
	CreateBucket bool `json:"create_bucket,omitempty"`
	// RetentionDays is how long backups written to this destination must stay restorable — the
	// window the bucket's lifecycle rules are reconciled against (ADR-0063 §3). Zero declares no
	// window, under which any age-expiring lifecycle rule conflicts, because nothing prunes
	// Burrow's backups today.
	RetentionDays int `json:"retention_days,omitempty"`
	// AccessKeyID is one half of the object-storage credential VALUE. Like Token it travels only in
	// this request body, is written to burrow-credentials after the destination is verified, and is
	// never logged, stored in Postgres, or echoed back.
	AccessKeyID string `json:"access_key_id,omitempty"`
	// SecretAccessKey is the other half of the credential VALUE, held to exactly the same rules.
	SecretAccessKey string `json:"secret_access_key,omitempty"`
	// Confirm acknowledges the bucket.create guardrail so a bucket creation proceeds past it.
	Confirm bool `json:"confirm,omitempty"`
}

type AddonInfo struct {
	Name string    `json:"name"`
	Type AddonType `json:"type"`
	// Environment is the environment this instance serves — the canonical name, with the reserved
	// "default" for the implicit one (ADR-0067 §1). Each environment gets its own instance, so this
	// is what says which one this row is, and it is what an attach reads to decide which server to
	// provision a database on. It is recorded rather than parsed back out of Name: the name is
	// derived from the environment, never the other way round.
	Environment string `json:"environment,omitempty"`
	// 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 instance's backing workload is available. It is probed
	// from the cluster at list time and never persisted in the registry.
	Ready bool `json:"ready"`
	// Warning is a non-blocking note about the operation that produced this row. It is NOT persisted
	// — the registry holds what an add-on IS, and this is a fact about one install — so it is empty
	// on every row read back from the registry and only ever set on the value an install returns.
	//
	// It exists for one situation and is deliberately not a refusal: an object-storage destination is
	// registered, so the operator plainly wants backups, and the cluster has no pgBackRest plugin to
	// take them with (ADR-0066 §3). Refusing the install there would take the DATABASE away to
	// protect a backup, on a cluster where installing the plugin may not even be possible yet; and
	// installing silently would hand somebody an instance they believe is archiving. So the instance
	// is created without archiving and the omission is stated.
	Warning string `json:"warning,omitempty"`
}

type AddonRemoval struct {
	// Namespace is the namespace the add-on's resources — and any retained volume — live in.
	Namespace string `json:"namespace,omitempty"`
	// DataDeleted reports whether the add-on's data volume was destroyed. It is true only when the
	// caller explicitly asked for it AND the add-on had a volume to destroy.
	DataDeleted bool `json:"data_deleted"`
	// RetainedDataVolume names the PersistentVolumeClaim holding the add-on's data that was left in
	// place. Empty when the add-on has no volume, or when the caller asked for it to be deleted.
	RetainedDataVolume string `json:"retained_data_volume,omitempty"`
	// RetainedBackupVolume names the backup PersistentVolumeClaim that was left in place — the
	// Postgres add-on's dumps (ADR-0032). Backups deliberately outlive the database they came from,
	// so this survives even a data-deleting removal; it is empty when no backup volume exists.
	RetainedBackupVolume string `json:"retained_backup_volume,omitempty"`
}

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 AddonVolume struct {
	// Name is the claim name, which is also what `kubectl delete pvc` takes.
	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 claim was created for, read from the claim's own Burrow labels —
	// not inferred from its name.
	Addon AddonType `json:"addon"`
	// Environment is the environment the claim serves, read from the claim's own Burrow labels.
	// Empty for a claim created before add-ons were per-environment, which is the default
	// environment's by construction — it is left empty rather than filled in, because the label is
	// what the cluster actually says. With one instance and one backup claim per environment
	// (ADR-0067 §1) it is the difference between a listing that says which claim is which and one
	// that leaves the operator to read it off a name suffix.
	Environment string `json:"environment,omitempty"`
	// Role is what the claim holds: AddonVolumeData or AddonVolumeBackup.
	Role string `json:"role"`
	// Size is the claim's provisioned capacity where the cluster reports it, falling back to the
	// requested size (e.g. "10Gi"). Empty when neither is known. Size, not cost: cost needs the
	// provider's per-GiB price and can be wrong, and a wrong number about money is worse than an
	// honest one about bytes (ADR-0064 §Deliberately left open).
	Size string `json:"size,omitempty"`
	// ReinstallAdopts reports whether reinstalling the add-on picks this claim back up with its data
	// intact (ADR-0064 §1). True for a data claim — the reinstall lands on the same claim name — and
	// false for a backup claim, which is read by the backup/restore Jobs rather than adopted.
	ReinstallAdopts bool `json:"reinstall_adopts"`
	// CreatedAt is the claim's creation time as the cluster records it.
	CreatedAt time.Time `json:"created_at,omitempty"`
}

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

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

type AppDatabaseLister interface {
	// ListAppDatabases returns the app names with a Burrow-provisioned database on environment env's
	// instance, sorted. None yields an empty slice and no error. env is required for the same reason
	// it is on DatabaseProvisioner: the answer to "who is attached?" is only true of one instance,
	// and a removal names the apps it is about to affect (ADR-0067 §1).
	ListAppDatabases(ctx context.Context, env string) ([]string, error)
}

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

type ArchiveDestination struct {
	// Provider is the registry name of the object-storage provider. Not secret.
	Provider string
	// Config is the provider's non-secret configuration — endpoint, region, bucket, retention.
	Config ObjectStoreConfig
	// Credential is the pair pgBackRest signs its S3 requests with. Secret; see the type comment.
	Credential ObjectStoreCredential
	// RepoPath is the repository path within the bucket, from PgBackRestRepoPath — one per
	// environment, so one environment's repository is not addressable from another's stanza.
	RepoPath string
}

type AttachResult struct {
	App   string    `json:"app"`
	Addon AddonType `json:"addon"`
	// Environment is the environment whose instance the database was provisioned on (the reserved
	// "default" for the implicit one). It is reported because it is the thing that decides WHICH
	// database the app just got (ADR-0067 §1) — an attach result that named only the app would read
	// identically for two environments holding entirely separate data.
	Environment string `json:"environment,omitempty"`
	// 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 (the `burrow` CLI or `burrow-agent`) that
	// drove the operation, read from the X-Burrow-Client-Version handshake header (ADR-0039). It
	// records which client acted, next to the principal (who) and the server's own version — so
	// version skew is legible after the fact. Empty for a pre-handshake client that sent no version.
	// The json tag must match the client-side AuditEntry tag exactly (the struct crosses the API), or
	// the field would silently drop.
	ClientVersion string `json:"client_version,omitempty"`
}

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

type AuditOutcome string

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

type AutoDeployLevel string

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

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

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

type AutoscaleSpec struct {
	// MinReplicas is the floor the autoscaler will not scale below. Must be at least 1.
	MinReplicas int32 `json:"min_replicas"`
	// MaxReplicas is the ceiling the autoscaler will not scale above. Must be >= MinReplicas and is
	// itself bounded by the replica ceiling, an operational limit an operator sets (ADR-0068 §6).
	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"`
	// Kind says which mechanism produced this row: a per-app logical dump, or a physical base backup
	// of the whole instance (ADR-0066 §4). Empty on a row written before the two coexisted, which is
	// logical by construction — nothing else existed to write it.
	Kind BackupKind `json:"kind,omitempty"`
	// App is the application whose database was dumped. EMPTY on a physical row: that backup covers
	// every database on the instance, and naming one of them would make a listing claim a per-app
	// backup exists where none does.
	App string `json:"app"`
	// Environment is the environment whose instance the dump was taken from ("prod" for the default
	// one). Each environment has its own Postgres instance (ADR-0067 §1), so a dump
	// is only meaningful against the one it came from: restore requires the two to agree rather than
	// letting one environment's contents be written over another's.
	Environment string `json:"environment,omitempty"`
	// CreatedAt is when the backup was recorded, read from the injected clock.
	CreatedAt time.Time `json:"created_at"`
	// Path is the location of the dump WITHIN its claim (e.g. /backups/<app>/<id>.dump). It is a
	// path on a volume burrowd does not mount — never a credential. It does not identify a dump on
	// its own: the same path exists on every environment's claim, and Volume says which one.
	Path string `json:"path,omitempty"`
	// Volume is the PersistentVolumeClaim the dump was written to — this environment's backup claim
	// (BackupVolumeName). It is recorded rather than derived on read because the derivation changed:
	// backups written before backups were per-environment are all on the one claim that existed then
	// (PostgresBackupVolume), and a row that only said which environment it came from could not tell
	// the two eras apart. Recording it is what lets a restore refuse a dump that is not on the claim
	// this environment mounts, instead of running a Job that finds no such file.
	//
	// Empty only on a row written by an older burrowd against a newer schema; readers treat that as
	// the pre-migration claim, which is what it can only be.
	Volume string `json:"volume,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"`
	// Destination is where this backup's bytes ended up. It is written when the row is created, from
	// what was registered AT THAT MOMENT, so a listing says what each backup actually did rather
	// than what the current configuration would do — registering a destination today does not make
	// last month's in-cluster dumps durable, and the rows must not imply that it did.
	Destination BackupDestinationKind `json:"destination,omitempty"`
	// Provider is the name of the object-storage provider this backup was written to, empty for an
	// in-cluster one. It is a registry name, never a credential or an endpoint secret.
	Provider string `json:"provider,omitempty"`
	// ObjectKey is the key the dump occupies in the provider's bucket, empty for an in-cluster
	// backup. It is the address a restore reads from and the thing an operator checks at the vendor;
	// the bucket and endpoint it hangs off live on the provider row, not repeated here.
	ObjectKey string `json:"object_key,omitempty"`
	// FailureReason is why a failed backup failed — a member of the closed BackupFailureReason set,
	// or of ADR-0074 §2's IssueReason set when the Job never started. Empty on a pending or
	// completed row.
	FailureReason string `json:"failure_reason,omitempty"`
	// FailureDetail is one Burrow-authored line elaborating the reason, safe to print: an HTTP
	// status, an attempt count, a length mismatch. Never a vendor response body and never a
	// credential.
	FailureDetail string `json:"failure_detail,omitempty"`
}

type BackupDestination struct {
	// Provider is the registry name of the object-storage provider. It is not secret, and it is what
	// gets recorded on the Backup row.
	Provider string
	// Config is the provider's non-secret configuration — endpoint, region, bucket.
	Config ObjectStoreConfig
	// Credential is the pair the S3 request is signed with. Secret; see the type's own comment.
	Credential ObjectStoreCredential
	// Key is the object key this backup occupies, from BackupObjectKey.
	Key string
}

type BackupDestinationHealth struct {
	// Provider is the registry name of the object-storage provider.
	Provider string `json:"provider"`
	// Endpoint is the S3-compatible API endpoint that answers for it. Non-secret configuration.
	Endpoint string `json:"endpoint,omitempty"`
	// Bucket is the bucket Burrow writes backups to.
	Bucket string `json:"bucket,omitempty"`
	// Reachable reports whether the bucket answered for this credential just now.
	Reachable bool `json:"reachable"`
	// Detail says what was observed, in one Burrow-authored line. It never carries a vendor response
	// body and never carries a credential: an unreachable destination is described by what Burrow
	// could not do, not by quoting what the vendor said.
	Detail string `json:"detail,omitempty"`
}

type BackupDestinationKind string

type BackupHealth struct {
	// Addon is the add-on type the health is reported for. Only postgres has backups today.
	Addon AddonType `json:"addon"`
	// App is the app the report was narrowed to, empty when it spans every app.
	App string `json:"app,omitempty"`
	// Environment is the environment the report was narrowed to, empty when it spans every one.
	Environment string `json:"environment,omitempty"`
	// ObservedAt is when this report was assembled, from the injected clock. Every age below is
	// measured against it, so the numbers in one report are consistent with each other.
	ObservedAt time.Time `json:"observed_at"`
	// State says what kind of backup coverage exists.
	State BackupHealthState `json:"state"`
	// LastSuccess is the newest COMPLETED backup, wherever its bytes went. Nil when none exists.
	LastSuccess *BackupObservation `json:"last_success,omitempty"`
	// LastDurableSuccess is the newest backup that completed at an object-store destination — the
	// one ADR-0063 §7's age is about. Nil when no backup has left the cluster. It is the same row as
	// LastSuccess whenever the newest success was durable.
	LastDurableSuccess *BackupObservation `json:"last_durable_success,omitempty"`
	// LastFailure is the newest FAILED backup, with the closed reason it recorded. Nil when none
	// exists. It is reported alongside the successes rather than instead of them: a recent failure
	// after an older success is a different situation from never having succeeded, and an operator
	// deciding whether to act needs both.
	LastFailure *BackupObservation `json:"last_failure,omitempty"`
	// Pending counts rows still recorded as pending in this scope. A pending row is NEVER read as a
	// success — the ages above count completed rows only — so a burrowd that died mid-Job leaves the
	// age growing rather than resetting it. The count is surfaced because a growing pile of pending
	// rows is itself a symptom.
	Pending int `json:"pending,omitempty"`
	// Destinations are the registered object-storage destinations and whether each answered just
	// now, sorted by provider name. Empty when none is registered, which is not an error: an install
	// with no object storage still takes in-cluster dumps, and the state says so.
	Destinations []BackupDestinationHealth `json:"destinations,omitempty"`
	// Summary is one line a human can read or an agent can relay, stating the fact rather than a
	// verdict against a threshold Burrow has not been given.
	Summary string `json:"summary"`
}

type BackupHealthState string

type BackupJobOutcome struct {
	SizeBytes int64
	Reason    string
	Detail    string
}

type BackupKind string

type BackupObservation struct {
	// ID is the backup identifier.
	ID string `json:"id"`
	// Kind is which mechanism took it — a per-app logical dump or a physical base backup of the whole
	// instance (ADR-0066 §4). It is reported because the two are not interchangeable: a durable
	// physical backup means every database on that instance is recoverable, and a durable logical one
	// means exactly one app's is.
	Kind BackupKind `json:"kind,omitempty"`
	// App is the application whose database was dumped. Empty on a physical backup, which covers
	// every database on the instance and belongs to no one app.
	App string `json:"app"`
	// Environment is the environment whose instance it was taken from.
	Environment string `json:"environment,omitempty"`
	// At is when the backup was recorded.
	At time.Time `json:"at"`
	// AgeSeconds is how long ago that was, measured against the injected clock at the moment of the
	// call. It is reported in seconds rather than as a rendered duration so a caller — an agent, an
	// alert rule — compares a number instead of parsing prose.
	AgeSeconds int64 `json:"age_seconds"`
	// Status is the row's lifecycle state.
	Status BackupStatus `json:"status"`
	// Destination is where the bytes ended up: the cluster volume, or the object store.
	Destination BackupDestinationKind `json:"destination,omitempty"`
	// Provider names the object-storage provider, for an object-store destination. A registry name,
	// never a credential or an endpoint secret.
	Provider string `json:"provider,omitempty"`
	// SizeBytes is the dump's size, or 0 when unknown.
	SizeBytes int64 `json:"size_bytes,omitempty"`
	// Reason is why a failed backup failed — a member of the closed BackupFailureReason set, or of
	// ADR-0074 §2's IssueReason set when the Job never started. Empty on a completed row.
	Reason string `json:"reason,omitempty"`
	// Detail is one Burrow-authored line elaborating the reason. Never a vendor response body and
	// never a credential.
	Detail string `json:"detail,omitempty"`
}

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

type BackupStatus string

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

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

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

type Capability string

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

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

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

type ChecksReport struct {
	App         string `json:"app"`
	Environment string `json:"environment,omitempty"`
	// Enabled reports whether the default deploy-time check runs. True unless it was turned off for
	// this app and environment.
	Enabled bool `json:"enabled"`
	// Dependencies are what Burrow derived from what it provisioned. Empty means there is nothing to
	// check, and then no check pod runs at all — an app with no database and no exposure costs
	// nothing.
	Dependencies []Dependency `json:"dependencies"`
	// Note explains an empty or partial list in one line, so "nothing to check" and "could not tell"
	// do not read the same.
	Note string `json:"note,omitempty"`
}

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

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 is the ingress-controller situation: whether a controller is actually running, and
	// which IngressClass(es) exist.
	Ingress IngressCapability `json:"ingress"`
	// Storage is the default-StorageClass situation: whether a default exists and its name.
	Storage StorageCapability `json:"storage"`
	// LoadBalancer is whether Service type=LoadBalancer is likely supported, detected from whatever
	// services LoadBalancers — a cloud provider, k3s's servicelb, or MetalLB.
	LoadBalancer LoadBalancerCapability `json:"load_balancer"`
	// CertManager is whether cert-manager is installed, detected via its API group (its CRDs).
	CertManager CertManagerCapability `json:"cert_manager"`
	// MetricsServer is whether metrics-server is serving the Kubernetes Metrics API (metrics.k8s.io),
	// detected via API-group discovery. It powers `kubectl top`, HPA CPU/memory autoscaling, and the
	// utilization layer of capacity reporting; Burrow auto-ensures it as a baseline (ADR-0054 §1).
	MetricsServer MetricsServerCapability `json:"metrics_server"`
	// CloudNativePG is the CloudNativePG operator's situation: whether its CRDs are served, whether
	// a controller is actually running, and which release it is (ADR-0066 §1). It is the cluster
	// prerequisite the Postgres add-on runs on, installed by an operator-CLI setup
	// step because CRDs need cluster-admin.
	CloudNativePG CloudNativePGCapability `json:"cloudnative_pg"`
	// PgBackRest is the CloudNativePG pgBackRest plugin's situation (ADR-0066 §3): the component that
	// archives a Postgres instance's write-ahead log and takes its base backups. It is reported
	// separately from CloudNativePG because the two fail apart — an operator with no plugin runs
	// databases that cannot be backed up off-cluster — and installed by the same operator-CLI step,
	// for the same reason: its CRDs need cluster-admin.
	PgBackRest PgBackRestCapability `json:"pgbackrest"`
	// 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 ClusterConfigFunc func(ctx context.Context) OperationalConfig

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

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

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

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

type Coverage struct {
	// Since and Until bound the period this describes.
	Since time.Time `json:"since"`
	Until time.Time `json:"until"`
	// Windows are the observer runs overlapping that period, oldest first.
	Windows []ObservationWindow `json:"windows"`
	// Gaps are the stretches inside it that no window covers, oldest first. Non-empty means the
	// ledger is INCOMPLETE for this period and an empty failure list says nothing about it.
	Gaps []CoverageGap `json:"gaps"`
	// DegradedSweeps is how many sweeps across those windows could not read every object they set
	// out to. It is partial coverage rather than none: rows for the objects a degraded sweep could
	// not read may be missing or stale, and their absence is not evidence of health either.
	DegradedSweeps int64 `json:"degraded_sweeps,omitempty"`
	// Detail is the most recent degradation note across those windows, empty when none degraded.
	Detail string `json:"detail,omitempty"`
}

type CoverageGap struct {
	// From is when coverage stopped.
	From time.Time `json:"from"`
	// To is when it resumed — or the moment the answer was assembled, for a gap that is still open.
	To time.Time `json:"to"`
}

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 the agent control channel — and is written straight to the Secret: it is
	// NEVER logged, never stored in Postgres, and never returned in a response. Any error names
	// the key only, never the value.
	SetToken(ctx context.Context, key, value string) error
}

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

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

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

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

type DNSRecordType string

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

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

	// AppHook returns the command app runs at phase in env — the lifecycle hook configured beside the
	// app's config (ADR-0072 §1). A phase with no hook yields a nil command and no error: unset means
	// no hook and today's behaviour exactly, so absence is the ordinary answer and not ErrNotFound.
	// The command is an argv, stored so an argument boundary survives rather than depending on a
	// shell to re-split it. env is the canonical environment name ("prod" for the default one).
	AppHook(ctx context.Context, app, env string, phase HookPhase) ([]string, error)
	// AppHooks returns every hook configured for app in env. None yields an empty slice and no error.
	AppHooks(ctx context.Context, app, env string) ([]Hook, error)
	// SetAppHook upserts the command app runs at phase in env, replacing any command already set
	// there — the write behind `burrow app hook set`. The command arrives validated (non-empty argv).
	SetAppHook(ctx context.Context, app, env string, phase HookPhase, command []string) error
	// UnsetAppHook removes app's hook at phase in env. Removing a hook that is not set is a no-op,
	// not an error: afterwards that phase runs nothing, which is what the caller asked for.
	UnsetAppHook(ctx context.Context, app, env string, phase HookPhase) error
	// DeleteAppHooks removes every hook for app across every environment — the durable side of an app
	// teardown, beside DeleteReleases. Deleting the hooks of an app that has none is a no-op.
	DeleteAppHooks(ctx context.Context, app 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

	// OperationalConfig returns the operator-set operational configuration: every stored limit
	// value, keyed by the code it was set under (ADR-0068 §1). A limit with no stored value
	// resolves to its built-in default, so a store with nothing set yields the defaults.
	OperationalConfig(ctx context.Context) (OperationalConfig, error)
	// SetLimit persists the value of one operational limit — the write behind `cluster config
	// set`. code is the key the value is stored under, which is the bare limit code for a cluster
	// value and `<env>.<code>` for an environment one; the engine composes it, exactly as it does
	// for SetGuardrail. The value arrives already validated and in its canonical text form.
	SetLimit(ctx context.Context, code LimitCode, value string) error

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

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

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

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

	// RecordBackup persists a new backup row (ADR-0032). burrowd records it pending before
	// starting the backup Job. The row names the app, the on-PVC path, the destination it is
	// being written to, 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 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
	// FailBackup marks a recorded backup failed AND records why: reason is a member of the closed
	// BackupFailureReason set, or of ADR-0074 §2's IssueReason set when the Job never started, and
	// detail is one Burrow-authored line. It is a separate method from SetBackupStatus because a
	// failure without a reason is the thing ADR-0063 §7 exists to stop — "it did not work" sends the
	// reader to the logs, which is where the destination's silence was hiding in the first place.
	//
	// Neither argument may carry a secret value or a vendor response body. Failing an unknown backup
	// id returns ErrNotFound.
	FailBackup(ctx context.Context, id, reason, detail string) error
	// ListBackups returns recorded backups, newest first. An empty app lists every app's backups and
	// an empty env every environment's; a non-empty value restricts to that app or that environment.
	// A listing is a read, not a target, so an unfiltered call spans environments deliberately —
	// unlike backup and restore, which act on exactly one instance and take the environment as a
	// required argument (ADR-0067 §1). No matches yields an empty slice and no error.
	ListBackups(ctx context.Context, app, env string) ([]Backup, error)
	// GetBackup returns the backup with the given id, or ErrNotFound.
	GetBackup(ctx context.Context, id string) (Backup, error)
	// PendingBackups returns the recorded backups still in `pending` that were created before
	// `before`, oldest first — the candidates for ADR-0074 §6's "a backup row still pending whose Job
	// no longer exists". The cutoff is the caller's, not the store's: it is what separates a backup
	// that is simply still running from one nothing is going to finish, and the observer sets it from
	// the injected clock. None yields an empty slice and no error.
	PendingBackups(ctx context.Context, before time.Time) ([]Backup, error)

	// ManagedApps returns the distinct (app, environment) pairs the registry says Burrow OWNS A
	// WORKLOAD FOR: an app whose release history shows a rollout that actually reached the cluster.
	// It is the intent side of ADR-0074 §6's first comparison, so it is deliberately not "every app
	// with a release row" — an app whose only deploy failed before a workload was ever applied has no
	// Deployment to be missing, and reporting one would be a false positive on the day someone is
	// already debugging a failed deploy. None yields an empty slice and no error.
	ManagedApps(ctx context.Context) ([]AppEnvRef, error)

	// RecordExposure upserts the intent behind a successful expose, keyed by (app, environment)
	// (ADR-0074 §6). It records what was ASKED FOR — the host, the port, whether TLS was requested —
	// and never whether it currently works, which stays a live read.
	RecordExposure(ctx context.Context, ex Exposure) error
	// DeleteExposure removes the recorded exposure for app in env. Removing one that is not recorded
	// is a no-op, not an error: an unexpose must succeed whether or not the intent row survived.
	DeleteExposure(ctx context.Context, app, env string) error
	// Exposures returns every recorded exposure, ordered by app then environment. None yields an
	// empty slice and no error.
	Exposures(ctx context.Context) ([]Exposure, error)
	// Exposure returns the recorded exposure for app in env, or ErrNotFound when the app is not
	// published there. It is the read behind ADR-0076 §3's conservative default: the container port
	// an exposure routes to is the ONLY port Burrow knows for an app, so it is what a readiness
	// probe can honestly check. Not being published is the ordinary case, not a failure — the caller
	// treats ErrNotFound as "no port known" and authors no probe.
	Exposure(ctx context.Context, app, env string) (Exposure, error)

	// HealthEndpoint returns the health endpoint declared for app in env (ADR-0076 §5), or the zero
	// value when none was declared — which is where every app starts, since the endpoint is opt-in.
	// A missing row is not an error.
	HealthEndpoint(ctx context.Context, app, env string) (HealthEndpoint, error)
	// SetHealthEndpoint upserts the declared health endpoint for app in env — the write behind
	// `burrow app health set`. The path and port arrive already validated.
	SetHealthEndpoint(ctx context.Context, ep HealthEndpoint) error
	// UnsetHealthEndpoint removes the declared endpoint for app in env, returning the app to
	// ADR-0076 §3's default. Unsetting one that was never declared is a no-op, not an error.
	UnsetHealthEndpoint(ctx context.Context, app, env string) error
	// DeleteHealthEndpoints removes every declared endpoint for app across all environments — the
	// durable side of an app teardown, alongside DeleteReleases. Deleting for an app that declared
	// none is a no-op.
	DeleteHealthEndpoints(ctx context.Context, app string) error

	// DependencyChecksEnabled reports whether the deploy-time dependency check runs for app in env
	// (ADR-0076 §4). It answers TRUE when nothing was recorded: the check is a Burrow-supplied
	// default, so a row exists only where someone made a decision about it, and a missing row is the
	// default rather than an error.
	DependencyChecksEnabled(ctx context.Context, app, env string) (bool, error)
	// SetDependencyChecks records whether the deploy-time dependency check runs for app in env — the
	// write behind `burrow app checks enable|disable`, and the "disableable rather than silent" half
	// of adding a Burrow-supplied default to a path ADR-0072 described as user-configured.
	SetDependencyChecks(ctx context.Context, app, env string, enabled bool, at time.Time) error
	// DeleteDependencyCheckSettings removes app's recorded setting across all environments — the
	// durable side of an app teardown, alongside DeleteHealthEndpoints. Deleting for an app that
	// never recorded one is a no-op.
	DeleteDependencyCheckSettings(ctx context.Context, app string) error

	// RecordFailure opens or extends the ledger row for one observed failure (ADR-0074 §4). The row
	// is keyed by (object, reason) so concurrent reasons on one object coexist as separate rows with
	// independent lifetimes (§5). A first sighting writes first_seen, last_seen and a count of one; a
	// later sighting of the same still-active failure advances last_seen and increments the count,
	// leaving first_seen — the answer to "when did it start" — alone. A sighting of a failure that
	// had been RESOLVED opens a new row rather than reviving the old one, so a thing that broke,
	// recovered and broke again reads as two episodes instead of one long outage.
	//
	// It is the ledger's only write path for failures, and it is not the audit log: they are separate
	// tables deliberately (§7).
	RecordFailure(ctx context.Context, obs FailureObservation) error
	// ResolveFailures closes, at time at, every active ledger row that is not in keep and whose
	// object is not in skip — the "did it recover on its own" half of §4, decided by absence.
	//
	// The two lists are what keep that decision honest. keep is every failure the sweep observed
	// still happening. skip is every object the sweep could NOT read: those rows are left exactly as
	// they are, because a failure Burrow could not check is not a failure that recovered. A row for
	// an object that is in neither — one the sweep read and found healthy, or one that has left the
	// registry entirely — is resolved.
	ResolveFailures(ctx context.Context, at time.Time, keep []FailureKey, skip []ObjectRef) error
	// Failures returns ledger rows matching filter, oldest first. Oldest-first is the order ADR-0074
	// §5 asks for: when one cause has produced many rows, the earliest first_seen in the cascade is
	// the likeliest thing to actually fix. No matches yields an empty slice and no error.
	Failures(ctx context.Context, filter FailureFilter) ([]Failure, error)

	// StartObservationWindow opens a new observation window beginning at `at` and returns its id.
	// One is opened per RUN of the observer, never reused across a restart: a gap between windows is
	// time nobody was watching, and it is the only thing that stops an empty ledger from reading as
	// "nothing broke" (ADR-0074's consequences).
	StartObservationWindow(ctx context.Context, at time.Time) (int64, error)
	// ExtendObservationWindow advances window id's coverage to `until` and counts one more sweep. A
	// non-empty degraded note counts the sweep as incomplete and is stored as the window's most
	// recent degradation, so a stretch during which some objects could not be read is visible as
	// partial coverage rather than as clean coverage. Extending a window that no longer exists
	// returns ErrNotFound, which tells the caller to open a fresh one rather than stop recording.
	ExtendObservationWindow(ctx context.Context, id int64, until time.Time, degraded string) error
	// ObservationWindows returns the windows whose coverage ends at or after since, oldest first,
	// capped by limit (a store default when unset). The gaps BETWEEN the returned windows are the
	// answer the caller is really after. None yields an empty slice and no error.
	ObservationWindows(ctx context.Context, since time.Time, limit int) ([]ObservationWindow, error)

	// PruneLedger enforces ADR-0074 §4's retention bound: it removes failure rows RESOLVED before
	// `before` and observation windows whose coverage ended before it. An ACTIVE failure is never
	// removed, however old — a thing that is still broken is not history. Unbounded growth here is
	// not untidiness; it is an outage in the control plane's own database, which is why the bound is
	// a requirement rather than a setting.
	PruneLedger(ctx context.Context, before time.Time) (LedgerPruneResult, 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 default environment `prod` IS stored here, written once by Engine.EnsureDefaultEnvironment
	// at burrowd startup (ADR-0067 §2) rather than synthesized on every read.
	CreateEnvironment(ctx context.Context, name, namespace string) error
	// ListEnvironments returns the registered environments ordered by name, INCLUDING the default
	// environment `prod`; the engine hoists that one first and marks it. None yields an empty slice
	// and no error.
	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)
	// DeleteEnvironment removes the registered environment with the given name, or ErrNotFound when
	// no such environment is registered. The default environment `prod` is stored here but is never
	// removed: the engine rejects it before this call (ADR-0067 §2).
	DeleteEnvironment(ctx context.Context, name string) error
}

type DatabaseProvisioner interface {
	// EnsureAppDatabase idempotently provisions an isolated database and login role for app on
	// environment env's own 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. env and app are both
	// validated against a strict identifier pattern and every SQL identifier is quoted BEFORE any SQL
	// runs, so neither can carry SQL; an empty env is ErrInvalid, never the default environment. 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, env string) (databaseURL string, err error)
	// DropAppDatabase removes app's database and login role from environment env's instance — the
	// destructive side of detach. Dropping a database/role that is already absent is a no-op, not an
	// error. env and app are validated before any SQL, exactly as in EnsureAppDatabase, so a detach
	// can no more reach another environment's server than an attach can.
	DropAppDatabase(ctx context.Context, app, env string) error
}

type Dependency struct {
	// Kind is the class of dependency.
	Kind DependencyKind `json:"kind"`
	// Provisioned is the one-line, non-secret statement of WHAT Burrow gave the app, so a reader can
	// see that the check was derived rather than configured.
	Provisioned string `json:"provisioned"`
	// EnvKey is the environment variable the app reads the dependency's credential from, for a
	// dependency reached with one. Never a value.
	EnvKey string `json:"env_key,omitempty"`
	// Endpoint is the in-cluster address the check dials, for a dependency reached without a
	// credential. Never a value.
	Endpoint string `json:"endpoint,omitempty"`
}

type DependencyKind string

type DependencyOutcome string

type DependencyResult struct {
	// Kind is the dependency this result is about.
	Kind DependencyKind `json:"kind"`
	// Outcome is passed, failed, or skipped.
	Outcome DependencyOutcome `json:"outcome"`
	// Reason is a member of DependencyReasons, empty on a passed check.
	Reason string `json:"reason,omitempty"`
	// Detail is one bounded, Burrow-authored line: what was tried and what came back. It never
	// carries a credential, a driver message, or any part of a connection string beyond the host and
	// port that were dialled.
	Detail string `json:"detail,omitempty"`
	// Status is the HTTP status code an exposure check received. Zero when none was.
	Status int `json:"status,omitempty"`
}

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

type DeployResult struct {
	// Release is the new release that is now running.
	Release Release `json:"release"`
	// SupersededReleaseID is the release this deploy replaced, or "" if it was the
	// first deploy of the app. It is the handle a rollback would return to.
	SupersededReleaseID string `json:"superseded_release_id,omitempty"`
	// Hints are non-blocking notes about the deploy the agent can reason over (ADR-0052 §8): today,
	// a nudge toward semver when the deployed tag cannot be classified for auto-update. They never
	// gate or fail the deploy — any reference deploys (ADR-0007). Empty when there is nothing to note.
	Hints []string `json:"hints,omitempty"`
	// Dependencies is what the deploy-time dependency check found (ADR-0076 §4): for each thing
	// Burrow provisioned for this app — a database it attached, a port it published — whether the app
	// could actually reach it from inside its own container after the deploy.
	//
	// IT IS A REPORT AND NEVER A VERDICT ON THE DEPLOY. A failed entry here sits on a DeployResult
	// that succeeded, because it does: the release is deployed, the rollout happened, and Burrow does
	// not roll back by itself (ADR-0072 §6). Empty when Burrow provisioned nothing it can check, or
	// when the check is turned off for this app.
	Dependencies []DependencyResult `json:"dependencies,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
	// ObjectStore builds an ObjectStore for an S3-compatible endpoint and credential pair, so a
	// backup can be written outside the cluster it came from (ADR-0063). Optional — nil is allowed,
	// and registering an object-storage provider errors cleanly (ErrNotImplemented) when it is not
	// wired, exactly as the build path does without a Builder.
	ObjectStore ObjectStoreFactory
	// Logs maps a backend id (e.g. "victorialogs", "loki") to the querier serving an installed
	// or connected logs add-on. Optional — an empty or nil map is allowed, and the engine errors
	// cleanly on a logs query when no querier is wired for the add-on's backend (ADR-0026).
	Logs map[string]LogsQuerier
	// Metrics maps a backend id (e.g. "prometheus", "victoriametrics") to the querier serving an
	// installed or connected metrics add-on. Optional — an empty or nil map is allowed, and the
	// engine errors cleanly on a metrics query when no querier is wired for the add-on's backend
	// (ADR-0026).
	Metrics map[string]MetricsQuerier
	// DatabaseProvisioner provisions a per-app database and role on the installed Postgres add-on
	// (ADR-0031). Optional — nil is allowed, and the engine errors cleanly (ErrNotImplemented) on a
	// Postgres attach when it is not wired.
	DatabaseProvisioner DatabaseProvisioner
	// ClusterProber detects the cluster's read-only capabilities (ADR-0034). Optional — nil is
	// allowed, and the engine errors cleanly (ErrNotImplemented) on a capabilities read when it is
	// not wired.
	ClusterProber ClusterProber
	// CapacityProber reads the cluster's scheduling-capacity facts (node allocatable, pod requests)
	// for the headroom surface (issue #275). Optional — nil is allowed, and the engine errors cleanly
	// (ErrNotImplemented) on a capacity read when it is not wired.
	CapacityProber CapacityProber
	// RegistryClient lists an image repository's tags for the auto-deploy read/watch (ADR-0052).
	// Optional — nil is allowed, and the auto-deploy show degrades to reporting the level alone
	// when it is not wired. It is OUTBOUND-only and never used on the core deploy path (ADR-0040).
	RegistryClient RegistryClient
	// Builder builds an image from a git source reference inside the cluster for the optional
	// in-cluster build path (ADR-0053). Optional — nil is allowed, and the engine errors cleanly
	// (ErrNotImplemented) on a build when it is not wired.
	Builder Builder
	// BuildRegistry is the in-cluster registry reference host:port the in-cluster build defaults its
	// push target to when the caller supplies none — the zero-config default push target for a build
	// (ADR-0053 §5). Optional — an empty value means a build with no explicit target errors, and a
	// caller-supplied target always overrides it (external registries stay fully supported). burrowd
	// sets it from BURROW_BUILD_REGISTRY, which `burrow cluster registry install` wires to the
	// in-cluster registry it deploys.
	BuildRegistry string
	// BuildPublicRegistry is the PUBLIC registry host the in-cluster build's resulting deploy
	// references so the node pulls through the ingress over TLS, distinct from BuildRegistry (the
	// internal push endpoint) — ADR-0054 §5. Optional — an empty value falls back to referencing the
	// internal push endpoint. burrowd sets it from BURROW_BUILD_PUBLIC_REGISTRY, which
	// `burrow cluster registry install --host` wires to the registry's public ingress hostname.
	BuildPublicRegistry string
	// AppNamespace is the namespace burrowd deploys apps into (BURROW_NAMESPACE) — the namespace the
	// default environment `prod` maps to (ADR-0067 §3). Optional — an empty value defaults to the
	// Kubernetes namespace "default", matching the kube Adapter. That is a NAMESPACE name and has
	// nothing to do with the retired environment name of the same spelling.
	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. "prod", "staging").
	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 default environment — `prod`, created at install and
	// mapped to the app namespace burrowd runs against (ADR-0067 §2–§3). Environments added later
	// are never default.
	Default bool `json:"default"`
	// CreatedAt is when the environment was registered, read from the injected clock. It is the
	// zero time when the default environment is synthesized because its registry row is missing.
	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
	// "prod" targets the default environment, a name added later 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 Exposure struct {
	// App is the exposed application.
	App string `json:"app"`
	// Environment is the canonical environment the exposure was made in ("prod" for the default
	// one), because the same app in two environments is exposed at two different hosts.
	Environment string `json:"environment,omitempty"`
	// Host is the external hostname routed to the app.
	Host string `json:"host"`
	// Port is the app's container port the Service forwards to.
	Port int32 `json:"port"`
	// TLS records whether a certificate was requested for Host, which is what makes "the Ingress is
	// there but the certificate never issued" a failure Burrow can name rather than guess at.
	TLS bool `json:"tls,omitempty"`
	// CreatedAt is when the exposure was recorded, read from the injected clock.
	CreatedAt time.Time `json:"created_at,omitempty"`
}

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 Failure struct {
	// ID is the store-assigned row identity (0 before it is persisted).
	ID int64 `json:"id,omitempty"`
	// Object is what failed.
	Object ObjectRef `json:"object"`
	// Reason is the member of the closed ledger vocabulary this row is about.
	Reason string `json:"reason"`
	// Detail is the most recent bounded, Burrow-authored line for this failure. It is overwritten
	// on each sighting rather than accumulated: the row is a transition, not a log.
	Detail string `json:"detail,omitempty"`
	// FirstSeen is when this failure began — the answer to "when did it start", and the reason the
	// ledger exists at all.
	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 the failure stopped being observed, nil while it is still active — the
	// answer to "did it recover on its own". It is a pointer so an active row serialises without a
	// zero timestamp that reads as a date in the year 1.
	ResolvedAt *time.Time `json:"resolved_at,omitempty"`
	// Occurrences is how many OBSERVATIONS found this failure present, counting the one that opened
	// the row. It is deliberately a count of sightings rather than of restarts: a restart count
	// exists for a crash loop and for nothing else in the vocabulary, and a field that meant
	// different things for different reasons could not be compared across rows. Read with the
	// observation cadence, it is what says whether a failure is a blip or a standing condition.
	Occurrences int64 `json:"occurrences"`
}

type FailureFilter struct {
	// Kind restricts to one class of object; empty matches any.
	Kind FailureKind
	// Name restricts to one object name; empty matches any.
	Name string
	// Environment restricts to one environment; empty matches any.
	Environment string
	// Reason restricts to one reason; empty matches any. It is the filter that answers "what else
	// hit this in the same window", which is §5's grouping seen from the query side.
	Reason string
	// Since restricts to rows last seen at or after this instant; the zero value applies no bound.
	Since time.Time
	// IncludeResolved widens the result from active failures to the history as well.
	IncludeResolved bool
	// Limit caps the number of rows returned. Zero or negative applies the store's default cap.
	Limit int
}

type FailureKey struct {
	Object ObjectRef
	Reason string
}

type FailureKind string

type FailureObservation struct {
	// Object is what failed.
	Object ObjectRef
	// Reason is a member of the closed ledger vocabulary (LedgerReasons).
	Reason string
	// Detail is one bounded, Burrow-authored line — already through LedgerDetail.
	Detail string
	// At is the observation time, from the injected clock (ADR-0010).
	At time.Time
}

type FailureQuery struct {
	// Kind restricts to one class of managed object; empty matches any.
	Kind FailureKind
	// Name restricts to one object name; empty matches any.
	Name string
	// Environment restricts to one environment; empty matches any.
	Environment string
	// Reason restricts to one reason from the closed ledger vocabulary; empty matches any. It is
	// ADR-0074 §5's grouping asked from the query side: "what else hit this in the same window".
	Reason string
	// Since bounds the answer to failures last seen within this much of now, and widens it from the
	// active failures to the history — a window over the past is not a question about the present.
	// Zero leaves the query on the active rows and reads coverage over DefaultFailureLookback.
	Since time.Duration
	// IncludeResolved widens the answer to failures that have since recovered, with no time bound
	// beyond the ledger's retention.
	IncludeResolved bool
	// Limit caps the rows returned. Zero or negative applies the store's default cap.
	Limit int
}

type FailureReport struct {
	// Failures are the ledger rows, oldest first — the order ADR-0074 §5 asks for, because the
	// earliest first_seen in a cascade is the likeliest thing to actually fix. They are rows and not
	// groups on purpose: see the file comment.
	Failures []Failure `json:"failures"`
	// Coverage is what was watching over the period described. It is never omitted.
	Coverage Coverage `json:"coverage"`
}

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 HealthEndpoint struct {
	// App is the application the endpoint belongs to.
	App string `json:"app"`
	// Environment is the canonical environment name ("prod" for the default one).
	Environment string `json:"environment,omitempty"`
	// Path is the HTTP path the app serves its readiness answer on, e.g. "/healthz". Empty means no
	// endpoint was declared and §3's default applies.
	Path string `json:"path,omitempty"`
	// Port is the container port the path is served on. Zero means "the port the app is published
	// on", resolved at apply time from the recorded exposure — so an app that moves its exposure
	// does not need its health endpoint re-declared.
	Port int32 `json:"port,omitempty"`
	// UpdatedAt is when the endpoint was recorded, read from the injected clock.
	UpdatedAt time.Time `json:"updated_at,omitempty"`
}

type HealthReport 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 is the port the probe checks; zero when Probe is "none".
	ProbePort int32 `json:"probe_port,omitempty"`
	// ProbePath is the path an HTTP probe requests; empty for a TCP or absent probe.
	ProbePath string `json:"probe_path,omitempty"`
	// Source is where the probe came from: "endpoint" (declared), "exposure" (§3's TCP default off
	// the published port), or "none".
	Source string `json:"source"`
	// Liveness is always false and is reported anyway, because "does Burrow restart my container
	// when this fails?" is the first question a reader has and the answer is load-bearing (§1).
	Liveness bool `json:"liveness"`
	// Hint is the §5 guidance, present whenever no endpoint has been declared. It is what turns this
	// from a status read into the place an agent learns that adding one is worth doing and what a
	// good one checks.
	Hint string `json:"hint,omitempty"`
	// AppliesOn says when the reported probe reaches the running pods, when it is not already there.
	AppliesOn string `json:"applies_on,omitempty"`
}

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

type HookError struct {
	App     string
	Env     string
	Phase   HookPhase
	Command []string
	// Image is the image the hook ran from: the one being deployed for a pre-deploy hook, the one
	// being left for a pre-rollback hook (ADR-0072 §2, §8).
	Image string
	// ExitCode is the command's exit code when it ran and failed. Zero when the command never
	// produced one (Cause is set instead).
	ExitCode int
	// Output is the command's captured combined output, bounded by hookOutputLimit.
	Output string
	// TimedOut reports the hook did not finish inside the run window and Burrow stopped waiting.
	TimedOut bool
	// Cause is the launch, poll, or timeout failure when the hook never ran to an exit code. Nil
	// when the command ran and exited non-zero, which is the ordinary failure.
	Cause error
}

type HookPhase string

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 InstallAddonOptions struct {
	// Confirm satisfies the addon.install guardrail's confirmation hold (ADR-0020).
	Confirm bool
	// ArchiveDestination names which registered object-storage provider a Postgres instance archives
	// its write-ahead log and takes its base backups to (ADR-0066 §3). It is only needed when several
	// are registered — ADR-0063 §6 allows that on purpose — and Burrow refuses to guess rather than
	// tying an instance to a repository nobody is watching, because an instance keeps the repository
	// it was created against. Empty with exactly one registered provider means that one; empty with
	// none means the instance does not archive at all, which is not an error.
	ArchiveDestination string
}

type IssueEvidence struct {
	// Reason is the member of the closed set this evidence is for. Empty means no issue.
	Reason string
	// Container is the container the evidence came from, when the reason is a container's.
	Container string
	// Image is the container image, for an image-pull reason.
	Image string
	// Detail is the reason-specific evidence: the scheduler's message for a scheduling or volume
	// failure, the kubelet's message for a config error, the memory limit for an OOM kill.
	Detail string
	// ExitCode is the code the previous run of a crash-looping container exited with. A crash loop
	// with code 0 is a real and confusing case (a container that keeps exiting cleanly under
	// restartPolicy Always), so it is reported as-is rather than treated as "unknown".
	ExitCode int32
	// LogTail is a bounded tail of a crash-looping container's PREVIOUS log — application output,
	// captured verbatim. Message labels it as such; Burrow does not inspect or sanitise it.
	LogTail string
}

type JobBlockedError struct {
	// Job is the Job's name, so a reader can go straight to it (a blocked Job is deliberately left
	// undeleted for diagnosis).
	Job string
	// Reason is the member of the closed set. ReasonDeadlineExceeded is the backstop: the waiter ran
	// out of time without any pod reporting a blocking condition.
	Reason string
	// Issue is the rendered, actionable explanation — the same prose the status surface shows.
	Issue string
}

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)

	// AwaitRollout blocks until app's newest revision has SETTLED — the completion test
	// `kubectl rollout status` uses, not merely that the write was accepted — or until it can say why
	// it did not, bounded by timeout (ADR-0072 §4-§5). It is what makes a `post-deploy` hook possible:
	// a hook cannot be told how a deploy went until something waits for it to go.
	//
	// EVERY OBSERVABLE CONDITION IS AN OUTCOME, NOT AN ERROR, exactly as a non-zero exit is a result
	// rather than an error on RunJob (ADR-0048 §3). A crash loop, an unschedulable pod, a missing
	// workload and an expired deadline all come back as a RolloutOutcome with a reason from the closed
	// vocabulary, because the caller's next move is the same in every case: tell the hook. The error
	// return is reserved for a call that could not be made at all (an invalid app identifier).
	//
	// It returns as soon as it has a verdict rather than sleeping out its bound: a pod reporting a
	// blocking condition ends the wait immediately, which is the difference between a hook told
	// "CrashLoopBackOff" in fifteen seconds and one told "timed out" in five minutes (issue #352).
	// An expired bound is the BACKSTOP, and its outcome carries what was observed rather than the
	// elapsed time (ADR-0072 §5).
	//
	// It mutates nothing. A rollout it reports as failed is left exactly as it is, for the hook to
	// decide about — Burrow does not roll back by itself (ADR-0072 §6).
	AwaitRollout(ctx context.Context, app string, timeout time.Duration) (RolloutOutcome, error)

	// DeployAddon installs a building-block backing service per spec for environment env — 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.
	//
	// env is required and names which environment's instance this is (ADR-0067 §1): the resources are
	// named by AddonInstanceName, so the default environment lands on exactly the names an existing
	// install already has and any other environment gets its own instance beside it — its own pod,
	// its own volume, and for Postgres its own superuser credential.
	//
	// The add-on's TYPE decides what is written. Postgres is a CloudNativePG `Cluster` — one custom
	// resource, from which the operator composes the workload, the volume and the services (ADR-0066
	// §1) — and every other add-on is a Deployment Burrow authors. Which one it is follows from the
	// spec; there is no mechanism to select.
	//
	// archive, when non-nil, is the pgBackRest repository this instance archives its write-ahead log
	// and takes its base backups to (ADR-0066 §3). It applies to Postgres and is ignored by every
	// other add-on. Passing it is what wires the plugin into the instance, so an instance created
	// with a nil archive has no archiving at all and physical backups of it are refused by name; a
	// later install with one wires it, because a destination registered after the instance was
	// created is a normal sequence and not a reason to rebuild the database. Like BackupDestination
	// it carries a credential PAIR and therefore never crosses an API boundary — the adapter puts it
	// in a Secret the plugin's sidecar reads by reference and nowhere else.
	DeployAddon(ctx context.Context, spec AddonSpec, env string, archive *ArchiveDestination) (AddonInfo, error)
	// AddonReady reports whether the named add-on's backing workload is available. It is a cheap
	// single-object readiness probe — readiness is a live property, not stored in the registry — and
	// a missing workload is reported as not ready (false, nil), not an error.
	//
	// WHICH object it reads is resolved from the cluster rather than from the name, because an add-on
	// instance is not always a Deployment: a Postgres instance has none at all, and its readiness is
	// its CloudNativePG `Cluster`'s ready instance count (ADR-0066 §1). Reading only the Deployment
	// would report every Postgres instance as not running, and the failure observer would then open
	// an ADR-0074 §6 discrepancy row against a database that is serving perfectly well — a false
	// absence, which is precisely the diagnosis §6 exists to make correctly.
	AddonReady(ctx context.Context, name string) (bool, error)
	// DeleteAddon tears down the named add-on's WORKLOAD — its Deployment, Service, collector, and
	// generated config — and, only when deleteData is true, destroys its data volume as well.
	// Keeping the volume by default is the load-bearing part: for the Postgres add-on that volume
	// holds every attached app's database (ADR-0031), and a removal meant as "stop this and put it
	// back" must not destroy it. A retained volume is left with whatever the add-on needs to be
	// usable again after a reinstall. It returns what was torn down and what was deliberately kept,
	// so the caller can report it. Removing an add-on that is not installed returns ErrNotFound.
	//
	// t is the add-on's TYPE, taken from the registry row rather than probed for, and it decides
	// which teardown runs: Postgres is a CloudNativePG `Cluster` and everything else is a Deployment
	// (ADR-0066 §1). A removal is the operation that must never guess — a Postgres instance has no
	// Deployment, and probing for one and finding nothing is indistinguishable from a probe that was
	// refused. Under CloudNativePG the claims belong to the OPERATOR and carry the `Cluster` as their
	// owner, so keeping the data means disowning them before the `Cluster` is deleted rather than
	// simply not deleting them — the same promise, a different act.
	DeleteAddon(ctx context.Context, name string, t AddonType, deleteData bool) (AddonRemoval, error)
	// AddonVolumes returns every PersistentVolumeClaim in the add-on namespace that Burrow created
	// for an add-on, whether or not the add-on that owns it still exists. It reads the CLUSTER, not
	// the registry, because that is the only place a volume outliving its add-on can be seen at all
	// (ADR-0064 §6) — a removed add-on is no longer a registry row, but its claim is still there and
	// still costing money. Deciding which of them are RETAINED is the engine's job. No claims is an
	// empty slice, not an error.
	AddonVolumes(ctx context.Context) ([]AddonVolume, 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 the agent control channel. 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

	// BackupJobPresent reports whether the one-shot Job for the given backup id still exists in the
	// add-on namespace. It is a READ, and it exists for one question the registry cannot answer on
	// its own (ADR-0074 §6): a backup row left `pending` — by a burrowd that restarted mid-backup, or
	// by a Job the cluster garbage-collected — is indistinguishable from a backup still running, and
	// a backup that never completed is the sort of thing discovered at restore time unless something
	// looks. A missing Job is reported as absent (false, nil), not an error.
	BackupJobPresent(ctx context.Context, backupID string) (bool, error)

	// RunBackupJob runs a one-shot Job in the add-on namespace that pg_dumps app's database on
	// environment env's 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 that instance's 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. env and app are validated before any Job is built: a dump names the server
	// it came from, so it is as environment-scoped as the database it reads (ADR-0067 §1).
	//
	// dest, when non-nil, adds the SECOND half of the Job: after the dump lands on the PVC, the same
	// pod writes it to the object store and reads it back, retrying a write that did not complete
	// (ADR-0063 §7). The Job then succeeds only if the object is there, which is what lets the
	// caller record a completed backup without lying. dest carries a credential PAIR and therefore
	// never crosses an API boundary — the adapter puts it in a Job-owned Secret and nowhere else.
	//
	// The returned BackupJobOutcome carries the dump's size in bytes (0 when unknown) and, on the
	// error path, the closed reason the Job reported for its failure, so the caller can record WHY a
	// backup failed rather than that it did. A non-nil error always accompanies a failure reason;
	// the outcome is still returned so the caller does not have to parse the error to record it.
	RunBackupJob(ctx context.Context, app, env, backupID string, dest *BackupDestination) (BackupJobOutcome, error)
	// RunRestoreJob runs a one-shot Job in the add-on namespace that pg_restores
	// /<backup-pvc>/<app>/<backupID>.dump into app's database on environment env's instance (--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. env and app are validated before any Job is built — restoring is the one
	// operation where reaching the wrong environment's server overwrites live data with another
	// environment's.
	RunRestoreJob(ctx context.Context, app, env, backupID string) error

	// RunPhysicalBackup asks CloudNativePG for a base backup of environment env's whole instance and
	// waits for the answer (ADR-0066 §2). It CREATES A CUSTOM RESOURCE and reads `.status`: a
	// `postgresql.cnpg.io/v1 Backup` with method `plugin`, handled by the pgBackRest plugin. Burrow
	// runs no backup tool, handles no superuser credential on this path, and constructs no Job — the
	// operator does the work and this seam reports what it said.
	//
	// It is refused, before any object is written, on an instance whose `Cluster` carries no
	// pgBackRest plugin: there is nowhere for a base backup to go, and a `Backup` object created
	// against it would sit in `pending` until the timeout rather than saying so.
	//
	// archive is the destination the caller resolved, and it is CHECKED against the instance's own
	// `Stanza` rather than trusted: the two can differ, and a backup verified against the wrong bucket
	// would be recorded as unreadable when it succeeded. The returned ObjectKey is derived from the
	// stanza, so it addresses where this instance actually writes.
	//
	// The returned outcome carries pgBackRest's own backup LABEL on success — the name the repository
	// knows this backup by, and the only handle a later restore has — and on failure the closed
	// reason. A `Backup` object that failed and an archive that is not reaching the store are
	// different reasons, because they are different problems (ADR-0063 §7). A non-nil error always
	// accompanies a failure reason; the outcome is returned either way so the caller records WHY
	// without parsing the error.
	RunPhysicalBackup(ctx context.Context, env, backupID string, archive *ArchiveDestination) (PhysicalBackupOutcome, error)
	// PhysicalBackupPresent reports whether the `Backup` object for the given backup id still exists
	// in the add-on namespace — BackupJobPresent's question for a physical backup, and it exists for
	// the same reason (ADR-0074 §6): a row left `pending` by a burrowd that restarted mid-backup is
	// otherwise indistinguishable from a backup still running. A missing object is absent (false,
	// nil), not an error.
	PhysicalBackupPresent(ctx context.Context, backupID string) (bool, error)
	// RestoreInstance rewinds environment req.Environment's whole Postgres instance to a point in its
	// pgBackRest repository and waits until the recovered instance is serving (ADR-0066 §4).
	//
	// IT REPLACES THE INSTANCE UNDER ITS OWN NAME. CloudNativePG never recovers in place — a recovery
	// bootstraps a new `Cluster` — but the name every consumer of a Postgres instance resolves
	// (AddonInstanceName: the Service, the superuser Secret, every DATABASE_URL) is not a detail a
	// restore may move. So the pre-restore `Cluster` and its data claims are removed and the recovered
	// one comes up under the same name, rather than a differently-named instance being stood up beside
	// it and every derivation in Burrow being asked to follow.
	//
	// THE CALLER HAS ALREADY TAKEN A BACKUP OF WHAT THIS DESTROYS, and this seam does not check that —
	// it is the engine's ordering (ADR-0064 §5) and the seam's job is the replacement. What the seam
	// does refuse is a recovery it cannot address: an instance with no `Stanza`, or one whose stanza
	// describes a repository other than req.Archive, because recovering from a bucket the instance
	// never wrote to produces an empty database rather than an error.
	//
	// req carries a credential PAIR and therefore never crosses an API boundary. The archived
	// write-ahead log and every base backup in the repository are left untouched: this reads from the
	// repository and writes nothing to it.
	RestoreInstance(ctx context.Context, req RestoreInstanceRequest) (RestoreInstanceOutcome, error)

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

type LedgerPruneResult struct {
	// Failures is how many resolved failure rows were removed.
	Failures int64 `json:"failures"`
	// Windows is how many observation windows were removed.
	Windows int64 `json:"windows"`
}

type LifecycleCheck struct {
	Status LifecycleStatus `json:"status"`
	// Detail explains the verdict in one line. For an unknown status it says WHY the configuration
	// could not be read, so nothing reads as "checked and fine".
	Detail string `json:"detail"`
	// Rule is the identifier of the rule that conflicts, when one does.
	Rule string `json:"rule,omitempty"`
	// Backup is the identifier of a retained backup the rule would already have expired, when
	// there is one. It is the concrete half of the refusal: not "this could be a problem" but
	// "this backup would be gone".
	Backup string `json:"backup,omitempty"`
}

type LifecycleRule struct {
	// ID is the rule's identifier at the vendor, quoted back in a refusal so the operator can find
	// the rule they have to change.
	ID string `json:"id,omitempty"`
	// Prefix is the key prefix the rule applies to; empty means the whole bucket.
	Prefix string `json:"prefix,omitempty"`
	// Enabled reports whether the rule is in force. A disabled rule deletes nothing and so cannot
	// conflict with retention.
	Enabled bool `json:"enabled"`
	// ExpireAfterDays is how many days after creation the rule deletes an object, or 0 when the
	// rule expires nothing by age (e.g. it only aborts incomplete multipart uploads).
	ExpireAfterDays int `json:"expire_after_days,omitempty"`
}

type LifecycleStatus string

type LimitCode string

type LimitError struct {
	// Operation is the operation that was refused (e.g. "deploy", "scale").
	Operation string
	// Code is the machine-readable limit that was exceeded.
	Code LimitCode
	// Requested is the value the caller asked for.
	Requested int32
	// Limit is the effective bound the request exceeded.
	Limit int32
	// Scope is the tier the effective bound came from: "environment", "cluster", or "default".
	Scope string
	// Env is the environment the request targeted, when it named one.
	Env string
	// Message is a human-readable explanation, naming the limit, the tier it came from, and the
	// operator command that changes it.
	Message string
}

type LimitInfo struct {
	Code        LimitCode `json:"code"`
	Value       string    `json:"value"`
	Description string    `json:"description"`
	Kind        LimitKind `json:"kind"`
	// Scope reports which tier the effective value came from: "environment", "cluster", or
	// "default" (the built-in). It is what tells an operator whether the value they are reading is
	// one someone set or one nobody has.
	Scope string `json:"scope"`
	// EnvScoped reports whether a value may be set for one environment at all (ADR-0068 §5).
	EnvScoped bool `json:"env_scoped"`
	// Default is the built-in value, so a listing shows what the limit reverts to.
	Default string `json:"default"`
}

type LimitKind string

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 MetricPoint struct {
	Time  string `json:"time,omitempty"`
	Value string `json:"value"`
}

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

type MetricSeries struct {
	Labels map[string]string `json:"labels,omitempty"`
	Points []MetricPoint     `json:"points"`
}

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 MetricsRangeQuerier interface {
	// QueryMetricsRange runs a PromQL range query against the Prometheus-API-compatible store
	// reachable at endpoint (an in-cluster host:port) over [start, end] sampled every step, and
	// returns one MetricSeries per matching series. token is a bearer credential for an
	// authenticated backend; an empty token means unauthenticated and no Authorization header is
	// sent.
	QueryMetricsRange(ctx context.Context, endpoint, query, token string, start, end time.Time, step time.Duration) ([]MetricSeries, error)
}

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

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

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

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

type NodeAllocatable struct {
	Name      string
	CPUMillis int64
	MemBytes  int64
}

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

type ObjectRef struct {
	Kind        FailureKind `json:"kind"`
	Name        string      `json:"name"`
	Environment string      `json:"environment,omitempty"`
}

type ObjectStore interface {
	// BucketExists reports whether the bucket is present and reachable with this credential. A
	// bucket that exists but belongs to someone else is reported as absent-or-unreachable rather
	// than present, since Burrow can do nothing with it either way.
	BucketExists(ctx context.Context, bucket string) (bool, error)
	// CreateBucket creates the bucket. The NAME is the engine's to choose (ADR-0063 §4: a readable
	// prefix plus a random component, recorded in the providers row) — an implementation creates
	// exactly the name it is given and never derives or adopts one.
	CreateBucket(ctx context.Context, bucket string) error
	// PutObject writes body at key. It exists for the configuration-time probe of ADR-0063 §2 and
	// for the backup path that follows; it is not a general upload surface.
	PutObject(ctx context.Context, bucket, key string, body []byte) error
	// PutObjectStream writes size bytes read from body at key, without holding them in memory. It
	// is PutObject's shape for the one payload that is not small — a pg_dump, which is routinely
	// gigabytes and would OOM the container that buffered it.
	//
	// sha256Hex is the hex SHA-256 of exactly those bytes, computed by the caller before the read
	// begins. It is not an optimisation: an S3-compatible endpoint validates the body against the
	// hash it was signed with and REFUSES a transfer that does not match, so passing it is what
	// makes "the store accepted the write" mean "the store accepted these bytes" rather than "the
	// store accepted some bytes". A caller that cannot compute it cannot use this method.
	//
	// It reports whether the write was REFUSED (the endpoint answered, and said no) as opposed to
	// failing to complete, because ADR-0063 §7 retries the second and must not retry the first: a
	// revoked credential does not become a valid one by being asked again, and spending the retry
	// budget on it delays the loud failure that is the whole point.
	PutObjectStream(ctx context.Context, bucket, key string, body io.Reader, size int64, sha256Hex string) (refused bool, err error)
	// StatObject returns the size of the object at key, or ErrNotFound when it is not there.
	//
	// It exists so a backup can be VERIFIED rather than assumed (ADR-0063 §7). A 200 on a write is
	// the endpoint's word that it accepted the request; reading the object back afterwards is the
	// separate fact that it can serve it, at the key Burrow recorded, at the length Burrow sent.
	// Those come apart in practice — an eventually-consistent listing, a bucket policy that permits
	// writes and not reads, a multipart upload that completed into nothing — and the difference is
	// only ever discovered at restore time unless something looks.
	StatObject(ctx context.Context, bucket, key string) (int64, error)
	// DeleteObject removes key. Deleting an object that is already absent is a no-op, not an error,
	// so the probe's cleanup is idempotent.
	DeleteObject(ctx context.Context, bucket, key string) error
	// LifecycleRules returns the bucket's lifecycle rules. NO rules is an empty slice and no error.
	//
	// A store that cannot ANSWER — the vendor does not implement the lifecycle API, or this
	// credential is not permitted to read it — returns an error wrapping ErrLifecycleUnknown, and
	// the engine reports the reconciliation as unknown rather than as verified (ADR-0063 §3: an
	// unverifiable invariant reported as verified is worse than one reported as unknown). Any other
	// error is a genuine failure.
	LifecycleRules(ctx context.Context, bucket string) ([]LifecycleRule, error)
}

type ObjectStoreConfig struct {
	// Endpoint is the S3-compatible API endpoint that answers for this provider. The vendor is
	// whoever answers it (ADR-0063 §1): Burrow maintains no vendor list.
	Endpoint string `json:"endpoint"`
	// Region is the region the request is signed for. Vendors that have no meaningful region still
	// require one in the signature; "auto" or "us-east-1" is the usual answer.
	Region string `json:"region,omitempty"`
	// Bucket is the bucket Burrow writes to. It is RECORDED, never derived (ADR-0063 §4): Burrow
	// only ever writes to the bucket it knows about, because inferring one by name is how a tool
	// ends up writing into something that belonged to somebody else.
	Bucket string `json:"bucket"`
	// Created reports whether Burrow created this bucket, as opposed to being pointed at one that
	// already existed.
	Created bool `json:"created,omitempty"`
	// AccessKeyIDKey is the burrow-credentials key holding the access key ID.
	AccessKeyIDKey string `json:"access_key_id_key"`
	// SecretAccessKeyKey is the burrow-credentials key holding the secret access key.
	SecretAccessKeyKey string `json:"secret_access_key_key"`
	// RetentionDays is how long backups written here must stay RESTORABLE, in days — the window
	// ADR-0063 §3 reconciles the bucket's lifecycle rules against. Zero means no window has been
	// declared, which today is the truthful description of Burrow's backups: nothing prunes them,
	// so they are meant to be restorable indefinitely and ANY expiry rule will eventually delete
	// one that is still retained.
	RetentionDays int `json:"retention_days,omitempty"`
}

type ObjectStoreCredential struct {
	AccessKeyID     string
	SecretAccessKey string
}

type ObjectStoreFactory interface {
	ObjectStore(endpoint, region string, cred ObjectStoreCredential) (ObjectStore, error)
}

type ObservationWindow struct {
	// ID is the store-assigned window identity (0 before it is persisted).
	ID int64 `json:"id,omitempty"`
	// StartedAt is when this run of the observer began.
	StartedAt time.Time `json:"started_at"`
	// Until is the end of the most recent sweep that COMPLETED its enumeration of what Burrow
	// manages. A sweep that could not enumerate does not advance it, so an observer that is running
	// but wedged stops claiming coverage instead of claiming it falsely.
	Until time.Time `json:"until"`
	// Sweeps is how many sweeps have advanced this window.
	Sweeps int64 `json:"sweeps"`
	// DegradedSweeps is how many of those could not read every object they set out to. Coverage in
	// such a sweep is partial, and a window that reports some is saying its ledger rows may be
	// incomplete for that stretch.
	DegradedSweeps int64 `json:"degraded_sweeps,omitempty"`
	// Detail is the most recent degradation note, bounded like a failure detail. Empty on a window
	// whose sweeps all completed.
	Detail string `json:"detail,omitempty"`
}

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

type ObserverConfig struct {
	// Interval is the sweep cadence. Zero or negative applies DefaultObserveInterval.
	Interval time.Duration
	// Retention is how long resolved failures and elapsed windows are kept. Zero applies
	// DefaultLedgerRetention; negative disables pruning, which is a deliberate operator choice and
	// not the default (ADR-0074 §4 requires the bound).
	Retention time.Duration
	// PruneInterval is how often retention is enforced. Zero applies DefaultLedgerPruneInterval.
	PruneInterval time.Duration
	// After returns a channel that fires after d — the seam the run loop waits on between sweeps.
	// Nil applies time.After. It is injected (rather than reading the wall clock) so a test drives
	// the loop with no real sleeping and no ambient time (ADR-0010).
	After func(d time.Duration) <-chan time.Time
}

type OperationalConfig struct {
	// Values holds every stored limit value keyed by the code it was set under — the bare code for
	// a cluster value and `<env>.<code>` for an environment one. That is the same keying guardrail
	// dispositions already use, so the two configuration surfaces resolve the same way and an
	// operator learns one rule (ADR-0068 §3).
	Values map[LimitCode]string
}