v1alpha1

type Admission struct {
	// From names the Beacon whose Bundles this admission covers.
	From BundleOrigin `json:"from"`
	// After lists upstream Gates a Bundle must have cleared first. Empty means
	// the Bundle may come straight from the Beacon — the entry point of a
	// pipeline.
	//
	// +optional
	After []string `json:"after,omitempty"`
	// RequireApproval blocks crossing until a human explicitly approves the
	// Bundle for this Gate, regardless of upstream state.
	//
	// +optional
	RequireApproval bool `json:"requireApproval,omitempty"`
}

type Artifact struct {
	// +optional
	Image *ImageArtifact `json:"image,omitempty"`
	// +optional
	Chart *ChartArtifact `json:"chart,omitempty"`
	// +optional
	Commit *CommitArtifact `json:"commit,omitempty"`
}

type Beacon struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   BeaconSpec   `json:"spec"`
	Status BeaconStatus `json:"status,omitempty"`
}

type BeaconList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []Beacon `json:"items"`
}

type BeaconSpec struct {
	// Interval is how often to poll the watched sources. Sources that support
	// webhooks will also emit on push; the interval is the safety net, not the
	// primary mechanism.
	//
	// +kubebuilder:default="5m"
	// +optional
	Interval metav1.Duration `json:"interval,omitempty"`
	// Watch lists the artifact sources to observe.
	//
	// +kubebuilder:validation:MinItems=1
	Watch []WatchSource `json:"watch"`
	// Emit controls when Bundles are created.
	//
	// +kubebuilder:default=Automatic
	// +optional
	Emit EmitPolicy `json:"emit,omitempty"`
	// Retain bounds how many *unreferenced* Bundles from this Beacon are kept.
	//
	// A Beacon polling every couple of minutes emits indefinitely; unbounded,
	// that is etcd growth with no ceiling and a `kubectl get bundles` nobody can
	// read. Zero disables collection entirely.
	//
	// Bundles in use are never collected regardless of this value — see the
	// safety rule in D13. The long-term record belongs in the evidence store,
	// not in etcd.
	//
	// +kubebuilder:default=10
	// +kubebuilder:validation:Minimum=0
	// +optional
	Retain *int32 `json:"retain,omitempty"`
	// Suspend stops this Beacon from discovering anything new, without
	// deleting it. Existing Bundles are unaffected.
	//
	// +optional
	Suspend bool `json:"suspend,omitempty"`
}

type BeaconStatus struct {
	// ObservedGeneration is the spec generation this status describes. If it
	// lags metadata.generation, this status is about the previous spec.
	//
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
	// Conditions follow the standard Kubernetes convention.
	//
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
	// LastHandledReconcileAt echoes the value of the
	// reconcile.fluxcd.io/requestedAt annotation from the last reconcile that
	// acted on it.
	//
	// Without this a caller cannot tell whether its request landed, only that
	// *a* reconcile happened — so a CI job asking for an immediate poll has
	// nothing to wait for. Echoing the caller's own opaque token also
	// distinguishes it from someone else's request (D44).
	//
	// +optional
	LastHandledReconcileAt string `json:"lastHandledReconcileAt,omitempty"`
	// LastPolled is when the sources were last checked.
	//
	// +optional
	LastPolled *metav1.Time `json:"lastPolled,omitempty"`
	// LatestBundle is the most recent Bundle this Beacon emitted.
	//
	// +optional
	LatestBundle string `json:"latestBundle,omitempty"`
	// Discovered is the newest artifact version seen per source, whether or not
	// it produced a Bundle. Useful for answering "why has nothing been emitted?"
	//
	// +optional
	Discovered []Artifact `json:"discovered,omitempty"`
}

type Bundle struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   BundleSpec   `json:"spec"`
	Status BundleStatus `json:"status,omitempty"`
}

type BundleApproval struct {
	// Gate is the Gate this Bundle is approved for.
	Gate string `json:"gate"`
	// Actor is who approved it. Required, and the whole point of the record.
	Actor string `json:"actor"`
	// At is when the approval was given.
	At metav1.Time `json:"at"`
}

type BundleList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []Bundle `json:"items"`
}

type BundleOrigin struct {
	// Beacon is the emitting Beacon's name, in this namespace.
	Beacon string `json:"beacon"`
}

type BundleSpec struct {
	// Beacon names the Beacon that produced this Bundle.
	Beacon string `json:"beacon"`
	// Digest is the content address of this Bundle: a deterministic hash over
	// its artifact versions. Two Bundles with identical artifacts always have
	// the same digest, which is what makes "has this exact thing already been
	// through staging?" answerable.
	//
	// Set by the controller; ignored on input.
	//
	// +optional
	Digest string `json:"digest,omitempty"`
	// Alias is an optional short human-readable handle, so people can say
	// "promote wandering-owl" instead of reciting a hash.
	//
	// +optional
	Alias string `json:"alias,omitempty"`
	// Artifacts are the versioned things this Bundle carries.
	//
	// +kubebuilder:validation:MinItems=1
	Artifacts []Artifact `json:"artifacts"`
}

type BundleStatus struct {
	// Cleared lists the Gates this Bundle has successfully passed, in order.
	// This is the "how did it get to prod?" record.
	//
	// +optional
	Cleared []GateCrossing `json:"cleared,omitempty"`
	// Blocked lists Gates that rejected this Bundle, with the reason.
	//
	// +optional
	Blocked []GateCrossing `json:"blocked,omitempty"`
	// ApprovedFor lists the Gates a human has explicitly approved this Bundle
	// for.
	//
	// An approval is an *additional* requirement, never an override: upstream
	// ordering is checked first, and a Bundle that has not cleared staging
	// stays ineligible for production no matter who approves it (D51). This
	// comment used to claim the opposite, which would have made an approval a
	// silent way past the whole pipeline.
	//
	// Each entry names its approver. An approval that does not say who gave it
	// cannot satisfy four-eyes anywhere downstream — Fides evaluates
	// segregation of duties by comparing the committer, the approver and the
	// deployer as identities, and "approved" with no name is indistinguishable
	// from the author approving their own change.
	//
	// +optional
	// +listType=map
	// +listMapKey=gate
	ApprovedFor []BundleApproval `json:"approvedFor,omitempty"`
}

type ChartArtifact struct {
	// Repo is the chart repository — an HTTPS Helm repo or an OCI registry.
	Repo string `json:"repo"`
	// Name is the chart name. Empty for OCI charts, where the repo already
	// identifies the chart.
	//
	// +optional
	Name string `json:"name,omitempty"`
	// Version is the resolved chart version.
	Version string `json:"version"`
}

type ChartWatch struct {
	// Repo is an HTTPS Helm repository or an OCI registry reference.
	Repo string `json:"repo"`
	// Name is the chart name. Omit for OCI, where Repo identifies the chart.
	//
	// +optional
	Name string `json:"name,omitempty"`
	// Constraint is a semantic version range, e.g. "^6.0.0".
	//
	// +optional
	Constraint string `json:"constraint,omitempty"`
	// +optional
	CredentialsRef *LocalSecretRef `json:"credentialsRef,omitempty"`
}

type CommitArtifact struct {
	// Repo is the git repository URL.
	Repo string `json:"repo"`
	// SHA is the full commit SHA.
	SHA string `json:"sha"`
	// Branch or Tag records how the commit was found, for display.
	//
	// +optional
	Branch string `json:"branch,omitempty"`
	// +optional
	Tag string `json:"tag,omitempty"`
	// Message is the commit subject, for display.
	//
	// +optional
	Message string `json:"message,omitempty"`
}

type EmitPolicy string

type EvidenceConfig struct {
	// FidesEnvironment is the Fides environment this Gate corresponds to.
	//
	// Explicit, and a UUID, because that is what the environment-scoped Fides
	// checks take: `/api/v1/environments/{uuid}/policy-check` and
	// `/api/v1/environments/{uuid}/allowlist`. There is no convention that
	// could produce one — an environment's name is not its key — and a
	// convention that silently resolved to the wrong environment would check
	// the wrong policy while reporting success, which is the worst failure a
	// compliance control can have.
	//
	// +kubebuilder:validation:Pattern=`^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$`
	FidesEnvironment string `json:"fidesEnvironment"`
	// ServerURL is the Fides server. Empty falls back to the controller's
	// --fides-server flag, so a fleet with one Fides says it once.
	//
	// +optional
	ServerURL string `json:"serverURL,omitempty"`
	// CredentialsRef names a Secret holding a Fides API key under `token`.
	//
	// +optional
	CredentialsRef *LocalSecretRef `json:"credentialsRef,omitempty"`
}

type EvidenceRef struct {
	// Trail is the Fides trail identifier for this Passage.
	//
	// +optional
	Trail string `json:"trail,omitempty"`
	// Verdict is the change-gate outcome, e.g. "approve" or "hold".
	//
	// +optional
	Verdict string `json:"verdict,omitempty"`
	// Risk is the change-gate risk score, 0-100.
	//
	// +optional
	Risk *int32 `json:"risk,omitempty"`
	// Blockers are the reasons the change gate is withholding approval.
	//
	// The verdict says a crossing is held; only these say what would unblock
	// it. Without them "hold, risk 62" is a number to escalate rather than a
	// thing to fix, and the reasons existed only inside a step's message.
	//
	// +optional
	Blockers []string `json:"blockers,omitempty"`
	// URL links to the full record.
	//
	// +optional
	URL string `json:"url,omitempty"`
}

type Gate struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   GateSpec   `json:"spec"`
	Status GateStatus `json:"status,omitempty"`
}

type GateCrossing struct {
	// Gate is the Gate in question.
	Gate string `json:"gate"`
	// Passage is the Passage that produced this outcome.
	//
	// +optional
	Passage string `json:"passage,omitempty"`
	// At is when it happened.
	At metav1.Time `json:"at"`
	// Actor is who caused it — a user, or the controller for automatic passage.
	//
	// +optional
	Actor string `json:"actor,omitempty"`
	// Reason explains a block.
	//
	// +optional
	Reason string `json:"reason,omitempty"`
}

type GateList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []Gate `json:"items"`
}

type GateOccupant struct {
	// Bundle is the Bundle's object name.
	Bundle string `json:"bundle"`
	// Digest is its content address.
	//
	// +optional
	Digest string `json:"digest,omitempty"`
	// Passage is the Passage that brought it here.
	//
	// +optional
	Passage string `json:"passage,omitempty"`
	// EnteredAt is when the crossing completed.
	EnteredAt metav1.Time `json:"enteredAt"`
	// Actor is who initiated the crossing.
	//
	// +optional
	Actor string `json:"actor,omitempty"`
	// Verified reports whether this Bundle's verification succeeded here.
	// Downstream Gates should refuse to admit an unverified Bundle.
	//
	// +optional
	Verified *bool `json:"verified,omitempty"`
}

type GateSpec struct {
	// Admits declares which Bundles may cross this Gate.
	//
	// +kubebuilder:validation:MinItems=1
	Admits []Admission `json:"admits"`
	// Passage is the sequence of steps that moves an admitted Bundle into this
	// environment. Typically: render the new state, commit it, push it, and
	// wait for the delivery engine to apply it.
	//
	// +optional
	Passage *PassageTemplate `json:"passage,omitempty"`
	// Watch describes what to monitor to decide whether this Gate is healthy
	// once a Bundle is in place.
	//
	// +optional
	Watch []HealthCheck `json:"watch,omitempty"`
	// Verify describes evidence that must be gathered after crossing before
	// downstream Gates will admit the Bundle. Health says "it is running";
	// verification says "it is working".
	//
	// +optional
	Verify []Verification `json:"verify,omitempty"`
	// Auto admits and crosses eligible Bundles without waiting to be asked.
	// Sensible for dev, rarely for production.
	//
	// +optional
	Auto bool `json:"auto,omitempty"`
	// Windows restricts when Passages may start. Outside every window, eligible
	// Bundles queue rather than fail.
	//
	// +optional
	Windows []Window `json:"windows,omitempty"`
	// Suspend stops new Passages without deleting the Gate. In-flight Passages
	// are unaffected.
	//
	// +optional
	Suspend bool `json:"suspend,omitempty"`
	// Vars are values usable in expressions throughout this Gate's Passage.
	//
	// +optional
	Vars []Var `json:"vars,omitempty"`
	// Retain bounds how many finished Passages this Gate keeps. Older ones
	// beyond the limit are deleted, newest first.
	//
	// Zero means keep everything, which is what an unset-looking field should
	// do. Unfinished Passages, and the one that produced what is currently in
	// the Gate, are never collected whatever this says.
	//
	// A Passage is the record of *how* a crossing happened, so the default is
	// higher than a Beacon's: Gates produce far fewer objects than Beacons, and
	// each is worth more. Long-term history belongs in the evidence store
	// rather than in etcd (D13).
	//
	// +optional
	// +kubebuilder:validation:Minimum=0
	Retain *int32 `json:"retain,omitempty"`
	// Evidence binds this Gate to the compliance system that records what
	// crossed it and decides what may.
	//
	// +optional
	Evidence *EvidenceConfig `json:"evidence,omitempty"`
}

type GateStatus struct {
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
	// LastHandledReconcileAt echoes the value of the
	// reconcile.fluxcd.io/requestedAt annotation from the last reconcile that
	// acted on it.
	//
	// Without this a caller cannot tell whether its request landed, only that
	// *a* reconcile happened — so a CI job asking for an immediate poll has
	// nothing to wait for. Echoing the caller's own opaque token also
	// distinguishes it from someone else's request (D44).
	//
	// +optional
	LastHandledReconcileAt string `json:"lastHandledReconcileAt,omitempty"`
	// Current is the Bundle presently in this environment.
	//
	// +optional
	Current *GateOccupant `json:"current,omitempty"`
	// Health is the latest assessment from this Gate's watches.
	//
	// +optional
	Health *HealthReport `json:"health,omitempty"`
	// Eligible lists Bundles that could cross now but have not. This is the
	// queue a human acts on, and the answer to "what am I waiting for?"
	//
	// +optional
	Eligible []string `json:"eligible,omitempty"`
	// ActivePassage is the in-flight Passage, if any.
	//
	// +optional
	ActivePassage string `json:"activePassage,omitempty"`
	// History is the recent record of what crossed, newest first.
	//
	// +optional
	History []GateOccupant `json:"history,omitempty"`
	// Evidence is the change gate's verdict for the crossing in progress.
	//
	// Mirrored from the active Passage and **cleared when there is no
	// crossing**, so it can never be a stale verdict presented as current. The
	// question it answers is "why is this sitting there?", which is asked while
	// the crossing is stuck, not afterwards — a finished one is in `history`
	// and in the Passage that produced it.
	//
	// +optional
	Evidence *EvidenceRef `json:"evidence,omitempty"`
}

type GitWatch struct {
	// Repo is the repository URL.
	Repo string `json:"repo"`
	// Branch to follow. Mutually exclusive with Tags.
	//
	// +optional
	Branch string `json:"branch,omitempty"`
	// Tags selects by tag instead of by branch head.
	//
	// +optional
	Tags *TagWatch `json:"tags,omitempty"`
	// Paths restricts which changes count as new. A commit touching nothing in
	// these paths produces no Bundle — this is what keeps a monorepo from
	// promoting every service on every commit.
	//
	// +optional
	Paths []string `json:"paths,omitempty"`
	// IgnorePaths is the inverse, applied after Paths.
	//
	// +optional
	IgnorePaths []string `json:"ignorePaths,omitempty"`
	// +optional
	CredentialsRef *LocalSecretRef `json:"credentialsRef,omitempty"`
}

type Health string

type HealthCheck struct {
	// Uses names a registered health checker, e.g. "flux".
	Uses string `json:"uses"`
	// With is the checker's configuration.
	//
	// +optional
	With *apiextensionsv1.JSON `json:"with,omitempty"`
}

type HealthReport struct {
	// Status is the overall assessment.
	Status Health `json:"status"`
	// Issues explain any non-Healthy status, in human-readable form.
	//
	// +optional
	Issues []string `json:"issues,omitempty"`
	// Details is opaque, check-specific output for the UI and CLI.
	//
	// +optional
	Details *apiextensionsv1.JSON `json:"details,omitempty"`
	// ObservedAt is when this assessment was made.
	//
	// +optional
	ObservedAt *metav1.Time `json:"observedAt,omitempty"`
	// Since is when the status last changed, as opposed to when it was last
	// checked. "Degraded for 40 minutes" is a different fact from "Degraded,
	// checked 20 seconds ago", and only the first one tells you whether to
	// worry.
	//
	// It is also the only record of how long a Gate has been unhealthy that
	// survives a controller restart, which is what lets time-to-restore be
	// measured rather than estimated (D43).
	//
	// +optional
	Since *metav1.Time `json:"since,omitempty"`
}

type ImageArtifact struct {
	// Repo is the image repository, e.g. ghcr.io/acme/podinfo.
	Repo string `json:"repo"`
	// Tag is the resolved tag.
	//
	// +optional
	Tag string `json:"tag,omitempty"`
	// Digest is the image digest, e.g. sha256:abc... This is what gets reported
	// to Fides as an artifact, and what makes the promotion auditable — a tag
	// can be moved, a digest cannot.
	//
	// +optional
	Digest string `json:"digest,omitempty"`
}

type ImageWatch struct {
	// Repo is the image repository, e.g. ghcr.io/acme/podinfo.
	Repo string `json:"repo"`
	// Select is how to pick the newest tag.
	//
	// +kubebuilder:default=SemVer
	// +optional
	Select TagSelection `json:"select,omitempty"`
	// Constraint narrows the selection. For SemVer this is a range such as
	// "^6.0.0"; for Lexical and NewestBuild it is ignored.
	//
	// +optional
	Constraint string `json:"constraint,omitempty"`
	// Allow is a regular expression tags must match. Use it to exclude the
	// mutable tags that otherwise cause surprise promotions — `latest`,
	// `main`, nightly builds.
	//
	// +optional
	Allow string `json:"allow,omitempty"`
	// Ignore lists exact tags to never select.
	//
	// +optional
	Ignore []string `json:"ignore,omitempty"`
	// Platform restricts digest resolution to one platform for multi-arch
	// images, e.g. "linux/amd64".
	//
	// +optional
	Platform string `json:"platform,omitempty"`
	// CredentialsRef names a Secret holding registry credentials. Omit it to
	// use the controller's ambient cloud identity (IRSA, Workload Identity,
	// Managed Identity).
	//
	// +optional
	CredentialsRef *LocalSecretRef `json:"credentialsRef,omitempty"`
	// Insecure allows a plain-HTTP registry: one that terminates TLS elsewhere,
	// an air-gapped one, or a local development registry.
	//
	// False unless asked for, and deliberately so — downgrading to HTTP without
	// being told to would send the registry credentials above in clear. Matches
	// Flux's own `OCIRepository.spec.insecure`.
	//
	// +optional
	Insecure bool `json:"insecure,omitempty"`
}

type LocalSecretRef struct {
	Name string `json:"name"`
}

type Passage struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   PassageSpec   `json:"spec"`
	Status PassageStatus `json:"status,omitempty"`
}

type PassageList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []Passage `json:"items"`
}

type PassagePhase string

type PassageSpec struct {
	// Gate is the Gate being crossed.
	Gate string `json:"gate"`
	// Bundle is the Bundle being moved.
	Bundle string `json:"bundle"`
	// Steps is the resolved step list, copied from the Gate at creation time.
	//
	// Copied rather than referenced on purpose: editing a Gate must not
	// retroactively change what an in-flight or completed Passage did.
	//
	// +kubebuilder:validation:MinItems=1
	Steps []Step `json:"steps"`
	// Vars are the Gate's variables, copied at creation for the same reason the
	// steps are: editing a Gate must not change what an in-flight Passage sees.
	//
	// +optional
	Vars []Var `json:"vars,omitempty"`
	// Actor is who initiated this Passage — a username, or "controller" for
	// automatic crossings.
	//
	// +optional
	Actor string `json:"actor,omitempty"`
	// Abort requests that a running Passage stop. Set it to true to cancel;
	// the controller will mark remaining steps Aborted.
	//
	// +optional
	Abort bool `json:"abort,omitempty"`
}

type PassageStatus struct {
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
	// Phase is the overall outcome.
	//
	// +kubebuilder:default=Pending
	// +optional
	Phase PassagePhase `json:"phase,omitempty"`
	// Message explains the phase, especially a non-success one.
	//
	// +optional
	Message string `json:"message,omitempty"`
	// Steps records each step's outcome, in spec order.
	//
	// +optional
	Steps []StepStatus `json:"steps,omitempty"`
	// CurrentStep indexes the step being executed.
	//
	// +optional
	CurrentStep int32 `json:"currentStep,omitempty"`
	// StartedAt is when the first step ran.
	//
	// +optional
	StartedAt *metav1.Time `json:"startedAt,omitempty"`
	// FinishedAt is when the Passage reached a terminal phase.
	//
	// +optional
	FinishedAt *metav1.Time `json:"finishedAt,omitempty"`
	// Watch are the health checks this Passage's steps asked the Gate to adopt.
	//
	// A step that waited for something — `flux-wait` waiting on a Kustomization,
	// say — already knows what to watch, and the Gate should keep watching it
	// afterwards. Without this the Gate goes blind the moment the Passage ends,
	// and the operator has to restate the same resources in `gate.spec.watch`.
	//
	// +optional
	Watch []HealthCheck `json:"watch,omitempty"`
	// TraceID is the OpenTelemetry trace this Passage belongs to, so a
	// promotion can be correlated with the CI run that produced the artifact
	// and the reconciliation that applied it.
	//
	// +optional
	TraceID string `json:"traceID,omitempty"`
	// Evidence references the compliance record produced for this Passage.
	//
	// +optional
	Evidence *EvidenceRef `json:"evidence,omitempty"`
}

type PassageTemplate struct {
	// Steps run in order. Each may reference earlier steps' outputs.
	//
	// +kubebuilder:validation:MinItems=1
	Steps []Step `json:"steps"`
}

type ProviderWatch struct {
	// Name is the ResourceSetInputProvider, in the Beacon's namespace.
	Name string `json:"name"`
}

type Step struct {
	// Uses names a registered step implementation, e.g. "flux-wait".
	Uses string `json:"uses"`
	// As names this step's output so later steps can reference it, e.g. a step
	// with `as: commit` exposes `${{ steps.commit.sha }}`.
	//
	// +optional
	As string `json:"as,omitempty"`
	// With is the step's configuration. Its shape is defined by the step
	// implementation, which publishes a JSON Schema for validation and for
	// generating the UI form.
	//
	// +optional
	With *apiextensionsv1.JSON `json:"with,omitempty"`
	// If is an expression that must evaluate true for the step to run. Skipped
	// steps are recorded as Skipped, not silently omitted.
	//
	// +optional
	If string `json:"if,omitempty"`
	// Timeout bounds how long this step may run before it is abandoned.
	//
	// +optional
	Timeout *metav1.Duration `json:"timeout,omitempty"`
	// ContinueOnError lets the Passage proceed even if this step fails. Use
	// sparingly: it is how a broken deploy gets reported as a success.
	//
	// +optional
	ContinueOnError bool `json:"continueOnError,omitempty"`
}

type StepPhase string

type StepStatus struct {
	// Uses is the step implementation that ran.
	Uses string `json:"uses"`
	// As is the step's output name, if it had one.
	//
	// +optional
	As string `json:"as,omitempty"`
	// Phase is the outcome.
	Phase StepPhase `json:"phase"`
	// Reason is a stable, machine-readable code for a failure, in PascalCase —
	// GitAuthFailed, FluxStalled, InvalidConfig.
	//
	// Message is for a human reading one failure; Reason is for everything that
	// has to reason across many: `hecate diagnose`, a dashboard counting failure
	// classes, an operator asking "is this the same problem as yesterday?".
	//
	// +optional
	Reason string `json:"reason,omitempty"`
	// Message explains the phase.
	//
	// +optional
	Message string `json:"message,omitempty"`
	// Output is what the step produced, available to later steps.
	//
	// +optional
	Output *apiextensionsv1.JSON `json:"output,omitempty"`
	// StartedAt is when the step first ran.
	//
	// +optional
	StartedAt *metav1.Time `json:"startedAt,omitempty"`
	// FinishedAt is when the step reached a terminal phase.
	//
	// +optional
	FinishedAt *metav1.Time `json:"finishedAt,omitempty"`
	// Attempts counts how many times this step has been invoked. Steps that
	// wait on external systems are invoked repeatedly until they settle.
	//
	// +optional
	Attempts int32 `json:"attempts,omitempty"`
}

type TagSelection string

type TagWatch struct {
	// +kubebuilder:default=SemVer
	// +optional
	Select TagSelection `json:"select,omitempty"`
	// +optional
	Constraint string `json:"constraint,omitempty"`
	// +optional
	Allow string `json:"allow,omitempty"`
	// +optional
	Ignore []string `json:"ignore,omitempty"`
}

type Var struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

type Verification struct {
	// Uses names a registered verifier, e.g. "flagger" or "fides".
	Uses string `json:"uses"`
	// With is the verifier's configuration.
	//
	// +optional
	With *apiextensionsv1.JSON `json:"with,omitempty"`
}

type WatchSource struct {
	// +optional
	Image *ImageWatch `json:"image,omitempty"`
	// +optional
	Chart *ChartWatch `json:"chart,omitempty"`
	// +optional
	Git *GitWatch `json:"git,omitempty"`
	// Provider reads an existing Flux Operator ResourceSetInputProvider.
	//
	// +optional
	Provider *ProviderWatch `json:"provider,omitempty"`
}

type Window struct {
	// Schedule is a cron expression marking when the window opens.
	Schedule string `json:"schedule"`
	// Duration is how long it stays open once opened.
	Duration metav1.Duration `json:"duration"`
	// TimeZone is an IANA name, e.g. "Europe/London". Defaults to UTC.
	//
	// Set this deliberately: a window defined in UTC drifts an hour against
	// local working time twice a year, which is exactly when someone is
	// surprised by a deploy.
	//
	// +optional
	TimeZone string `json:"timeZone,omitempty"`
	// Deny inverts the window: instead of the only time Passages may start,
	// it becomes the only time they may not. For change freezes.
	//
	// +optional
	Deny bool `json:"deny,omitempty"`
}