cluster

type AdoptionProbe interface {
	// ForeignStore reports the workload named name in namespace on kctx that
	// forge did not install: a Deployment or StatefulSet that carries no
	// forge.dev/component-owner label. found=false when there is none, or it is
	// a forge component's.
	ForeignStore(ctx context.Context, kctx, namespace, name string) (kind string, found bool, err error)
}

type AppliedOverride struct {
	Key       string `json:"key"`
	Kind      string `json:"kind"`
	Name      string `json:"name"`
	Namespace string `json:"namespace,omitempty"`
	Cluster   string `json:"cluster,omitempty"`
}

type ApplyOpts struct {
	// MainK is the path to deploy/kcl/<env>/main.k — the KCL entrypoint
	// that renders the cluster manifests. Required.
	MainK string

	// ImageTag is the value bound to KCL's `image_tag` -D variable.
	// Required (callers default to gitShortSHA at the call site).
	ImageTag string

	// ImageDigests is the per-image content-addressed digest map bound to
	// KCL's `image_digests` -D variable. When set, each rendered service's
	// manifest image resolves to ITS image's digest rather than the env-wide
	// ImageTag — the structural fix for a multi-image env pinning every
	// service to one digest.
	//
	// Keys are BOTH the bare image name (`reliant`) and the tag-qualified
	// name the build pushed (`reliant:e2e`), because the render looks up
	// whichever one the workload declares: an unpinned image takes the env
	// tag and is keyed bare, while an image that pins its own tag must match
	// a digest captured for THAT tag or stay unpinned. A tag-pinned image
	// renders as `<image>:<tag>@sha256:…`.
	//
	// May be nil/empty (the no-digest path), in which case every image stays
	// on ImageTag, byte-identical to before.
	ImageDigests map[string]string

	// Namespace is the namespace this apply WAITS in and prunes: the
	// rollout wait lists Deployments and Jobs here, and a Job naming no
	// namespace of its own is waited for here. Required.
	//
	// It is NOT a render input when Render is set. A deploy spanning several
	// namespaces applies one group per (cluster, namespace), and re-rendering
	// the env once per group with that group's namespace bound to KCL's
	// `namespace` option changes what the env DECLARES — every override and
	// URL keyed on the env namespace — so a group's render could disagree
	// with `forge env render` about which objects exist. Without Render (the
	// single-group callers: cluster reload, a direct apply) it is also the
	// namespace the env is rendered with.
	Namespace string

	// Render, when set, supplies the env's manifest stream instead of
	// RenderManifests(Namespace, …). A deploy renders the env ONCE, with the
	// env namespace `forge env render` uses, and every group's apply
	// partitions that one stream by cluster (ClusterScope) — the groups
	// differ in where they apply and wait, never in what the env declares.
	Render func(ctx context.Context) (string, error)

	// EnvConfigKV is the per-env config map projected as additional
	// `-D key=value` bindings to KCL. May be nil — the dev cluster
	// reload doesn't project per-env config (it would force a re-deploy
	// pipeline rebuild, defeating the inner-loop purpose).
	EnvConfigKV map[string]string

	// DryRun skips kubectl apply and prints the rendered manifests
	// instead. With DryRunFramed, the output is wrapped in
	// "--- Generated Manifests (dry-run) ---" / "--- End Manifests ---"
	// markers (the forge env deploy convention). Without it, raw manifests
	// are printed (the forge cluster reload convention).
	DryRun       bool
	DryRunFramed bool

	// Prune deletes forge-managed Deployments in the namespace that the
	// just-applied KCL render no longer produces. Opt-in — pruning is
	// destructive (see deploy.go's pruneOrphanDeployments docstring).
	Prune bool

	// Project is the forge project name. With Env it names the owner of
	// the CRDs this apply renders (CRDOwner), which is what makes CRD
	// pruning provable. Empty disables the CRD stamp and prune.
	Project string
	// PruneCRDs deletes the CRDs this (project, env) previously rendered
	// and no longer does, provided no custom resource of them remains —
	// see crd_prune.go. It runs only on a FULL apply: never with Targets,
	// never on a dry run. The env up and deploy paths set it, because a
	// CRD the render dropped is otherwise served forever.
	PruneCRDs bool

	// Rollout governs what the post-apply wait DOES, and — critically —
	// whether a rollout that never becomes ready fails the deploy.
	//
	// The zero value is RolloutPolicy{}, which Normalize() turns into the
	// safe default: wait for every managed Deployment, and FAIL if any of
	// them does not become ready. See RolloutPolicy.
	Rollout RolloutPolicy

	// Quiet suppresses the section-header banners ("Applying
	// manifests...", "Waiting for rollouts...") and emits the matching
	// per-resource warnings in the bare format ("Warning: <msg>" with
	// no leading indent) — the shape `forge cluster reload` used
	// pre-extraction. Off by default; the deploy and up call sites
	// keep the framed banners.
	Quiet bool

	// Env is the environment name (e.g. "dev", "dev-host", "prod")
	// passed to KCL as `-D env=<env>`. User main.k files can read it via
	// `option("env")` to conditionally include manifests — typical use
	// is skipping in-cluster infra (NATS, Temporal, LiteLLM) on dev-host
	// envs where docker-compose provides the same services.
	Env string

	// Context, when non-empty, is the kubectl context every kubectl
	// invocation in the apply/wait path runs against — passed as
	// `--context <ctx>` per command rather than mutating the global
	// active context (`kubectl config use-context`). This is what makes
	// concurrent multi-cluster `forge env deploy` safe: two deploys sharing
	// one kubeconfig but targeting different clusters no longer race on
	// the single global context. Empty = use kubectl's current/default
	// context (unchanged for single-cluster users).
	Context string

	// Targets, when non-empty, is the EXCLUSIVE set of KCL-declared service
	// GROUPs (`app.kubernetes.io/name` values) this apply keeps. The whole
	// env bundle is still rendered (KCL renders the env as a unit), but after
	// RenderManifests and before KubectlApply the multi-doc YAML is filtered
	// to EXACTLY the manifests whose group ∈ Targets — and EXACTLY the helm
	// charts whose Name ∈ Targets are rendered. The filter is purely
	// mechanical: it includes nothing implicitly. There is no shared-base
	// auto-keep, and no synthetic group: the env-shared manifests (Namespace,
	// ConfigMap, RuntimeClass, NetworkPolicy) and bundle-level
	// `additional_manifests` carry NO group, so they apply ONLY on a bare
	// deploy and are NEVER selected by a service Target. To make a manifest
	// ride a service's Target, declare it on that service's `manifests`.
	// Empty Targets means "apply EVERYTHING" — every manifest and every
	// declared platform dep (the full declarative reconcile). See
	// SelectManifestsByGroup and selectHelmChartsByGroup.
	Targets []string

	// HelmCharts are the env's declared platform dependencies, rendered
	// with helm-as-a-RENDERER (helm template --skip-crds) and folded into
	// THIS apply stream. Each is a renderable whose NAME is its GROUP — the
	// SAME exclusive Targets filter selects it: a chart is rendered + applied
	// iff (no Targets) OR (its Name ∈ Targets), the identical rule every other
	// manifest obeys (each chart's manifests are stamped
	// `app.kubernetes.io/name = Name`). There is NO chart opt-in special case
	// — a bare `forge env deploy <env>` (no Targets) reconciles every declared
	// platform dep too. Apply renders each selected chart, stamps every
	// manifest with its group, and applies it in CRD-first order (the chart's
	// forge-supplied CRDs → wait Established → the chart's controllers) so the
	// apply leaves CRDs Established + controllers Deployed. Empty => no
	// platform deps. See helm.go.
	HelmCharts []HelmChartSpec

	// ClusterScope, when non-nil, scopes the rendered env bundle to ONE
	// deploy group's cluster before applying — declared-cluster-only
	// multi-cluster routing. KCL renders the whole env as a unit (every
	// service's manifests in one stream), but each manifest must land ONLY
	// on the cluster of its OWNING service (identified by its
	// `app.kubernetes.io/name` label), and no other cluster may receive it.
	// Without this, every group applied the entire bundle to its own
	// `--context`, so a two-cluster env cross-contaminated both clusters
	// (the secondary got the whole stack and hard-failed on missing CRDs).
	// ScopeManifestsToGroup does the per-doc partition by owner; nil leaves
	// the stream untouched (the single-cluster path, byte-identical to the
	// pre-scoping behaviour). See ScopeManifestsToGroup for the ownership
	// rule.
	//
	// nil does NOT mean "write everything to Context": an object stamped
	// for a different cluster (ClusterRoutingLabel) is refused, scoped or
	// not — see refuseForeignClusterDocs.
	ClusterScope *GroupScope

	// OnStream, when non-nil, is handed the FINAL manifest stream — after
	// the --target filter and the multi-cluster scope, with every rendered
	// chart folded in — immediately before it is either applied or printed
	// as a dry run.
	//
	// This is the only place that stream exists. A caller cannot reproduce
	// it by re-rendering: it would have to re-apply both filters and
	// re-template every chart, and a second implementation of that is free
	// to disagree with this one about what ships. Reporting it from here
	// means a `--dry-run` preview and a real apply describe the same bytes
	// by construction.
	//
	// Called for dry runs too, BEFORE the early return — previewing what
	// would be applied is the primary use. Purely observational: the
	// callback's result is ignored and it cannot affect the apply.
	OnStream func(manifests string)

	// SkipUnits are the delivery units whose objects this apply LEAVES to the
	// hub: Bundle.hub_converges, resolved by the caller. The objects are
	// dropped from what is sent and their Deployments from what is awaited,
	// and nothing else changes: pruning still reads the full stream, because
	// pruning from a filtered one would delete every skipped Deployment as an
	// orphan. See delivery_unit_filter.go.
	SkipUnits []string

	// OnRollout, when non-nil, receives one observation per resource whose
	// readiness was awaited, as each verdict arrives.
	//
	// Apply's own return value stays the aggregate error, which is what
	// fails the deploy; this reports the per-resource detail that the
	// aggregate necessarily loses — in particular WHICH resource, and
	// whether its budget expired rather than a failure being observed. See
	// rollout_observer.go for why that third state cannot be reconstructed
	// from the outside.
	//
	// Not called under RolloutSkip: forge asks the cluster nothing in that
	// mode, so it has nothing to report, and inventing "not waited" entries
	// here would mean synthesizing observations Apply never made.
	OnRollout func(RolloutObservation)
}

type CRDState struct {
	Present bool
	// Owner is the forge.dev/component-owner label ("" when forge did not
	// install it).
	Owner string
	// Versions are the versions the CRD SERVES.
	Versions []string
}

type ComponentOwnerError struct {
	Component, Cluster, Holder, Wanted string
}

type ConfigMapGetter interface {
	GetConfigMapKeys(ctx context.Context, kctx, namespace, name string) (keys map[string]struct{}, exists bool, err error)
}

type CredentialedImageArchChecker interface {
	WithDockerConfigDir(dir string) ImageArchChecker
}

type CredentialedImageChecker interface {
	// WithDockerConfigDir returns an ImageChecker that runs `docker` with
	// DOCKER_CONFIG=dir, so private-registry lookups authenticate with the
	// cluster's pull creds materialised there.
	WithDockerConfigDir(dir string) ImageChecker
}

type DockerImageArchChecker struct {
	// DockerConfigDir overrides DOCKER_CONFIG for the docker invocation. Empty
	// inherits the process environment.
	DockerConfigDir string
}

type ExternalSecretSyncError struct {
	Context  string
	Failures []secretSyncFailure
	// Held names what was withheld, for the closing line.
	Held string
}

type GroupScope struct {
	// Cluster is THIS group's cluster name (forge.K8sCluster.cluster). It
	// is the value a manifest's first-class `forge.dev/cluster` routing
	// label is matched against: a manifest carrying that label lands on
	// this group iff the label equals Cluster, and is dropped otherwise —
	// no app-label indirection. Empty disables the first-class match (the
	// stream is routed purely by OwnApps/OtherApps, the pre-existing
	// behaviour). See ClusterRoutingLabel and ScopeManifestsToGroup.
	Cluster string

	// OwnApps is the set of `app.kubernetes.io/name` values belonging to
	// THIS group's services — their workloads (Deployment / Service /
	// per-service RBAC / HPA) AND the raw manifests those services own (a
	// CRD, env-level infra pinned to this cluster via an image-less infra
	// service). All carry the service's app label. These land on this
	// group's cluster.
	OwnApps map[string]struct{}

	// OtherApps is the set of app-name labels owned by OTHER k8s groups —
	// services that target a DIFFERENT cluster. These are dropped from this
	// group so a manifest never lands on a cluster its owner doesn't declare.
	OtherApps map[string]struct{}
}

type HelmChartSpec struct {
	// Name is the platform dep's NAME — the `--target` selector and the
	// `app.kubernetes.io/name` stamped on every rendered manifest.
	Name string
	// Chart is the chart name for a repo chart (e.g. "cert-manager").
	// Empty for an OCI chart (OCI carries the full ref).
	Chart string
	// Repo is the chart-repo URL (e.g. "https://charts.jetstack.io").
	// Mutually exclusive with OCI.
	Repo string
	// OCI is the OCI chart ref (e.g.
	// "oci://docker.io/envoyproxy/gateway-helm"). Mutually exclusive with Repo.
	OCI string
	// Version is the pinned chart version (e.g. "v1.20.1").
	Version string
	// Namespace is the namespace to render the chart into
	// (`helm template -n <namespace>`).
	Namespace string
	// Values is the helm values overlay (the `--values` file content),
	// passed through verbatim from the KCL `values` dict.
	Values map[string]any
	// CRDs is the forge-supplied CRD manifest YAML applied FIRST (before
	// the chart's controllers) and waited until Established. The caller
	// fetches it (pinned standard Gateway API CRDs / cert-manager CRDs at
	// the chart version). Empty when the chart needs no forge CRDs.
	CRDs string
	// CRDBundle NAMES the forge-supplied bundle CRDs holds the content of
	// ("gateway-api", "cert-manager", or empty). CRDs alone cannot answer
	// "which bundle is this?" — it is megabytes of YAML — and the render
	// has to know, because a chart whose Gateway API CRDs forge supplies
	// must also be told not to render the resources that ship ALONGSIDE
	// those CRDs upstream. See gatewayAPIChartValues.
	CRDBundle string
	// Manifests is the consumer-declared raw manifest YAML (a `---`-joined
	// stream) that rides this chart's `--target`: the cluster-scoped
	// instances a chart's controller reconciles but the chart doesn't ship
	// (the `eg` GatewayClass, cert-manager ClusterIssuers). Applied AFTER
	// the chart's controllers (so the controller is up before its
	// instances), stamped with the chart's app-label like the chart's own
	// output, so they ride the chart's GROUP under the exclusive `--target`
	// filter (selected iff no targets, or the chart's Name ∈ targets — the
	// same rule as the chart itself). Empty when the chart carries none.
	Manifests string
	// Cluster, when non-empty, is the kubectl CONTEXT this chart installs
	// into, overriding the env's primary cluster for this chart alone. It
	// is the denormalized `.context` of the `forge.Cluster` the chart's KCL
	// `cluster` field references (the CLI resolves the reference and
	// validates it against the env's declared clusters before building this
	// spec — see cli.helmChartSpecsFromEntities).
	//
	// THE GAP THIS CLOSES. An operator must be installed where the custom
	// resources it reconciles land, and in a multi-cluster env that is not
	// the primary cluster. control-plane's dev installs CNPG while its
	// managed-database tier renders `postgresql.cnpg.io/v1 Cluster` objects
	// into the cp-daemon cluster; with the operator on the control-plane
	// cluster the CR apply fails `no matches for kind "Cluster" in version
	// "postgresql.cnpg.io/v1"`.
	//
	// Empty => the env's primary cluster, so every pre-existing chart
	// declaration applies through the identical argv it did before.
	Cluster string

	// NamespaceLabels and NamespaceAnnotations are written onto the Namespace
	// forge creates for the chart (helm template never emits it). The
	// Namespace rides the chart's server-side apply, so a re-apply sets
	// exactly the declared keys, drops a key that is no longer declared (the
	// same field manager owned it), and leaves every key another manager set.
	//
	// PRECEDENCE: the labels forge stamps on that Namespace are forge's, and
	// a declaration may not set them (forgeOwnedNamespaceLabel). That is
	// enforced by REFUSING the spec in RenderHelmChart, as the KCL schema
	// refuses the declaration, rather than by picking a winner. Either
	// silent outcome is wrong: if forge's value won, the declared one would
	// vanish, and if the declared one won, forge's routing and ownership
	// stamps would change without anyone deciding to change them.
	NamespaceLabels      map[string]string
	NamespaceAnnotations map[string]string
	// Owner is the (project, env) that applies this chart — ChartOwner's
	// value. Every object the chart renders is stamped with it
	// (ChartOwnerLabel), and the chart's inventory is recorded per owner. The
	// prune after a successful apply deletes only objects that an earlier
	// apply recorded in that inventory and that still carry the stamp
	// (chart_prune.go). Empty disables the stamp, the inventory and the prune:
	// an owner that cannot be named cannot be proven.
	Owner string
	// Prune enables that prune for this chart. The zero value is OFF so a
	// spec built by hand never deletes anything by accident; the KCL
	// declaration defaults it to on.
	Prune bool
	// Patches are merge patches applied to the objects `helm template`
	// rendered, keyed `Kind/name` (the Bundle.overrides grammar, minus the
	// cluster qualifier). They reach what a chart's values cannot — a field
	// the chart does not template, such as a pod's runtimeClassName. Every
	// key must match exactly one rendered object.
	Patches map[string]any
}

type ImageArchChecker interface {
	ImageArchitectures(ctx context.Context, ref string) (archs []string, err error)
}

type ImageChecker interface {
	ImageExists(ctx context.Context, ref string) (exists bool, err error)
}

type IncompleteApplyError struct {
	// Rendered is how many identifiable objects the manifest stream held.
	Rendered int
	// Confirmed is how many of those the apply reported acting on.
	Confirmed int
	// Missing names the objects with no line in the apply output, as
	// `kind/name`, in render order, capped at maxMissingObjectsReported.
	Missing []string
	// Truncated is how many missing objects were elided from Missing.
	Truncated int
}

type KCLRunner func(ctx context.Context, projectDir, source, env string, options []string) ([]byte, error)

type KubectlConfigMapGetter struct{}

type KubectlPullCredsResolver struct{}

type KubectlRunningImages struct{}

type KubectlSecretGetter struct{}

type KubectlSecretValueGetter struct{}

type KubectlServedKinds struct{}

type KubectlStoreProbe struct {
	// PresenceFn answers Presence. Nil answers every name as present, so a probe
	// built without a store client checks nothing it cannot check.
	PresenceFn func(ctx context.Context, kctx string, read StoreRead) (map[string]bool, error)
}

type KubectlVolumeResize struct{}

type ManifestGVK struct {
	APIVersion string
	Kind       string
	// Name is metadata.name of the document (best-effort, "" when absent) —
	// used only to make the missing-CRD report actionable.
	Name string
}

type ManifestRefs struct {
	// Secrets maps a Secret, located where the referencing pod resolves it,
	// to the set of keys referenced from it. A key of "" (present in the set)
	// means a whole-Secret reference (envFrom secretRef, a volume mount, an
	// imagePullSecret) — verify existence only.
	//
	// Only REQUIRED references are here: every consumer that reads Secrets
	// as demand (the live check, the render-time supply gate, the secrets
	// lint) reads this map. A reference marked `optional: true` is in
	// OptionalSecrets instead.
	Secrets map[ResourceRef]map[string]struct{}
	// OptionalSecrets is Secrets for references marked `optional: true`.
	// Such a reference has two modes. While the Secret is ABSENT it demands
	// nothing: kubelet starts the pod without it, so no gate may report it.
	// Once the Secret is PRESENT it is a real input of the pod: the pod
	// template is pinned to it like any other (secret_pins.go), and the live
	// check reads the Secret and warns about a referenced key it lacks.
	OptionalSecrets map[ResourceRef]map[string]struct{}
	// ConfigMaps maps a ConfigMap, located like Secrets, to the set of keys
	// referenced from it. A key of "" means a whole-ConfigMap reference
	// (envFrom configMapRef or a whole-ConfigMap volume mount) — verify
	// existence only. A missing ConfigMap key fails a pod identically to a
	// missing Secret key (CreateContainerConfigError). Required references
	// only, like Secrets.
	ConfigMaps map[ResourceRef]map[string]struct{}
	// OptionalConfigMaps is ConfigMaps for `optional: true` references, with
	// OptionalSecrets' two modes (a ConfigMap pins nothing).
	OptionalConfigMaps map[ResourceRef]map[string]struct{}
	// Images is the set of distinct container image refs in the bundle.
	Images map[string]struct{}
	// ImagePullSecrets is the set of distinct Secrets referenced via a pod
	// spec's imagePullSecrets[].name. These are the credentials the CLUSTER
	// uses to pull private images — the image-verification path resolves
	// their .dockerconfigjson from the target cluster and uses it to
	// authenticate an otherwise auth-denied registry lookup, so a present
	// private image isn't false-flagged just because the LOCAL docker daemon
	// lacks creds for that registry. A subset of Secrets (which records every
	// Secret reference shape); kept distinct here because only
	// imagePullSecrets carry registry credentials.
	ImagePullSecrets map[ResourceRef]struct{}
}

type ObjectRef struct{ Kind, Namespace, Name string }

type OpenBaoExpectation struct {
	Name      string
	Namespace string
	// Installs is true when this deploy applies the component, so its converge
	// Job is about to be created and has not run yet.
	Installs bool
}

type OwnedKeep struct {
	Cluster, Kind, Namespace, Name, Why string
}

type OwnedPruneReport struct {
	Delete []liveChartObject
	Kept   []OwnedKeep
}

type PDBFinding struct {
	Name      string
	Namespace string
	Reason    string
	Fix       string
}

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

type PreRolloutJobError struct {
	// Context is the kubectl context the Jobs ran in, threaded into the
	// commands the message prints so they can be pasted as-is.
	Context  string
	Failures []PreRolloutJobFailure
	// Kind names the gate in the message: "pre-rollout" when empty, "secret
	// store" for the store component's own Jobs.
	Kind string
}

type PreRolloutJobFailure struct {
	Job       string
	Namespace string
	// State distinguishes a Job that positively failed from one whose
	// budget expired while it was still running.
	State   RolloutState
	Timeout time.Duration
	Err     error
}

type PreflightOpts struct {
	// Manifests is the rendered `---`-separated YAML stream about to be
	// applied. Refs are collected from it.
	Manifests string

	// Context is the DECLARED kubectl context (forge.K8sCluster.cluster)
	// the Secret checks run against — the SAME context the apply targets,
	// never the ambient one. Empty disables the Secret check (host-only /
	// compose env with nothing to verify against a cluster).
	Context string

	// Namespace is the deploy's target namespace: where a rendered object
	// that declares no metadata.namespace is applied, and so where ITS
	// Secret / ConfigMap references resolve. An object that declares a
	// namespace resolves its references there instead.
	Namespace string

	// DocumentContexts attributes each rendered document to the kubectl
	// contexts it is applied to, for an env that spans several clusters, so
	// every reference is checked on the cluster its pod actually runs on. It
	// must be the deploy's own router (ScopeManifestsToGroup), not a second
	// model of it. Nil — a single-cluster env — checks every reference on
	// Context. See RefPlacement.Contexts.
	DocumentContexts func(doc string) []string

	// Secrets resolves Secret keys against the target cluster.
	Secrets SecretGetter

	// ConfigMaps resolves ConfigMap keys against the target cluster. Like
	// Secrets, the check runs only when this and Context are both set.
	ConfigMaps ConfigMapGetter

	// ServedKinds resolves which resource types the target cluster serves, so
	// the CRD preflight can BLOCK a deploy that renders a kind (e.g. GRPCRoute)
	// whose CRD / Gateway API channel isn't installed — before the partial
	// apply that otherwise errors `no matches for kind` mid-rollout. The check
	// runs only when this and Context are both set, and only gates NON-CORE
	// kinds (core kinds like Deployment/Service are served by every cluster, so
	// gating them would false-positive on a discovery blind spot). Nil disables
	// the CRD gate (local dev / nothing to verify).
	ServedKinds ServedKindChecker

	// VolumeResize judges every StatefulSet the bundle renders against the
	// live one, so a change to its volumeClaimTemplates that no resize can
	// converge (a shrink, a changed storage class, a claim whose class cannot
	// expand) BLOCKS before anything is applied. Runs only with a Context.
	// Nil disables the check. See VolumeResizeChecker.
	VolumeResize VolumeResizeChecker

	// Images checks image existence against the registry.
	Images ImageChecker

	// ImageRecheckDelay is how long to wait before the one recheck a miss or
	// an inconclusive lookup gets (see checkOneImage). A registry having a bad
	// minute answers wrongly in bursts, so a little space between the looks
	// is what makes the second one independent. Zero rechecks immediately.
	ImageRecheckDelay time.Duration

	// RunningImages lists the images the target cluster is RUNNING right
	// now. An image a live container is running cannot be "missing": the
	// registry's not-found (or refusal) for it is downgraded to a warning
	// that names both facts, instead of blocking a deploy whose image is
	// demonstrably pullable. Consulted only when an image would otherwise
	// block, and only with a Context. Nil disables the downgrade.
	RunningImages RunningImageLister

	// ImageArch reports an image's advertised architecture(s) for the arch
	// gate. Nil disables the gate entirely (the existence check still runs).
	ImageArch ImageArchChecker

	// PullCreds resolves the CLUSTER's registry pull credentials (the
	// .dockerconfigjson of the bundle's imagePullSecrets) from the target
	// cluster. When set AND the image checker implements
	// CredentialedImageChecker AND the bundle declares imagePullSecrets, an
	// AUTH-DENIED registry lookup from the LOCAL docker daemon is RETRIED with
	// those creds, so a present private image the cluster can pull yields a TRUE
	// verdict instead of a false BLOCK. Nil (or no imagePullSecrets, or creds
	// not resolvable) leaves the existing local-daemon behaviour unchanged — the
	// auth-denied lookup still BLOCKS (fail-safe, no regression). Each pull
	// Secret is resolved where the pod that names it reads it — its
	// namespace, on its cluster — and the results are merged.
	PullCreds PullCredsResolver

	// TargetArch is the DECLARED node architecture of the target cluster
	// (GOARCH form: "amd64" / "arm64"), resolved from the env's KCL
	// `deploy.Cluster.platform`. When set AND ImageArch is configured, each
	// checked image's architectures are compared to it and a mismatch BLOCKS
	// the deploy (the exec-format-error gate). EMPTY means the env hasn't
	// declared a platform yet — the gate is INERT (WARN-don't-block) so envs
	// that predate the platform field (incl. the local e2e path) are never
	// false-failed.
	TargetArch string

	// SkipImageRef, when non-nil, returns true for image refs that should
	// NOT be checked (e.g. local k3d / registry.localhost refs in a dev
	// loop). A nil func checks every image (both existence AND arch).
	SkipImageRef func(ref string) bool

	// RequiredSecrets are the env's DECLARED external Secret prerequisites
	// (forge.ExternalSecret) — out-of-band Secrets the deploy depends on but
	// forge does NOT create. UNLIKE the secretKeyRef check above (which is
	// driven by what the rendered manifests reference, each in its
	// referencing object's namespace), a declared prereq names no consumer
	// and carries its OWN namespace (cert-manager's `cloudflare-api-token`
	// lives in the `cert-manager` namespace, not the deploy namespace), so
	// each is checked in its declared namespace. A
	// declared-required-but-absent Secret/key BLOCKS — this is the whole
	// point: it converts "render green, then ACME hangs silently" into a
	// fail-fast pre-apply block. Verified only when opts.Secrets is configured
	// (a SecretGetter against the live target). Empty => no declared prereqs.
	RequiredSecrets []RequiredSecret

	// RequiredSecretContexts are the kubectl contexts in which the declared
	// prerequisites must ALL exist. An environment can deploy one render to
	// several clusters, and a workload scheduled onto the secondary needs its
	// Secret THERE — checking only the primary passes a deploy that then dies
	// at rollout with CreateContainerConfigError, which is the same class of
	// late, opaque failure this preflight exists to prevent.
	//
	// Unlike the manifest-driven secretKeyRef check, this one is NOT gated to
	// remote clusters. That gate exists because forge applies its own projected
	// Secrets moments after the preflight, so checking them locally would
	// false-fail the inner loop. A forge.ExternalSecret is BY DEFINITION one
	// forge does not create — the provisioning is out-of-band — so the
	// rationale does not apply, and skipping it locally removed the check
	// exactly where the local dev loop needed it.
	//
	// Empty falls back to Context, preserving single-cluster behaviour.
	RequiredSecretContexts []string

	// SecretValues, when set, resolves a Secret's full .data value bytes
	// (base64-decoded) for the cross-secret BYTE-MATCH check: ExternalSecrets
	// sharing a `value_group` must carry IDENTICAL bytes under their keys. A
	// drifted copy (same group, different bytes — a half-rotated credential)
	// is caught here before it ships. Nil => the byte-match compare is skipped
	// (the KCL schema still enforces that a group's members declare the same
	// KEY SET; only the live byte equality needs cluster reads).
	SecretValues SecretValueGetter

	// ProvisionedByDeploy are the Secrets THIS deploy creates AFTER the
	// preflight runs, so the live existence check must not demand them
	// up-front. Today that is exactly the forge.KubeconfigSecret declarations
	// forge MINTS on the deploy path (a declared service_account).
	//
	// Without this the gate blocks on its own output: forge refuses to deploy
	// because a Secret is absent, and the deploy it refuses is the one that
	// would have created it. There is no order of operations that fixes it —
	// minting first would grant a credential on a deploy the gate then
	// rejects, and under --dry-run the mint writes nothing at all, so the
	// Secret is absent by construction.
	//
	// This is the same reasoning that already skips the local-cluster Secret
	// check: a Secret forge itself applies moments later is not a missing
	// dependency, it is a not-yet-executed step of this deploy.
	//
	// The set must be DERIVED from the provisioning step rather than
	// re-described beside it, or the two drift and the gate silently stops
	// covering a Secret nobody creates. The caller builds it from the same
	// filter the mint phase iterates.
	//
	// Scope is deliberately narrow: a Secret in here is exempt from the live
	// existence check ONLY. It still counts as DEMAND for every other gate,
	// and a Secret forge does not provision — including a KubeconfigSecret
	// that COPIES a kubeconfig rather than minting one — is not in this set
	// and still BLOCKS when absent.
	ProvisionedByDeploy []ProvisionedSecret

	// SecretSupply is the env's bundle-internal Secret SUPPLY for the
	// RENDER-TIME back-propagation gate (CheckSecretSupply): the Secrets the
	// bundle PROVIDES via a forge.KubeconfigSecret mint, a forge.ExternalSecret
	// out-of-band promise, or any other generated/known Secret forge produces.
	// Rendered-stream Secrets (kind: Secret) are collected from Manifests
	// directly, so this need only carry the entity-derived supply. The gate is
	// pure (NO cluster) and ALWAYS runs — it converts a workload mounting a
	// Secret nothing declares (the silent FailedMount / 15-min ContainerCreating
	// rot) into a fail-fast render-time BLOCK. Empty => only rendered-stream
	// Secrets count as supply. See SecretSupply / CheckSecretSupply.
	SecretSupply []SecretSupply

	// StoreExpect and StoreProbe drive the store-source preflight (SF9): the
	// CRDs, the External Secrets Operator's owner, the store's readiness and
	// whether the store holds the names the store-backed ExternalSecrets read.
	// Each expectation names its OWN cluster, so the check runs whatever
	// opts.Context is. Both must be set for it to run. When it does, the
	// generic served-kinds gate leaves the external-secrets.io group to it,
	// because only the store check knows whether THIS deploy installs the
	// operator that serves those kinds. See CheckStore.
	StoreExpect []StoreExpectation
	StoreProbe  StoreProbe
}

type PreflightResult struct {
	// MissingSecretKeys maps "<namespace>/<secret>" to the sorted list of
	// referenced keys that are absent (or the whole Secret, rendered as a
	// single marker when the Secret doesn't exist). The namespace is the
	// referencing object's. When the run spans more than one cluster the
	// key is "<context>:<namespace>/<secret>".
	MissingSecretKeys map[string][]string
	// MissingConfigMapKeys maps "<namespace>/<configmap>" (cluster-qualified
	// like MissingSecretKeys) to the sorted list of referenced keys that are
	// absent (or the whole-ConfigMap marker when the ConfigMap doesn't
	// exist).
	MissingConfigMapKeys map[string][]string
	// MissingImages is the sorted list of image refs CONFIRMED absent.
	MissingImages []string
	// MissingImageEvidence maps each MissingImages ref to what the registry
	// answered, verbatim, when the checker carried it (ErrImageNotFound).
	MissingImageEvidence map[string]string
	// UnverifiableImages is the sorted list of "<ref>: <reason>" entries for
	// images whose registry lookup was AUTH-DENIED (denied / unauthorized /
	// 403). Their presence is unknown and a deploy gate must not silently
	// pass an image it cannot confirm — these BLOCK, with a message naming
	// both possible causes (image not pushed, OR the deploy host lacks pull
	// creds for the registry).
	UnverifiableImages []string
	// ImageWarnings is the sorted list of "could not verify" notes for
	// images whose existence check was inconclusive — a TRANSPORT failure
	// (DNS, connection refused, i/o timeout, docker daemon down) that says
	// nothing about the image. These do NOT block the deploy — they are
	// printed so the user knows the gate couldn't vouch for those images.
	ImageWarnings []string
	// ArchMismatchImages is the sorted list of "<ref>: image is <archs>,
	// cluster nodes are <target>" entries for images whose advertised
	// architecture does NOT include the target cluster's declared arch. These
	// BLOCK — running an arm64 image on amd64 nodes is the exec-format-error
	// crash, caught here before a single pod schedules. Only populated when a
	// target arch is DECLARED (an undeclared target arch can't assert a
	// mismatch).
	ArchMismatchImages []string
	// ArchWarnings is the sorted list of advisory notes for images whose arch
	// could not be read (transport failure / inconclusive). These do NOT
	// block — a mismatch can only be asserted on a known arch.
	ArchWarnings []string
	// MissingCRDs is the sorted list of "<Kind> (<apiVersion>) — required by
	// <manifest-name>" entries for NON-CORE kinds the bundle renders that the
	// target cluster's API server does NOT serve (no installed CRD / Gateway
	// API channel). These BLOCK — applying such a manifest fails `no matches
	// for kind` mid-rollout, AFTER other resources already applied. Only
	// populated when a ServedKindChecker is configured (an undeclared discovery
	// surface can't assert a kind is missing).
	MissingCRDs []string
	// VolumeResizeRefusals is the sorted list of "<namespace>/<name>: <reason>"
	// entries for StatefulSets whose declared volumeClaimTemplates differ from
	// the live ones in a way the pre-rollout resize Job (and the direct-apply
	// recovery) REFUSES: a shrink, a changed storage class or access mode, or a
	// claim that must grow whose StorageClass does not allow expansion. These
	// BLOCK: the apply would fail on the immutable field, and a Flux-applied
	// copy would wedge its whole tree.
	VolumeResizeRefusals []string
	// VolumeResizeWarnings are the StatefulSets whose live volumes could not
	// be read (a transport or permission failure). They do NOT block, and are
	// printed so a clean-looking run is not mistaken for a checked one.
	VolumeResizeWarnings []string
	// OptionalKeyWarnings are the keys an `optional: true` reference reads
	// from a Secret or ConfigMap that EXISTS on the live target but lacks
	// them, one "<Kind> <subject>: <key>" entry each, plus optional
	// resources that could not be read. They do NOT block: the reference is
	// optional down to the key (kubelet starts the pod with the variable
	// unset), and a key absent by design — an optional integration's
	// credential in a shared Secret — is exactly what `optional` is for. A
	// key the Secret must carry blocks through a declaration instead: a
	// required reference, or a forge.ExternalSecret's `keys`. An ABSENT
	// optional resource is not listed at all.
	OptionalKeyWarnings []string
	// MissingRequiredSecretKeys maps "<namespace>/<secret>" (as
	// "<context>:<namespace>/<secret>" when the run spans more than one
	// cluster) to the sorted list
	// of declared-required keys absent on the live target (or the whole-Secret
	// marker when the Secret itself is absent), for the DECLARED external
	// Secret prerequisites (forge.ExternalSecret). These BLOCK — the deploy
	// renders a consumer (e.g. cert-manager's DNS-01 ClusterIssuer) that reads
	// the Secret out-of-band, so its absence hangs ACME/DNS silently after a
	// green apply. Only populated when a SecretGetter is configured.
	MissingRequiredSecretKeys map[string][]string
	// ByteMatchMismatches is the sorted list of advisory notes for
	// cross-secret byte-match groups whose live Secret values are NOT
	// identical across the group (a half-rotated / drifted shared credential).
	// These BLOCK — a value_group declares that the same logical secret is
	// projected to N refs, so a divergence means one consumer has the stale
	// value. Only populated when a SecretValueGetter is configured AND every
	// member Secret exists (a missing member is reported by the existence
	// check, not here).
	ByteMatchMismatches []string
	// UndeclaredSecretMounts is the RENDER-TIME back-propagation result: every
	// Secret a workload mounts/references that NOTHING in the rendered bundle
	// provides (no rendered Secret, no KubeconfigSecret, no ExternalSecret, no
	// generated/known Secret). These BLOCK — the pod would stick on
	// MountVolume.SetUp failed / CreateContainerConfigError forever, with zero
	// error at deploy time. Unlike every other field here this is a PURE,
	// no-cluster check that ALWAYS runs (incl. dry-run / local clusters) — it's
	// the complement to the live Secret preflight. See CheckSecretSupply.
	UndeclaredSecretMounts []UndeclaredSecretMount
	// Store is the store-source preflight: gaps in how store-backed Secrets
	// would be delivered (CRDs, operator owner, store readiness, values the
	// store lacks). Its blocking findings BLOCK; Store.Warnings do not.
	Store StoreFindings
}

type ProvisionedSecret struct {
	// Name is the k8s Secret name this deploy will create.
	Name string
	// Namespace is the declared namespace (empty means the deploy namespace).
	Namespace string
	// By names the provisioning step, for the report.
	By SecretSupplyKind
}

type PullCredsResolver interface {
	ResolveDockerConfig(ctx context.Context, kctx, namespace string, secretNames []string) (dockerConfigJSON []byte, err error)
}

type RefPlacement struct {
	// Namespace is the namespace of a document that declares none — the
	// deploy namespace `kubectl apply -n` puts it in.
	Namespace string
	// Context is the cluster every document lands on when Contexts is nil.
	Context string
	// Contexts attributes one document to the kubectl contexts it is applied
	// to, for an env that spans several clusters. It must be the deploy's own
	// router (ScopeManifestsToGroup), never a second model of it. Nil means
	// every document lands on Context. A document it attributes to no cluster
	// is applied nowhere, so it demands nothing.
	Contexts func(doc string) []string
}

type RegistryImageChecker struct {
	// DockerConfigDir, when set, reads credentials from <dir>/config.json
	// instead of the ambient docker config.
	DockerConfigDir string
}

type RenderedChartStream struct {
	Name    string
	Cluster string
	Stream  string
}

type RequiredSecret struct {
	// Name / Namespace identify the out-of-band Secret. Namespace is the
	// declared namespace (often NOT the deploy namespace).
	Name      string
	Namespace string
	// Keys are the data keys the consumer reads; each must exist.
	Keys []string
	// ValueGroup ties this Secret to others that must carry identical bytes
	// (the cross-secret byte-match group). Empty => standalone.
	ValueGroup string
	// Contexts are the kubectl contexts THIS Secret must exist in: the
	// clusters that receive its consumer. A multi-cluster env does not need
	// every Secret everywhere — control-plane's prod daemon cluster receives
	// only PriorityClasses and a pre-pull DaemonSet, and requiring the app's
	// Secrets there blocked every prod deploy. Empty => every context the
	// prerequisites are checked in (RequiredSecretContexts, else Context), the
	// conservative choice for a Secret nothing attributes to a cluster.
	Contexts []string
}

type ResourceRef struct {
	// Context is the kubectl context of the cluster the referencing object is
	// applied to. Empty when the collection was not placed on a cluster.
	Context string
	// Namespace is the referencing object's metadata.namespace, or the deploy
	// namespace when it declares none.
	Namespace string
	// Name is the referenced Secret / ConfigMap name.
	Name string
}

type RolloutFailedError struct {
	Failures []error
}

type RolloutMode string

type RolloutObservation struct {
	// Kind is the workload kind that was awaited: "Deployment" or "Job".
	Kind string
	// Name is the resource's name.
	Name string
	// State is the three-way outcome.
	State RolloutState
	// Err is the underlying wait error for a failed or timed-out resource,
	// nil when ready. Carried so a caller can report the cause without
	// re-deriving it from the state.
	Err error
}

type RolloutPolicy struct {
	// Mode selects wait / warn / skip. Empty means RolloutWait.
	Mode RolloutMode

	// Timeout bounds EACH resource's wait (per Deployment, per Job), not
	// the whole set — a 12-service env is not 12x more likely to be broken
	// than a 1-service one, and a shared budget would make the last
	// service's verdict depend on how slow the first was.
	//
	// Zero means DefaultRolloutTimeout. The old hardcoded 60s was a
	// local-k3d value applied to cloud: a cold cloud rollout that pulls a
	// fresh image routinely exceeds a minute, so it produced spurious
	// failures on exactly the deploys that mattered most.
	Timeout time.Duration

	// FailFast stops at the FIRST resource that fails instead of waiting
	// for the rest.
	//
	// Default (false) is deliberate: when a deploy goes wrong you usually
	// want the whole picture — "these 3 of 12 never came up" — and the
	// remaining waits cost nothing on a healthy resource, because a ready
	// Deployment returns immediately. Turn it on when the failures are
	// expected to cascade and you would rather see the first one now than
	// wait out eleven timeouts.
	FailFast bool

	// Order, when non-empty, is a prefix ordering for the Deployment wait:
	// these names are awaited first, in this order, before everything else
	// (which follows in its natural order).
	//
	// This is a WAIT ordering, not an apply ordering — kubectl applies the
	// stream in one shot and Kubernetes converges concurrently, so forge
	// cannot serialize the rollouts themselves without lying about what it
	// controls. What it CAN do is decide what to report first, which is
	// what makes a phased deploy legible: put the database migration or the
	// API server first and its failure surfaces before a dozen dependents
	// time out waiting on the thing that was already broken.
	//
	// Names not present in the namespace are ignored, so an ordering can
	// name a resource a --target filter excluded without erroring.
	Order []string
}

type RolloutState int

type RunningImageLister interface {
	RunningImages(ctx context.Context, kctx string) (map[string]string, error)
}

type SecretGetter interface {
	GetSecretKeys(ctx context.Context, kctx, namespace, name string) (keys map[string]struct{}, exists bool, err error)
}

type SecretSupply struct {
	// Name is the k8s Secret name this source provides. The match key.
	Name string
	// Namespace is the source's declared namespace (may differ from the deploy
	// namespace; empty means "the deploy namespace"). Recorded for the report
	// only — the match is name-based to avoid false positives.
	Namespace string
	// Kind labels the source for the report.
	Kind SecretSupplyKind
}

type SecretSupplyKind string

type SecretValueGetter interface {
	GetSecretValues(ctx context.Context, kctx, namespace, name string) (values map[string][]byte, exists bool, err error)
}

type ServedKindChecker interface {
	// ServedKinds returns the set of resource types the cluster serves, keyed
	// by servedKindKey(group, kind).
	ServedKinds(ctx context.Context, kctx string) (served map[string]struct{}, err error)
}

type StoreExpectation struct {
	// Context is the kubectl context the objects land on.
	Context string
	// Owner is the component-owner stamp of this Bundle (CRDOwner(project, env)).
	Owner string
	// InstallsESO is true when this deploy installs the External Secrets
	// Operator on Context (a forge.ExternalSecretsOperator for the cluster that
	// the deploy's --target selects). The CRDs are then applied before anything
	// that uses them, so their absence is not a gap, and a different live owner
	// is a conflict.
	InstallsESO bool
	// OpenBao, when non-nil, is the forge.OpenBao this Bundle runs on Context
	// and that a store-backed Secret reads from.
	OpenBao *OpenBaoExpectation
	// Reads are the stores the Secrets on Context read from, by kind.
	Reads []StoreRead
}

type StoreFindings struct {
	// MissingCRDs: kinds the cluster does not serve and nothing in this deploy
	// installs.
	MissingCRDs []string
	// IncompatibleCRDs: the operator is there but does not serve the version
	// the render emits.
	IncompatibleCRDs []string
	// OwnerConflicts: another env owns the cluster's External Secrets Operator.
	OwnerConflicts []string
	// StoreNotReady: the store this Bundle runs has not finished converging.
	StoreNotReady []string
	// MissingStoreNames: names the ExternalSecrets read that the store does not
	// hold.
	MissingStoreNames []string
	// Warnings are advisory: a store that could not be asked. They do not block.
	Warnings []string
	// Adoptions are advisory: this deploy replaces a live OpenBao that forge did
	// not install, and the clients of that store lose access until they log in
	// the way the component's access document allows. They do not block.
	Adoptions []string
}

type StoreProbe interface {
	// CRD reads one CustomResourceDefinition on kctx.
	CRD(ctx context.Context, kctx, name string) (CRDState, error)
	// ConvergeSucceeded reports whether the NEWEST OpenBao converge Job of the
	// component has completed. found=false when none exists.
	ConvergeSucceeded(ctx context.Context, kctx, namespace, name string) (succeeded, found bool, err error)
	// Presence returns the names of read.Names the store holds a usable value
	// for. It never sees or returns a value.
	Presence(ctx context.Context, kctx string, read StoreRead) (present map[string]bool, err error)
}

type StoreRead struct {
	// Kind is "hosted", "openbao" or "gcpsm"; Project names the GSM project.
	Kind    string
	Project string
	// Names are the store names that must hold a value: every name the
	// ExternalSecrets read, less the ones the source generates itself.
	Names []string
	// Pending is true when the store is being installed by this deploy, so it
	// holds nothing yet and its names cannot be checked.
	Pending bool
}

type UndeclaredSecretMount struct {
	// Secret is the demanded Secret name nothing supplies.
	Secret string
	// Workloads are the names of the manifests that mount/reference it,
	// deduped + sorted. Best-effort: a workload whose metadata.name couldn't be
	// read contributes nothing.
	Workloads []string
}

type VolumeResizeChecker interface {
	Judge(ctx context.Context, kctx string, desired *appsv1.StatefulSet) error
}

type WorkloadImage struct {
	// Kind is the Kubernetes kind, as the API server reports it
	// ("Deployment", "CronJob").
	Kind string
	// Name is metadata.name.
	Name string
	// Container is the container's name within the pod template. Init
	// containers are included and are not distinguished here — the image is
	// what matters, and forge's `job` expansion puts real application images
	// in init containers.
	Container string
	// Init distinguishes a named init slot from a main/sidecar slot.
	Init bool
	// Image is the reference exactly as declared, unparsed:
	// "ghcr.io/acme/api@sha256:..." or "ghcr.io/acme/api:v1.2.3".
	Image string
	// EnvVar names the environment variable this reference came from, empty
	// when the reference is the container's own `image` field.
	//
	// WHY A SECOND SOURCE EXISTS. Not every image a release ships runs as a
	// workload. An operator that launches pods on demand carries its pod
	// image as a config value — control-plane's workspace-controller pins
	// the workspace base image in DAEMON_IMAGE — so the image is deployed,
	// digest-pinned, and part of the release, while running nowhere at the
	// moment anyone looks. Reading only container images reports that as
	// MISSING, which is a false failure on a correct environment; ignoring
	// it entirely would leave a genuinely drifted operator image invisible.
	// Both are avoided by treating it as what it is: a declared reference
	// from a different field of the same pod spec.
	EnvVar string
}