git

type AttachCommitRequest struct {
	// Namespace, Name, UID identify the CommitRequest. UID may be empty (a
	// Metadata-level audit policy can omit it); identity then keys on
	// namespace/name only.
	Namespace string
	Name      string
	UID       string

	// Author is the effective user that requested the finalize, captured from
	// validating admission. Only a window whose author
	// matches is attached; this binds "the open window" to "the requesting
	// author's open window".
	Author string
	// Attribution is the outcome of attributing THIS CommitRequest, from the command-authorship
	// path. It is matched alongside Author rather than inferred from it, because an empty Author
	// alone cannot say whether an actor was sought: it is both "attribution is off" and
	// "attribution ran and named nobody". Only the NamesActor half is compared against the
	// window's outcome — see matchesWindow for why the enums themselves must not be.
	Attribution AttributionOutcome
	// GitTargetName / GitTargetNamespace scope the finalize to one GitTarget.
	GitTargetName      string
	GitTargetNamespace string

	// Message is the verbatim commit message to attach to the window. Empty keeps
	// the generated grouped-commit message.
	Message string
	// CloseDelaySeconds is the close-delay collect window: the worker closes the
	// attached window and finalizes it at receipt + CloseDelaySeconds (the delay is
	// anchored at attach receipt).
	CloseDelaySeconds int32
}

type AttributionOutcome string

type BranchInfo struct {
	ShortName string // e.g., "main"
	Sha       string // commit hash, normally the tip of the default branch. But will be empty ("") for an unborn branch that is going to be orphaned branch (if the default branch does not exist)
	Unborn    bool   // Is true for branches that don't have commits yet: only HEAD is configured to it
}

type BranchKey struct {
	// RepoNamespace is the namespace containing the GitProvider.
	RepoNamespace string
	// RepoName is the name of the GitProvider.
	RepoName string
	// Branch is the Git branch name.
	Branch string
}

type BranchWorker struct {
	// Identity (immutable after creation)
	GitProviderRef       string
	GitProviderNamespace string
	Branch               string

	// Dependencies
	Client client.Client
	Log    logr.Logger
	// contains filtered or unexported fields
}

type BranchWorkerLimits struct {
	// MaxBufferBytes caps totalRetainedBytes: the open commit window plus the writes
	// committed locally and retained for replay until a push succeeds. Tripping it
	// finalizes the window early, ignoring the commit cadence.
	MaxBufferBytes int64

	// QueueDepth is the depth of the event queue, and it is a HARD drop boundary: the
	// enqueue is deliberately non-blocking, so a full queue throws the item away and
	// counts git_queue_drops_total rather than stalling the watch path behind a slow
	// remote.
	//
	// MaxBufferBytes does NOT cover this queue. That cap is accounted only once the loop
	// DEQUEUES an item, so whatever is still on the channel is bounded by count alone and
	// costs memory ON TOP of it. The channel itself is trivial (a WorkItem is three
	// pointers); what it retains is not, because each live-event item holds a sanitized
	// object as an unstructured map, measured at roughly SIX times the bytes it serializes
	// to. Budget QueueDepth x serialized size x ~6 per SATURATED worker: ~5MiB at the
	// default depth for ~800-byte resources, but the multiplier rides the payload, so a
	// folder mirroring megabyte-sized ConfigMaps reaches gigabytes at the same depth.
	QueueDepth int
}

type CommitConfig struct {
	Committer CommitterConfig
	Message   CommitMessageConfig
}

type CommitFile struct {
	Path    string
	Content []byte
}

type CommitMessageConfig struct {
	LiveTemplate      string
	ReconcileTemplate string
	// RequestTemplate frames a CommitRequest's message. Empty — the default — commits that
	// message verbatim, which is the behaviour every target had before the field existed.
	RequestTemplate string
}

type CommitMode string

type CommitterConfig struct {
	Name  string
	Email string
}

type Credential struct {
	SSH    *sshpkg.KeyAuth
	Basic  *gogithttp.BasicAuth
	Bearer *gogithttp.TokenAuth
}

type CredentialTransportPolicy struct {
	// AllowInsecureGitHTTP permits credentials with http:// GitProvider URLs. It is intended for
	// trusted in-cluster development Git servers only.
	AllowInsecureGitHTTP bool
}

type Encryptor interface {
	Encrypt(ctx context.Context, plain []byte, meta ResourceMeta) ([]byte, error)
}

type Event struct {
	// Object is the sanitized Kubernetes object. Exactly one of Object or
	// FieldPatch is set for a resource mutation; a control or DELETE event may
	// carry neither.
	Object *unstructured.Unstructured

	// FieldPatch, when set, replaces Object with a bounded in-place edit of an
	// existing parent manifest (subresource audit resolution). It is mutually
	// exclusive with Object.
	FieldPatch *FieldPatch

	// Identifier contains resource identification information.
	Identifier types.ResourceIdentifier

	// ResourceVersion is the metadata.resourceVersion of the observed state this event
	// describes. It is PROVENANCE, never content: sanitize strips resourceVersion from Object
	// on purpose (a version in a committed manifest makes every observation a byte change), so
	// this field carries the fact BESIDE the object rather than inside it. Never write it back
	// onto Object.
	//
	// Stamped where the object is observed — the live watch holds the unsanitized object there
	// and nowhere downstream does. Producers with no observed object (reconcile, bootstrap)
	// leave it empty.
	//
	// Unlike the object-derived fields, a DELETE CAN carry one: the watch Deleted frame
	// delivers the final object, so this names the last version that existed.
	ResourceVersion string

	// Generation is the metadata.generation of the observed state — the DESIRED state's counter,
	// where ResourceVersion counts every write. Same provenance-not-content rule: sanitize strips
	// generation from Object one line after resourceVersion, and for the same reason.
	//
	// 0 means "no generation", which covers both "this producer observed nothing" and "this kind
	// has none": a ConfigMap or a Secret never carries one, only types with a spec do.
	Generation int64

	// Operation is the admission operation (CREATE, UPDATE, DELETE).
	Operation string

	// UserInfo contains user information for commit messages.
	UserInfo UserInfo

	// Attribution is the authority for author rendering, the author_kind metric, and
	// CommitRequest window matching. None may infer the outcome from UserInfo: an empty username
	// cannot distinguish "attribution is off" from "it ran and found nothing". attachAuthor is
	// the only assignment outside tests.
	Attribution AttributionOutcome

	// Path is the POSIX-like relative path prefix for this event's files.
	// This comes from the GitTarget that triggered this event.
	// Empty string means write to repository root.
	Path string

	// GitTargetName is the target owning this event.
	GitTargetName string

	// GitTargetNamespace is the namespace of the target owning this event.
	GitTargetNamespace string

	// SourceCluster is the NAME of the source cluster this object was watched on —
	// (api/v1alpha3).GitTarget.SourceCluster(), the referenced ClusterProvider's name
	// ("default" for the in-cluster provider). The writer resolves this document's GVK->GVR
	// against that cluster's type registry, so a folder mirroring a remote is never indexed
	// against the local cluster's mapping.
	SourceCluster string

	// BootstrapOptions controls path-scoped bootstrap file staging for this event.
	BootstrapOptions pathBootstrapOptions

	// SourceCell names the target-watch cell that produced this event. Zero for every
	// non-stream producer (reconcile, bootstrap, the admission path). Diagnostic only:
	// nothing filters the queue on it. See source_cell.go.
	SourceCell types.CellKey
}

type FieldPatch struct {
	// Assignments are the (path, value) pairs to set on the parent manifest. Paths
	// are disjoint; each owns only its own subtree, so the patch is additive and
	// leaves every unmentioned field in Git untouched.
	Assignments []manifestedit.FieldAssignment
	// Source is a bounded origin label for commit messages and metrics, e.g.
	// "deployments/scale". Never the request URI.
	//
	// The parent Kind is NOT carried: the audit objectRef gives only the GVR, and the subresource
	// body's own Kind ("Scale") is not the parent's. The writer resolves the parent through the
	// same resource-identity inventory the GVR-only delete uses.
	Source string
}

type FinalizeOutcome string

type FinalizeResult struct {
	// Outcome is set when Err is nil.
	Outcome FinalizeOutcome
	// SHA is the resulting commit SHA when Outcome is FinalizeCommitted.
	SHA string
	// Branch is the branch the worker operates on.
	Branch string
	// Err is set when the request could not be completed.
	Err error
}

type LayoutReport struct {
	manifestanalyzer.LayoutResolution

	// Revision is the Git revision the scan read; ResolvedAt is when it ran.
	Revision   string
	ResolvedAt time.Time
}

type LayoutReporter func(target itypes.ResourceReference, report LayoutReport)

type LiveCommitMessageData struct {
	// Author is the verbatim event.UserInfo.Username for the group.
	Author string
	// GitTarget is the single target this commit is bound to.
	GitTarget string
	// Count is the number of retained resource entries before comparison with Git.
	Count int
	// Operations counts retained entries by operation kind (CREATE/UPDATE/DELETE).
	Operations map[string]int
	// Resources is the per-resource list, deduplicated by file path so the
	// final state is what's being committed.
	Resources []ResourceRef
	// RequestMessage is the message an attached CommitRequest supplied, unaltered. It is empty for
	// every window no request attached to, which is the ordinary case and why liveTemplate may
	// reference it freely.
	//
	// It lives on this struct rather than on a parallel request-only context for the reason
	// ResourceRef's own comment gives about the placement vocabulary: a reader should not have to
	// learn two vocabularies to describe one commit. One sample builder then serves both renders.
	RequestMessage string
}

type PathRefusalReporter func(
	target itypes.ResourceReference,
	cell itypes.CellKey,
	refused *manifestanalyzer.AcceptanceRefusedError,
)

type PendingWrite struct {
	Kind               PendingWriteKind
	Events             []Event
	CommitMessage      string
	CommitConfig       CommitConfig
	Signer             gogit.Signer
	GitTargetName      string
	GitTargetNamespace string
	Targets            map[pendingTargetKey]ResolvedTargetMetadata
	ByteSize           int64

	// Desired is the complete desired resource snapshot, set only for a
	// PendingWriteResync. The worker folds it over the worktree's content-derived
	// store to produce the resync plan (upserts + mark-and-sweep drops).
	Desired []manifestanalyzer.DesiredResource
	// Scope, when set, restricts the resync's mark-and-sweep to one type's
	// (group, resource) and optionally to one namespace: the M12 per-type
	// reconcile/sweep. Desired then carries only that scope's objects (empty for a pure
	// sweep), and no sibling type's — nor, for a namespace-scoped resync, any sibling
	// namespace's — document is ever dropped. Nil is the whole-GitTarget resync.
	Scope *ResyncScope
	// ResourceVersion is the cluster snapshot's resourceVersion the desired set is pinned to
	// (the joined streaming-watch bookmark) — the COLLECTION's version, not any one object's.
	// Carried for diagnostics, logging, and the reconcile commit message.
	//
	// Not "Revision": in this codebase a revision is a Git commit (see LayoutReport.Revision).
	ResourceVersion string
	// ResyncStats, when non-nil, is populated during apply with the plan's
	// create/update/delete/skip counts so a synchronous caller can report them.
	ResyncStats *ResyncStats
	// Committed, when non-nil, is set true during apply iff the resync produced a
	// commit. A no-op resync (e.g. an empty initial snapshot) must not be retained or
	// pushed: doing so would advance the push cooldown and delay the next real
	// snapshot's push past its window.
	Committed *bool

	// CommitRequest, when set, is the CommitRequest claiming this write: it is
	// resolved Committed (with CommitSHA) once this write is pushed. It rides the write through the
	// push cooldown and the conflict rebase-replay, so the result follows the data.
	CommitRequest *commitRequestID

	// CommitSHA is the hash of the commit this write created, captured in
	// executePendingWrite and refreshed when the write is re-executed on a
	// rebase-replay (so it is never a stale pre-rebase hash). Zero when the write
	// produced no commit (no diff).
	CommitSHA plumbing.Hash
	// contains filtered or unexported fields
}

type PendingWriteKind string

type PullReport struct {
	ExistsOnRemote  bool // Branch exists on remote
	HEAD            BranchInfo
	IncomingChanges bool // SHA changed, requiring resource-level reconcile
}

type ReconcileCommitMessageData struct {
	Count      int
	GitTarget  string
	Group      string
	Version    string
	Resource   string
	APIVersion string
	// ResourceVersion is THE COLLECTION'S metadata.resourceVersion — the LIST the desired set
	// was folded from, not any one object's. A reconcile describes a type, so the version it
	// can name is the snapshot's. (The per-object counterpart is
	// LiveCommitMessageData.Resources[i].ResourceVersion, which a live commit carries because
	// it names n resources.)
	//
	// Empty for a pure sweep. It was called Revision until v0.48.0; see the Revision tombstone
	// below for why the word moved.
	ResourceVersion string
	// Namespace is the single source namespace a namespace-scoped reconcile covered, and
	// is empty for a whole-target or all-namespaces reconcile.
	Namespace string
}

type RemoteMovedError struct {
	// Branch is the cycle's root branch, the one whose advertised hash was compared.
	Branch plumbing.ReferenceName
	// Expected is the hash the local commits were based on (the cycle's root hash).
	Expected plumbing.Hash
	// Advertised is where the remote says that branch is now.
	Advertised plumbing.Hash
	// Missing records that the branch was absent from the advertisement rather than sitting at a
	// different hash. Advertised is then the zero hash, which is the honest answer: there is
	// nothing there.
	//
	// A deleted branch IS the remote moving, and typing it as one is what lets the worker recover
	// from it. Reported as an untyped error, it fell through to the fallback probe — which reads
	// refs/remotes/origin/<branch>, a ref SmartFetch cannot prune because it builds no refspec for
	// a branch the remote no longer has. The probe therefore answered with the branch's old hash,
	// that hash matched the cycle's root, and the worker concluded the remote had not moved. No
	// replay followed, and the retained writes then made every later cycle skip its fetch as well,
	// so the worker pushed the same doomed commits forever.
	Missing bool
}

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

type RenderFidelityState string

type RenderFidelityStatus struct {
	// Revision is the highest scope revision this target has issued. It moves whenever any
	// scope is restarted, so a status projection can tell one plan from the next.
	Revision    uint64
	State       RenderFidelityState
	Reason      string
	Message     string
	Divergence  *manifestanalyzer.RenderDivergence
	ScopeCount  int
	CleanScopes int
}

type RepoInfo struct {
	DefaultBranch     *BranchInfo
	RemoteBranchCount int
}

type ResolvedEncryptionConfig struct {
	Provider      string
	AgeRecipients []string
}

type ResolvedTargetMetadata struct {
	Name             string
	Namespace        string
	Path             string
	BootstrapOptions pathBootstrapOptions
	EncryptionConfig *ResolvedEncryptionConfig
	// Placement is the GitTarget's declared new-file placement policy, resolved
	// from spec.placement. Nil when the GitTarget declares none, in which case new
	// resources are placed beside the folder's one kustomize root, if it has exactly one,
	// and otherwise at the canonical path.
	Placement *manifestanalyzer.PlacementPolicy
	// Namespaces is the GitTarget's declared namespace behavior — spec.serializeNamespace and the
	// source namespaces reaching the target — which decides whether the documents this target
	// writes carry metadata.namespace, and which namespace a namespace-free one belongs to. It is
	// resolved with the rest of the metadata so a replayed write honours the policy it was planned
	// under, exactly as PruneMode and Suspend are.
	Namespaces namespacePolicy
	// CommitMessage is the GitTarget's spec.commit.message, verbatim and possibly nil. It is
	// overlaid onto the provider-resolved CommitConfig so a commit is phrased by the folder it
	// writes to rather than by the connection it travels over. Resolved with the rest of the
	// target's mutable state, so a write replayed after a rebase is phrased by the policy it was
	// planned under.
	CommitMessage *v1alpha3.CommitMessageSpec

	// PruneMode is the GitTarget's EFFECTIVE spec.prune.mode — always a concrete value,
	// because it is resolved through EffectivePruneMode and an omitted policy is onEvent.
	// It gates both deletion paths: the resync mark-and-sweep (through the planner's
	// SweepMode) and the steady-state DELETE-event writer.
	//
	// Retained on the pending write so a replay after a rebase is not re-planned under a LOOSER
	// policy than it was planned against. Not frozen, though: tightenPendingPruneModes lowers it
	// when the current policy is stricter, because tightening exists to stop deletions that have
	// not landed yet.
	PruneMode v1alpha3.PruneMode
	// SourceCluster is the NAME of the source cluster the GitTarget mirrors from —
	// (api/v1alpha3).GitTarget.SourceCluster(), the referenced ClusterProvider's name
	// ("default" for the in-cluster provider). The resync mark-and-sweep resolves this subtree's
	// documents' GVK->GVR against that cluster's registry, so a folder mirroring a remote is swept
	// against the right cluster's mapping.
	SourceCluster string

	// Suspend suppresses the WRITE only; the scan still runs, which keeps a suspended target's
	// status fresh. Being CAPTURED defines the cutover: a suspension arriving after this write was
	// planned does not retract it, and a commit already made locally is still pushed. Reading the
	// live GitTarget at push time would strand that commit, to resurface out of order on resume.
	Suspend bool
}

type ResourceMeta struct {
	Identifier      itypes.ResourceIdentifier
	UID             string
	ResourceVersion string
	Generation      int64
}

type ResourceRef struct {
	Operation  string
	APIVersion string
	Group      string
	Version    string
	Resource   string
	// Kind is the manifest kind, the commit-message spelling of the {kind} placement
	// variable. It is read off the event's object, so it is EMPTY for a DELETE: the watcher
	// carries no object for one, because by then the object is gone from the cluster.
	Kind string
	// Namespace is the resource's namespace, or the literal "_cluster" when it is
	// cluster-scoped — types.ClusterScopeSegment, the same word the canonical Git path and the
	// {namespace} placement variable use. A cluster-scoped resource HAS a scope name; it is
	// simply not a namespace, and "_cluster" is a name no real namespace can collide with
	// (DNS-1123 forbids "_"). A template therefore never has to guard this field.
	Namespace string
	Name      string
	// Labels is the resource's metadata.labels as the writer commits them: the SANITIZED
	// object's labels, so one internal/sanitize strips is already absent, exactly as for the
	// "{label:key}" placement variable. It is nil for a DELETE (no object) and for a resource
	// carrying none.
	//
	// Read it with .Label, not with .Labels.key — see Label.
	Labels map[string]string
	// ResourceVersion is the metadata.resourceVersion of the observed state this commit wrote,
	// and "" for a producer that observed none (reconcile, bootstrap). Guard it with
	// {{with .ResourceVersion}} — empty here has one meaning, "this producer observed no
	// version", and no sentinel states that better than silence.
	//
	// It is NOT the object's current version, and the gap is deliberate: an update whose
	// git-writable content is unchanged (a /status-only write) is never routed, so this value
	// lags the cluster's. Compare it for EQUALITY — equal means nothing is pending — never by
	// subtraction: resourceVersion is opaque by contract and is the global store revision in
	// practice, so a gap measures other objects' writes, not our own drops. The census
	// counts those: watch_events_total{outcome="unchanged"}.
	//
	// Unlike Kind and Labels, a DELETE DOES carry one — see Event.ResourceVersion.
	ResourceVersion string
	// Generation is the metadata.generation of the state this commit wrote, and 0 when there is
	// none. It moves only when the DESIRED state changes, so unlike ResourceVersion it is worth
	// comparing: it is per object, starts at 1, and advances once per spec write, so a gap
	// between two commits really does mean spec changes that were not committed separately.
	//
	// Two blind spots keep it from replacing ResourceVersion. A ConfigMap, a Secret, and any
	// other kind without a spec never carry one, so this stays 0 for much of what a target
	// mirrors. And a label- or annotation-only edit changes what gets committed WITHOUT moving
	// it, so an unchanged Generation does not mean an unchanged commit.
	//
	// Guard it with {{with .Generation}}, which renders nothing for 0.
	Generation int64
}

type ResyncRequest struct {
	Desired            []manifestanalyzer.DesiredResource
	ResourceVersion    string
	GitTargetName      string
	GitTargetNamespace string
	// Scope, when set, makes this a per-type (M12) reconcile/sweep: the mark-and-sweep is
	// restricted to the named type — and, when the scope names a namespace, to that
	// namespace — while Desired carries only that scope's objects (empty = pure sweep of a
	// removed type). Nil is a whole-GitTarget resync. See ResyncScope for the invariant
	// binding this to Desired.
	Scope *ResyncScope
	// Heal marks a non-urgent drift-correcting resync the worker DEFERS while a commit window is
	// open. One worker serves N GitTargets and the window is a worker singleton, so a
	// force-finalizing heal can steal a DIFFERENT GitTarget's held CommitRequest window. Waiting
	// for idle recurs on every silence timeout, so it never starves. A first-sync backfill is NOT
	// a heal: it must establish initial state promptly.
	Heal bool
	// RefreshRemote asks the worker to fetch/reset to the remote tip before evaluating the
	// acceptance gate. Forced GitTarget rechecks use it because their trigger is often "I changed
	// Git; look again", and the local checkout may still hold the refused revision.
	RefreshRemote bool
	// SourceCell names the target-watch cell that gathered this snapshot. Zero for a
	// whole-GitTarget resync, which speaks for no single cell. Diagnostic only: nothing
	// filters the queue on it. See source_cell.go.
	SourceCell types.CellKey
	// Result receives exactly one reply. It is buffered (cap 1) by the emitter so
	// the worker never blocks delivering it.
	Result chan ResyncResult
}

type ResyncResult struct {
	Stats ResyncStats
	Err   error
}

type ResyncScope struct {
	// Cell is the sweep boundary and the scope's identity: group, resource, namespace.
	Cell types.CellKey
	// Version is the served version the desired set was gathered at. It is DATA, not
	// identity: it renders the reconcile commit message's {{.APIVersion}} and names the
	// version a snapshot came from in logs, and it is deliberately absent from the cell
	// key, so a scope always round-trips to the boundary it sweeps (types.CellKey).
	Version string
}

type ResyncStats struct {
	Created          int
	Updated          int
	Deleted          int
	Skipped          int
	PlacementSkipped int
	// Retained is how many managed documents this resync's prune policy kept that a converged
	// mirror would have dropped. It is the ONE count here that does not describe something the
	// resync did: a suppressed drop produces no action, no commit, and no other stat, so without
	// it nothing downstream can tell a converged mirror from a deliberately retaining one. It
	// rides the reply channel to the drain, which rolls it up onto GitTarget status.
	Retained int
	// PruneMode stamps Retained with the effective policy that produced it, so the count and the
	// reason for it travel together. Reading the mode from the spec at projection time instead
	// would let a target that has just been switched publish a new mode beside a count the old
	// one produced.
	PruneMode v1alpha3.PruneMode
}

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

type SSHHostKeyConfig struct {
	// ControllerNamespace is the namespace the controller runs in; it scopes the install-level
	// default known-hosts ConfigMap.
	ControllerNamespace string

	// DefaultKnownHostsConfigMap names an optional install-level ConfigMap in ControllerNamespace
	// that supplies known_hosts when neither the credentials Secret nor the GitProvider supplies
	// it. Empty disables this layer.
	DefaultKnownHostsConfigMap string

	// AllowMissingKnownHosts permits SSH only when NO host-key source produced any known_hosts at
	// all (the controller's --insecure-allow-missing-known-hosts flag). A known_hosts that is
	// present but unparseable is always a hard error.
	AllowMissingKnownHosts bool
}

type UserInfo struct {
	Username string
	UID      string
	// DisplayName is the human-readable name from the OIDC "name" claim, when
	// the audit event carries it. Empty means "fall back to Username".
	DisplayName string
	// Email is the address from the OIDC "email" claim, when the audit event
	// carries it. Empty means "fall back to ConstructSafeEmail(Username)".
	Email string
}

type WorkItem struct {
	// Request is a resource-write request.
	Request *WriteRequest
	// Attach is a CommitRequest attach: bind a message to the author's window and
	// finalize it after the grace.
	Attach *AttachCommitRequest
	// Resync is a streaming-snapshot resync request (M8): a synchronous
	// request/reply that materialises a GitTarget's complete desired set.
	Resync *ResyncRequest
}

type WorkerManager struct {
	Client client.Client
	Log    logr.Logger
	// contains filtered or unexported fields
}

type WriteRequest struct {
	Events             []Event
	CommitMessage      string
	CommitConfig       *CommitConfig
	Signer             gogit.Signer
	GitTargetName      string
	GitTargetNamespace string
	BootstrapOptions   pathBootstrapOptions
	CommitMode         CommitMode
}