v1alpha3

type AgeEncryptionSpec struct {
	// Enabled toggles age-based recipient resolution and bootstrap behavior.
	// +optional
	// +kubebuilder:default=false
	Enabled bool `json:"enabled,omitempty"`

	// Recipients defines how recipients are resolved.
	// +optional
	Recipients AgeRecipientsSpec `json:"recipients,omitempty"`
}

type AgeRecipientsSpec struct {
	// PublicKeys is a static list of age recipients (age1...).
	// +optional
	// +kubebuilder:validation:items:MinLength=1
	PublicKeys []string `json:"publicKeys,omitempty"`

	// ExtractFromSecret derives recipients from all *.agekey entries in encryption.secretRef.
	// +optional
	// +kubebuilder:default=false
	ExtractFromSecret bool `json:"extractFromSecret,omitempty"`

	// GenerateWhenMissing creates a date-named *.agekey entry in encryption.secretRef when no *.agekey exists.
	// +optional
	// +kubebuilder:default=false
	GenerateWhenMissing bool `json:"generateWhenMissing,omitempty"`
}

type ClusterProvider struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is a standard object metadata.
	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty,omitzero"`

	// spec defines the desired state of ClusterProvider.
	// +required
	Spec ClusterProviderSpec `json:"spec"`

	// status defines the observed state of ClusterProvider.
	// +optional
	Status ClusterProviderStatus `json:"status,omitempty,omitzero"`
}

type ClusterProviderAttribution struct {
	// AuditRoute is the route this cluster's audit events arrive on. The sender is the API server's
	// webhook backend (https://kubernetes.io/docs/tasks/debug/debug-cluster/audit/#webhook-backend),
	// and this is the <name> segment its configured URL ends in: /audit-webhook/<name>. When several
	// logical clusters share one backend it is instead the value of the audit-event annotation named
	// by --author-attribution-audit-route-annotation-key.
	//
	// It partitions the attribution facts, so two ClusterProviders carrying the same route read one
	// cluster's facts, and two carrying different routes can never cross-credit an author.
	//
	// Empty means metadata.name. Set it when several ClusterProviders name one cluster, since an API
	// server has one webhook backend and so posts under one route: every other provider for that
	// cluster must be pointed at the same route or it resolves no authors at all. Set it also when
	// the events are labelled for something other than this object, such as a kcp logical cluster.
	// +optional
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$`
	AuditRoute string `json:"auditRoute,omitempty"`
}

type ClusterProviderList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`

	Items []ClusterProvider `json:"items"`
}

type ClusterProviderSpec struct {
	// KubeConfig names the SOURCE CLUSTER this provider represents and the credentials to reach it
	// (Flux's meta.KubeConfigReference, embedded verbatim). OMITTED means the operator's own
	// in-cluster cluster, for any provider name. IMMUTABLE.
	//
	// The referenced Secret is resolved from the operator's namespace, so a cluster's credential
	// never has to live on that cluster. Only secretRef is honored; configMapRef is rejected. When
	// secretRef.key is empty the resolver reads "value" then "value.yaml" (Flux's order). Unsafe
	// kubeconfigs (exec auth, insecure-skip-tls-verify) are rejected with Validated=False unless the
	// operator opts in via flags.
	// +optional
	KubeConfig *meta.KubeConfigReference `json:"kubeConfig,omitempty"`

	// AccessFrom is the deny-by-default policy for which CONTROL-CLUSTER namespaces may reference
	// this provider from a GitTarget. Empty (or omitted) means no namespace may reference it. Its
	// selector matches labels on Namespaces in the control cluster (the cluster the operator's own
	// CRs live in), never on the source cluster this provider names.
	// +optional
	AccessFrom *NamespaceMatcher `json:"accessFrom,omitempty"`

	// AllowAnySourceNamespace delegates SOURCE-namespace selection to the GitTargets this provider
	// admits. While false (the default) a WatchRule mirroring through this provider may watch only
	// its OWN namespace.
	//
	// It grants no access by itself: the source credential's own RBAC remains the hard maximum, and
	// a request it permits still fails 403 if the credential cannot read that namespace. What it
	// delegates is the AUTHORITY to choose, so set it only when the owners of admitted GitTargets
	// are trusted to pick a subset of what that credential may read. Every cross-namespace request
	// needs it, including a rules[].sourceNamespace of "*", which reaches every namespace the
	// credential can read. It does not apply to ClusterWatchRule, which selects no namespaces at
	// all.
	// +optional
	// +kubebuilder:default=false
	AllowAnySourceNamespace bool `json:"allowAnySourceNamespace,omitempty"`

	// QPS overrides the operator's outgoing kube-client query-per-second throttle for this
	// cluster's watches and discovery. Omitted, the operator-wide --source-cluster-qps applies.
	// Ignored when kubeConfig is omitted (the in-cluster client is not per-provider).
	// +optional
	// +kubebuilder:validation:Minimum=1
	QPS *int32 `json:"qps,omitempty"`

	// Burst overrides the operator's outgoing kube-client burst for this cluster. Omitted, the
	// operator-wide --source-cluster-burst applies. Ignored when kubeConfig is omitted.
	// +optional
	// +kubebuilder:validation:Minimum=1
	Burst *int32 `json:"burst,omitempty"`

	// Attribution groups this cluster's author-attribution settings. The block is spelled
	// "attribution" rather than "authorAttribution" even though the operator flags are
	// --author-attribution-*: the prefix groups a flat flag namespace, and a block on a
	// source-cluster object already supplies that scope.
	// +optional
	Attribution *ClusterProviderAttribution `json:"attribution,omitempty"`
}

type ClusterProviderStatus struct {
	// ObservedGeneration is the latest generation observed by the controller.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions report the provider's readiness: Validated (kubeconfig inputs are safe and
	// resolvable, asserted without a network dial) plus the aggregated Ready and the kstatus
	// Reconciling/Stalled pair. Runtime reachability/discovery health and a last-audit-event
	// timestamp are deferred until authenticated remote ingest wires them from the watch engine.
	// +optional
	// +listType=map
	// +listMapKey=type
	// +patchMergeKey=type
	// +patchStrategy=merge
	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type"`
}

type ClusterResourceRule struct {
	// Operations to watch. If empty, watches all operations (CREATE, UPDATE, DELETE).
	// Supports: CREATE, UPDATE, DELETE, or * (wildcard for all operations).
	// Examples:
	//   - ["CREATE", "UPDATE"] watches only creation and updates
	//   - ["*"] or [] watches all operations
	// +optional
	Operations []OperationType `json:"operations,omitempty"`

	// APIGroups to match. Empty string ("") matches the core API group.
	// If omitted, GitOps Reverser resolves the resource name across all served API groups.
	// Wildcards supported: "*" matches all groups.
	// Examples:
	//   - [""] matches core API (nodes, namespaces)
	//   - ["rbac.authorization.k8s.io"] matches RBAC resources
	//   - ["*"] matches all groups
	//   - [] resolves a named resource only when it is served by one API group
	// +optional
	APIGroups []string `json:"apiGroups,omitempty"`

	// APIVersions to match. If empty, uses the preferred served version for each group/resource.
	// Wildcards supported: "*" matches all versions.
	// Examples:
	//   - ["v1"] matches only v1 version
	//   - ["*"] matches all served versions
	//   - [] matches the preferred served version
	// +optional
	APIVersions []string `json:"apiVersions,omitempty"`

	// Resources to match (plural names like "nodes", "clusterroles").
	// This field is required and determines which resource types trigger this rule.
	// Wildcard semantics follow Kubernetes admission webhook patterns:
	//   - "*" matches all resources
	//   - "nodes" matches exactly nodes
	//   - "pods" matches exactly pods (for namespaced scope)
	//
	// Note: Subresources cannot be added here. Values containing "/" (for example
	// "pods/log" or "pods/*") are rejected by the API because subresources are
	// not supported for list/watch snapshot planning. Prefix/suffix wildcards
	// like "pod*" or "*.example.com" are NOT supported. Use exact matches or the
	// "*" wildcard for broad matching.
	// +required
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:items:MinLength=1
	// +kubebuilder:validation:items:Pattern=`^[^/]*$`
	Resources []string `json:"resources"`
}

type ClusterWatchRule struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is a standard object metadata.
	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty,omitzero"`

	// spec defines the desired state of ClusterWatchRule.
	// +required
	Spec ClusterWatchRuleSpec `json:"spec"`

	// status defines the observed state of ClusterWatchRule.
	// +optional
	Status ClusterWatchRuleStatus `json:"status,omitempty"`
}

type ClusterWatchRuleList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`

	Items []ClusterWatchRule `json:"items"`
}

type ClusterWatchRuleSpec struct {
	// GitTargetRef names the GitTarget this rule feeds. A ClusterWatchRule has no namespace of its
	// own, so the namespace is required here rather than defaulted.
	// +required
	// +kubebuilder:validation:XValidation:rule="self.name != ”",message="spec.gitTargetRef.name must not be empty"
	// +kubebuilder:validation:XValidation:rule="has(self.namespace) && self.namespace != ”",message="spec.gitTargetRef.namespace is required: a ClusterWatchRule has no namespace to default to"
	GitTargetRef meta.NamespacedObjectReference `json:"gitTargetRef"`

	// Rules define which CLUSTER-SCOPED resources to watch.
	// Multiple rules create a logical OR - a resource matching ANY rule is watched.
	// A rule that resolves to no cluster-scoped type simply watches nothing; use a WatchRule with
	// spec.rules[].sourceNamespace for namespaced resources.
	// +required
	// +kubebuilder:validation:MinItems=1
	Rules []ClusterResourceRule `json:"rules"`
}

type ClusterWatchRuleStatus struct {
	// ObservedGeneration is the latest generation observed by the controller.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions represent the latest available observations of the ClusterWatchRule's state.
	// +optional
	// +listType=map
	// +listMapKey=type
	// +patchMergeKey=type
	// +patchStrategy=merge
	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type"`

	// Streams is the bounded stream-readiness roll-up for the types this rule resolves.
	// +optional
	Streams *WatchRuleStreamsStatus `json:"streams,omitempty"`
}

type CommitMessageSpec struct {
	// EventTemplate is a Go text/template string for per-event commit messages
	// (used when spec.commit.window is "0s"; one event per commit).
	// Available variables: Operation, Group, Version, Resource, Namespace, Name,
	// APIVersion, Username, GitTarget.
	// +optional
	EventTemplate string `json:"eventTemplate,omitempty"`

	// ReconcileTemplate is a Go text/template string for reconcile commit messages
	// (the mark-and-sweep reconcile path; one commit per synced type).
	// Available variables: Count, GitTarget, Group, Version, Resource, APIVersion, Revision.
	// Group/Version/Resource/APIVersion name the synced type for a per-type reconcile and
	// Revision is the cluster resourceVersion the reconcile was pinned to; both are empty
	// for a whole-target reconcile or a pure sweep, so a template referencing them must
	// render cleanly when they are absent (the default guards them with {{if}}).
	// +optional
	ReconcileTemplate string `json:"reconcileTemplate,omitempty"`

	// GroupTemplate is a Go text/template string for grouped commit messages
	// (the commit-window path; one commit per (author, gitTarget) group
	// produced by the batching pipeline).
	// Available variables: Author, GitTarget, Count, Operations (map of
	// CREATE/UPDATE/DELETE counts), Resources (slice of {Group, Version,
	// Resource, Namespace, Name}).
	// +optional
	GroupTemplate string `json:"groupTemplate,omitempty"`
}

type CommitRequest struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty,omitzero"`

	// spec defines the desired state of CommitRequest
	// +required
	Spec CommitRequestSpec `json:"spec"`

	// status defines the observed state of CommitRequest
	// +optional
	Status CommitRequestStatus `json:"status,omitempty,omitzero"`
}

type CommitRequestList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`

	Items []CommitRequest `json:"items"`
}

type CommitRequestSpec struct {
	// GitTargetRef names the GitTarget whose open commit window to finalize.
	// The GitTarget must be in the same namespace as this CommitRequest.
	// +required
	// +kubebuilder:validation:XValidation:rule="self.name != ”",message="spec.gitTargetRef.name must not be empty"
	GitTargetRef meta.LocalObjectReference `json:"gitTargetRef"`

	// Message is an optional commit message for the finalized commit. When
	// omitted, the generated grouped-commit message is used.
	//
	// When present it is limited to 1-1024 Unicode characters and used
	// verbatim as the commit message. Newlines are allowed so a subject and
	// body can be supplied; all other ASCII control characters (including tab
	// and carriage return) are rejected.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=1024
	// +kubebuilder:validation:Pattern=`^[^\x00-\x09\x0B-\x1F\x7F]*$`
	Message string `json:"message,omitempty"`

	// CloseDelaySeconds optionally delays closing the open commit window for this
	// many seconds after the CommitRequest attaches to a matching open window, acting as
	// an extra collect window: matching changes that arrive in the meantime still join
	// that window and are included in the resulting commit. Omitted or 0 closes the
	// window as soon as the CommitRequest attaches. The window can still be closed
	// earlier by another author's change or by the provider's commit window timer,
	// exactly as without a CommitRequest.
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=300
	CloseDelaySeconds int32 `json:"closeDelaySeconds,omitempty"`
}

type CommitRequestStatus struct {
	// ObservedGeneration is the most recent generation observed by the controller.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions report the request's progress and terminal outcome: the Ready
	// summary, the kstatus Reconciling/Stalled pair, and the domain conditions
	// AuthorAttributed and Pushed.
	// +optional
	// +listType=map
	// +listMapKey=type
	// +patchStrategy=merge
	// +patchMergeKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type"`

	// Branch is the Git branch the GitTarget commits to. Populated once the
	// finalize resolves.
	// +optional
	Branch string `json:"branch,omitempty"`

	// SHA is the resulting commit SHA. Set when the commit was pushed (Pushed=True).
	// +optional
	SHA string `json:"sha,omitempty"`
}

type CommitSigningSpec struct {
	// SecretRef references the Secret containing the signing key material.
	// +kubebuilder:validation:XValidation:rule="self.name != ”",message="commit.signing.secretRef.name must not be empty"
	// Expected keys will be defined by the signing implementation.
	SecretRef meta.LocalObjectReference `json:"secretRef"`

	// GenerateWhenMissing causes the operator to generate signing key material
	// in the referenced Secret when it is missing.
	// +optional
	// +kubebuilder:default=false
	GenerateWhenMissing bool `json:"generateWhenMissing,omitempty"`
}

type CommitSpec struct {
	// Committer configures the operator identity written as the commit committer.
	// When signing is enabled, Email must be a verified address on the account
	// that owns the signing key.
	// +optional
	Committer *CommitterSpec `json:"committer,omitempty"`

	// Signing configures commit signing.
	// +optional
	Signing *CommitSigningSpec `json:"signing,omitempty"`
}

type CommitterSpec struct {
	// Name is the git committer name.
	// +optional
	// +kubebuilder:default="GitOps Reverser"
	Name string `json:"name,omitempty"`

	// Email is the git committer email.
	// +optional
	// +kubebuilder:default="noreply@configbutler.ai"
	Email string `json:"email,omitempty"`
}

type EncryptionSpec struct {
	// Provider selects the encryption provider.
	// +kubebuilder:default=sops
	// +kubebuilder:validation:Enum=sops
	Provider string `json:"provider"`

	// SecretRef references namespace-local Secret data used by the encryption provider.
	// +kubebuilder:validation:XValidation:rule="self.name != ”",message="encryption.secretRef.name must not be empty"
	// +optional
	SecretRef meta.LocalObjectReference `json:"secretRef,omitempty"`

	// Age configures age-specific encryption behavior for SOPS.
	// +optional
	Age *AgeEncryptionSpec `json:"age,omitempty"`
}

type GitProvider struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty,omitzero"`

	// spec defines the desired state of GitProvider
	// +required
	Spec GitProviderSpec `json:"spec"`

	// status defines the observed state of GitProvider
	// +optional
	Status GitProviderStatus `json:"status,omitempty,omitzero"`
}

type GitProviderList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`

	Items []GitProvider `json:"items"`
}

type GitProviderSpec struct {
	// URL of the repository (HTTP/SSH).
	// Immutable: delete and recreate the GitProvider to point at a different repository.
	// +kubebuilder:validation:MinLength=1
	URL string `json:"url"`

	// SecretRef for authentication credentials (may be nil for public repos)
	//
	// An OMITTED secretRef means anonymous access. An empty name is refused rather than treated as
	// one: a typo there would otherwise downgrade a private repository to anonymous silently, and
	// the failure would surface as an authentication error against the remote rather than as a
	// mistake in this object.
	// +optional
	// +kubebuilder:validation:XValidation:rule="self.name != ”",message="spec.secretRef.name must not be empty; omit secretRef entirely for anonymous access"
	SecretRef *meta.LocalObjectReference `json:"secretRef,omitempty"`

	// KnownHostsRef optionally points at a namespace-local ConfigMap or Secret holding SSH
	// known_hosts, so host trust can be centralized across GitProviders on the same host instead
	// of repeated in every credentials Secret. It is used only for SSH and ignored for HTTP auth.
	// Host keys are resolved in priority order: the credentials Secret's own known_hosts, then this
	// ref, then the install-level default known-hosts ConfigMap; if none yields valid keys, SSH
	// fails closed.
	// +optional
	KnownHostsRef *KnownHostsReference `json:"knownHostsRef,omitempty"`

	// AllowedBranches restricts which branches can be written to.
	// +required
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:items:MinLength=1
	AllowedBranches []string `json:"allowedBranches"`

	// Commit configures the commit identity and signing behavior this connection uses. Message
	// formatting moved to GitTarget.spec.commit.message.
	// +optional
	Commit *CommitSpec `json:"commit,omitempty"`
}

type GitProviderStatus struct {
	// ObservedGeneration is the latest generation observed by the controller.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions report repository validation and commit configuration readiness:
	// the Ready summary plus the kstatus Reconciling/Stalled pair.
	// +optional
	// +listType=map
	// +listMapKey=type
	// +patchMergeKey=type
	// +patchStrategy=merge
	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type"`

	// SigningPublicKey is the operator's SSH signing public key in authorized_keys format.
	// Register this as a signing key on your git platform.
	// Only populated when commit.signing is configured and a signing key is available.
	// +optional
	SigningPublicKey string `json:"signingPublicKey,omitempty"`
}

type GitTarget struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty,omitzero"`

	// spec defines the desired state of GitTarget
	// +required
	Spec GitTargetSpec `json:"spec"`

	// status defines the observed state of GitTarget
	// +optional
	Status GitTargetStatus `json:"status,omitempty,omitzero"`
}

type GitTargetCommitSpec struct {

	// Window is the rolling silence window used to coalesce this target's events into a single
	// commit per author. The timer resets on every event arrival, and the commit is made after
	// this much silence. "0s" opts into per-event commits. Omitted, it is "5s".
	// +optional
	Window *string `json:"window,omitempty"`

	// Message configures how this target's commit messages are formatted. Omitted, or with any
	// individual template left empty, the built-in templates are used.
	// +optional
	Message *CommitMessageSpec `json:"message,omitempty"`
}

type GitTargetList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`

	Items []GitTarget `json:"items"`
}

type GitTargetPlacementSpec struct {
	// ByType maps an exact resource type key ("{group}/{version}/{resource}", e.g.
	// "v1/configmaps", "apps/v1/deployments", or "v1/secrets"; core resources omit
	// the group) to the path template used for a new resource of that type. A path
	// selected for a sensitive resource (Secrets, plus any operator-configured
	// sensitive type) must be identity-complete so it cannot collide two distinct
	// sensitive resources onto one file.
	// +optional
	ByType map[string]string `json:"byType,omitempty"`

	// Default is the path template used for a new resource whose type has no ByType
	// entry. Omitted, it falls through to the folder's one supported kustomization
	// root, if it has exactly one, and then to the built-in canonical path.
	// A bundling default (one that is not identity-complete,
	// such as "all.yaml") is only valid when a sensitive resource can never reach it
	// — give every sensitive type an explicit identity-complete ByType entry.
	// +optional
	Default string `json:"default,omitempty"`

	// UseKustomize declares that this folder is a kustomize folder whose root the operator
	// maintains. It controls one thing: what happens when NO kustomization governs the path a new
	// document lands at.
	//
	// Omitted or false, the document is written and nothing else is touched. True, a
	// kustomization.yaml is created at spec.path and the new document is registered in it as part
	// of the same commit.
	//
	// A created root ADOPTS the folder: its resources: lists every managed document already there
	// as well as the new one. Turning a folder into a kustomize folder means the folder, and a
	// root naming one file would leave every other file in Git but out of every render.
	//
	// A created root carries NO namespace:. It holds an apiVersion, a kind and the resources: list
	// and nothing else, so the namespace still comes from the documents (serializeNamespace unset
	// or true) or from whatever installs the folder (serializeNamespace false).
	//
	// A folder that already has a kustomize render root never gains a second one, because two
	// render roots is an ambiguous folder that stops accepting new documents altogether. If a
	// byType or default template places a document outside the existing root, that placement is
	// REFUSED rather than committed as a file no kustomization would render.
	//
	// It has NO bearing on a folder that already has a root. A new file is always registered with
	// the nearest kustomization governing it, whatever chose its path, because a file no
	// kustomization lists is a file kustomize never builds.
	// +optional
	UseKustomize bool `json:"useKustomize,omitempty"`
}

type GitTargetPlacementStatus struct {
	// Mode is how this folder is written, and it is the field that predicts the surprises.
	//
	// `Plain` — no kustomization governs the folder. A new document is written and nothing else
	// is touched; a delete removes it and nothing else is touched.
	//
	// `KustomizeRoot` — exactly one kustomization governs the folder and the folder is
	// self-contained. A new document is also registered in that root's `resources:`; a delete
	// also drops its entry; and every write is proved by re-rendering, so kustomize itself can
	// refuse one.
	//
	// `KustomizeOverlay` — as KustomizeRoot, and the folder additionally renders a base outside
	// it (ReadOnlyBases). The base is read-only input: an edit to a field the base owns is
	// authored into the overlay when it is expressible there (`images:`, `replicas:`) and refused
	// with WriteBoundaryRefused otherwise, and DELETING an object the overlay inherits authors a
	// `$patch: delete` into the overlay rather than removing anything.
	//
	// Empty when the folder covers more than one render root, which is LayoutResolved=Ambiguous:
	// there is no single answer, and no new document is placed until the target is pointed at one
	// of them.
	// +optional
	// +kubebuilder:validation:Enum=Plain;KustomizeRoot;KustomizeOverlay
	Mode PlacementMode `json:"mode,omitempty"`

	// RenderRoot is the kustomization directory that governs new documents in this folder,
	// relative to spec.path; "." is the folder itself. Empty for Plain (there is no root) and
	// under LayoutResolved=Ambiguous (there is no single one).
	// +optional
	RenderRoot string `json:"renderRoot,omitempty"`

	// ReadOnlyBases are the kustomization directories this folder renders but may never write to,
	// relative to spec.path — so they lead with "../". Non-empty exactly when Mode is
	// KustomizeOverlay, and it is what makes a WriteBoundaryRefused message predictable instead of
	// surprising: an edit that lands on a document under one of these paths cannot be written
	// where it lives.
	// +optional
	ReadOnlyBases []string `json:"readOnlyBases,omitempty"`

	// ResolvedAtRevision is the Git revision this resolution was first observed at. It is not
	// re-stamped on every scan: a resolution that has not changed is not republished, because
	// doing so would write status once per commit to the branch, whichever target caused the
	// commit. So it dates the RESOLUTION, not the last scan — a revision older than the branch
	// head means the folder's layout has not changed since, not that nothing has looked.
	//
	// It is empty when the branch had no commit at the time (a folder nothing has written to yet)
	// and is filled in by the first scan that finds one.
	// +optional
	ResolvedAtRevision string `json:"resolvedAtRevision,omitempty"`

	// ResolvedAt is when this resolution was computed. Like ResolvedAtRevision it dates the
	// resolution rather than the last scan, so a timestamp well in the past means the folder's
	// shape has been stable, not that scanning stopped.
	// +optional
	ResolvedAt *metav1.Time `json:"resolvedAt,omitempty"`
}

type GitTargetRetentionStatus struct {
	// Mode is the EFFECTIVE spec.prune.mode this roll-up was produced under. It is reported here
	// rather than left to be read from the spec because a GitTarget that predates spec.prune has
	// no stored value at all, so the spec alone cannot explain why documents are being kept.
	// +optional
	Mode PruneMode `json:"mode,omitempty"`

	// RetainedDocuments is how many managed documents the policy kept that a converged mirror
	// would not hold. Zero means a resync ran and found nothing to retain — the mirror is
	// converged. An ABSENT retention block means something different: no resync has reported yet.
	RetainedDocuments int32 `json:"retainedDocuments"`

	// ObservedTime is when this roll-up was last computed. A retention that begins just after a
	// reconcile is not visible until the next one, so read this before treating a zero as live.
	// +optional
	ObservedTime *metav1.Time `json:"observedTime,omitempty"`
}

type GitTargetSpec struct {
	// GitProviderRef names the GitProvider that backs this target, in this GitTarget's own
	// namespace. Many GitTargets may name the same GitProvider.
	// Immutable: delete and recreate the GitTarget to change its destination.
	// +required
	// +kubebuilder:validation:XValidation:rule="self.name != ”",message="spec.gitProviderRef.name must not be empty"
	GitProviderRef meta.LocalObjectReference `json:"gitProviderRef"`

	// Branch to use for this target.
	// Must be one of the allowed branches in the provider.
	// Immutable: delete and recreate the GitTarget to change its destination.
	// +required
	// +kubebuilder:validation:MinLength=1
	Branch string `json:"branch"`

	// Path within the repository to write resources to, relative to the repository
	// root. Required and must be non-empty — there is no default, so a GitTarget can
	// never silently write to the repository root. To deliberately target the
	// repository root, set it to "." (the ArgoCD/Flux convention); an empty string is
	// rejected because it is too easy to leave blank by accident to be a deliberate
	// root choice. Any leading slash (absolute path) and ".." are rejected, and a
	// trailing slash is normalized away.
	// Immutable: delete and recreate the GitTarget to change its destination.
	// +required
	// +kubebuilder:validation:MinLength=1
	Path string `json:"path"`

	// Encryption defines encryption settings for Secret resource writes.
	// +optional
	Encryption *EncryptionSpec `json:"encryption,omitempty"`

	// Placement declares where NEW resources are written. It has no effect on a
	// resource that already has a document in Git — that document is always
	// updated in place at its existing location, wherever that is. Mutable: a
	// change only affects resources created after the change.
	// +optional
	Placement *GitTargetPlacementSpec `json:"placement,omitempty"`

	// SerializeNamespace declares whether a committed document carries its own
	// metadata.namespace. It governs every write this target makes, not just the first one, and it
	// applies to NAMESPACED resources only — a cluster-scoped document has no namespace, so the
	// field is ignored for it rather than being an error.
	//
	// Omitted, the namespace is INFERRED per document, which is the behavior a target that says
	// nothing has always had: metadata.namespace is omitted only when the kustomization governing
	// the document's path sets namespace: to that resource's own namespace, and written explicitly
	// in every other case. Leave it unset for a folder that is legitimately non-uniform — a tree of
	// nested kustomize roots, each supplying its own namespace — because inference resolves each
	// document against the root governing its own path.
	//
	// true always writes it: the setting for a flat folder applied directly, where nothing
	// downstream supplies a namespace and a document without one is ambiguous.
	//
	// false never writes it, and is a claim about the whole folder: something outside this
	// repository — a Flux Kustomization's targetNamespace, an Argo Application's
	// destination.namespace, or a kustomization this target maintains itself — supplies the
	// namespace instead. Because a namespace-less document takes its namespace from a single
	// supplier, an explicit false admits exactly ONE source namespace: a second WatchRule bringing
	// another namespace to this target is refused, with GitPathAccepted=False and reason
	// MultipleSourceNamespaces.
	// +optional
	SerializeNamespace *bool `json:"serializeNamespace,omitempty"`

	// ClusterProviderRef names the SOURCE cluster this GitTarget mirrors FROM, by referencing a
	// cluster-scoped ClusterProvider by name. That ClusterProvider owns the cluster's connectivity
	// credential, namespace-access authorization, and author-attribution mode. The default provider
	// name is "default" and must exist; it may be in-cluster or remote.
	// Immutable: a folder's source cluster is part of what the folder means; delete and recreate.
	// +kubebuilder:default={name: "default"}
	// +optional
	// +kubebuilder:validation:XValidation:rule="self.name != ”",message="spec.clusterProviderRef.name must not be empty"
	ClusterProviderRef *meta.LocalObjectReference `json:"clusterProviderRef,omitempty"`

	// Prune controls which deletion paths may remove documents from this target's folder: an
	// explicit source DELETE event, and the resync mark-and-sweep that infers a deletion from a
	// desired snapshot. Omitted, it is `mode: OnEvent` — observed deletes are mirrored, inferred
	// ones are not — for a stored GitTarget as well as a new one.
	// +optional
	Prune *PrunePolicy `json:"prune,omitempty"`

	// Commit configures how this target's writes are batched into commits, and how those commits
	// are phrased. Omitted, writes coalesce over a 5s rolling silence window and use the built-in
	// message templates.
	// +optional
	Commit *GitTargetCommitSpec `json:"commit,omitempty"`

	// Suspend stops this target from writing to Git, without deleting it. It is the knob to turn
	// when something is wrong and the writes have to stop now: watches keep running, events keep
	// arriving, the folder keeps being scanned and status.placement keeps being maintained, and no
	// new commit is planned while it is set.
	//
	// It takes effect at the next planning boundary, not instantly. Work already committed
	// locally when suspend is set is still pushed, so a target suspended during a push cooldown
	// can publish one more commit seconds later. That is deliberate: a local commit that is never
	// pushed would sit in the worker's checkout indefinitely and surface later, out of order, on
	// resume. Suspend is a valve on new work, not an undo — it stops the next write, it does not
	// revert the last one.
	//
	// While it is set, status.retention is not published at all: nothing is swept, so nothing is
	// measured, and reporting zero retained documents would read as "converged" when nothing was
	// counted.
	//
	// Omitted, it is false. Clearing it resumes writing from the current cluster state on the next
	// resync; the writes suppressed while suspended are not replayed.
	// +optional
	Suspend bool `json:"suspend,omitempty"`
}

type GitTargetStatus struct {
	// ObservedGeneration is the latest generation observed by the controller.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions represent the latest available observations of an object's state
	// +optional
	// +listType=map
	// +listMapKey=type
	// +patchMergeKey=type
	// +patchStrategy=merge
	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type"`

	// LastPushTime is the timestamp of the last successful push.
	// +optional
	LastPushTime *metav1.Time `json:"lastPushTime,omitempty"`

	// Streams is the bounded data-plane roll-up over this GitTarget's tracked types.
	// Counts, never a per-type list, so it stays bounded however many types are watched.
	// +optional
	Streams *GitTargetStreamsStatus `json:"streams,omitempty"`

	// Retention reports documents a resync kept because this target's spec.prune.mode suppressed
	// the mark-and-sweep. It covers the INFERRED deletion path only: under `never`, a suppressed
	// source DELETE is not counted here, so a `never` target can report zero while still declining
	// to mirror deletes. It is informational either way — retention is the configured behavior,
	// never a fault, and no condition changes state because of it.
	// +optional
	Retention *GitTargetRetentionStatus `json:"retention,omitempty"`

	// Placement is what the last scan resolved about this folder's layout: whether a kustomize
	// render root governs new documents, which one, and whether the folder renders a base it may
	// not write to. It is an observation, like streams and retention, and the LayoutResolved
	// condition carries the verdict.
	// +optional
	Placement *GitTargetPlacementStatus `json:"placement,omitempty"`
}

type GitTargetStreamsStatus struct {
	// Summary is the display-only ready/total ratio, e.g. "3/4".
	//
	// It restates Ready and Total, which the API conventions would normally rule out. It exists
	// solely to feed the Streams printer column: a column can read one JSONPath, not format two.
	// Do not compute anything from it — read ready and total.
	// +optional
	Summary string `json:"summary,omitempty"`

	// Total is how many types this target tracks.
	Total int32 `json:"total"`

	// Ready is how many tracked types are Streaming.
	Ready int32 `json:"ready"`

	// Replaying is how many tracked types are still replaying their initial events.
	Replaying int32 `json:"replaying"`

	// Blocked is how many tracked types cannot currently be watched.
	Blocked int32 `json:"blocked"`
}

type KnownHostsReference struct {
	// Kind of the referent: ConfigMap (default) or Secret.
	// +optional
	// +kubebuilder:validation:Enum=ConfigMap;Secret
	// +kubebuilder:default=ConfigMap
	Kind string `json:"kind,omitempty"`

	// Name of the ConfigMap or Secret.
	// +required
	// +kubebuilder:validation:MinLength=1
	Name string `json:"name"`
}

type NamespaceMatcher struct {

	// Names is an explicit allow-list of namespace names. Entries are namespace names (DNS-1123
	// labels), never patterns — `*` is rejected. To admit every namespace, declare `selector: {}`.
	// +optional
	// +listType=set
	// +kubebuilder:validation:items:MinLength=1
	// +kubebuilder:validation:items:MaxLength=63
	// +kubebuilder:validation:items:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
	Names []string `json:"names,omitempty"`

	// Selector is a label selector matched against Namespace labels; a namespace whose labels
	// match is admitted. ORed with Names.
	// +optional
	Selector *metav1.LabelSelector `json:"selector,omitempty"`
}

type OperationType string

type PlacementMode string

type PruneMode string

type PrunePolicy struct {

	// Mode selects which deletion paths are enabled. `Never` removes nothing; `OnEvent` mirrors an
	// observed source DELETE but never infers a deletion from a resync snapshot; `Always` enables
	// both, restoring full desired-state convergence. Omitted, it is `OnEvent`.
	// +optional
	// +kubebuilder:validation:Enum=Never;OnEvent;Always
	// +kubebuilder:default=OnEvent
	Mode PruneMode `json:"mode,omitempty"`
}

type ResourceRule struct {
	// Operations to watch. If empty, watches all operations (CREATE, UPDATE, DELETE).
	// Supports: CREATE, UPDATE, DELETE, or * (wildcard for all operations).
	// Examples:
	//   - ["CREATE", "UPDATE"] watches only creation and updates, ignoring deletions
	//   - ["*"] or [] watches all operations
	// +optional
	Operations []OperationType `json:"operations,omitempty"`

	// APIGroups to match. Empty string ("") matches the core API group.
	// If omitted, GitOps Reverser resolves the resource name across all served API groups.
	// Wildcards supported: "*" matches all groups.
	// Examples:
	//   - [""] matches core API (pods, services, configmaps)
	//   - ["apps"] matches apps API group (deployments, statefulsets)
	//   - ["", "apps"] matches both core and apps groups
	//   - ["*"] matches all groups
	//   - [] resolves a named resource only when it is served by one API group
	// +optional
	APIGroups []string `json:"apiGroups,omitempty"`

	// APIVersions to match. If empty, uses the preferred served version for each group/resource.
	// Wildcards supported: "*" matches all versions.
	// Examples:
	//   - ["v1"] matches only v1 version
	//   - ["v1", "v1beta1"] matches both versions
	//   - ["*"] matches all served versions
	//   - [] matches the preferred served version
	//
	// Multi-version note: the built-in cold-start Git path is versionless, so two
	// objects that differ only by API version resolve to the same file. To watch
	// several versions of a group/resource and keep them in separate files, give the
	// GitTarget a placement template that includes {version} (see GitTargetPlacementSpec).
	// +optional
	APIVersions []string `json:"apiVersions,omitempty"`

	// Resources to match (plural names like "pods", "configmaps").
	// This field is required and determines which resource types trigger this rule.
	// Wildcard semantics follow Kubernetes admission webhook patterns:
	//   - "*" matches all resources
	//   - "pods" matches exactly pods (case-insensitive)
	//
	// For custom resources, use the exact plural resource name and set apiGroups
	// when more than one served API group exposes that name.
	//
	// Note: Subresources cannot be added here. Values containing "/" (for example
	// "pods/log" or "pods/*") are rejected by the API because subresources are
	// not supported for list/watch snapshot planning. Prefix/suffix wildcards
	// like "pod*" or "*.example.com" are NOT supported. Use exact matches or the
	// "*" wildcard for broad matching.
	// +required
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:items:MinLength=1
	// +kubebuilder:validation:items:Pattern=`^[^/]*$`
	Resources []string `json:"resources"`

	// SourceNamespace is the namespace this item watches IN THE SOURCE CLUSTER its GitTarget
	// mirrors from: omitted for this WatchRule's own namespace, an exact name for one other, or
	// "*" for every namespace the source credential can read.
	//
	// "*" is one cluster-wide list and watch rather than a set of per-namespace ones, so its bound
	// is the credential's own RBAC and nothing else. Naming any namespace other than this rule's
	// own, "*" included, requires the GitTarget's ClusterProvider to admit the target's namespace
	// AND to set spec.allowAnySourceNamespace; while that flag is false, "*" is refused outright.
	//
	// This changes only which namespace is WATCHED, never where objects are written: Git placement
	// follows each mirrored object's own namespace.
	// +optional
	// +kubebuilder:validation:MaxLength=63
	// +kubebuilder:validation:Pattern=`^(\*|[a-z0-9]([-a-z0-9]*[a-z0-9])?)$`
	SourceNamespace string `json:"sourceNamespace,omitempty"`
}

type ResourceScope string

type WatchRule struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty,omitzero"`

	// spec defines the desired state of WatchRule
	// +required
	Spec WatchRuleSpec `json:"spec"`

	// status defines the observed state of WatchRule
	// +optional
	Status WatchRuleStatus `json:"status,omitempty"`
}

type WatchRuleList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`

	Items []WatchRule `json:"items"`
}

type WatchRuleSpec struct {
	// GitTargetRef names the GitTarget this rule feeds, in this WatchRule's own namespace.
	// +required
	// +kubebuilder:validation:XValidation:rule="self.name != ”",message="spec.gitTargetRef.name must not be empty"
	GitTargetRef meta.LocalObjectReference `json:"gitTargetRef"`

	// Rules define which resources to watch, and in which source namespaces.
	// Multiple rules create a logical OR - a resource matching ANY rule is watched.
	// Each rule can specify operations, API groups, versions, resource types, and a source namespace.
	// +required
	// +kubebuilder:validation:MinItems=1
	Rules []ResourceRule `json:"rules"`
}

type WatchRuleStatus struct {
	// ObservedGeneration is the latest generation observed by the controller.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions represent the latest available observations of an object's state
	// +optional
	// +listType=map
	// +listMapKey=type
	// +patchMergeKey=type
	// +patchStrategy=merge
	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type"`

	// Streams is the bounded stream-readiness roll-up for the types this rule resolves.
	// +optional
	Streams *WatchRuleStreamsStatus `json:"streams,omitempty"`
}

type WatchRuleStreamsStatus struct {
	// Summary is the display-only ready/total ratio.
	// +optional
	Summary string `json:"summary,omitempty"`

	// Total is how many types this rule resolves.
	Total int32 `json:"total"`

	// Ready is how many resolved types are Streaming.
	Ready int32 `json:"ready"`

	// Replaying is how many resolved types are still replaying their initial events.
	Replaying int32 `json:"replaying"`

	// Blocked is how many resolved types cannot currently be watched.
	Blocked int32 `json:"blocked"`

	// PendingSample is a bounded sample of types not yet ready.
	// +optional
	// +kubebuilder:validation:MaxItems=5
	PendingSample []string `json:"pendingSample,omitempty"`
}