snapshot

type AdmissionView struct {
	Node adapter.NodeRef `json:"node"`
	// Source is the "ns/name" of the GitRepository.
	Source       string     `json:"source"`
	From         string     `json:"from,omitempty"`
	To           string     `json:"to"`
	ObservedRef  string     `json:"observedRef,omitempty"`
	Initial      bool       `json:"initial,omitempty"`
	PendingSince *time.Time `json:"pendingSince,omitempty"`
}

type ClusterIdent struct {
	Context      string `json:"context,omitempty"`
	Server       string `json:"server,omitempty"`
	WfctlVersion string `json:"wfctlVersion,omitempty"`
}

type DeriveSource struct {
	Reader    client.Reader
	Wavefront string
	// Poll, when set, lists each source's advertised refs before the
	// evaluation, exactly as the controller's poller would.
	Poll *PollOptions
	// Observations, when non-nil, supplies the observation set directly and
	// Poll is not consulted. It is the seam a future --live provider hands the
	// controller's own coherent sweep through, and what a test injects to
	// derive a pending fleet without a git host; a nil map (the default) means
	// no observations at all.
	Observations map[types.NamespacedName]gitpoll.Observation
	// Now is the clock used for CapturedAt, Evaluated and the observation
	// timestamps; nil means time.Now.
	Now func() time.Time
}

type DerivedStatus struct {
	Phase           wavefrontv1alpha1.Phase         `json:"phase,omitempty"`
	Counts          wavefrontv1alpha1.NodeCounts    `json:"counts"`
	Blocked         []wavefrontv1alpha1.BlockedNode `json:"blocked,omitempty"`
	Held            []wavefrontv1alpha1.HeldNode    `json:"held,omitempty"`
	BlockedByReason map[string]int                  `json:"blockedByReason,omitempty"`
	FetchFailures   int                             `json:"fetchFailures,omitempty"`
	// GraphValid, GraphReason and GraphMessage are inputs.GraphVerdict — the
	// GraphValid condition in all but name.
	GraphValid   bool   `json:"graphValid"`
	GraphReason  string `json:"graphReason,omitempty"`
	GraphMessage string `json:"graphMessage,omitempty"`
	// Admissions are the ancestor-gated pin advances this evaluation would
	// perform; Initial the ungated initial pins (DESIGN §3.5.4).
	Admissions []AdmissionView `json:"admissions,omitempty"`
	Initial    []AdmissionView `json:"initial,omitempty"`
}

type EventFilter struct {
	// Reason restricts to one event reason; empty means every reason.
	Reason string
	// Warnings restricts to type=Warning events.
	Warnings bool
	// Source restricts to events whose note names this source (as returned
	// by ParseSource's NamespacedName.String, "namespace/name") as a
	// standalone token; empty means every source.
	Source string
	// Since restricts to events at or after this instant; the zero value
	// means no lower bound.
	Since time.Time
}

type FileSource struct {
	Path string
}

type GraphView struct {
	Cycles  [][]adapter.NodeRef `json:"cycles,omitempty"`
	Unknown []adapter.NodeRef   `json:"unknown,omitempty"`
	Missing []adapter.NodeRef   `json:"missing,omitempty"`
}

type HoldView struct {
	// Kind is HandPin or Suspend.
	Kind string `json:"kind"`
	// Manager is empty for a Suspend hold.
	Manager string `json:"manager,omitempty"`
}

type NodeView struct {
	Ref   adapter.NodeRef `json:"ref"`
	Role  string          `json:"role"`
	State string          `json:"state"`
	Held  bool            `json:"held,omitempty"`
	// Blocked attributes a pending node's non-admission to its nearest
	// unsettled ancestor (or blocking sibling).
	Blocked      *wavefrontv1alpha1.BlockedRef `json:"blocked,omitempty"`
	PendingSince *time.Time                    `json:"pendingSince,omitempty"`
	Ready        bool                          `json:"ready"`
	// Failing is populated only under the derive origin (see above).
	Failing      bool              `json:"failing,omitempty"`
	ReadyMessage string            `json:"readyMessage,omitempty"`
	AppliedSHA   string            `json:"appliedSHA,omitempty"`
	DependsOn    []adapter.NodeRef `json:"dependsOn,omitempty"`
	// Source is the "ns/name" of the backing GitRepository; nil for a gate,
	// which by definition has none.
	Source      *string `json:"source,omitempty"`
	Pin         string  `json:"pin,omitempty"`
	ObservedSHA string  `json:"observedSHA,omitempty"`
	// Wave is the node's dependsOn depth; -1 means it is in, or behind, a
	// cycle and therefore never layered.
	Wave int `json:"wave"`
}

type PollOptions struct {
	// Timeout bounds one listing; <= 0 means DefaultPollTimeout.
	Timeout time.Duration
	// PerHostConcurrency bounds concurrent listings per git host, the same
	// courtesy the controller extends; <= 0 means the CRD default. The CLI
	// passes the Wavefront's own value.
	PerHostConcurrency int
	// Lister lists advertised refs; nil means the production go-git lister,
	// which fetches no objects and touches no disk (DESIGN §3.1.1).
	Lister gitpoll.Lister
	// Strategy selects the candidate SHA from an advertisement; nil means the
	// v1 default, TrackRef. It must be the same strategy the evaluation uses,
	// or the candidate and the tracking ref would come from different
	// policies.
	Strategy selection.Strategy
}

type Snapshot struct {
	APIVersion string `json:"apiVersion"`
	Kind       string `json:"kind"`
	// Origin is how the picture was obtained when it was captured: status or
	// derive. It survives a round trip through a file unchanged.
	Origin string `json:"origin"`
	// Replayed marks a Snapshot that came from a file rather than a live
	// cluster (`--from`). It is orthogonal to Origin: a replayed derive
	// snapshot is still a derive snapshot, and still carries Derived.
	Replayed bool `json:"replayed,omitempty"`
	// CapturedAt is when this snapshot was taken.
	CapturedAt time.Time `json:"capturedAt"`
	// Evaluated is when the picture was last derived: status.lastEvaluated
	// under the status origin, CapturedAt under derive. nil means the
	// controller has never published an evaluation.
	Evaluated *time.Time `json:"evaluated"`
	// Cluster identifies where the snapshot came from. Filled by the CLI,
	// which owns the kubeconfig; the Sources here never read one.
	Cluster ClusterIdent `json:"cluster"`
	// Observed reports whether observed SHAs are meaningful. False means
	// UNKNOWN, not "nothing pending": a renderer must say so rather than
	// present an empty ObservedSHA as a fact (plan B3, `?` columns).
	Observed bool `json:"observed"`
	// Wavefront is the object itself, as the cluster holds it.
	Wavefront WavefrontView `json:"wavefront"`
	// Nodes is every evaluated node, sorted by Ref.String().
	Nodes []NodeView `json:"nodes"`
	// Sources is every managed GitRepository backing a pinned node, sorted by
	// Name ("ns/name"). Entries may be partial under the status origin when
	// RBAC denies the GitRepository read; a Diagnostic says so.
	Sources []SourceView `json:"sources"`
	// Graph is the structural verdict on the dependsOn DAG.
	Graph GraphView `json:"graph"`
	// Derived carries what only a live re-derivation can prove; zero under
	// every other origin.
	Derived DerivedStatus `json:"derived"`
	// Diagnostics are human-readable degradations of this snapshot: selector
	// overlap, unsupported ref styles, poll and credential errors, stale
	// status, RBAC degradation. Never fatal — a degraded picture beats none.
	Diagnostics []string `json:"diagnostics"`
}

type Source interface {
	Capture(ctx context.Context) (*Snapshot, error)
}

type SourceView struct {
	// Name is "ns/name".
	Name string `json:"name"`
	// URL has any userinfo stripped, and is empty when the URL could not be
	// parsed — never a URL that might still embed credentials.
	URL           string `json:"url,omitempty"`
	SecretRefName string `json:"secretRefName,omitempty"`
	TrackingRef   string `json:"trackingRef,omitempty"`
	Pin           string `json:"pin,omitempty"`
	Suspended     bool   `json:"suspended,omitempty"`
	// CommitOwners lists every field manager owning spec.ref.commit — the
	// evidence behind a hold, and what `release` has to unpick.
	CommitOwners []pin.Owner `json:"commitOwners,omitempty"`
	Hold         *HoldView   `json:"hold,omitempty"`
	// Provenance carries the three wavefront.as-code.io pin annotations: the
	// durable ledger events are not (DESIGN §4.2).
	Provenance    map[string]string  `json:"provenance,omitempty"`
	ArtifactSHA   string             `json:"artifactSHA,omitempty"`
	FetchFailing  bool               `json:"fetchFailing,omitempty"`
	Conditions    []metav1.Condition `json:"conditions,omitempty"`
	ObservedSHA   string             `json:"observedSHA,omitempty"`
	FirstObserved *time.Time         `json:"firstObserved,omitempty"`
	// Nodes lists every node referencing this source, sorted.
	Nodes []adapter.NodeRef `json:"nodes,omitempty"`
	// Partial marks a source whose GitRepository could not be read (RBAC or
	// deletion): every field beyond Name, Pin and Nodes is unproven.
	Partial bool `json:"partial,omitempty"`
}

type StatusSource struct {
	Reader    client.Reader
	Wavefront string
	// Now is the clock used for CapturedAt and the staleness verdict; nil
	// means time.Now.
	Now func() time.Time
}

type WavefrontView struct {
	Name       string                            `json:"name"`
	Generation int64                             `json:"generation"`
	Spec       wavefrontv1alpha1.WavefrontSpec   `json:"spec"`
	Status     wavefrontv1alpha1.WavefrontStatus `json:"status"`
	// SpecOwners maps "spec.mode" and "spec.suspend" to the field manager
	// owning them, so a write command can warn that a GitOps applier will
	// revert the change (plan B4). Derived from managedFields; the raw
	// managedFields never appear in a Snapshot.
	SpecOwners map[string]string `json:"specOwners,omitempty"`
}