gittarget_controller.go

// SPDX-License-Identifier: Apache-2.0

package controller

import (
	"context"
	"errors"
	"fmt"
	"path/filepath"
	"strings"
	"time"

	"filippo.io/age"
	fluxmeta "github.com/fluxcd/pkg/apis/meta"
	"github.com/go-logr/logr"
	corev1 "k8s.io/api/core/v1"
	apierrors "k8s.io/apimachinery/pkg/api/errors"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/apimachinery/pkg/runtime"
	k8stypes "k8s.io/apimachinery/pkg/types"
	"k8s.io/client-go/tools/record"
	ctrl "sigs.k8s.io/controller-runtime"
	"sigs.k8s.io/controller-runtime/pkg/builder"
	"sigs.k8s.io/controller-runtime/pkg/client"
	"sigs.k8s.io/controller-runtime/pkg/event"
	"sigs.k8s.io/controller-runtime/pkg/handler"
	logf "sigs.k8s.io/controller-runtime/pkg/log"
	"sigs.k8s.io/controller-runtime/pkg/predicate"
	ctrlreconcile "sigs.k8s.io/controller-runtime/pkg/reconcile"
	"sigs.k8s.io/controller-runtime/pkg/source"

	configbutleraiv1alpha3 "github.com/ConfigButler/gitops-reverser/api/v1alpha3"
	"github.com/ConfigButler/gitops-reverser/internal/git"
	"github.com/ConfigButler/gitops-reverser/internal/reconcile"
	"github.com/ConfigButler/gitops-reverser/internal/telemetry"
	"github.com/ConfigButler/gitops-reverser/internal/types"
	"github.com/ConfigButler/gitops-reverser/internal/watch"
)

const (
	GitTargetConditionReady                = ConditionTypeReady
	GitTargetConditionReconciling          = ConditionTypeReconciling
	GitTargetConditionStalled              = ConditionTypeStalled
	GitTargetConditionValidated            = "Validated"
	GitTargetConditionEncryptionConfigured = "EncryptionConfigured"
	GitTargetConditionGitPathAccepted      = ConditionTypeGitPathAccepted
	GitTargetConditionRenderMatchesLive    = ConditionTypeRenderMatchesLive
	// GitTargetConditionStreamsRunning is the source data-plane axis: True when every tracked type's
	// watch has crossed its replay watermark or resumed from a durable cursor.
	GitTargetConditionStreamsRunning = ConditionTypeStreamsRunning
)

const (
	// GitTargetReasonOK is the healthy reason. It is the shared Succeeded vocabulary rather than
	// a per-kind spelling; the name is kept for call-site stability.
	GitTargetReasonOK               = ReasonSucceeded
	GitTargetReasonProviderNotFound = "ProviderNotFound"
	GitTargetReasonBranchNotAllowed = "BranchNotAllowed"
	// GitTargetReasonParentBranchNotFound is the Ready reason for a write branch that cannot be
	// created: the remote carries neither it nor the spec.parentBranch it would start from.
	GitTargetReasonParentBranchNotFound = "ParentBranchNotFound"
	GitTargetReasonTargetConflict       = "TargetConflict"
	GitTargetReasonNotChecked           = "NotChecked"
	GitTargetReasonBlocked              = "Blocked"
	GitTargetReasonNotStarted           = "NotStarted"
	GitTargetReasonNotRequired          = "NotRequired"
	GitTargetReasonMissingSecret        = "MissingSecret"
	GitTargetReasonInvalidConfig        = "InvalidConfig"
	GitTargetReasonSecretCreateDisabled = "SecretCreateDisabled"
	GitTargetReasonUnsupportedContent   = "UnsupportedContent"
	// GitTargetReasonIgnoreShadowsManagedPath is the terminal reason for the one
	// unrecoverable .gittargetignore footgun (docs/spec/gitpath-foreign-content-stringency.md
	// §4.3): an ignore pattern matches a path the operator writes, which would blind it to its
	// own file. The writer's write-plan precondition refuses the flush before any byte is
	// written and the GitTarget is failed with this reason. The string must stay in sync with
	// the watch package's gitPathRefusalReason.
	GitTargetReasonIgnoreShadowsManagedPath = "IgnoreShadowsManagedPath"
	// GitTargetReasonWriteBoundaryRefused is the reason for a write the operator refused
	// because it had nowhere safe to land, rather than because the folder holds content the
	// operator cannot manage
	// (docs/design/support-boundary/gittarget-granularity-and-cross-environment-edits.md §1): a
	// planned write escaping spec.path (L1), or an in-place edit of a source file more than
	// one kustomize render root reaches (L2, write-fan-in > 1). Nothing was committed. The
	// string must stay in sync with the watch package's gitPathRefusalReason.
	GitTargetReasonWriteBoundaryRefused = "WriteBoundaryRefused"
	// GitTargetReasonMultipleSourceNamespaces is the terminal reason for a target that declared
	// its folder namespace-free (spec.serializeNamespace: false) and that more than one source
	// namespace reaches. Two namespaces produce documents whose identities are equal once the
	// namespace is stripped, so each write flips one document between two live objects; the writer
	// refuses the flush before any byte is written. The remedy is a GitTarget or WatchRule edit.
	// The string must stay in sync with manifestanalyzer.GitPathRefusalReason.
	GitTargetReasonMultipleSourceNamespaces = "MultipleSourceNamespaces"
	// GitTargetReasonUnrenderedPlacement is the terminal reason for a placement under
	// spec.placement.useKustomize that no kustomization would render: the folder already has a
	// render root and the resolved path is outside it. Nothing is written, because a document in
	// Git that nothing applies looks mirrored and is not. The remedy is the target's own template
	// or path. The string must stay in sync with manifestanalyzer.GitPathRefusalReason.
	GitTargetReasonUnrenderedPlacement    = "UnrenderedPlacement"
	GitTargetReasonRenderDoesNotMatchLive = "RenderDoesNotMatchLive"
	GitTargetReasonRenderRechecking       = "Rechecking"

	GitTargetReadyReasonValidationFailed        = "ValidationFailed"
	GitTargetReadyReasonEncryptionNotConfigured = "EncryptionNotConfigured"
	GitTargetReadyReasonWorkerUnavailable       = "WorkerUnavailable"
	// GitTargetReasonWatchPlanFailing is Ready=False/Reconciling=True while the watch-plane
	// owner's pass for this GitTarget keeps failing and being retried on its backoff ladder. It
	// is deliberately a PROGRESSING reason rather than a stall: a pass fails on a source cluster
	// that is unreachable or a catalog that is not observable yet, both of which recover on their
	// own. What it buys is that such a target does not read as idle.
	GitTargetReasonWatchPlanFailing = "WatchPlanFailing"

	GitTargetStreamsRunningReasonNotReady = "NotReady"

	// GitTargetReasonSuspended is Ready=True on a target whose spec.suspend stops it writing. It
	// is True on purpose: suppressing writes on request is a configured outcome, not ill health.
	GitTargetReasonSuspended = fluxmeta.SuspendedReason
)

const (
	encryptionSecretRecipientAnnoKey   = "configbutler.ai/age-recipient"
	encryptionSecretBackupWarningAnno  = "configbutler.ai/backup-warning"
	encryptionSecretBackupWarningValue = "REMOVE_AFTER_BACKUP"
)

// GitTargetReconciler reconciles a GitTarget object.
type GitTargetReconciler struct {
	client.Client

	Scheme        *runtime.Scheme
	WorkerManager *git.WorkerManager
	EventRouter   *watch.EventRouter

	// GitRefreshInterval is how often an idle branch is asked to re-prove where its remote is,
	// and the quantizer status.remote's clock is written against. Zero or less turns the
	// refresher OFF, which buys back the property that nothing here holds a timer against the
	// Git host; status.remote still works in that mode, because pushes still renew it.
	GitRefreshInterval time.Duration
	// Recorder emits a Kubernetes Event on every persisted Ready transition. It may be nil in
	// tests, in which case no Event is recorded and nothing else changes.
	Recorder record.EventRecorder

	// reconcileRequests remembers which reconcile-request annotation values have been acted on,
	// so a standing annotation forces one re-read rather than one per reconcile forever. Its zero
	// value is usable.
	reconcileRequests reconcileRequestTracker

	// remotePublications is what each GitTarget last wrote to status.remote: when, and about which
	// repository. It is internal by design; see remotePublicationLedger.
	remotePublications remotePublicationLedger

	// clock is the source of "now" for the publication ledger, so a test can hold time still
	// across a reconcile that is measured in wall clock. Nil means time.Now.
	clock func() time.Time
}

// clockNow is the reconciler's wall clock.
func (r *GitTargetReconciler) clockNow() time.Time {
	if r.clock != nil {
		return r.clock()
	}
	return time.Now()
}

// +kubebuilder:rbac:groups=configbutler.ai,resources=gittargets,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=configbutler.ai,resources=gittargets/status,verbs=get;update;patch
// +kubebuilder:rbac:groups=configbutler.ai,resources=gitproviders,verbs=get;list;watch
// +kubebuilder:rbac:groups="",resources=secrets,verbs=get;create;update
// +kubebuilder:rbac:groups="",resources=events,verbs=create;patch

// newGitTargetReadiness starts the accumulator that owns this kind's kstatus trio. Its converged
// outcome is what Ready reports when no gate objected.
func newGitTargetReadiness() *readiness {
	return newReadiness("GitTarget is fully reconciled", "GitTarget is not stalled")
}

// Reconcile validates GitTarget references and drives startup lifecycle gates.
func (r *GitTargetReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
	log := logf.FromContext(ctx).WithName("GitTargetReconciler")

	var target configbutleraiv1alpha3.GitTarget
	if err := r.Get(ctx, req.NamespacedName, &target); err != nil {
		return r.handleFetchError(ctx, err, log, req.NamespacedName)
	}

	st := beginStatus(r.Client, r.Recorder, &target)
	gitPathWasRefused := conditionIsFalse(target.Status.Conditions, GitTargetConditionGitPathAccepted)
	// The branch worker keeps the writes decided while the parent is missing and publishes them when
	// it returns, so nothing has to be re-derived; this only reports the progress.
	recoveringParent := r.parentRecovering(&target, target.Namespace)
	publication := r.branchPublication(&target, target.Namespace)

	providerNS := target.Namespace
	// One read of the GitProvider for everything below it; see getGitProvider.
	gitProvider, providerErr := r.getGitProvider(ctx, providerNS, target.Spec.GitProviderRef.Name)
	if providerErr != nil {
		return ctrl.Result{}, providerErr
	}

	// awaitingAnswer: this reconcile is about to ask the remote where the branch is, so the answer
	// lands after the status write below. See requeueForRemoteAnswer.
	awaitingAnswer := r.publishGitObservations(st, &target, providerNS, repoIdentityOf(gitProvider))

	// Ahead of every gate, for the reason the layout stanza above is: the join series has to carry
	// the targets that are NOT working. git_pushes_total names a branch that stopped advancing and
	// cannot name the GitTargets behind it, and a mapping published only on the happy path would
	// go missing exactly when that question is being asked. It is a statement about configuration,
	// so it holds whether or not a worker ever started. See telemetry/branch_targets.go.
	telemetry.RecordBranchTarget(
		target.Namespace, target.Name, providerNS, target.Spec.GitProviderRef.Name, target.Spec.Branch,
		target.SourceCluster())

	validated, validationMsg, validationErr := r.evaluateValidatedGate(ctx, st, &target, providerNS, gitProvider)
	if validationErr != nil {
		return ctrl.Result{}, validationErr
	}
	if !validated {
		// A remote-source GitTarget whose kubeConfig stopped validating (Secret deleted, key gone,
		// or contents now unsafe/unparseable) must have its data plane STOPPED, not merely marked
		// blocked. Otherwise its watches keep mirroring the remote on the cached credential while
		// status claims Validated=False. Forgetting the declaration cancels those watches and
		// releases the source-cluster context; a later recovery re-declares and re-snapshots. A
		// local GitTarget names no source cluster, so its streams are left untouched.
		r.stopSourceClusterMirror(&target)
		st.set(
			GitTargetConditionEncryptionConfigured,
			metav1.ConditionUnknown,
			GitTargetReasonBlocked,
			"Blocked by Validated=False",
		)
		return r.stall(ctx, st, blockedGate{
			reason:  GitTargetReadyReasonValidationFailed,
			message: validationMsg,
			blocked: "Blocked by Validated=False",
		})
	}

	encryptionReady, encryptionMessage, encryptionRequeueAfter := r.evaluateEncryptionGate(ctx, st, &target, log)
	if !encryptionReady {
		return r.stall(ctx, st, blockedGate{
			reason:       GitTargetReadyReasonEncryptionNotConfigured,
			message:      encryptionMessage,
			blocked:      "Blocked by EncryptionConfigured=False",
			requeueAfter: encryptionRequeueAfter,
		})
	}

	// Ensure the branch worker exists and register the GitTarget's event stream before declaring
	// streams. The watch data plane can route live events as soon as it reaches Streaming, so the
	// destination worker must already be wired.
	wired, wiringMessage := r.evaluateWorkerWiringGate(ctx, &target, providerNS, repoIdentityOf(gitProvider), log)
	if !wired {
		return r.stall(ctx, st, blockedGate{
			reason:  GitTargetReadyReasonWorkerUnavailable,
			message: wiringMessage,
			blocked: "Blocked by worker wiring failure",
		})
	}

	// The refresher's trigger is this reconcile, which is already a scheduled tick looking for a
	// job: a converged GitTarget requeues on RequeueSteadyInterval and those passes publish
	// status without touching Git. Nothing new schedules anything, and the request is ENQUEUED
	// rather than run here — the reconcile must not block on a network round trip, and the work
	// belongs on the one goroutine allowed to touch the repository.
	r.requestRemoteRefresh(&target, providerNS)

	// One read of the source ClusterProvider serves everything below it: the audit route captured on
	// Declare and the ClusterProviderReady projection. Reading it twice invited the two to disagree.
	sourceProvider, sourceProviderErr := r.resolveSourceClusterProvider(ctx, &target)
	if sourceProviderErr != nil {
		return ctrl.Result{}, sourceProviderErr
	}

	// A standing reconcile request forces the same re-check a refused Git path does: the watch
	// plane re-anchors the target's streams, which is what makes it re-read the folder rather than
	// wait for the periodic pass. Taken once per distinct annotation value.
	forceRecheck := gitPathWasRefused || r.reconcileRequests.take(
		types.NewResourceReference(target.Name, target.Namespace), reconcileRequestedAt(&target))
	observed := r.observeDataPlane(&target, sourceProvider, forceRecheck, log)
	st.setValue(GitTargetConditionStreamsRunning, observed.axes.Streams)
	st.setValue(GitTargetConditionGitPathAccepted, observed.axes.GitPath)
	st.setValue(GitTargetConditionRenderMatchesLive, observed.axes.Render)

	refs := r.publishReferenceReadiness(st, &target, providerNS, gitProvider, sourceProvider)

	rd := newGitTargetReadiness()
	convergeAsSuspended(rd, &target)
	gitTargetReadinessGates(rd, observed, r.parentBranchReadiness(&target, providerNS, repoIdentityOf(gitProvider)),
		refs.gitProvider, refs.clusterProvider, refs.sourceCluster, publicationCondition(publication))
	parentRecoveryReadiness(rd, recoveringParent)
	st.applyReadiness(rd)

	if err := st.commit(ctx); err != nil {
		return ctrl.Result{}, err
	}
	// requeueAfter shortens the cadence when the status write lost a race: the object then holds
	// the WINNER's older answer and nothing re-enqueues it, because the For() predicate filters
	// status-only updates by design.
	requeue := st.requeueAfter(requeueForRemoteAnswer(gitTargetRequeue(rd), awaitingAnswer))
	// TEMPORARY at Info, while Failure A is open. The data plane can converge and this status not
	// follow it: a run has shown the render gate reaching True and both this GitTarget and every
	// WatchRule on it still publishing "Rechecking" two minutes later, with no dropped reconcile
	// request to explain it. This is the only place that publishes the axis, so it is the only
	// place that can say what it published and how long it intends to wait before saying anything
	// again.
	log.Info("GitTarget status published",
		"writeLost", st.writeLost(),
		"gitTarget", target.Namespace+"/"+target.Name,
		"render", string(observed.axes.Render.Status)+"/"+observed.axes.Render.Reason,
		"streams", observed.streams.Summary(),
		"converged", rd.converged(),
		"requeueAfter", requeue.String())
	return ctrl.Result{RequeueAfter: requeue}, nil
}

// convergeAsSuspended gives a suspended GitTarget the converged outcome, under its own reason.
//
// A suspended target is healthy, not faulty: not writing is the configured outcome, and no
// condition may go False for one — that is what trains operators to ignore the conditions that
// mean the mirror is genuinely broken. status.retention is the precedent. So Ready stays True and
// only its reason changes, which is what makes the state legible without making it look like a
// fault. Every real gate still applies afterwards: a suspended target with a broken provider is
// still not Ready.
func convergeAsSuspended(rd *readiness, target *configbutleraiv1alpha3.GitTarget) {
	if !target.Spec.Suspend {
		return
	}
	rd.convergesAs(conditionValue{
		Status:  metav1.ConditionTrue,
		Reason:  GitTargetReasonSuspended,
		Message: "GitTarget is suspended: it scans and publishes what it resolved, and writes nothing",
	})
}

// gitTargetRequeue picks the periodic cadence. Only a converged GitTarget earns the steady interval.
//
// A STALLED target gets the fast loop too, which is deliberate and specific to this kind: its
// terminal states clear when the Git FOLDER changes (someone removes the unsupported file, someone
// fixes the diverged value), and that produces no Kubernetes event at all. The data-plane
// acceptance channel is best-effort, so the periodic re-check is what actually recovers a refused
// target. It is cheap now that a re-check which finds nothing new writes nothing.
func gitTargetRequeue(rd *readiness) time.Duration {
	if rd.converged() {
		return RequeueSteadyInterval
	}
	return RequeueStreamSettleInterval
}

// blockedGate describes a control-plane gate that failed before the data plane could be evaluated.
type blockedGate struct {
	// reason and message are the terminal outcome published on the trio.
	reason, message string
	// blocked explains, on each data-plane condition, why it was not evaluated at all.
	blocked string
	// requeueAfter overrides the steady cadence this gate would otherwise get. Zero means take it.
	requeueAfter time.Duration
}

// stall publishes a terminal control-plane outcome and ends the reconcile.
//
// The three early-return gates used to repeat this block verbatim: mark the data plane
// not-evaluated, stamp the trio, write status with retry, choose a requeue. They differ only in the
// values blockedGate carries.
func (r *GitTargetReconciler) stall(
	ctx context.Context,
	st *reconcileStatus,
	gate blockedGate,
) (ctrl.Result, error) {
	st.set(GitTargetConditionStreamsRunning, metav1.ConditionUnknown,
		GitTargetStreamsRunningReasonNotReady, gate.blocked+"; streams not evaluated")
	st.set(GitTargetConditionRenderMatchesLive, metav1.ConditionUnknown,
		GitTargetReasonRenderRechecking, gate.blocked+"; render fidelity not evaluated")
	st.set(GitTargetConditionGitPathAccepted, metav1.ConditionUnknown,
		GitTargetReasonNotChecked, gate.blocked)

	rd := newGitTargetReadiness()
	rd.stalled(gate.reason, gate.message)
	st.applyReadiness(rd)

	if err := st.commit(ctx); err != nil {
		return ctrl.Result{}, err
	}
	// Through st.requeueAfter, exactly like the converged path below: a stalled reconcile whose
	// status write lost the race has published nothing, so leaving it on the gate's own cadence
	// strands the object on the previous answer for five minutes. This path returned gate.result
	// directly and was the one place that skipped the check.
	cadence := gate.requeueAfter
	if cadence == 0 {
		cadence = RequeueSteadyInterval
	}
	return ctrl.Result{RequeueAfter: st.requeueAfter(cadence)}, nil
}

// observeSourceReachable projects the source cluster's runtime reachability.
//
// A GitTarget with no source cluster mirrors the cluster the operator runs in, which is reachable
// by definition — so the default (used when no watch manager is wired, e.g. in tests) is
// True/LocalCluster for a local target and Unknown only for a remote one.
func (r *GitTargetReconciler) observeSourceReachable(
	target *configbutleraiv1alpha3.GitTarget,
) conditionValue {
	reach := watch.SourceClusterReachableStatus{State: "True", Reason: "LocalCluster"}
	if !target.IsLocalSource() {
		reach = watch.SourceClusterReachableStatus{State: "Unknown", Reason: "AwaitingDiscovery"}
	}
	if r.EventRouter != nil && r.EventRouter.WatchManager != nil {
		reach = r.EventRouter.WatchManager.SourceClusterReachable(target.SourceCluster())
	}
	return conditionValue{
		Status:  conditionStatusFromString(reach.State),
		Reason:  reach.Reason,
		Message: reach.Message,
	}
}

func (r *GitTargetReconciler) evaluateValidatedGate(
	ctx context.Context,
	st *reconcileStatus,
	target *configbutleraiv1alpha3.GitTarget,
	providerNS string,
	provider *configbutleraiv1alpha3.GitProvider,
) (bool, string, error) {
	validated, message, reason := validateProviderAndBranch(target, providerNS, provider)
	if !validated {
		st.set(GitTargetConditionValidated, metav1.ConditionFalse, reason, message)
		return false, fmt.Sprintf("Validated gate failed: %s", reason), nil
	}

	conflict, conflictMsg, conflictReason, conflictErr := r.checkForConflicts(ctx, target, providerNS)
	if conflictErr != nil {
		return false, "", conflictErr
	}
	if conflict {
		st.set(GitTargetConditionValidated, metav1.ConditionFalse, conflictReason, conflictMsg)
		return false, fmt.Sprintf("Validated gate failed: %s", conflictReason), nil
	}

	if placementOK, placementMsg := validatePlacementPolicy(target.Spec.Placement); !placementOK {
		st.set(GitTargetConditionValidated,
			metav1.ConditionFalse,
			GitTargetReasonInvalidConfig,
			placementMsg,
		)
		return false, fmt.Sprintf("Validated gate failed: %s", GitTargetReasonInvalidConfig), nil
	}

	if commitOK, commitMsg := validateCommitConfig(target); !commitOK {
		st.set(GitTargetConditionValidated,
			metav1.ConditionFalse,
			GitTargetReasonInvalidConfig,
			commitMsg,
		)
		return false, fmt.Sprintf("Validated gate failed: %s", GitTargetReasonInvalidConfig), nil
	}

	// The source cluster's connectivity inputs (kubeConfig) are validated on the referenced
	// ClusterProvider now, not here — the GitTarget only NAMES its source cluster. The
	// ClusterProvider's readiness is projected onto the GitTarget as a separate condition.

	// Namespace authorization: a GitTarget may reference a ClusterProvider only from a namespace
	// its spec.accessFrom admits. Enforced HERE and only here, on every reconcile — which
	// also covers a policy tightened after the GitTarget was created. Failing this gate returns
	// before DeclareForGitTarget below, so an unauthorized target starts no watch and writes no Git.
	authorized, authReason, authMsg, authErr := r.checkSourceAuthorization(ctx, target)
	if authErr != nil {
		return false, "", authErr
	}
	if !authorized {
		st.set(GitTargetConditionValidated, metav1.ConditionFalse, authReason, authMsg)
		return false, fmt.Sprintf("Validated gate failed: %s", authReason), nil
	}

	st.set(GitTargetConditionValidated,
		metav1.ConditionTrue,
		GitTargetReasonOK,
		"Provider, branch, placement and commit validation passed",
	)
	return true, "", nil
}

func (r *GitTargetReconciler) evaluateEncryptionGate(
	ctx context.Context,
	st *reconcileStatus,
	target *configbutleraiv1alpha3.GitTarget,
	log logr.Logger,
) (bool, string, time.Duration) {
	if !isTargetAgeEncryptionEnabled(target) {
		st.set(GitTargetConditionEncryptionConfigured,
			metav1.ConditionTrue,
			GitTargetReasonNotRequired,
			"SOPS age encryption is not enabled for this GitTarget",
		)
		return true, "", 0
	}

	if err := r.ensureEncryptionSecret(ctx, target, log); err != nil {
		reason := GitTargetReasonInvalidConfig
		if strings.Contains(err.Error(), "missing and generateWhenMissing is disabled") {
			reason = GitTargetReasonSecretCreateDisabled
		}
		if strings.Contains(err.Error(), "failed to fetch encryption secret") {
			reason = GitTargetReasonMissingSecret
		}
		st.set(GitTargetConditionEncryptionConfigured, metav1.ConditionFalse, reason, err.Error())
		return false, fmt.Sprintf("EncryptionConfigured gate failed: %s", reason), RequeueSteadyInterval
	}
	if _, err := git.ResolveTargetEncryption(ctx, r.Client, target); err != nil {
		reason := GitTargetReasonInvalidConfig
		if strings.Contains(err.Error(), "failed to fetch encryption secret") {
			reason = GitTargetReasonMissingSecret
		}
		st.set(GitTargetConditionEncryptionConfigured, metav1.ConditionFalse, reason, err.Error())
		return false, fmt.Sprintf("EncryptionConfigured gate failed: %s", reason), RequeueSteadyInterval
	}

	st.set(GitTargetConditionEncryptionConfigured,
		metav1.ConditionTrue,
		GitTargetReasonOK,
		"Encryption configuration is valid",
	)
	return true, "", 0
}

// evaluateWorkerWiringGate ensures the GitTarget's branch worker exists and registers its
// GitTargetEventStream, the route live watch events use to reach the branch worker. This is
// internal plumbing rather than a status condition of its own: rare failures fold into Ready
// with reason WorkerUnavailable. A nil EventRouter (test/standalone) is trivially wired.
func (r *GitTargetReconciler) evaluateWorkerWiringGate(
	ctx context.Context,
	target *configbutleraiv1alpha3.GitTarget,
	providerNS string,
	repo git.RepoIdentity,
	log logr.Logger,
) (bool, string) {
	if r.EventRouter == nil {
		return true, ""
	}

	if _, err := r.ensureEventStream(ctx, target, providerNS, repo, log); err != nil {
		return false, fmt.Sprintf("Failed to wire branch worker/event stream for %s/%s: %v",
			target.Namespace, target.Name, err)
	}

	return true, ""
}

// setBlockedDataPlane marks stream readiness as not-yet-evaluated when a control-plane gate
// blocked the reconcile before watches could be declared.
// stopSourceClusterMirror tears down the data plane of a GitTarget that is no longer Validated, so
// a dead credential — or a source ClusterProvider that was deleted (including the reserved
// "default" for the LOCAL cluster) — can never keep an active mirror running behind a
// Validated=False status. It applies to local AND remote targets: a local target references the
// "default" ClusterProvider, so if that provider is gone the local mirror must stop too, never
// falling back to an implicit in-cluster identity that bypasses the authorization policy. It is
// idempotent across requeues while the target stays blocked; a later recovery re-declares the
// watches and re-snapshots.
func (r *GitTargetReconciler) stopSourceClusterMirror(target *configbutleraiv1alpha3.GitTarget) {
	if r.EventRouter == nil || r.EventRouter.WatchManager == nil {
		return
	}
	gitDest := types.NewResourceReference(target.Name, target.Namespace)
	r.EventRouter.WatchManager.ForgetGitTargetDeclaration(gitDest)
}

// gitTargetAxes are the three data-plane observations a GitTarget publishes as conditions in their
// own right: what its watch streams are doing, whether its Git folder is safe to materialize, and
// whether what was rendered still matches live.
//
// They are OBSERVATIONS. None of them writes Ready, Reconciling or Stalled — that is
// gitTargetReadinessGates' job, and splitting the two is what stopped a later gate from silently
// overwriting an earlier gate's terminal verdict.
type gitTargetAxes struct {
	Streams conditionValue
	GitPath conditionValue
	Render  conditionValue
}

// dataPlaneObservation is everything one reconcile learned from the watch manager.
type dataPlaneObservation struct {
	axes    gitTargetAxes
	streams watch.StreamSummary
	// declare records whether the watch-plane owner has applied a plan for this GitTarget yet and
	// how its last pass ended, so a target whose passes keep failing reads as failing rather than
	// as an idle one whose axes happen to describe a surface nothing has observed.
	declare watch.DeclareStatus
}

// observeDataPlane declares this GitTarget's streams, reads back what the watch manager knows, and
// projects the three data-plane axes. It mutates only the roll-up fields of status.
func (r *GitTargetReconciler) observeDataPlane(
	target *configbutleraiv1alpha3.GitTarget,
	sourceProvider *configbutleraiv1alpha3.ClusterProvider,
	forceRecheck bool,
	log logr.Logger,
) dataPlaneObservation {
	if r.EventRouter == nil || r.EventRouter.WatchManager == nil {
		// No data plane is wired (tests, standalone). Nothing has been OBSERVED, which is not the
		// same as "observed to be empty": the streams axis stays False and holds the target below
		// Ready, and it says Progressing rather than NoResolvedTypes so the two are never confused.
		streams := noResolvedStreamsSummary()
		target.Status.Streams = streamsStatus(streams)
		return dataPlaneObservation{
			axes: gitTargetAxes{
				Streams: conditionValue{
					Status:  metav1.ConditionFalse,
					Reason:  ReasonProgressing,
					Message: "Data plane is not wired; streams have not been evaluated",
				},
				GitPath: gitPathAxis(watch.GitPathAcceptanceStatus{Accepted: true}),
				Render:  renderAxis(watch.RenderFidelityStatus{State: git.RenderFidelityTrue}),
			},
			streams: streams,
		}
	}

	manager := r.EventRouter.WatchManager
	gitDest := types.NewResourceReference(target.Name, target.Namespace).WithUID(string(target.UID))

	// Submitting the declaration is all this does. The watch-plane owner runs the pass once the
	// target has been quiet for its settle window, so this reconcile has no result to wait for —
	// it reads back the LAST pass's outcome, which is the honest thing to project: the reconcile
	// has never observed its own effect, it previously observed an intermediate state that merely
	// looked more immediate.
	manager.DeclareForGitTarget(
		gitDest,
		target.SourceCluster(),
		sourceProvider.AuditRoute(),
		target.EffectivePruneMode(),
		forceRecheck,
	)

	observation := dataPlaneObservation{declare: manager.DeclareStatusForGitTarget(gitDest)}
	if observation.declare.Failures > 0 {
		log.V(1).Info("the last watch-plan pass for this GitTarget failed; it is dirty and will retry",
			"gitDest", gitDest.String(), "failures", observation.declare.Failures,
			"err", observation.declare.LastError)
	}
	observation.streams = manager.StreamSummaryForGitTarget(gitDest)
	observation.axes = gitTargetAxes{
		Streams: streamsAxis(observation.streams),
		GitPath: gitPathAxis(manager.GitPathAcceptanceForGitTarget(gitDest)),
		Render:  renderAxis(manager.RenderFidelityForGitTarget(gitDest)),
	}

	target.Status.Streams = streamsStatus(observation.streams)
	// Retention is read beside the others and projected the same way, but it feeds NO condition: a
	// document kept by policy is the configured outcome, not a degraded target.
	//
	// A SUSPENDED target publishes none of it. The resync stops before the mark-and-sweep, so
	// nothing is swept and nothing is counted — and a published zero would read as "converged"
	// when it means "not measured". Absent already means "no resync has reported", which is
	// exactly the truth here.
	if target.Spec.Suspend {
		target.Status.Retention = nil
	} else {
		target.Status.Retention = gitTargetRetentionStatus(manager.RetentionForGitTarget(gitDest))
	}
	return observation
}

// streamsAxis renders StreamsRunning.
//
// Zero resolved types reports TRUE — vacuously, and deliberately. It used to report
// False/NoResolvedTypes, which pinned the GitTarget at Reconciling=True with nothing left that
// could ever resolve. That is not an exotic state: it is step 3 of the documented setup flow
// (create the GitTarget, THEN the WatchRules) and the steady state of any target whose rules were
// deleted. kstatus never reached Current, `kubectl wait --for=condition=Ready` never returned, and
// the reconcile burned a pass plus a status write every 10 seconds for the life of the object.
// "I have nothing to mirror" is converged — Flux's Kustomization with an empty path reports the
// same. The count stays visible: status.streams.summary still reads "0/0" and the condition's
// reason is still NoResolvedTypes, so the zero is legible without being reported as a failure.
func streamsAxis(streams watch.StreamSummary) conditionValue {
	status := metav1.ConditionFalse
	if streams.Ready == streams.Total {
		status = metav1.ConditionTrue
	}
	return conditionValue{Status: status, Reason: streams.Reason, Message: streams.Message}
}

// gitPathAxis renders GitPathAccepted from the data plane's write-plan verdict.
func gitPathAxis(gitPath watch.GitPathAcceptanceStatus) conditionValue {
	if gitPath.Accepted {
		message := gitPath.Message
		if message == "" {
			message = "GitTarget path accepted"
		}
		return conditionValue{
			Status:  metav1.ConditionTrue,
			Reason:  ReasonSucceeded,
			Message: message,
		}
	}

	value := conditionValue{Status: metav1.ConditionFalse, Reason: gitPath.Reason, Message: gitPath.Message}
	if value.Reason == "" {
		value.Reason = GitTargetReasonUnsupportedContent
	}
	if value.Message == "" {
		value.Message = "GitTarget path refused"
	}
	return value
}

// renderAxis renders RenderMatchesLive. A divergence is terminal; an incomplete epoch is progress.
func renderAxis(renderFidelity watch.RenderFidelityStatus) conditionValue {
	value := conditionValue{
		Status:  metav1.ConditionTrue,
		Reason:  ReasonSucceeded,
		Message: "Every rendered token matches live",
	}
	switch renderFidelity.State {
	case git.RenderFidelityFalse:
		value = conditionValue{
			Status:  metav1.ConditionFalse,
			Reason:  GitTargetReasonRenderDoesNotMatchLive,
			Message: renderFidelity.Message,
		}
	case git.RenderFidelityUnknown:
		value = conditionValue{
			Status:  metav1.ConditionUnknown,
			Reason:  GitTargetReasonRenderRechecking,
			Message: renderFidelity.Message,
		}
	case git.RenderFidelityTrue:
	}
	if renderFidelity.Reason != "" {
		value.Reason = renderFidelity.Reason
	}
	if value.Message == "" {
		value.Message = "Waiting for render-vs-live verification"
	}
	return value
}

// referenceReadiness is what the three objects a GitTarget REFERENCES say about themselves:
// destination-side (the GitProvider), source-config side (the ClusterProvider), and the runtime
// reachability of the source cluster.
type referenceReadiness struct {
	gitProvider     conditionValue
	clusterProvider conditionValue
	sourceCluster   conditionValue
}

// publishReferenceReadiness writes those three as conditions of their own and returns them, so the
// readiness trio can also take them into account. Publishing is all this does: nothing here
// writes Ready.
func (r *GitTargetReconciler) publishReferenceReadiness(
	st *reconcileStatus,
	target *configbutleraiv1alpha3.GitTarget,
	providerNS string,
	gitProvider *configbutleraiv1alpha3.GitProvider,
	sourceProvider *configbutleraiv1alpha3.ClusterProvider,
) referenceReadiness {
	refs := referenceReadiness{
		gitProvider:     gitProviderReadiness(target, providerNS, gitProvider),
		clusterProvider: clusterProviderReadiness(sourceProvider),
		sourceCluster:   r.observeSourceReachable(target),
	}
	st.setValue(GitTargetConditionSourceClusterReachable, refs.sourceCluster)
	st.setValue(GitTargetConditionGitProviderReady, refs.gitProvider)
	st.setValue(GitTargetConditionClusterProviderReady, refs.clusterProvider)
	return refs
}

// gitTargetReadinessGates contributes every GitTarget gate to the accumulator that owns the trio.
//
// THIS FUNCTION IS THE PRECEDENCE. Read it top to bottom: a stall always beats a progressing gate
// whatever the order, and within each group the first contributor wins, so the order of these calls
// is the order in which competing explanations are preferred. Adding a gate means adding a line
// here, in the position where its answer should outrank the ones below it — not calling a setter
// from wherever the gate happens to be evaluated.
func gitTargetReadinessGates(
	rd *readiness,
	observed dataPlaneObservation,
	parent, provider, clusterProvider, sourceReach, publication conditionValue,
) {
	// Terminal, most specific first. Each of these needs a human: the folder holds content the
	// operator will not manage, the write branch has no parent to be created from, a watch is
	// refused, or what was written no longer matches live.
	rd.stalledIf(observed.axes.GitPath.Status == metav1.ConditionFalse,
		observed.axes.GitPath.Reason, observed.axes.GitPath.Message)
	rd.stalledIf(parent.Status == metav1.ConditionFalse, parent.Reason, parent.Message)
	rd.stalledIf(observed.streams.Blocked > 0, observed.streams.Reason, observed.streams.Message)
	rd.stalledIf(observed.axes.Render.Status == metav1.ConditionFalse,
		observed.axes.Render.Reason, observed.axes.Render.Message)

	// Transient. Each of these clears on its own and each has a Watches() edge that re-runs this
	// reconcile when it does, so they are progress, never a stall. Dependencies before this
	// object's own data plane: "your GitProvider is down" is a more actionable answer than
	// "streams are still replaying", and it is usually the cause of the latter.
	rd.progressingIf(provider.Status == metav1.ConditionFalse, metav1.ConditionFalse,
		provider.Reason, provider.Message)
	rd.progressingIf(clusterProvider.Status == metav1.ConditionFalse, metav1.ConditionFalse,
		clusterProvider.Reason, clusterProvider.Message)
	rd.progressingIf(sourceReach.Status == metav1.ConditionFalse, metav1.ConditionFalse,
		sourceReach.Reason, sourceReach.Message)
	// An unconfirmed source has not been established at all, so Ready is Unknown rather than False.
	rd.progressingIf(sourceReach.Status == metav1.ConditionUnknown, metav1.ConditionUnknown,
		sourceReach.Reason, sourceReach.Message)
	// The branch cannot publish. Ahead of this target's own data plane, because it explains it: a
	// branch that paused intake keeps its streams waiting, and they say only that they wait.
	rd.progressingIf(publication.Status == metav1.ConditionFalse, metav1.ConditionFalse,
		publication.Reason, publication.Message)
	rd.progressingIf(observed.axes.Render.Status == metav1.ConditionUnknown, metav1.ConditionFalse,
		observed.axes.Render.Reason, observed.axes.Render.Message)
	rd.progressingIf(observed.axes.Streams.Status != metav1.ConditionTrue, metav1.ConditionFalse,
		observed.axes.Streams.Reason, observed.axes.Streams.Message)
	// Last: the declaration has not landed, so every axis above describes a surface that has not
	// been observed under the current configuration. Nothing else objected, but this target is not
	// converged either. A pass that keeps FAILING says so — and says why — instead of reading as a
	// target that is merely still settling, which is the difference between a mirror that is
	// converging and one whose source cluster has been unreachable for an hour.
	rd.progressingIf(observed.declare.Failures > 0, metav1.ConditionFalse,
		GitTargetReasonWatchPlanFailing,
		fmt.Sprintf("The watch plan for this GitTarget has failed %d time(s) and is being retried: %s",
			observed.declare.Failures, observed.declare.LastError))
	rd.progressingIf(observed.declare.Pending && observed.declare.Failures == 0,
		metav1.ConditionFalse, ReasonProgressing,
		"Stream declaration has not landed yet; the data-plane surface is not observable")
}

// parentBranchReadiness reports whether the write branch can be created: False when the last
// look at the remote found neither the write branch nor the parent it would be created from. That
// parent is the configured spec.parentBranch, or, when it is omitted, the remote's default branch:
// a repository that is not empty but whose HEAD names no branch it carries refuses as well, because
// starting there would make an orphan.
//
// It is read from the branch worker's remote observation, so it costs no round trip and holds
// with periodic refresh disabled: every fetch on the write path records the same observation. The
// observation counts only when it was made under the parent configured now, and only for the
// repository the GitProvider names now (a repoint proves nothing about the new one).
func (r *GitTargetReconciler) parentBranchReadiness(
	target *configbutleraiv1alpha3.GitTarget,
	providerNS string,
	repo git.RepoIdentity,
) conditionValue {
	ok := conditionValue{Status: metav1.ConditionTrue, Reason: GitTargetReasonOK}
	observed, seen := r.observeRemote(target, providerNS)
	if !seen || observed.ParentState != git.ParentMissing ||
		observed.ParentRequested != target.Spec.ParentBranch || differentRepository(observed.Repo, repo) {
		return ok
	}
	return conditionValue{
		Status:  metav1.ConditionFalse,
		Reason:  GitTargetReasonParentBranchNotFound,
		Message: parentBranchNotFoundMessage(target, observed.ParentBranch),
	}
}

// parentBranchNotFoundMessage says which parent is missing and what fixes it.
func parentBranchNotFoundMessage(target *configbutleraiv1alpha3.GitTarget, missing string) string {
	switch {
	case target.Spec.ParentBranch != "":
		return fmt.Sprintf(
			"Branch '%s' does not exist on the remote, and neither does its parent branch '%s' to create "+
				"it from; nothing is written until one of them exists",
			target.Spec.Branch, target.Spec.ParentBranch)
	case missing != "":
		return fmt.Sprintf(
			"Branch '%s' does not exist on the remote, and the remote's default branch (HEAD -> '%s') does "+
				"not exist either; fix the remote's HEAD or set spec.parentBranch. Nothing is written until then",
			target.Spec.Branch, missing)
	default:
		return fmt.Sprintf(
			"Branch '%s' does not exist on the remote, and the remote has no default branch to create it "+
				"from; set the remote's HEAD or spec.parentBranch. Nothing is written until then",
			target.Spec.Branch)
	}
}

// requestRemoteRefresh asks this target's branch worker to re-prove where the branch is, if
// nothing has proved it within the interval.
//
// The worker decides whether to spend a connection: the age test is its own, because only it
// knows when it last pushed. A target sharing a branch with a busy one therefore costs nothing
// here and still gets its status renewed, because the worker reports what it knows before it
// skips.
//
// A suspended target refreshes too, for the reason its layout is still scanned: a stopped valve
// that also stopped looking would freeze what an operator reads at whatever Git looked like when
// someone panicked. Refreshing writes nothing, so there is no valve to respect.
func (r *GitTargetReconciler) requestRemoteRefresh(
	target *configbutleraiv1alpha3.GitTarget,
	providerNS string,
) {
	if r.GitRefreshInterval <= 0 || r.WorkerManager == nil {
		return
	}
	worker, exists := r.WorkerManager.GetWorkerForTarget(
		target.Spec.GitProviderRef.Name, providerNS, target.Spec.Branch)
	if !exists || worker == nil {
		// Nothing has been published for this target yet, so there is no checkout to refresh and
		// the first publication reads the remote anyway.
		return
	}
	worker.EnqueueRefresh(&git.RefreshRequest{
		Target: types.NewResourceReference(target.Name, target.Namespace),
		Path:   target.Spec.Path,
		MaxAge: r.GitRefreshInterval,
	})
}

// publishGitObservations writes what the data plane last read about this target's folder and
// about its branch on the remote: status.placement with the LayoutResolved condition, and
// status.remote.
//
// It runs ahead of every gate, so a target held unready still shows both. That ordering is the
// point rather than a convenience: these stanzas exist to explain a refused or surprising write,
// and a projection that ran only on the happy path would be missing exactly when it is wanted.

func (r *GitTargetReconciler) publishGitObservations(
	st *reconcileStatus,
	target *configbutleraiv1alpha3.GitTarget,
	providerNS string,
	repo git.RepoIdentity,
) bool {
	layout, scanned := r.observeLayout(target)
	publishLayout(st, target, layout, scanned)

	now := r.clockNow()
	remote, remoteSeen := r.observeRemote(target, providerNS)
	r.publishRemote(st, target, remote, remoteSeen, repo, now)
	// Whether the refresh this reconcile goes on to enqueue will actually reach the remote: the
	// worker spends a connection only when what it holds is older than the interval configured.
	return r.GitRefreshInterval > 0 && (!remoteSeen || remote.Age(now) >= r.GitRefreshInterval)
}

// requeueForRemoteAnswer shortens the cadence for a target that has just ASKED the remote where
// its branch is.
//
// It is the one piece of scheduling this status field gets, and it exists because the refresh is
// enqueued during the reconcile: the worker answers moments later, after the status write, so the
// answer would otherwise sit undelivered until the next steady tick. An idle target would then
// spend a connection every interval and publish what it learned a whole tick late — visible to an
// operator as a target that follows a foreign push ten minutes after noticing it.
//
// Nothing else is threaded anywhere. A reconcile that asked nothing keeps its own cadence, and no
// early return has to carry a deadline.
func requeueForRemoteAnswer(cadence time.Duration, asked bool) time.Duration {
	if asked && RemotePublicationInterval < cadence {
		return RemotePublicationInterval
	}
	return cadence
}

// ensureEventStream wires this GitTarget to the branch worker for the repository its GitProvider
// names NOW, and wires the route live events take to reach it.
//
// EnsureWorker is called on EVERY reconcile rather than only when no worker is in the slot: it is
// the one place that compares the slot's repository against repo, and a lookup that found a worker
// says nothing about WHICH repository that worker is about. It is a map read and a lock when
// nothing has changed.
func (r *GitTargetReconciler) ensureEventStream(
	ctx context.Context,
	target *configbutleraiv1alpha3.GitTarget,
	providerNS string,
	repo git.RepoIdentity,
	log logr.Logger,
) (*reconcile.GitTargetEventStream, error) {
	if r.WorkerManager == nil {
		return nil, errors.New("worker manager is not configured")
	}

	err := r.WorkerManager.EnsureWorker(
		context.Background(),
		target.Spec.GitProviderRef.Name,
		providerNS,
		target.Spec.Branch,
		repo,
		target.Spec.ParentBranch,
	)
	if err != nil {
		return nil, fmt.Errorf(
			"failed to ensure branch worker for provider=%s/%s branch=%s: %w",
			providerNS,
			target.Spec.GitProviderRef.Name,
			target.Spec.Branch,
			err,
		)
	}
	// Asked on EVERY reconcile, not only on the one that did the replacing. The recovery is held
	// by the worker manager until it has been delivered, so a delivery that failed is retried by
	// whichever GitTarget on the branch reconciles next.
	branch := git.BranchKey{
		RepoNamespace: providerNS,
		RepoName:      target.Spec.GitProviderRef.Name,
		Branch:        target.Spec.Branch,
	}
	if r.WorkerManager.ReplacementPending(branch) &&
		r.recoverBranchAfterReplacement(ctx, branch, log) {
		r.WorkerManager.AcknowledgeReplacement(branch)
	}

	worker, ensured := r.WorkerManager.GetWorkerForTarget(
		target.Spec.GitProviderRef.Name,
		providerNS,
		target.Spec.Branch,
	)
	if !ensured {
		return nil, fmt.Errorf(
			"branch worker not found for provider=%s/%s branch=%s",
			providerNS,
			target.Spec.GitProviderRef.Name,
			target.Spec.Branch,
		)
	}

	gitDest := types.NewResourceReference(target.Name, target.Namespace)
	// A stream holds its worker directly, so one registered against a REPLACED worker would keep
	// handing live events to a stopped goroutine's queue — accepted, never written, and silently
	// dropped once it filled. The stream is thin and holds no state of its own, so re-pointing it
	// is a fresh registration.
	if existingStream := r.EventRouter.GetGitTargetEventStream(gitDest); existingStream != nil &&
		existingStream.ServesWorker(worker) {
		return existingStream, nil
	}

	stream := reconcile.NewGitTargetEventStream(target.Name, target.Namespace, worker, log)
	r.EventRouter.RegisterGitTargetEventStream(gitDest, stream)
	return stream, nil
}

// validateProviderAndBranch answers the two questions the GitProvider decides: is there one, and
// does it admit this branch. It takes the provider the reconcile already read rather than reading
// its own, so the branch worker cannot be wired for a different object than the one validated
// here; a nil provider is the not-found case.
func validateProviderAndBranch(
	target *configbutleraiv1alpha3.GitTarget,
	providerNS string,
	gp *configbutleraiv1alpha3.GitProvider,
) (bool, string, string) {
	if gp == nil {
		msg := fmt.Sprintf("Referenced GitProvider '%s/%s' not found", providerNS, target.Spec.GitProviderRef.Name)
		return false, msg, GitTargetReasonProviderNotFound
	}

	branchAllowed := false
	for _, pattern := range gp.Spec.AllowedBranches {
		match, matchErr := filepath.Match(pattern, target.Spec.Branch)
		if matchErr != nil {
			continue
		}
		if match {
			branchAllowed = true
			break
		}
	}
	if !branchAllowed {
		msg := fmt.Sprintf(
			"Branch '%s' does not match any pattern in allowedBranches list %v of GitProvider '%s/%s'",
			target.Spec.Branch,
			gp.Spec.AllowedBranches,
			providerNS,
			target.Spec.GitProviderRef.Name,
		)
		return false, msg, GitTargetReasonBranchNotAllowed
	}

	return true, "", ""
}

// recoverBranchAfterReplacement re-establishes every GitTarget on a branch whose worker was just
// replaced, because the replacement leaves that branch's state describing a repository that is no
// longer the destination.
//
// The new worker starts with no clone, no base trust and an empty queue: whatever the old one held
// was computed against the old repository and is deliberately dropped. Nothing else asks for it
// back. The declaration is level-triggered and its inputs did not change, so the next pass is a
// no-op, the streams keep running, and an IDLE target would leave the new repository empty for as
// long as nothing happened to it. Forcing a recheck re-anchors the streams, and a stream that
// starts replays, which is what drives the mark-and-sweep that rebuilds the folder.
//
// It runs for every target on the branch and not only the one whose reconcile noticed. A worker
// serves them all, and the siblings have no reason of their own to reconcile.
//
// The render-fidelity verdicts go the same way and for the same reason: they say a folder matches
// live, about a folder in the other repository. They are INVALIDATED rather than forgotten —
// forgetting a target leaves it unregistered, which the gate reads as writable, so the writes
// would be admitted against the new repository before anything had looked at it.
//
// It reports whether the recovery was DELIVERED. A list that fails delivers nothing, and the
// request it was serving stays pending on the worker manager for the next reconcile to pick up:
// the alternative, spending the notification on an attempt that reached nobody, left the new
// repository with no target ever asked to populate it.
func (r *GitTargetReconciler) recoverBranchAfterReplacement(
	ctx context.Context,
	branch git.BranchKey,
	log logr.Logger,
) bool {
	if r.EventRouter == nil || r.EventRouter.WatchManager == nil {
		return false
	}
	var targets configbutleraiv1alpha3.GitTargetList
	if err := r.List(ctx, &targets, client.InNamespace(branch.RepoNamespace)); err != nil {
		log.Error(err, "Could not re-establish the branch after its worker was replaced; it stays pending",
			"provider", branch.RepoNamespace+"/"+branch.RepoName, "branch", branch.Branch)
		return false
	}
	gate := r.WorkerManager.RenderFidelityGate()
	recovered := 0
	for i := range targets.Items {
		affected := &targets.Items[i]
		if affected.Spec.GitProviderRef.Name != branch.RepoName || affected.Spec.Branch != branch.Branch {
			continue
		}
		if !affected.DeletionTimestamp.IsZero() {
			continue
		}
		ref := types.NewResourceReference(affected.Name, affected.Namespace).WithUID(string(affected.UID))
		gate.Invalidate(ref)
		r.EventRouter.WatchManager.RequestRecheckForGitTarget(ref)
		recovered++
	}
	log.Info("Branch worker replaced; re-establishing every GitTarget on the branch",
		"provider", branch.RepoNamespace+"/"+branch.RepoName, "branch", branch.Branch, "gitTargets", recovered)
	return true
}

// getGitProvider reads the GitTarget's GitProvider ONCE for the whole reconcile.
//
// That one object answers the Validated gate's questions, projects GitProviderReady, and names the
// repository the branch worker has to be about. Reading it three times let those three disagree
// about which repository this target points at, which is the disagreement the worker's repository
// identity exists to prevent.
//
// A provider that is not there comes back (nil, nil): its absence is a configuration state the
// Validated gate reports as ProviderNotFound, not a reconcile failure to retry with a backoff.
func (r *GitTargetReconciler) getGitProvider(
	ctx context.Context,
	providerNS, providerName string,
) (*configbutleraiv1alpha3.GitProvider, error) {
	var gp configbutleraiv1alpha3.GitProvider
	key := k8stypes.NamespacedName{Name: providerName, Namespace: providerNS}
	if err := r.Get(ctx, key, &gp); err != nil {
		if apierrors.IsNotFound(err) {
			return nil, nil //nolint:nilnil // a GitProvider that is not there is a state, not an error
		}
		return nil, err
	}
	return &gp, nil
}

// repoIdentityOf is which repository a GitProvider names, in the form the data plane keys a branch
// worker by. A provider that could not be read names nothing, and the zero identity says exactly
// that rather than standing in for some repository.
func repoIdentityOf(provider *configbutleraiv1alpha3.GitProvider) git.RepoIdentity {
	if provider == nil {
		return git.RepoIdentity{}
	}
	return git.RepoIdentity{ProviderUID: provider.UID, URL: provider.Spec.URL}
}

func (r *GitTargetReconciler) checkForConflicts(
	ctx context.Context,
	target *configbutleraiv1alpha3.GitTarget,
	providerNS string,
) (bool, string, string, error) {
	var allTargets configbutleraiv1alpha3.GitTargetList
	if err := r.List(ctx, &allTargets); err != nil {
		return false, "", "", fmt.Errorf("list GitTargets for conflict validation: %w", err)
	}

	for i := range allTargets.Items {
		existing := &allTargets.Items[i]
		if existing.Namespace == target.Namespace && existing.Name == target.Name {
			continue
		}
		if existing.Namespace != providerNS || existing.Spec.GitProviderRef.Name != target.Spec.GitProviderRef.Name {
			continue
		}
		if existing.Spec.Branch != target.Spec.Branch {
			continue
		}
		// Checked whatever either path looks like: a target with a path its writer will reject
		// still wires the shared worker, and would set its parent.
		if lost, msg := losesParentBranchConflict(target, existing, providerNS); lost {
			return true, msg, GitTargetReasonTargetConflict, nil
		}
		if existing.Spec.ParentBranch != target.Spec.ParentBranch {
			continue // the other target loses, on its own reconcile
		}
		if lost, msg := losesPathConflict(target, existing, providerNS); lost {
			return true, msg, GitTargetReasonTargetConflict, nil
		}
	}

	return false, "", "", nil
}

// losesPathConflict reports whether target loses to existing, on the same write branch, because
// their paths are equal or nested. Two such targets fight over which documents each one owns. The
// later-created target loses (ties broken deterministically by identity) so every materialized
// folder keeps exactly one owner.
//
// A path the writer would reject (absolute, backslashes, ".." traversal) owns nothing, so it must
// neither block others nor be blocked here — its own write path fails it. Only well-formed paths
// participate in overlap detection.
func losesPathConflict(target, existing *configbutleraiv1alpha3.GitTarget, providerNS string) (bool, string) {
	if !git.IsValidTargetPath(target.Spec.Path) ||
		!git.IsValidTargetPath(existing.Spec.Path) ||
		!gitTargetPathsOverlap(target.Spec.Path, existing.Spec.Path) ||
		!gitTargetLosesConflict(target, existing) {
		return false, ""
	}
	if normalizeGitTargetPath(target.Spec.Path) == normalizeGitTargetPath(existing.Spec.Path) {
		return true, fmt.Sprintf(
			"Conflict detected. Another GitTarget '%s/%s' (created at %s) is already using GitProvider '%s/%s', branch '%s', path '%s'. This GitTarget was created later and will not be processed.",
			existing.Namespace,
			existing.Name,
			existing.CreationTimestamp.Format(time.RFC3339),
			providerNS,
			target.Spec.GitProviderRef.Name,
			target.Spec.Branch,
			target.Spec.Path,
		)
	}
	return true, fmt.Sprintf(
		"Conflict detected. This GitTarget's path '%s' overlaps the path '%s' of GitTarget '%s/%s' (created at %s) on GitProvider '%s/%s', branch '%s' — one path nests inside the other (sibling paths are allowed). This GitTarget was created later and will not be processed.",
		target.Spec.Path,
		existing.Spec.Path,
		existing.Namespace,
		existing.Name,
		existing.CreationTimestamp.Format(time.RFC3339),
		providerNS,
		target.Spec.GitProviderRef.Name,
		target.Spec.Branch,
	)
}

// losesParentBranchConflict reports whether target loses to existing, on the same write branch,
// because the two name different parent branches. One branch worker owns one checkout per write
// branch, so every target on it has to agree on where the branch starts. Compared as written, with
// omitted as its own value: the answer needs no remote round trip and cannot flip when somebody
// changes the remote's default branch.
func losesParentBranchConflict(target, existing *configbutleraiv1alpha3.GitTarget, providerNS string) (bool, string) {
	if existing.Spec.ParentBranch == target.Spec.ParentBranch || !gitTargetLosesConflict(target, existing) {
		return false, ""
	}
	return true, parentBranchConflictMessage(target, existing, providerNS)
}

// parentBranchConflictMessage explains a TargetConflict over spec.parentBranch.
func parentBranchConflictMessage(target, existing *configbutleraiv1alpha3.GitTarget, providerNS string) string {
	return fmt.Sprintf(
		"Conflict detected. GitTarget '%s/%s' (created at %s) writes GitProvider '%s/%s', branch '%s' with parent "+
			"branch %s, and this GitTarget names parent branch %s. All GitTargets on one branch must name the same "+
			"parent branch. This GitTarget was created later and will not be processed.",
		existing.Namespace, existing.Name, existing.CreationTimestamp.Format(time.RFC3339),
		providerNS, target.Spec.GitProviderRef.Name, target.Spec.Branch,
		describeParentBranch(existing.Spec.ParentBranch), describeParentBranch(target.Spec.ParentBranch),
	)
}

func describeParentBranch(name string) string {
	if name == "" {
		return "(omitted: the remote's default branch)"
	}
	return "'" + name + "'"
}

func (r *GitTargetReconciler) ensureEncryptionSecret(
	ctx context.Context,
	target *configbutleraiv1alpha3.GitTarget,
	log logr.Logger,
) error {
	if !shouldGenerateAgeKey(target) {
		return nil
	}

	secretKey, err := secretKeyForGeneratedEncryption(target)
	if err != nil {
		return err
	}

	var existing corev1.Secret
	if err := r.Get(ctx, secretKey, &existing); err != nil {
		if apierrors.IsNotFound(err) {
			return r.createGeneratedEncryptionSecret(ctx, target.Namespace, secretKey, log)
		}
		return fmt.Errorf("failed to fetch encryption secret %s: %w", secretKey.String(), err)
	}

	if hasAgeKeyEntry(existing.Data) {
		logEncryptionBackupWarning(log, secretKey, existing.Annotations)
		return nil
	}

	identity, recipient, err := generateAgeIdentity()
	if err != nil {
		return fmt.Errorf("failed to generate age identity for encryption secret %s: %w", secretKey.String(), err)
	}
	ageKeyDataKey := currentDateAgeKeySecretDataKey()
	ensureAgeSecretDataAndAnnotations(&existing, ageKeyDataKey, identity.String(), recipient)
	if err := r.Update(ctx, &existing); err != nil {
		return fmt.Errorf("failed to update encryption secret %s: %w", secretKey.String(), err)
	}

	log.Info(
		"Added missing .agekey entry to encryption secret. Back up the private key and remove warning annotation.",
		"secret", secretKey.String(),
		"secretDataKey", ageKeyDataKey,
		"recipient", recipient,
		"warningAnnotation", encryptionSecretBackupWarningAnno,
	)
	return nil
}

func (r *GitTargetReconciler) createGeneratedEncryptionSecret(
	ctx context.Context,
	namespace string,
	secretKey k8stypes.NamespacedName,
	log logr.Logger,
) error {
	identity, recipient, err := generateAgeIdentity()
	if err != nil {
		return fmt.Errorf("failed to generate age identity for encryption secret %s: %w", secretKey.String(), err)
	}
	ageKeyDataKey := currentDateAgeKeySecretDataKey()

	secret := corev1.Secret{
		ObjectMeta: metav1.ObjectMeta{
			Name:      secretKey.Name,
			Namespace: namespace,
			Annotations: map[string]string{
				encryptionSecretRecipientAnnoKey:  recipient,
				encryptionSecretBackupWarningAnno: encryptionSecretBackupWarningValue,
			},
		},
		Type: corev1.SecretTypeOpaque,
		StringData: map[string]string{
			ageKeyDataKey: identity.String(),
		},
	}
	if err := r.Create(ctx, &secret); err != nil {
		if apierrors.IsAlreadyExists(err) {
			return nil
		}
		return fmt.Errorf("failed to create encryption secret %s: %w", secretKey.String(), err)
	}

	log.Info(
		"Generated missing encryption secret with age key. Back up the private key and remove warning annotation.",
		"secret", secretKey.String(),
		"secretDataKey", ageKeyDataKey,
		"recipient", recipient,
		"warningAnnotation", encryptionSecretBackupWarningAnno,
	)
	return nil
}

func shouldGenerateAgeKey(target *configbutleraiv1alpha3.GitTarget) bool {
	return isTargetAgeEncryptionEnabled(target) && target.Spec.Encryption.Age.Recipients.GenerateWhenMissing
}

func secretKeyForGeneratedEncryption(target *configbutleraiv1alpha3.GitTarget) (k8stypes.NamespacedName, error) {
	if !target.Spec.Encryption.Age.Recipients.ExtractFromSecret {
		return k8stypes.NamespacedName{},
			errors.New("encryption.age.recipients.generateWhenMissing=true requires extractFromSecret=true")
	}

	secretName := strings.TrimSpace(target.Spec.Encryption.SecretRef.Name)
	if secretName == "" {
		return k8stypes.NamespacedName{}, errors.New(
			"encryption.secretRef.name must be set when encryption is configured",
		)
	}

	return k8stypes.NamespacedName{Name: secretName, Namespace: target.Namespace}, nil
}

func generateAgeIdentity() (*age.X25519Identity, string, error) {
	identity, err := age.GenerateX25519Identity()
	if err != nil {
		return nil, "", err
	}
	return identity, identity.Recipient().String(), nil
}

func ensureAgeSecretDataAndAnnotations(secret *corev1.Secret, ageKeyDataKey, identityValue, recipient string) {
	if secret.Data == nil {
		secret.Data = make(map[string][]byte)
	}
	secret.Data[ageKeyDataKey] = []byte(identityValue)

	if secret.Annotations == nil {
		secret.Annotations = make(map[string]string)
	}
	secret.Annotations[encryptionSecretRecipientAnnoKey] = recipient
	secret.Annotations[encryptionSecretBackupWarningAnno] = encryptionSecretBackupWarningValue
}

func currentDateAgeKeySecretDataKey() string {
	now := time.Now().UTC()
	return fmt.Sprintf("%04d%02d%d.agekey", now.Year(), now.Month(), now.Day())
}

func logEncryptionBackupWarning(log logr.Logger, secretKey k8stypes.NamespacedName, annotations map[string]string) {
	if annotations[encryptionSecretBackupWarningAnno] != encryptionSecretBackupWarningValue {
		return
	}
	log.Info("ENCRYPTION KEY BACKUP REQUIRED: remove annotation after backup is completed",
		"secret", secretKey.String(),
		"annotation", encryptionSecretBackupWarningAnno)
}

func isTargetAgeEncryptionEnabled(target *configbutleraiv1alpha3.GitTarget) bool {
	if target == nil || target.Spec.Encryption == nil {
		return false
	}

	providerName := strings.TrimSpace(target.Spec.Encryption.Provider)
	if providerName == "" {
		providerName = git.EncryptionProviderSOPS
	}
	if providerName != git.EncryptionProviderSOPS {
		return false
	}
	return target.Spec.Encryption.Age != nil && target.Spec.Encryption.Age.Enabled
}

func hasAgeKeyEntry(data map[string][]byte) bool {
	for key := range data {
		if strings.HasSuffix(key, ".agekey") {
			return true
		}
	}
	return false
}

// handleFetchError handles errors from fetching GitTarget.
func (r *GitTargetReconciler) handleFetchError(
	ctx context.Context,
	err error,
	log logr.Logger,
	namespacedName k8stypes.NamespacedName,
) (ctrl.Result, error) {
	if client.IgnoreNotFound(err) == nil {
		cleanupErr := r.cleanupDeletedGitTarget(ctx, namespacedName, log)
		log.Info("GitTarget not found, was likely deleted", "namespacedName", namespacedName)
		// A deleted object still has a reconcile key, so returning the error requeues this same
		// pass with backoff. That matters because the worker sweep is the ONLY thing that retires
		// a worker: if its read of the GitTargets failed, swallowing the error here would leave
		// the worker and its clone standing until another GitTarget somewhere is deleted, which
		// nothing guarantees will ever happen.
		return ctrl.Result{}, cleanupErr
	}
	log.Error(err, "unable to fetch GitTarget", "namespacedName", namespacedName)
	return ctrl.Result{}, err
}

// cleanupDeletedGitTarget releases everything this reconciler and its data plane held for a
// GitTarget that is gone.
//
// Every step is idempotent, and they all run before the error is returned: the in-memory releases
// cannot fail, and the one step that can — the worker sweep, which reads the API — must not stop
// the others from happening. The error it returns is the caller's signal to come back, not a
// report that nothing was cleaned up.
func (r *GitTargetReconciler) cleanupDeletedGitTarget(
	ctx context.Context,
	namespacedName k8stypes.NamespacedName,
	log logr.Logger,
) error {
	gitDest := types.NewResourceReference(namespacedName.Name, namespacedName.Namespace)
	// Unconditionally, and before the EventRouter check below: the tracker is the reconciler's own
	// memory, so it must be released for a deleted target whether or not a data plane is wired. The
	// condition gauge is released on the same terms and for a sharper reason: a condition series
	// that outlives its object reports Ready=False forever and the alert on it never clears.
	r.reconcileRequests.forget(gitDest)
	// Same terms: the publication ledger is this reconciler's memory of what the object's status
	// said, and an entry that outlives the object is a rate limit held against a name that may be
	// recreated tomorrow with nothing published.
	r.remotePublications.forget(gitDest)
	telemetry.ForgetResourceConditions(conditionKindGitTarget, namespacedName.Namespace, namespacedName.Name)
	// Same terms, same reason: a join series that outlives its GitTarget keeps attributing a live
	// branch's push failures to an object that no longer exists.
	telemetry.ForgetBranchTarget(namespacedName.Namespace, namespacedName.Name)

	// The branch worker outlives its GitTarget unless something says otherwise, and this reconcile
	// — the one the delete watch event produced — is the moment the set of needed workers can have
	// shrunk. The sweep decides from the API, so a branch several GitTargets share keeps its worker
	// while any of them is still listed. It runs ahead of the EventRouter check below because it is
	// the WorkerManager's business, not the data plane's.
	var sweepErr error
	if r.WorkerManager != nil {
		if err := r.WorkerManager.ReconcileWorkers(ctx); err != nil {
			log.V(1).Info("Could not sweep branch workers after a GitTarget was deleted",
				"error", err.Error())
			sweepErr = fmt.Errorf("sweep branch workers after %s was deleted: %w",
				namespacedName.String(), err)
		}
	}

	if r.EventRouter == nil {
		return sweepErr
	}

	r.EventRouter.UnregisterGitTargetEventStream(gitDest)

	// Forget the diff-wake's last-Declared cache so a GitTarget recreated with the same name is a
	// fresh claim and re-drives its initial replay (otherwise the recreate inherits the
	// dead one's declaration and never replays).
	if r.EventRouter.WatchManager != nil {
		r.EventRouter.WatchManager.ForgetGitTargetDeclaration(gitDest)
	}

	log.V(1).Info("Cleaned up in-memory state for deleted GitTarget", "gitDest", gitDest.String())
	return sweepErr
}

func clampIntToInt32(value int) int32 {
	if value < 0 {
		return 0
	}
	maxInt32 := int(^uint32(0) >> 1)
	if value > maxInt32 {
		return int32(maxInt32)
	}
	return int32(value)
}

// gitTargetRetentionStatus projects the data-plane retention roll-up.
//
// A summary that has never been reported projects to NIL rather than to a zero count, and the
// distinction is load-bearing: absent means "no resync has reported yet" (the target has not
// replayed, or predates the field), while zero means "a resync ran and found nothing to retain" —
// the converged signal. Collapsing them would make status unable to say a mirror is converged,
// which is half the reason the field exists.
func gitTargetRetentionStatus(summary watch.RetentionSummary) *configbutleraiv1alpha3.GitTargetRetentionStatus {
	if !summary.Reported {
		return nil
	}
	changed := metav1.NewTime(summary.LastChangedAt)
	return &configbutleraiv1alpha3.GitTargetRetentionStatus{
		Mode:              summary.Mode,
		RetainedDocuments: clampIntToInt32(summary.RetainedDocuments),
		LastChangedAt:     &changed,
	}
}

// SetupWithManager sets up the controller with the Manager.
func (r *GitTargetReconciler) SetupWithManager(mgr ctrl.Manager) error {
	b := ctrl.NewControllerManagedBy(mgr).
		// A For() predicate is not an optimisation here, it closes a self-triggering edge: a status
		// write bumps resourceVersion and fires an Update watch event that EnqueueRequestForObject
		// turns straight back into a queued request, un-rate-limited. reconcileStatus.commit()
		// already suppresses no-op writes, so the loop has no fuel; this makes it structural, and
		// matches what GitProvider and ClusterProvider already do.
		// It additionally admits a change to the reconcile-request annotation, which does not bump
		// metadata.generation and would otherwise be filtered out along with the status writes.
		For(&configbutleraiv1alpha3.GitTarget{}, builder.WithPredicates(reconcileRequestedOrSpecChanged())).
		// No control-plane Secret watch. Reacting to age-key Secret changes with a
		// full-object Secret watch made the process retain every Secret value in the
		// cluster. Generated-age-Secret recovery and out-of-band age-key updates are
		// picked up by the periodic reconcile (RequeueSteadyInterval) instead.
		// See docs/rbac.md.
		// GenerationChangedPredicate keeps this watch reacting to a freshly
		// applied or spec-changed GitProvider while ignoring the status-only
		// updates the controllers write themselves — without it every provider
		// heartbeat would re-list and re-enqueue all dependent GitTargets.
		Watches(
			&configbutleraiv1alpha3.GitProvider{},
			handler.EnqueueRequestsFromMapFunc(r.gitProviderToGitTargets),
			builder.WithPredicates(predicate.GenerationChangedPredicate{}),
		).
		// React to the referenced (cluster-scoped) ClusterProvider becoming Ready/NotReady so the
		// projected ClusterProviderReady condition and the namespace-authorization refusal re-run
		// promptly instead of waiting for the periodic reconcile. A plain GenerationChangedPredicate
		// would miss a Ready flip (a STATUS-only update), so this fires on spec changes OR a change
		// in the provider's Ready condition status (plus create/delete).
		Watches(
			&configbutleraiv1alpha3.ClusterProvider{},
			handler.EnqueueRequestsFromMapFunc(r.clusterProviderToGitTargets),
			builder.WithPredicates(clusterProviderReadyOrSpecChanged()),
		).
		// React to a Namespace's LABELS changing: a ClusterProvider's accessFrom selector is
		// evaluated against namespace labels, so a label change can grant or revoke a GitTarget's
		// authorization. Re-enqueue the GitTargets in that namespace so the reconcile-time refusal
		// converges instead of waiting for the periodic reconcile. LabelChangedPredicate ignores the
		// unrelated namespace churn (annotations, status).
		Watches(
			&corev1.Namespace{},
			handler.EnqueueRequestsFromMapFunc(r.namespaceToGitTargets),
			builder.WithPredicates(predicate.LabelChangedPredicate{}),
		).
		// React to a GitTarget's WatchRule/ClusterWatchRule set changing so it re-reconciles and
		// re-Declares its watched-type set promptly (the replacement for the deleted whole-target
		// rule-change resync). Without this a rule added after the GitTarget went Ready would not be
		// claimed — and so never materialised/mirrored — until the next ~10m periodic reconcile.
		// GenerationChangedPredicate ignores the status-only updates the rule controllers write.
		Watches(
			&configbutleraiv1alpha3.WatchRule{},
			handler.EnqueueRequestsFromMapFunc(r.watchRuleToGitTarget),
			builder.WithPredicates(predicate.GenerationChangedPredicate{}),
		).
		Watches(
			&configbutleraiv1alpha3.ClusterWatchRule{},
			handler.EnqueueRequestsFromMapFunc(r.clusterWatchRuleToGitTarget),
			builder.WithPredicates(predicate.GenerationChangedPredicate{}),
		).
		Named("gittarget")

	// React to a change of the branch worker's publication report (an outage starting, intake
	// pausing, a push landing), so the status says so within one reconcile instead of at the next
	// steady requeue.
	if r.WorkerManager != nil && r.WorkerManager.PublicationEvents() != nil {
		b = b.WatchesRawSource(source.Channel(
			r.WorkerManager.PublicationEvents(),
			&handler.EnqueueRequestForObject{},
		))
	}

	// React to a data-plane GitPath acceptance TRANSITION (refused/recovered) so GitPathAccepted
	// is re-projected within one reconcile instead of lagging up to RequeueSteadyInterval (5m).
	// The watch manager records acceptance asynchronously and pushes a GenericEvent here. See
	// docs/spec/manifest-system.md.
	if r.EventRouter != nil && r.EventRouter.WatchManager != nil {
		b = b.WatchesRawSource(source.Channel(
			r.EventRouter.WatchManager.GitPathEvents(),
			&handler.EnqueueRequestForObject{},
		))
		// Stream readiness arrives on its OWN channel, not the one above. Both sends are
		// best-effort and a full buffer drops the ARRIVING event, so sharing one would let
		// high-volume stream transitions crowd out an acceptance or retention transition — the
		// expensive event arrives to find the buffer full. Losing one of those leaves
		// status describing a sweep that already happened until the 5m steady requeue, where a
		// lost stream event costs 10s. See Manager.enqueueStreamStateChange.
		b = b.WatchesRawSource(source.Channel(
			r.EventRouter.WatchManager.StreamStateEvents(),
			&handler.EnqueueRequestForObject{},
		))
	}

	return b.Complete(r)
}

// watchRuleToGitTarget enqueues the GitTarget a WatchRule targets (a WatchRule targets a GitTarget
// in its own namespace), so the GitTarget re-Declares its watched-type set when a rule changes.
func (r *GitTargetReconciler) watchRuleToGitTarget(_ context.Context, obj client.Object) []ctrlreconcile.Request {
	wr, ok := obj.(*configbutleraiv1alpha3.WatchRule)
	if !ok || wr.Spec.GitTargetRef.Name == "" {
		return nil
	}
	return []ctrlreconcile.Request{{NamespacedName: k8stypes.NamespacedName{
		Name: wr.Spec.GitTargetRef.Name, Namespace: wr.Namespace,
	}}}
}

// clusterWatchRuleToGitTarget enqueues the GitTarget a ClusterWatchRule targets (its GitTargetRef
// carries the namespace), for the same reason as watchRuleToGitTarget.
func (r *GitTargetReconciler) clusterWatchRuleToGitTarget(
	_ context.Context, obj client.Object,
) []ctrlreconcile.Request {
	cwr, ok := obj.(*configbutleraiv1alpha3.ClusterWatchRule)
	if !ok || cwr.Spec.GitTargetRef.Name == "" {
		return nil
	}
	return []ctrlreconcile.Request{{NamespacedName: k8stypes.NamespacedName{
		Name: cwr.Spec.GitTargetRef.Name, Namespace: cwr.Spec.GitTargetRef.Namespace,
	}}}
}

// gitProviderToGitTargets maps a GitProvider event to every GitTarget in the
// same namespace that references it, so a freshly-arrived provider re-enqueues
// any dependents currently stuck on ProviderNotFound instead of waiting for the
// periodic RequeueSteadyInterval.
func (r *GitTargetReconciler) gitProviderToGitTargets(
	ctx context.Context,
	obj client.Object,
) []ctrlreconcile.Request {
	var targets configbutleraiv1alpha3.GitTargetList
	if err := r.List(ctx, &targets, client.InNamespace(obj.GetNamespace())); err != nil {
		logDependencyListError(ctx, err, "GitTargets", obj)
		return nil
	}

	var requests []ctrlreconcile.Request
	for i := range targets.Items {
		t := &targets.Items[i]
		if t.Spec.GitProviderRef.Name != obj.GetName() {
			continue
		}
		requests = append(requests, ctrlreconcile.Request{
			NamespacedName: k8stypes.NamespacedName{Name: t.Name, Namespace: t.Namespace},
		})
	}
	return requests
}

// clusterProviderToGitTargets maps a ClusterProvider event to every GitTarget that references it,
// across ALL namespaces (the provider is cluster-scoped). It re-enqueues dependents when the
// provider's Ready flips or its accessFrom policy changes, so the projected
// ClusterProviderReady and the namespace-authorization refusal converge without waiting for the
// periodic reconcile.
func (r *GitTargetReconciler) clusterProviderToGitTargets(
	ctx context.Context,
	obj client.Object,
) []ctrlreconcile.Request {
	var targets configbutleraiv1alpha3.GitTargetList
	if err := r.List(ctx, &targets); err != nil {
		logDependencyListError(ctx, err, "GitTargets", obj)
		return nil
	}

	var requests []ctrlreconcile.Request
	for i := range targets.Items {
		t := &targets.Items[i]
		if t.SourceCluster() != obj.GetName() {
			continue
		}
		requests = append(requests, ctrlreconcile.Request{
			NamespacedName: k8stypes.NamespacedName{Name: t.Name, Namespace: t.Namespace},
		})
	}
	return requests
}

// namespaceToGitTargets maps a Namespace label change to every GitTarget in that namespace, so the
// reconcile-time ClusterProvider authorization (which may match the namespace's labels via a
// selector) re-runs and grants/revokes the target promptly.
func (r *GitTargetReconciler) namespaceToGitTargets(
	ctx context.Context,
	obj client.Object,
) []ctrlreconcile.Request {
	var targets configbutleraiv1alpha3.GitTargetList
	if err := r.List(ctx, &targets, client.InNamespace(obj.GetName())); err != nil {
		logDependencyListError(ctx, err, "GitTargets", obj)
		return nil
	}
	requests := make([]ctrlreconcile.Request, 0, len(targets.Items))
	for i := range targets.Items {
		t := &targets.Items[i]
		requests = append(requests, ctrlreconcile.Request{
			NamespacedName: k8stypes.NamespacedName{Name: t.Name, Namespace: t.Namespace},
		})
	}
	return requests
}

// clusterProviderReadyStatus returns a ClusterProvider's Ready condition status ("" if absent), so
// a watch predicate can react to a Ready FLIP that arrives as a status-only update.
func clusterProviderReadyStatus(cp *configbutleraiv1alpha3.ClusterProvider) metav1.ConditionStatus {
	if c := findCondition(cp.Status.Conditions, ConditionTypeReady); c != nil {
		return c.Status
	}
	return ""
}

// clusterProviderReadyOrSpecChanged is the ClusterProvider watch predicate for the GitTarget
// controller: fire on create/delete, and on an update when the SPEC changed (generation) OR the
// Ready condition status changed — the latter a status-only update GenerationChangedPredicate drops.
func clusterProviderReadyOrSpecChanged() predicate.Predicate {
	return predicate.Funcs{
		CreateFunc:  func(event.CreateEvent) bool { return true },
		DeleteFunc:  func(event.DeleteEvent) bool { return true },
		GenericFunc: func(event.GenericEvent) bool { return false },
		UpdateFunc: func(e event.UpdateEvent) bool {
			oldCP, ok1 := e.ObjectOld.(*configbutleraiv1alpha3.ClusterProvider)
			newCP, ok2 := e.ObjectNew.(*configbutleraiv1alpha3.ClusterProvider)
			if !ok1 || !ok2 {
				return true
			}
			return oldCP.Generation != newCP.Generation ||
				clusterProviderReadyStatus(oldCP) != clusterProviderReadyStatus(newCP)
		},
	}
}