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
	// Attach selects the window: the author's current one or the next, or only the next.
	Attach v1alpha3.AttachPolicy
	// AttachTimeout bounds the wait for a window, counted from the worker's registration.
	AttachTimeout time.Duration
	// IdleTimeout closes the attached window after this much silence; nil means no idle close.
	IdleTimeout *time.Duration
	// MaxDuration closes the attached window this long after the attach.
	MaxDuration time.Duration
	// CommitEmpty records Message in an empty commit when the request ends with nothing to
	// commit: whenNothingToCommit: CommitEmpty.
	CommitEmpty bool
}

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. While a failed attempt waits
	// for its retry it is also the intake budget, covering queued work too. See intake.go.
	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 refuses the item and counts
	// git_queue_refusals_total rather than stalling the watch path behind a slow remote. The
	// producer keeps it and offers it again: the watch redelivers from its unadvanced cursor.
	//
	// On a healthy branch MaxBufferBytes does NOT cover this queue: the window 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. During an outage the intake gate charges queued
	// payload against MaxBufferBytes at enqueue (intake.go), in serialized bytes. 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 CommitRequestPhase 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 DefaultBranchUnresolvedError struct {
	// Head is the short name of the branch HEAD points at; empty when there is no symbolic HEAD.
	Head string
}

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

	// SourceCollection names the target-watch collection 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_collection.go.
	SourceCollection types.CollectionKey
	// contains filtered or unexported fields
}

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
	// Commit is the resulting commit Commit when Outcome is FinalizeCommitted.
	Commit string
	// Branch is the branch the worker operates on.
	Branch string
	// Err is set when the request could not be completed.
	Err error
	// Phase is where an UNRESOLVED request stands on the worker; empty once resolved, and empty
	// before the worker has registered it.
	Phase CommitRequestPhase
	// Held is why a request the worker holds has not reached the remote yet: the worker's
	// publication report while it cannot publish, empty otherwise. See PublicationStatus.
	Held string
}

type LayoutReport struct {
	manifestanalyzer.LayoutResolution

	// Commit is the commit hash the scan read; ResolvedAt is when it ran.
	Commit     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 ObservationSource string

type ParentState string

type PathRefusalReporter func(
	target itypes.ResourceReference,
	collection itypes.CollectionKey,
	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

	// AllowEmpty makes a grouped window commit even when its events changed nothing, because the
	// CommitRequest attached to it asked for whenNothingToCommit: CommitEmpty. A suspended target
	// still writes nothing.
	AllowEmpty bool
	// RequestAuthor and RequestAttribution author a PendingWriteRequestRecord, which has no
	// events to take an author from: they are the request submitter's, matched the same way a
	// window's author is.
	RequestAuthor      UserInfo
	RequestAttribution AttributionOutcome

	// CommitRequest, when set, is the CommitRequest attached to 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 PublicationStatus struct {
	// Failing is set while a failed attempt waits for its retry.
	Failing bool
	// Since is when this run of failures began. It holds until a publication lands.
	Since time.Time
	// Cause is what the last attempt met.
	Cause string
	// ParentUnavailable is set when the cause is the parent branch a new write branch is created
	// from: the parent status already says so, more precisely.
	ParentUnavailable bool
	// IntakePaused is set while the branch refuses new writes, saves and resyncs.
	IntakePaused bool
}

type PullReport struct {
	ExistsOnRemote  bool // Branch exists on remote
	HEAD            BranchInfo
	IncomingChanges bool // SHA changed, requiring resource-level reconcile
	// ParentBranch is the branch checked out instead, when the target branch is absent: the parent
	// it would be created from. HEAD.Sha is then the parent's commit. Empty otherwise.
	ParentBranch string
}

type PushOutcome struct {
	// Kind is which exit was taken.
	Kind PushOutcomeKind
	// Head is where the branch is on the remote now. Zero only for PushNoBranch.
	Head plumbing.Hash
}

type PushOutcomeKind string

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 RefreshRequest struct {
	// Target is the GitTarget this refresh is for, and the one its observation is reported
	// against. A worker serves every target on its (provider, branch); this names the one in
	// hand.
	Target itypes.ResourceReference
	// Path is the GitTarget's spec.path, so a refresh can re-read that folder and republish
	// what its shape resolves to. Empty skips the re-scan.
	Path string
	// MaxAge is how old an observation may be before it is topped up. A younger one makes the
	// refresh a no-op with no connection at all, which is what keeps an actively-publishing
	// branch free: its pushes renew the record continuously.
	MaxAge time.Duration
}

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 RemoteObservation struct {
	// Commit is the hash the branch is at on the remote. EMPTY means the advertisement did not
	// carry the branch: a branch does not exist without a commit, so "no revision" and "no
	// branch" are the same fact and do not need two fields.
	Commit string
	// At is when the observation was made.
	At time.Time
	// By is what proved it.
	By ObservationSource
	// Repo is the repository the observation is ABOUT: the identity of the worker that proved it.
	//
	// A revision means nothing without it. Workers are keyed by (provider, branch) while a
	// GitProvider can be repointed at another repository, so the layer that publishes this can be
	// holding a revision from a repository its GitTarget no longer uses — and if the new one is
	// unreachable, nothing else would ever correct it. Carrying the identity lets that be DERIVED
	// at the moment of publication, by comparing it against what the GitProvider names now,
	// instead of latched by whoever happened to notice the change.
	//
	// It is zero for a worker that has no identity of its own: the CLI, and tests that never reach
	// a remote. A comparison against an unknown identity proves nothing, so it is not made.
	Repo RepoIdentity
	// ParentState is what the remote offers an absent branch to be created from, observed
	// together with its absence. Empty while the branch exists.
	ParentState ParentState
	// ParentBranch and ParentCommit name that parent and where it is. ParentCommit is empty
	// unless ParentState is ParentFound; ParentBranch is empty for ParentUnborn. For an omitted
	// parent that is ParentMissing, ParentBranch is the branch the remote's HEAD names, or empty
	// when it names none.
	ParentBranch string
	ParentCommit string
	// ParentRequested is spec.parentBranch as the observing operation read it: empty for the
	// remote's default branch. It is set on ParentMissing, so a reader can tell whether the
	// observation is about the parent configured now.
	ParentRequested string
}

type RemoteReporter func(observed RemoteObservation)

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 RepoIdentity struct {
	// ProviderUID is the GitProvider object's metadata.uid.
	ProviderUID k8stypes.UID
	// URL is the GitProvider's spec.url, exactly as it is written there.
	URL string
}

type RepoInfo struct {
	DefaultBranch     *BranchInfo
	RemoteBranchCount int
}

type RepositoryNotEmptyError struct {
	// Refs is how many hash refs the advertisement carried.
	Refs 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 built-in 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 built-in 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
	// SourceCollection names the target-watch collection that gathered this snapshot. Zero for a
	// whole-GitTarget resync, which speaks for no single collection. Diagnostic only: nothing
	// filters the queue on it. See source_collection.go.
	SourceCollection types.CollectionKey
	// Result receives exactly one reply. It is buffered (cap 1) by the emitter so
	// the worker never blocks delivering it.
	Result chan ResyncResult
	// contains filtered or unexported fields
}

type ResyncResult struct {
	Stats ResyncStats
	Err   error
}

type ResyncScope struct {
	// Collection is the sweep boundary and the scope's identity: group, resource, namespace.
	Collection types.CollectionKey
	// 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 collection
	// key, so a scope always round-trips to the boundary it sweeps (types.CollectionKey).
	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 ScanAcceptanceReporter func(
	target itypes.ResourceReference,
	refused *manifestanalyzer.AcceptanceRefusedError,
)

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
	// let its timers close that window.
	Attach *AttachCommitRequest
	// Resync is the FIFO position of a streaming-snapshot resync request (M8): a synchronous
	// request/reply that materialises a GitTarget's complete desired set.
	Resync *resyncMarker
	// Refresh asks the worker to re-prove where its branch is on the remote. It is the only
	// work item that never writes anything: see RefreshRequest.
	Refresh *RefreshRequest
	// Withdraw cancels a CommitRequest the worker has not acted on yet. It rides the same FIFO as
	// the attach, so it is always handled after every attach sent before it.
	Withdraw *AttachCommitRequest
	// contains filtered or unexported fields
}

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
}